Graph lifecycle C reference

These are private interfaces. Shared contracts live at their header declarations; static lifecycle helpers are documented next to their definitions. This section covers lifecycle callbacks, option transactions, command routing and screen composition helpers.

Widget ownership and layout records

typedef struct GraphStruct Graph
struct GraphStruct

Shared widget owner for graph, bar, strip, polar and track plots.

Graph is the typedef for this record. It owns component registries, layout and screen caches. Tcl callbacks can destroy the Tk window before deferred record cleanup; borrowed interp/display pointers do not extend their lifetime.

Public Members

int axisFormatActive

Nonzero during a synchronous axis label callback.

int axisFormatInvalid

Nonzero when a label callback invalidates the current mapping.

struct GraphRedrawSettle *redrawSettle

Owned pending resize/exposure settling state, or NULL.

unsigned int flags

Flags; see below for definitions.

Tcl_Interp *interp

Borrowed interpreter owning the widget command.

Tk_Window tkwin

Window that embodies the graph.

NULL means that the window has been destroyed but the data structures haven’t yet been cleaned up.

Display *display

Borrowed display retained for resource cleanup after tkwin is gone.

Tcl_Command cmdToken

Token for graph’s widget command.

Tk_OptionTable optionTable

Tk option table associated with this record; managed by its configuration lifecycle.

Tk_Window optionProxy

Owned anonymous Tk option-database lookup window for graph pseudo-components.

Tcl_Obj *barModeObjPtr

Tk option-managed Tcl representation for bar mode; released with option state.

Tcl_Obj *borderWidthObjPtr

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

Tcl_Obj *bottomMarginObjPtr

Tk option-managed Tcl representation for bottom margin; released with option state.

Tcl_Obj *haloObjPtr

Tk option-managed Tcl representation for halo; released with option state.

Tcl_Obj *heightObjPtr

Tk option-managed Tcl representation for height; released with option state.

Tcl_Obj *highlightWidthObjPtr

Tk option-managed Tcl representation for highlight width; released with option state.

Tcl_Obj *leftMarginObjPtr

Tk option-managed Tcl representation for left margin; released with option state.

Tcl_Obj *plotBorderWidthObjPtr

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

Tcl_Obj *plotPadXObjPtr

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

Tcl_Obj *plotPadYObjPtr

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

Tcl_Obj *rightMarginObjPtr

Tk option-managed Tcl representation for right margin; released with option state.

Tcl_Obj *shadowObjPtr

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

Tcl_Obj *tileObjPtr

Tk option-managed Tcl representation for tile; released with option state.

Tcl_Obj *topMarginObjPtr

Tk option-managed Tcl representation for top margin; released with option state.

Tcl_Obj *widthObjPtr

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

unsigned int optionMask

Change mask from the current option transaction.

Tcl_Size optionObjc

Number of objects in the current borrowed configure argument slice.

Tcl_Obj *const *optionObjv

Borrowed configure arguments, valid only during the synchronous configuration transaction.

int optionsConfigured

Nonzero after the first successful configuration.

int optionsInitialized

Nonzero once Tk option initialization has completed.

int tkResourcesReleased

Nonzero after the guarded Tk-resource release pass.

char *data

Tk option-managed application data string; interpreted by Tcl bindings, not C drawing code.

Tk_Cursor cursor

Tk option-managed widget cursor.

int inset

Sum of focus highlight and 3-D border.

Indicates how far to offset the graph from outside edge of the window.

int borderWidth

Width of the exterior border.

int relief

Relief of the exterior border.

Tk_3DBorder border

3-D border used to delineate the plot surface and outer edge of window

int highlightWidth

Width in pixels of highlight to draw around widget when it has the focus.

<= 0 means don’t draw a highlight.

XColor *highlightBgColor

Color for drawing traversal highlight area when highlight is off.

XColor *highlightColor

Color for drawing traversal highlight.

char *title

Tk option-managed graph title string.

int titleX

Mapped title anchor X in widget pixels.

int titleY

Mapped title anchor Y in widget pixels.

TextStyle titleTextStyle

Graph title.

char *takeFocus

Tk option-managed focus traversal script/value.

int reqWidth

Requested widget width in pixels.

int reqHeight

Requested widget height in pixels.

int width

Current drawing width in pixels; temporarily changed during resized export.

int height

Current drawing height in pixels; temporarily changed during resized export.

Tcl_HashTable penTable

Table of pens.

struct Component elements

Owned element registry, display order and binding tags.

struct Component markers

Owned marker registry, display order and binding tags.

struct Component axes

Owned axis registry, display order and binding tags.

Rbc_Uid classUid

Default element type.

Rbc_BindTable bindTable

Owned component binding/picking table; component pointers in it are borrowed.

int nextMarkerId

Tracks next marker identifier available.

Rbc_Chain *axisChain[4]

Chain of axes for each of the margins.

They’re separate from the margin structures to make it easier to invert the X-Y axes by simply switching chain pointers.

Margin margins[4]

Four margin records indexed by MARGIN_* constants.

int pdfWidth

Requested PDF export width in pixels.

int pdfHeight

Requested PDF export height in pixels.

int pdfDecorations

Nonzero includes PDF plot decorations.

int pdfEmbedFonts

Nonzero embeds PDF font resources.

int svgWidth

Requested SVG export width in pixels.

int svgHeight

Requested SVG export height in pixels.

int svgDecorations

Nonzero includes SVG plot decorations.

int svgEmbedFonts

Nonzero embeds SVG font resources.

PostScript *postscript

Owned PostScript configuration record.

Legend *legend

Owned global legend record.

Rbc_BindTable trackLegendBindings

Owned binding table shared by local legends; picked records remain borrowed.

Crosshairs *crosshairs

Owned crosshair state.

Grid *gridPtr

Owned graph-wide grid configuration and caches.

int halo

Maximum distance allowed between points when searching for a point.

int inverted

If non-zero, indicates the x and y axis positions should be inverted.

Rbc_Tile tile

Retained tile client token for widget backgrounds.

GC drawGC

Used for drawing on the margins.

This includes the axis lines

GC fillGC

Used to fill the background of the margins.

The fill is governed by the background color or the tiled pixmap.

int plotBorderWidth

Width of interior 3-D border.

int plotRelief

3-d effect: TK_RELIEF_RAISED etc.

XColor *plotBg

Color of plotting surface.

GC plotFillGC

Used to fill the plotting area with a solid background color.

The fill color is stored in “plotBg”.

double aspect

If non-zero, force plot to conform to aspect ratio W/H.

int polarAutoAspect

