diff options
Diffstat (limited to 'Master/tlpkg/tlperl/site/lib/Tk/bind.pod')
| -rw-r--r-- | Master/tlpkg/tlperl/site/lib/Tk/bind.pod | 583 |
1 files changed, 583 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/site/lib/Tk/bind.pod b/Master/tlpkg/tlperl/site/lib/Tk/bind.pod new file mode 100644 index 00000000000..f595a48e318 --- /dev/null +++ b/Master/tlpkg/tlperl/site/lib/Tk/bind.pod @@ -0,0 +1,583 @@ +# Copyright (c) 1990 The Regents of the University of California. +# Copyright (c) 1994-1996 Sun Microsystems, Inc. +# See the file "license.terms" for information on usage and redistribution +# of this file, and for a DISCLAIMER OF ALL WARRANTIES. +# +# + +=head1 NAME + +Tk::bind - Arrange for X events to invoke callbacks + +=for category Binding Events and Callbacks + +=head1 SYNOPSIS + +Retrieve bindings: + +S< >I<$widget>-E<gt>B<bind> + +S< >I<$widget>-E<gt>B<bind>(I<tag>) + +S< >I<$widget>-E<gt>B<bind>(I<sequence>) + +S< >I<$widget>-E<gt>B<bind>(I<tag>,I<sequence>) + +Associate and destroy bindings: + +S< >I<$widget>-E<gt>B<bind>(I<sequence>,I<callback>) + +S< >I<$widget>-E<gt>B<bind>(I<tag>,I<sequence>,I<callback>) + +=head1 DESCRIPTION + +The B<bind> method associates callbacks with X events. +If I<callback> is specified, B<bind> will +arrange for I<callback> to be evaluated whenever +the event(s) given by I<sequence> occur in the window(s) +identified by I<$widget> or I<tag>. +If I<callback> is an empty string then the current binding for +I<sequence> is destroyed, leaving I<sequence> unbound. +In all of the cases where a I<callback> argument is provided, +B<bind> returns an empty string. + +If I<sequence> is specified without a I<callback>, then the +callback currently bound to I<sequence> is returned, or +B<undef> is returned if there is no binding for I<sequence>. +If neither I<sequence> nor I<callback> is specified, then the +return value is a list whose elements are all the sequences +for which there exist bindings for I<tag>. + +If no I<tag> is specified then the B<bind> refers to I<$widget>. +If I<tag> is specified then it is typically a class name and the B<bind> +refers to all instances of the class on the B<MainWindow> associated +with I<$widget>. (It is possible for I<tag> to be another "widget object" +but this practice is deprecated.) Perl's B<ref>(I<$object>) can be used +to get the class name of any object. +Each window has an associated list of tags, and a binding applies +to a particular window if its tag is among those specified for +the window. +Although the B<bindtags> method may be used to assign an +arbitrary set of binding tags to a window, the default binding +tags provide the following behavior: + +If a tag is the name of an internal window the binding applies +to that window. + +If the tag is the name of a toplevel window the binding applies +to the toplevel window and all its internal windows. + +If the tag is the name of a class of widgets, such as B<Tk::Button>, +the binding applies to all widgets in that class; + +If I<tag> has the value B<all>, +the binding applies to all windows descended from the MainWindow +of the application. + +=head1 EVENT PATTERNS + +The I<sequence> argument specifies a sequence of one or more event +patterns, with optional white space between the patterns. Each event +pat may take one of three forms. In the simplest case it is a single +printing ASCII character, such as B<a> or B<[>. The character may not +be a space character or the character <. This form of pattern matches +a B<KeyPress> event for the particular character. The second form of +pattern is longer but more general. It has the following syntax: + +S< >'<modifier-modifier-type-detail>' + +The entire event pattern is surrounded by angle brackets, and normally +needs to be quoted, as angle brackets are special to perl. +Inside the angle brackets are zero or more modifiers, an event +type, and an extra piece of information (I<detail>) identifying +a particular button or keysym. Any of the fields may be omitted, +as long as at least one of I<type> and I<detail> is present. +The fields must be separated by white space or dashes. + +The third form of pattern is used to specify a user-defined, named virtual +event; see L<Tk::event> for details. It has the following syntax: + +S< >'<<name>>' + +The entire virtual event pattern is surrounded by double angle brackets. +Inside the angle brackets is the user-defined name of the virtual event. +Modifiers, such as B<Shift> or B<Control>, may not be combined with a +virtual event to modify it. Bindings on a virtual event may be created +before the virtual event is defined, and if the definition of a virtual +event changes dynamically, all windows bound to that virtual event will +respond immediately to the new definition. + +=head1 MODIFIERS + +Modifiers consist of any of the following values: + + Control Mod2, M2 + Shift Mod3, M3 + Lock Mod4, M4 + Button1, B1 Mod5, M5 + Button2, B2 Meta, M + Button3, B3 Alt + Button4, B4 Double + Button5, B5 Triple + Mod1, M1 Quadruple + +Where more than one value is listed, separated by commas, the values +are equivalent. +Most of the modifiers have the obvious X meanings. +For example, B<Button1> requires that +button 1 be depressed when the event occurs. +For a binding to match a given event, the modifiers in the event +must include all of those specified in the event pattern. +An event may also contain additional modifiers not specified in +the binding. +For example, if button 1 is pressed while the shift and control keys +are down, the pattern B<E<lt>Control-Button-1E<gt>> will match +the event, but B<E<lt>Mod1-Button-1E<gt>> will not. +If no modifiers are specified, then any combination of modifiers may +be present in the event. + +B<Meta> and B<M> refer to whichever of the +B<M1> through B<M5> modifiers is associated with the meta +key(s) on the keyboard (keysyms B<Meta_R> and B<Meta_L>). +If there are no meta keys, or if they are not associated with any +modifiers, then B<Meta> and B<M> will not match any events. +Similarly, the B<Alt> modifier refers to whichever modifier +is associated with the alt key(s) on the keyboard (keysyms +B<Alt_L> and B<Alt_R>). + +The B<Double>, B<Triple> and B<Quadruple> modifiers are a convenience +for specifying double mouse clicks and other repeated events. They +cause a particular event pattern to be repeated 2, 3 or 4 times, and +also place a time and space requirement on the sequence: for a +sequence of events to match a B<Double>, B<Triple> or B<Quadruple> +pattern, all of the events must occur close together in time and +without substantial mouse motion in between. For example, +B<E<lt>Double-Button-1E<gt>> is equivalent to +B<E<lt>Button-1E<gt>E<lt>Button-1E<gt>> with the extra time and space +requirement. + +=head1 EVENT TYPES + +The I<type> field may be any of the standard X event types, with a +few extra abbreviations. Below is a list of all the valid types; +where two names appear together, they are synonyms. + + + Activate Destroy Map + ButtonPress, Button Enter MapRequest + ButtonRelease Expose Motion + Circulate FocusIn MouseWheel + CirculateRequest FocusOut Property + Colormap Gravity Reparent + Configure KeyPress, Key ResizeRequest + ConfigureRequest KeyRelease Unmap + Create Leave Visibility + Deactivate + +Most of the above events have the same fields and behaviors as events +in the X Windowing system. You can find more detailed descriptions of +these events in any X window programming book. A couple of the events +are extensions to the X event system to support features unique to the +Macintosh and Windows platforms. We provide a little more detail on +these events here. These include: + + Activate + Deactivate + +These two events are sent to every sub-window of a toplevel when they +change state. In addition to the focus Window, the Macintosh platform +and Windows platforms have a notion of an active window (which often +has but is not required to have the focus). On the Macintosh, widgets +in the active window have a different appearance than widgets in +deactive windows. The Activate event is sent to all the sub-windows +in a toplevel when it changes from being deactive to active. +Likewise, the Deactive event is sent when the window's state changes +from active to deactive. There are no use- ful percent substitutions +you would make when binding to these events. + + MouseWheel + +Some mice on the Windows platform support a mouse wheel which is +used for scrolling documents without using the scrollbars. By +rolling the wheel, the system will generate MouseWheel events that +the application can use to scroll. Like Key events the event is +always routed to the window that currently has focus. When the +event is received you can use the %D substitution to get the delta +field for the event which is a integer value of motion that the +mouse wheel has moved. The smallest value for which the system +will report is defined by the OS. On Windows 95 & 98 machines +this value is at least 120 before it is reported. However, higher +resolution devices may be available in the future. The sign of +the value determines which direction your widget should scroll. +Positive values should scroll up and negative values should scroll +down. + +The last part of a long event specification is I<detail>. In the +case of a B<ButtonPress> or B<ButtonRelease> event, it is the +number of a button (1-5). If a button number is given, then only an +event on that particular button will match; if no button number is +given, then an event on any button will match. Note: giving a +specific button number is different than specifying a button modifier; +in the first case, it refers to a button being pressed or released, +while in the second it refers to some other button that is already +depressed when the matching event occurs. If a button +number is given then I<type> may be omitted: if will default +to B<ButtonPress>. For example, the specifier B<E<lt>1E<gt>> +is equivalent to B<E<lt>ButtonPress-1E<gt>>. + +If the event type is B<KeyPress> or B<KeyRelease>, then +I<detail> may be specified in the form of an X keysym. Keysyms +are textual specifications for particular keys on the keyboard; +they include all the alphanumeric ASCII characters (e.g. ``a'' is +the keysym for the ASCII character ``a''), plus descriptions for +non-alphanumeric characters (``comma'' is the keysym for the comma +character), plus descriptions for all the non-ASCII keys on the +keyboard (``Shift_L'' is the keysm for the left shift key, and +``F1'' is the keysym for the F1 function key, if it exists). The +complete list of keysyms is not presented here; it is +available in other X documentation and may vary from system to +system. +If necessary, you can use the B<'K'> notation described below +to print out the keysym name for a particular key. +If a keysym I<detail> is given, then the +I<type> field may be omitted; it will default to B<KeyPress>. +For example, B<E<lt>Control-commaE<gt>> is equivalent to +B<E<lt>Control-KeyPress-commaE<gt>>. + +=head1 BINDING CALLBACKS AND SUBSTITUTIONS + +The I<callback> argument to B<bind> is a perl/Tk callback. +which will be executed whenever the given event sequence occurs. +(See L<Tk::callbacks> for description of the possible forms.) +I<Callback> will be associated with the same B<MainWindow> +that is associated with the I<$widget> that was used to invoke +the B<bind> method, and it will run as though called from B<MainLoop>. +If I<callback> contains +any B<Ev>(I<%>) calls, then each "nested" B<Ev>(I<%>) +"callback" will be evaluated when the event occurs to form arguments +to be passed to the main I<callback>. +The replacement +depends on the character I<%>, as defined in the +list below. Unless otherwise indicated, the +replacement string is the numeric (decimal) value of the given field from +the current event. Perl/Tk has enhanced this mechanism slightly compared +to the comparable Tcl/Tk mechanism. The enhancements are not yet all +reflected in the list below. +Some of the substitutions are only valid for +certain types of events; if they are used for other types of events +the value substituted is undefined (not the same as B<undef>!). + +=over 4 + +=item B<'#'> + +The number of the last client request processed by the server +(the I<serial> field from the event). Valid for all event +types. + +=item B<'a'> + +The I<above> field from the event, +formatted as a hexadecimal number. +Valid only for B<Configure> events. + +=item B<'b'> + +The number of the button that was pressed or released. Valid only +for B<ButtonPress> and B<ButtonRelease> events. + +=item B<'c'> + +The I<count> field from the event. Valid only for B<Expose> events. + +=item B<'d'> + +The I<detail> field from the event. The B<'d'> is replaced by +a string identifying the detail. For B<Enter>, +B<Leave>, B<FocusIn>, and B<FocusOut> events, +the string will be one of the following: + + NotifyAncestor NotifyNonlinearVirtual + NotifyDetailNone NotifyPointer + NotifyInferior NotifyPointerRoot + NotifyNonlinear NotifyVirtual + +For B<ConfigureRequest> events, the string will be one of: + + Above Opposite + Below None + BottomIf TopIf + +For events other than these, the substituted string is undefined. +(Note that this is I<not> the same as Detail part of sequence +use to specify the event.) + +=item B<'f'> + +The I<focus> field from the event (B<0> or B<1>). Valid only +for B<Enter> and B<Leave> events. + +=item B<'h'> + +The I<height> field from the event. Valid only for B<Configure>, +B<ConfigureRequest>, B<Create>, B<Expose>, and B<ResizeRequest> events. + +=item B<'i'> + +The window field from the event, represented as a hexadecimal integer. + +=item B<'k'> + +The I<keycode> field from the event. Valid only for B<KeyPress> +and B<KeyRelease> events. + +=item B<'m'> + +The I<mode> field from the event. The substituted string is one of +B<NotifyNormal>, B<NotifyGrab>, B<NotifyUngrab>, or +B<NotifyWhileGrabbed>. Valid only for B<Enter>, +B<FocusIn>, B<FocusOut>, and B<Leave> events. + +=item B<'o'> + +The I<override_redirect> field from the event. Valid only for +B<Map>, B<Reparent>, and B<Configure> events. + +=item B<'p'> + +The I<place> field from the event, substituted as one of the +strings B<PlaceOnTop> or B<PlaceOnBottom>. Valid only +for B<Circulate> and B<CirculateRequest> events. + +=item B<'s'> + +The I<state> field from the event. For B<ButtonPress>, +B<ButtonRelease>, B<Enter>, B<KeyPress>, B<KeyRelease>, +B<Leave>, and B<Motion> events, a decimal string +is substituted. For B<Visibility>, one of the strings +B<VisibilityUnobscured>, B<VisibilityPartiallyObscured>, +and B<VisibilityFullyObscured> is substituted. + +=item B<'t'> + +The I<time> field from the event. Valid only for events that +contain a I<time> field. + +=item B<'w'> + +The I<width> field from the event. Valid only for B<Configure>, +B<ConfigueRequest>, B<Create>, B<Expose>, and B<ResizeREquest> events. + +=item B<'x'> + +The I<x> field from the event. Valid only for events containing +an I<x> field. + +=item B<'y'> + +The I<y> field from the event. Valid only for events containing +a I<y> field. + +=item B<'@'> + +The string "@I<x,y>" where I<x> and I<y> are as above. +Valid only for events containing I<x> and I<y> fields. +This format is used my methods of B<Tk::Text> and similar widgets. + +=item B<'A'> + +Substitutes the UNICODE character corresponding to the event, or +the empty string if the event doesn't correspond to a UNICODE character +(e.g. the shift key was pressed). B<XmbLookupString> does all the +work of translating from the event to a UNICODE character. +Valid only for B<KeyPress> and B<KeyRelease> events. + +=item B<'B'> + +The I<border_width> field from the event. Valid only for +B<Configure>, B<ConfigureRequest> and B<Create> events. + +=item B<'D'> + +This reports the delta value of a B<MouseWheel> event. The delta +value represents the rotation units the mouse wheel has been +moved. On Windows 95 & 98 systems the smallest value for the +delta is 120. Future systems may support higher resolution values +for the delta. The sign of the value represents the direction the +mouse wheel was scrolled. + +=item B<'E'> + +The I<send_event> field from the event. Valid for all event types. + +=item B<'K'> + +The keysym corresponding to the event, substituted as a textual +string. Valid only for B<KeyPress> and B<KeyRelease> events. + +=item B<'N'> + +The keysym corresponding to the event, substituted as +a decimal +number. Valid only for B<KeyPress> and B<KeyRelease> events. + +=item B<'R'> + +The I<root> window identifier from the event. Valid only for +events containing a I<root> field. + +=item B<'S'> + +The I<subwindow> window identifier from the event, +as an object if it is one otherwise as a hexadecimal number. +Valid only for events containing a I<subwindow> field. + +=item B<'T'> + +The I<type> field from the event. Valid for all event types. + +=item B<'W'> + +The window to which the event was reported (the +$widget field from the event) - as an perl/Tk object. +Valid for all event types. + +=item B<'X'> + +The I<x_root> field from the event. +If a virtual-root window manager is being used then the substituted +value is the corresponding x-coordinate in the virtual root. +Valid only for +B<ButtonPress>, B<ButtonRelease>, B<KeyPress>, B<KeyRelease>, +and B<Motion> events. + +=item B<'Y'> + +The I<y_root> field from the event. +If a virtual-root window manager is being used then the substituted +value is the corresponding y-coordinate in the virtual root. +Valid only for +B<ButtonPress>, B<ButtonRelease>, B<KeyPress>, B<KeyRelease>, +and B<Motion> events. + +=back + +=head1 MULTIPLE MATCHES + +It is possible for several bindings to match a given X event. +If the bindings are associated with different I<tag>'s, +then each of the bindings will be executed, in order. +By default, a class binding will be executed first, followed +by a binding for the widget, a binding for its toplevel, and +an B<all> binding. +The B<bindtags> method may be used to change this order for +a particular window or to associate additional binding tags with +the window. + +B<return> and B<Tk-E<gt>break> may be used inside a +callback to control the processing of matching callbacks. +If B<return> is invoked, then the current callback +is terminated but Tk will continue processing callbacks +associated with other I<tag>'s. +If B<Tk-E<gt>break> is invoked within a callback, +then that callback terminates and no other callbacks will be invoked +for the event. +(B<Tk-E<gt>break> is implemented via perl's B<die> with a special value +which is "caught" by the perl/Tk "glue" code.) + +If more than one binding matches a particular event and they +have the same I<tag>, then the most specific binding +is chosen and its callback is evaluated. +The following tests are applied, in order, to determine which of +several matching sequences is more specific: +(a) an event pattern that specifies a specific button or key is more specific +than one that doesn't; +(b) a longer sequence (in terms of number +of events matched) is more specific than a shorter sequence; +(c) if the modifiers specified in one pattern are a subset of the +modifiers in another pattern, then the pattern with more modifiers +is more specific. +(d) a virtual event whose physical pattern matches the sequence is less +specific than the same physical pattern that is not associated with a +virtual event. +(e) given a sequence that matches two or more virtual events, one +of the virtual events will be chosen, but the order is undefined. + +If the matching sequences contain more than one event, then tests +(c)-(e) are applied in order from the most recent event to the least recent +event in the sequences. If these tests fail to determine a winner, then the +most recently registered sequence is the winner. + +If there are two (or more) virtual events that are both triggered by the +same sequence, and both of those virtual events are bound to the same window +tag, then only one of the virtual events will be triggered, and it will +be picked at random: + + $widget->eventAdd('<<Paste>>' => '<Control-y>'); + $widget->eventAdd('<<Paste>>' => '<Button-2>'); + $widget->eventAdd <<Scroll>>' => '<Button-2>'); + $widget->bind('Tk::Entry','<<Paste>>',sub { print 'Paste'}); + $widget->bind('Tk::Entry','<<Scroll>>', sub {print 'Scroll'}); + +If the user types Control-y, the B<E<lt>E<lt>PasteE<gt>E<gt>> binding +will be invoked, but if the user presses button 2 then one of +either the B<E<lt>E<lt>PasteE<gt>E<gt>> or the B<E<lt>E<lt>ScrollE<gt>E<gt>> bindings will +be invoked, but exactly which one gets invoked is undefined. + +If an X event does not match any of the existing bindings, then the +event is ignored. +An unbound event is not considered to be an error. + +=head1 MULTI-EVENT SEQUENCES AND IGNORED EVENTS + +When a I<sequence> specified in a B<bind> method contains +more than one event pattern, then its callback is executed whenever +the recent events (leading up to and including the current event) +match the given sequence. This means, for example, that if button 1 is +clicked repeatedly the sequence B<E<lt>Double-ButtonPress-1E<gt>> will match +each button press but the first. +If extraneous events that would prevent a match occur in the middle +of an event sequence then the extraneous events are +ignored unless they are B<KeyPress> or B<ButtonPress> events. +For example, B<E<lt>Double-ButtonPress-1E<gt>> will match a sequence of +presses of button 1, even though there will be B<ButtonRelease> +events (and possibly B<Motion> events) between the +B<ButtonPress> events. +Furthermore, a B<KeyPress> event may be preceded by any number +of other B<KeyPress> events for modifier keys without the +modifier keys preventing a match. +For example, the event sequence B<aB> will match a press of the +B<a> key, a release of the B<a> key, a press of the B<Shift> +key, and a press of the B<b> key: the press of B<Shift> is +ignored because it is a modifier key. +Finally, if several B<Motion> events occur in a row, only +the last one is used for purposes of matching binding sequences. + +=head1 ERRORS + +If an error occurs in executing the callback for a binding then the +B<Tk::Error> mechanism is used to report the error. +The B<Tk::Error> mechanism will be executed at same call level, +and associated with the same B<MainWindow> as +as the callback was invoked. + +=head1 CAVEATS + +Note that for the B<Canvas> widget, the call to B<bind> has to be +fully qualified. This is because there is already a bind method for +the B<Canvas> widget, which binds individual canvas tags. + +S< >I<$canvas>-E<gt>B<Tk::bind> + +=head1 SEE ALSO + +L<Tk::Error|Tk::Error> +L<Tk::callbacks|Tk::callbacks> +L<Tk::bindtags|Tk::bindtags> + +=head1 KEYWORDS + +Event, binding + +=cut + |