Axis control C reference

These implementation contracts cover registry lifetime, configuration entry points and command dispatch in rbcGrAxis.c. See Axis ownership and commands for ownership and error boundaries and Coordinate mapping C reference for coordinate helpers. Namespaces below disambiguate private handler names without changing linkage.

Registry and lifetime

group Axis registry and lifetime

Functions

static void DestroyAxis(Graph *graphPtr, Axis *axisPtr)

Destroy an axis and all resources it owns.

Cancels pending scrollbar notification, releases options and bindings, removes the margin link and registry entry when present, and frees styles, shadows, tick arrays, labels, formats, segments, tags and the record. Does not consult refCount; callers must ensure no consumers retain the record.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [inout] Owned axis consumed unconditionally; no consumer may retain it afterward, regardless of refCount.

static Axis *CreateAxis(Graph *graphPtr, char *name, int margin)

Allocate a registered axis or revive a pending deletion.

Rejects names beginning with a dash and existing live names, returning NULL with an interpreter error. A new record owns a copied name and label chain but is not yet configured or linked to a margin. Revival returns the same record, clears deletePending and invalidates notified limits; it preserves references and existing resources.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • name – [in] Borrowed NUL-terminated name copied for a new record; an existing pending-deletion record may be revived.

  • margin – [in] Initial margin selector used for defaults; does not insert the axis into a margin chain.

static int NameToAxis(Graph *graphPtr, const char *name, Axis **axisPtrPtr)

Look up a live named axis without retaining it.

Returns TCL_OK and a borrowed pointer. Missing and delete-pending axes return TCL_ERROR, set the interpreter result, and clear the output pointer.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • name – [in] Borrowed NUL-terminated axis name.

  • axisPtrPtr – [out] Required output receiving a borrowed live axis on success, or NULL on lookup failure; no reference is acquired.

static int GetAxis(Graph *graphPtr, const char *axisName, Rbc_Uid classUid, Axis **axisPtrPtr)

Look up an axis and optionally acquire a typed reference.

A NULL classUid performs a borrowed lookup. Otherwise establishes the logical X/Y class when unused or untyped, rejects a conflicting class, and increments refCount on success. Match each acquired reference with FreeAxis. The output pointer is assigned only on success.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisName – [in] Borrowed NUL-terminated name of a live axis in this graph.

  • classUid – [in] Interned logical X/Y class to acquire a reference, or NULL for a borrowed lookup.

  • axisPtrPtr – [out] Required output assigned only on success; borrowed for NULL classUid, otherwise owns one reference to release with FreeAxis.

static void FreeAxis(Graph *graphPtr, Axis *axisPtr)

Release one acquired axis reference.

Requires a positive reference count. Destroys the record when the count reaches zero and deletion is pending; an unreferenced live axis remains registered.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [inout] Axis representing one acquired reference with positive refCount; may be destroyed when this reference is released.

int Rbc_GetAxisFromObj(Graph *graphPtr, Tcl_Obj *objPtr, Rbc_Uid classUid, int allowEmpty, Axis **axisPtrPtr)

Resolve an optional Tcl axis name with the requested reference policy.

A NULL or empty object returns a NULL axis only when allowEmpty is true; otherwise it reports TCL_ERROR. Nonempty names delegate to GetAxis, including its typed-reference ownership and output- on-success rules.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • objPtr – [in] Borrowed axis-name object, or NULL/empty subject to allowEmpty.

  • classUid – [in] Interned logical X/Y class to acquire a reference, or NULL for a borrowed lookup.

  • allowEmpty – [in] Nonzero permits a NULL or empty name to resolve successfully to NULL.

  • axisPtrPtr – [out] Required output; empty names set NULL, successful typed lookup acquires one reference, and nonempty lookup errors leave it unchanged.

void Rbc_FreeAxisReference(Graph *graphPtr, Axis *axisPtr)

Release an optional retained axis reference.

Accepts NULL. A non-NULL argument must represent an acquired reference; release may destroy a delete-pending record.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [inout] Axis representing one acquired reference, or NULL; may become invalid during release.

void Rbc_DestroyAxes(Graph *graphPtr)

Tear down the complete graph axis registry.

Destroys records regardless of reference counts, then deletes registry and tag tables and axis chains. Clears each record hash pointer before destruction to keep hash iteration valid. Consumers must have been detached by graph teardown; this is not ordinary axis deletion.

Parameters:
  • graphPtr – [inout] Graph undergoing final teardown with initialized axis containers and all consumers detached; registry and chains are destroyed.

int Rbc_DefaultAxes(Graph *graphPtr)

Create and configure the four initial margin axes.

Creates x, y, x2 and y2 with one reference each and the appropriate logical class. Polar axes start hidden before database options are applied. Success links each configured record to its chain. Failure returns TCL_ERROR with partial initialization left for graph teardown.

Parameters:
  • graphPtr – [inout] Graph under construction with initialized axis registry; receives four default axes and margin chains, including partial state on failure.

Configuration entry points

group Axis configuration entry points

Functions

static int InitAxisOptions(Graph *graphPtr, Axis *axisPtr)

Initialize Tk options through the named Axis component.

Returns TCL_OK if already initialized or successfully initialized. On initialization failure, frees partially installed Tk resources and the option table. The component resource name is temporary; the Axis retains the option table.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [inout] Borrowed named axis receiving its option table and defaults; already initialized axes are unchanged.

static void ResetAxisOptionContext(Axis *axisPtr)

Clear borrowed configuration arguments and the option mask.

Does not free the caller-owned object vector or alter committed option values.

Parameters:
  • axisPtr – [inout] Borrowed axis whose temporary option vector/count/mask are cleared; committed options remain unchanged.

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

Apply one axis option transaction and construct derived state.

Requires initialized options and an even object count. Borrows objv only during ConfigureAxis, clearing that context before rollback or return. On failure restores Tk-managed options; on success releases saved options, marks configuration notification pending, and optionally returns the changed mask. Returns a Tcl status.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [inout] Borrowed axis with initialized Tk option table; candidate fields are rolled back on recoverable failure.

  • objc – [in] Even number of option/value entries, excluding widget and operation names; zero is allowed.

  • objv – [in] Borrowed option/value array of objc entries, valid through configuration and any expression evaluation.

  • maskPtr – [out] Optional changed-option mask output; assigned only on successful configuration.

static int ConfigureNewAxis(Graph *graphPtr, Axis *axisPtr, Tcl_Size objc, Tcl_Obj *const objv[])

Initialize options and derive a usable axis configuration.

Runs configuration even for an empty option vector so database defaults reach derived fields. Returns a Tcl status; the caller owns failure cleanup. An already initialized revived axis retains its option table.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [inout] New or revived axis to initialize/configure; caller remains responsible for failure cleanup.

  • objc – [in] Even number of option/value entries, excluding widget and operation names; zero is allowed.

  • objv – [in] Borrowed option/value array of objc entries, valid through configuration and any expression evaluation.

static void ReleaseAxisOptionResources(Graph *graphPtr, Axis *axisPtr)

Release Tk-owned option resources once.

Clears borrowed transaction context and deletes the initialized option table. Does not release derived labels, geometry, shadow colours or text-style graphics contexts; DestroyAxis owns those resources.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [inout] Borrowed axis whose Tk option resources are released once; derived resources and record remain for separate cleanup.

static void ResetTextStyles(Graph *graphPtr, Axis *axisPtr)

Refresh text styles and replace the axis tick graphics context.

Borrows configured fonts and colours. Allocates the new tick GC before releasing the old one; uses the existing native line-width conversion and projecting caps.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [inout] Borrowed configured axis with valid fonts/colors; text styles and tick GC are refreshed.

static int ConfigureAxis(Graph *graphPtr, Axis *axisPtr)

Validate staged options before committing derived axis resources.

Prepares limit, tick, loose-range, pixel, shadow, tag and format transactions as needed. Validates command prefixes without evaluating them. Recoverable errors free prepared resources before any commit. Success normalizes rotation, refreshes styles and title extents, marks axis and graph mapping dirty, and schedules redraw. The caller restores Tk-managed fields on error.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [inout] Borrowed axis with candidate Tk fields, mask and original option vector installed by the saved-options wrapper.

Commands and bindings

group Axis command dispatch and bindings

Functions

static int BindOp(Graph *graphPtr, Axis *axisPtr, int margin, Tcl_Size objc, Tcl_Obj *const objv[])

Query or configure bindings for a selected margin axis.

Interns the axis name as a binding tag and forwards the already sliced argument vector. Returns the binding subsystem Tcl status; does not evaluate an event binding here.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [inout] Borrowed live axis with the range, options and caches required above; no reference is acquired.

  • margin – [in] Unused shared-handler argument; the axis is already resolved.

  • objc – [in] Number of entries in the already-sliced argument suffix.

  • objv – [in] Borrowed suffix: Optional sequence and script after the operation; forwarded unchanged to binding configuration.

static int CgetOp(Graph *graphPtr, Axis *axisPtr, int margin, Tcl_Size objc, Tcl_Obj *const objv[])

Return one initialized axis option value.

Requires a live axis and initialized Tk option table. Uses the first sliced argument as the option name and returns TCL_ERROR if Tk cannot resolve it.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [inout] Borrowed live axis with the range, options and caches required above; no reference is acquired.

  • margin – [in] Unused shared-handler argument; the axis is already resolved.

  • objc – [in] Validated suffix count (one); not otherwise used by this handler.

  • objv – [in] Borrowed suffix: One option-name object at index 0; arity must have been validated.

static int ConfigureOp(Graph *graphPtr, Axis *axisPtr, int margin, Tcl_Size objc, Tcl_Obj *const objv[])

Query or configure one resolved axis.

Zero or one sliced argument returns Tk option metadata. Option/value pairs use ConfigureAxisOptions. Success additionally invalidates backing and margins for an onscreen axis. This transaction covers one axis, not a multi-axis command.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [inout] Borrowed live axis with the range, options and caches required above; no reference is acquired.

  • margin – [in] Unused shared-handler argument; the axis is already resolved.

  • objc – [in] Number of entries in the already-sliced argument suffix.

  • objv – [in] Borrowed suffix: Zero entries for all metadata, one option for metadata, or option/value pairs for mutation.

static int UseOp(Graph *graphPtr, Axis *axisPtr, int margin, Tcl_Size objc, Tcl_Obj *const objv[])

Query or replace the axes displayed on a margin.

Queries return chain order. Replacement chooses logical class using inversion and rejects trackgraph Y arrangement, which belongs to tracks. Validates every replacement name and type before changing any chain. Failure leaves all margins unchanged. Success moves existing links as needed and schedules full layout and redraw.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [in] Incoming selected-axis value is ignored; the margin chain and replacement list determine the axes.

  • margin – [in] Concrete MARGIN_TOP, MARGIN_BOTTOM, MARGIN_LEFT or MARGIN_RIGHT selector.

  • objc – [in] Number of entries in the already-sliced argument suffix.

  • objv – [in] Borrowed suffix: Empty suffix queries the margin; otherwise index 0 is the complete replacement axis-name list.

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

List interned axis tags or access one tag binding.

With no tag argument returns the tag table in hash order. Otherwise interns the supplied tag and forwards remaining arguments; the tag need not name an existing axis.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • objc – [in] Number of borrowed entries in the full command vector; arity is validated by dispatch.

  • objv – [in] Borrowed full widget command vector; operation is at index 2 and operands begin at index 3.

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

Create or revive a named axis and apply its options.

Returns the axis name on success. Configuration failure destroys only a newly allocated record. Failed revival restores pending deletion and the previous notification validity while preserving the record and its consumers; ConfigureNewAxis rolls back its option transaction.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • objc – [in] Number of borrowed entries in the full command vector; arity is validated by dispatch.

  • objv – [in] Borrowed full widget command vector; operation is at index 2 and operands begin at index 3.

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

