362 lines
15 KiB
HTML
362 lines
15 KiB
HTML
<HTML><BODY>
|
||
<H1 ALIGN=RIGHT><A NAME=events>6 - Handling Events</A></H1>
|
||
This chapter discusses the FLTK event model and how to handle events
|
||
in your program or widget.
|
||
<H2>The FLTK Event Model</H2>
|
||
Events are identified by the integer argument passed to the <A href=functions.html#handle>
|
||
<TT>Fl_Widget::handle()</TT></A> virtual method. Other information
|
||
about the most recent event is stored in static locations and acquired
|
||
by calling the <A href=#event_xxx><TT>Fl::event_*()</TT></A> 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 <TT>handle()</TT>
|
||
method).
|
||
<H2>Mouse Events</H2>
|
||
<H3>FL_PUSH</H3>
|
||
A mouse button has gone down with the mouse pointing at this widget.
|
||
You can find out what button by calling <A href=#event_button><TT>
|
||
Fl::event_button()</TT></A>. You find out the mouse position by
|
||
calling <A href=#event_x><TT>Fl::event_x()</TT></A> and <A href=functions.html#event_y>
|
||
<TT>Fl::event_y()</TT></A>.
|
||
<P>A widget indicates that it "wants" the mouse click by returning
|
||
non-zero from its <A href=functions.html#handle><TT>handle()</TT></A>
|
||
method. It will then become the <A href=functions.html#pushed><TT>
|
||
Fl::pushed()</TT></A> widget and will get <TT>FL_DRAG</TT> and the
|
||
matching <TT>FL_RELEASE</TT> events. If <TT>handle()</TT> returns zero
|
||
then FLTK will try sending the <TT>FL_PUSH</TT> to another widget. </P>
|
||
<H3>FL_DRAG</H3>
|
||
The mouse has moved with a button held down. The current button state is
|
||
in <a href="#event_state"><tt>Fl::event_state()</tt></a>. The mouse position
|
||
is in <a href="#event_x"><tt>Fl::event_x()</tt></a> and
|
||
<a href="#event_y"><tt>Fl::event_y()</tt></a>.
|
||
<H3>FL_RELEASE</H3>
|
||
A mouse button has been released. You can find out what button by
|
||
calling <A href=#event_button><TT>Fl::event_button()</TT></A>.
|
||
<H3>FL_MOVE</H3>
|
||
The mouse has moved without any mouse buttons held down. This event
|
||
is sent to the <A href="functions.html#belowmouse"><TT>Fl::belowmouse()</TT></A>
|
||
widget.
|
||
<H2>Focus Events</H2>
|
||
<H3>FL_ENTER</H3>
|
||
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 <A href=functions.html#handle>
|
||
<TT>handle()</TT></A> method. It then becomes the <A href=functions.html#belowmouse>
|
||
<TT>Fl::belowmouse()</TT></A> widget and will receive <TT>FL_MOVE</TT>
|
||
and <TT>FL_LEAVE</TT> events.
|
||
<H3>FL_LEAVE</H3>
|
||
The mouse has moved out of the widget.
|
||
<H3>FL_FOCUS</H3>
|
||
This indicates an <I>attempt</I> to give a widget the keyboard focus.
|
||
<P>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 <A href=functions.html#handle>
|
||
<TT>handle()</TT></A> method. It then becomes the <A href=functions.html#focus>
|
||
<TT>Fl::focus()</TT></A> widget and gets <TT>FL_KEYBOARD</TT> and <TT>
|
||
FL_UNFOCUS</TT> events. </P>
|
||
<P>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 <A href=functions.html#event_key>
|
||
<TT>Fl::event_key()</TT></A> 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. </P>
|
||
<H3>FL_UNFOCUS</H3>
|
||
Sent to the previous <A href=functions.html#focus><TT>Fl::focus()</TT></A>
|
||
widget when another widget gets the focus.
|
||
<H2>Keyboard Events</H2>
|
||
<H3>FL_KEYBOARD</H3>
|
||
A key press. The key pressed can be found in <A href=functions.html#event_key>
|
||
<TT>Fl::event_key()</TT></A>. The text that the key should insert can
|
||
be found with <A href=functions.html#event_text><TT>Fl::event_text()</TT>
|
||
</A> and its length is in <A href=functions.html#event_length><TT>
|
||
Fl::event_length()</TT></A>. If you use the key <TT>handle()</TT>
|
||
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 <TT>FL_SHORTCUT</TT>
|
||
event.
|
||
<H3>FL_SHORTCUT</H3>
|
||
If the <A href=functions.html#focus><TT>Fl::focus()</TT></A> widget is zero
|
||
or ignores an <TT>FL_KEYBOARD</TT> event then FLTK tries sending this
|
||
event to every widget it can, until one of them returns non-zero. <TT>
|
||
FL_SHORTCUT</TT> is first sent to the <TT>belowmouse()</TT> 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!
|
||
<P>You can also make "global" shortcuts by using <A href=osissues.html#add_handler>
|
||
<TT>Fl::add_handler()</TT></A>. A global shortcut will work no matter
|
||
what windows are displayed or which one has the focus. </P>
|
||
<H2>Widget Events</H2>
|
||
<H3>FL_DEACTIVATE</H3>
|
||
This widget is no longer active, due to <A href=Fl_Widget.html#Fl_Widget.deactivate>
|
||
<TT>deactivate()</TT></A> being called on it or one of its parents. <TT>
|
||
active()</TT> may still be true after this, the widget is only active
|
||
if <TT>active()</TT> is true on it and all its parents (use <TT>
|
||
active_r()</TT> to check this).
|
||
<H3>FL_ACTIVATE</H3>
|
||
This widget is now active, due to <A href=Fl_Widget.html#Fl_Widget.activate>
|
||
<TT>activate()</TT></A> being called on it or one of its parents.
|
||
<H3>FL_HIDE</H3>
|
||
This widget is no longer visible, due to <A #Fl_Widget.show" href="#Fl_Widget.hide><tt>hide()</tt></a> being called on it or one of its
|
||
parents, or due to a parent window being minimized. <tt>visible()</tt>
|
||
may still be true after this, but the widget is visible only if
|
||
<tt>visible()</tt> is true for it and all its parents (use
|
||
<tt>visible_r()</tt> to check this).
|
||
|
||
<h3>FL_SHOW</h3>
|
||
|
||
This widget is visible again, due to <a
|
||
href=">
|
||
<TT>show()</TT></A> being called on it or one of its parents, or due to
|
||
a parent window being restored. <I>Child <TT>Fl_Window</TT>s respond to
|
||
this by actually creating the window if not done already, so if you
|
||
subclass a window, be sure to pass <TT>FL_SHOW</TT> to the base class <TT>
|
||
handle()</TT> method!</I>
|
||
<H2>Clipboard Events</H2>
|
||
<H3>FL_PASTE</H3>
|
||
You should get this event some time after you call <A href=functions.html#paste>
|
||
<TT>Fl::paste()</TT></A>. The contents of <A href=functions.html#event_text>
|
||
<TT>Fl::event_text()</TT></A> is the text to insert and the number of
|
||
characters is in <A href=functions.html#event_length><TT>
|
||
Fl::event_length()</TT></A>.
|
||
<H3>FL_SELECTIONCLEAR</H3>
|
||
The <A href=functions.html#selection_owner>Fl::selection_owner()</A>
|
||
will get this event before the selection is moved to another widget.
|
||
This indicates that some other widget or program has claimed the
|
||
selection.
|
||
<H2><A name=event_xxx>Fl::event_*() methods</A></H2>
|
||
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 <TT>handle()</TT> and <TT>callback()</TT>
|
||
methods.
|
||
<P>These are all trivial inline functions and thus very fast and small: </P>
|
||
<UL>
|
||
<LI><A href=functions.html#event_button><TT>Fl::event_button</TT></A></LI>
|
||
<LI><A href=functions.html#event_clicks><TT>Fl::event_clicks</TT></A></LI>
|
||
<LI><A href=functions.html#event_inside><TT>Fl::event_inside</TT></A></LI>
|
||
<LI><A href=functions.html#event_is_click><TT>Fl::event_is_click</TT></A></LI>
|
||
<LI><A href=functions.html#event_key><TT>Fl::event_key</TT></A></LI>
|
||
<LI><A href=functions.html#event_length><TT>Fl::event_length</TT></A></LI>
|
||
<LI><A href=functions.html#event_state><TT>Fl::event_state</TT></A></LI>
|
||
<LI><A href=functions.html#event_text><TT>Fl::event_text</TT></A></LI>
|
||
<LI><A href=functions.html#event_x><TT>Fl::event_x</TT></A></LI>
|
||
<LI><A href=functions.html#event_x_root><TT>Fl::event_x_root</TT></A></LI>
|
||
<LI><A href=functions.html#event_y><TT>Fl::event_y</TT></A></LI>
|
||
<LI><A href=functions.html#event_y_root><TT>Fl::event_y_root</TT></A></LI>
|
||
<LI><A href=functions.html#get_key><TT>Fl::get_key</TT></A></LI>
|
||
<LI><A href=functions.html#get_mouse><TT>Fl::get_mouse</TT></A></LI>
|
||
<LI><A href=functions.html#test_shortcut><TT>Fl::test_shortcut</TT></A></LI>
|
||
</UL>
|
||
<H2><A name=propagation>Event Propagation</A></H2>
|
||
FLTK follows very simple and unchangeable rules for sending events.
|
||
The major innovation is that widgets can indicate (by returning 0 from
|
||
the <TT>handle()</TT> 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.
|
||
<P>Most events are sent directly to the <TT>handle()</TT> method of the <TT>
|
||
Fl_Window</TT> that the window system says they belong to. The window
|
||
(actually the <TT>Fl_Group</TT> that <TT>Fl_Window</TT> is a subclass
|
||
of) is responsible for sending the events on to any child widgets. To
|
||
make the <TT>Fl_Group</TT> code somewhat easier, FLTK sends some events
|
||
(<TT>FL_DRAG</TT>, <TT>FL_RELEASE</TT>, <TT>FL_KEYBOARD</TT>, <TT>
|
||
FL_SHORTCUT</TT>, <TT>FL_UNFOCUS</TT>, and <TT>FL_LEAVE</TT>) directly
|
||
to leaf widgets. These procedures control those leaf widgets: </P>
|
||
<UL>
|
||
<LI><A href=osissues.html#add_handler><TT>Fl::add_handler</TT></A></LI>
|
||
<LI><A href=functions.html#belowmouse><TT>Fl::belowmouse</TT></A></LI>
|
||
<LI><A href=functions.html#focus><TT>Fl::focus</TT></A></LI>
|
||
<LI><A href=functions.html#grab><TT>Fl::grab</TT></A></LI>
|
||
<LI><A href=functions.html#modal><TT>Fl::modal</TT></A></LI>
|
||
<LI><A href=functions.html#pushed><TT>Fl::pushed</TT></A></LI>
|
||
<LI><A href=functions.html#release><TT>Fl::release</TT></A></LI>
|
||
<LI><A href=Fl_Widget.html#Fl_Widget.take_focus><TT>Fl_Widget::take_focus</TT></A>
|
||
</LI>
|
||
</UL>
|
||
|
||
<H2><A name=compose>FLTK Compose-Character Sequences</A></H2>
|
||
|
||
The <A href="#Fl_Input"><tt>Fl_Input</tt></a> widget lets you type all the
|
||
characters in the standard ISO-8859-1 character set. Most fonts will
|
||
display these characters correctly.
|
||
|
||
<P>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 <TT>XK_Multi_key</TT>.
|
||
|
||
<center><table border=1>
|
||
<tr>
|
||
<th>Keys</th><th>Char</th>
|
||
<th>Keys</th><th>Char</th>
|
||
<th>Keys</th><th>Char</th>
|
||
<th>Keys</th><th>Char</th>
|
||
<th>Keys</th><th>Char</th>
|
||
<th>Keys</th><th>Char</th>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>sp</TT></td><td>nbsp</td>
|
||
<td><TT>*</TT></td><td><EFBFBD></td>
|
||
<td><TT>A`</TT></td><td><EFBFBD></td>
|
||
<td><TT>D-</TT></td><td><EFBFBD></td>
|
||
<td><TT>a`</TT></td><td><EFBFBD></td>
|
||
<td><TT>d-</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>!</TT></td><td><EFBFBD></td>
|
||
<td><TT>+-</TT></td><td><EFBFBD></td>
|
||
<td><TT>A'</TT></td><td><EFBFBD></td>
|
||
<td><TT>N~</TT></td><td><EFBFBD></td>
|
||
<td><TT>a'</TT></td><td><EFBFBD></td>
|
||
<td><TT>n~</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>%</TT></td><td><EFBFBD></td>
|
||
<td><TT>2</TT></td><td><EFBFBD></td>
|
||
<td><TT>A^</TT></td><td><EFBFBD></td>
|
||
<td><TT>O`</TT></td><td><EFBFBD></td>
|
||
<td><TT>a^</TT></td><td><EFBFBD></td>
|
||
<td><TT>o`</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>#</TT></td><td><EFBFBD></td>
|
||
<td><TT>3</TT></td><td><EFBFBD></td>
|
||
<td><TT>A~</TT></td><td><EFBFBD></td>
|
||
<td><TT>O'</TT></td><td><EFBFBD></td>
|
||
<td><TT>a~</TT></td><td><EFBFBD></td>
|
||
<td><TT>o'</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>$</TT></td><td><EFBFBD></td>
|
||
<td><TT>'</TT></td><td><EFBFBD></td>
|
||
<td><TT>A:</TT></td><td><EFBFBD></td>
|
||
<td><TT>O^</TT></td><td><EFBFBD></td>
|
||
<td><TT>a:</TT></td><td><EFBFBD></td>
|
||
<td><TT>o^</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>y=</TT></td><td><EFBFBD></td>
|
||
<td><TT>u</TT></td><td><EFBFBD></td>
|
||
<td><TT>A*</TT></td><td><EFBFBD></td>
|
||
<td><TT>O~</TT></td><td><EFBFBD></td>
|
||
<td><TT>a*</TT></td><td><EFBFBD></td>
|
||
<td><TT>o~</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>|</TT></td><td><EFBFBD></td>
|
||
<td><TT>p</TT></td><td><EFBFBD></td>
|
||
<td><TT>AE</TT></td><td><EFBFBD></td>
|
||
<td><TT>O:</TT></td><td><EFBFBD></td>
|
||
<td><TT>ae</TT></td><td><EFBFBD></td>
|
||
<td><TT>o:</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>&</TT></td><td><EFBFBD></td>
|
||
<td><TT>.</TT></td><td><EFBFBD></td>
|
||
<td><TT>C,</TT></td><td><EFBFBD></td>
|
||
<td><TT>x</TT></td><td><EFBFBD></td>
|
||
<td><TT>c,</TT></td><td><EFBFBD></td>
|
||
<td><TT>-:</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>:</TT></td><td><EFBFBD></td>
|
||
<td><TT>,</TT></td><td><EFBFBD></td>
|
||
<td><TT>E`</TT></td><td><EFBFBD></td>
|
||
<td><TT>O/</TT></td><td><EFBFBD></td>
|
||
<td><TT>e`</TT></td><td><EFBFBD></td>
|
||
<td><TT>o/</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>c</TT></td><td><EFBFBD></td>
|
||
<td><TT>1</TT></td><td><EFBFBD></td>
|
||
<td><TT>E'</TT></td><td><EFBFBD></td>
|
||
<td><TT>U`</TT></td><td><EFBFBD></td>
|
||
<td><TT>e'</TT></td><td><EFBFBD></td>
|
||
<td><TT>u`</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>a</TT></td><td><EFBFBD></td>
|
||
<td><TT>o</TT></td><td><EFBFBD></td>
|
||
<td><TT>E^</TT></td><td><EFBFBD></td>
|
||
<td><TT>U'</TT></td><td><EFBFBD></td>
|
||
<td><TT>e^</TT></td><td><EFBFBD></td>
|
||
<td><TT>u'</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT><<</TT></td><td><EFBFBD></td>
|
||
<td><TT>>></TT></td><td><EFBFBD></td>
|
||
<td><TT>E:</TT></td><td><EFBFBD></td>
|
||
<td><TT>U^</TT></td><td><EFBFBD></td>
|
||
<td><TT>e:</TT></td><td><EFBFBD></td>
|
||
<td><TT>u^</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>~</TT></td><td><EFBFBD></td>
|
||
<td><TT>14</TT></td><td><EFBFBD></td>
|
||
<td><TT>I`</TT></td><td><EFBFBD></td>
|
||
<td><TT>U:</TT></td><td><EFBFBD></td>
|
||
<td><TT>i`</TT></td><td><EFBFBD></td>
|
||
<td><TT>u:</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>-</TT></td><td><EFBFBD></td>
|
||
<td><TT>12</TT></td><td><EFBFBD></td>
|
||
<td><TT>I'</TT></td><td><EFBFBD></td>
|
||
<td><TT>Y'</TT></td><td><EFBFBD></td>
|
||
<td><TT>i'</TT></td><td><EFBFBD></td>
|
||
<td><TT>y'</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>r</TT></td><td><EFBFBD></td>
|
||
<td><TT>34</TT></td><td><EFBFBD></td>
|
||
<td><TT>I^</TT></td><td><EFBFBD></td>
|
||
<td><TT>DD</TT></td><td><EFBFBD></td>
|
||
<td><TT>i^</TT></td><td><EFBFBD></td>
|
||
<td><TT>dd</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
<tr>
|
||
<td><TT>_</TT></td><td><EFBFBD></td>
|
||
<td><TT>?</TT></td><td><EFBFBD></td>
|
||
<td><TT>I:</TT></td><td><EFBFBD></td>
|
||
<td><TT>ss</TT></td><td><EFBFBD></td>
|
||
<td><TT>i:</TT></td><td><EFBFBD></td>
|
||
<td><TT>y:</TT></td><td><EFBFBD></td>
|
||
</tr>
|
||
</table>
|
||
</center>
|
||
|
||
For instance, to type "<22>" type [compose][a]['] or [compose]['][a].
|
||
|
||
<P>The character "nbsp" (non-breaking space) is typed by using
|
||
[compose][space].
|
||
|
||
<P>The single-character sequences may be followed by a space if
|
||
necessary to remove ambiguity. For instance, if you really want to
|
||
type "<22>~" rather than "<22>" you must type [compose][a][space][~].
|
||
|
||
<P>If you wish to use the compose function in your own code, your
|
||
widget's <tt>handle()</tt> method must call <tt>fl_compose()</tt>
|
||
in response to <tt>FL_KEYPRESS</tt> events:
|
||
|
||
<h4><TT>int fl_compose(int state, char c, int &del, char *buffer, int &ins)</TT></h4>
|
||
|
||
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 <tt>state</tt> value. If this returns zero you can
|
||
ignore the result (which just says to insert the character unchanged)
|
||
and handle the keystroke yourself.
|
||
|
||
<P><tt>state</tt> must either be the return value of the last call to
|
||
<tt>fl_compose()</tt> or zero to start a new compose sequence. Be sure to reset
|
||
to zero if the user ever moves the cursor.
|
||
|
||
<P><tt>c</tt> is the ASCII character that the user typed.
|
||
|
||
<P><tt>del</tt> is set to the number of bytes to delete backwards. This
|
||
will always be less or equal to the <tt>ins</tt> from the last call to
|
||
<tt>fl_compose()</tt>, and will be zero if <tt>state</tt> is zero.
|
||
|
||
<P><tt>buffer</tt> will have the first <tt>ins</tt> bytes set to the data
|
||
to insert and display (it is <I>not</I> nul-terminated).
|
||
|
||
<P><tt>ins</tt> will be the number of characters to insert.
|
||
|
||
</BODY></HTML>
|