| 1 | # Copyright (c) 1996 Sun Microsystems, Inc. |
| 2 | # See the file "license.terms" for information on usage and redistribution |
| 3 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| 4 | # |
| 5 | # |
| 6 | |
| 7 | =head1 NAME |
| 8 | |
| 9 | Tk::event - Miscellaneous event facilities: define virtual events and generate events |
| 10 | |
| 11 | =for category Binding Events and Callbacks |
| 12 | |
| 13 | =head1 SYNOPSIS |
| 14 | |
| 15 | I<$widget>-E<gt>B<event>I<Action>(?I<arg, arg, ...>?); |
| 16 | |
| 17 | =head1 DESCRIPTION |
| 18 | |
| 19 | The B<event>I<Action> methods provides several facilities for dealing with |
| 20 | window system events, such as defining virtual events and synthesizing |
| 21 | events. Virtual events are shared by all widgets of the same |
| 22 | B<MainWindow>. Different L<MainWindow|Tk::MainWindow>s can have different |
| 23 | virtual event. |
| 24 | |
| 25 | The following methods are currently supported: |
| 26 | |
| 27 | =over 4 |
| 28 | |
| 29 | =item I<$widget>-E<gt>B<eventAdd>(B<'E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'>I<, sequence >?,I<sequence, ...>?) |
| 30 | |
| 31 | Associates the virtual event I<virtual> with the physical |
| 32 | event sequence(s) given by the I<sequence> arguments, so that |
| 33 | the virtual event will trigger whenever any one of the I<sequence>s |
| 34 | occurs. |
| 35 | I<Virtual> may be any string value and I<sequence> may have |
| 36 | any of the values allowed for the I<sequence> argument to the |
| 37 | L<bind|Tk::bind> method. |
| 38 | If I<virtual> is already defined, the new physical event sequences |
| 39 | add to the existing sequences for the event. |
| 40 | |
| 41 | =item I<$widget>-E<gt>B<eventDelete>(B<'E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'> ?,I<sequence,> I<sequence, ...>?) |
| 42 | |
| 43 | Deletes each of the I<sequence>s from those associated with |
| 44 | the virtual event given by I<virtual>. |
| 45 | I<Virtual> may be any string value and I<sequence> may have |
| 46 | any of the values allowed for the I<sequence> argument to the |
| 47 | L<bind|Tk::bind> method. |
| 48 | Any I<sequence>s not currently associated with I<virtual> |
| 49 | are ignored. |
| 50 | If no I<sequence> argument is provided, all physical event sequences |
| 51 | are removed for I<virtual>, so that the virtual event will not |
| 52 | trigger anymore. |
| 53 | |
| 54 | =item I<$widget>-E<gt>B<eventGenerate>(I<event> ?,I<option =E<gt> value, option =E<gt> value, ...>?) |
| 55 | |
| 56 | Generates a window event and arranges for it to be processed just as if |
| 57 | it had come from the window system. |
| 58 | I<$window> is a reference to the window for which the event |
| 59 | will be generated. |
| 60 | I<Event> provides a basic description of |
| 61 | the event, such as B<E<lt>Shift-Button-2E<gt>> or B<E<lt>E<lt>PasteE<gt>E<gt>>. |
| 62 | If I<Window> is empty the whole screen is meant, and coordinates |
| 63 | are relative to the screen. |
| 64 | I<Event> may have any of the forms allowed for the I<sequence> |
| 65 | argument of the L<bind|Tk::bind> method except that it must consist |
| 66 | of a single event pattern, not a sequence. |
| 67 | I<Option-value> pairs may be used to specify additional |
| 68 | attributes of the event, such as the x and y mouse position; |
| 69 | see L<"EVENT FIELDS"> below. If the B<-when> option is not specified, the |
| 70 | event is processed immediately: all of the handlers for the event |
| 71 | will complete before the B<eventGenerate> method returns. |
| 72 | If the B<-when> option is specified then it determines when the |
| 73 | event is processed. |
| 74 | |
| 75 | =item I<$widget>-E<gt>B<eventInfo>(?'B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'>?) |
| 76 | |
| 77 | Returns information about virtual events. |
| 78 | If the B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>> argument is omitted, the return value |
| 79 | is a list of all the virtual events that are currently defined. |
| 80 | If B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>> is specified then the return value is |
| 81 | a list whose elements are the physical event sequences currently |
| 82 | defined for the given virtual event; if the virtual event is |
| 83 | not defined then B<undef> is returned. |
| 84 | |
| 85 | =back |
| 86 | |
| 87 | =head1 EVENT FIELDS |
| 88 | |
| 89 | The following options are supported for the B<eventGenerate> |
| 90 | method. These correspond to the ``%'' expansions |
| 91 | allowed in binding callback for the L<bind|Tk::bind> method. |
| 92 | |
| 93 | =over 4 |
| 94 | |
| 95 | =item B<-above> => I<window> |
| 96 | |
| 97 | I<Window> specifies the I<above> field for the event, |
| 98 | either as a window path name or as an integer window id. |
| 99 | Valid for B<Configure> events. |
| 100 | Corresponds to the L<%a|Tk::bind/'a'> substitution for binding scripts. |
| 101 | |
| 102 | =item B<-borderwidth> => I<size> |
| 103 | |
| 104 | I<Size> must be a screen distance; it specifies the |
| 105 | I<border_width> field for the event. |
| 106 | Valid for B<Configure> events. |
| 107 | Corresponds to the L<%B|Tk::bind/'B'> substitution for binding scripts. |
| 108 | |
| 109 | =item B<-button> => I<number> |
| 110 | |
| 111 | I<Number> must be an integer; it specifies the I<detail> field |
| 112 | for a B<ButtonPress> or B<ButtonRelease> event, overriding |
| 113 | any button number provided in the base I<event> argument. |
| 114 | Corresponds to the L<%b|Tk::bind/'b'> substitution for binding scripts. |
| 115 | |
| 116 | =item B<-count> => I<number> |
| 117 | |
| 118 | I<Number> must be an integer; it specifies the I<count> field |
| 119 | for the event. Valid for B<Expose> events. |
| 120 | Corresponds to the L<%c|Tk::bind/'c'> substitution for binding scripts. |
| 121 | |
| 122 | =item B<-detail> => I<detail> |
| 123 | |
| 124 | I<Detail> specifies the I<detail> field for the event |
| 125 | and must be one of the following: |
| 126 | |
| 127 | =over 8 |
| 128 | |
| 129 | NotifyAncestor NotifyNonlinearVirtual |
| 130 | NotifyDetailNone NotifyPointer |
| 131 | NotifyInferior NotifyPointerRoot |
| 132 | NotifyNonlinear NotifyVirtual |
| 133 | |
| 134 | Valid for B<Enter>, B<Leave>, B<FocusIn> and |
| 135 | B<FocusOut> events. |
| 136 | Corresponds to the L<%d|Tk::bind/'d'> substitution for binding scripts. |
| 137 | |
| 138 | =back |
| 139 | |
| 140 | =item B<-focus>I< boolean> |
| 141 | |
| 142 | I<Boolean> must be a boolean value; it specifies the I<focus> |
| 143 | field for the event. |
| 144 | Valid for B<Enter> and B<Leave> events. |
| 145 | Corresponds to the L<%f|Tk::bind/'f'> substitution for binding scripts. |
| 146 | |
| 147 | =item B<-height>I< size> |
| 148 | |
| 149 | I<Size> must be a screen distance; it specifies the I<height> |
| 150 | field for the event. Valid for B<Configure> events. |
| 151 | Corresponds to the L<%h|Tk::bind/'h'> substitution for binding scripts. |
| 152 | |
| 153 | =item B<-keycode>I< number> |
| 154 | |
| 155 | I<Number> must be an integer; it specifies the I<keycode> |
| 156 | field for the event. |
| 157 | Valid for B<KeyPress> and B<KeyRelease> events. |
| 158 | Corresponds to the L<%k|Tk::bind/'k'> substitution for binding scripts. |
| 159 | |
| 160 | =item B<-keysym>I< name> |
| 161 | |
| 162 | I<Name> must be the name of a valid keysym, such as B<g>, |
| 163 | B<space>, or B<Return>; its corresponding |
| 164 | keycode value is used as the I<keycode> field for event, overriding |
| 165 | any detail specified in the base I<event> argument. |
| 166 | Valid for B<KeyPress> and B<KeyRelease> events. |
| 167 | Corresponds to the L<%K|Tk::bind/'K'> substitution for binding scripts. |
| 168 | |
| 169 | =item B<-mode>I< notify> |
| 170 | |
| 171 | I<Notify> specifies the I<mode> field for the event and must be |
| 172 | one of B<NotifyNormal>, B<NotifyGrab>, B<NotifyUngrab>, or |
| 173 | B<NotifyWhileGrabbed>. |
| 174 | Valid for B<Enter>, B<Leave>, B<FocusIn>, and |
| 175 | B<FocusOut> events. |
| 176 | Corresponds to the L<%m|Tk::bind/'m'> substitution for binding scripts. |
| 177 | |
| 178 | =item B<-override>I< boolean> |
| 179 | |
| 180 | I<Boolean> must be a boolean value; it specifies the |
| 181 | I<override_redirect> field for the event. |
| 182 | Valid for B<Map>, B<Reparent>, and B<Configure> events. |
| 183 | Corresponds to the L<%o|Tk::bind/'o'> substitution for binding scripts. |
| 184 | |
| 185 | =item B<-place>I< where> |
| 186 | |
| 187 | I<Where> specifies the I<place> field for the event; it must be |
| 188 | either B<PlaceOnTop> or B<PlaceOnBottom>. |
| 189 | Valid for B<Circulate> events. |
| 190 | Corresponds to the L<%p|Tk::bind/'p'> substitution for binding scripts. |
| 191 | |
| 192 | =item B<-root>I< window> |
| 193 | |
| 194 | I<Window> must be either a window path name or an integer window |
| 195 | identifier; it specifies the I<root> field for the event. |
| 196 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, |
| 197 | B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> |
| 198 | events. |
| 199 | Corresponds to the L<%R|Tk::bind/'R'> substitution for binding scripts. |
| 200 | |
| 201 | =item B<-rootx>I< coord> |
| 202 | |
| 203 | I<Coord> must be a screen distance; it specifies the I<x_root> |
| 204 | field for the event. |
| 205 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, |
| 206 | B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> |
| 207 | events. Corresponds to the L<%X|Tk::bind/'X'> substitution for binding scripts. |
| 208 | |
| 209 | =item B<-rooty>I< coord> |
| 210 | |
| 211 | I<Coord> must be a screen distance; it specifies the I<y_root> |
| 212 | field for the event. |
| 213 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, |
| 214 | B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> |
| 215 | events. |
| 216 | Corresponds to the L<%Y|Tk::bind/'Y'> substitution for binding scripts. |
| 217 | |
| 218 | =item B<-sendevent>I< boolean> |
| 219 | |
| 220 | B<Boolean> must be a boolean value; it specifies the I<send_event> |
| 221 | field for the event. Valid for all events. Corresponds to the |
| 222 | L<%E|Tk::bind/'E'> substitution for binding scripts. |
| 223 | |
| 224 | =item B<-serial>I< number> |
| 225 | |
| 226 | I<Number> must be an integer; it specifies the I<serial> field |
| 227 | for the event. Valid for all events. |
| 228 | Corresponds to the L<%#|Tk::bind/'#'> substitution for binding scripts. |
| 229 | |
| 230 | =item B<-state>I< state> |
| 231 | |
| 232 | I<State> specifies the I<state> field for the event. |
| 233 | For B<KeyPress>, B<KeyRelease>, B<ButtonPress>, |
| 234 | B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> events |
| 235 | it must be an integer value. |
| 236 | For B<Visibility> events it must be one of B<VisibilityUnobscured>, |
| 237 | B<VisibilityPartiallyObscured>, or B<VisibilityFullyObscured>. |
| 238 | This option overrides any modifiers such as B<Meta> or B<Control> |
| 239 | specified in the base I<event>. |
| 240 | Corresponds to the L<%s|Tk::bind/'s'> substitution for binding scripts. |
| 241 | |
| 242 | =item B<-subwindow>I< window> |
| 243 | |
| 244 | I<Window> specifies the I<subwindow> field for the event, either |
| 245 | as a path name for a Tk widget or as an integer window identifier. |
| 246 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, |
| 247 | B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> events. |
| 248 | Similar to L<%S|Tk::bind/'S'> substitution for binding scripts. |
| 249 | |
| 250 | =item B<-time>I< integer> |
| 251 | |
| 252 | I<Integer> must be an integer value; it specifies the I<time> field |
| 253 | for the event. |
| 254 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, |
| 255 | B<ButtonRelease>, B<Enter>, B<Leave>, B<Motion>, |
| 256 | and B<Property> events. |
| 257 | Corresponds to the L<%t|Tk::bind/'t'> substitution for binding scripts. |
| 258 | |
| 259 | |
| 260 | =item B<-warp>I< boolean> |
| 261 | |
| 262 | I<boolean> must be a boolean value; it specifies whether |
| 263 | the screen pointer should be warped as well. |
| 264 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, |
| 265 | B<ButtonRelease>, and B<Motion> events. |
| 266 | |
| 267 | =item B<-width>I< size> |
| 268 | |
| 269 | I<Size> must be a screen distance; it specifies the I<width> field |
| 270 | for the event. |
| 271 | Valid for B<Configure> events. |
| 272 | Corresponds to the L<%w|Tk::bind/'w'> substitution for binding scripts. |
| 273 | |
| 274 | =item B<-when>I< when> |
| 275 | |
| 276 | I<When> determines when the event will be processed; it must have one |
| 277 | of the following values: |
| 278 | |
| 279 | =over 8 |
| 280 | |
| 281 | =item B<now> |
| 282 | |
| 283 | Process the event immediately, before the command returns. |
| 284 | This also happens if the B<-when> option is omitted. |
| 285 | |
| 286 | =item B<tail> |
| 287 | |
| 288 | Place the event on perl/Tk's event queue behind any events already |
| 289 | queued for this application. |
| 290 | |
| 291 | =item B<head> |
| 292 | |
| 293 | Place the event at the front of perl/Tk's event queue, so that it |
| 294 | will be handled before any other events already queued. |
| 295 | |
| 296 | =item B<mark> |
| 297 | |
| 298 | Place the event at the front of perl/Tk's event queue but behind any |
| 299 | other events already queued with B<-when mark>. |
| 300 | This option is useful when generating a series of events that should |
| 301 | be processed in order but at the front of the queue. |
| 302 | |
| 303 | =back |
| 304 | |
| 305 | =item B<-x>I< coord> |
| 306 | |
| 307 | I<Coord> must be a screen distance; it specifies the I<x> field |
| 308 | for the event. |
| 309 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, |
| 310 | B<ButtonRelease>, B<Motion>, B<Enter>, B<Leave>, |
| 311 | B<Expose>, B<Configure>, B<Gravity>, and B<Reparent> |
| 312 | events. |
| 313 | Corresponds to the the L<%x|Tk::bind/'x'> substitution for binding scripts. |
| 314 | If I<Window> is empty the coordinate is relative to the |
| 315 | screen, and this option corresponds to the L<%X|Tk::bind/'X'> substitution |
| 316 | for binding scripts. |
| 317 | |
| 318 | =item B<-y>I< coord> |
| 319 | |
| 320 | I<Coord> must be a screen distance; it specifies the I<y> |
| 321 | field for the event. |
| 322 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, |
| 323 | B<ButtonRelease>, B<Motion>, B<Enter>, B<Leave>, |
| 324 | B<Expose>, B<Configure>, B<Gravity>, and B<Reparent> |
| 325 | events. |
| 326 | Corresponds to the the L<%y|Tk::bind/'y'> substitution for binding scripts. |
| 327 | If I<Window> is empty the coordinate is relative to the |
| 328 | screen, and this option corresponds to the L<%Y|Tk::bind/'Y'> substitution |
| 329 | for binding scripts. |
| 330 | |
| 331 | Any options that are not specified when generating an event are filled |
| 332 | with the value 0, except for I<serial>, which is filled with the |
| 333 | next X event serial number. |
| 334 | |
| 335 | =back |
| 336 | |
| 337 | =head1 VIRTUAL EVENT EXAMPLES |
| 338 | |
| 339 | In order for a virtual event binding to trigger, two things must |
| 340 | happen. First, the virtual event must be defined with the |
| 341 | B<eventAdd> method. Second, a binding must be created for |
| 342 | the virtual event with the B<bind> method. |
| 343 | Consider the following virtual event definitions: |
| 344 | |
| 345 | $widget->eventAdd('<<Paste>>' => '<Control-y>'); |
| 346 | $widget->eventAdd('<<Paste>>' => '<Button-2>'); |
| 347 | $widget->eventAdd('<<Save>>' => '<Control-X><Control-S>'); |
| 348 | $widget->eventAdd('<<Save>>' => '<Shift-F12>'); |
| 349 | |
| 350 | In the B<bind> method, a virtual event can be bound like any other |
| 351 | builtin event type as follows: |
| 352 | |
| 353 | $entry->bind('Tk::Entry', '<<Paste>>' => sub { |
| 354 | $entry->Insert($entry->selectionGet) }); |
| 355 | |
| 356 | The double angle brackets are used to specify that a virtual event is being |
| 357 | bound. If the user types Control-y or presses button 2, or if |
| 358 | a B<E<lt>E<lt>PasteE<gt>E<gt>> virtual event is synthesized with B<eventGenerate>, |
| 359 | then the B<E<lt>E<lt>PasteE<gt>E<gt>> binding will be invoked. |
| 360 | |
| 361 | If a virtual binding has the exact same sequence as a separate |
| 362 | physical binding, then the physical binding will take precedence. |
| 363 | Consider the following example: |
| 364 | |
| 365 | $mw->eventAdd('<<Paste>>' => '<Control-y>','<Meta-Control-y>'); |
| 366 | $mw->bind('Tk::Entry', '<Control-y>' => sub{print 'Control-y'}); |
| 367 | $mw->bind('Tk::Entry', '<<Paste>>' => sub{print 'Paste'}); |
| 368 | |
| 369 | When the user types Control-y the B<E<lt>Control-yE<gt>> binding |
| 370 | will be invoked, because a physical event is considered |
| 371 | more specific than a virtual event, all other things being equal. |
| 372 | However, when the user types Meta-Control-y the |
| 373 | B<E<lt>E<lt>PasteE<gt>E<gt>> binding will be invoked, because the |
| 374 | B<Meta> modifier in the physical pattern associated with the |
| 375 | virtual binding is more specific than the B<E<lt>Control-y>E<gt> sequence for |
| 376 | the physical event. |
| 377 | |
| 378 | Bindings on a virtual event may be created before the virtual event exists. |
| 379 | Indeed, the virtual event never actually needs to be defined, for instance, |
| 380 | on platforms where the specific virtual event would meaningless or |
| 381 | ungeneratable. |
| 382 | |
| 383 | When a definition of a virtual event changes at run time, all windows |
| 384 | will respond immediately to the new definition. |
| 385 | Starting from the preceding example, if the following code is executed: |
| 386 | |
| 387 | $entry->bind(ref($entry), '<Control-y>' => undef); |
| 388 | $entry->eventAdd('<<Paste>>' => '<Key-F6>'); |
| 389 | |
| 390 | the behavior will change such in two ways. First, the shadowed |
| 391 | B<E<lt>E<lt>PasteE<gt>E<gt>> binding will emerge. |
| 392 | Typing Control-y will no longer invoke the B<E<lt>Control-yE<gt>> binding, |
| 393 | but instead invoke the virtual event B<E<lt>E<lt>PasteE<gt>E<gt>>. Second, |
| 394 | pressing the F6 key will now also invoke the B<E<lt>E<lt>PasteE<gt>E<gt>> binding. |
| 395 | |
| 396 | =head1 SEE ALSO |
| 397 | |
| 398 | L<Tk::bind|Tk::bind> |
| 399 | L<Tk::callbacks|Tk::callbacks> |
| 400 | |
| 401 | =head1 KEYWORDS |
| 402 | |
| 403 | event, binding, define, handle, virtual event |
| 404 | |
| 405 | =cut |
| 406 | |