diff options
Diffstat (limited to 'documentation/src/basics.dox')
| -rw-r--r-- | documentation/src/basics.dox | 352 |
1 files changed, 352 insertions, 0 deletions
diff --git a/documentation/src/basics.dox b/documentation/src/basics.dox new file mode 100644 index 000000000..1c2a615c8 --- /dev/null +++ b/documentation/src/basics.dox @@ -0,0 +1,352 @@ +/** + + \page basics 2 - FLTK Basics + +This chapter teaches you the basics of compiling programs +that use FLTK. + +\section basics_writing Writing Your First FLTK Program + +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. + +\par Listing 1 - "hello.cxx" +\code +#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(); +} +\endcode + +<!-- NEED 2in --> + +After including the required header files, the program then creates a +window. All following widgets will automatically be children of this window. + +\code +Fl_Window *window = new Fl_Window(300,180); +\endcode + +Then we create a box with the "Hello, World!" string in it. FLTK automatically +adds the new box to <tt>window</tt>, the current grouping widget. + +\code +Fl_Box *box = new Fl_Box(20,40,260,100,"Hello, World!"); +\endcode + +Next, we set the type of box and the size, font, and style of the label: + +\code +box->box(FL_UP_BOX); +box->labelsize(36); +box->labelfont(FL_BOLD+FL_ITALIC); +box->labeltype(FL_SHADOW_LABEL); +\endcode + +We tell FLTK that we will not add any more widgets to <tt>window</tt>. + +\code +window->end(); +\endcode + +Finally, we show the window and enter the FLTK event loop: + +\code +window->show(argc, argv); +return Fl::run(); +\endcode + +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. + +\image html hello.C.gif "Figure 2-1: The Hello, World! Window" + +\subsection basics_creating Creating the Widgets + +The widgets are created using the C++ <tt>new</tt> operator. For +most widgets the arguments to the constructor are: + +\code +Fl_Widget(x, y, width, height, label) +\endcode + +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. + +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. + +<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. + +\subsection basics_hierarchies Creating Widget hierarchies + +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->begin()</tt> and +<tt>myGroup->end()</tt>. In this example, <tt>myGroup</tt> +would be the <i>current</i> group. + +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. + +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>. + +\subsection basics_getset Get/Set Methods + +<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="common.html#boxtypes">Chapter 3</A>. + +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". + +\subsection basics_redrawing Redrawing After Changing Attributes + +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. + +\subsection basics_labels Labels + +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 <tt>labelfont()</tt>,<tt> labelsize</tt>, +and <tt>labeltype()</tt> methods. + +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. + +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. + +The <tt>labelsize</tt> method sets the height of the font in pixels. + +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. + +A complete list of all label options can be found in +<A href="common.html#labels">Chapter 3</A>. + +\subsection basics_showing Showing the Window + +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. + +\subsection basics_eventloop The Main Event Loop + +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. + +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. + +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. + +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. + +FLTK applications must periodically check (Fl::check()) +or wait (Fl::wait()) for events or use the Fl::run() +method to enter a standard event processing loop. Calling +Fl::run() is equivalent to the following code: + +\code +while (Fl::wait()); +\endcode + +Fl::run() does not return until all of the windows +under FLTK control are closed by the user or your program. + +\section basics_standard_compiler Compiling Programs with Standard Compilers + +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: + +\code +CC -I/usr/local/include ... +gcc -I/usr/local/include ... +\endcode + +The <tt>fltk-config</tt> script included with FLTK can be +used to get the options that are required by your compiler: + +\code +CC `fltk-config --cxxflags` ... +\endcode + +Similarly, when linking your application you will need to tell the +compiler to use the FLTK library: + +\code +CC ... -L/usr/local/lib -lfltk -lXext -lX11 -lm +gcc ... -L/usr/local/lib -lfltk -lXext -lX11 -lm +\endcode + +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, Fl_Help_Dialog widget, and system icon support. + +\note +The libraries are named "fltk.lib", "fltkgl.lib", "fltkforms.lib", +and "fltkimages.lib", respectively under Windows. + +As before, the <tt>fltk-config</tt> script included with FLTK can be +used to get the options that are required by your linker: + +\code +CC ... `fltk-config --ldflags` +\endcode + +<!-- NEED 2in --> + +The forms, GL, and images libraries are included with the "--use-foo" +options, as follows: + +\code +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` +\endcode + +Finally, you can use the <tt>fltk-config</tt> script to +compile a single source file as a FLTK program: + +\code +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 +\endcode + +Any of these will create an executable named <tt>filename</tt>. + +\section basics_visual_cpp Compiling Programs with Microsoft Visual C++ + +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. You will also +need to add the FLTK and WinSock2 (WS2_32.LIB) libraries to +the "Link" settings. + +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. + +<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. + +\section basics_naming Naming + +All public symbols in FLTK start with the characters 'F' and 'L': + +\li Functions are either <tt>Fl::foo()</tt> or <tt>fl_foo()</tt>. + +\li Class and type names are capitalized: <tt>Fl_Foo</tt>. + +\li <A href="enumerations.html">Constants and enumerations</A> + are uppercase: <tt>FL_FOO</tt>. + +\li All header files start with <tt><FL/...></tt>. + +<!-- NEED 5in --> + +\section basics_headerfiles Header Files + +The proper way to include FLTK header files is: + +\code +#include <FL/Fl_xyz.H> +\endcode + +\note +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> + +\code +#include <FL\Fl_xyz.H> +#include <fl/fl_xyz.h> +#include <Fl/fl_xyz.h> +\endcode + +\htmlonly +<hr> +<a class="el" href="index.html">[Index]</a> +<a class="el" href="intro.html">[Previous] 1 - Introduction to FLTK</a> +<a class="el" href="common.html">[Next] 3 - Common Widgets and Attributes</a> +\endhtmlonly +*/ |