Resolve a named axis and delegate its option query.

Uses a borrowed live lookup and passes the option suffix to CgetOp. Returns the lookup or option- query Tcl status.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • objc – [in] Number of borrowed entries in the full command vector; arity is validated by dispatch.

  • objv – [in] Borrowed full widget command vector; operation is at index 2 and operands begin at index 3.

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

Apply a shared option suffix to one or more named axes.

Validates names before the first option beginning with a dash, then configures them sequentially. Earlier successful axes are not rolled back if a later configuration fails. Query results are replaced by each successive axis result.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • objc – [in] Number of borrowed entries in the full command vector; arity is validated by dispatch.

  • objv – [in] Borrowed full widget command vector; operation is at index 2 and operands begin at index 3.

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

Mark named axes for deletion and destroy unreferenced records.

Rejects track-owned axes until detached. Marks an active formatter traversal invalid before deletion. Referenced records remain allocated but disappear from live name lookup. Processes names sequentially, so earlier deletions survive a later error.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • objc – [in] Number of borrowed entries in the full command vector; arity is validated by dispatch.

  • objv – [in] Borrowed full widget command vector; operation is at index 2 and operands begin at index 3.

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

Report the current axis name or picked detail.

Checks the binding context before interpreting the picked object as an axis. Returns a value only for current or detail with an eligible picked axis; otherwise returns TCL_OK without setting a new result.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • objc – [in] Number of borrowed entries in the full command vector; arity is validated by dispatch.

  • objv – [in] Borrowed full widget command vector; operation is at index 2 and operands begin at index 3.

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

List live axis names matching any supplied glob pattern.

Skips delete-pending records, returns each matching name once and preserves hash traversal order, not display order. No patterns means all live names.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • objc – [in] Number of borrowed entries in the full command vector; arity is validated by dispatch.

  • objv – [in] Borrowed full widget command vector; operation is at index 2 and operands begin at index 3.

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

Dispatch the named-axis command family.

Validates operation and argument counts with the shared operation table, then forwards the complete widget command vector. Handlers resolve names and apply their own lifetime and transaction rules.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

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

  • objc – [in] Number of borrowed command entries; this dispatcher validates its supported operation/request arity.

  • objv – [in] Borrowed full widget command vector; operation is at index 2 and operands begin at index 3.

int Rbc_AxisOp(Graph *graphPtr, int margin, Tcl_Size objc, Tcl_Obj *const objv[])

Dispatch a margin-axis operation.

Validates operation and argument counts, selects the first axis from the margin chain and passes the suffix after the operation. UseOp can query or replace the chain; other handlers require an appropriate selected axis.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • margin – [in] Concrete MARGIN_TOP, MARGIN_BOTTOM, MARGIN_LEFT or MARGIN_RIGHT selector.

  • objc – [in] Number of borrowed command entries; this dispatcher validates its supported operation/request arity.

  • objv – [in] Borrowed full widget command vector; operation is at index 2 and operands begin at index 3.

static ClientData MakeAxisTag(Graph *graphPtr, char *tagName)

Intern a binding tag in the graph axis tag table.

Returns a borrowed stable hash key. Its storage belongs to the graph and is released with the tag table, not by individual binding operations.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • tagName – [in] Borrowed NUL-terminated binding tag, copied by the hash table on first insertion.

void Rbc_AppendAxisBindingTags(Graph *graphPtr, Axis *axisPtr, Rbc_List list)

Append axis name, class and configured tags in binding order.

Borrows the graph, axis and destination list. Interned keys remain owned by the graph tag table. The list is appended to rather than cleared; configured tags follow the name and class.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [inout] Borrowed live axis with the range, options and caches required above; no reference is acquired.

  • list – [inout] Caller-owned destination list; appends borrowed interned keys without clearing existing entries.

Option transaction internals

group Axis option transactions

Functions

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

Compare a validated option with its canonical name.

Uses the axis option table to resolve abbreviations and synonyms. Returns false when resolution fails. This helper does not replace Tk option validation or report an interpreter error.

Parameters:
  • objPtr – [in] Borrowed option-name object resolved through the axis option table, including abbreviations and synonyms.

  • optionName – [in] Borrowed NUL-terminated canonical option name, including its leading dash.

static int IsAxisBindTagsOption(Tcl_Obj *objPtr)

Recognize the -bindtags option.

Delegates canonical-name matching to IsAxisOption after Tk has rejected unknown or ambiguous options.

Parameters:
  • objPtr – [in] Borrowed option-name object resolved through the axis option table, including abbreviations and synonyms.

static int StageAxisTags(Tcl_Interp *interp, Tcl_Obj *objPtr, AxisTagsTransaction *transactionPtr)

Stage a replacement binding-tag list.

Parses into a new string-list allocation before releasing the previous candidate. Success owns the new allocation and sets staged; failure preserves the prior candidate. Does not alter live tags.

Parameters:
  • interp – [inout] Borrowed interpreter receiving conversion diagnostics; see Interpreter arguments.

  • objPtr – [in] Borrowed Tcl list of binding tags; its strings are copied into candidate storage.

  • transactionPtr – [inout] Initialized or zeroed caller-owned candidate transaction; staged fields are updated only after successful parsing.

static void FreeAxisTagsTransaction(AxisTagsTransaction *transactionPtr)

Discard an axis tags transaction.

Releases owned tag-list allocation and zeroes the complete transaction. Requires initialized or zeroed storage. Safe after commit because transferred ownership has been cleared; does not alter live axis fields.

Parameters:
  • transactionPtr – [inout] Initialized or zeroed transaction whose candidate resources are released and complete contents reset; record is retained.

static int PrepareAxisTagsTransaction(Graph *graphPtr, Axis *axisPtr, AxisTagsTransaction *transactionPtr)

Prepare the axis tags option family.

Initializes fresh transaction storage; do not pass an existing owning transaction. Examines the borrowed even-length option vector, identifies explicit options, and on first configuration parses effective defaults only for options not explicitly overridden. Processes every explicit occurrence in caller order, so a bad earlier value cannot be hidden by a later valid one. Returns a Tcl status without committing live derived fields. On error releases all candidates owned by this transaction.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [in] Borrowed axis with candidate Tk fields and the original even-length option vector installed; derived fields are not committed here.

  • transactionPtr – [out] Fresh caller-owned transaction storage, initialized here; must not already own resources. Success requires commit or cleanup.

static void CommitAxisTagsTransaction(Axis *axisPtr, AxisTagsTransaction *transactionPtr)

Commit prepared axis tags candidates.

Transfers the staged list, clears its pointer and flag, then frees the old live list. Unstaged options are unchanged. Performs no parsing, callback evaluation or recoverable validation; the caller must have prepared all option families first.

Parameters:
  • axisPtr – [inout] Live axis receiving only staged derived fields; all option families must be validated before any commit.

  • transactionPtr – [inout] Successfully prepared candidate transaction; transferred pointers and staging flags are cleared without freeing the record.

static void FreeAxisFormats(char **formats)

Release a split limit-format allocation.

Accepts NULL. Frees the single allocation, not each string separately; cannot clear the caller pointer.

Parameters:
  • formats – [in] Owned split-list allocation to release, or NULL; individual strings must not be freed separately.

static int IsAxisLimitsFormatOption(Tcl_Obj *objPtr)

Recognize the -limitsformat option.

Delegates canonical-name matching to IsAxisOption after Tk has rejected unknown or ambiguous options.

Parameters:
  • objPtr – [in] Borrowed option-name object resolved through the axis option table, including abbreviations and synonyms.

static int ValidateAxisLimitFormat(Tcl_Interp *interp, const char *format)

Validate a format string used with one double argument.

Allows literal text, escaped percent signs and at most one a/A/e/E/f/F/g/G conversion, optionally with lowercase l. Rejects dynamic width/precision, other conversion types and excessive format length, width or precision above TICK_LABEL_SIZE. Zero conversions are allowed. Returns a Tcl status; it validates argument compatibility rather than guaranteeing the rendered output fits a label buffer.

Parameters:
  • interp – [inout] Borrowed interpreter receiving conversion diagnostics; see Interpreter arguments.

  • format – [in] Borrowed NUL-terminated printf-style format to validate for a single double argument.

static int GetAxisLimitsFormatsFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, char ***formatsPtrPtr, int *nFormatsPtr)

Allocate zero, one or two validated limit formats.

Initializes outputs to NULL and zero. NULL or an empty string succeeds without allocation. Splits the Tcl list, rejects more than two entries and validates each format. Failure frees the split allocation. Success transfers one allocation containing the pointer list and strings to the caller; free it with FreeAxisFormats.

Parameters:
  • interp – [inout] Borrowed interpreter receiving conversion diagnostics; see Interpreter arguments.

  • objPtr – [in] Borrowed list of zero to two format strings; NULL or empty selects no formats.

  • formatsPtrPtr – [out] Required output initialized to NULL; successful nonempty output transfers one allocation released by FreeAxisFormats.

  • nFormatsPtr – [out] Required output initialized to zero; receives the validated format count on success.

static int StageAxisLimitsFormats(Tcl_Interp *interp, Tcl_Obj *objPtr, AxisFormatTransaction *transactionPtr)

Stage replacement axis-limit formats.

Parses and validates the replacement before freeing previous staged formats. Success records the new allocation, count and staged flag; failure preserves the previous candidate.

Parameters:
  • interp – [inout] Borrowed interpreter receiving conversion diagnostics; see Interpreter arguments.

  • objPtr – [in] Borrowed list of zero to two format strings; NULL or empty stages removal.

  • transactionPtr – [inout] Initialized or zeroed caller-owned candidate transaction; staged fields are updated only after successful parsing.

static void FreeAxisFormatTransaction(AxisFormatTransaction *transactionPtr)

Discard an axis format transaction.

Releases owned format-list allocation and zeroes the complete transaction. Requires initialized or zeroed storage. Safe after commit because transferred ownership has been cleared; does not alter live axis fields.

Parameters:
  • transactionPtr – [inout] Initialized or zeroed transaction whose candidate resources are released and complete contents reset; record is retained.

static int PrepareAxisFormatTransaction(Graph *graphPtr, Axis *axisPtr, AxisFormatTransaction *transactionPtr)

Prepare the axis format option family.

Initializes fresh transaction storage; do not pass an existing owning transaction. Examines the borrowed even-length option vector, identifies explicit options, and on first configuration parses effective defaults only for options not explicitly overridden. Processes every explicit occurrence in caller order, so a bad earlier value cannot be hidden by a later valid one. Returns a Tcl status without committing live derived fields. On error releases all candidates owned by this transaction.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [in] Borrowed axis with candidate Tk fields and the original even-length option vector installed; derived fields are not committed here.

  • transactionPtr – [out] Fresh caller-owned transaction storage, initialized here; must not already own resources. Success requires commit or cleanup.

static void CommitAxisFormatTransaction(Axis *axisPtr, AxisFormatTransaction *transactionPtr)

Commit prepared axis format candidates.

Transfers the staged format list and count, clears the candidate pointer/count/flag, then frees the old live allocation. Unstaged options are unchanged. Performs no parsing, callback evaluation or recoverable validation; the caller must have prepared all option families first.

Parameters:
  • axisPtr – [inout] Live axis receiving only staged derived fields; all option families must be validated before any commit.

  • transactionPtr – [inout] Successfully prepared candidate transaction; transferred pointers and staging flags are cleared without freeing the record.

static AxisLimitOption GetAxisLimitOption(Tcl_Obj *objPtr)

Classify an axis limit option.

