1event(n) Tk Built-In Commands event(n)
2______________________________________________________________________________
6
8 event - Miscellaneous event facilities: define virtual events and gen‐
9 erate events
10
12 event option ?arg arg ...?
13_________________________________________________________________
14
16 The event command provides several facilities for dealing with window
17 system events, such as defining virtual events and synthesizing events.
18 The command has several different forms, determined by the first argu‐
19 ment. The following forms are currently supported:
20 event add <<virtual>> sequence ?sequence ...?
22 Associates the virtual event virtual with the physical event
23 sequence(s) given by the sequence arguments, so that the virtual
24 event will trigger whenever any one of the sequences occurs.
25 Virtual may be any string value and sequence may have any of the
26 values allowed for the sequence argument to the bind command.
27 If virtual is already defined, the new physical event sequences
28 add to the existing sequences for the event.
29 event delete <<virtual>> ?sequence sequence ...?
31 Deletes each of the sequences from those associated with the
32 virtual event given by virtual. Virtual may be any string value
33 and sequence may have any of the values allowed for the sequence
34 argument to the bind command. Any sequences not currently asso‐
35 ciated with virtual are ignored. If no sequence argument is
36 provided, all physical event sequences are removed for virtual,
37 so that the virtual event will not trigger anymore.
38 event generate window event ?option value option value ...?
40 Generates a window event and arranges for it to be processed
41 just as if it had come from the window system. Window gives the
42 path name of the window for which the event will be generated;
43 it may also be an identifier (such as returned by winfo id) as
44 long as it is for a window in the current application. Event
45 provides a basic description of the event, such as <Shift-But‐
46 ton-2> or <<Paste>>. If Window is empty the whole screen is
47 meant, and coordinates are relative to the screen. Event may
48 have any of the forms allowed for the sequence argument of the
49 bind command except that it must consist of a single event pat‐
50 tern, not a sequence. Option-value pairs may be used to specify
51 additional attributes of the event, such as the x and y mouse
52 position; see EVENT FIELDS below. If the -when option is not
53 specified, the event is processed immediately: all of the han‐
54 dlers for the event will complete before the event generate com‐
55 mand returns. If the -when option is specified then it deter‐
56 mines when the event is processed. Certain events, such as key
57 events, require that the window has focus to receive the event
58 properly.
59 event info ?<<virtual>>?
61 Returns information about virtual events. If the <<virtual>>
62 argument is omitted, the return value is a list of all the vir‐
63 tual events that are currently defined. If <<virtual>> is spec‐
64 ified then the return value is a list whose elements are the
65 physical event sequences currently defined for the given virtual
66 event; if the virtual event is not defined then an empty string
67 is returned.
68 Note that virtual events that that are not bound to physical
70 event sequences are not returned by event info.
71
73 The following options are supported for the event generate command.
74 These correspond to the “%” expansions allowed in binding scripts for
75 the bind command.
76 -above window
78 Window specifies the above field for the event, either as a win‐
79 dow path name or as an integer window id. Valid for Configure
80 events. Corresponds to the %a substitution for binding scripts.
81 -borderwidth size
83 Size must be a screen distance; it specifies the border_width
84 field for the event. Valid for Configure events. Corresponds
85 to the %B substitution for binding scripts.
86 -button number
88 Number must be an integer; it specifies the detail field for a
89 ButtonPress or ButtonRelease event, overriding any button num‐
90 ber provided in the base event argument. Corresponds to the %b
91 substitution for binding scripts.
92 -count number
94 Number must be an integer; it specifies the count field for the
95 event. Valid for Expose events. Corresponds to the %c substi‐
96 tution for binding scripts. │
97 -data string │
99 String may be any value; it specifies the user_data field for │
100 the event. Only valid for virtual events. Corresponds to the │
101 %d substitution for virtual events in binding scripts.
102 -delta number
104 Number must be an integer; it specifies the delta field for the
105 MouseWheel event. The delta refers to the direction and magni‐
106 tude the mouse wheel was rotated. Note the value is not a
107 screen distance but are units of motion in the mouse wheel.
108 Typically these values are multiples of 120. For example, 120
109 should scroll the text widget up 4 lines and -240 would scroll
110 the text widget down 8 lines. Of course, other widgets may
111 define different behaviors for mouse wheel motion. This field
112 corresponds to the %D substitution for binding scripts.
113 -detail detail
115 Detail specifies the detail field for the event and must be one
116 of the following:
117 NotifyAncestor NotifyNonlinearVirtual NotifyDetail‐
118 None NotifyPointer NotifyInferior NotifyPointer‐
119 Root NotifyNonlinear NotifyVirtual Valid for Enter,
120 Leave, FocusIn and FocusOut events. Corresponds to the %d sub‐
121 stitution for binding scripts.
122 -focus boolean
124 Boolean must be a boolean value; it specifies the focus field
125 for the event. Valid for Enter and Leave events. Corresponds
126 to the %f substitution for binding scripts.
127 -height size
129 Size must be a screen distance; it specifies the height field
130 for the event. Valid for Configure events. Corresponds to the
131 %h substitution for binding scripts.
132 -keycode number
134 Number must be an integer; it specifies the keycode field for
135 the event. Valid for KeyPress and KeyRelease events. Corre‐
136 sponds to the %k substitution for binding scripts.
137 -keysym name
139 Name must be the name of a valid keysym, such as g, space, or
140 Return; its corresponding keycode value is used as the keycode
141 field for event, overriding any detail specified in the base
142 event argument. Valid for KeyPress and KeyRelease events. Cor‐
143 responds to the %K substitution for binding scripts.
144 -mode notify
146 Notify specifies the mode field for the event and must be one of
147 NotifyNormal, NotifyGrab, NotifyUngrab, or NotifyWhileGrabbed.
148 Valid for Enter, Leave, FocusIn, and FocusOut events. Corre‐
149 sponds to the %m substitution for binding scripts.
150 -override boolean
152 Boolean must be a boolean value; it specifies the override_re‐
153 direct field for the event. Valid for Map, Reparent, and Con‐
154 figure events. Corresponds to the %o substitution for binding
155 scripts.
156 -place where
158 Where specifies the place field for the event; it must be
159 either PlaceOnTop or PlaceOnBottom. Valid for Circulate events.
160 Corresponds to the %p substitution for binding scripts.
161 -root window
163 Window must be either a window path name or an integer window
164 identifier; it specifies the root field for the event. Valid
165 for KeyPress, KeyRelease, ButtonPress, ButtonRelease, Enter,
166 Leave, and Motion events. Corresponds to the %R substitution
167 for binding scripts.
168 -rootx coord
170 Coord must be a screen distance; it specifies the x_root field
171 for the event. Valid for KeyPress, KeyRelease, ButtonPress,
172 ButtonRelease, Enter, Leave, and Motion events. Corresponds to
173 the %X substitution for binding scripts.
174 -rooty coord
176 Coord must be a screen distance; it specifies the y_root field
177 for the event. Valid for KeyPress, KeyRelease, ButtonPress,
178 ButtonRelease, Enter, Leave, and Motion events. Corresponds to
179 the %Y substitution for binding scripts.
180 -sendevent boolean
182 Boolean must be a boolean value; it specifies the send_event
183 field for the event. Valid for all events. Corresponds to the
184 %E substitution for binding scripts.
185 -serial number
187 Number must be an integer; it specifies the serial field for
188 the event. Valid for all events. Corresponds to the %# substi‐
189 tution for binding scripts.
190 -state state
192 State specifies the state field for the event. For KeyPress,
193 KeyRelease, ButtonPress, ButtonRelease, Enter, Leave, and Motion
194 events it must be an integer value. For Visibility events it
195 must be one of VisibilityUnobscured, VisibilityPartiallyOb‐
196 scured, or VisibilityFullyObscured. This option overrides any
197 modifiers such as Meta or Control specified in the base event.
198 Corresponds to the %s substitution for binding scripts.
199 -subwindow window
201 Window specifies the subwindow field for the event, either as a
202 path name for a Tk widget or as an integer window identifier.
203 Valid for KeyPress, KeyRelease, ButtonPress, ButtonRelease,
204 Enter, Leave, and Motion events. Similar to %S substitution for
205 binding scripts.
206 -time integer
208 Integer must be an integer value; it specifies the time field
209 for the event. Valid for KeyPress, KeyRelease, ButtonPress,
210 ButtonRelease, Enter, Leave, Motion, and Property events. Cor‐
211 responds to the %t substitution for binding scripts.
212 -warp boolean
214 boolean must be a boolean value; it specifies whether the
215 screen pointer should be warped as well. Valid for KeyPress,
216 KeyRelease, ButtonPress, ButtonRelease, and Motion events. The
217 pointer will only warp to a window if it is mapped.
218 -width size
220 Size must be a screen distance; it specifies the width field
221 for the event. Valid for Configure events. Corresponds to the
222 %w substitution for binding scripts.
223 -when when
225 When determines when the event will be processed; it must have
226 one of the following values:
227 now Process the event immediately, before the command
229 returns. This also happens if the -when option is
230 omitted.
231 tail Place the event on Tcl's event queue behind any events
233 already queued for this application.
234 head Place the event at the front of Tcl's event queue, so
236 that it will be handled before any other events
237 already queued.
238 mark Place the event at the front of Tcl's event queue but
240 behind any other events already queued with -when
241 mark. This option is useful when generating a series
242 of events that should be processed in order but at the
243 front of the queue.
244 -x coord
246 Coord must be a screen distance; it specifies the x field for
247 the event. Valid for KeyPress, KeyRelease, ButtonPress, Button‐
248 Release, Motion, Enter, Leave, Expose, Configure, Gravity, and
249 Reparent events. Corresponds to the %x substitution for binding
250 scripts. If Window is empty the coordinate is relative to the
251 screen, and this option corresponds to the %X substitution for
252 binding scripts.
253 -y coord
255 Coord must be a screen distance; it specifies the y field for
256 the event. Valid for KeyPress, KeyRelease, ButtonPress, Button‐
257 Release, Motion, Enter, Leave, Expose, Configure, Gravity, and
258 Reparent events. Corresponds to the %y substitution for binding
259 scripts. If Window is empty the coordinate is relative to the
260 screen, and this option corresponds to the %Y substitution for
261 binding scripts.
262 Any options that are not specified when generating an event are filled
264 with the value 0, except for serial, which is filled with the next X
265 event serial number.
266
268 Tk defines the following virtual events for the purposes of notifica‐
269 tion:
270 <<AltUnderlined>>
272 This is sent to widget to notify it that the letter it has
273 underlined (as an accelerator indicator) with the -underline
274 option has been pressed in combination with the Alt key. The
275 usual response to this is to either focus into the widget (or
276 some related widget) or to invoke the widget.
277 <<ListboxSelect>>
279 This is sent to a listbox when the set of selected item(s) in
280 the listbox is updated.
281 <<MenuSelect>>
283 This is sent to a menu when the currently selected item in the
284 menu changes. It is intended for use with context-sensitive help
285 systems.
286 <<Modified>>
288 This is sent to a text widget when the contents of the widget
289 are changed.
290 <<Selection>>
292 This is sent to a text widget when the selection in the widget
293 is changed.
294 <<TraverseIn>>
296 This is sent to a widget when the focus enters the widget
297 because of a user-driven “tab to widget” action.
298 <<TraverseOut>>
300 This is sent to a widget when the focus leaves the widget
301 because of a user-driven “tab to widget” action.
302 Tk defines the following virtual events for the purposes of unifying
304 bindings across multiple platforms. Users expect them to behave in the
305 following way:
306 <<Clear>>
308 Delete the currently selected widget contents.
309 <<Copy>>
311 Copy the currently selected widget contents to the clipboard.
312 <<Cut>>
314 Move the currently selected widget contents to the clipboard.
315 <<Paste>>
317 Replace the currently selected widget contents with the contents
318 of the clipboard.
319 <<PasteSelection>>
321 Insert the contents of the selection at the mouse location.
322 (This event has meaningful %x and %y substitutions).
323 <<PrevWindow>>
325 Traverse to the previous window.
326 <<Redo>>
328 Redo one undone action.
329 <<Undo>>
331 Undo the last action.
332
334 In order for a virtual event binding to trigger, two things must hap‐
335 pen. First, the virtual event must be defined with the event add com‐
336 mand. Second, a binding must be created for the virtual event with the
337 bind command. Consider the following virtual event definitions:
338 event add <<Paste>> <Control-y>
339 event add <<Paste>> <Button-2>
340 event add <<Save>> <Control-X><Control-S>
341 event add <<Save>> <Shift-F12>
342 In the bind command, a virtual event can be bound like any other
343 builtin event type as follows:
344 bind Entry <<Paste>> {%W insert [selection get]}
345 The double angle brackets are used to specify that a virtual event is
346 being bound. If the user types Control-y or presses button 2, or if a
347 <<Paste>> virtual event is synthesized with event generate, then the
348 <<Paste>> binding will be invoked.
349 If a virtual binding has the exact same sequence as a separate physical
351 binding, then the physical binding will take precedence. Consider the
352 following example:
353 event add <<Paste>> <Control-y> <Meta-Control-y>
354 bind Entry <Control-y> {puts Control-y}
355 bind Entry <<Paste>> {puts Paste}
356 When the user types Control-y the <Control-y> binding will be invoked,
357 because a physical event is considered more specific than a virtual
358 event, all other things being equal. However, when the user types
359 Meta-Control-y the <<Paste>> binding will be invoked, because the Meta
360 modifier in the physical pattern associated with the virtual binding is
361 more specific than the <Control-y> sequence for the physical event.
362 Bindings on a virtual event may be created before the virtual event
364 exists. Indeed, the virtual event never actually needs to be defined,
365 for instance, on platforms where the specific virtual event would mean‐
366 ingless or ungeneratable.
367 When a definition of a virtual event changes at run time, all windows
369 will respond immediately to the new definition. Starting from the pre‐
370 ceding example, if the following code is executed:
371 bind <Entry> <Control-y> {}
372 event add <<Paste>> <Key-F6>
373 the behavior will change such in two ways. First, the shadowed
374 <<Paste>> binding will emerge. Typing Control-y will no longer invoke
375 the <Control-y> binding, but instead invoke the virtual event
376 <<Paste>>. Second, pressing the F6 key will now also invoke the
377 <<Paste>> binding.
378
381 bind(n)
382
385 event, binding, define, handle, virtual event
386Tk 8.3 event(n)