5 - Adding and Extending Widgets

Subclassing

Adding Syntax Highlighting to the Fl_Input Widget

Drawing Functions

Lines, Rectangles, and Curves, Oh, My!

Colors

Fonts

Images

Writing a Table Widget

Methods

Cut and Paste Support

Cut & paste

void Fl::paste(Fl_Widget *receiver)

Set things up so the receiver widget will be called with an FL_PASTE event some time in the future. The reciever should be prepared to be called directly by this, or for it to happen later, or possibly not at all. This allows the window system to take as long as necessary to retrieve the paste buffer (or even to screw up completely) without complex and error-prone synchronization code in fltk.

void Fl::selection(Fl_Widget *owner, const char *stuff, int len);

Change the current selection. The block of text is copied to an internal buffer by Fltk (be careful if doing this in response to an FL_PASTE as this may be the same buffer returned by event_text()). The selection_owner is set to the passed owner (possibly sending FL_SELECTIONCLEAR to the previous owner).

const char* Fl::selection();
int Fl::selection_length();

You can look at the buffer containing the current selection. Contents of this buffer are undefined if this program does not own the X selection.

Fl_Widget *Fl::selection_owner() const;
void Fl::selection_owner(Fl_Widget *);

The single-argument selection_owner(x) call can be used to move the selection to another widget or to set the owner to NULL, without changing the actual text of the selection. FL_SELECTIONCLEAR is sent to the old selection owner, if any.

Copying the buffer every time the selection is changed is obviously wasteful, especially for large selections. I expect an interface will be added in a future version to allow the selection to be made by a callback function. The current interface will be emulated on top of this.

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.

Parts of this document:

• Constructing your Fl_Widget
• Protected methods of Fl_Widget
• Virtual functions to override:
  • int Fl_Widget::handle(int event);
  • void Fl_Widget::draw();
  • void Fl_Widget::resize(int,int,int,int);
  • Fl_Widget::~Fl_Widget();
• Making a Composite/Group Widget
• Making a subclass of Fl_Window

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

This will allow the class name to be typed into fluid and it will produce the correct call.

The constructor must call the constructor for the base class and pass the same arguments. 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_GRAY);
    selection_color(FL_GRAY);
    labeltype(FL_NORMAL_LABEL);
    labelstyle(FL_NORMAL_STYLE);
    labelsize(FL_NORMAL_SIZE);
    labelcolor(FL_BLACK);
    align(FL_ALIGN_CENTER);
    callback(default_callback,0);
    flags(ACTIVE|VISIBLE);

The property Fl_Widget::type() can return an arbitrary 8-bit identifier, and can be set with the protected method type(uchar). This value had to be provided for Forms compatability, 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 Infomation), 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 mechanisim, by having type() have a unique value. These unique values must be greater than the symbol FL_RESERVED_TYPE (which is 100). Grep through the header files for "FL_RESERVED_TYPE" to find an unused number. If you make a subclass of Fl_Group you must use FL_GROUP+n, and if you make a subclass of Fl_Window you must use FL_WINDOW+n (in both cases n is in the range 1-7).

void Fl_Widget::set_flag(SHORTCUT_LABEL);

If your constructor calls this it modifies draw_label() so that '&' characters cause an underscore to be printed under the next letter.

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

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 key press, 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 to an arbitrary string.

void Fl_Widget::x(short);
void Fl_Widget::y(short);
void Fl_Widget::w(short);
void Fl_Widget::h(short);

You can directly clobber the values for x(), y(), w(), and h(). Make sure you know what you are doing. This is most useful for temporarily replacing the values before calling handle() or draw() on the base class to "fool" it into working in a different area.

void Fl_Widget::damage(uchar mask);

Indicate 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(-1).

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

Indicate 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, in which case they are forced to the value 6 for internal reasons).

void Fl_Widget::clear_damage(uchar value = 0);

Directly set damage() to the passed value. This is provided for kludges only.

uchar Fl_Widget::damage()

Return the bitwise-or of all damage(n) calls done since the last draw(). The public method redraw() does damage(-1), but the implementation of your widget can call the private damage(n).

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.

void Fl_Widget::draw_box() const ;

Draw this widget's box(), using the dimensions of the widget.

void Fl_Widget::draw_box(Fl_Boxtype b,ulong c) const ;

Pretend the box()==b and the color()==c and draw this widget's box.

void Fl_Widget::draw_label() const ;

This 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).

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

Do the same thing except use the passed bounding box. This is useful so "centered" labels are aligned with some feature, such as a moving slider.

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

Draw the label anywhere. It acts as though FL_ALIGN_INSIDE has been forced on, the label will appear inside the passed bounding box. This is designed for parent groups to draw labels with.

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

Events are identified the small integer argument. Other information about the most recent event is stored in static locations and aquired by calling Fl::event_*(). This other information remains valid until another event is read from the X server.

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

int Fl_Pushbutton::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, so that the callback
	// may delete the widget!
      }
      return 1;
    case FL_SHORTCUT:
      if (Fl::event_key() == 'x') {do_callback(); return 1;}
      return 0;
    default:
      return 0;
    }
  }
}

You must return non-zero if your handle() method used the event. If you return zero it indicates to the parent that it can try sending another widget the event.

It looks like it is best to make the handle() method public.

virtual void Fl_Widget::draw()

Expose events (and the above damage(b,x,y,w,h)) will cause draw() to be called with fltk's clipping turned on. You can greatly speed up redrawing in some cases by testing fl_clipped and fl_current_clip and skipping invisible parts.

The functions you can use to draw are described in <FL/fl_draw.H> or any of the protected Fl_Widget::draw_* methods described above.

virtual void Fl_Widget::resize(int,int,int,int);

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

It may be useful to refer to the size the widget was constructed at, these are stored in Fl_Widget::ix(), iy(), iw(), and ih().

Resize should be declared public.

virtual Fl_Widget::~Fl_Widget();

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

class MyClass : public Fl_Group {
  Fl_Button the_button;
  Fl_Slider the_slider;
  ...
};

The constructor has to initialize these instances. They are automatically add()ed to the group, since the Fl_Group constructor does begin(). Don't forget to call end():

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::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 (notice that 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 ...
}

If you override draw() you need to draw all the children. If redraw() or damage() is called on a child, damage(1) is done to the group. Thus the 1 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:

int MyClass::draw() {
  Fl_Widget*const* a = array();
  if (damage()==1) { // 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 want to do this
    }
  }
}

Fl_Group provides some protected methods to make drawing easier:

void Fl_Group::draw_outside_label(Fl_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::draw_child(Fl_Widget&);

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::update_child(Fl_Widget&);

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

You may also want to subclass Fl_Window in order to get access to different X visuals or to change other X attributes of the windows, See here for details.

(back to contents)