FLTK 1.4.5: Common Widgets and Attributes

FLTK 1.4.5

Loading...
Searching...
No Matches
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:

- Fl_Button - A standard push button.

- Fl_Check_Button - A button with a check box.

- Fl_Light_Button - A push button with a light.

- Fl_Repeat_Button - A push button that repeats when held.

- Fl_Return_Button - A push button that is activated by the `Enter` key.

- Fl_Round_Button - A button with a radio circle.

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:

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");
Fl_Button
Buttons generate callbacks when they are clicked by the user.
Definition Fl_Button.H:76
Fl_Light_Button
This subclass displays the "on" state by turning on a light, rather than drawing pushed in.
Definition Fl_Light_Button.H:36
Fl_Round_Button
Buttons generate callbacks when they are clicked by the user.
Definition Fl_Round_Button.H:34

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);
Fl_Widget::type
uchar type() const
Gets the widget type.
Definition Fl_Widget.H:351

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:

- 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_Multiline_Output - A multi-line text output field.

- Fl_Text_Display - A multi-line 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:

Fl_Input *input = new Fl_Input(x, y, width, height, "label");
input->value("Now is the time for all good men...");
Fl_Input_::value
int value(const char *)
Changes the widget text.
Definition Fl_Input_.cxx:1460
Fl_Input
This is the FLTK text input widget.
Definition Fl_Input.H:220

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:

- Fl_Counter - A widget with arrow buttons that shows the current value.

- Fl_Dial - A round knob.

- Fl_Roller - An SGI-like dolly widget.

- Fl_Scrollbar - A standard scrollbar widget.

- Fl_Slider - A scrollbar with a knob.

- Fl_Value_Slider - A slider that shows the current value.

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:

- Fl_Double_Window - A double-buffered window on the screen.

- Fl_Flex - A flexible container of one row or column of widgets. Fl_Flex widgets may be nested, but see also Fl_Grid.

- Fl_Gl_Window - An OpenGL window on the screen.

- Fl_Grid - A flexible container of one or more rows and columns of widgets arranged in a "grid" with auto-layout features. Fl_Grid widgets can be nested with other Fl_Grid or many Fl_Group type widgets. Nesting with other self-resizing containers like Fl_Pack and Fl_Tile is not recommended but may work.

- 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_Scroll - A scrolled window area.

- Fl_Tabs - Displays child widgets as tabs.

- Fl_Tile - A tiled window area.

- Fl_Window - A window on the screen.

- Fl_Wizard - Displays one group of widgets at a time.

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

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

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 a 32-bit unsigned number that is either an index into a color palette of 256 colors (0 <= color <= 255) or a 24-bit RGB color (color > 255). The color palette is not the X or Windows colormap, but instead is an internal table with fixed contents.

See the Colors section of Drawing Things in FLTK for implementation details.

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

- `FL_BLACK`
- `FL_RED`
- `FL_GREEN`
- `FL_YELLOW`
- `FL_BLUE`
- `FL_MAGENTA`
- `FL_CYAN`
- `FL_WHITE`

Other symbols are used as the default colors for all FLTK widgets.

- `FL_FOREGROUND_COLOR`
- `FL_BACKGROUND_COLOR`
- `FL_INACTIVE_COLOR`
- `FL_SELECTION_COLOR`

The full list of named color values can be found in FLTK Enumerations.

A color value can be created from its RGB components by using the `fl_rgb_color`() function, and decomposed again with `Fl::get_color()`:

Fl_Color c = fl_rgb_color(85, 170, 255); // RGB to Fl_Color
Fl::get_color(c, r, g, b); // Fl_Color to RGB
fl_rgb_color
Fl_Color fl_rgb_color(uchar r, uchar g, uchar b)
Returns the 24-bit color value closest to r, g, b.
Definition Enumerations.H:1234
Fl_Color
unsigned int Fl_Color
An FLTK color value; see also Colors.
Definition Enumerations.H:1120
Fl::get_color
static unsigned get_color(Fl_Color i)
Returns the RGB value(s) for the given FLTK color index.
Definition fl_color.cxx:51

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

