mirrors
/
fltk
mirror of https://github.com/fltk/fltk
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Lots of documentation fixes, and added a new image for the Fluid chapter. 

git-svn-id: file:///fltk/svn/fltk/trunk@244 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Michael R Sweet 1999-01-26 21:36:02 +00:00
parent 43a4c224ef
commit b983b285cc
12 changed files with 455 additions and 397 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
documentation/Fl_Menu_Item.html
View File

@ -52,14 +52,14 @@ enum { // values for flags:
<TR valign=top><TD><IMG align=left src=./menu.gif></TD><TD>
<PRE>
Fl_Menu_Item popup[] = {
{&quot;, FL_ALT+'a', the_cb, (void*)1},
{&quot;, FL_ALT+'b', the_cb, (void*)2},
{&quot;&amp;alpha&quot;, FL_ALT+'a', the_cb, (void*)1},
{&quot;&amp;beta&quot;, FL_ALT+'b', the_cb, (void*)2},
{&quot;gamma&quot;, FL_ALT+'c', the_cb, (void*)3, FL_MENU_DIVIDER},
{&quot;, 0, strange_cb},
{&quot;, 0, charm_cb},
{&quot;, 0, truth_cb},
{&quot;b, 0, beauty_cb},
{&quot;sub, 0, 0, 0, FL_SUBMENU},
{&quot;&amp;strange&quot;, 0, strange_cb},
{&quot;&amp;charm&quot;, 0, charm_cb},
{&quot;&amp;truth&quot;, 0, truth_cb},
{&quot;b&amp;eauty&quot;, 0, beauty_cb},
{&quot;sub&amp;menu&quot;, 0, 0, 0, FL_SUBMENU},
{&quot;one&quot;},
{&quot;two&quot;},
{&quot;three&quot;},
@ -292,4 +292,4 @@ Fl_Menu_Item::next(int n=1) const
<BR> Fl_Menu_Item* Fl_Menu_Item::next(int n=1);</A></H4>
Advance a pointer by <TT>n</TT> items through a menu array, skipping
the contents of submenus and invisible items. There are two calls so
that you can advance through const and non-const data. </BODY></HTML>
that you can advance through const and non-const data. </BODY></HTML>

7
documentation/basics.html
View File

@ -57,11 +57,12 @@ FLTK header files. This can be done by selecting &quot;Settings&quot; from the
WIN32 applications. If you want to use the standard C <TT>main()</TT>
function as the entry point, FLTK includes a <TT>WinMain()</TT>
function that will call your <TT>main()</TT> function for you. </P>
<P><I>Note: The Visual C++ optimizer is known to cause problems with
<P><I>Note: The Visual C++ 5.0 optimizer is known to cause problems with
many programs. We only recommend using the &quot;Favor Small Code&quot;
optimization setting.</I></P>
optimization setting.</I> The Visual C++ 6.0 optimizer seems to be much
better and can be used with the "optimized for speed" setting.</P>
<H2>Writing Your First FLTK Program</H2>
All programs must include the file <TT>&lt;FL/Fl.H In addition the
All programs must include the file <TT>&lt;FL/Fl.H&gt;</TT>. In addition the
program must include a header file for each FLTK class it uses.
Listing 1 shows a simple &quot;Hello, World!&quot; program that uses FLTK to
display the window.

26
documentation/common.html
View File

@ -3,7 +3,7 @@
This chapter describes many of the widgets that are provided with FLTK
and covers how to query and set the standard attributes.
<H2>Buttons</H2>
FLTK provides many types of buttons:
FLTK provides many types of buttons:
<UL>
<LI><TT>Fl_Button</TT> - A standard push button. </LI>
<LI><TT>Fl_Check_Button</TT> - A button with a check box. </LI>
@ -13,7 +13,8 @@ and covers how to query and set the standard attributes.
Enter key. </LI>
<LI><TT>Fl_Round_Button</TT> - A button with a check circle. </LI>
</UL>
For all of these buttons you just need to include the corresponding <TT>
<P ALIGN=CENTER><IMG SRC="buttons.gif"></P>
For all of these buttons you just need to include the corresponding <TT>
&lt;FL/Fl_xyz_Button.H&gt;</TT> header file. The constructor takes the
bounding box of the button and optionally a label string:
<UL>
@ -39,7 +40,7 @@ rbutton-&gt;type(FL_RADIO_BUTTON);
<TT>clear()</TT></A> methods can be used on toggle buttons to turn a
toggle button on or off, respectively. Radio buttons can be turned on
with the <A href=#Fl_Widget.setonly><TT>setonly()</TT></A> method; this
will also turn off other radio buttons in the current group.
will also turn off other radio buttons in the same group.
<H2>Text</H2>
FLTK provides several text widgets for displaying and receiving text:
<UL>
@ -74,7 +75,8 @@ strings. FLTK provides the following valuators:
<LI><TT>Fl_Slider</TT> - A scrollbar with a knob. </LI>
<LI><TT>Fl_Value_Slider</TT> - A slider that shows the current value. </LI>
</UL>
The <A href=Fl_Valuator.html#Fl_Valuator.value><TT>value()</TT></A>
<P ALIGN=CENTER><IMG SRC="valuators.gif"></P>
The <A href=Fl_Valuator.html#Fl_Valuator.value><TT>value()</TT></A>
method gets and sets the current value of the widget. The <A href=Fl_Valuator.html#Fl_Valuator.minimum>
<TT>minimum()</TT></A> and <A href=Fl_Valuator.html#Fl_Valuator.maximum><TT>
maximum()</TT></A> methods set the range of values that are reported by
@ -144,11 +146,11 @@ button-&gt;labelcolor(FL_WHITE);
<P ALIGN=CENTER><IMG src="boxtypes.gif"></P>
<P><TT>FL_NO_BOX</TT> means nothing is drawn at all, so whatever is
already on the screen remains. The <TT>FL_..._FRAME</TT> types only
draw their edges, leaving the center unchanged. In the above diagram
draw their edges, leaving the interior unchanged. In the above diagram
the blue color is the area that is not drawn by the box. </P>
<H3>Making your own Boxtypes</H3>
You can define your own boxtypes by making a small function that draws
the box and adding a pointer to it to a table of boxtypes.
the box and adding it to the table of boxtypes.
<H4>The Drawing Function</H4>
The drawing function is passed the bounding box and background color
for the widget:
@ -183,9 +185,9 @@ Fl::set_boxtype(XYZ_BOX, xyz_draw, 1, 1, 2, 2);
</UL>
The last 4 arguments to <TT>Fl::set_boxtype()</TT> are the offsets for
the bounding box that should be subtracted when drawing the label
inside the box.
inside the box.
<H2><A NAME=labels>Labels and Label Types</A></H2>
The <TT>label()</TT>, <TT>align</TT>, <TT>labelfont()</TT>, <TT>
The <TT>label()</TT>, <TT>align()</TT>, <TT>labelfont()</TT>, <TT>
labelsize()</TT>, and <TT>labeltype()</TT> methods control the labeling
of widgets.
<H3>label()</H3>
@ -226,7 +228,7 @@ raised </LI>
<TT>Fl_Bitmap</TT></A> or <A href=drawing.html#Fl_Pixmap><TT>Fl_Pixmap</TT>
</A> objects.
<H4>Making Your Own Label Types</H4>
Label types are actually indexes into a table of functions to draw
Label types are actually indexes into a table of functions that draw
them. The primary purpose of this is to let you reuse the <TT>label()</TT>
pointer as a pointer to arbitrary data such as a bitmap or pixmap. You
can also use this to draw the labels in ways inaccessible through the <TT>
@ -252,7 +254,7 @@ label value is <TT>NULL</TT>.
Fl_Label</TT></A> structure and references to the width and height: </P>
<UL>
<PRE>
void xyz_measure(Fl_Label *label, int w int h {
void xyz_measure(Fl_Label *label, int &amp;w, int &amp;h) {
...
}
</PRE>
@ -276,9 +278,9 @@ type.
<P>The <TT>Fl::set_labeltype</TT> method can also be used to overload
an existing label type such as <TT>FL_NORMAL_LABEL</TT>. </P>
<H4><A name=symbols>Symbol Labels</A></H4>
<P>The <TT>FL_SYMBOL_LABEL</TT> label type uses the <TT>label()</TT>
The <TT>FL_SYMBOL_LABEL</TT> label type uses the <TT>label()</TT>
string to look up a small drawing procedure in a hash table. For
historical reasons the string always starts with '@', if it starts with
historical reasons the string always starts with '@'; if it starts with
something else (or the symbol is not found) the label is drawn
normally:
<CENTER><IMG src=./symbols.gif></CENTER>

56
documentation/drawing.html
View File

@ -28,9 +28,9 @@ overlay, or OpenGL windows!</I></LI>
drawing functions:
<UL>
<LI><A href=#clipping>Clipping</A></LI>
<LI><A href=#color>Colors</A></LI>
<LI><A href=#colors>Colors</A></LI>
<LI><A href=#fast>Fast Shapes</A></LI>
<LI><A href=#vertex>Complex Shapes</A></LI>
<LI><A href=#complex>Complex Shapes</A></LI>
<LI><A href=#text>Text</A></LI>
<LI><A href=#images>Images</A></LI>
<LI><A href=#cursor>Cursor</A></LI>
@ -43,12 +43,14 @@ fl_clip</TT>, and put the drawings back by using <TT>fl_pop_clip</TT>.
transformation matrix).
<P>In addition, the system may provide clipping when updating windows,
this clip region may be more complex than a simple rectangle. </P>
<H4>void fl_clip(int x, int y, int w, int h)</H4>
Intersect the current clip region with a rectangle and push this new
<H4>void fl_push_clip(int x, int y, int w, int h)</H4>
Intersect the current clip region with a rectangle and push this new
region onto the stack.
<H4>void fl_push_no_clip()</H4>
Pushes an empty clip region on the stack so nothing will be clipped.
<H4>void fl_pop_clip()</H4>
Restore the previous clip region. <I>You must call <TT>fl_pop_clip()</TT>
once for every time you call <TT>fl_clip()</TT>. If you return to
Restore the previous clip region. <I>You must call <TT>fl_pop_clip()</TT>
once for every time you call <TT>fl_clip()</TT>. If you return to
FLTK with the clip stack not empty unpredictable results occur.</I>
<H4>int fl_not_clipped(int x, int y, int w, int h)</H4>
Returns true if any of the rectangle intersects the current clip
@ -57,9 +59,9 @@ Under X this returns 2 if the rectangle is partially clipped, and 1 if
it is entirely inside the clip region</I>.
<H4>int fl_clip_box(int x, int y, int w, int h, int &amp;X, int &amp;Y, int &amp;W,
int &amp;H)</H4>
Intersect the rectangle <TT>x,y,w,h</TT> with the current clip region
Intersect the rectangle <TT>x,y,w,h</TT> with the current clip region
and returns the bounding box of the result in <TT>X,Y,W,H</TT>.
Returns non-zero if the resulting rectangle is different than the
Returns non-zero if the resulting rectangle is different than the
original. This can be used to limit the necessary drawing to a
rectangle. <TT>W</TT> and <TT>H</TT> are set to zero if the rectangle
is completely outside the region.
@ -70,8 +72,8 @@ is completely outside the region.
is <I>not</I> the X or WIN32 pixel, it is an index into an internal
table! The table provides several general colors, a 24-entry gray
ramp, and a 5x8x5 color cube. All of these are named with
poorly-documented symbols in <A href=enumerations.html#enumerations><TT>
&lt;FL/Enumerations.H&gt;</TT></A>.
symbols in <A href=enumerations.html#enumerations>
<TT>&lt;FL/Enumerations.H&gt;</TT></A>.
<P>For colormapped displays, a color cell will be allocated out of <TT>
fl_colormap</TT> the first time you use a color. If the colormap fills
up then a least-squares algorithm is used to find the closest color. </P>
@ -83,7 +85,7 @@ for state save/restore.
possible match to the RGB color is used. The RGB color is used
directly on TrueColor displays. For colormap visuals the nearest index
in the gray ramp or color cube is used.
<H3><A name=fast_shapes>Fast Shapes</A></H3>
<H3><A name=fast>Fast Shapes</A></H3>
These are used to draw almost all the FLTK widgets. They draw on
exact pixel boundaries and are as fast as possible, and their behavior
will be duplicated exactly on any platform FLTK is ported to. It is
@ -121,10 +123,9 @@ drawn first, then a vertical, then a horizontal.
Draw 1-pixel wide vertical and horizontal lines. A vertical line is
drawn first, then a horizontal, then a vertical.
<H4>void fl_arc(int x, int y, int w, int h, double a1, double a2)
<BR> void fl_pie(int x, int y, int w, int h, double a1, double a2)
<BR> void fl_chord(int x, int y, int w, int h, double a1, double a2)</H4>
<BR> void fl_pie(int x, int y, int w, int h, double a1, double a2)</H4>
High-speed ellipse sections. These functions match the rather limited
circle drawing code provided by X and MSWindows. The advantage over
circle drawing code provided by X and WIN32. The advantage over
using <A href=#fl_arc><TT>fl_arc</TT></A> is that they are faster
because they often use the hardware, and they draw much nicer small
circles, since the small sizes are often hard-coded bitmaps.
@ -138,12 +139,11 @@ different number of arguments than the <A href=#fl_arc><TT>fl_arc()</TT></A>
<P><TT>fl_pie()</TT> draws a filled-in pie slice. This slice may
extend outside the line drawn by <TT>fl_arc</TT>, to avoid this use <TT>
w - 1</TT> and <TT>h - 1</TT>. </P>
<P><TT>fl_chord()</TT> is not yet implemented. </P>
<H3><A name=complex_shapes>Complex Shapes</A></H3>
<H3><A name=complex>Complex Shapes</A></H3>
These functions let you draw arbitrary shapes with 2-D linear
transformations. The functionality matches that found in Adobe&reg;
PostScript<SUP>TM</SUP>. The exact pixels filled in is less defined
than for the above calls, so that FLTK can take advantage of drawing
PostScript<SUP>TM</SUP>. The exact pixels that are filled is less defined
than for the previous calls so that FLTK can take advantage of drawing
hardware. The transformed vertices are rounded to integers before
drawing the line segments. This severely limits the accuracy of these
functions for complex graphics. Use OpenGL when greater accuracy
@ -234,8 +234,8 @@ box to draw the text at so it looks centered vertically in that box.
<H4>float fl_width(const char*)
<BR> float fl_width(const char*, int n)
<BR> float fl_width(uchar)</H4>
Return the width of a nul-terminated string, a sequence of <TT>n</TT>
characters, or a single character.
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>const char *fl_shortcut_label(ulong)</H4>
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>
@ -318,10 +318,6 @@ thus redrawing is <I>much</I> faster.
It is undefined whether the location or drawing of the image is
affected by the current transformation, so you should only call these
when it is the identity.
<H4>void fl_draw_bitmap(const uchar *, int X, int Y, int W, int H, int
LD = 0)</H4>
This function is planned but not yet implemented (it may be impossible
under X without allocating a pixmap).
<H4>void fl_draw_image(const uchar *, int X, int Y, int W, int H, int D
= 3, int LD = 0)
<BR> void fl_draw_image_mono(const uchar *, int X, int Y, int W, int H,
@ -383,8 +379,8 @@ 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>int fl_draw_pixmap(char **data, int X, int Y, Fl_Color = FL_GRAY)</H4>
Draw XPM image data, with the top-left corner at the given position.
The images is dithered on 8-bit displays so you won't lose color space
Draws XPM image data, with the top-left corner at the given position.
The image is dithered on 8-bit displays so you won't lose color space
for programs displaying both images and pixmaps. This function returns
zero if there was any error decoding the XPM data.
<P>To use an XPM, do: </P>
@ -395,7 +391,7 @@ zero if there was any error decoding the XPM data.
fl_draw_pixmap(foo, X, Y);
</PRE>
</UL>
In the current version the XPM data is converted to 8-bit full color
In the current version the XPM data is converted to 24-bit RGB color
and passed through <TT>fl_draw_image()</TT>. This is obviously not the
most efficient way to do it, and has the same visual limitations as
listed above for <TT>fl_draw_image()</TT>. Transparent colors are
@ -448,7 +444,7 @@ make an <TT>Fl_Widget</TT> use a pixmap as a label, or to just draw the
pixmap directly. <I>Under X it will create an offscreen pixmap the
first time it is drawn, and copy this each subsequent time it is drawn</I>
.
<P>The current implementation converts the pixmap to 8 bit color data
<P>The current implementation converts the pixmap to 24-bit RGB data
and uses <A href=#fl_draw_image><TT>fl_draw_image()</TT></A> to draw
it. Thus you will get dithered colors on an 8 bit screen. </P>
<H4>Fl_Pixmap(char *const* data)</H4>
@ -482,7 +478,7 @@ to draw the pixmap. You can use the same pixmap for many widgets.
make an <TT>Fl_Widget</TT> use an image as a label, or to just draw the
image directly. <I>Under X it will create an offscreen pixmap the first
time it is drawn, and copy this each subsequent time it is drawn</I>.
<H4>Fl_Image(char uchar *data, int W, int H, int D = 3, int LD = 0)</H4>
<H4>Fl_Image(const uchar *data, int W, int H, int D = 3, int LD = 0)</H4>
Construct using a pointer to RGB data. <TT>W</TT> and <TT>H</TT> are
the size of the image in pixels. <TT>D</TT> is the delta between pixels
(it may be more than 3 to skip alpha or other data, or negative to flip
@ -504,4 +500,4 @@ ox</TT> and <TT>oy</TT> may be negative and <TT>w</TT> and <TT>h</TT>
the same as doing <TT>draw(x,y,this-&gt;w,this-&gt;h,0,0)</TT>.
<H4>void label(Fl_Widget *)</H4>
Change the <TT>label()</TT> and the <TT>labeltype()</TT> of the widget
to draw the image. You can use the same image for many widgets. </BODY></HTML>
to draw the image. You can use the same image for many widgets. </BODY></HTML>

8
documentation/editor.html
View File

@ -6,7 +6,7 @@ editor.
Since this will be the first big project you'll be doing with FLTK,
lets define what we want our text editor to do:
<OL>
<LI>Menu_Bar/menus for all functions. </LI>
<LI>Menubar/menus for all functions. </LI>
<LI>Edit a single text file. </LI>
<LI>Load from a file. </LI>
<LI>Save to a file. </LI>
@ -31,7 +31,7 @@ things:
<UL>
<PRE>
Fl_Window *window;
Fl_Menu_Bar *menubar;
Fl_Menu_Bar *menubar;
Fl_Multiline_Input *input;
Fl_Window *replace_dlg;
Fl_Input *replace_find;
@ -48,7 +48,7 @@ char search[256] = &quot;&quot;;
The <TT>window</TT> variable is our top-level window described
previously. We'll cover the other variables as we build the
application.
<H2>Menu_Bars and Menus</H2>
<H2>Menubars and Menus</H2>
The first goal requires us to use a menubar and menus that define each
function the editor needs to perform. The <A href=Fl_Menu_Item.html#Fl_Menu_Item>
<TT>Fl_Menu_Item</TT></A> structure is used to define the menus and
@ -83,7 +83,7 @@ Fl_Menu_Item menuitems[] = {
};
</PRE>
</UL>
Once we have the menus defined we can create the <TT>Fl_Menu_Bar</TT>
Once we have the menus defined we can create the <TT>Fl_Menu_Bar</TT>
widget and assign the menus to it with:
<UL>
<PRE>

60
documentation/events.html
View File

@ -24,13 +24,17 @@ Fl::pushed()</TT></A> widget and will get <TT>FL_DRAG</TT> and the
matching <TT>FL_RELEASE</TT> events. If <TT>handle()</TT> returns zero
then FLTK will try sending the <TT>FL_PUSH</TT> to another widget. </P>
<H3>FL_DRAG</H3>
The mouse has moved with a button held down.
The mouse has moved with a button held down. The current button state is
in <a href="#event_state"><tt>Fl::event_state()</tt></a>. The mouse position
is in <a href="#event_x"><tt>Fl::event_x()</tt></a> and
<a href="#event_y"><tt>Fl::event_y()</tt></a>.
<H3>FL_RELEASE</H3>
A mouse button has been released. You can find out what button by
calling <A href=#event_button><TT>Fl::event_button()</TT></A>.
<H3>FL_MOVE</H3>
The mouse has moved without any mouse buttons held down. This event
is sent to the <TT>belowmouse()</TT> widget.
is sent to the <A href="functions.html#belowmouse"><TT>Fl::belowmouse()</TT></A>
widget.
<H2>Focus Events</H2>
<H3>FL_ENTER</H3>
The mouse has been moved to point at this widget. This can be used
@ -55,8 +59,8 @@ using tab, arrows, or other keys. You can check <A href=functions.html#event_ke
navigation it will be the key pressed and for instructions from the
window manager it will be zero. </P>
<H3>FL_UNFOCUS</H3>
Sent to the previous <A href=functions.html#focus><TT>Fl::focus()</TT></A>
when another widget gets the focus.
Sent to the previous <A href=functions.html#focus><TT>Fl::focus()</TT></A>
widget when another widget gets the focus.
<H2>Keyboard Events</H2>
<H3>FL_KEYBOARD</H3>
A key press. The key pressed can be found in <A href=functions.html#event_key>
@ -69,7 +73,7 @@ the key. It will then attempt to send it to a parent widget. If none
of them want it, it will change the event into a <TT>FL_SHORTCUT</TT>
event.
<H3>FL_SHORTCUT</H3>
If the <A href=functions.html#focus><TT>Fl::focus()</TT></A> is zero
If the <A href=functions.html#focus><TT>Fl::focus()</TT></A> widget is zero
or ignores an <TT>FL_KEYBOARD</TT> event then FLTK tries sending this
event to every widget it can, until one of them returns non-zero. <TT>
FL_SHORTCUT</TT> is first sent to the <TT>belowmouse()</TT> widget,
@ -124,21 +128,21 @@ Thus it is valid inside <TT>handle()</TT> and <TT>callback()</TT>
methods.
<P>These are all trivial inline functions and thus very fast and small: </P>
<UL>
<LI><A name=event_button>Fl::event_button</A></LI>
<LI><A name=event_clicks>Fl::event_clicks</A></LI>
<LI><A name=event_inside>Fl::event_inside</A></LI>
<LI><A name=event_is_click>Fl::event_is_click</A></LI>
<LI><A name=event_key>Fl::event_key</A></LI>
<LI><A name=event_length>Fl::event_length</A></LI>
<LI><A name=event_state>Fl::event_state</A></LI>
<LI><A name=event_text>Fl::event_text</A></LI>
<LI><A name=event_x>Fl::event_x</A></LI>
<LI><A name=event_x_root>Fl::event_x_root</A></LI>
<LI><A name=event_y>Fl::event_y</A></LI>
<LI><A name=event_y_root>Fl::event_y_root</A></LI>
<LI><A name=get_key>Fl::get_key</A></LI>
<LI><A name=get_mouse>Fl::get_mouse</A></LI>
<LI><A name=test_shortcut>Fl::test_shortcut</A></LI>
<LI><A href=functions.html#event_button><TT>Fl::event_button</TT></A></LI>
<LI><A href=functions.html#event_clicks><TT>Fl::event_clicks</TT></A></LI>
<LI><A href=functions.html#event_inside><TT>Fl::event_inside</TT></A></LI>
<LI><A href=functions.html#event_is_click><TT>Fl::event_is_click</TT></A></LI>
<LI><A href=functions.html#event_key><TT>Fl::event_key</TT></A></LI>
<LI><A href=functions.html#event_length><TT>Fl::event_length</TT></A></LI>
<LI><A href=functions.html#event_state><TT>Fl::event_state</TT></A></LI>
<LI><A href=functions.html#event_text><TT>Fl::event_text</TT></A></LI>
<LI><A href=functions.html#event_x><TT>Fl::event_x</TT></A></LI>
<LI><A href=functions.html#event_x_root><TT>Fl::event_x_root</TT></A></LI>
<LI><A href=functions.html#event_y><TT>Fl::event_y</TT></A></LI>
<LI><A href=functions.html#event_y_root><TT>Fl::event_y_root</TT></A></LI>
<LI><A href=functions.html#get_key><TT>Fl::get_key</TT></A></LI>
<LI><A href=functions.html#get_mouse><TT>Fl::get_mouse</TT></A></LI>
<LI><A href=functions.html#test_shortcut><TT>Fl::test_shortcut</TT></A></LI>
</UL>
<H2><A name=propagation>Event Propagation</A></H2>
FLTK follows very simple and unchangeable rules for sending events.
@ -156,14 +160,14 @@ make the <TT>Fl_Group</TT> code somewhat easier, FLTK sends some events
FL_SHORTCUT</TT>, <TT>FL_UNFOCUS</TT>, and <TT>FL_LEAVE</TT>) directly
to leaf widgets. These procedures control those leaf widgets: </P>
<UL>
<LI><A href=osissues.html#add_handler>Fl::add_handler</A></LI>
<LI><A href=functions.html#belowmouse>Fl::belowmouse</A></LI>
<LI><A href=functions.html#focus>Fl::focus</A></LI>
<LI><A href=functions.html#grab>Fl::grab</A></LI>
<LI><A href=functions.html#modal>Fl::modal</A></LI>
<LI><A href=functions.html#pushed>Fl::pushed</A></LI>
<LI><A href=functions.html#release>Fl::release</A></LI>
<LI><A href=Fl_Widget.html#Fl_Widget.take_focus>Fl_Widget::take_focus</A>
<LI><A href=osissues.html#add_handler><TT>Fl::add_handler</TT></A></LI>
<LI><A href=functions.html#belowmouse><TT>Fl::belowmouse</TT></A></LI>
<LI><A href=functions.html#focus><TT>Fl::focus</TT></A></LI>
<LI><A href=functions.html#grab><TT>Fl::grab</TT></A></LI>
<LI><A href=functions.html#modal><TT>Fl::modal</TT></A></LI>
<LI><A href=functions.html#pushed><TT>Fl::pushed</TT></A></LI>
<LI><A href=functions.html#release><TT>Fl::release</TT></A></LI>
<LI><A href=Fl_Widget.html#Fl_Widget.take_focus><TT>Fl_Widget::take_focus</TT></A>
</LI>
</UL>

471
documentation/fluid.html
View File

@ -3,39 +3,71 @@
This chapter shows how to use the Fast Light User-Interface Designer
(&quot;FLUID&quot;) to create your GUIs.
<H2>What is FLUID?</H2>
The Fast Light User Interface Designer, or &quot;FLUID&quot;, is a graphical
The Fast Light User Interface Designer, or FLUID, is a graphical
editor that is used to produce FLTK source code.
<P>FLUID edits and saves its state in &quot;.fl&quot; files. These files are
<P>FLUID edits and saves its state in <TT>.fl</TT> files. These files are
text, and you can (with care) edit them in a text editor, perhaps to
get some special effects. </P>
<P>FLUID can &quot;compile&quot; the .fl file into a .cxx and a .h file. The
.cxx file defines all the objects from the .fl file and the .h file
<P>FLUID can &quot;compile&quot; the <TT>.fl</TT> file into a <TT>.cxx</TT> and a <TT>.h</TT> file. The
<TT>.cxx</TT> file defines all the objects from the <TT>.fl</TT> file and the <TT>.h</TT> file
declares all the global ones. </P>
<P>A simple program can be made by putting all your code (including a <TT>
main()</TT> function) into the .fl file and thus making the .cxx file a
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 .cxx files that call the FLUID functions.
These .cxx files must <TT>#include</TT> the .h file or they can <TT>
#include</TT> the .cxx file so it still appears to be a single source
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
file.
<CENTER><IMG src=./fluid-org.gif></CENTER>
</P>
<P>Normally the FLUID file defines one or more &quot;functions&quot;, which
output C++ functions. Each function defines a one or more FLTK
<P>Normally the FLUID file defines one or more functions or classes which
output C++ code. Each function defines a one or more FLTK
windows, and all the widgets that go inside those windows. </P>
<P>Widgets created by FLUID are either &quot;named&quot;, &quot;complex named&quot; or
&quot;unnamed&quot;. A named widget has a legal C++ variable identifier as its
name (i.e. only alphanumeric and underscore). In this case FLUID
defines a global variable or class member that will point at the widget
after the function defining it is called. A &quot;complex named&quot; object has
after the function defining it is called. A complex named object has
punctuation such as '.' or '-&gt;' or any other symbols in its name. In
this case FLUID assigns a pointer to the widget to the name, but does
not attempt to declare it. This can be used to get the widgets into
structures. An &quot;unnamed&quot; widget has a blank name and no pointer to
them is stored. </P>
structures. An unnamed widget has a blank name and no pointer is stored. </P>
<P>Widgets may either call a named callback function that you write in
another source file, or you can supply a small piece of C++ source and
FLUID will write a private callback function into the .cxx file. </P>
FLUID will write a private callback function into the <TT>.cxx</TT> file. </P>
<H2>Running FLUID Under UNIX</H2>
To run FLUID under UNIX, type:
<UL>
<PRE>
fluid <I>filename.fl</I> &amp;</PRE>
</UL>
to edit the <TT>.fl</TT> file <TT>filename.fl</TT>. If the file does not exist
you will get an error pop-up, but if you dismiss it you will be editing
a blank file of that name. You can run FLUID without any name, in
which case you will be editing an unnamed blank setup (but you can use
save-as to write it to a file).
<P>You can provide any of the standard FLTK switches before the filename: </P>
<UL>
<PRE>
-display host:n.n
-geometry WxH+X+Y
-title windowtitle
-name classname
-iconic
-fg color
-bg color
-bg2 color
</PRE>
</UL>
Changing the colors may be useful to see what your interface will look
at if the user calls it with the same switches.
<P>In the current version, if you don't go into the background (with
'&amp;' then you will be able to abort FLUID by typing ^C on the terminal. It
will exit immediately, losing any changes. </P>
<H2>Running FLUID Under Microsoft Windows</H2>
To run FLUID under WIN32, double-click on the <I>fluid.exe</I> file.
You can also run FLUID from the Command Prompt window (FLUID always
runs in the background under WIN32).
<H2>A Short Tutorial</H2>
<OL>
<LI>Type &quot;FLUID&quot; </LI>
@ -85,59 +117,24 @@ panel. </LI>
<LI>Type &quot;Alt+Q&quot; to exit FLUID. </LI>
<LI>Ok, now try to make a real program. </LI>
</OL>
<H2>Running FLUID Under UNIX</H2>
To run FLUID under UNIX, type:
<UL>
<PRE>
fluid <I>filename.fl</I> </PRE>
</UL>
to edit the .fl file <I>filename.fl</I>. If the file does not exist
you will get an error pop-up, but if you dismiss it you will be editing
a blank file of that name. You can run FLUID without any name, in
which case you will be editing an unnamed blank setup (but you can use
save-as to write it to a file).
<P>You can provide any of the standard FLTK switches before the name: </P>
<UL>
<PRE>
-display host:n.n
-geometry WxH+X+Y
-title windowtitle
-name classname
-iconic
-fg color
-bg color
-bg2 color
</PRE>
</UL>
Changing the colors may be useful to see what your interface will look
at if the user calls it with the same switches.
<P>In the current version, if you don't go into the background (with
'then you will be able to abort FLUID by typing ^C on the terminal. It
will exit immediately, losing any changes. </P>
<H2>Running FLUID Under Microsoft Windows</H2>
To run FLUID under windows, double-click on the <I>fluid.exe</I> file.
You can also run FLUID from the Command Prompt window (FLUID always
runs in the background).
<H2>Compiling .fl files</H2>
<H2>Compiling <TT>.fl</TT> files</H2>
FLUID can also be called as a command-line &quot;compiler&quot; to create the
.cxx and .h file from a .fl file. To do this type:
<UL>
<PRE>
FLUID -c <I>filename.fl</I>
</PRE>
</UL>
This will read the .fl file and write <I>filename.cxx</I> and <I>
<TT>.cxx</TT> and <TT>.h</TT> file from a <TT>.fl</TT> file. To do this type:
<UL><PRE>
FLUID -c <I>filename.fl</I>
</PRE></UL>
This will read the <TT>filename.fl</TT> file and write <I>filename.cxx</I> and <I>
filename.h</I>. The directory will be stripped, so they are written to
the current directory always. If there are any errors reading or
writing the files it will print the error and exit with a non-zero
code. In a makefile you can use a line like this: work:
code. In a makefile you can use a line like this:
<UL>
<PRE>
my_panels.h my_panels.cxx: my_panels.fl
fluid -c my_panels.fl
</PRE>
</UL>
Some versions of make will accept rules like this to allow all .fl
Some versions of make will accept rules like this to allow all <TT>.fl</TT>
files found to be compiled:
<UL>
<PRE>
@ -149,84 +146,86 @@ files found to be compiled:
<H2>The Widget Browser</H2>
<TABLE cellpadding=0 cellspacing=0>
<TR><TD>The main window shows a menu bar and a scrolling browser of all
the defined widgets. The name of the .fl file being edited is shown in
the defined widgets. The name of the <TT>.fl</TT> file being edited is shown in
the window title.
<P>The widgets are stored in a hierarchy. You can open and close a
level by clicking the &quot;triangle&quot; at the left of a widget. This widget
is the <I>parent</I>, and all the widgets listed below it are its <I>
children</I>. There can be zero children. </P>
<P>The top level of the hierarchy is <I>functions</I>. Each of these
will produce a single C++ public function in the output .cxx file.
Calling the function will create all of its child windows. </P>
<P>The second level of the hierarchy is <I>windows</I>. Each of these
produces an instance of class Fl_Window. </P>
<P>Below that are either <I>widgets</I> (subclasses of Fl_Widget) or <I>
level by clicking the &quot;triangle&quot; at the left of a widget.
The leftmost widgets are the <I>parents</I>, and all the widgets
listed below them are their <I>children</I>. Parents don't have to have
any children.</P>
<P>The top level of the hierarchy is composed of <I>functions</I> and
<I>classes</I>. Each of these will produce a single C++ public
function or class in the output <TT>.cxx</TT> file. Calling the function or
instantiating the class will create all of the child widgets. </P>
<P>The second level of the hierarchy contains the <I>windows</I>. Each of these
produces an instance of class <tt>Fl_Window</tt>. </P>
<P>Below that are either <I>widgets</I> (subclasses of <tt>Fl_Widget</tt>) or <I>
groups</I> of widgets (including other groups). Plain groups are for
layout, navigation, and resize purposes. <I>Tab groups</I> provide the
well-known file-card tab interface. </P>
<P>Widgets are shown in the browser as either their <I>name</I> (such
as &quot;main_panel&quot; in the example), or if <I>unnamed</I> as their <I>type</I>
and <I>label</I> (such as &quot;Button &quot;the green&quot;&quot;). </P>
<P>Widgets are shown in the browser by either their <I>name</I> (such
as &quot;main_panel&quot; in the example), or by their <I>type</I>
and <I>label</I> (such as &quot;Button &quot;the green&quot;&quot;). </P>
</TD><TD><IMG src=./fluid_main.gif width=245></TD></TR>
</TABLE>
You <I>select</I> widgets by clicking on their names, which highlights
them (you can also select widgets from any displayed window). You can
select many widgets by dragging the mouse across them, or by using
shift+click to toggle them on and off. To select no widgets, click in
the blank area under the last widget. Notice that hidden children may
be selected and there is no visual indication of this.
<P>You <I>open</I> widgets by double clicking them, or (to open several
widgets you have picked) by typing the F1 key. This will bring up a
control panel or window from which you can change the widget. </P>
Shift+Click to toggle them on and off. To select no widgets, click in
the blank area under the last widget. Note that hidden children may
be selected even when there is no visual indication of this.
<P>You <I>open</I> widgets by double-clicking on them, or (to open several
widgets you have picked) by typing the F1 key. A control panel will appear
so you can change the widget(s).</P>
<H2>Menu Items</H2>
<P>The menu bar at the top is duplicated as a pop-up menu on any
displayed window. The shortcuts for all the menu items work in any
window. The menu items are: </P>
<H3>File/Open... (Alt+Shift+O)</H3>
Discard the current editing session and read in a different .fl file.
You are asked for confirmation if you have changed the current data.
<P>FLUID can also read .fd files produced by the Forms and XForms
&quot;fdesign&quot; programs. It is best to read them with Merge. FLUID does
not understand everything in a .fd file, and will print a warning
message on the controlling terminal for all data it does not
understand. You will probably need to edit the resulting setup to fix
these errors. Be careful not to save the file without changing the
name, as FLUID will write over the .fd file with its own format, which
fdesign cannot read! </P>
<H3>File/Open... (Alt+o)</H3>
Discards the current editing session and reads in a different <TT>.fl</TT> file.
You are asked for confirmation if you have changed the current file.
<P>FLUID can also read <tt>.fd</tt> files produced by the Forms and
XForms &quot;fdesign&quot; programs. It is best to File/Merge them
instead of opening them. FLUID does not understand everything in a
<tt>.fd</tt> file, and will print a warning message on the controlling
terminal for all data it does not understand. You will probably need
to edit the resulting setup to fix these errors. Be careful not to
save the file without changing the name, as FLUID will write over the
<tt>.fd</tt> file with its own format, which fdesign cannot read! </P>
<H3>File/Save (Alt+s)</H3>
Write the current data to the .fl file. If the file is unnamed
(because FLUID was started with no name) then ask for a file name.
Writes the current data to the <TT>.fl</TT> file. If the file is unnamed
then FLUID will ask for a filename.
<H3>File/Save As...(Alt+Shift+S)</H3>
Ask for a new name to save the file as, and save it.
Asks for a new filename and saves the file.
<H3>File/Merge... (Alt+i)</H3>
Insert the contents of another .fl file, without changing the name of
the current .fl file. All the functions (even if they have the same
names as the current ones) are added, you will have to use cut/paste to
Inserts the contents of another <TT>.fl</TT> file, without changing the name of
the current <TT>.fl</TT> file. All the functions (even if they have the same
names as the current ones) are added, and you will have to use cut/paste to
put the widgets where you want.
<H3>File/Write code (Alt+Shift+C)</H3>
&quot;Compiles&quot; the data into a .cxx and .h file. These are exactly the
same as the files you get when you run FLUID with the -c switch.
<P>The output file names are the same as the .fl file, with the leading
directory and trailing &quot;.fl&quot; stripped, and &quot;.h&quot; or &quot;.cxx&quot; appended.
Currently there is no way to override this. </P>
<H3>File/Write Code (Alt+Shift+C)</H3>
&quot;Compiles&quot; the data into a <TT>.cxx</TT> and <TT>.h</TT>
file. These are exactly the same as the files you get when you run
FLUID with the <tt>-c</tt> switch.
<P>The output file names are the same as the <TT>.fl</TT> file, with
the leading directory and trailing &quot;.fl&quot; stripped, and
&quot;.h&quot; or &quot;.cxx&quot; appended. </P>
<H3>File/Quit (Alt+q)</H3>
Exit FLUID. You are asked for confirmation if you have changed the
Exits FLUID. You are asked for confirmation if you have changed the
current data.
<H3>Edit/Undo (Alt+z)</H3>
Don't you wish... This isn't implemented yet. You should do save
often so that any mistakes you make don't irretrivably destroy your
data.
This isn't implemented yet. You should do save often so you can
recover from any mistakes you make.
<H3>Edit/Cut (Alt+x)</H3>
Delete the selected widgets and all their children. These are saved
to a &quot;clipboard&quot; file (/usr/tmp/cut_buffer.fl) and can be pasted back
into this FLUID or any other one.
Deletes the selected widgets and all of their children. These are saved
to a &quot;clipboard&quot; file and can be pasted back into any FLUID
window.
<H3>Edit/Copy (Alt+c)</H3>
Copy the selected widgets and all their children to the &quot;clipboard&quot;
Copies the selected widgets and all of their children to the &quot;clipboard&quot;
file.
<H3>Edit/Paste (Alt+c)</H3>
Paste in the widgets in the clipboard file.
Pastes the widgets from the clipboard file.
<P>If the widget is a window, it is added to whatever function is
selected, or contains the current selection. </P>
selected, or contained in the current selection. </P>
<P>If the widget is a normal widget, it is added to whatever window or
group is selected. If none is, it is added to the window or group that
is the parent of the current selection. </P>
@ -234,107 +233,114 @@ is the parent of the current selection. </P>
doing a paste. </P>
<P>Cut/paste is the only way to change the parent of a widget. </P>
<H3>Edit/Select All (Alt+a)</H3>
Select all widgets in the same group as the current selection.
Selects all widgets in the same group as the current selection.
<P>If they are all selected already then this selects all widgets in
that group's parent. Repeatedly typing Alt+a will select larger and
larger groups of widgets until everything is selected. </P>
<H3>Edit/Open... (F1 or double click)</H3>
If the current widget is a window and it is not displayed, display it.
Otherwise open a control panel for the most recent (and possibly all)
selected widgets.
Displays the current widget in the attributes panel. If the widget is a window
and it is not visible then the window is shown instead.
<H3>Edit/Sort</H3>
All the selected widgets are sorted into left to right, top to bottom
Sorts the selected widgets into left to right, top to bottom
order. You need to do this to make navigation keys in FLTK work
correctly. You may then fine-tune the sorting with &quot;Earlier&quot; and
&quot;Later&quot;. This does not affect the positions of windows or functions.
<H3>Edit/Earlier (F2)</H3>
All the selected widgets are moved one earlier in order amoung the
Moves all of the selected widgets one earlier in order among the
children of their parent (if possible). This will affect navigation
order, and if the widgets overlap it will affect how they draw, as the
later widget is drawn on top of the earlier one. You can also use this
to reorder functions and windows within functions.
to reorder functions, classes, and windows within functions.
<H3>Edit/Later (F3)</H3>
All the selected widgets are moved one later in order amoung the
Moves all of the selected widgets one later in order among the
children of their parent (if possible).
<H3>Edit/Group (F7)</H3>
Create a new Fl_Group and make all the currently selected widgets be
Creates a new <tt>Fl_Group</tt> and make all the currently selected widgets
children of it.
<H3>Edit/Ungroup (F8)</H3>
If all the children of a group are selected, delete that group and
make them all be children of its parent.
<H3>Edit/Overlays on/off (Alt+o)</H3>
Toggle the display of the red overlays off, without changing the
Deletes the parent group if all the children of a group are selected.
<H3>Edit/Overlays on/off (Alt+Shift+O)</H3>
Toggles the display of the red overlays off, without changing the
selection. This makes it easier to see box borders and how the layout
looks. The overlays will be forced back on if you change the
selection.
<H3>Edit/Preferences (Alt+p)</H3>
Currently the only preferences are for the &quot;alignment grid&quot; that all
widgets snap to when you move them and resize them, and for the &quot;snap&quot;
which is how far a widget has to be dragged from its original position
to actually change.
<H3>New/code/Function</H3>
Create a new C function. You will be asked for a name for the
<TABLE WIDTH=100%>
<TR>
<TD VALIGN=TOP>
Displays the preferences panel. The alignment preferences control the
grid that all widgets snap to when you move and resize them, and for the
"snap" which is how far a widget has to be dragged from its original position
to actually change.
<P>The output filenames control the extensions or names of the files the are
generated by FLUID. If you check the "Include .h from .cxx" button the code
file will include the header file automatically.
</TD>
<TD VALIGN=TOP><IMG SRC="fluid_prefs.gif"></TD>
</TR>
</TABLE>
<H3>New/Code/Function</H3>
Creates a new C function. You will be asked for a name for the
function. This name should be a legal C++ function template, without
the return type. You can pass arguments, they can be referred to by
the return type. You can pass arguments which can be referred to by
code you type into the individual widgets.
<P>If the function contains any unnamed windows, it will be declared as
returning an Fl_Window*. The unnamed window will be returned from it
(more than one unnamed window is useless). If the function contains
only named windows it will be declared as returning void. </P>
<P>It is possible to make the .cxx output be a self-contained program
that can be compiled and executed. This is done by deleting the
function name, in which case &quot;main(argc,argv)&quot; is used. The function
will call show() on all the windows it creates and then call Fl::run().
This can be used to test resize behavior or other parts of the user
interface. I'm not sure if it is possible to create really useful
programs using just FLUID. </P>
<P>You can change the function name by double clicking the function. </P>
<P>If the function contains any unnamed windows, it will be declared
as returning a Fl_Window pointer. The unnamed window will be returned
from it (more than one unnamed window is useless). If the function
contains only named windows, it will be declared as returning nothing
(<tt>void</tt>). </P>
<P>It is possible to make the <TT>.cxx</TT> output be a self-contained
program that can be compiled and executed. This is done by deleting
the function name so <tt>main(argc,argv)</tt> is used. The function
will call <tt>show()</tt> on all the windows it creates and then call
<tt>Fl::run()</tt>. This can also be used to test resize behavior or
other parts of the user interface.</P>
<P>You can change the function name by double-clicking on the function. </P>
<H3>New/Window</H3>
Create a new Fl_Window. It is added to the currently selected
function, or to the function containing the currently selected item.
The window will appear, sized to 100x100. You will want to resize it
to whatever size you require.
<P>You also get the window's control panel, which is almost exactly the
same as any other Fl_Widget, and is described in the next chapter. </P>
Creates a new <tt>Fl_Window</tt> widget. The window is added to the
currently selected function, or to the function containing the
currently selected item. The window will appear, sized to 100x100.
You can resize it to whatever size you require.
<P>The widget panel will also appear and is described later in this
chapter.</P>
<H3>New/...</H3>
All other items on the New menu are subclasses of Fl_Widget. Creating
All other items on the New menu are subclasses of <tt>Fl_Widget</tt>. Creating
them will add them to the currently selected group or window, or the
group or window containing the currently selected widget. The initial
dimensions and position are chosen by copying the current widget, if
possible.
<P>When you create the widget you will get the widget's control panel,
described in the next chapter. </P>
which is described later in this chapter. </P>
<H3>Help/About FLUID</H3>
Pops up a panel showing the version of FLUID.
<H3>Help/Manual</H3>
Not yet implemented. Use a HTML or PDF file viewer to read these
pages instead.
Pops up a panel showing the version of FLUID.
<H2>The Widget Panel</H2>
<TABLE cellpadding=0 cellspacing=0>
<TR><TD>When you double-click a widget or a set of widgets you will get
<TR><TD>When you double-click on a widget or a set of widgets you will get
the &quot;widget attribute panel&quot;.
<P>When you change attributes using this panel, the changes are
reflected immediately in the window. It is useful to hit the &quot;no
overlay&quot; button (or type Alt+o) to hide the red overlay so you can see
overlay&quot; button (or type Alt+Shift+O) to hide the red overlay so you can see
the widgets more accurately, especially when setting the box type. </P>
<P>If you have several widgets selected, they may have different values
for the fields. In this case the value for <I>one</I> of the widgets
is shown. But if you change this value, <I>all</I> the selected
is shown. But if you change this value, <I>all</I> of the selected
widgets are changed to the new value. </P>
<P>Hitting &quot;OK&quot; makes the changes permanent. Selecting a different
widget also makes the changes permanent. FLUID checks for simple
syntax errors in any code (such as mismatched parenthesis) before
syntax errors such as mismatched parenthesis in any code before
saving any text. </P>
</TD><TD><IMG src=./fluid_widget.gif width=225></TD></TR>
</TABLE>
&quot;Revert&quot; or &quot;Cancel&quot; put everything back to when you last brought up
the panel or hit OK. However in the current version of FLUID, changes
to &quot;visible&quot; attributes (such as the color, label, box) are not undone
by revert or cancel. Changes to code like the callbacks is undone,
by revert or cancel. Changes to code like the callbacks are undone,
however. <A name=widget_attributes>
<H2>Widget Attributes</H2>
<H3>Name (text field)</H3>
Name of a global C variable to declare, and to store a pointer to this
Name of a variable to declare, and to store a pointer to this
widget into. This variable will be of type &quot;&lt;class&gt;*&quot;. If the name is
blank then no variable is created.
<P>You can name several widgets with &quot;name[0]&quot;, &quot;name[1]&quot;, &quot;name[2]&quot;,
@ -349,12 +355,12 @@ You pick the subtype off of this menu.
<P>Many widgets will work, and draw faster, with a &quot;frame&quot; instead of a
&quot;box&quot;. A frame does not draw the colored interior, leaving whatever
was already there visible. Be careful, as FLUID may draw this ok but
the real program leave unwanted stuff inside the widget. </P>
the real program may leave unwanted stuff inside the widget. </P>
<P>If a window is filled with child widgets, you can speed up redrawing
by changing the window's box type to &quot;NO_BOX&quot;. FLUID will display a
checkerboard for any areas that are not colored in by boxes (notice
that this checkerboard is not drawn by the resulting program, instead
random garbage is left there). </P>
checkerboard for any areas that are not colored in by boxes. Note
that this checkerboard is not drawn by the resulting program. Instead
random garbage will be displayed.</P>
<H3>Color</H3>
<P>The color to draw the box with. </P>
<H3>Color2</H3>
@ -363,118 +369,119 @@ always show the result of this: this is the color buttons draw in when
pushed down, and the color of input fields when they have the focus. </P>
<H3>Label</H3>
String to print next to or inside the button.
<P>You can put newlines into the string to make multiple lines, the
easiest way is by typing ctrl+j. </P>
<P>You can put newlines into the string to make multiple lines. The
easiest way is by typing Ctrl+j. </P>
<H3>Label style (pull down menu)</H3>
How to draw the label. Normal, shadowned, engraved, and embossed
How to draw the label. Normal, shadowed, engraved, and embossed
change the appearance of the text. &quot;symbol&quot; requires the label to
start with an '@' sign to draw a named <A href=Labeltypes.html#symbols>
symbol</A>.
<P>From this menu you can also pick <A href=drawing.html#images>
&quot;Image...&quot;</A>. This lets you use the contents of an image file
(currently an xpm pixmap or xbm bitmap) to label the widget. </P>
<H3>Label alignement (buttons)</H3>
&quot;Image...&quot;</A>. This lets you use the contents of a GIF, XPM, or
XBM image file to label the widget. </P>
<H3>Label Alignment (Buttons)</H3>
Where to draw the label. The arrows put it on that side of the
widget, you can combine the to put it in the corner. The &quot;box&quot; button
puts the label inside the widget, rather than outside.
<H3>Label font</H3>
<H3>Label Font</H3>
Font to draw the label in. Ignored by symbols, bitmaps, and pixmaps.
Your program can change the actual font used by these &quot;slots&quot;, in case
Your program can change the actual font used by these &quot;slots&quot; in case
you want some font other than the 16 provided.
<H3>Label size</H3>
Point size for the font to draw the label in. Ignored by symbols,
<H3>Label Size</H3>
Pixel size (height) for the font to draw the label in. Ignored by symbols,
bitmaps, and pixmaps. To see the result without dismissing the panel,
type the new number and then Tab.
<H3>Label color</H3>
Color to draw the label. Ignored by pixmaps (bitmaps, however, do use
<H3>Label Color</H3>
Color to draw the label. Ignored by pixmaps (bitmaps, however, do use
this color as the foreground color).
<H3>Text font, size, color</H3>
Some widgets display text, such as input fields, pull-down menus,
browsers. You can change this here.
<H3>Text Font, Size, and Color</H3>
Some widgets display text, such as input fields, pull-down menus, and
browsers.
<H3>Visible</H3>
If you turn this off the widget is hidden initially. Don't change
If you turn this off then the widget is hidden initially. Don't change
this for windows or for the immediate children of a Tabs group.
<H3>Active</H3>
If you turn this off the widget is deactivated initially. Currently
no FLTK widgets display the fact that they are inactive (like by
graying out), but this may change in the future.
If you turn this off then the widget is deactivated initially.
<H3>Resizable</H3>
If a window is resizable or has an immediate child that is resizable,
If a window is resizable or has an immediate child that is resizable,
then the user will be able to resize it. In addition all the size
changes of a window or group will go &quot;into&quot; the resizable child. If
you have a large data display surrounded by buttons, you probably want
that data area to be resizable.
<P>Only one child can be resizable. Turning this on turns it off for
other children. </P>
the other children. </P>
<P>You can get more complex behavior by making invisible boxes the
resizable widget, or by using hierarchies of groups. Unfortunatley the
resizable widget, or by using hierarchies of groups. Unfortunately the
only way to test it is to compile the program. Resizing the FLUID
window is <I>not</I> the same as what will happen in the user program. </P>
<H3>Hotspot</H3>
Each window may have exactly one hotspot (turning this on will turn
off any others). This will cause it to be positioned with that widget
centered on the mouse. This position is determined <I>when the FLUID
function is called, so you should call it immediately before showing
the window</I>. If you want the window to hide and then reappear at a
function is called</I>, so you should call it immediately before showing
the window. If you want the window to hide and then reappear at a
new position, you should have your program set the hotspot itself just
before show().
<H3>subclass</H3>
This is how you put your own subclasses of Fl_Widget in. Whatever
before <tt>show()</tt>.
<H3>Subclass</H3>
This is how you use your own subclasses of <tt>Fl_Widget</tt>. Whatever
identifier you type in here will be the class that is instantiated.
<P>In addition, no #include header file is put in the .h file. You
must provide a #include line as the first of the &quot;extrawhich declares
your subclass. </P>
<P>The class had better be similar to the class you are spoofing. It
<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 &quot;Extra
Code&quot; which declares your subclass. </P>
<P>The class must be similar to the class you are spoofing. It
does not have to be a subclass. It is sometimes useful to change this
to another FLTK class: currently the only way to get a double-buffered
to another FLTK class. Currently the only way to get a double-buffered
window is to change this field for the window to &quot;Fl_Double_Window&quot; and
to add &quot;#include &lt;FL/Fl_Double_Window.h&gt;&quot; to the extra code. </P>
<H3>Extra code</H3>
These four fields let you type in literal lines of code to dump into
the .h or .cxx files.
<P>If the text starts with a '#' or the word &quot;extern&quot; then FLUID thinks
this is an &quot;include&quot; line, and it is written to the .h file. If the
<H3>Extra Code</H3>
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 <tt>extern</tt> then FLUID thinks
this is an &quot;include&quot; line, and it is written to the <TT>.h</TT> file. If the
same include line occurs several times then only one copy is written. </P>
<P>All other lines are &quot;code&quot; lines. The widget being constructed is
pointed to by the local variable 'o'. The window being constructed is
pointed to by the local variable 'w'. You can also access any
<P>All other lines are &quot;code&quot; lines. The current widget is
pointed to by the local variable <tt>o</tt>. The window being constructed is
pointed to by the local variable <tt>w</tt>. You can also access any
arguments passed to the function here, and any named widgets that are
before this one. </P>
<P>FLUID will check for matching parenthesis, braces, and quotes, but
does not do much other error checking. Be careful here, as it may be
hard to figure out what widget is producing an error in the compiler.
If you need more than 4 lines you probably should call a function in
your own .cxx code. </P>
If you need more than four lines you probably should call a function in
your own <TT>.cxx</TT> code. </P>
<H3>Callback</H3>
This can either be the name of a function, or a small snippet of code.
FLUID thinks that if there is any punctuation then it is code.
This can either be the name of a function, or a small snippet of code.
If you enter anything but letters, numbers, and the underscore then FLUID
treats it as code.
<P>A name names a function in your own code. It must be declared as
&quot;voidname&gt;(&lt;class&gt;*,void*)&quot;. </P>
<P>A code snippet is inserted into a static function in the .cxx output
file. The function prototype is &quot;voidclass&gt;*so you can refer to the
widget as 'o' and the user_data as 'v'. FLUID will check for matching
parenthesis, braces, and quotes, but does not do much other error
checking. Be careful here, as it may be hard to figure out what widget
is producing an error in the compiler. </P>
<tt>void name(&lt;class&gt;*,void*)</tt>. </P>
<P>A code snippet is inserted into a static function in the
<TT>.cxx</TT> output file. The function prototype is <tt>void
name(class *o, void *v)</tt> so that you can refer to the widget as
<tt>o</tt> and the <tt>user_data()</tt> as <tt>v</tt>. FLUID will
check for matching parenthesis, braces, and quotes, but does not do
much other error checking. Be careful here, as it may be hard to
figure out what widget is producing an error in the compiler. </P>
<P>If the callback is blank then no callback is set. </P>
<H3>user_data</H3>
<P>This is a value for the user_data() of the widget. If blank the
<P>This is a value for the <tt>user_data()</tt> of the widget. If blank the
default value of zero is used. This can be any piece of C code that
can be put &quot;(void*)(&lt;here&gt;)&quot;. </P>
<H3>User data type</H3>
The &quot;void*&quot; in the callback function prototypes is replaced with this.
You may want to use &quot;long&quot; for old XForms code. Be warned that
anything other than &quot;void*&quot; is not guaranteed to work by the C++ spec!
However on most architectures other pointer types are ok, and long is
usually ok.
can be cast to a <tt>void</tt> pointer.</P>
<H3>User Data Type</H3>
The <tt>void *</tt> in the callback function prototypes is replaced with this.
You may want to use <tt>long</tt> for old XForms code. Be warned that
anything other than <tt>void *</tt> is not guaranteed to work!
However on most architectures other pointer types are ok, and <tt>long</tt> is
usually ok, too.
<H3>When</H3>
When to do the callback. Can be &quot;never&quot;, &quot;changed&quot;, &quot;release&quot;. The
When to do the callback. This can be &quot;never&quot;, &quot;changed&quot;,
&quot;release&quot;, &quot;enter key&quot;, or &quot;no change&quot;. The
value of &quot;enter key&quot; is only useful for text input fields. The &quot;no
change&quot; button means the callback is done on the matching event even if
the data is not changed.
<P>There are rare but useful other values for the when() field that are
<P>There are other rare but useful values for the <tt>when()</tt> field that are
not in the menu. You should use the extra code fields to put these
values in. <A name=windows></P>
values in.</P>
<H2>Selecting Moving Widgets</H2>
<P>Double-clicking a window name in the browser will display it, if not
displayed yet. From this display you can select widgets, sets of
@ -530,15 +537,15 @@ up a file chooser from which you pick the image file. If an image has
already been chosen, you can change the image used by picking
&quot;Image...&quot; again. The name of the image will appear in the &quot;label&quot;
field, but you can't edit it. </P>
<P>The <I>contents</I> of the image file are written to the .cxx file,
so if you wish to distribute the C code, you only need to copy the .cxx
<P>The <I>contents</I> of the image file are written to the <TT>.cxx</TT> file,
so if you wish to distribute the C code, you only need to copy the <TT>.cxx</TT>
file, not the images. If many widgets share the same image then only
one copy is written. </P>
<P>However the <I>file name</I> is stored in the .fl file, so to read
the .fl file you need the image files as well. Filenames are relative
to the location the .fl file is (not necessarily the current
<P>However the <I>file name</I> is stored in the <TT>.fl</TT> file, so to read
the <TT>.fl</TT> file you need the image files as well. Filenames are relative
to the location the <TT>.fl</TT> file is (not necessarily the current
directory). I recommend you either put the images in the same
directory as the .fl file, or use absolute path names. </P>
directory as the <TT>.fl</TT> file, or use absolute path names. </P>
<H3>Notes for all image types</H3>
<P>FLUID runs using the default visual of your X server. This may be 8
bits, which will give you dithered images. You may get better results
@ -598,4 +605,4 @@ as for xpm files. Notice that the conversion removes the compression,
so the code may be much bigger than the .gif file. Only the first
image of an animated gif file is used. </P>
<P>Behavior and performance with large .gif files is not guaranteed! </P>
</A></A></BODY></HTML>
</A></A></BODY></HTML>

BIN
documentation/fluid_prefs.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

30
documentation/intro.html
View File

@ -95,7 +95,7 @@ terms of the <A href=#licensing>GNU Library General Public License</A>.
Contrary to popular belief, it can be used in commercial software!
(Even Bill Gates could use it.)
<H2>What Does &quot;FLTK&quot; Mean?</H2>
FLTK was originally designed to be compatable with the Forms Library
FLTK was originally designed to be compatible with the Forms Library
written for SGI machines. In that library all the functions and
structures started with &quot;fl_&quot;. This naming was extended to all new
methods and widgets in the C++ library, and this prefix was taken as
@ -110,8 +110,30 @@ Kit&quot;.
the default of no options and then compile everything.
<P>FLTK uses GNU autoconf to configure itself for your UNIX platform.
The main things that the configure script will look for are the X11,
OpenGL (or Mesa), and JPEG header and library files. Make sure that
they are in the standard include/library locations. </P>
OpenGL (or Mesa), and JPEG header and library files. If these cannot be
found in the standard include/library locations you'll need to define the
<tt>CFLAGS</tt>, <tt>CXXFLAGS</tt>, and <tt>LDFLAGS</tt> environment
variables. For the Bourne and Korn shells you'd use:</P>
<UL><PRE>
CFLAGS=-I<I>includedir</I>; export CFLAGS
CXXFLAGS=-I<I>includedir</I>; export CXXFLAGS
LDFLAGS=-L<I>libdir</I>; export LDFLAGS
</PRE></UL>
For C shell and tcsh, use:
<UL><PRE>
setenv CFLAGS "-I<I>includedir</I>"
setenv CXXFLAGS "-I<I>includedir</I>"
setenv LDFLAGS "-L<I>libdir</I>"
</PRE></UL>
By default configure will look for a C++ compiler named <tt>CC</tt>, <tt>c++</tt>,
<tt>g++</tt>, or <tt>gcc</tt> in that order. To use another compiler you need
to set the <tt>CXX</tt> environment variable:
<UL><PRE>
CXX=xlC; export xlC
setenv CXX "xlC"
</PRE></UL>
The <tt>CC</tt> environment variable can also be used to override the default
C compiler, which is used for a few FLTK source files.
<P>You can run configure yourself to get the exact setup you need. Type
&quot;./configure &lt;options&gt;&quot;, where options are: </P>
<DL>
@ -184,7 +206,7 @@ reporting bugs]</DD>
</DL>
To send a message to the FLTK mailing list (&quot;fltk@easysw.com&quot;) you
must first join the list. Non-member submissions are blocked to avoid
problems with SPAM...
problems with unsolicited email.
<P>To join the FLTK mailing list, send a message to
&quot;majordomo@easysw.com&quot; with &quot;subscribe fltk&quot; in the message body. A
digest of this list is available by subscribing to the &quot;fltk-digest&quot;

73
documentation/opengl.html
View File

@ -2,16 +2,16 @@
<H1 ALIGN=RIGHT><A NAME=opengl>9 - Using OpenGL</A></H1>
This chapter discusses using FLTK for your OpenGL applications.
<H2>Using OpenGL in FLTK</H2>
The easiest way to make an OpenGL display is to subclass <A href=Fl_Gl_Window.html#Fl_Gl_Window>
The easiest way to make an OpenGL display is to subclass <A href=Fl_Gl_Window.html#Fl_Gl_Window>
<TT>Fl_Gl_Window</TT></A>. Your subclass must implement a <TT>draw()</TT>
method which uses OpenGL calls to draw the display. Your main program
method which uses OpenGL calls to draw the display. Your main program
should call <TT>redraw()</TT> when the display needs to change, and
(somewhat later) FLTK will call <TT>draw()</TT>.
<P>With a bit of care you can also use OpenGL to draw into normal FLTK
windows. This is mostly useful because you can use Gourand shading for
windows. This allows you to use Gouraud shading for
drawing your widgets. To do this you use the <A href=#gl_start><TT>
gl_start()</TT></A> and <A href=#gl_finish><TT>gl_finish()</TT></A>
functions around your OpenGL code. </P>
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 some extra drawing
functions provided by FLTK, and include the <TT>&lt;windows.h&gt;</TT> header
@ -25,7 +25,7 @@ file needed by WIN32 applications. </P>
user). </LI>
</UL>
<H3>Defining the Subclass</H3>
To define the subclass you just subclass <TT>Fl_Gl_Window</TT> class:
To define the subclass you just subclass the <TT>Fl_Gl_Window</TT> class:
<UL>
<PRE>
class MyWindow : public Fl_Gl_Window {
@ -81,6 +81,10 @@ int MyWindow::handle(int event) {
... keypress, key is in Fl::event_key(), ascii in Fl::event_text()
... Return 1 if you understand/use the keyboard event, 0 otherwise...
return 1;
case FL_SHORTCUT:
... shortcut, key is in Fl::event_key(), ascii in Fl::event_text()
... Return 1 if you understand/use the shortcut event, 0 otherwise...
return 1;
default:
// tell FLTK that I don't understand other events
return 0;
@ -88,11 +92,11 @@ int MyWindow::handle(int event) {
}
</PRE>
</UL>
When <TT>handle()</TT> is called, the OpenGL context is not set up!
If your display changes, you should call <TT>redraw()</TT> and let <TT>
When <TT>handle()</TT> is called, the OpenGL context is not set up!
If your display changes, you should call <TT>redraw()</TT> and let <TT>
draw()</TT> do the work. Don't call any OpenGL drawing functions from
inside <TT>handle()</TT>!
<P>You can call some OpenGL stuff like hit detection and texture
<P>You can call <I>some</I> OpenGL stuff like hit detection and texture
loading functions by doing: </P>
<UL>
<PRE>
@ -106,25 +110,25 @@ loading functions by doing: </P>
detection, loading textures, etc...
</PRE>
</UL>
Your main program can now create one of your windows by doing <TT>new
MyWindow(...)</TT>. You can also use <A href=fluid.html#fluid>fluid</A>
by:
Your main program can now create one of your windows by doing <TT>new
MyWindow(...)</TT>. You can also use <A href=FLUID.html#FLUID>FLUID</A>
by:
<OL>
<LI>Put your class definition in a MyWindow.H file. </LI>
<LI>In fluid create a box object, resize place where you want. </LI>
<LI>In the control panel, fill in the &quot;class&quot; field with MyWindow.H.
This will make fluid produce constructors for your new class. </LI>
<LI>In the &quot;extra code&quot; put <TT>#include &quot;MyWindow.H&quot;</TT>, so that
the fluid output file will compile. </LI>
<LI>Putting your class definition in a <tt>MyWindow.H</tt> file. </LI>
<LI>Creating a <tt>Fl_Box</tt> widget in FLUID.</LI>
<LI>In the widget panel fill in the &quot;class&quot; 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 file will compile. </LI>
</OL>
You must put <TT>glwindow-&gt;show()</TT> in your main code after calling <TT>
You must put <TT>glwindow-&gt;show()</TT> in your main code after calling <TT>
show()</TT> on the window containing the OpenGL window.
<H2>Using OpenGL in Normal FLTK Windows</H2>
You can put OpenGL code into an <A href=#draw><TT>Fl_Widget::draw()</TT>
You can put OpenGL code into an <A href=#draw><TT>Fl_Widget::draw()</TT>
</A> method or into the code for a <A href=common.html#boxtypes>boxtype</A>
or other places with some care.
<P>Most important, before you show <I>any</I> windows (including those
that don't have OpenGL drawing) you must initialize FLTK so that it
or other places with some 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> to describe how you intend to use OpenGL: </P>
@ -133,7 +137,7 @@ Fl_Gl_Window::mode()</TT></A> to describe how you intend to use OpenGL: </P>
Fl::gl_visual(FL_RGB);
</PRE>
</UL>
You can then put OpenGL drawing code anywhere you can draw normally by
You can then put OpenGL drawing code anywhere you can draw normally by
surrounding it with:
<UL>
<PRE>
@ -153,7 +157,7 @@ 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 get the
drawable height so you can flip the Y coordinates. </P>
drawable height so that you can flip the Y coordinates. </P>
<P>Unfortunately, there are a bunch of limitations you must adhere to
for maximum portability: </P>
<UL>
@ -163,24 +167,25 @@ for maximum portability: </P>
<LI>You cannot use <TT>Fl_Double_Window</TT> or <TT>Fl_Overlay_Window</TT>
. </LI>
</UL>
Do <I>not</I> call <TT>gl_start()</TT> or <TT>gl_finish()</TT> when
Do <I>not</I> call <TT>gl_start()</TT> or <TT>gl_finish()</TT> when
drawing into an <TT>Fl_Gl_Window</TT>!
<H2>OpenGL drawing functions</H2>
FLTK provides some useful OpenGL drawing functions. They can be
<H2>OpenGL Drawing Functions</H2>
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>).
<H3>void gl_color(Fl_Color)</H3>
Set the current color to a FLTK color index. <I>For color-index modes
Set the current color to a FLTK color. <I>For color-index modes
it will use <TT>fl_xpixel(c)</TT>, which is only right if this window
uses the default colormap!</I>
<H3>void gl_rect(int x, int y, int w, int h)
<BR> void gl_rectf(int x, int y, int w, int h)</H3>
Outline or fill a rectangle with the current color. If <TT>ortho()</TT>
has been called, then the rectangle will exactly fill the pixel
Outline or fill 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.
<H3>void gl_font(Fl_Font fontid, int size)</H3>
Set the &quot;current OpenGL font&quot; to the same font you get by calling <A href=drawing.html#fl_font>
Set the current OpenGL font to the same font you get by calling <A href=drawing.html#fl_font>
<TT>fl_font()</TT></A>.
<H3>int gl_height()
<BR> int gl_descent()
@ -190,8 +195,8 @@ rectangle passed.
Return information about the current OpenGL font.
<H3>void gl_draw(const char *)
<BR> void gl_draw(const char *, int n)</H3>
Draw a nul-terminated string or an array of <TT>n</TT> characters in
the current OpenGL font at the current <TT>glRasterPos</TT>.
Draw a nul-terminated string or an array of <TT>n</TT> characters in
the current OpenGL font at the current raster position.
<H3>void gl_draw(const char *, int x, int y)
<BR> void gl_draw(const char *, int n, int x, int y)
<BR> void gl_draw(const char *, float x, float y)
@ -299,4 +304,4 @@ void OptimizerWindow::draw() {
<H3>The scene() Method</H3>
The <TT>scene()</TT> method sets the scene to be drawn. The scene is
a collection of 3D objects in a <TT>csGroup</TT>. The scene is redrawn
after this call. </BODY></HTML>
after this call. </BODY></HTML>

6
documentation/preface.html
View File

@ -1,11 +1,11 @@
<HTML>
<HEAD><META CONTENT="Michael Sweet" NAME=Author><META CONTENT="Copyright 1998-1999 by Bill Spitzak and Others."
NAME=Copyright><META CONTENT="Revision 1" NAME=DocNumber>
<HEAD><META CONTENT="Written by Michael Sweet and Bill Spitzak" NAME=Author><META CONTENT="Copyright 1998-1999 by Bill Spitzak and Others."
NAME=Copyright><META CONTENT="Revision 2" NAME=DocNumber>
<TITLE>FLTK 1.0 Programming Manual</TITLE>
</HEAD>
<BODY>
<H1 ALIGN=RIGHT><A NAME=preface>Preface</A></H1>
This manual describes the Fast Light Tool Kit (&quot;FLTK&quot;) version 1.0, a
This manual describes the Fast Light Tool Kit (&quot;FLTK&quot;) version 1.0, a
C++ Graphical User Interface (&quot;GUI&quot;) toolkit for UNIX and Microsoft
Windows. Each of the chapters in this manual is designed as a tutorial
for using FLTK, while the appendices provide a convenient reference for

99
documentation/subclassing.html
View File

@ -5,12 +5,12 @@ widgets in FLTK.
<H2>Subclassing</H2>
New widgets are created by <I>subclassing</I> an existing FLTK widget,
typically <TT>Fl_Widget</TT> for controls and <TT>Fl_Group</TT> for
containers.
composite widgets.
<P>A control widget typically interacts with the user to receive and/or
display a value of some sort. </P>
<P>A container widget holds a list of child widgets and handles moving,
<P>A composite widget widget holds a list of child widgets and handles moving,
sizing, showing, or hiding them as needed. <TT>Fl_Group</TT> is the
main container widget class in FLTK, and all of the other containers (<TT>
main composite widget widget class in FLTK, and all of the other composite widgets (<TT>
Fl_Pack</TT>, <TT>Fl_Scroll</TT>, <TT>Fl_Tabs</TT>, <TT>Fl_Tile</TT>,
and <TT>Fl_Window</TT>) are subclasses of it. </P>
<P>You can also subclass other existing widgets to provide a different
@ -23,13 +23,13 @@ the face of the button. </P>
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 access the following arguments:
The constructor should have the following arguments:
<UL>
<PRE>
MyClass(int x, int y, int w, int h, const char *label = 0);
</PRE>
</UL>
This will allow the class to be used in <A href=fluid.html#fluid>Fluid</A>
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>
@ -41,8 +41,8 @@ MyClass::MyClass(int x, int y, int w, int h, const char *label)
}
</PRE>
</UL>
<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
<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>
@ -62,14 +62,14 @@ flags(ACTIVE|VISIBLE);
<H2>Protected Methods of Fl_Widget</H2>
The following methods are provided for subclasses to use:
<UL>
<LI><A name=#clear_visible>clear_visible</A></LI>
<LI><A name=#damage>damage</A></LI>
<LI><A name=#draw_box>draw_box</A></LI>
<LI><A name=#draw_label>draw_label</A></LI>
<LI><A name=#set_flag>set_flag</A></LI>
<LI><A name=#set_visible>set_visible</A></LI>
<LI><A name=#test_shortcut>test_shortcut</A></LI>
<LI><A name=#type>type</A></LI>
<LI><A href=#clear_visible><TT>Fl_Widget::clear_visible</TT></A></LI>
<LI><A href=#damage><TT>Fl_Widget::damage</TT></A></LI>
<LI><A href=#draw_box><TT>Fl_Widget::draw_box</TT></A></LI>
<LI><A href=#draw_label><TT>Fl_Widget::draw_label</TT></A></LI>
<LI><A href=#set_flag><TT>Fl_Widget::set_flag</TT></A></LI>
<LI><A href=#set_visible><TT>Fl_Widget::set_visible</TT></A></LI>
<LI><A href=#test_shortcut><TT>Fl_Widget::test_shortcut</TT></A></LI>
<LI><A href=#type><TT>Fl_Widget::type</TT></A></LI>
</UL>
<H3><A name=damage>void Fl_Widget::damage(uchar mask)
<BR> void Fl_Widget::damage(uchar mask, int x, int y, int w, int h)
@ -84,9 +84,31 @@ your widget can call the private <TT>damage(n)</TT>.
calls are done in a window (no calls to <TT>damage(n)</TT>) then FLTK
will clip to the union of all these calls before drawing anything.
This can greatly speed up incremental displays. The mask bits are
or'd into <TT>damage()</TT> unless this is a <TT>Fl_Window</TT> widget. </P>
OR'd into <TT>damage()</TT> unless this is a <TT>Fl_Window</TT> widget. </P>
<P>The third form returns the bitwise-OR of all <TT>damage(n)</TT>
calls done since the last <TT>draw()</TT>.</P>
<P><I>When redrawing your widgets you should look at the damage bits to
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>
MyClass::handle(int event) {
...
if (change_to_part1) damage(1);
if (change_to_part2) damage(2);
if (change_to_part3) damage(4);
}
MyClass::draw() {
if (damage() & FL_DAMAGE_ALL) {
... draw frame/box and other static stuff ...
}
if (damage() & (FL_DAMAGE_ALL | 1)) draw_part1();
if (damage() & (FL_DAMAGE_ALL | 2)) draw_part2();
if (damage() & (FL_DAMAGE_ALL | 4)) draw_part3();
}
</PRE></UL>
<H3><A name=draw_box>void Fl_Widget::draw_box() const
<BR></A>void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const</H3>
The first form draws this widget's <TT>box()</TT>, using the
@ -102,15 +124,14 @@ to be outside the box (on the assumption that the enclosing group will
draw those labels).
<P>The second form uses the passed bounding box instead of the widget's
bounding box. This is useful so &quot;centered&quot; labels are aligned with some
feature, such as a moving slider. </P>
feature, like a moving slider. </P>
<P>The third form draws the label anywhere. It acts as though <TT>
FL_ALIGN_INSIDE</TT> has been forced on, the label will appear inside
FL_ALIGN_INSIDE</TT> has been forced on so the label will appear inside
the passed bounding box. This is designed for parent groups to draw
labels with. </P>
<H3><A name=set_flag>void Fl_Widget::set_flag(SHORTCUT_LABEL)</A></H3>
If your constructor calls this it modifies <TT>draw_label()</TT> so
that '&amp;' characters cause an underscore to be printed under the next
letter.
Modifies <TT>draw_label()</TT> so that '&amp;' characters cause an underscore
to be printed under the next letter.
<H3><A name=set_visible>void Fl_Widget::set_visible()</A>
<BR><A name=clear_visible>void Fl_Widget::clear_visible()</A></H3>
Fast inline versions of <TT>Fl_Widget::hide()</TT> and <TT>
@ -137,7 +158,7 @@ to not interfere with reserved values.
portability. But this may change in the near future if RTTI becomes
standard everywhere. </P>
<P>If you don't have RTTI you can use the clumsy FLTK mechanisim, by
having <TT>type()</TT> have a unique value. These unique values must
having <TT>type()</TT> use a unique value. These unique values must
be greater than the symbol <TT>FL_RESERVED_TYPE</TT> (which is 100).
Look through the header files for <TT>FL_RESERVED_TYPE</TT> to find an
unused number. If you make a subclass of <TT>Fl_Window</TT>
@ -215,13 +236,13 @@ be called from non-drawing code.
calls to this widget since it was last drawn. This can be used for
minimal update, by only redrawing the parts whose bits are set. FLTK
will turn on the <TT>FL_DAMAGE_ALL</TT> bit if it thinks the entire widget
must be redrawn (for instance due to an expose event). </P>
must be redrawn (e.g. for an expose event). </P>
<P>Expose events (and the above <TT>damage(b,x,y,w,h)</TT>) will cause <TT>
draw()</TT> to be called with FLTK's <A href=drawing.html#clipping>
clipping</A> turned on. You can greatly speed up redrawing in some
cases by testing <TT>fl_clipped</TT> and <TT>fl_current_clip</TT> and
skipping invisible parts. </P>
<P>Besides the protected methods described above, FLTK provide a large
<P>Besides the protected methods described above, FLTK provides a large
number of basic drawing functions, which are described <A href=drawing.html#drawing>
below</A>. </P>
<H2>Resizing the Widget</H2>
@ -232,12 +253,12 @@ and <TT>h()</TT> still remain the old size. You must call <TT>resize()</TT>
on your base class with the same arguments to get the widget size to
actually change.
<P>This should <I>not</I> call <TT>redraw()</TT>, at least if only the <TT>
x()</TT> and <TT>y()</TT> change. This is because group objects like <A href=Fl_Scroll.html#Fl_Scroll>
x()</TT> and <TT>y()</TT> change. This is because composite widgets like <A href=Fl_Scroll.html#Fl_Scroll>
<TT>Fl_Scroll</TT></A> may have a more efficient way of drawing the new
position. </P>
<H2>Making a Composite/Group Widget</H2>
A &quot;composite&quot; widget contains one or more &quot;child&quot; widgets. To do this
you should subclass <A href=Fl_Group.html#Fl_Group><TT>Fl_Group</TT></A>
<H2>Making a Composite Widget</H2>
A &quot;composite&quot; widget contains one or more &quot;child&quot; widgets.
To make a composite widget you should subclass <A href=Fl_Group.html#Fl_Group><TT>Fl_Group</TT></A>
. It is possible to make a composite object that is not a subclass of <TT>
Fl_Group</TT>, but you'll have to duplicate the code in <TT>Fl_Group</TT>
anyways.
@ -335,7 +356,7 @@ Fl_Group::draw_outside_label(Fl_Widget&amp;) const</A></H3>
draw_label()</TT></A>. If you want more control over the label
positions you might want to call <TT>child-&gt;draw_label(x,y,w,h,a)</TT>.
<H3><A name=update_child>void Fl_Group::update_child(Fl_Widget&amp;)</A></H3>
Draws the child only if it's <TT>damage()</TT> is non-zero. You
Draws the child only if its <TT>damage()</TT> is non-zero. You
should call this on all the children if your own damage is equal to
FL_DAMAGE_CHILD. Nothing is done if the child is not <TT>visible()</TT>
or if it is clipped.
@ -343,10 +364,10 @@ FL_DAMAGE_CHILD. Nothing is done if the child is not <TT>visible()</TT>
FLTK provides routines to cut and paste ASCII text (in the future this
may be UTF-8) between applications:
<UL>
<LI><A href=functions.html#paste>Fl::paste</A></LI>
<LI><A href=functions.html#selection>Fl::selection</A></LI>
<LI><A href=#selection_length>Fl::selection_length</A></LI>
<LI><A href=functions.html#selection_owner>Fl::selection_owner</A></LI>
<LI><A href=functions.html#paste><TT>Fl::paste</TT></A></LI>
<LI><A href=functions.html#selection><TT>Fl::selection</TT></A></LI>
<LI><A href=#selection_length><TT>Fl::selection_length</TT></A></LI>
<LI><A href=functions.html#selection_owner><TT>Fl::selection_owner</TT></A></LI>
</UL>
It may be possible to cut/paste non-ASCII data by using <A href=osissues.html#add_handler>
<TT>Fl::add_handler()</TT></A>.
@ -354,21 +375,21 @@ may be UTF-8) between applications:
You may want your widget to be a subclass of <TT>Fl_Window</TT>. This
can be useful if your widget wants to occupy an entire window, and can
also be used to take advantage of system-provided clipping, or to work
with a library that expects a system window id to indicate where to
with a library that expects a system window ID to indicate where to
draw.
<P>Subclassing <TT>Fl_Window</TT> is almost exactly like subclassing <TT>
Fl_Widget</TT>, in fact you can easily switch a subclass back and
Fl_Widget</TT>, and in fact you can easily switch a subclass back and
forth. Watch out for the following differences: </P>
<OL>
<LI><TT>Fl_Window</TT> is a subclass of <TT>Fl_Group</TT> so <I>make
sure your constructor calls <TT>end()</TT></I> (unless you actually
want children added to your window). </LI>
<LI>When handling events and drawing, the upper-left corner is at 0,0,
not <TT>x(),y()</TT> as in other <TT>Fl_Widget</TT>s. For instance, to
not <TT>x(),y()</TT> as in other <TT>Fl_Widget</TT>'s. For instance, to
draw a box around the widget, call <TT>draw_box(0, 0, w(), h())</TT>,
rather than <TT>draw_box( x(), y(), w(), h())</TT>. </LI>
rather than <TT>draw_box(x(), y(), w(), h())</TT>. </LI>
</OL>
You may also want to subclass <TT>Fl_Window</TT> in order to get
access to different visuals or to change other attributes of the
windows. See <A href=osissues.html#osissues>Appendix F - Operating
System Issues</A> for more information. </BODY></HTML>
windows. See <A href=osissues.html#osissues>"Appendix F - Operating
System Issues"</A> for more information. </BODY></HTML>