1Tk_CreateBindingTable(3)     Tk Library Procedures    Tk_CreateBindingTable(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_CreateBindingTable,     Tk_DeleteBindingTable,     Tk_CreateBinding,
9       Tk_DeleteBinding, Tk_GetBinding,  Tk_GetAllBindings,  Tk_DeleteAllBind‐
10       ings, Tk_BindEvent - invoke scripts in response to X events
11

SYNOPSIS

13       #include <tk.h>
14
15       Tk_BindingTable
16       Tk_CreateBindingTable(interp)
17
18       Tk_DeleteBindingTable(bindingTable)
19
20       unsigned long
21       Tk_CreateBinding(interp, bindingTable, object, eventString, script, append)
22
23       int
24       Tk_DeleteBinding(interp, bindingTable, object, eventString)
25
26       const char *
27       Tk_GetBinding(interp, bindingTable, object, eventString)
28
29       Tk_GetAllBindings(interp, bindingTable, object)
30
31       Tk_DeleteAllBindings(bindingTable, object)
32
33       Tk_BindEvent(bindingTable, eventPtr, tkwin, numObjects, objectPtr)
34

ARGUMENTS

36       Tcl_Interp *interp (in)                    Interpreter  to use when in‐
37                                                  voking bindings  in  binding
38                                                  table.   Also  used  for re‐
39                                                  turning results  and  errors
40                                                  from binding procedures.
41
42       Tk_BindingTable bindingTable (in)          Token   for  binding  table;
43                                                  must have been  returned  by
44                                                  some    previous   call   to
45                                                  Tk_CreateBindingTable.
46
47       ClientData object (in)                     Identifies object with which
48                                                  binding is associated.
49
50       const char *eventString (in)               String  describing event se‐
51                                                  quence.
52
53       const char *script (in)                    Tcl script  to  invoke  when
54                                                  binding triggers.
55
56       int append (in)                            Non-zero means append script
57                                                  to existing script for bind‐
58                                                  ing,  if any; zero means re‐
59                                                  place existing  script  with
60                                                  new one.
61
62       XEvent *eventPtr (in)                      X  event  to  match  against
63                                                  bindings in bindingTable.
64
65       Tk_Window tkwin (in)                       Identifier for any window on
66                                                  the  display where the event
67                                                  occurred.  Used to find dis‐
68                                                  play-related     information
69                                                  such as key maps.
70
71       int numObjects (in)                        Number of object identifiers
72                                                  pointed to by objectPtr.
73
74       ClientData *objectPtr (in)                 Points to an array of object
75                                                  identifiers:  bindings  will
76                                                  be  considered  for  each of
77                                                  these objects in order  from
78                                                  first to last.
79______________________________________________________________________________
80

DESCRIPTION

82       These  procedures  provide a general-purpose mechanism for creating and
83       invoking bindings.  Bindings are organized in terms of binding  tables.
84       A  binding table consists of a collection of bindings plus a history of
85       recent events.  Within a binding table, bindings  are  associated  with
86       objects.  The meaning of an object is defined by clients of the binding
87       package.  For example, Tk keeps uses one binding table to hold  all  of
88       the  bindings created by the bind command.  For this table, objects are
89       pointers to strings such as window names, class names, or other binding
90       tags such as all.  Tk also keeps a separate binding table for each can‐
91       vas widget, which manages bindings created by the canvas's bind  widget
92       command;   within  this table, an object is either a pointer to the in‐
93       ternal structure for a canvas item or a Tk_Uid identifying a tag.
94
95       The procedure Tk_CreateBindingTable creates a new binding table and as‐
96       sociates  interp  with  it (when bindings in the table are invoked, the
97       scripts will be evaluated in interp).  Tk_CreateBindingTable returns  a
98       token  for  the  table, which must be used in calls to other procedures
99       such as Tk_CreateBinding or Tk_BindEvent.
100
101       Tk_DeleteBindingTable frees all of the state associated with a  binding
102       table.   Once it returns the caller should not use the bindingTable to‐
103       ken again.
104
105       Tk_CreateBinding adds a new binding to an existing table.   The  object
106       argument  identifies the object with which the binding is to be associ‐
107       ated, and it may be any one-word value.  Typically it is a pointer to a
108       string  or  data  structure.   The  eventString argument identifies the
109       event or sequence of events for the binding;  see the documentation for
110       the  bind  command  for a description of its format.  script is the Tcl
111       script to be evaluated when the  binding  triggers.   append  indicates
112       what   to  do  if  there  already  exists  a  binding  for  object  and
113       eventString:  if append is zero then script replaces  the  old  script;
114       if  append  is non-zero then the new script is appended to the old one.
115       Tk_CreateBinding returns an X event mask for all the events  associated
116       with the bindings.  This information may be useful to invoke XSelectIn‐
117       put to select relevant events, or to disallow the use of certain events
118       in  bindings.   If  an error occurred while creating the binding (e.g.,
119       eventString refers to a non-existent event), then 0 is returned and  an
120       error message is left as the result of interpreter interp.
121
122       Tk_DeleteBinding  removes from bindingTable the binding given by object
123       and eventString, if such a binding exists.  Tk_DeleteBinding always re‐
124       turns TCL_OK.  In some cases it may reset the interpreter result to the
125       default empty value.
126
127       Tk_GetBinding  returns  a  pointer  to  the  script   associated   with
128       eventString and object in bindingTable.  If no such binding exists then
129       NULL is returned and an error message is left as the result  of  inter‐
130       preter interp.
131
132       Tk_GetAllBindings  returns  in  interp's result a list of all the event
133       strings for which there are bindings in  bindingTable  associated  with
134       object.   If  there  are  no bindings for object, the result will be an
135       empty string.
136
137       Tk_DeleteAllBindings deletes all of the bindings in  bindingTable  that
138       are associated with object.
139
140       Tk_BindEvent  is  called  to  process an event.  It makes a copy of the
141       event in an internal history list associated with  the  binding  table,
142       then  it  checks  for bindings that match the event.  Tk_BindEvent pro‐
143       cesses each of the objects pointed to by objectPtr in turn.   For  each
144       object, it finds all the bindings that match the current event history,
145       selects the most specific binding  using  the  priority  mechanism  de‐
146       scribed  in the documentation for bind, and invokes the script for that
147       binding.  If there are no matching bindings for  a  particular  object,
148       then  the object is skipped.  Tk_BindEvent continues through all of the
149       objects, handling exceptions such as errors, break, and continue as de‐
150       scribed in the documentation for bind.
151

KEYWORDS

153       binding, event, object, script
154
155
156
157Tk                                    4.0             Tk_CreateBindingTable(3)
Impressum