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