From d7b88a3bcc7e76f38ee5799be7722fd5a10781ef Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Wed, 13 Jan 1999 19:28:54 +0000 Subject: Updated all links so they work between files. Revision 1. git-svn-id: file:///fltk/svn/fltk/trunk@219 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/drawing.html | 1172 +++++++++++++++++++------------------------- 1 file changed, 499 insertions(+), 673 deletions(-) (limited to 'documentation/drawing.html') diff --git a/documentation/drawing.html b/documentation/drawing.html index 9219273eb..df1e395fb 100644 --- a/documentation/drawing.html +++ b/documentation/drawing.html @@ -1,681 +1,507 @@ - - - +

5 - Drawing Things in FLTK

- -This chapter covers the drawing functions that are provided with FLTK. - -

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! - - - -

FLTK Drawing Functions

- -To use the drawing functions you must first include the -<FL/fl_draw.H> header file. FLTK provides the following types -of drawing functions: - - - -

Clipping

- -You can limit all your drawing to a rectangular region by calling -fl_clip, and put the drawings back by using -fl_pop_clip. This rectangle is measured in pixels (it is -unaffected by the current transformation matrix). - -

In addition, the system may provide clipping when updating windows, -this clip region may be more complex than a simple rectangle. - -

void fl_clip(int x, int y, int w, int h)

- -Intersect the current clip region with a rectangle and push this new -region onto the stack. - -

void fl_pop_clip()

- -Restore the previous clip region. You must call -fl_pop_clip() once for every time you call -fl_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)

- -Returns true if any of the rectangle intersects the current clip -region. If this returns false you don't have to draw the object. -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)

- -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. W and H are set to zero if the rectangle -is completely outside the region. - -

Colors

- -

void fl_color(Fl_Color)

- -Set the color for all subsequent drawing operations. Fl_Color -is an enumeration type, and all values are in the range 0-255. This is -not the X or WIN32 pixel, it is an index into an internal -table! The table provides several general colors, a 24-entry gray -ramp, and a 5x8x5 color cube. All of these are named with -poorly-documented symbols in <FL/Enumerations.H>. - -

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()

- -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)

- -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. - -

Fast Shapes

- -These are used to draw almost all the FLTK widgets. They draw on exact -pixel boundaries and are as fast as possible, and their behavior will -be duplicated exactly on any platform FLTK is ported to. It is -undefined whether these are affected by the transformation matrix, so you should only call these -while it is the identity. - -

void fl_rectf(int x, int y, int w, int h)

- -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)

- -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 dithering is -produced. - -

void fl_rect(int x, int y, int w, int h)

- -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)

- -Draw one or two 1-pixel thick 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)

- -Outline a 3 or 4-sided polygon with 1-pixel thick 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. - -

void fl_xyline(int x, int y, int x1, int y1)
-void fl_xyline(int x, int y, int x1, int y1, int x2)
-void fl_xyline(int x, int y, int x1, int y1, int x2, int y3)

- -Draw 1-pixel wide 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)

- -Draw 1-pixel wide 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)
-void fl_chord(int x, int y, int w, int h, double a1, double a2)

- -High-speed ellipse sections. These functions match the rather limited -circle drawing code provided by X and MSWindows. The advantage over -using fl_arc 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 1-pixel thick line (notice this has a different -number of arguments than the fl_arc() described -below. - -

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. - -

fl_chord() is not yet implemented. - -

Complex Shapes

- -These functions let you draw arbitrary shapes with 2-D linear -transformations. The functionality matches that found in Adobe® -PostScriptTM. The exact pixels filled in is less defined -than for the above calls, so that FLTK can take advantage of drawing -hardware. The transformed vertices are rounded to integers before -drawing the line segments. This severely limits the accuracy of these -functions for complex graphics. Use OpenGL when greater accuracy -and/or performance is required. - -

void fl_push_matrix()
-void fl_pop_matrix()

- -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)

- -Concatenate another transformation onto the current one. The rotation angle -is in degrees (not radians) and is counter-clockwise. - -

void fl_begin_line()
-void fl_end_line()

