FLTK 1.4.4: Adding and Extending Widgets

FLTK 1.4.4

Loading...
Searching...
No Matches
Adding and Extending Widgets

This chapter describes how to add your own widgets or extend existing widgets in FLTK.

# Subclassing

New widgets are created by subclassing an existing FLTK widget, typically Fl_Widget for controls and Fl_Group for composite widgets.

A control widget typically interacts with the user to receive and/or display a value of some sort.

A composite widget holds a list of child widgets and handles moving, sizing, showing, or hiding them as needed. Fl_Group is the main composite widget class in FLTK, and all of the other composite widgets (Fl_Pack, Fl_Scroll, Fl_Tabs, Fl_Tile, Fl_Window, Fl_Flex, Fl_Grid, etc.) are subclasses of it.

You can also subclass other existing widgets to provide a different look or user-interface. For example, the button widgets are all subclasses of Fl_Button since they all interact with the user via a mouse button click. The only difference is the code that draws the face of the button.

# Making a Subclass of Fl_Widget

Your subclasses can directly descend from Fl_Widget or any subclass of Fl_Widget. Fl_Widget has only four virtual methods, and overriding some or all of these may be necessary.

# The Constructor

The constructor should have the following arguments:

MyClass(int x, int y, int w, int h, const char *label = 0);

This will allow the class to be used in FLUID without problems.

The constructor must call the constructor for the base class and pass the same arguments:

MyClass::MyClass(int x, int y, int w, int h, const char *label)
: Fl_Widget(x, y, w, h, label) {
// do initialization stuff...
}
Fl_Widget
Fl_Widget is the base class for all widgets in FLTK.
Definition Fl_Widget.H:112

Fl_Widget's protected constructor sets `x()`, `y()`, `w()`, `h()`, and `label()` to the passed values and initializes the other instance variables to:

type(0);
box(FL_NO_BOX);
color(FL_BACKGROUND_COLOR);
selection_color(FL_BACKGROUND_COLOR);
labeltype(FL_NORMAL_LABEL);
labelstyle(FL_NORMAL_STYLE);
labelsize(FL_NORMAL_SIZE);
labelcolor(FL_FOREGROUND_COLOR);
align(FL_ALIGN_CENTER);
callback(default_callback,0);
flags(ACTIVE|VISIBLE);
image(0);
deimage(0);
FL_ALIGN_CENTER
const Fl_Align FL_ALIGN_CENTER
Align the label horizontally in the middle.
Definition Enumerations.H:989
FL_FOREGROUND_COLOR
const Fl_Color FL_FOREGROUND_COLOR
the default foreground color (0) used for labels and text
Definition Enumerations.H:1123
FL_NORMAL_SIZE
Fl_Fontsize FL_NORMAL_SIZE
normal font size
Definition Fl_Widget.cxx:107
FL_BACKGROUND_COLOR
const Fl_Color FL_BACKGROUND_COLOR
Default background color.
Definition Enumerations.H:1136
FL_NORMAL_LABEL
@ FL_NORMAL_LABEL
draws the text (0)
Definition Enumerations.H:836
FL_NO_BOX
@ FL_NO_BOX
nothing is drawn at all, this box is invisible
Definition Enumerations.H:646

# Protected Methods of Fl_Widget

The following methods are provided for subclasses to use:

- clear_visible()
- damage()
- draw_box()
- draw_focus()
- draw_label()
- set_flag()
- set_visible()
- test_shortcut()
- type()

void Fl_Widget::damage(uchar mask)
void Fl_Widget::damage(uchar mask, int x, int y, int w, int h)
uchar Fl_Widget::damage()

  The first form indicates that a partial update of the object is needed. The bits in mask are OR'd into damage(). Your `draw()` routine can examine these bits to limit what it is drawing. The public method Fl_Widget::redraw() simply does `Fl_Widget::damage(FL_DAMAGE_ALL)`, but the implementation of your widget can call the public `damage(n)`.

  The second form indicates that a region is damaged. If only these calls are done in a window (no calls to `damage(n)`) then FLTK will clip to the union of all these calls before drawing anything. This can greatly speed up incremental displays. The mask bits are OR'd into `damage()` unless this is a Fl_Window widget.

  The third form returns the bitwise-OR of all `damage(n)` calls done since the last `draw()`.

  When redrawing your widgets you should look at the damage bits to see what parts of your widget need redrawing. The `handle()` method can then set individual damage bits to limit the amount of drawing that needs to be done:
  int MyClass::handle(int event) {
  // ...
  if (change_to_part1) damage(1);
  if (change_to_part2) damage(2);
  if (change_to_part3) damage(4);
  }
  void MyClass::draw() {
  if (damage() & FL_DAMAGE_ALL) {
  // ... draw frame/box and other static stuff ...
  }
  if (damage() & (FL_DAMAGE_ALL | 1)) draw_part1();
  if (damage() & (FL_DAMAGE_ALL | 2)) draw_part2();
  if (damage() & (FL_DAMAGE_ALL | 4)) draw_part3();
  }
  FL_DAMAGE_ALL
  @ FL_DAMAGE_ALL
  Everything needs to be redrawn.
  Definition Enumerations.H:1347

