1999-01-13 22:28:54 +03:00
|
|
|
<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.
|
1998-12-29 17:21:17 +03:00
|
|
|
<H2>The FLTK Event Model</H2>
|
2000-04-28 22:15:26 +04:00
|
|
|
|
|
|
|
|
<P>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.
|
|
|
|
|
|
|
|
|
|
<P>Events are identified by the integer argument passed to the
|
2001-10-01 00:25:36 +04:00
|
|
|
<A href="subclassing.html#handle"> <TT>Fl_Widget::handle()</TT></A> virtual
|
2000-04-28 22:15:26 +04:00
|
|
|
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).
|
|
|
|
|
|
1999-01-07 19:36:11 +03:00
|
|
|
<H2>Mouse Events</H2>
|
1999-01-13 22:28:54 +03:00
|
|
|
<H3>FL_PUSH</H3>
|
2000-04-28 22:15:26 +04:00
|
|
|
A mouse button has gone down with the mouse pointing at this widget.
|
2001-10-01 00:25:36 +04:00
|
|
|
You can find out what button by calling <A href="functions.html#event_button"><TT>
|
1999-01-13 22:28:54 +03:00
|
|
|
Fl::event_button()</TT></A>. You find out the mouse position by
|
2001-10-01 00:25:36 +04:00
|
|
|
calling <A href="functions.html#event_x"><TT>Fl::event_x()</TT></A> and <A href="functions.html#event_y">
|
1999-01-13 22:28:54 +03:00
|
|
|
<TT>Fl::event_y()</TT></A>.
|
|
|
|
|
<P>A widget indicates that it "wants" the mouse click by returning
|
2001-10-01 00:25:36 +04:00
|
|
|
non-zero from its <A href="subclassing.html#handle"><TT>handle()</TT></A>
|
|
|
|
|
method. It will then become the <A href="functions.html#pushed"><TT>
|
1999-01-13 22:28:54 +03:00
|
|
|
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>
|
1999-01-27 00:36:02 +03:00
|
|
|
The mouse has moved with a button held down. The current button state is
|
2001-10-01 00:25:36 +04:00
|
|
|
in <a href="functions.html#event_state"><tt>Fl::event_state()</tt></a>. The mouse position
|
|
|
|
|
is in <a href="functions.html#event_x"><tt>Fl::event_x()</tt></a> and
|
|
|
|
|
<a href="functions.html#event_y"><tt>Fl::event_y()</tt></a>.
|
1999-06-12 17:53:34 +04:00
|
|
|
|
|
|
|
|
<P>To receive <CODE>FL_DRAG</CODE> events you must also respond to the
|
|
|
|
|
<CODE>FL_PUSH</CODE> and <CODE>FL_RELEASE</CODE> events.
|
|
|
|
|
|
1999-01-13 22:28:54 +03:00
|
|
|
<H3>FL_RELEASE</H3>
|
|
|
|
|
A mouse button has been released. You can find out what button by
|
2001-10-01 00:25:36 +04:00
|
|
|
calling <A href="functions.html#event_button"><TT>Fl::event_button()</TT></A>.
|
1999-01-13 22:28:54 +03:00
|
|
|
<H3>FL_MOVE</H3>
|
|
|
|
|
The mouse has moved without any mouse buttons held down. This event
|
1999-01-27 00:36:02 +03:00
|
|
|
is sent to the <A href="functions.html#belowmouse"><TT>Fl::belowmouse()</TT></A>
|
|
|
|
|
widget.
|
1999-01-07 19:36:11 +03:00
|
|
|
<H2>Focus Events</H2>
|
1999-01-13 22:28:54 +03:00
|
|
|
<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>
|
1999-01-27 00:36:02 +03:00
|
|
|
Sent to the previous <A href=functions.html#focus><TT>Fl::focus()</TT></A>
|
|
|
|
|
widget when another widget gets the focus.
|
1999-01-07 19:36:11 +03:00
|
|
|
<H2>Keyboard Events</H2>
|
1999-01-13 22:28:54 +03:00
|
|
|
<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>
|
1999-06-12 17:53:34 +04:00
|
|
|
should return 1. If you return zero then FLTK assummes you ignored
|
1999-01-13 22:28:54 +03:00
|
|
|
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>
|
1999-06-12 17:53:34 +04:00
|
|
|
event.
|
|
|
|
|
|
|
|
|
|
<P>To receive <CODE>FL_KEYBOARD</CODE> events you must also respond to the
|
|
|
|
|
<CODE>FL_FOCUS</CODE> and <CODE>FL_UNFOCUS</CODE> events.
|
|
|
|
|
|
2000-02-21 13:45:59 +03:00
|
|
|
<p>If you are writing a text-editing widget you may also want to call
|
|
|
|
|
the <a href=#compose>Fl::compose()</a> function to translate
|
|
|
|
|
individual keystrokes into foreign characters.
|
|
|
|
|
|
1999-01-13 22:28:54 +03:00
|
|
|
<H3>FL_SHORTCUT</H3>
|
1999-01-27 00:36:02 +03:00
|
|
|
If the <A href=functions.html#focus><TT>Fl::focus()</TT></A> widget is zero
|
1999-01-13 22:28:54 +03:00
|
|
|
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>
|
1999-01-07 19:36:11 +03:00
|
|
|
<H2>Widget Events</H2>
|
1999-01-13 22:28:54 +03:00
|
|
|
<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>
|
2000-02-21 13:45:59 +03:00
|
|
|
|
|
|
|
|
This widget is no longer visible, due to <A href=Fl_Widget.html#Fl_Widget.hide><tt>hide()</tt></a> being called on it or one of its
|
1999-01-07 19:36:11 +03:00
|
|
|
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).
|
1998-12-29 17:21:17 +03:00
|
|
|
|
1999-01-07 19:36:11 +03:00
|
|
|
<h3>FL_SHOW</h3>
|
1998-12-29 17:21:17 +03:00
|
|
|
|
|
|
|
|
This widget is visible again, due to <a
|
2000-02-21 13:45:59 +03:00
|
|
|
href=Fl_Widget.html#Fl_Widget.show>
|
1999-01-13 22:28:54 +03:00
|
|
|
<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>
|
1999-01-07 19:36:11 +03:00
|
|
|
<H2>Clipboard Events</H2>
|
1999-01-13 22:28:54 +03:00
|
|
|
<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
|
2000-02-21 13:45:59 +03:00
|
|
|
selection. Motif programs used this to clear the selection
|
|
|
|
|
indication. Most modern programs ignore this.
|
1999-01-13 22:28:54 +03:00
|
|
|
<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>
|
1999-01-27 00:36:02 +03:00
|
|
|
<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>
|
1999-01-13 22:28:54 +03:00
|
|
|
</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>
|
1999-01-27 00:36:02 +03:00
|
|
|
<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>
|
2001-10-01 00:25:36 +04:00
|
|
|
<LI><TT>Fl::release</TT></LI>
|
1999-01-27 00:36:02 +03:00
|
|
|
<LI><A href=Fl_Widget.html#Fl_Widget.take_focus><TT>Fl_Widget::take_focus</TT></A>
|
1999-01-13 22:28:54 +03:00
|
|
|
</LI>
|
|
|
|
|
</UL>
|
1999-01-19 23:53:39 +03:00
|
|
|
|
|
|
|
|
<H2><A name=compose>FLTK Compose-Character Sequences</A></H2>
|
|
|
|
|
|
2000-02-21 13:45:59 +03:00
|
|
|
The foreign-letter compose processing done by the <A
|
|
|
|
|
href=Fl_Input.html#compose><tt>Fl_Input</tt></a> widget is provided in
|
|
|
|
|
a function that you can call if you are writing your own text editor
|
|
|
|
|
widget.
|
1999-01-19 23:53:39 +03:00
|
|
|
|
2000-02-21 13:45:59 +03:00
|
|
|
<p>Fltk uses it's own compose processing to allow "preview" of the
|
|
|
|
|
partially composed sequence, which is impossible with the usual
|
|
|
|
|
"dead key" processing.
|
1999-01-19 23:53:39 +03:00
|
|
|
|
2000-02-21 13:45:59 +03:00
|
|
|
<p>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.
|
1999-01-19 23:53:39 +03:00
|
|
|
|
2000-02-21 13:45:59 +03:00
|
|
|
<h4><tt>int Fl::compose(int& del)</tt></h4>
|
1999-01-19 23:53:39 +03:00
|
|
|
|
2000-02-21 13:45:59 +03:00
|
|
|
<p>Use of this function is very simple. Any text editing widget should
|
|
|
|
|
call this for each <tt>FL_KEYBOARD</tt> event.
|
1999-01-19 23:53:39 +03:00
|
|
|
|
2000-02-21 13:45:59 +03:00
|
|
|
<p>If <i>true</i> is returned, then it has modified the
|
|
|
|
|
Fl::event_text() and Fl::event_length() to a set of <i>bytes</i> to
|
|
|
|
|
insert (it may be of zero length!). In will also set the "del"
|
|
|
|
|
parameter to the number of <i>bytes</i> to the left of the cursor to
|
|
|
|
|
delete, this is used to delete the results of the previous call to
|
|
|
|
|
Fl::compose().
|
1999-01-19 23:53:39 +03:00
|
|
|
|
2000-02-21 13:45:59 +03:00
|
|
|
<p>If <i>false</i> 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.
|
1999-01-19 23:53:39 +03:00
|
|
|
|
2000-02-21 13:45:59 +03:00
|
|
|
<p>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.
|
1999-01-19 23:53:39 +03:00
|
|
|
|
2000-02-21 13:45:59 +03:00
|
|
|
<h4><tt>int Fl::compose_reset()</tt></h4>
|
1999-01-19 23:53:39 +03:00
|
|
|
|
2000-02-21 13:45:59 +03:00
|
|
|
<p>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.
|
1999-01-19 23:53:39 +03:00
|
|
|
|
2000-02-21 13:45:59 +03:00
|
|
|
</body></html>
|
