From 09cfc1a1ea00f7edf394e647f1f32e5b0913f564 Mon Sep 17 00:00:00 2001 From: Fabien Costantini Date: Fri, 17 Oct 2008 11:22:35 +0000 Subject: Removing current broken history documentation/src dir. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6451 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/src/drawing.dox | 1013 ----------------------------------------- 1 file changed, 1013 deletions(-) delete mode 100644 documentation/src/drawing.dox (limited to 'documentation/src/drawing.dox') diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox deleted file mode 100644 index ea47d8fe2..000000000 --- a/documentation/src/drawing.dox +++ /dev/null @@ -1,1013 +0,0 @@ -/** - - \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