Legend C reference

See Legend ownership and layout for ownership, layout, placement, redraw and command contracts. These are internal services, not public stubs. The documentation namespaces below disambiguate static helper names without changing C linkage.

Creation and configuration

group Legend configuration and creation

Internal legend services; not part of the public stubs API.

Functions

static int IsLegendPositionPrefix(const char *string, Tcl_Size length, const char *fullName)

Recognize a nonempty case-sensitive placement keyword prefix.

Returns a boolean for the borrowed spelling and fullName. Empty and overlong spellings fail; does not allocate or change interpreter state.

Parameters:
  • string – [in] Borrowed candidate spelling, readable for length bytes.

  • length – [in] Candidate byte count; zero and overlong spellings do not match.

  • fullName – [in] Borrowed NUL-terminated canonical placement name.

static int GetLegendPositionFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, LegendPosition *positionPtr)

Parse a global placement into a temporary position record.

Empty input selects rightmargin. Accepts keyword prefixes, a dot-prefixed external path or @x,y with Tcl long expressions. The returned windowName borrows the object string. Returns TCL_OK or TCL_ERROR with a diagnostic; output may be partially initialized on error. Coordinate expressions can execute Tcl, so callers must maintain owner and argument lifetime.

Parameters:
  • interp – [in] Borrowed interpreter receiving results and diagnostics; see Interpreter arguments.

  • objPtr – [in] Borrowed non-NULL placement object; coordinate expressions may evaluate Tcl.

  • positionPtr – [out] Required staging record; may be partially written on error. windowName borrows objPtr storage.

static void SetLegendPositionObject(Legend *legendPtr, const char *value)

Replace the retained position object after an internal placement change.

Creates and retains a string object, swaps it into the legend and releases the previous reference. Does not parse placement, change site or schedule work.

Parameters:
  • legendPtr – [inout] Live legend whose retained position object is replaced.

  • value – [in] Borrowed NUL-terminated spelling copied into a newly retained Tcl string.

static int ConfigureLegend(Graph *graphPtr, Legend *legendPtr, int mask)

Prepare derived options and external placement before committing.

Candidate Tk fields are already installed. Validates nonnegative counts and widths, stages padding/shadow/position and prepares any new external window. Local positions use exact names and reject windows/coordinates. Commits derived state after ordinary failures are past, then resets style and schedules layout/redraw as the mask requires. Returns TCL_OK or TCL_ERROR, freeing staged resources on error. Caller restores Tk fields; callback side effects from expressions/window operations are not rolled back.

Parameters:
  • graphPtr – [inout] Borrowed live owning graph; mapping/redraw flags and external associations may change.

  • legendPtr – [inout] Initialized legend with candidate Tk fields; caller restores Tk saved options on error.

  • mask – [in] LEGEND_*_CHANGED bits selecting conversion, placement, text-style and layout work.

int Rbc_CreateLegend(Graph *graphPtr)

Create and configure the graph-owned legend and its binding table.

Requires a graph window and option proxy. Allocates zeroed storage, installs the graph pointer, initializes text style and component options under legend/Legend, then configures derived state. Returns TCL_OK on success. On failure destroys partial legend state and returns TCL_ERROR. Allocation is asserted; this is an internal constructor, not a public stubs API.

Parameters:
  • graphPtr – [inout] Live graph with option proxy and no global legend; owns the new record and bindings on success.

int Rbc_CreateTrackLegend(Graph *graphPtr, RbcTrack *track)

Create an opt-in local legend sharing graph event infrastructure.

Requires a track without an existing legend. Creates a private tag table, borrows or lazily creates trackLegendBindings and initializes component options under trackLegend/TrackLegend. Returns TCL_OK on success; failure destroys the partial local legend but retains the graph-owned shared table.

Parameters:
  • graphPtr – [inout] Live owning graph; shared local binding table may be created and retained even after failure.

  • track – [inout] Live graph member with no legend; receives the new record on success, NULL after failure.

struct LegendPosition

Staged position; windowName borrows the parsed Tcl object’s string.

Public Members

int site

Legend site selector.

Point2D anchorPos

Explicit position in widget pixels; negative values are resolved from the far edges.

const char *windowName

Borrowed Tk pathname for an external legend, or NULL.

Measurement and placement

group Legend measurement and placement

Internal legend services; not part of the public stubs API.

Functions

static int LegendLayoutSize(Tcl_WideInt value)

Clamp a wide layout dimension to a nonnegative int.