- -Start and end drawing 1-pixel thick lines. - -

void fl_begin_loop()
-void fl_end_loop()

- -Start and end drawing a closed sequence of 1-pixel thick lines. - -

void fl_begin_polygon()
-void fl_end_polygon()

- -Start and end drawing a convex filled polygon. - -

void fl_begin_complex_polygon()
-void fl_gap()
-void fl_end_complex_polygon()

- -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 seperate 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). For portability, you should -only draw polygons that appear the same whether "even/odd" or -"non-zero" winding rules are used to fill them. This mostly means that -holes should be drawn in the opposite direction of the outside. - -

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)

- -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)

- -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)

- -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 -this). 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)

- -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(). This draws incorrectly if the transformation is -both rotated and non-square scaled. - -

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 *, float x, float y)
-void fl_draw(const char *, int n, float x, float y)

- -Draw a nul-terminated string or an array of n characters -starting at the given location. - -

void fl_draw(const char *, int x, int y, int w, int h, Fl_Align)

- -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. See Fl_Widget::align() for values for -align. The value FL_ALIGN_INSIDE is ignored, as this -function always prints inside the box. - -

void fl_measure(const char *, int &w, int &h)

- -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()

- -Recommended minimum line spacing for the current font. You can also -just use the value of size passed to -fl_font(). - -

int fl_descent()

- -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)

- -Return the width of a nul-terminated string, a sequence of n -characters, or a single character. - -

const char *fl_shortcut_label(ulong)

- -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. - -

Fonts

- -

void fl_font(int face, int size)

- -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. - -

The font is identified by a face and a size. The -size of the font is measured in pixels (i.e. it is not -"resolution [in]dependent"). Lines should be spaced size -pixels apart (or more). - -

The face is an index into an internal 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 it stores the index as a byte. - -

int fl_font()
-int fl_size()

- -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. - -

Cursor

- -

void fl_cursor(Fl_Cursor, Fl_Color = FL_WHITE, Fl_Color = FL_BLACK)

- -Change the cursor. Depending on the system this may affect the cursor -everywhere, or only when it is pointing at the window that is current -when you call this. For portability you should change the cursor back -to the default in response to FL_LEAVE events. - -

The type Fl_Cursor is an enumeration defined in <Enumerations.H>. The -double-headed arrows are bitmaps provided by FLTK on X, the others are -provided by system-defined cursors. Under X you can get any XC_cursor -value by passing Fl_Cursor((XC_foo/2)+1). - -

The following standard cursors are available: - -

    -
  • FL_CURSOR_DEFAULT - the default cursor, usually an arrow -
  • FL_CURSOR_ARROW - an arrow pointer -
  • FL_CURSOR_CROSS - crosshair -
  • FL_CURSOR_WAIT - watch or hourglass -
  • FL_CURSOR_INSERT - I-beam -
  • FL_CURSOR_HAND - hand (uparrow on MSWindows) -
  • FL_CURSOR_HELP - question mark -
  • FL_CURSOR_MOVE - 4-pointed arrow -
  • FL_CURSOR_NS - up/down arrow -
  • FL_CURSOR_WE - left/right arrow -
  • FL_CURSOR_NWSE - diagonal arrow -
  • FL_CURSOR_NESW - diagonal arrow -
  • FL_CURSOR_NONE - invisible -
- -

Overlays

- -

void fl_overlay_rect(int x, int y, int w, int h)
-void fl_overlay_clear()

- -These functions allow you to draw interactive selection rectangles -without using the overlay hardware. FLTK will XOR a single rectangle -outline over a window. Calling this will erase any previous rectangle -(by XOR'ing it), and then draw the new one. Calling -fl_overlay_clear() will erase the rectangle without drawing a -new one. - -

Using this 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. - -

Images

- -To draw images, you can either do it directly from data in your memory, -or you can create Fl_Bitmap, Fl_Image, or Fl_Pixmap objects. 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. - -

Direct Image Drawing

- -It is undefined whether the location or drawing of the image is -affected by the current transformation, so you should only call these -when it is the identity. - -

void fl_draw_bitmap(const uchar *, int X, int Y, int W, int H, int LD = 0)

- -This function is planned but not yet implemented (it may be impossible -under X without allocating a pixmap). - -

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)