Resolves the canonical name using axisOptionSpecs and returns the corresponding enum for display and scroll minima/maxima. Returns the NONE enum for unrelated or unresolved names; performs no allocation.

Parameters:
  • objPtr – [in] Borrowed option-name object resolved through the axis option table, including abbreviations and synonyms.

static int GetAxisLimitFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, double *valuePtr)

Evaluate an optional finite axis-limit expression.

NULL or an empty object selects VALUE_UNDEFINED. Otherwise calls Tcl_ExprDoubleObj and rejects nonfinite results. Returns a Tcl status. Expression evaluation may execute Tcl substitutions; it is not a literal-only conversion and does not itself preserve graph or axis lifetime. The output is usable only on success.

Parameters:
  • interp – [inout] Borrowed interpreter receiving conversion diagnostics; see Interpreter arguments.

  • objPtr – [in] Borrowed finite Tcl expression, or NULL/empty for VALUE_UNDEFINED; evaluation may execute Tcl.

  • valuePtr – [out] Required output receiving a finite limit or VALUE_UNDEFINED on success; unusable on error.

static AxisPixelOption GetAxisPixelOption(Tcl_Obj *objPtr)

Classify an axis pixel option.

Resolves the canonical name using axisOptionSpecs and returns the corresponding enum for border width, line width and scroll increment. Returns the NONE enum for unrelated or unresolved names; performs no allocation.

Parameters:
  • objPtr – [in] Borrowed option-name object resolved through the axis option table, including abbreviations and synonyms.

static int StageAxisPixelOption(Graph *graphPtr, Tcl_Obj *objPtr, AxisPixelOption option, AxisPixelTransaction *transactionPtr)

Stage one validated pixel-distance value.

Border and line widths must be nonnegative; scroll increment must be positive. Uses Tk-window scaling through Rbc_GetPixelsFromObj. Success updates the selected scalar and mask only; an invalid internal enum panics.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • objPtr – [in] Borrowed screen-distance value interpreted using the graph window scaling.

  • option – [in] Valid non-NONE selector for this option family; invalid internal selectors panic.

  • transactionPtr – [inout] Initialized or zeroed caller-owned candidate transaction; staged fields are updated only after successful parsing.

static int PrepareAxisPixelTransaction(Graph *graphPtr, Axis *axisPtr, AxisPixelTransaction *transactionPtr)

Prepare the axis pixel option family.

Initializes fresh transaction storage; do not pass an existing owning transaction. Examines the borrowed even-length option vector, identifies explicit options, and on first configuration parses effective defaults only for options not explicitly overridden. Processes every explicit occurrence in caller order, so a bad earlier value cannot be hidden by a later valid one. Returns a Tcl status without committing live derived fields. Contains only scalar candidates; no allocation cleanup is required on error.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [in] Borrowed axis with candidate Tk fields and the original even-length option vector installed; derived fields are not committed here.

  • transactionPtr – [out] Fresh caller-owned transaction storage, initialized here; must not already own resources. Success requires commit or cleanup.

static void CommitAxisPixelTransaction(Axis *axisPtr, AxisPixelTransaction *transactionPtr)

Commit prepared axis pixel candidates.

Copies only masked values into borderWidth, lineWidth and scrollUnits, then clears the mask. Unstaged options are unchanged. Performs no parsing, callback evaluation or recoverable validation; the caller must have prepared all option families first.

Parameters:
  • axisPtr – [inout] Live axis receiving only staged derived fields; all option families must be validated before any commit.

  • transactionPtr – [inout] Successfully prepared candidate transaction; transferred pointers and staging flags are cleared without freeing the record.

static int StageAxisLimit(Tcl_Interp *interp, Tcl_Obj *objPtr, AxisLimitOption option, AxisLimitTransaction *transactionPtr)

Stage one display or scroll limit.

Evaluates the candidate before writing the selected scalar and setting its mask bit. Failure leaves the candidate unchanged. An invalid internal enum panics. Cross-field and logarithmic range validation belong to preparation.

Parameters:
  • interp – [inout] Borrowed interpreter receiving conversion diagnostics; see Interpreter arguments.

  • objPtr – [in] Borrowed finite Tcl expression, or NULL/empty for an automatic limit; evaluation may execute Tcl.

  • option – [in] Valid non-NONE selector for this option family; invalid internal selectors panic.

  • transactionPtr – [inout] Initialized or zeroed caller-owned candidate transaction; staged fields are updated only after successful parsing.

static int PrepareAxisLimitTransaction(Graph *graphPtr, Axis *axisPtr, AxisLimitTransaction *transactionPtr)

Prepare the axis limit option family.

Initializes fresh transaction storage; do not pass an existing owning transaction. Examines the borrowed even-length option vector, identifies explicit options, and on first configuration parses effective defaults only for options not explicitly overridden. Processes every explicit occurrence in caller order, so a bad earlier value cannot be hidden by a later valid one. Returns a Tcl status without committing live derived fields. Contains only scalar candidates; no allocation cleanup is required on error. Starts with current live limits, checks final display and scroll ordering, and requires defined limits to be positive for log scaling even when only logScale changed.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [in] Borrowed axis with candidate Tk fields and the original even-length option vector installed; derived fields are not committed here.

  • transactionPtr – [out] Fresh caller-owned transaction storage, initialized here; must not already own resources. Success requires commit or cleanup.

static void CommitAxisLimitTransaction(Axis *axisPtr, AxisLimitTransaction *transactionPtr)

Commit prepared axis limit candidates.

Copies only masked requested/scroll limits into the live axis, then clears the mask. Validated but unstaged values remain untouched. Unstaged options are unchanged. Performs no parsing, callback evaluation or recoverable validation; the caller must have prepared all option families first.

Parameters:
  • axisPtr – [inout] Live axis receiving only staged derived fields; all option families must be validated before any commit.

  • transactionPtr – [inout] Successfully prepared candidate transaction; transferred pointers and staging flags are cleared without freeing the record.

static void FreeAxisTicks(Ticks *ticksPtr)

Release one explicit tick allocation.

Accepts NULL. Frees the allocation without modifying the caller pointer.

Parameters:
  • ticksPtr – [in] Owned tick allocation to release, or NULL; the caller pointer is not cleared.

static AxisTickOption GetAxisTickOption(Tcl_Obj *objPtr)

Classify an axis tick option.

Resolves the canonical name using axisOptionSpecs and returns the corresponding enum for major and minor tick lists. Returns the NONE enum for unrelated or unresolved names; performs no allocation.

Parameters:
  • objPtr – [in] Borrowed option-name object resolved through the axis option table, including abbreviations and synonyms.

static int IsAxisLooseOption(Tcl_Obj *objPtr)

Recognize the -loose option.

Delegates canonical-name matching to IsAxisOption after Tk has rejected unknown or ambiguous options.

Parameters:
  • objPtr – [in] Borrowed option-name object resolved through the axis option table, including abbreviations and synonyms.

static int GetAxisLooseFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, int *looseMinPtr, int *looseMaxPtr)

Parse one or two tick-range policies.

Accepts Tcl booleans or the exact string always. One entry applies to both ends; two entries specify minimum then maximum. Returns TCL_ERROR for invalid list length or entries without assigning the output pair. Allocates no retained storage.

Parameters:
  • interp – [inout] Borrowed interpreter receiving conversion diagnostics; see Interpreter arguments.

  • objPtr – [in] Borrowed list of one or two booleans or exact always keywords; NULL is not accepted.

  • looseMinPtr – [out] Required minimum-end policy output, assigned only after the complete input validates.

  • looseMaxPtr – [out] Required separate maximum-end policy output, assigned only on success.

static int StageAxisLoose(Tcl_Interp *interp, Tcl_Obj *objPtr, AxisLooseTransaction *transactionPtr)

Stage minimum and maximum tick-range policies.

Parses the complete one/two-entry value before updating the scalar pair and setting staged. Failure preserves earlier candidates; no owned allocation is created.

Parameters:
  • interp – [inout] Borrowed interpreter receiving conversion diagnostics; see Interpreter arguments.

  • objPtr – [in] Borrowed one- or two-entry loose-range policy list; NULL is not accepted.

  • transactionPtr – [inout] Initialized or zeroed caller-owned candidate transaction; staged fields are updated only after successful parsing.

static int PrepareAxisLooseTransaction(Graph *graphPtr, Axis *axisPtr, AxisLooseTransaction *transactionPtr)

Prepare the axis loose option family.

Initializes fresh transaction storage; do not pass an existing owning transaction. Examines the borrowed even-length option vector, identifies explicit options, and on first configuration parses effective defaults only for options not explicitly overridden. Processes every explicit occurrence in caller order, so a bad earlier value cannot be hidden by a later valid one. Returns a Tcl status without committing live derived fields. Contains only scalar candidates; no allocation cleanup is required on error.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [in] Borrowed axis with candidate Tk fields and the original even-length option vector installed; derived fields are not committed here.

  • transactionPtr – [out] Fresh caller-owned transaction storage, initialized here; must not already own resources. Success requires commit or cleanup.

static void CommitAxisLooseTransaction(Axis *axisPtr, AxisLooseTransaction *transactionPtr)

Commit prepared axis loose candidates.

Copies the staged minimum/maximum policies and clears staged. Unstaged options are unchanged. Performs no parsing, callback evaluation or recoverable validation; the caller must have prepared all option families first.

Parameters:
  • axisPtr – [inout] Live axis receiving only staged derived fields; all option families must be validated before any commit.

  • transactionPtr – [inout] Successfully prepared candidate transaction; transferred pointers and staging flags are cleared without freeing the record.

static int GetTicksByteCount(Tcl_Size nTicks, size_t *sizePtr)

Compute the allocation size for a variable-length tick array.

Rejects negative counts and size_t overflow using offsetof(Ticks, values). Writes the byte count only on TCL_OK. Does not impose MAXTICKS or report an interpreter error; the caller applies those policies.

Parameters:
  • nTicks – [in] Requested number of double entries; negative or unrepresentable counts fail.

  • sizePtr – [out] Required byte-size output, including the Ticks header; assigned only on TCL_OK.

static int GetAxisTicksFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, Ticks **ticksPtrPtr)

Allocate explicit ticks from a list of finite expressions.

NULL or an empty list returns TCL_OK with a NULL output. Rejects more than MAXTICKS entries, overflow, allocation failure and invalid/nonfinite expressions. Evaluates entries in input order with Tcl_ExprDoubleObj; no sorting or deduplication is performed. Frees partial storage on failure and leaves the output NULL. Successful nonempty storage belongs to the caller. Expression evaluation can execute Tcl substitutions; this helper supplies no graph lifetime guard.

Parameters:
  • interp – [inout] Borrowed interpreter receiving conversion diagnostics; see Interpreter arguments.

  • objPtr – [in] Borrowed list of finite Tcl expressions; NULL or empty selects automatic ticks. Evaluation may execute Tcl.

  • ticksPtrPtr – [out] Required output initialized to NULL; success transfers any nonempty allocation, released by FreeAxisTicks.

static int StageAxisTicks(Tcl_Interp *interp, Tcl_Obj *objPtr, AxisTickOption option, AxisTickTransaction *transactionPtr)

Stage a major or minor explicit tick allocation.

Parses and allocates the replacement before releasing an earlier candidate for that option. NULL is a valid staged candidate selecting automatic ticks. Success sets the mask; failure retains previous candidates. Invalid internal enums free the new allocation and panic.

Parameters:
  • interp – [inout] Borrowed interpreter receiving conversion diagnostics; see Interpreter arguments.

  • objPtr – [in] Borrowed list of finite Tcl expressions; NULL or empty stages automatic ticks. Evaluation may execute Tcl.

  • option – [in] Valid non-NONE selector for this option family; invalid internal selectors panic.

  • transactionPtr – [inout] Initialized or zeroed caller-owned candidate transaction; staged fields are updated only after successful parsing.

