1event(n)                     Tk Built-In Commands                     event(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       event  - Miscellaneous event facilities: define virtual events and gen‐
9       erate events
10

SYNOPSIS

12       event option ?arg arg ...?
13______________________________________________________________________________
14

DESCRIPTION

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
21       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
30       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
39       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
60       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
69              Note  that  virtual  events that are not bound to physical event
70              sequences are not returned by event info.
71

EVENT FIELDS

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
77       -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
82       -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
87       -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
93       -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
98       -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
103       -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
114       -detail detail
115              Detail  specifies the detail field for the event and must be one
116              of the following:
117
118                     NotifyAncestor          NotifyNonlinearVirtual
119                     NotifyDetailNone        NotifyPointer
120                     NotifyInferior          NotifyPointerRoot
121                     NotifyNonlinear         NotifyVirtual
122
123              Valid for Enter, Leave, FocusIn  and  FocusOut  events.   Corre‐
124              sponds to the %d substitution for binding scripts.
125
126       -focus boolean
127              Boolean  must  be a boolean value;  it specifies the focus field
128              for the event.  Valid for Enter and Leave  events.   Corresponds
129              to the %f substitution for binding scripts.
130
131       -height size
132              Size  must  be a screen distance;  it specifies the height field
133              for the event.  Valid for Configure events.  Corresponds to  the
134              %h substitution for binding scripts.
135
136       -keycode number
137              Number   must be an integer;  it specifies the keycode field for
138              the event.  Valid for KeyPress and  KeyRelease  events.   Corre‐
139              sponds to the %k substitution for binding scripts.
140
141       -keysym name
142              Name  must  be  the name of a valid keysym, such as g, space, or
143              Return;  its corresponding keycode value is used as the  keycode
144              field  for  event,  overriding  any detail specified in the base
145              event argument.  Valid for KeyPress and KeyRelease events.  Cor‐
146              responds to the %K substitution for binding scripts.
147
148       -mode notify
149              Notify specifies the mode field for the event and must be one of
150              NotifyNormal, NotifyGrab, NotifyUngrab,  or  NotifyWhileGrabbed.
151              Valid  for  Enter,  Leave, FocusIn, and FocusOut events.  Corre‐
152              sponds to the %m substitution for binding scripts.
153
154       -override boolean
155              Boolean must be a boolean value;  it specifies the  override_re‐
156              direct  field  for the event.  Valid for Map, Reparent, and Con‐
157              figure events.  Corresponds to the %o substitution  for  binding
158              scripts.
159
160       -place where
161              Where  specifies  the  place  field  for  the event;  it must be
162              either PlaceOnTop or PlaceOnBottom.  Valid for Circulate events.
163              Corresponds to the %p substitution for binding scripts.
164
165       -root window
166              Window  must  be  either a window path name or an integer window
167              identifier;  it specifies the root field for the  event.   Valid
168              for  KeyPress,  KeyRelease,  ButtonPress,  ButtonRelease, Enter,
169              Leave, and Motion events.  Corresponds to  the  %R  substitution
170              for binding scripts.
171
172       -rootx coord
173              Coord  must be a screen distance;  it specifies the x_root field
174              for the event.  Valid  for  KeyPress,  KeyRelease,  ButtonPress,
175              ButtonRelease,  Enter, Leave, and Motion events.  Corresponds to
176              the %X substitution for binding scripts.
177
178       -rooty coord
179              Coord must be a screen distance;  it specifies the y_root  field
180              for  the  event.   Valid  for KeyPress, KeyRelease, ButtonPress,
181              ButtonRelease, Enter, Leave, and Motion events.  Corresponds  to
182              the %Y substitution for binding scripts.
183
184       -sendevent boolean
185              Boolean  must  be  a boolean value;  it specifies the send_event
186              field for the event.  Valid for all events.  Corresponds to  the
187              %E substitution for binding scripts.
188
189       -serial number
190              Number  must  be  an integer;  it specifies the serial field for
191              the event.  Valid for all events.  Corresponds to the %# substi‐
192              tution for binding scripts.
193
194       -state state
195              State  specifies  the  state field for the event.  For KeyPress,
196              KeyRelease, ButtonPress, ButtonRelease, Enter, Leave, and Motion
197              events  it  must  be an integer value.  For Visibility events it
198              must  be  one  of  VisibilityUnobscured,  VisibilityPartiallyOb‐
199              scured,  or  VisibilityFullyObscured.  This option overrides any
200              modifiers such as Meta or Control specified in the  base  event.
201              Corresponds to the %s substitution for binding scripts.
202
203       -subwindow window
204              Window  specifies the subwindow field for the event, either as a
205              path name for a Tk widget or as an  integer  window  identifier.
206              Valid  for  KeyPress,  KeyRelease,  ButtonPress,  ButtonRelease,
207              Enter, Leave, and Motion events.  Similar to %S substitution for
208              binding scripts.
209
210       -time integer
211              Integer  must  be an integer value;  it specifies the time field
212              for the event.  Valid  for  KeyPress,  KeyRelease,  ButtonPress,
213              ButtonRelease,  Enter, Leave, Motion, and Property events.  Cor‐
214              responds to the %t substitution for binding scripts.
215
216       -warp boolean
217              boolean must be a  boolean  value;   it  specifies  whether  the
218              screen  pointer  should  be warped as well.  Valid for KeyPress,
219              KeyRelease, ButtonPress, ButtonRelease, and Motion events.   The
220              pointer will only warp to a window if it is mapped.
221
222       -width size
223              Size  must  be  a screen distance;  it specifies the width field
224              for the event.  Valid for Configure events.  Corresponds to  the
225              %w substitution for binding scripts.
226
227       -when when
228              When  determines when the event will be processed;  it must have
229              one of the following values:
230
231              now       Process the  event  immediately,  before  the  command
232                        returns.   This  also  happens  if the -when option is
233                        omitted.
234
235              tail      Place the event on Tcl's event queue behind any events
236                        already queued for this application.
237
238              head      Place  the event at the front of Tcl's event queue, so
239                        that it  will  be  handled  before  any  other  events
240                        already queued.
241
242              mark      Place  the event at the front of Tcl's event queue but
243                        behind any other  events  already  queued  with  -when
244                        mark.   This option is useful when generating a series
245                        of events that should be processed in order but at the
246                        front of the queue.
247
248       -x coord
249              Coord  must  be a screen distance;  it specifies the x field for
250              the event.  Valid for KeyPress, KeyRelease, ButtonPress, Button‐
251              Release,  Motion,  Enter, Leave, Expose, Configure, Gravity, and
252              Reparent events.  Corresponds to the %x substitution for binding
253              scripts.   If  Window is empty the coordinate is relative to the
254              screen, and this option corresponds to the %X  substitution  for
255              binding scripts.
256
257       -y coord
258              Coord  must  be a screen distance;  it specifies the y field for
259              the event.  Valid for KeyPress, KeyRelease, ButtonPress, Button‐
260              Release,  Motion,  Enter, Leave, Expose, Configure, Gravity, and
261              Reparent events.  Corresponds to the %y substitution for binding
262              scripts.   If  Window is empty the coordinate is relative to the
263              screen, and this option corresponds to the %Y  substitution  for
264              binding scripts.
265
266       Any  options that are not specified when generating an event are filled
267       with the value 0, except for serial, which is filled with  the  next  X
268       event serial number.
269

PREDEFINED VIRTUAL EVENTS

271       Tk  defines  the following virtual events for the purposes of notifica‐
272       tion:
273
274       <<AltUnderlined>>
275              This is sent to widget to notify  it  that  the  letter  it  has
276              underlined  (as  an  accelerator  indicator) with the -underline
277              option has been pressed in combination with  the  Alt  key.  The
278              usual  response  to  this is to either focus into the widget (or
279              some related widget) or to invoke the widget.
280
281       <<Invoke>>
282              This can be sent to some widgets (e.g. button, listbox, menu) as
283              an alternative to <space>.
284
285       <<ListboxSelect>>
286              This  is  sent  to a listbox when the set of selected item(s) in
287              the listbox is updated.
288
289       <<MenuSelect>>
290              This is sent to a menu when the currently selected item  in  the
291              menu changes. It is intended for use with context-sensitive help
292              systems.
293
294       <<Modified>>
295              This is sent to a text widget when the contents  of  the  widget
296              are changed.
297
298       <<Selection>>
299              This  is  sent to a text widget when the selection in the widget
300              is changed.
301
302       <<ThemeChanged>>
303              This is sent to a text widget when the ttk (Tile) theme changed.
304
305       <<TraverseIn>>
306              This is sent to a  widget  when  the  focus  enters  the  widget
307              because of a user-driven “tab to widget” action.
308
309       <<TraverseOut>>
310              This  is  sent  to  a  widget  when  the focus leaves the widget
311              because of a user-driven “tab to widget” action.
312
313       <<UndoStack>>
314              This is sent to a text widget when its undo stack or redo  stack
315              becomes empty or unempty.
316
317       <<WidgetViewSync>>
318              This  is  sent  to  a  text widget when its internal data become
319              obsolete, and again when these internal data are  back  in  sync
320              with  the  widget  view.  The  detail field (%d substitution) is
321              either true (when the widget is in sync) or false  (when  it  is
322              not).
323
324       Tk  defines  the  following virtual events for the purposes of unifying
325       bindings across multiple platforms. Users expect them to behave in  the
326       following way:
327
328       <<Clear>>
329              Delete the currently selected widget contents.
330
331       <<Copy>>
332              Copy the currently selected widget contents to the clipboard.
333
334       <<Cut>>
335              Move the currently selected widget contents to the clipboard.
336
337       <<LineEnd>>
338              Move  to  the  end of the line in the current widget while dese‐
339              lecting any selected contents.
340
341       <<LineStart>>
342              Move to the start of the line in the current widget while  dese‐
343              lecting any selected contents.
344
345       <<NextChar>>
346              Move  to  the next item (i.e., visible character) in the current
347              widget while deselecting any selected contents.
348
349       <<NextLine>>
350              Move to the next line in the current  widget  while  deselecting
351              any selected contents.
352
353       <<NextPara>>
354              Move to the next paragraph in the current widget while deselect‐
355              ing any selected contents.
356
357       <<NextWord>>
358              Move to the next group of items (i.e., visible word) in the cur‐
359              rent widget while deselecting any selected contents.
360
361       <<Paste>>
362              Replace the currently selected widget contents with the contents
363              of the clipboard.
364
365       <<PasteSelection>>
366              Insert the contents of the  selection  at  the  mouse  location.
367              (This event has meaningful %x and %y substitutions).
368
369       <<PrevChar>>
370              Move  to the previous item (i.e., visible character) in the cur‐
371              rent widget while deselecting any selected contents.
372
373       <<PrevLine>>
374              Move to the previous line in the current widget while  deselect‐
375              ing any selected contents.
376
377       <<PrevPara>>
378              Move to the previous paragraph in the current widget while dese‐
379              lecting any selected contents.
380
381       <<PrevWindow>>
382              Traverse to the previous window.
383
384       <<PrevWord>>
385              Move to the previous group of items (i.e., visible word) in  the
386              current widget while deselecting any selected contents.
387
388       <<Redo>>
389              Redo one undone action.
390
391       <<SelectAll>>
392              Set the range of selected contents to the complete widget.
393
394       <<SelectLineEnd>>
395              Move  to the end of the line in the current widget while extend‐
396              ing the range of selected contents.
397
398       <<SelectLineStart>>
399              Move to the start of  the  line  in  the  current  widget  while
400              extending the range of selected contents.
401
402       <<SelectNextChar>>
403              Move  to  the next item (i.e., visible character) in the current
404              widget while extending the range of selected contents.
405
406       <<SelectNextLine>>
407              Move to the next line in the current widget while extending  the
408              range of selected contents.
409
410       <<SelectNextPara>>
411              Move to the next paragraph in the current widget while extending
412              the range of selected contents.
413
414       <<SelectNextWord>>
415              Move to the next group of items (i.e., visible word) in the cur‐
416              rent widget while extending the range of selected contents.
417
418       <<SelectNone>>
419              Reset the range of selected contents to be empty.
420
421       <<SelectPrevChar>>
422              Move  to the previous item (i.e., visible character) in the cur‐
423              rent widget while extending the range of selected contents.
424
425       <<SelectPrevLine>>
426              Move to the previous line in the current widget while  extending
427              the range of selected contents.
428
429       <<SelectPrevPara>>
430              Move  to  the  previous  paragraph  in  the current widget while
431              extending the range of selected contents.
432
433       <<SelectPrevWord>>
434              Move to the previous group of items (i.e., visible word) in  the
435              current widget while extending the range of selected contents.
436
437       <<ToggleSelection>>
438              Toggle the selection.
439
440       <<Undo>>
441              Undo the last action.
442

EXAMPLES

444   MAPPING KEYS TO VIRTUAL EVENTS
445       In  order  for a virtual event binding to trigger, two things must hap‐
446       pen.  First, the virtual event must be defined with the event add  com‐
447       mand.  Second, a binding must be created for the virtual event with the
448       bind command.  Consider the following virtual event definitions:
449
450              event add <<Paste>> <Control-y>
451              event add <<Paste>> <Button-2>
452              event add <<Save>> <Control-X><Control-S>
453              event add <<Save>> <Shift-F12>
454              if {[tk windowingsystem] eq "aqua"} {
455                  event add <<Save>> <Command-s>
456              }
457
458       In the bind command, a virtual  event  can  be  bound  like  any  other
459       builtin event type as follows:
460
461              bind Entry <<Paste>> {%W insert [selection get]}
462
463       The  double  angle brackets are used to specify that a virtual event is
464       being bound.  If the user types Control-y or presses button 2, or if  a
465       <<Paste>>  virtual  event  is synthesized with event generate, then the
466       <<Paste>> binding will be invoked.
467
468       If a virtual binding has the exact same sequence as a separate physical
469       binding,  then the physical binding will take precedence.  Consider the
470       following example:
471
472              event add <<Paste>> <Control-y> <Meta-Control-y>
473              bind Entry <Control-y> {puts Control-y}
474              bind Entry <<Paste>> {puts Paste}
475
476       When the user types Control-y the <Control-y> binding will be  invoked,
477       because  a  physical  event  is considered more specific than a virtual
478       event, all other things being equal.   However,  when  the  user  types
479       Meta-Control-y  the <<Paste>> binding will be invoked, because the Meta
480       modifier in the physical pattern associated with the virtual binding is
481       more specific than the <Control-y> sequence for the physical event.
482
483       Bindings  on  a  virtual  event may be created before the virtual event
484       exists.  Indeed, the virtual event never actually needs to be  defined,
485       for  instance,  on  platforms where the specific virtual event would be
486       meaningless or ungeneratable.
487
488       When a definition of a virtual event changes at run time,  all  windows
489       will respond immediately to the new definition.  Starting from the pre‐
490       ceding example, if the following code is executed:
491
492              bind Entry <Control-y> {}
493              event add <<Paste>> <Key-F6>
494
495       the behavior will  change  such  in  two  ways.   First,  the  shadowed
496       <<Paste>>  binding will emerge.  Typing Control-y will no longer invoke
497       the  <Control-y>  binding,  but  instead  invoke  the   virtual   event
498       <<Paste>>.   Second,  pressing  the  F6  key  will  now also invoke the
499       <<Paste>> binding.
500
501   MOVING THE MOUSE POINTER
502       Sometimes it is useful to be able to really move the mouse pointer. For
503       example,  if  you  have  some software that is capable of demonstrating
504       directly to the user how to use the program. To do this,  you  need  to
505       “warp” the mouse around by using event generate, like this:
506
507              for {set xy 0} {$xy < 200} {incr xy} {
508                  event generate . <Motion> -x $xy -y $xy -warp 1
509                  update
510                  after 50
511              }
512
513       Note  that it is usually considered bad style to move the mouse pointer
514       for the user because it removes control from them. Therefore this tech‐
515       nique  should be used with caution. Also note that it is not guaranteed
516       to function on all platforms.
517

SEE ALSO

519       bind(n)
520

KEYWORDS

522       event, binding, define, handle, virtual event
523
524
525
526Tk                                    8.3                             event(n)
Impressum