bind(n)			     Ck Built-In Commands		       bind(n)



______________________________________________________________________________

NAME
       bind - Arrange for events to invoke Tcl scripts

SYNOPSIS
       bind tag
       bind tag sequence
       bind tag sequence script
       bind tag sequence +script
_________________________________________________________________


INTRODUCTION
       The  bind command associates Tcl scripts with events.  If all three ar-
       guments are specified, bind will arrange for script (a Tcl  script)  to
       be  evaluated whenever the event(s) given by sequence occur in the win-
       dow(s) identified by tag.  If script is prefixed with a ``+'', then  it
       is appended to any existing binding for sequence;  otherwise script re-
       places any existing binding.  If script is an  empty  string  then  the
       current	binding	 for  sequence is destroyed, leaving sequence unbound.
       In all of the cases where a script argument is provided,	 bind  returns
       an empty string.

       If  sequence  is	 specified without a script, then the script currently
       bound to sequence is returned, or an empty string is returned if	 there
       is  no  binding for sequence.  If neither sequence nor script is speci-
       fied, then the return value is a list whose elements are	 all  the  se-
       quences for which there exist bindings for tag.

       The tag argument determines which window(s) the binding applies to.  If
       tag begins with a dot, as in .a.b.c, 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 bind-
       tags command 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 Button,
	      the binding applies to all widgets in that class;

	      If tag has the value all, the binding applies to all windows  in
	      the application.


EVENT PATTERNS
       The  sequence  argument	specifies a sequence of one or more event pat-
       terns, with optional white space between the patterns.  Each event pat-
       tern may take either of two forms.  In the simplest case it is a single
       printing ASCII character, such as a or [.  The character may not	 be  a
       space  character	 or  the  character <.	This form of pattern matches a
       KeyPress event for the particular character.  The second form  of  pat-
       tern  is	 longer but more general.  It has the following syntax: <type-
       detail> The entire event pattern is surrounded by angle brackets.   In-
       side the angle brackets are an event type, and an extra piece of infor-
       mation (detail) identifying a particular button or keysym. Any  of  the
       fields  may  be	omitted, as long as at least one of type and detail is
       present.	 The fields must be separated by white space or dashes.


EVENT TYPES
       The type field may be any of the following list.	 Where two  names  ap-
       pear    together,    they    are	  synonyms.    BarCode		   Ex-
       pose		Map ButtonPress, Button FocusIn		   Unmap  But-
       tonRelease	FocusOut Destroy	     KeyPress, Key, Control

       The  last part of a long event specification is detail.	In the case of
       a ButtonPress or ButtonRelease event, it is  the	 number	 of  a	button
       (1-5).  If a button number is given, then only an event on that partic-
       ular button will match;	if no button number is given, then an event on
       any  button will match.	Note:  giving a specific button number is dif-
       ferent 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 oc-
       curs.   If  a button number is given then type may be omitted:  if will
       default to ButtonPress.	For example, the specifier <1>	is  equivalent
       to <ButtonPress-1>.

       If the event type is KeyPress, Key or Control, then detail may be spec-
       ified in the form of a 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 some of  the
       non-ASCII  keys	on  the keyboard (e.g. ``F1'' is the keysym for the F1
       function key, if it exists).  The complete list of keysyms is not  pre-
       sented here;  it is available by invoking the curses haskey Tcl command
       and may vary from system to system.  If necessary, you can use  the  %K
       notation	 described below to print out the keysym name for a particular
       key.  If a keysym detail is given, then the type field may be  omitted;
       it  will default to KeyPress.  For example, <KeyPress-comma> is equiva-
       lent to <comma>.


BINDING SCRIPTS AND SUBSTITUTIONS
       The script argument to bind is a Tcl script,  which  will  be  executed
       whenever	 the given event sequence occurs.  Command will be executed in
       the same interpreter that the bind command was executed in, and it will
       run  at	global	level  (only global variables will be accessible).  If
       script contains any % characters, then the script will not be  executed
       directly.  Instead, a new script will be generated by replacing each %,
       and the character following  it,	 with  information  from  the  current
       event.	The  replacement  depends on the character following the %, 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 un-
       defined.

       %%     Replaced with a single percent.

       %b     The number of the button that was pressed	 or  released.	 Valid
	      only for ButtonPress and ButtonRelease events.

       %k     The  keycode  field from the event.  Valid only for KeyPress and
	      KeyRelease events.

       %x     The x coordinate (window coordinate system) from ButtonPress and
	      ButtonRelease events.

       %y     The y coordinate (window coordinate system) from ButtonPress and
	      ButtonRelease events.

       %A     For KeyPress events, substitutes the ASCII character correspond-
	      ing  to the event, or the empty string if the event doesn't cor-
	      respond to an ASCII character (e.g. the shift key was  pressed).
	      For BarCode events, substitutes the entire barcode data packet.

       %K     The  keysym corresponding to the event, substituted as a textual
	      string. Valid only for KeyPress events.

       %N     The keysym corresponding to the event, substituted as a  decimal
	      number. Valid only for KeyPress events.

       %W     The path name of the window to which the event was reported (the
	      window field from the event).  Valid for all event types.

       %X     The x coordinate (screen coordinate system) from ButtonPress and
	      ButtonRelease events.

       %Y     The y coordinate (screen coordinate system) from ButtonPress and
	      ButtonRelease events.

       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 $ and { 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 comma;  for these replace-
       ments no special formatting is ever necessary.  The  most  common  case
       where  reformatting occurs is for the %A substitution.  For example, if
       script is insert %A and the character typed is an open square  bracket,
       then the script actually executed will be insert \[ This will cause the
       insert 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.


MULTIPLE MATCHES
       It is possible for several bindings to match a  given  event.   If  the
       bindings are associated with different tag's, then each of the bindings
       will be executed, in order.  By default, a class binding will  be  exe-
       cuted  first,  followed	by a binding for the widget, a binding for its
       toplevel, and an all binding.  The bindtags  command  may  be  used  to
       change  this  order  for a particular window or to associate additional
       binding tags with the window.

       The continue and break commands may be used inside a binding script  to
       control	the  processing	 of matching scripts.  If continue is invoked,
       then the current binding script is terminated but Tk will continue pro-
       cessing binding scripts associated with other tag's.  If the break com-
       mand is invoked within a binding script, then  that  script  terminates
       and no other scripts will be invoked for the event.

       If  more	 than one binding matches a particular event and they have the
       same tag, 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  se-
       quence  (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.

       If an event does not match any of the existing bindings, then the event
       is ignored.  An unbound event is not considered to be an error.


ERRORS
       If an error occurs in executing the script for a binding then the tker-
       ror mechanism is used to report the error.  The tkerror command will be
       executed at global level (outside the context of any Tcl procedure).


SEE ALSO
       tkerror


KEYWORDS
       event, binding



Ck				      8.0			       bind(n)
