3 - Common Widgets and Attributes

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

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:

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

button->type(0);
lbutton->type(FL_TOGGLE_BUTTON);
rbutton->type(FL_RADIO_BUTTON);

Text

• Fl_Input - A standard one-line text input field.
• Fl_Output - A standard one-line text output field.
• Fl_Multiline_Input - A standard multi-line text input field.
• Fl_Multiline_Output - A standard multi-line text output field.

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

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

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.

Groups

• Fl_Double_Window - A double-buffered window on the screen.
• Fl_Gl_Window - An OpenGL window on the screen.
• Fl_Group - The base container class; can be used to group any widgets together.
• Fl_Scroll - A scrolled window area.
• Fl_Tabs - Displays child widgets as tabs.
• Fl_Window - A window on the screen.

Setting the Size and Position of Widgets

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

Colors

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

• FL_BLACK (this is the default label color)
• FL_RED
• FL_GREEN
• FL_YELLOW
• FL_BLUE
• FL_MAGENTA
• FL_CYAN
• FL_WHITE (this is the default background color of text widgets)
• FL_GRAY (this is the default background color of most widgets)

button->color(FL_RED);

button->labelcolor(FL_WHITE);

Box Types

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

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

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

void xyz_draw(int x, int y, int w, int h, Fl_Color c) {
...
}

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

Adding Your Box Type

#define XYZ_BOX FL_FREE_BOXTYPE

Fl::set_boxtype(XYZ_BOX, xyz_draw, 1, 1, 2, 2);

Labels and Label Types

label()

align()

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

labeltype()

• FL_NORMAL_LABEL - draws the text.
• FL_NO_LABEL - does nothing
• FL_SYMBOL_LABEL - draws "@xyz" labels, see " Symbol Labels"
• 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 thought the text is raised

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 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 Type Functions

void xyz_draw(Fl_Label *label, int x, int y, int w, int h, Fl_Align align) {
...
}

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

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

Adding Your Label Type

#define XYZ_LABEL FL_FREE_LABELTYPE

Fl::set_labeltype(XYZ_LABEL, xyz_draw, xyz_measure);

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:

The @ sign may 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.
• [1-9] - rotates by a multiple of 45 degrees. '6' does nothing, the others point in the direction of that key on a numeric keypad.

Callbacks

void xyz_callback(Fl_Widget *w, void *data) {
...
}

int xyz_data;

button->callback(xyz_callback, data);

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

Shortcuts

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