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, 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
-