diff --git a/FL/Fl_Input.H b/FL/Fl_Input.H index 631d3f639..043bcb8d2 100644 --- a/FL/Fl_Input.H +++ b/FL/Fl_Input.H @@ -86,8 +86,9 @@ selection. RightCtrl or -
ComposeStart - a compose-character +
Compose + \anchor Fl_Input_Compose_Character + Start a compose-character sequence. The next one or two keys typed define the character to insert (see table that follows.) diff --git a/documentation/src/events.dox b/documentation/src/events.dox index 9682cf3ce..227049eb5 100644 --- a/documentation/src/events.dox +++ b/documentation/src/events.dox @@ -13,13 +13,21 @@ 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 \ref events_event_xxx -methods. This static information remains valid until the next event +Fl_Widget::handle() +virtual method. +Other information about the most recent event is stored in +static locations and acquired by calling the +\ref events_event_xxx. +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. +of the +\ref Fl_Widget::handle() "handle()" +method. + +In the next chapter, the +\ref subclassing_events "MyClass::handle()" +example shows how to override this method to accept and process +specific events. \section events_mouse Mouse Events @@ -27,59 +35,60 @@ of the handle() method. A mouse button has gone down with the mouse pointing at this widget. You can find out what button by calling -Fl::event_button(). +Fl::event_button(). You find out the mouse position by calling -Fl::event_x() +Fl::event_x() and - Fl::event_y(). +Fl::event_y(). -A widget indicates that it "wants" the mouse click +A widget indicates that it \e "wants" the mouse click by returning non-zero from its -handle() +\ref Fl_Widget::handle() "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 +Fl::pushed() +widget and will get \p FL_DRAG and +the matching \p FL_RELEASE events. +If \ref Fl_Widget::handle() "handle()" +returns zero then FLTK will try sending the \p FL_PUSH to another widget. \subsection events_fl_drag FL_DRAG The mouse has moved with a button held down. The current button state is in -Fl::event_state(). +Fl::event_state(). The mouse position is in -Fl::event_x() +Fl::event_x() and -Fl::event_y(). +Fl::event_y(). -In order to receive FL_DRAG events, the widget must -return non-zero when handling FL_PUSH. +In order to receive \p FL_DRAG events, the widget must +return non-zero when handling \p FL_PUSH. \subsection events_fl_release FL_RELEASE A mouse button has been released. You can find out what button by calling -Fl::event_button(). +Fl::event_button(). -In order to receive the FL_RELEASE event, the widget must -return non-zero when handling FL_PUSH. +In order to receive the \p FL_RELEASE event, the widget must +return non-zero when handling \p FL_PUSH. \subsection events_fl_move FL_MOVE The mouse has moved without any mouse buttons held down. This event is sent to the -Fl::belowmouse() +Fl::belowmouse() widget. -In order to receive FL_MOVE events, the widget must -return non-zero when handling FL_ENTER. +In order to receive \p FL_MOVE events, the widget must +return non-zero when handling \p FL_ENTER. \subsection events_fl_mousewheel FL_MOUSEWHEEL The user has moved the mouse wheel. The -Fl::event_dx() +Fl::event_dx() and -Fl::event_dy() +Fl::event_dy() methods can be used to find the amount to scroll horizontally and vertically. @@ -91,44 +100,43 @@ 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() +If \ref Fl_Widget::handle() "handle()" method. It then becomes the -Fl::belowmouse() -widget and will receive FL_MOVE and FL_LEAVE +Fl::belowmouse() +widget and will receive \p FL_MOVE and \p FL_LEAVE events. \subsection events_fl_leave 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. +In order to receive the \p FL_LEAVE event, the widget must +return non-zero when handling \p FL_ENTER. \subsection events_fl_focus FL_FOCUS -This indicates an attempt to give a widget the -keyboard focus. +This indicates an \e 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() +\ref Fl_Widget::handle() "handle()" method. It then becomes the -Fl::focus() +Fl::focus() widget and gets -FL_KEYDOWN, FL_KEYUP, and FL_UNFOCUS +\p FL_KEYDOWN, \p FL_KEYUP, and \p 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() +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. \subsection events_fl_unfocus FL_UNFOCUS This event is sent to the previous -Fl::focus() +Fl::focus() widget when another widget gets the focus or the window loses focus. \section events_keyboard Keyboard Events @@ -136,44 +144,45 @@ widget when another widget gets the focus or the window loses focus. \subsection events_fl_keydown FL_KEYDOWN, FL_KEYUP A key was pressed or released. The key can be found in -Fl::event_key(). +Fl::event_key(). The text that the key should insert can be found with -Fl::event_text() +Fl::event_text() and its length is in -Fl::event_length(). -If you use the key handle() should return 1. If you +Fl::event_length(). +If you use the key +\ref Fl_Widget::handle() "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. +it, it will change the event into a \p FL_SHORTCUT event. -To receive FL_KEYBOARD events you must also -respond to the FL_FOCUS and FL_UNFOCUS +To receive \p FL_KEYBOARD events you must also +respond to the \p FL_FOCUS and \p FL_UNFOCUS events. If you are writing a text-editing widget you may also want to call the -Fl::compose() +Fl::compose() function to translate individual keystrokes into foreign characters. -FL_KEYUP events are sent to the widget that +\p 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 +that received the corresponding \p FL_KEYDOWN event because focus may have changed between events. \subsection events_fl_shortcut FL_SHORTCUT If the -Fl::focus() -widget is zero or ignores an FL_KEYBOARD event then +Fl::focus() +widget is zero or ignores an \p 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 +of them returns non-zero. \p 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(). +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. @@ -182,51 +191,60 @@ or which one has the focus. \subsection events_fl_deactivate 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). +\ref Fl_Widget::activate() "activate()" +being called on it or one of its parents. +\ref Fl_Widget::active() "active()" +may still be true after this, the widget is only active if +\ref Fl_Widget::active() "active()" +is true on it and all its parents (use +\ref Fl_Widget::active_r() "active_r()" +to check this). \subsection events_fl_activate FL_ACTIVATE This widget is now active, due to -activate() +\ref Fl_Widget::activate() "activate()" being called on it or one of its parents. \subsection events_fl_hide FL_HIDE This widget is no longer visible, due to -hide() +\ref Fl_Widget::hide() "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). +being minimized. +\ref Fl_Widget::visible() "visible()" +may still be true after this, but the widget is visible only if +\ref Fl_Widget::visible() "visible()" +true for it and all its parents (use +\ref Fl_Widget::visible_r() "visible_r()" +to check this). \subsection events_fl_show FL_SHOW This widget is visible again, due to -show() +\ref Fl_Widget::show() "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 +being restored. A child Fl_Window will 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! +subclass a window, be sure to pass \p FL_SHOW to the base +class +\ref Fl_Widget::handle() "handle()" +method! \section events_clipboard Clipboard Events \subsection events_fl_paste FL_PASTE You should get this event some time after you call -Fl::paste(). +Fl::paste(). The contents of -Fl::event_text() +Fl::event_text() is the text to insert and the number of characters is in -Fl::event_length(). +Fl::event_length(). \subsection events_fl_selectionclear FL_SELECTIONCLEAR -The Fl::selection_owner() +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 @@ -241,20 +259,20 @@ 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, +The drag and drop data is available in Fl::event_text() +at the concluding \p FL_PASTE. On some platforms, the +event text is also available for the \p 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. +\p FL_DND_* events cannot be used in widgets derived +from Fl_Group or Fl_Window. \subsection events_fl_dnd_enter 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. +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 +\p FL_DND_DRAG, \p FL_DND_LEAVE and \p FL_DND_RELEASE events. \subsection events_fl_dnd_drag FL_DND_DRAG @@ -270,7 +288,7 @@ The mouse has moved out of the widget. 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. +the immediatly following \p FL_PASTE event. @@ -279,89 +297,77 @@ the immediatly following FL_PASTE event. 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. +processed. Thus it is valid inside +\ref Fl_Widget::handle() "handle()" +and +\ref Fl_Widget::callback() "callback()" +methods. These are all trivial inline functions and thus very fast and small: -\li Fl::event_button - -\li Fl::event_clicks - -\li Fl::event_dx - -\li Fl::event_dy - -\li Fl::event_inside - -\li Fl::event_is_click - -\li Fl::event_key - -\li Fl::event_length - -\li Fl::event_state - -\li Fl::event_text - -\li Fl::event_x - -\li Fl::event_x_root - -\li Fl::event_y - -\li Fl::event_y_root - -\li Fl::get_key - -\li Fl::get_mouse - -\li Fl::test_shortcut +\li Fl::event_button() +\li Fl::event_clicks() +\li Fl::event_dx() +\li Fl::event_dy() +\li Fl::event_inside() +\li Fl::event_is_click() +\li Fl::event_key() +\li Fl::event_length() +\li Fl::event_state() +\li Fl::event_text() +\li Fl::event_x() +\li Fl::event_x_root() +\li Fl::event_y() +\li Fl::event_y_root() +\li Fl::get_key() +\li Fl::get_mouse() +\li Fl::test_shortcut() \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 handle() method) that they are not +returning 0 from the +\ref Fl_Widget::handle() "handle()" +method) that they are not interested in an event, and FLTK can then send that event -elsewhere. This eliminates the need for "interests" +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. -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 +Most events are sent directly to the +\ref Fl_Widget::handle() "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 +Fl_Group code somewhat easier, FLTK sends some events +(\p FL_DRAG, \p FL_RELEASE, \p FL_KEYBOARD, +\p FL_SHORTCUT, \p FL_UNFOCUS, and +\p FL_LEAVE) directly to leaf widgets. These procedures control those leaf widgets: -\li Fl::add_handler - -\li Fl::belowmouse - -\li Fl::focus - -\li Fl::grab - -\li Fl::modal - -\li Fl::pushed - -\li Fl::release - -\li Fl_Widget::take_focus +\li Fl::add_handler() +\li Fl::belowmouse() +\li Fl::focus() +\li Fl::grab() +\li Fl::modal() +\li Fl::pushed() +\li Fl::release() +\li Fl::take_focus() \section events_compose_characters FLTK Compose-Character Sequences +\todo Does Fltk Compose Character Sequences text need updating + after the addition of UTF-8 handling to FLTK-1.3.x ? + The foreign-letter compose processing done by the -Fl_Input -widget is provided in a function that you can call if you are writing +Fl_Input widget's +\ref Fl_Input_Compose_Character "compose" key handler +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 @@ -376,9 +382,8 @@ text. The following methods are provided for character composition: -\li Fl::compose() - -\li Fl::compose_reset() +\li Fl::compose() +\li Fl::compose_reset() \htmlonly