OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [tk/] [doc/] [bind.n] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
'\"
2
'\" Copyright (c) 1990 The Regents of the University of California.
3
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
4
'\" Copyright (c) 1998 by Scriptics Corporation.
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
'\" RCS: @(#) $Id: bind.n,v 1.1.1.1 2002-01-16 10:25:48 markom Exp $
10
'\"
11
.so man.macros
12
.TH bind n 8.0 Tk "Tk Built-In Commands"
13
.BS
14
'\" Note:  do not modify the .SH NAME line immediately below!
15
.SH NAME
16
bind \- Arrange for X events to invoke Tcl scripts
17
.SH SYNOPSIS
18
\fBbind\fI tag\fR
19
.sp
20
\fBbind\fI tag sequence\fR
21
.sp
22
\fBbind\fI tag sequence script\fR
23
.sp
24
\fBbind\fI tag sequence \fB+\fIscript\fR
25
.BE
26
 
27
.SH INTRODUCTION
28
.PP
29
The \fBbind\fR command associates Tcl scripts with X events.
30
If all three arguments are specified, \fBbind\fR will
31
arrange for \fIscript\fR (a Tcl script) to be evaluated whenever
32
the event(s) given by \fIsequence\fR occur in the window(s)
33
identified by \fItag\fR.
34
If \fIscript\fR is prefixed with a ``+'', then it is appended to
35
any existing binding for \fIsequence\fR;  otherwise \fIscript\fR replaces
36
any existing binding.
37
If \fIscript\fR is an empty string then the current binding for
38
\fIsequence\fR is destroyed, leaving \fIsequence\fR unbound.
39
In all of the cases where a \fIscript\fR argument is provided,
40
\fBbind\fR returns an empty string.
41
.PP
42
If \fIsequence\fR is specified without a \fIscript\fR, then the
43
script currently bound to \fIsequence\fR is returned, or
44
an empty string is returned if there is no binding for \fIsequence\fR.
45
If neither \fIsequence\fR nor \fIscript\fR is specified, then the
46
return value is a list whose elements are all the sequences
47
for which there exist bindings for \fItag\fR.
48
.PP
49
The \fItag\fR argument determines which window(s) the binding applies to.
50
If \fItag\fR begins with a dot, as in \fB.a.b.c\fR, then it must
51
be the path name for a window; otherwise it may be an arbitrary
52
string.
53
Each window has an associated list of tags, and a binding applies
54
to a particular window if its tag is among those specified for
55
the window.
56
Although the \fBbindtags\fR command may be used to assign an
57
arbitrary set of binding tags to a window, the default binding
58
tags provide the following behavior:
59
.IP
60
If a tag is the name of an internal window the binding applies
61
to that window.
62
.IP
63
If the tag is the name of a toplevel window the binding applies
64
to the toplevel window and all its internal windows.
65
.IP
66
If the tag is the name of a class of widgets, such as \fBButton\fR,
67
the binding applies to all widgets in that class;
68
.IP
69
If \fItag\fR has the value \fBall\fR,
70
the binding applies to all windows in the application.
71
 
