441 lines
		
	
	
		
			20 KiB
		
	
	
	
		
			HTML
		
	
	
	
			
		
		
	
	
			441 lines
		
	
	
		
			20 KiB
		
	
	
	
		
			HTML
		
	
	
	
<HTML><HEAD><TITLE>Tk Built-In Commands - bind manual page</TITLE></HEAD>
 | 
						||
<BR>
 | 
						||
<BODY bgcolor = #c3c3ff>
 | 
						||
<H2><IMG ALIGN=BOTTOM SRC="./Img/ManPageBlue.gif"> bind</H2>
 | 
						||
<I>Arrange for X events to invoke STk scripts</I><P><IMG ALIGN=TOP SRC="./Img/line-red.gif">
 | 
						||
<H3><A NAME="M2">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>
 | 
						||
<H3><A NAME="M3">INTRODUCTION</A></H3>
 | 
						||
The <B>bind</B> procedure associates STk scripts with X events.
 | 
						||
If all three arguments are specified, <B>bind</B> will
 | 
						||
arrange for <I>script</I> (a STk script) to be evaluated whenever
 | 
						||
the event(s) given by <I>sequence</I> occur in the window(s)
 | 
						||
identified by <I>tag</I>.
 | 
						||
If is specified for a given sequence, it replaces
 | 
						||
the previous 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 list.
 | 
						||
<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 list 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="./bindtags.n.html">bindtags</A></B> procedure may be used to assign an
 | 
						||
arbitrary set of binding tags to a window, the default binding
 | 
						||
tags provide the following behavior:
 | 
						||
<UL>
 | 
						||
<P>
 | 
						||
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="./button.n.html">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.
 | 
						||
 | 
						||
</UL>
 | 
						||
<H3><A NAME="M4">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="M5">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></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> and <B>Triple</B> modifiers are a convenience
 | 
						||
for specifying double mouse clicks and other repeated
 | 
						||
events. They cause a particular event pattern to be
 | 
						||
repeated 2 or 3 times, and also place a time and space requirement
 | 
						||
on the sequence:  for a sequence of events to match a <B>Double</B>
 | 
						||
or <B>Triple</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="M6">EVENT TYPES</A></H3>
 | 
						||
The <I>type</I> field may be any of the standard X event types, with a
 | 
						||
few extra abbreviations.  Below is a list of all the val%id types;
 | 
						||
where two names appear together, they are synonyms.
 | 
						||
<PRE><B>ButtonPress, Button	Expose	Map
 | 
						||
ButtonRelease	FocusIn	Motion
 | 
						||
Circulate	FocusOut	Property	
 | 
						||
Colormap	Gravity	Reparent
 | 
						||
Configure	KeyPress, Key	Unmap
 | 
						||
Destroy	KeyRelease	Visibility
 | 
						||
Enter	Leave	Activate
 | 
						||
Deactivate</B></PRE>
 | 
						||
<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> closure parameter 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="M7">BINDING SCRIPTS AND SUBSTITUTIONS</A></H3>
 | 
						||
The <I>script</I> argument to <B>bind</B> must be a closure, which will
 | 
						||
be executed whenever the given event sequence occurs. The closure can
 | 
						||
have parameters. Those parameters are one character symbols (with
 | 
						||
convention which are described below). Parameter list will be
 | 
						||
evaluated just before the script is fired. Note that some parameters
 | 
						||
are only valid for certain types of events; if they are used for other
 | 
						||
types of events the value substituted is undefined.
 | 
						||
 | 
						||
<P>
 | 
						||
<DL>
 | 
						||
<DT><A NAME="M8">{B%R}</A><DD>
 | 
						||
Replaced with a single percent.
 | 
						||
<P>
 | 
						||
