From de6f468b5121df32566bbaa3b250d35eae8e1178 Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Sun, 14 Sep 2008 21:58:12 +0000 Subject: Edited basic chapters to be more doxygen-friendly, added \image html statements. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6245 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/basics.dox | 201 +++++++++++++++----------------- documentation/common.dox | 290 ++++++++++++++++++++++------------------------- documentation/editor.dox | 6 +- 3 files changed, 229 insertions(+), 268 deletions(-) (limited to 'documentation') diff --git a/documentation/basics.dox b/documentation/basics.dox index 3c330f907..ed5c3812d 100644 --- a/documentation/basics.dox +++ b/documentation/basics.dox @@ -7,84 +7,82 @@ that use FLTK.

Writing Your First FLTK Program

-

All programs must include the file <FL/Fl.H>. +

All programs must include the file . 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.

+FLTK class it uses. Listing 1 shows a simple "Hello, +World!" program that uses FLTK to display the window.

- +\endcode

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 +

Then we create a box with the "Hello, World!" string in it. FLTK automatically adds the new box to window, 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 window.

- +\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 +You can quit the program by closing the window or pressing the ESCape key.

-

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

+\image html hello.C.gif "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:

- +\endcode

The x and y parameters determine where the widget or window is placed on the screen. In FLTK the top left @@ -107,8 +105,8 @@ copy of it - it just uses the pointer.

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 +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 @@ -122,19 +120,19 @@ hierarchies. New widgets can now be added manually using

Get/Set Methods

-

box->box(FL_UP_BOX) sets the type of box the +

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, +"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 +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".

+the form "void name(type)", and a "get" method is always +of the form "type name() const".

Redrawing After Changing Attributes

@@ -148,6 +146,11 @@ only common exceptions are value() which calls

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.

+

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 @@ -203,17 +206,16 @@ 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() +

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() is equivalent to the following code:

- +\endcode -

Fl::run() does not return until all of the windows +

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

@@ -222,71 +224,64 @@ under FLTK control are closed by the user or your program.

tools) you will probably need to tell the compiler where to find the header files. This is usually done using the -I option:

- +\endcode

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

- +\endcode

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

- +\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", +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:

- +\endcode

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

+\endcode

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

+\endcode

Any of these will create an executable named filename. @@ -294,11 +289,10 @@ fltk-config --use-forms --use-gl --use-images --compile filename.cpp

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.

+"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 main() @@ -306,7 +300,7 @@ 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" +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.

@@ -325,7 +319,7 @@ better and can be used with the "optimized for speed" setting.

  • Constants and enumerations are uppercase: FL_FOO.
    • -
  • All header files start with <FL/...>. +
  • All header files start with .
    • @@ -336,27 +330,20 @@ better and can be used with the "optimized for speed" setting.

    The proper way to include FLTK header files is:

    - - -
    - - - -
    Note: +\code +#include +\endcode -

    Case is significant on many operating systems, +\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>
-
    + include lines: -
    + \code + #include + #include + #include + \endcode */ diff --git a/documentation/common.dox b/documentation/common.dox index 20553873e..6dc452010 100644 --- a/documentation/common.dox +++ b/documentation/common.dox @@ -11,61 +11,49 @@ attributes.

    FLTK provides many types of buttons:

      +
    • Fl_Button - A standard push button.
      • -
    • Fl_Button - A - standard push button.
      • +
    • Fl_Check_Button - A button with a check box.
      • -
    • Fl_Check_Button - - A button with a check box.
      • +
    • Fl_Light_Button - A push button with a light.
      • -
    • Fl_Light_Button - - A push button with a light.
      • +
    • Fl_Repeat_Button - A push button that repeats + when held.
      • -
    • Fl_Repeat_Button - - A push button that repeats when held.
      • +
    • Fl_Return_Button - A push button that is activated + by the Enter key.
      • -
    • Fl_Return_Button - - A push button that is activated by the Enter key.
      • - -
    • Fl_Round_Button - - A button with a radio circle.
      • +
    • Fl_Round_Button - A button with a radio circle.
    -

    FLTK Buttons
    -Figure 3-1: FLTK Button Widgets

    +\image html buttons.gif "Figure 3-1: FLTK Button Widgets"

    All of these buttons just need the corresponding -<FL/Fl_xyz_Button.H> header file. The constructor + header file. The constructor takes the bounding box of the button and optionally a label string:

    -
      -Fl_Button *button = new Fl_Button(x, y, width, height, "label");
