# 6 - Handling Events

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

## The FLTK Event Model

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 window system (i.e. 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()`.

To receive `FL_DRAG` events you must also respond to the `FL_PUSH` and `FL_RELEASE` events.

### FL_RELEASE

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

### FL_MOVE

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

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

### 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_KEYBOARD` 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.

## Keyboard Events

### FL_KEYBOARD

A key press. 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()`. If you use the key `handle()` 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 `FL_SHORTCUT` event.

To receive `FL_KEYBOARD` events you must also respond to the `FL_FOCUS` and `FL_UNFOCUS` 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 `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 `show()` being called on it or one of its parents, or due to a parent window being restored. Child `Fl_Window`s 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.

## 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_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 `Fl_Input` widget lets you type all the characters in the standard ISO-8859-1 character set. Most fonts will display these characters correctly.

To insert them, type the [compose] key and then one or two characters. The two characters can be in either order. The [compose] key is any of: Ctrl+Q, the righthand control key, or any key your X server calls `XK_Multi_key`.

Keys | Char |  | Keys | Char |  | Keys | Char |  | Keys | Char |  | Keys | Char |  | Keys | Char
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
space | nbsp |  | `*` | ° |  | `A`` | À |  | `D-` | Ð |  | `a`` | à |  | `d-` | ð
`!` | ¡ |  | `+-` | ± |  | `A'` | Á |  | `N~` | Ñ |  | `a'` | á |  | `n~` | ñ
`%` | ¢ |  | `2` | ² |  | `A^` | Â |  | `O`` | Ò |  | `a^` | â |  | `o`` | ò
`#` | £ |  | `3` | ³ |  | `A~` | Ã |  | `O'` | Ó |  | `a~` | ã |  | `o'` | ó
`$` | ¤ |  | `'` | ´ |  | `A:` | Ä |  | `O^` | Ô |  | `a:` | ä |  | `o^` | ô
`y=` | ¥ |  | `u` | µ |  | `A*` | Å |  | `O~` | Õ |  | `a*` | å |  | `o~` | õ
`|` | ¦ |  | `p` | ¶ |  | `AE` | Æ |  | `O:` | Ö |  | `ae` | æ |  | `o:` | ö
`&` | § |  | `.` | · |  | `C,` | Ç |  | `x` | × |  | `c,` | ç |  | `-:` | ÷
`:` | ¨ |  | `,` | ¸ |  | `E`` | È |  | `O/` | Ø |  | `e`` | è |  | `o/` | ø
`c` | © |  | `1` | ¹ |  | `E'` | É |  | `U`` | Ù |  | `e'` | é |  | `u`` | ù
`a` | ª |  | `o` | º |  | `E^` | Ê |  | `U'` | Ú |  | `e^` | ê |  | `u'` | ú
`<<` | « |  | `>>` | » |  | `E:` | Ë |  | `U^` | Û |  | `e:` | ë |  | `u^` | û
`~` | ¬ |  | `14` | ¼ |  | `I`` | Ì |  | `U:` | Ü |  | `i`` | ì |  | `u:` | ü
`-` |  |  | `12` | ½ |  | `I'` | Í |  | `Y'` | Ý |  | `i'` | í |  | `y'` | ý
`r` | ® |  | `34` | ¾ |  | `I^` | Î |  | `TH` | Þ |  | `i^` | î |  | `th` | þ
`_` | ¯ |  | `?` | ¿ |  | `I:` | Ï |  | `ss` | ß |  | `i:` | ï |  | `y:` | ÿ

For instance, to type "á" type [compose][a]['] or [compose]['][a].

The character "nbsp" (non-breaking space) is typed by using [compose][space].

The single-character sequences may be followed by a space if necessary to remove ambiguity. For instance, if you really want to type "ª~" rather than "ã" you must type [compose][a][space][~].

If you wish to use the compose function in your own code, your widget's `handle()` method must call `fl_compose()` in response to `FL_KEYPRESS` events:

#### `int fl_compose(int state, char c, int &del, char *buffer, int &ins)`

Starts or adds a single ASCII character to a compose sequence. This will return the number of old bytes to delete and a set of new bytes to insert, and a new `state` value. If this returns zero you can ignore the result (which just says to insert the character unchanged) and handle the keystroke yourself.

`state` must either be the return value of the last call to `fl_compose()` or zero to start a new compose sequence. Be sure to reset to zero if the user ever moves the cursor.

`c` is the ASCII character that the user typed.

`del` is set to the number of bytes to delete backwards. This will always be less or equal to the `ins` from the last call to `fl_compose()`, and will be zero if `state` is zero.

`buffer` will have the first `ins` bytes set to the data to insert and display (it is not nul-terminated).

`ins` will be the number of characters to insert.