From 09cfc1a1ea00f7edf394e647f1f32e5b0913f564 Mon Sep 17 00:00:00 2001 From: Fabien Costantini Date: Fri, 17 Oct 2008 11:22:35 +0000 Subject: Removing current broken history documentation/src dir. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6451 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/src/events.dox | 389 ------------------------------------------- 1 file changed, 389 deletions(-) delete mode 100644 documentation/src/events.dox (limited to 'documentation/src/events.dox') diff --git a/documentation/src/events.dox b/documentation/src/events.dox deleted file mode 100644 index 9682cf3ce..000000000 --- a/documentation/src/events.dox +++ /dev/null @@ -1,389 +0,0 @@ -/** - - \page events 6 - Handling Events - -This chapter discusses the FLTK event model and how to handle -events in your program or widget. - -\section events_model 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. - -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 -is read from the window system, so it is ok to look at it outside -of the handle() method. - -\section events_mouse Mouse Events - -\subsection events_fl_push 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. - -\subsection events_fl_drag 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(). - -In order to receive FL_DRAG events, the widget must -return non-zero when handling 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(). - -In order to receive the FL_RELEASE event, the widget must -return non-zero when handling 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() -widget. - -In order to receive FL_MOVE events, the widget must -return non-zero when handling FL_ENTER. - -\subsection events_fl_mousewheel 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. - -\section events_focus Focus Events - -\subsection events_fl_enter 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. - -\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. - -\subsection events_fl_focus 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_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. - -\subsection events_fl_unfocus FL_UNFOCUS - -This event is sent to the previous -Fl::focus() -widget when another widget gets the focus or the window loses focus. - -\section events_keyboard Keyboard Events - -\subsection events_fl_keydown 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_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 -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 -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. - -\section events_widget Widget Events - -\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). - -\subsection events_fl_activate FL_ACTIVATE - -This widget is now active, due to -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() -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). - -\subsection events_fl_show 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! - -\section events_clipboard Clipboard Events - -\subsection events_fl_paste 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(). - -\subsection events_fl_selectionclear 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. - - -\section events_dnd Drag and Drop Events - -FLTK supports drag and drop of text and files from any -application on the desktop. Text is transfered using -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, -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. - -\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. - -\subsection events_fl_dnd_drag FL_DND_DRAG - -The mouse has been moved inside a widget while dragging data. -A widget that is interested in receiving drag'n'drop data should -indicate the possible drop position. - -\subsection events_fl_dnd_leave FL_DND_LEAVE - -The mouse has moved out of the widget. - -\subsection events_fl_dnd_release FL_DND_RELEASE - -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. - - - - -\section events_event_xxx 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: - -\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 -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: - -\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 - - -\section events_compose_characters FLTK Compose-Character Sequences - -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 its 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. - -The following methods are provided for character composition: - -\li Fl::compose() - -\li Fl::compose_reset() - -\htmlonly -
-[Index]    -[Previous]  5 - Drawing Things in FLTK  -[Next]  7 - Adding and Extending Widgets  -\endhtmlonly -*/ -- cgit v1.2.3