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/common.dox | 290 ++++++++++++++++++++++------------------------- 1 file changed, 133 insertions(+), 157 deletions(-) (limited to 'documentation/common.dox') 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:

-

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:

- - -

Each button has an associated -type() -which allows it to behave as a push button, toggle button, or -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:

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:

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

-

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:

@@ -192,11 +170,11 @@ create them. You can access them with the x(), position(), resize(), and size() methods:

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

    - +\endcode

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

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

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

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

    - +\endcode

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

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

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

    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:

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

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

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

    - +\endcode

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

    - +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:

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

    - +\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 -- cgit v1.2.3