path: root/documentation/src/events.dox

/**

 \page	events Handling Events
 
This chapter discusses the FLTK event model and how to handle
events in your program or widget.

\section events_model The FLTK Event Model

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.

Events are identified by the integer argument passed to a
\p handle() method that overrides the
Fl_Widget::handle()
virtual method.
Other information about the most recent event is stored in
static locations and acquired by calling the
\ref events_event_xxx.
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
\p handle()
method.

Event numbers can be converted to their actual names using the \ref fl_eventnames[] array
defined in \#include <FL/names.h>; see next chapter for details.

In the next chapter, the
\ref subclassing_events "MyClass::handle()"
example shows how to override the
Fl_Widget::handle()
method to accept and process specific events.

\section events_mouse Mouse Events

\subsection events_fl_push 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 \e "wants" the mouse click
by returning non-zero from its
\p handle()
method, as in the
\ref subclassing_events "MyClass::handle()"
example.
It will then become the
Fl::pushed()
widget and will get \p FL_DRAG and
the matching \p FL_RELEASE events.
If
\p handle()
returns zero then FLTK will try sending the \p FL_PUSH to
another widget. 

\subsection events_fl_drag 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().

In order to receive \p FL_DRAG events, the widget must
return non-zero when handling \p FL_PUSH.

\subsection events_fl_release FL_RELEASE

A mouse button has been released. You can find out what button by calling
Fl::event_button().

In order to receive the \p FL_RELEASE event, the widget must
return non-zero when handling \p FL_PUSH.

\subsection events_fl_move FL_MOVE

The mouse has moved without any mouse buttons held down. 
This event is sent to the
Fl::belowmouse()
widget.

In order to receive \p FL_MOVE events, the widget must
return non-zero when handling \p FL_ENTER.

\subsection events_fl_mousewheel FL_MOUSEWHEEL

The user has moved the mouse wheel. The
Fl::event_dx()
and
Fl::event_dy()
methods can be used to find the amount to scroll horizontally and
vertically.

\section events_focus Focus Events

\subsection events_fl_enter 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
\p handle()
method. It then becomes the
Fl::belowmouse()
widget and will receive \p FL_MOVE and \p FL_LEAVE
events.

\subsection events_fl_leave FL_LEAVE

The mouse has moved out of the widget.

In order to receive the \p FL_LEAVE event, the widget must
return non-zero when handling \p FL_ENTER.

\subsection events_fl_focus FL_FOCUS

This indicates an \e 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
\p handle()
method.  It then becomes the
Fl::focus()
widget and gets
\p FL_KEYDOWN, \p FL_KEYUP, and \p 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 interaction with the window manager it will be zero.

\subsection events_fl_unfocus FL_UNFOCUS

This event is sent to the previous
Fl::focus()
widget when another widget gets the focus or the window loses focus.

\section events_keyboard Keyboard Events

\subsection events_fl_keydown FL_KEYDOWN, FL_KEYUP

A key was pressed or released. The key 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, then 
\p handle()
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 \p FL_SHORTCUT event.

To receive \p FL_KEYBOARD events you must also
respond to the \p FL_FOCUS and \p FL_UNFOCUS
events.

If you are writing a text-editing widget you may also want to call the
Fl::compose()
function to translate individual keystrokes into foreign characters.

\p FL_KEYUP events are sent to the widget that 
currently has focus. This is not necessarily the same widget
that received the corresponding \p FL_KEYDOWN event
because focus may have changed between events.

\subsection events_fl_shortcut FL_SHORTCUT

If the
Fl::focus()
widget is zero or ignores an \p FL_KEYBOARD event then
FLTK tries sending this event to every widget it can, until one
of them returns non-zero. \p FL_SHORTCUT is first sent to
the Fl::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.

\section events_widget Widget Events

\subsection events_fl_deactivate FL_DEACTIVATE

This widget is no longer active, due to
\ref Fl_Widget::deactivate() "deactivate()"
being called on it or one of its parents.
Please note that although
\ref Fl_Widget::active() "active()"
may still return true for this widget after receiving this event,
it is only truly active if
\ref Fl_Widget::active() "active()"
is true for both it and all of its parents.
(You can use
\ref Fl_Widget::active_r() "active_r()"
to check this).

\subsection events_fl_activate FL_ACTIVATE

This widget is now active, due to
\ref Fl_Widget::activate() "activate()"
being called on it or one of its parents.

\subsection events_fl_hide FL_HIDE

This widget is no longer visible, due to
\ref Fl_Widget::hide() "hide()"
being called on it or one of its parents, or due to a parent window
being minimized.
Please note that although
\ref Fl_Widget::visible() "visible()"
may still return true for this widget after receiving this event,
it is only truly visible if
\ref Fl_Widget::visible() "visible()"
is true for both it and all of its parents.
(You can use
\ref Fl_Widget::visible_r() "visible_r()"
to check this).

\subsection events_fl_show FL_SHOW

This widget is visible again, due to
\ref Fl_Widget::show() "show()"
being called on it or one of its parents, or due to a parent window
being restored. <I>A child Fl_Window will respond to this by
actually creating the window if not done already, so if you
subclass a window, be sure to pass \p FL_SHOW to the base
class
\p handle()
method!</I>

\section events_clipboard Clipboard Events

\subsection events_fl_paste 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().

\subsection events_fl_selectionclear 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. Motif programs used this to clear the
selection indication. Most modern programs ignore this.

\section events_dnd Drag and Drop Events

FLTK supports drag and drop of text and files from any 
application on the desktop. Text is transfered using
the current code page. Files are received as a list of full path
and file names, separated by newline. On some platforms, path
names are prepended with <tt>%file://</tt>.

The drag and drop data is available in Fl::event_text()
at the concluding \p FL_PASTE. On some platforms, the
event text is also available for the \p FL_DND_* events,
however application must not depend on that behavior because it
depends on the protocol used on each platform.

\p FL_DND_* events cannot be used in widgets derived
from Fl_Group or Fl_Window.

\subsection events_fl_dnd_enter FL_DND_ENTER

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
\p FL_DND_DRAG, \p FL_DND_LEAVE and \p FL_DND_RELEASE events.

\subsection events_fl_dnd_drag FL_DND_DRAG

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.

\subsection events_fl_dnd_leave FL_DND_LEAVE

The mouse has moved out of the widget.

\subsection events_fl_dnd_release FL_DND_RELEASE

The user has released the mouse button dropping data into 
the widget. If the widget returns 1, it will receive the data in
the immediately following \p FL_PASTE event.

<!-- NEED 6in -->

\section events_event_xxx Fl::event_*() methods

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
\p handle()
and
\p callback()
methods.

These are all trivial inline functions and thus very fast and small: 

\li Fl::event_button()
\li Fl::event_clicks()
\li Fl::event_dx()
\li Fl::event_dy()
\li Fl::event_inside()
\li Fl::event_is_click()
\li Fl::event_key()
\li Fl::event_length()
\li Fl::event_state()
\li Fl::event_text()
\li Fl::event_x()
\li Fl::event_x_root()
\li Fl::event_y()
\li Fl::event_y_root()
\li Fl::get_key()
\li Fl::get_mouse()
\li Fl::test_shortcut()

\section events_propagation Event Propagation

FLTK follows very simple and unchangeable rules for sending
events. The major innovation is that widgets can indicate (by
returning 0 from the
\p handle()
method) that they are not
interested in an event, and FLTK can then send that event
elsewhere.  This eliminates the need for \e "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
\p 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
(\p FL_DRAG, \p FL_RELEASE, \p FL_KEYBOARD,
\p FL_SHORTCUT, \p FL_UNFOCUS, and
\p FL_LEAVE) directly to leaf widgets. These procedures
control those leaf widgets:

\li Fl::add_handler()
\li Fl::belowmouse()
\li Fl::focus()
\li Fl::grab()
\li Fl::modal()
\li Fl::pushed()
\li Fl::release()
\li Fl_Widget::take_focus()

\section events_compose_characters FLTK Compose-Character Sequences

\todo Does Fltk Compose Character Sequences text need updating
      after the addition of UTF-8 handling to FLTK-1.3.x ?

The foreign-letter compose processing done by the Fl_Input widget's
\ref Fl_Input_Compose_Character "compose"
key handler is provided in a function that you can call if you are
writing your own text editor widget.

FLTK uses its own compose processing to allow "preview" of
the partially composed sequence, which is impossible with the
usual "dead key" processing.

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.

The following methods are provided for character composition:

\li Fl::compose()
\li Fl::compose_reset()


\htmlonly
<hr>
<table summary="navigation bar" width="100%" border="0">
<tr>
  <td width="45%" align="LEFT">
    <a class="el" href="drawing.html">
    [Prev]
    Drawing Things in FLTK
    </a>
  </td>
  <td width="10%" align="CENTER">
    <a class="el" href="main.html">[Index]</a>
  </td>
  <td width="45%" align="RIGHT">
    <a class="el" href="subclassing.html">
    Adding and Extending Widgets
    [Next]
    </a>
  </td>
</tr>
</table>
\endhtmlonly

*/