mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Another bunch of doxygen updates: *.dox. Fixed links and many html tags.

Browse Source 
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6287 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Albrecht Schlosser 2008-09-17 21:13:03 +00:00
parent a2eaf60572
commit 74cbd55745
13 changed files with 361 additions and 385 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
documentation/development.dox
View File

@ -83,7 +83,7 @@ From Duncan: (will be removed later, just for now as a reminder)
5. I've just added comments for the fl_color_chooser() functions, and
in order to keep them and the general Function Reference information
for them together, I created a new doxygen group, and used \ingroup
for them together, I created a new doxygen group, and used \\ingroup
in the three comment blocks. This creates a new Modules page (which
may not be what we want) with links to it from the File Members and
Fl_Color_Chooser.H pages. It needs a bit more experimentation on my

315
documentation/drawing.dox
View File

@ -13,26 +13,23 @@ behavior!
<UL>
<LI>The most common place is inside the virtual method
<A
href="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A>.
<A href="subclassing.html#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>
existing Fl_Widget classes and implement your
own version of draw().</LI>
<LI>You can also write <A
href="common.html#boxtypes">boxtypes</A> and <A
href="common.html#labeltypes">labeltypes</A>. These are
small procedures that can be called by existing <A
HREF="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A>
methods. These &quot;types&quot; are identified by an
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
box(), labeltype(), and possibly other
properties.</LI>
<LI>You can call <A
href="Fl_Window.html#Fl_Window.make_current"><TT>Fl_Window::make_current()</TT></A>
to do incremental update of a widget. Use <A
href=Fl_Widget.html#Fl_Widget.window><TT>Fl_Widget::window()</TT></A>
<LI>You can call Fl_Window::make_current() to do incremental
update of a widget. Use Fl_Widget::window()
to find the window.</LI>
</UL>
@ -40,7 +37,7 @@ behavior!
<H2>FLTK Drawing Functions</H2>
<P>To use the drawing functions you must first include the
<TT>&lt;FL/fl_draw.H&gt;</TT> header file. FLTK provides the
<FL/fl_draw.H> header file. FLTK provides the
following types of drawing functions:
<UL>
@ -111,7 +108,7 @@ not a multiple of 4 characters in length are undefined.
<H3><A name="clipping">Clipping</A></H3>
<P>You can limit all your drawing to a rectangular region by calling
<TT>fl_push_clip</TT>, and put the drawings back by using <TT>fl_pop_clip</TT>.
fl_push_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.
@ -125,11 +122,11 @@ void fl_push_clip(int x, int y, int w, int h)</H4>
region onto the stack. The <CODE>fl_clip()</CODE> name is deprecated and
will be removed from future releases.
<H4><A NAME=fl_push_no_clip>void fl_push_no_clip()</A></H4>
<H4><A NAME="fl_push_no_clip">void fl_push_no_clip()</A></H4>
<P>Pushes an empty clip region on the stack so nothing will be clipped.
<H4><A NAME=fl_pop_clip>void fl_pop_clip()</A></H4>
<H4><A NAME="fl_pop_clip">void fl_pop_clip()</A></H4>
<P>Restore the previous clip region.
@ -137,8 +134,8 @@ will be removed from future releases.
<TR>
<TD><B>Note:</B>
<P>You must call <TT>fl_pop_clip()</TT> once for every
time you call <TT>fl_push_clip()</TT>. If you return to FLTK
<P>You must call fl_pop_clip() once for every
time you call fl_push_clip(). If you return to FLTK
with the clip stack not empty unpredictable results
occur.
@ -146,7 +143,7 @@ will be removed from future releases.
</TR>
</TABLE></CENTER>
<H4><A NAME=fl_not_clipped>int fl_not_clipped(int x, int y, int w, int h)</A></H4>
<H4><A NAME="fl_not_clipped">int fl_not_clipped(int x, int y, int w, int h)</A></H4>
<P>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.
@ -162,8 +159,8 @@ region. If this returns 0 you don't have to draw the object.
</TR>
</TABLE></CENTER>
<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,
int &amp;H)</A></H4>
<H4><A NAME="fl_clip_box">int fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W,
int &H)</A></H4>
<P>Intersect the rectangle <TT>x,y,w,h</TT> with the current
clip region and returns the bounding box of the result in
@ -172,7 +169,7 @@ 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.
<H4><A NAME=fl_clip_region>void fl_clip_region(Fl_Region r)
<H4><A NAME="fl_clip_region">void fl_clip_region(Fl_Region r)
<BR>Fl_Region fl_clip_region()</A></H4>
<P>Replace the top of the clip stack with a clipping region of any shape.
@ -184,10 +181,10 @@ the current clipping region.
<P>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 <TT>Fl_Color</TT> enumeration type defines the
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 <A
href="enumerations.html#colors"><TT>&lt;FL/Enumerations.H&gt;</TT></A>.
href="enumerations.html#colors"><TT><FL/Enumerations.H></TT></A>.
<P>Color values greater than 255 are treated as 24-bit RGB
values. These are mapped to the closest color supported by the
@ -208,7 +205,7 @@ the closest color.</P>
<H4>Fl_Color fl_color()</H4>
<P>Returns the last <TT>fl_color()</TT> that was set. This can
<P>Returns the last fl_color() that was set. This can
be used for state save/restore.
<H4>void fl_color(uchar r, uchar g, uchar b)</H4>
@ -229,7 +226,7 @@ systems provide.
<P>Set how to draw lines (the "pen"). If you change this it is your
responsibility to set it back to the default with
<tt>fl_line_style(0)</tt>.
fl_line_style(0).
<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
<TR>
@ -249,7 +246,7 @@ 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.
<ul>
<UL>
<li><tt>FL_SOLID&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -------</tt>
@ -273,7 +270,7 @@ system-defined default of whatever value is fastest.
<li><tt>FL_JOIN_BEVEL</tt> (flat)
</ul>
</UL>
<P><i>width</i> is the number of pixels thick to draw the lines.
Zero results in the system-defined default, which on both X and
@ -310,60 +307,60 @@ href="#complex">transformation matrix</A>, so you should only
call these while the matrix is set to the identity matrix (the
default).
<H4><A NAME=fl_point>void fl_point(int x, int y)</A></H4>
<H4><A NAME="fl_point">void fl_point(int x, int y)</A></H4>
<P>Draw a single pixel at the given coordinates.
<H4><A NAME=fl_rectf>void fl_rectf(int x, int y, int w, int h)
<H4><A NAME="fl_rectf">void fl_rectf(int x, int y, int w, int h)
<BR>void fl_rectf(int x, int y, int w, int h)</A></H4>
<P>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>
<P>Color a rectangle with &quot;exactly&quot; the passed
<P>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
the correct color shade is produced.
<H4><A NAME=fl_rect>void fl_rect(int x, int y, int w, int h)
<H4><A NAME="fl_rect">void fl_rect(int x, int y, int w, int h)
<BR>void fl_rect(int x, int y, int w, int h, Fl_Color c)</A></H4>
<P>Draw a 1-pixel border <I>inside</I> this bounding box.
<H4><A NAME=fl_line>void fl_line(int x, int y, int x1, int y1)
<H4><A NAME="fl_line">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)</A></H4>
<P>Draw one or two lines between the given points.
<H4><A NAME=fl_loop>void fl_loop(int x, int y, int x1, int y1, int x2, int y2)
<H4><A NAME="fl_loop">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)</A></H4>
<P>Outline a 3 or 4-sided polygon with lines.
<H4><A NAME=fl_polygon>void fl_polygon(int x, int y, int x1, int y1, int x2, int y2)
<H4><A NAME="fl_polygon">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)</A></H4>
<P>Fill a 3 or 4-sided polygon. The polygon must be convex.
<H4><A NAME=fl_xyline>void fl_xyline(int x, int y, int x1)
<H4><A NAME="fl_xyline">void fl_xyline(int x, int y, int x1)
<BR>void fl_xyline(int x, int y, int x1, int y2)
<BR>void fl_xyline(int x, int y, int x1, int y2, int x3)</A></H4>
<P>Draw horizontal and vertical lines. A horizontal line is
drawn first, then a vertical, then a horizontal.
<H4><A NAME=fl_yxline>void fl_yxline(int x, int y, int y1)
<H4><A NAME="fl_yxline">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)</A></H4>
<P>Draw vertical and horizontal lines. A vertical line is drawn
first, then a horizontal, then a vertical.
<H4><A NAME=fl_pie>void fl_arc(int x, int y, int w, int h, double a1, double a2)
<H4><A NAME="fl_pie">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)</A></H4>
<P>Draw ellipse sections using integer coordinates. These
@ -379,16 +376,16 @@ 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>
<P><TT>fl_arc()</TT> draws a series of lines to approximate the arc.
Notice that the integer version of <TT>fl_arc()</TT> has a different
<P>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 <A href="#fl_arc"><TT>fl_arc()</TT></A>
function described later in this chapter.</P>
<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
<P>fl_pie() draws a filled-in pie slice. This slice may
extend outside the line drawn by fl_arc(); to avoid this
use <TT>w - 1</TT> and <TT>h - 1</TT>.</P>
<h4><a name=fl_scroll>void fl_scroll(int X, int Y, int W, int H, int dx, int dy,
<h4><a name="fl_scroll">void fl_scroll(int X, int Y, int W, int H, int dx, int dy,
void (*draw_area)(void*, int,int,int,int), void* data)</a></h4>
<P>Scroll a rectangle and draw the newly exposed portions. The contents
@ -409,13 +406,13 @@ severely limits the accuracy of these functions for complex
graphics, so use OpenGL when greater accuracy and/or performance
is required.
<H4><A NAME=fl_push_matrix>void fl_push_matrix()
<H4><A NAME="fl_push_matrix">void fl_push_matrix()
<BR>void fl_pop_matrix()</A></H4>
<P>Save and restore the current transformation. The maximum
depth of the stack is 4.
<H4><A NAME=fl_scale>void fl_scale(float x, float y)
<H4><A NAME="fl_scale">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)
@ -425,7 +422,7 @@ x, float y)</A></H4>
<P>Concatenate another transformation onto the current one. The rotation
angle is in degrees (not radians) and is counter-clockwise.
<H4><A NAME=fl_transform>double fl_transform_x(double x, double y)
<H4><A NAME="fl_transform">double fl_transform_x(double x, double y)
<BR>double fl_transform_y(double x, double y)
<BR>double fl_transform_dx(double x, double y)
<BR>double fl_transform_dy(double x, double y)
@ -435,36 +432,36 @@ angle is in degrees (not radians) and is counter-clockwise.
After transforming a coordinate pair, it can be added to the vertex
list without any forther translations using <tt>fl_transformed_vertex</tt>.
<H4><A NAME=fl_begin_points>void fl_begin_points()
<H4><A NAME="fl_begin_points">void fl_begin_points()
<BR>void fl_end_points()</A></H4>
<P>Start and end drawing a list of points. Points are added to
the list with <tt>fl_vertex</tt>.
<H4><A NAME=fl_begin_line>void fl_begin_line()
<H4><A NAME="fl_begin_line">void fl_begin_line()
<BR>void fl_end_line()</A></H4>
<P>Start and end drawing lines.
<H4><A NAME=fl_begin_loop>void fl_begin_loop()
<H4><A NAME="fl_begin_loop">void fl_begin_loop()
<BR> void fl_end_loop()</A></H4>
<P>Start and end drawing a closed sequence of lines.
<H4><A NAME=fl_begin_polygon>void fl_begin_polygon()
<H4><A NAME="fl_begin_polygon">void fl_begin_polygon()
<BR>void fl_end_polygon()</A></H4>
<P>Start and end drawing a convex filled polygon.
<H4><A NAME=fl_begin_complex_polygon>void fl_begin_complex_polygon()
<H4><A NAME="fl_begin_complex_polygon">void fl_begin_complex_polygon()
<BR>void fl_gap()
<BR>void fl_end_complex_polygon()</A></H4>
<P>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
disconnected pieces. Call fl_gap() to separate loops of
the path. It is unnecessary but harmless to call
<TT>fl_gap()</TT> before the first vertex, after the last one,
fl_gap() before the first vertex, after the last one,
or several times in a row.
<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
@ -472,8 +469,8 @@ or several times in a row.
<TD><B>Note:</B>
<P>For portability, you should only draw polygons that
appear the same whether &quot;even/odd&quot; or
&quot;non-zero&quot; winding rules are used to fill
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.
@ -481,16 +478,16 @@ or several times in a row.
</TR>
</TABLE></CENTER>
<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>.</P>
<P>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().</P>
<H4><A NAME=fl_vertex>void fl_vertex(float x, float y)</A></H4>
<H4><A NAME="fl_vertex">void fl_vertex(float x, float y)</A></H4>
Add a single vertex to the current path.
<H4><A NAME=fl_curve>void fl_curve(float x, float y, float x1, float y1, float x2, float
<H4><A NAME="fl_curve">void fl_curve(float x, float y, float x1, float y1, float x2, float
y2, float x3, float y3)</A></H4>
<P>Add a series of points on a Bezier curve to the path. The curve ends
@ -500,24 +497,24 @@ y2, float x3, float y3)</A></H4>
<P>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 <TT>fl_arc()</TT>. <TT>x,y</TT> are the center of
the circle, and <TT>r</TT> is its radius. <TT>fl_arc()</TT>
before calling fl_arc(). <TT>x,y</TT> are the center of
the circle, and <TT>r</TT> is its radius. fl_arc()
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><A NAME=fl_circle>void fl_circle(float x, float y, float r)</A></H4>
<H4><A NAME="fl_circle">void fl_circle(float x, float y, float r)</A></H4>
<P><TT>fl_circle()</TT> is equivalent to <TT>fl_arc(...,0,360)</TT> but
<P>fl_circle() is equivalent to fl_arc(...,0,360) 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>.
want a circle as part of a complex polygon you must use fl_arc().
<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
<TR>
<TD><B>Note:</B>
<P><TT>fl_circle()</TT> draws incorrectly if the
<P>fl_circle() draws incorrectly if the
transformation is both rotated and non-square scaled.
</TD>
@ -530,7 +527,7 @@ want a circle as part of a complex polygon you must use <TT>fl_arc()</TT>.
It is undefined whether this location or the characters are
modified by the current transformation.
<H4><A NAME=fl_draw>void fl_draw(const char *, int x, int y)
<H4><A NAME="fl_draw">void fl_draw(const char *, int x, int y)
<BR>void fl_draw(const char *, int n, int x, int y)</A></H4>
<P>Draw a nul-terminated string or an array of <TT>n</TT> characters
@ -548,9 +545,8 @@ Fl_Align align, Fl_Image *img = 0, int draw_symbols = 1)</H4>
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 described by <i>x</i>, <i>y</i>, <i>w</i> and <i>h</i>. See <A
href="Fl_Widget.html#Fl_Widget.align"><TT>Fl_Widget::align()</TT></A>
for values for <TT>align</TT>. The value
box described by <i>x</i>, <i>y</i>, <i>w</i> and <i>h</i>. See
Fl_Widget::align() for values for <TT>align</TT>. The value
<TT>FL_ALIGN_INSIDE</TT> is ignored, as this function always
prints inside the box.
@ -563,39 +559,36 @@ to look for symbol names starting with the "@" character.
<P>The text length is limited to 1024 caracters per line.
<H4><A NAME=fl_measure>void fl_measure(const char *, int &amp;w,
int &amp;h, int draw_symbols = 1)</A></H4>
<H4><A NAME="fl_measure">void fl_measure(const char *, int &w,
int &h, int draw_symbols = 1)</A></H4>
<P>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><A NAME=fl_height>int fl_height()</A></H4>
<H4><A NAME="fl_height">int fl_height()</A></H4>
<P>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>.
href="#fl_font"><TT>fl_font()</TT></A>.
<H4><A NAME=fl_descent>int fl_descent()</A></H4>
<H4><A NAME="fl_descent">int fl_descent()</A></H4>
<P>Recommended distance above the bottom of a
<TT>fl_height()</TT> tall box to draw the text at so it looks
fl_height() tall box to draw the text at so it looks
centered vertically in that box.
<H4><A NAME=fl_width>float fl_width(const char*)
<H4><A NAME="fl_width">float fl_width(const char*)
<BR>float fl_width(const char*, int n)
<BR>float fl_width(uchar)</A></H4>
<P>Return the pixel width of a nul-terminated string, a sequence of <TT>n</TT>
characters, or a single character in the current font.
<H4><A NAME=fl_shortcut_label>const char *fl_shortcut_label(ulong)</A></H4>
<H4><A NAME="fl_shortcut_label">const char *fl_shortcut_label(ulong)</A></H4>
<P>Unparse a shortcut value as used by <A
href="Fl_Button.html#Fl_Button.shortcut"><TT>Fl_Button</TT></A>
or <A
href="Fl_Menu_Item.html#Fl_Menu_Item"><TT>Fl_Menu_Item</TT></A>
into a human-readable string like &quot;Alt+N&quot;. This only
<P>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
@ -609,18 +602,18 @@ custom fonts that your application may load. Each font is
accessed by an index into a font table.
<P>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 <TT>Fl_Widget</TT> stores the index as a byte.</P>
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.</P>
<H4><A name="fl_font">void fl_font(int face, int size)</A></H4>
<P>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
necessary to call fl_width(), but on X this will open
the display.
<P>The font is identified by a <TT>face</TT> and a
@ -628,23 +621,23 @@ the display.
<TT>pixels</TT> and not "points". Lines should be spaced
<TT>size</TT> pixels apart or more.</P>
<H4><A NAME=fl_size>int fl_font()
<H4><A NAME="fl_size">int fl_font()
<BR>int fl_size()</A></H4>
<P>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
fl_font(a,b). This can be used to save/restore the
font.
<H3><A NAME=character_encoding>Character Encoding</A></H3>
<H3><A NAME="character_encoding">Character Encoding</A></H3>
<P>FLTK 1 supports western character sets using the eight bit encoding
of the user-selected global code page. For MS Windows and X11, the code
page is assumed to be Windows-1252/Latin1, a superset to ISO 8859-1.
On Mac OS X, we assume MacRoman.
<P>FLTK provides the functions <tt>fl_latin1_to_local</tt>,
<tt>fl_local_to_latin1</tt>, <tt>fl_mac_roman_to_local</tt>, and
<tt>fl_local_to_mac_roman</tt> to convert strings between both
<P>FLTK provides the functions fl_latin1_to_local(),
fl_local_to_latin1(), fl_mac_roman_to_local(), and
fl_local_to_mac_roman() to convert strings between both
encodings. These functions are only required if your source
code contains "C"-strings with international characters and
if this source will be compiled on multiple platforms.
@ -653,10 +646,10 @@ if this source will be compiled on multiple platforms.
this example will output the correct label on OS X and X11 as well.
Without the conversion call, the label on OS X would read
<tt>Fahrvergn&cedil;gen</tt> with a deformed umlaut u.
<PRE>
\code
btn = new Fl_Button(10, 10, 300, 25);
btn-&gt;copy_label(fl_latin1_to_local("Fahrvergn&uuml;gen"));
</PRE>
btn->copy_label(fl_latin1_to_local("Fahrvergn&uuml;gen"));
\endcode
<P>If your application uses characters that are not part of both
encodings, or it will be used in areas that commonly use different
@ -672,24 +665,23 @@ outline over a window.
<H4>void fl_overlay_rect(int x, int y, int w, int h);
<BR>void fl_overlay_clear();</H4>
<P><TT>fl_overlay_rect()</TT> draws a selection rectangle, erasing any
previous rectangle by XOR'ing it first. <TT>fl_overlay_clear()</TT>
<P>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.
<P>Using these functions 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()-&gt;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.</P>
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.</P>
<H2><A name="images">Drawing Images</A></H2>
<P>To draw images, you can either do it directly from data in
your memory, or you can create a <A
href="#Fl_Image"><TT>Fl_Image</TT></A> object. The advantage of
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
@ -708,7 +700,7 @@ should only draw images when the matrix is set to the identity.
int D = 1, int LD = 0)</A></H4>
<P>Draw an 8-bit per color RGB or luminance image. The pointer
points at the &quot;r&quot; data of the top-left pixel. Color
points at the "r" data of the top-left pixel. Color
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
@ -720,16 +712,16 @@ 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
first show() of <I>any</I> window in your program to get rid
of the dithering if possible: </P>
<UL><PRE>
\code
Fl::visual(FL_RGB);
</PRE></UL>
\endcode
<P>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
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
<TT>D</TT> greater than 1 will let you display one channel of a
@ -785,7 +777,7 @@ the first one may be greater than zero.</P>
<P>If <TT>D</TT> is 4 or more, you must fill in the unused bytes
with zero.</P>
<H4><A NAME=fl_draw_pixmap>int fl_draw_pixmap(char **data, int X, int Y, Fl_Color = FL_GRAY)</A></H4>
<H4><A NAME="fl_draw_pixmap">int fl_draw_pixmap(char **data, int X, int Y, Fl_Color = FL_GRAY)</A></H4>
<P>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
@ -794,17 +786,17 @@ zero if there was any error decoding the XPM data.
<P>To use an XPM, do:</P>
<UL><PRE>
#include &quot;foo.xpm&quot;
\code
#include "foo.xpm"
...
fl_draw_pixmap(foo, X, Y);
</PRE></UL>
\endcode
<P>Transparent colors are replaced by the optional
<TT>Fl_Color</TT> argument. To draw with true transparency you must
use the <A HREF="Fl_Pixmap.html"><TT>Fl_Pixmap</TT></A> class.
Fl_Color argument. To draw with true transparency you must
use the Fl_Pixmap class.
<H4><A NAME=fl_measure_pixmap>int fl_measure_pixmap(char **data, int &amp;w, int &amp;h)</A></H4>
<H4><A NAME="fl_measure_pixmap">int fl_measure_pixmap(char **data, int &w, int &h)</A></H4>
<P>An XPM image contains the dimensions in its data. This
function finds and returns the width and height. The return
@ -832,49 +824,43 @@ channel. If 0, no alpha channel is generated.</p>
<H3><A name="Fl_Image">Image Classes</A></H3>
<P>FLTK provides a base image class called <A
HREF="Fl_Image.html"><TT>Fl_Image</TT></A> which supports
<P>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 <A
HREF="Fl_Widget.html#Fl_Widget.image"><TT>image()</TT></A> and
<A
HREF="Fl_Widget.html#Fl_Widget.deimage"><TT>deimage()</TT></A>
methods or drawn directly.
for widgets using the image() and deimage() methods or drawn directly.
<P>The <TT>Fl_Image</TT> class
does almost nothing by itself, but is instead supported by three
basic image types:
<P>The Fl_Image class does almost nothing by itself, but is instead
supported by three basic image types:
<UL>
<LI><A HREF="Fl_Bitmap.html"><TT>Fl_Bitmap</TT></A></LI>
<LI>Fl_Bitmap</LI>
<LI><A HREF="Fl_Pixmap.html"><TT>Fl_Pixmap</TT></A></LI>
<LI>Fl_Pixmap</LI>
<LI><A HREF="Fl_RGB_Image.html"><TT>Fl_RGB_Image</TT></A></LI>
<LI>Fl_RGB_Image</LI>
</UL>
<P>The <TT>Fl_Bitmap</TT> class encapsulates a mono-color bitmap image.
The <TT>draw()</TT> method draws the image using the current drawing
<P>The Fl_Bitmap class encapsulates a mono-color bitmap image.
The draw() method draws the image using the current drawing
color.
<P>The <TT>Fl_Pixmap</TT> class encapsulates a colormapped image.
The <TT>draw()</TT> method draws the image using the colors in the
<P>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.
<P>The <TT>Fl_RGB_Image</TT> class encapsulates a full-color
<P>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 <TT>draw()</TT> method is either a 24-bit
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.
<H4><A NAME=fl_can_do_alpha_blending>char fl_can_do_alpha_blending()</A></H4>
<H4><A NAME="fl_can_do_alpha_blending">char fl_can_do_alpha_blending()</A></H4>
<P><TT>fl_can_do_alpha_blending()</TT> will return 1, if your
<P>fl_can_do_alpha_blending() will return 1, if your
platform supports true alpha blending for RGBA images, or 0,
if FLTK will use screen door transparency.
@ -883,42 +869,39 @@ standard image types for common file formats:
<UL>
<LI><A HREF="Fl_GIF_Image.html"><TT>Fl_GIF_Image</TT></A></LI>
<LI>Fl_GIF_Image</LI>
<LI><A HREF="Fl_JPEG_Image.html"><TT>Fl_JPEG_Image</TT></A></LI>
<LI>Fl_JPEG_Image</LI>
<LI><A HREF="Fl_PNG_Image.html"><TT>Fl_PNG_Image</TT></A></LI>
<LI>Fl_PNG_Image</LI>
<LI><A HREF="Fl_PNM_Image.html"><TT>Fl_PNM_Image</TT></A></LI>
<LI>Fl_PNM_Image</LI>
<LI><A HREF="Fl_XBM_Image.html"><TT>Fl_XBM_Image</TT></A></LI>
<LI>Fl_XBM_Image</LI>
<LI><A HREF="Fl_XPM_Image.html"><TT>Fl_XPM_Image</TT></A></LI>
<LI>Fl_XPM_Image</LI>
</UL>
<P>Each of these image classes load a named file of the
corresponding format. The <A
HREF="Fl_Shared_Image.html"><TT>Fl_Shared_Image</TT></A> class
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.
<P>Finally, FLTK provides a special image class called <A
HREF="Fl_Tiled_Image.html"><TT>Fl_Tiled_Image</TT></A> to tile
another image object in the specified area. This class can be
used to tile a background image in a <TT>Fl_Group</TT> widget,
for example.
<P>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.
<H4>virtual void copy();<BR>
virtual void copy(int w, int h);</H4>
<P>The <TT>copy()</TT> method creates a copy of the image. The second form
<P>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.
<H4>void draw(int x, int y, int w, int h, int ox = 0, int oy = 0);</H4>
<P>The <TT>draw()</TT> method draws the image object.
<P>The draw() method draws the image object.
<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
@ -929,36 +912,36 @@ image, and this area is left unchanged.
<H4>void draw(int x, int y)</H4>
<P>Draws the image with the upper-left corner at <TT>x,y</TT>.
This is the same as doing <TT>draw(x,y,img-&gt;w(),img-&gt;h(),0,0)</TT>.
This is the same as doing draw(x,y,img->w(),img->h(),0,0).
<h3><A NAME=offscreen>Offscreen Drawing</A></h3>
<h3><A NAME="offscreen">Offscreen Drawing</A></h3>
Sometimes it can be very useful to generate a complex drawing
in memory first and copy it to the screen at a later point in
time. This technique can significantly reduce the amount of
repeated drawing. <tt>Fl_Double_Window</tt> uses offscreen rendering
repeated drawing. Fl_Double_Window uses offscreen rendering
to avoid flickering on systems that don't support
double-buffering natively.
<H4><A NAME=fl_create_offscreen>Fl_Offscreen fl_create_offscreen(int w, int h)</A></H4>
<H4><A NAME="fl_create_offscreen">Fl_Offscreen fl_create_offscreen(int w, int h)</A></H4>
<P>Create an RGB offscreen buffer with <tt>w*h</tt> pixels.
<H4><A NAME=fl_delete_offscreen>void fl_delete_offscreen(Fl_Offscreen)</A></H4>
<H4><A NAME="fl_delete_offscreen">void fl_delete_offscreen(Fl_Offscreen)</A></H4>
<P>Delete a previously created offscreen buffer. All drawings are lost.
<H4><A NAME=fl_begin_offscreen>void fl_begin_offscreen(Fl_Offscreen)</A></H4>
<H4><A NAME="fl_begin_offscreen">void fl_begin_offscreen(Fl_Offscreen)</A></H4>
<P>Send all subsequent drawing commands to this offscreen buffer.
FLTK can draw into a buffer at any time. There is no need to wait for
an Fl_Widget::draw() to occur.
<H4><A NAME=fl_end_offscreen>void fl_end_offscreen()</A></H4>
<H4><A NAME="fl_end_offscreen">void fl_end_offscreen()</A></H4>
<P>Quit sending drawing commands to this offscreen buffer.
<H4><A NAME=fl_copy_offscreen>void fl_copy_offscreen(int x, int y,
<H4><A NAME="fl_copy_offscreen">void fl_copy_offscreen(int x, int y,
int w, int h, Fl_Offscreen osrc, int srcx, int srcy)</A></H4>
<P>Copy a rectangular area of the size <tt>w*h</tt> from <tt>srcx, srcy</tt> in the offscreen

2
documentation/examples.dox
View File

@ -15,7 +15,7 @@ They are not meant to be great achievements in clean C++ programming, but merely
a test platform to verify the functionality of the FLTK library.</P>
<table width=100% border=0>
<tr><td colspan=4><font size=+1><b>Example Applications</b></font></td>
<tr><td colspan=4><H3><b>Example Applications</b></H3></td>
<tr>
<td><a href="#adjuster"><tt>adjuster</tt></a></td>
<td><a href="#arc"><tt>arc</tt></a></td>

28
documentation/fluid.dox
View File

@ -37,8 +37,8 @@ POSIX catgets interfaces.
main()</TT> function) into the <TT>.fl</TT> file and thus making the <TT>.cxx</TT> file a
single source file to compile. Most programs are more complex than
this, so you write other <TT>.cxx</TT> files that call the FLUID functions.
These <TT>.cxx</TT> files must <TT>#include</TT> the <TT>.h</TT> file or they can <TT>
#include</TT> the <TT>.cxx</TT> file so it still appears to be a single source
These <TT>.cxx</TT> files must <TT>\#include</TT> the <TT>.h</TT> file or they can <TT>
\#include</TT> the <TT>.cxx</TT> file so it still appears to be a single source
file.
\image html fluid-org.gif "Figure 9-1: FLUID organization"
@ -154,9 +154,7 @@ how to:
constructor and any member functions necessary.
<li>Use FLUID to set callbacks member functions of a custom widget
classes.
<li>Subclass an <a
href="Fl_Gl_Window.html#Fl_Gl_Window"><TT>Fl_Gl_Window</TT></A> to suit
your purposes.
<li>Subclass an Fl_Gl_Window to suit your purposes.
</ol>
<h3>The CubeView Class</h3>
@ -361,7 +359,7 @@ CubeView defined in the previous section using FLUID.
<h4><a name="defui">Defining the CubeViewUI Class</a></h4>
<P>Once you have started FLUID, the first step in defining a class is to
create a new class within FLUID using the \em New->Code->Class</b>
create a new class within FLUID using the \em New->Code->Class
menu item. Name the class "CubeViewUI" and leave the
subclass blank. We do not need any inheritance for this
window. You should see the new class declaration in the FLUID
@ -416,9 +414,9 @@ This will be no ordinary box, however.
display CubeView is to enter CubeView in the "Class:" text
entry box. This tells FLUID that it is not an <tt>Fl_Box</tt>, but a
similar widget with the same constructor. In the "Extra
Code:" field enter <tt>#include "CubeView.h"</tt>
Code:" field enter <tt>\#include "CubeView.h"</tt>
<p>This <tt>#include</tt> is important, as we have just included
<p>This <tt>\#include</tt> is important, as we have just included
CubeView as a member of CubeViewUI, so any public CubeView methods are
now available to CubeViewUI.
@ -595,7 +593,7 @@ changed the current file.
<H4>Edit/Undo (Ctrl+z)</H4>
<P>This isn't implemented yet. You should do save often so you can
<P>This isn't implemented yet. You should do save often so you can
recover from any mistakes you make.
<H4>Edit/Cut (Ctrl+x)</H4>
@ -990,8 +988,8 @@ menus, and browsers.
<tt>Fl_Widget</tt>. Whatever identifier you type in here will
be the class that is instantiated.
<P>In addition, no <tt>#include</tt> header file is put in the
<TT>.h</TT> file. You must provide a <tt>#include</tt> line as
<P>In addition, no <tt>\#include</tt> header file is put in the
<TT>.h</TT> file. You must provide a <tt>\#include</tt> line as
the first line of the "Extra Code" which declares your
subclass.</P>
@ -1032,7 +1030,7 @@ Otherwise is controls whether the widget is declared
<P>These four fields let you type in literal lines of code to
dump into the <TT>.h</TT> or <TT>.cxx</TT> files.
<P>If the text starts with a <tt>#</tt> or the word
<P>If the text starts with a <tt>\#</tt> or the word
<tt>extern</tt> then FLUID thinks this is an "include"
line, and it is written to the <TT>.h</TT> file. If the same
include line occurs several times then only one copy is
@ -1301,7 +1299,7 @@ strings.
\image html fluid-gettext.gif "Figure 9-11: Internationalization using GNU gettext"
<P>The "#include" field controls the header file to include for
<P>The "\#include" field controls the header file to include for
I18N; by default this is \b <libintl.h>, the
standard I18N file for GNU gettext.
@ -1324,7 +1322,7 @@ strings.
\image html fluid-catgets.gif "Figure 9-12: Internationalization using POSIX catgets"
<P>The "#include" field controls the header file to include for
<P>The "\#include" field controls the header file to include for
I18N; by default this is \b <nl_types.h>, the
standard I18N file for POSIX catgets.
@ -1340,7 +1338,7 @@ The default set is 1 and rarely needs to be changed.
<H2><A NAME="limitations">Known limitations</A></H2>
Declaration Blocks can be used to temporarily block out already
designed code using <code>#if 0</code> and <code>#endif</code>
designed code using <tt>\#if 0</tt> and <tt>\#endif</tt>
type construction. This will effectively avoid compilation of
blocks of code. However, static code and data generated by this
segment (menu items, images, include statements, etc.) will still