If non-zero, Polar/Smith layout preserves equal physical X/Y data-unit scales.

PolarRepresentation representation

Polar or Smith presentation selector; data coordinates remain Cartesian.

XColor *trackSeparatorColor

NULL disables visible track dividers.

int trackSeparatorWidth

Track divider stroke width in pixels.

int trackScroll

Preserve requested track sizes instead of fitting.

Tcl_Obj *trackScrollCmdObj

Retained Tcl scrollbar callback prefix, or NULL; governed by widget options.

double trackOffset

Track-stack scroll offset in pixels along the stacking direction.

double trackExtent

Total laid-out track-stack extent in pixels.

double trackFirst

First fraction last reported to the track scrollbar callback.

double trackLast

Last fraction last reported to the track scrollbar callback.

int trackResize

Enable the optional Trackgraph class drag bindings.

int trackGraph

Named, vertically stacked plot regions.

RbcTrack *tracks

Owned linked track records.

RbcTrack *activeTrack

Borrowed track temporarily selected for component mapping/drawing, or NULL.

int left

Left edge of the plot bounding box in widget pixels.

int right

Right edge of the plot bounding box in widget pixels.

int top

Top edge of the plot bounding box in widget pixels.

int bottom

Bottom edge of the plot bounding box in widget pixels.

Rbc_Pad padX

Horizontal plot padding in pixels (left and right).

int vRange

Positive vertical mapping span in pixels.

int vOffset

Vertical mapping origin below the top plot padding, in pixels.

Rbc_Pad padY

Vertical plot padding in pixels (top and bottom).

int hRange

Positive horizontal mapping span in pixels.

int hOffset

Horizontal mapping origin after the left plot padding, in pixels.

double vScale

Reciprocal of vRange for normalized inverse mapping.

double hScale

Reciprocal of hRange for normalized inverse mapping.

int antialias

Rbc_Antialias; applies to Cairo geometry.

struct Rbc_RenderTarget *renderTarget

Borrowed active synchronous renderer marker-pass target; released by the pass owner.

int renderer

Rbc_Renderer selected by -renderer.

int doubleBuffer

If non-zero, draw the graph into a pixmap first to reduce flashing.

int backingStore

If non-zero, cache elements by drawing them into a pixmap.

Pixmap backPixmap

Pixmap used to cache elements displayed.

If backingStore is non-zero, each element is drawn into this pixmap before it is copied onto the screen. The pixmap then acts as a cache (only the pixmap is redisplayed if the none of elements have changed). This is done so that markers can be redrawn quickly over elements without redrawing each element.

int backWidth

Allocated backing-store width in pixels.

int backHeight

Allocated backing-store height in pixels.

double baseline

Baseline from bar chart.

double barWidth

Graph-level fallback bar width in data units.

BarMode mode

BarMode selector for coincident bars, including overlap.

FreqInfo *freqArr

Contains information about duplicate x-values in bar elements (malloc-ed).

This information can also be accessed by the frequency hash table

Tcl_HashTable freqTable

Group-key index into the graph-owned freqArr; does not separately own the array entries.

Tcl_Size nStacks

Number of entries in frequency array.

If zero, indicates nothing special needs to be done for “stack” or “align” modes

char *dataCmd

Tk option-managed data-command string; currently stored but not invoked by C code.

struct Component

Graph-owned registry, painter order and binding-tag storage.

The graph initializes and destroys these containers; component teardown releases the records they index.

Public Members

Tcl_HashTable table

Name-to-component registry; entries index the owning graph component records.

Rbc_Chain *displayList

Owned chain of borrowed component pointers in traversal/painter order.

Tcl_HashTable tagTable

Owned binding-tag registry; tag identities must remain valid during binding dispatch.

struct Margin

Computed and requested layout for one graph margin.

Axis chains are shared with the graph axis layout; margin output variables can invoke Tcl traces when updated.

Public Members

int width

Computed horizontal margin extent in pixels.

int height

Computed vertical margin extent in pixels.

int axesOffset

Pixel offset used when laying out successive margin axes.

int axesTitleLength

Maximum axis title length contributing to the margin requirement.

Tcl_Size nAxes

Number of displayed axes in this margin.

Rbc_Chain *axes

Borrowed axis chain selected from the graph axis chains.

char *varName

Optional Tcl variable name receiving the computed margin size.

int reqSize

Requested margin thickness in pixels.

int site

MARGIN_BOTTOM, MARGIN_LEFT, MARGIN_TOP or MARGIN_RIGHT.

Shared entry points

void Rbc_EventuallyRedrawGraph(Graph *graphPtr)

Coalesce a graph redraw request into the Tcl idle queue.

If its window exists and REDRAW_PENDING is clear, queue DisplayGraph, set REDRAW_PENDING and request external-legend redraw. An unmapped window can still be queued. During axis formatting, mark the current layout invalid. Does not set geometry or backing-store dirty flags: callers set those separately. Window destruction cancels pending graph display callbacks.

Parameters:
  • graphPtr – [inout] Non-NULL graph record, valid throughout the call.

int Rbc_LayoutGraph(Graph *graphPtr)

Update pending axis ranges, margins and mapped component geometry.

Axis label callbacks may execute Tcl and destroy or reconfigure the widget. Stop immediately on error before using cached component pointers. This is not a transaction: some layout work may already have occurred. Small plot ranges can leave mapping pending even when TCL_OK is returned. Does not draw, schedule a redraw, or acquire a Tcl_Preserve scope for the caller.

Parameters:
  • graphPtr – [inout] Borrowed graph, kept alive by the caller.

Returns:

TCL_OK on completion; TCL_ERROR on recursive layout or callback cancellation, with an interpreter diagnostic and RBC GRAPH CALLBACK code.

int Rbc_GraphCallbackValid(Graph *graphPtr)

Test window existence and axis-format cancellation state.

This is not a general pointer-validity or component-lifetime test. A Tcl_Preserve scope can retain the graph record after its Tk resources have been released; it cannot make a destroyed widget usable again.

Parameters:
  • graphPtr – [in] Non-NULL graph whose storage is still alive.

Returns:

TRUE if the window exists and axisFormatInvalid is false; otherwise FALSE with an interpreter diagnostic and RBC GRAPH CALLBACK error code.

void Rbc_DrawGraph(Graph *graphPtr, Drawable drawable, int backingStore)

Paint mapped graph content and decorations into a borrowed drawable.

Does not perform layout or present the frame with crosshairs. May allocate or replace the backing pixmap and consume REDRAW_BACKING_STORE. Polar label formatting can cancel drawing; callers must check Rbc_GraphCallbackValid() before presenting the drawable. The caller retains graph lifetime across callbacks. Partial drawing on cancellation is not rolled back.

