Initial revision

1 files changed, 157 insertions, 0 deletions

diff --git a/doc/BindTable.3 b/doc/BindTable.3
new file mode 100644
index 0000000..bbcb64d
--- /dev/null
+++ b/doc/BindTable.3
@@ -0,0 +1,157 @@
+'\"
+'\" 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