Contents
Previous
Next
This chapter discusses the FLTK event model and
how to handle events in your program or
widget.
Every time a user moves the mouse pointer,
clicks a button, or presses a key, an event
is generated and sent to your application. Events
can also come from other programs like the
window manager.
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).
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.
The current button state is in
Fl::event_state(). The mouse position is
in Fl::event_x()
and Fl::event_y().
To receive FL_DRAG events you must
also respond to the FL_PUSH and
FL_RELEASE events.
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
Fl::belowmouse() widget.
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() widget when another widget gets
the focus.
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.
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 foreign characters.
FL_SHORTCUT
If the Fl::focus()
widget 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.
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
hide() being called on it or one of
its parents, or due to a parent window being
minimized. visible() may still be true
after this, but the widget is visible only if
visible() is true for it and all its
parents (use visible_r() to check this).
FL_SHOW
This widget is visible again, 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!
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. Motif programs used this to clear the
selection indication. Most modern programs ignore
this.
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:
The foreign-letter compose processing done by the Fl_Input widget is
provided in a function that you can call if
you are writing your own text editor widget.
Fltk uses it's own compose processing to allow
"preview" of the partially composed sequence, which
is impossible with the usual "dead key"
processing.
Although currently only characters in the
ISO-8859-1 character set are handled, you should
call this in case any enhancements to the
processing are done in the future. The interface
has been designed to handle arbitrary UTF-8
encoded text.
int Fl::compose(int& del)
Use of this function is very simple. Any
text editing widget should call this for each
FL_KEYBOARD event.
If true is returned, then it has
modified the Fl::event_text() and Fl::event_length() to
a set of bytes to insert (it may be
of zero length!). In will also set the "del"
parameter to the number of bytes to the
left of the cursor to delete, this is used
to delete the results of the previous call to
Fl::compose().
If false is returned, the keys should be
treated as function keys, and del is set to
zero. You could insert the text anyways, if
you don't know what else to do.
Though the current implementation returns
immediately, future versions may take quite awhile,
as they may pop up a window or do other
user-interface things to allow characters to be
selected.
int Fl::compose_reset()
If the user moves the cursor, be sure to
call Fl::compose_reset(). The next call to
Fl::compose() will start out in an initial state.
In particular it will not set "del" to
non-zero. This call is very fast so it is
ok to call it many times and in many places.
Contents
Previous
Next