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.
class MyClass(Fl_Widget):
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)
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()
Draws a focus box inside the widgets bounding box. The second form allows you to specify a different bounding box.
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.
The second version lets you do this test against an arbitrary string.
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.
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.
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.
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 hereIf 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:
Drag'n'drop operations are initiated by copying data to the clipboard and calling the function Fl.dnd().
Drop attempts are handled via events:
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_Windowis almost exactly like subclassing Fl_Group, and in fact you can easily switch a subclass back and forth. Watch out for the following differences:
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.