button->color(FL_RED); // set color using named value

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

button->labelcolor(FL_WHITE);

The Fl_Color encoding maps to a 32-bit unsigned integer representing RGBI, so it is also possible to specify a color using a hex constant as a color map index:

button->color(0x000000ff); // colormap index #255 (FL_WHITE)

or specify a color using a hex constant for the RGB components:

button->color(0xff000000); // RGB: red
button->color(0x00ff0000); // RGB: green
button->color(0x0000ff00); // RGB: blue
button->color(0xffffff00); // RGB: white

Note
  If TrueColor is not available, any RGB colors will be set to the nearest entry in the colormap.

# Box Types

The type Fl_Boxtype stored and returned in Fl_Widget::box() is an enumeration defined in Enumerations.H.

These are the standard box types included with FLTK:

FLTK Standard 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 the image above 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.

The Drawing Function

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

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:

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);
}
fl_color
Fl_Color fl_color()
Return the last fl_color() that was set.
Definition fl_draw.H:74
fl_rectf
void fl_rectf(int x, int y, int w, int h)
Color with current color a rectangle that exactly fills the given bounding box.
Definition fl_draw.H:339
fl_rect
void fl_rect(int x, int y, int w, int h)
Draw a border inside the given bounding box.
Definition fl_draw.H:298

Fl_Boxtype fl_down(Fl_Boxtype b)

  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 Drawing Functions for more details.

Fl_Boxtype fl_frame(Fl_Boxtype b)

  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 Drawing Functions for more details.

Fl_Boxtype fl_box(Fl_Boxtype b)

  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 Drawing Functions for more details.

Adding Your Box Type

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

#define XYZ_BOX FL_FREE_BOXTYPE
Fl::set_boxtype(XYZ_BOX, xyz_draw, 1, 1, 2, 2);
Fl::set_boxtype
static void set_boxtype(Fl_Boxtype, Fl_Box_Draw_F *, uchar, uchar, uchar, uchar, Fl_Box_Draw_Focus_F *=NULL)
Sets the function to call to draw a specific box type.
Definition fl_boxtype.cxx:448

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 dividable by two. fl_frame(Fl_Boxtype) expects the `UP_BOX` design at a value dividable 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. These are the available symbols:

FLTK label symbols

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

- '#' forces square scaling, rather than distortion to the widget's shape.

- +[1-9] or -[1-9] tweaks the scaling a little bigger or smaller.

- '$' flips the symbol horizontally, '%' flips it vertically.

- [0-9] - rotates by a multiple of 45 degrees. '5' and '6' do no rotation while the others point in the direction of that key on a numeric keypad. '0', followed by four more digits rotates the symbol by that amount in degrees.

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

Symbols and text can be combined in a label, however the symbol must be at the beginning and/or at the end of the text. If the text spans multiple lines, the symbol or symbols will scale up to match the height of all the lines.

FLTK symbols and text

align()

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

- `FL_ALIGN_CENTER` - center the label in the widget.
- `FL_ALIGN_TOP` - align the label at the top of the widget.
- `FL_ALIGN_BOTTOM` - align the label at the bottom of the widget.
- `FL_ALIGN_LEFT` - align the label to the left of the widget.
- `FL_ALIGN_RIGHT` - align the label to the right of the widget.
- `FL_ALIGN_LEFT_TOP` - The label appears to the left of the widget, aligned at the top. Outside labels only.
- `FL_ALIGN_RIGHT_TOP` - The label appears to the right of the widget, aligned at the top. Outside labels only.
- `FL_ALIGN_LEFT_BOTTOM` - The label appears to the left of the widget, aligned at the bottom. Outside labels only.
- `FL_ALIGN_RIGHT_BOTTOM` - The label appears to the right of the widget, aligned at the bottom. Outside labels only.
- `FL_ALIGN_INSIDE` - align the label inside the widget.
- `FL_ALIGN_CLIP` - clip the label to the widget's bounding box.
- `FL_ALIGN_WRAP` - wrap the label text as needed.
- `FL_ALIGN_TEXT_OVER_IMAGE` - show the label text over the image.
- `FL_ALIGN_IMAGE_OVER_TEXT` - show the label image over the text (default).
- `FL_ALIGN_IMAGE_NEXT_TO_TEXT` - The image will appear to the left of the text.
- `FL_ALIGN_TEXT_NEXT_TO_IMAGE` - The image will appear to the right of the text.
- `FL_ALIGN_IMAGE_BACKDROP` - The image will be used as a background for the widget.

