2cde58f966
I am missing a decent Linux machine. Could someone please check if DND works smoothly on those machines? Just run the 'Input' test and mark and drag text out of the text widgets into another app. Then drag'n'drop text into the FLTK widgets. Finally drag text from one widget into another widget within the same FLTK app. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1972 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
361 lines
12 KiB
HTML
361 lines
12 KiB
HTML
<HTML>
|
|
<BODY>
|
|
|
|
<H1 ALIGN="RIGHT"><A NAME="events">6 - Handling Events</A></H1>
|
|
|
|
<P>This chapter discusses the FLTK event model and how to handle
|
|
events in your program or widget.
|
|
|
|
<H2>The FLTK Event Model</H2>
|
|
|
|
<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
|
|
<A href="subclassing.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 the window
|
|
system, so it is ok to look at it outside of the <TT>handle()</TT>
|
|
method.
|
|
|
|
<H2>Mouse Events</H2>
|
|
|
|
<H3>FL_PUSH</H3>
|
|
|
|
<P>A mouse button has gone down with the mouse pointing at this
|
|
widget. You can find out what button by calling <A
|
|
href="Fl.html#Fl.event_button"><TT>
|
|
Fl::event_button()</TT></A>. You find out the mouse position by
|
|
calling <A
|
|
href="Fl.html#Fl.event_x"><TT>Fl::event_x()</TT></A> and <A
|
|
href="Fl.html#Fl.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="subclassing.html#handle"><TT>handle()</TT></A> method. It
|
|
will then become the <A href="Fl.html#Fl.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>
|
|
|
|
<P>The mouse has moved with a button held down. The current
|
|
button state is in <a
|
|
href="Fl.html#Fl.event_state"><tt>Fl::event_state()</tt></a>.
|
|
The mouse position is in <a
|
|
href="Fl.html#Fl.event_x"><tt>Fl::event_x()</tt></a> and <a
|
|
href="Fl.html#Fl.event_y"><tt>Fl::event_y()</tt></a>.
|
|
|
|
<P>To receive <CODE>FL_DRAG</CODE> events you must also respond to the
|
|
<CODE>FL_PUSH</CODE> and <CODE>FL_RELEASE</CODE> events.
|
|
|
|
<H3>FL_RELEASE</H3>
|
|
|
|
<P>A mouse button has been released. You can find out what
|
|
button by calling <A
|
|
href="Fl.html#Fl.event_button"><TT>Fl::event_button()</TT></A>.
|
|
|
|
<H3>FL_MOVE</H3>
|
|
|
|
<P>The mouse has moved without any mouse buttons held down.
|
|
This event is sent to the <A
|
|
href="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse()</TT></A>
|
|
widget.
|
|
|
|
<H3>FL_MOUSEWHEEL</H3>
|
|
|
|
<P>The user has moved the mouse wheel. The <A
|
|
HREF="Fl.html#Fl.event_dx"><TT>Fl::event_dx()</TT></A> and <A
|
|
HREF="Fl.html#Fl.event_dy"><TT>Fl::event_dy()</TT></A> methods
|
|
can be used to find the amount to scroll horizontally and
|
|
vertically.
|
|
|
|
<H2>Focus Events</H2>
|
|
|
|
<H3>FL_ENTER</H3>
|
|
|
|
<P>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="Fl.html#Fl.handle"><TT>handle()</TT></A> method. It then
|
|
becomes the <A
|
|
href="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse()</TT></A>
|
|
widget and will receive <TT>FL_MOVE</TT> and <TT>FL_LEAVE</TT>
|
|
events.
|
|
|
|
<H3>FL_LEAVE</H3>
|
|
|
|
<P>The mouse has moved out of the widget.
|
|
|
|
<H3>FL_FOCUS</H3>
|
|
|
|
<P>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="Fl_Widget.html#Fl_Widget.handle"><TT>handle()</TT></A>
|
|
method. It then becomes the <A
|
|
href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A> widget and gets
|
|
<TT>FL_KEYDOWN</TT>, <TT>FL_KEYUP</TT>, and <TT>FL_UNFOCUS</TT>
|
|
events.
|
|
|
|
<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="Fl.html#Fl.event_key"><TT>Fl::event_key()</TT></A> to
|
|
figure out why it moved. For navigation it will be the key
|
|
pressed and interaction with the window manager it will be
|
|
zero.
|
|
|
|
<H3>FL_UNFOCUS</H3>
|
|
|
|
<P>This event is sent to the previous <A
|
|
href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A> widget when
|
|
another widget gets the focus or the window loses focus.
|
|
|
|
<H2>Keyboard Events</H2>
|
|
|
|
<H3>FL_KEYDOWN, FL_KEYUP</H3>
|
|
|
|
<P>A key was pressed or released. The key can be found in <A
|
|
href="Fl.html#Fl.event_key"><TT>Fl::event_key()</TT></A>. The
|
|
text that the key should insert can be found with <A
|
|
href="Fl.html#Fl.event_text"><TT>Fl::event_text()</TT></A> and
|
|
its length is in <A
|
|
href="Fl.html#Fl.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 assumes you ignored the key and 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.
|
|
|
|
<P>To receive <CODE>FL_KEYBOARD</CODE> events you must also
|
|
respond to the <CODE>FL_FOCUS</CODE> and <CODE>FL_UNFOCUS</CODE>
|
|
events.
|
|
|
|
<P>If you are writing a text-editing widget you may also want to
|
|
call the <a href="Fl.html#Fl.compose"><TT>Fl::compose()</TT></a>
|
|
function to translate individual keystrokes into foreign
|
|
characters.
|
|
|
|
<H3>FL_SHORTCUT</H3>
|
|
|
|
<P>If the <A href="Fl.html#Fl.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>Fl::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="Fl.html#Fl.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>
|
|
|
|
<P>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>
|
|
|
|
<P>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>
|
|
|
|
<P>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 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>
|
|
|
|
<P>This widget is visible again, due to <a
|
|
href="Fl_Widget.html#Fl_Widget.show"><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>
|
|
|
|
<P>You should get this event some time after you call <A
|
|
href="Fl.html#Fl.paste"><TT>Fl::paste()</TT></A>. The contents
|
|
of <A href="Fl.html#Fl.event_text"><TT>Fl::event_text()</TT></A>
|
|
is the text to insert and the number of characters is in <A
|
|
href="Fl.html#Fl.event_length"><TT>Fl::event_length()</TT></A>.
|
|
|
|
<H3>FL_SELECTIONCLEAR</H3>
|
|
|
|
<P>The <A
|
|
href="Fl.html#Fl.selection_owner"><TT>Fl::selection_owner()</TT></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. Motif programs used this to clear the
|
|
selection indication. Most modern programs ignore this.
|
|
|
|
<H2><A NAME="dnd">Drag And Drop Events</A></H2>
|
|
|
|
<H3>FL_DND_ENTER</H3>
|
|
|
|
<P>The mouse has been moved to point at this widget. A widget
|
|
that is interested in receiving drag'n'drop data must return 1
|
|
to receive FL_DND_DRAG, FL_DND_LEAVE and FL_DND_RELEASE events.
|
|
|
|
<H3>FL_DND_DRAG</H3>
|
|
|
|
<P>The mouse has been moved inside a widget while dragging data.
|
|
A widget that is interested in receiving drag'n'drop data should
|
|
indicate the possible drop position.
|
|
|
|
<H3>FL_DND_LEAVE</H3>
|
|
|
|
<P>The mouse has moved out of the widget.
|
|
|
|
<H3>FL_DND_RELEASE</H3>
|
|
|
|
<P>The user has released the mouse button dropping data into
|
|
the widget. If the widget returns 1, it will receive the data in
|
|
the immediatly following FL_PASTE event.
|
|
|
|
<H2><A name="event_xxx">Fl::event_*() methods</A></H2>
|
|
|
|
<P>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="Fl.html#Fl.event_button"><TT>Fl::event_button</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_clicks"><TT>Fl::event_clicks</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_dx"><TT>Fl::event_dx</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_dy"><TT>Fl::event_dy</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_inside"><TT>Fl::event_inside</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_is_click"><TT>Fl::event_is_click</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_key"><TT>Fl::event_key</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_length"><TT>Fl::event_length</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_state"><TT>Fl::event_state</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_text"><TT>Fl::event_text</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_x"><TT>Fl::event_x</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_x_root"><TT>Fl::event_x_root</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_y"><TT>Fl::event_y</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.event_y_root"><TT>Fl::event_y_root</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.get_key"><TT>Fl::get_key</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.get_mouse"><TT>Fl::get_mouse</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.test_shortcut"><TT>Fl::test_shortcut</TT></A></LI>
|
|
|
|
</UL>
|
|
|
|
<H2><A name=propagation>Event Propagation</A></H2>
|
|
|
|
<P>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:
|
|
|
|
<UL>
|
|
|
|
<LI><A HREF="Fl.html#Fl.add_handler"><TT>Fl::add_handler</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.focus"><TT>Fl::focus</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.grab"><TT>Fl::grab</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.modal"><TT>Fl::modal</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.pushed"><TT>Fl::pushed</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.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>
|
|
|
|
<P>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.
|
|
|
|
<p>FLTK uses its own compose processing to allow "preview" of
|
|
the partially composed sequence, which is impossible with the
|
|
usual "dead key" processing.
|
|
|
|
<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.
|
|
|
|
<P>The following methods are provided for character composition:
|
|
|
|
<UL>
|
|
|
|
<LI><A HREF="Fl.html#Fl.compose"><TT>Fl::compose()</TT></A></LI>
|
|
|
|
<LI><A HREF="Fl.html#Fl.compose_reset"><TT>Fl::compose_reset()</TT></A></LI>
|
|
|
|
</UL>
|
|
|
|
</BODY>
|
|
</HTML>
|