This chapter discusses the FLTK event model and how to handle events in your program or
widget.
The FLTK Event Model
Events are identified by the integer argument passed to the Fl_Widget::handle() virtual method. Other
information about the most recent event is stored in static locations
and acquired by calling the Fl::event_*() methods. This static
information remains valid until the next event is read from window
system (i.e. it is ok to look at it outside of the handle() method).
Mouse Events
FL_PUSH
A mouse button has gone down with the mouse pointing at this widget.
You can find out what button by calling Fl::event_button(). You find out the
mouse position by calling Fl::event_x()
and Fl::event_y().
A widget indicates that it "wants" the mouse click by returning
non-zero from its handle() method. It
will then become the Fl::pushed() widget
and will get FL_DRAG and the matching FL_RELEASE
events. If handle() returns zero then FLTK will try sending
the FL_PUSH to another widget.
FL_DRAG
The mouse has moved with a button held down.
FL_RELEASE
A mouse button has been released. You can find out what button by
calling Fl::event_button().
FL_MOVE
The mouse has moved without any mouse buttons held down. This event
is sent to the belowmouse() widget.
Focus Events
FL_ENTER
The mouse has been moved to point at this widget. This can be used for
highlighting feedback. If a widget wants to highlight or otherwise
track the mouse, it indicates this by returning non-zero from its handle() method. It then becomes the Fl::belowmouse() widget and will
receive FL_MOVE and FL_LEAVE events.
FL_LEAVE
The mouse has moved out of the widget.
FL_FOCUS
This indicates an attempt to give a widget the keyboard
focus.
If a widget wants the focus, it should change itself to display the
fact that it has the focus, and return non-zero from its handle() method. It then becomes the Fl::focus() widget and gets FL_KEYBOARD
and FL_UNFOCUS events.
The focus will change either because the window manager changed
which window gets the focus, or because the user tried to navigate
using tab, arrows, or other keys. You can check Fl::event_key() to figure out why it moved. For
navigation it will be the key pressed and for instructions from the
window manager it will be zero.
FL_UNFOCUS
Sent to the previous Fl::focus() when
another widget gets the focus.
Keyboard Events
FL_KEYBOARD
A key press. The key pressed can be found in Fl::event_key(). The text that the key
should insert can be found with Fl::event_text() and its length is in
Fl::event_length(). If you use
the key handle() should return 1. If you return zero then
FLTK assummes you ignored the key. It will then attempt to send it to
a parent widget. If none of them want it, it will change the event into
a FL_SHORTCUT event.
FL_SHORTCUT
If the Fl::focus() is zero or ignores an
FL_KEYBOARD event then FLTK tries sending this event to every
widget it can, until one of them returns non-zero.
FL_SHORTCUT is first sent to the belowmouse() widget,
then its parents and siblings, and eventually to every widget in the
window, trying to find an object that returns non-zero. FLTK tries
really hard to not to ignore any keystrokes!
You can also make "global" shortcuts by using Fl::add_handler(). A global shortcut
will work no matter what windows are displayed or which one has the
focus.
Widget Events
FL_DEACTIVATE
This widget is no longer active, due to deactivate() being called on
it or one of its parents. active() may still be true after this, the
widget is only active if active() is true on it and all its parents
(use active_r() to check this).
FL_ACTIVATE
This widget is now active, due to activate() being called on it
or one of its parents.
FL_HIDE
This widget is no longer visible, due to show() being called on it or one of
its parents, or due to a parent window being restored. Child
Fl_Windows respond to this by actually creating the window if not
done already, so if you subclass a window, be sure to pass FL_SHOW to
the base class handle() method!
Clipboard Events
FL_PASTE
You should get this event some time after you call Fl::paste(). The contents of Fl::event_text() is the text to insert
and the number of characters is in Fl::event_length().
FL_SELECTIONCLEAR
The Fl::selection_owner() will get this
event before the selection is moved to another widget. This indicates
that some other widget or program has claimed the selection.
FLTK keeps the information about the most recent event in static
storage. This information is good until the next event is processed.
Thus it is valid inside handle() and callback() methods.
These are all trivial inline functions and thus very fast and
small:
FLTK follows very simple and unchangeable rules for sending events. The
major innovation is that widgets can indicate (by returning 0 from the
handle() method) that they are not interested in an event, and
FLTK can then send that event elsewhere. This eliminates the need for
"interests" (event masks or tables), and this is probably the main
reason FLTK is much smaller than other toolkits.
Most events are sent directly to the handle() method of the
Fl_Window that the window system says they belong to. The
window (actually the Fl_Group that Fl_Window is a
subclass of) is responsible for sending the events on to any child
widgets. To make the Fl_Group code somewhat easier, FLTK
sends some events (FL_DRAG, FL_RELEASE,
FL_KEYBOARD, FL_SHORTCUT, FL_UNFOCUS, and
FL_LEAVE) directly to leaf widgets. These procedures control
those leaf widgets: