Unix/Linux Go Back    


RedHat 9 (Linux i386) - man page for bind (redhat section n)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

_________________________________________________________________________________________________

NAME
       bind - Arrange for X 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 X events.	If all three arguments are speci-
       fied, bind will arrange for script (a Tcl script) to be evaluated  whenever  the  event(s)
       given  by sequence occur in the window(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 argu-
       ment 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 specified, 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 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 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 pattern is longer but more gen-
       eral.  It has the following syntax:
	      <modifier-modifier-type-detail>
       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 (detail) identi-
       fying 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.											  |

       The third form of pattern is used to specify a user-defined, named virtual event.  It  has |
       the following syntax:									  |
	      <<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 Shift or  Con- |
       trol,  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 immedi- |
       ately to the new definition.

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  But-
       ton4,  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, 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 <Control-Button-1> will
       match the event, but <Mod1-Button-1> will not.  If no modifiers are  specified,	then  any
       combination of modifiers may be present in the event.

       Meta  and  M refer to whichever of the M1 through M5 modifiers is associated with the meta
       key(s) on the keyboard (keysyms Meta_R and Meta_L).  If there are no meta keys, or if they
       are  not  associated with any modifiers, then Meta and M will not match any events.  Simi-
       larly, the Alt modifier refers to whichever modifier is associated with the alt key(s)  on
       the keyboard (keysyms Alt_L and Alt_R).

       The  Double,  Triple and 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 Double, Triple or Quadruple pattern, all of  the  events  must  occur
       close  together	in  time  and  without substantial mouse motion in between.  For example,
       <Double-Button-1> is equivalent to <Button-1><Button-1> with  the  extra  time  and  space
       requirement.

EVENT TYPES
       The  type  field may be any of the standard X event types, with a few extra abbreviations.
       The type 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.     Acti-
       vate	       Enter		  Map  ButtonPress, Button Expose	      Motion But- |
       tonRelease	FocusIn 	   MouseWheel			Circulate	    Focu-
       sOut	      Property	     Colormap		 Gravity	    Reparent	  Config-
       ure	     KeyPress,	   KeyUnmap	Deactivate	    KeyRelease	       Visibility
       Destroy		   Leave

       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  program- |
       ming  book.   A	couple of the events are extensions to the X event system to support fea- |
       tures 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  wid- |
	    gets  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 useful |
	    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 gener- |
	    ate 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 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 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 differ-
       ent 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 or KeyRelease, then 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  key-
       board  (``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 %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, <Control-comma> is equivalent to <Control-KeyPress-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.

       %#   The  number of the last client request processed by the server (the serial field from
	    the event).  Valid for all event types.

       %a   The above field from the event, formatted as a hexadecimal number.	 Valid	only  for
	    Configure events.

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

       %c   The count field from the event.  Valid only for Expose events.

       %d   The detail field from the event.  The %d is replaced  by  a  string  identifying  the
	    detail.   For  Enter,  Leave, FocusIn, and FocusOut events, the string will be one of
	    the following:
	    NotifyAncestor	    NotifyNonlinearVirtual  NotifyDetailNone	    NotifyPointer
	    NotifyInferior	    NotifyPointerRoot  NotifyNonlinear	       NotifyVirtual  For
	    events other than these, the substituted string is undefined.

       %f   The focus field from the event (0 or 1).  Valid only for Enter and Leave events.

       %h   The height field from the event.  Valid for the Configure and Expose events.	  |

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

       %m   The mode field from the event.  The substituted string is one of NotifyNormal,  Noti-
	    fyGrab,  NotifyUngrab,  or	NotifyWhileGrabbed.  Valid only for Enter, FocusIn, Focu- |
	    sOut, and Leave events.

       %o   The override_redirect field from the event.  Valid only for Map, Reparent,	and  Con-
	    figure events.

       %p   The  place	field  from  the  event,  substituted as one of the strings PlaceOnTop or
	    PlaceOnBottom.  Valid only for Circulate events.

       %s   The state field from the event.  For  ButtonPress,	ButtonRelease,	Enter,	KeyPress,
	    KeyRelease,  Leave, and Motion events, a decimal string is substituted.  For Visibil-
	    ity, one of the strings VisibilityUnobscured, VisibilityPartiallyObscured, and  Visi-
	    bilityFullyObscured is substituted.

       %t   The time field from the event.  Valid only for events that contain a time field.

       %w   The width field from the event.  Valid only for Configure and Expose events.	  |

       %x   The x field from the event.  Valid only for events containing an x field.

       %y   The y field from the event.  Valid only for events containing a y field.

       %A   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).
	    XLookupString  does all the work of translating from the event to an ASCII character.
	    Valid only for KeyPress and KeyRelease events.

       %B   The border_width field from the event.  Valid only for Configure events.		  |

       %D											  |
	    This reports the delta value of a MouseWheel event.  The delta value  represents  the |
	    rotation units the mouse wheel has been moved.  On Windows 95 & 98 systems the small- |
	    est 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.

       %E   The send_event field from the event.  Valid for all event types.

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

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

       %R   The root window identifier from the event.	Valid only for events containing  a  root
	    field.

       %S   The  subwindow  window  identifier from the event, formatted as a hexadecimal number.
	    Valid only for events containing a subwindow field.

       %T   The type field from the event.  Valid for all event types.

       %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_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 ButtonPress, ButtonRelease, KeyPress, KeyRelease, and Motion events.

       %Y   The 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 ButtonPress, ButtonRelease, KeyPress, KeyRelease, and Motion 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  char-
       acters  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 replace-
       ments  are  numbers or well-defined strings such as Above;  for these replacements no spe-
       cial 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 X event.  If the bindings are associ-
       ated  with  different  tag'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 all binding.  The bindtags command may be used to change
       this order for a particular window or to associate additional binding tags with	the  win-
       dow.

       The  continue  and  break commands may be used inside a binding script to control the pro-
       cessing of matching scripts.  If continue is invoked, then the current binding  script  is
       terminated  but	Tk  will continue processing binding scripts associated with other tag's.
       If the break command 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) |
       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 win- |
       ner.											  |

       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:			  |
	      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}						  |
       If the user types Control-y, the <<Paste>> binding  will  be  invoked,  but  if	the  user |
       presses	button	2  then  one  of  either the <<Paste>> or the <<Scroll>> 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.

MULTI-EVENT SEQUENCES AND IGNORED EVENTS
       When a sequence specified in a bind 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 <Double-ButtonPress-1> 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  KeyPress  or  ButtonPress  events.
       For  example,  <Double-ButtonPress-1>  will  match a sequence of presses of button 1, even
       though there will be ButtonRelease events (and possibly Motion events) between the Button-
       Press  events.	Furthermore, a KeyPress event may be preceded by any number of other Key-
       Press events for modifier keys without the modifier keys preventing a match.  For example,
       the  event sequence aB will match a press of the a key, a release of the a key, a press of
       the Shift key, and a press of the b key:  the press of Shift is ignored because	it  is	a
       modifier key.  Finally, if several Motion events occur in a row, only the last one is used
       for purposes of matching binding sequences.

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

SEE ALSO
       bgerror, keysyms

KEYWORDS
       form, manual

Tk					       8.0					  bind(n)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 07:09 PM.