+\code
+Fl_Button *button = new Fl_Button(x, y, width, height, "label");
 Fl_Light_Button *lbutton = new Fl_Light_Button(x, y, width, height);
-Fl_Round_Button *rbutton = new Fl_Round_Button(x, y, width, height, "label");
-
    - -

    Each button has an associated -type() -which allows it to behave as a push button, toggle button, or -radio button:

    - -
      -button->type(FL_NORMAL_BUTTON);
-lbutton->type(FL_TOGGLE_BUTTON);
-rbutton->type(FL_RADIO_BUTTON);
-
    - -

    For toggle and radio buttons, the -value() -method returns the current button state (0 = off, 1 = on). The -set() and -clear() -methods can be used on toggle buttons to turn a toggle button -on or off, respectively. Radio buttons can be turned on with -the -setonly() +Fl_Round_Button *rbutton = new Fl_Round_Button(x, y, width, height, "label"); +\endcode + +

    Each button has an associated type() which allows +it to behave as a push button, toggle button, or radio button:

    + +\code +button->type(FL_NORMAL_BUTTON); +lbutton->type(FL_TOGGLE_BUTTON); +rbutton->type(FL_RADIO_BUTTON); +\endcode + +

    For toggle and radio buttons, the value() method returns +the current button state (0 = off, 1 = on). The set() and +clear() methods can be used on toggle buttons to turn a +toggle button on or off, respectively. +Radio buttons can be turned on with the setonly() method; this will also turn off other radio buttons in the same group.

    @@ -74,41 +62,32 @@ group.

    FLTK provides several text widgets for displaying and receiving text:

      +
    • Fl_Input - A one-line text input field.
      • -
    • Fl_Input - A - one-line text input field.
      • - -
    • Fl_Output - A - one-line text output field.
      • - -
    • Fl_Multiline_Input - - A multi-line text input field.
      • +
    • Fl_Output - A one-line text output field.
      • -
    • Fl_Multiline_Output - - A multi-line text output field.
      • +
    • Fl_Multiline_Input - A multi-line text input field.
      • -
    • Fl_Text_Display - - A multi-line text display widget.
      • +
    • Fl_Multiline_Output - A multi-line text output field.
      • -
    • Fl_Text_Editor - - A multi-line text editing widget.
      • +
    • Fl_Text_Display - A multi-line text display widget.
      • -
    • Fl_Help_View - A - HTML text display widget.
      • +
    • Fl_Text_Editor - A multi-line text editing widget.
      • +
    • Fl_Help_View - A HTML text display widget.

    The Fl_Output and Fl_Multiline_Output widgets allow the user to copy text from the output field but not change it.

    -

    The value() -method is used to get or set the string that is displayed:

    +

    The value() method is used to get or set the +string that is displayed:

    -
      -Fl_Input *input = new Fl_Input(x, y, width, height, "label");
