From d7b88a3bcc7e76f38ee5799be7722fd5a10781ef Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Wed, 13 Jan 1999 19:28:54 +0000 Subject: Updated all links so they work between files. Revision 1. git-svn-id: file:///fltk/svn/fltk/trunk@219 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/events.html | 366 ++++++++++++++++++++-------------------------- 1 file changed, 155 insertions(+), 211 deletions(-) (limited to 'documentation/events.html') diff --git a/documentation/events.html b/documentation/events.html index c9471ae25..3b62864b5 100644 --- a/documentation/events.html +++ b/documentation/events.html @@ -1,139 +1,96 @@ - - - -

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

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

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

FL_DRAG

- -The mouse has moved with a button held down. - -

FL_RELEASE

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

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.

+

FL_DRAG

+ The mouse has moved with a button held down. +

FL_RELEASE

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

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

FL_LEAVE

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

FL_UNFOCUS

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

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

FL_LEAVE

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

+

FL_UNFOCUS

+ Sent to the previous Fl::focus() + when another widget gets the 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. - -

FL_SHORTCUT

- -If the Fl::focus() 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. - +

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

FL_SHORTCUT

+ If the Fl::focus() 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.

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

FL_ACTIVATE

- -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 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! - +href="> +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(). - -

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

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

- - - +

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

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

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:

+ + \ No newline at end of file -- cgit v1.2.3