158 lines
6.5 KiB
Groff
158 lines
6.5 KiB
Groff
'\"
|
|
'\" Copyright (c) 1994 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) BindTable.3 1.5 96/03/26 18:03:09
|
|
'\"
|
|
.so man.macros
|
|
.TH Tk_CreateBindingTable 3 4.0 Tk "Tk Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tk.h>\fR
|
|
.sp
|
|
Tk_BindingTable
|
|
\fBTk_CreateBindingTable(\fIinterp\fB)\fR
|
|
.sp
|
|
\fBTk_DeleteBindingTable(\fIbindingTable\fB)\fR
|
|
.sp
|
|
unsigned long
|
|
\fBTk_CreateBinding(\fIinterp, bindingTable, object, eventString, script, append\fB)\fR
|
|
.sp
|
|
int
|
|
\fBTk_DeleteBinding(\fIinterp, bindingTable, object, eventString\fB)\fR
|
|
.sp
|
|
char *
|
|
\fBTk_GetBinding(\fIinterp, bindingTable, object, eventString\fB)\fR
|
|
.sp
|
|
\fBTk_GetAllBindings(\fIinterp, bindingTable, object\fB)\fR
|
|
.sp
|
|
\fBTk_DeleteAllBindings(\fIbindingTable, object\fB)\fR
|
|
.sp
|
|
\fBTk_BindEvent(\fIbindingTable, eventPtr, tkwin, numObjects, objectPtr\fB)\fR
|
|
.SH ARGUMENTS
|
|
.AS Tk_BindingTable bindingTable
|
|
.AP Tcl_Interp *interp in
|
|
Interpreter to use when invoking bindings in binding table. Also
|
|
used for returning results and errors from binding procedures.
|
|
.AP Tk_BindingTable bindingTable in
|
|
Token for binding table; must have been returned by some previous
|
|
call to \fBTk_CreateBindingTable\fR.
|
|
.AP ClientData object in
|
|
Identifies object with which binding is associated.
|
|
.AP char *eventString in
|
|
String describing event sequence.
|
|
.AP char *script in
|
|
Tcl script to invoke when binding triggers.
|
|
.AP int append in
|
|
Non-zero means append \fIscript\fR to existing script for binding,
|
|
if any; zero means replace existing script with new one.
|
|
.AP XEvent *eventPtr in
|
|
X event to match against bindings in \fIbindingTable\fR.
|
|
.AP Tk_Window tkwin in
|
|
Identifier for any window on the display where the event occurred.
|
|
Used to find display-related information such as key maps.
|
|
.AP int numObjects in
|
|
Number of object identifiers pointed to by \fIobjectPtr\fR.
|
|
.AP ClientData *objectPtr in
|
|
Points to an array of object identifiers: bindings will be considered
|
|
for each of these objects in order from first to last.
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
These procedures provide a general-purpose mechanism for creating
|
|
and invoking bindings.
|
|
Bindings are organized in terms of \fIbinding tables\fR.
|
|
A binding table consists of a collection of bindings plus a history
|
|
of recent events.
|
|
Within a binding table, bindings are associated with \fIobjects\fR.
|
|
The meaning of an object is defined by clients of the binding package.
|
|
For example, Tk keeps uses one binding table to hold all of the bindings
|
|
created by the \fBbind\fR command.
|
|
For this table, objects are pointers to strings such as window names, class
|
|
names, or other binding tags such as \fBall\fR.
|
|
Tk also keeps a separate binding table for each canvas widget, which manages
|
|
bindings created by the canvas's \fBbind\fR widget command; within
|
|
this table, an object is either a pointer to the internal structure for a
|
|
canvas item or a Tk_Uid identifying a tag.
|
|
.PP
|
|
The procedure \fBTk_CreateBindingTable\fR creates a new binding
|
|
table and associates \fIinterp\fR with it (when bindings in the
|
|
table are invoked, the scripts will be evaluated in \fIinterp\fR).
|
|
\fBTk_CreateBindingTable\fR returns a token for the table, which
|
|
must be used in calls to other procedures such as \fBTk_CreateBinding\fR
|
|
or \fBTk_BindEvent\fR.
|
|
.PP
|
|
\fBTk_DeleteBindingTable\fR frees all of the state associated
|
|
with a binding table.
|
|
Once it returns the caller should not use the \fIbindingTable\fR
|
|
token again.
|
|
.PP
|
|
\fBTk_CreateBinding\fR adds a new binding to an existing table.
|
|
The \fIobject\fR argument identifies the object with which the
|
|
binding is to be associated, and it may be any one-word value.
|
|
Typically it is a pointer to a string or data structure.
|
|
The \fIeventString\fR argument identifies the event or sequence
|
|
of events for the binding; see the documentation for the
|
|
\fBbind\fR command for a description of its format.
|
|
\fIscript\fR is the Tcl script to be evaluated when the binding
|
|
triggers.
|
|
\fIappend\fR indicates what to do if there already
|
|
exists a binding for \fIobject\fR and \fIeventString\fR: if \fIappend\fR
|
|
is zero then \fIscript\fR replaces the old script; if \fIappend\fR
|
|
is non-zero then the new script is appended to the old one.
|
|
\fBTk_CreateBinding\fR returns an X event mask for all the events
|
|
associated with the bindings.
|
|
This information may be useful to invoke \fBXSelectInput\fR to
|
|
select relevant events, or to disallow the use of certain events
|
|
in bindings.
|
|
If an error occurred while creating the binding (e.g., \fIeventString\fR
|
|
refers to a non-existent event), then 0 is returned and an error
|
|
message is left in \fIinterp->result\fR.
|
|
.PP
|
|
\fBTk_DeleteBinding\fR removes from \fIbindingTable\fR the
|
|
binding given by \fIobject\fR and \fIeventString\fR, if
|
|
such a binding exists.
|
|
\fBTk_DeleteBinding\fR always returns TCL_OK.
|
|
In some cases it may reset \fIinterp->result\fR to the default
|
|
empty value.
|
|
.PP
|
|
\fBTk_GetBinding\fR returns a pointer to the script associated
|
|
with \fIeventString\fR and \fIobject\fR in \fIbindingTable\fR.
|
|
If no such binding exists then NULL is returned and an error
|
|
message is left in \fIinterp->result\fR.
|
|
.PP
|
|
\fBTk_GetAllBindings\fR returns in \fIinterp->result\fR a list
|
|
of all the event strings for which there are bindings in
|
|
\fIbindingTable\fR associated with \fIobject\fR.
|
|
If there are no bindings for \fIobject\fR then an empty
|
|
string is returned in \fIinterp->result\fR.
|
|
.PP
|
|
\fBTk_DeleteAllBindings\fR deletes all of the bindings in
|
|
\fIbindingTable\fR that are associated with \fIobject\fR.
|
|
.PP
|
|
\fBTk_BindEvent\fR is called to process an event.
|
|
It makes a copy of the event in an internal history list associated
|
|
with the binding table, then it checks for bindings that match
|
|
the event.
|
|
\fBTk_BindEvent\fR processes each of the objects pointed to
|
|
by \fIobjectPtr\fR in turn.
|
|
For each object, it finds all the bindings that match the current
|
|
event history, selects the most specific binding using the priority
|
|
mechanism described in the documentation for \fBbind\fR,
|
|
and invokes the script for that binding.
|
|
If there are no matching bindings for a particular object, then
|
|
the object is skipped.
|
|
\fBTk_BindEvent\fR continues through all of the objects, handling
|
|
exceptions such as errors, \fBbreak\fR, and \fBcontinue\fR as
|
|
described in the documentation for \fBbind\fR.
|
|
|
|
.SH KEYWORDS
|
|
binding, event, object, script
|