diff options
| author | Michael R Sweet <michael.r.sweet@gmail.com> | 1999-01-07 16:36:11 +0000 |
|---|---|---|
| committer | Michael R Sweet <michael.r.sweet@gmail.com> | 1999-01-07 16:36:11 +0000 |
| commit | 367f908d8ed5a3464b9676223a26ddf4e11bdb5b (patch) | |
| tree | 2b0ec583852973ccf7b9804957e78d474e0e7e5d /documentation/events.html | |
| parent | 85e6f449590eeb6e09f7547733adf4c7137470d0 (diff) | |
"Final" changes for first draft of 1.0 documentation.
git-svn-id: file:///fltk/svn/fltk/trunk@187 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
Diffstat (limited to 'documentation/events.html')
| -rw-r--r-- | documentation/events.html | 572 |
1 files changed, 149 insertions, 423 deletions
diff --git a/documentation/events.html b/documentation/events.html index b4b5f1513..c4bc8c052 100644 --- a/documentation/events.html +++ b/documentation/events.html @@ -1,499 +1,225 @@ <HTML> <BODY> -<H1 ALIGN=RIGHT>4 - Handling Events</H1> +<H1 ALIGN=RIGHT><A NAME="events">6 - Handling Events</A></H1> This chapter discusses the FLTK event model and how to handle events in your program or widget. <H2>The FLTK Event Model</H2> -<H2>Mouse Events</H2> - -<H3><TT>FL_PUSH</TT></H3> - -<H3><TT>FL_RELEASE</TT></H3> - -<H3><TT>FL_DRAG</TT></H3> - -<H3><TT>FL_MOVE</TT></H3> - -<H2>Keyboard Events</H2> - -<H3><TT>FL_KEYBOARD</TT></H3> - -<H3><TT>FL_SHORTCUT</TT></H3> - -<H2>Widget Events</H2> - -<H3><TT>FL_ACTIVATE</TT></H3> - -<H3><TT>FL_DEACTIVATE</TT></H3> - -<H3><TT>FL_HIDE</TT></H3> - -<H3><TT>FL_SHOW</TT></H3> - -<H3><TT>FL_FOCUS</TT></H3> - -<H3><TT>FL_UNFOCUS</TT></H3> +Events are identified the small integer argument passed to the <a +href="#handle"><tt>Fl_Widget::handle()</tt></a> virtual method. Other +information about the most recent event is stored in static locations +and acquired by calling the <a +href="#event_xxx"><tt>Fl::event_*()</tt></a> 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 <tt>handle()</tt> method). -<H3><TT>FL_ENTER</TT></H3> - -<H3><TT>FL_LEAVE</TT></H3> - -<H3><TT>FL_PASTE</TT></H3> - -<H3><TT>FL_SELECTIONCLEAR</TT></H3> - -</BODY> -</HTML> -<title>Events in Fltk</title> -<a name=types> -<h2>Events in Fltk</h2> - -<p>Events are identified the small integer argument passed to the <a -href=subclass.html#handle>Fl_Widget::handle()</a> virtual method. -Other information about the most recent event is stored in static -locations and aquired by calling <a -href=#information><code>Fl::event_*()</code></a>. This static -information remains valid until the next event is read from the X -server (that is, it is ok to look at it outside the handle() method). +<H2>Mouse Events</H2> -</ul><h4><code>FL_PUSH (1)</code></h4><ul> +<h3>FL_PUSH</h3> A mouse button has gone down with the mouse pointing at this widget. You can find out what button by calling <a -href=#event_button>Fl::event_button()</a>. You find out the mouse -position by calling <a href=#event_x>Fl::event_x() and -Fl::event_y()</a>. +href="#event_button"><tt>Fl::event_button()</tt></a>. You find out the +mouse position by calling <a href="#event_x"><tt>Fl::event_x()</tt></a> +and <a href="#event_y"><tt>Fl::event_y()</tt></a>. <p>A widget indicates that it "wants" the mouse click by returning -non-zero from it's <a href=subclass.html#handle>handle()</a> method. -It will then become the <a href=#pushed>Fl::pushed()</a> 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. +non-zero from its <a href="#handle"><tt>handle()</tt></a> method. It +will then become the <a href="#pushed"><tt>Fl::pushed()</tt></a> widget +and will get <tt>FL_DRAG</tt> and the matching <tt>FL_RELEASE</tt> +events. If <tt>handle()</tt> returns zero then FLTK will try sending +the <tt>FL_PUSH</tt> to another widget. -</ul><h4><code>FL_DRAG (5)</code></h4><ul> +<h3>FL_DRAG</h3> -The mouse has moved with the button held down. +The mouse has moved with a button held down. -</ul><h4><code>FL_RELEASE (2)</code></h4><ul> +<h3>FL_RELEASE</h3> A mouse button has been released. You can find out what button by -calling <a href=#event_button>Fl::event_button()</a>. +calling <a href="#event_button"><tt>Fl::event_button()</tt></a>. -</ul><h4><code>FL_ENTER (3)</code></h4><ul> +<h3>FL_MOVE</h3> -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 it's <a href=subclass.html#handle>handle()</a> method. -It then becomes the <a href=#belowmouse>Fl::belowmouse()</a> widget -and will receive FL_MOVE and FL_EXIT events. +The mouse has moved without any mouse buttons held down. This event +is sent to the <tt>belowmouse()</tt> widget. -</ul><h4><code>FL_MOVE (10)</code></h4><ul> +<H2>Focus Events</H2> -The mouse has moved without any mouse buttons held down. This event -is sent (sort of) to the belowmouse() widget. +<h3>FL_ENTER</h3> + +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 <a +href="#handle"><tt>handle()</tt></a> method. It then becomes the <a +href="#belowmouse"><tt>Fl::belowmouse()</tt></a> widget and will +receive <tt>FL_MOVE</tt> and <tt>FL_LEAVE</tt> events. -</ul><h4><code>FL_LEAVE (4)</code></h4><ul> +<h3>FL_LEAVE</h3> The mouse has moved out of the widget. -</ul><h4><code>FL_FOCUS (6)</code></h4><ul> +<h3>FL_FOCUS</h3> This indicates an <i>attempt</i> to give a widget the keyboard focus. <p>If a widget wants the focus, it should change itself to display the -fact that it has the focus, and return non-zero from it's <a -href=subclass.html#handle>handle()</a> method. It then becomes the <a -href=#focus>Fl::focus()</a> widget and gets FL_KEYBOARD and FL_UNFOCUS -events. +fact that it has the focus, and return non-zero from its <a +href="#handle"><tt>handle()</tt></a> method. It then becomes the <a +href="#focus"><tt>Fl::focus()</tt></a> widget and gets <tt>FL_KEYBOARD</tt> +and <tt>FL_UNFOCUS</tt> events. <p>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 <a -href=#event_key>Fl::event_key()</a> to figure out why it moved. For -navigation it will be the key pressed, for instructions from the +href="#event_key"><tt>Fl::event_key()</tt></a> 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. -</ul><h4><code>FL_UNFOCUS (7)</code></h4><ul> +<h3>FL_UNFOCUS</h3> -Sent to the old <a href=#focus>Fl::focus()</a> when something else -gets the focus. +Sent to the previous <a href="#focus"><tt>Fl::focus()</tt></a> when +another widget gets the focus. + +<H2>Keyboard Events</H2> -</ul><h4><code>FL_KEYBOARD (8)</code></h4><ul> +<h3>FL_KEYBOARD</h3> A key press. The key pressed can be found in <a -href=#event_key>Fl::event_key()</a>, or, more usefully, the text that -the key should insert can be found with <a -href=#event_text>Fl::event_text()</a> and it's length is in <a -href=#event_length>Fl::event_length()</a>. 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. - -</ul><h4><code>FL_SHORTCUT (11)</code></h4><ul> - -If the <a href=#focus>Fl::focus()</a> 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 it's parents and siblings, and -eventually to every widget in the window, trying to find an object -that returns non-zero. Fltk tries real hard to not let any keystrokes -be ignored! - -<p>If the <a href=#event_text>Fl::event_text()</a> is a lower or -upper-case letter, and nothing wants the shortcut +href="#event_key"><tt>Fl::event_key()</tt></a>. The text that the key +should insert can be found with <a +href="#event_text"><tt>Fl::event_text()</tt></a> and its length is in +<a href="#event_length"><tt>Fl::event_length()</tt></a>. If you use +the key <tt>handle()</tt> 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 <tt>FL_SHORTCUT</tt> event. + +<h3>FL_SHORTCUT</h3> + +If the <a href="#focus"><tt>Fl::focus()</tt></a> is zero or ignores an +<tt>FL_KEYBOARD</tt> event then FLTK tries sending this event to every +widget it can, until one of them returns non-zero. +<tt>FL_SHORTCUT</tt> is first sent to the <tt>belowmouse()</tt> 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! <p>You can also make "global" shortcuts by using <a -href=#add_handler>Fl::add_handler()</a>. A global shortcut will work -no matter what windows are displayed or which one has the focus. +href="#add_handler"><tt>Fl::add_handler()</tt></a>. A global shortcut +will work no matter what windows are displayed or which one has the +focus. + +<H2>Widget Events</H2> -</ul><h4><code>FL_DEACTIVATE (13)</code></h4><ul> +<h3>FL_DEACTIVATE</h3> This widget is no longer active, due to <a -href=Fl_Widget.html#active>deactivate()</a> being called on it or one -of it's parents. active() may still be true after this, the widget is -only active if active() is true on it and all it's parents. +href="#Fl_Widget.deactivate"><tt>deactivate()</tt></a> being called on +it or one of its parents. <tt>active()</tt> may still be true after this, the +widget is only active if <tt>active()</tt> is true on it and all its parents +(use <tt>active_r()</tt> to check this). -</ul><h4><code>FL_ACTIVATE (14)</code></h4><ul> +<h3>FL_ACTIVATE</h3> This widget is now active, due to <a -href=Fl_Widget.html#activate>active()</a> being called on it or one -of it's parents. +href="#Fl_Widget.activate"><tt>activate()</tt></a> being called on it +or one of its parents. -</ul><h4><code>FL_HIDE (15)</code></h4><ul> +<h3>FL_HIDE</h3> This widget is no longer visible, due to <a -href=Fl_Widget.html#visible>hide()</a> being called, or a parent group -or window having hide() be called, or due to a parent window being -iconized. visible() may still be true after this, the widget is -visible only if visible() is true for it and all it's parents. +href="#Fl_Widget.hide><tt>hide()</a> being called on it or one of its +parents, or due to a parent window being minimized. <tt>visible()</tt> +may still be true after this, but the widget is visible only if +<tt>visible()</tt> is true for it and all its parents (use +<tt>visible_r()</tt> to check this). -</ul><h4><code>FL_SHOW (16)</code></h4><ul> +<h3>FL_SHOW</h3> This widget is visible again, due to <a -href=Fl_Widget.html#visible>show()</a> being called on it or one of -it's parents, or due to a parent window being deiconized. <i>Child -Fl_Windows respond to this by actually creating the X window if not -done already, so if you subclass a window, be sure to pass FL_SHOW to -the base class handle() method!</i> +href="#Fl_Widget.show"><tt>show()</tt></a> being called on it or one of +its parents, or due to a parent window being restored. <i>Child +<tt>Fl_Window</tt>s respond to this by actually creating the window if not +done already, so if you subclass a window, be sure to pass <tt>FL_SHOW</tt> to +the base class <tt>handle()</tt> method!</i> + +<H2>Clipboard Events</H2> -<a name=paste> -</ul><h4><code>FL_PASTE (17)</code></h4><ul> +<h3>FL_PASTE</h3> You should get this event some time after you call <a -href=cutpaste.html>Fl::paste()</a>. The contents of <a -href=#event_text>Fl::event_text()</a> is the text to insert and the -number of characters is in <a href=#event_length>Fl::event_length()</a>. +href="#paste"><tt>Fl::paste()</tt></a>. The contents of <a +href="#event_text"><tt>Fl::event_text()</tt></a> is the text to insert +and the number of characters is in <a +href="#event_length"><tt>Fl::event_length()</tt></a>. -</ul><h4><code>FL_SELECTIONCLEAR (18)</code></h4><ul> +<h3>FL_SELECTIONCLEAR</h3> -The <a href=cutpaste.html>Fl::selection_owner()</a> will get this +The <a href="#selection_owner">Fl::selection_owner()</a> will get this event before the selection is moved to another widget. This indicates that some other widget or program has claimed the selection. -</ul> - -<a name=information> -<h2>Fl::event_*() methods</h2> +<h2><a name="event_xxx">Fl::event_*() methods</a></h2> -Fltk keeps the information about the most recent event in static +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. +Thus it is valid inside <tt>handle()</tt> and <tt>callback()</tt> methods. <p>These are all trivial inline functions and thus very fast and -small. The data is stored in static locations and remains valid until -the next X event is handled. - -<a name=event_button> -</ul><h4><code>int Fl::event_button();</code></h4><ul> - -Returns which mouse button was pressed. This returns garbage if the -most recent event was not a FL_PUSH or FL_RELEASE. - -<a name=event_x> -</ul><h4><code>int Fl::event_x()</code> -<br><code>int Fl::event_y()</code></h4><ul> - -Returns the mouse position of the event (relative to the Fl_Window it -was passed to). - -</ul><h4><code>int Fl::event_x_root()</code> -<br><code>int Fl::event_y_root()</code></h4><ul> - -Returns the mouse position on the screen of the event. To find the -absolute position of an Fl_Window on the screen, use the difference -between event_x_root and event_x. - -<a name=get_mouse> -</ul><h4><code>void Fl::get_mouse(int &,int &)</code></h4><ul> - -<p>Return where the mouse is on the screen by doing a round-trip query -to the server. You should use <a -href=#event_x>Fl::event_x/y_root()</a> if possible, but this is -necessary if you are not sure if a mouse event has been processed -recently (such as to position your first window). If the display is -not open, this will open it. - -<a name=event_state> -</ul><h4><code>ulong Fl::event_state(); -<br>unsigned int Fl::event_state(int);</code></h4><ul> - -This is a bitfield of what shift states were on and what mouse buttons -were held down during the most recent event. The second version -returns non-zero if any of the passed bits are turned on. The legal -bits are <code>FL_SHIFT, FL_CAPS_LOCK, FL_CTRL, FL_ALT, FL_NUM_LOCK, -FL_META, FL_SCROLL_LOCK, FL_BUTTON1, FL_BUTTON2, FL_BUTTON3</code>. - -<i><p>X servers do not agree on shift states and FL_NUM_LOCK, FL_META, -and FL_SCROLL_LOCK may not work. The values were selected to match -the XFree86 server on Linux. In addition there is a bug in the way -Xlib works so that the shift state is not correctly reported until the -first event <b>after</b> the shift key is pressed or released.</i> - -<a name=event_key> -</ul><h4><code>int Fl::event_key(); -<br>int Fl::event_key(int); -<br>int Fl::get_key(int);</code></h4><ul> - -Fl::event_key() returns which key on the keyboard was last pushed. - -<p>Fl::event_key(int) returns true if the given key was held down (or -pressed) <i>during</i> the last event. This is constant until the -next event is read from the server. - -<p>Fl::get_key(int) returns true if the given key is held down -<i>now</i>. Under X this requires a round-trip to the server and is -<i>much</i> slower than Fl::event_key(int). - -<p>Keys are identified by the <i>unshifted</i> X keysym values. -However fltk defines a set of symbols that should work on most modern -machines for every key on the generic PC keyboard: - -<p><ul> - -<li>All keys on the main keyboard producing a printable ASCII -character use the value of that ASCII character (as though shift, -ctrl, and caps lock were not on). The space bar is 32. - -<li>All keys on the numeric keypad producing a printable ASCII -character use the value of that ASCII character plus -<code>FL_KP</code>. The highest possible value is -<code>FL_KP_Last</code> so you can range-check to see if something is -on the keypad. - -<li>All numbered function keys use the number on the function key plus -<code>FL_F</code>. The highest possible number is -<code>FL_F_Last</code>, so you can range-check a value. - -<li>Buttons on the mouse are considered keys, and use the button -number (where the left button is 1) plus <code>FL_Button</code>. - -<li>All other keys on the keypad have a symbol: <code>FL_Escape, -FL_BackSpace, FL_Tab, FL_Enter, FL_Print, FL_Scroll_Lock, FL_Pause, -FL_Insert, FL_Home, FL_Page_Up, FL_Delete, FL_End, FL_Page_Down, -FL_Left, FL_Up, FL_Right, FL_Down, FL_Shift_L, FL_Shift_R, -FL_Control_L, FL_Control_R, FL_Caps_Lock, FL_Alt_L, FL_Alt_R, -FL_Meta_L, FL_Meta_R, FL_Menu, FL_Num_Lock, FL_KP_Enter</code>. Be -careful not to confuse these with the very similar, but all-caps, -symbols used by <a href=#event_state>Fl::event_state()</a>. - -</ul> - -<p>Known bugs: on X <code>Fl::get_key(FL_Button+n)</code> does not -work. On MSWindows <code>Fl::get_key(FL_KP_Enter)</code> and -<code>Fl::event_key(FL_KP_Enter)</code> do not work. - -<a name=event_text> -</ul><h4><code>char * Fl::event_text()</code></h4><ul> - -<p>ASCII text (in the future this may be UTF-8) produced by the last -FL_KEYBOARD or FL_PASTE or possibly other event. A zero-length string -is returned for any keyboard function keys that do not produce text. -This pointer points at a static buffer and is only valid until the -next event is processed. - -<p>Under X this is the result of XLookupString. - -<a name=event_length> -</ul><h4><code>char * Fl::event_length()</code></h4><ul> - -<p>Length of the text in Fl::event_text(). There will always be a -null at this position in the text. However there may be a nul before -that if the keystroke translates to a nul character or you paste a nul -character. - -</ul><h4><code>int Fl::event_is_click()</code></h4><ul> - -Returns non-zero if the mouse has not moved far enough and not enough -time has passed since the last FL_PUSH or FL_KEYBOARD event for it -to be considered a "drag" rather than a "click". You can test this on -FL_DRAG, FL_RELEASE, and FL_MOVE events. - -</ul><h4><code>void Fl::event_is_click(0)</code></h4><ul> - -Clear the value returned by Fl::event_is_click(). Useful to prevent -the <i>next</i> click from being counted as a double-click or to make -a popup menu pick an item with a single click. Don't pass non-zero to -this. - -</ul><h4><code>int Fl::event_clicks()</code></h4><ul> - -Returns non-zero if the most recent FL_PUSH or FL_KEYBOARD was a -"double click". Returns N-1 for N clicks. A double click is counted -if the same button is pressed again while event_is_click() is true. - -</ul><h4><code>void Fl::event_clicks(int)</code></h4><ul> - -Directly set the number returned by Fl::event_clicks(). This can be -used to set it to zero so that later code does not think an item was -double-clicked. - -</ul><h4><code>int Fl::event_inside(const Fl_Widget *) const ; -<br>int Fl::event_inside(int,int,int,int);</code></h4><ul> - -Returns non-zero if the current event_x and event_y put it inside the -widget or inside an arbitrary bounding box. You should always call -this rather than doing your own comparison so you are consistent about -edge effects. - -</ul><h4><code>int Fl::test_shortcut(ulong) const ;</code></h4><ul> - -Test the current event, which must be an FL_KEYBOARD or FL_SHORTCUT, -against a shortcut value (described in <a -href=Fl_Button.html#shortcut>Fl_Button</a>). Returns non-zero if -there is a match. Not to be confused with <a -href=subclass.html#test_shortcut>Fl_Widget::test_shortcut()</a>. - +small: + +<ul> + <li><a name="event_button">Fl::event_button</a> + <li><a name="event_clicks">Fl::event_clicks</a> + <li><a name="event_inside">Fl::event_inside</a> + <li><a name="event_is_click">Fl::event_is_click</a> + <li><a name="event_key">Fl::event_key</a> + <li><a name="event_length">Fl::event_length</a> + <li><a name="event_state">Fl::event_state</a> + <li><a name="event_text">Fl::event_text</a> + <li><a name="event_x">Fl::event_x</a> + <li><a name="event_x_root">Fl::event_x_root</a> + <li><a name="event_y">Fl::event_y</a> + <li><a name="event_y_root">Fl::event_y_root</a> + <li><a name="get_key">Fl::get_key</a> + <li><a name="get_mouse">Fl::get_mouse</a> + <li><a name="test_shortcut">Fl::test_shortcut</a> </ul> -<a name=propagation> -<h2>Event Propagation</h2> +<h2><a name="propagation">Event Propagation</a></h2> -<p>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 +FLTK follows very simple and unchangeable rules for sending events. The +major innovation is that widgets can indicate (by returning 0 from the +<tt>handle()</tt> 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 X toolkits. - -<p>Most events are sent directly to the handle() method of the -Fl_Window that X 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, FL_LEAVE) directly to leaf -widgets. These procedures control those leaf widgets: - -<a name=focus> -</ul><h4><code>Fl_Widget *Fl::focus() const; -<br>void Fl::focus(Fl_Widget *);</code></h4><ul> - -Get or set the widget that will receive FL_KEYBOARD events. - -<p>If you change Fl::focus(), the old one and all parents (that don't -contain the new widget) are sent FL_UNFOCUS events. Changing the -focus does <i>not</i> send FL_FOCUS to this or any widget, because -sending FL_FOCUS is supposed to <i>test</i> if the widget wants the -focus (by it returning non-zero from handle()). - -</ul><h4><code>int Fl_Widget::take_focus();</code></h4><ul> - -<p>Try to make this widget be the Fl::focus(), by first sending it an -FL_FOCUS event, and if it returns non-zero, setting Fl::focus() to -this widget. You should use this method to assign the focus to an -widget. Returns true if the widget accepted the focus. - -<a name=belowmouse> -</ul><h4><code>Fl_Widget *Fl::belowmouse() const; -<br>void Fl::belowmouse(Fl_Widget *);</code></h4><ul> - -Get or set the widget that is below the mouse. This is for -highlighting buttons. It is not used to send FL_PUSH or FL_MOVE -directly, for several obscure reasons, but those events typically go -to this widget. This is also the first widget tried for FL_SHORTCUT -events. - -<p>If you change the belowmouse widget, the old one and all parents (that -don't contain the new widget) are sent FL_LEAVE events. Changing this -does <i>not</i> send FL_ENTER to this or any widget, because -sending FL_ENTER is supposed to <i>test</i> if the widget wants the -mouse (by it returning non-zero from handle()). - -<a name=pushed> -</ul><h4><code>Fl_Widget *Fl::pushed() const; -<br>void Fl::pushed(Fl_Widget *);</code></h4><ul> - -<p>Get or set the widget that is being pushed. FL_DRAG or FL_RELEASE -(and any more FL_PUSH) events will be sent to this widget. - -<p>If you change the pushed widget, the old one and all parents (that -don't contain the new widget) are sent FL_RELEASE events. Changing -this does <i>not</i> send FL_PUSH to this or any widget, because -sending FL_PUSH is supposed to <i>test</i> if the widget wants the -mouse (by it returning non-zero from handle()). - -<a name=add_handler> -</ul><h4><code>void Fl::add_handler(int (*f)(int));</code></h4><ul> - -Install a function to parse unrecognized events. If fltk cannot figure -out what to do with an event, it calls each of these functions (most -recent first) until one of them returns non-zero. If none of them -returns non zero then the event is ignored. Events that cause this to -be called are: - -<p><ul> -<li>FL_SHORTCUT events that are not recognized by any widget. This -lets you provide global shortcut keys. - -<li>System events that fltk does not recognize. See <a -href=x.html#fl_xevent>fl_xevent</a>. - -<li><i>Some</i> other events when the widget fltk selected returns zero -from it's handle() method. Exactly which ones may change in future -versions, however. +reason FLTK is much smaller than other toolkits. + +<p>Most events are sent directly to the <tt>handle()</tt> method of the +<tt>Fl_Window</tt> that the window system says they belong to. The +window (actually the <tt>Fl_Group</tt> that <tt>Fl_Window</tt> is a +subclass of) is responsible for sending the events on to any child +widgets. To make the <tt>Fl_Group</tt> code somewhat easier, FLTK +sends some events (<tt>FL_DRAG</tt>, <tt>FL_RELEASE</tt>, +<tt>FL_KEYBOARD</tt>, <tt>FL_SHORTCUT</tt>, <tt>FL_UNFOCUS</tt>, and +<tt>FL_LEAVE</tt>) directly to leaf widgets. These procedures control +those leaf widgets: + +<ul> + <li><a href="#add_handler">Fl::add_handler</a> + <li><a href="#belowmouse">Fl::belowmouse</a> + <li><a href="#focus">Fl::focus</a> + <li><a href="#grab">Fl::grab</a> + <li><a href="#modal">Fl::modal</a> + <li><a href="#pushed">Fl::pushed</a> + <li><a href="#release">Fl::release</a> + <li><a href="#Fl_Widget.take_focus">Fl_Widget::take_focus</a> </ul> -<a name=modal> -</ul><h4><code>Fl_Window* Fl::modal();</code></h4><ul> - -The modal() window has it's handle() method called for all events, and -no other windows will have handle() called. If <a -href=#grab>grab()</a> has been done then this is equal to grab(). -Otherwise this is the most recently shown() window with <a -href=Fl_Window.html#modal>modal()</a> true, or null if there are no -modal() windows shown(). - -<a name=grab> -</ul><h4><code>void Fl::grab(Fl_Window&);<br> -Fl_Window* Fl::grab();</code></h4><ul> - -This is used when pop-up menu systems are active. Send all events to -the passed window no matter where the pointer or focus is (including -in other programs). The window <i>does not have to be shown()</i>, -this lets the handle() method of a "dummy" window override all event -handling and allows you to map and unmap a complex set of windows -(under both X and NT <i>some</i> window must be mapped because the -system interface needs a window id). - -<p>Fl::event_x() and y() are undefiend if the passed widget is not a -mapped Fl_Window. Use Fl::event_x_root() and Fl::event_y_root() -instead. - -<p><i>Be careful that your program does not enter an infinite loop -while grab() is on. On X this will lock up your screen!</i> - -<p>The second function returns the current grab window, or null if -none. - -<a name=release> -</ul><h4><code>void Fl::release()</code></h4><ul> - -Turn off the grab() behavior. - -</ul><p><a href = index.html>(back to contents)</a> +</BODY> +</HTML> |