labeltype()

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

- `FL_NORMAL_LABEL` - draws the text.
- `FL_NO_LABEL` - does nothing.
- `FL_SHADOW_LABEL` - draws a drop shadow under the text.
- `FL_ENGRAVED_LABEL` - draws edges as though the text is engraved.
- `FL_EMBOSSED_LABEL` - draws edges as though the text is raised.
- `FL_ICON_LABEL` - draws the icon (Fl_Image) associated with the text.
- `FL_IMAGE_LABEL` - draws the image (Fl_Image) associated with the text.
- `FL_MULTI_LABEL` - draws multiple parts side by side, see Fl_Multi_Label.

Note
  Some of these labeltypes are no longer necessary for normal widgets. Widgets allow for an image and a text side by side, depending on the widget's align() flag. FL_MULTI_LABEL was designed to be used with Fl_Menu_Item's to support icons or small images, typically left of the menu text.
  As of this writing (FLTK 1.4.0) Fl_Menu_Items support only one label part (text or image), but using Fl_Multi_Label as the label can extend this to more than one part.

See also
  class Fl_Multi_Label, Fl_Widget::align()

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() mechanism (e.g. FL_ENGRAVED_LABEL) or with program-generated letters or symbology.

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:

void xyz_draw(const Fl_Label *label, int x, int y, int w, int h, Fl_Align align) {
...
}
Fl_Align
unsigned Fl_Align
FLTK type for alignment control.
Definition Enumerations.H:986
Fl_Label
This struct stores all information for a text or mixed graphics label.
Definition Fl_Widget.H:49

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:

void xyz_measure(const Fl_Label *label, int &w, int &h) {
...
}

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:

#define XYZ_LABEL FL_FREE_LABELTYPE
Fl::set_labeltype(XYZ_LABEL, xyz_draw, xyz_measure);
Fl::set_labeltype
static void set_labeltype(Fl_Labeltype, Fl_Label_Draw_F *, Fl_Label_Measure_F *)
Sets the functions to call to draw and measure a specific labeltype.
Definition fl_labeltype.cxx:75

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 functions described in Drawing Complex Shapes 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():

int fl_add_symbol(const char *name, void (*drawit)(Fl_Color), int scalable)
fl_add_symbol
int fl_add_symbol(const char *name, void(*drawit)(Fl_Color), int scalable)
Adds a symbol to the system.
Definition fl_symbols.cxx:77

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

int fl_draw_symbol(const char *name,int x,int y,int w,int h,Fl_Color col)
fl_draw_symbol
int fl_draw_symbol(const char *label, int x, int y, int w, int h, Fl_Color)
Draw the named symbol in the given rectangle using the given color.
Definition fl_symbols.cxx:102

This function draws 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:

void xyz_callback(Fl_Widget *w, void *data) {
...
}
Fl_Widget
Fl_Widget is the base class for all widgets in FLTK.
Definition Fl_Widget.H:112

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

int xyz_data;
button->callback(xyz_callback, &xyz_data);

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.

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);

In an effort to make callbacks easier, more flexible, and type safe, FLTK provides three groups of macros that generate the code needed to call class methods directly with up to five custom parameters.