-input->value("Now is the time for all good men...");
-
    +\code +Fl_Input *input = new Fl_Input(x, y, width, height, "label"); +input->value("Now is the time for all good men..."); +\endcode

    The string is copied to the widget's own storage when you set the value() of the widget.

    @@ -126,28 +105,25 @@ strings. FLTK provides the following valuators:

      -
    • Fl_Counter - A widget with arrow buttons that shows the - current value.
      • +
    • Fl_Counter - A widget with arrow buttons that shows the + current value.
      • -
    • Fl_Dial - A round knob.
      • +
    • Fl_Dial - A round knob.
      • -
    • Fl_Roller - An SGI-like dolly widget.
      • +
    • Fl_Roller - An SGI-like dolly widget.
      • -
    • Fl_Scrollbar - A standard scrollbar widget.
      • +
    • Fl_Scrollbar - A standard scrollbar widget.
      • -
    • Fl_Slider - A scrollbar with a knob.
      • +
    • Fl_Slider - A scrollbar with a knob.
      • -
    • Fl_Value_Slider - A slider that shows the current value.
      • +
    • Fl_Value_Slider - A slider that shows the current value.
    -

    FLTK Valuators
    -Figure 3-2: FLTK valuator widgets

    +\image html valuators.gif "Figure 3-2: FLTK valuator widgets" -

    The value() -method gets and sets the current value of the widget. The -minimum() -and maximum() +

    The value() method gets and sets the current value +of the widget. The minimum() and maximum() methods set the range of values that are reported by the widget.

    @@ -156,29 +132,31 @@ widget.

    Groups

    The Fl_Group widget class is used as a general -purpose "container" widget. Besides grouping radio +purpose "container" widget. Besides grouping radio buttons, the groups are used to encapsulate windows, tabs, and scrolled windows. The following group classes are available with FLTK:

      -
    • Fl_Double_Window - A double-buffered window on the screen.
      • +
    • Fl_Double_Window - A double-buffered window on the screen.
      • -
    • Fl_Gl_Window - An OpenGL window on the screen.
      • +
    • Fl_Gl_Window - An OpenGL window on the screen.
      • -
    • Fl_Group - The base container class; can be used to group - any widgets together.
      • +
    • Fl_Group - The base container class; can be used to group + any widgets together.
      • -
    • Fl_Pack - A collection of widgets that are packed into the group area.
      • +
    • Fl_Pack - A collection of widgets that are packed into the group area.
      • -
    • Fl_Scroll - A scrolled window area.
      • +
    • Fl_Scroll - A scrolled window area.
      • -
    • Fl_Tabs - Displays child widgets as tabs.
      • +
    • Fl_Tabs - Displays child widgets as tabs.
      • -
    • Fl_Tile - A tiled window area.
      • +
    • Fl_Tile - A tiled window area.
      • -
    • Fl_Window - A window on the screen.
      • +
    • Fl_Window - A window on the screen.
      • + +
    • Fl_Wizard - Displays one group of widgets at a time.
    @@ -192,11 +170,11 @@ create them. You can access them with the x(), position(), resize(), and size() methods:

    -
      -button->position(x, y);
-group->resize(x, y, width, height);
-window->size(width, height);
-
    +\code +button->position(x, y); +group->resize(x, y, width, height); +window->size(width, height); +\endcode

    If you change a widget's size or position after it is displayed you will have to call redraw() on the @@ -228,6 +206,8 @@ fixed contents.

  • FL_CYAN
  • FL_WHITE
    • + +
  • FL_WHITE

    • These symbols are the default colors for all FLTK widgets. They are @@ -244,35 +224,34 @@ explained in more detail in the chapter

  • FL_SELECTION_COLOR
    • -

    RGB colors can be set using the fl_rgb_color() +

    RGB colors can be set using the fl_rgb_color() function:

    -
      +\code
 Fl_Color c = fl_rgb_color(85, 170, 255);
-
    +\endcode

    The widget color is set using the color() method:

    -
      -button->color(FL_RED);
-
    +\code +button->color(FL_RED); +\endcode

    Similarly, the label color is set using the labelcolor() method:

    -
      -button->labelcolor(FL_WHITE);
-
    +\code +button->labelcolor(FL_WHITE); +\endcode

    Box Types

    The type Fl_Boxtype stored and returned in Fl_Widget::box() -is an enumeration defined in <Enumerations.H>. +is an enumeration defined in . Figure 3-3 shows the standard box types included with FLTK.

    -

    FLTK Box Types
    -Figure 3-3: FLTK box types

    +\image html boxtypes.gif "Figure 3-3: FLTK box types"

    FL_NO_BOX means nothing is drawn at all, so whatever is already on the screen remains. The FL_..._FRAME types only @@ -297,25 +276,25 @@ the box and adding it to the table of boxtypes.

    The drawing function is passed the bounding box and background color for the widget:

    -
      +\code
 void xyz_draw(int x, int y, int w, int h, Fl_Color c) {
 ...
 }
