From 8416a4012ecb985d150fad566659cf59ee1dc3aa Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Sat, 13 Sep 2008 15:55:32 +0000 Subject: Doxygen documentation - WP12 and WP13 - first step. 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 --- documentation/basics.dox | 362 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 362 insertions(+) create mode 100644 documentation/basics.dox (limited to 'documentation/basics.dox') diff --git a/documentation/basics.dox b/documentation/basics.dox new file mode 100644 index 000000000..3c330f907 --- /dev/null +++ b/documentation/basics.dox @@ -0,0 +1,362 @@ +/** + + \page basics 2 - FLTK Basics + +

This chapter teaches you the basics of compiling programs +that use FLTK.

+ +

Writing Your First FLTK Program

+ +

All programs must include the file <FL/Fl.H>. +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.

+ + + + + +

After including the required header files, the program then creates a +window. All following widgets will automatically be children of this window.

+ + + +

Then we create a box with the "Hello, World!" string in it. FLTK automatically adds +the new box to window, the current grouping widget.

+ + + +

Next, we set the type of box and the size, font, and style of the label:

+ + + +

We tell FLTK that we will not add any more widgets to window.

+ + + +

Finally, we show the window and enter the FLTK event loop:

+ + + +

The resulting program will display the window in Figure 2-1. +You can quit the program by closing the window or pressing the +ESCape key.

+ +

Hello, World! Window
+Figure 2-1: The Hello, World! Window

+ +

Creating the Widgets

+ +

The widgets are created using the C++ new operator. For +most widgets the arguments to the constructor are:

+ + + +

The x and y 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 width and height 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.

+ +

label is a pointer to a character string to label +the widget with or NULL. If not specified the label +defaults to NULL. 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.

+ +

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 myGroup->begin() and +myGroup->end(). In this example, myGroup +would be the current group.

+ +

Newly created groups and their derived widgets implicitly call +begin() in the constructor, effectively adding all +subsequently created widgets to itself until end() +is called.

+ +

Setting the current group to NULL will stop automatic +hierarchies. New widgets can now be added manually using +Fl_Group::add(...) and Fl_Group::insert(...).

+ +

Get/Set Methods

+ +

box->box(FL_UP_BOX) sets the type of box the +Fl_Box draws, changing it from the default of +FL_NO_BOX, which means that no box is drawn. In our +"Hello, World!" example we use FL_UP_BOX, +which means that a raised button border will be drawn around +the widget. You can learn more about boxtypes in +Chapter 3.

+ +

You could examine the boxtype in by doing +box->box(). 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".

+ +

Redrawing After Changing Attributes

+ +

Almost all of the set/get pairs are very fast, short inline +functions and thus very efficient. However, the "set" methods +do not call redraw() - you have to call it +yourself. This greatly reduces code size and execution time. The +only common exceptions are value() which calls +redraw() and label() which calls +redraw_label() if necessary.

+ +

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 +labelfont, + labelsize, +and labeltype +methods.

+ +

The labelfont method sets the typeface and style +that is used for the label, which for this example we are using +FL_BOLD and FL_ITALIC. You can also specify +typefaces directly.

The labelsize method sets +the height of the font in pixels.

The labeltype +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 +Chapter 3.

+ +

Showing the Window

+ +

The show() 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.

+ +

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:

+ + + +

Fl::run() does not return until all of the windows +under FLTK control are closed by the user or your program.

+ +

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 -I option:

+ + + +

The fltk-config script included with FLTK can be +used to get the options that are required by your compiler:

+ + + +

Similarly, when linking your application you will need to tell the +compiler to use the FLTK library:

+ + + +

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 fltk-config script included with FLTK can be +used to get the options that are required by your linker:

+ + + + + +

The forms, GL, and images libraries are included with the "--use-foo" +options, as follows: + +

+ +

Finally, you can use the fltk-config script to +compile a single source file as a FLTK program: + +

+ +

Any of these will create an executable named filename. + +

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 +WinSock (WSOCK32.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 main() +function as the entry point, FLTK includes a WinMain() +function that will call your main() function for you.

+ +

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. The Visual C++ 6.0 optimizer seems to be much +better and can be used with the "optimized for speed" setting.

+ +

Naming

+ +

All public symbols in FLTK start with the characters 'F' and 'L':

+ + + + + +

Header Files

+ +

The proper way to include FLTK header files is:

+ + + +
+ + + +
Note: + +

Case is significant on many operating systems, + and the C standard uses the forward slash (/) to + separate directories. Do not use any of the following + include lines:

+ + 
    +	#include <FL\Fl_xyz.H>
+	#include <fl/fl_xyz.h>
+	#include <Fl/fl_xyz.h>
+
+ +
+ +*/ -- cgit v1.2.3