62
documentation/forms.dox
View File

@ -12,7 +12,7 @@ new name so you don't write over the old one.
<P>You will need to edit your main code considerably to get it to link
with the output from FLUID. If you are not interested in this you may
have more immediate luck with the forms compatibility header, <TT>
&lt;FL/forms.H&gt;</TT>. </P>
<FL/forms.H></TT>. </P>
<H2>Using the Compatibility Header File</H2>
You should be able to compile existing Forms or XForms source code by
changing the include directory switch to your compiler so that the <TT>
@ -29,17 +29,17 @@ a goal of FLTK. Compatibility was limited to things that were free, or
that would add code that would not be linked in if the feature is
unused, or that was not X-specific. </P>
<P>To use any new features of FLTK, you should rewrite your code to not
use the inline functions and instead use &quot;pure&quot; FLTK. This will make
use the inline functions and instead use "pure" FLTK. This will make
it a lot cleaner and make it easier to figure out how to call the FLTK
functions. Unfortunately this conversion is harder than expected and
even Digital Domain's inhouse code still uses <TT>forms.H</TT> a lot. </P>
<H2>Problems You Will Encounter</H2>
<P>Many parts of XForms use X-specific structures like <TT>XEvent</TT>
in their interface. I did not emulate these! Unfortunately these
features (such as the &quot;canvas&quot; widget) are needed by most large
features (such as the "canvas" widget) are needed by most large
programs. You will need to rewrite these to use FLTK subclasses. </P>
<P><A href=Fl_Free.html#Fl_Free><TT>Fl_Free</TT></A> widgets emulate
the <I>old</I> Forms &quot;free&quot; widget. It may be useful for porting
the <I>old</I> Forms "free" widget. It may be useful for porting
programs that change the <TT>handle()</TT> function on widgets, but you
will still need to rewrite things. </P>
<P><A href=Fl_Timer.html#Fl_Timer><TT>Fl_Timer</TT></A> widgets are
@ -49,8 +49,8 @@ inefficient and inaccurate compared to using <A href="Fl.html#Fl.add_timeout">
<P><I>All instance variables are hidden.</I> If you directly refer to
the x, y, w, h, label, or other fields of your Forms widgets you will
have to add empty parenthesis after each reference. The easiest way to
do this is to globally replace &quot;-&gt;x&quot; with &quot;-&gt;x()&quot;, etc. Replace
&quot;boxtype&quot; with &quot;box()&quot;. </P>
do this is to globally replace "->x" with "->x()", etc. Replace
"boxtype" with "box()". </P>
<P><TT>const char *</TT> arguments to most FLTK methods are simply
stored, while Forms would <TT>strdup()</TT> the passed string. This is
most noticable with the label of widgets. Your program must always
@ -61,11 +61,11 @@ may want to try the <A href=Fl_Output.html#Fl_Output><TT>Fl_Output</TT></A>
<P>The default fonts and sizes are matched to the older GL version of
Forms, so all labels will draw somewhat larger than an XForms program
does. </P>
<P>fdesign outputs a setting of a &quot;fdui&quot; instance variable to the main
<P>fdesign outputs a setting of a "fdui" instance variable to the main
window. I did not emulate this because I wanted all instance variables
to be hidden. You can store the same information in the <TT>user_data()</TT>
field of a window. To do this, search through the fdesign output for
all occurances of &quot;-&gt;fdui&quot; and edit to use &quot;-&gt;user_data()&quot; instead.
all occurances of "->fdui" and edit to use "->user_data()" instead.
This will require casts and is not trivial. </P>
<P>The prototype for the functions passed to <TT>fl_add_timeout()</TT>
and <TT>fl_set_idle_callback()</TT> callback are different. </P>
@ -123,9 +123,9 @@ IRISGL version of Forms. Most of these problems are the same ones
encountered when going from old Forms to XForms:
<H3>Does Not Run In Background</H3>
The IRISGL library always forked when you created the first window,
unless &quot;foreground()&quot; was called. FLTK acts like &quot;foreground()&quot; is
called all the time. If you really want the fork behavior do &quot;if
(fork()) exit(0)&quot; right at the start of your program.
unless "foreground()" was called. FLTK acts like "foreground()" is
called all the time. If you really want the fork behavior do "if
(fork()) exit(0)" right at the start of your program.
<H3>You Cannot Use IRISGL Windows or fl_queue</H3>
If a Forms (not XForms) program if you wanted your own window for
displaying things you would create a IRISGL window and draw in it,
@ -148,7 +148,7 @@ of your program, call <TT>Fl::wait()</TT> and then check these
variables, acting on them as though they are events read from <TT>
fl_queue</TT>. </P>
<H3>You Must Use OpenGL to Draw Everything</H3>
<P>The file <TT>&lt;FL/gl.h&gt;</TT> defines replacements for a lot of IRISGL
<P>The file <TT><FL/gl.h></TT> defines replacements for a lot of IRISGL
calls, translating them to OpenGL. There are much better translators
available that you might want to investigate. </P>
<H3>You Cannot Make Forms Subclasses</H3>
@ -158,15 +158,15 @@ subclass of <TT>Fl_Widget</TT>. It is important to note that the <TT>
handle()</TT> method is not exactly the same as the <TT>handle()</TT>
function of Forms. Where a Forms <TT>handle()</TT> returned non-zero,
your <TT>handle()</TT> must call <TT>do_callback()</TT>. And your <TT>
handle()</TT> must return non-zero if it &quot;understood&quot; the event.
<P>An attempt has been made to emulate the &quot;free&quot; widget. This appears
handle()</TT> must return non-zero if it "understood" the event.
<P>An attempt has been made to emulate the "free" widget. This appears
to work quite well. It may be quicker to modify your subclass into a
&quot;free&quot; widget, since the &quot;handle&quot; functions match. </P>
"free" widget, since the "handle" functions match. </P>
<P>If your subclass draws into the overlay you are in trouble and will
have to rewrite things a lot. </P>
<H3>You Cannot Use &lt;device.h&gt;</H3>
If you have written your own &quot;free&quot; widgets you will probably get a
lot of errors about &quot;getvaluator&quot;. You should substitute:
<H3>You Cannot Use <device.h></H3>
If you have written your own "free" widgets you will probably get a
lot of errors about "getvaluator". You should substitute:
<CENTER><TABLE border=1 WIDTH=90% summary="Mapping of Forms valuators to FLTK.">
<TR><TH align=center>Forms</TH><TH align=center>FLTK</TH></TR>
<TR><TD>MOUSE_X</TD><TD>Fl::event_x_root()</TD></TR>
@ -181,21 +181,21 @@ lot of errors about &quot;getvaluator&quot;. You should substitute:
</TABLE></CENTER>
Anything else in <TT>getvaluator</TT> and you are on your own...
<H3>Font Numbers Are Different</H3>
The &quot;style&quot; numbers have been changed because I wanted to insert
The "style" numbers have been changed because I wanted to insert
bold-italic versions of the normal fonts. If you use Times, Courier,
or Bookman to display any text you will get a different font out of
FLTK. If you are really desperate to fix this use the following code:
<UL>
<PRE>
fl_font_name(3,&quot;*courier-medium-r-no*&quot;);
fl_font_name(4,&quot;*courier-bold-r-no*&quot;);
fl_font_name(5,&quot;*courier-medium-o-no*&quot;);
fl_font_name(6,&quot;*times-medium-r-no*&quot;);
fl_font_name(7,&quot;*times-bold-r-no*&quot;);
fl_font_name(8,&quot;*times-medium-i-no*&quot;);
fl_font_name(9,&quot;*bookman-light-r-no*&quot;);
fl_font_name(10,&quot;*bookman-demi-r-no*&quot;);
fl_font_name(11,&quot;*bookman-light-i-no*&quot;);
</PRE>
\code
fl_font_name(3,"*courier-medium-r-no*");
fl_font_name(4,"*courier-bold-r-no*");
fl_font_name(5,"*courier-medium-o-no*");
fl_font_name(6,"*times-medium-r-no*");
fl_font_name(7,"*times-bold-r-no*");
fl_font_name(8,"*times-medium-i-no*");
fl_font_name(9,"*bookman-light-r-no*");
fl_font_name(10,"*bookman-demi-r-no*");
fl_font_name(11,"*bookman-light-i-no*");
\endcode
*/