Parameters:
  • graphPtr – [inout] Live graph with current layout and drawing resources.

  • drawable – [in] Compatible window or pixmap in widget coordinates.

  • backingStore – [in] Nonzero to reuse/update the graph-owned plot pixmap.

Internal lifecycle callbacks

static void GraphEventProc(ClientData clientData, XEvent *eventPtr)

Translate Tk events into redraw requests and deferred destruction.

Expose/resize use ancestry-settled idle drawing; focus uses ordinary idle drawing. DestroyNotify releases window-dependent resources before clearing tkwin, deletes the widget command, cancels both display idle callbacks and schedules DestroyGraph through Tcl_EventuallyFree.

Parameters:
  • clientData – [in] Graph record registered with Tk_CreateEventHandler.

  • eventPtr – [in] Borrowed event; never retained.

static void GraphInstCmdDeleteProc(ClientData clientData)

Release Tk-dependent resources and destroy a command’s live window.

No-op once tkwin is NULL. Clear the borrowed window cursor before releasing option resources, then clear tkwin before Tk_DestroyWindow can reenter the destruction path. DestroyNotify schedules final record disposal.

Parameters:
  • clientData – [in] Graph record owned by the widget lifecycle.

static void DestroyGraph(DestroyData dataPtr)

Dispose of the graph record after outstanding preserves are released.

Destroy components in dependency order (markers/elements before tracks, axes and pens), then bindings, legend, drawing resources and the record. Normal window destruction has already released Tk-dependent options and cancelled idle work. The option cleanup fallback requires a valid tkwin. Does not accept NULL and must not be called on an actively used graph.

Parameters:
  • dataPtr – [in] Graph record transferred to this Tcl_FreeProc.

static void DisplayGraphFrame(ClientData clientData)

Build one screen frame after the idle request is consumed.

Clear REDRAW_PENDING even when drawing is deferred for vector notifications or skipped during axis formatting. Sample Tk dimensions and lay out before testing whether the window is mapped. Buffered drawing composes crosshairs before presentation; direct drawing uses their erase/update/enable cycle. Successful frames queue view-change events and update margin/view callbacks.

Parameters:
  • clientData – [in] Graph retained by the DisplayGraph wrapper.

static void DisplayGraph(ClientData clientData)

Run idle drawing with graph/interpreter lifetime and result protection.

Preserve both records and save the interpreter state around DisplayGraphFrame. Restore the interpreter state before releasing the records; do not use them after release. Preservation protects storage, not Tk resources or components that callbacks may destroy. Frame code must still validate callback state.

Parameters:
  • clientData – [in] Graph record belonging to the pending idle request.

Widget option transactions

static int GetGraphOptionFromObj(Tcl_Obj *objPtr, const GraphOptionName *optionMap, size_t nOptions)

Classify a canonical graph option through a private map.

Borrows the object and map. Unknown or ambiguous names, and options absent from the map, return zero; this helper does not report an interpreter error.

Parameters:
  • objPtr – [in] Borrowed Tcl option object; no reference is retained.

  • optionMap – [in] Borrowed array mapping canonical graph options to private selectors.

  • nOptions – [in] Number of entries accessible in optionMap.

static int IsGraphOption(Tcl_Obj *objPtr, const char *optionName)

Compare an option spelling with one canonical graph option.

Resolves aliases and unambiguous abbreviations through graphOptionSpecs. Returns false if resolution fails; neither argument is retained.

Parameters:
  • objPtr – [in] Borrowed Tcl option object; no reference is retained.

  • optionName – [in] Borrowed canonical option name to compare against the resolved spelling.

static GraphPixelOption GetGraphPixelOption(Tcl_Obj *objPtr)

Identify a retained graph distance option.

Returns GRAPH_PIXEL_OPTION_NONE for other or unresolved options. The classification is used both for explicit-override masks and ordered parsing.

Parameters:
  • objPtr – [in] Borrowed Tcl option object; no reference is retained.

static Tcl_Obj *GetGraphPixelObject(Graph *graphPtr, GraphPixelOption option)

Borrow the retained Tcl object for a graph distance.

Does not change its reference count. The option must be a valid distance selector; invalid selectors panic rather than returning a recoverable error.

Parameters:
  • graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • option – [in] Valid selector identifying the distance or padding field to access.

static int StageGraphPixelOption(Graph *graphPtr, Tcl_Obj *objPtr, GraphPixelOption option, GraphPixelTransaction *transactionPtr)

Parse one distance into a candidate transaction.

Uses the graph window for unit conversion. All distances except highlight thickness require nonnegative values; highlight thickness uses Tk conversion directly. On success sets the selected field and mask bit; on conversion error leaves that candidate unchanged and returns TCL_ERROR.

Parameters:
  • graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • objPtr – [in] Borrowed proposed option value; parsed before replacing the candidate.

  • option – [in] Valid selector identifying the distance or padding field to access.

  • transactionPtr – [inout] Initialized candidate record updated only after successful parsing; retains prior candidate on failure.

static int PrepareGraphPixelTransaction(Graph *graphPtr, GraphPixelTransaction *transactionPtr)

Prepare distance values without changing live numeric fields.

Requires an even borrowed option vector in the graph context. Zeroes the transaction, parses unoverridden retained defaults on first configuration, then parses every explicit occurrence in caller order. An invalid earlier occurrence fails even if a later occurrence is valid. Partial candidates on error own no resources and can be discarded.

Parameters:
  • graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • transactionPtr – [out] Caller-owned fresh candidate record, initialized here; success requires commit or cleanup as described above.

static void CommitGraphPixelTransaction(Graph *graphPtr, GraphPixelTransaction *transactionPtr)

Publish only staged graph distances.

Copies selected integers into graph and margin fields, then clears the mask. No conversion, geometry request or redraw occurs here.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • transactionPtr – [inout] Prepared candidate record consumed into live fields and disarmed; record storage remains caller-owned.

static GraphPaddingOption GetGraphPaddingOption(Tcl_Obj *objPtr)

Identify retained X or Y plot padding.

Returns GRAPH_PADDING_OPTION_NONE for other or unresolved options. The input object remains caller-owned.

Parameters:
  • objPtr – [in] Borrowed Tcl option object; no reference is retained.

static Tcl_Obj *GetGraphPaddingObject(Graph *graphPtr, GraphPaddingOption option)

Borrow the retained Tcl object for plot padding.

Returns the X or Y object without retaining it. Invalid selectors panic.

