1/** 2 3 \page drawing Drawing Things in FLTK 4 5This chapter covers the drawing functions that are provided with FLTK. 6 7\section sect_WhenCanYouDraw When Can You Draw Things in FLTK? 8 9There are only certain places you can execute drawing code in FLTK. 10Calling these functions at other places will result in undefined behavior! 11 12\li The most common place is inside the virtual Fl_Widget::draw() method. 13 To write code here, you must subclass one of the existing Fl_Widget 14 classes and implement your own version of draw(). 15 16\li You can also create custom \ref common_boxtypes "boxtypes" and 17 \ref common_labeltype "labeltypes". These involve writing small 18 procedures that can be called by existing Fl_Widget::draw() methods. 19 These "types" are identified by an 8-bit index that is stored in the 20 widget's \p box(), \p labeltype(), and possibly other properties. 21 22\li You can call Fl_Window::make_current() to do incremental update of a 23 widget. Use Fl_Widget::window() to find the window. 24 25 26\section sect_DrawingFunctions Drawing Functions 27 28To use the drawing functions you must first include the <FL/fl_draw.H> 29header file. FLTK provides the following types of drawing functions: 30 31\li \ref ssect_Boxes 32\li \ref ssect_Clipping 33\li \ref drawing_colors 34\li \ref ssect_Lines 35\li \ref ssect_Fast 36\li \ref ssect_Complex 37\li \ref ssect_Text 38\li \ref ssect_Fonts 39\li \ref ssect_CharacterEncoding 40\li \ref ssect_Overlay 41\li \ref drawing_images 42\li \ref ssect_DirectImageDrawing 43\li \ref ssect_DirectImageReading 44\li \ref ssect_Fl_Image 45\li \ref ssect_Offscreen 46 47\subsection ssect_Boxes Boxes 48 49FLTK provides three functions that can be used to draw boxes for buttons 50and other UI controls. Each function uses the supplied upper-lefthand corner 51and width and height to determine where to draw the box. 52 53void fl_draw_box(Fl_Boxtype b, int x, int y, int w, int h, Fl_Color c); 54 55\par 56The \p %fl_draw_box() function draws a standard boxtype \p b 57in the specified color \p c. 58 59\anchor drawing_fl_frame 60void fl_frame(const char *s, int x, int y, int w, int h) <br> 61void fl_frame2(const char *s, int x, int y, int w, int h) 62 63\par 64The \p %fl_frame() and \p %fl_frame2() functions draw a series of 65line segments around the given box. The string \p s must contain groups 66of 4 letters which specify one of 24 standard grayscale values, 67where 'A' is black and 'X' is white. 68The results of calling these functions with a string that is not a 69multiple of 4 characters in length are undefined. 70 71\par 72The only difference between \p %fl_frame() and \p %fl_frame2() 73is the order of the line segments: 74 - For \p %fl_frame() the order of each set of 4 characters is: 75 top, left, bottom, right. 76 - For \p %fl_frame2() the order of each set of 4 characters is: 77 bottom, right, top, left. 78 79\par 80Note that 81\ref common_fl_frame "fl_frame(Fl_Boxtype b)" 82is described in the \ref common_boxtypes section. 83 84 85\subsection ssect_Clipping Clipping 86 87You can limit all your drawing to a rectangular region by calling 88\p %fl_push_clip(), and put the drawings back by using 89\p %fl_pop_clip(). 90This rectangle is measured in pixels and is unaffected by the current 91transformation matrix. 92 93In addition, the system may provide clipping when updating windows 94which may be more complex than a simple rectangle. 95 96void fl_push_clip(int x, int y, int w, int h) <br> 97void fl_clip(int x, int y, int w, int h) 98 99\par 100Intersect the current clip region with a rectangle and push this new 101region onto the stack. 102 103\par 104The \p %fl_clip() version is deprecated and 105will be removed from future releases. 106 107void fl_push_no_clip() 108 109\par 110Pushes an empty clip region on the stack so nothing will be clipped. 111 112void fl_pop_clip() 113 114\par 115Restore the previous clip region. 116 117\par 118\b Note: 119You must call \p %fl_pop_clip() once for every time you call 120\p %fl_push_clip(). 121If you return to FLTK with the clip stack not empty unpredictable results 122occur. 123 124int fl_not_clipped(int x, int y, int w, int h) 125 126\par 127Returns non-zero if any of the rectangle intersects the current clip 128region. If this returns 0 you don't have to draw the object. 129 130\par 131\b Note: 132Under X this returns 2 if the rectangle is partially clipped, 133and 1 if it is entirely inside the clip region. 134 135int fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H) 136 137\par 138Intersect the rectangle <tt>x,y,w,h</tt> with the current 139clip region and returns the bounding box of the result in 140<tt>X,Y,W,H</tt>. Returns non-zero if the resulting rectangle is 141different than the original. This can be used to limit the 142necessary drawing to a rectangle. \c W and \c H are 143set to zero if the rectangle is completely outside the region. 144 145void fl_clip_region(Fl_Region r) <br> 146Fl_Region fl_clip_region() 147 148\par 149Replace the top of the clip stack with a clipping region of any shape. 150Fl_Region is an operating system specific type. The second form returns 151the current clipping region. 152 153 154\section drawing_colors Colors 155 156FLTK manages colors as 32-bit unsigned integers, encoded as RGBI. 157When the RGB bytes are non-zero, the value is treated as RGB. 158If these bytes are zero, the I byte will be used as an index 159into the colormap. 160 161Values from 0 to 255, i.e. the I index value, represent 162colors from the FLTK 1.3.x standard colormap 163and are allocated as needed on screens without TrueColor support. 164The \b Fl_Color enumeration type defines the 165standard colors and color cube for the first 256 colors. All of 166these are named with symbols in 167\ref enumerations "<FL/Enumerations.H>". 168 169Color values greater than 255 are treated as 24-bit RGB 170values. These are mapped to the closest color supported by the 171screen, either from one of the 256 colors in the FLTK 1.3.x 172colormap or a direct RGB value on TrueColor screens. 173 174Fl_Color fl_rgb_color(uchar r, uchar g, uchar b) <br> 175Fl_Color fl_rgb_color(uchar grayscale) 176 177\par 178Generate Fl_Color out of specified 1798-bit RGB values or one 8-bit grayscale value. 180 181void fl_color(Fl_Color c) <br> 182void fl_color(int c) 183 184\par 185Sets the color for all subsequent drawing operations. 186Please use the first form: 187the second form is only provided for back compatibility. 188 189\par 190For colormapped displays, a color cell will be allocated out 191of \p fl_colormap the first time you use a color. If the 192colormap fills up then a least-squares algorithm is used to find 193the closest color. 194 195Fl_Color fl_color() 196 197\par 198Returns the last color that was set using \p %fl_color(). 199This can be used for state save/restore. 200 201void fl_color(uchar r, uchar g, uchar b) 202 203\par 204Set the color for all subsequent drawing operations. The 205closest possible match to the RGB color is used. The RGB color 206is used directly on TrueColor displays. For colormap visuals the 207nearest index in the gray ramp or color cube is used. 208 209unsigned Fl::get_color(Fl_Color i) <br> 210void Fl::get_color(Fl_Color i, uchar &red, uchar &green, uchar &blue) 211 212\par 213Generate RGB values from a colormap index value \p i. 214The first returns the RGB as a 32-bit unsigned integer, 215and the second decomposes the RGB into three 8-bit values. 216\todo work out why Fl::get_color() does not give links! 217 218Fl::get_system_colors() <br> 219Fl::foreground() <br> 220Fl::background() <br> 221Fl::background2() 222 223\par 224The first gets color values from the user preferences or the system, 225and the other routines are used to apply those values. 226 227Fl::own_colormap() <br> 228Fl::free_color(Fl_Color i, int overlay) <br> 229Fl::set_color(Fl_Color i, unsigned c) 230 231\par 232\p Fl::own_colormap() is used to install a local colormap [X11 only]. 233\par 234\p Fl::free_color() and \p Fl::set_color() are used to remove and replace 235entries from the colormap. 236\todo work out why these do not give links! 237 238There are two predefined graphical interfaces for choosing colors. 239The function fl_show_colormap() shows a table of colors and returns an 240Fl_Color index value. 241The Fl_Color_Chooser widget provides a standard RGB color chooser. 242 243As the Fl_Color encoding maps to a 32-bit unsigned integer representing 244RGBI, it is also possible to specify a color using a hex constant as a 245color map index: 246<pre> 247// COLOR MAP INDEX 248color(0x000000II) 249 ------ | 250 | | 251 | Color map index (8 bits) 252 Must be zero 253</pre> 254\code 255button->color(0x000000ff); // colormap index #255 (FL_WHITE) 256\endcode 257 258or specify a color using a hex constant for the RGB components: 259<pre> 260// RGB COLOR ASSIGNMENTS 261color(0xRRGGBB00) 262 | | | | 263 | | | Must be zero 264 | | Blue (8 bits) 265 | Green (8 bits) 266 Red (8 bits) 267</pre> 268\code 269button->color(0xff000000); // RGB: red 270button->color(0x00ff0000); // RGB: green 271button->color(0x0000ff00); // RGB: blue 272button->color(0xffffff00); // RGB: white 273\endcode 274 275\note 276If TrueColor is not available, any RGB colors will be set to 277the nearest entry in the colormap. 278 279\subsection ssect_Lines Line Dashes and Thickness 280 281FLTK supports drawing of lines with different styles and 282widths. Full functionality is not available under Windows 95, 98, 283and Me due to the reduced drawing functionality these operating 284systems provide. 285 286void fl_line_style(int style, int width, char* dashes) 287 288\par 289Set how to draw lines (the "pen"). If you change this it is your 290responsibility to set it back to the default with 291\p fl_line_style(0). 292 293\par 294\b Note: 295Because of how line styles are implemented on MS Windows systems, you 296\e must set the line style \e after setting the drawing color. 297If you set the 298color after the line style you will lose the line style settings! 299 300\par 301\p style is a bitmask which is a bitwise-OR of the following 302values. If you don't specify a dash type you will get a solid 303line. If you don't specify a cap or join type you will get a 304system-defined default of whatever value is fastest. 305 306\par 307\li <tt>FL_SOLID -------</tt> 308\li <tt>FL_DASH - - - -</tt> 309\li <tt>FL_DOT .......</tt> 310\li <tt>FL_DASHDOT - . - .</tt> 311\li <tt>FL_DASHDOTDOT - .. -</tt> 312\li <tt>FL_CAP_FLAT</tt> 313\li <tt>FL_CAP_ROUND</tt> 314\li <tt>FL_CAP_SQUARE</tt> (extends past end point 1/2 line width) 315\li <tt>FL_JOIN_MITER</tt> (pointed) 316\li <tt>FL_JOIN_ROUND</tt> 317\li <tt>FL_JOIN_BEVEL</tt> (flat) 318 319\par 320\p width is the number of pixels thick to draw the lines. 321Zero results in the system-defined default, which on both X and 322Windows is somewhat different and nicer than 1. 323 324\par 325\p dashes is a pointer to an array of dash lengths, measured in 326pixels. The first location is how long to draw a solid portion, the 327next is how long to draw the gap, then the solid, etc. It is 328terminated with a zero-length entry. A \p NULL pointer or a zero-length 329array results in a solid line. Odd array sizes are not supported and 330result in undefined behavior. 331 332\par 333\b Note: 334The dashes array does not work under Windows 95, 98, or Me, since those 335operating systems do not support complex line styles. 336 337 338\subsection ssect_Fast Drawing Fast Shapes 339 340These functions are used to draw almost all the FLTK widgets. 341They draw on exact pixel boundaries and are as fast as possible. 342Their behavior is duplicated exactly on all platforms FLTK is 343ported. It is undefined whether these are affected by the 344\ref ssect_Complex "transformation matrix", 345so you should only call these while the matrix is set to the 346identity matrix (the default). 347 348void fl_point(int x, int y) 349 350\par 351Draw a single pixel at the given coordinates. 352 353void fl_rectf(int x, int y, int w, int h) <br> 354void fl_rectf(int x, int y, int w, int h) 355 356\par 357Color a rectangle that exactly fills the given bounding box. 358 359void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b) 360 361\par 362Color a rectangle with "exactly" the passed 363<tt>r,g,b</tt> color. On screens with less than 24 bits of 364color this is done by drawing a solid-colored block using 365\ref drawing_fl_draw_image "fl_draw_image()" 366so that the correct color shade is produced. 367 368void fl_rect(int x, int y, int w, int h) <br> 369void fl_rect(int x, int y, int w, int h, Fl_Color c) 370 371\par 372Draw a 1-pixel border \e inside this bounding box. 373 374void fl_line(int x, int y, int x1, int y1) <br> 375void fl_line(int x, int y, int x1, int y1, int x2, int y2) 376 377\par 378Draw one or two lines between the given points. 379 380void fl_loop(int x, int y, int x1, int y1, int x2, int y2) <br> 381void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) 382 383\par 384Outline a 3 or 4-sided polygon with lines. 385 386void fl_polygon(int x, int y, int x1, int y1, int x2, int y2) <br> 387void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) 388 389\par 390Fill a 3 or 4-sided polygon. The polygon must be convex. 391 392void fl_xyline(int x, int y, int x1) <br> 393void fl_xyline(int x, int y, int x1, int y2) <br> 394void fl_xyline(int x, int y, int x1, int y2, int x3) 395 396\par 397Draw horizontal and vertical lines. A horizontal line is 398drawn first, then a vertical, then a horizontal. 399 400void fl_yxline(int x, int y, int y1) <br> 401void fl_yxline(int x, int y, int y1, int x2) <br> 402void fl_yxline(int x, int y, int y1, int x2, int y3) 403 404\par 405Draw vertical and horizontal lines. A vertical line is drawn 406first, then a horizontal, then a vertical. 407 408void fl_arc(int x, int y, int w, int h, double a1, double a2) <br> 409void fl_pie(int x, int y, int w, int h, double a1, double a2) 410 411\par 412Draw ellipse sections using integer coordinates. These 413functions match the rather limited circle drawing code provided 414by X and MS Windows. The advantage over using 415\ref drawing_fl_arc "fl_arc()" 416with floating point 417coordinates is that they are faster because they often use the 418hardware, and they draw much nicer small circles, since the 419small sizes are often hard-coded bitmaps. 420 421\par 422If a complete circle is drawn it will fit inside the passed bounding 423box. The two angles are measured in degrees counter-clockwise from 4243'oclock and are the starting and ending angle of the arc, \p a2 425must be greater or equal to \p a1. 426 427\par 428\p %fl_arc() draws a series of lines to approximate the arc. 429Notice that the integer version of \p %fl_arc() has a different 430number of arguments to the other 431\ref drawing_fl_arc "fl_arc()" 432function described later in this chapter. 433 434\par 435\p %fl_pie() draws a filled-in pie slice. This slice may 436extend outside the line drawn by \p %fl_arc(); to avoid this 437use \p w-1 and \p h-1. 438 439\todo 440add an Fl_Draw_Area_Cb typedef to allow fl_scroll(...) to be doxygenated? 441 442void fl_scroll(int X, int Y, int W, int H, int dx, int dy, void (*draw_area)(void*, int,int,int,int), void* data) 443 444\par 445Scroll a rectangle and draw the newly exposed portions. The contents 446of the rectangular area is first shifted by \p dx and 447\p dy pixels. The callback is then called for every newly 448exposed rectangular area, 449 450 451\subsection ssect_Complex Drawing Complex Shapes 452 453The complex drawing functions let you draw arbitrary shapes 454with 2-D linear transformations. The functionality matches that 455found in the Adobe® PostScript&tm; language. The 456exact pixels that are filled are less defined than for the fast 457drawing functions so that FLTK can take advantage of drawing 458hardware. On both X and MS Windows the transformed vertices are 459rounded to integers before drawing the line segments: this 460severely limits the accuracy of these functions for complex 461graphics, so use OpenGL when greater accuracy and/or performance 462is required. 463 464void fl_push_matrix() <br> 465void fl_pop_matrix() 466 467\par 468Save and restore the current transformation. The maximum 469depth of the stack is 32 entries. 470 471void fl_scale(double x,double y) <br> 472void fl_scale(double x) <br> 473void fl_translate(double x,double y) <br> 474void fl_rotate(double d) <br> 475void fl_mult_matrix(double a,double b,double c,double d,double x,double y) 476 477\par 478Concatenate another transformation onto the current one. The rotation 479angle is in degrees (not radians) and is counter-clockwise. 480 481double fl_transform_x(double x, double y) <br> 482double fl_transform_y(double x, double y) <br> 483double fl_transform_dx(double x, double y) <br> 484double fl_transform_dy(double x, double y) <br> 485void fl_transformed_vertex(double xf, double yf) 486 487\par 488Transform a coordinate or a distance using the current transformation matrix. 489After transforming a coordinate pair, it can be added to the vertex 490list without any further translations using \p %fl_transformed_vertex(). 491 492void fl_begin_points() <br> 493void fl_end_points() 494 495\par 496Start and end drawing a list of points. Points are added to 497the list with \p %fl_vertex(). 498 499void fl_begin_line() <br> 500void fl_end_line() 501 502\par 503Start and end drawing lines. 504 505void fl_begin_loop() <br> 506void fl_end_loop() 507 508\par 509Start and end drawing a closed sequence of lines. 510 511void fl_begin_polygon() <br> 512void fl_end_polygon() 513 514\par 515Start and end drawing a convex filled polygon. 516 517void fl_begin_complex_polygon() <br> 518void fl_gap() <br> 519void fl_end_complex_polygon() 520 521\par 522Start and end drawing a complex filled polygon. This polygon 523may be concave, may have holes in it, or may be several 524disconnected pieces. Call \p %fl_gap() to separate loops of 525the path. It is unnecessary but harmless to call 526\p %fl_gap() before the first vertex, after the last one, 527or several times in a row. 528 529\par 530\p %fl_gap() should only be called between 531\p %fl_begin_complex_polygon() and 532\p %fl_end_complex_polygon(). 533To outline the polygon, use 534\p %fl_begin_loop() and replace each 535\p %fl_gap() with a 536\p %fl_end_loop();%fl_begin_loop() pair. 537 538\par 539\b Note: 540For portability, you should only draw polygons that appear the same whether 541"even/odd" or "non-zero" winding rules are used to fill them. Holes should 542be drawn in the opposite direction of the outside loop. 543 544void fl_vertex(double x,double y) 545 546\par 547Add a single vertex to the current path. 548 549void fl_curve(double X0, double Y0, double X1, double Y1, double X2, double Y2, double X3, double Y3) 550 551\par 552Add a series of points on a Bezier curve to the path. The curve ends 553(and two of the points) are at <tt>X0,Y0</tt> and <tt>X3,Y3</tt>. 554 555\anchor drawing_fl_arc 556void fl_arc(double x, double y, double r, double start, double end) 557 558\par 559Add a series of points to the current path on the arc of a 560circle; you can get elliptical paths by using scale and rotate 561before calling \p %fl_arc(). 562The center of the circle is given by \p x and \p y, 563and \p r is its radius. 564\p %fl_arc() 565takes \p start and \p end angles that are measured 566in degrees counter-clockwise from 3 o'clock. 567If \p end is less than \p start then it draws the arc in a clockwise 568direction. 569 570void fl_circle(double x, double y, double r) 571 572\par 573\p fl_circle(...) is equivalent to \p fl_arc(...,0,360) but may 574be faster. It must be the \e only thing in the path: if you want 575a circle as part of a complex polygon you must use \p %fl_arc(). 576 577\par 578\b Note: 579\p %fl_circle() draws incorrectly if the transformation is both rotated and 580non-square scaled. 581 582\subsection ssect_Text Drawing Text 583 584All text is drawn in the 585\ref drawing_fl_font "current font". 586It is undefined whether this location or the characters are 587modified by the current transformation. 588 589void fl_draw(const char *, int x, int y) <br> 590void fl_draw(const char *, int n, int x, int y) 591 592\par 593Draw a nul-terminated string or an array of \p n characters 594starting at the given location. Text is aligned to the left and to 595the baseline of the font. To align to the bottom, subtract 596\p %fl_descent() from \p y. 597To align to the top, subtract \p %fl_descent() and add \p %fl_height(). 598This version of \p %fl_draw() provides direct access to 599the text drawing function of the underlying OS. It does not apply any 600special handling to control characters. 601 602void fl_draw(const char* str, int x, int y, int w, int h, Fl_Align align, Fl_Image* img, int draw_symbols) 603 604\par 605Fancy string drawing function which is used to draw all the 606labels. The string is formatted and aligned inside the passed 607box. Handles '\\t' and '\\n', expands all other control 608characters to ^X, and aligns inside or against the edges of the 609box described by \p x, \p y, \p w and \p h. 610See Fl_Widget::align() for values for \p align. 611The value \p FL_ALIGN_INSIDE is ignored, as this function always 612prints inside the box. 613 614\par 615If \p img is provided and is not \p NULL, the 616image is drawn above or below the text as specified by the 617\p align value. 618 619\par 620The \p draw_symbols argument specifies whether or not 621to look for symbol names starting with the "@" character. 622 623\par 624The text length is limited to 1024 characters per line. 625 626void fl_measure(const char *str, int& w, int& h, int draw_symbols) 627 628\par 629Measure how wide and tall the string will be when printed by 630the \p fl_draw(...align) function. 631If the incoming \p w is non-zero it will wrap to that width. 632 633int fl_height() 634 635\par 636Recommended minimum line spacing for the current font. You 637can also just use the value of \p size passed to 638\ref drawing_fl_font "fl_font()". 639 640int fl_descent() 641 642\par 643Recommended distance above the bottom of a \p %fl_height() tall box to draw 644the text at so it looks centered vertically in that box. 645 646double fl_width(const char* txt) <br> 647double fl_width(const char* txt, int n) <br> 648double fl_width(unsigned int unicode_char) 649 650\par 651Return the pixel width of a nul-terminated string, a sequence of \p n 652characters, or a single character in the current font. 653 654const char* fl_shortcut_label(int shortcut) 655 656\par 657Unparse a shortcut value as used by Fl_Button or Fl_Menu_Item 658into a human-readable string like "Alt+N". This only 659works if the shortcut is a character key or a numbered function 660key. If the shortcut is zero an empty string is returned. The 661return value points at a static buffer that is overwritten with 662each call. 663 664\subsection ssect_Fonts Fonts 665 666FLTK supports a set of standard fonts based on the Times, 667Helvetica/Arial, Courier, and Symbol typefaces, as well as 668custom fonts that your application may load. Each font is 669accessed by an index into a font table. 670 671Initially only the first 16 faces are filled in. There are 672symbolic names for them: FL_HELVETICA, 673FL_TIMES, FL_COURIER, and modifier values 674FL_BOLD and FL_ITALIC which can be added to 675these, and FL_SYMBOL and FL_ZAPF_DINGBATS. 676Faces greater than 255 cannot be used in Fl_Widget 677labels, since Fl_Widget stores the index as a byte. 678 679\anchor drawing_fl_font 680void fl_font(int face, int size) 681 682\par 683Set the current font, which is then used by the routines 684described above. You may call this outside a draw context if 685necessary to call fl_width(), but on X this will open 686the display. 687 688\par 689The font is identified by a \p face and a \p size. 690The size of the font is measured in \p pixels and not "points". 691Lines should be spaced \p size pixels apart or more. 692 693int fl_font() <br> 694int fl_size() 695 696\par 697Returns the face and size set by the most recent call to 698\p fl_font(a,b). This can be used to save/restore the font. 699 700\subsection ssect_CharacterEncoding Character Encoding 701 702FLTK 1.3 expects all text in Unicode UTF-8 encoding. UTF-8 is 703ASCII compatible for the first 128 characters. International 704characters are encoded in multibyte sequences. 705 706FLTK expects individual characters, characters that are not part of 707a string, in UCS-4 encoding, which is also ASCII compatible, but 708requires 4 bytes to store a Unicode character. 709 710For more information about character encodings, see the chapter on 711\ref unicode. 712 713\subsection ssect_Overlay Drawing Overlays 714 715These functions allow you to draw interactive selection rectangles 716without using the overlay hardware. FLTK will XOR a single rectangle 717outline over a window. 718 719void fl_overlay_rect(int x, int y, int w, int h); <br> 720void fl_overlay_clear(); 721 722\par 723\p %fl_overlay_rect() draws a selection rectangle, erasing any 724previous rectangle by XOR'ing it first. \p %fl_overlay_clear() 725will erase the rectangle without drawing a new one. 726 727\par 728Using these functions is tricky. You should make a widget 729with both a \p handle() and \p draw() method. 730\p draw() should call \p %fl_overlay_clear() before 731doing anything else. Your \p handle() method should call 732<tt>window()->make_current()</tt> and then 733\p %fl_overlay_rect() after FL_DRAG events, and 734should call \p %fl_overlay_clear() after a 735FL_RELEASE event. 736 737 738\section drawing_images Drawing Images 739 740To draw images, you can either do it directly from data in 741your memory, or you can create a Fl_Image object. The advantage of 742drawing directly is that it is more intuitive, and it is faster 743if the image data changes more often than it is redrawn. The 744advantage of using the object is that FLTK will cache translated 745forms of the image (on X it uses a server pixmap) and thus 746redrawing is \e much faster. 747 748\subsection ssect_DirectImageDrawing Direct Image Drawing 749 750The behavior when drawing images when the current 751transformation matrix is not the identity is not defined, so you 752should only draw images when the matrix is set to the identity. 753 754\anchor drawing_fl_draw_image 755void fl_draw_image(const uchar *buf,int X,int Y,int W,int H,int D,int L)<br> 756void fl_draw_image_mono(const uchar *buf,int X,int Y,int W,int H,int D,int L) 757 758\par 759Draw an 8-bit per color RGB or luminance image. The pointer 760points at the "r" data of the top-left pixel. Color 761data must be in <tt>r,g,b</tt> order. 762The top left corner is given by \p X and \p Y 763and the size of the image is given by \p W and \p H. 764\p D is the delta to add to the pointer between pixels, 765it may be any value greater or equal to \p 3, 766or it can be negative to flip the image horizontally. 767\p L is the delta to add to the pointer between lines 768(if 0 is passed it uses \p W*D). 769and may be larger than \p W*D to crop data, 770or negative to flip the image vertically. 771 772\par 773It is highly recommended that you put the following code before the 774first show() of \e any window in your program to get rid 775of the dithering if possible: 776 777\code 778Fl::visual(FL_RGB); 779\endcode 780 781\par 782Gray scale (1-channel) images may be drawn. This is done if 783<tt>abs(D)</tt> is less than 3, or by calling 784\p %fl_draw_image_mono(). Only one 8-bit sample is used for 785each pixel, and on screens with different numbers of bits for 786red, green, and blue only gray colors are used. Setting 787\p D greater than 1 will let you display one channel of a 788color image. 789 790\par 791\b Note: 792The X version does not support all possible visuals. 793If FLTK cannot draw the image in the current visual it 794will abort. FLTK supports any visual of 8 bits or less, 795and all common TrueColor visuals up to 32 bits. 796 797typedef void (*Fl_Draw_Image_Cb)(void *data,int x,int y,int w,uchar *buf) <br> 798void fl_draw_image(Fl_Draw_Image_Cb cb,void *data,int X,int Y,int W,int H,int D) <br> 799void fl_draw_image_mono(Fl_Draw_Image_Cb cb,void *data,int X,int Y,int W,int H,int D) 800 801\par 802Call the passed function to provide each scan line of the 803image. This lets you generate the image as it is being drawn, 804or do arbitrary decompression of stored data, provided it can be 805decompressed to individual scan lines easily. 806 807\par 808The callback is called with the \p void* user data 809pointer which can be used to point at a structure of information 810about the image, and the \p x, \p y, and \p w 811of the scan line desired from the image. 0,0 is the upper-left 812corner of the image, <I>not <tt>X,Y</tt></I>. A pointer to a 813buffer to put the data into is passed. You must copy \p w 814pixels from scanline \p y, starting at pixel \p x, 815to this buffer. 816 817\par 818Due to cropping, less than the whole image may be requested. 819So \p x may be greater than zero, the first \p y may 820be greater than zero, and \p w may be less than \p W. 821The buffer is long enough to store the entire \p W*D 822pixels, this is for convenience with some decompression 823schemes where you must decompress the entire line at once: 824decompress it into the buffer, and then if \p x is not 825zero, copy the data over so the \p x'th pixel is at the 826start of the buffer. 827 828\par 829You can assume the \p y's will be consecutive, except 830the first one may be greater than zero. 831 832\par 833If \p D is 4 or more, you must fill in the unused bytes 834with zero. 835 836int fl_draw_pixmap(char* const* data, int x, int y, Fl_Color bg) <br> 837int fl_draw_pixmap(const char* const* cdata, int x, int y, Fl_Color bg) 838 839\par 840Draws XPM image data, with the top-left corner at the given position. 841The image is dithered on 8-bit displays so you won't lose color space 842for programs displaying both images and pixmaps. This function returns 843zero if there was any error decoding the XPM data. 844 845\par 846To use an XPM, do: 847 848\code 849#include "foo.xpm" 850... 851fl_draw_pixmap(foo, X, Y); 852\endcode 853 854\par 855Transparent colors are replaced by the optional 856Fl_Color argument. To draw with true transparency you must 857use the Fl_Pixmap class. 858 859int fl_measure_pixmap(char* const* data, int &w, int &h) <br> 860int fl_measure_pixmap(const char* const* cdata, int &w, int &h) 861 862\par 863An XPM image contains the dimensions in its data. This 864function finds and returns the width and height. The return 865value is non-zero if the dimensions were parsed ok and zero if 866there was any problem. 867 868\subsection ssect_DirectImageReading Direct Image Reading 869 870FLTK provides a single function for reading from the current 871window or off-screen buffer into a RGB(A) image buffer. 872 873uchar* fl_read_image(uchar *p, int X, int Y, int W, int H, int alpha) 874 875\par 876Read a RGB(A) image from the current window or off-screen 877buffer. The \p p argument points to a buffer that can hold 878the image and must be at least \p W*H*3 bytes when reading 879RGB images and \p W*H*4 bytes when reading RGBA images. If 880\p NULL, \p %fl_read_image() will create an array of 881the proper size which can be freed using \p delete[]. 882 883\par 884The \p alpha parameter controls whether an alpha 885channel is created and the value that is placed in the alpha 886channel. If 0, no alpha channel is generated. 887 888\subsection ssect_Fl_Image Image Classes 889 890FLTK provides a base image class called Fl_Image which supports 891creating, copying, and drawing images of various kinds, along 892with some basic color operations. Images can be used as labels 893for widgets using the \p image() and \p deimage() methods or drawn directly. 894 895The Fl_Image class does almost nothing by itself, but is instead 896supported by three basic image types: 897 898\li Fl_Bitmap 899\li Fl_Pixmap 900\li Fl_RGB_Image 901 902The Fl_Bitmap class encapsulates a mono-color bitmap image. 903The \p draw() method draws the image using the current drawing 904color. 905 906The Fl_Pixmap class encapsulates a colormapped image. 907The \p draw() method draws the image using the colors in the 908file, and masks off any transparent colors automatically. 909 910The Fl_RGB_Image class encapsulates a full-color 911(or grayscale) image with 1 to 4 color components. Images with 912an even number of components are assumed to contain an 913alpha channel that is used for transparency. The transparency 914provided by the draw() method is either a 24-bit 915blend against the existing window contents or a "screen door" 916transparency mask, depending on the platform and screen color depth. 917 918char fl_can_do_alpha_blending() 919 920\par 921\p %fl_can_do_alpha_blending() will return 1, if your 922platform supports true alpha blending for RGBA images, or 0, 923if FLTK will use screen door transparency. 924 925FLTK also provides several image classes based on the three 926standard image types for common file formats: 927 928\li Fl_GIF_Image 929\li Fl_JPEG_Image 930\li Fl_PNG_Image 931\li Fl_PNM_Image 932\li Fl_XBM_Image 933\li Fl_XPM_Image 934 935Each of these image classes load a named file of the 936corresponding format. The Fl_Shared_Image class 937can be used to load any type of image file - the class examines 938the file and constructs an image of the appropriate type. 939 940Finally, FLTK provides a special image class called Fl_Tiled_Image to 941tile another image object in the specified area. This class can be 942used to tile a background image in a Fl_Group widget, for example. 943 944virtual void Fl_Tiled_Image::copy(); <br> 945virtual Fl_Image* Fl_Tiled_Image::copy(int w, int h); 946 947\par 948The \p copy() method creates a copy of the image. The second form 949specifies the new size of the image - the image is resized using the 950nearest-neighbor algorithm. 951 952void Fl_Tiled_Image::draw(int x, int y, int w, int h, int ox, int oy); 953 954\par 955The \p draw() method draws the image object. 956<tt>x,y,w,h</tt> indicates a destination rectangle. 957<tt>ox,oy,w,h</tt> is a source rectangle. This source rectangle 958is copied to the destination. The source rectangle may extend 959outside the image, i.e. \p ox and \p oy may be 960negative and \p w and \p h may be bigger than the 961image, and this area is left unchanged. 962 963void Fl_Tiled_Image::draw(int x, int y) 964 965\par 966Draws the image with the upper-left corner at <tt>x,y</tt>. 967This is the same as doing \p draw(x,y,img->w(),img->h(),0,0). 968 969\subsection ssect_Offscreen Offscreen Drawing 970 971Sometimes it can be very useful to generate a complex drawing 972in memory first and copy it to the screen at a later point in 973time. This technique can significantly reduce the amount of 974repeated drawing. Offscreen drawing functions are declared in <FL/x.H>. 975Fl_Double_Window uses offscreen rendering 976to avoid flickering on systems that don't support 977double-buffering natively. 978 979Fl_Offscreen fl_create_offscreen(int w, int h) 980 981\par 982Create an RGB offscreen buffer with \p w*h pixels. 983 984void fl_delete_offscreen(Fl_Offscreen) 985 986\par 987Delete a previously created offscreen buffer. All drawings are lost. 988 989void fl_begin_offscreen(Fl_Offscreen) 990 991\par 992Send all subsequent drawing commands to this offscreen buffer. 993FLTK can draw into a buffer at any time. There is no need to wait for 994an Fl_Widget::draw() to occur. 995 996void fl_end_offscreen() 997 998\par 999Quit sending drawing commands to this offscreen buffer. 1000 1001void fl_copy_offscreen(int x, int y, int w, int h, Fl_Offscreen osrc, int srcx, int srcy) 1002 1003\par 1004Copy a rectangular area of the size \p w*h from \p srcx,srcy 1005in the offscreen buffer into the current buffer at \p x,y. 1006 1007 1008\htmlonly 1009<hr> 1010<table summary="navigation bar" width="100%" border="0"> 1011<tr> 1012 <td width="45%" align="LEFT"> 1013 <a class="el" href="editor.html"> 1014 [Prev] 1015 Designing a Simple Text Editor 1016 </a> 1017 </td> 1018 <td width="10%" align="CENTER"> 1019 <a class="el" href="index.html">[Index]</a> 1020 </td> 1021 <td width="45%" align="RIGHT"> 1022 <a class="el" href="events.html"> 1023 Handling Events 1024 [Next] 1025 </a> 1026 </td> 1027</tr> 1028</table> 1029\endhtmlonly 1030 1031*/ 1032