Fltk Buttons

Buttons generate callbacks when they are clicked by the user. You control exactly when and how by changing the values for type() and when().

Buttons can also generate callbacks in response to FL_SHORTCUT events. The button can either have an explicit shortcut() value or a letter shortcut can be indicated in the label() with an '&' character before it. For the label shortcut it does not matter if Alt is held down, but if you have an input field in the same window, the user will have to hold down the Alt key so that the input field does not eat the event first as an FL_KEYBOARD event.

Besides the base class there are some useful subclasses defined:

class Fl_Light_Button : public Fl_Button

This subclass display the "on" state by turning on a light, rather than drawing pushed in. The shape of the "light" is controlled by down_box() (if down_box() is zero then a Flame-style rectangle light is drawn). The color of the light when on is controlled with selection_color(), which defaults to FL_YELLOW.

class Fl_Round_Button : public Fl_Light_Button
class Fl_Check_Button : public Fl_Light_Button

These subclasses set box() to FL_NO_BOX, down_box() to FL_ROUND_DOWN_BOX or FL_DIAMOND_DOWN_BOX, and selection_color() to red.

class Fl_Return_Button : public Fl_Button

This subclass has a built-in shortcut for the Enter Key, and draws a "return arrow" on the right edge.

class Fl_Repeat_Button : public Fl_Button

This subclass generates a callback when it is pressed, and then repeatedly generates callbacks as long as it is held down. The speed of the repeat is fixed and depends on the implementation.

class Fl_Button : public Fl_Widget

Fl_Button::Fl_Button(int,int,int,int,const char * = 0);

The constructor, takes a position, size, and label.

uchar Fl_Button::type() const;
void Fl_Button::type(uchar);

What happens to the button when you click it (or type a shortcut key):
• 0 : The value is unchanged.
• FL_TOGGLE_BUTTON : The value is inverted.
• FL_RADIO_BUTTON : The value is set to 1, and all other buttons in the current group with type()==FL_RADIO_BUTTON are set to zero.

The Fl_Light_Button, Fl_Round_Button, and Fl_Check_Button subclasses default type() to FL_TOGGLE_BUTTON, all other subclasses default to zero.

Fl_When Fl_Widget::when() const;
void Fl_Widget::when(Fl_When);

Controls when callbacks are done. The following values are useful, the default value is FL_WHEN_RELEASE:
• 0 : The callback is not done, instead changed() is turned on.
• FL_WHEN_RELEASE : The callback is done after the user successfully clicks the button, or when a shortcut is typed.
• FL_WHEN_CHANGED : The callback is done each time the value() changes (when the user pushes and releases the button, and as the mouse is dragged around in and out of the button).

char Fl_Button::value() const;

The current value.

int Fl_Button::value(int);
int Fl_Button::set();
int Fl_Button::clear();

You can directly set the value. value(int) returns non-zero if the value has changed, and redraws the button. set() is the same as value(1), and clear() is the same as value(0).

void Fl_Button::setonly();

Turns on this button and turns off all other radio buttons in the group (calling value(1) does not do this).

Fl_Boxtype Fl_Button::down_box() const;
void Fl_Button::down_box(Fl_Boxtype);

Which box type to draw when Fl_Button::value() is non-zero (when value() is zero it draws box()). The default value of 0 causes fltk to figure out the correct matching down version of box().

ulong Fl_Button::shortcut() const;
void Fl_Button::shortcut(ulong);

Sets exactly what key combination will trigger the button. Setting this overrides the use of '&' in the label(). The value is a logical 'or' of a key and a set of shift flags, for instance FL_ALT+'a' or FL_ALT+FL_F+10 or just 'a'. A value of zero disables the shortcut.

The key can be any value returned by Fl::event_key(), but will usually be an ascii letter. Use a lower-case letter unless you require the shift key to be held down.

The shift flags can be any set of values accepted by Fl::event_state(). If the bit is on that shift key must be pushed. Meta, Alt, Ctrl, and Shift must be off if they are not in the shift flags (zero for the other bits indicates a "don't care" setting).