From 09daf20b81cdae78772f07c0af22a571d7cc73eb Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Thu, 29 Nov 2001 19:24:00 +0000 Subject: Documentation updates galore (up to chapter 7, still need to do chapter 8 and 9, tweek the appendices, and recapture the screenshots...) git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1786 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/drawing.html | 1158 +++++++++++++++++++++++++++----------------- 1 file changed, 715 insertions(+), 443 deletions(-) (limited to 'documentation/drawing.html') diff --git a/documentation/drawing.html b/documentation/drawing.html index 737d8264e..30a359247 100644 --- a/documentation/drawing.html +++ b/documentation/drawing.html @@ -1,90 +1,176 @@ - -

5 - Drawing Things in FLTK

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

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

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

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.

+ +

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

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

void fl_push_no_clip()

-Pushes an empty clip region on the stack so nothing will be clipped. + +

Pushes an empty clip region on the stack so nothing will be clipped. +

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

Restore the previous clip region. + +

+ + + +
Note: + +

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

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

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

-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

+ +

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

+ +

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 <FL/Enumerations.H>. + +

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)

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

+ +

Sets the color for all subsequent drawing operations. + +

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

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

Line dashes and thickness

+

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

+ +

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)

@@ -92,431 +178,617 @@ in the gray ramp or color cube is used. responsibility to set it back to the default with fl_line_style(0). -
-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! -
+
+ + + +
Note: -

style is a bitmask in which you 'or' 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. +

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.

-

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

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 +

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. The dashes array does not work on -Windows 95/98, use the dash styles instead. - -

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

+ +

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)

-Draw a single pixel at the given coordinates. + +

Draw a single pixel at the given coordinates. +

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

- Color a rectangle that exactly fills the given bounding box. + +

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

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)

- Draw a 1-pixel border inside this bounding box. + +

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_line(int x, int y, int x1, int y1, int x2, int y2) + +

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

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

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_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 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_yxline(int x, int y, int y1, int x2) +
void fl_yxline(int x, int y, int y1, int x2, int y3) + +

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)

- High-speed ellipse sections. These functions match the rather limited -circle drawing code provided by X and WIN32. 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 +
void fl_pie(int x, int y, int w, int h, double a1, double a2) + +

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

-

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 that are filled is less defined -than for the previous calls 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. +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.

+ +

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

- Save and restore the current transformation. The maximum depth of the -stack is 4. +
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_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_end_line() + +

Start and end drawing lines. +

void fl_begin_loop()
void fl_end_loop()

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

Start and end drawing a closed sequence of lines. +

void fl_begin_polygon() -
void fl_end_polygon()

- Start and end drawing a convex filled 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. +
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. + +

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

+

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

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

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

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)

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

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

fl_circle() draws incorrectly if the + transformation is both rotated and non-square scaled. + +

+ +

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 *, 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. +
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 align, Fl_Image *img = 0, int draw_symbols = 1)

+ +

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

If img is provided and is not NULL, the +image is drawn above or below the text as specified by the +align value. + +

The draw_symbols argument specifies whether or not +to look for symbol names starting with the "@" character. + +

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

+ +

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

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

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 pixel width of a nul-terminated string, a sequence of n - characters, or a single character in the current font. +
float fl_width(const char*, int n) +
float fl_width(uchar) + +

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)

- 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 (not "points"). 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.

+ +

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

+ +

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)

+ +

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 and not "points". Lines should be spaced +size pixels apart or more.

+

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

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

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

+ +

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

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.

+ +

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

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_image(const uchar *, int X, int Y, int W, int H, int D + +

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

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

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:

- + +

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

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

+ +

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

+ +

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.

+ +

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)

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

To use an XPM, do:

- + +

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)

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

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

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

-

~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 24-bit RGB 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: + +

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

FLTK also provides several image classes based on the three +standard image types for common file formats: +

-

~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(const 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. + +

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

+ +

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

+ +

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)

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

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). + + + -- cgit v1.2.3