Tk_CreateBindingTable(3tk)

💖 NAME 💖

okay bestie, gather round, because this page is literally a whole family of functions: Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, and Tk_BindEvent — and what do they do? they invoke scripts in response to X events. that's the whole vibe. ✨

(this is a Tk library procedures page, iykyk 💅)

---

🌈 SYNOPSIS 🌈

#include <tk.h>

Tk_BindingTable
Tk_CreateBindingTable(interp)

Tk_DeleteBindingTable(bindingTable)

unsigned long
Tk_CreateBinding(interp, bindingTable, object, eventString, script, append)

int
Tk_DeleteBinding(interp, bindingTable, object, eventString)

const char *
Tk_GetBinding(interp, bindingTable, object, eventString)

Tk_GetAllBindings(interp, bindingTable, object)

Tk_DeleteAllBindings(bindingTable, object)

Tk_BindEvent(bindingTable, eventPtr, tkwin, numObjects, objectPtr)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the interpreter you use when invoking bindings in the binding table. it's also where results and errors from binding procedures get returned, so like, it's doing double duty bestie 🫶
• Tk_BindingTable bindingTable (in) — the token for the binding table. it must have been returned by some previous call to Tk_CreateBindingTable. no improvising, no making one up. 🙈
• void * object (in) — identifies the object the binding is associated with.
• const char *eventString (in) — a string describing the event sequence.
• const char *script (in) — the Tcl script to invoke when the binding triggers. the moment. the main character. ✨
• int append (in) — non-zero means append the script to the existing script for the binding, if there is one; zero means replace the existing script with the new one. choose wisely 💅
• XEvent *eventPtr (in) — the X event to match against the bindings in bindingTable.
• Tk_Window tkwin (in) — an identifier for any window on the display where the event occurred. it's used to find display-related info like key maps.
• Tcl_Size numObjects (in) — how many object identifiers objectPtr is pointing to.
• void ** objectPtr (in) — points to an array of object identifiers. bindings get considered for each of these objects, in order, first to last. no skipping the line, bestie. 👑

---

🦋 DESCRIPTION 🦋

these procedures give you a general-purpose mechanism for creating and invoking bindings. bindings are organized in terms of binding tables. a binding table is a collection of bindings plus a history of recent events. and within a binding table, bindings are associated with objects. what does "object" mean? literally whatever the clients of the binding package decide it means — it's defined by them, not by us. slay, flexible.

for example, Tk keeps uses one binding table to hold all of the bindings created by the bind command. in that table, objects are pointers to strings like window names, class names, or other binding tags such as all. Tk also keeps a separate binding table for each canvas widget, which manages bindings created by the canvas's bind widget command. within that table, an object is either a pointer to the internal structure for a canvas item, or a Tk_Uid identifying a tag. two tables, two whole personalities. 💜

---

💫 Tk_CreateBindingTable 💫

this one creates a new binding table and associates interp with it — meaning when bindings in the table are invoked, the scripts get evaluated in interp. it returns a token for the table, and you must use that token in calls to the other procedures like Tk_CreateBinding or Tk_BindEvent. it's your hall pass. keep it safe. 🎀

💫 Tk_DeleteBindingTable 💫

frees all of the state associated with a binding table. and once it returns? the caller should not use the bindingTable token again. like, ever. that token is gone, bestie, we don't text it back. 💀

💫 Tk_CreateBinding 💫

adds a new binding to an existing table. the object argument identifies the object the binding is to be associated with, and it can be any one-word value — typically it's a pointer to a string or data structure. the eventString argument identifies the event, or the sequence of events, for the binding; peep the documentation for the bind command for a description of its format. script is the Tcl script to be evaluated when the binding triggers.

now, append — this is the "what if there's already a binding for object and eventString?" question. if append is zero, then script replaces the old script. if append is non-zero, the new script gets appended to the old one. ✨

Tk_CreateBinding returns an X event mask for all the events associated with the bindings. that info may be useful to invoke XSelectInput to select relevant events, or to disallow the use of certain events in bindings. and if an error occurred while creating the binding — e.g., eventString refers to a non-existent event — then 0 is returned and an error message is left as the result of interpreter interp. 😭

💫 Tk_DeleteBinding 💫

removes from bindingTable the binding given by object and eventString, if such a binding exists. Tk_DeleteBinding always returns TCL_OK. in some cases it may reset the interpreter result to the default empty value. no drama, just vibes. 🧚

💫 Tk_GetBinding 💫

returns a pointer to the script associated with eventString and object in bindingTable. if no such binding exists, then NULL is returned and an error message is left as the result of interpreter interp. 🙈

💫 Tk_GetAllBindings 💫

returns, in interp's result, a list of all the event strings for which there are bindings in bindingTable associated with object. if there are no bindings for object, the result will be an empty string. iconic empty-string representation. 💅

💫 Tk_DeleteAllBindings 💫

deletes all of the bindings in bindingTable that are associated with object. that's it. that's the whole thing. 🫶

💫 Tk_BindEvent 💫

this is the one you call 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.

Tk_BindEvent processes each of the objects pointed to by objectPtr, 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 bind, and invokes the script for that binding. if there are no matching bindings for a particular object, then the object is skipped. and Tk_BindEvent continues through all of the objects, handling exceptions such as errors, break, and continue as described in the documentation for bind. periodt. 👑

---

🌸 KEYWORDS 🌸

binding, event, object, script

---

no cap bestie — this whole page is from Tk version 4.0, and it's the Tk_CreateBindingTable(3tk) page, so that's the date/version tea right there. 💖✨