# 3 - Common Widgets and Attributes

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

## Buttons

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

Figure 3-1: pyFLTK Button Widgets

The constructor for these buttons takes the bounding box of the button and optionally a label string:

    button = Fl_Button(x, y, width, height, "label");
    lbutton = Fl_Light_Button(x, y, width, height);
    rbutton = Fl_Round_Button(x, y, width, height, "label");

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

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

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

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

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

Figure 3-2: pyFLTK 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 pyFLTK:

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

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

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

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

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

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

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

    c = fl_rgb_color(85, 170, 255)

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

    button.color(FL_RED);

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

    button.labelcolor(FL_WHITE);

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

Figure 3-3: pyFLTK 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.

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

Figure 3-4: pyFLTK 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 horizontaly, '%' flips it verticaly.
- [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->".

### 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_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_TEXT_OVER_IMAGE` - show the label text over the image.
- `FL_IMAGE_OVER_TEXT` - show the label image over the text (default).

### 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 thought the text is raised.
- `FL_ICON_LABEL` - draws the icon associated with the text.

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

## Callbacks

Callbacks are functions or class methods 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:

    def xyz_callback(widget, data):
        ...

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

    xyz_data = 15

    button.callback(xyz_callback, xyz_data);

Normally callbacks are performed only when the value of the widget changes. You can change this using the `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);

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.

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

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