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.

Shared interface

typedef struct Rbc_BindTableStruct *Rbc_BindTable

Owner-managed binding table; destroy with Rbc_DestroyBindingTable().

typedef ClientData Rbc_BindPickProc(ClientData clientData, int x, int y, ClientData *contextPtr)

Return a borrowed object at window-relative pixel coordinates.

clientData is the owner supplied at construction. Set contextPtr to the object’s type or owner context; object and context together identify the target. Return NULL for no hit. The callback must not destroy the binding table. Any callback-capable layout it performs needs owner lifetime protection.

typedef void Rbc_BindTagProc(Rbc_BindTable bindTable, ClientData object, ClientData context, Rbc_List list)

Append ordered binding-key pointers for a borrowed object/context.

list is a temporary one-word-key list owned by dispatch. Append keys without destroying the list or transferring ownership of the key storage. Keys must remain valid for Tk_BindEvent; this callback should not evaluate Tcl scripts.

The picker writes an object context alongside its returned pointer. The tag collector appends stable keys to the temporary list supplied by dispatch; neither callback acquires ownership of its arguments.

Rbc_BindTable Rbc_CreateBindingTable(Tcl_Interp *interp, Tk_Window tkwin, ClientData clientData, Rbc_BindPickProc *pickProc, Rbc_BindTagProc *tagProc)

Create an empty binding table and register its Tk event handler.

Owner destruction must cooperate with Tcl_Preserve/Tcl_Release and defer freeing this table while dispatch is active. Construction does not select an initial current item or retain the owner/window.

Parameters:
  • interp – [in] Interpreter used by Tk’s binding table.

  • tkwin – [in] Borrowed live window for key, button, crossing and motion events.

  • clientData – [in] Borrowed owner; event dispatch preserves this address.

  • pickProc – [in] Required hit-test callback.

  • tagProc – [in] Optional tag collector; NULL uses the all UID then the item.

Returns:

Owner-managed table; allocation failure is not a recoverable result.

void Rbc_DestroyBindingTable(Rbc_BindTable table)

Delete the Tk bindings, unregister the event handler and free a table.

Does not free the owner, objects or tag-key storage. Frees immediately, so the owner must defer this call until active dispatch/repick calls finish.

Parameters:
  • table – [in] Non-NULL live table, with its registered window still valid for Tk_DeleteEventHandler.

int Rbc_ConfigureBindingsFromObj(Tcl_Interp *interp, Rbc_BindTable table, ClientData item, Tcl_Size objc, Tcl_Obj *const *objv)

Query or change bindings for one pointer-identity binding key.

Zero arguments lists sequences, one queries a sequence, two set it. An empty script deletes the binding; leading ‘+’ appends. Unsupported event masks remove the newly created binding and return an error, without rollback of an earlier binding replaced by that call. No binding script is evaluated here.

Parameters:
  • interp – [in] Interpreter receiving the result or diagnostic.

  • table – [inout] Live binding table.

  • item – [in] Stable key, which can be a tag token rather than an object.

  • objc – [in] Number of arguments; caller validates the supported range 0..2.

  • objv – [in] Borrowed sequence and optional script objects.

Returns:

TCL_OK or TCL_ERROR with interpreter result from this operation/Tk.

void Rbc_PickCurrentItem(Rbc_BindTable table)

Repick using the last saved pointer event, if one exists.

Can synchronously run Leave and Enter scripts. Does not query the pointer, schedule idle work, or acquire a preserve scope. The caller must retain the owner/table and revalidate component/window state after callback execution.

Parameters:
  • table – [inout] Live table retained by its owner throughout this call.

void Rbc_DeleteBindings(Rbc_BindTable table, ClientData object)

Delete one key’s bindings and clear matching saved object pointers.

Clears matching current, pending and focus objects together with their contexts. Does not free the object, evaluate scripts or immediately repick. Distinct name/class/tag keys are not removed merely because an object using those keys is deleted; the owning component manages that tag policy.

Parameters:
  • table – [inout] Live table.

  • object – [in] Binding key and/or object identity to remove.

void Rbc_MoveBindingTable(Rbc_BindTable table, Tk_Window tkwin)

Move the event-handler registration to another live window.

Preserves Tk bindings, owner, current/focus targets and the saved pick event. Does not remap coordinates or repick. The owner manages geometry and lifetime when moving between graph and external-legend windows.

Parameters:
  • table – [inout] Live table; any old registered window must still be valid.

  • tkwin – [in] Borrowed non-NULL destination window.

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.