27
documentation/glut.dox
View File

@ -4,7 +4,7 @@
<P>This appendix describes the GLUT compatibility header file supplied with FLTK. FLTK's GLUT compatibility is based on the original GLUT 3.7 and the follow-on FreeGLUT 2.4.0 libraries.</P>
<H2>Using the GLUT Compatibility Header File</H2>
<P>You should be able to compile existing GLUT source code by including <TT>&lt;FL/glut.H&gt;</TT> instead of <TT>&lt;GL/glut.h&gt;</TT>. This can be done by editing the source, by changing the <TT>-I</TT> switches to the compiler, or by providing a symbolic link from <TT>GL/glut.h</TT> to <TT>FL/glut.H</TT>.</P>
<P>You should be able to compile existing GLUT source code by including <TT><FL/glut.H></TT> instead of <TT><GL/glut.h></TT>. This can be done by editing the source, by changing the <TT>-I</TT> switches to the compiler, or by providing a symbolic link from <TT>GL/glut.h</TT> to <TT>FL/glut.H</TT>.</P>
<P><I>All files calling GLUT procedures must be compiled with C++</I>. You may have to alter them slightly to get them to compile without warnings, and you may have to rename them to get make to use the C++ compiler.</P>
<P>You must link with the FLTK library. Most of <TT>FL/glut.H</TT> is inline functions. You should take a look at it (and maybe at <TT>test/glpuzzle.cxx</TT> in the FLTK source) if you are having trouble porting your GLUT program. </P>
<P>This has been tested with most of the demo programs that come with the GLUT and FreeGLUT distributions.</P>
@ -54,7 +54,7 @@ small crosshair. </P>
<P><TT>glutInit(argc,argv)</TT> will consume different switches than
GLUT does. It accepts the switches recognized by <A href="Fl.html#Fl.args">
<TT>Fl::args()</TT></A>, and will accept any abbreviation of these
switches (such as &quot;-di&quot; for &quot;-display&quot;). </P>
switches (such as "-di" for "-display"). </P>
<H2>Mixing GLUT and FLTK Code</H2>
You can make your GLUT window a child of a <TT>Fl_Window</TT> with the
following scheme. The biggest trick is that GLUT insists on <TT>show()</TT>
@ -66,12 +66,12 @@ Fl_Window</TT> parent window must already be shown.
blank area in the window for your GLUT window. </LI>
<LI><TT>show()</TT> the <TT>Fl_Window</TT>. Perhaps call <TT>
show(argc,argv)</TT>. </LI>
<LI>Call <TT>window-&gt;begin()</TT> so that the GLUT window will be
<LI>Call <TT>window->begin()</TT> so that the GLUT window will be
automatically added to it. </LI>
<LI>Use <TT>glutInitWindowSize()</TT> and <TT>glutInitWindowPosition()</TT>
to set the location in the parent window to put the GLUT window. </LI>
<LI>Put your GLUT code next. It probably does not need many changes.
Call <TT>window-&gt;end()</TT> immediately after the <TT>
Call <TT>window->end()</TT> immediately after the <TT>
glutCreateWindow()</TT>! </LI>
<LI>You can call either <TT>glutMainLoop()</TT>, <TT>Fl::run()</TT>, or
loop calling <TT>Fl::wait()</TT> to run the program. </LI>
@ -80,19 +80,18 @@ loop calling <TT>Fl::wait()</TT> to run the program. </LI>
<H2><A name=Fl_Glut_Window>class Fl_Glut_Window</A></H2>
<HR>
<H3>Class Hierarchy</H3>
<UL>
<PRE>
\code
<A href=Fl_Gl_Window.html#Fl_Gl_Window>Fl_Gl_Window</A>
|
+----<B>Fl_Glut_Window</B>
</PRE>
</UL>
\endcode
<H3>Include Files</H3>
<UL>
<PRE>
#include &lt;FL/glut.H&gt;
</PRE>
</UL>
\code
#include <FL/glut.H>
\endcode
<H3>Description</H3>
Each GLUT window is an instance of this class. You may find it useful
to manipulate instances directly rather than use GLUT window id's.
@ -103,7 +102,7 @@ glut_window</TT>. </P>
<P><TT>new Fl_Glut_Window(...)</TT> is the same as <TT>
glutCreateWindow()</TT> except it does not <TT>show()</TT> the window
or make the window current. </P>
<P><TT>window-&gt;make_current()</TT> is the same as <TT>
<P><TT>window->make_current()</TT> is the same as <TT>
glutSetWindow(number)</TT>. If the window has not had <TT>show()</TT>
called on it yet, some functions that assumme an OpenGL context will
not work. If you do <TT>show()</TT> the window, call <TT>make_current()</TT>