- -Draw an 8-bit per color RGB or luminance image. The pointer points at -the "r" data of the top-left pixel. 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. - -

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: - -

    + This chapter covers the drawing functions that are provided with FLTK. 
+
    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! 
+
      
+
    • The most common 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(). 
      • 
+
    • You can also write boxtypes and 
+labeltypes.  These are small procedures  that can be called by 
+existing Fl_Widgetdraw() methods.  These "types" are 
+identified by an  8-bit index that is stored in the widget's box()
+, labeltype(), and possibly other properties. 
      • 
+
    • You can call 
+Fl_Window::make_current() to do incremental update of a 
+widget. Use 
+Fl_Widget::window() to  find the window. Under X this only 
+works for the base Fl_Window class, not for double buffered, 
+overlay, or  OpenGL windows!
      • 
+
    
+
    FLTK Drawing Functions
    
+ To use the drawing functions you must first include the 
+<FL/fl_draw.H> header file.  FLTK provides the following types of 
+drawing functions: 
+
+
    Clipping
    
+ You can limit all your drawing to a rectangular region by calling 
+fl_clip, and put the drawings back by using fl_pop_clip. 
+ This rectangle is measured in pixels (it is unaffected by the current 
+transformation matrix). 
+
    In addition, the system may provide clipping when updating windows, 
+this clip region may be more complex than a simple rectangle. 
    
+
    void fl_clip(int x, int y, int w, int h)
    
+ Intersect the current clip region with a rectangle and push this new 
+region onto the stack. 
+
    void fl_pop_clip()
    
+ Restore the previous clip region. You must call fl_pop_clip()
+ once for every time you call fl_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)
    
+ Returns true if any of the rectangle intersects the current clip 
+region.  If this returns false you don't have to draw the object. 
+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)
    
+ 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. W and H are set to zero if the rectangle 
+is completely outside the region. 
+
    Colors
    
+
    void fl_color(Fl_Color)
    
+ Set the color for all subsequent drawing operations. Fl_Color
+ is an enumeration type, and all values are in the range 0-255.  This 
+is not the X or WIN32 pixel, it is an index into an internal 
+table!  The table provides several general colors, a 24-entry gray 
+ramp, and a 5x8x5 color cube. All of these are named with 
+poorly-documented symbols in 
+<FL/Enumerations.H>. 
+
    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()
    
+ 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)
    
+ 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. 
+
    Fast Shapes
    
+ These are used to draw almost all the FLTK widgets.  They draw on 
+exact pixel boundaries and are as fast as possible, and their behavior 
+will be duplicated exactly on any platform FLTK is ported to.  It is 
+undefined whether these are affected by the 
+transformation matrix, so you should only call these while it is 
+the identity. 
+
    void fl_rectf(int x, int y, int w, int h)
    
+ 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)
    
+ 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 dithering is produced. 
+
    void fl_rect(int x, int y, int w, int h)
    
+ 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)
    
+ Draw one or two 1-pixel thick 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)
    
+ Outline a 3 or 4-sided polygon with 1-pixel thick 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. 
+
    void fl_xyline(int x, int y, int x1, int y1)
+
     void fl_xyline(int x, int y, int x1, int y1, int x2)
+
     void fl_xyline(int x, int y, int x1, int y1, int x2, int y3)
    
+ Draw 1-pixel wide 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)
    
+ Draw 1-pixel wide 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)
+
     void fl_chord(int x, int y, int w, int h, double a1, double a2)
    
+ High-speed ellipse sections.  These functions match the rather limited 
+circle drawing code provided by X and MSWindows.  The advantage over 
+using fl_arc 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 1-pixel thick line (notice this has a 
+different number of arguments than the fl_arc()
+ described below. 
    
+
    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. 
    
+
    fl_chord() is not yet implemented. 
    
+
    Complex Shapes
    
+ These functions let you draw arbitrary shapes with 2-D linear 
+transformations.  The functionality matches that found in Adobe® 
+PostScriptTM.  The exact pixels filled in is less defined 
+than for the above calls, so that FLTK can take advantage of drawing 
+hardware.  The transformed vertices are rounded to integers before 
+drawing the line segments.  This severely limits the accuracy of these 
+functions for complex graphics.  Use OpenGL when greater accuracy 
+and/or performance is required. 
+
    void fl_push_matrix()
+
     void fl_pop_matrix()
    
+ 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)
    
