30fa233681
Removed spreadsheet chapter (for the moment). git-svn-id: file:///fltk/svn/fltk/trunk@218 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
682 lines
27 KiB
HTML
682 lines
27 KiB
HTML
<HTML>
|
|
<BODY>
|
|
|
|
<H1><A NAME=drawing>5 - Drawing Things in FLTK</A></H1>
|
|
|
|
This chapter covers the drawing functions that are provided with FLTK.
|
|
|
|
<h2>When Can You Draw Things in FLTK?</h2>
|
|
|
|
There are only certain places you can execute drawing code in FLTK.
|
|
Calling these functions at other places will result in undefined
|
|
behavior!
|
|
|
|
<ul>
|
|
|
|
<li>The most common is inside the virtual method <a
|
|
href="#draw"><tt>Fl_Widget::draw()</tt></a>. To write code
|
|
here, you must subclass one of the existing <tt>Fl_Widget</tt>
|
|
classes and implement your own version of <tt>draw()</tt>.
|
|
|
|
<li>You can also write <a href="#boxtypes">boxtypes</a> and <a
|
|
href="#labeltypes">labeltypes</a>. These are small procedures
|
|
that can be called by existing <tt>Fl_Widget</tt>
|
|
<tt>draw()</tt> methods. These "types" are identified by an
|
|
8-bit index that is stored in the widget's <tt>box()</tt>,
|
|
<tt>labeltype()</tt>, and possibly other properties.
|
|
|
|
<li>You can call <a
|
|
href="#Fl_Window.make_current"><tt>Fl_Window::make_current()</tt></a>
|
|
to do incremental update of a widget. Use <a
|
|
href="#Fl_Widget.window"><tt>Fl_Widget::window()</tt></a> to
|
|
find the window. <i>Under X this only works for the base
|
|
<tt>Fl_Window</tt> class, not for double buffered, overlay, or
|
|
OpenGL windows!</i>
|
|
|
|
</ul>
|
|
|
|
<h2>FLTK Drawing Functions</h2>
|
|
|
|
To use the drawing functions you must first include the
|
|
<tt><FL/fl_draw.H></tt> header file. FLTK provides the following types
|
|
of drawing functions:
|
|
|
|
<ul>
|
|
<li><a href="#clipping">Clipping</a>
|
|
<li><a href="#color">Colors</a>
|
|
<li><a href="#fast">Fast Shapes</a>
|
|
<li><a href="#vertex">Complex Shapes</a>
|
|
<li><a href="#text">Text</a>
|
|
<li><a href="#images">Images</a>
|
|
<li><a href="#cursor">Cursor</a>
|
|
<li><a href="#overlay">Overlay</a>
|
|
</ul>
|
|
|
|
<h3><a name="clipping">Clipping</a></h3>
|
|
|
|
You can limit all your drawing to a rectangular region by calling
|
|
<tt>fl_clip</tt>, and put the drawings back by using
|
|
<tt>fl_pop_clip</tt>. This rectangle is measured in pixels (it is
|
|
unaffected by the current transformation matrix).
|
|
|
|
<p>In addition, the system may provide clipping when updating windows,
|
|
this clip region may be more complex than a simple rectangle.
|
|
|
|
<h4>void fl_clip(int x, int y, int w, int h)</h4>
|
|
|
|
Intersect the current clip region with a rectangle and push this new
|
|
region onto the stack.
|
|
|
|
<h4>void fl_pop_clip()</h4>
|
|
|
|
Restore the previous clip region. <i>You must call
|
|
<tt>fl_pop_clip()</tt> once for every time you call
|
|
<tt>fl_clip()</tt>. If you return to FLTK with the clip stack not
|
|
empty unpredictable results occur.</i>
|
|
|
|
<h4>int fl_not_clipped(int x, int y, int w, int h)</h4>
|
|
|
|
Returns true if any of the rectangle intersects the current clip
|
|
region. If this returns false you don't have to draw the object.
|
|
<i>Under X this returns 2 if the rectangle is partially clipped, and 1
|
|
if it is entirely inside the clip region</i>.
|
|
|
|
<h4>int fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H)</h4>
|
|
|
|
Intersect the rectangle <tt>x,y,w,h</tt> with the current clip region
|
|
and returns the bounding box of the result in <tt>X,Y,W,H</tt>.
|
|
Returns non-zero if the resulting rectangle is different than the
|
|
original. This can be used to limit the necessary drawing to a
|
|
rectangle. <tt>W</tt> and <tt>H</tt> are set to zero if the rectangle
|
|
is completely outside the region.
|
|
|
|
<h3><a name="colors">Colors</a></h3>
|
|
|
|
<h4>void fl_color(Fl_Color)</h4>
|
|
|
|
Set the color for all subsequent drawing operations. <tt>Fl_Color</tt>
|
|
is an enumeration type, and all values are in the range 0-255. This is
|
|
<i>not</i> 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 <a
|
|
href=#enumerations><tt><FL/Enumerations.H></tt></a>.
|
|
|
|
<p>For colormapped displays, a color cell will be allocated out of
|
|
<tt>fl_colormap</tt> the first time you use a color. If the colormap
|
|
fills up then a least-squares algorithm is used to find the closest
|
|
color.
|
|
|
|
<h4>Fl_Color fl_color()</h4>
|
|
|
|
Returns the last <tt>fl_color()</tt> that was set. This can be used for state
|
|
save/restore.
|
|
|
|
<h4>void fl_color(uchar r, uchar g, uchar b)</h4>
|
|
|
|
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.
|
|
|
|
<h3><a name="fast_shapes">Fast Shapes</a></h3>
|
|
|
|
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 <a
|
|
href="#complex_shapes">transformation matrix</a>, so you should only call these
|
|
while it is the identity.
|
|
|
|
<h4>void fl_rectf(int x, int y, int w, int h)</h4>
|
|
|
|
Color a rectangle that exactly fills the given bounding box.
|
|
|
|
<h4>void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b)</h4>
|
|
|
|
Color a rectangle with "exactly" the passed <tt>r,g,b</tt> color. On
|
|
screens with less than 24 bits of color this is done by drawing a
|
|
solid-colored block using <a
|
|
href="#fl_draw_image"><tt>fl_draw_image()</tt></a> so that dithering is
|
|
produced.
|
|
|
|
<h4>void fl_rect(int x, int y, int w, int h)</h4>
|
|
|
|
Draw a 1-pixel border <i>inside</i> this bounding box.
|
|
|
|
<h4>void fl_line(int x, int y, int x1, int y1)<br>
|
|
void fl_line(int x, int y, int x1, int y1, int x2, int y2)</h4>
|
|
|
|
Draw one or two 1-pixel thick lines between the given points.
|
|
|
|
<h4>void fl_loop(int x, int y, int x1, int y1, int x2, int y2)<br>
|
|
void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3)</h4>
|
|
|
|
Outline a 3 or 4-sided polygon with 1-pixel thick lines.
|
|
|
|
<h4>void fl_polygon(int x, int y, int x1, int y1, int x2, int y2)<br>
|
|
void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3)</h4>
|
|
|
|
Fill a 3 or 4-sided polygon. The polygon must be convex.
|
|
|
|
<h4>void fl_xyline(int x, int y, int x1, int y1)<br>
|
|
void fl_xyline(int x, int y, int x1, int y1, int x2)<br>
|
|
void fl_xyline(int x, int y, int x1, int y1, int x2, int y3)</h4>
|
|
|
|
Draw 1-pixel wide horizontal and vertical lines. A horizontal line is
|
|
drawn first, then a vertical, then a horizontal.
|
|
|
|
<h4>void fl_yxline(int x, int y, int y1)<br>
|
|
void fl_yxline(int x, int y, int y1, int x2)<br>
|
|
void fl_yxline(int x, int y, int y1, int x2, int y3)</h4>
|
|
|
|
Draw 1-pixel wide vertical and horizontal lines. A vertical line is
|
|
drawn first, then a horizontal, then a vertical.
|
|
|
|
<h4>void fl_arc(int x, int y, int w, int h, double a1, double a2)<br>
|
|
void fl_pie(int x, int y, int w, int h, double a1, double a2)<br>
|
|
void fl_chord(int x, int y, int w, int h, double a1, double a2)</h4>
|
|
|
|
High-speed ellipse sections. These functions match the rather limited
|
|
circle drawing code provided by X and MSWindows. The advantage over
|
|
using <a href="#fl_arc"><tt>fl_arc</tt></a> 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.
|
|
|
|
<p>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, <tt>a2</tt>
|
|
must be greater or equal to <tt>a1</tt>.
|
|
|
|
<p><tt>fl_arc()</tt> draws a 1-pixel thick line (notice this has a different
|
|
number of arguments than the <a href="#fl_arc"><tt>fl_arc()</tt></a> described
|
|
below.
|
|
|
|
<p><tt>fl_pie()</tt> draws a filled-in pie slice. This slice may extend outside
|
|
the line drawn by <tt>fl_arc</tt>, to avoid this use <tt>w - 1</tt> and
|
|
<tt>h - 1</tt>.
|
|
|
|
<p><tt>fl_chord()</tt> is not yet implemented.
|
|
|
|
<h3><a name="complex_shapes">Complex Shapes</a></h3>
|
|
|
|
These functions let you draw arbitrary shapes with 2-D linear
|
|
transformations. The functionality matches that found in Adobe®
|
|
PostScript<sup>TM</sup>. 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.
|
|
|
|
<h4>void fl_push_matrix()<br>
|
|
void fl_pop_matrix()</h4>
|
|
|
|
Save and restore the current transformation. The maximum depth of the
|
|
stack is 4.
|
|
|
|
<h4>void fl_scale(float x, float y)<br>
|
|
void fl_scale(float x)<br>
|
|
void fl_translate(float x, float y)<br>
|
|
void fl_rotate(float d)<br>
|
|
void fl_mult_matrix(float a, float b, float c, float d, float x, float y)</h4>
|
|
|
|
Concatenate another transformation onto the current one. The rotation angle
|
|
is in degrees (not radians) and is counter-clockwise.
|
|
|
|
<h4>void fl_begin_line()<br>
|
|
void fl_end_line()</h4>
|
|
|
|
Start and end drawing 1-pixel thick lines.
|
|
|
|
<h4>void fl_begin_loop()<br>
|
|
void fl_end_loop()</h4>
|
|
|
|
Start and end drawing a closed sequence of 1-pixel thick lines.
|
|
|
|
<h4>void fl_begin_polygon()<br>
|
|
void fl_end_polygon()</h4>
|
|
|
|
Start and end drawing a convex filled polygon.
|
|
|
|
<h4>void fl_begin_complex_polygon()<br>
|
|
void fl_gap()<br>
|
|
void fl_end_complex_polygon()</h4>
|
|
|
|
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 <tt>fl_gap()</tt> to seperate loops of the path (it is unnecessary
|
|
but harmless to call <tt>fl_gap()</tt> 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.
|
|
|
|
<p><tt>fl_gap()</tt> should only be called between
|
|
<tt>fl_begin_complex_polygon()</tt> and
|
|
<tt>fl_end_complex_polygon()</tt>. To outline the polygon, use
|
|
<tt>fl_begin_loop()</tt> and replace each <tt>fl_gap()</tt> with
|
|
<tt>fl_end_loop();fl_begin_loop()<tt>.
|
|
|
|
<h4>void fl_vertex(float x, float y)</h4>
|
|
|
|
Add a single vertex to the current path.
|
|
|
|
<h4>void fl_curve(float x, float y, float x1, float y1, float x2, float y2, float x3, float y3)</h4>
|
|
|
|
Add a series of points on a Bezier curve to the path. The curve ends
|
|
(and two of the points) are at <tt>x,y</tt> and <tt>x3,y3</tt>.
|
|
|
|
<h4>void fl_arc(float x, float y, float r, float start, float end)</h4>
|
|
|
|
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). <tt>x,y</tt> are the center of the circle, and <tt>r</tt> is
|
|
its radius. <tt>fl_arc()</tt> takes <tt>start</tt> and <tt>end</tt>
|
|
angles that are measured in degrees counter-clockwise from 3 o'clock.
|
|
If <tt>end</tt> is less than <tt>start</tt> then it draws the arc in a
|
|
clockwise direction.
|
|
|
|
<h4>void fl_circle(float x, float y, float r)</h4>
|
|
|
|
<tt>fl_circle()</tt> is equivalent to <tt>fl_arc(...,0,360)</tt> but
|
|
may be faster. It must be the <i>only</i> thing in the path: if you
|
|
want a circle as part of a complex polygon you must use
|
|
<tt>fl_arc()</tt>. <i>This draws incorrectly if the transformation is
|
|
both rotated and non-square scaled.</i>
|
|
|
|
<h3><a name="text">Text</a></h3>
|
|
|
|
All text is drawn in the <a href="#fl_font">current font</a>. It is
|
|
undefined whether this location or the characters are modified by the
|
|
current transformation.
|
|
|
|
<h4>void fl_draw(const char *, float x, float y)<br>
|
|
void fl_draw(const char *, int n, float x, float y)</h4>
|
|
|
|
Draw a nul-terminated string or an array of <tt>n</tt> characters
|
|
starting at the given location.
|
|
|
|
<h4>void fl_draw(const char *, int x, int y, int w, int h, Fl_Align)</h4>
|
|
|
|
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 <a
|
|
href="#Fl_Widget.align"><tt>Fl_Widget::align()</tt></a> for values for
|
|
<tt>align</tt>. The value <tt>FL_ALIGN_INSIDE</tt> is ignored, as this
|
|
function always prints inside the box.
|
|
|
|
<h4>void fl_measure(const char *, int &w, int &h)</h4>
|
|
|
|
Measure how wide and tall the string will be when printed by the
|
|
<tt>fl_draw(...align)</tt> function. If the incoming <tt>w</tt> is
|
|
non-zero it will wrap to that width.
|
|
|
|
<h4>int fl_height()</h4>
|
|
|
|
Recommended minimum line spacing for the current font. You can also
|
|
just use the value of <tt>size</tt> passed to <a href="#fl_font">
|
|
<tt>fl_font()</tt></a>.
|
|
|
|
<h4>int fl_descent()</h4>
|
|
|
|
Recommended distance above the bottom of a <tt>fl_height()</tt> tall
|
|
box to draw the text at so it looks centered vertically in that box.
|
|
|
|
<h4>float fl_width(const char*)<br>
|
|
float fl_width(const char*, int n)<br>
|
|
float fl_width(uchar)</h4>
|
|
|
|
Return the width of a nul-terminated string, a sequence of <tt>n</tt>
|
|
characters, or a single character.
|
|
|
|
<h4>const char *fl_shortcut_label(ulong)</h4>
|
|
|
|
Unparse a shortcut value as used by <a
|
|
href="#Fl_Button.shortcut"><tt>Fl_Button</tt></a> or <a
|
|
href="#Fl_Menu_Item"><tt>Fl_Menu_Item</tt></a> 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.
|
|
|
|
<h3><a name="fonts">Fonts</a></h3>
|
|
|
|
<h4><a name="fl_font">void fl_font(int face, int size)</a></h4>
|
|
|
|
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
|
|
<tt>fl_width()</tt>, but on X this will open the display.
|
|
|
|
<p>The font is identified by a <tt>face</tt> and a <tt>size</tt>. The
|
|
size of the font is measured in <tt>pixels</tt> (i.e. it is not
|
|
"resolution [in]dependent"). Lines should be spaced <tt>size</tt>
|
|
pixels apart (or more).
|
|
|
|
<p>The <tt>face</tt> is an index into an internal table. Initially
|
|
only the first 16 faces are filled in. There are symbolic names for
|
|
them: <tt>FL_HELVETICA</tt>, <tt>FL_TIMES</tt>, <tt>FL_COURIER</tt>,
|
|
and modifier values <tt>FL_BOLD</tt> and <tt>FL_ITALIC</tt> which can
|
|
be added to these, and <tt>FL_SYMBOL</tt> and
|
|
<tt>FL_ZAPF_DINGBATS</tt>. Faces greater than 255 cannot be used in
|
|
<tt>Fl_Widget</tt> labels, since it stores the index as a byte.
|
|
|
|
<h4>int fl_font()<br>
|
|
int fl_size()</h4>
|
|
|
|
Returns the face and size set by the most recent call to
|
|
<tt>fl_font(a,b)</tt>. This can be used to save/restore the font.
|
|
|
|
<h3><a name="cursor">Cursor</a></h3>
|
|
|
|
<h4>void fl_cursor(Fl_Cursor, Fl_Color = FL_WHITE, Fl_Color = FL_BLACK)</h4>
|
|
|
|
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 <tt>FL_LEAVE</tt> events.
|
|
|
|
<p>The type <tt>Fl_Cursor</tt> is an enumeration defined in <a
|
|
href="#enumerations"><tt><Enumerations.H></tt></a>. 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 <tt>Fl_Cursor((XC_foo/2)+1)</tt>.
|
|
|
|
<p>The following standard cursors are available:
|
|
|
|
<ul>
|
|
<li><tt>FL_CURSOR_DEFAULT</tt> - the default cursor, usually an arrow
|
|
<li><tt>FL_CURSOR_ARROW</tt> - an arrow pointer
|
|
<li><tt>FL_CURSOR_CROSS</tt> - crosshair
|
|
<li><tt>FL_CURSOR_WAIT</tt> - watch or hourglass
|
|
<li><tt>FL_CURSOR_INSERT</tt> - I-beam
|
|
<li><tt>FL_CURSOR_HAND</tt> - hand (uparrow on MSWindows)
|
|
<li><tt>FL_CURSOR_HELP</tt> - question mark
|
|
<li><tt>FL_CURSOR_MOVE</tt> - 4-pointed arrow
|
|
<li><tt>FL_CURSOR_NS</tt> - up/down arrow
|
|
<li><tt>FL_CURSOR_WE</tt> - left/right arrow
|
|
<li><tt>FL_CURSOR_NWSE</tt> - diagonal arrow
|
|
<li><tt>FL_CURSOR_NESW</tt> - diagonal arrow
|
|
<li><tt>FL_CURSOR_NONE</tt> - invisible
|
|
</ul>
|
|
|
|
<h3><a name="overlay">Overlays</a></h3>
|
|
|
|
<h4>void fl_overlay_rect(int x, int y, int w, int h)<br>
|
|
void fl_overlay_clear()</h4>
|
|
|
|
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
|
|
<tt>fl_overlay_clear()</tt> will erase the rectangle without drawing a
|
|
new one.
|
|
|
|
<p>Using this is tricky. You should make a widget with both a
|
|
<tt>handle()</tt> and <tt>draw()</tt> method. <tt>draw()</tt> should
|
|
call <tt>fl_overlay_clear()</tt> before doing anything else. Your
|
|
<tt>handle()</tt> method should call <tt>window()->make_current()</tt>
|
|
and then <tt>fl_overlay_rect()</tt> after <tt>FL_DRAG</tt> events, and
|
|
should call <tt>fl_overlay_clear()</tt> after a <tt>FL_RELEASE</tt>
|
|
event.
|
|
|
|
<h2><a name="images">Images</a></h2>
|
|
|
|
To draw images, you can either do it directly from data in your memory,
|
|
or you can create <a href="#Fl_Bitmap"><tt>Fl_Bitmap</tt></a>, <a
|
|
href="#Fl_Image"><tt>Fl_Image</tt></a>, or <a
|
|
href="#Fl_Pixmap"><tt>Fl_Pixmap</tt></a> 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 <i>much</i>
|
|
faster.
|
|
|
|
<h3>Direct Image Drawing</h3>
|
|
|
|
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.
|
|
|
|
<h4>void fl_draw_bitmap(const uchar *, int X, int Y, int W, int H, int LD = 0)</h4>
|
|
|
|
This function is planned but not yet implemented (it may be impossible
|
|
under X without allocating a pixmap).
|
|
|
|
<h4>void fl_draw_image(const uchar *, int X, int Y, int W, int H, int D = 3, int LD = 0)<br>
|
|
void fl_draw_image_mono(const uchar *, int X, int Y, int W, int H, int D = 1, int LD = 0)</h4>
|
|
|
|
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 <tt>r,g,b</tt>
|
|
order. <tt>X,Y</tt> are where to put the top-left corner. <tt>W</tt>
|
|
and <tt>H</tt> define the size of the image. <tt>D</tt> is the delta
|
|
to add to the pointer between pixels, it may be any value greater or
|
|
equal to <tt>3</tt>, or it can be negative to flip the image
|
|
horizontally. <tt>LD</tt> is the delta to add to the pointer between
|
|
lines (if 0 is passed it uses <tt>W * D</tt>), and may be larger than
|
|
<tt>W * D</tt> to crop data, or negative to flip the image vertically.
|
|
|
|
<p>It is highly recommended that you put the following code before the
|
|
first <tt>show()</tt> of <i>any</i> window in your program to get rid
|
|
of the dithering if possible:
|
|
|
|
<ul><pre>
|
|
Fl::visual(FL_RGB);
|
|
</pre></ul>
|
|
|
|
Gray scale (1-channel) images may be drawn. This is done if
|
|
<tt>abs(D)</tt> is less than 3, or by calling
|
|
<tt>fl_draw_image_mono()</tt>. 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 <tt>D</tt> greater than 1
|
|
will let you display one channel of a color image.
|
|
|
|
<p><i>The X version does not support all possible visuals.</i> 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.
|
|
|
|
<h4>typedef void (*fl_draw_image_cb)(void *, int x, int y, int w, uchar *)<br>
|
|
void fl_draw_image(fl_draw_image_cb, void *, int X, int Y, int W, int H, int D = 3)<br>
|
|
void fl_draw_image_mono(fl_draw_image_cb, void *, int X, int Y, int W, int H, int D = 1)</h4>
|
|
|
|
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).
|
|
|
|
<p>The callback is called with the <tt>void *</tt> user data pointer
|
|
(this can be used to point at a structure of information about the
|
|
image), and the <tt>x</tt>, <tt>y</tt>, and <tt>w</tt> of the scan line
|
|
desired from the image. 0,0 is the upper-left corner (<i>not
|
|
<tt>X,Y</tt></i>). A pointer to a buffer to put the data into is
|
|
passed. You must copy <tt>w</tt> pixels from scanline <tt>y</tt>,
|
|
starting at pixel <tt>x</tt>, to this buffer.
|
|
|
|
<p>Due to cropping, less than the whole image may be requested. So
|
|
<tt>x</tt> may be greater than zero, the first <tt>y</tt> may be
|
|
greater than zero, and <tt>w</tt> may be less than <tt>W</tt>. The
|
|
buffer is long enough to store the entire <tt>W * D</tt> 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 <tt>x</tt> is not zero, copy the data over so the <tt>x</tt>'th
|
|
pixel is at the start of the buffer.
|
|
|
|
<p>You can assume the <tt>y</tt>'s will be consecutive, except the first one
|
|
may be greater than zero.
|
|
|
|
<p>If <tt>D</tt> is 4 or more, you must fill in the unused bytes with zero.
|
|
|
|
<h4>int fl_draw_pixmap(char **data, int X, int Y, Fl_Color = FL_GRAY)</h4>
|
|
|
|
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.
|
|
|
|
<p>To use an XPM, do:
|
|
|
|
<ul><pre>
|
|
#include "foo.xpm"
|
|
...
|
|
fl_draw_pixmap(foo, X, Y);
|
|
</pre></ul>
|
|
|
|
In the current version the XPM data is converted to 8-bit full color
|
|
and passed through <tt>fl_draw_image()</tt>. This is obviously not the
|
|
most efficient way to do it, and has the same visual limitations as
|
|
listed above for <tt>fl_draw_image()</tt>. Transparent colors are
|
|
replaced by the optional <tt>Fl_Color</tt> argument (this may change in
|
|
the future).
|
|
|
|
<h4>int fl_measure_pixmap(char **data, int &w, int &h)</h4>
|
|
|
|
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.
|
|
|
|
<h3><a name="Fl_Bitmap">class Fl_Bitmap</a></h3>
|
|
|
|
This object encapsulates the width, height, and bits of an X bitmap
|
|
(XBM), and allows you to make an <tt>Fl_Widget</tt> 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.
|
|
|
|
<h4>Fl_Bitmap(const char *bits, int W, int H)<br>
|
|
Fl_Bitmap(const uchar *bits, int W, int H)</h4>
|
|
|
|
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:
|
|
|
|
<ul><pre>
|
|
#include "foo.xbm"
|
|
...
|
|
Fl_Bitmap bitmap = new Fl_Bitmap(foo_bits, foo_width, foo_height);
|
|
</pre></ul>
|
|
|
|
<h4>~Fl_Bitmap()</h4>
|
|
|
|
The destructor will destroy any X pixmap created. It does not do
|
|
anything to the bits data.
|
|
|
|
<h4>void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)</h4>
|
|
|
|
<tt>x,y,w,h</tt> indicates a destination rectangle. <tt>ox,oy,w,h</tt>
|
|
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. <tt>ox</tt> and <tt>oy</tt> may be negative and <tt>w</tt> and
|
|
<tt>h</tt> may be bigger than the bitmap) and this area is left
|
|
unchanged.
|
|
|
|
<h4>void draw(int x, int y)</h4>
|
|
|
|
Draws the bitmap with the upper-left corner at <tt>x,y</tt>. This is
|
|
the same as doing <tt>draw(x,y,this->w,this->h,0,0)</tt>.
|
|
|
|
<h4>void label(Fl_Widget *)</h4>
|
|
|
|
Change the <tt>label()</tt> and the <tt>labeltype()</tt> of the widget
|
|
to draw the bitmap. 1 bits will be drawn with the
|
|
<tt>labelcolor()</tt>, zero bits will be unchanged. You can use the
|
|
same bitmap for many widgets.
|
|
|
|
|
|
<h2><a name="Fl_Pixmap">class Fl_Pixmap</h2>
|
|
|
|
This object encapsulates the data from an XPM image, and allows you to
|
|
make an <tt>Fl_Widget</tt> use a pixmap as a label, or to just draw the
|
|
pixmap directly. <i>Under X it will create an offscreen pixmap the
|
|
first time it is drawn, and copy this each subsequent time it is
|
|
drawn</i>.
|
|
|
|
<p>The current implementation converts the pixmap to 8 bit color data
|
|
and uses <a href="#fl_draw_image"><tt>fl_draw_image()</tt></a> to draw
|
|
it. Thus you will get dithered colors on an 8 bit screen.
|
|
|
|
<h4>Fl_Pixmap(char *const* data)</h4>
|
|
|
|
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:
|
|
|
|
<ul><pre>
|
|
#include <FL/Fl_Pixmap.H>
|
|
#include "foo.xpm"
|
|
...
|
|
Fl_Pixmap pixmap = new Fl_Pixmap(foo);
|
|
</ul></pre>
|
|
|
|
<h4>~Fl_Pixmap()</h4>
|
|
|
|
The destructor will destroy any X pixmap created. It does not do
|
|
anything to the data.
|
|
|
|
<h4>void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)</h4>
|
|
|
|
<tt>x,y,w,h</tt> indicates a destination rectangle. <tt>ox,oy,w,h</tt>
|
|
is a source rectangle. This source rectangle is copied to the
|
|
destination. The source rectangle may extend outside the pixmap (i.e.
|
|
<tt>ox</tt> and <tt>oy</tt> may be negative and <tt>w</tt> and
|
|
<tt>h</tt> may be bigger than the pixmap) and this area is left
|
|
unchanged.
|
|
|
|
<h4>void draw(int x, int y)</h4>
|
|
|
|
Draws the image with the upper-left corner at <tt>x,y</tt>. This is
|
|
the same as doing <tt>draw(x,y,this->w,this->h,0,0)</tt>.
|
|
|
|
<h4>void label(Fl_Widget *)</h4>
|
|
|
|
Change the <tt>label()</tt> and the <tt>labeltype()</tt> of the widget
|
|
to draw the pixmap. You can use the same pixmap for many widgets.
|
|
|
|
|
|
<H3><a name="Fl_Image">class Fl_Image</a></H3>
|
|
|
|
This object encapsulates a full-color RGB image, and allows you to make
|
|
an <tt>Fl_Widget</tt> use an image as a label, or to just draw the
|
|
image directly. <i>Under X it will create an offscreen pixmap the
|
|
first time it is drawn, and copy this each subsequent time it is
|
|
drawn</i>.
|
|
|
|
<h4>Fl_Image(char uchar *data, int W, int H, int D = 3, int LD = 0)</h4>
|
|
|
|
Construct using a pointer to RGB data. <tt>W</tt> and <tt>H</tt> are
|
|
the size of the image in pixels. <tt>D</tt> 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). <tt>LD</tt> is the delta between lines
|
|
(it may be more than <tt>D * W</tt> 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.
|
|
|
|
<h4>~Fl_Image()</h4>
|
|
|
|
The destructor will destroy any X pixmap created. It does not do
|
|
anything to the data.
|
|
|
|
<h4>void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)</h4>
|
|
|
|
<tt>x,y,w,h</tt> indicates a destination rectangle. <tt>ox,oy,w,h</tt>
|
|
is a source rectangle. This source rectangle is copied to the
|
|
destination. The source rectangle may extend outside the image (i.e.
|
|
<tt>ox</tt> and <tt>oy</tt> may be negative and <tt>w</tt> and
|
|
<tt>h</tt> may be bigger than the image) and this area is left
|
|
unchanged.
|
|
|
|
<h4>void draw(int x, int y)</h4>
|
|
|
|
Draws the image with the upper-left corner at <tt>x,y</tt>. This is
|
|
the same as doing <tt>draw(x,y,this->w,this->h,0,0)</tt>.
|
|
|
|
<h4>void label(Fl_Widget *)</h4>
|
|
|
|
Change the <tt>label()</tt> and the <tt>labeltype()</tt> of the widget
|
|
to draw the image. You can use the same image for many widgets.
|
|
|
|
</BODY>
|
|
</HTML>
|