72
.SH "EVENT PATTERNS"
73
.PP
74
The \fIsequence\fR argument specifies a sequence of one or more
75
event patterns, with optional white space between the patterns.  Each
76
.VS
77
event pattern may
78
take one of three forms.  In the simplest case it is a single
79
.VE
80
printing ASCII character, such as \fBa\fR or \fB[\fR.  The character
81
may not be a space character or the character \fB<\fR.  This form of
82
pattern matches a \fBKeyPress\fR event for the particular
83
character.  The second form of pattern is longer but more general.
84
It has the following syntax:
85
.CS
86
\fB<\fImodifier-modifier-type-detail\fB>\fR
87
.CE
88
The entire event pattern is surrounded by angle brackets.
89
Inside the angle brackets are zero or more modifiers, an event
90
type, and an extra piece of information (\fIdetail\fR) identifying
91
a particular button or keysym.  Any of the fields may be omitted,
92
as long as at least one of \fItype\fR and \fIdetail\fR is present.
93
The fields must be separated by white space or dashes.
94
.VS
95
.PP
96
The third form of pattern is used to specify a user-defined, named virtual
97
event.  It has the following syntax:
98
.CS
99
\fB<<\fIname\fB>>\fR
100
.CE
101
The entire virtual event pattern is surrounded by double angle brackets.
102
Inside the angle brackets is the user-defined name of the virtual event.
103
Modifiers, such as \fBShift\fR or \fBControl\fR, may not be combined with a
104
virtual event to modify it.  Bindings on a virtual event may be created
105
before the virtual event is defined, and if the definition of a virtual
106
event changes dynamically, all windows bound to that virtual event will
107
respond immediately to the new definition.
108
.VE
109
.SH "MODIFIERS"
110
.PP
111
Modifiers consist of any of the following values:
112
.DS
113
.ta 6c
114
\fBControl\fR   \fBMod2, M2\fR
115
\fBShift\fR     \fBMod3, M3\fR
116
\fBLock\fR      \fBMod4, M4\fR
117
\fBButton1, B1\fR       \fBMod5, M5\fR
118
\fBButton2, B2\fR       \fBMeta, M\fR
119
\fBButton3, B3\fR       \fBAlt\fR
120
\fBButton4, B4\fR       \fBDouble\fR
121
\fBButton5, B5\fR       \fBTriple\fR
122
\fBMod1, M1\fR
123
.DE
124
Where more than one value is listed, separated by commas, the values
125
are equivalent.
126
Most of the modifiers have the obvious X meanings.
127
For example, \fBButton1\fR requires that
128
button 1 be depressed when the event occurs.
129
For a binding to match a given event, the modifiers in the event
130
must include all of those specified in the event pattern.
131
An event may also contain additional modifiers not specified in
132
the binding.
133
For example, if button 1 is pressed while the shift and control keys
134
are down, the pattern \fB\fR will match
135
the event, but \fB\fR will not.
136
If no modifiers are specified, then any combination of modifiers may
137
be present in the event.
138
.PP
139
\fBMeta\fR and \fBM\fR refer to whichever of the
140
\fBM1\fR through \fBM5\fR modifiers is associated with the meta
141
key(s) on the keyboard (keysyms \fBMeta_R\fR and \fBMeta_L\fR).
142
If there are no meta keys, or if they are not associated with any
143
modifiers, then \fBMeta\fR and \fBM\fR will not match any events.
144
Similarly, the \fBAlt\fR modifier refers to whichever modifier
145
is associated with the alt key(s) on the keyboard (keysyms
146
\fBAlt_L\fR and \fBAlt_R\fR).
147
.PP
148
The \fBDouble\fR and \fBTriple\fR modifiers are a convenience
149
for specifying double mouse clicks and other repeated
150
events. They cause a particular event pattern to be
151
repeated 2 or 3 times, and also place a time and space requirement
152
on the sequence:  for a sequence of events to match a \fBDouble\fR
153
or \fBTriple\fR pattern, all of the events must occur close together
154
in time and without substantial mouse motion in between.
155
For example, \fB\fR
156
is equivalent to \fB\fR with the extra
157
time and space requirement.
158
 
159
.SH "EVENT TYPES"
160
.PP
161
The \fItype\fR field may be any of the standard X event types, with a
162
few extra abbreviations.  The \fItype\fR field will also accept a
163
couple non-standard X event types that were added to better support
164
the Macintosh and Windows platforms.  Below is a list of all the valid
165
types; where two names appear together, they are synonyms.
166
.DS C
167
.ta 5c 10c
168
\fBActivate     Enter   Map
169
ButtonPress, Button     Expose  Motion
170
.VS
171
ButtonRelease   FocusIn MouseWheel
172
.VE
173
Circulate       FocusOut        Property
174
Colormap        Gravity Reparent
175
Configure       KeyPress, Key   Unmap
176
Deactivate      KeyRelease      Visibility
177
Destroy Leave\fR
178
.DE
179
.PP
180
.VS
181
Most of the above events have the same fields and behaviors as events
182
in the X Windowing system.  You can find more detailed descriptions of
183
these events in any X window programming book.  A couple of the events
184
are extensions to the X event system to support features unique to the
185
Macintosh and Windows platforms.  We provide a little more detail on
186
these events here.  These include:
187
.IP \fBActivate\fR 5
188
.IP \fBDeactivate\fR 5
189
These two events are sent to every sub-window of a toplevel when they
190
change state.  In addition to the focus Window, the Macintosh platform
191
and Windows platforms have a notion of an active window (which often
192
has but is not required to have the focus).  On the Macintosh, widgets
193
in the active window have a different appearance than widgets in
194
deactive windows.  The \fBActivate\fR event is sent to all the
195
sub-windows in a toplevel when it changes from being deactive to
196
active.  Likewise, the \fBDeactive\fR event is sent when the window's
197
state changes from active to deactive.  There are no useful percent
198
substitutions you would make when binding to these events.
199
.IP \fBMouseWheel\fR 5
200
Some mice on the Windows platform support a mouse wheel which is used
201
for scrolling documents without using the scrollbars.  By rolling the
202
wheel, the system will generate \fBMouseWheel\fR events that the
203
application can use to scroll.  Like \fBKey\fR events the event is
204
always routed to the window that currently has focus. When the event
205
is received you can use the \fB%D\fR substitution to get the
206
\fIdelta\fR field for the event which is a integer value of motion
207
that the mouse wheel has moved.  The smallest value for which the
208
system will report is defined by the OS.  On Windows 95 & 98 machines
209
this value is at least 120 before it is reported.  However, higher
210
resolution devices may be available in the future.  The sign of the
211
value determines which direction your widget should scroll.  Positive
212
values should scroll up and negative values should scroll down.
213
.VE
214
.PP
215
The last part of a long event specification is \fIdetail\fR.  In the
216
case of a \fBButtonPress\fR or \fBButtonRelease\fR event, it is the
217
number of a button (1-5).  If a button number is given, then only an
218
event on that particular button will match;  if no button number is
219
given, then an event on any button will match.  Note:  giving a
220
specific button number is different than specifying a button modifier;
221
in the first case, it refers to a button being pressed or released,
222
while in the second it refers to some other button that is already
223
depressed when the matching event occurs.  If a button
224
number is given then \fItype\fR may be omitted:  if will default
225
to \fBButtonPress\fR.  For example, the specifier \fB<1>\fR
226
is equivalent to \fB\fR.
227
.PP
228
If the event type is \fBKeyPress\fR or \fBKeyRelease\fR, then
229
\fIdetail\fR may be specified in the form of an X keysym.  Keysyms
230
are textual specifications for particular keys on the keyboard;
231
they include all the alphanumeric ASCII characters (e.g. ``a'' is
232
the keysym for the ASCII character ``a''), plus descriptions for
233
non-alphanumeric characters (``comma'' is the keysym for the comma
234
character), plus descriptions for all the non-ASCII keys on the
235
keyboard (``Shift_L'' is the keysm for the left shift key, and
236
``F1'' is the keysym for the F1 function key, if it exists).  The
237
complete list of keysyms is not presented here;  it is
238
available in other X documentation and may vary from system to
239
system.
240
If necessary, you can use the \fB%K\fR notation described below
241
to print out the keysym name for a particular key.
242
If a keysym \fIdetail\fR is given, then the
243
\fItype\fR field may be omitted;  it will default to \fBKeyPress\fR.
244
For example, \fB\fR is equivalent to
245
\fB\fR.
246
 
247
.SH "BINDING SCRIPTS AND SUBSTITUTIONS"
248
.PP
249
The \fIscript\fR argument to \fBbind\fR is a Tcl script,
250
which will be executed whenever the given event sequence occurs.
251
\fICommand\fR will be executed in the same interpreter that the
252
\fBbind\fR command was executed in, and it will run at global
253
level (only global variables will be accessible).
254
If \fIscript\fR contains
255
any \fB%\fR characters, then the script will not be
256
executed directly.  Instead, a new script will be
257
generated by replacing each \fB%\fR, and the character following
258
it, with information from the current event.  The replacement
259
depends on the character following the \fB%\fR, as defined in the
260
list below.  Unless otherwise indicated, the
261
replacement string is the decimal value of the given field from
262
the current event.
263
Some of the substitutions are only valid for
264
certain types of events;  if they are used for other types of events
265
the value substituted is undefined.
266
.IP \fB%%\fR 5
267
Replaced with a single percent.
268
.IP \fB%#\fR 5
269
The number of the last client request processed by the server
270
(the \fIserial\fR field from the event).  Valid for all event
271
types.
272
.IP \fB%a\fR 5
273
The \fIabove\fR field from the event,
274
formatted as a hexadecimal number.
275
Valid only for \fBConfigure\fR events.
276
.IP \fB%b\fR 5
277
The number of the button that was pressed or released.  Valid only
278
for \fBButtonPress\fR and \fBButtonRelease\fR events.
279
.IP \fB%c\fR 5
280
The \fIcount\fR field from the event.  Valid only for \fBExpose\fR events.
281
.IP \fB%d\fR 5
282
The \fIdetail\fR field from the event.  The \fB%d\fR is replaced by
283
a string identifying the detail.  For \fBEnter\fR,
284
\fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events,
285
the string will be one of the following:
286
.RS
287
.DS
288
.ta 6c
289
\fBNotifyAncestor       NotifyNonlinearVirtual
290
NotifyDetailNone        NotifyPointer
291
NotifyInferior  NotifyPointerRoot
292
NotifyNonlinear NotifyVirtual\fR
293
.DE
294
For events other than these, the substituted string is undefined.
295
.RE
296
.IP \fB%f\fR 5
297
The \fIfocus\fR field from the event (\fB0\fR or \fB1\fR).  Valid only
298
for \fBEnter\fR and \fBLeave\fR events.
299
.IP \fB%h\fR 5
300
.VS
301
The \fIheight\fR field from the event.  Valid for the \fBConfigure\fR and
302
\fBExpose\fR events.
303
.VE
304
.IP \fB%k\fR 5
305
The \fIkeycode\fR field from the event.  Valid only for \fBKeyPress\fR
306
and \fBKeyRelease\fR events.
307
.IP \fB%m\fR 5
308
The \fImode\fR field from the event.  The substituted string is one of
309
\fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or
310
.VS
311
\fBNotifyWhileGrabbed\fR.  Valid only for \fBEnter\fR,
312
\fBFocusIn\fR, \fBFocusOut\fR, and \fBLeave\fR events.
313
.VE
314
.IP \fB%o\fR 5
315
The \fIoverride_redirect\fR field from the event.  Valid only for
316
\fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events.
317
.IP \fB%p\fR 5
318
The \fIplace\fR field from the event, substituted as one of the
319
strings \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR.  Valid only
320
for \fBCirculate\fR events.
321
.IP \fB%s\fR 5
322
The \fIstate\fR field from the event.  For \fBButtonPress\fR,
323
\fBButtonRelease\fR, \fBEnter\fR, \fBKeyPress\fR, \fBKeyRelease\fR,
324
\fBLeave\fR, and \fBMotion\fR events, a decimal string
325
is substituted.  For \fBVisibility\fR, one of the strings
326
\fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR,
327
and \fBVisibilityFullyObscured\fR is substituted.
328
.IP \fB%t\fR 5
329
The \fItime\fR field from the event.  Valid only for events that
330
contain a \fItime\fR field.
331
.IP \fB%w\fR 5
332
The \fIwidth\fR field from the event.  Valid only for
333
.VS
334
\fBConfigure\fR and \fBExpose\fR events.
335
.VE
336
.IP \fB%x\fR 5
337
The \fIx\fR field from the event.  Valid only for events containing
338
an \fIx\fR field.
339
.IP \fB%y\fR 5
340
The \fIy\fR field from the event.  Valid only for events containing
341
a \fIy\fR field.
342
.IP \fB%A\fR 5
343
Substitutes the ASCII character corresponding to the event, or
344
the empty string if the event doesn't correspond to an ASCII character
345
(e.g. the shift key was pressed).  \fBXLookupString\fR does all the
346
work of translating from the event to an ASCII character.
347
Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
348
.IP \fB%B\fR 5
349
The \fIborder_width\fR field from the event.  Valid only for
350
\fBConfigure\fR events.
351
.VS
352
.IP \fB%D\fR 5
353
This reports the \fIdelta\fR value of a \fBMouseWheel\fR event.  The
354
\fIdelta\fR value represents the rotation units the mouse wheel has
355
been moved.  On Windows 95 & 98 systems the smallest value for the
356
delta is 120.  Future systems may support higher resolution values for
357
the delta.  The sign of the value represents the direction the mouse
358
wheel was scrolled.
359
.VE
360
.IP \fB%E\fR 5
361
The \fIsend_event\fR field from the event.  Valid for all event types.
362
.IP \fB%K\fR 5
363
The keysym corresponding to the event, substituted as a textual
364
string.  Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
365
.IP \fB%N\fR 5
366
The keysym corresponding to the event, substituted as a decimal
367
number.  Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
368
.IP \fB%R\fR 5
369
The \fIroot\fR window identifier from the event.  Valid only for
370
events containing a \fIroot\fR field.
371
.IP \fB%S\fR 5
372
The \fIsubwindow\fR window identifier from the event,
373
formatted as a hexadecimal number.
374
Valid only for events containing a \fIsubwindow\fR field.
375
.IP \fB%T\fR 5
376
The \fItype\fR field from the event.  Valid for all event types.
377
.IP \fB%W\fR 5
378
The path name of the window to which the event was reported (the
379
\fIwindow\fR field from the event).  Valid for all event types.
380
.IP \fB%X\fR 5
381
The \fIx_root\fR field from the event.
382
If a virtual-root window manager is being used then the substituted
383
value is the corresponding x-coordinate in the virtual root.
384
Valid only for
385
\fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR,
386
and \fBMotion\fR events.
387
.IP \fB%Y\fR 5
388
The \fIy_root\fR field from the event.
389
If a virtual-root window manager is being used then the substituted
390
value is the corresponding y-coordinate in the virtual root.
391
Valid only for
392
\fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR,
393
and \fBMotion\fR events.
394
.LP
395
The replacement string for a %-replacement is formatted as a proper
396
Tcl list element.
397
This means that it will be surrounded with braces
398
if it contains spaces, or special characters such as \fB$\fR and
399
\fB{\fR may be preceded by backslashes.
400
This guarantees that the string will be passed through the Tcl
401
parser when the binding script is evaluated.
402
Most replacements are numbers or well-defined strings such
403
as \fBAbove\fR;  for these replacements no special formatting
404
is ever necessary.
405
The most common case where reformatting occurs is for the \fB%A\fR
406
substitution.  For example, if \fIscript\fR is
407
.CS
408
\fBinsert\0%A\fR
409
.CE
410
and the character typed is an open square bracket, then the script
411
actually executed will be
412
.CS
413
\fBinsert\0\e[\fR
414
.CE
415
This will cause the \fBinsert\fR to receive the original replacement
416
string (open square bracket) as its first argument.
417
If the extra backslash hadn't been added, Tcl would not have been
418
able to parse the script correctly.
419
 
420
.SH MULTIPLE MATCHES
421
.PP
422
It is possible for several bindings to match a given X event.
423
If the bindings are associated with different \fItag\fR's,
424
then each of the bindings will be executed, in order.
425
By default, a binding for the widget will be executed first, followed
426
by a class binding, a binding for its toplevel, and
427
an \fBall\fR binding.
428
The \fBbindtags\fR command may be used to change this order for
429
a particular window or to associate additional binding tags with
430
the window.
431
.PP
432
The \fBcontinue\fR and \fBbreak\fR commands may be used inside a
433
binding script to control the processing of matching scripts.
434
If \fBcontinue\fR is invoked, then the current binding script
435
is terminated but Tk will continue processing binding scripts
436
associated with other \fItag\fR's.
437
If the \fBbreak\fR command is invoked within a binding script,
438
then that script terminates and no other scripts will be invoked
439
for the event.
440
.VS
441
.PP
442
If more than one binding matches a particular event and they
443
have the same \fItag\fR, then the most specific binding
444
is chosen and its script is evaluated.
445
The following tests are applied, in order, to determine which of
446
several matching sequences is more specific:
447
(a) an event pattern that specifies a specific button or key is more specific
448
than one that doesn't;
449
(b) a longer sequence (in terms of number
450
of events matched) is more specific than a shorter sequence;
451
(c) if the modifiers specified in one pattern are a subset of the
452
modifiers in another pattern, then the pattern with more modifiers
453
is more specific.
454
.VS
455
(d) a virtual event whose physical pattern matches the sequence is less
456
specific than the same physical pattern that is not associated with a
457
virtual event.
458
(e) given a sequence that matches two or more virtual events, one
459
of the virtual events will be chosen, but the order is undefined.
460
.PP
461
If the matching sequences contain more than one event, then tests
462
(c)-(e) are applied in order from the most recent event to the least recent
463
event in the sequences.  If these tests fail to determine a winner, then the
464
most recently registered sequence is the winner.
465
.PP
466
If there are two (or more) virtual events that are both triggered by the
467
same sequence, and both of those virtual events are bound to the same window
468
tag, then only one of the virtual events will be triggered, and it will
469
be picked at random:
470
.CS
471
event add <> 
472
event add <> 
473
event add <> 
474
bind Entry <> {puts Paste}
475
bind Entry <> {puts Scroll}
476
.CE
477
If the user types Control-y, the \fB<>\fR binding
478
will be invoked, but if the user presses button 2 then one of
479
either the \fB<>\fR or the \fB<>\fR bindings will
480
be invoked, but exactly which one gets invoked is undefined.
481
.VE
482
.PP
483
If an X event does not match any of the existing bindings, then the
484
event is ignored.
485
An unbound event is not considered to be an error.
486
 
487
.SH "MULTI-EVENT SEQUENCES AND IGNORED EVENTS"
488
.PP
489
When a \fIsequence\fR specified in a \fBbind\fR command contains
490
more than one event pattern, then its script is executed whenever
491
the recent events (leading up to and including the current event)
492
match the given sequence.  This means, for example, that if button 1 is
493
clicked repeatedly the sequence \fB\fR will match
494
each button press but the first.
495
If extraneous events that would prevent a match occur in the middle
496
of an event sequence then the extraneous events are
497
ignored unless they are \fBKeyPress\fR or \fBButtonPress\fR events.
498
For example, \fB\fR will match a sequence of
499
presses of button 1, even though there will be \fBButtonRelease\fR
500
events (and possibly \fBMotion\fR events) between the
501
\fBButtonPress\fR events.
502
Furthermore, a \fBKeyPress\fR event may be preceded by any number
503
of other \fBKeyPress\fR events for modifier keys without the
504
modifier keys preventing a match.
505
For example, the event sequence \fBaB\fR will match a press of the
506
\fBa\fR key, a release of the \fBa\fR key, a press of the \fBShift\fR
507
key, and a press of the \fBb\fR key:  the press of \fBShift\fR is
508
ignored because it is a modifier key.
509
Finally, if several \fBMotion\fR events occur in a row, only
510
the last one is used for purposes of matching binding sequences.
511
 
512
.SH ERRORS
513
.PP
514
If an error occurs in executing the script for a binding then the
515
\fBbgerror\fR mechanism is used to report the error.
516
The \fBbgerror\fR command will be executed at global level
517
(outside the context of any Tcl procedure).
518
 
519
.SH "SEE ALSO"
520
bgerror
521
 
522
.SH KEYWORDS
523
form, manual

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.