static void FreeAxisTickTransaction(AxisTickTransaction *transactionPtr)

Discard an axis tick transaction.

Releases owned major and minor tick allocations and zeroes the complete transaction. Requires initialized or zeroed storage. Safe after commit because transferred ownership has been cleared; does not alter live axis fields.

Parameters:
  • transactionPtr – [inout] Initialized or zeroed transaction whose candidate resources are released and complete contents reset; record is retained.

static int PrepareAxisTickTransaction(Graph *graphPtr, Axis *axisPtr, AxisTickTransaction *transactionPtr)

Prepare the axis tick option family.

Initializes fresh transaction storage; do not pass an existing owning transaction. Examines the borrowed even-length option vector, identifies explicit options, and on first configuration parses effective defaults only for options not explicitly overridden. Processes every explicit occurrence in caller order, so a bad earlier value cannot be hidden by a later valid one. Returns a Tcl status without committing live derived fields. On error releases all candidates owned by this transaction.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [in] Borrowed axis with candidate Tk fields and the original even-length option vector installed; derived fields are not committed here.

  • transactionPtr – [out] Fresh caller-owned transaction storage, initialized here; must not already own resources. Success requires commit or cleanup.

static void CommitAxisTickTransaction(Axis *axisPtr, AxisTickTransaction *transactionPtr)

Commit prepared axis tick candidates.

Transfers masked candidates into t1Ptr/t2Ptr, updates AXIS_CONFIG_MAJOR/MINOR according to non-NULL candidates, releases old arrays and clears transferred pointers and mask. A staged NULL restores automatic tick generation. Unstaged options are unchanged. Performs no parsing, callback evaluation or recoverable validation; the caller must have prepared all option families first.

Parameters:
  • axisPtr – [inout] Live axis receiving only staged derived fields; all option families must be validated before any commit.

  • transactionPtr – [inout] Successfully prepared candidate transaction; transferred pointers and staging flags are cleared without freeing the record.

static void FreeAxisShadow(Shadow *shadowPtr)

Release an owned shadow colour and reset its fields.

The Shadow record must be valid, with an owned Tk colour or NULL. Releases the colour reference, then clears colour and offset. Does not free the Shadow record itself.

Parameters:
  • shadowPtr – [inout] Caller-owned Shadow record containing an owned Tk color or NULL; color and offset are cleared.

static AxisShadowOption GetAxisShadowOption(Tcl_Obj *objPtr)

Classify an axis shadow option.

Resolves the canonical name using axisOptionSpecs and returns the corresponding enum for limits, tick and title shadows. Returns the NONE enum for unrelated or unresolved names; performs no allocation.

Parameters:
  • objPtr – [in] Borrowed option-name object resolved through the axis option table, including abbreviations and synonyms.

static int StageAxisShadow(Graph *graphPtr, Tcl_Obj *objPtr, AxisShadowOption option, AxisShadowTransaction *transactionPtr)

Stage one owned shadow colour and offset.

Acquires and validates a new shadow before releasing an earlier candidate for the same option. Success transfers the new colour reference into the transaction and sets its mask. Invalid internal enums release the new colour and panic.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • objPtr – [in] Borrowed shadow color/offset option value; successful parsing acquires a separate color reference.

  • option – [in] Valid non-NONE selector for this option family; invalid internal selectors panic.

  • transactionPtr – [inout] Initialized or zeroed caller-owned candidate transaction; staged fields are updated only after successful parsing.

static void FreeAxisShadowTransaction(AxisShadowTransaction *transactionPtr)

Discard an axis shadow transaction.

Releases owned three shadow colour references and zeroes the complete transaction. Requires initialized or zeroed storage. Safe after commit because transferred ownership has been cleared; does not alter live axis fields.

Parameters:
  • transactionPtr – [inout] Initialized or zeroed transaction whose candidate resources are released and complete contents reset; record is retained.

static int PrepareAxisShadowTransaction(Graph *graphPtr, Axis *axisPtr, AxisShadowTransaction *transactionPtr)

Prepare the axis shadow option family.

Initializes fresh transaction storage; do not pass an existing owning transaction. Examines the borrowed even-length option vector, identifies explicit options, and on first configuration parses effective defaults only for options not explicitly overridden. Processes every explicit occurrence in caller order, so a bad earlier value cannot be hidden by a later valid one. Returns a Tcl status without committing live derived fields. On error releases all candidates owned by this transaction.

Parameters:
  • graphPtr – [inout] Borrowed owning graph supplying the registry, interpreter and Tk resource context.

  • axisPtr – [in] Borrowed axis with candidate Tk fields and the original even-length option vector installed; derived fields are not committed here.

  • transactionPtr – [out] Fresh caller-owned transaction storage, initialized here; must not already own resources. Success requires commit or cleanup.

static void CommitAxisShadowTransaction(Axis *axisPtr, AxisShadowTransaction *transactionPtr)

Commit prepared axis shadow candidates.

Transfers masked colours and offsets into the three text styles, clears transferred candidate fields, releases old colours and clears the mask. Unstaged options are unchanged. Performs no parsing, callback evaluation or recoverable validation; the caller must have prepared all option families first.

Parameters:
  • axisPtr – [inout] Live axis receiving only staged derived fields; all option families must be validated before any commit.

  • transactionPtr – [inout] Successfully prepared candidate transaction; transferred pointers and staging flags are cleared without freeing the record.

struct AxisLimitTransaction

Scalar requested/scroll candidates, initialized from live values; stagedMask selects fields to commit.

Public Members

unsigned int stagedMask

Bit mask selecting staged replacements to commit or release.

double reqMin

Requested lower limit staged for commit or abort.

double reqMax

Requested upper limit staged for commit or abort.

double scrollMin

Scroll-region lower limit staged for commit or abort.

double scrollMax

Scroll-region upper limit staged for commit or abort.

struct AxisTickTransaction

Owns major/minor tick allocations until commit.

A masked NULL candidate requests automatic ticks.

Public Members

unsigned int stagedMask

Bit mask selecting staged replacements to commit or release.

Ticks *majorTicksPtr

Owned major-tick replacement staged for commit or abort.

Ticks *minorTicksPtr

Owned minor-tick replacement staged for commit or abort.

struct AxisLooseTransaction

Scalar minimum/maximum policies; staged distinguishes no change from a parsed pair.

Public Members

int staged

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

int looseMin

Lower-limit loose-mode selector staged for commit or abort.

int looseMax

Upper-limit loose-mode selector staged for commit or abort.

struct AxisPixelTransaction

Scalar pixel candidates; stagedMask identifies parsed fields and no heap cleanup is needed.

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 lineWidth

Stroke thickness in pixels staged for commit or abort.

int scrollIncrement

Unit-scroll increment in pixels staged for commit or abort.

struct AxisShadowTransaction

Owns staged Tk colour references and offsets until commit; unmasked entries are zero initialized.

Public Members

unsigned int stagedMask

Bit mask selecting staged replacements to commit or release.

Shadow limitsShadow

Limit-label shadow staged for commit or abort.

Shadow tickShadow

Tick-label shadow staged for commit or abort.

Shadow titleShadow

Title shadow staged for commit or abort.

struct AxisTagsTransaction

Owns one staged string-list allocation until commit; staged distinguishes no change from an empty list.

Public Members

int staged

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

char **tags

Owned replacement binding-tag array staged for commit or abort.

struct AxisFormatTransaction

Owns one split-list allocation with at most two formats until commit; count and staged accompany it.

Public Members

int staged

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

char **formats

Owned replacement format-string array staged for commit or abort.

int nFormats

Number of replacement format strings staged for commit or abort.

Ranges, coordinates and tick sweeps

group Axis ranges and tick sweeps

Functions

static double RoundToStep(double value, double step)

Round a finite value to a multiple of a finite nonzero step.

Uses halfway-away-from-zero rounding without an integer conversion. Returns the original value if inputs, quotient or rounded product cannot be used safely; does not report a Tcl error.

Parameters:
  • value – [in] Value to round; returned unchanged when the inputs or intermediate arithmetic are unusable.

  • step – [in] Finite nonzero rounding interval; invalid values leave the input value unchanged.

static int GetLinearSweep(double min, double max, double step, double *tickMinPtr, double *tickMaxPtr, Tcl_Size *nTicksPtr)

Compute bounded enclosing tick endpoints and count.

Requires finite endpoints and a positive finite step. Works in step units to avoid subtracting large raw endpoints. Rejects nonfinite quotients/products and counts outside 1..MAXTICKS before converting to Tcl_Size. Returns TRUE and assigns all outputs only on success; FALSE leaves outputs untouched.

Parameters:
  • min – [in] Lower endpoint used to select mapping bounds and tick spacing.

  • max – [in] Upper endpoint in the same coordinate space as min.

  • step – [in] Positive finite interval in the same units as min/max; other values return FALSE.

  • tickMinPtr – [out] Required lower enclosing-tick output; assigned only on TRUE.

  • tickMaxPtr – [out] Required separate upper enclosing-tick output; assigned only on TRUE.

  • nTicksPtr – [out] Required tick-count output in 1..MAXTICKS; assigned only on TRUE.

static double AutomaticLinearStep(double min, double max)

Select a practical automatic linear tick interval.

First applies NiceNum to the representable positive span, aiming for DEF_NUM_TICKS intervals. If that fails, uses quarter-scaled endpoint subtraction to avoid span overflow. Returns a positive finite nice step when possible, otherwise 1.0; does not allocate or report errors.

Parameters:
  • min – [in] Lower endpoint used to select mapping bounds and tick spacing.

  • max – [in] Upper endpoint in the same coordinate space as min.

static void SetAxisRange(AxisRange *rangePtr, double min, double max)

Store endpoints and cached normalization factors.

Stores min/max unchanged, computes their difference and substitutes a unit range when its absolute value is below DBL_EPSILON. Stores the reciprocal as scale. Does not sort or validate endpoints; an overflowed difference remains nonfinite for the normalization helpers to handle.

Parameters:
  • rangePtr – [inout] Caller-owned range record whose endpoints, range and scale are replaced.

  • min – [in] Lower endpoint in axis space; not sorted or validated here.

  • max – [in] Upper endpoint in axis space; logarithmic ranges use exponents.

static double NormalizeAxisValue(const AxisRange *rangePtr, double value)

Normalize a coordinate against a prepared axis range.

Uses cached range/scale for finite spans. For an overflowed span, halves endpoints and the value before division; returns NAN when the half-span is invalid or zero. Does not clip to 0..1 or apply logarithms, descending direction or screen offsets.

Parameters:
  • rangePtr – [in] Borrowed prepared range with consistent endpoints and cached range/scale.

  • value – [in] Axis-space coordinate, already logarithmically converted when needed.

static double InterpolateAxisValue(const AxisRange *rangePtr, double norm)

Reconstruct an axis-space value from a normalized coordinate.

Uses cached range and minimum for finite spans, or a half-scaled endpoint interpolation for overflowed spans. Does not clamp the normalized coordinate. Extrapolation may produce nonfinite results; callers must validate values before drawing or integer conversion.

Parameters:
  • rangePtr – [in] Borrowed prepared range.

  • norm – [in] Normalized fraction; values outside [0,1] request extrapolation rather than clipping.

static double LogAxisValue(double exponent)

Convert a base-ten exponent within the supported normal-double interval.

Rejects nonfinite exponents and those outside log10(DBL_MIN)..log10(DBL_MAX) with NAN. Returns exact DBL_MIN/DBL_MAX at the endpoints to avoid power rounding across them. Otherwise requires a finite positive power result. This policy deliberately does not expose subnormal values.

