526 lines
26 KiB
HTML
526 lines
26 KiB
HTML
<HTML><HEAD><TITLE>Tk Built-In Commands - bind manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="bind.htm#M2" NAME="L51">NAME</A>
|
|
<DL><DD>bind - Arrange for X events to invoke Tcl scripts</DL>
|
|
<DD><A HREF="bind.htm#M3" NAME="L52">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>bind</B><I> tag</I>
|
|
<DD><B>bind</B><I> tag sequence</I>
|
|
<DD><B>bind</B><I> tag sequence script</I>
|
|
<DD><B>bind</B><I> tag sequence </I><B>+</B><I>script</I>
|
|
</DL>
|
|
<DD><A HREF="bind.htm#M4" NAME="L53">INTRODUCTION</A>
|
|
<DD><A HREF="bind.htm#M5" NAME="L54">EVENT PATTERNS</A>
|
|
<DD><A HREF="bind.htm#M6" NAME="L55">MODIFIERS</A>
|
|
<DD><A HREF="bind.htm#M7" NAME="L56">EVENT TYPES</A>
|
|
<DL>
|
|
<DD><A HREF="bind.htm#M8" NAME="L57"><B>Activate</B></A>
|
|
<DD><A HREF="bind.htm#M9" NAME="L58"><B>Deactivate</B></A>
|
|
<DD><A HREF="bind.htm#M10" NAME="L59"><B>MouseWheel</B></A>
|
|
</DL>
|
|
<DD><A HREF="bind.htm#M11" NAME="L60">BINDING SCRIPTS AND SUBSTITUTIONS</A>
|
|
<DL>
|
|
<DD><A HREF="bind.htm#M12" NAME="L61"><B>%%</B></A>
|
|
<DD><A HREF="bind.htm#M13" NAME="L62"><B>%#</B></A>
|
|
<DD><A HREF="bind.htm#M14" NAME="L63"><B>%a</B></A>
|
|
<DD><A HREF="bind.htm#M15" NAME="L64"><B>%b</B></A>
|
|
<DD><A HREF="bind.htm#M16" NAME="L65"><B>%c</B></A>
|
|
<DD><A HREF="bind.htm#M17" NAME="L66"><B>%d</B></A>
|
|
<DD><A HREF="bind.htm#M18" NAME="L67"><B>%f</B></A>
|
|
<DD><A HREF="bind.htm#M19" NAME="L68"><B>%h</B></A>
|
|
<DD><A HREF="bind.htm#M20" NAME="L69"><B>%k</B></A>
|
|
<DD><A HREF="bind.htm#M21" NAME="L70"><B>%m</B></A>
|
|
<DD><A HREF="bind.htm#M22" NAME="L71"><B>%o</B></A>
|
|
<DD><A HREF="bind.htm#M23" NAME="L72"><B>%p</B></A>
|
|
<DD><A HREF="bind.htm#M24" NAME="L73"><B>%s</B></A>
|
|
<DD><A HREF="bind.htm#M25" NAME="L74"><B>%t</B></A>
|
|
<DD><A HREF="bind.htm#M26" NAME="L75"><B>%w</B></A>
|
|
<DD><A HREF="bind.htm#M27" NAME="L76"><B>%x</B></A>
|
|
<DD><A HREF="bind.htm#M28" NAME="L77"><B>%y</B></A>
|
|
<DD><A HREF="bind.htm#M29" NAME="L78"><B>%A</B></A>
|
|
<DD><A HREF="bind.htm#M30" NAME="L79"><B>%B</B></A>
|
|
<DD><A HREF="bind.htm#M31" NAME="L80"><B>%D</B></A>
|
|
<DD><A HREF="bind.htm#M32" NAME="L81"><B>%E</B></A>
|
|
<DD><A HREF="bind.htm#M33" NAME="L82"><B>%K</B></A>
|
|
<DD><A HREF="bind.htm#M34" NAME="L83"><B>%N</B></A>
|
|
<DD><A HREF="bind.htm#M35" NAME="L84"><B>%R</B></A>
|
|
<DD><A HREF="bind.htm#M36" NAME="L85"><B>%S</B></A>
|
|
<DD><A HREF="bind.htm#M37" NAME="L86"><B>%T</B></A>
|
|
<DD><A HREF="bind.htm#M38" NAME="L87"><B>%W</B></A>
|
|
<DD><A HREF="bind.htm#M39" NAME="L88"><B>%X</B></A>
|
|
<DD><A HREF="bind.htm#M40" NAME="L89"><B>%Y</B></A>
|
|
</DL>
|
|
<DD><A HREF="bind.htm#M41" NAME="L90">MULTIPLE MATCHES</A>
|
|
<DD><A HREF="bind.htm#M42" NAME="L91">MULTI-EVENT SEQUENCES AND IGNORED EVENTS</A>
|
|
<DD><A HREF="bind.htm#M43" NAME="L92">ERRORS</A>
|
|
<DD><A HREF="bind.htm#M44" NAME="L93">SEE ALSO</A>
|
|
<DD><A HREF="bind.htm#M45" NAME="L94">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
bind - Arrange for X events to invoke Tcl scripts
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>bind</B><I> tag</I><BR>
|
|
<B>bind</B><I> tag sequence</I><BR>
|
|
<B>bind</B><I> tag sequence script</I><BR>
|
|
<B>bind</B><I> tag sequence </I><B>+</B><I>script</I><BR>
|
|
<H3><A NAME="M4">INTRODUCTION</A></H3>
|
|
The <B>bind</B> command associates Tcl scripts with X events.
|
|
If all three arguments are specified, <B>bind</B> will
|
|
arrange for <I>script</I> (a Tcl script) to be evaluated whenever
|
|
the event(s) given by <I>sequence</I> occur in the window(s)
|
|
identified by <I>tag</I>.
|
|
If <I>script</I> is prefixed with a ``+'', then it is appended to
|
|
any existing binding for <I>sequence</I>; otherwise <I>script</I> replaces
|
|
any existing binding.
|
|
If <I>script</I> is an empty string then the current binding for
|
|
<I>sequence</I> is destroyed, leaving <I>sequence</I> unbound.
|
|
In all of the cases where a <I>script</I> argument is provided,
|
|
<B>bind</B> returns an empty string.
|
|
<P>
|
|
If <I>sequence</I> is specified without a <I>script</I>, then the
|
|
script currently bound to <I>sequence</I> is returned, or
|
|
an empty string is returned if there is no binding for <I>sequence</I>.
|
|
If neither <I>sequence</I> nor <I>script</I> is specified, then the
|
|
return value is a list whose elements are all the sequences
|
|
for which there exist bindings for <I>tag</I>.
|
|
<P>
|
|
The <I>tag</I> argument determines which window(s) the binding applies to.
|
|
If <I>tag</I> begins with a dot, as in <B>.a.b.c</B>, then it must
|
|
be the path name for a window; otherwise it may be an arbitrary
|
|
string.
|
|
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><A HREF="../TclCmd/bindtags.htm">bindtags</A></B> command may be used to assign an
|
|
arbitrary set of binding tags to a window, the default binding
|
|
tags provide the following behavior:
|
|
<DL><P><DD>
|
|
If a tag is the name of an internal window the binding applies
|
|
to that window.
|
|
<P>
|
|
If the tag is the name of a toplevel window the binding applies
|
|
to the toplevel window and all its internal windows.
|
|
<P>
|
|
If the tag is the name of a class of widgets, such as <B><A HREF="../TclCmd/button.htm">Button</A></B>,
|
|
the binding applies to all widgets in that class;
|
|
<P>
|
|
If <I>tag</I> has the value <B>all</B>,
|
|
the binding applies to all windows in the application.
|
|
|
|
</DL>
|
|
<H3><A NAME="M5">EVENT PATTERNS</A></H3>
|
|
The <I>sequence</I> argument specifies a sequence of one or more
|
|
event patterns, with optional white space between the patterns. Each
|
|
event pattern may
|
|
take one of three forms. In the simplest case it is a single
|
|
printing ASCII character, such as <B>a</B> or <B>[</B>. The character
|
|
may not be a space character or the character <B><</B>. This form of
|
|
pattern matches a <B>KeyPress</B> event for the particular
|
|
character. The second form of pattern is longer but more general.
|
|
It has the following syntax:
|
|
<PRE><B><</B><I>modifier-modifier-type-detail</I><B>></B></PRE>
|
|
The entire event pattern is surrounded by angle brackets.
|
|
Inside the angle brackets are zero or more modifiers, an event
|
|
type, and an extra piece of information (<I>detail</I>) identifying
|
|
a particular button or keysym. Any of the fields may be omitted,
|
|
as long as at least one of <I>type</I> and <I>detail</I> is present.
|
|
The fields must be separated by white space or dashes.
|
|
<P>
|
|
The third form of pattern is used to specify a user-defined, named virtual
|
|
event. It has the following syntax:
|
|
<PRE><B><<</B><I>name</I><B>>></B></PRE>
|
|
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</B> or <B>Control</B>, 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.
|
|
<H3><A NAME="M6">MODIFIERS</A></H3>
|
|
Modifiers consist of any of the following values:
|
|
<PRE><B>Control</B> <B>Mod2, M2</B>
|
|
<B>Shift</B> <B>Mod3, M3</B>
|
|
<B>Lock</B> <B>Mod4, M4</B>
|
|
<B>Button1, B1</B> <B>Mod5, M5</B>
|
|
<B>Button2, B2</B> <B>Meta, M</B>
|
|
<B>Button3, B3</B> <B>Alt</B>
|
|
<B>Button4, B4</B> <B>Double</B>
|
|
<B>Button5, B5</B> <B>Triple</B>
|
|
<B>Mod1, M1</B> <B>Quadruple</B></PRE>
|
|
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</B> 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><Control-Button-1></B> will match
|
|
the event, but <B><Mod1-Button-1></B> will not.
|
|
If no modifiers are specified, then any combination of modifiers may
|
|
be present in the event.
|
|
<P>
|
|
<B>Meta</B> and <B>M</B> refer to whichever of the
|
|
<B>M1</B> through <B>M5</B> modifiers is associated with the meta
|
|
key(s) on the keyboard (keysyms <B>Meta_R</B> and <B>Meta_L</B>).
|
|
If there are no meta keys, or if they are not associated with any
|
|
modifiers, then <B>Meta</B> and <B>M</B> will not match any events.
|
|
Similarly, the <B>Alt</B> modifier refers to whichever modifier
|
|
is associated with the alt key(s) on the keyboard (keysyms
|
|
<B>Alt_L</B> and <B>Alt_R</B>).
|
|
<P>
|
|
The <B>Double</B>, <B>Triple</B> and <B>Quadruple</B> 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>, <B>Triple</B> or <B>Quadruple</B>
|
|
pattern, all of the events must occur close together in time and without
|
|
substantial mouse motion in between. For example, <B><Double-Button-1></B>
|
|
is equivalent to <B><Button-1><Button-1></B> with the extra time and space
|
|
requirement.
|
|
|
|
<H3><A NAME="M7">EVENT TYPES</A></H3>
|
|
The <I>type</I> field may be any of the standard X event types, with a
|
|
few extra abbreviations. The <I>type</I> field will also accept a
|
|
couple non-standard X event types that were added to better support
|
|
the Macintosh and Windows platforms. Below is a list of all the valid
|
|
types; where two names appear together, they are synonyms.
|
|
<PRE><B>Activate Enter Map
|
|
ButtonPress, Button Expose Motion
|
|
ButtonRelease FocusIn MouseWheel
|
|
Circulate FocusOut Property
|
|
Colormap Gravity Reparent
|
|
Configure KeyPress, Key Unmap
|
|
Deactivate KeyRelease Visibility
|
|
Destroy Leave</B></PRE>
|
|
<P>
|
|
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:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M8"><B>Activate</B></A><DD>
|
|
<P><DT><A NAME="M9"><B>Deactivate</B></A><DD>
|
|
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 <B>Activate</B> event is sent to all the
|
|
sub-windows in a toplevel when it changes from being deactive to
|
|
active. Likewise, the <B>Deactive</B> event is sent when the window's
|
|
state changes from active to deactive. There are no useful percent
|
|
substitutions you would make when binding to these events.
|
|
<P><DT><A NAME="M10"><B>MouseWheel</B></A><DD>
|
|
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 <B>MouseWheel</B> events that the
|
|
application can use to scroll. Like <B>Key</B> events the event is
|
|
always routed to the window that currently has focus. When the event
|
|
is received you can use the <B>%D</B> substitution to get the
|
|
<I>delta</I> 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.
|
|
<P></DL>
|
|
<P>
|
|
The last part of a long event specification is <I>detail</I>. In the
|
|
case of a <B>ButtonPress</B> or <B>ButtonRelease</B> 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</I> may be omitted: if will default
|
|
to <B>ButtonPress</B>. For example, the specifier <B><1></B>
|
|
is equivalent to <B><ButtonPress-1></B>.
|
|
<P>
|
|
If the event type is <B>KeyPress</B> or <B>KeyRelease</B>, then
|
|
<I>detail</I> 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</B> notation described below
|
|
to print out the keysym name for a particular key.
|
|
If a keysym <I>detail</I> is given, then the
|
|
<I>type</I> field may be omitted; it will default to <B>KeyPress</B>.
|
|
For example, <B><Control-comma></B> is equivalent to
|
|
<B><Control-KeyPress-comma></B>.
|
|
|
|
<H3><A NAME="M11">BINDING SCRIPTS AND SUBSTITUTIONS</A></H3>
|
|
The <I>script</I> argument to <B>bind</B> is a Tcl script,
|
|
which will be executed whenever the given event sequence occurs.
|
|
<I>Command</I> will be executed in the same interpreter that the
|
|
<B>bind</B> command was executed in, and it will run at global
|
|
level (only global variables will be accessible).
|
|
If <I>script</I> contains
|
|
any <B>%</B> characters, then the script will not be
|
|
executed directly. Instead, a new script will be
|
|
generated by replacing each <B>%</B>, and the character following
|
|
it, with information from the current event. The replacement
|
|
depends on the character following the <B>%</B>, as defined in the
|
|
list below. Unless otherwise indicated, the
|
|
replacement string is the decimal value of the given field from
|
|
the current event.
|
|
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.
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M12"><B>%%</B></A><DD>
|
|
Replaced with a single percent.
|
|
<P><DT><A NAME="M13"><B>%#</B></A><DD>
|
|
The number of the last client request processed by the server
|
|
(the <I>serial</I> field from the event). Valid for all event
|
|
types.
|
|
<P><DT><A NAME="M14"><B>%a</B></A><DD>
|
|
The <I>above</I> field from the event,
|
|
formatted as a hexadecimal number.
|
|
Valid only for <B>Configure</B> events.
|
|
<P><DT><A NAME="M15"><B>%b</B></A><DD>
|
|
The number of the button that was pressed or released. Valid only
|
|
for <B>ButtonPress</B> and <B>ButtonRelease</B> events.
|
|
<P><DT><A NAME="M16"><B>%c</B></A><DD>
|
|
The <I>count</I> field from the event. Valid only for <B>Expose</B> events.
|
|
<P><DT><A NAME="M17"><B>%d</B></A><DD>
|
|
The <I>detail</I> field from the event. The <B>%d</B> is replaced by
|
|
a string identifying the detail. For <B>Enter</B>,
|
|
<B>Leave</B>, <B>FocusIn</B>, and <B>FocusOut</B> events,
|
|
the string will be one of the following:
|
|
<PRE><B>NotifyAncestor NotifyNonlinearVirtual
|
|
NotifyDetailNone NotifyPointer
|
|
NotifyInferior NotifyPointerRoot
|
|
NotifyNonlinear NotifyVirtual</B></PRE>
|
|
For events other than these, the substituted string is undefined.
|
|
<P><DT><A NAME="M18"><B>%f</B></A><DD>
|
|
The <I>focus</I> field from the event (<B>0</B> or <B>1</B>). Valid only
|
|
for <B>Enter</B> and <B>Leave</B> events.
|
|
<P><DT><A NAME="M19"><B>%h</B></A><DD>
|
|
The <I>height</I> field from the event. Valid for the <B>Configure</B> and
|
|
<B>Expose</B> events.
|
|
<P><DT><A NAME="M20"><B>%k</B></A><DD>
|
|
The <I>keycode</I> field from the event. Valid only for <B>KeyPress</B>
|
|
and <B>KeyRelease</B> events.
|
|
<P><DT><A NAME="M21"><B>%m</B></A><DD>
|
|
The <I>mode</I> field from the event. The substituted string is one of
|
|
<B>NotifyNormal</B>, <B>NotifyGrab</B>, <B>NotifyUngrab</B>, or
|
|
<B>NotifyWhileGrabbed</B>. Valid only for <B>Enter</B>,
|
|
<B>FocusIn</B>, <B>FocusOut</B>, and <B>Leave</B> events.
|
|
<P><DT><A NAME="M22"><B>%o</B></A><DD>
|
|
The <I>override_redirect</I> field from the event. Valid only for
|
|
<B>Map</B>, <B>Reparent</B>, and <B>Configure</B> events.
|
|
<P><DT><A NAME="M23"><B>%p</B></A><DD>
|
|
The <I>place</I> field from the event, substituted as one of the
|
|
strings <B>PlaceOnTop</B> or <B>PlaceOnBottom</B>. Valid only
|
|
for <B>Circulate</B> events.
|
|
<P><DT><A NAME="M24"><B>%s</B></A><DD>
|
|
The <I>state</I> field from the event. For <B>ButtonPress</B>,
|
|
<B>ButtonRelease</B>, <B>Enter</B>, <B>KeyPress</B>, <B>KeyRelease</B>,
|
|
<B>Leave</B>, and <B>Motion</B> events, a decimal string
|
|
is substituted. For <B>Visibility</B>, one of the strings
|
|
<B>VisibilityUnobscured</B>, <B>VisibilityPartiallyObscured</B>,
|
|
and <B>VisibilityFullyObscured</B> is substituted.
|
|
<P><DT><A NAME="M25"><B>%t</B></A><DD>
|
|
The <I>time</I> field from the event. Valid only for events that
|
|
contain a <I>time</I> field.
|
|
<P><DT><A NAME="M26"><B>%w</B></A><DD>
|
|
The <I>width</I> field from the event. Valid only for
|
|
<B>Configure</B> and <B>Expose</B> events.
|
|
<P><DT><A NAME="M27"><B>%x</B></A><DD>
|
|
The <I>x</I> field from the event. Valid only for events containing
|
|
an <I>x</I> field.
|
|
<P><DT><A NAME="M28"><B>%y</B></A><DD>
|
|
The <I>y</I> field from the event. Valid only for events containing
|
|
a <I>y</I> field.
|
|
<P><DT><A NAME="M29"><B>%A</B></A><DD>
|
|
Substitutes the ASCII character corresponding to the event, or
|
|
the empty string if the event doesn't correspond to an ASCII character
|
|
(e.g. the shift key was pressed). <B>XLookupString</B> does all the
|
|
work of translating from the event to an ASCII character.
|
|
Valid only for <B>KeyPress</B> and <B>KeyRelease</B> events.
|
|
<P><DT><A NAME="M30"><B>%B</B></A><DD>
|
|
The <I>border_width</I> field from the event. Valid only for
|
|
<B>Configure</B> events.
|
|
<P><DT><A NAME="M31"><B>%D</B></A><DD>
|
|
This reports the <I>delta</I> value of a <B>MouseWheel</B> event. The
|
|
<I>delta</I> 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.
|
|
<P><DT><A NAME="M32"><B>%E</B></A><DD>
|
|
The <I>send_event</I> field from the event. Valid for all event types.
|
|
<P><DT><A NAME="M33"><B>%K</B></A><DD>
|
|
The keysym corresponding to the event, substituted as a textual
|
|
string. Valid only for <B>KeyPress</B> and <B>KeyRelease</B> events.
|
|
<P><DT><A NAME="M34"><B>%N</B></A><DD>
|
|
The keysym corresponding to the event, substituted as a decimal
|
|
number. Valid only for <B>KeyPress</B> and <B>KeyRelease</B> events.
|
|
<P><DT><A NAME="M35"><B>%R</B></A><DD>
|
|
The <I>root</I> window identifier from the event. Valid only for
|
|
events containing a <I>root</I> field.
|
|
<P><DT><A NAME="M36"><B>%S</B></A><DD>
|
|
The <I>subwindow</I> window identifier from the event,
|
|
formatted as a hexadecimal number.
|
|
Valid only for events containing a <I>subwindow</I> field.
|
|
<P><DT><A NAME="M37"><B>%T</B></A><DD>
|
|
The <I>type</I> field from the event. Valid for all event types.
|
|
<P><DT><A NAME="M38"><B>%W</B></A><DD>
|
|
The path name of the window to which the event was reported (the
|
|
<I>window</I> field from the event). Valid for all event types.
|
|
<P><DT><A NAME="M39"><B>%X</B></A><DD>
|
|
The <I>x_root</I> 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>, <B>ButtonRelease</B>, <B>KeyPress</B>, <B>KeyRelease</B>,
|
|
and <B>Motion</B> events.
|
|
<P><DT><A NAME="M40"><B>%Y</B></A><DD>
|
|
The <I>y_root</I> 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>, <B>ButtonRelease</B>, <B>KeyPress</B>, <B>KeyRelease</B>,
|
|
and <B>Motion</B> events.
|
|
<P></DL>
|
|
<P>
|
|
The replacement string for a %-replacement is formatted as a proper
|
|
Tcl list element.
|
|
This means that it will be surrounded with braces
|
|
if it contains spaces, or special characters such as <B>$</B> and
|
|
<B>{</B> may be preceded by backslashes.
|
|
This guarantees that the string will be passed through the Tcl
|
|
parser when the binding script is evaluated.
|
|
Most replacements are numbers or well-defined strings such
|
|
as <B>Above</B>; for these replacements no special formatting
|
|
is ever necessary.
|
|
The most common case where reformatting occurs is for the <B>%A</B>
|
|
substitution. For example, if <I>script</I> is
|
|
<PRE><B>insert %A</B></PRE>
|
|
and the character typed is an open square bracket, then the script
|
|
actually executed will be
|
|
<PRE><B>insert \[</B></PRE>
|
|
This will cause the <B>insert</B> to receive the original replacement
|
|
string (open square bracket) as its first argument.
|
|
If the extra backslash hadn't been added, Tcl would not have been
|
|
able to parse the script correctly.
|
|
|
|
<H3><A NAME="M41">MULTIPLE MATCHES</A></H3>
|
|
It is possible for several bindings to match a given X event.
|
|
If the bindings are associated with different <I>tag</I>'s,
|
|
then each of the bindings will be executed, in order.
|
|
By default, a binding for the widget will be executed first, followed
|
|
by a class binding, a binding for its toplevel, and
|
|
an <B>all</B> binding.
|
|
The <B><A HREF="../TclCmd/bindtags.htm">bindtags</A></B> command may be used to change this order for
|
|
a particular window or to associate additional binding tags with
|
|
the window.
|
|
<P>
|
|
The <B><A HREF="../TkCmd/continue.htm">continue</A></B> and <B><A HREF="../TkCmd/break.htm">break</A></B> commands may be used inside a
|
|
binding script to control the processing of matching scripts.
|
|
If <B><A HREF="../TkCmd/continue.htm">continue</A></B> is invoked, then the current binding script
|
|
is terminated but Tk will continue processing binding scripts
|
|
associated with other <I>tag</I>'s.
|
|
If the <B><A HREF="../TkCmd/break.htm">break</A></B> command is invoked within a binding script,
|
|
then that script terminates and no other scripts will be invoked
|
|
for the event.
|
|
<P>
|
|
If more than one binding matches a particular event and they
|
|
have the same <I>tag</I>, then the most specific binding
|
|
is chosen and its script 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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
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:
|
|
<PRE>event add <<Paste>> <Control-y>
|
|
event add <<Paste>> <Button-2>
|
|
event add <<Scroll>> <Button-2>
|
|
bind Entry <<Paste>> {puts Paste}
|
|
bind Entry <<Scroll>> {puts Scroll}</PRE>
|
|
If the user types Control-y, the <B><<Paste>></B> binding
|
|
will be invoked, but if the user presses button 2 then one of
|
|
either the <B><<Paste>></B> or the <B><<Scroll>></B> bindings will
|
|
be invoked, but exactly which one gets invoked is undefined.
|
|
<P>
|
|
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.
|
|
|
|
<H3><A NAME="M42">MULTI-EVENT SEQUENCES AND IGNORED EVENTS</A></H3>
|
|
When a <I>sequence</I> specified in a <B>bind</B> command contains
|
|
more than one event pattern, then its script 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><Double-ButtonPress-1></B> 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</B> or <B>ButtonPress</B> events.
|
|
For example, <B><Double-ButtonPress-1></B> will match a sequence of
|
|
presses of button 1, even though there will be <B>ButtonRelease</B>
|
|
events (and possibly <B>Motion</B> events) between the
|
|
<B>ButtonPress</B> events.
|
|
Furthermore, a <B>KeyPress</B> event may be preceded by any number
|
|
of other <B>KeyPress</B> events for modifier keys without the
|
|
modifier keys preventing a match.
|
|
For example, the event sequence <B>aB</B> will match a press of the
|
|
<B>a</B> key, a release of the <B>a</B> key, a press of the <B>Shift</B>
|
|
key, and a press of the <B>b</B> key: the press of <B>Shift</B> is
|
|
ignored because it is a modifier key.
|
|
Finally, if several <B>Motion</B> events occur in a row, only
|
|
the last one is used for purposes of matching binding sequences.
|
|
|
|
<H3><A NAME="M43">ERRORS</A></H3>
|
|
If an error occurs in executing the script for a binding then the
|
|
<B><A HREF="../TkCmd/bgerror.htm">bgerror</A></B> mechanism is used to report the error.
|
|
The <B><A HREF="../TkCmd/bgerror.htm">bgerror</A></B> command will be executed at global level
|
|
(outside the context of any Tcl procedure).
|
|
|
|
<H3><A NAME="M44">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/bgerror.htm">bgerror</A></B>, <B><A HREF="../TclCmd/keysyms.htm">keysyms</A></B>
|
|
<H3><A NAME="M45">KEYWORDS</A></H3>
|
|
<A href="../Keywords/F.htm#form">form</A>, <A href="../Keywords/M.htm#manual">manual</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1990 The Regents of the University of California.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1998 by Scriptics Corporation.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|