- FL_FUNCTION_CALLBACK_#(WIDGET, FUNCTION, ...) creates code for callbacks to functions and static class methods with up to five arguments. The # must be replaced by the number of callback arguments.
- FL_METHOD_CALLBACK_#(WIDGET, CLASS, SELF, METH, ...) creates code for callbacks to arbitrary public class methods
- FL_INLINE_CALLBACK_#(WIDGET, ..., FUNCTION_BODY) creates code for callback functions that are very close to (almost in the same line) the widget creation code, similar to lambda function in C++11. The last argument of this macro is the callback code.

The syntax is a bit unconventional, but the resulting code is flexible and needs no additional maintenance. It is also C++98 compatible. For example:

#include <FL/fl_callback_macros.H>
...
Fl_String *str = new Fl_String("FLTK");
Fl_Button *btn = new Fl_Button(10, 10, 100, 100);
FL_METHOD_CALLBACK_2(btn, Fl_String, str, insert, int, 2, const char*, "...");
...
Fl_Button *inline_cb_btn_2 = new Fl_Button(390, 60, 180, 25, "2 args");
FL_INLINE_CALLBACK_2( inline_cb_btn_2,
const char *, text, "FLTK", int, number, 2,
{
fl_message("We received the message %s with %d!", text, number);
}
);
fl_callback_macros.H
This file provides macros for easy function and method callbacks with multiple type safe arguments.
FL_INLINE_CALLBACK_2
#define FL_INLINE_CALLBACK_2(WIDGET, TYPE0, NAME0, VALUE0, TYPE1, NAME1, VALUE1, LAMBDA)
Creates code to declare a callback function in line with instantiating a widget.
Definition fl_callback_macros.H:175

See also
  Fl_Widget::callback(Fl_Callback*, void*), FL_FUNCTION_CALLBACK_3, FL_METHOD_CALLBACK_1, FL_INLINE_CALLBACK_2

# When and Reason

Normally callbacks are performed only when the value of the 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);
FL_WHEN_ENTER_KEY
@ FL_WHEN_ENTER_KEY
Do the callback when the user presses the ENTER key and the value changes.
Definition Enumerations.H:441
FL_WHEN_RELEASE_ALWAYS
@ FL_WHEN_RELEASE_ALWAYS
Do the callback when the button or key is released, even if the value doesn't change.
Definition Enumerations.H:440
FL_WHEN_ENTER_KEY_ALWAYS
@ FL_WHEN_ENTER_KEY_ALWAYS
Do the callback when the user presses the ENTER key, even if the value doesn't change.
Definition Enumerations.H:442
FL_WHEN_NOT_CHANGED
@ FL_WHEN_NOT_CHANGED
Do the callback whenever the user interacts with the widget.
Definition Enumerations.H:438
FL_WHEN_NEVER
@ FL_WHEN_NEVER
Never call the callback.
Definition Enumerations.H:436
FL_WHEN_CHANGED
@ FL_WHEN_CHANGED
Do the callback only when the widget value changes.
Definition Enumerations.H:437
FL_WHEN_RELEASE
@ FL_WHEN_RELEASE
Do the callback when the button or key is released and the value changes.
Definition Enumerations.H:439

Within the callback, you can query why the callback was called using Fl::callback_reason(). For example, setting

myInput->when(FL_WHEN_RELEASE|FL_WHEN_CHANGED)

for a text input field may return FL_REASON_LOST_FOCUS or FL_REASON_CHANGED as a callback reason.

# Shortcuts

Shortcuts are key sequences that activate widgets such as 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
FL_CTRL
#define FL_CTRL
One of the ctrl keys is down.
Definition Enumerations.H:581
FL_ALT
#define FL_ALT
One of the alt keys is down.
Definition Enumerations.H:582
FL_SHIFT
#define FL_SHIFT
One of the shift keys is down.
Definition Enumerations.H:579
FL_Enter
#define FL_Enter
The enter key.
Definition Enumerations.H:490

The shortcut value is the key event value - the ASCII value or one of the special keys described in Fl::event_key() Values combined with any modifiers like `Shift` , `Alt` , and `Control`.

[Prev] FLTK Basics | [Index] | Coordinates and Layout Widgets [Next]