Parameters:
  • exponent – [in] Base-ten exponent to convert; supported bounds are log10(DBL_MIN) through log10(DBL_MAX).

static double MapHorizontalAxisCoordinate(Graph *graphPtr, Axis *axisPtr, double value)

Map an already converted axis-space value horizontally.

Normalizes, rejects nonfinite normalized values and applies descending reversal. Uses the owning track world rectangle when present, otherwise graph horizontal range/offset. Track spans have a one- pixel minimum. Does not perform logarithmic conversion or clipping.

Parameters:
  • graphPtr – [in] Borrowed graph with current layout and mapping scales.

  • axisPtr – [in] Borrowed axis with a prepared axisRange and live owning track, if any.

  • value – [in] Already converted axis-space value; logarithmic axes require an exponent, not raw data.

static double MapVerticalAxisCoordinate(Graph *graphPtr, Axis *axisPtr, double value)

Map an already converted axis-space value vertically.

Normalizes, rejects nonfinite normalized values and applies descending reversal and downward screen Y direction. Uses the owning track world rectangle or graph vertical range/offset. Track spans have a one-pixel minimum; no clipping or logarithmic conversion occurs here.

Parameters:
  • graphPtr – [in] Borrowed graph with current layout and mapping scales.

  • axisPtr – [in] Borrowed axis with a prepared axisRange and live owning track, if any.

  • value – [in] Already converted axis-space value; logarithmic axes require an exponent, not raw data.

static void MakeLogRange(double value, double *minPtr, double *maxPtr)

Construct a positive logarithmic interval around one value.

Invalid or nonpositive input selects 0.001..1.0. Otherwise chooses roughly one decade centred on the value, shifting the interval at supported exponent endpoints, and converts it with LogAxisValue. Writes both outputs without changing an Axis record.

Parameters:
  • value – [in] Raw positive data value around which to form a range; invalid inputs select fallback bounds.

  • minPtr – [out] Required separate output for the positive raw-data lower limit.

  • maxPtr – [out] Required separate output for the positive raw-data upper limit.

static int InRange(double x, AxisRange *rangePtr)

Test a finite coordinate against a prepared range.

Normalizes the coordinate, rejects nonfinite results and applies DBL_EPSILON tolerance around the unit interval. Uses axis-space coordinates, which are exponents for logarithmic axes; does not perform raw-data log conversion.

Parameters:
  • x – [in] Axis-space coordinate to test, not unconverted logarithmic data.

  • rangePtr – [in] Borrowed prepared range; not modified despite the non-const pointer type.

static int AxisIsHorizontal(Graph *graphPtr, Axis *axisPtr)

Resolve logical axis identity into screen orientation.

Compares the logical Y class with graph inversion. Borrows graph and axis; does not modify their class or layout.

Parameters:
  • graphPtr – [in] Borrowed graph supplying inversion state.

  • axisPtr – [in] Borrowed axis supplying its logical class identity.

static double InvHMap(Graph *graphPtr, Axis *axisPtr, double x)

Invert horizontal mapping into a logical data value.

Normalizes against the full owning-track world extent or graph horizontal scale, reverses descending direction and interpolates axis space. Converts logarithmic exponents through LogAxisValue. Extrapolates outside the plot and may return nonfinite values; no layout is performed.

Parameters:
  • graphPtr – [in] Borrowed graph with current layout and mapping scales.

  • axisPtr – [in] Borrowed axis with a prepared axisRange and live owning track, if any.

  • x – [in] Horizontal widget coordinate; off-plot positions are extrapolated.

static double InvVMap(Graph *graphPtr, Axis *axisPtr, double y)

Invert vertical mapping into a logical data value.

Normalizes against the full owning-track world extent or graph vertical scale, reverses descending direction and accounts for downward screen Y. Interpolates axis space and converts logarithmic exponents. Does not clip or refresh layout; callers must handle nonfinite results.

Parameters:
  • graphPtr – [in] Borrowed graph with current layout and mapping scales.

  • axisPtr – [in] Borrowed axis with a prepared axisRange and live owning track, if any.

  • y – [in] Vertical widget coordinate increasing downward; off-plot positions are extrapolated.

static void GetDataLimits(Axis *axisPtr, double min, double max)

Accumulate an element extent into an axis data range.

Expands valueRange endpoints by comparison only; does not validate the extent, recompute cached range/scale or apply requested limits. Rbc_ResetAxes initializes the accumulation sentinels before calling this helper.

Parameters:
  • axisPtr – [inout] Live axis whose initialized valueRange endpoints accumulate the extent.

  • min – [in] Contributing raw-data lower bound.

  • max – [in] Contributing raw-data upper bound; cached range/scale are not recomputed here.

static void FixAxisRange(Axis *axisPtr)

Resolve accumulated data bounds and requested display limits.

Supplies empty-data defaults, expands degenerate ranges and repairs invalid logarithmic inputs before caching valueRange. Copies data limits into min/max, applies requested endpoints and adjusts automatic endpoints when necessary. Applies automatic window shifting only when neither requested endpoint is defined, clamping negative shiftBy to zero. Marks AXIS_DIRTY and updates previous limits when resolved min/max change. Does not generate ticks or map geometry.

Parameters:
  • axisPtr – [inout] Borrowed axis with accumulated valueRange and configured requested limits; resolved ranges and dirty state are updated.

static double NiceNum(double x, int round)

Choose a decimal 1/2/5/10 multiple near a positive magnitude.

Uses Heckbert’s nice-number method (Graphics Gems, pages 61-63). The round argument selects nearest- style thresholds rather than upward enclosure. Expects a positive input; does not guarantee a finite positive result for extreme magnitudes, so scaling callers validate it. No graph state is changed.

Parameters:
  • x – [in] Positive magnitude to approximate; extreme results must be validated by the caller.

  • round – [in] Nonzero selects nearest-style thresholds; zero selects upward enclosure.

static Ticks *GenerateTicks(TickSweep *sweepPtr)

Allocate values from an internal tick sweep.

Returns an owned allocation, possibly with zero ticks. Invalid counts or nonfinite sweep fields produce an empty array. A zero step selects the fixed log10(2)..log10(9) table and allows at most eight entries. Other steps generate rounded successive values, stopping before a nonfinite value. Uses ckalloc, so allocation failure is not a recoverable NULL result. Free the returned allocation with ckfree.

Parameters:
  • sweepPtr – [in] Borrowed sweep recipe; zero step selects the fixed logarithmic minor-tick table.

Ticks *Rbc_AllocAxisMajorTicks(Axis *axisPtr)

Return an independently owned major-tick array.

Copies t1Ptr when present, whether explicit or cached generated ticks; size or attempted-allocation failure then returns NULL. Otherwise generates from majorSweep, supporting hidden Polar axes without rectangular tick caches. The axis and prepared sweep are borrowed; callers free the result with ckfree. Generation uses the fatal allocator rather than the copy path’s attempted allocator.

Parameters:
  • axisPtr – [in] Borrowed axis with the prepared range and caches described above; no mutation or reference acquisition.

static void LogScaleAxis(Axis *axisPtr, double min, double max)

Prepare logarithmic mapping bounds and tick sweeps.

Repairs invalid positive inputs and collapsed logarithms, then selects major ticks in exponent space. Spans exceeding ten enclosing decades use a nice exponent interval; narrower spans use unit decades. Applies endpoint loose policies and supported exponent bounds. Narrow minor sweeps use the zero-step log table; wide sweeps use four fractions at 0.2 increments. Explicit major ticks disable automatic minors. Writes axisRange and both sweep records, without allocating tick arrays.

Parameters:
  • axisPtr – [inout] Borrowed axis supplying loose-endpoint and tick policies; mapping range and sweep recipes are overwritten.

  • min – [in] Lower raw-data limit; logarithmic conversion is performed here only for LogScaleAxis.

  • max – [in] Upper raw-data limit; logarithmic conversion is performed here only for LogScaleAxis.

static void LinearScaleAxis(Axis *axisPtr, double min, double max)

Prepare linear mapping bounds and tick sweeps.

Tries a requested positive step, reducing overly large intervals by halves. Falls back to AutomaticLinearStep if the requested sweep is impractical, then to no major ticks if necessary. Applies independent loose policies to mapping endpoints. Automatic minors subdivide the major interval unless explicit major ticks are configured. Writes axisRange and sweep records; actual arrays are generated later.

Parameters:
  • axisPtr – [inout] Borrowed axis supplying loose-endpoint and tick policies; mapping range and sweep recipes are overwritten.

  • min – [in] Lower raw-data limit; logarithmic conversion is performed here only for LogScaleAxis.

  • max – [in] Upper raw-data limit; logarithmic conversion is performed here only for LogScaleAxis.

static void SweepTicks(Axis *axisPtr)

Refresh generated tick caches while retaining explicit arrays.

Replaces t1Ptr/t2Ptr only when their AXIS_CONFIG_MAJOR/MINOR flags are clear. Frees old generated arrays and owns the new GenerateTicks results. Does not change explicit arrays, recompute sweeps or report recoverable allocation errors.

Parameters:
  • axisPtr – [inout] Borrowed axis with prepared sweeps; generated tick arrays are replaced while explicit arrays remain owned by the axis.

void Rbc_ResetAxes(Graph *graphPtr)

Recompute data ranges and scaling sweeps for the graph.

Prepares bar frequencies/stacks, resets every registered axis to accumulation sentinels and collects extents from elements that are neither hidden nor plotHidden. Applies Polar empty-grid fallbacks or Smith unit-circle bounds to mapped nonlogarithmic grid axes. Resolves requested ranges, constrains scaling inputs by scroll limits and computes linear/log sweeps. Clears RESET_AXES and requests geometry, layout, mapping and redraw; does not allocate tick caches or draw. Registered delete- pending records are included because consumers may still reference them.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

static int GetMinorTickPosition(const Axis *axisPtr, const Ticks *majorPtr, Tcl_Size index, double fraction, double *valuePtr)

Resolve a minor fraction against a major interval.

Requires a valid major array index. With explicit majors, requires a following distinct endpoint and a fraction strictly inside 0..1, interpolates between adjacent entries, and rejects rounded results outside that open interval. Otherwise adds majorSweep.step times fraction. Returns FALSE for invalid/nonfinite results without assigning the output; TRUE writes an axis-space coordinate.

Parameters:
  • axisPtr – [in] Borrowed axis with the prepared range and caches described above; no mutation or reference acquisition.

  • majorPtr – [in] Borrowed major-tick array with a readable entry at index.

  • index – [in] Major-array index in 0..nTicks-1; explicit interpolation additionally needs a following entry.

  • fraction – [in] Minor interval fraction; explicit-major mode requires strictly between zero and one.

  • valuePtr – [out] Required minor-position output in axis space; assigned only on TRUE.

Labels, geometry and presentation

group Axis labels and presentation

Functions

static int LayoutSize(Tcl_WideInt value)

Clamp a wide layout size to a nonnegative int.

Returns zero for nonpositive input; otherwise uses Rbc_ClampToInt. Does not alter graph state.

Parameters:
  • value – [in] Wide integer layout extent in pixels, clamped before narrowing to int.

static int LayoutRange(Tcl_WideInt value)

Clamp a wide layout range to a positive int.

Returns one below the minimum usable scalar range; otherwise uses Rbc_ClampToInt. This arithmetic floor does not make collapsed plot geometry drawable.

Parameters:
  • value – [in] Wide integer layout extent in pixels, clamped before narrowing to int.

static int AxisRotatedSize(double value)

Round a rotated extent without overflowing int.