+ Concatenate another transformation onto the current one.  The rotation 
+angle is in degrees (not radians) and is counter-clockwise. 
+
    void fl_begin_line()
+
     void fl_end_line()
    
+ Start and end drawing 1-pixel thick lines. 
+
    void fl_begin_loop()
+
     void fl_end_loop()
    
+ Start and end drawing a closed sequence of 1-pixel thick lines. 
+
    void fl_begin_polygon()
+
     void fl_end_polygon()
    
+ Start and end drawing a convex filled polygon. 
+
    void fl_begin_complex_polygon()
+
     void fl_gap()
+
     void fl_end_complex_polygon()
    
+ 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 seperate 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).  For portability, you should 
+only draw polygons that appear the same whether "even/odd" or 
+"non-zero" winding rules are used to fill them.  This mostly means that 
+holes should be drawn in the opposite direction of the outside. 
+
    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)
    
+ 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)
    
+ 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)
    
+ 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 
+this). 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)
    
+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()
+. This draws incorrectly if the transformation is both rotated and 
+non-square scaled.
+
    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 *, float x, float y)
+
     void fl_draw(const char *, int n, float x, float y)
    
+ Draw a nul-terminated string or an array of n characters 
+starting at the given location. 
+
    void fl_draw(const char *, int x, int y, int w, int h, Fl_Align)
    
+ 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.  See 
+Fl_Widget::align() for values for align.  The 
+value FL_ALIGN_INSIDE is ignored, as this function always 
+prints inside the box. 
+
    void fl_measure(const char *, int &w, int &h)
    
+ 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()
    
+ Recommended minimum line spacing for the current font.  You can also 
+just use the value of size passed to 
+fl_font(). 
+
    int fl_descent()
    
+ 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)
    
+ Return the width of a nul-terminated string, a sequence of n
+ characters, or a single character. 
+
    const char *fl_shortcut_label(ulong)
    
+ 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. 
+
    Fonts
    
+
    void fl_font(int face, int size)
    
+ 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. 
+
    The font is identified by a face and a size.  The 
+size of the font is measured in pixels (i.e. it is not 
+"resolution [in]dependent").  Lines should be spaced size
+ pixels apart (or more). 
    
+
    The face is an index into an internal 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 it stores the index as a byte. 
    
+
    int fl_font()
+
     int fl_size()
    
+ 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. 
+
    Cursor
    
+
    void fl_cursor(Fl_Cursor, Fl_Color = FL_WHITE, Fl_Color = FL_BLACK)
    
+ Change the cursor.  Depending on the system this may affect the cursor 
+everywhere, or only when it is pointing at the window that is current 
+when you call this.  For portability you should change the cursor back 
+to the default in response to FL_LEAVE events. 
+
    The type Fl_Cursor is an enumeration defined in 
+<Enumerations.H>.  The  double-headed arrows are bitmaps 
+provided by FLTK on X, the others are provided by system-defined 
+cursors.  Under X you can get any XC_cursor value by passing 
+Fl_Cursor((XC_foo/2)+1). 
    
+
    The following standard cursors are available: 
    
+
      
+
    • FL_CURSOR_DEFAULT - the default cursor, usually an arrow 
      • 
+
    • FL_CURSOR_ARROW - an arrow pointer 
      • 
+
    • FL_CURSOR_CROSS - crosshair 
      • 
+
    • FL_CURSOR_WAIT - watch or hourglass 
      • 
+
    • FL_CURSOR_INSERT - I-beam 
      • 
+
    • FL_CURSOR_HAND - hand (uparrow on MSWindows) 
      • 
+
    • FL_CURSOR_HELP - question mark 
      • 
