diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/bind.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/bind.pod | 583 |
1 files changed, 0 insertions, 583 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/bind.pod b/Master/tlpkg/tlperl/lib/Tk/bind.pod deleted file mode 100644 index f595a48e318..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/bind.pod +++ /dev/null @@ -1,583 +0,0 @@ -# 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 - |