Binding and picking C reference
All interfaces here are private. Objects, contexts and tag tokens are borrowed; the owning component supplies their lifetime. See Binding dispatch and picking for event order, picking priority, callback reentry and the distinction between objects and binding keys.
Binding table state
-
struct Rbc_BindTableStruct
Owned event-binding table with borrowed picked-object state.
The owner must defer destruction while dispatch or repicking is active, and clear object bindings before releasing objects. Item/context fields never retain component records.
Public Members
-
unsigned int flags
Binding-dispatch state bits used to guard repicking and synthetic transitions.
-
Tk_BindingTable bindingTable
Owned eagerly created Tk binding table; tag keys are pointer identities supplied by tagProc.
-
ClientData currentItem
Borrowed current picked object, or NULL.
-
ClientData currentContext
Borrowed context identifying the current picked object kind.
-
ClientData newItem
Borrowed pending Enter target, exposed while delivering Leave so deletion can invalidate it.
-
ClientData newContext
Borrowed context of the pending picked object.
-
ClientData focusItem
Borrowed object selected for keyboard/focus event dispatch, or NULL.
-
ClientData focusContext
Borrowed context of the focus object.
-
XEvent pickEvent
The event upon which the current choice of the current item is based.
Must be saved so that if the current item is deleted, we can pick another.
-
int activePick
The pick event has been initialized so that we can repick it.
-
int state
Last known modifier state.
Used to defer picking a new current object while buttons are down.
-
ClientData clientData
Borrowed owner passed to the picker and preserved by dispatch as required.
-
Tk_Window tkwin
Borrowed window on which event handlers are installed; must remain valid for handler removal.
-
Rbc_BindPickProc *pickProc
Borrowed picker callback returning an object and its context from screen coordinates.
-
Rbc_BindTagProc *tagProc
Borrowed tag collector callback appending stable tag keys to the supplied temporary list.
-
unsigned int flags
Internal dispatch callbacks
-
static void DoEvent(Rbc_BindTableStruct *bindPtr, XEvent *eventPtr, ClientData item, ClientData context)
Collect binding keys and synchronously dispatch one event through Tk.
Key events prefer an explicit focus object. Skips absent/dead windows and absent objects. Calls tagProc (or supplies all/item keys), copies keys to a stack array of up to 32 entries or an allocated array, then calls Tk_BindEvent. Releases only temporary list/array storage. Scripts can delete components; this helper does not preserve the owner or binding table itself.
- Parameters:
bindPtr – [inout] Table retained by its owner for the call.
eventPtr – [in] Borrowed real or synthesized event.
item – [in] Borrowed picked object, or NULL to skip delivery.
context – [in] Borrowed object type/owner discriminator.
-
static void PickCurrentItem(Rbc_BindTableStruct *bindPtr, XEvent *eventPtr)
Update the current object/context and synthesize crossing events.
Saves pointer state for later repicks. LeaveNotify clears the hit without calling pickProc. Both object and context participate in target comparison. Publishes the pending target before Leave so Rbc_DeleteBindings can cancel its subsequent Enter. Recursive repick during Leave saves the event but returns without another transition. Button state controls grab behavior.
- Parameters:
bindPtr – [inout] Table retained by the caller across callback execution.
eventPtr – [in] Pointer-location event, or the table’s saved pickEvent.
-
static void BindProc(ClientData clientData, XEvent *eventPtr)
Handle Tk key, button, crossing and motion events for object bindings.
Preserves the owner at bindPtr->clientData, not the binding table separately. Press repicks before dispatch; release dispatches before repicking with the post-release button state. Motion repicks then dispatches; key events use current/focus state. Owner cleanup must defer table destruction until return.
- Parameters:
clientData – [in] Binding table registered as the Tk event-handler data.
eventPtr – [inout] Borrowed event; release-state edits are restored.
Graph-specific callbacks
-
static void GraphTags(Rbc_BindTable table, ClientData object, ClientData context, Rbc_List list)
Append graph binding keys according to the explicit object context.
Axes/elements/markers append name, class and configured tags using separate component token tables. Tracks append the track pointer and private all-track token. Does not evaluate Tcl or take ownership of the appended keys.
- Parameters:
table – [in] Graph-owned binding table.
object – [in] Borrowed axis, element, marker or track.
context – [in] Encoded GraphBindContext; no shared record prefix is assumed.
list – [inout] Temporary one-word-key list owned by event dispatch.
-
static ClientData PickEntry(ClientData clientData, int x, int y, ClientData *contextPtr)
Hit-test graph components and return a borrowed object/context pair.
Pending full mapping can invoke axis format callbacks. Local legend rectangles exclude graph hits. Margins select axes; the plot tests above-markers, eligible elements, under-markers and finally track backgrounds. Elements use their own closestProc under the owning track viewport, skipping dirty/pending vector geometry. The caller must retain the graph across callback-capable layout.
- Parameters:
clientData – [in] Graph retained by the binding dispatcher or repick caller.
x – [in] Window-relative horizontal pixel coordinate.
y – [in] Window-relative vertical pixel coordinate.
contextPtr – [out] Encoded GraphBindContext on a hit, otherwise NULL.
- Returns:
Borrowed component or NULL for no hit/layout cancellation.