Mirrors_UI_SDK/fltk
1
0
Fork 0
mirror of https://github.com/fltk/fltk.git synced 2026-06-07 00:55:23 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Doxygen documentation - WP12 and WP13 - first step.

Browse Source 
Converted the descriptive chapters of the html docs to doxygen format
and modified index.dox accordingly.

This checkin includes only trivial reformatting, no major rewriting.

Added a chapter "Migrating Code from FLTK 1.1 to 1.3".

All links on the main page are working now.

Todo:
  - Check doxygen error messages, rewrite pages (html tags, contents).
  - Fill the new "Migrating..." chapter.


git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6224 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Albrecht Schlosser
2008-09-13 15:55:32 +00:00
parent 054d25081a
commit 8416a4012e
19 changed files with 8456 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/basics.dox
+362
View File
@@ -0,0 +1,362 @@
/**
\page basics 2 - FLTK Basics
<P>This chapter teaches you the basics of compiling programs
that use FLTK.</P>
<H2>Writing Your First FLTK Program</H2>
<P>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.</P>
<UL>
<P><I>Listing 1 - &quot;hello.cxx&quot;</I>
<PRE>
#include &lt;FL/Fl.H&gt;
#include &lt;FL/Fl_Window.H&gt;
#include &lt;FL/Fl_Box.H&gt;
int main(int argc, char **argv) {
<A href="Fl_Window.html">Fl_Window</A> *window = new <A href="Fl_Window.html#Fl_Window.Fl_Window">Fl_Window</A>(300,180);
<A href="Fl_Box.html">Fl_Box</A> *box = new <A href="Fl_Box.html#Fl_Box.Fl_Box">Fl_Box</A>(20,40,260,100,&quot;Hello, World!&quot;);
box-&gt;<A href="Fl_Widget.html#Fl_Widget.box">box</A>(<A href="common.html#boxtypes">FL_UP_BOX</A>);
box-&gt;<A href="Fl_Widget.html#Fl_Widget.labelsize">labelsize</A>(36);
box-&gt;<A href="Fl_Widget.html#Fl_Widget.labelfont">labelfont</A>(<A href="drawing.html#fonts">FL_BOLD</A>+<A href="drawing.html#fonts">FL_ITALIC</A>);
box-&gt;<A href="Fl_Widget.html#Fl_Widget.labeltype">labeltype</A>(<A href="common.html#labels">FL_SHADOW_LABEL</A>);
window-&gt;<A href="Fl_Group.html#Fl_Group.end">end</A>();
window-&gt;<A href="Fl_Window.html#Fl_Window.show">show</A>(argc, argv);
return <A href="Fl.html#Fl.run">Fl::run</A>();
}
</PRE></UL>
<!-- NEED 2in -->
<P>After including the required header files, the program then creates a
window. All following widgets will automatically be children of this window.</P>
<UL><PRE>
Fl_Window *window = new <A href="Fl_Window.html#Fl_Window">Fl_Window</A>(300,180);
</PRE></UL>
<P>Then we create a box with the &quot;Hello, World!&quot; string in it. FLTK automatically adds
the new box to <tt>window</tt>, the current grouping widget.</P>
<UL><PRE>
Fl_Box *box = new <A href="Fl_Box.html#Fl_Box">Fl_Box</A>(20,40,260,100,&quot;Hello, World!&quot;);
</PRE></UL>
<P>Next, we set the type of box and the size, font, and style of the label:</P>
<UL><PRE>
box-&gt;<A href="Fl_Widget.html#Fl_Widget.box">box</A>(FL_UP_BOX);
box-&gt;<A href=Fl_Widget.html#Fl_Widget.labelsize>labelsize</A>(36);
box-&gt;<A href=Fl_Widget.html#Fl_Widget.labelfont>labelfont</A>(FL_BOLD+FL_ITALIC);
box-&gt;<A href=Fl_Widget.html#Fl_Widget.labeltype>labeltype</A>(FL_SHADOW_LABEL);
</PRE></UL>
<P>We tell FLTK that we will not add any more widgets to <tt>window</tt>.</P>
<UL><PRE>
window-&gt;<A href=Fl_Group.html#Fl_Group.end>end</A>();
</PRE></UL>
<P>Finally, we show the window and enter the FLTK event loop:</P>
<UL><PRE>
window-&gt;<A href=Fl_Window.html#Fl_Window.show>show</A>(argc, argv);
return <A href="Fl.html#Fl.run">Fl::run</A>();
</PRE></UL>
<P>The resulting program will display the window in Figure 2-1.
You can quit the program by closing the window or pressing the
<KBD>ESC</KBD>ape key.</P>
<P ALIGN="CENTER"><IMG src="hello.C.gif" alt="Hello, World! Window"><BR>
<I>Figure 2-1: The Hello, World! Window</I></P>
<H3>Creating the Widgets</H3>
<P>The widgets are created using the C++ <TT>new</TT> operator. For
most widgets the arguments to the constructor are:</P>
<UL><PRE>
Fl_Widget(x, y, width, height, label)
</PRE></UL>
<P>The <TT>x</TT> and <TT>y</TT> parameters determine where the
widget or window is placed on the screen. In FLTK the top left
corner of the window or screen is the origin (i.e. x = 0, y =
0) and the units are in pixels.</P>
<P>The <TT>width</TT> and <TT>height</TT> parameters determine
the size of the widget or window in pixels. The maximum widget
size is typically governed by the underlying window system or
hardware.</P>
<P><tt>label</tt> is a pointer to a character string to label
the widget with or <tt>NULL</tt>. If not specified the label
defaults to <tt>NULL</tt>. The label string must be in static
storage such as a string constant because FLTK does not make a
copy of it - it just uses the pointer.</P>
<H3>Creating Widget hierarchies</H3>
<P>Widgets are commonly ordered into functional groups, which
in turn may be grouped again, creating a hierarchy of widgets.
FLTK makes it easy to fill groups by automatically adding all widgets
that are created between a <tt>myGroup-&gt;begin()</tt> and
<tt>myGroup-&gt;end()</tt>. In this example, <tt>myGroup</tt>
would be the <i>current</i> group.</P>
<P>Newly created groups and their derived widgets implicitly call
<tt>begin()</tt> in the constructor, effectively adding all
subsequently created widgets to itself until <tt>end()</tt>
is called.</P>
<P>Setting the current group to <tt>NULL</tt> will stop automatic
hierarchies. New widgets can now be added manually using
<tt>Fl_Group::add(...)</tt> and <tt>Fl_Group::insert(...)</tt>.</P>
<H3>Get/Set Methods</H3>
<P><tt>box-&gt;box(FL_UP_BOX)</tt> sets the type of box the
Fl_Box draws, changing it from the default of
<tt>FL_NO_BOX</tt>, which means that no box is drawn. In our
&quot;Hello, World!&quot; example we use <TT>FL_UP_BOX</TT>,
which means that a raised button border will be drawn around
the widget. You can learn more about boxtypes in
<A href="common.html#boxtypes">Chapter 3</A>.</P>
<P>You could examine the boxtype in by doing
<tt>box-&gt;box()</tt>. FLTK uses method name overloading to make
short names for get/set methods. A "set" method is always of
the form "void&nbsp;name(type)", and a "get" method is always
of the form "type&nbsp;name()&nbsp;const".</P>
<H3>Redrawing After Changing Attributes</H3>
<P>Almost all of the set/get pairs are very fast, short inline
functions and thus very efficient. However, <i>the "set" methods
do not call <TT>redraw()</TT></i> - you have to call it
yourself. This greatly reduces code size and execution time. The
only common exceptions are <tt>value()</tt> which calls
<TT>redraw()</TT> and <tt>label()</tt> which calls
<TT>redraw_label()</TT> if necessary.</P>
<H3>Labels</H3>
<P>All widgets support labels. In the case of window widgets,
the label is used for the label in the title bar. Our example
program calls the <A href=Fl_Widget.html#Fl_Widget.labelfont>
<TT>labelfont</TT></A>,
<A href=Fl_Widget.html#Fl_Widget.labelsize><TT> labelsize</TT></A>,
and <A href=Fl_Widget.html#Fl_Widget.labeltype><TT>labeltype</TT></A>
methods.</P>
<P>The <TT>labelfont</TT> method sets the typeface and style
that is used for the label, which for this example we are using
<TT>FL_BOLD</TT> and <TT>FL_ITALIC</TT>. You can also specify
typefaces directly. </P> <P>The <TT>labelsize</TT> method sets
the height of the font in pixels. </P> <P>The <TT>labeltype</TT>
method sets the type of label. FLTK supports normal, embossed,
and shadowed labels internally, and more types can be added as
desired.</P>
<P>A complete list of all label options can be found in
<A href="common.html#labels">Chapter 3</A>.</P>
<H3>Showing the Window</H3>
<P>The <TT>show()</TT> method shows the widget or window. For windows
you can also provide the command-line arguments to allow users to
customize the appearance, size, and position of your windows.</P>
<H3>The Main Event Loop</H3>
<P>All FLTK applications (and most GUI applications in general)
are based on a simple event processing model. User actions such
as mouse movement, button clicks, and keyboard activity generate
events that are sent to an application. The application may then
ignore the events or respond to the user, typically by redrawing
a button in the "down" position, adding the text to an input
field, and so forth.</P>
<P>FLTK also supports idle, timer, and file pseudo-events that
cause a function to be called when they occur. Idle functions
are called when no user input is present and no timers or files
need to be handled - in short, when the application is not doing
anything. Idle callbacks are often used to update a 3D display
or do other background processing.</P>
<P>Timer functions are called after a specific amount of time
has expired. They can be used to pop up a progress dialog after
a certain amount of time or do other things that need to happen
at more-or-less regular intervals. FLTK timers are not 100%
accurate, so they should not be used to measure time intervals,
for example.</P>
<P>File functions are called when data is ready to read or
write, or when an error condition occurs on a file. They are
most often used to monitor network connections (sockets) for
data-driven displays.</P>
<P>FLTK applications must periodically check
(<TT>Fl::check()</TT>) or wait (<TT>Fl::wait()</TT>) for events
or use the <A href="Fl.html#Fl.run"><TT>Fl::run()</TT></A>
method to enter a standard event processing loop. Calling
<TT>Fl::run()</TT> is equivalent to the following code:</P>
<UL><PRE>
while (Fl::wait());
</PRE></UL>
<P><TT>Fl::run()</TT> does not return until all of the windows
under FLTK control are closed by the user or your program.</P>
<H2>Compiling Programs with Standard Compilers</H2>
<P>Under UNIX (and under Microsoft Windows when using the GNU development
tools) you will probably need to tell the compiler where to find the
header files. This is usually done using the <TT>-I</TT> option:</P>
<UL><PRE>
CC -I/usr/local/include ...
gcc -I/usr/local/include ...
</PRE></UL>
<P>The <TT>fltk-config</TT> script included with FLTK can be
used to get the options that are required by your compiler:</P>
<UL><PRE>
CC `fltk-config --cxxflags` ...
</PRE></UL>
<P>Similarly, when linking your application you will need to tell the
compiler to use the FLTK library:</P>
<UL><PRE>
CC ... -L/usr/local/lib -lfltk -lXext -lX11 -lm
gcc ... -L/usr/local/lib -lfltk -lXext -lX11 -lm
</PRE></UL>
<P>Aside from the "fltk" library, there is also a "fltk_forms"
library for the XForms compatibility classes, "fltk_gl" for the
OpenGL and GLUT classes, and "fltk_images" for the image file
classes, <A
HREF="Fl_Help_Dialog.html#Fl_Help_Dialog"><CODE>Fl_Help_Dialog</CODE></A>
widget, and system icon support.
<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="10" BGCOLOR="#cccccc">
<TR>
<TD><B>Note:</B>
<P>The libraries are named "fltk.lib", "fltkgl.lib", "fltkforms.lib",
and "fltkimages.lib", respectively under Windows.
</TD>
</TR>
</TABLE></CENTER>
<P>As before, the <TT>fltk-config</TT> script included with FLTK can be
used to get the options that are required by your linker:</P>
<UL><PRE>
CC ... `fltk-config --ldflags`
</PRE></UL>
<!-- NEED 2in -->
<P>The forms, GL, and images libraries are included with the "--use-foo"
options, as follows:
<UL><PRE>
CC ... `fltk-config --use-forms --ldflags`
CC ... `fltk-config --use-gl --ldflags`
CC ... `fltk-config --use-images --ldflags`
CC ... `fltk-config --use-forms --use-gl --use-images --ldflags`
</PRE></UL>
<P>Finally, you can use the <TT>fltk-config</TT> script to
compile a single source file as a FLTK program:
<UL><PRE>
fltk-config --compile filename.cpp
fltk-config --use-forms --compile filename.cpp
fltk-config --use-gl --compile filename.cpp
fltk-config --use-images --compile filename.cpp
fltk-config --use-forms --use-gl --use-images --compile filename.cpp
</PRE></UL>
<P>Any of these will create an executable named <TT>filename</TT>.
<H2>Compiling Programs with Microsoft Visual C++</H2>
<P>In Visual C++ you will need to tell the compiler where to
find the FLTK header files. This can be done by selecting
&quot;Settings&quot; from the &quot;Project&quot; menu and then
changing the &quot;Preprocessor&quot; settings under the
&quot;C/C++&quot; tab. You will also need to add the FLTK and
WinSock (WSOCK32.LIB) libraries to the &quot;Link&quot;
settings.</P>
<P>You can build your Microsoft Windows applications as Console or
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++ 5.0 optimizer is known to cause problems with
many programs. We only recommend using the &quot;Favor Small Code&quot;
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>Naming</H2>
<P>All public symbols in FLTK start with the characters 'F' and 'L':</P>
<UL>
<LI>Functions are either <TT>Fl::foo()</TT> or
<TT>fl_foo()</TT>.</LI>
<LI>Class and type names are capitalized:
<TT>Fl_Foo</TT>.</LI>
<LI><A href="enumerations.html">Constants and
enumerations</A> are uppercase: <TT>FL_FOO</TT>.</LI>
<LI>All header files start with <TT>&lt;FL/...&gt;</TT>.
</LI>
</UL>
<!-- NEED 5in -->
<H2>Header Files</H2>
<P>The proper way to include FLTK header files is:</P>
<UL><PRE>
#include &lt;FL/Fl_xyz.H&gt;
</PRE></UL>
<CENTER><TABLE BORDER="1" CELLPADDING="10" BGCOLOR="#cccccc">
<TR>
<TD><B>Note:</B>
<P>Case <I>is</I> significant on many operating systems,
and the C standard uses the forward slash (/) to
separate directories. <i>Do not use any of the following
include lines:</i></P>
<UL><PRE>
#include &lt;FL\Fl_xyz.H&gt;
#include &lt;fl/fl_xyz.h&gt;
#include &lt;Fl/fl_xyz.h&gt;
</PRE></UL>
</TD>
</TR>
</TABLE></CENTER>
*/
documentation/common.dox
+667
View File
File diff suppressed because it is too large Load Diff
documentation/drawing.dox
+967
View File
File diff suppressed because it is too large Load Diff
documentation/editor.dox
+905
View File
File diff suppressed because it is too large Load Diff
documentation/enumerations.dox
+304
View File
@@ -0,0 +1,304 @@
/**
\page enumerations C - FLTK Enumerations
<P>This appendix lists the enumerations provided in the
<TT>&lt;FL/Enumerations.H&gt;</TT> header file, organized by
section. Constants whose value is zero are marked with "(0)",
this is often useful to know when programming.
<H2>Version Numbers</H2>
The FLTK version number is stored in a number of compile-time
constants:
<UL>
<LI><TT>FL_MAJOR_VERSION</TT> - The major release number, currently 1. </LI>
<LI><TT>FL_MINOR_VERSION</TT> - The minor release number, currently 1. </LI>
<LI><TT>FL_PATCH_VERSION</TT> - The patch release number, currently 0. </LI>
<LI><TT>FL_VERSION</TT> - A combined floating-point version number for
the major, minor, and patch release numbers, currently 1.0100. </LI>
</UL>
<H2><A NAME="events">Events</A></H2>
Events are identified by an <TT>Fl_Event</TT> enumeration value. The
following events are currently defined:
<UL>
<LI><TT>FL_NO_EVENT</TT> - No event (or an event fltk does not
understand) occurred (0).</LI>
<LI><TT>FL_PUSH</TT> - A mouse button was pushed. </LI>
<LI><TT>FL_RELEASE</TT> - A mouse button was released. </LI>
<LI><TT>FL_ENTER</TT> - The mouse pointer entered a widget. </LI>
<LI><TT>FL_LEAVE</TT> - The mouse pointer left a widget. </LI>
<LI><TT>FL_DRAG</TT> - The mouse pointer was moved with a button
pressed. </LI>
<LI><TT>FL_FOCUS</TT> - A widget should receive keyboard focus. </LI>
<LI><TT>FL_UNFOCUS</TT> - A widget loses keyboard focus. </LI>
<LI><TT>FL_KEYBOARD</TT> - A key was pressed. </LI>
<LI><TT>FL_CLOSE</TT> - A window was closed. </LI>
<LI><TT>FL_MOVE</TT> - The mouse pointer was moved with no buttons
pressed. </LI>
<LI><TT>FL_SHORTCUT</TT> - The user pressed a shortcut key. </LI>
<LI><TT>FL_DEACTIVATE</TT> - The widget has been deactivated. </LI>
<LI><TT>FL_ACTIVATE</TT> - The widget has been activated. </LI>
<LI><TT>FL_HIDE</TT> - The widget has been hidden. </LI>
<LI><TT>FL_SHOW</TT> - The widget has been shown. </LI>
<LI><TT>FL_PASTE</TT> - The widget should paste the contents of the
clipboard. </LI>
<LI><TT>FL_SELECTIONCLEAR</TT> - The widget should clear any selections
made for the clipboard. </LI>
<LI><TT>FL_MOUSEWHEEL</TT> - The horizontal or vertical mousewheel was turned. </LI>
<LI><TT>FL_DND_ENTER</TT> - The mouse pointer entered a widget dragging data. </LI>
<LI><TT>FL_DND_DRAG</TT> - The mouse pointer was moved dragging data. </LI>
<LI><TT>FL_DND_LEAVE</TT> - The mouse pointer left a widget still dragging data. </LI>
<LI><TT>FL_DND_RELEASE</TT> - Dragged data is about to be dropped. </LI>
</UL>
<H2><a name=when>Callback &quot;When&quot; Conditions</A></H2>
The following constants determine when a callback is performed:
<UL>
<LI><TT>FL_WHEN_NEVER</TT> - Never call the callback (0). </LI>
<LI><TT>FL_WHEN_CHANGED</TT> - Do the callback only when the widget
value changes. </LI>
<LI><TT>FL_WHEN_NOT_CHANGED</TT> - Do the callback whenever the user
interacts with the widget. </LI>
<LI><TT>FL_WHEN_RELEASE</TT> - Do the callback when the button or key
is released and the value changes. </LI>
<LI><TT>FL_WHEN_ENTER_KEY</TT> - Do the callback when the user presses
the ENTER key and the value changes. </LI>
<LI><TT>FL_WHEN_RELEASE_ALWAYS</TT> - Do the callback when the button
or key is released, even if the value doesn't change. </LI>
<LI><TT>FL_WHEN_ENTER_KEY_ALWAYS</TT> - Do the callback when the user
presses the ENTER key, even if the value doesn't change. </LI>
</UL>
<H2><A NAME="button_values">Fl::event_button() Values</A></H2>
<P>The following constants define the button numbers for <TT>FL_PUSH</TT> and
<TT>FL_RELEASE</TT> events:
<UL>
<LI><TT>FL_LEFT_MOUSE</TT> - the left mouse button
<LI><TT>FL_MIDDLE_MOUSE</TT> - the middle mouse button
<LI><TT>FL_RIGHT_MOUSE</TT> - the right mouse button
</UL>
<H2><A NAME="key_values">Fl::event_key() Values</A></H2>
The following constants define the non-ASCII keys on the keyboard for <TT>
FL_KEYBOARD</TT> and <TT>FL_SHORTCUT</TT> events:
<UL>
<LI><TT>FL_Button</TT> - A mouse button; use <TT>Fl_Button + n</TT>
for mouse button <TT>n</TT>. </LI>
<LI><TT>FL_BackSpace</TT> - The backspace key. </LI>
<LI><TT>FL_Tab</TT> - The tab key. </LI>
<LI><TT>FL_Enter</TT> - The enter key. </LI>
<LI><TT>FL_Pause</TT> - The pause key. </LI>
<LI><TT>FL_Scroll_Lock</TT> - The scroll lock key. </LI>
<LI><TT>FL_Escape</TT> - The escape key. </LI>
<LI><TT>FL_Home</TT> - The home key. </LI>
<LI><TT>FL_Left</TT> - The left arrow key. </LI>
<LI><TT>FL_Up</TT> - The up arrow key. </LI>
<LI><TT>FL_Right</TT> - The right arrow key. </LI>
<LI><TT>FL_Down</TT> - The down arrow key. </LI>
<LI><TT>FL_Page_Up</TT> - The page-up key. </LI>
<LI><TT>FL_Page_Down</TT> - The page-down key. </LI>
<LI><TT>FL_End</TT> - The end key. </LI>
<LI><TT>FL_Print</TT> - The print (or print-screen) key. </LI>
<LI><TT>FL_Insert</TT> - The insert key. </LI>
<LI><TT>FL_Menu</TT> - The menu key. </LI>
<LI><TT>FL_Num_Lock</TT> - The num lock key. </LI>
<LI><TT>FL_KP</TT> - One of the keypad numbers; use <TT>FL_KP + n</TT>
for number <TT>n</TT>. </LI>
<LI><TT>FL_KP_Enter</TT> - The enter key on the keypad. </LI>
<LI><TT>FL_F</TT> - One of the function keys; use <TT>FL_F + n</TT>
for function key <TT>n</TT>. </LI>
<LI><TT>FL_Shift_L</TT> - The lefthand shift key. </LI>
<LI><TT>FL_Shift_R</TT> - The righthand shift key. </LI>
<LI><TT>FL_Control_L</TT> - The lefthand control key. </LI>
<LI><TT>FL_Control_R</TT> - The righthand control key. </LI>
<LI><TT>FL_Caps_Lock</TT> - The caps lock key. </LI>
<LI><TT>FL_Meta_L</TT> - The left meta/Windows key. </LI>
<LI><TT>FL_Meta_R</TT> - The right meta/Windows key. </LI>
<LI><TT>FL_Alt_L</TT> - The left alt key. </LI>
<LI><TT>FL_Alt_R</TT> - The right alt key. </LI>
<LI><TT>FL_Delete</TT> - The delete key. </LI>
</UL>
<H2>Fl::event_state() Values</H2>
The following constants define bits in the <TT>Fl::event_state()</TT>
value:
<UL>
<LI><TT>FL_SHIFT</TT> - One of the shift keys is down. </LI>
<LI><TT>FL_CAPS_LOCK</TT> - The caps lock is on. </LI>
<LI><TT>FL_CTRL</TT> - One of the ctrl keys is down. </LI>
<LI><TT>FL_ALT</TT> - One of the alt keys is down. </LI>
<LI><TT>FL_NUM_LOCK</TT> - The num lock is on. </LI>
<LI><TT>FL_META</TT> - One of the meta/Windows keys is down. </LI>
<LI><TT>FL_COMMAND</TT> - An alias for <TT>FL_CTRL</TT> on WIN32 and X11, or
<TT>FL_META</TT> on MacOS X. </LI>
<LI><TT>FL_SCROLL_LOCK</TT> - The scroll lock is on. </LI>
<LI><TT>FL_BUTTON1</TT> - Mouse button 1 is pushed. </LI>
<LI><TT>FL_BUTTON2</TT> - Mouse button 2 is pushed. </LI>
<LI><TT>FL_BUTTON3</TT> - Mouse button 3 is pushed. </LI>
<LI><TT>FL_BUTTONS</TT> - Any mouse button is pushed. </LI>
<LI><TT>FL_BUTTON(n)</TT> - Mouse button N (N &gt; 0) is pushed. </LI>
</UL>
<!-- NEED 4in -->
<H2><a name=align>Alignment Values</A></H2>
The following constants define bits that can be used with <A href=Fl_Widget.html#Fl_Widget.align>
<TT>Fl_Widget::align()</TT></A> to control the positioning of the
label:
<UL>
<LI><TT>FL_ALIGN_CENTER</TT> - The label is centered (0). </LI>
<LI><TT>FL_ALIGN_TOP</TT> - The label is top-aligned. </LI>
<LI><TT>FL_ALIGN_BOTTOM</TT> - The label is bottom-aligned. </LI>
<LI><TT>FL_ALIGN_LEFT</TT> - The label is left-aligned. </LI>
<LI><TT>FL_ALIGN_RIGHT</TT> - The label is right-aligned. </LI>
<LI><TT>FL_ALIGN_CLIP</TT> - The label is clipped to the widget. </LI>
<LI><TT>FL_ALIGN_WRAP</TT> - The label text is wrapped as needed. </LI>
<LI><TT>FL_ALIGN_TOP_LEFT</TT></LI>
<LI><TT>FL_ALIGN_TOP_RIGHT</TT></LI>
<LI><TT>FL_ALIGN_BOTTOM_LEFT</TT></LI>
<LI><TT>FL_ALIGN_BOTTOM_RIGHT</TT></LI>
<LI><TT>FL_ALIGN_LEFT_TOP</TT></LI>
<LI><TT>FL_ALIGN_RIGHT_TOP</TT></LI>
<LI><TT>FL_ALIGN_LEFT_BOTTOM</TT></LI>
<LI><TT>FL_ALIGN_RIGHT_BOTTOM</TT></LI>
<LI><TT>FL_ALIGN_INSIDE</TT> - 'or' this with other values to put
label inside the widget. </LI>
</UL>
<H2><a name=fonts>Fonts</A></H2>
The following constants define the standard FLTK fonts:
<ul>
<LI><TT>FL_HELVETICA</TT> - Helvetica (or Arial) normal (0). </LI>
<LI><TT>FL_HELVETICA_BOLD</TT> - Helvetica (or Arial) bold. </LI>
<LI><TT>FL_HELVETICA_ITALIC</TT> - Helvetica (or Arial) oblique. </LI>
<LI><TT>FL_HELVETICA_BOLD_ITALIC</TT> - Helvetica (or Arial)
bold-oblique. </LI>
<LI><TT>FL_COURIER</TT> - Courier normal. </LI>
<LI><TT>FL_COURIER_BOLD</TT> - Courier bold. </LI>
<LI><TT>FL_COURIER_ITALIC</TT> - Courier italic. </LI>
<LI><TT>FL_COURIER_BOLD_ITALIC</TT> - Courier bold-italic. </LI>
<LI><TT>FL_TIMES</TT> - Times roman. </LI>
<LI><TT>FL_TIMES_BOLD</TT> - Times bold. </LI>
<LI><TT>FL_TIMES_ITALIC</TT> - Times italic. </LI>
<LI><TT>FL_TIMES_BOLD_ITALIC</TT> - Times bold-italic. </LI>
<LI><TT>FL_SYMBOL</TT> - Standard symbol font. </LI>
<LI><TT>FL_SCREEN</TT> - Default monospaced screen font. </LI>
<LI><TT>FL_SCREEN_BOLD</TT> - Default monospaced bold screen font. </LI>
<LI><TT>FL_ZAPF_DINGBATS</TT> - Zapf-dingbats font.
</ul>
<H2><a name=colors>Colors</A></H2>
<P>The <TT>Fl_Color</TT> enumeration type holds a FLTK color value.
Colors are either 8-bit indexes into a virtual colormap or 24-bit RGB
color values. Color indices occupy the lower 8 bits of the value, while
RGB colors occupy the upper 24 bits, for a byte organization of RGBI.
<H3>Color Constants</H3>
<P>Constants are defined for the user-defined foreground and background
colors, as well as specific colors and the start of the grayscale ramp
and color cube in the virtual colormap. Inline functions are provided to
retrieve specific grayscale, color cube, or RGB color values.
<P>The following color constants can be used to access the user-defined
colors:
<UL>
<LI><TT>FL_BACKGROUND_COLOR</TT> - the default
background color</LI>
<LI><TT>FL_BACKGROUND2_COLOR</TT> - the default
background color for text, list, and valuator widgets</LI>
<LI><TT>FL_FOREGROUND_COLOR</TT> - the default
foreground color (0) used for labels and text</LI>
<LI><TT>FL_INACTIVE_COLOR</TT> - the inactive foreground
color</LI>
<LI><TT>FL_SELECTION_COLOR</TT> - the default selection/highlight
color</LI>
</UL>
<P>The following color constants can be used to access the colors from the
FLTK standard color cube:
<UL>
<LI><TT>FL_BLACK</TT></LI>
<LI><TT>FL_BLUE</TT></LI>
<LI><TT>FL_CYAN</TT></LI>
<LI><TT>FL_DARK_BLUE</TT></LI>
<LI><TT>FL_DARK_CYAN</TT></LI>
<LI><TT>FL_DARK_GREEN</TT></LI>
<LI><TT>FL_DARK_MAGENTA</TT></LI>
<LI><TT>FL_DARK_RED</TT></LI>
<LI><TT>FL_DARK_YELLOW</TT></LI>
<LI><TT>FL_GREEN</TT></LI>
<LI><TT>FL_MAGENTA</TT></LI>
<LI><TT>FL_RED</TT></LI>
<LI><TT>FL_WHITE</TT></LI>
<LI><TT>FL_YELLOW</TT></LI>
</UL>
<P>The inline methods for getting a grayscale, color cube, or
RGB color value are described in <A
HREF="functions.html#functions">Appendix B - Function
Reference</A>.
<H2><a name=cursor>Cursors</A></H2>
<P>The following constants define the mouse cursors that are available in
FLTK. The double-headed arrows are bitmaps
provided by FLTK on X, the others are provided by system-defined
cursors.</P>
<UL>
<LI><TT>FL_CURSOR_DEFAULT</TT> - the default cursor, usually an arrow (0)</LI>
<LI><TT>FL_CURSOR_ARROW</TT> - an arrow pointer </LI>
<LI><TT>FL_CURSOR_CROSS</TT> - crosshair </LI>
<LI><TT>FL_CURSOR_WAIT</TT> - watch or hourglass </LI>
<LI><TT>FL_CURSOR_INSERT</TT> - I-beam </LI>
<LI><TT>FL_CURSOR_HAND</TT> - hand (uparrow on MSWindows) </LI>
<LI><TT>FL_CURSOR_HELP</TT> - question mark </LI>
<LI><TT>FL_CURSOR_MOVE</TT> - 4-pointed arrow </LI>
<LI><TT>FL_CURSOR_NS</TT> - up/down arrow </LI>
<LI><TT>FL_CURSOR_WE</TT> - left/right arrow </LI>
<LI><TT>FL_CURSOR_NWSE</TT> - diagonal arrow </LI>
<LI><TT>FL_CURSOR_NESW</TT> - diagonal arrow </LI>
<LI><TT>FL_CURSOR_NONE</TT> - invisible </LI>
</UL>
<H2>FD &quot;When&quot; Conditions</H2>
<UL>
<LI><TT>FL_READ</TT> - Call the callback when there is data to be
read.</LI>
<LI><TT>FL_WRITE</TT> - Call the callback when data can be written
without blocking.</LI>
<LI><TT>FL_EXCEPT</TT> - Call the callback if an exception occurs on
the file.</LI>
</UL>
<H2><a name=damage>Damage Masks</A></H2>
The following damage mask bits are used by the standard FLTK widgets:
<UL>
<LI><TT>FL_DAMAGE_CHILD</TT> - A child needs to be redrawn. </LI>
<LI><TT>FL_DAMAGE_EXPOSE</TT> - The window was exposed. </LI>
<LI><TT>FL_DAMAGE_SCROLL</TT> - The <TT>Fl_Scroll</TT> widget was
scrolled. </LI>
<LI><TT>FL_DAMAGE_OVERLAY</TT> - The overlay planes need to be redrawn. </LI>
<LI><TT>FL_DAMAGE_USER1</TT> - First user-defined damage bit. </LI>
<LI><TT>FL_DAMAGE_USER2</TT> - Second user-defined damage bit. </LI>
<LI><TT>FL_DAMAGE_ALL</TT> - Everything needs to be redrawn. </LI>
</UL>
*/
documentation/events.dox
+389
View File
@@ -0,0 +1,389 @@
/**
\page events 6 - Handling Events
<P>This chapter discusses the FLTK event model and how to handle
events in your program or widget.
<H2>The FLTK Event Model</H2>
<P>Every time a user moves the mouse pointer, clicks a button,
or presses a key, an event is generated and sent to your
application. Events can also come from other programs like the
window manager.
<P>Events are identified by the integer argument passed to the
<A href="subclassing.html#handle"><TT>Fl_Widget::handle()</TT></A> virtual
method. Other information about the most recent event is stored in
static locations and acquired by calling the <A
href="#event_xxx"><TT>Fl::event_*()</TT></A> methods. This static
information remains valid until the next event is read from the window
system, so it is ok to look at it outside of the <TT>handle()</TT>
method.
<H2>Mouse Events</H2>
<H3>FL_PUSH</H3>
<P>A mouse button has gone down with the mouse pointing at this
widget. You can find out what button by calling <A
href="Fl.html#Fl.event_button"><TT>
Fl::event_button()</TT></A>. You find out the mouse position by
calling <A
href="Fl.html#Fl.event_x"><TT>Fl::event_x()</TT></A> and <A
href="Fl.html#Fl.event_y"> <TT>Fl::event_y()</TT></A>.
<P>A widget indicates that it &quot;wants&quot; the mouse click
by returning non-zero from its <A
href="subclassing.html#handle"><TT>handle()</TT></A> method. It
will then become the <A href="Fl.html#Fl.pushed"><TT>
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>
<P>The mouse has moved with a button held down. The current
button state is in <a
href="Fl.html#Fl.event_state"><tt>Fl::event_state()</tt></a>.
The mouse position is in <a
href="Fl.html#Fl.event_x"><tt>Fl::event_x()</tt></a> and <a
href="Fl.html#Fl.event_y"><tt>Fl::event_y()</tt></a>.
<P>In order to receive <TT>FL_DRAG</TT> events, the widget must
return non-zero when handling <TT>FL_PUSH</TT>.</P>
<H3>FL_RELEASE</H3>
<P>A mouse button has been released. You can find out what
button by calling <A
href="Fl.html#Fl.event_button"><TT>Fl::event_button()</TT></A>.
<P>In order to receive the <TT>FL_RELEASE</TT> event, the widget must
return non-zero when handling <TT>FL_PUSH</TT>.</P>
<H3>FL_MOVE</H3>
<P>The mouse has moved without any mouse buttons held down.
This event is sent to the <A
href="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse()</TT></A>
widget.</P>
<P>In order to receive <TT>FL_MOVE</TT> events, the widget must
return non-zero when handling <TT>FL_ENTER</TT>.</P>
<H3>FL_MOUSEWHEEL</H3>
<P>The user has moved the mouse wheel. The <A
HREF="Fl.html#Fl.event_dx"><TT>Fl::event_dx()</TT></A> and <A
HREF="Fl.html#Fl.event_dy"><TT>Fl::event_dy()</TT></A> methods
can be used to find the amount to scroll horizontally and
vertically.
<H2>Focus Events</H2>
<H3>FL_ENTER</H3>
<P>The mouse has been moved to point at this widget. This can
be used for highlighting feedback. If a widget wants to
highlight or otherwise track the mouse, it indicates this by
returning non-zero from its <A
href="Fl.html#Fl.handle"><TT>handle()</TT></A> method. It then
becomes the <A
href="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse()</TT></A>
widget and will receive <TT>FL_MOVE</TT> and <TT>FL_LEAVE</TT>
events.
<H3>FL_LEAVE</H3>
<P>The mouse has moved out of the widget.
<P>In order to receive the <TT>FL_LEAVE</TT> event, the widget must
return non-zero when handling <TT>FL_ENTER</TT>.</P>
<H3>FL_FOCUS</H3>
<P>This indicates an <I>attempt</I> to give a widget the
keyboard focus.
<P>If a widget wants the focus, it should change itself to
display the fact that it has the focus, and return non-zero from
its <A
href="Fl_Widget.html#Fl_Widget.handle"><TT>handle()</TT></A>
method. It then becomes the <A
href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A> widget and gets
<TT>FL_KEYDOWN</TT>, <TT>FL_KEYUP</TT>, and <TT>FL_UNFOCUS</TT>
events.
<P>The focus will change either because the window manager
changed which window gets the focus, or because the user tried
to navigate using tab, arrows, or other keys. You can check <A
href="Fl.html#Fl.event_key"><TT>Fl::event_key()</TT></A> to
figure out why it moved. For navigation it will be the key
pressed and interaction with the window manager it will be
zero.
<H3>FL_UNFOCUS</H3>
<P>This event is sent to the previous <A
href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A> widget when
another widget gets the focus or the window loses focus.
<H2>Keyboard Events</H2>
<H3>FL_KEYDOWN, FL_KEYUP</H3>
<P>A key was pressed or released. The key can be found in <A
href="Fl.html#Fl.event_key"><TT>Fl::event_key()</TT></A>. The
text that the key should insert can be found with <A
href="Fl.html#Fl.event_text"><TT>Fl::event_text()</TT></A> and
its length is in <A
href="Fl.html#Fl.event_length"><TT>Fl::event_length()</TT></A>.
If you use the key <TT>handle()</TT> should return 1. If you
return zero then FLTK assumes you ignored the key and 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.
<P>To receive <CODE>FL_KEYBOARD</CODE> events you must also
respond to the <CODE>FL_FOCUS</CODE> and <CODE>FL_UNFOCUS</CODE>
events.
<P>If you are writing a text-editing widget you may also want to
call the <a href="Fl.html#Fl.compose"><TT>Fl::compose()</TT></a>
function to translate individual keystrokes into foreign
characters.
<P><code>FL_KEYUP</code> events are sent to the widget that
currently has focus. This is not necessarily the same widget
that received the corresponding <code>FL_KEYDOWN</code> event
because focus may have changed between events.
<H3>FL_SHORTCUT</H3>
<P>If the <A href="Fl.html#Fl.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>Fl::belowmouse()</TT> widget, then its parents and
siblings, and eventually to every widget in the window, trying
to find an object that returns non-zero. FLTK tries really hard
to not to ignore any keystrokes!
<P>You can also make &quot;global&quot; shortcuts by using <A
href="Fl.html#Fl.add_handler"><TT>Fl::add_handler()</TT></A>. A
global shortcut will work no matter what windows are displayed
or which one has the focus.</P>
<H2>Widget Events</H2>
<H3>FL_DEACTIVATE</H3>
<P>This widget is no longer active, due to <A
href="Fl_Widget.html#Fl_Widget.deactivate"><TT>deactivate()</TT></A>
being called on it or one of its parents. <TT> active()</TT> may
still be true after this, the widget is only active if
<TT>active()</TT> is true on it and all its parents (use <TT>active_r()</TT> to check this).
<H3>FL_ACTIVATE</H3>
<P>This widget is now active, due to <A
href="Fl_Widget.html#Fl_Widget.activate"><TT>activate()</TT></A>
being called on it or one of its parents.
<H3>FL_HIDE</H3>
<P>This widget is no longer visible, due to <A
href="Fl_Widget.html#Fl_Widget.hide"><tt>hide()</tt></a> being
called on it or one of its parents, or due to a parent window
being minimized. <tt>visible()</tt> may still be true after
this, but the widget is visible only if <tt>visible()</tt> is
true for it and all its parents (use <tt>visible_r()</tt> to
check this).
<h3>FL_SHOW</h3>
<P>This widget is visible again, due to <a
href="Fl_Widget.html#Fl_Widget.show"><TT>show()</TT></A> being
called on it or one of its parents, or due to a parent window
being restored. <I>Child <TT>Fl_Window</TT>s respond to this by
actually creating the window if not done already, so if you
subclass a window, be sure to pass <TT>FL_SHOW</TT> to the base
class <TT>handle()</TT> method!</I>
<H2>Clipboard Events</H2>
<H3>FL_PASTE</H3>
<P>You should get this event some time after you call <A
href="Fl.html#Fl.paste"><TT>Fl::paste()</TT></A>. The contents
of <A href="Fl.html#Fl.event_text"><TT>Fl::event_text()</TT></A>
is the text to insert and the number of characters is in <A
href="Fl.html#Fl.event_length"><TT>Fl::event_length()</TT></A>.
<H3>FL_SELECTIONCLEAR</H3>
<P>The <A
href="Fl.html#Fl.selection_owner"><TT>Fl::selection_owner()</TT></A>
will get this event before the selection is moved to another
widget. This indicates that some other widget or program has
claimed the selection. Motif programs used this to clear the
selection indication. Most modern programs ignore this.
<H2><A NAME="dnd">Drag And Drop Events</A></H2>
<P>FLTK supports drag and drop of text and files from any
application on the desktop. Text is transfered using
the current code page. Files are received as a list of full path
and file names, seperated by newline. On some platforms, path
names are prepended with <tt>file://</tt>.
<P>The drag and drop data is available in <tt>Fl::event_text()</tt>
at the concluding <tt>FL_PASTE</tt>. On some platforms, the
event text is also available for the <tt>FL_DND_*</tt> events,
however application must not depend on that behavior because it
depends on the protocol used on each platform.
<P><tt>FL_DND_*</tt> events cannot be used in widgets derived
from <tt>Fl_Group</tt> or <tt>Fl_Window</tt>.
<H3>FL_DND_ENTER</H3>
<P>The mouse has been moved to point at this widget. A widget
that is interested in receiving drag'n'drop data must return 1
to receive FL_DND_DRAG, FL_DND_LEAVE and FL_DND_RELEASE events.
<H3>FL_DND_DRAG</H3>
<P>The mouse has been moved inside a widget while dragging data.
A widget that is interested in receiving drag'n'drop data should
indicate the possible drop position.
<H3>FL_DND_LEAVE</H3>
<P>The mouse has moved out of the widget.
<H3>FL_DND_RELEASE</H3>
<P>The user has released the mouse button dropping data into
the widget. If the widget returns 1, it will receive the data in
the immediatly following FL_PASTE event.
<!-- NEED 6in -->
<H2><A name="event_xxx">Fl::event_*() methods</A></H2>
<P>FLTK keeps the information about the most recent event in
static storage. This information is good until the next event is
processed. 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 HREF="Fl.html#Fl.event_button"><TT>Fl::event_button</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_clicks"><TT>Fl::event_clicks</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_dx"><TT>Fl::event_dx</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_dy"><TT>Fl::event_dy</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_inside"><TT>Fl::event_inside</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_is_click"><TT>Fl::event_is_click</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_key"><TT>Fl::event_key</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_length"><TT>Fl::event_length</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_state"><TT>Fl::event_state</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_text"><TT>Fl::event_text</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_x"><TT>Fl::event_x</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_x_root"><TT>Fl::event_x_root</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_y"><TT>Fl::event_y</TT></A></LI>
<LI><A HREF="Fl.html#Fl.event_y_root"><TT>Fl::event_y_root</TT></A></LI>
<LI><A HREF="Fl.html#Fl.get_key"><TT>Fl::get_key</TT></A></LI>
<LI><A HREF="Fl.html#Fl.get_mouse"><TT>Fl::get_mouse</TT></A></LI>
<LI><A HREF="Fl.html#Fl.test_shortcut"><TT>Fl::test_shortcut</TT></A></LI>
</UL>
<H2><A name=propagation>Event Propagation</A></H2>
<P>FLTK follows very simple and unchangeable rules for sending
events. The major innovation is that widgets can indicate (by
returning 0 from the <TT>handle()</TT> method) that they are not
interested in an event, and FLTK can then send that event
elsewhere. This eliminates the need for &quot;interests&quot;
(event masks or tables), and this is probably the main reason
FLTK is much smaller than other toolkits.
<P>Most events are sent directly to the <TT>handle()</TT> method
of the <TT>Fl_Window</TT> that the window system says they
belong to. The window (actually the <TT>Fl_Group</TT> that
<TT>Fl_Window</TT> is a subclass of) is responsible for sending
the events on to any child widgets. To make the
<TT>Fl_Group</TT> code somewhat easier, FLTK sends some events
(<TT>FL_DRAG</TT>, <TT>FL_RELEASE</TT>, <TT>FL_KEYBOARD</TT>,
<TT>FL_SHORTCUT</TT>, <TT>FL_UNFOCUS</TT>, and
<TT>FL_LEAVE</TT>) directly to leaf widgets. These procedures
control those leaf widgets:
<UL>
<LI><A HREF="Fl.html#Fl.add_handler"><TT>Fl::add_handler</TT></A></LI>
<LI><A HREF="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse</TT></A></LI>
<LI><A HREF="Fl.html#Fl.focus"><TT>Fl::focus</TT></A></LI>
<LI><A HREF="Fl.html#Fl.grab"><TT>Fl::grab</TT></A></LI>
<LI><A HREF="Fl.html#Fl.modal"><TT>Fl::modal</TT></A></LI>
<LI><A HREF="Fl.html#Fl.pushed"><TT>Fl::pushed</TT></A></LI>
<LI><A HREF="Fl.html#Fl.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>
<H2><A name="compose">FLTK Compose-Character Sequences</A></H2>
<P>The foreign-letter compose processing done by the <A
href="Fl_Input.html#compose"><tt>Fl_Input</tt></a> widget is provided in
a function that you can call if you are writing your own text editor
widget.
<p>FLTK uses its own compose processing to allow "preview" of
the partially composed sequence, which is impossible with the
usual "dead key" processing.
<p>Although currently only characters in the ISO-8859-1
character set are handled, you should call this in case any
enhancements to the processing are done in the future. The
interface has been designed to handle arbitrary UTF-8 encoded
text.
<P>The following methods are provided for character composition:
<UL>
<LI><A HREF="Fl.html#Fl.compose"><TT>Fl::compose()</TT></A></LI>
<LI><A HREF="Fl.html#Fl.compose_reset"><TT>Fl::compose_reset()</TT></A></LI>
</UL>
*/
documentation/examples.dox
+448
View File
@@ -0,0 +1,448 @@
/**
\page examples J - Example Source Code
<P ALIGN="RIGHT">March 19, 2005</P>
<P>The FLTK distribution contains over 60 sample applications written
in, or ported to, FLTK. If the FLTK archive you received does not
contain a 'test' directory, you can download the complete FLTK
distribution from
<a href="http://fltk.org/software.php">http://fltk.org/software.php</a>.</P>
<P>Most of the example programs were created while testing a group of widgets.
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><a href="#adjuster"><tt>adjuster</tt></a></td>
<td><a href="#arc"><tt>arc</tt></a></td>
<td><a href="#ask"><tt>ask</tt></a></td>
<td><a href="#bitmap"><tt>bitmap</tt></a></td>
<td><a href="#blocks"><tt>blocks</tt></a></td>
<td><a href="#boxtype"><tt>boxtype</tt></a></td>
</tr>
<tr>
<td><a href="#browser"><tt>browser</tt></a></td>
<td><a href="#button"><tt>button</tt></a></td>
<td><a href="#buttons"><tt>buttons</tt></a></td>
<td><a href="#checkers"><tt>checkers</tt></a></td>
<td><a href="#clock"><tt>clock</tt></a></td>
<td><a href="#colbrowser"><tt>colbrowser</tt></a></td>
</tr>
<tr>
<td><a href="#color_chooser"><tt>color_chooser</tt></a></td>
<td><a href="#cube"><tt>cube</tt></a></td>
<td><a href="#CubeView"><tt>CubeView</tt></a></td>
<td><a href="#cursor"><tt>cursor</tt></a></td>
<td><a href="#curve"><tt>curve</tt></a></td>
<td><a href="#demo"><tt>demo</tt></a></td>
</tr>
<tr>
<td><a href="#doublebuffer"><tt>doublebuffer</tt></a></td>
<td><a href="#editor"><tt>editor</tt></a></td>
<td><a href="#fast_slow"><tt>fast_slow</tt></a></td>
<td><a href="#file_chooser"><tt>file_chooser</tt></a></td>
<td><a href="#fluid"><tt>fluid</tt></a></td>
<td><a href="#fonts"><tt>fonts</tt></a></td>
</tr>
<tr>
<td><a href="#forms"><tt>forms</tt></a></td>
<td><a href="#fractals"><tt>fractals</tt></a></td>
<td><a href="#fullscreen"><tt>fullscreen</tt></a></td>
<td><a href="#gl_overlay"><tt>gl_overlay</tt></a></td>
<td><a href="#glpuzzle"><tt>glpuzzle</tt></a></td>
<td><a href="#hello"><tt>hello</tt></a></td>
</tr>
<tr>
<td><a href="#help"><tt>help</tt></a></td>
<td><a href="#iconize"><tt>iconize</tt></a></td>
<td><a href="#image"><tt>image</tt></a></td>
<td><a href="#inactive"><tt>inactive</tt></a></td>
<td><a href="#input"><tt>input</tt></a></td>
<td><a href="#input_choice"><tt>input_choice</tt></a></td>
</tr>
<tr>
<td><a href="#keyboard"><tt>keyboard</tt></a></td>
<td><a href="#label"><tt>label</tt></a></td>
<td><a href="#line_style"><tt>line_style</tt></a></td>
<td><a href="#list_visuals"><tt>list_visuals</tt></a></td>
<td><a href="#mandelbrot"><tt>mandelbrot</tt></a></td>
<td><a href="#menubar"><tt>menubar</tt></a></td>
</tr>
<tr>
<td><a href="#message"><tt>message</tt></a></td>
<td><a href="#minimum"><tt>minimum</tt></a></td>
<td><a href="#navigation"><tt>navigation</tt></a></td>
<td><a href="#output"><tt>output</tt></a></td>
<td><a href="#overlay"><tt>overlay</tt></a></td>
<td><a href="#pack"><tt>pack</tt></a></td>
</tr>
<tr>
<td><a href="#pixmap_browser"><tt>pixmap_browser</tt></a></td>
<td><a href="#pixmap"><tt>pixmap</tt></a></td>
<td><a href="#preferences"><tt>preferences</tt></a></td>
<td><a href="#radio"><tt>radio</tt></a></td>
<td><a href="#resizebox"><tt>resizebox</tt></a></td>
<td><a href="#resize"><tt>resize</tt></a></td>
</tr>
<tr>
<td><a href="#scroll"><tt>scroll</tt></a></td>
<td><a href="#shape"><tt>shape</tt></a></td>
<td><a href="#subwindow"><tt>subwindow</tt></a></td>
<td><a href="#sudoku"><tt>sudoku</tt></a></td>
<td><a href="#symbols"><tt>symbols</tt></a></td>
<td><a href="#tabs"><tt>tabs</tt></a></td>
</tr>
<tr>
<td><a href="#threads"><tt>threads</tt></a></td>
<td><a href="#tile"><tt>tile</tt></a></td>
<td><a href="#tiled_image"><tt>tiled_image</tt></a></td>
<td><a href="#valuators"><tt>valuators</tt></a></td>
</tr>
</table>
<h3><a name="adjuster">adjuster</h3>
<tt>adjuster</tt> shows a nifty little widget for quickly
setting values in a great range.
<h3><a name="arc">arc</h3>
The <tt>arc</tt> demo explains how to derive your own widget to
generate some custom drawings. The sample drawings use the matrix
based arc drawing for some fun effects.
<h3><a name="ask">ask</h3>
<tt>ask</tt> shows some of FLTK's standard dialog boxes. Click
the correct answers or you may end up in a loop, or you may end
up in a loop, or you... .
<h3><a name="bitmap">bitmap</h3>
This simple test shows the use of a single color bitmap as a
label for a box widget. Bitmaps are stored in the X11 '.bmp'
file format and can be part of the source code.
<h3><a name="blocks">blocks</h3>
A wonderful and addictive game that shows the usage of FLTK
timers, graphics, and how to implement sound on all platforms.
<tt>blocks</tt> is also a good example for the Mac OS X specific
bundle format.
<h3><a name="boxtype">boxtype</h3>
<tt>boxtype</tt> gives an overview of readily available boxes and
frames in FLTK. More types can be added by the application programmer.
When using themes, FLTK shuffles boxtypes around to give your program
a new look.
<h3><a name="browser">browser</h3>
<tt>browser</tt> shows the capabilities of the <tt>Fl_Browser</tt> widget.
Important features tested are loading of files, line formatting, and
correct positioning of the browser data window.
<h3><a name="button">button</h3>
The <tt>button</tt> test is a simple demo of push-buttons and callbacks.
<h3><a name="buttons">buttons</h3>
<tt>buttons</tt> shows a sample of FLTK button types.
<h3><a name="checkers">checkers</h3>
Written by Steve Poulsen in early 1979, <tt>checkers</tt> shows
how to convert a VT100 text-terminal based program into a neat
application with a graphical UI. Check out the code that drags the
pieces, and how the pieces are drawn by layering. Then tell me
how to beat the computer at Checkers.
<h3><a name="clock">clock</h3>
The <tt>clock</tt> demo shows two analog clocks. The innards of
the <tt>Fl_Clock</tt> widget are pretty interesting, explaining
the use of timeouts and matrix based drawing.
<h3><a name="colbrowser">colbrowser</h3>
<tt>colbrowser</tt> runs only on X11 systems. It reads
<i>/usr/lib/X11/rgb.txt</i> to show the color representation
of every text entry in the file. This is beautiful, but
only moderatly useful unless your UI is written in <i>Motif</i>.
<h3><a name="color_chooser">color_chooser</h3>
The <tt>color_chooser</tt> gives a short demo of FLTK's palette based
color chooser and of the RGB based color wheel.
<h3><a name="cube">cube</h3>
The <tt>cube</tt> demo shows the speed of OpenGL. It also tests
the ability to render two OpenGL buffers into a single window,
and shows OpenGL text.
<h3><a name="CubeView">CubeView</h3>
<tt>CubeView</tt> shows how to create a UI containing OpenGL with Fluid.
<h3><a name="cursor">cursor</h3>
The <tt>cursor</tt> demo show all mouse cursor shapes that come standard
with FLTK. The <i>fgcolor</i> and <i>bgcolor</i> sliders work only
on few systems (some version of Irix for example).
<h3><a name="curve">curve</h3>
<tt>curve</tt> draws a nice Bezier curve into a custom widget. The
<i>points</i> option for splines is not supported on all platforms.
<h3><a name="demo">demo</h3>
This tool allows quick access to all programs in the <tt>test</tt> directory.
<tt>demo</tt> is based on the visuals of the IrixGL demo program. The menu
tree can be changed by editing <tt>test/demo.menu</tt>.
<h3><a name="doublebuffer">doublebuffer</h3>
The <tt>doublebuffer</tt> demo show the difference between a single
buffered window, which may flicker during a slow redraw, and a
double buffered window, which never flickers, but uses twice the
amount of RAM. Some modern OS's double buffer all windows automatically
to allow transparency and shadows on the desktop. FLTK is smart enough
to not tripple buffer a window in that case.
<h3><a name="editor">editor</h3>
FLTK has two very different text input widgets. <tt>Fl_Input</tt>
and derived classes are rather leight weight, however
<tt>Fl_Text_Editor</tt> is a complete port of <i>nedit</i> (with permission).
The <tt>editor</tt> test is almost a full application, showing custom
syntax highlighting and dialog creation.
<h3><a name="fast_slow">fast_slow</h3>
<tt>fast_slow</tt> shows how an application can use then <tt>when()</tt>
setting to receive different kinds of callbacks.
<h3><a name="file_chooser">file_chooser</h3>
The standard FLTK <tt>file_chooser</tt> is the result of many
iterations, trying to find a middle ground between a complex
browser and a fast light implementation.
<h3><a name="fonts">fonts</h3>
<tt>fonts</tt> show all available text fonts on the host system.
If your machine still has some pixmap based fonts, the supported
sizes will be shown in bold face. Only the first 256 fonts will
be listed.
<h3><a name="forms">forms</h3>
<tt>forms</tt> is an XForms program with very few changes.
Search for "fltk" to find all changes necessary to port to fltk.
This demo show the different boxtypes. Note that some
boxtypes are not appropriate for some objects.
<h3><a name="fractals">fractals</h3>
<tt>fractals</tt> shows how to mix OpenGL, Glut and FLTK code.
FLTK supports a rather large subset of Glut, so that many Glut
application compile just fine.
<h3><a name="fullscreen">fullscreen</h3>
This demo shows how to do many of the window manipulations that
are popular for games.
You can toggle the border on/off, switch between single-
and double-buffered rendering, and take over the entire
screen. More information in the source code.
<h3><a name="gl_overlay">gl_overlay</h3>
<tt>gl_overlay</tt> shows OpenGL overlay plane rendering. If no
hardware overlay plane is available, FLTK will simulate it
for you.
<h3><a name="glpuzzle">glpuzzle</h3>
The <tt>glpuzzle</tt> test shows how most Glut source code compiles
easily under FLTK.
<h3><a name="hello">hello</h3>
<tt>hello</tt>: Hello, World. Need I say maore? Well, maybe. This
tiny demo shows how little is needed to get a functioning application
running with FLTK. Quite impressive, I'd say.
<h3><a name="help">help</h3>
<tt>help</tt> displays the built-in FLTK help browser. The
<tt>Fl_Help_Dialog</tt> understands a subset of html and renders
various image formats. This widget makes it easy to provide help
pages to the user without depending on the operating system's
html browser.
<h3><a name="iconize">iconize</h3>
<tt>iconize</tt> demonstrates the effect of the window functions
<tt>hide()</tt>, <tt>iconize()</tt>, and <tt>show()</tt>.
<h3><a name="image">image</h3>
The <tt>image</tt> demo shows how an image can be created on the fly.
This generated image contains an alpha (transparency) channel which
lets previous renderings 'shine through', either via true
transparency or by using screen door transparency (pixelation).
<h3><a name="inactive">inactive</h3>
<tt>inactive</tt> tests the correct rendering of inactive widgets.
To see the inactive version of images, you can check out the pixmap
or image test.
<h3><a name="input">input</h3>
This tool shows and tests different types of text input fields based on
<tt>Fl_Input_</tt>. The <tt>input</tt> program also tests various
settings of <tt>Fl_Input::when()</tt>.
<h3><a name="input_choice">input_choice</h3>
<tt>input_choice</tt> tests the latest addition to FLTK1, a text input
field with an attached pulldown menu. Windows users will recognize
similarities to the 'ComboBox'. <tt>input_choice</tt> starts up in
'plastic' scheme, but the traditional scheme is also supported.
<h3><a name="keyboard">keyboard</h3>
FLTK unifies keyboard events for all platforms. The <tt>keyboard</tt>
test can be used to check the return values of <tt>Fl::event_key()</tt>
and <tt>Fl::event_text()</tt>. It is also great to see the modifier
buttons and the scroll wheel at work. Quit this application by closing
the window. The ESC key will not work.
<h3><a name="label">label</h3>
Every FLTK widget can have a label attached to it. The <tt>label</tt>
demo shows alignment, clipping and wrapping of text labels. Labels
can contain symbols at the start and end of the text, like <i>@FLTK</i>
or <i>@circle uh-huh @square</i>.
<h3><a name="line_style">line_style</h3>
Advanced line drawing can be tested with <tt>line_style</tt>.
Not all platforms support all line styles.
<h3><a name="list_visuals">list_visuals</h3>
This little app finds all available pixel formats for the current X11
screen. But since you are now an FLTK user, you don't have to worry
about any of this.
<h3><a name="mandelbrot">mandelbrot</h3>
<tt>mandelbrot</tt> shows two advanced topics in one test. It creates
grayscale images on the fly, updating them via the <i>idle</i> callback
system. This is one of the few occasions where the <i>idle</i> callback
is very useful by giving all available processor time to the application
without blocking the UI or other apps.
<h3><a name="menubar">menubar</h3>
The <tt>menubar</tt> tests many aspects of FLTK's popup menu system.
Among the features are radio buttons, menus taller than the screen,
arbitrary sub menu depth, and global shortcuts.
<h3><a name="message">message</h3>
<tt>message</tt> pops up a few of FLTK's standars message boxes.
<h3><a name="minimum">minimum</h3>
The <tt>minimum</tt> test program verifies that the update regions
are set correctly. In a real life application, the trail would
be avoided by choosing a smaller label or by setting label clipping
differently.
<h3><a name="navigation">navigation</h3>
<tt>navigation</tt> demonstrates how the text cursor moves from
text field to text field when using the arrow keys, tab, and shift-tab.
<h3><a name="output">output</h3>
<tt>output</tt> shows the difference between the single line and
multi line mode of the <tt>Fl_Output</tt> widget. Fonts can be
selected from the FLTK standard list of fonts.
<h3><a name="overlay">overlay</h3>
The <tt>overlay</tt> test app show how easy an FLTK window can
be layered to display cursor and manipulator style elemnts. This
example derives a new class from <tt>Fl_Overly_WIndow</tt> and
provides a new function to draw custom overlays.
<h3><a name="pack">pack</h3>
The <tt>pack</tt> test program demonstrates the resizing
and repositioning of children of the <tt>Fl_Pack</tt> group.
Putting an <tt>Fl_Pack</tt> into an <tt>Fl_Scroll</tt> is
a useful way to create a browser for large sets of data.
<h3><a name="pixmap_browser">pixmap_browser</h3>
<tt>pixmap_browser</tt> tests the shared-image interface. When using
the same image multiple times, <tt>Fl_Shared_Image</tt> will keep it
only once in memory.
<h3><a name="pixmap">pixmap</h3>
This simple test shows the use of a LUT based pixmap as a
label for a box widget. Pixmaps are stored in the X11 '.xpm'
file format and can be part of the source code. Pixmaps support
one transparent color.
<h3><a name="preferences">preferences</h3>
I do have my <tt>preferences</tt> in the morning, but sometimes I
just can't remember a thing. This is where the <tt>Fl_Preferences</tt>
come in handy. They remember any kind of data between program launches.
<h3><a name="radio">radio</h3>
The <tt>radio</tt> tool was created entirely with <i>fluid</i>. It
shows some of the available button types and tests radio
button behavior.
<h3><a name="resizebox">resizebox</h3>
<tt>resizebox</tt> shows some possible ways of FLTK's automatic
resize bahavior..
<h3><a name="resize">resize</h3>
The <tt>resize</tt> demo tests size and position functions with
the given window manager.
<h3><a name="scroll">scroll</h3>
<tt>scroll</tt> shows how to scroll an area of widgets, one of
them beeing a slow custom drawing. <tt>Fl_Scroll</tt> uses
clipping and smart window area copying to improve redraw speed.
The buttons at the bottom of the window control decoration rendering
and updates.
<h3><a name="shape">shape</h3>
<tt>shape</tt> is a very minimal demo that shows how to create
your own OpenGL rendering widget. Now that you know that, go ahead
and write that flight simulator you always dreamt of.
<h3><a name="subwindow">subwindow</h3>
The <tt>subwindow</tt> demo tests messaging and drawing between
the main window and 'true' sub windows. A sub window is different
to a group by resetting the FLTK coordinate stystem to 0, 0 in the
top left corner. On Win32 and X11, subwindows have their own
operating system specific handle.
<h3><a name="sudoku">sudoku</h3>
Another highly addictive game - don't play it, I warned you.
The implementation shows how to create application icons,
how to deal with OS specifics, and how to generate sound.
<h3><a name="symbols">symbols</h3>
<tt>symbols</tt> are a speciality of FLTK. These little vector
drawings can be integrated into labels. They scale and rotate,
and with a little patience, you can define your own. The rotation
number refers to 45 degree rotations if you were looking at a
numeric keypad (2 is down, 6 is right, etc.).
<h3><a name="tabs">tabs</h3>
The <tt>tabs</tt> tool was created with <i>fluid</i>. It tests
correct hiding and redisplaying of tabs, navigation across tabs,
resize behavior, and no unneeded redrawing of invisible widgets.
<P>The <tt>tabs</tt> application shows the <tt>Fl_Tabs</tt> widget
on the left and the <tt>Fl_Wizard</tt> widget on the right side
for direct comparison of these two panel management widgets.
<h3><a name="threads">threads</h3>
FLTK can be used in a multithreading environment. There are some
limitations, mostly due to the underlying operating system.
<tt>threads</tt> show how to use <tt>Fl::lock()</tt>,
<tt>Fl::unlock()</tt>, and <tt>Fl::awake()</tt> in secondary threads
to keep FLTK happy. Although locking works on all platforms,
this demo is not available on every machine.
<h3><a name="tile">tile</h3>
The <tt>tile</tt> tool shows a nice way of using <tt>Fl_Tile</tt>.
To test correct resizing of subwindows, the widget for region
1 is created from an <tt>Fl_Window</tt> class.
<h3><a name="tiled_image">tiled_image</h3>
The <tt>tiled_image</tt> demo uses an image as the background
for a window by repeating it over the full size of the widget.
Thw window is resizable and shows how the image gets repeated.
<h3><a name="valuators">valuators</h3>
<tt>valuators</tt> shows all of FLTK's nifty widgets to change
numeric values.
<h3><a name="fluid">fluid</h3>
<tt>fuid</tt> is not only a big test program, but also a very
useful visual UI designer. Many parts of <tt>fluid</tt> were
created using <tt>fluid</tt>.
*/
documentation/fluid.dox
+1359
View File
File diff suppressed because it is too large Load Diff
documentation/forms.dox
+201
View File
@@ -0,0 +1,201 @@
/**
\page forms E - Forms Compatibility
<P>This appendix describes the Forms compatibility included with FLTK.
<H2>Importing Forms Layout Files</H2>
<A href=fluid.html#FLUID>FLUID</A> can read the .fd files put out by
all versions of Forms and XForms fdesign. However, it will mangle them
a bit, but it prints a warning message about anything it does not
understand. FLUID cannot write fdesign files, so you should save to a
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>
<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>
forms.h</TT> file supplied with FLTK is included. Take a look at <TT>
forms.h</TT> to see how it works, but the basic trick is lots of inline
functions. Most of the XForms demo programs work without changes.
<P>You will also have to compile your Forms or XForms program using a
C++ compiler. The FLTK library does not provide C bindings or header
files. </P>
<P>Although FLTK was designed to be compatible with the GL Forms
library (version 0.3 or so), XForms has bloated severely and it's
interface is X-specific. Therefore, XForms compatibility is no longer
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
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
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
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
provided to emulate the XForms timer. These work, but are quite
inefficient and inaccurate compared to using <A href="Fl.html#Fl.add_timeout">
<TT>Fl::add_timeout()</TT></A>. </P>
<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>
<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
pass static data such as a string constant or malloc'd buffer to <TT>
label()</TT>. If you are using labels to display program output you
may want to try the <A href=Fl_Output.html#Fl_Output><TT>Fl_Output</TT></A>
widget. </P>
<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
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.
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>
<P><B>All the following XForms calls are missing:</B></P>
<UL>
<LI><TT>FL_REVISION</TT>, <TT>fl_library_version()</TT></LI>
<LI><TT>FL_RETURN_DBLCLICK</TT> (use <TT>Fl::event_clicks()</TT>) </LI>
<LI><TT>fl_add_signal_callback()</TT></LI>
<LI><TT>fl_set_form_atactivate()</TT> <TT>fl_set_form_atdeactivate()</TT>
</LI>
<LI><TT>fl_set_form_property()</TT></LI>
<LI><TT>fl_set_app_mainform()</TT>, <TT>fl_get_app_mainform()</TT></LI>
<LI><TT>fl_set_form_minsize()</TT>, <TT>fl_set_form_maxsize()</TT></LI>
<LI><TT>fl_set_form_event_cmask()</TT>, <TT>fl_get_form_event_cmask()</TT>
</LI>
<LI><TT>fl_set_form_dblbuffer()</TT>, <TT>fl_set_object_dblbuffer()</TT>
(use an <TT>Fl_Double_Window</TT> instead) </LI>
<LI><TT>fl_adjust_form_size()</TT></LI>
<LI><TT>fl_register_raw_callback()</TT></LI>
<LI><TT>fl_set_object_bw()</TT>, <TT>fl_set_border_width()</TT></LI>
<LI><TT>fl_set_object_resize()</TT>, <TT>fl_set_object_gravity()</TT></LI>
<LI><TT>fl_set_object_shortcutkey()</TT></LI>
<LI><TT>fl_set_object_automatic()</TT></LI>
<LI><TT>fl_get_object_bbox()</TT> (maybe FLTK should do this) </LI>
<LI><TT>fl_set_object_prehandler()</TT>, <TT>fl_set_object_posthandler()</TT>
</LI>
<LI><TT>fl_enumerate_fonts()</TT></LI>
<LI>Most drawing functions </LI>
<LI><TT>fl_set_coordunit()</TT> (FLTK uses pixels all the time) </LI>
<LI><TT>fl_ringbell()</TT></LI>
<LI><TT>fl_gettime()</TT></LI>
<LI><TT>fl_win*()</TT> (all these functions) </LI>
<LI><TT>fl_initialize(argc,argv,x,y,z)</TT> ignores last 3 arguments </LI>
<LI><TT>fl_read_bitmapfile()</TT>, <TT>fl_read_pixmapfile()</TT></LI>
<LI><TT>fl_addto_browser_chars()</TT></LI>
<LI><TT>FL_MENU_BUTTON</TT> just draws normally </LI>
<LI><TT>fl_set_bitmapbutton_file()</TT>, <TT>fl_set_pixmapbutton_file()</TT>
</LI>
<LI><TT>FL_CANVAS</TT> objects </LI>
<LI><TT>FL_DIGITAL_CLOCK</TT> (comes out analog) </LI>
<LI><TT>fl_create_bitmap_cursor()</TT>, <TT>fl_set_cursor_color()</TT></LI>
<LI><TT>fl_set_dial_angles()</TT></LI>
<LI><TT>fl_show_oneliner()</TT></LI>
<LI><TT>fl_set_choice_shortcut(a,b,c) </TT></LI>
<LI>command log </LI>
<LI>Only some of file selector is emulated </LI>
<LI><TT>FL_DATE_INPUT</TT></LI>
<LI><TT>fl_pup*()</TT> (all these functions) </LI>
<LI>textbox object (should be easy but I had no sample programs) </LI>
<LI>xyplot object </LI>
</UL>
<H2>Additional Notes</H2>
These notes were written for porting programs written with the older
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.
<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,
periodically calling Forms to check if the user hit buttons on the
panels. If the user did things to the IRISGL window, you would find
this out by having the value FL_EVENT returned from the call to Forms.
<P>None of this works with FLTK. Nor will it compile, the necessary
calls are not in the interface. </P>
<P>You have to make a subclass of <A href=Fl_Gl_Window.html#Fl_Gl_Window>
<TT>Fl_Gl_Window</TT></A> and write a <TT>draw()</TT> method and <TT>
handle()</TT> method. This may require anywhere from a trivial to a
major rewrite. </P>
<P>If you draw into the overlay planes you will have to also write a <TT>
draw_overlay()</TT> method and call <TT>redraw_overlay()</TT> on the
OpenGL window. </P>
<P>One easy way to hack your program so it works is to make the <TT>
draw()</TT> and <TT>handle()</TT> methods on your window set some
static variables, storing what event happened. Then in the main loop
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
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>
Programs that call <TT>fl_make_object</TT> or directly setting the
handle routine will not compile. You have to rewrite them to use a
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
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>
<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:
<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>
<TR><TD>MOUSE_Y</TD><TD>Fl::event_y_root()</TD></TR>
<TR><TD>LEFTSHIFTKEY,RIGHTSHIFTKEY</TD><TD>Fl::event_shift()</TD></TR>
<TR><TD>CAPSLOCKKEY</TD><TD>Fl::event_capslock()</TD></TR>
<TR><TD>LEFTCTRLKEY,RIGHTCTRLKEY</TD><TD>Fl::event_ctrl()</TD></TR>
<TR><TD>LEFTALTKEY,RIGHTALTKEY</TD><TD>Fl::event_alt()</TD></TR>
<TR><TD>MOUSE1,RIGHTMOUSE</TD><TD>Fl::event_state()</TD></TR>
<TR><TD>MOUSE2,MIDDLEMOUSE</TD><TD>Fl::event_state()</TD></TR>
<TR><TD>MOUSE3,LEFTMOUSE</TD><TD>Fl::event_state()</TD></TR>
</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
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>
*/
documentation/glut.dox
+193
View File
@@ -0,0 +1,193 @@
/**
\page glut D - GLUT Compatibility
<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><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>
<H2>Known Problems</H2>
<P>The following functions and/or arguments to functions are missing, and
you will have to replace them or comment them out for your code to
compile:
<UL>
<LI><TT>glutGet(GLUT_ELAPSED_TIME)</TT></LI>
<LI><TT>glutGet(GLUT_SCREEN_HEIGHT_MM)</TT></LI>
<LI><TT>glutGet(GLUT_SCREEN_WIDTH_MM)</TT></LI>
<LI><TT>glutGet(GLUT_WINDOW_NUM_CHILDREN)</TT></LI>
<LI><TT>glutInitDisplayMode(GLUT_LUMINANCE)</TT></LI>
<LI><TT>glutLayerGet(GLUT_HAS_OVERLAY)</TT></LI>
<LI><TT>glutLayerGet(GLUT_LAYER_IN_USE)</TT></LI>
<LI><TT>glutPushWindow()</TT></LI>
<LI><TT>glutSetColor(), glutGetColor(), glutCopyColormap()</TT></LI>
<LI><TT>glutVideoResize()</TT> missing. </LI>
<LI><TT>glutWarpPointer()</TT></LI>
<LI><TT>glutWindowStatusFunc()</TT></LI>
<LI>Spaceball, buttonbox, dials, and tablet functions</LI>
</UL>
Most of the symbols/enumerations have different values than GLUT uses.
This will break code that relies on the actual values. The only
symbols guaranteed to have the same values are true/false pairs like <TT>
GLUT_DOWN</TT> and <TT>GLUT_UP</TT>, mouse buttons <TT>
GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, GLUT_RIGHT_BUTTON</TT>, and <TT>
GLUT_KEY_F1</TT> thru <TT>F12</TT>.
<P>The strings passed as menu labels are not copied. </P>
<P><TT>glutPostRedisplay()</TT> does not work if called from inside a
display function. You must use <TT>glutIdleFunc()</TT> if you want
your display to update continuously. </P>
<P><TT>glutSwapBuffers()</TT> does not work from inside a display
function. This is on purpose, because FLTK swaps the buffers for you. </P>
<P><TT>glutUseLayer()</TT> does not work well, and should only be used
to initialize transformations inside a resize callback. You should
redraw overlays by using <TT>glutOverlayDisplayFunc()</TT>. </P>
<P>Overlays are cleared before the overlay display function is called. <TT>
glutLayerGet(GLUT_OVERLAY_DAMAGED)</TT> always returns true for
compatibility with some GLUT overlay programs. You must rewrite your
code so that <TT>gl_color()</TT> is used to choose colors in an
overlay, or you will get random overlay colors. </P>
<P><TT>glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR)</TT> just results in a
small crosshair. </P>
<P>The fonts used by <TT>glutBitmapCharacter() and glutBitmapWidth()</TT>
may be different. </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>
<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>
'ing the window at the point it is created, which means the <TT>
Fl_Window</TT> parent window must already be shown.
<UL>
<LI>Don't call <TT>glutInit()</TT>. </LI>
<LI>Create your <TT>Fl_Window</TT>, and any FLTK widgets. Leave a
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
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>
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>
</UL>
<HR break>
<H2><A name=Fl_Glut_Window>class Fl_Glut_Window</A></H2>
<HR>
<H3>Class Hierarchy</H3>
<UL>
<PRE>
<A href=Fl_Gl_Window.html#Fl_Gl_Window>Fl_Gl_Window</A>
|
+----<B>Fl_Glut_Window</B>
</PRE>
</UL>
<H3>Include Files</H3>
<UL>
<PRE>
#include &lt;FL/glut.H&gt;
</PRE>
</UL>
<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.
These may be created without opening the display, and thus can fit
better into FLTK's method of creating windows.
<P>The current GLUT window is available in the global variable <TT>
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>
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>
again to set the context. </P>
<P><TT>~Fl_Glut_Window()</TT> is the same as <TT>glutDestroyWindow()</TT>
. </P>
<H3>Members</H3>
The <TT>Fl_Glut_Window</TT> class contains several public members that can
be altered directly:
<CENTER><TABLE WIDTH="80%" BORDER="1" ALT="Fl_Glut_Window public members.">
<TR>
<TH>member</TH>
<TH>description</TH>
</TR>
<TR>
<TD>display</TD>
<TD>A pointer to the function to call to draw the normal planes.</TD>
</TR>
<TR>
<TD>entry</TD>
<TD>A pointer to the function to call when the mouse moves into
or out of the window.</TD>
</TR>
<TR>
<TD>keyboard</TD>
<TD>A pointer to the function to call when a regular key is pressed.</TD>
</TR>
<TR>
<TD>menu[3]</TD>
<TD>The menu to post when one of the mouse buttons is pressed.</TD>
</TR>
<TR>
<TD>mouse</TD>
<TD>A pointer to the function to call when a button is pressed or
released.</TD>
</TR>
<TR>
<TD>motion</TD>
<TD>A pointer to the function to call when the mouse is moved with
a button down.</TD>
</TR>
<TR>
<TD>overlaydisplay</TD>
<TD>A pointer to the function to call to draw the overlay planes.</TD>
</TR>
<TR>
<TD>passivemotion</TD>
<TD>A pointer to the function to call when the mouse is moved with
no buttons down.</TD>
</TR>
<TR>
<TD>reshape</TD>
<TD>A pointer to the function to call when the window is resized.</TD>
</TR>
<TR>
<TD>special</TD>
<TD>A pointer to the function to call when a special key is pressed.</TD>
</TR>
<TR>
<TD>visibility</TD>
<TD>A pointer to the function to call when the window is iconified
or restored (made visible.)</TD>
</TR>
</TABLE></CENTER>
<H3>Methods</H3>
<UL>
<LI><A href=#Fl_Glut_Window.Fl_Glut_Window>Fl_Glut_Window</A></LI>
<LI><A href=#Fl_Glut_Window.~Fl_Glut_Window>~Fl_Glut_Window</A></LI>
<LI><A href=#Fl_Glut_Window.make_current>make_current</A></LI>
</UL>
<H4><A name=Fl_Glut_Window.Fl_Glut_Window>
Fl_Glut_Window::Fl_Glut_Window(int x, int y, int w, int h, const char
*title = 0)
<BR> Fl_Glut_Window::Fl_Glut_Window(int w, int h, const char *title = 0)</A>
</H4>
The first constructor takes 4 int arguments to create the window with
a preset position and size. The second constructor with 2 arguments
will create the window with a preset size, but the window manager will
choose the position according to it's own whims.
<H4><A name=Fl_Glut_Window.~Fl_Glut_Window>virtual
Fl_Glut_Window::~Fl_Glut_Window()</A></H4>
Destroys the GLUT window.
<H4><A name="Fl_Glut_Window.make_current">void Fl_Glut_Window::make_current()</A></H4>
Switches all drawing functions to the GLUT window.
*/
documentation/index.dox
+53 -55
View File
@@ -19,18 +19,16 @@
<TABLE BGCOLOR="#9f9fef" CELLPADDING="8" CELLSPACING="0" SUMMARY="Table of Contents" WIDTH="700">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP"><B>
<TD ALIGN="LEFT" VALIGN="TOP">
\subpage preface
</B>
<BR>
<BR>
<B><A HREF="intro.html#intro">1 - Introduction to FLTK</A></B>
<BR>
<BR>
<B><A HREF="basics.html#basics">2 - FLTK Basics</A></B>
<BR>
<BR>
<B><A HREF="common.html#common">3 - Common Widgets and Attributes</A></B>
\subpage intro
\subpage basics
\subpage common
<B>
<UL>
<LI><A HREF="drawing.html#colors">Colors</A></LI>
<LI><A HREF="common.html#boxtypes">Box Types</A></LI>
@@ -38,66 +36,66 @@
<LI><A HREF="drawing.html#images">Images</A></LI>
<LI><A HREF="Fl_Pixmap.html#Fl_Pixmap">class Fl_Pixmap</A></LI>
</UL>
<B><A HREF="editor.html#editor">4 - Designing a Simple Text Editor</A></B>
<BR>
<BR>
<B><A HREF="drawing.html#drawing">5 - Drawing Things in FLTK</A></B>
<BR>
<BR>
<B><A HREF="events.html#events">6 - Handling Events</A></B>
</B>
\subpage editor
\subpage drawing
\subpage events
<B>
<UL>
<LI><A HREF="events.html#event_xxx">Fl::event_*() methods</A></LI>
<LI><A HREF="events.html#propagation">Event Propagation</A></LI>
</UL>
<B><A HREF="subclassing.html#subclassing">7 - Adding and Extending
Widgets</A></B>
<BR>
<BR>
<B><A HREF="opengl.html#opengl">8 - Using OpenGL</A></B>
</B>
\subpage subclassing
\subpage opengl
</TD>
<TD ALIGN=LEFT VALIGN=TOP>
<B><A HREF="fluid.html#FLUID">9 - Programming with FLUID</A></B>
\subpage fluid
<B>
<UL>
<LI><A HREF="fluid.html#widget_attributes">Widget Attributes</A></LI>
<LI><A HREF="fluid.html#widget_attributes">Selecting Moving Widgets</A></LI>
<LI><A HREF="fluid.html#images">Image Labels</A></LI>
</UL>
<B>
\subpage advanced
</B>
<BR>
<BR>
<B><A HREF="classes.html">A - Class Reference</A></B>
<BR>
<BR>
<B><A HREF="globals_func.html">B - Function Reference</A></B>
<BR>
<BR>
<B><A HREF="enumerations.html#Enumerations">C - FLTK Enumerations.H</A>
</B>
<BR>
<BR>
<B><A HREF="glut.html#glut">D - GLUT Compatibility</A></B>
\subpage advanced
<B><A HREF="classes.html">A - Class Reference</A></B>
<B><A HREF="globals_func.html">B - Function Reference</A></B>
\subpage enumerations
\subpage glut
<B>
<UL>
<LI><A HREF="glut.html#Fl_Glut_Window">class Fl_Glut_Window</A></LI>
</UL>
<B><A HREF="forms.html#forms">E - Forms Compatibility</A></B>
<BR>
<BR>
<B><A HREF="osissues.html#osissues">F - Operating System Issues</A></B>
<BR>
<BR>
<B><A HREF="migration.html">G - Migrating Code from FLTK 1.0.x</A></B>
<BR>
<BR>
<B><A HREF="license.html#license">H - Software License</A></B>
<BR>
<BR>
<B><A HREF="examples.html#examples">I - Example Source Code</A></B>
</TD>
</B>
\subpage forms
\subpage osissues
\subpage migration_1_1
\subpage migration_1_3
\subpage license
\subpage examples
</TD>
</TR>
</TABLE>
*/
documentation/intro.dox
+367
View File
@@ -0,0 +1,367 @@
/**
\page intro 1 - Introduction to FLTK
<P>The Fast Light Tool Kit (&quot;FLTK&quot;, pronounced
&quot;fulltick&quot;) is a cross-platform C++ GUI toolkit for
UNIX&reg;/Linux&reg; (X11), Microsoft&reg; Windows&reg;, and
MacOS&reg; X. FLTK provides modern GUI functionality without the
bloat and supports 3D graphics via OpenGL&reg; and its built-in
GLUT emulation. It was originally developed by Mr. Bill Spitzak
and is currently maintained by a small group of developers
across the world with a central repository in the US.</P>
<H2>History of FLTK</H2>
<P>It has always been Bill's belief that the GUI API of all
modern systems is much too high level. Toolkits (even FLTK) are
<I>not</I> what should be provided and documented as part of an
operating system. The system only has to provide arbitrary
shaped but featureless windows, a powerful set of graphics
drawing calls, and a simple <I>unalterable</I> method of
delivering events to the owners of the windows. NeXT (if you
ignored NextStep) provided this, but they chose to hide it and
tried to push their own baroque toolkit instead.</P>
<P>Many of the ideas in FLTK were developed on a NeXT (but
<I>not</I> using NextStep) in 1987 in a C toolkit Bill called
&quot;views&quot;. Here he came up with passing events downward
in the tree and having the handle routine return a value
indicating whether it used the event, and the table-driven menus. In
general he was trying to prove that complex UI ideas could be
entirely implemented in a user space toolkit, with no knowledge
or support by the system.</P>
<P>After going to film school for a few years, Bill worked at
Sun Microsystems on the (doomed) NeWS project. Here he found an
even better and cleaner windowing system, and he reimplemented
&quot;views&quot; atop that. NeWS did have an unnecessarily
complex method of delivering events which hurt it. But the
designers did admit that perhaps the user could write just as
good of a button as they could, and officially exposed the lower
level interface.</P>
<P>With the death of NeWS Bill realized that he would have to
live with X. The biggest problem with X is the &quot;window
manager&quot;, which means that the toolkit can no longer
control the window borders or drag the window around.</P>
<P>At Digital Domain Bill discovered another toolkit,
&quot;Forms&quot;. Forms was similar to his work, but provided
many more widgets, since it was used in many real applications,
rather then as theoretical work. He decided to use Forms, except
he integrated his table-driven menus into it. Several very large
programs were created using this version of Forms.</P>
<P>The need to switch to OpenGL and GLX, portability, and a
desire to use C++ subclassing required a rewrite of Forms.
This produced the first version of FLTK. The conversion to C++
required so many changes it made it impossible to recompile any
Forms objects. Since it was incompatible anyway, Bill decided
to incorporate his older ideas as much as possible by
simplifying the lower level interface and the event passing
mechanisim.</P>
<P>Bill received permission to release it for free on the
Internet, with the GNU general public license. Response from
Internet users indicated that the Linux market dwarfed the SGI
and high-speed GL market, so he rewrote it to use X for all
drawing, greatly speeding it up on these machines. That is the
version you have now.</P>
<P>Digital Domain has since withdrawn support for FLTK. While
Bill is no longer able to actively develop it, he still
contributes to FLTK in his free time and is a part of the FLTK
development team.</P>
<H2>Features</H2>
<P>FLTK was designed to be statically linked. This was done by
splitting it into many small objects and designing it so that
functions that are not used do not have pointers to them in the
parts that are used, and thus do not get linked in. This allows
you to make an easy-to-install program or to modify FLTK to
the exact requirements of your application without worrying
about bloat. FLTK works fine as a shared library, though, and
is now included with several Linux distributions.</P>
<P>Here are some of the core features unique to FLTK:</P>
<UL>
<LI>sizeof(Fl_Widget) == 64 to 92.</LI>
<LI>The &quot;core&quot; (the &quot;hello&quot; program
compiled &amp; linked with a static FLTK library using
gcc on a 486 and then stripped) is 114K.</LI>
<LI>The FLUID program (which includes every widget) is
538k.</LI>
<LI>Written directly atop core libraries (Xlib, WIN32 or
Carbon) for maximum speed, and carefully optimized for
code size and performance.</LI>
<LI>Precise low-level compatability between the X11,
WIN32 and MacOS versions - only about 10% of the code is
different.</LI>
<LI>Interactive user interface builder program. Output is
human-readable and editable C++ source code.</LI>
<LI>Support for overlay hardware, with emulation if none
is available.</LI>
<LI>Very small &amp; fast portable 2-D drawing library
to hide Xlib, WIN32, or QuickDraw.</LI>
<LI>OpenGL/Mesa drawing area widget.</LI>
<LI>Support for OpenGL overlay hardware on both X11 and
WIN32, with emulation if none is available.</LI>
<LI>Text widgets with Emacs key bindings, X cut &amp;
paste, and foreign letter compose!</LI>
<LI>Compatibility header file for the GLUT library.</LI>
<LI>Compatibility header file for the XForms library.</LI>
</UL>
<H2>Licensing</H2>
<P>FLTK comes with complete free source code. FLTK is available
under the terms of the <A href="license.html">GNU Library
General Public License</A> with exceptions that allow for static
linking. Contrary to popular belief, it can be used in
commercial software - even Bill Gates could use it!</P>
<H2>What Does &quot;FLTK&quot; Mean?</H2>
<P>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 the name of the library.
It is almost impossible to search for &quot;FL&quot; on the
Internet, due to the fact that it is also the abbreviation for
Florida. After much debating and searching for a new name for
the toolkit, which was already in use by several people, Bill
came up with &quot;FLTK&quot;, including a bogus excuse that it
stands for &quot;The Fast Light Toolkit&quot;.</P>
<H2>Building and Installing FLTK Under UNIX and MacOS X</H2>
<P>In most cases you can just type &quot;make&quot;. This will
run configure with the default of no options and then compile
everything.</P>
<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 and OpenGL (or Mesa) 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>
<P>For C shell and tcsh, use:</P>
<UL><PRE>
setenv CFLAGS "-I<I>includedir</I>"
setenv CXXFLAGS "-I<I>includedir</I>"
setenv LDFLAGS "-L<I>libdir</I>"
</PRE></UL>
<P>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:</P>
<UL><PRE>
CXX=xlC; export CXX
setenv CXX "xlC"
</PRE></UL>
<P>The <tt>CC</tt> environment variable can also be used to
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 &quot;./configure &lt;options&gt;&quot;, where
options are:</P>
<DL>
<DT>--enable-cygwin</DT>
<DD>Enable the Cygwin libraries under WIN32</DD>
<DT>--enable-debug</DT>
<DD>Enable debugging code &amp; symbols</DD>
<DT>--disable-gl</DT>
<DD>Disable OpenGL support</DD>
<DT>--enable-shared</DT>
<DD>Enable generation of shared libraries</DD>
<DT>--enable-threads</DT>
<DD>Enable multithreading support</DD>
<DT>--enable-xdbe</DT>
<DD>Enable the X double-buffer extension</DD>
<DT>--enable-xft</DT>
<DD>Enable the Xft library for anti-aliased fonts under X11</DD>
<DT>--bindir=/path</DT>
<DD>Set the location for executables [default = $prefix/bin]</DD>
<DT>--datadir=/path</DT>
<DD>Set the location for data files. [default = $prefix/share]</DD>
<DT>--libdir=/path</DT>
<DD>Set the location for libraries [default = $prefix/lib]</DD>
<DT>--includedir=/path</DT>
<DD>Set the location for include files. [default = $prefix/include]</DD>
<DT>--mandir=/path</DT>
<DD>Set the location for man pages. [default = $prefix/man]</DD>
<DT>--prefix=/dir</DT>
<DD>Set the directory prefix for files [default = /usr/local]</DD>
</DL>
<P>When the configure script is done you can just run the
&quot;make&quot; command. This will build the library, FLUID
tool, and all of the test programs.</P>
<P>To install the library, become root and type &quot;make
install&quot;. This will copy the &quot;fluid&quot; executable
to &quot;bindir&quot;, the header files to
&quot;includedir&quot;, and the library files to
&quot;libdir&quot;.</P>
<H2>Building FLTK Under Microsoft Windows</H2>
<P>There are three ways to build FLTK under Microsoft Windows.
The first is to use the Visual C++ 5.0 project files under the
&quot;visualc&quot; directory. Just open (or double-click on)
the &quot;fltk.dsw&quot; file to get the whole shebang.</P>
<P>The second method is to use the <TT>configure</TT> script
included with the FLTK software; this has only been tested with
the CygWin tools:</P>
<UL><PRE>
sh configure --prefix=C:/FLTK
make
</PRE></UL>
<P>The final method is to use a GNU-based development tool with
the files in the &quot;makefiles&quot; directory. To build
using one of these tools simply copy the appropriate
makeinclude and config files to the main directory and do a
make:</P>
<UL><PRE>
copy makefiles\Makefile.&lt;env&gt; Makefile
make
</PRE></UL>
<H3>Using the Visual C++ DLL Library</H3>
<P>The &quot;fltkdll.dsp&quot; project file builds a DLL-version
of the FLTK library. Because of name mangling differences
between PC compilers (even between different versions of Visual
C++!) you can only use the DLL that is generated with the same
version compiler that you built it with.</P>
<P>When compiling an application or DLL that uses the FLTK DLL,
you will need to define the <tt>FL_DLL</tt> preprocessor symbol
to get the correct linkage commands embedded within the FLTK
header files.</P>
<H2>Building FLTK Under OS/2</H2>
<P>The current OS/2 build requires XFree86 for OS/2 to work. A
native Presentation Manager version has not been implemented
yet (volunteers are welcome!).</P>
<p>The current set of Makefiles/configuration failes assumes that
EMX 0.9d and libExt
(from <A HREF="http://posix2.sourceforge.net">posix2.sourceforge.net</A>)
is installed.
<P>To build the XFree86 version of FLTK for OS/2, copy the appropriate
makeinclude and config files to the main directory and do a make: </P>
<UL><PRE>
copy makefiles\Makefile.os2x Makefile
make
</PRE></UL>
<H2>Internet Resources</H2>
<P>FLTK is available on the 'net in a bunch of locations:</P>
<DL>
<DT>WWW
<DD><A href="http://www.fltk.org/">http://www.fltk.org/</A>
<DD><A href="http://www.fltk.org/str.php">http://www.fltk.org/str.php</A>
[for reporting bugs]
<DD><A href="http://www.fltk.org/software.php">http://www.fltk.org/software.php</A>
[source code]
<DT>FTP
<DD><A HREF="ftp://ftp.fltk.org/pub/fltk">California, USA (ftp.fltk.org)</A>
<DD><A HREF="ftp://ftp2.fltk.org/pub/fltk">Maryland, USA (ftp2.fltk.org)</A>
<DD><A HREF="ftp://ftp.funet.fi/pub/mirrors/ftp.fltk.org/pub/fltk">Espoo, Finland (ftp.funet.fi)</A>
<DD><A HREF="ftp://linux.mathematik.tu-darmstadt.de/pub/linux/mirrors/misc/fltk">Germany (linux.mathematik.tu-darmstadt.de)</A>
<DD><A HREF="ftp://gd.tuwien.ac.at/hci/fltk">Austria (gd.tuwien.ac.at)</A>
<DT>EMail</DT>
<DD><A href="mailto:fltk@fltk.org">fltk@fltk.org</A> [see
instructions below]
<DD><A href="mailto:fltk-bugs@fltk.org">fltk-bugs@fltk.org</A> [for
reporting bugs]
<DT>NNTP Newsgroups</DT>
<DD>news.easysw.com</DD>
</DL>
<P>To send a message to the FLTK mailing list
(&quot;fltk@fltk.org&quot;) you must first join the list.
Non-member submissions are blocked to avoid problems with
unsolicited email.</P>
<P>To join the FLTK mailing list, send a message to
&quot;majordomo@fltk.org&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; mailing list.</P>
<H2>Reporting Bugs</H2>
<P>To report a bug in FLTK, send an email to
&quot;fltk-bugs@fltk.org&quot;. Please include the FLTK version,
operating system &amp; version, and compiler that you are using
when describing the bug or problem. We will be unable to provide
any kind of help without that basic information.</P>
<P>Bugs can also be reported to the "fltk.bugs" newsgroup or on the
SourceForge bug tracker pages.</P>
<P>For general support and questions, please use the FLTK mailing list
at &quot;fltk@fltk.org&quot; or one of the newsgroups.</P>
*/
documentation/license.dox
+437
View File
@@ -0,0 +1,437 @@
/**
\page license I - Software License
<P ALIGN="RIGHT">December 11, 2001</P>
<P>The FLTK library and included programs are provided under the terms
of the GNU Library General Public License (LGPL) with the following
exceptions:</P>
<OL>
<LI>Modifications to the FLTK configure script, config
header file, and makefiles by themselves to support
a specific platform do not constitute a modified or
derivative work.<BR>
<BR>
The authors do request that such modifications be
contributed to the FLTK project - send all
contributions to "fltk-bugs@fltk.org".<BR>
<BR>
</LI>
<LI>Widgets that are subclassed from FLTK widgets do not
constitute a derivative work.<BR>
<BR>
</LI>
<LI>Static linking of applications and widgets to the
FLTK library does not constitute a derivative work
and does not require the author to provide source
code for the application or widget, use the shared
FLTK libraries, or link their applications or
widgets against a user-supplied version of FLTK.<BR>
<BR>
If you link the application or widget to a modified
version of FLTK, then the changes to FLTK must be
provided under the terms of the LGPL in sections
1, 2, and 4.<BR>
<BR>
</LI>
<LI>You do not have to provide a copy of the FLTK license
with programs that are linked to the FLTK library, nor
do you have to identify the FLTK license in your
program or documentation as required by section 6
of the LGPL.<BR>
<BR>
However, programs must still identify their use of FLTK.
The following example statement can be included in user
documentation to satisfy this requirement:<BR>
<BR>
<I>[program/widget] is based in part on the work of
the FLTK project (http://www.fltk.org).</I></LI>
</OL>
<HR>
<P ALIGN=CENTER><BIG>GNU LIBRARY GENERAL PUBLIC LICENSE</BIG></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
<BR> Everyone is permitted to copy and distribute verbatim copies of
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>
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
software--to make sure the software is free for all its users.
<P>This license, the Library General Public License, applies to some
specially designated Free Software Foundation software, and to any
other libraries whose authors decide to use it. You can use it for
your libraries, too. </P>
<P>When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things. </P>
<P>To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the library, or if you modify it. </P>
<P>For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you. You must make sure that they, too, receive or can get the source
code. If you link a program with the library, you must provide
complete object files to the recipients so that they can relink them
with the library, after making changes to the library and recompiling
it. And you must show them these terms so they know their rights. </P>
<P>Our method of protecting your rights has two steps: (1) copyright
the library, and (2) offer you this license which gives you legal
permission to copy, distribute and/or modify the library. </P>
<P>Also, for each distributor's protection, we want to make certain
that everyone understands that there is no warranty for this free
library. If the library is modified by someone else and passed on, we
want its recipients to know that what they have is not the original
version, so that any problems introduced by others will not reflect on
the original authors' reputations. </P>
<P>Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that companies distributing free
software will individually obtain patent licenses, thus in effect
transforming the program into proprietary software. To prevent this,
we have made it clear that any patent must be licensed for everyone's
free use or not licensed at all. </P>
<P>Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License, which was designed for utility
programs. This license, the GNU Library General Public License,
applies to certain designated libraries. This license is quite
different from the ordinary one; be sure to read it in full, and don't
assume that anything in it is the same as in the ordinary license. </P>
<P>The reason we have a separate public license for some libraries is
that they blur the distinction we usually make between modifying or
adding to a program and simply using it. Linking a program with a
library, without changing the library, is in some sense simply using
the library, and is analogous to running a utility program or
application program. However, in a textual and legal sense, the linked
executable is a combined work, a derivative of the original library,
and the ordinary General Public License treats it as such. </P>
<P>Because of this blurred distinction, using the ordinary General
Public License for libraries did not effectively promote software
sharing, because most developers did not use the libraries. We
concluded that weaker conditions might promote sharing better. </P>
<P>However, unrestricted linking of non-free programs would deprive the
users of those programs of all benefit from the free status of the
libraries themselves. This Library General Public License is intended
to permit developers of non-free programs to use free libraries, while
preserving your freedom as a user of such programs to change the free
libraries that are incorporated in them. (We have not seen how to
achieve this as regards changes in header files, but we have achieved
it as regards changes in the actual functions of the Library.) The
hope is that this will lead to faster development of free libraries. </P>
<P>The precise terms and conditions for copying, distribution and
modification follow. Pay close attention to the difference between a
&quot;work based on the libary&quot; and a &quot;work that uses the library&quot;. The
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>
<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
Library General Public License (also called &quot;this License&quot;). Each
licensee is addressed as &quot;you&quot;.
<P>A &quot;library&quot; means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables. </P>
<P>The &quot;Library&quot;, below, refers to any such software library or work
which has been distributed under these terms. A &quot;work based on the
Library&quot; means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language. (Hereinafter, translation is
included without limitation in the term &quot;modification&quot;.) </P>
<P>&quot;Source code&quot; for a work means the preferred form of the work for
making modifications to it. For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control
compilation and installation of the library. </P>
<P>Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it). Whether that is true depends on what the Library does and
what the program that uses the Library does. </P>
<P><STRONG>1.</STRONG> You may copy and distribute verbatim copies of
the Library's complete source code as you receive it, in any medium,
provided that you conspicuously and appropriately publish on each copy
an appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the Library. </P>
<P>You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
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>
<STRONG>a)</STRONG> The modified work must itself be a software
library.
<P><STRONG>b)</STRONG> You must cause the files modified to carry
prominent notices stating that you changed the files and the date of
any change. </P>
<P><STRONG>c)</STRONG> You must cause the whole of the work to be
licensed at no charge to all third parties under the terms of this
License. </P>
<P><STRONG>d)</STRONG> If a facility in the modified Library refers to
a function or a table of data to be supplied by an application program
that uses the facility, other than as an argument passed when the
facility is invoked, then you must make a good faith effort to ensure
that, in the event an application does not supply such function or
table, the facility still operates, and performs whatever part of its
purpose remains meaningful. </P>
<P>(For example, a function in a library to compute square roots has a
purpose that is entirely well-defined independent of the application.
Therefore, Subsection 2d requires that any application-supplied
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
works in themselves, then this License, and its terms, do not apply to
those sections when you distribute them as separate works. But when
you distribute the same sections as part of a whole which is a work
based on the Library, the distribution of the whole must be on the
terms of this License, whose permissions for other licensees extend to
the entire whole, and thus to each and every part regardless of who
wrote it. </P>
<P>Thus, it is not the intent of this section to claim rights or
contest your rights to work written entirely by you; rather, the intent
is to exercise the right to control the distribution of derivative or
collective works based on the Library. </P>
<P>In addition, mere aggregation of another work not based on the
Library with the Library (or with a work based on the Library) on a
volume of a storage or distribution medium does not bring the other
work under the scope of this License. </P>
<P><STRONG>3.</STRONG> You may opt to apply the terms of the ordinary
GNU General Public License instead of this License to a given copy of
the Library. To do this, you must alter all the notices that refer to
this License, so that they refer to the ordinary GNU General Public
License, version 2, instead of to this License. (If a newer version
than version 2 of the ordinary GNU General Public License has appeared,
then you can specify that version instead if you wish.) Do not make
any other change in these notices. </P>
<P>Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy. </P>
<P>This option is useful when you wish to copy part of the code of the
Library into a program that is not a library. </P>
<P><STRONG>4.</STRONG> You may copy and distribute the Library (or a
portion or derivative of it, under Section 2) in object code or
executable form under the terms of Sections 1 and 2 above provided that
you accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections 1
and 2 above on a medium customarily used for software interchange. </P>
<P>If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to distribute
the source code, even though third parties are not compelled to copy
the source along with the object code. </P>
<P><STRONG>5.</STRONG> A program that contains no derivative of any
portion of the Library, but is designed to work with the Library by
being compiled or linked with it, is called a &quot;work that uses the
Library&quot;. Such a work, in isolation, is not a derivative work of the
Library, and therefore falls outside the scope of this License. </P>
<P>However, linking a &quot;work that uses the Library&quot; with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a &quot;work that uses the
library&quot;. The executable is therefore covered by this License. Section
6 states terms for distribution of such executables. </P>
<P>When a &quot;work that uses the Library&quot; uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library. The
threshold for this to be true is not precisely defined by law. </P>
<P>If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work. (Executables containing this object code plus portions of the
Library will still fall under Section 6.) </P>
<P>Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6, whether
or not they are linked directly with the Library itself. </P>
<P><STRONG>6.</STRONG> As an exception to the Sections above, you may
also compile or link a &quot;work that uses the Library&quot; with the Library to
produce a work containing portions of the Library, and distribute that
work under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications. </P>
<P>You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
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
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
executable linked with the Library, with the complete machine-readable
&quot;work that uses the Library&quot;, as object code and/or source code, so
that the user can modify the Library and then relink to produce a
modified executable containing the modified Library. (It is
understood that the user who changes the contents of definitions files
in the Library will not necessarily be able to recompile the
application to use the modified definitions.)
<P><STRONG>b)</STRONG> Accompany the work with a written offer, valid
for at least three years, to give the same user the materials
specified in Subsection 6a, above, for a charge no more than the cost
of performing this distribution. </P>
<P><STRONG>c)</STRONG> If distribution of the work is made by offering
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,
the source code distributed need not include anything that is normally
distributed (in either source or binary form) with the major components
(compiler, kernel, and so on) of the operating system on which the
executable runs, unless that component itself accompanies the
executable.</P>
<P>It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system. Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute. </P>
<P><STRONG>7.</STRONG> You may place library facilities that are a work
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>
<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
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
with, or distribute the Library is void, and will automatically
terminate your rights under this License. However, parties who have
received copies, or rights, from you under this License will not have
their licenses terminated so long as such parties remain in full
compliance. </P>
<P><STRONG>9.</STRONG> You are not required to accept this License,
since you have not signed it. However, nothing else grants you
permission to modify or distribute the Library or its derivative works.
These actions are prohibited by law if you do not accept this License.
Therefore, by modifying or distributing the Library (or any work based
on the Library), you indicate your acceptance of this License to do so,
and all its terms and conditions for copying, distributing or modifying
the Library or works based on it. </P>
<P><STRONG>10.</STRONG> Each time you redistribute the Library (or any
work based on the Library), the recipient automatically receives a
license from the original licensor to copy, distribute, link with or
modify the Library subject to these terms and conditions. You may not
impose any further restrictions on the recipients' exercise of the
rights granted herein. You are not responsible for enforcing compliance
by third parties to this License. </P>
<P><STRONG>11.</STRONG> If, as a consequence of a court judgment or
allegation of patent infringement or for any other reason (not limited
to patent issues), conditions are imposed on you (whether by court
order, agreement or otherwise) that contradict the conditions of this
License, they do not excuse you from the conditions of this License.
If you cannot distribute so as to satisfy simultaneously your
obligations under this License and any other pertinent obligations,
then as a consequence you may not distribute the Library at all. For
example, if a patent license would not permit royalty-free
redistribution of the Library by all those who receive copies directly
or indirectly through you, then the only way you could satisfy both it
and this License would be to refrain entirely from distribution of the
Library. </P>
<P>If any portion of this section is held invalid or unenforceable
under any particular circumstance, the balance of the section is
intended to apply, and the section as a whole is intended to apply in
other circumstances. </P>
<P>It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is implemented
by public license practices. Many people have made generous
contributions to the wide range of software distributed through that
system in reliance on consistent application of that system; it is up
to the author/donor to decide if he or she is willing to distribute
software through any other system and a licensee cannot impose that
choice. </P>
<P>This section is intended to make thoroughly clear what is believed
to be a consequence of the rest of this License. </P>
<P><STRONG>12.</STRONG> If the distribution and/or use of the Library
is restricted in certain countries either by patents or by copyrighted
interfaces, the original copyright holder who places the Library under
this License may add an explicit geographical distribution limitation
excluding those countries, so that distribution is permitted only in or
among countries not thus excluded. In such case, this License
incorporates the limitation as if written in the body of this License. </P>
<P><STRONG>13.</STRONG> The Free Software Foundation may publish
revised and/or new versions of the Library General Public License from
time to time. Such new versions will be similar in spirit to the
present version, but may differ in detail to address new problems or
concerns. </P>
<P>Each version is given a distinguishing version number. If the
Library specifies a version number of this License which applies to it
and &quot;any later version&quot;, you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation. </P>
<P><STRONG>14.</STRONG> If you wish to incorporate parts of the Library
into other free programs whose distribution conditions are incompatible
with these, write to the author to ask for permission. For software
which is copyrighted by the Free Software Foundation, write to the Free
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><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
HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY &quot;AS IS&quot; WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU
ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. </P>
<P><STRONG>16.</STRONG> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW
OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY
WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL
OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
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>
*/
documentation/migration_1_1.dox
+158
View File
@@ -0,0 +1,158 @@
/**
\page migration_1_1 G - Migrating Code from FLTK 1.0 to 1.1
<P>This appendix describes the differences between the FLTK
1.0.x and FLTK 1.1.x functions and classes.</P>
<H2>Color Values</H2>
<P>Color values are now stored in a 32-bit unsigned integer
instead of the unsigned character in 1.0.x. This allows for the
specification of 24-bit RGB values or 8-bit FLTK color indices.
<P><TT>FL_BLACK</TT> and <TT>FL_WHITE</TT> now remain black and
white, even if the base color of the gray ramp is changed using
<A HREF="Fl.html#Fl.background"><TT>Fl::background()</TT></A>.
<TT>FL_DARK3</TT> and <TT>FL_LIGHT3</TT> can be used instead to
draw a very dark or a very bright background hue.</P>
<P>Widgets use the new color symbols <TT>FL_FORGROUND_COLOR</TT>,
<TT>FL_BACKGROUND_COLOR</TT>, <TT>FL_BACKGROUND2_COLOR</TT>,
<TT>FL_INACTIVE_COLOR</TT>, and <TT>FL_SELECTION_COLOR</TT>.
More details can be found in the chapter
<A HREF="enumerations.html#colors">Enumerations</A>.</P>
<H2>Cut and Paste Support</H2>
<P>The FLTK clipboard is now broken into two parts - a local
selection value and a cut-and-paste value. This allows FLTK to
support things like highlighting and replacing text that was
previously cut or copied, which makes FLTK applications behave
like traditional GUI applications.
<H2>File Chooser</H2>
<P>The file chooser in FLTK 1.1.x is significantly different
than the one supplied with FLTK 1.0.x. Any code that directly
references the old <TT>FCB</TT> class or members will need
to be ported to the new <A
HREF="Fl_File_Chooser.html"><TT>Fl_File_Chooser</TT></A>
class.</P>
<H2>Function Names</H2>
<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>
symbol on the command-line when you compile
(<CODE>-DFLTK_1_0_COMPAT</CODE>) or in your source, e.g.:
<UL><PRE>
#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>
<P>The following table shows the old and new function names:</P>
<CENTER><TABLE WIDTH="80%" BORDER="1">
<TR>
<TH>Old 1.0.x Name</TH>
<TH>New 1.1.x Name</TH>
</TR>
<TR>
<TD>contrast()</TD>
<TD>fl_contrast()</TD>
</TR>
<TR>
<TD>down()</TD>
<TD>fl_down()</TD>
</TR>
<TR>
<TD>filename_absolute()</TD>
<TD>fl_filename_absolute()</TD>
</TR>
<TR>
<TD>filename_expand()</TD>
<TD>fl_filename_expand()</TD>
</TR>
<TR>
<TD>filename_ext()</TD>
<TD>fl_filename_ext()</TD>
</TR>
<TR>
<TD>filename_isdir()</TD>
<TD>fl_filename_isdir()</TD>
</TR>
<TR>
<TD>filename_list()</TD>
<TD>fl_filename_list()</TD>
</TR>
<TR>
<TD>filename_match()</TD>
<TD>fl_filename_match()</TD>
</TR>
<TR>
<TD>filename_name()</TD>
<TD>fl_filename_name()</TD>
</TR>
<TR>
<TD>filename_relative()</TD>
<TD>fl_filename_relative()</TD>
</TR>
<TR>
<TD>filename_setext()</TD>
<TD>fl_filename_setext()</TD>
</TR>
<TR>
<TD>frame()</TD>
<TD>fl_frame()</TD>
</TR>
<TR>
<TD>inactive()</TD>
<TD>fl_inactive()</TD>
</TR>
<TR>
<TD>numericsort()</TD>
<TD>fl_numericsort()</TD>
</TR>
</TABLE></CENTER>
<H2>Image Support</H2>
<P>Image support in FLTK has been significantly revamped in
1.1.x. The <A HREF="Fl_Image.html"><TT>Fl_Image</TT></A> class
is now a proper base class, with the core image drawing
functionality in the <A
HREF="Fl_Bitmap.html"><TT>Fl_Bitmap</TT></A>, <A
HREF="Fl_Pixmap.html"><TT>Fl_Pixmap</TT></A>, and <A
HREF="Fl_RGB_Image.html"><TT>Fl_RGB_Image</TT></A> classes.
<P>BMP, GIF, JPEG, PNG, XBM, and XPM image files can now be
loaded using the appropriate image classes, and the <A
HREF="Fl_Shared_Image.html"><TT>Fl_Shared_Image</TT></A> class
can be used to cache images in memory.
<P>Image labels are no longer provided as an add-on label type.
If you use the old <TT>label()</TT> methods on an image, the
widget's <TT>image()</TT> method is called to set the image
as the label.
<P>Image labels in menu items must still use the old labeltype
mechanism to preserve source compatibility.
<H2>Keyboard Navigation</H2>
<P>FLTK 1.1.x now supports keyboard navigation and control with
all widgets. To restore the old FLTK 1.0.x behavior so that only
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>
Fl::visible_focus(0);
</PRE></UL>
*/
documentation/migration_1_3.dox
+11
View File
@@ -0,0 +1,11 @@
/**
\page migration_1_3 H - Migrating Code from FLTK 1.1 to 1.3
<P>This appendix describes the differences between the FLTK
1.1.x and FLTK 1.3.x functions and classes.</P>
If you want to migrate your code from FLTK 1.0 to FLTK 1.3,
then you should also consult Appendix \ref migration_1_1.
*/
documentation/opengl.dox
+463
View File
@@ -0,0 +1,463 @@
/**
\page opengl 8 - Using OpenGL
<P>This chapter discusses using FLTK for your OpenGL applications.
<H2>Using OpenGL in FLTK</H2>
<P>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 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 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>
<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 file needed by WIN32
applications.</P>
<H2>Making a Subclass of Fl_Gl_Window</H2>
<P>To make a subclass of Fl_Gl_Window, you must provide:
<UL>
<LI>A class definition.</LI>
<LI>A <TT>draw()</TT> method.</LI>
<LI>A <TT>handle()</TT> method if you need to receive
input from the user.</LI>
</UL>
<P>If your subclass provides static controls in the window, they
must be redrawn whenever the <tt>FL_DAMAGE_ALL</tt> bit is set
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>
#ifndef MESA
glDrawBuffer(GL_FRONT_AND_BACK);
#endif // !MESA
... draw stuff here ...
#ifndef MESA
glDrawBuffer(GL_BACK);
#endif // !MESA
</PRE></UL>
<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
<TR>
<TD><B>Note:</B>
<P>If you are using the Mesa graphics library, the call
to <tt>glDrawBuffer()</tt> is not required and will slow
down drawing considerably. The preprocessor instructions
shown above will optimize your code based upon the
graphics library used.
</TD>
</TR>
</TABLE></CENTER>
<H3>Defining the Subclass</H3>
<P>To define the subclass you just subclass the
<TT>Fl_Gl_Window</TT> class:
<UL><PRE>
class MyWindow : public Fl_Gl_Window {
void draw();
int handle(int);
public:
MyWindow(int X, int Y, int W, int H, const char *L)
: Fl_Gl_Window(X, Y, W, H, L) {}
};
</PRE></UL>
<P>The <TT>draw()</TT> and <TT>handle()</TT> methods are
described below. Like any widget, you can include additional
private and public data in your class (such as scene graph
information, etc.)
<H3>The draw() Method</H3>
<P>The <TT>draw()</TT> method is where you actually do your
OpenGL drawing:
<UL><PRE>
void MyWindow::draw() {
if (!valid()) {
... set up projection, viewport, etc ...
... window size is in w() and h().
... valid() is turned on by FLTK after draw() returns
}
... draw ...
}
</PRE></UL>
<H3>The handle() Method</H3>
<P>The <TT>handle()</TT> method handles mouse and keyboard
events for the window:
<UL><PRE>
int MyWindow::handle(int event) {
switch(event) {
case FL_PUSH:
... mouse down event ...
... position in Fl::event_x() and Fl::event_y()
return 1;
case FL_DRAG:
... mouse moved while down event ...
return 1;
case FL_RELEASE:
... mouse up event ...
return 1;
case FL_FOCUS :
case FL_UNFOCUS :
... Return 1 if you want keyboard events, 0 otherwise
return 1;
case FL_KEYBOARD:
... 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:
// pass other events to the base class...
return Fl_Gl_Window::handle(event);
}
}
</PRE></UL>
<P>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 <I>some</I> OpenGL stuff like hit detection and texture
loading functions by doing: </P>
<UL><PRE>
case FL_PUSH:
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
}
... ok to call NON-DRAWING OpenGL code here, such as hit
detection, loading textures, etc...
</PRE></UL>
<P>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>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>
<P>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>
<P>You can put OpenGL code into an <A
href="subclassing.html#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 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>
<UL><PRE>
Fl::gl_visual(FL_RGB);
</PRE></UL>
<P>You can then put OpenGL drawing code anywhere you can draw
normally by surrounding it with:
<UL><PRE>
gl_start();
... put your OpenGL code here ...
gl_finish();
</PRE></UL>
<P><A name="gl_start"><TT>gl_start()</TT></A> and <A
name="gl_finish"><TT>gl_finish()</TT></A> set up an OpenGL
context with an orthographic projection so that 0,0 is the
lower-left corner of the window and each pixel is one unit. The
current clipping is reproduced with OpenGL <TT>glScissor()</TT>
commands. These functions also synchronize the OpenGL graphics stream
with the drawing done by other X, WIN32, or FLTK functions.
<P>The same context is reused each time. If your code changes
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
get the 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>
<LI>You must choose a default visual with <A
href="Fl.html#Fl.gl_visual"><TT>Fl::gl_visual()</TT></A>.</LI>
<LI>You cannot pass <TT>FL_DOUBLE</TT> to
<TT>Fl::gl_visual()</TT>.</LI>
<LI>You cannot use <TT>Fl_Double_Window</TT> or
<TT>Fl_Overlay_Window</TT>.</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>!
<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>.
<H4>void gl_color(Fl_Color)</H4>
<P>Sets the current OpenGL 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>
<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.
<H4>void gl_font(Fl_Font fontid, int size)</H4>
<P>Sets the current OpenGL font to the same font you get by
calling <A href="drawing.html#fl_font"><TT>fl_font()</TT></A>.
<H4>int gl_height()
<BR>int gl_descent()
<BR>float gl_width(const char *)
<BR>float gl_width(const char *, int n)
<BR>float gl_width(uchar)</H4>
<P>Returns information about the current OpenGL font.
<H4>void gl_draw(const char *)
<BR>void gl_draw(const char *, int n)</H4>
<P>Draws a nul-terminated string or an array of <TT>n</TT>
characters in the current OpenGL font at the current raster
position.
<H4>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)
<BR>void gl_draw(const char *, int n, float x, float y)</H4>
<P>Draws a nul-terminated string or an array of <TT>n</TT>
characters in the current OpenGL font at the given position.
<H4>void gl_draw(const char *, int x, int y, int w, int h, Fl_Align)</H4>
<P>Draws a string formatted into a box, with newlines and tabs
expanded, other control characters changed to ^X, and aligned
with the edges or center. Exactly the same output as <A
href="drawing.html#text"><TT>fl_draw()</TT></A>.
<h2>Speeding up OpenGL</h2>
<P>Performance of Fl_Gl_Window may be improved on some types of
OpenGL implementations, in particular MESA and other software
emulators, by setting the <tt>GL_SWAP_TYPE</tt> environment
variable. This variable declares what is in the backbuffer after
you do a swapbuffers.
<ul>
<li><tt>setenv GL_SWAP_TYPE COPY</tt>
<p>This indicates that the back buffer is copied to the
front buffer, and still contains it's old data. This is
true of many hardware implementations. Setting this
will speed up emulation of overlays, and widgets that
can do partial update can take advantage of this as
damage() will not be cleared to -1. <p>
<li><tt>setenv GL_SWAP_TYPE NODAMAGE</tt>
<p>This indicates that nothing changes the back buffer
except drawing into it. This is true of MESA and Win32
software emulation and perhaps some hardware emulation
on systems with lots of memory. <p>
<li>All other values for <tt>GL_SWAP_TYPE</tt>, and not
setting the variable, cause FLTK to assume that the
back buffer must be completely redrawn after a swap.
</ul>
<p>This is easily tested by running the <TT>gl_overlay</TT> demo
program and seeing if the display is correct when you drag
another window over it or if you drag the window off the screen
and back on. You have to exit and run the program again for it
to see any changes to the environment variable.
<H2>Using OpenGL Optimizer with FLTK</H2>
<P><A href="http://www.sgi.com/software/optimizer">OpenGL
Optimizer</A> is a scene graph toolkit for OpenGL available from
Silicon Graphics for IRIX and Microsoft Windows. It allows you
to view large scenes without writing a lot of OpenGL code.
<H4>OptimizerWindow Class Definition</H4>
<P>To use OpenGL Optimizer with FLTK you'll need to create a
subclass of <TT>Fl_Gl_Widget</TT> that includes several state
variables:
<UL><PRE>
class OptimizerWindow : public Fl_Gl_Window {
csContext *context_; // Initialized to 0 and set by draw()...
csDrawAction *draw_action_; // Draw action...
csGroup *scene_; // Scene to draw...
csCamara *camera_; // Viewport for scene...
void draw();
public:
OptimizerWindow(int X, int Y, int W, int H, const char *L)
: Fl_Gl_Window(X, Y, W, H, L) {
context_ = (csContext *)0;
draw_action_ = (csDrawAction *)0;
scene_ = (csGroup *)0;
camera_ = (csCamera *)0;
}
void scene(csGroup *g) { scene_ = g; redraw(); }
void camera(csCamera *c) {
camera_ = c;
if (context_) {
draw_action_-&gt;setCamera(camera_);
camera_-&gt;draw(draw_action_);
redraw();
}
}
};
</PRE></UL>
<H4>The camera() Method</H4>
<P>The <TT>camera()</TT> method sets the camera (projection and
viewpoint) to use when drawing the scene. The scene is redrawn after
this call.
<H4>The draw() Method</H4>
<P>The <TT>draw()</TT> method performs the needed initialization and does
the actual drawing:
<UL><PRE>
void OptimizerWindow::draw() {
if (!context_) {
// This is the first time we've been asked to draw; create the
// Optimizer context for the scene...
#ifdef WIN32
context_ = new csContext((HDC)fl_getHDC());
context_-&gt;ref();
context_-&gt;makeCurrent((HDC)fl_getHDC());
#else
context_ = new csContext(fl_display, fl_visual);
context_-&gt;ref();
context_-&gt;makeCurrent(fl_display, fl_window);
#endif // WIN32
... perform other context setup as desired ...
// Then create the draw action to handle drawing things...
draw_action_ = new csDrawAction;
if (camera_) {
draw_action_-&gt;setCamera(camera_);
camera_-&gt;draw(draw_action_);
}
} else {
#ifdef WIN32
context_-&gt;makeCurrent((HDC)fl_getHDC());
#else
context_-&gt;makeCurrent(fl_display, fl_window);
#endif // WIN32
}
if (!valid()) {
// Update the viewport for this context...
context_-&gt;setViewport(0, 0, w(), h());
}
// Clear the window...
context_-&gt;clear(csContext::COLOR_CLEAR | csContext::DEPTH_CLEAR,
0.0f, // Red
0.0f, // Green
0.0f, // Blue
1.0f); // Alpha
// Then draw the scene (if any)...
if (scene_)
draw_action_-&gt;apply(scene_);
}
</PRE></UL>
<H4>The scene() Method</H4>
<P>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.
*/
documentation/osissues.dox
+740
View File
File diff suppressed because it is too large Load Diff
documentation/preface.dox
+1 -1
View File
@@ -40,7 +40,7 @@ HREF="license.html">Appendix A</A>.</B>
<LI><A HREF="fluid.html#FLUID">Chapter 9 - Programming With FLUID</A></LI>
<LI><A HREF="widgets.html#widgets">Appendix A - Class Reference</A></LI>
<LI><A HREF="classes.html">Appendix A - Class Reference</A></LI>
<LI><A HREF="functions.html#functions">Appendix B - Function Reference</A></LI>
documentation/subclassing.dox
+431
View File
@@ -0,0 +1,431 @@
/**
\page subclassing 7 - Adding and Extending Widgets
<P>This chapter describes how to add your own widgets or extend existing
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
composite widgets.
<P>A control widget typically interacts with the user to receive and/or
display a value of some sort. </P>
<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 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
look or user-interface. For example, the button widgets are all
subclasses of <TT>Fl_Button</TT> since they all interact with the user
via a mouse button click. The only difference is the code that draws
the face of the button. </P>
<H2>Making a Subclass of Fl_Widget</H2>
Your subclasses can directly descend from <TT>Fl_Widget</TT> or any
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>
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>
without problems.
<P>The constructor must call the constructor for the base class and
pass the same arguments: </P>
<UL><PRE>
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>
<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>
type(0);
box(FL_NO_BOX);
color(FL_BACKGROUND_COLOR);
selection_color(FL_BACKGROUND_COLOR);
labeltype(FL_NORMAL_LABEL);
labelstyle(FL_NORMAL_STYLE);
labelsize(FL_NORMAL_SIZE);
labelcolor(FL_FOREGROUND_COLOR);
align(FL_ALIGN_CENTER);
callback(default_callback,0);
flags(ACTIVE|VISIBLE);
image(0);
deimage(0);
</PRE></UL>
<H2>Protected Methods of Fl_Widget</H2>
The following methods are provided for subclasses to use:
<UL>
<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_focus><TT>Fl_Widget::draw_focus</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>
<H4><A name=damage>void Fl_Widget::damage(uchar mask)
<BR> void Fl_Widget::damage(uchar mask, int x, int y, int w, int h)
<BR> uchar Fl_Widget::damage()</A></H4>
The first form indicates that a partial update of the object is
needed. The bits in mask are OR'd into <TT>damage()</TT>. Your <TT>
draw()</TT> routine can examine these bits to limit what it is
drawing. The public method <TT>Fl_Widget::redraw()</TT> simply does
<TT> Fl_Widget::damage(FL_DAMAGE_ALL)</TT>, but the implementation of
your widget can call the private <TT>damage(n)</TT>.
<P>The second form indicates that a region is damaged. If only these
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>
<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() &amp; FL_DAMAGE_ALL) {
... draw frame/box and other static stuff ...
}
if (damage() &amp; (FL_DAMAGE_ALL | 1)) draw_part1();
if (damage() &amp; (FL_DAMAGE_ALL | 2)) draw_part2();
if (damage() &amp; (FL_DAMAGE_ALL | 4)) draw_part3();
}
</PRE></UL>
<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
dimensions of the widget. The second form uses <TT>b</TT> as the box
type and <TT>c</TT> as the color for the box.
<H4><A name="draw_focus">void Fl_Widget::draw_focus() const
<BR>void Fl_Widget::draw_focus(Fl_Boxtype b, int x, int y, int w, int h) const</A></H4>
<P>Draws a focus box inside the widgets bounding box. The second
form allows you to specify a different bounding box.
<H4><A name=draw_label>void Fl_Widget::draw_label() const
<BR> void Fl_Widget::draw_label(int x, int y, int w, int h) const
<BR> void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align
align) const</A></H4>
This is the usual function for a <TT>draw()</TT> method to call to
draw the widget's label. It does not draw the label if it is supposed
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, 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 so the label will appear inside
the passed bounding box. This is designed for parent groups to draw
labels with. </P>
<H4><A name=set_flag>void Fl_Widget::set_flag(SHORTCUT_LABEL)</A></H4>
Modifies <TT>draw_label()</TT> so that '&amp;' characters cause an underscore
to be printed under the next letter.
<H4><A name=set_visible>void Fl_Widget::set_visible()</A>
<BR><A name=clear_visible>void Fl_Widget::clear_visible()</A></H4>
Fast inline versions of <TT>Fl_Widget::hide()</TT> and <TT>
Fl_Widget::show()</TT>. These do not send the <TT>FL_HIDE</TT> and <TT>
FL_SHOW</TT> events to the widget.
<H4><A name=test_shortcut>int Fl_Widget::test_shortcut() const
<BR> static int Fl_Widget::test_shortcut(const char *s)</A></H4>
The first version tests <TT>Fl_Widget::label()</TT> against the
current event (which should be a <TT>FL_SHORTCUT</TT> event). If the
label contains a '&amp;' character and the character after it matches the key
press, this returns true. This returns false if the <TT>SHORTCUT_LABEL</TT>
flag is off, if the label is <TT>NULL</TT> or does not have a
'&amp;' character in it, or if the keypress does not match the character.
<P>The second version lets you do this test against an arbitrary
string. </P>
<H4><A name=type>uchar Fl_Widget::type() const
<BR> void Fl_Widget::type(uchar t)</A></H4>
The property <TT>Fl_Widget::type()</TT> can return an arbitrary 8-bit
identifier, and can be set with the protected method <TT>type(uchar t)</TT>
. This value had to be provided for Forms compatibility, but you can
use it for any purpose you want. Try to keep the value less than 100
to not interfere with reserved values.
<P>FLTK does not use RTTI (Run Time Typing Infomation), to enhance
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> 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>
you must use <TT>FL_WINDOW + n</TT> (<TT>n</tt> must be in the
range 1 to 7). </P>
<H2><A NAME="handle">Handling Events</A></H2>
The virtual method <TT>int Fl_Widget::handle(int event)</TT> is called
to handle each event passed to the widget. It can:
<UL>
<LI>Change the state of the widget. </LI>
<LI>Call <A href=Fl_Widget.html#Fl_Widget.redraw><TT>Fl_Widget::redraw()</TT>
</A> if the widget needs to be redisplayed. </LI>
<LI>Call <A href=Fl_Widget.html#Fl_Widget.damage><TT>
Fl_Widget::damage(n)</TT></A> if the widget needs a partial-update
(assuming you provide support for this in your <A HREF="#draw"><TT>Fl_Widget::draw()</TT></A>
method). </LI>
<LI>Call <A href=Fl_Widget.html#Fl_Widget.do_callback><TT>
Fl_Widget::do_callback()</TT></A> if a callback should be generated. </LI>
<LI>Call <TT>Fl_Widget::handle()</TT> on child widgets. </LI>
</UL>
Events are identified by the integer argument. Other information
about the most recent event is stored in static locations and aquired
by calling the <A href=events.html#events><TT>Fl::event_*()</TT></A>
functions. This information remains valid until another event is
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>
int MyClass::handle(int event) {
switch(event) {
case FL_PUSH:
highlight = 1;
redraw();
return 1;
case FL_DRAG: {
int t = Fl::event_inside(this);
if (t != highlight) {
highlight = t;
redraw();
}
}
return 1;
case FL_RELEASE:
if (highlight) {
highlight = 0;
redraw();
do_callback();
// never do anything after a callback, as the callback
// may delete the widget!
}
return 1;
case FL_SHORTCUT:
if (Fl::event_key() == 'x') {
do_callback();
return 1;
}
return 0;
default:
return Fl_Widget::handle(event);
}
}
</PRE></UL>
<P>You must return non-zero if your <TT>handle()</TT> method
uses the event. If you return zero, the parent widget will try
sending the event to another widget.
<H2><A NAME="draw">Drawing the Widget</A></H2>
<P>The <TT>draw()</TT> virtual method is called when FLTK wants
you to redraw your widget. It will be called if and only if
<TT>damage()</TT> is non-zero, and <TT>damage()</TT> will be
cleared to zero after it returns. The <TT>draw()</TT> method
should be declared protected so that it can't be called from
non-drawing code.
<P>The <TT>damage()</TT> value contains the bitwise-OR of all
the <TT>damage(n)</TT> 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, 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_not_clipped(x,y,w,h)</TT> or <TT>fl_clip_box(...)</TT> and
skipping invisible parts. </P>
<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>
The <TT>resize(int x, int y, int w, int h)</TT> method is called when
the widget is being resized or moved. The arguments are the new
position, width, and height. <TT>x()</TT>, <TT>y()</TT>, <TT>w()</TT>,
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 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 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.
<P>Instances of the child widgets may be included in the parent: </P>
<UL><PRE>
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>
MyClass::MyClass(int x, int y, int w, int h) :
Fl_Group(x, y, w, h),
the_button(x + 5, y + 5, 100, 20),
the_slider(x, y + 50, w, 20)
{
...(you could add dynamically created child widgets here)...
end(); // don't forget to do this!
}
</PRE></UL>
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>
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>
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>
int MyClass::handle(int event) {
if (Fl_Group::handle(event)) return 1;
... handle events that children don't want ...
}
</PRE></UL>
<P>If you override <TT>draw()</TT> you need to draw all the
children. If <TT>redraw()</TT> or <TT>damage()</TT> is called
on a child, <TT>damage(FL_DAMAGE_CHILD)</TT> is done to the
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>
int MyClass::draw() {
Fl_Widget *const*a = array();
if (damage() == FL_DAMAGE_CHILD) { // only redraw some children
for (int i = children(); i --; a ++) update_child(**a);
} else { // total redraw
... draw background graphics ...
// now draw all the children atop the background:
for (int i = children_; i --; a ++) {
draw_child(**a);
draw_outside_label(**a); // you may not need to do this
}
}
}
</PRE></UL>
<TT>Fl_Group</TT> provides some protected methods to make drawing
easier:
<UL>
<LI><A href=#draw_child>draw_child</A></LI>
<LI><A href=#draw_outside_label>draw_outside_label</A></LI>
<LI><A href=#update_child>update_child</A></LI>
</UL>
<H4><A name=draw_child>void Fl_Group::draw_child(Fl_Widget&amp;)</A></H4>
This will force the child's <TT>damage()</TT> bits all to one and call <TT>
draw()</TT> on it, then clear the <TT>damage()</TT>. You should call
this on all children if a total redraw of your widget is requested, or
if you draw something (like a background box) that damages the child.
Nothing is done if the child is not <TT>visible()</TT> or if it is
clipped.
<H4><A name=draw_outside_label>void
Fl_Group::draw_outside_label(Fl_Widget&amp;) const</A></H4>
Draw the labels that are <I>not</I> drawn by <A href=#draw_label><TT>
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>.
<H4><A name=update_child>void Fl_Group::update_child(Fl_Widget&amp;)</A></H4>
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.
<H2>Cut and Paste Support</H2>
FLTK provides routines to cut and paste 8-bit text (in the future this
may be UTF-8) between applications:
<UL>
<LI><A href="Fl.html#Fl.paste"><TT>Fl::paste</TT></A></LI>
<LI><A href="Fl.html#Fl.selection"><TT>Fl::selection</TT></A></LI>
<LI><A href="Fl.html#Fl.selection_owner"><TT>Fl::selection_owner</TT></A></LI>
</UL>
It may be possible to cut/paste non-text data by using <A href=osissues.html#add_handler>
<TT>Fl::add_handler()</TT></A>.
<H2>Drag And Drop Support</H2>
FLTK provides routines to drag and drop 8-bit text between applications:
<P>Drag'n'drop operations are are initiated by copying data to the
clipboard and calling the function
<A href="Fl.html#Fl.dnd"><TT>Fl::dnd()</TT></A>.
<P>Drop attempts are handled via <A href="events.html#dnd">events</A>:
<UL>
<LI><TT>FL_DND_ENTER</TT></LI>
<LI><TT>FL_DND_DRAG</TT></LI>
<LI><TT>FL_DND_LEAVE</TT></LI>
<LI><TT>FL_DND_RELEASE</TT></LI>
<LI><TT>FL_PASTE</TT></LI>
</UL>
<H2>Making a subclass of Fl_Window</H2>
<P>You may want your widget to be a subclass of
<TT>Fl_Window</TT>, <TT>Fl_Double_Window</TT>, or
<TT>FL_Gl_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 draw.
<P>Subclassing <TT>Fl_Window</TT>is almost exactly like
subclassing <TT>Fl_Group</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 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>
</OL>
<P>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">"Appendix F - Operating
System Issues"</A> for more information.
*/