Events are identified by the integer argument passed to a handle()
method that overrides 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 the window system, so it is ok to look at it outside of the handle()
method.
Event numbers can be converted to their actual names using the fl_eventnames[] array defined in #include <FL/names.h>; see next chapter for details.
In the next chapter, the MyClass::handle() example shows how to override the Fl_Widget::handle() method to accept and process specific events.
A widget indicates that it "wants" the mouse click by returning non-zero from its handle()
method, as in the MyClass::handle() example. 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.
In order to receive FL_DRAG
events, the widget must return non-zero when handling FL_PUSH
.
In order to receive the FL_RELEASE
event, the widget must return non-zero when handling FL_PUSH
.
In order to receive FL_MOVE
events, the widget must return non-zero when handling FL_ENTER
.
handle()
method. It then becomes the Fl::belowmouse() widget and will receive FL_MOVE
and FL_LEAVE
events.
In order to receive the FL_LEAVE
event, the widget must return non-zero when handling FL_ENTER
.
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_KEYDOWN
, FL_KEYUP
, 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 interaction with the window manager it will be zero.
handle()
should return 1. If you return zero then FLTK assumes you ignored the key and 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_KEYBOARD events are also generated by the character palette/map.
To receive FL_KEYBOARD
events you must also respond to the FL_FOCUS
and FL_UNFOCUS
events.
If you are writing a text-editing widget you may also want to call the Fl::compose() function to translate individual keystrokes into characters.
FL_KEYUP
events are sent to the widget that currently has focus. This is not necessarily the same widget that received the corresponding FL_KEYDOWN
event because focus may have changed between events.
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 Fl::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.
FL_SHOW
to the base class handle()
method!file://
. See Fl::dnd() for drag and drop from an FLTK widget.
The drag and drop data is available in Fl::event_text() at the concluding FL_PASTE
. On some platforms, the event text is also available for the FL_DND_*
events, however application must not depend on that behavior because it depends on the protocol used on each platform.
FL_DND_*
events cannot be used in widgets derived from Fl_Group or Fl_Window.
FL_DND_DRAG
, FL_DND_LEAVE
and FL_DND_RELEASE
events.FL_PASTE
event.handle()
and callback()
methods.These are all trivial inline functions and thus very fast and small:
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:
Mouse click events are first sent to the window that caused them. The window then forwards the event down the hierarchy until it reaches the widget that is below the click position. If that widget uses the given event, the widget is marked "pushed" and will receive all following mouse motion (FL_DRAG) events until the mouse button is released.
Keyboard events are sent directly to the widget that has keyboard focus. If the focused widget rejects the event, it is resent as a shortcut event, first to the top-most window, then to the widget below the mouse pointer, propagating up the hierarchy to all its parents. Those send the event also to all widgets that are not below the mouse pointer. Now if that did not work out, the shortcut is sent to all registered shortcut handlers.
If we are still unsuccessful, the event handler flips the case of the shortcut letter and starts over. Finally, if the key is "escape", FLTK sends a close event to the top-most window.
All other events are pretty much sent right away to the window that created the event.
Widgets can "grab" events. The grabbing window gets all events exclusively, but usually by the same rules as described above.
Windows can also request exclusivity in event handling by making the window modal.
Currently, all characters made by single key strokes with or without modifier keys, or by system-defined character compose sequences (that can involve dead keys or a compose key) can be input. You should call Fl::compose() in case any enhancements to this processing are done in the future. The interface has been designed to handle arbitrary UTF-8 encoded text.
The following methods are provided for character composition:
Under Mac OS X, FLTK "previews" partially composed sequences.
[Prev] Drawing Things in FLTK | [Index] | Adding and Extending Widgets [Next] |