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. The current button state is
in Fl::event_state(). The mouse position
is in Fl::event_x() and
Fl::event_y().
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.
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()
widget 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() 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.
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:
The Fl_Input widget lets you type all the
characters in the standard ISO-8859-1 character set. Most fonts will
display these characters correctly.
To insert them, type the [compose] key and then one or two
characters. The two characters can be in either order. The [compose]
key is any of: Ctrl+Q, the righthand control key, or any key your X server
calls XK_Multi_key.
| Keys | Char |
Keys | Char |
Keys | Char |
Keys | Char |
Keys | Char |
Keys | Char |
| sp | nbsp |
* | ° |
A` | À |
D- | Ð |
a` | à |
d- | ð |
| ! | ¡ |
+- | ± |
A' | Á |
N~ | Ñ |
a' | á |
n~ | ñ |
| % | ¢ |
2 | ² |
A^ | Â |
O` | Ò |
a^ | â |
o` | ò |
| # | £ |
3 | ³ |
A~ | Ã |
O' | Ó |
a~ | ã |
o' | ó |
| $ | ¤ |
' | ´ |
A: | Ä |
O^ | Ô |
a: | ä |
o^ | ô |
| y= | ¥ |
u | µ |
A* | Å |
O~ | Õ |
a* | å |
o~ | õ |
| | | ¦ |
p | ¶ |
AE | Æ |
O: | Ö |
ae | æ |
o: | ö |
| & | § |
. | · |
C, | Ç |
x | × |
c, | ç |
-: | ÷ |
| : | ¨ |
, | ¸ |
E` | È |
O/ | Ø |
e` | è |
o/ | ø |
| c | © |
1 | ¹ |
E' | É |
U` | Ù |
e' | é |
u` | ù |
| a | ª |
o | º |
E^ | Ê |
U' | Ú |
e^ | ê |
u' | ú |
| << | « |
>> | » |
E: | Ë |
U^ | Û |
e: | ë |
u^ | û |
| ~ | ¬ |
14 | ¼ |
I` | Ì |
U: | Ü |
i` | ì |
u: | ü |
| - | |
12 | ½ |
I' | Í |
Y' | Ý |
i' | í |
y' | ý |
| r | ® |
34 | ¾ |
I^ | Î |
DD | Þ |
i^ | î |
dd | þ |
| _ | ¯ |
? | ¿ |
I: | Ï |
ss | ß |
i: | ï |
y: | ÿ |
For instance, to type "á" type [compose][a]['] or [compose]['][a].
The character "nbsp" (non-breaking space) is typed by using
[compose][space].
The single-character sequences may be followed by a space if
necessary to remove ambiguity. For instance, if you really want to
type "ª~" rather than "ã" you must type [compose][a][space][~].
If you wish to use the compose function in your own code, your
widget's handle() method must call fl_compose()
in response to FL_KEYPRESS events:
int fl_compose(int state, char c, int &del, char *buffer, int &ins)
Starts or adds a single ASCII character to a compose sequence. This
will return the number of old bytes to delete and a set of new bytes to
insert, and a new state value. If this returns zero you can
ignore the result (which just says to insert the character unchanged)
and handle the keystroke yourself.
state must either be the return value of the last call to
fl_compose() or zero to start a new compose sequence. Be sure to reset
to zero if the user ever moves the cursor.
c is the ASCII character that the user typed.
del is set to the number of bytes to delete backwards. This
will always be less or equal to the ins from the last call to
fl_compose(), and will be zero if state is zero.
buffer will have the first ins bytes set to the data
to insert and display (it is not nul-terminated).
ins will be the number of characters to insert.