Nonfinite or nonpositive inputs return zero. Values within half a unit of INT_MAX are saturated before ROUND adds its rounding offset; ordinary positive extents retain legacy rounding.

Parameters:
  • value – [in] Rotated pixel extent; nonfinite/nonpositive values return zero, excessive values saturate.

static void FreeLabels(Rbc_Chain *chainPtr)

Release every label in a chain and empty its links.

Frees the owned TickLabel allocations, then resets the chain. The chain itself remains owned by the axis and reusable. Requires a valid chain.

Parameters:
  • chainPtr – [inout] Valid caller-owned chain whose owned TickLabel records and links are released; the chain itself remains reusable.

static TickLabel *NewTickLabel(const char *string)

Allocate a label with its copied string inline.

Checks allocation-size overflow and uses the fatal allocator. Initializes anchor coordinates to DBL_MAX to mark an unmapped label; dimensions are filled during geometry measurement. The caller owns the allocation and frees it with ckfree.

Parameters:
  • string – [in] Borrowed NUL-terminated label text, copied into the returned allocation.

TickLabel *Rbc_AllocAxisTickLabel(Graph *graphPtr, Axis *axisPtr, double value)

Format and allocate one major-tick label.

Produces the legacy numeric label first: exponent notation for logarithmic axes, NUMDIGITS significant digits otherwise. A nonempty formatter prefix receives widget path and that label. Preserves interpreter state, reports callback errors in the background and falls back to the numeric label. After evaluation checks graph validity without dereferencing the axis; invalidation frees the candidate and returns NULL. Callers must stop traversing cached axis/layout pointers on NULL. Successful labels are caller-owned.

Parameters:
  • graphPtr – [inout] Borrowed graph kept alive by the caller through Tcl evaluation and subsequent callback-validity checks.

  • axisPtr – [inout] Borrowed axis supplying formatting state; may become invalid during Tcl evaluation and must not be reused after a NULL result.

  • value – [in] Value in axis space; logarithmic axes use base-ten exponents.

static void AxisOffsets(Graph *graphPtr, Axis *axisPtr, int margin, int axisOffset, AxisInfo *infoPtr)

Compute baseline, tick and label offsets for one margin band.

Requires a concrete margin and prepared axis thickness. Updates title rotation/anchor/position, tick anchor and picking region. Accounts for plot and axis borders, alternate titles and line width. Returns absolute baseline/major/minor/label positions in AxisInfo. A negative tick length swaps the baseline and major endpoint to retain inward-tick behavior.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [inout] Borrowed live axis with the range, options and caches required above; no reference is acquired.

  • margin – [in] Concrete MARGIN_TOP, MARGIN_BOTTOM, MARGIN_LEFT or MARGIN_RIGHT selector.

  • axisOffset – [in] Accumulated perpendicular margin-band offset from the plot edge, in pixels.

  • infoPtr – [out] Required AxisInfo output receiving absolute baseline, tick and label screen coordinates.

static void MakeAxisLine(Graph *graphPtr, Axis *axisPtr, int line, Segment2D *segPtr)

Map the baseline endpoints from the prepared axis range.

Writes one Segment2D using logical orientation and track-aware coordinate mapping. The line argument is the fixed screen coordinate perpendicular to the axis. Inputs are axis-space bounds, already logarithmic when appropriate.

Parameters:
  • graphPtr – [in] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [in] Borrowed axis with the prepared range and caches described above; no mutation or reference acquisition.

  • line – [in] Absolute baseline screen coordinate perpendicular to the axis.

  • segPtr – [out] Required single-segment output in display coordinates.

static void MakeTick(Graph *graphPtr, Axis *axisPtr, double value, int tick, int line, Segment2D *segPtr)

Map one axis-space value to a tick segment.

Writes the segment between the absolute line and tick screen coordinates. Chooses screen orientation from logical class and inversion. Does not check range membership or convert raw logarithmic values; the caller does so before mapping.

Parameters:
  • graphPtr – [in] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [in] Borrowed axis with the prepared range and caches described above; no mutation or reference acquisition.

  • value – [in] Value in axis space; logarithmic axes use base-ten exponents.

  • tick – [in] Absolute tick-end screen coordinate perpendicular to the axis, not a tick length.

  • line – [in] Absolute baseline screen coordinate perpendicular to the axis.

  • segPtr – [out] Required single-segment output in display coordinates.

static void MapAxis(Graph *graphPtr, Axis *axisPtr, int offset, int margin)

Replace cached axis segments and position measured labels.

Requires prepared tick arrays and the matching filtered label chain when ticks are shown. Computes offsets, releases old segments, checks count/byte overflow and attempts allocation. Failure leaves zero segments and returns without an interpreter error. Maps in-range major/minor ticks and label anchors, including labelOffset. Saves the owned segment array only when nonempty; does not evaluate label callbacks.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [inout] Borrowed axis with current ticks and matching measured labels; owned segments and label positions are replaced.

  • offset – [in] Perpendicular offset from the plot edge in pixels, including preceding axes in this margin/track.

  • margin – [in] Concrete MARGIN_TOP, MARGIN_BOTTOM, MARGIN_LEFT or MARGIN_RIGHT selector.

static void DrawAxis(Graph *graphPtr, Drawable drawable, Axis *axisPtr)

Draw a mapped axis and queue its scrollbar update.

Borrows prepared axis geometry. Draws its optional screen border, title, labels and segments through renderer interfaces, with native segment fallback. Screen strokes use projecting caps. When valid scroll geometry exists, updates live min/max and queues scrollbar fractions; the Tcl callback is deferred. Ends all renderer contexts before returning.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • drawable – [in] Borrowed compatible screen destination with graph-window coordinate origin.

  • axisPtr – [inout] Borrowed live axis with the range, options and caches required above; no reference is acquired.

static void AxisExport(Rbc_ExportContext *exportPtr, Axis *axisPtr)

Export mapped title, labels and strokes through the shared renderer.

Borrows the export context and axis geometry; closes contexts it creates. Uses butt caps for exported segments. Unlike DrawAxis, emits no axis border and performs no scrollbar update. Does not reformat labels or refresh layout.

Parameters:
  • exportPtr – [inout] Borrowed document output context; geometry must already match the current export dimensions.

  • axisPtr – [in] Borrowed axis with the prepared range and caches described above; no mutation or reference acquisition.

static void MakeGridLine(Graph *graphPtr, Axis *axisPtr, double value, Segment2D *segPtr)

Map a tick into a full plot-spanning grid segment.

Uses axis-space coordinates and logical orientation. The varying coordinate uses track-aware mapping; the other dimension spans the current graph plot rectangle. Callers entering a track must establish the desired viewport first.

Parameters:
  • graphPtr – [in] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [in] Borrowed axis with the prepared range and caches described above; no mutation or reference acquisition.

  • value – [in] Value in axis space; logarithmic axes use base-ten exponents.

  • segPtr – [out] Required single-segment output in display coordinates.

void Rbc_GetAxisSegments(Graph *graphPtr, Axis *axisPtr, int minorGrid, Segment2D **segPtrPtr, Tcl_Size *nSegmentsPtr)

Allocate in-range grid segments for an optional axis.

Initializes outputs to NULL and zero; NULL axes produce no segments. Borrows existing tick arrays or generates temporary ones without installing them on the axis. Includes major ticks and optionally minor ticks, using checked capacity arithmetic and attempted segment allocation. Failure or empty output leaves NULL/zero. Frees temporary ticks on all exits. Successful segments belong to the caller and must be freed with ckfree.

Parameters:
  • graphPtr – [in] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [in] Borrowed prepared axis, or NULL for no segments; its caches are not changed.

  • minorGrid – [in] Nonzero includes minor ticks as well as major ticks.

  • segPtrPtr – [out] Required output initialized to NULL; successful nonempty output transfers an array to free with ckfree.

  • nSegmentsPtr – [out] Required output initialized to zero; receives the number of returned segments.

static void GetAxisGeometry(Graph *graphPtr, Axis *axisPtr)

Rebuild labels and measure the perpendicular axis thickness.

Frees old labels, refreshes generated ticks when shown, filters major-label positions and allocates formatted labels. Stops immediately on formatter invalidation; callers must check graph callback validity before continuing. Measures multiline/rotated labels, baseline, ticks and title using wide size arithmetic, then stores clamped width or height for the orientation. Does not assign final label anchors.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [inout] Borrowed configured axis whose labels/tick caches and dimensions are rebuilt; callbacks can invalidate it.

static int GetMarginGeometry(Graph *graphPtr, Margin *marginPtr)

Measure visible axes and alternate-title requirements in one margin.

Optionally refreshes axis geometry when GET_AXIS_GEOMETRY is set, stopping with zero if a formatter invalidates layout. Stores visible count, thickness, title length and axesOffset. Track-owned Y margins reserve the maximum summed thickness of any track rather than summing all tracks. Applies minimum margin dimensions and clamps wide sums; the return value is not by itself a callback- validity indicator.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • marginPtr – [inout] Borrowed graph margin whose visible-axis count, thickness and title requirements are updated.

void Rbc_MapAxes(Graph *graphPtr)

Map visible margin axes after arranging track viewports.

Calls Rbc_LayoutTracks, then maps nonhidden onscreen axes in margin order. Ordinary axes accumulate margin offsets; track axes use per-track offsets and the full world rectangle inside an entered viewport. Skips empty visible tracks and restores the graph viewport after each local axis. Requires current ranges and measured labels.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

static int AxisLayoutUsable(Graph *graphPtr)

Check whether both plot ranges permit mapped presentation.

Returns true only when horizontal and vertical ranges exceed one pixel. Prevents drawing, exporting or picking stale geometry and newly allocated labels with unmapped DBL_MAX anchors. Does not perform layout.

Parameters:
  • graphPtr – [in] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

static void DrawTrackAxis(Graph *graphPtr, Drawable drawable, Axis *axisPtr)

Confine local axis output to its visible scrolling band.

Allocates a graph-sized temporary pixmap and GC, copies the visible band into it, draws the complete axis there and copies only that band back. The band includes the axis margin; inversion switches the clipped direction. Releases temporary resources. Empty bands return immediately.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • drawable – [in] Borrowed compatible screen destination with graph-window coordinate origin.

  • axisPtr – [inout] Borrowed mapped axis with a non-NULL live owning track; drawing may queue scrollbar updates.

void Rbc_DrawAxes(Graph *graphPtr, Drawable drawable)

Draw eligible axes with scrolling-track clipping.

Returns for collapsed plot geometry. Traverses margin chains, skipping hidden/offscreen axes and tracks with collapsed visible rectangles. Uses DrawTrackAxis only for track-owned axes when track scrolling is enabled; otherwise draws directly. Borrows all axis records and does not map them.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • drawable – [in] Borrowed compatible screen destination with graph-window coordinate origin.

void Rbc_AxesExport(Graph *graphPtr, Rbc_ExportContext *exportPtr)

Export eligible axes with scrolling-track clip scopes.

Uses the same collapsed-layout and visibility checks as screen drawing. For scrolling local axes, opens a renderer clip around the visible band including margins, exports the axis and closes the scope. Requires geometry already mapped for the export dimensions.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • exportPtr – [inout] Borrowed document output context; geometry must already match the current export dimensions.

void Rbc_DrawAxisLimits(Graph *graphPtr, Drawable drawable)

Draw formatted range annotations around the plot edges.

Iterates the axis registry in hash order, selecting nFormats rather than margin visibility. Formats axisRange endpoints with bounded snprintf, uses logical orientation plus inversion and swaps labels for descending axes. Measures/draws with limitsTextStyle and updates its rotation/anchor. Logarithmic annotations currently receive exponent values; these are not the data-space limits command results.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • drawable – [in] Borrowed compatible screen destination with graph-window coordinate origin.

