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

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [tk/] [doc/] [BindTable.3] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
'\"
2
'\" Copyright (c) 1994 The Regents of the University of California.
3
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
4
'\"
5
'\" See the file "license.terms" for information on usage and redistribution
6
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7
'\"
8
'\" RCS: @(#) $Id: BindTable.3,v 1.1.1.1 2002-01-16 10:25:47 markom Exp $
9
'\"
10
.so man.macros
11
.TH Tk_CreateBindingTable 3 4.0 Tk "Tk Library Procedures"
12
.BS
13
.SH NAME
14
Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events
15
.SH SYNOPSIS
16
.nf
17
\fB#include \fR
18
.sp
19
Tk_BindingTable
20
\fBTk_CreateBindingTable(\fIinterp\fB)\fR
21
.sp
22
\fBTk_DeleteBindingTable(\fIbindingTable\fB)\fR
23
.sp
24
unsigned long
25
\fBTk_CreateBinding(\fIinterp, bindingTable, object, eventString, script, append\fB)\fR
26
.sp
27
int
28
\fBTk_DeleteBinding(\fIinterp, bindingTable, object, eventString\fB)\fR
29
.sp
30
char *
31
\fBTk_GetBinding(\fIinterp, bindingTable, object, eventString\fB)\fR
32
.sp
33
\fBTk_GetAllBindings(\fIinterp, bindingTable, object\fB)\fR
34
.sp
35
\fBTk_DeleteAllBindings(\fIbindingTable, object\fB)\fR
36
.sp
37
\fBTk_BindEvent(\fIbindingTable, eventPtr, tkwin, numObjects, objectPtr\fB)\fR
38
.SH ARGUMENTS
39
.AS Tk_BindingTable bindingTable
40
.AP Tcl_Interp *interp in
41
Interpreter to use when invoking bindings in binding table.  Also
42
used for returning results and errors from binding procedures.
43
.AP Tk_BindingTable bindingTable in
44
Token for binding table;  must have been returned by some previous
45
call to \fBTk_CreateBindingTable\fR.
46
.AP ClientData object in
47
Identifies object with which binding is associated.
48
.AP char *eventString in
49
String describing event sequence.
50
.AP char *script in
51
Tcl script to invoke when binding triggers.
52
.AP int append in
53
Non-zero means append \fIscript\fR to existing script for binding,
54
if any; zero means replace existing script with new one.
55
.AP XEvent *eventPtr in
56
X event to match against bindings in \fIbindingTable\fR.
57
.AP Tk_Window tkwin in
58
Identifier for any window on the display where the event occurred.
59
Used to find display-related information such as key maps.
60
.AP int numObjects in
61
Number of object identifiers pointed to by \fIobjectPtr\fR.
62
.AP ClientData *objectPtr in
63
Points to an array of object identifiers:  bindings will be considered
64
for each of these objects in order from first to last.
65
.BE
66
 
67
.SH DESCRIPTION
68
.PP
69
These procedures provide a general-purpose mechanism for creating
70
and invoking bindings.
71
Bindings are organized in terms of \fIbinding tables\fR.
72
A binding table consists of a collection of bindings plus a history
73
of recent events.
74
Within a binding table, bindings are associated with \fIobjects\fR.
75
The meaning of an object is defined by clients of the binding package.
76
For example, Tk keeps uses one binding table to hold all of the bindings
77
created by the \fBbind\fR command.
78
For this table, objects are pointers to strings such as window names, class
79
names, or other binding tags such as \fBall\fR.
80
Tk also keeps a separate binding table for each canvas widget, which manages
81
bindings created by the canvas's \fBbind\fR widget command;  within
82
this table, an object is either a pointer to the internal structure for a
83
canvas item or a Tk_Uid identifying a tag.
84
.PP
85
The procedure \fBTk_CreateBindingTable\fR creates a new binding
86
table and associates \fIinterp\fR with it (when bindings in the
87
table are invoked, the scripts will be evaluated in \fIinterp\fR).
88
\fBTk_CreateBindingTable\fR returns a token for the table, which
89
must be used in calls to other procedures such as \fBTk_CreateBinding\fR
90
or \fBTk_BindEvent\fR.
91
.PP
92
\fBTk_DeleteBindingTable\fR frees all of the state associated
93
with a binding table.
94
Once it returns the caller should not use the \fIbindingTable\fR
95
token again.
96
.PP
97
\fBTk_CreateBinding\fR adds a new binding to an existing table.
98
The \fIobject\fR argument identifies the object with which the
99
binding is to be associated, and it may be any one-word value.
100
Typically it is a pointer to a string or data structure.
101
The \fIeventString\fR argument identifies the event or sequence
102
of events for the binding;  see the documentation for the
103
\fBbind\fR command for a description of its format.
104
\fIscript\fR is the Tcl script to be evaluated when the binding
105
triggers.
106
\fIappend\fR indicates what to do if there already
107
exists a binding for \fIobject\fR and \fIeventString\fR:  if \fIappend\fR
108
is zero then \fIscript\fR replaces the old script;  if \fIappend\fR
109
is non-zero then the new script is appended to the old one.
110
\fBTk_CreateBinding\fR returns an X event mask for all the events
111
associated with the bindings.
112
This information may be useful to invoke \fBXSelectInput\fR to
113
select relevant events, or to disallow the use of certain events
114
in bindings.
115
If an error occurred while creating the binding (e.g., \fIeventString\fR
116
refers to a non-existent event), then 0 is returned and an error
117
message is left in \fIinterp->result\fR.
118
.PP
119
\fBTk_DeleteBinding\fR removes from \fIbindingTable\fR the
120
binding given by \fIobject\fR and \fIeventString\fR, if
121
such a binding exists.
122
\fBTk_DeleteBinding\fR always returns TCL_OK.
123
In some cases it may reset \fIinterp->result\fR to the default
124
empty value.
125
.PP
126
\fBTk_GetBinding\fR returns a pointer to the script associated
127
with \fIeventString\fR and \fIobject\fR in \fIbindingTable\fR.
128
If no such binding exists then NULL is returned and an error
129
message is left in \fIinterp->result\fR.
130
.PP
131
\fBTk_GetAllBindings\fR returns in \fIinterp->result\fR a list
132
of all the event strings for which there are bindings in
133
\fIbindingTable\fR associated with \fIobject\fR.
134
If there are no bindings for \fIobject\fR then an empty
135
string is returned in \fIinterp->result\fR.
136
.PP
137
\fBTk_DeleteAllBindings\fR deletes all of the bindings in
138
\fIbindingTable\fR that are associated with \fIobject\fR.
139
.PP
140
\fBTk_BindEvent\fR is called to process an event.
141
It makes a copy of the event in an internal history list associated
142
with the binding table, then it checks for bindings that match
143
the event.
144
\fBTk_BindEvent\fR processes each of the objects pointed to
145
by \fIobjectPtr\fR in turn.
146
For each object, it finds all the bindings that match the current
147
event history, selects the most specific binding using the priority
148
mechanism described in the documentation for \fBbind\fR,
149
and invokes the script for that binding.
150
If there are no matching bindings for a particular object, then
151
the object is skipped.
152
\fBTk_BindEvent\fR continues through all of the objects, handling
153
exceptions such as errors, \fBbreak\fR, and \fBcontinue\fR as
154
described in the documentation for \fBbind\fR.
155
 
156
.SH KEYWORDS
157
binding, event, object, script

powered by: WebSVN 2.1.0

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