source: rtems-graphics-toolkit/fltk-1.1.10/documentation/drawing.html @ 513eea1

Last change on this file since 513eea1 was 513eea1, checked in by Joel Sherrill <joel.sherrill@…>, on 01/09/10 at 22:43:24

2010-01-08 Joel Sherrill <joel.sherrill@…>

fltk 1.1.10. imported

  • ORIGIN: Updated.
  • Property mode set to 100644
File size: 36.2 KB
Line 
1<HTML>
2<HEAD>
3        <TITLE>5 - Drawing Things in FLTK</TITLE>
4</HEAD>
5<BODY>
6
7<H1 ALIGN="RIGHT"><A NAME="drawing">5 - Drawing Things in FLTK</A></H1>
8
9<P>This chapter covers the drawing functions that are provided with FLTK.
10
11<H2>When Can You Draw Things in FLTK?</H2>
12
13<P>There are only certain places you can execute drawing code in FLTK.
14Calling these functions at other places will result in undefined
15behavior!
16
17<UL>
18
19        <LI>The most common place is inside the virtual method
20        <A
21        href="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A>.
22        To write code here, you must subclass one of the
23        existing <TT>Fl_Widget</TT> classes and implement your
24        own version of <TT>draw()</TT>.</LI>
25
26        <LI>You can also write <A
27        href="common.html#boxtypes">boxtypes</A> and <A
28        href="common.html#labeltypes">labeltypes</A>. These are
29        small procedures that can be called by existing <A
30        HREF="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A>
31        methods. These &quot;types&quot; are identified by an
32        8-bit index that is stored in the widget's
33        <TT>box()</TT>, <TT>labeltype()</TT>, and possibly other
34        properties.</LI>
35
36        <LI>You can call <A
37        href="Fl_Window.html#Fl_Window.make_current"><TT>Fl_Window::make_current()</TT></A>
38        to do incremental update of a widget. Use <A
39        href=Fl_Widget.html#Fl_Widget.window><TT>Fl_Widget::window()</TT></A>
40        to find the window.</LI>
41
42</UL>
43
44<H2>FLTK Drawing Functions</H2>
45
46<P>To use the drawing functions you must first include the
47<TT>&lt;FL/fl_draw.H&gt;</TT> header file. FLTK provides the
48following types of drawing functions:
49
50<UL>
51
52        <LI><A href="#boxdraw">Boxes</A></LI>
53
54        <LI><A href="#clipping">Clipping</A></LI>
55
56        <LI><A href="#colors">Colors</A></LI>
57
58        <LI><A href="#lines">Line dashes and thickness</A></LI>
59
60        <LI><A href="#fast">Fast Shapes</A></LI>
61
62        <LI><A href="#complex">Complex Shapes</A></LI>
63
64        <LI><A href="#text">Text</A></LI>
65
66        <LI><A href="#images">Images</A></LI>
67
68        <LI><A href="#overlay">Overlay</A></LI>
69
70        <LI><A href="#offscreen">Offscreen Drawing</A></LI>
71
72</UL>
73
74<H3><A name="boxdraw">Boxes</A></H3>
75
76<P>FLTK provides three functions that can be used to draw boxes
77for buttons and other UI controls. Each function uses the
78supplied upper-lefthand corner and width and height to determine
79where to draw the box.
80
81<H4><A NAME="fl_draw_box">void fl_draw_box(Fl_Boxtype b, int x, int y, int w, int h, Fl_Color c);</A></H4>
82
83<P>The first box drawing function is <CODE>fl_draw_box()</CODE>
84which draws a standard boxtype <CODE>c</CODE> in the specified
85color <CODE>c</CODE>.
86
87<H4><A NAME="fl_frame">void fl_frame(const char *s, int x, int y, int w, int h);</A></H4>
88
89<P>The <CODE>fl_frame()</CODE> function draws a series of line
90segments around the given box. The string <CODE>s</CODE> must
91contain groups of 4 letters which specify one of 24 standard
92grayscale values, where 'A' is black and 'X' is white. The order
93of each set of 4 characters is: top, left, bottom, right. The
94results of calling <CODE>fl_frame()</CODE> with a string that is
95not a multiple of 4 characters in length are undefined.
96
97<P>The only difference between this function and
98<CODE>fl_frame2()</CODE> is the order of the line segments.
99
100<P>See also: <A HREF="common.html#fl_frame">fl_frame boxtype</A>.
101
102<H4><A NAME="fl_frame2">void fl_frame2(const char *s, int x, int y, int w, int h);</A></H4>
103
104<P>The <CODE>fl_frame2()</CODE> function draws a series of line
105segments around the given box. The string <CODE>s</CODE> must
106contain groups of 4 letters which specify one of 24 standard
107grayscale values, where 'A' is black and 'X' is white. The order
108of each set of 4 characters is: bottom, right, top, left. The
109results of calling <CODE>fl_frame2()</CODE> with a string that is
110not a multiple of 4 characters in length are undefined.
111
112<P>The only difference between this function and
113<CODE>fl_frame()</CODE> is the order of the line segments.
114
115<H3><A name="clipping">Clipping</A></H3>
116
117<P>You can limit all your drawing to a rectangular region by calling
118<TT>fl_push_clip</TT>, and put the drawings back by using <TT>fl_pop_clip</TT>.
119This rectangle is measured in pixels and is unaffected by the current
120transformation matrix.
121
122<P>In addition, the system may provide clipping when updating windows
123which may be more complex than a simple rectangle.</P>
124
125<H4><A name="fl_push_clip">void fl_clip(int x, int y, int w, int h)</A><BR>
126void fl_push_clip(int x, int y, int w, int h)</H4>
127
128<P>Intersect the current clip region with a rectangle and push this new
129region onto the stack. The <CODE>fl_clip()</CODE> name is deprecated and
130will be removed from future releases.
131
132<H4><A NAME=fl_push_no_clip>void fl_push_no_clip()</A></H4>
133
134<P>Pushes an empty clip region on the stack so nothing will be clipped.
135
136<H4><A NAME=fl_pop_clip>void fl_pop_clip()</A></H4>
137
138<P>Restore the previous clip region.
139
140<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
141<TR>
142        <TD><B>Note:</B>
143
144        <P>You must call <TT>fl_pop_clip()</TT> once for every
145        time you call <TT>fl_push_clip()</TT>. If you return to FLTK
146        with the clip stack not empty unpredictable results
147        occur.
148
149        </TD>
150</TR>
151</TABLE></CENTER>
152
153<H4><A NAME=fl_not_clipped>int fl_not_clipped(int x, int y, int w, int h)</A></H4>
154
155<P>Returns non-zero if any of the rectangle intersects the current clip
156region. If this returns 0 you don't have to draw the object.
157
158<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
159<TR>
160        <TD><B>Note:</B>
161
162        <P>Under X this returns 2 if the rectangle is partially
163        clipped, and 1 if it is entirely inside the clip region.
164
165        </TD>
166</TR>
167</TABLE></CENTER>
168
169<H4><A NAME=fl_clip_box>int fl_clip_box(int x, int y, int w, int h, int &amp;X, int &amp;Y, int &amp;W,
170int &amp;H)</A></H4>
171
172<P>Intersect the rectangle <TT>x,y,w,h</TT> with the current
173clip region and returns the bounding box of the result in
174<TT>X,Y,W,H</TT>. Returns non-zero if the resulting rectangle is
175different than the original. This can be used to limit the
176necessary drawing to a rectangle. <TT>W</TT> and <TT>H</TT> are
177set to zero if the rectangle is completely outside the region.
178
179<H4><A NAME=fl_clip_region>void fl_clip_region(Fl_Region r)
180<BR>Fl_Region fl_clip_region()</A></H4>
181
182<P>Replace the top of the clip stack with a clipping region of any shape.
183Fl_Region is an operating system specific type. The second form returns
184the current clipping region.
185
186<H3><A name="colors">Colors</A></H3>
187
188<P>FLTK manages colors as 32-bit unsigned integers. Values from
1890 to 255 represent colors from the FLTK 1.0.x standard colormap
190and are allocated as needed on screens without TrueColor
191support. The <TT>Fl_Color</TT> enumeration type defines the
192standard colors and color cube for the first 256 colors. All of
193these are named with symbols in <A
194href="enumerations.html#colors"><TT>&lt;FL/Enumerations.H&gt;</TT></A>.
195
196<P>Color values greater than 255 are treated as 24-bit RGB
197values. These are mapped to the closest color supported by the
198screen, either from one of the 256 colors in the FLTK 1.0.x
199colormap or a direct RGB value on TrueColor screens. You can
200generate 24-bit RGB color values using the <A
201HREF="functions.html#fl_rgb_color"><TT>fl_rgb_color()</TT></A>
202function.
203
204<H4><A name="fl_color">void fl_color(Fl_Color)</A></H4>
205
206<P>Sets the color for all subsequent drawing operations.
207
208<P>For colormapped displays, a color cell will be allocated out
209of <TT>fl_colormap</TT> the first time you use a color. If the
210colormap fills up then a least-squares algorithm is used to find
211the closest color.</P>
212
213<H4>Fl_Color fl_color()</H4>
214
215<P>Returns the last <TT>fl_color()</TT> that was set. This can
216be used for state save/restore.
217
218<H4>void fl_color(uchar r, uchar g, uchar b)</H4>
219
220<P>Set the color for all subsequent drawing operations. The
221closest possible match to the RGB color is used. The RGB color
222is used directly on TrueColor displays. For colormap visuals the
223nearest index in the gray ramp or color cube is used.
224
225<h3><A name="lines">Line Dashes and Thickness</a></h3>
226
227<P>FLTK supports drawing of lines with different styles and
228widths. Full functionality is not available under Windows 95, 98,
229and Me due to the reduced drawing functionality these operating
230systems provide.
231
232<h4><A NAME="fl_line_style">void fl_line_style(int style, int width=0, char* dashes=0)</A></h4>
233
234<P>Set how to draw lines (the "pen").  If you change this it is your
235responsibility to set it back to the default with
236<tt>fl_line_style(0)</tt>.
237
238<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
239<TR>
240        <TD><B>Note:</B>
241
242        <P>Because of how line styles are implemented on WIN32
243        systems, you <I>must</I> set the line style <I>after</I>
244        setting the drawing color. If you set the color after
245        the line style you will lose the line style settings!
246
247        </TD>
248</TR>
249</TABLE></CENTER>
250
251<P><i>style</i> is a bitmask which is a bitwise-OR of the following
252values. If you don't specify a dash type you will get a solid
253line. If you don't specify a cap or join type you will get a
254system-defined default of whatever value is fastest.
255
256<ul>
257
258        <li><tt>FL_SOLID&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -------</tt>
259
260        <li><tt>FL_DASH&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - - - -</tt>
261
262        <li><tt>FL_DOT&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; .......</tt>
263
264        <li><tt>FL_DASHDOT&nbsp;&nbsp;&nbsp; - . - .</tt>
265
266        <li><tt>FL_DASHDOTDOT - .. -</tt>
267
268        <li><tt>FL_CAP_FLAT</tt>
269
270        <li><tt>FL_CAP_ROUND</tt>
271
272        <li><tt>FL_CAP_SQUARE</tt> (extends past end point 1/2 line width)
273
274        <li><tt>FL_JOIN_MITER</tt> (pointed)
275
276        <li><tt>FL_JOIN_ROUND</tt>
277
278        <li><tt>FL_JOIN_BEVEL</tt> (flat)
279
280</ul>
281
282<P><i>width</i> is the number of pixels thick to draw the lines.
283Zero results in the system-defined default, which on both X and
284Windows is somewhat different and nicer than 1.
285
286<!-- NEED 4in -->
287
288<P><i>dashes</i> is a pointer to an array of dash lengths, measured in
289pixels.  The first location is how long to draw a solid portion, the
290next is how long to draw the gap, then the solid, etc.  It is
291terminated with a zero-length entry. A <TT>NULL</TT> pointer or a zero-length
292array results in a solid line. Odd array sizes are not supported and
293result in undefined behavior.
294
295<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
296<TR>
297        <TD><B>Note:</B>
298
299        <P>The dashes array does not work under Windows 95, 98,
300        or Me, since those operating systems do not support
301        complex line styles.
302
303        </TD>
304</TR>
305</TABLE></CENTER>
306
307<H3><A name="fast">Drawing Fast Shapes</A></H3>
308
309<P>These functions are used to draw almost all the FLTK widgets.
310They draw on exact pixel boundaries and are as fast as possible.
311Their behavior is duplicated exactly on all platforms FLTK is
312ported. It is undefined whether these are affected by the <A
313href="#complex">transformation matrix</A>, so you should only
314call these while the matrix is set to the identity matrix (the
315default).
316
317<H4><A NAME=fl_point>void fl_point(int x, int y)</A></H4>
318
319<P>Draw a single pixel at the given coordinates.
320
321<H4><A NAME=fl_rectf>void fl_rectf(int x, int y, int w, int h)
322<BR>void fl_rectf(int x, int y, int w, int h)</A></H4>
323
324<P>Color a rectangle that exactly fills the given bounding box.
325
326<H4>void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b)</H4>
327
328<P>Color a rectangle with &quot;exactly&quot; the passed
329<TT>r,g,b</TT> color. On screens with less than 24 bits of
330color this is done by drawing a solid-colored block using <A
331href="#fl_draw_image"><TT>fl_draw_image()</TT></A> so that
332the correct color shade is produced.
333
334<H4><A NAME=fl_rect>void fl_rect(int x, int y, int w, int h)
335<BR>void fl_rect(int x, int y, int w, int h, Fl_Color c)</A></H4>
336
337<P>Draw a 1-pixel border <I>inside</I> this bounding box.
338
339<H4><A NAME=fl_line>void fl_line(int x, int y, int x1, int y1)
340<BR>void fl_line(int x, int y, int x1, int y1, int x2, int y2)</A></H4>
341
342<P>Draw one or two lines between the given points.
343
344<H4><A NAME=fl_loop>void fl_loop(int x, int y, int x1, int y1, int x2, int y2)
345<BR>void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3,
346int y3)</A></H4>
347
348<P>Outline a 3 or 4-sided polygon with lines.
349
350<H4><A NAME=fl_polygon>void fl_polygon(int x, int y, int x1, int y1, int x2, int y2)
351<BR>void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int
352x3, int y3)</A></H4>
353
354<P>Fill a 3 or 4-sided polygon. The polygon must be convex.
355
356<H4><A NAME=fl_xyline>void fl_xyline(int x, int y, int x1)
357<BR>void fl_xyline(int x, int y, int x1, int y2)
358<BR>void fl_xyline(int x, int y, int x1, int y2, int x3)</A></H4>
359
360<P>Draw horizontal and vertical lines. A horizontal line is
361drawn first, then a vertical, then a horizontal.
362
363<H4><A NAME=fl_yxline>void fl_yxline(int x, int y, int y1)
364<BR>void fl_yxline(int x, int y, int y1, int x2)
365<BR>void fl_yxline(int x, int y, int y1, int x2, int y3)</A></H4>
366
367<P>Draw vertical and horizontal lines. A vertical line is drawn
368first, then a horizontal, then a vertical.
369
370<H4><A NAME=fl_pie>void fl_arc(int x, int y, int w, int h, double a1, double a2)
371<BR>void fl_pie(int x, int y, int w, int h, double a1, double a2)</A></H4>
372
373<P>Draw ellipse sections using integer coordinates. These
374functions match the rather limited circle drawing code provided
375by X and WIN32. The advantage over using <A
376href="#fl_arc"><TT>fl_arc</TT></A> with floating point
377coordinates is that they are faster because they often use the
378hardware, and they draw much nicer small circles, since the
379small sizes are often hard-coded bitmaps.
380
381<P>If a complete circle is drawn it will fit inside the passed bounding
382box. The two angles are measured in degrees counterclockwise from
3833'oclock and are the starting and ending angle of the arc, <TT>a2</TT>
384must be greater or equal to <TT>a1</TT>.</P>
385
386<P><TT>fl_arc()</TT> draws a series of lines to approximate the arc.
387Notice that the integer version of <TT>fl_arc()</TT> has a different
388number of arguments than the <A href="#fl_arc"><TT>fl_arc()</TT></A>
389function described later in this chapter.</P>
390
391<P><TT>fl_pie()</TT> draws a filled-in pie slice. This slice may
392extend outside the line drawn by <TT>fl_arc</TT>; to avoid this
393use <TT>w - 1</TT> and <TT>h - 1</TT>.</P>
394
395<h4><a name=fl_scroll>void fl_scroll(int X, int Y, int W, int H, int dx, int dy,
396void (*draw_area)(void*, int,int,int,int), void* data)</a></h4>
397
398<P>Scroll a rectangle and draw the newly exposed portions. The contents
399of the rectangular area is first shifted by <tt>dx</tt> and
400<tt>dy</tt> pixels. The callback is then called for every newly
401exposed rectangular area,
402
403<H3><A name="complex">Drawing Complex Shapes</A></H3>
404
405<P>The complex drawing functions let you draw arbitrary shapes
406with 2-D linear transformations. The functionality matches that
407found in the Adobe&reg; PostScript<SUP>TM</SUP> language. The
408exact pixels that are filled are less defined than for the fast
409drawing functions so that FLTK can take advantage of drawing
410hardware. On both X and WIN32 the transformed vertices are
411rounded to integers before drawing the line segments: this
412severely limits the accuracy of these functions for complex
413graphics, so use OpenGL when greater accuracy and/or performance
414is required.
415
416<H4><A NAME=fl_push_matrix>void fl_push_matrix()
417<BR>void fl_pop_matrix()</A></H4>
418
419<P>Save and restore the current transformation.  The maximum
420depth of the stack is 4.
421
422<H4><A NAME=fl_scale>void fl_scale(float x, float y)
423<BR>void fl_scale(float x)
424<BR>void fl_translate(float x, float y)
425<BR>void fl_rotate(float d)
426<BR>void fl_mult_matrix(float a, float b, float c, float d, float
427x, float y)</A></H4>
428
429<P>Concatenate another transformation onto the current one. The rotation
430angle is in degrees (not radians) and is counter-clockwise.
431
432<H4><A NAME=fl_transform>double fl_transform_x(double x, double y)
433<BR>double fl_transform_y(double x, double y)
434<BR>double fl_transform_dx(double x, double y)
435<BR>double fl_transform_dy(double x, double y)
436<BR>void fl_transformed_vertex(double xf, double yf)</A></H4>
437
438<P>Transform a coordinate or a distance trough the current transformation matrix.
439After transforming a coordinate pair, it can be added to the vertex
440list without any further translations using <tt>fl_transformed_vertex</tt>.
441
442<H4><A NAME=fl_begin_points>void fl_begin_points()
443<BR>void fl_end_points()</A></H4>
444
445<P>Start and end drawing a list of points. Points are added to
446the list with <tt>fl_vertex</tt>.
447
448<H4><A NAME=fl_begin_line>void fl_begin_line()
449<BR>void fl_end_line()</A></H4>
450
451<P>Start and end drawing lines.
452
453<H4><A NAME=fl_begin_loop>void fl_begin_loop()
454<BR> void fl_end_loop()</A></H4>
455
456<P>Start and end drawing a closed sequence of lines.
457
458<H4><A NAME=fl_begin_polygon>void fl_begin_polygon()
459<BR>void fl_end_polygon()</A></H4>
460
461<P>Start and end drawing a convex filled polygon.
462
463<H4><A NAME=fl_begin_complex_polygon>void fl_begin_complex_polygon()
464<BR>void fl_gap()
465<BR>void fl_end_complex_polygon()</A></H4>
466
467<P>Start and end drawing a complex filled polygon. This polygon
468may be concave, may have holes in it, or may be several
469disconnected pieces. Call <TT>fl_gap()</TT> to separate loops of
470the path. It is unnecessary but harmless to call
471<TT>fl_gap()</TT> before the first vertex, after the last one,
472or several times in a row.
473
474<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
475<TR>
476        <TD><B>Note:</B>
477
478        <P>For portability, you should only draw polygons that
479        appear the same whether &quot;even/odd&quot; or
480        &quot;non-zero&quot; winding rules are used to fill
481        them. Holes should be drawn in the opposite direction of
482        the outside loop.
483
484        </TD>
485</TR>
486</TABLE></CENTER>
487
488<P><TT>fl_gap()</TT> should only be called between <TT>
489fl_begin_complex_polygon()</TT> and
490<TT>fl_end_complex_polygon()</TT>. To outline the polygon, use
491<TT>fl_begin_loop()</TT> and replace each <TT>fl_gap()</TT> with
492<TT>fl_end_loop();fl_begin_loop()</TT>.</P>
493
494<H4><A NAME=fl_vertex>void fl_vertex(float x, float y)</A></H4>
495Add a single vertex to the current path.
496
497<H4><A NAME=fl_curve>void fl_curve(float x, float y, float x1, float y1, float x2, float
498y2, float x3, float y3)</A></H4>
499
500<P>Add a series of points on a Bezier curve to the path.  The curve ends
501(and two of the points) are at <TT>x,y</TT> and <TT>x3,y3</TT>.
502
503<H4><A NAME="fl_arc">void fl_arc(float x, float y, float r, float start, float end)</A></H4>
504
505<P>Add a series of points to the current path on the arc of a
506circle; you can get elliptical paths by using scale and rotate
507before calling <TT>fl_arc()</TT>. <TT>x,y</TT> are the center of
508the circle, and <TT>r</TT> is its radius. <TT>fl_arc()</TT>
509takes <TT>start</TT> and <TT>end</TT> angles that are measured
510in degrees counter-clockwise from 3 o'clock.  If <TT>end</TT> is
511less than <TT>start</TT> then it draws the arc in a clockwise
512direction.
513
514<H4><A NAME=fl_circle>void fl_circle(float x, float y, float r)</A></H4>
515
516<P><TT>fl_circle()</TT> is equivalent to <TT>fl_arc(...,0,360)</TT> but
517may be faster. It must be the <I>only</I> thing in the path: if you
518want a circle as part of a complex polygon you must use <TT>fl_arc()</TT>.
519
520<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
521<TR>
522        <TD><B>Note:</B>
523
524        <P><TT>fl_circle()</TT> draws incorrectly if the
525        transformation is both rotated and non-square scaled.
526
527        </TD>
528</TR>
529</TABLE></CENTER>
530
531<H3><A name="text">Drawing Text</A></H3>
532
533<P>All text is drawn in the <A href="#fl_font">current font</A>.
534It is undefined whether this location or the characters are
535modified by the current transformation.
536
537<H4><A NAME=fl_draw>void fl_draw(const char *, int x, int y)
538<BR>void fl_draw(const char *, int n, int x, int y)</A></H4>
539
540<P>Draw a nul-terminated string or an array of <TT>n</TT> characters
541starting at the given location. Text is aligned to the left and to
542the baseline of the font. To align to the bottom, subtract fl_descent() from
543<i>y</i>. To align to the top, subtract fl_descent() and add fl_height().
544This version of fl_draw provides direct access to
545the text drawing function of the underlying OS. It does not apply any
546special handling to control characters.
547
548<H4>void fl_draw(const char *, int x, int y, int w, int h,
549Fl_Align align, Fl_Image *img = 0, int draw_symbols = 1)</H4>
550
551<P>Fancy string drawing function which is used to draw all the
552labels. The string is formatted and aligned inside the passed
553box.  Handles '\t' and '\n', expands all other control
554characters to ^X, and aligns inside or against the edges of the
555box described by <i>x</i>, <i>y</i>, <i>w</i> and <i>h</i>. See <A
556href="Fl_Widget.html#Fl_Widget.align"><TT>Fl_Widget::align()</TT></A>
557for values for <TT>align</TT>. The value
558<TT>FL_ALIGN_INSIDE</TT> is ignored, as this function always
559prints inside the box.
560
561<P>If <TT>img</TT> is provided and is not <TT>NULL</TT>, the
562image is drawn above or below the text as specified by the
563<TT>align</TT> value.
564
565<P>The <TT>draw_symbols</TT> argument specifies whether or not
566to look for symbol names starting with the "@" character.
567
568<P>The text length is limited to 1024 caracters per line.
569
570<H4><A NAME=fl_measure>void fl_measure(const char *, int &amp;w,
571int &amp;h, int draw_symbols = 1)</A></H4>
572
573<P>Measure how wide and tall the string will be when printed by
574the <TT>fl_draw(...align)</TT> function. If the incoming
575<TT>w</TT> is non-zero it will wrap to that width.
576
577<H4><A NAME=fl_height>int fl_height()</A></H4>
578
579<P>Recommended minimum line spacing for the current font.  You
580can also just use the value of <TT>size</TT> passed to <A
581href=#fl_font><TT>fl_font()</TT></A>.
582
583<H4><A NAME=fl_descent>int fl_descent()</A></H4>
584
585<P>Recommended distance above the bottom of a
586<TT>fl_height()</TT> tall box to draw the text at so it looks
587centered vertically in that box.
588
589<H4><A NAME=fl_width>float fl_width(const char*)
590<BR>float fl_width(const char*, int n)
591<BR>float fl_width(uchar)</A></H4>
592
593<P>Return the pixel width of a nul-terminated string, a sequence of <TT>n</TT>
594characters, or a single character in the current font.
595
596<H4><A NAME=fl_shortcut_label>const char *fl_shortcut_label(ulong)</A></H4>
597
598<P>Unparse a shortcut value as used by <A
599href="Fl_Button.html#Fl_Button.shortcut"><TT>Fl_Button</TT></A>
600or <A
601href="Fl_Menu_Item.html#Fl_Menu_Item"><TT>Fl_Menu_Item</TT></A>
602into a human-readable string like &quot;Alt+N&quot;.  This only
603works if the shortcut is a character key or a numbered function
604key. If the shortcut is zero an empty string is returned. The
605return value points at a static buffer that is overwritten with
606each call.
607
608<H3><A name="fonts">Fonts</A></H3>
609
610<P>FLTK supports a set of standard fonts based on the Times,
611Helvetica/Arial, Courier, and Symbol typefaces, as well as
612custom fonts that your application may load. Each font is
613accessed by an index into a font table.
614
615<P>Initially only the first 16 faces are filled in. There are
616symbolic names for them: <TT>FL_HELVETICA</TT>,
617<TT>FL_TIMES</TT>, <TT>FL_COURIER</TT>, and modifier values
618<TT>FL_BOLD</TT> and <TT>FL_ITALIC</TT> which can be added to
619these, and <TT>FL_SYMBOL</TT> and <TT>FL_ZAPF_DINGBATS</TT>.
620Faces greater than 255 cannot be used in <TT>Fl_Widget</TT>
621labels, since <TT>Fl_Widget</TT> stores the index as a byte.</P>
622
623<H4><A name="fl_font">void fl_font(int face, int size)</A></H4>
624
625<P>Set the current font, which is then used by the routines
626described above. You may call this outside a draw context if
627necessary to call <TT>fl_width()</TT>, but on X this will open
628the display.
629
630<P>The font is identified by a <TT>face</TT> and a
631<TT>size</TT>. The size of the font is measured in
632<TT>pixels</TT> and not "points". Lines should be spaced
633<TT>size</TT> pixels apart or more.</P>
634
635<H4><A NAME=fl_size>int fl_font()
636<BR>int fl_size()</A></H4>
637
638<P>Returns the face and size set by the most recent call to
639<TT>fl_font(a,b)</TT>. This can be used to save/restore the
640font.
641
642<H3><A NAME=character_encoding>Character Encoding</A></H3>
643
644<P>FLTK 1 supports western character sets using the eight bit encoding
645of the user-selected global code page. For MS Windows and X11, the code
646page is assumed to be Windows-1252/Latin1, a superset to ISO 8859-1.
647On Mac OS X, we assume MacRoman.
648
649<P>FLTK provides the functions <tt>fl_latin1_to_local</tt>,
650<tt>fl_local_to_latin1</tt>, <tt>fl_mac_roman_to_local</tt>, and
651<tt>fl_local_to_mac_roman</tt> to convert strings between both
652encodings. These functions are only required if your source
653code contains "C"-strings with international characters and
654if this source will be compiled on multiple platforms.
655
656<P>Assuming that the following source code was written on MS Windows,
657this example will output the correct label on OS X and X11 as well.
658Without the conversion call, the label on OS X would read
659<tt>Fahrvergn&cedil;gen</tt> with a deformed umlaut u.
660<PRE>
661  btn = new Fl_Button(10, 10, 300, 25);
662  btn-&gt;copy_label(fl_latin1_to_local("Fahrvergn&uuml;gen"));
663</PRE>
664
665<P>If your application uses characters that are not part of both
666encodings, or it will be used in areas that commonly use different
667code pages, yoou might consider upgrading to FLTK 2 which supports
668UTF-8 encoding.
669
670<H3><A name="overlay">Drawing Overlays</A></H3>
671
672<P>These functions allow you to draw interactive selection rectangles
673without using the overlay hardware. FLTK will XOR a single rectangle
674outline over a window.
675
676<H4>void fl_overlay_rect(int x, int y, int w, int h);
677<BR>void fl_overlay_clear();</H4>
678
679<P><TT>fl_overlay_rect()</TT> draws a selection rectangle, erasing any
680previous rectangle by XOR'ing it first. <TT>fl_overlay_clear()</TT>
681will erase the rectangle without drawing a new one.
682
683<P>Using these functions is tricky. You should make a widget
684with both a <TT>handle()</TT> and <TT>draw()</TT> method.
685<TT>draw()</TT> should call <TT>fl_overlay_clear()</TT> before
686doing anything else.  Your <TT>handle()</TT> method should call
687<TT>window()-&gt;make_current()</TT> and then
688<TT>fl_overlay_rect()</TT> after <TT>FL_DRAG</TT> events, and
689should call <TT>fl_overlay_clear()</TT> after a
690<TT>FL_RELEASE</TT> event.</P>
691
692<H2><A name="images">Drawing Images</A></H2>
693
694<P>To draw images, you can either do it directly from data in
695your memory, or you can create a <A
696href="#Fl_Image"><TT>Fl_Image</TT></A> object. The advantage of
697drawing directly is that it is more intuitive, and it is faster
698if the image data changes more often than it is redrawn. The
699advantage of using the object is that FLTK will cache translated
700forms of the image (on X it uses a server pixmap) and thus
701redrawing is <I>much</I> faster.
702
703<H3>Direct Image Drawing</H3>
704
705<P>The behavior when drawing images when the current
706transformation matrix is not the identity is not defined, so you
707should only draw images when the matrix is set to the identity.
708
709<H4><A NAME="fl_draw_image">void fl_draw_image(const uchar *, int X, int Y, int W, int H, int D
710= 3, int LD = 0)
711<BR>void fl_draw_image_mono(const uchar *, int X, int Y, int W, int H,
712int D = 1, int LD = 0)</A></H4>
713
714<P>Draw an 8-bit per color RGB or luminance image.  The pointer
715points at the &quot;r&quot; data of the top-left pixel. Color
716data must be in <TT>r,g,b</TT> order. <TT>X,Y</TT> are where to
717put the top-left corner. <TT>W</TT> and <TT>H</TT> define the
718size of the image. <TT>D</TT> is the delta to add to the pointer
719between pixels, it may be any value greater or equal to
720<TT>3</TT>, or it can be negative to flip the image
721horizontally. <TT>LD</TT> is the delta to add to the pointer
722between lines (if 0 is passed it uses <TT>W * D</TT>), and may
723be larger than <TT>W * D</TT> to crop data, or negative to flip
724the image vertically.
725
726<P>It is highly recommended that you put the following code before the
727first <TT>show()</TT> of <I>any</I> window in your program to get rid
728of the dithering if possible: </P>
729
730<UL><PRE>
731Fl::visual(FL_RGB);
732</PRE></UL>
733
734<P>Gray scale (1-channel) images may be drawn. This is done if
735<TT>abs(D)</TT> is less than 3, or by calling
736<TT>fl_draw_image_mono()</TT>. Only one 8-bit sample is used for
737each pixel, and on screens with different numbers of bits for
738red, green, and blue only gray colors are used. Setting
739<TT>D</TT> greater than 1 will let you display one channel of a
740color image.
741
742<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
743<TR>
744        <TD><B>Note:</B>
745
746        <P>The X version does not support all possible visuals.
747        If FLTK cannot draw the image in the current visual it
748        will abort. FLTK supports any visual of 8 bits or less,
749        and all common TrueColor visuals up to 32 bits.</P>
750
751        </TD>
752</TR>
753</TABLE></CENTER>
754
755<H4>typedef void (*fl_draw_image_cb)(void *, int x, int y, int w, uchar
756*)
757<BR>void fl_draw_image(fl_draw_image_cb, void *, int X, int Y, int W,
758int H, int D = 3)
759<BR>void fl_draw_image_mono(fl_draw_image_cb, void *, int X, int Y,
760int W, int H, int D = 1)</H4>
761
762<P>Call the passed function to provide each scan line of the
763image.  This lets you generate the image as it is being drawn,
764or do arbitrary decompression of stored data, provided it can be
765decompressed to individual scan lines easily.
766
767<P>The callback is called with the <TT>void *</TT> user data
768pointer which can be used to point at a structure of information
769about the image, and the <TT>x</TT>, <TT>y</TT>, and <TT>w</TT>
770of the scan line desired from the image. 0,0 is the upper-left
771corner of the image, <I>not <TT>X,Y</TT></I>. A pointer to a
772buffer to put the data into is passed. You must copy <TT>w</TT>
773pixels from scanline <TT>y</TT>, starting at pixel <TT>x</TT>,
774to this buffer.</P>
775
776<P>Due to cropping, less than the whole image may be requested.
777So <TT>x</TT> may be greater than zero, the first <TT>y</TT> may
778be greater than zero, and <TT>w</TT> may be less than
779<TT>W</TT>. The buffer is long enough to store the entire <TT>W
780* D</TT> pixels, this is for convenience with some decompression
781schemes where you must decompress the entire line at once:
782decompress it into the buffer, and then if <TT>x</TT> is not
783zero, copy the data over so the <TT>x</TT>'th pixel is at the
784start of the buffer.</P>
785
786<P>You can assume the <TT>y</TT>'s will be consecutive, except
787the first one may be greater than zero.</P>
788
789<P>If <TT>D</TT> is 4 or more, you must fill in the unused bytes
790with zero.</P>
791
792<H4><A NAME=fl_draw_pixmap>int fl_draw_pixmap(char **data, int X, int Y, Fl_Color = FL_GRAY)</A></H4>
793
794<P>Draws XPM image data, with the top-left corner at the given position.
795The image is dithered on 8-bit displays so you won't lose color space
796for programs displaying both images and pixmaps. This function returns
797zero if there was any error decoding the XPM data.
798
799<P>To use an XPM, do:</P>
800
801<UL><PRE>
802#include &quot;foo.xpm&quot;
803...
804fl_draw_pixmap(foo, X, Y);
805</PRE></UL>
806
807<P>Transparent colors are replaced by the optional
808<TT>Fl_Color</TT> argument. To draw with true transparency you must
809use the <A HREF="Fl_Pixmap.html"><TT>Fl_Pixmap</TT></A> class.
810
811<H4><A NAME=fl_measure_pixmap>int fl_measure_pixmap(char **data, int &amp;w, int &amp;h)</A></H4>
812
813<P>An XPM image contains the dimensions in its data. This
814function finds and returns the width and height. The return
815value is non-zero if the dimensions were parsed ok and zero if
816there was any problem.
817
818<H3>Direct Image Reading</H3>
819
820<p>FLTK provides a single function for reading from the current
821window or off-screen buffer into a RGB(A) image buffer.</p>
822
823<H4><A NAME="fl_read_image">uchar *fl_read_image(uchar *p, int
824X, int Y, int W, int H, int alpha = 0);</A></H4>
825
826<p>Read a RGB(A) image from the current window or off-screen
827buffer. The <tt>p</tt> argument points to a buffer that can hold
828the image and must be at least <tt>W*H*3</tt> bytes when reading
829RGB images and <tt>W*H*4</tt> bytes when reading RGBA images. If
830<tt>NULL</tt>, <tt>fl_read_image()</tt> will create an array of
831the proper size which can be freed using <tt>delete[]</tt>.</p>
832
833<p>The <tt>alpha</tt> parameter controls whether an alpha
834channel is created and the value that is placed in the alpha
835channel. If 0, no alpha channel is generated.</p>
836
837<H3><A name="Fl_Image">Image Classes</A></H3>
838
839<P>FLTK provides a base image class called <A
840HREF="Fl_Image.html"><TT>Fl_Image</TT></A> which supports
841creating, copying, and drawing images of various kinds, along
842with some basic color operations. Images can be used as labels
843for widgets using the <A
844HREF="Fl_Widget.html#Fl_Widget.image"><TT>image()</TT></A> and
845<A
846HREF="Fl_Widget.html#Fl_Widget.deimage"><TT>deimage()</TT></A>
847methods or drawn directly.
848
849<P>The <TT>Fl_Image</TT> class
850does almost nothing by itself, but is instead supported by three
851basic image types:
852
853<UL>
854
855        <LI><A HREF="Fl_Bitmap.html"><TT>Fl_Bitmap</TT></A></LI>
856
857        <LI><A HREF="Fl_Pixmap.html"><TT>Fl_Pixmap</TT></A></LI>
858
859        <LI><A HREF="Fl_RGB_Image.html"><TT>Fl_RGB_Image</TT></A></LI>
860
861</UL>
862
863<P>The <TT>Fl_Bitmap</TT> class encapsulates a mono-color bitmap image.
864The <TT>draw()</TT> method draws the image using the current drawing
865color.
866
867<P>The <TT>Fl_Pixmap</TT> class encapsulates a colormapped image.
868The <TT>draw()</TT> method draws the image using the colors in the
869file, and masks off any transparent colors automatically.
870
871<P>The <TT>Fl_RGB_Image</TT> class encapsulates a full-color
872(or grayscale) image with 1 to 4 color components. Images with
873an even number of components are assumed to contain an
874alpha channel that is used for transparency. The transparency
875provided by the <TT>draw()</TT> method is either a 24-bit
876blend against the existing window contents or a "screen door"
877transparency mask, depending on the platform and screen color depth.
878
879<H4><A NAME=fl_can_do_alpha_blending>char fl_can_do_alpha_blending()</A></H4>
880
881<P><TT>fl_can_do_alpha_blending()</TT> will return 1, if your
882platform supports true alpha blending for RGBA images, or 0,
883if FLTK will use screen door transparency.
884
885<P>FLTK also provides several image classes based on the three
886standard image types for common file formats:
887
888<UL>
889
890        <LI><A HREF="Fl_GIF_Image.html"><TT>Fl_GIF_Image</TT></A></LI>
891
892        <LI><A HREF="Fl_JPEG_Image.html"><TT>Fl_JPEG_Image</TT></A></LI>
893
894        <LI><A HREF="Fl_PNG_Image.html"><TT>Fl_PNG_Image</TT></A></LI>
895
896        <LI><A HREF="Fl_PNM_Image.html"><TT>Fl_PNM_Image</TT></A></LI>
897
898        <LI><A HREF="Fl_XBM_Image.html"><TT>Fl_XBM_Image</TT></A></LI>
899
900        <LI><A HREF="Fl_XPM_Image.html"><TT>Fl_XPM_Image</TT></A></LI>
901
902</UL>
903
904<P>Each of these image classes load a named file of the
905corresponding format. The <A
906HREF="Fl_Shared_Image.html"><TT>Fl_Shared_Image</TT></A> class
907can be used to load any type of image file - the class examines
908the file and constructs an image of the appropriate type.
909
910<P>Finally, FLTK provides a special image class called <A
911HREF="Fl_Tiled_Image.html"><TT>Fl_Tiled_Image</TT></A> to tile
912another image object in the specified area. This class can be
913used to tile a background image in a <TT>Fl_Group</TT> widget,
914for example.
915
916<H4>virtual void copy();<BR>
917virtual void copy(int w, int h);</H4>
918
919<P>The <TT>copy()</TT> method creates a copy of the image. The second form
920specifies the new size of the image - the image is resized using the
921nearest-neighbor algorithm.
922
923<H4>void draw(int x, int y, int w, int h, int ox = 0, int oy = 0);</H4>
924
925<P>The <TT>draw()</TT> method draws the image object.
926<TT>x,y,w,h</TT> indicates a destination rectangle.
927<TT>ox,oy,w,h</TT> is a source rectangle. This source rectangle
928is copied to the destination. The source rectangle may extend
929outside the image, i.e. <TT>ox</TT> and <TT>oy</TT> may be
930negative and <TT>w</TT> and <TT>h</TT> may be bigger than the
931image, and this area is left unchanged.
932
933<H4>void draw(int x, int y)</H4>
934
935<P>Draws the image with the upper-left corner at <TT>x,y</TT>.
936This is the same as doing <TT>draw(x,y,img-&gt;w(),img-&gt;h(),0,0)</TT>.
937
938<h3><A NAME=offscreen>Offscreen Drawing</A></h3>
939
940Sometimes it can be very useful to generate a complex drawing
941in memory first and copy it to the screen at a later point in
942time. This technique can significantly reduce the amount of
943repeated drawing. <tt>Fl_Double_Window</tt> uses offscreen rendering
944to avoid flickering on systems that don't support
945double-buffering natively.
946
947<H4><A NAME=fl_create_offscreen>Fl_Offscreen fl_create_offscreen(int w, int h)</A></H4>
948
949<P>Create an RGB offscreen buffer with <tt>w*h</tt> pixels.
950
951<H4><A NAME=fl_delete_offscreen>void fl_delete_offscreen(Fl_Offscreen)</A></H4>
952
953<P>Delete a previously created offscreen buffer. All drawings are lost.
954
955<H4><A NAME=fl_begin_offscreen>void fl_begin_offscreen(Fl_Offscreen)</A></H4>
956
957<P>Send all subsequent drawing commands to this offscreen buffer.
958FLTK can draw into a buffer at any time. There is no need to wait for
959an <tt>Fl_Widget::draw()</tt> to occur.
960
961<H4><A NAME=fl_end_offscreen>void fl_end_offscreen()</A></H4>
962
963<P>Quit sending drawing commands to this offscreen buffer.
964
965<H4><A NAME=fl_copy_offscreen>void fl_copy_offscreen(int x, int y,
966int w, int h, Fl_Offscreen osrc, int srcx, int srcy)</A></H4>
967
968<P>Copy a rectangular area of the size <tt>w*h</tt> from <tt>srcx, srcy</tt> in the offscreen
969buffer into the current buffer at <tt>x, y</tt>.
970
971</BODY>
972</HTML>
Note: See TracBrowser for help on using the repository browser.