# 7 - Adding and Extending Widgets

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

## Subclassing

New widgets are created by subclassing an existing pyFltk 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 widget class in pyFltk, and all of the other composite widgets (`Fl_Pack`, `Fl_Scroll`, `Fl_Tabs`, `Fl_Tile`, and `Fl_Window`) 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.

    class MyClass(Fl_Widget):

## The Constructor

The constructor should have the following arguments:

    def __init__(self, xpos, ypos, width, height, label=None):

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

      Fl_Widget.__init__(self, xpos, ypos, width, height, label)
      # do initialization stuff...

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

## Methods of Fl_Widget

The following methods are provided for subclasses to use:

- `Fl_Widget.clear_visible`
- `Fl_Widget.damage`
- `Fl_Widget.draw_box`
- `Fl_Widget.draw_focus`
- `Fl_Widget.draw_label`
- `Fl_Widget.set_flag`
- `Fl_Widget.set_visible`
- `Fl_Widget.test_shortcut`
- `Fl_Widget.type`

#### Fl_Widget.damage(mask)
Fl_Widget.damage(mask, xpos, ypos, width, height)
mask <- 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 private `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 pyFltk 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:

    MyClass.handle(self, event):
      ...
      if change_to_part1: damage(1)
      if change_to_part2: damage(2)
      if change_to_part3: damage(4)

    MyClass.draw(self):
      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_Widget.draw_box()
Fl_Widget.draw_box(boxtype, color)

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

#### Fl_Widget.draw_focus()
Fl_Widget.draw_focus(boxtype, xpos, ypos, width, height)

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

#### Fl_Widget.draw_label()
Fl_Widget.draw_label(xpos, ypos, width, height)
Fl_Widget.draw_label(xpos, ypos, width, height, align)

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

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.

#### Fl_Widget.set_flag(SHORTCUT_LABEL)

Modifies `draw_label()` so that '&' characters cause an underscore to be printed under the next letter.

#### Fl_Widget.set_visible()
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.

#### shortcut_status <- Fl_Widget.test_shortcut()
shortcut_status <- Fl_Widget.test_shortcut(string)

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 against an arbitrary string.

#### type <- Fl_Widget.type() const
Fl_Widget.type(type)

The property `Fl_Widget.type()` can return an arbitrary 8-bit identifier, and can be set with the protected method `type(type)` . 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.

## Handling Events

The virtual method `handled <- Fl_Widget.handle(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(n)` if the widget needs a partial-update (assuming 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 by the integer argument. Other information about the most recent event is stored in static locations and aquired by calling the `Fl.event_*()` functions. 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:

    def MyClass.handle(self, event):
        if event == FL_PUSH:
          highlight = 1
          redraw()
          return 1
        elif event == FL_DRAG:
            t = Fl.event_inside(self)
            if t != highlight:
              highlight = t
    	  redraw()
          return 1
        elif event == FL_RELEASE:
          if highlight != 0:
    	highlight = 0
    	redraw()
            do_callback()
    	# never do anything after a callback, as the callback
    	# may delete the widget!
          return 1
        elif event == FL_SHORTCUT:
          if Fl.event_key() == 'x':
            do_callback()
    	return 1
          return 0
        else:
          return Fl_Widget.handle(self, event)

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.

## Drawing the Widget

The `draw()` virtual method is called when pyFltk 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 `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. pyFltk 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 above `damage(boxtype,xpos,ypos,width,height)`) will cause `draw()` to be called with pyFltk's clipping turned on. You can greatly speed up redrawing in some cases by testing `fl_not_clipped(xpos,ypos,width,height)` or `fl_clip_box(...)` and skipping invisible parts.

Besides the protected methods described above, pyFltk provides a large number of basic drawing functions, which are described below.

## Resizing the Widget

The `resize(xpos, ypos, width, height)` 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(Fl_Group):
      the_button = None
      the_slider = None
      ...

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()` or use the `Fl_End` pseudo-class:

    # class MyClass
    def __init__(self, xpos, ypos, width, height) :
      Fl_Group.__init__(self, xpos, ypos, width, height)
      self.the_button = Fl_Button(xpos + 5, ypos + 5, 100, 20)
      the_slider = Fl_Slider(xpos, ypos + 50, width, 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. These callbacks can be methods or normal functions:

    # class MyClass
    def slider_cb(self, widget, data):
      do something here

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:

    # class MyClass
    def handle(self, event):
      if Fl_Group.handle(event) != 0: 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(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. `Fl_Group` provides some methods to make drawing easier:

- draw_child
- draw_outside_label
- update_child

#### Fl_Group.draw_child(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.

#### Fl_Group.draw_outside_label(widget)

Draw the labels that are not drawn by `draw_label()`.

#### Fl_Group.update_child(widget)

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

pyFltk provides routines to cut and paste 8-bit text (in the future this may be UTF-8) between applications:

- `Fl.paste`
- `Fl.selection`
- `Fl.selection_owner`

It may be possible to cut/paste non-text data by using `Fl.add_handler()`.

## Drag And Drop Support

pyFltk provides routines to drag and drop 8-bit 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 events:

- `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 "Appendix F - Operating System Issues" for more information.