2
documentation/intro.dox
View File

@ -194,7 +194,7 @@ override the default C compiler (<tt>cc</tt> or <tt>gcc</tt>),
which is used for a few FLTK source files.</P>
<P>You can run configure yourself to get the exact setup you
need. Type "./configure &lt;options&gt;", where
need. Type "./configure <options>", where
options are:</P>
<DL>

28
documentation/license.dox
View File

@ -57,7 +57,7 @@ exceptions:</P>
<HR>
<P ALIGN=CENTER><BIG>GNU LIBRARY GENERAL PUBLIC LICENSE</BIG></P>
<P ALIGN=CENTER><B>GNU LIBRARY GENERAL PUBLIC LICENSE</B></P>
<P ALIGN=CENTER>Version 2, June 1991
<BR> Copyright (C) 1991 Free Software Foundation, Inc.
<BR> 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
@ -65,7 +65,7 @@ exceptions:</P>
this license document, but changing it is not allowed.
<BR> [This is the first released version of the library GPL. It is
numbered 2 because it goes with version 2 of the ordinary GPL.] </P>
<P><BIG>Preamble</BIG></P>
<P><B>Preamble</B></P>
The licenses for most software are designed to take away your freedom
to share and change it. By contrast, the GNU General Public Licenses
are intended to guarantee your freedom to share and change free
@ -140,8 +140,8 @@ former contains code derived from the library, while the latter only
works together with the library. </P>
<P>Note that it is possible for a library to be covered by the ordinary
General Public License rather than by this special one. </P>
<P ALIGN="CENTER"><BIG>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND
MODIFICATION</BIG></P>
<P ALIGN="CENTER"><B>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND
MODIFICATION</B></P>
<STRONG>0.</STRONG> This License Agreement applies to any software
library which contains a notice placed by the copyright holder or other
authorized party saying it may be distributed under the terms of this
@ -181,7 +181,7 @@ fee. </P>
<P><STRONG>2.</STRONG> You may modify your copy or copies of the
Library or any portion of it, thus forming a work based on the Library,
and copy and distribute such modifications or work under the terms of
Section 1 above, provided that you also meet all of these conditions: <BLOCKQUOTE>
Section 1 above, provided that you also meet all of these conditions:
<STRONG>a)</STRONG> The modified work must itself be a software
library.
<P><STRONG>b)</STRONG> You must cause the files modified to carry
@ -203,7 +203,7 @@ purpose that is entirely well-defined independent of the application.
function or table used by this function must be optional: if the
application does not supply it, the square root function must still
compute square roots.) </P>
</BLOCKQUOTE>
<P>These requirements apply to the modified work as a whole.
If identifiable sections of that work are not derived from the
Library, and can be reasonably considered independent and separate
@ -284,7 +284,7 @@ this License. You must supply a copy of this License. If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License. Also, you must do one
of these things: <BLOCKQUOTE><STRONG>a)</STRONG> Accompany the work
of these things: <STRONG>a)</STRONG> Accompany the work
with the complete corresponding machine-readable source code for the
Library including whatever changes were used in the work (which must
be distributed under Sections 1 and 2 above); and, if the work is an
@ -304,7 +304,7 @@ access to copy from a designated place, offer equivalent access to
copy the above specified materials from the same place. </P>
<P><STRONG>d)</STRONG> Verify that the user has already received a copy
of these materials or that you have already sent this user a copy. </P>
</BLOCKQUOTE>
<P>For an executable, the required form of the &quot;work that
uses the Library&quot; must include any data and utility programs needed for
reproducing the executable from it. However, as a special exception,
@ -323,16 +323,16 @@ based on the Library side-by-side in a single library together with
other library facilities not covered by this License, and distribute
such a combined library, provided that the separate distribution of the
work based on the Library and of the other library facilities is
otherwise permitted, and provided that you do these two things: <BLOCKQUOTE>
otherwise permitted, and provided that you do these two things:
<STRONG>a)</STRONG> Accompany the combined library with a copy of the
same work based on the Library, uncombined with any other library
facilities. This must be distributed under the terms of the Sections
above.
<P><STRONG>b)</STRONG> Give prominent notice with the combined library
of the fact that part of it is a work based on the Library, and
explaining where to find the accompanying uncombined form of the same
of the fact that part of it is a work based on the Library, and
explaining where to find the accompanying uncombined form of the same
work. </P>
</BLOCKQUOTE>
<P><STRONG>8.</STRONG> You may not copy, modify, sublicense,
link with, or distribute the Library except as expressly provided under
this License. Any attempt otherwise to copy, modify, sublicense, link
@ -412,7 +412,7 @@ Software Foundation; we sometimes make exceptions for this. Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally. </P>
<P ALIGN="CENTER"><BIG>NO WARRANTY</BIG></P>
<P ALIGN="CENTER"><B>NO WARRANTY</B></P>
<P><STRONG>15.</STRONG> BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE,
THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
@ -432,6 +432,6 @@ RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES. </P>
<P ALIGN="CENTER"><BIG>END OF TERMS AND CONDITIONS</BIG></P>
<P ALIGN="CENTER"><B>END OF TERMS AND CONDITIONS</B></P>
*/

