6 - Handling Events

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

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 the Fl_Widget::handle() virtual method. Other information about the most recent event is stored in static locations and acquired by calling the Fl::event_*() 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 handle() method.

Mouse Events

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 "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.

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 FL_DRAG events, the widget must return non-zero when handling FL_PUSH.

FL_RELEASE

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

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

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 FL_MOVE events, the widget must return non-zero when handling FL_ENTER.

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.

Focus Events

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

FL_LEAVE

The mouse has moved out of the widget.

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

FL_FOCUS

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

FL_UNFOCUS

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

Keyboard Events

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 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 FL_SHORTCUT event.

To receive FL_KEYBOARD events you must also respond to the FL_FOCUS and 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.

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

FL_SHORTCUT

If the Fl::focus() widget is zero or ignores an FL_KEYBOARD 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 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.

Widget Events

FL_DEACTIVATE

This widget is no longer active, due to deactivate() being called on it or one of its parents. active() may still be true after this, the widget is only active if active() is true on it and all its parents (use active_r() to check this).

FL_ACTIVATE

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

FL_HIDE

This widget is no longer visible, due to hide() being called on it or one of its parents, or due to a parent window being minimized. visible() may still be true after this, but the widget is visible only if visible() is true for it and all its parents (use visible_r() to check this).

FL_SHOW

This widget is visible again, due to show() being called on it or one of its parents, or due to a parent window being restored. Child Fl_Windows respond to this by actually creating the window if not done already, so if you subclass a window, be sure to pass FL_SHOW to the base class handle() method!

Clipboard Events

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().

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.

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, seperated by newline. On some platforms, path names are prepended with file://.

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

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

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

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.

FL_DND_LEAVE

The mouse has moved out of the widget.

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 immediatly following FL_PASTE event.

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

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

• Fl::event_button
• Fl::event_clicks
• Fl::event_dx
• Fl::event_dy
• Fl::event_inside
• Fl::event_is_click
• Fl::event_key
• Fl::event_length
• Fl::event_state
• Fl::event_text
• Fl::event_x
• Fl::event_x_root
• Fl::event_y
• Fl::event_y_root
• Fl::get_key
• Fl::get_mouse
• Fl::test_shortcut

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 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.

Most events are sent directly to the 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 (FL_DRAG, FL_RELEASE, FL_KEYBOARD, FL_SHORTCUT, FL_UNFOCUS, and FL_LEAVE) directly to leaf widgets. These procedures control those leaf widgets:

• Fl::add_handler
• Fl::belowmouse
• Fl::focus
• Fl::grab
• Fl::modal
• Fl::pushed
• Fl::release
• Fl_Widget::take_focus

FLTK Compose-Character Sequences

The foreign-letter compose processing done by the Fl_Input widget 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:

• Fl::compose()
• Fl::compose_reset()

User Comments [ Add Comment ]

From Anonymous, 00:41 Aug 24, 2004 (score=4)

set focus problem: if some widget uses grab(internalWidget) you cannot set Fl::focus(nextWidget ). (See src. Fl::event) Solution: grab(0); Fl::focus(nextWidget); some widgets manipulate the focus, after calling the callback. beware. JH [ Reply ]

From Heinz, 02:13 Jul 12, 2004 (score=4)

MY PROBLEM: I m tryng to make a macro program. To interact with it , I need it to recognize  certain keypresses (shortcuts), even if its minimized and bunch of other programs working at the front. Tryed add_handle, it wont work when program is in background. Grab() looks promising..um..i don't get how to use it .. ???

FEEDBACK: This site is actually best site for learning FLTK as far as i have looked around and FLTK actually is FAST LIGHT TOOLKIT and fluid is good. With all this u have the same (and i think even better) tools for making windows applications than with commercial stuff. [ Reply ]

From Anonymous, 12:44 Oct 13, 2004 (score=2)

"matthiasm" said in a newsgroup posting concerning the FL_SHORTCUT event vs an FL_KEYDOWN event.

Explanation: FL_SHORTCUT events have the lowest priority in the system, because a wrong shortcut could harm the whole application. If you were to give the 'a' key as a shortcut, and it had higher priority, you could never enter the 'a' into any text field. So in order to determine which Widget should get a key event, FLTK first sends an FL_KEYDOWN event to the widget with focus. If that widget doesn't use the keystroke (returning 0), FLTK will resend the keystroke to all widgets, this time as an FL_SHORTCUT event. If still nobody uses the event, FLTK will call the user event handler. After that, it will return the event to the system.

There is no FL_SHORTCUT_UP corresponding to the FL_KEYUP event. [ Reply ]

From tieTYT, 15:03 May 27, 2004 (score=2)

This is all very complicated.  Some examples would be very appreciated.  I would like to see how you can use tab to change the focus.  How you could build something like a keyboard configuration for a game where each time you press a key it goes to the next textbox.  Or in the very least i'd like to see a simple example for every thing mentioned.  I can't even tell if every widget gets notified if the mouse moves or only the widget that the mouse is under... [ Reply ]