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 |
---|
10 | events 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, |
---|
15 | or presses a key, an event is generated and sent to your |
---|
16 | application. Events can also come from other programs like the |
---|
17 | window 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 |
---|
21 | method. Other information about the most recent event is stored in |
---|
22 | static locations and acquired by calling the <A |
---|
23 | href="#event_xxx"><TT>Fl::event_*()</TT></A> methods. This static |
---|
24 | information remains valid until the next event is read from the window |
---|
25 | system, so it is ok to look at it outside of the <TT>handle()</TT> |
---|
26 | method. |
---|
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 |
---|
33 | widget. You can find out what button by calling <A |
---|
34 | href="Fl.html#Fl.event_button"><TT> |
---|
35 | Fl::event_button()</TT></A>. You find out the mouse position by |
---|
36 | calling <A |
---|
37 | href="Fl.html#Fl.event_x"><TT>Fl::event_x()</TT></A> and <A |
---|
38 | href="Fl.html#Fl.event_y"> <TT>Fl::event_y()</TT></A>. |
---|
39 | |
---|
40 | <P>A widget indicates that it "wants" the mouse click |
---|
41 | by returning non-zero from its <A |
---|
42 | href="subclassing.html#handle"><TT>handle()</TT></A> method. It |
---|
43 | will then become the <A href="Fl.html#Fl.pushed"><TT> |
---|
44 | Fl::pushed()</TT></A> widget and will get <TT>FL_DRAG</TT> and |
---|
45 | the matching <TT>FL_RELEASE</TT> events. If <TT>handle()</TT> |
---|
46 | returns zero then FLTK will try sending the <TT>FL_PUSH</TT> to |
---|
47 | another widget. </P> |
---|
48 | |
---|
49 | <H3>FL_DRAG</H3> |
---|
50 | |
---|
51 | <P>The mouse has moved with a button held down. The current |
---|
52 | button state is in <a |
---|
53 | href="Fl.html#Fl.event_state"><tt>Fl::event_state()</tt></a>. |
---|
54 | The mouse position is in <a |
---|
55 | href="Fl.html#Fl.event_x"><tt>Fl::event_x()</tt></a> and <a |
---|
56 | href="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 |
---|
59 | return 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 |
---|
64 | button by calling <A |
---|
65 | href="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 |
---|
68 | return 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. |
---|
73 | This event is sent to the <A |
---|
74 | href="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse()</TT></A> |
---|
75 | widget.</P> |
---|
76 | |
---|
77 | <P>In order to receive <TT>FL_MOVE</TT> events, the widget must |
---|
78 | return 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 |
---|
83 | HREF="Fl.html#Fl.event_dx"><TT>Fl::event_dx()</TT></A> and <A |
---|
84 | HREF="Fl.html#Fl.event_dy"><TT>Fl::event_dy()</TT></A> methods |
---|
85 | can be used to find the amount to scroll horizontally and |
---|
86 | vertically. |
---|
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 |
---|
93 | be used for highlighting feedback. If a widget wants to |
---|
94 | highlight or otherwise track the mouse, it indicates this by |
---|
95 | returning non-zero from its <A |
---|
96 | href="Fl.html#Fl.handle"><TT>handle()</TT></A> method. It then |
---|
97 | becomes the <A |
---|
98 | href="Fl.html#Fl.belowmouse"><TT>Fl::belowmouse()</TT></A> |
---|
99 | widget and will receive <TT>FL_MOVE</TT> and <TT>FL_LEAVE</TT> |
---|
100 | events. |
---|
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 |
---|
107 | return 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 |
---|
112 | keyboard focus. |
---|
113 | |
---|
114 | <P>If a widget wants the focus, it should change itself to |
---|
115 | display the fact that it has the focus, and return non-zero from |
---|
116 | its <A |
---|
117 | href="Fl_Widget.html#Fl_Widget.handle"><TT>handle()</TT></A> |
---|
118 | method. It then becomes the <A |
---|
119 | href="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> |
---|
121 | events. |
---|
122 | |
---|
123 | <P>The focus will change either because the window manager |
---|
124 | changed which window gets the focus, or because the user tried |
---|
125 | to navigate using tab, arrows, or other keys. You can check <A |
---|
126 | href="Fl.html#Fl.event_key"><TT>Fl::event_key()</TT></A> to |
---|
127 | figure out why it moved. For navigation it will be the key |
---|
128 | pressed and interaction with the window manager it will be |
---|
129 | zero. |
---|
130 | |
---|
131 | <H3>FL_UNFOCUS</H3> |
---|
132 | |
---|
133 | <P>This event is sent to the previous <A |
---|
134 | href="Fl.html#Fl.focus"><TT>Fl::focus()</TT></A> widget when |
---|
135 | another 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 |
---|
142 | href="Fl.html#Fl.event_key"><TT>Fl::event_key()</TT></A>. The |
---|
143 | text that the key should insert can be found with <A |
---|
144 | href="Fl.html#Fl.event_text"><TT>Fl::event_text()</TT></A> and |
---|
145 | its length is in <A |
---|
146 | href="Fl.html#Fl.event_length"><TT>Fl::event_length()</TT></A>. |
---|
147 | If you use the key <TT>handle()</TT> should return 1. If you |
---|
148 | return zero then FLTK assumes you ignored the key and will |
---|
149 | then attempt to send it to a parent widget. If none of them want |
---|
150 | it, 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 |
---|
153 | respond to the <CODE>FL_FOCUS</CODE> and <CODE>FL_UNFOCUS</CODE> |
---|
154 | events. |
---|
155 | |
---|
156 | <P>If you are writing a text-editing widget you may also want to |
---|
157 | call the <a href="Fl.html#Fl.compose"><TT>Fl::compose()</TT></a> |
---|
158 | function to translate individual keystrokes into foreign |
---|
159 | characters. |
---|
160 | |
---|
161 | <P><code>FL_KEYUP</code> events are sent to the widget that |
---|
162 | currently has focus. This is not necessarily the same widget |
---|
163 | that received the corresponding <code>FL_KEYDOWN</code> event |
---|
164 | because 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> |
---|
169 | widget is zero or ignores an <TT>FL_KEYBOARD</TT> event then |
---|
170 | FLTK tries sending this event to every widget it can, until one |
---|
171 | of them returns non-zero. <TT>FL_SHORTCUT</TT> is first sent to |
---|
172 | the <TT>Fl::belowmouse()</TT> widget, then its parents and |
---|
173 | siblings, and eventually to every widget in the window, trying |
---|
174 | to find an object that returns non-zero. FLTK tries really hard |
---|
175 | to not to ignore any keystrokes! |
---|
176 | |
---|
177 | <P>You can also make "global" shortcuts by using <A |
---|
178 | href="Fl.html#Fl.add_handler"><TT>Fl::add_handler()</TT></A>. A |
---|
179 | global shortcut will work no matter what windows are displayed |
---|
180 | or 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 |
---|
187 | href="Fl_Widget.html#Fl_Widget.deactivate"><TT>deactivate()</TT></A> |
---|
188 | being called on it or one of its parents. <TT> active()</TT> may |
---|
189 | still 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 |
---|
195 | href="Fl_Widget.html#Fl_Widget.activate"><TT>activate()</TT></A> |
---|
196 | being 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 |
---|
201 | href="Fl_Widget.html#Fl_Widget.hide"><tt>hide()</tt></a> being |
---|
202 | called on it or one of its parents, or due to a parent window |
---|
203 | being minimized. <tt>visible()</tt> may still be true after |
---|
204 | this, but the widget is visible only if <tt>visible()</tt> is |
---|
205 | true for it and all its parents (use <tt>visible_r()</tt> to |
---|
206 | check this). |
---|
207 | |
---|
208 | <h3>FL_SHOW</h3> |
---|
209 | |
---|
210 | <P>This widget is visible again, due to <a |
---|
211 | href="Fl_Widget.html#Fl_Widget.show"><TT>show()</TT></A> being |
---|
212 | called on it or one of its parents, or due to a parent window |
---|
213 | being restored. <I>Child <TT>Fl_Window</TT>s respond to this by |
---|
214 | actually creating the window if not done already, so if you |
---|
215 | subclass a window, be sure to pass <TT>FL_SHOW</TT> to the base |
---|
216 | class <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 |
---|
223 | href="Fl.html#Fl.paste"><TT>Fl::paste()</TT></A>. The contents |
---|
224 | of <A href="Fl.html#Fl.event_text"><TT>Fl::event_text()</TT></A> |
---|
225 | is the text to insert and the number of characters is in <A |
---|
226 | href="Fl.html#Fl.event_length"><TT>Fl::event_length()</TT></A>. |
---|
227 | |
---|
228 | <H3>FL_SELECTIONCLEAR</H3> |
---|
229 | |
---|
230 | <P>The <A |
---|
231 | href="Fl.html#Fl.selection_owner"><TT>Fl::selection_owner()</TT></A> |
---|
232 | will get this event before the selection is moved to another |
---|
233 | widget. This indicates that some other widget or program has |
---|
234 | claimed the selection. Motif programs used this to clear the |
---|
235 | selection 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 |
---|
240 | application on the desktop. Text is transfered using |
---|
241 | the current code page. Files are received as a list of full path |
---|
242 | and file names, separated by newline. On some platforms, path |
---|
243 | names are prepended with <tt>file://</tt>. |
---|
244 | |
---|
245 | <P>The drag and drop data is available in <tt>Fl::event_text()</tt> |
---|
246 | at the concluding <tt>FL_PASTE</tt>. On some platforms, the |
---|
247 | event text is also available for the <tt>FL_DND_*</tt> events, |
---|
248 | however application must not depend on that behavior because it |
---|
249 | depends on the protocol used on each platform. |
---|
250 | |
---|
251 | <P><tt>FL_DND_*</tt> events cannot be used in widgets derived |
---|
252 | from <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 |
---|
257 | that is interested in receiving drag'n'drop data must return 1 |
---|
258 | to 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. |
---|
263 | A widget that is interested in receiving drag'n'drop data should |
---|
264 | indicate 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 |
---|
273 | the widget. If the widget returns 1, it will receive the data in |
---|
274 | the 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 |
---|
281 | static storage. This information is good until the next event is |
---|
282 | processed. 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 |
---|
328 | events. The major innovation is that widgets can indicate (by |
---|
329 | returning 0 from the <TT>handle()</TT> method) that they are not |
---|
330 | interested in an event, and FLTK can then send that event |
---|
331 | elsewhere. This eliminates the need for "interests" |
---|
332 | (event masks or tables), and this is probably the main reason |
---|
333 | FLTK is much smaller than other toolkits. |
---|
334 | |
---|
335 | <P>Most events are sent directly to the <TT>handle()</TT> method |
---|
336 | of the <TT>Fl_Window</TT> that the window system says they |
---|
337 | belong to. The window (actually the <TT>Fl_Group</TT> that |
---|
338 | <TT>Fl_Window</TT> is a subclass of) is responsible for sending |
---|
339 | the 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 |
---|
344 | control 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 |
---|
369 | href="Fl_Input.html#compose"><tt>Fl_Input</tt></a> widget is provided in |
---|
370 | a function that you can call if you are writing your own text editor |
---|
371 | widget. |
---|
372 | |
---|
373 | <p>FLTK uses its own compose processing to allow "preview" of |
---|
374 | the partially composed sequence, which is impossible with the |
---|
375 | usual "dead key" processing. |
---|
376 | |
---|
377 | <p>Although currently only characters in the ISO-8859-1 |
---|
378 | character set are handled, you should call this in case any |
---|
379 | enhancements to the processing are done in the future. The |
---|
380 | interface has been designed to handle arbitrary UTF-8 encoded |
---|
381 | text. |
---|
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> |
---|