Nonpositive values return zero; larger positive values saturate at INT_MAX. No allocation or graph mutation occurs.

Parameters:
  • value – [in] Wide pixel dimension; nonpositive values become zero and large values saturate.

static int LegendCoordinate(double value)

Saturate a finite coordinate before conversion to int.

Values within int bounds truncate toward zero. The caller must exclude NaN; this helper does not report a conversion error.

Parameters:
  • value – [in] Pixel coordinate excluding NaN; finite values truncate toward zero within int bounds.

static int GetLegendPixelDimension(Tcl_Size count, int entrySize, int borderWidth, const Rbc_Pad *padPtr, int *dimensionPtr)

Check a cell-count dimension including border and exterior padding.

Returns TCL_OK and writes dimensionPtr only when all inputs are nonnegative and the complete dimension fits in int. Returns TCL_ERROR without changing output otherwise. Uses division before multiplication; performs no allocation.

Parameters:
  • count – [in] Number of cells along the requested dimension; negative values are rejected.

  • entrySize – [in] Pixel size per cell; zero is allowed, negative values are rejected.

  • borderWidth – [in] Pixel border thickness on each side; must be nonnegative.

  • padPtr – [in] Borrowed exterior padding with two nonnegative pixel widths.

  • dimensionPtr – [out] Required int output; unchanged if inputs or the complete size are invalid.

static int LegendHasElement(Legend *legendPtr, Element *elemPtr)

Test track membership independently of label or visibility.

A global legend accepts every borrowed element. A local legend accepts only elements with the same track pointer. Callers separately check label and display-list eligibility; no reference is acquired.

Parameters:
  • legendPtr – [in] Borrowed legend selecting global or one-track membership.

  • elemPtr – [in] Borrowed element whose track is compared; label and display membership are not tested.

static void SetLegendOrigin(Legend *legendPtr)

Compute legend placement from cached dimensions and its owning region.

Requires current graph/track geometry. Local placement uses full world bounds; global placement uses margins, plot bounds or screen coordinates. Negative explicit coordinates are relative to the graph window extent. Applies the anchor and padding with saturated arithmetic. External placement forces the NW anchor and origin zero. Does not remeasure entries.

Parameters:
  • legendPtr – [inout] Mapped legend with current owning-region geometry; cached origin and external anchor may change.

static int LegendEntryWidth(Legend *legendPtr, Element *elemPtr)

Return a compact single-row width or the uniform grid-cell width.

Borrows a labeled element and initialized text style. In one row, remeasures that label and adds entryInset; otherwise returns cached style.width. Mapping must already have validated the dimensions and label state.

Parameters:
  • legendPtr – [in] Mapped legend with initialized font/style and validated entry inset.

  • elemPtr – [in] Borrowed element with a non-NULL label; measured only for a single-row layout.

void Rbc_MapLegend(Legend *legendPtr, int plotWidth, int plotHeight)

Measure entries and replace cached legend dimensions.

Borrows an initialized legend and owning graph. plotWidth/plotHeight are available dimensions; an external window larger than one pixel overrides them. Resets layout first, then counts labeled display-list elements in scope. Single rows use individual widths; multiple rows use maximum-size cells. Unusable or overflowing dimensions leave an empty layout. Does not set the origin or draw; may request new external-window geometry.

Parameters:
  • legendPtr – [inout] Initialized legend with live graph and display-list elements; cached layout is replaced.

  • plotWidth – [in] Available pixel width; a usable external-window width overrides it.

  • plotHeight – [in] Available pixel height; a usable external-window height overrides it.

int Rbc_LegendSite(Legend *legendPtr)

Return the legend’s placement code.

Requires a non-NULL live legend. Reads site without remapping, scheduling work or acquiring a reference; cached geometry need not be current.

Parameters:
  • legendPtr – [in] Non-NULL live legend; reads cached state without refreshing layout or acquiring a reference.

int Rbc_LegendWidth(Legend *legendPtr)

Return the legend’s cached width.

Requires a non-NULL live legend. Reads width without remapping, scheduling work or acquiring a reference; cached geometry need not be current.

Parameters:
  • legendPtr – [in] Non-NULL live legend; reads cached state without refreshing layout or acquiring a reference.

int Rbc_LegendHeight(Legend *legendPtr)

Return the legend’s cached height.

Requires a non-NULL live legend. Reads height without remapping, scheduling work or acquiring a reference; cached geometry need not be current.

