From 9f39d287b969329d511354f92eaa4bd57bf9b69b Mon Sep 17 00:00:00 2001 From: engelsman Date: Wed, 8 Oct 2008 22:04:13 +0000 Subject: completed addition of \section, \subsection and \par to drawing.dox consistent \section, \subsection, \par applied to complete file. corresponding source code comments for functions still to be completed. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6399 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/drawing.dox | 378 +++++++++++++++++++++------------------------- 1 file changed, 174 insertions(+), 204 deletions(-) (limited to 'documentation') diff --git a/documentation/drawing.dox b/documentation/drawing.dox index 84e6adaf1..3ba6ea8e6 100644 --- a/documentation/drawing.dox +++ b/documentation/drawing.dox @@ -184,51 +184,50 @@ 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. -

-Line Dashes and Thickness -

+ +\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). -\note +\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! @@ -267,9 +266,8 @@ result in undefined behavior. The dashes array does not work under Windows 95, 98, or Me, since those operating systems do not support complex line styles. -

-Drawing Fast Shapes -

+ +\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. @@ -279,100 +277,89 @@ ported. It is undefined whether these are affected by the 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) -

-

Fill a 3 or 4-sided polygon. The polygon must be convex. +\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 @@ -397,19 +384,18 @@ 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, -

-Drawing Complex Shapes -

+ +\subsection ssect_Complex Drawing Complex Shapes The complex drawing functions let you draw arbitrary shapes with 2-D linear transformations. The functionality matches that @@ -422,102 +408,87 @@ 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 @@ -525,35 +496,37 @@ 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. -\note +\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 @@ -563,34 +536,33 @@ 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(). -\note +\par +\b Note: fl_circle() draws incorrectly if the transformation is both rotated and non-square scaled. -

-Drawing Text -

+ +\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 @@ -599,9 +571,10 @@ 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)

+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 @@ -611,55 +584,56 @@ 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 @@ -667,9 +641,8 @@ 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. -

-Fonts -

+ +\subsection ssect_Fonts Fonts FLTK supports a set of standard fonts based on the Times, Helvetica/Arial, Courier, and Symbol typefaces, as well as @@ -684,33 +657,32 @@ 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. -

-Character Encoding -

+ +\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 @@ -755,25 +727,23 @@ html "¸"). For more information about character encoding, unicode and utf-8 see chapter \ref unicode. -

-Drawing Overlays -

+ +\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 @@ -795,21 +765,20 @@ 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. -

Direct Image Drawing

+\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 @@ -822,6 +791,7 @@ 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: @@ -830,6 +800,7 @@ of the dithering if possible: 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 @@ -838,29 +809,28 @@ red, green, and blue only gray colors are used. Setting D greater than 1 will let you display one channel of a color image. -\note +\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 @@ -870,6 +840,7 @@ 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 @@ -880,21 +851,24 @@ 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 @@ -903,28 +877,29 @@ To use an XPM, do: 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. -

Direct Image Reading

+\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 @@ -932,13 +907,13 @@ 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. -

-Image Classes -

+ +\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 @@ -968,10 +943,10 @@ 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. @@ -995,21 +970,18 @@ 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 @@ -1018,16 +990,14 @@ 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). -

-Offscreen Drawing -

+ +\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 @@ -1036,37 +1006,37 @@ 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. -- cgit v1.2.3