Parameters:
  • graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • option – [in] Valid selector identifying the distance or padding field to access.

static int StageGraphPaddingOption(Graph *graphPtr, Tcl_Obj *objPtr, GraphPaddingOption option, GraphPaddingTransaction *transactionPtr)

Parse one plot-padding candidate.

Rbc_GetPadFromObj validates using the graph window. On success stores the padding and sets its mask bit; on error reports TCL_ERROR without publishing any live padding. The selector must be X or Y.

Parameters:
  • graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • objPtr – [in] Borrowed proposed option value; parsed before replacing the candidate.

  • option – [in] Valid selector identifying the distance or padding field to access.

  • transactionPtr – [inout] Initialized candidate record updated only after successful parsing; retains prior candidate on failure.

static int PrepareGraphPaddingTransaction(Graph *graphPtr, GraphPaddingTransaction *transactionPtr)

Prepare both plot-padding fields in caller order.

Zeroes the transaction and requires an even borrowed option vector. First configuration parses defaults only for axes without an explicit override. Every explicit occurrence is validated, including superseded ones. Partial candidates on failure require no resource cleanup.

Parameters:
  • graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • transactionPtr – [out] Caller-owned fresh candidate record, initialized here; success requires commit or cleanup as described above.

static void CommitGraphPaddingTransaction(Graph *graphPtr, GraphPaddingTransaction *transactionPtr)

Publish staged plot padding and clear its mask.

Unstaged axes keep their current padding. This helper does not request layout or redraw.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • transactionPtr – [inout] Prepared candidate record consumed into live fields and disarmed; record storage remains caller-owned.

static int GetGraphBarModeFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, BarMode *modePtr)

Parse a graph-wide bar mode with Tcl abbreviation rules.

Normal and infront map to MODE_INFRONT. Writes the destination only on success; invalid or ambiguous names return TCL_ERROR with a diagnostic.

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

  • objPtr – [in] Borrowed Tcl option object; no reference is retained.

  • modePtr – [out] Required output receiving the parsed bar mode only on success.

static int StageGraphBarMode(Graph *graphPtr, Tcl_Obj *objPtr, GraphBarModeTransaction *transactionPtr)

Validate and retain one candidate bar mode.

Updates the transaction only after successful conversion. Neither the input object nor a resource is retained; the live mode is unchanged.

Parameters:
  • graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • objPtr – [in] Borrowed proposed option value; parsed before replacing the candidate.

  • transactionPtr – [inout] Initialized candidate record updated only after successful parsing; retains prior candidate on failure.

static int PrepareGraphBarModeTransaction(Graph *graphPtr, GraphBarModeTransaction *transactionPtr)

Prepare the graph-wide mode from defaults and explicit options.

Zeroes the transaction. On first configuration, uses the retained default only when no explicit mode occurs. Parses all explicit occurrences in order and stops at the first error; the borrowed option vector must be even.

Parameters:
  • graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • transactionPtr – [out] Caller-owned fresh candidate record, initialized here; success requires commit or cleanup as described above.

static void CommitGraphBarModeTransaction(Graph *graphPtr, GraphBarModeTransaction *transactionPtr)

Publish a staged bar mode.

Leaves the live mode unchanged when unstaged and clears the staged flag after copying. No mapping or drawing is performed.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • transactionPtr – [inout] Prepared candidate record consumed into live fields and disarmed; record storage remains caller-owned.

static void FreeGraphShadow(Shadow *shadowPtr)

Release an owned title-shadow color and reset its value.

Accepts a non-NULL Shadow record whose color may be NULL. Clears both color and offset, allowing repeated cleanup of the same record.

Parameters:
  • shadowPtr – [inout] Owned shadow value whose color is released and fields reset; record storage remains caller-owned.

static int StageGraphShadow(Graph *graphPtr, Tcl_Obj *objPtr, GraphShadowTransaction *transactionPtr)

Acquire a replacement title shadow before discarding a candidate.

On parse failure returns TCL_ERROR and keeps the prior candidate. On success releases any previously staged shadow, owns the new color in the transaction and marks it staged. The live title style is not changed.

Parameters:
  • graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • objPtr – [in] Borrowed proposed option value; parsed before replacing the candidate.

  • transactionPtr – [inout] Initialized candidate record updated only after successful parsing; retains prior candidate on failure.

static void FreeGraphShadowTransaction(GraphShadowTransaction *transactionPtr)

Discard an uncommitted shadow candidate.

Releases its color when staged and zeroes the complete transaction. Safe for a zero-initialized or already committed transaction.

Parameters:
  • transactionPtr – [inout] Initialized candidate record whose staged resources are released and fields cleared.

static int PrepareGraphShadowTransaction(Graph *graphPtr, GraphShadowTransaction *transactionPtr)

Prepare an owned shadow candidate from retained options.

Requires a fresh transaction and an even borrowed argument vector. First configuration uses the default only if not overridden. Processes explicit occurrences in order. On any conversion error releases all staged ownership and returns TCL_ERROR; success leaves cleanup or commit to the caller.

Parameters:
  • graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • transactionPtr – [out] Caller-owned fresh candidate record, initialized here; success requires commit or cleanup as described above.

static void CommitGraphShadowTransaction(Graph *graphPtr, GraphShadowTransaction *transactionPtr)

Transfer the shadow candidate to the live title style.

An unstaged transaction is a no-op. Otherwise moves ownership to the graph, disarms the transaction and releases the old live shadow color.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • transactionPtr – [inout] Prepared candidate record consumed into live fields and disarmed; record storage remains caller-owned.

static int StageGraphTile(Graph *graphPtr, Tcl_Obj *objPtr, GraphTileTransaction *transactionPtr)

Acquire a candidate tile, including an explicit empty tile.

A NULL or empty object stages NULL. A nonempty name acquires a tile client. Acquisition failure keeps the prior candidate. Success frees any earlier candidate and transfers ownership to the transaction, not the graph.

Parameters:
  • graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • objPtr – [in] Borrowed proposed image name; NULL or an empty object explicitly stages no tile.

  • transactionPtr – [inout] Initialized candidate record updated only after successful parsing; retains prior candidate on failure.

static void FreeGraphTileTransaction(GraphTileTransaction *transactionPtr)

Release any uncommitted tile client and zero the transaction.

Safe for a zero-initialized or committed transaction. Does not release the graph live tile.

Parameters:
  • transactionPtr – [inout] Initialized candidate record whose staged resources are released and fields cleared.

static int PrepareGraphTileTransaction(Graph *graphPtr, GraphTileTransaction *transactionPtr)