Parameters:
  • legendPtr – [in] Non-NULL live legend; reads cached state without refreshing layout or acquiring a reference.

int Rbc_LegendIsHidden(Legend *legendPtr)

Return the legend’s hidden flag.

Requires a non-NULL live legend. Reads hidden without remapping, scheduling work or acquiring a reference; cached geometry need not be current.

Parameters:
  • legendPtr – [in] Non-NULL live legend; reads cached state without refreshing layout or acquiring a reference.

int Rbc_LegendIsRaised(Legend *legendPtr)

Return the legend’s raised flag.

Requires a non-NULL live legend. Reads raised without remapping, scheduling work or acquiring a reference; cached geometry need not be current.

Parameters:
  • legendPtr – [in] Non-NULL live legend; reads cached state without refreshing layout or acquiring a reference.

int Rbc_LegendX(Legend *legendPtr)

Return the legend’s cached origin X.

Requires a non-NULL live legend. Reads x without remapping, scheduling work or acquiring a reference; cached geometry need not be current.

Parameters:
  • legendPtr – [in] Non-NULL live legend; reads cached state without refreshing layout or acquiring a reference.

int Rbc_LegendY(Legend *legendPtr)

Return the legend’s cached origin Y.

Requires a non-NULL live legend. Reads y without remapping, scheduling work or acquiring a reference; cached geometry need not be current.

Parameters:
  • legendPtr – [in] Non-NULL live legend; reads cached state without refreshing layout or acquiring a reference.

void Rbc_MapTrackLegends(Graph *graphPtr)

Map local legends after full track geometry is available.

Uses world widths/heights, then computes origins. Local legends do not reserve graph margins. Borrows graph and tracks, and does not draw or schedule redisplay; visible clipping is handled separately.

Parameters:
  • graphPtr – [inout] Borrowed graph with prepared full track world rectangles; local dimensions and origins are updated.

Picking and binding identity

group Legend picking and binding identity

Internal legend services; not part of the public stubs API.

Functions

static ClientData LegendTag(Legend *legendPtr, const char *name)

Intern a stable binding tag in the owning legend scope.

Global legends use the graph element-tag table; local legends use their own string-key table. Returns a borrowed key pointer valid until that table is destroyed. Identical strings in separate local tables have distinct binding identities.

Parameters:
  • legendPtr – [inout] Borrowed legend selecting the global or local tag registry; missing keys are interned.

  • name – [in] Borrowed NUL-terminated tag spelling; the registry owns its retained key.

static void LegendTags(Rbc_BindTable table, ClientData object, ClientData context, Rbc_List list)

Append name, class and configured tags for a picked legend entry.

Borrows the element object and destination list. Context identifies the legend; NULL context falls back to the graph-wide legend. Interns tags through LegendTag. Does not evaluate binding scripts or own the element.

Parameters:
  • table – [in] Borrowed binding table whose client data supplies the graph when context is NULL.

  • object – [in] Borrowed picked Element pointer, not a tag string.

  • context – [in] Borrowed owning Legend pointer, or NULL to use the global legend.

  • list – [inout] Caller-owned initialized tag list; stable borrowed keys are appended in binding order.

static ClientData PickLegendIn(Legend *legendPtr, int x, int y)

Return the borrowed element at a point within one mapped legend.

Recomputes origin, rejects hidden/empty legends and points outside a local track clip, then excludes outer borders and padding. One row scans measured widths; a grid uses column-major cell indices with overflow checks. Walks the display list in reverse, applying label and track filters. Returns NULL for no entry; does not update graph layout or acquire an element reference.

Parameters:
  • legendPtr – [inout] Borrowed mapped legend; origin may be recomputed, layout is not refreshed.

  • x – [in] Horizontal pixel coordinate in the legend drawing window, not relative to its origin.

  • y – [in] Vertical pixel coordinate in the same drawing window.

static int LegendContains(Legend *legendPtr, int x, int y)

Test the legend rectangle for occlusion, including blank areas.

Recomputes origin and rejects hidden/empty/unattached legends. Local legends additionally require the point inside visible track bounds. This boolean test deliberately differs from entry picking: padding can occlude content.

Parameters:
  • legendPtr – [inout] Borrowed mapped legend; origin may be recomputed, layout is not refreshed.

  • x – [in] Horizontal pixel coordinate in the legend drawing window, not relative to its origin.

  • y – [in] Vertical pixel coordinate in the same drawing window.

