From ecd2c821be8a72b0364cf3e08d102e3f9a82defc Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Mon, 26 Nov 2001 21:40:14 +0000 Subject: Doco updates. Remove unneeded files from the makefiles directory. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1735 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/common.html | 761 ++++++++++++++++++++++++++++++---------------- 1 file changed, 493 insertions(+), 268 deletions(-) (limited to 'documentation/common.html') diff --git a/documentation/common.html b/documentation/common.html index b13955da2..e05bdfbc8 100644 --- a/documentation/common.html +++ b/documentation/common.html @@ -1,326 +1,515 @@ - + + +

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

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 provides many types of buttons:

+ -

FLTK Buttons -

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

+ +

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

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

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

+ -

FLTK Valuators

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

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

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:

+ - The widget color can be set using the color() 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. In the above diagram -the blue color is the area that is not drawn by the box.

-

Making your own Boxtypes

-Warning: this interface may change in future versions of fltk! -

You can define your own boxtypes by making a small function that draws -the box and adding it to the table of boxtypes. +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: - +

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.

+ +

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. For the FL_SYMBOL_LABEL and image label types the -string contains the actual symbol or image data. + +

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:

+ + +

align()

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

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

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

+ - To make bitmaps or pixmaps you use a method on the -Fl_Bitmap or Fl_Pixmap - objects. + +

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

-Warning: this interface is changing in FLTK 2.0! -

Label types are actually indexes into a table of functions that draw -them. The primary purpose of this is to let you reuse the label() - pointer as a pointer to arbitrary data such as a bitmap or pixmap. You -can also 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. + +

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 to -draw and 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 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.

-

Symbol Labels

-

The FL_SYMBOL_LABEL label type uses the label() -string to look up a small drawing procedure in a hash table. For -historical reasons the string always starts with '@'; if it starts with -something else (or the symbol is not found) the label is drawn -normally: -

FLTK Symbols
-

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

+an existing label type such as FL_NORMAL_LABEL.

+

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 optionally a pointer to data of some sort: - + +
+ + + +
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(Widget *);
+  static void my_static_callback(Widget *w, foo *f) { f->my_callback(w); }
+  ...
+}
+
+...
+
+w->callback(my_static_callback, this);
+
+
+

Shortcuts

- Shortcuts are key sequences that activate widgets (usually 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