-
    +\endcode

    A simple drawing function might fill a rectangle with the given color and then draw a black outline:

    -
      +\code
 void xyz_draw(int x, int y, int w, int h, Fl_Color c) {
   fl_color(c);
   fl_rectf(x, y, w, h);
   fl_color(FL_BLACK);
   fl_rect(x, y, w, h);
 }
-
    +\endcode

    Fl_Boxtype fl_down(Fl_Boxtype)

    @@ -343,11 +322,11 @@ See also: fl_frame.

    The Fl::set_boxtype() method adds or replaces the specified box type:

    -
      +\code
 #define XYZ_BOX FL_FREE_BOXTYPE
 
 Fl::set_boxtype(XYZ_BOX, xyz_draw, 1, 1, 2, 2);
-
    +\endcode

    The last 4 arguments to Fl::set_boxtype() are the offsets for the x, y, width, and height values that should be @@ -376,13 +355,12 @@ for the label. Symbols can be included with the label string by escaping them using the "@" symbol - "@@" displays a single at sign. Figure 3-4 shows the available symbols.

    -

    FLTK Symbols
    -Figure 3-4: FLTK label symbols

    +\image html symbols.gif "Figure 3-4: FLTK label symbols"

    The @ sign may also be followed by the following optional -"formatting" characters, in this order:

    +"formatting" characters, in this order:

      @@ -402,7 +380,7 @@ sign. Figure 3-4 shows the available symbols.

    Thus, to show a very large arrow pointing downward you would use the -label string "@+92->". +label string "@+92->".

    align()

    @@ -495,11 +473,11 @@ function is called with a pointer to a Fl_Label structure containing the label information, the bounding box for the label, and the label alignment:

    -
      +\code
 void xyz_draw(const Fl_Label *label, int x, int y, int w, int h, Fl_Align align) {
 ...
 }