static Legend *LegendAtPoint(Graph *graphPtr, int x, int y)

Find the topmost in-widget legend rectangle at a graph point.

Requires a live graph-wide legend. Checks raised then non-raised layers, global before local within each layer, and tracks in list order. Excludes external windows. Returns a borrowed legend or NULL, without picking an entry.

Parameters:
  • graphPtr – [inout] Live graph with a global legend and prepared global/local layouts; tested origins may change.

  • x – [in] Horizontal graph-window pixel coordinate.

  • y – [in] Vertical graph-window pixel coordinate.

int Rbc_PointInLegend(Graph *graphPtr, int x, int y)

Test whether any in-widget legend occludes a graph point.

Delegates to LegendAtPoint, including blank legend areas. Does not remap the graph or test external legend windows.

Parameters:
  • graphPtr – [inout] Live graph with a global legend and prepared global/local layouts; tested origins may change.

  • x – [in] Horizontal graph-window pixel coordinate.

  • y – [in] Vertical graph-window pixel coordinate.

int Rbc_PointInTrackLegend(Graph *graphPtr, int x, int y)

Test whether the topmost legend at a graph point is local.

Returns false when a global legend occludes a local one. Uses current mapped geometry and borrows the graph; no binding scripts are run.

Parameters:
  • graphPtr – [inout] Live graph with a global legend and prepared global/local layouts; tested origins may change.

  • x – [in] Horizontal graph-window pixel coordinate.

  • y – [in] Vertical graph-window pixel coordinate.

static ClientData PickLegendEntry(ClientData clientData, int x, int y, ClientData *contextPtr)

Adapt global or external legend picking to the binding interface.

clientData is the graph. Writes the global legend to optional contextPtr, even if no entry is found. In-widget picking requires it to be topmost; external picking uses that window’s coordinates directly. Returns a borrowed element or NULL.

Parameters:
  • clientData – [inout] Borrowed Graph pointer supplied by the binding table.

  • x – [in] Horizontal event-window pixel coordinate; graph coordinates for local legends.

  • y – [in] Vertical event-window pixel coordinate.

  • contextPtr – [out] Optional output for the borrowed global legend, including when no item is found.

static ClientData PickTrackLegendEntry(ClientData clientData, int x, int y, ClientData *contextPtr)

Adapt local legend picking with an explicit legend context.

clientData is the graph and contextPtr must be writable. Stores the topmost legend, then returns a borrowed entry only if that legend is local. Context can identify a global legend even when the returned item is NULL.

Parameters:
  • clientData – [inout] Borrowed Graph pointer supplied by the binding table.

  • x – [in] Horizontal event-window pixel coordinate; graph coordinates for local legends.

  • y – [in] Vertical event-window pixel coordinate.

  • contextPtr – [out] Required output for the borrowed topmost legend or NULL; can identify a global legend with no returned item.

void Rbc_LegendRemoveElement(Legend *legendPtr, Element *elemPtr)

Forget an element object in global and shared local binding state.

Passes the borrowed element pointer to Rbc_DeleteBindings in both relevant tables, clearing current/new item state as needed. Does not remove interned string tags, erase tag scripts by name, free the element or edit display order.

Parameters:
  • legendPtr – [inout] Live legend identifying the global/shared-local binding state to clear.

  • elemPtr – [in] Borrowed element identity to forget; neither the record nor its string tags are freed.

Screen and document output

group Legend screen and document output

Internal legend services; not part of the public stubs API.

Functions

void Rbc_DrawLegend(Legend *legendPtr, Drawable drawable)

Compose a mapped legend in a temporary pixmap and copy it to output.

Requires live window, graph and element records and current layout. Clears DRAW_LEGEND even when hidden or empty. Sets origin, composes background, active/relief entry borders, element symbol callbacks, text and outer border. Local copies are intersected with the visible track rectangle. Frees the pixmap and closes the text context. Borrows entries; does not own elements or provide a mutation-safe snapshot across symbol callbacks.

Parameters:
  • legendPtr – [inout] Mapped legend with live window, graph and element records; origin and draw flags may change.

  • drawable – [in] Borrowed compatible destination receiving the composed legend; not freed by this call.

void Rbc_LegendExport(Legend *legendPtr, Rbc_ExportContext *exportPtr)

Emit mapped legend decoration, symbols and labels to an export backend.

