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>
|
1999-01-13 22:28:54 +03:00
|
|
|
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).
|
1999-01-07 19:36:11 +03:00
|
|
|
<H2>Mouse Events</H2>
|
1999-01-13 22:28:54 +03:00
|
|
|
<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.
|
|
|
|
|
<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 <TT>belowmouse()</TT> 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>
|
|
|
|
|
Sent to the previous <A href=functions.html#focus><TT>Fl::focus()</TT></A>
|
|
|
|
|
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>
|
|
|
|
|
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> 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>
|
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>
|
|
|
|
|
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
|
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
|
1999-01-13 22:28:54 +03:00
|
|
|
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>
|
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
|
|
|
|
|
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 name=event_button>Fl::event_button</A></LI>
|
|
|
|
|
<LI><A name=event_clicks>Fl::event_clicks</A></LI>
|
|
|
|
|
<LI><A name=event_inside>Fl::event_inside</A></LI>
|
|
|
|
|
<LI><A name=event_is_click>Fl::event_is_click</A></LI>
|
|
|
|
|
<LI><A name=event_key>Fl::event_key</A></LI>
|
|
|
|
|
<LI><A name=event_length>Fl::event_length</A></LI>
|
|
|
|
|
<LI><A name=event_state>Fl::event_state</A></LI>
|
|
|
|
|
<LI><A name=event_text>Fl::event_text</A></LI>
|
|
|
|
|
<LI><A name=event_x>Fl::event_x</A></LI>
|
|
|
|
|
<LI><A name=event_x_root>Fl::event_x_root</A></LI>
|
|
|
|
|
<LI><A name=event_y>Fl::event_y</A></LI>
|
|
|
|
|
<LI><A name=event_y_root>Fl::event_y_root</A></LI>
|
|
|
|
|
<LI><A name=get_key>Fl::get_key</A></LI>
|
|
|
|
|
<LI><A name=get_mouse>Fl::get_mouse</A></LI>
|
|
|
|
|
<LI><A name=test_shortcut>Fl::test_shortcut</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>Fl::add_handler</A></LI>
|
|
|
|
|
<LI><A href=functions.html#belowmouse>Fl::belowmouse</A></LI>
|
|
|
|
|
<LI><A href=functions.html#focus>Fl::focus</A></LI>
|
|
|
|
|
<LI><A href=functions.html#grab>Fl::grab</A></LI>
|
|
|
|
|
<LI><A href=functions.html#modal>Fl::modal</A></LI>
|
|
|
|
|
<LI><A href=functions.html#pushed>Fl::pushed</A></LI>
|
|
|
|
|
<LI><A href=functions.html#release>Fl::release</A></LI>
|
|
|
|
|
<LI><A href=Fl_Widget.html#Fl_Widget.take_focus>Fl_Widget::take_focus</A>
|
|
|
|
|
</LI>
|
|
|
|
|
</UL>
|
|
|
|
|
</BODY></HTML>
|
