4c53a5d8f4
a distribution). Documentation fixes. git-svn-id: file:///fltk/svn/fltk/trunk@259 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
187 lines
7.8 KiB
HTML
187 lines
7.8 KiB
HTML
<HTML><BODY>
|
|
<H1 ALIGN=RIGHT><A NAME=basics>2 - FLTK Basics</A></H1>
|
|
This chapter will teach you the basics of compiling programs that use
|
|
FLTK.
|
|
<H2>Naming</H2>
|
|
All public symbols in FLTK start with the characters 'F' and 'L':
|
|
<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#Enumerations>Constants and enumerations</A>
|
|
are uppercase: <TT>FL_FOO</TT>. </LI>
|
|
<LI>All header files start with <TT><FL/...></TT>. </LI>
|
|
</UL>
|
|
<H2>Header Files</H2>
|
|
The proper way to include FLTK header files is:
|
|
<UL>
|
|
<PRE>
|
|
#include <FL/Fl_xyz.H>
|
|
</PRE>
|
|
</UL>
|
|
<B>Microsoft Windows developers please note:</B> case *is* significant
|
|
under other operating systems, and the C standard uses the forward
|
|
slash (/) to separate directories. <i>Do not do any of the following:</i>
|
|
<UL>
|
|
<PRE>
|
|
#include <FL\Fl_xyz.H>
|
|
#include <fl/fl_xyz.h>
|
|
#include <Fl/fl_xyz.h>
|
|
</PRE>
|
|
</UL>
|
|
<H2>Compiling Programs with Standard Compilers</H2>
|
|
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:
|
|
<UL>
|
|
<PRE>
|
|
CC -I/usr/local/include ...
|
|
gcc -I/usr/local/include ...
|
|
</PRE>
|
|
</UL>
|
|
Similarly, when linking your application you will need to tell the
|
|
compiler to use the FLTK library:
|
|
<UL>
|
|
<PRE>
|
|
CC ... -L/usr/local/lib -lfltk -lXext -lX11 -lm
|
|
gcc ... -L/usr/local/lib -lfltk -lXext -lX11 -lm
|
|
</PRE>
|
|
</UL>
|
|
<H2>Compiling Programs with Microsoft Visual C++</H2>
|
|
In Visual C++ you will need to tell the compiler where to find the
|
|
FLTK header files. This can be done by selecting "Settings" from the
|
|
"Project" menu and then changing the "Preprocessor" settings under the
|
|
"C/C++" tab. Similarly, you will need to add the FLTK library to the
|
|
"Link" settings.
|
|
<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 "Favor Small Code"
|
|
optimization setting.</I> The Visual C++ 6.0 optimizer seems to be much
|
|
better and can be used with the "optimized for speed" setting.</P>
|
|
<H2>Writing Your First FLTK Program</H2>
|
|
All programs must include the file <TT><FL/Fl.H></TT>. In addition the
|
|
program must include a header file for each FLTK class it uses.
|
|
Listing 1 shows a simple "Hello, World!" program that uses FLTK to
|
|
display the window.
|
|
<UL><I>Listing 1 - "hello.cxx"</I>
|
|
<BR>
|
|
<PRE>
|
|
#include <FL/Fl.H>
|
|
#include <FL/Fl_Window.H>
|
|
#include <FL/Fl_Box.H>
|
|
|
|
int main(int argc, char **argv) {
|
|
Fl_Window *window = new Fl_Window(300,180);
|
|
Fl_Box *box = new Fl_Box(20,40,260,100,"Hello, World!");
|
|
box->box(FL_UP_BOX);
|
|
box->labelsize(36);
|
|
box->labelfont(FL_BOLD+FL_ITALIC);
|
|
box->labeltype(FL_SHADOW_LABEL);
|
|
window->end();
|
|
window->show(argc, argv);
|
|
return Fl::run();
|
|
}
|
|
</PRE>
|
|
</UL>
|
|
After including the required header files, the program then creates a
|
|
window:
|
|
<UL>
|
|
<PRE>
|
|
Fl_Window *window = new <A href=Fl_Window.html#Fl_Window>Fl_Window</A>(300,180);
|
|
</PRE>
|
|
</UL>
|
|
and a box with the "Hello, World!" string in it:
|
|
<UL>
|
|
<PRE>
|
|
Fl_Box *box = new <A href=Fl_Box.html#Fl_Box>Fl_Box</A>(20,40,260,100,"Hello, World!");
|
|
</PRE>
|
|
</UL>
|
|
Next, we set the type of box and the size, font, and style of the label:
|
|
<UL>
|
|
<PRE>
|
|
box->box(FL_UP_BOX);
|
|
box-><A href=Fl_Widget.html#Fl_Widget.labelsize>labelsize</A>(36);
|
|
box-><A href=Fl_Widget.html#Fl_Widget.labelfont>labelfont</A>(FL_BOLD+FL_ITALIC);
|
|
box-><A href=Fl_Widget.html#Fl_Widget.labeltype>labeltype</A>(FL_SHADOW_LABEL);
|
|
</PRE>
|
|
</UL>
|
|
Finally, we show the window and enter the FLTK event loop:
|
|
<UL>
|
|
<PRE>
|
|
window-><A href=Fl_Group.html#Fl_Group.end>end</A>();
|
|
window-><A href=Fl_Window.html#Fl_Window.show>show</A>(argc, argv);
|
|
return <A href=functions.html#run>Fl::run</A>();
|
|
</PRE>
|
|
</UL>
|
|
The resulting program will display the window below. You can quit the
|
|
program by closing the window or pressing the ESCape key.
|
|
<P ALIGN=CENTER><IMG src=./hello.C.gif></P>
|
|
<H3>Creating the Widgets</H3>
|
|
The widgets are created using the C++ <TT>new</TT> operator. For
|
|
most widgets the arguments to the constructor are:
|
|
<UL>
|
|
<PRE>
|
|
Fl_Widget(x, y, width, height)
|
|
</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).
|
|
<H3>Get/Set Methods</H3>
|
|
<tt>box->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 "Hello, World!" 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=#boytypes>
|
|
Chapter 3</A>.
|
|
<p>You could examine the boxtype in by doing
|
|
<tt>box->box()</tt>. Fltk uses method name overloading to make
|
|
short names for get/set methods. A "set" method is always of the form
|
|
"void name(type)", and a "get" method is always of the form
|
|
"type name() const".
|
|
<p>Almost all of these set/get pairs are very fast and short inline
|
|
functions and thus very efficient. However, <i>the "set" methods do
|
|
not call redraw()</i>, you have to call it yourself. This greatly
|
|
reduces code size and execution time. The only common exception is
|
|
<tt>value()</tt>, this does redraw() if necessary.
|
|
<H3>Labels</H3>
|
|
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>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, shadowed, symbol, and image labels. </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>
|
|
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.
|
|
<H3>The Main Event Loop</H3>
|
|
FLTK provides the <A href=functions.html#run><TT>Fl:run()</TT></A>
|
|
method to enter a standard event processing loop. This is equivalent
|
|
to the following code:
|
|
<UL>
|
|
<PRE>
|
|
while (Fl::wait());
|
|
</PRE>
|
|
</UL>
|
|
<TT>Fl::run()</TT> does not return until all of the windows under FLTK
|
|
control are closed (either by the user or your program). </TT></BODY></HTML>
|