Prepare a tile client from retained defaults and explicit options.

Requires a fresh transaction and an even borrowed option vector. Parses the initial default only if not overridden, then every explicit occurrence in order. Failure releases staged ownership; success requires commit or cleanup by the caller.

Parameters:
  • graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • transactionPtr – [out] Caller-owned fresh candidate record, initialized here; success requires commit or cleanup as described above.

static void CommitGraphTileTransaction(Graph *graphPtr, GraphTileTransaction *transactionPtr)

Install the tile candidate and its graph-change callback.

Moves ownership to the graph and disarms the transaction before freeing the previous live tile. A staged NULL clears the tile; an unstaged transaction does nothing.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • transactionPtr – [inout] Prepared candidate record consumed into live fields and disarmed; record storage remains caller-owned.

static int InitGraphOptions(Graph *graphPtr)

Initialize Tk-managed widget options and their database defaults.

Uses the actual widget window rather than a named component. Repeated calls after success are harmless. On Tk_InitOptions failure undefines the window cursor before freeing partially initialized options and the table. Success marks resources live but does not construct derived RBC fields.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

static void ResetGraphOptionContext(Graph *graphPtr)

Clear borrowed configuration arguments and the active option mask.

Does not decrement object references: the argument vector is caller-owned. Used before configuration and before restoring or releasing options.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

static int ConfigureGraphOptions(Graph *graphPtr, Tcl_Size objc, Tcl_Obj *const objv[], int *maskPtr)

Apply Tk options and validate derived graph resources.

Requires initialized options and an even option/value vector. Exposes the borrowed original arguments only during ConfigureGraph, forcing initialization masks on the first call. Derived conversion failure clears that context and restores Tk saved options. Success frees saved options, marks the graph configured and optionally returns the Tk change mask. A successful explicit Polar aspect disables automatic aspect; a renderer change invalidates mapping and backing pixels. Rollback concerns option resources, not all auxiliary notification state touched by validation.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • objc – [in] Even number of option/value entries in objv; zero is valid.

  • objv – [in] Borrowed even-length option/value vector, not a widget-command vector; retained only during configuration.

  • maskPtr – [out] Optional output for the Tk option change mask on successful configuration.

static int ConfigureNewGraph(Graph *graphPtr, Tcl_Size objc, Tcl_Obj *const objv[])

Initialize widget defaults and perform the first derived configuration.

Always calls ConfigureGraphOptions, including with zero arguments. Polar uses automatic data-unit aspect only when the option database supplies no aspect; a successful explicit aspect overrides that policy. Returns TCL_ERROR on initialization or configuration failure; creation owns graph cleanup.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • objc – [in] Even number of option/value entries in objv; zero is valid.

  • objv – [in] Borrowed even-length option/value vector, not a widget-command vector; retained only during configuration.

static void ReleaseGraphOptionResources(Graph *graphPtr)

Release Tk-owned options while the graph window remains valid.

No-op before initialization or after release. Clears borrowed transaction context, frees options and deletes the table. Derived GCs, shadow and tile remain owned by the graph destruction path.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

static int ConfigureGraph(Graph *graphPtr)

Validate retained graph values, then commit derived resources.

Requires initialized options and active configuration context. Validates track options, renderer availability and finite aspect, bar width and baseline, then prepares distance, padding, mode, shadow and tile candidates. Reportable conversion errors precede commits; owned candidates are freed on failure. After commit normalizes nonpositive bar width, updates geometry and GCs, reconfigures text and crosshairs, invalidates affected caches and schedules redraw. Tk option rollback belongs to ConfigureGraphOptions; auxiliary track notification bookkeeping is not part of these candidate transactions.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

Commands and screen composition

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

Dispatch the X margin-axis operation.

Uses the bottom margin normally and the left margin when inverted. Borrows the original argument vector and returns Rbc_AxisOp status unchanged; axis lookup, mutation and result construction belong to that dispatcher.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Dispatch the secondary X margin-axis operation.

Uses the top margin normally and the right margin when inverted. Borrows the original argument vector and returns Rbc_AxisOp status unchanged; axis lookup, mutation and result construction belong to that dispatcher.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Dispatch the Y margin-axis operation.

Uses the left margin normally and the bottom margin when inverted. Borrows the original argument vector and returns Rbc_AxisOp status unchanged; axis lookup, mutation and result construction belong to that dispatcher.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Dispatch the secondary Y margin-axis operation.

Uses the right margin normally and the top margin when inverted. Borrows the original argument vector and returns Rbc_AxisOp status unchanged; axis lookup, mutation and result construction belong to that dispatcher.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Dispatch a bar operation through the shared element interface.

Passes rbcBarElementUid as the element class with the original borrowed arguments. Returns the element dispatcher status unchanged; does not acquire an element reference or perform drawing itself.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Dispatch a strip operation through the shared element interface.

Passes rbcStripElementUid as the element class with the original borrowed arguments. Returns the element dispatcher status unchanged; does not acquire an element reference or perform drawing itself.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Dispatch a line operation through the shared element interface.

Passes rbcLineElementUid as the element class with the original borrowed arguments. Returns the element dispatcher status unchanged; does not acquire an element reference or perform drawing itself.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Dispatch a default element operation through the shared element interface.

Passes graphPtr->classUid as the element class with the original borrowed arguments. Returns the element dispatcher status unchanged; does not acquire an element reference or perform drawing itself.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Query option metadata or configure the graph.

With two arguments returns all Tk option descriptions; with three returns one description. Longer calls delegate option/value pairs to ConfigureGraphOptions. Requires initialized options; returns TCL_ERROR on lookup or configuration failure.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Return one Tk-managed option value.

Requires initialized options and dispatcher-validated arity. Installs the value as the interpreter result, or propagates a Tk lookup error. Does not convert retained values into derived graph fields.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Report cached plot, margin or legend geometry.

Accepts Tcl unambiguous abbreviations. Plot area and legend return x, y, width and height; other selectors return one integer. Plot dimensions use inclusive endpoints. Does not perform layout; invalid selectors return TCL_ERROR rather than unconditional success.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Test a window point against the graph plotting extents.

Converts both coordinates through Tk screen-distance parsing and returns a Tcl boolean. Conversion errors propagate. Uses current graph extents without laying out pending geometry; it does not select an individual track.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Map a window point to the first logical X/Y axis pair.

Evaluates both coordinates as Tcl expressions, synchronizes element vectors and resets dirty ranges, then returns two doubles. Does not perform full margin layout. Checks widget validity after each expression before accessing graph resources, and rejects nonfinite input coordinates.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Map a data point to rounded integer window coordinates.

