All other information about the most recent event is stored in static locations and acquired by calling these functions. 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 handle() method). This allows the data to be accessed by callbacks and other functions without having to pass an event argument to them, and allows more fields to be added to events without breaking binary compatability. These are all trivial inline functions and thus very fast and small:
The following functions do not return current event state, but are often used when processing events as well:
FLTK follows very simple and unchangeable rules for sending events. The major innovation is that widgets can indicate (by returning 0 from the handle() 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.Some events are sent directly to widgets by fltk, but others are always sent to the outermost Fl_Window and fltk relies on the widgets correctly sending the events on to their children. This is to allow composite widgets to implement more efficient code for finding the correct child than the simple linear search fltk uses. The following functions control where events are sent:
This is a list of all the events currently defined.
A widget indicates that it "wants" the mouse click by returning non-zero from its handle() method. It will then become the Fl::pushed() widget and will get FL_DRAG and the matching FL_RELEASE events. If handle() returns zero then FLTK will try sending the FL_PUSH to another widget.
To receive FL_DRAG events you must return 1 when passed a
FL_PUSH event.
FL_RELEASE
A mouse button has been released. You can find out what button by
calling Fl::event_button().
To receive FL_RELEASE events you must return 1 when passed a
FL_PUSH event.
FL_MOVE
The mouse has moved without any mouse buttons held down. This event
is sent to the Fl::belowmouse() widget.
FL_MOUSEWHEEL
The wheel was moved on the mouse. Fl::event_dy() contains
how many clicks the wheel moved, positive for up and negative for
down. There is also a Fl::event_dx() for any
kind of horizontal scrolling device but nothing produces that yet.
On X you may want to write stuff to the xrdb database to control how fltk interprets the wheel. On Windows the normal Windows settings are used for this.
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 handle() method. It then becomes the Fl::focus() widget and gets FL_KEY, FL_KEYUP and 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 for
instructions from the window manager it will be zero.
FL_UNFOCUS
Sent to the previous Fl::focus()
widget when another widget gets the focus.
FL_KEY
A key press event. Fltk sends these directly to the
Fl::focus() widget. If it
does not return 1 then fltk will change the event into a
FL_SHORTCUT event and try the widgets under the mouse.
The key pressed 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().
To receive FL_KEYBOARD events you must return 1 in
response to a FL_FOCUS event.
FL_KEYUP
Sent to the Fl::focus()
widget. The key that was released can be found in Fl::event_key(). Don't rely
on anything being in Fl::event_text().
FL_SHORTCUT
If the Fl::focus() widget is
zero or ignores an FL_KEY event then FLTK tries sending this
event to every widget it can, until one of them returns
non-zero. FL_SHORTCUT is first sent to the
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.
Fltk uses it's 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.
Use of this function is very simple. Any text editing widget should call this for each FL_KEYBOARD event.
If true is returned, then it has modified the Fl::event_text() and Fl::event_length() to a set of bytes to insert (it may be of zero length!). It will also set the del parameter to the number of bytes to the left of the cursor to delete, this is used to delete the results of the previous call to Fl::compose().
If false is returned, the keys should be treated as function keys. You could insert the text anyways, if you don't know what else to do, del is set to zero and the Fl::event_text() and Fl::event_length() are left unchanged, length is zero for any function keys.
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.
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.