-
    +\endcode

    The label should be drawn inside this bounding box, even if FL_ALIGN_INSIDE is not enabled. The function @@ -509,11 +487,11 @@ is not called if the label value is NULL.

    Fl_Label structure and references to the width and height:

    -
      -void xyz_measure(const Fl_Label *label, int &w, int &h) {
+\code
+void xyz_measure(const Fl_Label *label, int &w, int &h) {
 ...
 }
-
    +\endcode

    The function should measure the size of the label and set w and h to the size it will occupy.

    @@ -523,11 +501,11 @@ void xyz_measure(const Fl_Label *label, int &w, int &h) {

    The Fl::set_labeltype method creates a label type using your draw and measure functions:

    -
      +\code
 #define XYZ_LABEL FL_FREE_LABELTYPE
 
 Fl::set_labeltype(XYZ_LABEL, xyz_draw, xyz_measure);
-
    +\endcode

    The label type number n can be any integer value starting at the constant FL_FREE_LABELTYPE. Once you @@ -550,19 +528,19 @@ to generate a vector shape inside a two-by-two units sized box around the origin. This function is then linked into the symbols table using fl_add_symbol:

    - +\code +int fl_add_symbol(const char *name, void (*drawit)(Fl_Color), int scalable) +\endcode

    name is the name of the symbol without the "@"; scalable must be set to 1 if the symbol is generated using scalable vector drawing functions.

    - +\code +int fl_draw_symbol(const char *name,int x,int y,int w,int h,Fl_Color col) +\endcode -

    This function draw a named symbol fitting the given rectangle. +

    This function draws a named symbol fitting the given rectangle.

    Callbacks

    @@ -571,36 +549,35 @@ widget changes. A callback function is sent a Fl_Widget pointer of the widget that changed and a pointer to data that you provide:

    -
      +\code
 void xyz_callback(Fl_Widget *w, void *data) {
 ...
 }
-
    +\endcode

    The callback() method sets the callback function for a widget. You can optionally pass a pointer to some data needed for the callback:

    -
      +\code
 int xyz_data;
 
-button->callback(xyz_callback, &xyz_data);
-
    +button->callback(xyz_callback, &xyz_data); +\endcode

    Normally callbacks are performed only when the value of the -widget changes. You can change this using the -when() +widget changes. You can change this using the Fl_Widget::when() method:

    -
      -button->when(FL_WHEN_NEVER);
-button->when(FL_WHEN_CHANGED);
-button->when(FL_WHEN_RELEASE);
-button->when(FL_WHEN_RELEASE_ALWAYS);
-button->when(FL_WHEN_ENTER_KEY);
-button->when(FL_WHEN_ENTER_KEY_ALWAYS);
-button->when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED);
-
    +\code +button->when(FL_WHEN_NEVER); +button->when(FL_WHEN_CHANGED); +button->when(FL_WHEN_RELEASE); +button->when(FL_WHEN_RELEASE_ALWAYS); +button->when(FL_WHEN_ENTER_KEY); +button->when(FL_WHEN_ENTER_KEY_ALWAYS); +button->when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED); +\endcode
    @@ -608,8 +585,7 @@ button->when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED);

    You cannot delete a widget inside a callback, as the widget may still be accessed by FLTK after your callback - is completed. Instead, use the Fl::delete_widget() + is completed. Instead, use the Fl::delete_widget() method to mark your widget for deletion when it is safe to do so.

    @@ -628,17 +604,17 @@ button->when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED); callback() method of the widget can be a pointer to the instance of your class.

    -
    +\code
 class Foo {
   void my_callback(Fl_Widget *w);
-  static void my_static_callback(Fl_Widget *w, void *f) { ((Foo *)f)->my_callback(w); }
+  static void my_static_callback(Fl_Widget *w, void *f) { ((Foo *)f)->my_callback(w); }
   ...
 }
 
 ...
 
-w->callback(my_static_callback, (void *)this);
-
    +w->callback(my_static_callback, (void *)this); +\endcode
    @@ -649,14 +625,14 @@ w->callback(my_static_callback, (void *)this); buttons or menu items. The shortcut() method sets the shortcut for a widget:

    -
      -button->shortcut(FL_Enter);
-button->shortcut(FL_SHIFT + 'b');
-button->shortcut(FL_CTRL + 'b');
-button->shortcut(FL_ALT + 'b');
-button->shortcut(FL_CTRL + FL_ALT + 'b');
-button->shortcut(0); // no shortcut
-
    +\code +button->shortcut(FL_Enter); +button->shortcut(FL_SHIFT + 'b'); +button->shortcut(FL_CTRL + 'b'); +button->shortcut(FL_ALT + 'b'); +button->shortcut(FL_CTRL + FL_ALT + 'b'); +button->shortcut(0); // no shortcut +\endcode

    The shortcut value is the key event value - the ASCII value or one of the special keys like diff --git a/documentation/editor.dox b/documentation/editor.dox index 260c7a887..f6e37e759 100644 --- a/documentation/editor.dox +++ b/documentation/editor.dox @@ -150,8 +150,7 @@ custom window. To keep things simple we will have a the "replace next " button is a Fl_Return_Button widget:

    -

    The search and replace dialog.
    -Figure 4-1: The search and replace dialog.

    +\image html editor-replace.gif "Figure 4-1: The search and replace dialog" 
       Fl_Window *replace_dlg = new Fl_Window(300, 105, "Replace");
@@ -618,8 +617,7 @@ or c++ on your system.
 
 The final editor window should look like the image in Figure 4-2.
 
-
      The completed editor window.
      
-Figure 4-2: The completed editor window
      
+\image html editor.gif "Figure 4-2: The completed editor window"
 
 
      Advanced Features
      
 
-- 
cgit v1.2.3