From 7f105bfa47e0f8a24f019f87c76bae387fbe0c1b Mon Sep 17 00:00:00 2001 From: engelsman Date: Fri, 10 Oct 2008 17:10:28 +0000 Subject: converted more html to plain old doxygen in basics.dox and common.dox git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6404 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/common.dox | 498 ++++++++++++++++++++++------------------------- 1 file changed, 232 insertions(+), 266 deletions(-) (limited to 'documentation/common.dox') diff --git a/documentation/common.dox b/documentation/common.dox index 62dbebe73..eeceae4cf 100644 --- a/documentation/common.dox +++ b/documentation/common.dox @@ -2,37 +2,33 @@ \page common 3 - Common Widgets and Attributes -

This chapter describes many of the widgets that are provided +This chapter describes many of the widgets that are provided with FLTK and covers how to query and set the standard -attributes.

+attributes. -

Buttons

+\section common_buttons Buttons -

FLTK provides many types of buttons:

+FLTK provides many types of buttons: - +\li Fl_Round_Button - A button with a radio circle. \image html buttons.gif "Figure 3-1: FLTK Button Widgets" -

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

+string: \code Fl_Button *button = new Fl_Button(x, y, width, height, "label"); @@ -40,8 +36,8 @@ 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"); \endcode -

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

+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); @@ -49,126 +45,115 @@ lbutton->type(FL_TOGGLE_BUTTON); rbutton->type(FL_RADIO_BUTTON); \endcode -

For toggle and radio buttons, the value() method returns +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.

+group. -

Text

+\section common_text Text -

FLTK provides several text widgets for displaying and receiving text:

+FLTK provides several text widgets for displaying and receiving text: - +\li Fl_Help_View - A HTML text display widget. -

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

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

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

The Fl_Text_Display and Fl_Text_Editor -widgets use an associated Fl_Text_Buffer class for the -value, instead of a simple string.

+The Fl_Text_Display and Fl_Text_Editor +widgets use an associated Fl_Text_Buffer class for the +value, instead of a simple string. -

Valuators

- -

Unlike text widgets, valuators keep track of numbers instead of -strings. FLTK provides the following valuators:

- - +\li Fl_Value_Slider - A slider that shows the current value. \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.

+widget. -

Groups

+\section common_groups Groups -

The Fl_Group widget class is used as a general +The Fl_Group widget class is used as a general 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:

+with FLTK: - - -

Setting the Size and Position of Widgets

- -

The size and position of widgets is usually set when you +The size and position of widgets is usually set when you create them. You can access them with the x(), -y(), w(), and h() methods.

+y(), w(), and h() methods. -

You can change the size and position by using the -position(), resize(), and size() -methods:

+You can change the size and position by using the +position(), resize(), and size() +methods: \code button->position(x, y); @@ -176,69 +161,65 @@ group->resize(x, y, width, height); window->size(width, height); \endcode -

If you change a widget's size or position after it is +If you change a widget's size or position after it is displayed you will have to call redraw() on the -widget's parent.

+widget's parent. -

Colors

+ +\section common_colors Colors -

FLTK stores the colors of widgets as an 32-bit unsigned +FLTK stores the colors of widgets as an 32-bit unsigned number that is either an index into a color palette of 256 colors or a 24-bit RGB color. The color palette is not the X or WIN32 colormap, but instead is an internal table with -fixed contents.

+fixed contents. -

There are symbols for naming some of the more common colors:

+There are symbols for naming some of the more common colors: - +\li FL_WHITE -

These symbols are the default colors for all FLTK widgets. They are +These symbols are the default colors for all FLTK widgets. They are explained in more detail in the chapter -Enumerations

+Enumerations - +\li FL_SELECTION_COLOR -

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

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

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

+Similarly, the label color is set using the labelcolor() +method: \code button->labelcolor(FL_WHITE); @@ -247,35 +228,35 @@ button->labelcolor(FL_WHITE); \section common_boxtypes Box Types -

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

+Figure 3-3 shows the standard box types included with FLTK. \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 +FL_NO_BOX means nothing is drawn at all, so whatever is +already on the screen remains. The FL_..._FRAME types only draw their edges, leaving the interior unchanged. The blue color in -Figure 3-3 is the area that is not drawn by the frame types.

+Figure 3-3 is the area that is not drawn by the frame types. -

Making Your Own Boxtypes

+\subsection common_boxtypes Making Your Own Boxtypes -

