source: rtems-graphics-toolkit/fltk-1.1.10/documentation/events.html @ 513eea1

Last change on this file since 513eea1 was 513eea1, checked in by Joel Sherrill <joel.sherrill@…>, on 01/09/10 at 22:43:24

2010-01-08 Joel Sherrill <joel.sherrill@…>

fltk 1.1.10. imported

  • ORIGIN: Updated.
  • Property mode set to 100644
File size: 13.8 KB
Line 
1<HTML>
2<HEAD>
3        <TITLE>6 - Handling Events</TITLE>
4</HEAD>
5<BODY>
6
7<H1 ALIGN="RIGHT"><A NAME="events">6 - Handling Events</A></H1>
8
9<P>This chapter discusses the FLTK event model and how to handle
10events in your program or widget.
11
12<H2>The FLTK Event Model</H2>
13
14<P>Every time a user moves the mouse pointer, clicks a button,
15or presses a key, an event is generated and sent to your
16application. Events can also come from other programs like the
17window manager.
18
19<P>Events are identified by the integer argument passed to the
20<A href="subclassing.html#handle"><TT>Fl_Widget::handle()</TT></A> virtual
21method. Other information about the most recent event is stored in
22static locations and acquired  by calling the <A
23href="#event_xxx"><TT>Fl::event_*()</TT></A> methods. This static
24information remains valid until the next event is read from the window
25system, so it is ok to look at it outside of the <TT>handle()</TT>
26method.
27
28<H2>Mouse Events</H2>
29
30<H3>FL_PUSH</H3>
31
32<P>A mouse button has gone down with the mouse pointing at this
33widget. You can find out what button by calling <A
34href="Fl.html#Fl.event_button"><TT>
35Fl::event_button()</TT></A>. You find out the mouse position by
36calling <A
37href="Fl.html#Fl.event_x"><TT>Fl::event_x()</TT></A> and <A
38href="Fl.html#Fl.event_y"> <TT>Fl::event_y()</TT></A>.
39
40<P>A widget indicates that it &quot;wants&quot; the mouse click
41by returning non-zero from its <A
42href="subclassing.html#handle"><TT>handle()</TT></A> method. It
43will then become the <A href="Fl.html#Fl.pushed"><TT>
44Fl::pushed()</TT></A> widget and will get <TT>FL_DRAG</TT> and
45the matching <TT>FL_RELEASE</TT> events.  If <TT>handle()</TT>
46returns zero then FLTK will try sending the <TT>FL_PUSH</TT> to
47another widget. </P>
48
49<H3>FL_DRAG</H3>
50
51<P>The mouse has moved with a button held down. The current
52button state is in <a
53href="Fl.html#Fl.event_state"><tt>Fl::event_state()</tt></a>.
54The mouse position is in <a
55href="Fl.html#Fl.event_x"><tt>Fl::event_x()</tt></a> and <a
56href="Fl.html#Fl.event_y"><tt>Fl::event_y()</tt></a>.
57
58<P>In order to receive <TT>FL_DRAG</TT> events, the widget must
59return non-zero when handling <TT>FL_PUSH</TT>.</P>
60
61<H3>FL_RELEASE</H3>
62
63<P>A mouse button has been released. You can find out what
64button by calling <A
65href="Fl.html#Fl.event_button"><TT>Fl::event_button()</TT></A>.
66
67<P>In order to receive the <TT>FL_RELEASE</TT> event, the widget must
68return non-zero when handling <TT>FL_PUSH</TT>.</P>
69
70<H3>FL_MOVE</H3>
71
72<P>The mouse has moved without any mouse buttons held down.
73This event is sent to the <A
74href="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse()</TT></A>
75widget.</P>
76
77<P>In order to receive <TT>FL_MOVE</TT> events, the widget must
78return non-zero when handling <TT>FL_ENTER</TT>.</P>
79
80<H3>FL_MOUSEWHEEL</H3>
81
82<P>The user has moved the mouse wheel. The <A
83HREF="Fl.html#Fl.event_dx"><TT>Fl::event_dx()</TT></A> and <A
84HREF="Fl.html#Fl.event_dy"><TT>Fl::event_dy()</TT></A> methods
85can be used to find the amount to scroll horizontally and
86vertically.
87
88<H2>Focus Events</H2>
89
90<H3>FL_ENTER</H3>
91
92<P>The mouse has been moved to point at this widget.  This can
93be used for highlighting feedback.  If a widget wants to
94highlight or otherwise track the mouse, it indicates this by
95returning non-zero from its <A
96href="Fl.html#Fl.handle"><TT>handle()</TT></A> method. It then
97becomes the <A
98href="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse()</TT></A>
99widget and will receive <TT>FL_MOVE</TT> and <TT>FL_LEAVE</TT>
100events.
101
102<H3>FL_LEAVE</H3>
103
104<P>The mouse has moved out of the widget.
105
106<P>In order to receive the <TT>FL_LEAVE</TT> event, the widget must
107return non-zero when handling <TT>FL_ENTER</TT>.</P>
108
109<H3>FL_FOCUS</H3>
110
111<P>This indicates an <I>attempt</I> to give a widget the
112keyboard focus.
113
114<P>If a widget wants the focus, it should change itself to
115display the fact that it has the focus, and return non-zero from
116its <A
117href="Fl_Widget.html#Fl_Widget.handle"><TT>handle()</TT></A>
118method.  It then becomes the <A
119href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A> widget and gets
120<TT>FL_KEYDOWN</TT>, <TT>FL_KEYUP</TT>, and <TT>FL_UNFOCUS</TT>
121events.
122
123<P>The focus will change either because the window manager
124changed which window gets the focus, or because the user tried
125to navigate using tab, arrows, or other keys. You can check <A
126href="Fl.html#Fl.event_key"><TT>Fl::event_key()</TT></A> to
127figure out why it moved. For navigation it will be the key
128pressed and interaction with the window manager it will be
129zero.
130
131<H3>FL_UNFOCUS</H3>
132
133<P>This event is sent to the previous <A
134href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A> widget when
135another widget gets the focus or the window loses focus.
136
137<H2>Keyboard Events</H2>
138
139<H3>FL_KEYDOWN, FL_KEYUP</H3>
140
141<P>A key was pressed or released. The key can be found in <A
142href="Fl.html#Fl.event_key"><TT>Fl::event_key()</TT></A>. The
143text that the key should insert can be found with <A
144href="Fl.html#Fl.event_text"><TT>Fl::event_text()</TT></A> and
145its length is in <A
146href="Fl.html#Fl.event_length"><TT>Fl::event_length()</TT></A>.
147If you use the key <TT>handle()</TT> should return 1. If you
148return zero then FLTK assumes you ignored the key and will
149then attempt to send it to a parent widget. If none of them want
150it, it will change the event into a <TT>FL_SHORTCUT</TT> event.
151
152<P>To receive <CODE>FL_KEYBOARD</CODE> events you must also
153respond to the <CODE>FL_FOCUS</CODE> and <CODE>FL_UNFOCUS</CODE>
154events.
155
156<P>If you are writing a text-editing widget you may also want to
157call the <a href="Fl.html#Fl.compose"><TT>Fl::compose()</TT></a>
158function to translate individual keystrokes into foreign
159characters.
160
161<P><code>FL_KEYUP</code> events are sent to the widget that
162currently has focus. This is not necessarily the same widget
163that received the corresponding <code>FL_KEYDOWN</code> event
164because focus may have changed between events.
165
166<H3>FL_SHORTCUT</H3>
167
168<P>If the <A href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A>
169widget is zero or ignores an <TT>FL_KEYBOARD</TT> event then
170FLTK tries sending this event to every widget it can, until one
171of them returns non-zero. <TT>FL_SHORTCUT</TT> is first sent to
172the <TT>Fl::belowmouse()</TT> widget, then its parents and
173siblings, and eventually to every widget in the window, trying
174to find an object that returns non-zero. FLTK tries really hard
175to not to ignore any keystrokes!
176
177<P>You can also make &quot;global&quot; shortcuts by using <A
178href="Fl.html#Fl.add_handler"><TT>Fl::add_handler()</TT></A>. A
179global shortcut will work no matter what windows are displayed
180or which one has the focus.</P>
181
182<H2>Widget Events</H2>
183
184<H3>FL_DEACTIVATE</H3>
185
186<P>This widget is no longer active, due to <A
187href="Fl_Widget.html#Fl_Widget.deactivate"><TT>deactivate()</TT></A>
188being called on it or one of its parents. <TT> active()</TT> may
189still be true after this, the widget is only active if
190<TT>active()</TT> is true on it and all its parents (use <TT>active_r()</TT> to check this).
191
192<H3>FL_ACTIVATE</H3>
193
194<P>This widget is now active, due to <A
195href="Fl_Widget.html#Fl_Widget.activate"><TT>activate()</TT></A>
196being called on it or one of its parents.
197
198<H3>FL_HIDE</H3>
199
200<P>This widget is no longer visible, due to <A
201href="Fl_Widget.html#Fl_Widget.hide"><tt>hide()</tt></a> being
202called on it or one of its parents, or due to a parent window
203being minimized.  <tt>visible()</tt> may still be true after
204this, but the widget is visible only if <tt>visible()</tt> is
205true for it and all its parents (use <tt>visible_r()</tt> to
206check this).
207
208<h3>FL_SHOW</h3>
209
210<P>This widget is visible again, due to <a
211href="Fl_Widget.html#Fl_Widget.show"><TT>show()</TT></A> being
212called on it or one of its parents, or due to a parent window
213being restored. <I>Child <TT>Fl_Window</TT>s respond to this by
214actually creating the window if not done already, so if you
215subclass a window, be sure to pass <TT>FL_SHOW</TT> to the base
216class <TT>handle()</TT> method!</I>
217
218<H2>Clipboard Events</H2>
219
220<H3>FL_PASTE</H3>
221
222<P>You should get this event some time after you call <A
223href="Fl.html#Fl.paste"><TT>Fl::paste()</TT></A>. The contents
224of <A href="Fl.html#Fl.event_text"><TT>Fl::event_text()</TT></A>
225is the text to insert and the number of characters is in <A
226href="Fl.html#Fl.event_length"><TT>Fl::event_length()</TT></A>.
227
228<H3>FL_SELECTIONCLEAR</H3>
229
230<P>The <A
231href="Fl.html#Fl.selection_owner"><TT>Fl::selection_owner()</TT></A>
232will get this event before the selection is moved to another
233widget. This indicates that some other widget or program has
234claimed the selection. Motif programs used this to clear the
235selection indication. Most modern programs ignore this.
236
237<H2><A NAME="dnd">Drag And Drop Events</A></H2>
238
239<P>FLTK supports drag and drop of text and files from any
240application on the desktop. Text is transfered using
241the current code page. Files are received as a list of full path
242and file names, separated by newline. On some platforms, path
243names are prepended with <tt>file://</tt>.
244
245<P>The drag and drop data is available in <tt>Fl::event_text()</tt> 
246at the concluding <tt>FL_PASTE</tt>. On some platforms, the
247event text is also available for the <tt>FL_DND_*</tt> events,
248however application must not depend on that behavior because it
249depends on the protocol used on each platform.
250
251<P><tt>FL_DND_*</tt> events cannot be used in widgets derived
252from <tt>Fl_Group</tt> or <tt>Fl_Window</tt>.
253
254<H3>FL_DND_ENTER</H3>
255
256<P>The mouse has been moved to point at this widget. A widget
257that is interested in receiving drag'n'drop data must return 1
258to receive FL_DND_DRAG, FL_DND_LEAVE and FL_DND_RELEASE events.
259
260<H3>FL_DND_DRAG</H3>
261
262<P>The mouse has been moved inside a widget while dragging data.
263A widget that is interested in receiving drag'n'drop data should
264indicate the possible drop position.
265
266<H3>FL_DND_LEAVE</H3>
267
268<P>The mouse has moved out of the widget.
269
270<H3>FL_DND_RELEASE</H3>
271
272<P>The user has released the mouse button dropping data into
273the widget. If the widget returns 1, it will receive the data in
274the immediately following FL_PASTE event.
275
276<!-- NEED 6in -->
277
278<H2><A name="event_xxx">Fl::event_*() methods</A></H2>
279
280<P>FLTK keeps the information about the most recent event in
281static storage. This information is good until the next event is
282processed. Thus it is valid inside <TT>handle()</TT> and
283<TT>callback()</TT> methods.
284
285<P>These are all trivial inline functions and thus very fast and small: </P>
286
287<UL>
288
289        <LI><A HREF="Fl.html#Fl.event_button"><TT>Fl::event_button</TT></A></LI>
290
291        <LI><A HREF="Fl.html#Fl.event_clicks"><TT>Fl::event_clicks</TT></A></LI>
292
293        <LI><A HREF="Fl.html#Fl.event_dx"><TT>Fl::event_dx</TT></A></LI>
294
295        <LI><A HREF="Fl.html#Fl.event_dy"><TT>Fl::event_dy</TT></A></LI>
296
297        <LI><A HREF="Fl.html#Fl.event_inside"><TT>Fl::event_inside</TT></A></LI>
298
299        <LI><A HREF="Fl.html#Fl.event_is_click"><TT>Fl::event_is_click</TT></A></LI>
300
301        <LI><A HREF="Fl.html#Fl.event_key"><TT>Fl::event_key</TT></A></LI>
302
303        <LI><A HREF="Fl.html#Fl.event_length"><TT>Fl::event_length</TT></A></LI>
304
305        <LI><A HREF="Fl.html#Fl.event_state"><TT>Fl::event_state</TT></A></LI>
306
307        <LI><A HREF="Fl.html#Fl.event_text"><TT>Fl::event_text</TT></A></LI>
308
309        <LI><A HREF="Fl.html#Fl.event_x"><TT>Fl::event_x</TT></A></LI>
310
311        <LI><A HREF="Fl.html#Fl.event_x_root"><TT>Fl::event_x_root</TT></A></LI>
312
313        <LI><A HREF="Fl.html#Fl.event_y"><TT>Fl::event_y</TT></A></LI>
314
315        <LI><A HREF="Fl.html#Fl.event_y_root"><TT>Fl::event_y_root</TT></A></LI>
316
317        <LI><A HREF="Fl.html#Fl.get_key"><TT>Fl::get_key</TT></A></LI>
318
319        <LI><A HREF="Fl.html#Fl.get_mouse"><TT>Fl::get_mouse</TT></A></LI>
320
321        <LI><A HREF="Fl.html#Fl.test_shortcut"><TT>Fl::test_shortcut</TT></A></LI>
322
323</UL>
324
325<H2><A name=propagation>Event Propagation</A></H2>
326
327<P>FLTK follows very simple and unchangeable rules for sending
328events. The major innovation is that widgets can indicate (by
329returning 0 from the <TT>handle()</TT> method) that they are not
330interested in an event, and FLTK can then send that event
331elsewhere.  This eliminates the need for &quot;interests&quot;
332(event masks or tables), and this is probably the main reason
333FLTK is much smaller than other toolkits.
334
335<P>Most events are sent directly to the <TT>handle()</TT> method
336of the <TT>Fl_Window</TT> that the window system says they
337belong to.  The window (actually the <TT>Fl_Group</TT> that
338<TT>Fl_Window</TT> is a subclass of) is responsible for sending
339the events on to any child widgets.  To make the
340<TT>Fl_Group</TT> code somewhat easier, FLTK sends some events
341(<TT>FL_DRAG</TT>, <TT>FL_RELEASE</TT>, <TT>FL_KEYBOARD</TT>,
342<TT>FL_SHORTCUT</TT>, <TT>FL_UNFOCUS</TT>, and
343<TT>FL_LEAVE</TT>) directly to leaf widgets. These procedures
344control those leaf widgets:
345
346<UL>
347
348        <LI><A HREF="Fl.html#Fl.add_handler"><TT>Fl::add_handler</TT></A></LI>
349
350        <LI><A HREF="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse</TT></A></LI>
351
352        <LI><A HREF="Fl.html#Fl.focus"><TT>Fl::focus</TT></A></LI>
353
354        <LI><A HREF="Fl.html#Fl.grab"><TT>Fl::grab</TT></A></LI>
355
356        <LI><A HREF="Fl.html#Fl.modal"><TT>Fl::modal</TT></A></LI>
357
358        <LI><A HREF="Fl.html#Fl.pushed"><TT>Fl::pushed</TT></A></LI>
359
360        <LI><A HREF="Fl.html#Fl.release"><TT>Fl::release</TT></A></LI>
361
362        <LI><A HREF="Fl_Widget.html#Fl_Widget.take_focus"><TT>Fl_Widget::take_focus</TT></A></LI>
363
364</UL>
365
366<H2><A name="compose">FLTK Compose-Character Sequences</A></H2>
367
368<P>The foreign-letter compose processing done by the <A
369href="Fl_Input.html#compose"><tt>Fl_Input</tt></a> widget is provided in
370a function that you can call if you are writing your own text editor
371widget.
372
373<p>FLTK uses its own compose processing to allow "preview" of
374the partially composed sequence, which is impossible with the
375usual "dead key" processing.
376
377<p>Although currently only characters in the ISO-8859-1
378character set are handled, you should call this in case any
379enhancements to the processing are done in the future. The
380interface has been designed to handle arbitrary UTF-8 encoded
381text.
382
383<P>The following methods are provided for character composition:
384
385<UL>
386
387        <LI><A HREF="Fl.html#Fl.compose"><TT>Fl::compose()</TT></A></LI>
388
389        <LI><A HREF="Fl.html#Fl.compose_reset"><TT>Fl::compose_reset()</TT></A></LI>
390
391</UL>
392
393</BODY>
394</HTML>
Note: See TracBrowser for help on using the repository browser.