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
       arguments 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
       replaces 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
       sequences 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.
       Inside  the  angle  brackets  are  an event type, and an extra piece of
       information (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
       appear	    together,	    they       are	 synonyms.	  Bar-
       Code		Expose		   Map	      ButtonPress,	  But-
       ton FocusIn	      Unmap		  ButtonRelease	      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
       occurs.	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
       undefined.

       %%     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
       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.

       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)