You can define your own boxtypes by making a small function that draws -the box and adding it to the table of boxtypes.

+You can define your own boxtypes by making a small function that draws +the box and adding it to the table of boxtypes.
Note: -

This interface has changed in FLTK 2.0!

+

This interface has changed in FLTK 2.0!

-

The Drawing Function

+\par The Drawing Function -

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

+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) { @@ -285,8 +266,8 @@ void xyz_draw(int x, int y, int w, int h, Fl_Color c) { -

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

+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) { @@ -297,183 +278,167 @@ void xyz_draw(int x, int y, int w, int h, Fl_Color c) { } \endcode -

Fl_Boxtype fl_down(Fl_Boxtype)

+ +\par Fl_Boxtype fl_down(Fl_Boxtype) -

fl_down returns the "pressed" or "down" version of a box. +fl_down returns the "pressed" or "down" version of a box. If no "down" version of a given box exists, the behavior of this function is undefined and some random box or frame is returned. See also: fl_frame drawing. -

Fl_Boxtype fl_frame(Fl_Boxtype)

+ +\par Fl_Boxtype fl_frame(Fl_Boxtype) -

fl_frame returns the unfilled, frame-only version of a box. +fl_frame returns the unfilled, frame-only version of a box. If no frame version of a given box exists, the behavior of this function is undefined and some random box or frame is returned. See also: fl_frame drawing. -

Fl_Boxtype fl_box(Fl_Boxtype)

+ +\par Fl_Boxtype fl_box(Fl_Boxtype) -

fl_box returns the filled version of a frame. +fl_box returns the filled version of a frame. If no filled version of a given frame exists, the behavior of this function is undefined and some random box or frame is returned. -See also: fl_frame. +See also: fl_frame. -

Adding Your Box Type

+\par Adding Your Box Type -

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

+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 +The last 4 arguments to Fl::set_boxtype() are the offsets for the x, y, width, and height values that should be -subtracted when drawing the label inside the box.

+subtracted when drawing the label inside the box. -

A complete box design contains four box types in this order: -a filled, neutral box (UP_BOX), a filled, depressed box -(DOWN_BOX), and the same as outlines only (UP_FRAME -and DOWN_FRAME). The function -fl_down(Fl_Boxtype) +A complete box design contains four box types in this order: +a filled, neutral box (UP_BOX), a filled, depressed box +(DOWN_BOX), and the same as outlines only (UP_FRAME +and DOWN_FRAME). The function +fl_down(Fl_Boxtype) expects the neutral design on a boxtype with a numerical value evenly divideable by two. -fl_frame(Fl_Boxtype) -expects the UP_BOX design at a value divideable by four.

+fl_frame(Fl_Boxtype) +expects the UP_BOX design at a value divideable by four. \section common_labels Labels and Label Types -

The label(), align(), labelfont(), -labelsize(), labeltype(), image(), and -deimage() methods control the labeling of widgets.

+The label(), align(), labelfont(), +labelsize(), labeltype(), image(), and +deimage() methods control the labeling of widgets. -

label()

+\par label() -

The label() method sets the string that is displayed +The label() method sets the string that is displayed 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.

+sign. Figure 3-4 shows the available 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:

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

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

align()

- -

The align() method positions the label. The following -constants are defined and may be OR'd together as needed:

- - +\li FL_ALIGN_WRAP - wrap the label text as needed. -

labeltype()

+\li FL_TEXT_OVER_IMAGE - show the label text over the image. -

The labeltype() method sets the type of the label. The -following standard label types are included:

+\li FL_IMAGE_OVER_TEXT - show the label image over the text (default). - +\li FL_ICON_LABEL - draws the icon associated with the text. -

image() and deimage()

+\par image() and deimage() -

The image() and deimage() methods set an image that -will be displayed with the widget. The deimage() method sets the -image that is shown when the widget is inactive, while the image() -method sets the image that is shown when the widget is active.

+The image() and deimage() methods set an image that +will be displayed with the widget. The deimage() method sets the +image that is shown when the widget is inactive, while the image() +method sets the image that is shown when the widget is active. -

To make an image you use a subclass of -Fl_Image.

+To make an image you use a subclass of +Fl_Image. -

Making Your Own Label Types

+\par Making Your Own Label Types -

Label types are actually indexes into a table of functions +Label types are actually indexes into a table of functions that draw them. The primary purpose of this is to use this to draw the labels in ways inaccessible through the -fl_font mechanisim (e.g. FL_ENGRAVED_LABEL) or -with program-generated letters or symbology.

+fl_font mechanisim (e.g. FL_ENGRAVED_LABEL) or +with program-generated letters or symbology.
Note: -

This interface has changed in FLTK 2.0!

+

This interface has changed in FLTK 2.0!

-
Label Type Functions
+\par Label Type Functions -

To setup your own label type you will need to write two +To setup your own label type you will need to write two functions: one to draw and one to measure the label. The draw -function is called with a pointer to a Fl_Label +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:

+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) { @@ -481,13 +446,13 @@ 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 -is not called if the label value is NULL.

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

The measure function is called with a pointer to a -Fl_Label structure and references to the width and -height:

+The measure function is called with a pointer to a +Fl_Label structure and references to the width and +height: \code void xyz_measure(const Fl_Label *label, int &w, int &h) { @@ -495,13 +460,13 @@ 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.

+The function should measure the size of the label and set +w and h to the size it will occupy. -
Adding Your Label Type
+\par Adding Your Label Type -

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

+The Fl::set_labeltype method creates a label type +using your draw and measure functions: \code #define XYZ_LABEL FL_FREE_LABELTYPE @@ -509,47 +474,48 @@ using your draw and measure functions:

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 -have added the label type you can use the labeltype() -method to select your label type.

+The label type number n can be any integer value +starting at the constant FL_FREE_LABELTYPE. Once you +have added the label type you can use the labeltype() +method to select your label type. -

The Fl::set_labeltype method can also be used to overload -an existing label type such as FL_NORMAL_LABEL.

+The Fl::set_labeltype method can also be used to overload +an existing label type such as FL_NORMAL_LABEL. -

Making your own symbols

+ +\par Making your own symbols -

It is also possible to define your own drawings and add +It is also possible to define your own drawings and add them to the symbol list, so they can be rendered as part of -any label.

+any label. -

To create a new symbol, you implement a drawing function +To create a new symbol, you implement a drawing function void drawit(Fl_Color c) which typically uses the complex drawing functions 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:

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

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

This function draws a named symbol fitting the given rectangle. +This function draws a named symbol fitting the given rectangle. -

Callbacks

+\section common_callbacks Callbacks -

Callbacks are functions that are called when the value of a -widget changes. A callback function is sent a Fl_Widget +Callbacks are functions that are called when the value of a +widget changes. A callback function is sent a Fl_Widget pointer of the widget that changed and a pointer to data that -you provide:

+you provide: \code void xyz_callback(Fl_Widget *w, void *data) { @@ -557,9 +523,9 @@ void xyz_callback(Fl_Widget *w, void *data) { } \endcode -

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

+callback: \code int xyz_data; @@ -567,9 +533,9 @@ int xyz_data; button->callback(xyz_callback, &xyz_data); \endcode -

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

+method: \code button->when(FL_WHEN_NEVER); @@ -589,22 +555,22 @@ button->when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED); widget may still be accessed by FLTK after your callback is completed. Instead, use the Fl::delete_widget() method to mark your widget for deletion when it is safe - to do so.

+ to do so.

Hint:

Many programmers new to FLTK or C++ try to use a non-static class method instead of a static class method or function for their callback. Since callbacks are done - outside a C++ class, the this pointer is not - initialized for class methods.

+ outside a C++ class, the this pointer is not + initialized for class methods.

To work around this problem, define a static method in your class that accepts a pointer to the class, and then have the static method call the class method(s) as needed. The data pointer you provide to the - callback() method of the widget can be a - pointer to the instance of your class.

+ callback() method of the widget can be a + pointer to the instance of your class. \code class Foo { @@ -621,11 +587,11 @@ w->callback(my_static_callback, (void *)this); -

Shortcuts

+\section common_shortcuts Shortcuts -

Shortcuts are key sequences that activate widgets such as -buttons or menu items. The shortcut() method sets the -shortcut for a widget:

+Shortcuts are key sequences that activate widgets such as +buttons or menu items. The shortcut() method sets the +shortcut for a widget: \code button->shortcut(FL_Enter); @@ -636,11 +602,11 @@ button->shortcut(FL_CTRL + FL_ALT + 'b'); button->shortcut(0); // no shortcut \endcode -

The shortcut value is the key event value - the ASCII value +The shortcut value is the key event value - the ASCII value or one of the special keys like -FL_Enter - +FL_Enter - combined with any modifiers like Shift, -Alt, and Control.

+Alt, and Control.
[Index]    -- cgit v1.2.3