From 09daf20b81cdae78772f07c0af22a571d7cc73eb Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Thu, 29 Nov 2001 19:24:00 +0000 Subject: Documentation updates galore (up to chapter 7, still need to do chapter 8 and 9, tweek the appendices, and recapture the screenshots...) git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1786 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/events.html | 468 ++++++++++++++++++++++++++++------------------ 1 file changed, 283 insertions(+), 185 deletions(-) (limited to 'documentation/events.html') diff --git a/documentation/events.html b/documentation/events.html index 2eb847545..a742d69f4 100644 --- a/documentation/events.html +++ b/documentation/events.html @@ -1,238 +1,336 @@ - -

6 - Handling Events

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

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

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 +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). +href="#event_xxx">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.

+ +

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

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

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

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

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

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

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.

+ +

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

-Sent to the previous Fl::focus() -widget when another widget gets the focus. + +

This event is sent to the previous Fl::focus() widget when +another widget gets the focus or the window loses 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. - -

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

+ +

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

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

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

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! +

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

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

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

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

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:

+ +

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:

+ +

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: +

-

FLTK Compose-Character Sequences

+

FLTK Compose-Character Sequences

-The foreign-letter compose processing done by the Fl_Input widget is provided in +

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

int Fl::compose(int& del)

+

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

Use of this function is very simple. Any text editing widget should -call this for each FL_KEYBOARD event. +

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

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!). In 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(). +

The following methods are provided for character composition: -

If false is returned, the keys should be treated as function -keys, and del is set to zero. You could insert the text anyways, if -you don't know what else to do. +

- + + -- cgit v1.2.3