Todo
  Clarify Fl_Window::damage(uchar) handling - seems confused/wrong? ORing value doesn't match setting behavior in Fl_Widget.H!

void Fl_Widget::draw_box() const
void Fl_Widget::draw_box(Fl_Boxtype t, Fl_Color c) const

  The first form draws this widget's `box()`, using the dimensions of the widget. The second form uses `t` as the box type and `c` as the color for the box.

void Fl_Widget::draw_focus()
void Fl_Widget::draw_focus(Fl_Boxtype t, int x, int y, int w, int h) const

  Draws a focus box inside the widget's bounding box. The second form allows you to specify a different bounding box.

void Fl_Widget::draw_label() const
void Fl_Widget::draw_label(int x, int y, int w, int h) const
void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align align) const

  The first form is the usual function for a `draw()` method to call to draw the widget's label. It does not draw the label if it is supposed to be outside the box (on the assumption that the enclosing group will draw those labels).

  The second form uses the passed bounding box instead of the widget's bounding box. This is useful so "centered" labels are aligned with some feature, like a moving slider.

  The third form draws the label anywhere. It acts as though `FL_ALIGN_INSIDE` has been forced on so the label will appear inside the passed bounding box. This is designed for parent groups to draw labels with.

void Fl_Widget::set_flag(int c)

  Calling `set_flag(SHORTCUT_LABEL)` modifies the behavior of draw_label() so that '&' characters cause an underscore to be printed under the next letter.

void Fl_Widget::set_visible()
void Fl_Widget::clear_visible()

  Fast inline versions of Fl_Widget::hide() and Fl_Widget::show(). These do not send the `FL_HIDE` and `FL_SHOW` events to the widget.

int Fl_Widget::test_shortcut()
static int Fl_Widget::test_shortcut(const char *s)

  The first version tests Fl_Widget::label() against the current event (which should be a `FL_SHORTCUT` event). If the label contains a '&' character and the character after it matches the keypress, this returns true. This returns false if the `SHORTCUT_LABEL` flag is off, if the label is `NULL`, or does not have a '&' character in it, or if the keypress does not match the character.

  The second version lets you do this test against an arbitrary string.

uchar Fl_Widget::type() const
void Fl_Widget::type(uchar t)

  The property Fl_Widget::type() can return an arbitrary 8-bit identifier, and can be set with the protected method type(uchar t). This value had to be provided for Forms compatibility, but you can use it for any purpose you want. Try to keep the value less than 100 to not interfere with reserved values.

  FLTK does not use RTTI (Run Time Typing Information) to enhance portability. But this may change in the near future if RTTI becomes standard everywhere.

  If you don't have RTTI you can use the clumsy FLTK mechanism, by having `type()` use a unique value. These unique values must be greater than the symbol `FL_RESERVED_TYPE` (which is 100) and less than `FL_WINDOW` (unless you make a subclass of Fl_Window). Look through the header files for `FL_RESERVED_TYPE` to find an unused number. If you make a subclass of Fl_Window you must use FL_WINDOW + n (where `n` must be in the range 1 to 7).

# Handling Events

The virtual method Fl_Widget::handle(int event) is called to handle each event passed to the widget. It can:

- Change the state of the widget.
- Call Fl_Widget::redraw() if the widget needs to be redisplayed.
- Call Fl_Widget::damage(uchar c) if the widget needs a partial-update (assuming you provide support for this in your draw() method).
- Call Fl_Widget::do_callback() if a callback should be generated.
- Call Fl_Widget::handle() on child widgets.

Events are identified by the integer argument. Other information about the most recent event is stored in static locations and acquired by calling the Fl::event_*() methods. This information remains valid until another event is handled.

Here is a sample `handle()` method for a widget that acts as a pushbutton and also accepts the keystroke `'x'` to cause the callback:

int MyClass::handle(int event) {
switch (event) {
case FL_PUSH:
highlight = 1;
redraw();
return 1;
case FL_DRAG: {
int t = Fl::event_inside(this);
if (t != highlight) {
highlight = t;
redraw();
}
}
return 1;
case FL_RELEASE:
if (highlight) {
highlight = 0;
redraw();
do_callback();
// never do anything after a callback, as the callback
// may delete the widget!
}
return 1;
case FL_SHORTCUT:
if (Fl::event_key() == 'x') {
do_callback();
return 1;
}
return 0;
default:
return Fl_Widget::handle(event);
}
}
FL_PUSH
@ FL_PUSH
A mouse button has gone down with the mouse pointing at this widget.
Definition Enumerations.H:220
FL_RELEASE
@ FL_RELEASE
A mouse button has been released.
Definition Enumerations.H:228
FL_SHORTCUT
@ FL_SHORTCUT
If the Fl::focus() widget is zero or ignores an FL_KEYBOARD event then FLTK tries sending this event ...
Definition Enumerations.H:333
FL_DRAG
@ FL_DRAG
The mouse has moved with a button held down.
Definition Enumerations.H:252
Fl_Widget::handle
virtual int handle(int event)
Handles the specified event.
Definition Fl_Widget.cxx:102
Fl::event_key
static int event_key()
Gets which key on the keyboard was last pushed.
Definition Fl.H:773
Fl::event_inside
static int event_inside(int, int, int, int)
Returns whether or not the mouse event is inside the given rectangle.
Definition Fl.cxx:198

You must return non-zero if your `handle()` method uses the event. If you return zero, the parent widget will try sending the event to another widget.

For debugging purposes, event numbers can be printed as their actual event names using the fl_eventnames[] array, e.g.:

#include <FL/names.h> // defines fl_eventnames[]
[..]
int MyClass::handle(int e) {
printf("Event was %s (%d)\n", fl_eventnames[e], e); // e.g. "Event was FL_PUSH (1)"
[..]
fl_eventnames
const char *const fl_eventnames[]
This is an array of event names you can use to convert event numbers into names.
Definition names.h:46
names.h
This file defines arrays of human readable names for FLTK symbolic constants.

# Drawing the Widget

The `draw()` virtual method is called when FLTK wants you to redraw your widget. It will be called if and only if `damage()` is non-zero, and `damage()` will be cleared to zero after it returns. The `draw()` method should be declared protected so that it can't be called from non-drawing code.

The `damage()` value contains the bitwise-OR of all the `damage(n)` calls to this widget since it was last drawn. This can be used for minimal update, by only redrawing the parts whose bits are set. FLTK will turn on the `FL_DAMAGE_ALL` bit if it thinks the entire widget must be redrawn, e.g. for an expose event.

Expose events (and the damage(mask,x,y,w,h) function described above) will cause `draw()` to be called with FLTK's clipping turned on. You can greatly speed up redrawing in some cases by testing `fl_not_clipped(x,y,w,h)` or `fl_clip_box`() and skipping invisible parts.

Besides the protected methods described above, FLTK provides a large number of basic drawing functions, which are described in the chapter Drawing Things in FLTK.

# Resizing the Widget

The `resize(x,y,w,h)` method is called when the widget is being resized or moved. The arguments are the new position, width, and height. `x()`, `y()`, `w()`, and `h()` still remain the old size. You must call `resize()` on your base class with the same arguments to get the widget size to actually change.

This should not call `redraw()`, at least if only the `x()` and `y()` change. This is because composite widgets like Fl_Scroll may have a more efficient way of drawing the new position.

# Making a Composite Widget

A "composite" widget contains one or more "child" widgets. To make a composite widget you should subclass Fl_Group. It is possible to make a composite object that is not a subclass of Fl_Group, but you'll have to duplicate the code in Fl_Group anyways.

Instances of the child widgets may be included in the parent:

class MyClass : public Fl_Group {
Fl_Button the_button;
Fl_Slider the_slider;
...
};
Fl_Button
Buttons generate callbacks when they are clicked by the user.
Definition Fl_Button.H:76
Fl_Group
The Fl_Group class is the main FLTK container widget.
Definition Fl_Group.H:56
Fl_Slider
The Fl_Slider widget contains a sliding knob inside a box.
Definition Fl_Slider.H:59

The constructor has to initialize these instances. They are automatically added to the group, since the Fl_Group constructor does Fl_Group::begin(). Don't forget to call Fl_Group::end() or use the Fl_End pseudo-class:

MyClass::MyClass(int x, int y, int w, int h) :
Fl_Group(x, y, w, h),
the_button(x + 5, y + 5, 100, 20),
the_slider(x, y + 50, w, 20)
{
...(you could add dynamically created child widgets here)...
end(); // don't forget to do this!
}

The child widgets need callbacks. These will be called with a pointer to the children, but the widget itself may be found in the `parent()` pointer of the child. Usually these callbacks can be static private methods, with a matching private method:

void MyClass::static_slider_cb(Fl_Widget* v, void *) { // static method
((MyClass*)(v->parent())->slider_cb();
}
void MyClass::slider_cb() { // normal method
use(the_slider->value());
}

If you make the `handle()` method, you can quickly pass all the events to the children using the Fl_Group::handle() method. You don't need to override `handle()` if your composite widget does nothing other than pass events to the children:

int MyClass::handle(int event) {
if (Fl_Group::handle(event)) return 1;
... handle events that children don't want ...
}
Fl_Group::handle
int handle(int) FL_OVERRIDE
Handles the specified event.
Definition Fl_Group.cxx:145

If you override `draw()` you need to draw all the children. If `redraw()` or `damage()` is called on a child, `damage(FL_DAMAGE_CHILD)` is done to the group, so this bit of `damage()` can be used to indicate that a child needs to be drawn. It is fastest if you avoid drawing anything else in this case:

void MyClass::draw() {
Fl_Widget *const*a = array();
if (damage() == FL_DAMAGE_CHILD) { // only redraw some children
for (int i = children(); i--; a++) {
update_child(**a);
}
} else { // total redraw
// ... draw background graphics ...
// now draw all the children atop the background:
for (int i = children(); i--; a++) {
draw_child(**a);
draw_outside_label(**a); // you may not need to do this
}
}
}
FL_DAMAGE_CHILD
@ FL_DAMAGE_CHILD
A child needs to be redrawn.
Definition Enumerations.H:1341

Fl_Group provides some protected methods to make drawing easier:

- draw_child()
- draw_children()
- draw_outside_label()
- update_child()

void Fl_Group::draw_child(Fl_Widget &widget) const

  This will force the child's `damage()` bits all to one and call `draw()` on it, then clear the `damage()`. You should call this on all children if a total redraw of your widget is requested, or if you draw something (like a background box) that damages the child. Nothing is done if the child is not `visible()` or if it is clipped.

void Fl_Group::draw_children()

  A convenience function that draws all children of the group. This is useful if you derived a widget from Fl_Group and want to draw a special border or background. You can call `draw_children()` from the derived `draw()` method after drawing the box, border, or background.

void Fl_Group::draw_outside_label(const Fl_Widget &widget) const

  Draw the labels that are not drawn by draw_label(). If you want more control over the label positions you might want to call child->draw_label(x,y,w,h,a).

void Fl_Group::update_child(Fl_Widget& widget) const

  Draws the child only if its `damage()` is non-zero. You should call this on all the children if your own damage is equal to `FL_DAMAGE_CHILD`. Nothing is done if the child is not `visible()` or if it is clipped.

# Cut and Paste Support

FLTK provides routines to cut and paste UTF-8 encoded text between applications:

- Fl::copy()
- Fl::paste()
- Fl::selection()
- Fl::selection_owner()

It is also possible to copy and paste image data between applications:

- Fl_Copy_Surface
- Fl::clipboard_contains()
- Fl::paste()

It may be possible to cut/paste other kinds of data by using Fl::add_handler(). Note that handling events beyond those provided by FLTK may be operating system specific. See Operating System Issues for more details.

# Drag And Drop Support

FLTK provides routines to drag and drop UTF-8 encoded text between applications:

Drag'n'drop operations are initiated by copying data to the clipboard and calling the function Fl::dnd().

Drop attempts are handled via the following events, already described under Drag and Drop Events in a previous chapter:

- `FL_DND_ENTER`
- `FL_DND_DRAG`
- `FL_DND_LEAVE`
- `FL_DND_RELEASE`
- `FL_PASTE`

# Making a subclass of Fl_Window

You may want your widget to be a subclass of Fl_Window, Fl_Double_Window, or Fl_Gl_Window. This can be useful if your widget wants to occupy an entire window, and can also be used to take advantage of system-provided clipping, or to work with a library that expects a system window ID to indicate where to draw.

Subclassing Fl_Window is almost exactly like subclassing Fl_Group, and in fact you can easily switch a subclass back and forth. Watch out for the following differences:

1. Fl_Window is a subclass of Fl_Group so make sure your constructor calls `end()` unless you actually want children added to your window.
2. When handling events and drawing, the upper-left corner is at 0,0, not x(),y() as in other Fl_Widget's. For instance, to draw a box around the widget, call draw_box(0,0,w(),h()), rather than draw_box(x(),y(),w(),h()).

You may also want to subclass Fl_Window in order to get access to different visuals or to change other attributes of the windows. See the Operating System Issues chapter for more information.

[Prev] Handling Events | [Index] | Using OpenGL [Next]