From efd09a5a70cd2eac6ea58330ff456cd51c82c51d Mon Sep 17 00:00:00 2001 From: Matthias Melcher Date: Wed, 7 Apr 2010 19:24:49 +0000 Subject: Added some more information on event delivery (STR 1983) git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@7466 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- CHANGES | 1 + documentation/src/events.dox | 52 ++++++++++++++++++++++++++++++++++++-------- 2 files changed, 44 insertions(+), 9 deletions(-) diff --git a/CHANGES b/CHANGES index 6fd109eaa..9eafd32bc 100644 --- a/CHANGES +++ b/CHANGES @@ -1,5 +1,6 @@ CHANGES IN FLTK 1.3.0 + - Added documentation for event delivery (STR #1983) - Fixed menu and tooltip window animation bug under X11 (compiz) by setting an appropriate window type (STR #2082) - redesigned CMake files (STR #2317). diff --git a/documentation/src/events.dox b/documentation/src/events.dox index 9ea3df10c..23018e4af 100644 --- a/documentation/src/events.dox +++ b/documentation/src/events.dox @@ -337,15 +337,11 @@ These are all trivial inline functions and thus very fast and small: \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. +Widgets receive events via the virtual handle() function. The argument indicates +the type of event that can be handled. The widget must indicat if it handled the +event by returning 1. FLTK will then remove the event and wait for further events +from the host. If the widget's handle function returns 0, FLTK may redistribute +the event based on a few rules. Most events are sent directly to the \p handle() @@ -369,6 +365,44 @@ control those leaf widgets: \li Fl::release() \li Fl_Widget::take_focus() +FLTK propagetes events along the widget hierarchy depending on the kind of event +and the status of the UI. Some events are injected directly into the widgets, others +may be resend as anew event to a different group of receivers. + +Mouse click events are first sent to the Window that caused them. The Window +then forwards the event down the hierarchy until it reaches the Widget that +is below the click position. It that Widget uses the given event, the widget +is marked "pushed" and will receive all following mouse motion events until the +mouse button release. + +Mouse wheel events are sent to the Window that caused the event. The Window +propagets the event down the tree, first to the widget that is below the +mouse pointer, and if that does not succeed, to all other widgets in the Group. +This ensures that Scroll widgets work as expected with the widget furthest +down in the hierarchy getting the first opportunity to use the wheel event, +but also giving scroll bars, that are ot directly below the mouse a chance. + +Keyboard events are sent directly to the Widget that has keyboard focus. +If the focused Widget rejects the event, it is resent as a Shortcut event, +first to the top-most window, then to the widget below the mouse pointer, +propagiting up the hierarchy to all its parents. Those send the event also +to all widgets that are not below the mouse pointer. Now if that did not work +out, the shortcut is sent to all registered shortcut handler. + +If we are still unsuccessful, the event handler flips the case of the shortcut +letter and starts over. Finally, if the key is "escape", FLTK sends a close +event to the top-most window. + +All other events are pretty much sent right away to the window that created +the event. + +Widgets can "grab" events. The grabbing window gets all events exclusively, but +usually by the same rules as described above. + +Windows can also request eclusivity in event handling by making the +window non-modal. + + \section events_compose_characters FLTK Compose-Character Sequences \todo Does Fltk Compose Character Sequences text need updating -- cgit v1.2.3