Borrows legend, export context and displayed elements. Hidden/empty layouts emit nothing. Subtracts exterior padding from the output box, sets origin and handles decorations before visiting entries in column-major order. Uses each concrete element’s exportSymbolProc and closes its own output context. Local clipping and external-legend exclusion belong to callers.

Parameters:
  • legendPtr – [inout] Mapped legend with valid styles and displayed elements; origin is recomputed.

  • exportPtr – [inout] Borrowed initialized document context; caller supplies local clipping and finalization.

void Rbc_DrawTrackLegends(Graph *graphPtr, Drawable drawable, int raised)

Draw local legends in one requested raised layer.

Borrows tracks in list order. Selects legends with matching raised flag and a noncollapsed visible track rectangle; Rbc_DrawLegend handles hidden and empty legends and clips the final copy. Does not remap tracks.

Parameters:
  • graphPtr – [inout] Borrowed graph with mapped local legends and current visible track bounds.

  • drawable – [in] Borrowed compatible graph destination; each local copy is clipped to its visible track.

  • raised – [in] Exact raised flag to select, normally zero or one; not an arbitrary truth value.

void Rbc_ExportTrackLegends(Graph *graphPtr, Rbc_ExportContext *exportPtr, int raised)

Export a local legend layer within each visible track clip.

Selects matching raised flags and noncollapsed track rectangles. Opens an output context, pushes the inclusive visible rectangle as a clip, exports the legend, then balances clip/context cleanup. Does not remap track geometry.

Parameters:
  • graphPtr – [inout] Borrowed graph with mapped local legends and visible track bounds.

  • exportPtr – [inout] Borrowed initialized export context; each local clip is balanced before return.

  • raised – [in] Exact raised flag to select, normally zero or one.

Windows, scheduling and cleanup

group Legend window and resource lifetime

Internal legend services; not part of the public stubs API.

Functions

static void EventuallyRedrawLegend(Legend *legendPtr)

Coalesce a legend idle draw while its target window exists.

Schedules DisplayLegend only with a non-NULL window and no REDRAW_PENDING flag, then marks the request pending. Does not check whether the window is mapped; the idle handler does that. Caller must cancel before freeing records.

Parameters:
  • legendPtr – [inout] Live legend retained until idle delivery or cancellation; pending state is updated.

void Rbc_RedrawExternalLegend(Graph *graphPtr)

Schedule the global external legend’s independent redraw.

Borrows a graph whose legend may be absent. Does nothing for an absent, resource-released or non-window legend. Coalesces idle work without drawing synchronously or remapping the graph.

Parameters:
  • graphPtr – [inout] Borrowed graph whose global legend may be NULL; eligible external redraw is queued.

static int PrepareLegendWindow(Tcl_Interp *interp, Legend *legendPtr, const char *pathName, Tk_Window *tkwinPtr, Tcl_Command *cmdTokenPtr)

Create a candidate external window, command and event association.

Borrows interpreter, legend and path. The command forwards to the graph instance dispatcher; it is not a standalone legend dispatcher. Returns TCL_OK and writes both handles only on success. Returns TCL_ERROR after cleaning partial associations otherwise. The caller owns adoption/cleanup of successful candidates; no packing or mapping is performed.

Parameters:
  • interp – [in] Borrowed interpreter receiving results and diagnostics; see Interpreter arguments.

  • legendPtr – [in] Borrowed legend associated with the candidate window and graph-forwarding command.

  • pathName – [in] Borrowed NUL-terminated Tk window path.

  • tkwinPtr – [out] Required output for the new window; assigned only on success, caller adopts or destroys it.

  • cmdTokenPtr – [out] Required output for the new command; assigned only on success, caller adopts or deletes it.

static void CloseExternalLegendWindow(Legend *legendPtr)

Detach and destroy an external legend window before replacement.

No-op for an absent window or the graph window. Cancels idle work, resets stored handles before deleting the old command/window associations, and moves the binding table back to the graph. Does not set the new site or position object; the configuration caller completes that transition.

Parameters:
  • legendPtr – [inout] Live legend with graph and binding infrastructure; external associations are removed, record retained.

static void ReleaseLegendTkResources(Graph *graphPtr, Legend *legendPtr)

Release one legend’s Tk resources while the graph window is valid.

Accepts NULL and guards absent/already released option tables. Cancels idle work, frees text drawing resources before option fonts/colors, frees the separately acquired shadow, and releases options/table. Clears an in-widget window pointer but retains an external one for final destruction. Does not free the legend record or binding table.

