doc/bind.n

   1 '\"
   2 '\" Copyright (c) 1990 The Regents of the University of California.
   3 '\" Copyright (c) 1994 Sun Microsystems, Inc.
   4 '\" Copyright (c) 1996-1999 Christian Werner
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution
   7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 '\"
   9 .so man.macros
  10 .TH bind n 8.0 Ck "Ck Built-In Commands"
  11 .BS
  12 '\" Note:  do not modify the .SH NAME line immediately below!
  13 .SH NAME
  14 bind \- Arrange for events to invoke Tcl scripts
  15 .SH SYNOPSIS
  16 \fBbind\fI tag\fR
  17 .br
  18 \fBbind\fI tag sequence\fR
  19 .br
  20 \fBbind\fI tag sequence script\fR
  21 .br
  22 \fBbind\fI tag sequence \fB+\fIscript\fR
  23 .BE
  24
  25 .SH INTRODUCTION
  26 .PP
  27 The \fBbind\fR command associates Tcl scripts with events.
  28 If all three arguments are specified, \fBbind\fR will
  29 arrange for \fIscript\fR (a Tcl script) to be evaluated whenever
  30 the event(s) given by \fIsequence\fR occur in the window(s)
  31 identified by \fItag\fR.
  32 If \fIscript\fR is prefixed with a ``+'', then it is appended to
  33 any existing binding for \fIsequence\fR;  otherwise \fIscript\fR replaces
  34 any existing binding.
  35 If \fIscript\fR is an empty string then the current binding for
  36 \fIsequence\fR is destroyed, leaving \fIsequence\fR unbound.
  37 In all of the cases where a \fIscript\fR argument is provided,
  38 \fBbind\fR returns an empty string.
  39 .PP
  40 If \fIsequence\fR is specified without a \fIscript\fR, then the
  41 script currently bound to \fIsequence\fR is returned, or
  42 an empty string is returned if there is no binding for \fIsequence\fR.
  43 If neither \fIsequence\fR nor \fIscript\fR is specified, then the
  44 return value is a list whose elements are all the sequences
  45 for which there exist bindings for \fItag\fR.
  46 .PP
  47 The \fItag\fR argument determines which window(s) the binding applies to.
  48 If \fItag\fR begins with a dot, as in \fB.a.b.c\fR, then it must
  49 be the path name for a window; otherwise it may be an arbitrary
  50 string.
  51 Each window has an associated list of tags, and a binding applies
  52 to a particular window if its tag is among those specified for
  53 the window.
  54 Although the \fBbindtags\fR command may be used to assign an
  55 arbitrary set of binding tags to a window, the default binding
  56 tags provide the following behavior:
  57 .IP
  58 If a tag is the name of an internal window the binding applies
  59 to that window.
  60 .IP
  61 If the tag is the name of a toplevel window the binding applies
  62 to the toplevel window and all its internal windows.
  63 .IP
  64 If the tag is the name of a class of widgets, such as \fBButton\fR,
  65 the binding applies to all widgets in that class;
  66 .IP
  67 If \fItag\fR has the value \fBall\fR,
  68 the binding applies to all windows in the application.
  69
  70 .SH "EVENT PATTERNS"
  71 .PP
  72 The \fIsequence\fR argument specifies a sequence of one or more
  73 event patterns, with optional white space between the patterns.  Each
  74 event pattern may
  75 take either of two forms.  In the simplest case it is a single
  76 printing ASCII character, such as \fBa\fR or \fB[\fR.  The character
  77 may not be a space character or the character \fB<\fR.  This form of
  78 pattern matches a \fBKeyPress\fR event for the particular
  79 character.  The second form of pattern is longer but more general.
  80 It has the following syntax:
  81 .DS C
  82 \fB<\fItype-detail\fB>\fR
  83 .DE
  84 The entire event pattern is surrounded by angle brackets.
  85 Inside the angle brackets are an event
  86 type, and an extra piece of information (\fIdetail\fR) identifying
  87 a particular button or keysym. Any of the fields may be omitted,
  88 as long as at least one of \fItype\fR and \fIdetail\fR is present.
  89 The fields must be separated by white space or dashes.
  90
  91 .SH "EVENT TYPES"
  92 .LP
  93 The \fItype\fR field may be any of the following list.
  94 Where two names appear together, they are synonyms.
  95 .DS C
  96 .ta 5c 10c
  97 \fB
  98 BarCode Expose  Map
  99 ButtonPress, Button     FocusIn Unmap
 100 ButtonRelease   FocusOut
 101 Destroy KeyPress, Key, Control\fR
 102 .DE
 103 .LP
 104 The last part of a long event specification is \fIdetail\fR.  In the
 105 case of a \fBButtonPress\fR or \fBButtonRelease\fR event, it is the
 106 number of a button (1-5).  If a button number is given, then only an
 107 event on that particular button will match;  if no button number is
 108 given, then an event on any button will match.  Note:  giving a
 109 specific button number is different than specifying a button modifier;
 110 in the first case, it refers to a button being pressed or released,
 111 while in the second it refers to some other button that is already
 112 depressed when the matching event occurs.  If a button
 113 number is given then \fItype\fR may be omitted:  if will default
 114 to \fBButtonPress\fR.  For example, the specifier \fB<1>\fR
 115 is equivalent to \fB<ButtonPress-1>\fR.
 116 .LP
 117 If the event type is \fBKeyPress\fR, \fBKey\fR or \fBControl\fR, then
 118 \fIdetail\fR may be specified in the form of a keysym.  Keysyms
 119 are textual specifications for particular keys on the keyboard;
 120 they include all the alphanumeric ASCII characters (e.g. ``a'' is
 121 the keysym for the ASCII character ``a''), plus descriptions for
 122 non-alphanumeric characters (``comma'' is the keysym for the comma
 123 character), plus descriptions for some of the non-ASCII keys on the
 124 keyboard (e.g. ``F1'' is the keysym for the F1 function key, if it exists).
 125 The complete list of keysyms is not presented here;  it is
 126 available by invoking the \fBcurses haskey\fR Tcl command and may vary
 127 from system to system.
 128 If necessary, you can use the \fB%K\fR notation described below
 129 to print out the keysym name for a particular key.
 130 If a keysym \fIdetail\fR is given, then the
 131 \fItype\fR field may be omitted;  it will default to \fBKeyPress\fR.
 132 For example, \fB<KeyPress-comma>\fR is equivalent to
 133 \fB<comma>\fR.
 134
 135 .SH "BINDING SCRIPTS AND SUBSTITUTIONS"
 136 .LP
 137 The \fIscript\fR argument to \fBbind\fR is a Tcl script,
 138 which will be executed whenever the given event sequence occurs.
 139 \fICommand\fR will be executed in the same interpreter that the
 140 \fBbind\fR command was executed in, and it will run at global
 141 level (only global variables will be accessible).
 142 If \fIscript\fR contains
 143 any \fB%\fR characters, then the script will not be
 144 executed directly.  Instead, a new script will be
 145 generated by replacing each \fB%\fR, and the character following
 146 it, with information from the current event.  The replacement
 147 depends on the character following the \fB%\fR, as defined in the
 148 list below.  Unless otherwise indicated, the
 149 replacement string is the decimal value of the given field from
 150 the current event.
 151 Some of the substitutions are only valid for
 152 certain types of events;  if they are used for other types of events
 153 the value substituted is undefined.
 154 .TP
 155 \fB%%\fR
 156 Replaced with a single percent.
 157 .TP
 158 \fB%b\fR
 159 The number of the button that was pressed or released.  Valid only
 160 for \fBButtonPress\fR and \fBButtonRelease\fR events.
 161 .TP
 162 \fB%k\fR
 163 The \fIkeycode\fR field from the event.  Valid only for \fBKeyPress\fR
 164 and \fBKeyRelease\fR events.
 165 .TP
 166 \fB%x\fR
 167 The \fIx\fR coordinate (window coordinate system)
 168 from \fBButtonPress\fR and \fBButtonRelease\fR events.
 169 .TP
 170 \fB%y\fR
 171 The \fIy\fR coordinate (window coordinate system)
 172 from \fBButtonPress\fR and \fBButtonRelease\fR events.
 173 .TP
 174 \fB%A\fR
 175 For \fBKeyPress\fR events, substitutes the ASCII character corresponding to
 176 the event, or the empty string if the event doesn't correspond to an ASCII
 177 character (e.g. the shift key was pressed).
 178 For \fBBarCode\fR events, substitutes the entire barcode data packet.
 179 .TP
 180 \fB%K\fR
 181 The keysym corresponding to the event, substituted as a textual
 182 string. Valid only for \fBKeyPress\fR events.
 183 .TP
 184 \fB%N\fR
 185 The keysym corresponding to the event, substituted as
 186 a decimal number. Valid only for \fBKeyPress\fR events.
 187 .TP
 188 \fB%W\fR
 189 The path name of the window to which the event was reported (the
 190 \fIwindow\fR field from the event).  Valid for all event types.
 191 .TP
 192 \fB%X\fR
 193 The \fIx\fR coordinate (screen coordinate system)
 194 from \fBButtonPress\fR and \fBButtonRelease\fR events.
 195 .TP
 196 \fB%Y\fR
 197 The \fIy\fR coordinate (screen coordinate system)
 198 from \fBButtonPress\fR and \fBButtonRelease\fR events.
 199 .LP
 200 The replacement string for a %-replacement is formatted as a proper
 201 Tcl list element.
 202 This means that it will be surrounded with braces
 203 if it contains spaces, or special characters such as \fB$\fR and
 204 \fB{\fR may be preceded by backslashes.
 205 This guarantees that the string will be passed through the Tcl
 206 parser when the binding script is evaluated.
 207 Most replacements are numbers or well-defined strings such
 208 as \fBcomma\fR;  for these replacements no special formatting
 209 is ever necessary.
 210 The most common case where reformatting occurs is for the \fB%A\fR
 211 substitution.  For example, if \fIscript\fR is
 212 .DS
 213 \fBinsert\0%A\fR
 214 .DE
 215 and the character typed is an open square bracket, then the script
 216 actually executed will be
 217 .DS
 218 \fBinsert\0\e[\fR
 219 .DE
 220 This will cause the \fBinsert\fR to receive the original replacement
 221 string (open square bracket) as its first argument.
 222 If the extra backslash hadn't been added, Tcl would not have been
 223 able to parse the script correctly.
 224
 225 .SH MULTIPLE MATCHES
 226 .LP
 227 It is possible for several bindings to match a given event.
 228 If the bindings are associated with different \fItag\fR's,
 229 then each of the bindings will be executed, in order.
 230 By default, a class binding will be executed first, followed
 231 by a binding for the widget, a binding for its toplevel, and
 232 an \fBall\fR binding.
 233 The \fBbindtags\fR command may be used to change this order for
 234 a particular window or to associate additional binding tags with
 235 the window.
 236 .LP
 237 The \fBcontinue\fR and \fBbreak\fR commands may be used inside a
 238 binding script to control the processing of matching scripts.
 239 If \fBcontinue\fR is invoked, then the current binding script
 240 is terminated but Tk will continue processing binding scripts
 241 associated with other \fItag\fR's.
 242 If the \fBbreak\fR command is invoked within a binding script,
 243 then that script terminates and no other scripts will be invoked
 244 for the event.
 245 .LP
 246 If more than one binding matches a particular event and they
 247 have the same \fItag\fR, then the most specific binding
 248 is chosen and its script is evaluated.
 249 The following tests are applied, in order, to determine which of
 250 several matching sequences is more specific:
 251 (a) a longer sequence (in terms of number
 252 of events matched) is more specific than a shorter sequence;
 253 (b) an event pattern that specifies a specific button or key is more specific
 254 than one that doesn't.
 255 .LP
 256 If an event does not match any of the existing bindings, then the
 257 event is ignored.
 258 An unbound event is not considered to be an error.
 259
 260 .SH ERRORS
 261 .LP
 262 If an error occurs in executing the script for a binding then the
 263 \fBtkerror\fR mechanism is used to report the error.
 264 The \fBtkerror\fR command will be executed at global level
 265 (outside the context of any Tcl procedure).
 266
 267 .SH "SEE ALSO"
 268 tkerror
 269
 270 .SH KEYWORDS
 271 event, binding