void Rbc_AxisLimitsExport(Graph *graphPtr, Rbc_ExportContext *exportPtr)

Export formatted range annotations with screen-equivalent endpoint placement.

Iterates formatted registry axes and formats axisRange endpoints with bounded snprintf. Uses inversion-aware orientation, swaps descending endpoint strings and measures with limitsTextStyle, matching screen placement. Ends its output context even when layout is collapsed.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • exportPtr – [inout] Borrowed document output context; geometry must already match the current export dimensions.

Axis *Rbc_GetFirstAxis(Rbc_Chain *chainPtr)

Borrow the first record in an axis chain.

Returns NULL for an empty chain. Performs no hidden/deletion filtering or reference acquisition; callers must apply any additional eligibility requirements.

Parameters:
  • chainPtr – [in] Borrowed valid chain of axis pointers; no record reference is acquired.

Axis *Rbc_NearestAxis(Graph *graphPtr, int x, int y)

Pick the first axis whose label, title or region contains a point.

Returns NULL for unusable layout or no hit. Iterates registry order, not nearest-distance order; skips hidden/offscreen axes and collapsed or out-of-band scrolling tracks. Tests rotated label polygons, then title polygon, then line region. Sets detail to label, title or line on the borrowed returned record. Requires prepared geometry and does not acquire a reference.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

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

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

void Rbc_AxisFontsChanged(Graph *graphPtr)

Refresh configured axis styles after named-font changes.

Visits all registered configured axes, refreshes text GCs and title dimensions, and marks each AXIS_DIRTY. Does not regenerate tick labels or directly schedule full graph layout; the font-change caller owns subsequent invalidation.

Parameters:
  • graphPtr – [inout] Borrowed graph with registered configured axes; caller schedules subsequent geometry/layout invalidation.

Layout, queries, scrolling and notifications

group Axis layout and view control

Functions

static int ValidateAxisCommandPrefix(Tcl_Interp *interp, Tcl_Obj *objPtr)

Validate the list representation of an optional command prefix.

NULL and empty lists succeed. Returns a Tcl parsing status for other values; does not evaluate the command, resolve its first word or retain list elements.

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

  • objPtr – [in] Borrowed command-prefix object, or NULL; an empty list is also accepted.

static void NotifyAxisScrollbar(ClientData clientData)

Deliver the latest queued scrollbar fractions at idle.

Clears the pending flag before delivery and skips destroyed graphs, deleted axes and absent/empty prefixes. Copies the prefix and appends owned fraction objects before evaluation. Preserves graph/interpreter storage and interpreter state, evaluates globally and reports errors in the background. Does not dereference the axis after Tcl evaluation; destruction cancels outstanding idle delivery.

Parameters:
  • clientData – [inout] Borrowed Axis pointer registered for idle delivery; destruction must cancel the pending callback.

static void UpdateAxisScrollbar(Graph *graphPtr, Axis *axisPtr, double firstFract, double lastFract)

Coalesce a scrollbar notification using the latest fractions.

Suppresses updates during GRAPH_EXPORT. Otherwise replaces pending fraction values and schedules at most one idle callback for the axis. Does not evaluate Tcl, compare fractions with the previous delivery or retain a separate axis reference.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [inout] Borrowed live axis with the range, options and caches required above; no reference is acquired.

  • firstFract – [in] Latest screen-oriented first scrollbar fraction, copied without clamping.

  • lastFract – [in] Latest screen-oriented last scrollbar fraction, copied without clamping.

static double AdjustViewport(double offset, double windowSize)

Constrain a normalized scrolling offset using canvas-style rules.

For views no larger than the world, constrains the offset to 0..1-windowSize. Larger views permit the world to move within the window. Returns the adjusted offset without validating finiteness; callers establish valid scroll state first.

Parameters:
  • offset – [in] Finite normalized start position established by the caller.

  • windowSize – [in] Finite view/world size ratio; values greater than one allow the world to move within the view.

static int GetAxisScrollState(Axis *axisPtr, AxisRange *rangePtr, double *viewMinNormPtr, double *viewMaxNormPtr)

Derive a normalized current view and effective scroll world.

Starts from valueRange and min/max, replaces missing world sentinels with view endpoints, then applies requested scroll bounds. Rejects nonfinite values, nonpositive logarithmic inputs and nonincreasing worlds. Intersects the view with the world, collapsing wholly outside views to the nearest boundary. Allows a zero-width view. On TRUE returns normalized endpoints and a world range in linear or exponent coordinates. Outputs must not be consumed after FALSE; no live axis state is modified.

Parameters:
  • axisPtr – [in] Borrowed axis with the prepared range and caches described above; no mutation or reference acquisition.

  • rangePtr – [out] Required effective-world range in linear or exponent coordinates; may be written even on FALSE.

  • viewMinNormPtr – [out] Required normalized lower-view output; assigned only on TRUE.

  • viewMaxNormPtr – [out] Required separate normalized upper-view output; assigned only on TRUE.

static int GetPolarAutoAspect(Graph *graphPtr, double *aspectPtr)

Compute a physical plot ratio for equal Polar data-unit scaling.

Requires a Polar widget with automatic aspect enabled, a grid and two nonlogarithmic mapped axes with finite positive ranges. Uses the grid-selected axes rather than primary x/y. Returns X/Y range ratio, or its inverse when inverted, only if finite and positive. FALSE leaves the output untouched; performs no layout.

Parameters:
  • graphPtr – [in] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • aspectPtr – [out] Required positive physical width/height ratio output; assigned only on TRUE.

static void ComputeMargins(Graph *graphPtr)

Combine axis, title, legend and aspect requirements into margins.

Measures each margin and checks callback validity immediately afterward. Maps the legend against the estimated cavity, adds margin-hosted legend dimensions, applies automatic Polar or fixed aspect, reserves adjoining alternate-title space and finally applies positive requested margin overrides. Uses wide intermediate sizes and clamped storage. Callback invalidation returns early; callers must not treat partial geometry as completed layout.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

void Rbc_LayoutMargins(Graph *graphPtr)

Compute plot bounds, mapping scales and graph-title position.

Calls ComputeMargins and stops on callback invalidation. Adds widget/plot insets, computes the cavity with wide arithmetic and clamps it to at least one pixel. Plot padding defines mapping offsets/ranges; stores reciprocals and title position. A one-pixel arithmetic range is not a drawable-layout guarantee. Does not map axes or clear the caller layout flags.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

static void GetAxisLimits(Axis *axisPtr, double *minPtr, double *maxPtr)

Read prepared mapping bounds in data coordinates.

Copies linear axisRange endpoints or converts logarithmic exponents with LogAxisValue. Does not sync vectors, reset ranges or validate conversion results. Callers control range freshness.

Parameters:
  • axisPtr – [in] Borrowed axis with the prepared range and caches described above; no mutation or reference acquisition.

  • minPtr – [out] Required lower-limit output in raw data coordinates, including inverse log conversion.

  • maxPtr – [out] Required separate upper-limit output in raw data coordinates.

void Rbc_NotifyAxisChanges(Graph *graphPtr)

Emit axis configuration and limit-change events after screen display.

Collects names of configured live axes in registry order, comparing data-space limits against a separate notification baseline. Configuration or limit changes contribute to RbcAxisChanged; only limit changes contribute to RbcAxisLimitsChanged. Updates baselines and clears configure flags before sending events, balancing temporary list references. The display caller must exclude temporary export mappings; this function has no GRAPH_EXPORT guard of its own.

Parameters:
  • graphPtr – [inout] Borrowed live graph after screen display, outside temporary export mapping; notification baselines are advanced before event submission.

static int LimitsOp(Graph *graphPtr, Axis *axisPtr, int margin, Tcl_Size objc, Tcl_Obj *const objv[])

Return the two prepared axis limits as Tcl doubles.

Synchronizes element vectors and resets pending axis ranges before reading data-space bounds. Returns a two-element minimum/maximum list, not a four-coordinate graph rectangle. Requires a valid borrowed axis and does not perform complete margin layout.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [inout] Borrowed live axis with the range, options and caches required above; no reference is acquired.

  • margin – [in] Unused shared-handler argument; the axis is already resolved.

  • objc – [in] Unused suffix count; the query accepts zero arguments.

  • objv – [in] Borrowed suffix: Unused argument vector; this query accepts an empty suffix.

static int InvTransformOp(Graph *graphPtr, Axis *axisPtr, int margin, Tcl_Size objc, Tcl_Obj *const objv[])

Convert one integer screen coordinate to an axis value.

Synchronizes vectors and resets pending ranges, parses the sliced argument as an int and chooses horizontal/vertical inverse mapping from logical class and inversion. Returns TCL_ERROR for parsing failure or a nonfinite result; success returns a Tcl double. Uses existing mapping geometry rather than forcing complete layout.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [inout] Borrowed live axis with the range, options and caches required above; no reference is acquired.

  • margin – [in] Unused shared-handler argument; the axis is already resolved.

  • objc – [in] Validated suffix count (one); not otherwise used by this handler.

  • objv – [in] Borrowed suffix: One integer screen-coordinate object at index 0.

static int TransformOp(Graph *graphPtr, Axis *axisPtr, int margin, Tcl_Size objc, Tcl_Obj *const objv[])

Evaluate an axis value and return its integer screen coordinate.

Synchronizes vectors and resets pending ranges before evaluating the sliced argument with Tcl_ExprDoubleObj. Rejects nonfinite input, nonpositive logarithmic values and mapped coordinates outside int range. Success truncates toward zero, preserving historical conversion. Uses existing mapping geometry. Expression evaluation can execute Tcl; this handler does not revalidate its borrowed axis after that evaluation.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • axisPtr – [inout] Borrowed live axis with the range, options and caches required above; no reference is acquired.

  • margin – [in] Unused shared-handler argument; the axis is already resolved.

  • objc – [in] Validated suffix count (one); not otherwise used by this handler.

  • objv – [in] Borrowed suffix: One raw-data Tcl expression at index 0; evaluation may execute application Tcl.

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

Resolve a named axis for inverse transformation.

Uses live borrowed lookup and forwards the argument suffix to InvTransformOp. Returns the lookup or conversion status; acquires no axis reference.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • objc – [in] Number of borrowed entries in the full command vector; arity is validated by dispatch.

  • objv – [in] Borrowed full widget command vector; operation is at index 2 and operands begin at index 3.

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

Resolve a named axis and return its minimum/maximum pair.

Uses live borrowed lookup and delegates synchronization and range reset to LimitsOp. Returns TCL_ERROR for a missing axis; this wrapper does not acquire a reference or force full layout.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • objc – [in] Number of borrowed entries in the full command vector; arity is validated by dispatch.

  • objv – [in] Borrowed full widget command vector; operation is at index 2 and operands begin at index 3.

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

Resolve a named axis for forward transformation.

Uses live borrowed lookup and forwards the suffix to TransformOp, including its expression- evaluation behavior. Returns the lookup or conversion status without acquiring an axis reference.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • objc – [in] Number of borrowed entries in the full command vector; arity is validated by dispatch.

  • objv – [in] Borrowed full widget command vector; operation is at index 2 and operands begin at index 3.

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

Query or change the normalized viewport of one named axis.

Parses a mutation request before lookup, derives current scroll state and converts its direction to screen orientation. Queries clamp returned fractions to 0..1. Moving an empty view is a no-op. Pages advance by 90 percent of the view; units use scrollUnits and the current scale, or the full owning- track extent. Validates reconstructed data limits before assigning reqMin/reqMax and scheduling geometry/layout/range reset. Does not synchronize vectors or perform layout itself.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • objc – [in] Number of borrowed entries in the full command vector; arity is validated by dispatch.

  • objv – [in] Borrowed full command vector: axis name at index 3, optional scroll request starting at index 4.

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

