## Callbacks

Callbacks are functions that are called when the value of a widget changes. A callback function is sent a `fltk::Widget` pointer of the widget that changed and optionally a pointer to data of some sort:

    void xyz_callback(fltk::Widget *w, void *data) {
    ...
    }

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

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

    button->when(fltk::WHEN_NEVER);
    button->when(fltk::WHEN_CHANGED);
    button->when(fltk::WHEN_RELEASE);
    button->when(fltk::WHEN_RELEASE_ALWAYS);
    button->when(fltk::WHEN_ENTER_KEY);
    button->when(fltk::WHEN_ENTER_KEY_ALWAYS);
    button->when(fltk::WHEN_CHANGED | fltk::WHEN_NOT_CHANGED);

## Buttons

FLTK provides many types of buttons:

- `fltk::Button` - A standard button.
- `fltk::CheckButton` - A toggle button with a check box.
- `fltk::LightButton` - A push button with a light.
- `fltk::RepeatButton` - A push button that repeats it's callback when held.
- `fltk::ReturnButton` - A push button that is activated by the Enter key.
- `fltk::Radio_Button` - A button with a circular mark.

For all of these buttons you just need to include the corresponding `<fltk/xyz_Button.h>` header file. The constructor takes the bounding box of the button and optionally a label string:

    fltk::Button *button = new fltk::Button(x, y, width, height, "label");
    fltk::LightButton *lbutton = new fltk::LightButton(x, y, width, height);
    fltk::RoundButton *rbutton = new fltk::RoundButton(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. This type is defaulted for each button type but you can change it.

    button->type(0); // default for all other buttons
    button->type(fltk::TOGGLE_BUTTON); // default for fltk::CheckButton & fltk::LightButton
    button->type(fltk::RADIO_BUTTON); // default for fltk::Radio_Button

The `value()` method returns the current button state (0 = off, 1 = on) (push buttons are on while they are held down). 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::Input` - A standard one-line text input field.
- `fltk::Output` - A standard one-line text output field.
- `fltk::MultilineInput` - A standard multi-line text input field.
- `fltk::MultilineOutput` - A standard multi-line text output field.

The `fltk::Output` and `fltk::MultilineOutput` 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:

    fltk::Input *input = new fltk::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

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

- `fltk::ValueInput` - A text field for a number and up/down arrow buttons (MicroSoft calls this a "spin box")
- `fltk::Slider` - A scrollbar with a knob.
- `fltk::ValueSlider` - A slider that shows the current value.
- `fltk::Dial` - A round knob.
- `fltk::Roller` - An SGI-like dolly widget.
- `fltk::Scrollbar` - A standard scrollbar widget.

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 `fltk::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:

- `fltk::DoubleBufferWindow` - A double-buffered window on the screen.
- `fltk::GlWindow` - An OpenGL window on the screen.
- `fltk::Group` - The base container class; can be used to group any widgets together.
- `fltk::Scroll` - A scrolled window area.
- `fltk::Tabs` - Displays child widgets as tabs.
- `fltk::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

The typedef fltk::Color is a 32-bit number that is used to store a color. For most widgets only the "indexed" colors are used, these are colors with a value less than 256 that is an index into a color palette of 256 colors. This 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:

- `fltk::BLACK`
- `fltk::RED`
- `fltk::GREEN`
- `fltk::YELLOW`
- `fltk::BLUE`
- `fltk::MAGENTA`
- `fltk::CYAN`
- `fltk::WHITE`
- `fltk::GRAY` (this is the default background color of most widgets)

You can also get an arbitrary color with fltk::rgb(r,g,b). However this does not work that well on 8-bit screens. The widget color can be set using the `color()` method:

    button->color(fltk::RED);
    button->color(fltk::rgb(128,200,210));

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

    button->labelcolor(fltk::WHITE);

## Box Types

`fltk::Widget::box()` is a pointer to a struct fltk::Box_. This describes how to draw the box around the widget. By making your own you can cause arbitrary drawing code to be called.

There are macros that are pointers to the built-in box types:

`fltk::NO_BOX` means nothing is drawn at all, so whatever is already on the screen remains. The `fltk::..._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.

## Labels and Label Types

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

### label()

The `label()` method sets the string that is displayed for the label. For the `fltk::SYMBOL_LABEL` and image label types the string contains the actual symbol or image data.

### image()

The `image()` method sets an image that is drawn with the label. The value is a pointer to a class fltk::Image. This class stores the data of the image and also stores a window-system cached copy that is created when the image is first drawn so that redrawing it is very fast.

Different subclasses draw different types of images. The provided types include `fltk::Bitmap`, `fltk::Pixmap`, `fltk::RGB_Image`.

### align()

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

- `fltk::ALIGN_CENTER` - center the label in the widget.
- `fltk::ALIGN_TOP` - align the label at the top of the widget.
- `fltk::ALIGN_BOTTOM` - align the label at the bottom of the widget.
- `fltk::ALIGN_LEFT` - align the label to the left of the widget.
- `fltk::ALIGN_RIGHT` - align the label to the right of the widget.
- `fltk::ALIGN_INSIDE` - align the label inside the widget.
- `fltk::ALIGN_CLIP` - clip the label to the widget's bounding box.
- `fltk::ALIGN_WRAP` - wrap the label text as needed.

If there is an image, it is aligned first. Then the text label is aligned in the same way in the space that remains beside the image. If you need more complex layout you can try making your own image or labeltype objects.

### label_type()

The `label_type()` method sets how to draw the text label. It does not affect the image. The following standard label types are included:

- `fltk::NORMAL_LABEL` - draws the text.
- `fltk::NO_LABEL` - does nothing
- `fltk::SYMBOL_LABEL` - draws "@xyz" labels, see " Symbol Labels"
- `fltk::SHADOW_LABEL` - draws a drop shadow under the text
- `fltk::ENGRAVED_LABEL` - draws edges as though the text is engraved
- `fltk::EMBOSSED_LABEL` - draws edges as thought the text is raised

`fltk::Widget::label_type()` is a pointer to a struct fltk::Labeltype_. By making your own you can cause arbitrary drawing code to be called.

#### Symbol Labels

The `fltk::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.

## Shortcuts

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

    button->shortcut(fltk::Enter);
    button->shortcut(fltk::SHIFT + 'b');
    button->shortcut(fltk::CTRL + 'b');
    button->shortcut(fltk::ALT + 'b');
    button->shortcut(fltk::CTRL + fltk::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 `fltk::Enter`) combined with any modifiers (like shift, alt, and control).