Parameters:
  • graphPtr – [in] Owning graph with usable Tk window/display for option and drawing-resource cleanup.

  • legendPtr – [inout] Legend to release, or NULL; record and binding table are retained.

void Rbc_ReleaseLegendTkResources(Graph *graphPtr)

Release local and global legend options before window loss.

Requires the owning graph’s valid track list and Tk window context. Visits local legends first, then the optional global legend. Per-record guards prevent duplicate release; final destruction owns records and bindings.

Parameters:
  • graphPtr – [inout] Owning graph with valid track list and Tk cleanup context; records remain for final destruction.

static void LegendEventProc(ClientData clientData, XEvent *eventPtr)

Handle exposure, resize and destruction of the external legend window.

Coalesces exposes and configure events into idle draws. DestroyNotify removes command/instance associations, cancels pending work, restores rightmargin and its retained option string, moves bindings to the graph and requests graph remapping/redrawing. Borrows a live legend record.

Parameters:
  • clientData – [inout] Borrowed Legend pointer registered with the external window event handler.

  • eventPtr – [in] Borrowed exposure or structure event; not retained or modified.

static void DisplayLegend(ClientData clientData)

Consume an idle redraw and paint a mapped legend window.

Clears REDRAW_PENDING first. Missing windows are skipped. External windows of at most one pixel are skipped; changed dimensions trigger remapping. Unmapped windows are not painted. The scheduled record must remain live until the callback runs or is cancelled.

Parameters:
  • clientData – [inout] Scheduled Legend pointer retained by its owner until callback or cancellation.

static void DestroyLegend(Graph *graphPtr, Legend *legendPtr)

Free one legend after releasing resources and external associations.

Accepts NULL. Cancels idle work, releases Tk resources if the graph window still exists, and destroys any external command/window after clearing its stored handles. Local legends remove their private tag bindings and table; global legends destroy their owned binding table. Frees the record, but does not clear owner pointers or destroy the shared local binding table.

Parameters:
  • graphPtr – [inout] Owning graph; Tk resources must already be released if its window is gone.

  • legendPtr – [inout] Owned legend to free, or NULL; caller clears its owner pointer and retains shared local binding infrastructure.

void Rbc_DestroyLegend(Graph *graphPtr)

Destroy the global legend and shared local-legend binding table.

Clears graph-owned pointers. Local legends must already have been destroyed before their shared binding table disappears. Tk resources should have been released while the graph window was valid.

Parameters:
  • graphPtr – [inout] Owning graph after local legends are destroyed; global legend and shared binding pointers are cleared.

void Rbc_DestroyTrackLegend(Graph *graphPtr, RbcTrack *track)

Destroy a local legend and clear its track pointer.

Requires the shared local binding table to remain live. An absent legend is harmless. Releases local tag bindings, not the shared binding table; Tk resources must be released before window loss.

Parameters:
  • graphPtr – [inout] Owning graph whose shared local-legend binding table remains live.

  • track – [inout] Live owning track; its legend is freed if present and its pointer cleared.

void Rbc_LegendFontsChanged(Graph *graphPtr)

Refresh local/global text styles and external redraw scheduling.

Borrows graph and track records. Resets styles only when window and font are available; an external global legend receives an idle redraw request. Does not itself remap legends or schedule in-widget graph redisplay.

Parameters:
  • graphPtr – [inout] Borrowed graph with valid track list; available styles are reset and external redraw may be queued.

struct LegendStruct

Graph- or track-owned legend with borrowed elements and scoped bindings.

Owns option state, derived shadow/text resources and optional external associations. A local legend owns tags but borrows the shared event table; a global legend owns its binding table. Cached dimensions are not entry records: entries remain in the graph’s element display list.

Public Members

RbcTrack *track

NULL for the graph-wide legend.

Tcl_HashTable tags

Local binding tags, separate from global tags.

Tk_OptionTable optionTable

Tk option table for this component configuration lifecycle.

Tcl_Obj *activeBorderWidthObjPtr

Tk option-managed Tcl representation for active border width; released with the owning option state.

Tcl_Obj *borderWidthObjPtr

Tk option-managed Tcl representation for border width; released with the owning option state.

Tcl_Obj *columnsObjPtr

Tk option-managed Tcl representation for columns; released with the owning option state.

Tcl_Obj *ipadXObjPtr

Tk option-managed Tcl representation for ipad x; released with the owning option state.

Tcl_Obj *ipadYObjPtr

Tk option-managed Tcl representation for ipad y; released with the owning option state.