<DT><A NAME="M9">{B#R}</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="M10">{BaR}</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="M11">{BbR}</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="M12">{BcR}</A><DD>
 | 
						||
The <I>count</I> field from the event.  Valid only for <B>Expose</B> events.
 | 
						||
<P>
 | 
						||
<DT><A NAME="M13">{BdR}</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:
 | 
						||
<P>
 | 
						||
<UL>
 | 
						||
<PRE><B>NotifyAncestor	NotifyNonlinearVirtual
 | 
						||
NotifyDetailNone	NotifyPointer
 | 
						||
NotifyInferior	NotifyPointerRoot
 | 
						||
NotifyNonlinear	NotifyVirtual</B></PRE>
 | 
						||
For events other than these, the substituted string is undefined.
 | 
						||
</UL>
 | 
						||
<DT><A NAME="M14">{BfR}</A><DD>
 | 
						||
The <I>focus</I> field from the event (<B>#f</B> or <B>#t</B>).  Valid only
 | 
						||
for <B>Enter</B> and <B>Leave</B> events.
 | 
						||
<P>
 | 
						||
<DT><A NAME="M15">{BhR}</A><DD>
 | 
						||
The <I>height</I> field from the event.  Valid only for <B>Configure</B> and
 | 
						||
<B>Expose</B> events.
 | 
						||
<P>
 | 
						||
<DT><A NAME="M16">{BkR}</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="M17">{BmR}</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="M18">{BoR}</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="M19">{BpR}</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="M20">{BsR}</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="M21">{BtR}</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="M22">{BwR}</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="M23">{BxR}</A><DD>
 | 
						||
The <I>x</I> field from the event.  Valid only for events containing
 | 
						||
an <I>x</I> field.
 | 
						||
<P>
 | 
						||
<DT><A NAME="M24">{ByR}</A><DD>
 | 
						||
The <I>y</I> field from the event.  Valid only for events containing
 | 
						||
a <I>y</I> field.
 | 
						||
<P>
 | 
						||
<DT><A NAME="M25">{BAR}</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="M26">{BBR}</A><DD>
 | 
						||
The <I>border_width</I> field from the event.  Valid only for
 | 
						||
<B>Configure</B> events.
 | 
						||
<P>
 | 
						||
<DT><A NAME="M27">{BER}</A><DD>
 | 
						||
The <I>send_event</I> field from the event.  Valid for all event types.
 | 
						||
<P>
 | 
						||
<DT><A NAME="M28">{BKR}</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="M29">{BNR}</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="M30">{BRR}</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="M31">{BSR}</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="M32">{BTR}</A><DD>
 | 
						||
The <I>type</I> field from the event.  Valid for all event types.
 | 
						||
<P>
 | 
						||
<DT><A NAME="M33">{BWR}</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="M34">{BXR}</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="M35">{BYR}</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 following example show how to display a message each time the l1 or l2 label is entered: 
 | 
						||
<PRE>(pack (label '.l1 :text "One"))
 | 
						||
(pack (label '.l2 :text "Two"))
 | 
						||
(let ((mess (lambda (|W| x y)
 | 
						||
              (format #t "Entering ~S x=~a y=~a\n" |W| x y))))
 | 
						||
  (bind .l1 "<Enter>" mess)
 | 
						||
  (bind .l2 "<Enter>" mess))</PRE>
 | 
						||
<B>Note the usage of the "|" convention for the symbol parameters which must be in left in
 | 
						||
upper-case.</B>
 | 
						||
 | 
						||
<H3><A NAME="M36">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="./bindtags.n.html">bindtags</A></B> procedure may be used to change this order for
 | 
						||
a particular window or to associate additional binding tags with
 | 
						||
the window.
 | 
						||
<P>
 | 
						||
If the binding procedure result is the symbol <B>break</B>, then 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) a longer sequence (in terms of number
 | 
						||
of events matched) is more specific than a shorter sequence;
 | 
						||
(b) an event pattern that specifies a specific button or key is more specific
 | 
						||
than one that doesn't;
 | 
						||
(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>>"  (lambda () (display "Paste\n")))
 | 
						||
(bind "Entry" "<<Scroll>>" (lambda () (display "Scroll\n")))</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.
 | 
						||
 | 
						||
<P>
 | 
						||
The following example illustrates how to use the <B>break</B> symbol to
 | 
						||
break a binding chain.
 | 
						||
<PRE>(pack (entry '.e))
 | 
						||
(bind .e "<KeyPress>" (lambda (|A|)
 | 
						||
                        (unless (string->number |A|) 'break)))</PRE>
 | 
						||
Bindings for the entry <B>.e</B> are executed before those for its
 | 
						||
class (i.e. <B><A HREF="./entry.n.html">Entry</A></B>). This allows us to filter the characters
 | 
						||
which are effectively passed to the <B>.e</B> widget. The test in this
 | 
						||
binding closure breaks the chain of bindings if the typed character is
 | 
						||
not a digit. Otherwise, the following binding, the one for the
 | 
						||
<B><A HREF="./entry.n.html">Entry</A></B> class, is executed and inserts the character typed (a
 | 
						||
digit).
 | 
						||
Consequently, the simple previous binding makes <B>.e</B> a
 | 
						||
controlled entry which only accepts integer numbers.
 | 
						||
 | 
						||
 | 
						||
<H3><A NAME="M37">MULTI-EVENT SEQUENCES AND IGNORED EVENTS</A></H3>
 | 
						||
When a <I>sequence</I> specified in a <B>bind</B> procedure 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="M38">ERRORS</A></H3>
 | 
						||
If an error occurs in executing the script for a binding then the
 | 
						||
<B>bgerror</B> mechanism is used to report the error.
 | 
						||
 | 
						||
<H3><A NAME="M39">SEE ALSO</A></H3>
 | 
						||
<B><A HREF="./bindtags.n.html">bindtags</A></B>, <B>tkerror</B>
 | 
						||
<P><IMG ALIGN=TOP SRC="./Img/line-red.gif"><P>
 | 
						||
<A HREF=./STk-hlp.html><IMG ALIGN=BOTTOM SRC="./Img/RefBookBlue.gif"> Back to the <B>STk</B> main page</A>
 | 
						||
</BODY></HTML>
 |