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
17 The event command provides several facilities for dealing with window
18 system events, such as defining virtual events and synthesizing events.
19 The command has several different forms, determined by the first argu‐
20 ment. The following forms are currently supported:
21 event add <<virtual>> sequence ?sequence ...?
23 Associates the virtual event virtual with the physical event
24 sequence(s) given by the sequence arguments, so that the virtual
25 event will trigger whenever any one of the sequences occurs.
26 Virtual may be any string value and sequence may have any of the
27 values allowed for the sequence argument to the bind command.
28 If virtual is already defined, the new physical event sequences
29 add to the existing sequences for the event.
30 event delete <<virtual>> ?sequence sequence ...?
32 Deletes each of the sequences from those associated with the
33 virtual event given by virtual. Virtual may be any string value
34 and sequence may have any of the values allowed for the sequence
35 argument to the bind command. Any sequences not currently asso‐
36 ciated with virtual are ignored. If no sequence argument is
37 provided, all physical event sequences are removed for virtual,
38 so that the virtual event will not trigger anymore.
39 event generate window event ?option value option value ...?
41 Generates a window event and arranges for it to be processed
42 just as if it had come from the window system. Window gives the
43 path name of the window for which the event will be generated; │
44 it may also be an identifier (such as returned by winfo id) as │
45 long as it is for a window in the current application. Event
46 provides a basic description of the event, such as <Shift-But‐
47 ton-2> or <<Paste>>. If Window is empty the whole screen is
48 meant, and coordinates are relative to the screen. Event may
49 have any of the forms allowed for the sequence argument of the
50 bind command except that it must consist of a single event pat‐
51 tern, not a sequence. Option-value pairs may be used to specify
52 additional attributes of the event, such as the x and y mouse
53 position; see EVENT FIELDS below. If the -when option is not
54 specified, the event is processed immediately: all of the han‐
55 dlers for the event will complete before the event generate com‐
56 mand returns. If the -when option is specified then it deter‐
57 mines when the event is processed. Certain events, such as key
58 events, require that the window has focus to receive the event
59 properly.
60 event info ?<<virtual>>?
62 Returns information about virtual events. If the <<virtual>>
63 argument is omitted, the return value is a list of all the vir‐
64 tual events that are currently defined. If <<virtual>> is spec‐
65 ified then the return value is a list whose elements are the
66 physical event sequences currently defined for the given virtual
67 event; if the virtual event is not defined then an empty string
68 is returned.
69
71 The following options are supported for the event generate command.
72 These correspond to the ``%'' expansions allowed in binding scripts for
73 the bind command.
74 -above window
76 Window specifies the above field for the event, either as a win‐
77 dow path name or as an integer window id. Valid for Configure
78 events. Corresponds to the %a substitution for binding scripts.
79 -borderwidth size
81 Size must be a screen distance; it specifies the border_width
82 field for the event. Valid for Configure events. Corresponds
83 to the %B substitution for binding scripts.
84 -button number
86 Number must be an integer; it specifies the detail field for a
87 ButtonPress or ButtonRelease event, overriding any button num‐
88 ber provided in the base event argument. Corresponds to the %b
89 substitution for binding scripts.
90 -count number
92 Number must be an integer; it specifies the count field for the
93 event. Valid for Expose events. Corresponds to the %c substi‐
94 tution for binding scripts.
95 -delta number
97 Number must be an integer; it specifies the delta field for the
98 MouseWheel event. The delta refers to the direction and magni‐
99 tude the mouse wheel was rotated. Note the value is not a
100 screen distance but are units of motion in the mouse wheel.
101 Typically these values are multiples of 120. For example, 120
102 should scroll the text widget up 4 lines and -240 would scroll
103 the text widget down 8 lines. Of course, other widgets may
104 define different behaviors for mouse wheel motion. This field
105 corresponds to the %D substitution for binding scripts.
106 -detail detail
108 Detail specifies the detail field for the event and must be one
109 of the following:
110 NotifyAncestor NotifyNonlinearVirtual NotifyDetail‐
111 None NotifyPointer NotifyInferior NotifyPointer‐
112 Root NotifyNonlinear NotifyVirtual Valid for Enter,
113 Leave, FocusIn and FocusOut events. Corresponds to the %d sub‐
114 stitution for binding scripts.
115 -focus boolean
117 Boolean must be a boolean value; it specifies the focus field
118 for the event. Valid for Enter and Leave events. Corresponds
119 to the %f substitution for binding scripts.
120 -height size
122 Size must be a screen distance; it specifies the height field
123 for the event. Valid for Configure events. Corresponds to the
124 %h substitution for binding scripts.
125 -keycode number
127 Number must be an integer; it specifies the keycode field for
128 the event. Valid for KeyPress and KeyRelease events. Corre‐
129 sponds to the %k substitution for binding scripts.
130 -keysym name
132 Name must be the name of a valid keysym, such as g, space, or
133 Return; its corresponding keycode value is used as the keycode
134 field for event, overriding any detail specified in the base
135 event argument. Valid for KeyPress and KeyRelease events. Cor‐
136 responds to the %K substitution for binding scripts.
137 -mode notify
139 Notify specifies the mode field for the event and must be one of
140 NotifyNormal, NotifyGrab, NotifyUngrab, or NotifyWhileGrabbed.
141 Valid for Enter, Leave, FocusIn, and FocusOut events. Corre‐
142 sponds to the %m substitution for binding scripts.
143 -override boolean
145 Boolean must be a boolean value; it specifies the override_re‐
146 direct field for the event. Valid for Map, Reparent, and Con‐
147 figure events. Corresponds to the %o substitution for binding
148 scripts.
149 -place where
151 Where specifies the place field for the event; it must be
152 either PlaceOnTop or PlaceOnBottom. Valid for Circulate events.
153 Corresponds to the %p substitution for binding scripts.
154 -root window
156 Window must be either a window path name or an integer window
157 identifier; it specifies the root field for the event. Valid
158 for KeyPress, KeyRelease, ButtonPress, ButtonRelease, Enter,
159 Leave, and Motion events. Corresponds to the %R substitution
160 for binding scripts.
161 -rootx coord
163 Coord must be a screen distance; it specifies the x_root field
164 for the event. Valid for KeyPress, KeyRelease, ButtonPress,
165 ButtonRelease, Enter, Leave, and Motion events. Corresponds to
166 the %X substitution for binding scripts.
167 -rooty coord
169 Coord must be a screen distance; it specifies the y_root field
170 for the event. Valid for KeyPress, KeyRelease, ButtonPress,
171 ButtonRelease, Enter, Leave, and Motion events. Corresponds to
172 the %Y substitution for binding scripts.
173 -sendevent boolean
175 Boolean must be a boolean value; it specifies the send_event
176 field for the event. Valid for all events. Corresponds to the
177 %E substitution for binding scripts.
178 -serial number
180 Number must be an integer; it specifies the serial field for
181 the event. Valid for all events. Corresponds to the %# substi‐
182 tution for binding scripts.
183 -state state
185 State specifies the state field for the event. For KeyPress,
186 KeyRelease, ButtonPress, ButtonRelease, Enter, Leave, and Motion
187 events it must be an integer value. For Visibility events it
188 must be one of VisibilityUnobscured, VisibilityPartiallyOb‐
189 scured, or VisibilityFullyObscured. This option overrides any
190 modifiers such as Meta or Control specified in the base event.
191 Corresponds to the %s substitution for binding scripts.
192 -subwindow window
194 Window specifies the subwindow field for the event, either as a
195 path name for a Tk widget or as an integer window identifier.
196 Valid for KeyPress, KeyRelease, ButtonPress, ButtonRelease,
197 Enter, Leave, and Motion events. Similar to %S substitution for
198 binding scripts.
199 -time integer
201 Integer must be an integer value; it specifies the time field
202 for the event. Valid for KeyPress, KeyRelease, ButtonPress,
203 ButtonRelease, Enter, Leave, Motion, and Property events. Cor‐
204 responds to the %t substitution for binding scripts.
205 -warp boolean
207 boolean must be a boolean value; it specifies whether the
208 screen pointer should be warped as well. Valid for KeyPress,
209 KeyRelease, ButtonPress, ButtonRelease, and Motion events. The
210 pointer will only warp to a window if it is mapped.
211 -width size
213 Size must be a screen distance; it specifies the width field
214 for the event. Valid for Configure events. Corresponds to the
215 %w substitution for binding scripts.
216 -when when
218 When determines when the event will be processed; it must have
219 one of the following values:
220 now Process the event immediately, before the command
222 returns. This also happens if the -when option is
223 omitted.
224 tail Place the event on Tcl's event queue behind any events
226 already queued for this application.
227 head Place the event at the front of Tcl's event queue, so
229 that it will be handled before any other events
230 already queued.
231 mark Place the event at the front of Tcl's event queue but
233 behind any other events already queued with -when
234 mark. This option is useful when generating a series
235 of events that should be processed in order but at the
236 front of the queue.
237 -x coord
239 Coord must be a screen distance; it specifies the x field for
240 the event. Valid for KeyPress, KeyRelease, ButtonPress, Button‐
241 Release, Motion, Enter, Leave, Expose, Configure, Gravity, and
242 Reparent events. Corresponds to the %x substitution for binding
243 scripts. If Window is empty the coordinate is relative to the
244 screen, and this option corresponds to the %X substitution for
245 binding scripts.
246 -y coord
248 Coord must be a screen distance; it specifies the y field for
249 the event. Valid for KeyPress, KeyRelease, ButtonPress, Button‐
250 Release, Motion, Enter, Leave, Expose, Configure, Gravity, and
251 Reparent events. Corresponds to the %y substitution for binding
252 scripts. If Window is empty the coordinate is relative to the
253 screen, and this option corresponds to the %Y substitution for
254 binding scripts.
255 Any options that are not specified when generating an event are filled
257 with the value 0, except for serial, which is filled with the next X
258 event serial number.
259
261 In order for a virtual event binding to trigger, two things must hap‐
262 pen. First, the virtual event must be defined with the event add com‐
263 mand. Second, a binding must be created for the virtual event with the
264 bind command. Consider the following virtual event definitions:
265 event add <<Paste>> <Control-y>
266 event add <<Paste>> <Button-2>
267 event add <<Save>> <Control-X><Control-S>
268 event add <<Save>> <Shift-F12>
269 In the bind command, a virtual event can be bound like any other
270 builtin event type as follows:
271 bind Entry <<Paste>> {%W insert [selection get]}
272 The double angle brackets are used to specify that a virtual event is
273 being bound. If the user types Control-y or presses button 2, or if a
274 <<Paste>> virtual event is synthesized with event generate, then the
275 <<Paste>> binding will be invoked.
276 If a virtual binding has the exact same sequence as a separate physical
278 binding, then the physical binding will take precedence. Consider the
279 following example:
280 event add <<Paste>> <Control-y> <Meta-Control-y>
281 bind Entry <Control-y> {puts Control-y}
282 bind Entry <<Paste>> {puts Paste}
283 When the user types Control-y the <Control-y> binding will be invoked,
284 because a physical event is considered more specific than a virtual
285 event, all other things being equal. However, when the user types
286 Meta-Control-y the <<Paste>> binding will be invoked, because the Meta
287 modifier in the physical pattern associated with the virtual binding is
288 more specific than the <Control-y> sequence for the physical event.
289 Bindings on a virtual event may be created before the virtual event
291 exists. Indeed, the virtual event never actually needs to be defined,
292 for instance, on platforms where the specific virtual event would mean‐
293 ingless or ungeneratable.
294 When a definition of a virtual event changes at run time, all windows
296 will respond immediately to the new definition. Starting from the pre‐
297 ceding example, if the following code is executed:
298 bind <Entry> <Control-y> {}
299 event add <<Paste>> <Key-F6>
300 the behavior will change such in two ways. First, the shadowed
301 <<Paste>> binding will emerge. Typing Control-y will no longer invoke
302 the <Control-y> binding, but instead invoke the virtual event
303 <<Paste>>. Second, pressing the F6 key will now also invoke the
304 <<Paste>> binding.
305
308 bind(n)
309
312 event, binding, define, handle, virtual event
313Tk 8.3 event(n)