tk/doc/BindTable.3

   1 '\"
   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$
   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 <tk.h>\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
 158