Apply local scrolling to selected track axes with limit rollback.

Query or move the data viewport of a track-owned Y axis or axes.

An optional -mapy must name a member of the track. Queries use the selected or first axis; mutations apply to all members unless selected. Parses requests and performs graph layout before invoking ViewOp. Saves requested limits and graph flags, restoring them on a later axis error while retaining REDRAW_PENDING because an idle callback may already be scheduled. Frees temporary limit storage and name objects. Borrows the track and axis array; performs no independent reference acquisition.

Apply local scrolling to selected track axes with limit rollback.

Borrow graph, track and arguments; the enclosing widget command protects lifetime across layout callbacks. An optional -mapy selects one owned axis. Queries use the first selected axis; movement applies to all selected axes. Strict request parsing precedes layout. A later axis failure restores saved requested limits and flags, retaining any already scheduled redraw. Returns TCL_OK or TCL_ERROR with an interpreter result.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; required range/layout freshness and callback boundaries are described above.

  • track – [inout] Borrowed selected track and its axis array, required to remain valid through layout and scrolling.

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

  • objc – [in] Number of borrowed command entries; this dispatcher validates its supported operation/request arity.

  • objv – [in] Borrowed full track command vector; track name is at index 3, followed by optional -mapy axis and a scroll request.

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 AxisInfo

Pixel offsets used to place the axis line, ticks and labels.

Public Members

int axis

Length of the axis.

int t1

Length of a major tick (in pixels).

int t2

Length of a minor tick (in pixels).

int label

Distance from axis to tick label.

struct AxisOpSpec

Typed command dispatch entry with shared argument validation metadata.

Public Members

Rbc_OpSpecHeader header

Operation name, total argument bounds and usage suffix.

RbcGrAxisOp *proc

Typed command handler for this operation.

struct AxisVirtualOpSpec

Typed command dispatch entry with shared argument validation metadata.

Public Members

Rbc_OpSpecHeader header

Operation name, total argument bounds and usage suffix.

RbcGrAxisVirtualOp *proc

Typed command handler for this operation.

struct Axis

Graph-owned axis options, retained references and mapped presentation.

Deletion may be deferred while components retain references; Tk resources and derived tick storage are released by axis cleanup.

Public Members

char *name

Axis registry name, owned by the axis.

Rbc_Uid classUid

Type of axis.

Graph *graphPtr

Borrowed owning graph.

Tk_OptionTable optionTable

Tk option table for this component configuration lifecycle.

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 after Tk option initialization.

int tkResourcesReleased

Nonzero after guarded Tk-resource release.

Tcl_Obj *bindTagsObjPtr

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

Tcl_Obj *formatCmdObjPtr

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

Tcl_Obj *scrollCmdObjPtr

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

int scrollNotifyPending

Nonzero when scrollbar notification awaits delivery.

double scrollNotifyFirst

First visible fraction queued for the scrollbar callback.

double scrollNotifyLast

Last visible fraction queued for the scrollbar callback.

Tcl_Obj *limitsFormatObjPtr

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

Tcl_Obj *limitsShadowObjPtr

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

Tcl_Obj *looseObjPtr

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

Tcl_Obj *majorTicksObjPtr

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

Tcl_Obj *minorTicksObjPtr

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

Tcl_Obj *minObjPtr

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

Tcl_Obj *maxObjPtr

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

Tcl_Obj *scrollMinObjPtr

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

Tcl_Obj *scrollMaxObjPtr

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

Tcl_Obj *tickShadowObjPtr

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

Tcl_Obj *titleShadowObjPtr

Tk option-managed Tcl representation for title shadow; 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 *lineWidthObjPtr

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

Tcl_Obj *scrollIncrementObjPtr

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

unsigned int flags

Set bit field definitions below.

char **tags

Owned NULL-terminated binding-tag array.

char *detail

Borrowed pick-detail string identifying the selected axis part.

int deletePending

Indicates that the axis was scheduled for deletion.

The actual deletion may be deferred until the axis is no longer in use.

int refCount

Number of retained component references delaying deletion.

Tcl_HashEntry *hashPtr

Points to axis entry in hash table.

Used to quickly remove axis entries.

int logScale

If non-zero, scale the axis values logarithmically.

int hidden

If non-zero, don’t display the axis title, ticks, or line.

int showTicks

If non-zero, display tick marks and labels.

int descending

If non-zero, display the range of values on the axis in descending order, from high to low.

int looseMin

If non-zero, axis range extends to the outer major ticks, otherwise at the limits of the data values.

This is overridden by setting the -min and -max options.

int looseMax

If non-zero, axis range extends to the outer major ticks, otherwise at the limits of the data values.

This is overridden by setting the -min and -max options.

char *title

Title of the axis.

TextStyle titleTextStyle

Text attributes (color, font, rotation, etc.) of the axis title.

int titleAlternate

Indicates whether to position the title above/left of the axis.

Point2D titlePos

Position of the title.

int titleWidth

Measured title width in pixels.

int titleHeight

Measured title height in pixels.

int lineWidth

Width of lines representing axis (including ticks).

If zero, then no axis lines or ticks are drawn.

char **limitsFormats

One or two strings of sprintf-like formats describing how to display virtual axis limits.

If NULL, display no limits.

int nFormats

Number of strings in limitsFormats.

TextStyle limitsTextStyle

Text attributes (color, font, rotation, etc.) of the limits.

double windowSize

Size of a sliding window of values used to scale the axis automatically as new data values are added.

The axis will always display the latest values in this range.

double shiftBy

Shift maximum by this interval.

int tickLength

Length of major ticks in pixels.

TextStyle tickTextStyle

Text attributes (color, font, rotation, etc.) for labels at each major tick.

int scrollUnits

Pixel increment for unit scrolling.

double min

The actual axis range.

double max

The actual axis range.

double reqMin

Requested axis bounds.

Consult the axisPtr->flags field for AXIS_CONFIG_MIN and AXIS_CONFIG_MAX to see if the requested bound have been set. They override the computed range of the axis (determined by auto-scaling).

double reqMax

Requested axis bounds.

Consult the axisPtr->flags field for AXIS_CONFIG_MIN and AXIS_CONFIG_MAX to see if the requested bound have been set. They override the computed range of the axis (determined by auto-scaling).

double scrollMin

Defines the scrolling region of the axis.

Normally the region is determined from the data limits. If specified, these values override the data-range.

double scrollMax

Defines the scrolling region of the axis.

Normally the region is determined from the data limits. If specified, these values override the data-range.

AxisRange valueRange

Range of data values of elements mapped to this axis.

This is used to auto-scale the axis in “tight” mode.

AxisRange axisRange

Smallest and largest major tick values for the axis.

The tick values lie outside the range of data values. This is used to auto-scale the axis in “loose” mode.

double prevMin

Previous mapped lower limit used to detect range changes.

double prevMax

Previous mapped upper limit used to detect range changes.

double notifiedMin

Last displayed limits, in data units.

double notifiedMax

Last displayed limits, in data units.

int notifiedLimitsValid

Nonzero when the last displayed-limit snapshot is valid.

int notifyConfigure

A successful configuration awaits display.

double reqStep

If > 0.0, overrides the computed major tick interval.

Otherwise a stepsize is automatically calculated, based upon the range of elements mapped to the axis. The default value is 0.0.

GC tickGC

Graphics context for axis and tick labels.

Ticks *t1Ptr

Array of major tick positions.

May be set by the user or generated from the major sweep below.

Ticks *t2Ptr

Array of minor tick positions.

May be set by the user or generated from the minor sweep below.

TickSweep minorSweep

Generated minor tick progression.

TickSweep majorSweep

Generated major tick progression.

int reqNumMinorTicks

If non-zero, represents the requested the number of minor ticks to be uniformly displayed along each major tick.

int labelOffset

If non-zero, indicates that the tick label should be offset to sit in the middle of the next interval.

Rbc_ChainLink *linkPtr

Axis link in margin list.

Rbc_Chain *chainPtr

Borrowed margin axis chain containing linkPtr.

struct RbcTrack *track

Owning plot region, or NULL for shared axes.

int width

Extents of axis.

int height

Extents of axis.

Segment2D *segments

Array of line segments representing the major and minor ticks, but also the axis line itself.

The segment coordinates are relative to the axis.

Tcl_Size nSegments

Number of segments in the above array.

Rbc_Chain *tickLabels

Contains major tick label strings and their offsets along the axis.

Region2D region

Mapped axis hit-test rectangle in widget pixels.

Tk_3DBorder border

Tk option-managed axis background border.

int borderWidth

Axis background border thickness in pixels.

int relief

Tk relief of the axis background.

struct Axis2D

Axis pair borrowed by a mapping or held through its owner references.

Public Members

Axis *x

X-axis identity; reference management belongs to the containing component.

Axis *y

Y-axis identity; reference management belongs to the containing component.

struct AxisRange

Minimum, maximum and cached normalization of an axis interval.

Public Members

double min

Lower endpoint in the range coordinate system.

double max

Upper endpoint in the range coordinate system.

double range

Difference between max and min.

double scale

Reciprocal of range, used to normalize coordinates.

struct TickLabel

Variable-size tick label allocation with mapped placement.

Public Members

Point2D anchorPos

Mapped label anchor in widget pixels.

int width

Measured label width in pixels.

int height

Measured label height in pixels.

char string[1]

Inline NUL-terminated label text; allocation extends beyond this one-byte placeholder.

struct TickSweep

Arithmetic progression used to generate ticks.

Public Members

double initial

Initial value.

double step

Size of interval.

Tcl_Size nSteps

Number of intervals.

struct Ticks

Variable-size allocation containing explicit or generated tick positions.

Public Members

Tcl_Size nTicks

of ticks on axis

double values[1]

Inline tick values; allocation extends beyond this one-entry placeholder.

Implementation selectors

enum AxisComponents

Legacy identifiers for tick marks, labels and the axis line; no current axis code dispatches on this type.

Values:

enumerator MAJOR_TICK
enumerator MINOR_TICK
enumerator TICK_LABEL
enumerator AXIS_LINE
enum AxisLimitOption

Selects which explicit data or scroll limit a pending axis configuration updates.

Values:

enumerator AXIS_LIMIT_OPTION_NONE
enumerator AXIS_LIMIT_OPTION_MIN
enumerator AXIS_LIMIT_OPTION_MAX
enumerator AXIS_LIMIT_OPTION_SCROLL_MIN
enumerator AXIS_LIMIT_OPTION_SCROLL_MAX
enum AxisTickOption

Distinguishes major and minor tick-list inputs during axis configuration.

Values:

enumerator AXIS_TICK_OPTION_NONE
enumerator AXIS_TICK_OPTION_MAJOR
enumerator AXIS_TICK_OPTION_MINOR
enum AxisPixelOption

Selects the dimension to convert from a Tk screen distance before committing axis options.

Values:

enumerator AXIS_PIXEL_OPTION_NONE
enumerator AXIS_PIXEL_OPTION_BORDER_WIDTH
enumerator AXIS_PIXEL_OPTION_LINE_WIDTH
enumerator AXIS_PIXEL_OPTION_SCROLL_INCREMENT
enum AxisShadowOption

Selects which text style receives a staged shadow resource.

Values:

enumerator AXIS_SHADOW_OPTION_NONE
enumerator AXIS_SHADOW_OPTION_LIMITS
enumerator AXIS_SHADOW_OPTION_TICK
enumerator AXIS_SHADOW_OPTION_TITLE
typedef enum AxisComponents AxisComponent

Legacy identifiers for tick marks, labels and the axis line; no current axis code dispatches on this type.