Evaluates Tcl expressions, synchronizes element vectors and resets dirty ranges before selecting the first logical X/Y axis pair. Checks validity after each expression and rejects nonfinite input or out-of-range rounded output before integer conversion. Does not perform full layout. Trackgraphs are rejected by the enclosing dispatcher.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Render the graph to a photo or a Windows metafile target.

Parses paired format and integer size options; sizes below two use the current Tk window dimension. Temporarily assigns graph dimensions, requests layout and draws without the element backing store. Photo output owns a temporary pixmap and releases it after capture or callback cancellation. Windows output owns a recording DC and metafile; CLIPBOARD requests transfer of the metafile to the system. The enclosing SnapOp restores screen dimensions and invalidates temporary geometry on every return, including capture errors.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

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

Capture a snapshot and restore screen geometry on every return path.

Keep pre-existing dirty and idle-request flags. Restoration preserves the capture error when capture failed, and reports layout failure otherwise. A deleted window is never used for restoration or redraw scheduling.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

static Rbc_GraphOpProc *GetGraphOpFromObj(Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Resolve a widget operation and validate its argument count.

Uses the shared operation-table dispatcher at argument one. Returns a borrowed static procedure pointer, or NULL with a Tcl diagnostic. Does not execute the operation or retain any arguments.

Parameters:
int Rbc_GraphInstCmdProc(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Dispatch a graph widget command under graph preservation.

Rejects widget-wide transforms for trackgraphs and recursive snapshot or document output during axis formatting. Preserves the Graph allocation across the selected handler, then releases it and returns the handler status. Preservation does not keep the Tk window or separately owned components alive; handlers crossing Tcl callbacks still need validity checks.

Parameters:
  • clientData – [in] Borrowed widget-owned Graph registered for this callback; no new ownership is acquired.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

static int NewGraph(Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[], Rbc_Uid classUid)

Create a widget and return its Tk pathname.

Requires a pathname argument, then delegates construction to CreateGraph. On failure propagates TCL_ERROR; on success installs a new pathname string as the result. The created graph belongs to the widget lifecycle.

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

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed constructor arguments: objv[1] is the pathname, followed by option/value pairs.

  • classUid – [in] Interned widget/element class identifier selecting the constructor behavior.

static int GraphObjCmd(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Create a graph widget through the common constructor.

Passes rbcLineElementUid to NewGraph and returns its Tcl status unchanged. The clientData argument is unused; construction owns the new widget resources.

Parameters:
  • clientData – [in] Unused constructor command data.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

static int BarchartObjCmd(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Create a barchart widget through the common constructor.

Passes rbcBarElementUid to NewGraph and returns its Tcl status unchanged. The clientData argument is unused; construction owns the new widget resources.

Parameters:
  • clientData – [in] Unused constructor command data.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

static int StripchartObjCmd(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Create a stripchart widget through the common constructor.

Passes rbcStripElementUid to NewGraph and returns its Tcl status unchanged. The clientData argument is unused; construction owns the new widget resources.

Parameters:
  • clientData – [in] Unused constructor command data.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

static int PolarObjCmd(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Create a polar widget through the common constructor.

Passes rbcPolarElementUid to NewGraph and returns its Tcl status unchanged. The clientData argument is unused; construction owns the new widget resources.

Parameters:
  • clientData – [in] Unused constructor command data.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

static void FillMarginRectangle(Graph *graphPtr, Drawable drawable, int x, int y, int width, int height)

Fill one positive-sized margin rectangle.

Borrows the drawable and graph resources. Uses the tile when present, otherwise the margin fill GC, through the screen renderer. Nonpositive width or height is a no-op; this helper does not set tile origin.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • drawable – [in] Borrowed compatible destination drawable; caller retains ownership and presentation responsibility.

  • x – [in] Left margin rectangle coordinate in window pixels.

  • y – [in] Top margin rectangle coordinate in window pixels.

  • width – [in] Rectangle width in pixels; nonpositive values draw nothing.

  • height – [in] Rectangle height in pixels; nonpositive values draw nothing.

static void DrawMargins(Graph *graphPtr, Drawable drawable)

Paint margins, the plot border, margin legend, title and axes.

Sets tile origin to the widget origin, fills four surrounding rectangles, then draws decorations in that order. Uses current mapped geometry and borrowed resources. Opens and closes a screen-text context for the title; does not recompute layout or present the drawable.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • drawable – [in] Borrowed compatible destination drawable; caller retains ownership and presentation responsibility.

static void DrawPlotRegion(Graph *graphPtr, Drawable drawable)

Compose the cacheable plot layer in drawing order.

Clears the inclusive plot rectangle, draws track separators and grids, then Polar or Smith labels. After checking callback validity, draws under markers, lowered local/global legends, axis limits and ordinary elements. Borrows the drawable and mapped geometry. A void return does not indicate callback success; callers must check Rbc_GraphCallbackValid.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

  • drawable – [in] Borrowed compatible destination drawable; caller retains ownership and presentation responsibility.

static int UpdateMarginTraces(Graph *graphPtr)

Publish cached margin dimensions to global Tcl variables.

Writes left/right widths and top/bottom heights for configured variables. Copies names and sizes before invoking traces so configuration changes cannot invalidate borrowed option strings. Stops writes and returns false if a trace destroys the widget or cancels layout. Assignment errors remain ignored for compatibility. The display wrapper preserves graph and interpreter storage.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

static int TrackgraphObjCmd(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Create a trackgraph widget through the common constructor.

Passes trackGraphUid to NewGraph and returns its Tcl status unchanged. The clientData argument is unused; construction owns the new widget resources.

Parameters:
  • clientData – [in] Unused constructor command data.

  • interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.

Construction and redraw support

static void FreeGraphRedrawSettle(Graph *graphPtr)

Release the pending ancestry-sampling record.

Frees the owned sample array and record, then clears redrawSettle. A NULL record is harmless. Does not cancel an idle call or clear REDRAW_PENDING; the caller must handle scheduling state separately.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

static void SettleGraphRedraw(ClientData clientData)

Wait for two unchanged ancestry samples before presenting a frame.

Requires the graph-owned redrawSettle record installed by EventuallyRedrawSettledGraph. Samples window identity, position, size and border from the widget through its toplevel; reallocates samples when the ancestry length changes. Changed geometry resets the stable-pass count. Requeues itself until two unchanged passes, then frees samples and delegates to DisplayGraph, which consumes REDRAW_PENDING. A dead window frees samples and clears the pending flag without drawing. Does not enter an event loop.

Parameters:
  • clientData – [in] Borrowed widget-owned Graph registered for this callback; no new ownership is acquired.

static void EventuallyRedrawSettledGraph(Graph *graphPtr)

Replace ordinary idle drawing with ancestry-settled drawing.

Does nothing for a dead window or an already active settle request. Cancels a pending DisplayGraph call, allocates a fresh sampling record, sets REDRAW_PENDING and schedules SettleGraphRedraw. Also requests external legend redraw. Callers set geometry and drawing invalidation flags themselves.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

static void GraphWorldChanged(ClientData clientData)

Refresh derived font resources after a Tk world change.

Ignores dead or not-yet-configured graphs. Resets title style and height, notifies axes, legends, markers, line and bar elements of font changes, then invalidates geometry and backing pixels and schedules redraw. Does not reparse option objects or deliberately evaluate application scripts.

Parameters:
  • clientData – [in] Borrowed widget-owned Graph registered for this callback; no new ownership is acquired.

static void TileChangedProc(ClientData clientData, Rbc_Tile tile)

Request margin redisplay when the graph tile changes.

The tile argument is unused. For a live window sets REDRAW_WORLD and schedules drawing; a dead window is ignored. Does not rebuild a GC or replace the tile client, whose ownership belongs to graph configuration.

Parameters:
  • clientData – [in] Borrowed widget-owned Graph registered for this callback; no new ownership is acquired.

  • tile – [in] Borrowed changed tile token; unused by this callback.

static void AdjustAxisPointers(Graph *graphPtr)

Associate logical axis chains with physical margins.

Borrows the four existing chains. Normal order maps X/Y/X2/Y2 to bottom/left/top/right; inversion maps them to left/bottom/right/top. Does not change chain contents, axis classes, reference counts or axis sites, and does not itself invalidate geometry.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

static int InitPens(Graph *graphPtr)

Initialize the pen registry and create default active pens.

Creates activeLine and activeBar in that order. Returns TCL_ERROR if either creation fails, retaining any already-created pen for graph teardown. Must run once on a new graph; does not roll back the registry locally.

Parameters:
  • graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.

static Graph *CreateGraph(Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[], Rbc_Uid classUid)

Allocate a graph widget and install its components and lifecycle.

Requires a pathname at objv[1]. Creates the Tk window, zeroed Graph, registries and display lists after creating the anonymous option proxy. Trackgraphs retain a distinct Tk class and trackGraph flag but use the line element class. Installs window instance data, class procedures, widget command and event handler before component configuration. Creates pens, axes, exporters, crosshairs, legend and grid before applying widget options, and creates bindings last. Success returns a widget-owned Graph; failure returns NULL with the interpreter error and destroys the window. Anonymous-window failure destroys the parent before any Graph storage is allocated and preserves the original interpreter error; later failures use the installed event handler.

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

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed constructor arguments: objv[1] is the pathname, followed by option/value pairs.

  • classUid – [in] Interned widget/element class identifier selecting the constructor behavior.

int Rbc_GraphInit(Tcl_Interp *interp)

Intern component class identifiers and register graph constructors.

Creates graph, barchart, stripchart, polar and trackgraph Tcl commands in the interpreter. Initializes class identifiers including the contour identifier, but does not register a contour widget constructor. Returns TCL_OK; no graph widget is created here.

Parameters:
Graph *Rbc_GetGraphFromWindowData(Tk_Window tkwin)

Find graph instance data on a window or its ancestors.

Walks Tk_Parent until non-NULL RBC window instance data is found. Returns a borrowed Graph pointer, or NULL when the chain is empty. Does not retain the graph or verify a component class; callers must supply a window chain whose RBC instance data follows the graph convention.

Parameters:
  • tkwin – [in] Borrowed starting window, or NULL for an empty ancestry chain.

struct GraphGeometrySample

One borrowed window identity and its sampled integer geometry.

The window handle is compared with the current ancestry, not retained or dereferenced through this record. The settle owner owns the sample array.

Public Members

Tk_Window window

Borrowed sampled Tk window.

int x

Window X position in parent pixels.

int y

Window Y position in parent pixels.

int width

Window width in pixels.

int height

Window height in pixels.

int border

Window border width in pixels.

struct GraphRedrawSettle

Graph-owned state for coalescing geometry-manager idle work.

Owns count sample records; stablePasses counts consecutive unchanged samples. REDRAW_PENDING represents the scheduled work separately.

Public Members

int count

Number of geometry samples.

int stablePasses

Number of consecutive passes with unchanged geometry.

GraphGeometrySample *samples

Owned sample array.

Windows metafile packaging

These private functions use the Windows extraction project. Their scope below is documentation-only and does not change the compiled symbols.

group Windows metafile snapshots

Private placeable-WMF encoding and native snapshot file ownership.

Functions

static int InitMetaFileHeader(Tcl_Interp *interp, Tk_Window tkwin, int width, int height, APMHEADER *mfhPtr)

Initialize a packed 22-byte placeable-WMF header.

Converts width and height independently from pixels to 1440 units per inch. Rejects invalid screen metrics and dimensions that cannot fit positive signed 16-bit bounds before writing the output. The checksum XORs ten little-endian 16-bit words, excluding the checksum itself; no unaligned integer reads occur. Returns TCL_OK or TCL_ERROR with an interpreter diagnostic.

Parameters:
  • interp – [inout] Borrowed result interpreter; see Interpreter arguments.

  • tkwin – [in] Borrowed live window supplying screen pixel and millimeter dimensions.

  • width – [in] Positive snapshot width in pixels.

  • height – [in] Positive snapshot height in pixels.

  • mfhPtr – [out] Required packed header storage, assigned only on success.

static int CreateAPMetaFile(Tcl_Interp *interp, HANDLE hMetaFile, HDC hDC, APMHEADER *mfhPtr, const char *fileName)

Convert a borrowed enhanced metafile and write a placeable WMF file.

Validates both native conversion calls and the global-memory lock before opening the destination. Owns and releases the temporary memory and file; does not consume the metafile or reference DC. Conversion failure leaves an existing destination untouched. Write failure may leave a partial file. Returns TCL_OK after both writes, or TCL_ERROR with a native diagnostic.

Parameters:
  • interp – [inout] Borrowed result interpreter; see Interpreter arguments.

  • hMetaFile – [in] Borrowed non-NULL enhanced metafile to convert.

  • hDC – [in] Borrowed reference DC used for MM_ANISOTROPIC conversion.

  • mfhPtr – [in] Borrowed initialized packed placeable header.

  • fileName – [in] Borrowed NUL-terminated native ANSI pathname for CreateFileA.

Data records and member contracts

These records describe stored state and resource ownership. Their presence in the reference does not make private layouts part of the installed C API.

struct GraphBarModeTransaction

Staged option replacements; commit transfers resources and abort releases uncommitted resources.

Public Members

int staged

Nonzero when the transaction contains a replacement to commit or release.

BarMode mode

Validated mode selector staged for commit or abort.

struct GraphOpSpec

Typed command dispatch entry with shared argument validation metadata.

Public Members

Rbc_OpSpecHeader header

Operation name, total argument bounds and usage suffix.

Rbc_GraphOpProc *proc

Typed command handler for this operation.

struct GraphOptionName

Static graph option-name lookup entry.

Public Members

const char *name

Borrowed option name.

int option

Associated option selector.

struct GraphPaddingTransaction

Staged option replacements; commit transfers resources and abort releases uncommitted resources.

Public Members

unsigned int stagedMask

Bit mask selecting staged replacements to commit or release.

Rbc_Pad padX

Horizontal pixel padding staged for commit or abort.

Rbc_Pad padY

Vertical pixel padding staged for commit or abort.

struct GraphPixelTransaction

Staged option replacements; commit transfers resources and abort releases uncommitted resources.

Public Members

unsigned int stagedMask

Bit mask selecting staged replacements to commit or release.

int borderWidth

Border thickness in pixels staged for commit or abort.

int bottomMarginSize

Bottom margin size in pixels staged for commit or abort.

int halo

Picking halo in pixels staged for commit or abort.

int reqHeight

Requested widget height in pixels staged for commit or abort.

int highlightWidth

Focus-highlight thickness in pixels staged for commit or abort.

int leftMarginSize

Left margin size in pixels staged for commit or abort.

int plotBorderWidth

Plot border thickness in pixels staged for commit or abort.

int rightMarginSize

Right margin size in pixels staged for commit or abort.

int topMarginSize

Top margin size in pixels staged for commit or abort.

int reqWidth

Requested widget width in pixels staged for commit or abort.

struct GraphShadowTransaction

Staged option replacements; commit transfers resources and abort releases uncommitted resources.

Public Members

int staged

Nonzero when the transaction contains a replacement to commit or release.

Shadow shadow

Replacement text shadow staged for commit or abort.

struct GraphTileTransaction

Staged option replacements; commit transfers resources and abort releases uncommitted resources.

Public Members

int staged

Nonzero when the transaction contains a replacement to commit or release.

Rbc_Tile tile

Retained replacement tile token staged for commit or abort.

struct SnapData

Parsed graph snapshot destination and dimensions.

Public Members

const char *name

Snapshot destination name.

int width

Requested snapshot width in pixels.

int height

Requested snapshot height in pixels.

int format

Snapshot format selector.

Implementation selectors

enum Rbc_Renderer

Selects the graph’s screen drawing backend; export format is selected separately.

Values:

enumerator RBC_RENDERER_NATIVE
enumerator RBC_RENDERER_CAIRO
enum Rbc_Antialias

Selects the requested screen antialias policy for renderers that implement it.

Values:

enumerator RBC_ANTIALIAS_DEFAULT
enumerator RBC_ANTIALIAS_NONE
enumerator RBC_ANTIALIAS_GRAY
enumerator RBC_ANTIALIAS_FAST
enumerator RBC_ANTIALIAS_GOOD
enumerator RBC_ANTIALIAS_BEST
enum GraphBindContext

Discriminates the picked component passed through the graph binding table.

Values:

enumerator GRAPH_BIND_CONTEXT_AXIS
enumerator GRAPH_BIND_CONTEXT_ELEMENT
enumerator GRAPH_BIND_CONTEXT_MARKER
enumerator GRAPH_BIND_CONTEXT_TRACK
enum ClassType

Legacy graph class identifiers; this list is not a registry of all current marker or element classes.

Values:

enumerator CLASS_UNKNOWN
enumerator CLASS_LINE_ELEMENT
enumerator CLASS_STRIP_ELEMENT
enumerator CLASS_BAR_ELEMENT
enumerator CLASS_BITMAP_MARKER
enumerator CLASS_IMAGE_MARKER
enumerator CLASS_LINE_MARKER
enumerator CLASS_POLYGON_MARKER
enumerator CLASS_TEXT_MARKER
enumerator CLASS_WINDOW_MARKER
enum PolarRepresentation

Chooses polar or Smith presentation of Cartesian data.

Values:

enumerator POLAR_REPRESENTATION_POLAR
enumerator POLAR_REPRESENTATION_SMITH
enum SmithGridMode

Selects impedance circles, admittance circles or both for a Smith grid.

Values:

enumerator SMITH_GRID_IMPEDANCE
enumerator SMITH_GRID_ADMITTANCE
enumerator SMITH_GRID_BOTH
enum BarModes

Chooses the placement of bars that share an abscissa, including stacking and grouped positioning.

Values:

enumerator MODE_INFRONT
enumerator MODE_STACKED
enumerator MODE_ALIGNED
enumerator MODE_OVERLAP
enum MonoAttribute

Legacy foreground/background identifiers for monochrome PostScript attributes.

Values:

enumerator PS_MONO_BACKGROUND
enumerator PS_MONO_FOREGROUND
enum GraphPixelOption

Selects a widget dimension during staged conversion of graph pixel options.

Values:

enumerator GRAPH_PIXEL_OPTION_NONE
enumerator GRAPH_PIXEL_OPTION_BORDER_WIDTH
enumerator GRAPH_PIXEL_OPTION_BOTTOM_MARGIN
enumerator GRAPH_PIXEL_OPTION_HALO
enumerator GRAPH_PIXEL_OPTION_HEIGHT
enumerator GRAPH_PIXEL_OPTION_HIGHLIGHT_WIDTH
enumerator GRAPH_PIXEL_OPTION_LEFT_MARGIN
enumerator GRAPH_PIXEL_OPTION_PLOT_BORDER_WIDTH
enumerator GRAPH_PIXEL_OPTION_RIGHT_MARGIN
enumerator GRAPH_PIXEL_OPTION_TOP_MARGIN
enumerator GRAPH_PIXEL_OPTION_WIDTH
enum GraphPaddingOption

Selects the horizontal or vertical plot padding during widget configuration.

Values:

enumerator GRAPH_PADDING_OPTION_NONE
enumerator GRAPH_PADDING_OPTION_X
enumerator GRAPH_PADDING_OPTION_Y
typedef enum BarModes BarMode

Chooses the placement of bars that share an abscissa, including stacking and grouped positioning.