From 501690edce2cecc356334fc42e7f429907cdfa1e Mon Sep 17 00:00:00 2001 From: Fabien Costantini Date: Fri, 17 Oct 2008 11:08:15 +0000 Subject: Last test does keep history, lets add all related files and patch them afterwards... git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6447 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/src_doc/drawing.dox | 1013 +++++++++++++++++++++++++++++++++++++ 1 file changed, 1013 insertions(+) create mode 100644 documentation/src_doc/drawing.dox (limited to 'documentation/src_doc/drawing.dox') diff --git a/documentation/src_doc/drawing.dox b/documentation/src_doc/drawing.dox new file mode 100644 index 000000000..ea47d8fe2 --- /dev/null +++ b/documentation/src_doc/drawing.dox @@ -0,0 +1,1013 @@ +/** + + \page drawing 5 - Drawing Things in FLTK + +This chapter covers the drawing functions that are provided with FLTK. + +\section sect_WhenCanYouDraw When Can You Draw Things in FLTK? + +There are only certain places you can execute drawing code in FLTK. +Calling these functions at other places will result in undefined behavior! + +\li The most common place is inside the virtual Fl_Widget::draw() method. + To write code here, you must subclass one of the existing Fl_Widget + classes and implement your own version of draw(). + +\li The most common place is inside the virtual method + Fl_Widget::draw(). + To write code here, you must subclass one of the existing Fl_Widget + classes and implement your own version of draw(). + +\li You can also write boxtypes and + labeltypes. These are small + procedures that can be called by existing + Fl_Widget::draw() + methods. These "types" are identified by an 8-bit index that is stored + in the widget's box(), labeltype(), and possibly other properties. + +\li You can call Fl_Window::make_current() to do incremental update of a + widget. Use Fl_Widget::window() to find the window. + + +\section sect_DrawingFunctions Drawing Functions + +To use the drawing functions you must first include the +header file. FLTK provides the following types of drawing functions: + +\li \ref ssect_Boxes +\li \ref ssect_Clipping +\li \ref drawing_colors +\li \ref ssect_Lines +\li \ref ssect_Fast +\li \ref ssect_Complex +\li \ref ssect_Text +\li \ref ssect_Fl_Image +\li \ref ssect_Overlay +\li \ref ssect_Offscreen + + +\subsection ssect_Boxes Boxes + +FLTK provides three functions that can be used to draw boxes for buttons +and other UI controls. Each function uses the supplied upper-lefthand corner +and width and height to determine where to draw the box. + + +void fl_draw_box(Fl_Boxtype b, int x, int y, int w, int h, Fl_Color c); + +\par +The first box drawing function is fl_draw_box() +which draws a standard boxtype \a b in the specified color \a c . + + +void fl_frame(const char *s, int x, int y, int w, int h) + +\par +The fl_frame() function draws a series of line segments around the +given box. The string \a s must contain groups of 4 letters which specify +one of 24 standard grayscale values, where 'A' is black and 'X' is white. +The order of each set of 4 characters is: top, left, bottom, right. The +results of calling fl_frame() with a string that is not a multiple +of 4 characters in length are undefined. + +\par +The only difference between this function and fl_frame2() is the +order of the line segments. + +\par +See also: fl_frame boxtype. + + +void fl_frame2(const char *s, int x, int y, int w, int h); + +\par +The fl_frame2() function draws a series of line segments around +the given box. The string \a s must contain groups of 4 letters which +specify one of 24 standard grayscale values, where 'A' is black and 'X' is +white. The order of each set of 4 characters is: bottom, right, top, left. +The results of calling fl_frame2() with a string that is +not a multiple of 4 characters in length are undefined. + +\par +The only difference between this function and fl_frame() +is the order of the line segments. + + +\subsection ssect_Clipping Clipping + +You can limit all your drawing to a rectangular region by calling +fl_push_clip(), and put the drawings back by using fl_pop_clip(). +This rectangle is measured in pixels and is unaffected by the current +transformation matrix. + +In addition, the system may provide clipping when updating windows +which may be more complex than a simple rectangle. + + +void fl_clip(int x, int y, int w, int h)
+void fl_push_clip(int x, int y, int w, int h) + +\par +Intersect the current clip region with a rectangle and push this new +region onto the stack. The fl_clip() name is deprecated and +will be removed from future releases. + + +void fl_push_no_clip() + +\par +Pushes an empty clip region on the stack so nothing will be clipped. + + +void fl_pop_clip() + +\par +Restore the previous clip region. + +\par +\b Note: +You must call fl_pop_clip() once for every time you call fl_push_clip(). +If you return to FLTK with the clip stack not empty unpredictable results +occur. + + +int fl_not_clipped(int x, int y, int w, int h) + +\par +Returns non-zero if any of the rectangle intersects the current clip +region. If this returns 0 you don't have to draw the object. + +\par +\b Note: +Under X this returns 2 if the rectangle is partially clipped, +and 1 if it is entirely inside the clip region. + + +int fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H) + +\par +Intersect the rectangle x,y,w,h with the current +clip region and returns the bounding box of the result in +X,Y,W,H. Returns non-zero if the resulting rectangle is +different than the original. This can be used to limit the +necessary drawing to a rectangle. \c W and \c H are +set to zero if the rectangle is completely outside the region. + + +void fl_clip_region(Fl_Region r)
+Fl_Region fl_clip_region() + +\par +Replace the top of the clip stack with a clipping region of any shape. +Fl_Region is an operating system specific type. The second form returns +the current clipping region. + + + +\section drawing_colors Colors + +FLTK manages colors as 32-bit unsigned integers. Values from +0 to 255 represent colors from the FLTK 1.0.x standard colormap +and are allocated as needed on screens without TrueColor +support. The Fl_Color enumeration type defines the +standard colors and color cube for the first 256 colors. All of +these are named with symbols in +. + +Color values greater than 255 are treated as 24-bit RGB +values. These are mapped to the closest color supported by the +screen, either from one of the 256 colors in the FLTK 1.0.x +colormap or a direct RGB value on TrueColor screens. You can +generate 24-bit RGB color values using the +fl_rgb_color() +function. + + +void fl_color(Fl_Color) + +\par +Sets the color for all subsequent drawing operations. + +\par +For colormapped displays, a color cell will be allocated out +of fl_colormap the first time you use a color. If the +colormap fills up then a least-squares algorithm is used to find +the closest color. + +Fl_Color fl_color() + +\par +Returns the last fl_color() that was set. This can +be used for state save/restore. + +void fl_color(uchar r, uchar g, uchar b) + +\par +Set the color for all subsequent drawing operations. The +closest possible match to the RGB color is used. The RGB color +is used directly on TrueColor displays. For colormap visuals the +nearest index in the gray ramp or color cube is used. + + +\subsection ssect_Lines Line Dashes and Thickness + +FLTK supports drawing of lines with different styles and +widths. Full functionality is not available under Windows 95, 98, +and Me due to the reduced drawing functionality these operating +systems provide. + + +void fl_line_style(int style, int width=0, char* dashes=0) + +\par +Set how to draw lines (the "pen"). If you change this it is your +responsibility to set it back to the default with +fl_line_style(0). + +\par +\b Note: +Because of how line styles are implemented on WIN32 systems, you must +set the line style after setting the drawing color. If you set the +color after the line style you will lose the line style settings! + +style is a bitmask which is a bitwise-OR of the following +values. If you don't specify a dash type you will get a solid +line. If you don't specify a cap or join type you will get a +system-defined default of whatever value is fastest. + +\li FL_SOLID      ------- +\li FL_DASH       - - - - +\li FL_DOT        ....... +\li FL_DASHDOT    - . - . +\li FL_DASHDOTDOT - .. - +\li FL_CAP_FLAT +\li FL_CAP_ROUND +\li FL_CAP_SQUARE (extends past end point 1/2 line width) +\li FL_JOIN_MITER (pointed) +\li FL_JOIN_ROUND +\li FL_JOIN_BEVEL (flat) + +width is the number of pixels thick to draw the lines. +Zero results in the system-defined default, which on both X and +Windows is somewhat different and nicer than 1. + + + +dashes is a pointer to an array of dash lengths, measured in +pixels. The first location is how long to draw a solid portion, the +next is how long to draw the gap, then the solid, etc. It is +terminated with a zero-length entry. A NULL pointer or a zero-length +array results in a solid line. Odd array sizes are not supported and +result in undefined behavior. + +\note +The dashes array does not work under Windows 95, 98, or Me, since those +operating systems do not support complex line styles. + + +\subsection ssect_Fast Drawing Fast Shapes + +These functions are used to draw almost all the FLTK widgets. +They draw on exact pixel boundaries and are as fast as possible. +Their behavior is duplicated exactly on all platforms FLTK is +ported. It is undefined whether these are affected by the +transformation matrix, +so you should only call these while the matrix is set to the +identity matrix (the default). + + +void fl_point(int x, int y) + +\par +Draw a single pixel at the given coordinates. + + +void fl_rectf(int x, int y, int w, int h)
+void fl_rectf(int x, int y, int w, int h) + +\par +Color a rectangle that exactly fills the given bounding box. + +void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b) + +\par +Color a rectangle with "exactly" the passed +r,g,b color. On screens with less than 24 bits of +color this is done by drawing a solid-colored block using +fl_draw_image() +so that the correct color shade is produced. + + +void fl_rect(int x, int y, int w, int h)
+void fl_rect(int x, int y, int w, int h, Fl_Color c) + +\par +Draw a 1-pixel border inside this bounding box. + + +void fl_line(int x, int y, int x1, int y1)
+void fl_line(int x, int y, int x1, int y1, int x2, int y2) + +\par +Draw one or two lines between the given points. + + +void fl_loop(int x, int y, int x1, int y1, int x2, int y2)
+void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) + +\par +Outline a 3 or 4-sided polygon with lines. + + +void fl_polygon(int x, int y, int x1, int y1, int x2, int y2)
+void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) + +\par +Fill a 3 or 4-sided polygon. The polygon must be convex. + + +void fl_xyline(int x, int y, int x1)
+void fl_xyline(int x, int y, int x1, int y2)
+void fl_xyline(int x, int y, int x1, int y2, int x3) + +\par +Draw horizontal and vertical lines. A horizontal line is +drawn first, then a vertical, then a horizontal. + + +void fl_yxline(int x, int y, int y1)
+void fl_yxline(int x, int y, int y1, int x2)
+void fl_yxline(int x, int y, int y1, int x2, int y3) + +\par +Draw vertical and horizontal lines. A vertical line is drawn +first, then a horizontal, then a vertical. + + +void fl_arc(int x, int y, int w, int h, double a1, double a2)
+void fl_pie(int x, int y, int w, int h, double a1, double a2) + +\par +Draw ellipse sections using integer coordinates. These +functions match the rather limited circle drawing code provided +by X and WIN32. The advantage over using +fl_arc +with floating point +coordinates is that they are faster because they often use the +hardware, and they draw much nicer small circles, since the +small sizes are often hard-coded bitmaps. + +If a complete circle is drawn it will fit inside the passed bounding +box. The two angles are measured in degrees counterclockwise from +3'oclock and are the starting and ending angle of the arc, a2 +must be greater or equal to a1. + +fl_arc() draws a series of lines to approximate the arc. +Notice that the integer version of fl_arc() has a different +number of arguments than the +fl_arc() +function described later in this chapter. + +fl_pie() draws a filled-in pie slice. This slice may +extend outside the line drawn by fl_arc(); to avoid this +use w - 1 and h - 1. + + +void fl_scroll(int X, int Y, int W, int H, int dx, int dy, +void (*draw_area)(void*, int,int,int,int), void* data) + +\par +Scroll a rectangle and draw the newly exposed portions. The contents +of the rectangular area is first shifted by dx and +dy pixels. The callback is then called for every newly +exposed rectangular area, + + +\subsection ssect_Complex Drawing Complex Shapes + +The complex drawing functions let you draw arbitrary shapes +with 2-D linear transformations. The functionality matches that +found in the Adobe® PostScript&tm; language. The +exact pixels that are filled are less defined than for the fast +drawing functions so that FLTK can take advantage of drawing +hardware. On both X and WIN32 the transformed vertices are +rounded to integers before drawing the line segments: this +severely limits the accuracy of these functions for complex +graphics, so use OpenGL when greater accuracy and/or performance +is required. + + +void fl_push_matrix()
+void fl_pop_matrix() + +\par +Save and restore the current transformation. The maximum +depth of the stack is 4. + + +void fl_scale(float x, float y)
+void fl_scale(float x)
+void fl_translate(float x, float y)
+void fl_rotate(float d)
+void fl_mult_matrix(float a, float b, float c, float d, float x, float y) + +\par +Concatenate another transformation onto the current one. The rotation +angle is in degrees (not radians) and is counter-clockwise. + + +double fl_transform_x(double x, double y)
+double fl_transform_y(double x, double y)
+double fl_transform_dx(double x, double y)
+double fl_transform_dy(double x, double y)
+void fl_transformed_vertex(double xf, double yf) + +\par +Transform a coordinate or a distance trough the current transformation matrix. +After transforming a coordinate pair, it can be added to the vertex +list without any forther translations using fl_transformed_vertex. + + +void fl_begin_points()
+void fl_end_points() + +\par +Start and end drawing a list of points. Points are added to +the list with fl_vertex. + + +void fl_begin_line()
+void fl_end_line() + +\par +Start and end drawing lines. + + +void fl_begin_loop()
+void fl_end_loop() + +\par +Start and end drawing a closed sequence of lines. + + +void fl_begin_polygon()
+void fl_end_polygon() + +\par +Start and end drawing a convex filled polygon. + + +void fl_begin_complex_polygon()
+void fl_gap()
+void fl_end_complex_polygon() + +\par +Start and end drawing a complex filled polygon. This polygon +may be concave, may have holes in it, or may be several +disconnected pieces. Call fl_gap() to separate loops of +the path. It is unnecessary but harmless to call +fl_gap() before the first vertex, after the last one, +or several times in a row. + +\par +\b Note: +For portability, you should only draw polygons that appear the same whether +"even/odd" or "non-zero" winding rules are used to fill them. Holes should +be drawn in the opposite direction of the outside loop. + +\par +fl_gap() should only be called between +fl_begin_complex_polygon() and +fl_end_complex_polygon(). To outline the polygon, use +fl_begin_loop() and replace each fl_gap() with +fl_end_loop();fl_begin_loop(). + + +void fl_vertex(float x, float y) + +\par +Add a single vertex to the current path. + + +void fl_curve(float x, float y, float x1, float y1, float x2, float y2, +float x3, float y3) + +\par +Add a series of points on a Bezier curve to the path. The curve ends +(and two of the points) are at x,y and x3,y3. + + +void fl_arc(float x, float y, float r, float start, float end) + +\par +Add a series of points to the current path on the arc of a +circle; you can get elliptical paths by using scale and rotate +before calling fl_arc(). x,y are the center of +the circle, and r is its radius. fl_arc() +takes start and end angles that are measured +in degrees counter-clockwise from 3 o'clock. If end is +less than start then it draws the arc in a clockwise +direction. + + +void fl_circle(float x, float y, float r) + +\par +fl_circle() is equivalent to fl_arc(...,0,360) but +may be faster. It must be the only thing in the path: if you +want a circle as part of a complex polygon you must use fl_arc(). + +\par +\b Note: +fl_circle() draws incorrectly if the transformation is both rotated and +non-square scaled. + + +\subsection ssect_Text Drawing Text + +All text is drawn in the +current font. +It is undefined whether this location or the characters are +modified by the current transformation. + + +void fl_draw(const char *, int x, int y)
+void fl_draw(const char *, int n, int x, int y) + +\par +Draw a nul-terminated string or an array of n characters +starting at the given location. Text is aligned to the left and to +the baseline of the font. To align to the bottom, subtract fl_descent() from +y. To align to the top, subtract fl_descent() and add fl_height(). +This version of fl_draw provides direct access to +the text drawing function of the underlying OS. It does not apply any +special handling to control characters. + +void fl_draw(const char *, int x, int y, int w, int h, +Fl_Align align, Fl_Image *img = 0, int draw_symbols = 1) + +\par +Fancy string drawing function which is used to draw all the +labels. The string is formatted and aligned inside the passed +box. Handles '\\t' and '\\n', expands all other control +characters to ^X, and aligns inside or against the edges of the +box described by x, y, w and h. See +Fl_Widget::align() for values for align. The value +FL_ALIGN_INSIDE is ignored, as this function always +prints inside the box. + +\par +If img is provided and is not NULL, the +image is drawn above or below the text as specified by the +align value. + +\par +The draw_symbols argument specifies whether or not +to look for symbol names starting with the "@" character. + +\par +The text length is limited to 1024 caracters per line. + + +void fl_measure(const char *, int &w, int &h, int draw_symbols = 1) + +\par +Measure how wide and tall the string will be when printed by +the fl_draw(...align) function. If the incoming +w is non-zero it will wrap to that width. + + +int fl_height() + +\par +Recommended minimum line spacing for the current font. You +can also just use the value of size passed to +fl_font(). + + +int fl_descent() + +\par +Recommended distance above the bottom of a fl_height() tall box to draw +the text at so it looks centered vertically in that box. + + +float fl_width(const char*)
+float fl_width(const char*, int n)
+float fl_width(uchar) + +\par +Return the pixel width of a nul-terminated string, a sequence of n +characters, or a single character in the current font. + + +const char *fl_shortcut_label(ulong) + +\par +Unparse a shortcut value as used by Fl_Button or Fl_Menu_Item +into a human-readable string like "Alt+N". This only +works if the shortcut is a character key or a numbered function +key. If the shortcut is zero an empty string is returned. The +return value points at a static buffer that is overwritten with +each call. + + +\subsection ssect_Fonts Fonts + +FLTK supports a set of standard fonts based on the Times, +Helvetica/Arial, Courier, and Symbol typefaces, as well as +custom fonts that your application may load. Each font is +accessed by an index into a font table. + +Initially only the first 16 faces are filled in. There are +symbolic names for them: FL_HELVETICA, +FL_TIMES, FL_COURIER, and modifier values +FL_BOLD and FL_ITALIC which can be added to +these, and FL_SYMBOL and FL_ZAPF_DINGBATS. +Faces greater than 255 cannot be used in Fl_Widget +labels, since Fl_Widget stores the index as a byte. + + +void fl_font(int face, int size) + +\par +Set the current font, which is then used by the routines +described above. You may call this outside a draw context if +necessary to call fl_width(), but on X this will open +the display. + +\par +The font is identified by a face and a +size. The size of the font is measured in +pixels and not "points". Lines should be spaced +size pixels apart or more. + + +int fl_font()
+int fl_size() + +\par +Returns the face and size set by the most recent call to +fl_font(a,b). This can be used to save/restore the font. + + +\subsection ssect_CharacterEncoding Character Encoding + +FLTK 1 supports western character sets using the eight bit encoding +of the user-selected global code page. For MS Windows and X11, the code +page is assumed to be Windows-1252/Latin1, a superset to ISO 8859-1. +On Mac OS X, we assume MacRoman. + +FLTK provides the functions fl_latin1_to_local(), +fl_local_to_latin1(), fl_mac_roman_to_local(), and +fl_local_to_mac_roman() to convert strings between both +encodings. These functions are only required if your source +code contains "C"-strings with international characters and +if this source will be compiled on multiple platforms. + + + +Assuming that the following source code was written on MS Windows, +this example will output the correct label on OS X and X11 as well. +Without the conversion call, the label on OS X would read +Fahrvergn¸gen with a deformed umlaut u ("cedille", +html "¸"). +\code + btn = new Fl_Button(10, 10, 300, 25); + btn->copy_label(fl_latin1_to_local("Fahrvergnügen")); +\endcode + +\note If your application uses characters that are not part of both + encodings, or it will be used in areas that commonly use different + code pages, you might consider upgrading to FLTK 2 which supports + UTF-8 encoding. + +\todo drawing.dox: I fixed the above encoding problem of these \¸ + and umlaut characters, but this text is obsoleted by FLTK 1.3 + with utf-8 encoding, or must be rewritten accordingly: + How to use native (e.g. Windows "ANSI", or ISO-8859-x) + encoding in embedded strings for labels, error messages + and more. Please check this (utf-8) encoding on different + OS'es and with different language and font environments. + +For more information about character encoding, unicode and utf-8 +see chapter \ref unicode. + + +\subsection ssect_Overlay Drawing Overlays + +These functions allow you to draw interactive selection rectangles +without using the overlay hardware. FLTK will XOR a single rectangle +outline over a window. + +void fl_overlay_rect(int x, int y, int w, int h);
+void fl_overlay_clear(); + +\par +fl_overlay_rect() draws a selection rectangle, erasing any +previous rectangle by XOR'ing it first. fl_overlay_clear() +will erase the rectangle without drawing a new one. + +\par +Using these functions is tricky. You should make a widget +with both a handle() and draw() method. +draw() should call fl_overlay_clear() before +doing anything else. Your handle() method should call +window()->make_current() and then +fl_overlay_rect() after FL_DRAG events, and +should call fl_overlay_clear() after a +FL_RELEASE event. + + + +\section drawing_images Drawing Images + +To draw images, you can either do it directly from data in +your memory, or you can create a Fl_Image object. The advantage of +drawing directly is that it is more intuitive, and it is faster +if the image data changes more often than it is redrawn. The +advantage of using the object is that FLTK will cache translated +forms of the image (on X it uses a server pixmap) and thus +redrawing is much faster. + +\subsection ssect_DirectImageDrawing Direct Image Drawing + +The behavior when drawing images when the current +transformation matrix is not the identity is not defined, so you +should only draw images when the matrix is set to the identity. + + +void fl_draw_image(const uchar *, int X, int Y, int W, int H, +int D = 3, int LD = 0)
+void fl_draw_image_mono(const uchar *, int X, int Y, int W, int H, +int D = 1, int LD = 0) + +\par +Draw an 8-bit per color RGB or luminance image. The pointer +points at the "r" data of the top-left pixel. Color +data must be in r,g,b order. X,Y are where to +put the top-left corner. W and H define the +size of the image. D is the delta to add to the pointer +between pixels, it may be any value greater or equal to +3, or it can be negative to flip the image +horizontally. LD is the delta to add to the pointer +between lines (if 0 is passed it uses W * D), and may +be larger than W * D to crop data, or negative to flip +the image vertically. + +\par +It is highly recommended that you put the following code before the +first show() of any window in your program to get rid +of the dithering if possible: + +\code +Fl::visual(FL_RGB); +\endcode + +\par +Gray scale (1-channel) images may be drawn. This is done if +abs(D) is less than 3, or by calling +fl_draw_image_mono(). Only one 8-bit sample is used for +each pixel, and on screens with different numbers of bits for +red, green, and blue only gray colors are used. Setting +D greater than 1 will let you display one channel of a +color image. + +\par +\b Note: +The X version does not support all possible visuals. +If FLTK cannot draw the image in the current visual it +will abort. FLTK supports any visual of 8 bits or less, +and all common TrueColor visuals up to 32 bits. + +typedef void (*fl_draw_image_cb)(void *, int x, int y, int w, uchar *)
+void fl_draw_image(fl_draw_image_cb, void *, int X, int Y, int W, int H, +int D = 3)
+void fl_draw_image_mono(fl_draw_image_cb, void *, int X, int Y, int W, int H, +int D = 1) + +\par +Call the passed function to provide each scan line of the +image. This lets you generate the image as it is being drawn, +or do arbitrary decompression of stored data, provided it can be +decompressed to individual scan lines easily. + +\par +The callback is called with the void * user data +pointer which can be used to point at a structure of information +about the image, and the x, y, and w +of the scan line desired from the image. 0,0 is the upper-left +corner of the image, not X,Y. A pointer to a +buffer to put the data into is passed. You must copy w +pixels from scanline y, starting at pixel x, +to this buffer. + +\par +Due to cropping, less than the whole image may be requested. +So x may be greater than zero, the first y may +be greater than zero, and w may be less than +W. The buffer is long enough to store the entire W * D +pixels, this is for convenience with some decompression +schemes where you must decompress the entire line at once: +decompress it into the buffer, and then if x is not +zero, copy the data over so the x'th pixel is at the +start of the buffer. + +\par +You can assume the y's will be consecutive, except +the first one may be greater than zero. + +\par +If D is 4 or more, you must fill in the unused bytes +with zero. + + +int fl_draw_pixmap(char **data, int X, int Y, Fl_Color = FL_GRAY) + +\par +Draws XPM image data, with the top-left corner at the given position. +The image is dithered on 8-bit displays so you won't lose color space +for programs displaying both images and pixmaps. This function returns +zero if there was any error decoding the XPM data. + +\par +To use an XPM, do: + +\code +#include "foo.xpm" +... +fl_draw_pixmap(foo, X, Y); +\endcode + +\par +Transparent colors are replaced by the optional +Fl_Color argument. To draw with true transparency you must +use the Fl_Pixmap class. + + +int fl_measure_pixmap(char **data, int &w, int &h) + +\par +An XPM image contains the dimensions in its data. This +function finds and returns the width and height. The return +value is non-zero if the dimensions were parsed ok and zero if +there was any problem. + +\subsection ssect_DirectImageReading Direct Image Reading + +FLTK provides a single function for reading from the current +window or off-screen buffer into a RGB(A) image buffer. + + +uchar *fl_read_image(uchar *p, int X, int Y, int W, int H, int alpha = 0); + +\par +Read a RGB(A) image from the current window or off-screen +buffer. The p argument points to a buffer that can hold +the image and must be at least W*H*3 bytes when reading +RGB images and W*H*4 bytes when reading RGBA images. If +NULL, fl_read_image() will create an array of +the proper size which can be freed using delete[]. + +\par +The alpha parameter controls whether an alpha +channel is created and the value that is placed in the alpha +channel. If 0, no alpha channel is generated. + + +\subsection ssect_Fl_Image Image Classes + +FLTK provides a base image class called Fl_Image which supports +creating, copying, and drawing images of various kinds, along +with some basic color operations. Images can be used as labels +for widgets using the image() and deimage() methods or drawn directly. + +The Fl_Image class does almost nothing by itself, but is instead +supported by three basic image types: + +\li Fl_Bitmap +\li Fl_Pixmap +\li Fl_RGB_Image + +The Fl_Bitmap class encapsulates a mono-color bitmap image. +The draw() method draws the image using the current drawing +color. + +The Fl_Pixmap class encapsulates a colormapped image. +The draw() method draws the image using the colors in the +file, and masks off any transparent colors automatically. + +The Fl_RGB_Image class encapsulates a full-color +(or grayscale) image with 1 to 4 color components. Images with +an even number of components are assumed to contain an +alpha channel that is used for transparency. The transparency +provided by the draw() method is either a 24-bit +blend against the existing window contents or a "screen door" +transparency mask, depending on the platform and screen color depth. + + +char fl_can_do_alpha_blending() + +\par +fl_can_do_alpha_blending() will return 1, if your +platform supports true alpha blending for RGBA images, or 0, +if FLTK will use screen door transparency. + +FLTK also provides several image classes based on the three +standard image types for common file formats: + +\li Fl_GIF_Image +\li Fl_JPEG_Image +\li Fl_PNG_Image +\li Fl_PNM_Image +\li Fl_XBM_Image +\li Fl_XPM_Image + +Each of these image classes load a named file of the +corresponding format. The Fl_Shared_Image class +can be used to load any type of image file - the class examines +the file and constructs an image of the appropriate type. + +Finally, FLTK provides a special image class called Fl_Tiled_Image to +tile another image object in the specified area. This class can be +used to tile a background image in a Fl_Group widget, for example. + +virtual void copy();
+virtual void copy(int w, int h); + +\par +The copy() method creates a copy of the image. The second form +specifies the new size of the image - the image is resized using the +nearest-neighbor algorithm. + +void draw(int x, int y, int w, int h, int ox = 0, int oy = 0); + +\par +The draw() method draws the image object. +x,y,w,h indicates a destination rectangle. +ox,oy,w,h is a source rectangle. This source rectangle +is copied to the destination. The source rectangle may extend +outside the image, i.e. ox and oy may be +negative and w and h may be bigger than the +image, and this area is left unchanged. + +void draw(int x, int y) + +\par +Draws the image with the upper-left corner at x,y. +This is the same as doing draw(x,y,img->w(),img->h(),0,0). + + +\subsection ssect_Offscreen Offscreen Drawing + +Sometimes it can be very useful to generate a complex drawing +in memory first and copy it to the screen at a later point in +time. This technique can significantly reduce the amount of +repeated drawing. Fl_Double_Window uses offscreen rendering +to avoid flickering on systems that don't support +double-buffering natively. + + +Fl_Offscreen fl_create_offscreen(int w, int h) + +\par +Create an RGB offscreen buffer with w*h pixels. + + +void fl_delete_offscreen(Fl_Offscreen) + +\par +Delete a previously created offscreen buffer. All drawings are lost. + + +void fl_begin_offscreen(Fl_Offscreen) + +\par +Send all subsequent drawing commands to this offscreen buffer. +FLTK can draw into a buffer at any time. There is no need to wait for +an Fl_Widget::draw() to occur. + + +void fl_end_offscreen() + +\par +Quit sending drawing commands to this offscreen buffer. + + +void fl_copy_offscreen(int x, int y, int w, int h, +Fl_Offscreen osrc, int srcx, int srcy) + +\par +Copy a rectangular area of the size w*h from srcx, srcy +in the offscreen buffer into the current buffer at x, y. + +\htmlonly +
+[Index]    +[Previous]  4 - Designing a Simple Text Editor  +[Next]  6 - Handling Events  +\endhtmlonly +*/ -- cgit v1.2.3