18
documentation/migration_1_1.dox
View File

@ -44,16 +44,16 @@ class.</P>
<P>Some function names have changed from FLTK 1.0.x to 1.1.x in
order to avoid name space collisions. You can still use the old
function names by defining the <CODE>FLTK_1_0_COMPAT</CODE>
function names by defining the <TT>FLTK_1_0_COMPAT</TT>
symbol on the command-line when you compile
(<CODE>-DFLTK_1_0_COMPAT</CODE>) or in your source, e.g.:
(<TT>-DFLTK_1_0_COMPAT</TT>) or in your source, e.g.:
<UL><PRE>
\code
#define FLTK_1_0_COMPAT
#include &lt;FL/Fl.H&gt;
#include &lt;FL/Enumerations.H&gt;
#include &lt;FL/filename.H&gt;
</PRE></UL>
#include <FL/Fl.H>
#include <FL/Enumerations.H>
#include <FL/filename.H>
\endcode
<P>The following table shows the old and new function names:</P>
@ -151,8 +151,8 @@ text widgets get keyboard focus, call the <A
HREF="Fl.html#Fl.visible_focus"><CODE>Fl::visible_focus()</CODE></A>
method to disable it:
<UL><PRE>
\code
Fl::visible_focus(0);
</PRE></UL>
\endcode
*/