Tcl_Obj *padXObjPtr

Tk option-managed Tcl representation for pad x; released with the owning option state.

Tcl_Obj *padYObjPtr

Tk option-managed Tcl representation for pad y; released with the owning option state.

Tcl_Obj *positionObjPtr

Tk option-managed Tcl representation for position; released with the owning option state.

Tcl_Obj *rowsObjPtr

Tk option-managed Tcl representation for rows; released with the owning option state.

Tcl_Obj *shadowObjPtr

Tk option-managed Tcl representation for shadow; released with the owning option state.

int optionsInitialized

Nonzero after Tk option initialization.

int tkResourcesReleased

Nonzero after guarded Tk-resource release.

unsigned int flags

Legend state flags, including redraw scheduling.

Rbc_Uid classUid

Type: Element or Marker.

int hidden

If non-zero, don’t display the legend.

int raised

If non-zero, draw the legend last, above everything else.

int entryInset

Entry width excluding its label.

Tcl_Size nEntries

Number of element entries in table.

int width

Dimensions of the legend.

int height

Dimensions of the legend.

Tcl_Size nColumns

Number of columns and rows in legend.

Tcl_Size nRows

Number of columns and rows in legend.

int site

Legend placement selector: margin, plot, coordinates or external window.

Point2D anchorPos

Says how to position the legend.

Indicates the site and/or x-y screen coordinates of the legend. Used in conjunction with the anchor to determine its location.

Tk_Anchor anchor

Anchor of legend.

Used to interpret the positioning point of the legend in the graph

int x

Computed origin of legend.

int y

Computed origin of legend.

Graph *graphPtr

Borrowed owning graph.

Tcl_Command cmdToken

Token for graph’s widget command.

int reqColumns

Requested column count; zero allows automatic layout.

int reqRows

Requested row count; zero allows automatic layout.

Rbc_Pad ipadX

of pixels padding around legend entries

Rbc_Pad ipadY

of pixels padding around legend entries

Rbc_Pad padX

of pixels padding to exterior of legend

Rbc_Pad padY

of pixels padding to exterior of legend

Tk_Window tkwin

Optional external window to draw legend.

TextStyle style

Entry text style and owned GC.

int maxSymSize

Size of largest symbol to be displayed.

Used to calculate size of legend

Tk_3DBorder activeBorder

Active legend entry background color.

int activeRelief

3-D effect on active entry.

int entryBorderWidth

Border width around each entry in legend.

Tk_3DBorder border

3-D effect of legend.

int borderWidth

Width of legend 3-D border.

int relief

3-d effect of border around the legend: TK_RELIEF_RAISED etc.

Rbc_BindTable bindTable

Binding table used by this legend; local legends borrow the shared track table.

Command handlers

group Legend command dispatch

Internal legend services; not part of the public stubs API.

Functions

