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/common.dox | 667 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 667 insertions(+) create mode 100644 documentation/common.dox (limited to 'documentation/common.dox') diff --git a/documentation/common.dox b/documentation/common.dox new file mode 100644 index 000000000..20553873e --- /dev/null +++ b/documentation/common.dox @@ -0,0 +1,667 @@ +/** + + \page common 3 - Common Widgets and Attributes + +

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

+ +

Buttons

+ +

FLTK provides many types of buttons:

+ + + +

FLTK Buttons
+Figure 3-1: FLTK Button Widgets

+ +

All of these buttons just need the corresponding +<FL/Fl_xyz_Button.H> 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() +method; this will also turn off other radio buttons in the same +group.

+ +

Text

+ +

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

+ + + +

Valuators

+ +

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

+ + + +

FLTK Valuators
+Figure 3-2: FLTK valuator widgets

+ +

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.

+ + + +

Groups

+ +

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:

+ + + +

Setting the Size and Position of Widgets

+ +

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.

+ +

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

+ + + +

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

+ +

Colors

+ +

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.

+ +

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

+ + + +

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

+ + + +

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

+ + + +

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

+ + + +

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

+ + + +

Box Types

+ +

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.

+ +

FLTK Box Types
+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 +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.

+ +

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.

+ +
+ + + +
Note: +

This interface has changed in FLTK 2.0!

+
+ +

The Drawing Function

+ +

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

+ + + + + +

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

+ + + +

Fl_Boxtype fl_down(Fl_Boxtype)

+ +

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)

+ +

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)

+ +

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

Adding Your Box Type

+ +

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

+ + + +

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.

+ +

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.

+ +

Labels and Label Types

+ +

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

+ +

label()

+ +

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.

+ +

FLTK Symbols
+Figure 3-4: FLTK label symbols

+ + + +

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 +label string "@+92->". + +

align()

+ +

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

+ + + +

labeltype()

+ +

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

+ + + +

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.

+ +

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

+ +

Making Your Own Label Types

+ +

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.

+ +
+ + + +
Note: +

This interface has changed in FLTK 2.0!

+
+ +
Label Type Functions
+ +

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 +structure containing the label information, the bounding box for +the label, and the label alignment:

+ + + +

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 function should measure the size of the label and set +w and h to the size it will occupy.

+ +
Adding Your Label Type
+ +

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

+ + + +

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.

+ +

Making your own symbols

+ +

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.

+ +

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:

+ + + +

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.

+ + + +

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

Callbacks

+ +

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:

+ + + +

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

+ + + +

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

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

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() + method to mark your widget for deletion when it is safe + 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.

+ +

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.

+ +
+class Foo {
+  void my_callback(Fl_Widget *w);
+  static void my_static_callback(Fl_Widget *w, void *f) { ((Foo *)f)->my_callback(w); }
+  ...
+}
+
+...
+
+w->callback(my_static_callback, (void *)this);
+
+
+ +

Shortcuts

+ +

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

+ + + +

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

+ +*/ -- cgit v1.2.3