109
documentation/opengl.dox
View File

@ -20,10 +20,10 @@ href="#gl_start"><TT>gl_start()</TT></A> and <A
href=#gl_finish><TT>gl_finish()</TT></A> functions around your
OpenGL code.</P>
<P>You must include FLTK's <TT>&lt;FL/gl.h&gt;</TT> header
file. It will include the file <TT>&lt;GL/gl.h&gt;</TT>, define
<P>You must include FLTK's <TT><FL/gl.h></TT> header
file. It will include the file <TT><GL/gl.h></TT>, define
some extra drawing functions provided by FLTK, and include the
<TT>&lt;windows.h&gt;</TT> header file needed by WIN32
<TT><windows.h></TT> header file needed by WIN32
applications.</P>
<H2>Making a Subclass of Fl_Gl_Window</H2>
@ -47,7 +47,7 @@ in the value returned by <tt>damage()</tt>. For double-buffered
windows you will need to surround the drawing code with the
following code to make sure that both buffers are redrawn:
<UL><PRE>
\code
#ifndef MESA
glDrawBuffer(GL_FRONT_AND_BACK);
#endif // !MESA
@ -55,7 +55,7 @@ glDrawBuffer(GL_FRONT_AND_BACK);
#ifndef MESA
glDrawBuffer(GL_BACK);
#endif // !MESA
</PRE></UL>
\endcode
<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
<TR>
@ -77,7 +77,7 @@ glDrawBuffer(GL_BACK);
<P>To define the subclass you just subclass the
<TT>Fl_Gl_Window</TT> class:
<UL><PRE>
\code
class MyWindow : public Fl_Gl_Window {
void draw();
int handle(int);
@ -86,7 +86,7 @@ public:
MyWindow(int X, int Y, int W, int H, const char *L)
: Fl_Gl_Window(X, Y, W, H, L) {}
};
</PRE></UL>
\endcode
<P>The <TT>draw()</TT> and <TT>handle()</TT> methods are
described below. Like any widget, you can include additional
@ -98,7 +98,7 @@ information, etc.)
<P>The <TT>draw()</TT> method is where you actually do your
OpenGL drawing:
<UL><PRE>
\code
void MyWindow::draw() {
if (!valid()) {
... set up projection, viewport, etc ...
@ -107,14 +107,14 @@ void MyWindow::draw() {
}
... draw ...
}
</PRE></UL>
\endcode
<H3>The handle() Method</H3>
<P>The <TT>handle()</TT> method handles mouse and keyboard
events for the window:
<UL><PRE>
\code
int MyWindow::handle(int event) {
switch(event) {
case FL_PUSH:
@ -144,7 +144,7 @@ int MyWindow::handle(int event) {
return Fl_Gl_Window::handle(event);
}
}
</PRE></UL>
\endcode
<P>When <TT>handle()</TT> is called, the OpenGL context is not
set up! If your display changes, you should call
@ -154,16 +154,18 @@ call any OpenGL drawing functions from inside <TT>handle()</TT>!
<P>You can call <I>some</I> OpenGL stuff like hit detection and texture
loading functions by doing: </P>
<UL><PRE>
\code
case FL_PUSH:
make_current(); // make OpenGL context current
make_current(); // make OpenGL context current
if (!valid()) {
... set up projection exactly the same as draw ...
valid(1); // stop it from doing this next time
valid(1); // stop it from doing this next time
}
... ok to call NON-DRAWING OpenGL code here, such as hit
detection, loading textures, etc...
</PRE></UL>
\endcode
<P>Your main program can now create one of your windows by doing
<TT>new MyWindow(...)</TT>. You can also use <A
@ -176,17 +178,17 @@ href="fluid.html#FLUID">FLUID</A> by:
<LI>Creating a <tt>Fl_Box</tt> widget in FLUID.</LI>
<LI>In the widget panel fill in the &quot;class&quot;
<LI>In the widget panel fill in the "class"
field with <tt>MyWindow</tt>. This will make FLUID
produce constructors for your new class.</LI>
<LI>In the &quot;Extra Code&quot; field put <TT>#include
&quot;MyWindow.H&quot;</TT>, so that the FLUID output
<LI>In the "Extra Code" field put <TT>\#include
"MyWindow.H"</TT>, so that the FLUID output
file will compile.</LI>
</OL>
<P>You must put <TT>glwindow-&gt;show()</TT> in your main code
<P>You must put <TT>glwindow->show()</TT> in your main code
after calling <TT>show()</TT> on the window containing the
OpenGL window.
@ -201,22 +203,21 @@ care.
<P>Most importantly, before you show <I>any</I> windows,
including those that don't have OpenGL drawing, you <B>must</B>
initialize FLTK so that it knows it is going to use OpenGL. You
may use any of the symbols described for <A
href="Fl_Gl_Window.html#Fl_Gl_Window.mode"><TT>Fl_Gl_Window::mode()</TT></A>
may use any of the symbols described for Fl_Gl_Window::mode()
to describe how you intend to use OpenGL:</P>
<UL><PRE>
\code
Fl::gl_visual(FL_RGB);
</PRE></UL>
\endcode
<P>You can then put OpenGL drawing code anywhere you can draw
normally by surrounding it with:
<UL><PRE>
\code
gl_start();
... put your OpenGL code here ...
gl_finish();
</PRE></UL>
\endcode
<P><A name="gl_start"><TT>gl_start()</TT></A> and <A
name="gl_finish"><TT>gl_finish()</TT></A> set up an OpenGL
@ -231,7 +232,7 @@ the projection transformation or anything else you should use
<TT>glPushMatrix()</TT> and <TT>glPopMatrix()</TT> functions to
put the state back before calling <TT>gl_finish()</TT>.</P>
<P>You may want to use <TT>Fl_Window::current()-&gt;h()</TT> to
<P>You may want to use Fl_Window::current()->h() to
get the drawable height so that you can flip the Y
coordinates.</P>
@ -240,26 +241,23 @@ adhere to for maximum portability: </P>
<UL>
<LI>You must choose a default visual with <A
href="Fl.html#Fl.gl_visual"><TT>Fl::gl_visual()</TT></A>.</LI>
<LI>You must choose a default visual with Fl::gl_visual().</LI>
<LI>You cannot pass <TT>FL_DOUBLE</TT> to
<TT>Fl::gl_visual()</TT>.</LI>
<LI>You cannot pass <TT>FL_DOUBLE</TT> to Fl::gl_visual().</LI>
<LI>You cannot use <TT>Fl_Double_Window</TT> or
<TT>Fl_Overlay_Window</TT>.</LI>
<LI>You cannot use Fl_Double_Window or Fl_Overlay_Window.</LI>
</UL>
<P>Do <I>not</I> call <TT>gl_start()</TT> or
<TT>gl_finish()</TT> when drawing into an <TT>Fl_Gl_Window</TT>!
<TT>gl_finish()</TT> when drawing into an Fl_Gl_Window !
<H2>OpenGL Drawing Functions</H2>
<P>FLTK provides some useful OpenGL drawing functions. They can
be freely mixed with any OpenGL calls, and are defined by
including <TT>&lt;FL/gl.H&gt;</TT> which you should include
instead of the OpenGL header <TT>&lt;GL/gl.h&gt;</TT>.
including <FL/gl.H> which you should include
instead of the OpenGL header <TT><GL/gl.h></TT>.
<H4>void gl_color(Fl_Color)</H4>
@ -270,10 +268,9 @@ only right if this window uses the default colormap!</I>
<H4>void gl_rect(int x, int y, int w, int h)
<BR>void gl_rectf(int x, int y, int w, int h)</H4>
<P>Outlines or fills a rectangle with the current color. If <A
HREF="Fl_Gl_Window.html#Fl_Gl_Window.ortho"><TT>Fl_Gl_Window::ortho()</TT></A>
has been called, then the rectangle will exactly fill the pixel
rectangle passed.
<P>Outlines or fills a rectangle with the current color. If
Fl_Gl_Window::ortho() has been called, then the rectangle will exactly
fill the pixel rectangle passed.
<H4>void gl_font(Fl_Font fontid, int size)</H4>
@ -361,7 +358,7 @@ to view large scenes without writing a lot of OpenGL code.
subclass of <TT>Fl_Gl_Widget</TT> that includes several state
variables:
<UL><PRE>
\code
class OptimizerWindow : public Fl_Gl_Window {
csContext *context_; // Initialized to 0 and set by draw()...
csDrawAction *draw_action_; // Draw action...
@ -384,13 +381,13 @@ public:
void camera(csCamera *c) {
camera_ = c;
if (context_) {
draw_action_-&gt;setCamera(camera_);
camera_-&gt;draw(draw_action_);
draw_action_->setCamera(camera_);
camera_->draw(draw_action_);
redraw();
}
}
};
</PRE></UL>
\endcode
<H4>The camera() Method</H4>
@ -403,7 +400,7 @@ this call.
<P>The <TT>draw()</TT> method performs the needed initialization and does
the actual drawing:
<UL><PRE>
\code
void OptimizerWindow::draw() {
if (!context_) {
// This is the first time we've been asked to draw; create the
@ -411,12 +408,12 @@ void OptimizerWindow::draw() {
#ifdef WIN32
context_ = new csContext((HDC)fl_getHDC());
context_-&gt;ref();
context_-&gt;makeCurrent((HDC)fl_getHDC());
context_->ref();
context_->makeCurrent((HDC)fl_getHDC());
#else
context_ = new csContext(fl_display, fl_visual);
context_-&gt;ref();
context_-&gt;makeCurrent(fl_display, fl_window);
context_->ref();
context_->makeCurrent(fl_display, fl_window);
#endif // WIN32
... perform other context setup as desired ...
@ -425,24 +422,24 @@ void OptimizerWindow::draw() {
draw_action_ = new csDrawAction;
if (camera_) {
draw_action_-&gt;setCamera(camera_);
camera_-&gt;draw(draw_action_);
draw_action_->setCamera(camera_);
camera_->draw(draw_action_);
}
} else {
#ifdef WIN32
context_-&gt;makeCurrent((HDC)fl_getHDC());
context_->makeCurrent((HDC)fl_getHDC());
#else
context_-&gt;makeCurrent(fl_display, fl_window);
context_->makeCurrent(fl_display, fl_window);
#endif // WIN32
}
if (!valid()) {
// Update the viewport for this context...
context_-&gt;setViewport(0, 0, w(), h());
context_->setViewport(0, 0, w(), h());
}
// Clear the window...
context_-&gt;clear(csContext::COLOR_CLEAR | csContext::DEPTH_CLEAR,
context_->clear(csContext::COLOR_CLEAR | csContext::DEPTH_CLEAR,
0.0f, // Red
0.0f, // Green
0.0f, // Blue
@ -450,9 +447,9 @@ void OptimizerWindow::draw() {
// Then draw the scene (if any)...
if (scene_)
draw_action_-&gt;apply(scene_);
draw_action_->apply(scene_);
}
</PRE></UL>
\endcode
<H4>The scene() Method</H4>

102
documentation/osissues.dox
View File

@ -9,9 +9,9 @@
<P>All programs that need to access the operating system
specific interfaces must include the following header file:
<UL><PRE>
#include &lt;FL/x.H&gt;
</PRE></UL>
\code
#include <FL/x.H>
\endcode
<P>Despite the name, this header file will define the
appropriate interface for your environment. The pages that
@ -78,7 +78,7 @@ XID, or <TT>NULL</TT> if not found. This function uses a cache
so it is slightly faster than iterating through the windows
yourself.</P>
<H4><A name="fl_handle">int fl_handle(const XEvent &amp;)</A></H4>
<H4><A name="fl_handle">int fl_handle(const XEvent &)</A></H4>
<P>This call allows you to supply the X events to FLTK, which
may allow FLTK to cooperate with another toolkit or library. The
@ -104,21 +104,21 @@ HREF="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A> is
called, or by <A
href="Fl_Window.html#Fl_Window.make_current"><TT>Fl_Window::make_current()</TT></A>:
<UL><PRE>
\code
extern Display *fl_display;
extern Window fl_window;
extern GC fl_gc;
extern int fl_screen;
extern XVisualInfo *fl_visual;
extern Colormap fl_colormap;
</PRE></UL>
\endcode
<P>You must use them to produce Xlib calls. Don't attempt to change
them. A typical X drawing call is written like this:
<UL><PRE>
\code
XDrawSomething(fl_display, fl_window, fl_gc, ...);
</PRE></UL>
\endcode
<P>Other information such as the position or size of the X
window can be found by looking at <A
@ -132,11 +132,11 @@ unsigned long fl_xpixel(uchar r, uchar g, uchar b)</A></H4>
index or RGB color. This is the X pixel that <A
href="drawing.html#fl_color"><TT>fl_color()</TT></A> would use.
<H4><A name="fl_parse_color">int fl_parse_color(const char* p, uchar&amp; r, uchar&amp; g, uchar&amp; b)</A></H4>
<H4><A name="fl_parse_color">int fl_parse_color(const char* p, uchar& r, uchar& g, uchar& b)</A></H4>
<P>Convert a name into the red, green, and blue values of a color
by parsing the X11 color names. On other systems, <tt>fl_parse_color</tt>
can only convert names in hexadecimal encoding, for example <tt>#ff8083</tt>.
can only convert names in hexadecimal encoding, for example <tt>\#ff8083</tt>.
<H4><A name="fl_xfont">extern XFontStruct *fl_xfont</A></H4>
@ -170,7 +170,7 @@ visual.
<H4><A name="display">int Fl::display(const char *)</A></H4>
<P>Set which X display to use. This actually does
<TT>putenv(&quot;DISPLAY=...&quot;)</TT> so that child programs
<TT>putenv("DISPLAY=...")</TT> so that child programs
will display on the same screen if called with <TT>exec()</TT>.
This must be done before the display is opened. This call is
provided under MacOS and WIN32 but it has no effect.
@ -206,7 +206,7 @@ probably cannot call any FLTK functions.
<TT>fl_open_display()</TT> to the default screen. You can change
it by setting this to a different value immediately afterwards.
It can also be set by changing the last number in the
<TT>Fl::display()</TT> string to &quot;host:0.#&quot;.
<TT>Fl::display()</TT> string to "host:0.#".
<H4><A name="fl_visual">extern XVisualInfo *fl_visual</A><BR>
<A name="fl_colormap">extern Colormap fl_colormap</A></H4>
@ -217,15 +217,15 @@ visual and colormap. You can change them before calling
<TT>show()</TT> on the first window. Typical code for changing
the default visual is:
<UL><PRE>
\code
Fl::args(argc, argv); // do this first so $DISPLAY is set
fl_open_display();
fl_visual = find_a_good_visual(fl_display, fl_screen);
if (!fl_visual) Fl::abort(&quot;No good visual&quot;);
fl_colormap = make_a_colormap(fl_display, fl_visual-&gt;visual, fl_visual-&gt;depth);
if (!fl_visual) Fl::abort("No good visual");
fl_colormap = make_a_colormap(fl_display, fl_visual->visual, fl_visual->depth);
// it is now ok to show() windows:
window-&gt;show(argc, argv);
</PRE></UL>
window->show(argc, argv);
\endcode
<H3>Using a Subclass of Fl_Window for Special X Stuff</H3>
@ -252,7 +252,7 @@ implementation must call either <TT>Fl_X::set_xid()</TT> or
<P>An example:</P>
<UL><PRE>
\code
void MyWindow::show() {
if (shown()) {Fl_Window::show(); return;} // you must do this!
fl_open_display(); // necessary if this is first window
@ -262,11 +262,11 @@ void MyWindow::show() {
if (!visual) {
visual = figure_out_visual();
colormap = XCreateColormap(fl_display, RootWindow(fl_display,fl_screen),
vis-&gt;visual, AllocNone);
vis->visual, AllocNone);
}
Fl_X::make_xid(this, visual, colormap);
}
</PRE></UL>
\endcode
<H4>Fl_X *Fl_X::set_xid(Fl_Window *, Window xid)</H4>
@ -293,7 +293,7 @@ your own windows you might just want to put all the drawing code
in here.
<P>The X region that is a combination of all <TT>damage()</TT>
calls done so far is in <TT>Fl_X::i(this)-&gt;region</TT>. If
calls done so far is in <TT>Fl_X::i(this)->region</TT>. If
<TT>NULL</TT> then you should redraw the entire window. The
undocumented function <TT>fl_clip_region(XRegion)</TT> will
initialize the FLTK clip stack with a region or <TT>NULL</TT>
@ -301,20 +301,20 @@ for no clipping. You must set region to <TT>NULL</TT> afterwards
as <TT>fl_clip_region()</TT> will own and delete it when
done.</P>
<P>If <TT>damage() &amp; FL_DAMAGE_EXPOSE</TT> then only X
<P>If <TT>damage() & FL_DAMAGE_EXPOSE</TT> then only X
expose events have happened. This may be useful if you have an
undamaged image (such as a backing buffer) around.</P>
<P>Here is a sample where an undamaged image is kept somewhere:</P>
<UL><PRE>
\code
void MyWindow::flush() {
fl_clip_region(Fl_X::i(this)-&gt;region);
Fl_X::i(this)-&gt;region = 0;
fl_clip_region(Fl_X::i(this)->region);
Fl_X::i(this)->region = 0;
if (damage() != 2) {... draw things into backing store ...}
... copy backing store to window ...
}
</PRE></UL>
\endcode
<H4>virtual void Fl_Window::hide()</H4>
@ -324,7 +324,7 @@ window, and then call <TT>Fl_Window::hide()</TT> to get rid of
the main window identified by <TT>xid()</TT>. If you override
this, you must also override the destructor as shown:
<UL><PRE>
\code
void MyWindow::hide() {
if (mypixmap) {
XFreePixmap(fl_display,mypixmap);
@ -332,7 +332,7 @@ void MyWindow::hide() {
}
Fl_Window::hide(); // you must call this
}
</PRE></UL>
\endcode
<H4>virtual void Fl_Window::~Fl_Window()</H4>
@ -340,11 +340,11 @@ void MyWindow::hide() {
you <I>must</I> override the destructor as well (otherwise only
the base class <TT>hide()</TT> is called):
<UL><PRE>
\code
MyWindow::~MyWindow() {
hide();
}
</PRE></UL>
\endcode
<H3>Setting the Icon of a Window</H3>
@ -358,33 +358,33 @@ need to cast the icon <TT>Pixmap</TT> to a <TT>char *</TT> when
calling this method. To set a monochrome icon using a bitmap compiled
with your application use:
<UL><PRE>
#include &quot;icon.xbm&quot;
\code
#include "icon.xbm"
fl_open_display(); // needed if display has not been previously opened
Pixmap p = XCreateBitmapFromData(fl_display, DefaultRootWindow(fl_display),
icon_bits, icon_width, icon_height);
window-&gt;icon((char *)p);
</PRE></UL>
window->icon((char *)p);
\endcode
<P>To use a multi-colored icon, the XPM format and library
should be used as follows:
<UL><PRE>
#include &lt;X11/xpm.h&gt;
#include &quot;icon.xpm&quot;
\code
#include <X11/xpm.h>
#include "icon.xpm"
fl_open_display(); // needed if display has not been previously opened
Pixmap p, mask;
XpmCreatePixmapFromData(fl_display, DefaultRootWindow(fl_display),
icon_xpm, &amp;p, &amp;mask, NULL);
icon_xpm, &p, &mask, NULL);
window-&gt;icon((char *)p);
</PRE></UL>
window->icon((char *)p);
\endcode
<p>When using the Xpm library, be sure to include it in the list
of libraries that are used to link the application (usually
@ -453,7 +453,7 @@ state information and data structures.
<H3>Handling Other WIN32 Messages</H3>
<P>By default a single WNDCLASSEX called &quot;FLTK&quot; is
<P>By default a single WNDCLASSEX called "FLTK" is
created. All <TT>Fl_Window</TT>'s are of this class unless you
use <TT>Fl_Window::xclass()</TT>. The window class is created
the first time <TT>Fl_Window::show()</TT> is called.
@ -505,14 +505,14 @@ HREF="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A> is
called, FLTK stores all the silly extra arguments you need to
make a proper GDI call in some global variables:
<UL><PRE>
\code
extern HINSTANCE fl_display;
extern HWND fl_window;
extern HDC fl_gc;
COLORREF fl_RGB();
HPEN fl_pen();
HBRUSH fl_brush();
</PRE></UL>
\endcode
<P>These global variables are set before <TT>draw()</TT> is
called, or by <A
@ -523,9 +523,9 @@ the current color set by <TT>fl_color()</TT> and are created as
needed and cached. A typical GDI drawing call is written like
this:
<UL><PRE>
\code
DrawSomething(fl_gc, ..., fl_brush());
</PRE></UL>
\endcode
<P>It may also be useful to refer to <A
href="Fl_Window.html#Fl_Window.make_current"><TT>Fl_Window::current()</TT></A>
@ -543,9 +543,9 @@ need to cast the <TT>HICON</TT> handle to a <TT>char *</TT> when
calling this method. To set the icon using an icon resource
compiled with your application use:
<UL><PRE>
window-&gt;icon((char *)LoadIcon(fl_display, MAKEINTRESOURCE(IDI_ICON)));
</PRE></UL>
\code
window->icon((char *)LoadIcon(fl_display, MAKEINTRESOURCE(IDI_ICON)));
\endcode
<P>You can also use the <TT>LoadImage()</TT> and related
functions to load specific resolutions or create the icon from
@ -572,9 +572,9 @@ executables that controls whether or not to make a console
window.
<P>To always get a console window you simply create a console
application (the &quot;/SUBSYSTEM:CONSOLE&quot; option for the
application (the "/SUBSYSTEM:CONSOLE" option for the
linker). For a GUI-only application create a WIN32 application
(the &quot;/SUBSYSTEM:WINDOWS&quot; option for the linker).</P>
(the "/SUBSYSTEM:WINDOWS" option for the linker).</P>
<P>FLTK includes a <TT>WinMain()</TT> function that calls the
ANSI standard <TT>main()</TT> entry point for you. <I>This
@ -707,7 +707,7 @@ applications
will NOT copy any resource forks! For copying and moving use
CpMac and MvMac respectively. For creating a tar archive, all
executables need to be stripped from their Resource Fork before
packing, e.g. "DeRez fluid &gt; fluid.r". After unpacking the
packing, e.g. "DeRez fluid > fluid.r". After unpacking the
Resource Fork needs to be reattached, e.g. "Rez fluid.r -o
fluid".
</TD></TR></TABLE></CENTER>

4
documentation/preface.dox
View File

@ -12,7 +12,7 @@ interfaces.</P>
<P><B>This manual may be printed, modified, and/or used under
the terms of the FLTK license provided in <A
HREF="license.html">Appendix H</A>.</B>
HREF="license.html">Appendix J</A>.</B>
<H2>Organization</H2>
@ -99,7 +99,7 @@ HREF="license.html">Appendix H</A>.</B>
<P>FLTK is Copyright 1998-2006 by Bill Spitzak and others. Use and
distribution of FLTK is governed by the GNU Library General Public
License, located in <A HREF="license.html#license">Appendix H</A>.</P>
License, located in <A HREF="license.html#license">Appendix J</A>.</P>
<P>UNIX is a registered trademark of the X Open Group, Inc.
Microsoft and Windows are registered trademarks of Microsoft

47
documentation/subclassing.dox
View File

@ -26,23 +26,23 @@ subclass of <TT>Fl_Widget</TT>. <TT>Fl_Widget</TT> has only four
virtual methods, and overriding some or all of these may be necessary.
<H2>The Constructor</H2>
The constructor should have the following arguments:
<UL><PRE>
\code
MyClass(int x, int y, int w, int h, const char *label = 0);
</PRE></UL>
\endcode
This will allow the class to be used in <A href="fluid.html#FLUID">FLUID</A>
without problems.
<P>The constructor must call the constructor for the base class and
pass the same arguments: </P>
<UL><PRE>
\code
MyClass::MyClass(int x, int y, int w, int h, const char *label)
: Fl_Widget(x, y, w, h, label) {
// do initialization stuff...
}
</PRE></UL>
\endcode
<TT>Fl_Widget</TT>'s protected constructor sets <TT>x()</TT>, <TT>y()</TT>,
<TT>w()</TT>, <TT>h()</TT>, and <TT>label()</TT> to the passed values
and initializes the other instance variables to:
<UL><PRE>
\code
type(0);
box(FL_NO_BOX);
color(FL_BACKGROUND_COLOR);
@ -56,7 +56,7 @@ callback(default_callback,0);
flags(ACTIVE|VISIBLE);
image(0);
deimage(0);
</PRE></UL>
\endcode
<H2>Protected Methods of Fl_Widget</H2>
The following methods are provided for subclasses to use:
<UL>
@ -90,7 +90,7 @@ calls done since the last <TT>draw()</TT>.</P>
see what parts of your widget need redrawing.</I> The <tt>handle()</tt>
method can then set individual damage bits to limit the amount of drawing
that needs to be done:
<UL><PRE>
\code
MyClass::handle(int event) {
...
if (change_to_part1) damage(1);
@ -107,7 +107,7 @@ MyClass::draw() {
if (damage() &amp; (FL_DAMAGE_ALL | 2)) draw_part2();
if (damage() &amp; (FL_DAMAGE_ALL | 4)) draw_part3();
}
</PRE></UL>
\endcode
<H4><A name="draw_box">void Fl_Widget::draw_box() const
<BR></A>void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const</H4>
The first form draws this widget's <TT>box()</TT>, using the
@ -192,7 +192,7 @@ by calling the <A href="events.html#events"><TT>Fl::event_*()</TT></A>
handled.
<P>Here is a sample <TT>handle()</TT> method for a widget that acts as
a pushbutton and also accepts the keystroke 'x' to cause the callback: </P>
<UL><PRE>
\code
int MyClass::handle(int event) {
switch(event) {
case FL_PUSH:
@ -226,7 +226,7 @@ int MyClass::handle(int event) {
return Fl_Widget::handle(event);
}
}
</PRE></UL>
\endcode
<P>You must return non-zero if your <TT>handle()</TT> method
uses the event. If you return zero, the parent widget will try
@ -274,18 +274,17 @@ position. </P>
Fl_Group</TT>, but you'll have to duplicate the code in <TT>Fl_Group</TT>
anyways.
<P>Instances of the child widgets may be included in the parent: </P>
<UL><PRE>
\code
class MyClass : public Fl_Group {
Fl_Button the_button;
Fl_Slider the_slider;
...
};
</PRE></UL>
The constructor has to initialize these instances. They are
automatically <TT>add()</TT>ed to the group, since the <TT>Fl_Group</TT>
constructor does <TT>begin()</TT>. <I>Don't forget to call <TT>end()</TT>
or use the <A href="Fl_End.html#Fl_End"><TT>Fl_End</TT></A> pseudo-class:</I>
<UL><PRE>
\endcode
The constructor has to initialize these instances. They are automatically
<TT>add()</TT>ed to the group, since the Fl_Group constructor does Fl_Group::begin().
<I>Don't forget to call Fl_Group::end() or use the Fl_End pseudo-class:</I>
\code
MyClass::MyClass(int x, int y, int w, int h) :
Fl_Group(x, y, w, h),
the_button(x + 5, y + 5, 100, 20),
@ -294,29 +293,29 @@ MyClass::MyClass(int x, int y, int w, int h) :
...(you could add dynamically created child widgets here)...
end(); // don't forget to do this!
}
</PRE></UL>
\endcode
The child widgets need callbacks. These will be called with a pointer
to the children, but the widget itself may be found in the <TT>parent()</TT>
pointer of the child. Usually these callbacks can be static private
methods, with a matching private method:
<UL><PRE>
\code
void MyClass::static_slider_cb(Fl_Widget* v, void *) { // static method
((MyClass*)(v-&gt;parent())-&gt;slider_cb();
}
void MyClass::slider_cb() { // normal method
use(the_slider-&gt;value());
}
</PRE></UL>
\endcode
If you make the <TT>handle()</TT> method, you can quickly pass all the
events to the children using the <TT>Fl_Group::handle()</TT> method.
You don't need to override <TT>handle()</TT> if your composite widget
does nothing other than pass events to the children:
<UL><PRE>
\code
int MyClass::handle(int event) {
if (Fl_Group::handle(event)) return 1;
... handle events that children don't want ...
}
</PRE></UL>
\endcode
<P>If you override <TT>draw()</TT> you need to draw all the
children. If <TT>redraw()</TT> or <TT>damage()</TT> is called
@ -325,7 +324,7 @@ group, so this bit of <TT>damage()</TT> can be used to indicate
that a child needs to be drawn. It is fastest if you avoid
drawing anything else in this case:
<UL><PRE>
\code
int MyClass::draw() {
Fl_Widget *const*a = array();
if (damage() == FL_DAMAGE_CHILD) { // only redraw some children
@ -339,7 +338,7 @@ int MyClass::draw() {
}
}
}
</PRE></UL>
\endcode
<TT>Fl_Group</TT> provides some protected methods to make drawing
easier:
<UL>