+
    • FL_CURSOR_MOVE - 4-pointed arrow 
      • 
+
    • FL_CURSOR_NS - up/down arrow 
      • 
+
    • FL_CURSOR_WE - left/right arrow 
      • 
+
    • FL_CURSOR_NWSE - diagonal arrow 
      • 
+
    • FL_CURSOR_NESW - diagonal arrow 
      • 
+
    • FL_CURSOR_NONE - invisible 
      • 
+
    
+
    Overlays
    
+
    void fl_overlay_rect(int x, int y, int w, int h)
+
     void fl_overlay_clear()
    
+ These functions allow you to draw interactive selection rectangles 
+without using the overlay hardware.  FLTK will XOR a single rectangle 
+outline over a window. Calling this will erase any previous rectangle 
+(by XOR'ing it), and then draw the new one.  Calling 
+fl_overlay_clear() will erase the rectangle without drawing a new 
+one. 
+
    Using this 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. 
    
+
    Images
    
+ To draw images, you can either do it directly from data in your 
+memory, or you can create Fl_Bitmap, 
+Fl_Image, or Fl_Pixmap
+ objects.  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. 
+
    Direct Image Drawing
    
+ It is undefined whether the location or drawing of the image is 
+affected by the current transformation, so you should only call these 
+when it is the identity. 
+
    void fl_draw_bitmap(const uchar *, int X, int Y, int W, int H, int 
+LD = 0)
    
+ This function is planned but not yet implemented (it may be impossible 
+under X without allocating a pixmap). 
+
    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)
    
+ Draw an 8-bit per color RGB or luminance image.  The pointer points at 
+the "r" data of the top-left pixel.  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. 
+
    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: 
    
+
      
+
       Fl::visual(FL_RGB);
-
    
-
-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.
-
-
    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)
    
-
-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).
-
-
    The callback is called with the void * user data pointer
-(this 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 (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.
-
-
    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 convienence 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.
-
-
    You can assume the y's will be consecutive, except the first one
-may be greater than zero.
-
-
    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)
    
-
-Draw XPM image data, with the top-left corner at the given position.
-The images 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.
-
-
    To use an XPM, do:
-
-
      -#include "foo.xpm"
+
      
+
    
+ 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. 
+
    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)
    
+ 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). 
+
    The callback is called with the void * user data pointer 
+(this 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 (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. 
    
+
    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 
+convienence 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. 
    
+
    You can assume the y's will be consecutive, except the 
+first one may be greater than zero. 
    
+
    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)
    
+ Draw XPM image data, with the top-left corner at the given position. 
+The images 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. 
+
    To use an XPM, do: 
    
+
      
+
      +#include "foo.xpm"
 ...
 fl_draw_pixmap(foo, X, Y);
-
    
-
-In the current version the XPM data is converted to 8-bit full color
-and passed through fl_draw_image().  This is obviously not the
-most efficient way to do it, and has the same visual limitations as
-listed above for fl_draw_image().  Transparent colors are
-replaced by the optional Fl_Color argument (this may change in
-the future).
-
-
    int fl_measure_pixmap(char **data, int &w, int &h)
    
-
-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 it parsed the dimensions ok, and zero if there is any problem.
-
-
    class Fl_Bitmap
    
-
-This object encapsulates the width, height, and bits of an X bitmap
-(XBM), and allows you to make an Fl_Widget use a bitmap as a
-label, or to just draw the bitmap directly.  Under X it will create an
-offscreen pixmap the first time it is drawn, and copy this each
-subsequent time it is drawn.
-
-
    Fl_Bitmap(const char *bits, int W, int H)
    
-Fl_Bitmap(const uchar *bits, int W, int H)
    
-
-Construct using an X bitmap.  The bits pointer is simply copied to the
-object, so it must point at persistent storage.  The two constructors
-are provided because various X implementations disagree about the type
-of bitmap data.  To use an XBM file use:
-
-
      -#include "foo.xbm"
+
      
+
    
+ In the current version the XPM data is converted to 8-bit full color 
+and passed through fl_draw_image().  This is obviously not the 
+most efficient way to do it, and has the same visual limitations as 
+listed above for fl_draw_image().  Transparent colors are 
+replaced by the optional Fl_Color argument (this may change in 
+the future). 
+
    int fl_measure_pixmap(char **data, int &w, int &h)
    
+ 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 it 
+parsed the dimensions ok, and zero if there is any problem. 
+
    class Fl_Bitmap
    
+ This object encapsulates the width, height, and bits of an X bitmap 
+(XBM), and allows you to make an Fl_Widget use a bitmap as a 
+label, or to just draw the bitmap directly.  Under X it will create an 
+offscreen pixmap the first time it is drawn, and copy this each 
+subsequent time it is drawn. 
+
    Fl_Bitmap(const char *bits, int W, int H)
+
     Fl_Bitmap(const uchar *bits, int W, int H)
    
+ Construct using an X bitmap.  The bits pointer is simply copied to the 
+object, so it must point at persistent storage.  The two constructors 
+are provided because various X implementations disagree about the type 
+of bitmap data.  To use an XBM file use: 
+
      
+
      +#include "foo.xbm"
 ...
 Fl_Bitmap bitmap = new Fl_Bitmap(foo_bits, foo_width, foo_height);
-
    
-
-
    ~Fl_Bitmap()
    
-
-The destructor will destroy any X pixmap created.  It does not do
-anything to the bits data.
-
-
    void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)
    