static int GetOp(Legend *legendPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Query the current entry or pick an entry at @x,y in this legend.

Uses normalized arguments with the selector at objv[3]. Hidden/empty layouts return TCL_OK without setting a name. Local current lookup checks binding context; coordinate lookup uses PickLegendIn. Does not resolve ordinary element-name strings. Malformed coordinates return TCL_ERROR with the parser diagnostic, even for hidden or empty legends. Valid queries with no matching entry return TCL_OK without setting a name.

Parameters:
  • legendPtr – [inout] Borrowed live legend selected by global or nested track dispatch.

  • interp – [in] Borrowed interpreter receiving results and diagnostics; see Interpreter arguments.

  • objc – [in] Validated count of four; selector is objv[3].

  • objv – [in] Borrowed normalized command vector; see Tcl command arguments.

static int ActivateOp(Legend *legendPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Set matching element label flags and return active names in scope.

Normalized operation name selects activation or deactivation. Matches patterns against the complete element table, filtered by track, and changes shared LABEL_ACTIVE flags. No patterns changes nothing. Returns a Tcl list of all active names in scope, in hash order, including undisplayed elements. Schedules graph/backing redraw for plot legends and cheaper legend redraw when appropriate; track graphs also refresh other copies of shared entries.

Parameters:
  • legendPtr – [inout] Borrowed live legend selected by global or nested track dispatch.

  • interp – [in] Borrowed interpreter receiving results and diagnostics; see Interpreter arguments.

  • objc – [in] Normalized count including operation at index two and zero or more patterns from index three.

  • objv – [in] Borrowed normalized command vector; see Tcl command arguments.

static int BindOp(Legend *legendPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

List interned tags or delegate a legend binding query/update.

Normalized arguments begin with the operation at objv[2]. With no tag, returns the owning tag table’s keys in hash order; these need not all have scripts. Otherwise interns the supplied tag and delegates remaining arguments to the shared binding service. Returns its Tcl status.

Parameters:
  • legendPtr – [inout] Borrowed live legend selected by global or nested track dispatch.

  • interp – [in] Borrowed interpreter receiving results and diagnostics; see Interpreter arguments.

  • objc – [in] Validated normalized count from three through six: optional tag, sequence and script.

  • objv – [in] Borrowed normalized command vector; see Tcl command arguments.

static int CgetOp(Legend *legendPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Return a retained legend option value through Tk.

Borrows a live legend and normalized option name at objv[3]. Returns TCL_OK with the value or TCL_ERROR from Tk. Does not configure or redraw.

Parameters:
  • legendPtr – [inout] Borrowed live legend selected by global or nested track dispatch.

  • interp – [in] Borrowed interpreter receiving results and diagnostics; see Interpreter arguments.

  • objc – [in] Validated count of four; option name is objv[3].

  • objv – [in] Borrowed normalized command vector; see Tcl command arguments.

static int ConfigureOp(Legend *legendPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Query options or apply a saved-options configuration transaction.

Normalized objc of three queries all options; four queries one. Other calls install candidate values with Tk_SetOptions and ConfigureLegend. Derived failure restores saved options while preserving the diagnostic; success frees saved options. Returns a Tcl status. Does not undo arbitrary application side effects from coordinate expressions or window callbacks.

Parameters:
  • legendPtr – [inout] Borrowed live legend selected by global or nested track dispatch.

  • interp – [in] Borrowed interpreter receiving results and diagnostics; see Interpreter arguments.

  • objc – [in] Normalized count: three queries all options, four queries one, otherwise option/value pairs start at three.

  • objv – [in] Borrowed normalized command vector; see Tcl command arguments.

int Rbc_LegendOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Validate and dispatch a graph-wide legend operation.

Borrows the complete graph-command argument vector, with operation at index two. Shared dispatch checks spelling and arity, then calls the selected handler. Returns TCL_OK/TCL_ERROR; this dispatcher adds no layout refresh or object-lifetime preservation around the handler.

Parameters:
  • graphPtr – [inout] Live graph with initialized global legend; enclosing caller owns lifetime protection.

  • interp – [in] Borrowed interpreter receiving results and diagnostics; see Interpreter arguments.

  • objc – [in] Full widget-command count; operation is at index two.

  • objv – [in] Borrowed full widget-command vector; see Tcl command arguments.

static int TrackLegendBboxOp(Legend *legendPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Return the clipped local legend box as x y width height.

Requires current track/legend layout and a local legend. Hidden, empty or fully clipped legends leave no result. Intersects the legend extent with inclusive visible track bounds and returns pixel dimensions, not right and bottom coordinates. Recomputes origin but does not remap.

Parameters:
  • legendPtr – [inout] Borrowed live local legend with current track layout.

  • interp – [in] Borrowed interpreter receiving results and diagnostics; see Interpreter arguments.

  • objc – [in] Validated count of three; unused by this handler.

  • objv – [in] Unused normalized command vector.

int Rbc_TrackLegendOp(Graph *graphPtr, RbcTrack *track, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Normalize a nested track-legend command and refresh layout before dispatch.

Requires a track with a live legend. Creates an owned normalized argument vector, validates operation/arity, refreshes layout and dispatches only on success, then releases the vector. Returns the Tcl status of the failing stage or handler. Borrows graph/track/legend; adds no preservation boundary around layout callbacks.

Parameters:
  • graphPtr – [inout] Live graph retained across layout callbacks by the enclosing caller.

  • track – [inout] Live graph member with an existing legend; borrowed across layout and handler dispatch.

  • interp – [in] Borrowed interpreter receiving results and diagnostics; see Interpreter arguments.

  • objc – [in] Full nested-command count; operation is at index four.

  • objv – [in] Borrowed nested command; a temporary adapted vector is freed before return. See Tcl command arguments.

struct LegendOpSpec

Shared dispatch header followed by a legend-specific handler pointer.

Public Members

Rbc_OpSpecHeader header

Operation name, total argument bounds and usage suffix.

RbcGrLegdOp *proc

Typed command handler for this operation.