-
-x,y,w,h indicates a destination rectangle.  ox,oy,w,h
-is a source rectangle.  This source rectangle from the bitmap is drawn
-in the destination.  1 bits are drawn with the current color, 0 bits
-are unchanged.  The source rectangle may extend outside the bitmap
-(i.e. ox and oy may be negative and w and
-h may be bigger than the bitmap) and this area is left
-unchanged.
-
-
    void draw(int x, int y)
    
-
-Draws the bitmap with the upper-left corner at x,y.  This is
-the same as doing draw(x,y,this->w,this->h,0,0).
-
-
    void label(Fl_Widget *)
    
-
-Change the label() and the labeltype() of the widget
-to draw the bitmap.  1 bits will be drawn with the
-labelcolor(), zero bits will be unchanged.  You can use the
-same bitmap for many widgets.
-
-
-
    class Fl_Pixmap
    
-
-This object encapsulates the data from an XPM image, and allows you to
-make an Fl_Widget use a pixmap as a label, or to just draw the
-pixmap directly.  Under X it will create an offscreen pixmap the
-first time it is drawn, and copy this each subsequent time it is
-drawn.
-
-
    The current implementation converts the pixmap to 8 bit color data
-and uses fl_draw_image() to draw
-it.  Thus you will get dithered colors on an 8 bit screen.
-
-
    Fl_Pixmap(char *const* data)
    
-
-Construct using XPM data.  The data pointer is simply copied to the
-object, so it must point at persistent storage.  To use an XPM file do:
-
-
      -#include <FL/Fl_Pixmap.H>
-#include "foo.xpm"
+
      
+
    
+
    ~Fl_Bitmap()
    
+ The destructor will destroy any X pixmap created.  It does not do 
+anything to the bits data. 
+
    void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)
    
+x,y,w,h indicates a destination rectangle. ox,oy,w,h
+ is a source rectangle.  This source rectangle from the bitmap is drawn 
+in the destination.  1 bits are drawn with the current color, 0 bits 
+are unchanged.  The source rectangle may extend outside the bitmap 
+(i.e. ox and oy may be negative and w and 
+h may be bigger than the bitmap) and this area is left unchanged. 
+
    void draw(int x, int y)
    
+ Draws the bitmap with the upper-left corner at x,y.  This is 
+the same as doing draw(x,y,this->w,this->h,0,0). 
+
    void label(Fl_Widget *)
    
+ Change the label() and the labeltype() of the widget 
+to draw the bitmap.  1 bits will be drawn with the labelcolor()
+, zero bits will be unchanged.  You can use the same bitmap for many 
+widgets. 
+
    class Fl_Pixmap
    
+ This object encapsulates the data from an XPM image, and allows you to 
+make an Fl_Widget use a pixmap as a label, or to just draw the 
+pixmap directly. Under X it will create an offscreen pixmap the 
+first time it is drawn, and copy this each subsequent time it is drawn
+. 
+
    The current implementation converts the pixmap to 8 bit color data 
+and uses fl_draw_image() to draw 
+it.  Thus you will get dithered colors on an 8 bit screen. 
    
+
    Fl_Pixmap(char *const* data)
    
+ Construct using XPM data.  The data pointer is simply copied to the 
+object, so it must point at persistent storage.  To use an XPM file do: 
+
      
+
      +#include <FL/Fl_Pixmap.H>
+#include "foo.xpm"
 ...
 Fl_Pixmap pixmap = new Fl_Pixmap(foo);
-
    - -

    ~Fl_Pixmap()

    - -The destructor will destroy any X pixmap created. It does not do -anything to the data. - -

    void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)

    - -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 pixmap (i.e. -ox and oy may be negative and w and -h may be bigger than the pixmap) and this area is left -unchanged. - -

    void draw(int x, int y)

    - -Draws the image with the upper-left corner at x,y. This is -the same as doing draw(x,y,this->w,this->h,0,0). - -

    void label(Fl_Widget *)

    - -Change the label() and the labeltype() of the widget -to draw the pixmap. You can use the same pixmap for many widgets. - - -

    class Fl_Image

    - -This object encapsulates a full-color RGB image, and allows you to make -an Fl_Widget use an image as a label, or to just draw the -image directly. Under X it will create an offscreen pixmap the -first time it is drawn, and copy this each subsequent time it is -drawn. - -

    Fl_Image(char uchar *data, int W, int H, int D = 3, int LD = 0)

    - -Construct using a pointer to RGB data. W and H are -the size of the image in pixels. D is the delta between -pixels (it may be more than 3 to skip alpha or other data, or negative -to flip the image left/right). LD is the delta between lines -(it may be more than D * W to crop images, or negative to flip -the image vertically). The data pointer is simply copied to the -object, so it must point at persistent storage. - -

    ~Fl_Image()

    - -The destructor will destroy any X pixmap created. It does not do -anything to the data. - -

    void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)

    - -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)

    - -Draws the image with the upper-left corner at x,y. This is -the same as doing draw(x,y,this->w,this->h,0,0). - -

    void label(Fl_Widget *)

    - -Change the label() and the labeltype() of the widget -to draw the image. You can use the same image for many widgets. - - - + +
+

~Fl_Pixmap()

+ The destructor will destroy any X pixmap created. It does not do +anything to the data. +

void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)

+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 pixmap (i.e. +ox and oy may be negative and w and h + may be bigger than the pixmap) and this area is left unchanged. +

void draw(int x, int y)

+ Draws the image with the upper-left corner at x,y. This is +the same as doing draw(x,y,this->w,this->h,0,0). +

void label(Fl_Widget *)

+ Change the label() and the labeltype() of the widget +to draw the pixmap. You can use the same pixmap for many widgets. +

class Fl_Image

+ This object encapsulates a full-color RGB image, and allows you to +make an Fl_Widget use an image as a label, or to just draw the +image directly. Under X it will create an offscreen pixmap the first +time it is drawn, and copy this each subsequent time it is drawn. +

Fl_Image(char uchar *data, int W, int H, int D = 3, int LD = 0)

+ Construct using a pointer to RGB data. W and H are +the size of the image in pixels. D is the delta between pixels +(it may be more than 3 to skip alpha or other data, or negative to flip +the image left/right). LD is the delta between lines (it may +be more than D * W to crop images, or negative to flip the +image vertically). The data pointer is simply copied to the object, so +it must point at persistent storage. +

~Fl_Image()

+ The destructor will destroy any X pixmap created. It does not do +anything to the data. +

void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)

+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)

+ Draws the image with the upper-left corner at x,y. This is +the same as doing draw(x,y,this->w,this->h,0,0). +

void label(Fl_Widget *)

+ Change the label() and the labeltype() of the widget +to draw the image. You can use the same image for many widgets. \ No newline at end of file -- cgit v1.2.3