Grid C reference

These private entry points borrow the graph and require the preparation or cleanup context described in Grid mapping and inheritance.

Grid configuration and mapped caches

struct Grid

Graph or track grid options and mapped drawing caches.

Tk option state owns Tcl representations and color resources; derived tick arrays and segment caches are released by grid cleanup. Owner pointers are borrowed; selected axes carry references released by grid cleanup.

Public Members

Tk_OptionTable optionTable

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

Graph *graphPtr

Borrowed owning graph; does not retain the widget.

RbcTrack *track

Borrowed owning track, or NULL for the graph-wide grid.

int optionsConfigured

Nonzero after the first successful configuration.

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.

Tcl_Obj *angleMajorTicksObjPtr

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

Tcl_Obj *angleMinorTicksObjPtr

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

Tcl_Obj *angleCommandObjPtr

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

Tcl_Obj *smithRealCommandObjPtr

Tk option-managed Tcl representation for smith real command; released with option state.

Tcl_Obj *smithImagCommandObjPtr

Tk option-managed Tcl representation for smith imag command; released with option state.

Tcl_Obj *smithRealMajorTicksObjPtr

Tk option-managed Tcl representation for smith real major ticks; released with option state.

Tcl_Obj *smithRealMinorTicksObjPtr

Tk option-managed Tcl representation for smith real minor ticks; released with option state.

Tcl_Obj *smithImagMajorTicksObjPtr

Tk option-managed Tcl representation for smith imag major ticks; released with option state.

Tcl_Obj *smithImagMinorTicksObjPtr

Tk option-managed Tcl representation for smith imag minor ticks; released with option state.

Tcl_Obj *dashesObjPtr

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

Tcl_Obj *lineWidthObjPtr

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

Tcl_Obj *mapXObjPtr

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

Tcl_Obj *mapYObjPtr

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

SmithGridMode smithGrid

Impedance, admittance or combined Smith-grid selector.

PolarLabelAnchor radialLabelAnchor

Anchor policy for radial labels.

PolarLabelAnchor angleLabelAnchor

Anchor policy for angular labels.

double *angleMajorTicks

Owned parsed major angle tick values; paired with nAngleMajorTicks.

Tcl_Size nAngleMajorTicks

Number of initialized values in angleMajorTicks.

double *angleMinorTicks

Owned parsed minor angle tick values; paired with nAngleMinorTicks.

Tcl_Size nAngleMinorTicks

Number of initialized values in angleMinorTicks.

double *smithRealMajorTicks

Owned parsed major Smith real tick values; paired with nSmithRealMajorTicks.

Tcl_Size nSmithRealMajorTicks

Number of initialized values in smithRealMajorTicks.

double *smithRealMinorTicks

Owned parsed minor Smith real tick values; paired with nSmithRealMinorTicks.

Tcl_Size nSmithRealMinorTicks

Number of initialized values in smithRealMinorTicks.

double *smithImagMajorTicks

Owned parsed major Smith imaginary tick values; paired with nSmithImagMajorTicks.

Tcl_Size nSmithImagMajorTicks

Number of initialized values in smithImagMajorTicks.

double *smithImagMinorTicks

Owned parsed minor Smith imaginary tick values; paired with nSmithImagMinorTicks.

Tcl_Size nSmithImagMinorTicks

Number of initialized values in smithImagMinorTicks.

GC gc

Graphics context for the grid.

Axis2D axes

Retained X/Y axis references used for Cartesian grid selection.

int hidden

If non-zero, grid isn’t displayed.

int minorGrid

If non-zero, draw minor grid lines.

Rbc_Dashes dashes

Parsed dash pattern.

int lineWidth

Line width in pixels.

XColor *colorPtr

Grid colour.

struct GridSegments x

Owned mapped grid segments associated with the selected X axis.

struct GridSegments y

Owned mapped grid segments associated with the selected Y axis.

struct GridSegments

Owned mapped grid segment storage.

Used for graph and track grid caches; coordinates are display pixels, not source tick values.

Public Members

Segment2D *segments

Owned mapped endpoint-pair array; NULL when empty.

Tcl_Size nSegments

Number of initialized Segment2D entries.

struct PolarLabelAnchor

Polar label anchor policy.

An automatic anchor is resolved from geometry; the stored Tk anchor applies when automatic selection is off.

Public Members

Tk_Anchor anchor

Explicit Tk anchor selector.

int isAuto

Nonzero selects geometry-dependent anchoring.

Mapping and output

void Rbc_MapGrid(Graph *graphPtr)

Rebuild grid segment caches from prepared axes and plot geometry.

Releases old global segments. Polar and Smith representations delegate to their specialized mappers. Trackgraphs rebuild per-track caches using local settings or inherited defaults; ordinary graphs rebuild global X/Y segments. Does not draw, schedule layout or use hidden state to suppress mapping.

Parameters:
  • graphPtr – Borrowed graph with initialized grid and current layout.

void Rbc_DrawGrid(Graph *graphPtr, Drawable drawable)

Draw prepared grid segments into a borrowed screen drawable.

Trackgraphs dispatch before testing global visibility, so each effective track grid controls its own visibility. Uses renderer services and native fallback as needed. Does not remap geometry or own the drawable.

Parameters:
  • graphPtr – Borrowed graph with current grid mapping and resources.

  • drawable – Compatible window or pixmap.

void Rbc_GridExport(Graph *graphPtr, Rbc_ExportContext *exportPtr)

Emit prepared grid segments through an initialized export context.

Track grids use their effective styles, visibility and per-track clips. Ordinary graphs skip a hidden global grid. Does not perform layout or finalize the document.

Parameters:
  • graphPtr – Borrowed graph mapped for the export dimensions.

  • exportPtr – Borrowed export context owned by the caller.

Ownership and cleanup

int Rbc_CreateGrid(Graph *graphPtr)

Create the graph-owned named grid component.

Selects graph, bar or polar option defaults, initializes resource name grid and class Grid, and validates derived resources. Returns TCL_OK on success. On TCL_ERROR, releases partial state through Rbc_DestroyGrid() and leaves gridPtr NULL; the diagnostic remains in the graph interpreter.

Parameters:
  • graphPtr – [inout] Graph with no existing global grid and a live Tk configuration context.

void Rbc_DestroyTrackGrid(Graph *graphPtr, RbcTrack *track)

Release a track’s local grid and both mapped segment caches.

A NULL local grid is allowed. Does not destroy the track or global grid.

Parameters:
  • graphPtr – Owning graph with live Tk window for local option cleanup.

  • track – Track whose local grid pointer and caches are cleared.

void Rbc_DestroyGrid(Graph *graphPtr)

Destroy global and local grid resources while the Tk window is live.

Clears graphPtr->gridPtr, destroys each track’s local grid and cached segments, then destroys the global grid. Frees axis references, Tk options, private GC, segment/tick arrays and the grid records.

Parameters:
  • graphPtr – Owning graph with valid track list and Tk window context.

Implementation helpers

group Grid configuration and output helpers

Private component helpers; not installed C API entry points.

Functions

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

Match a canonical grid option after abbreviation resolution.

Borrows objPtr and compares its canonical name from graphGridOptionSpecs with optionName. Returns FALSE when resolution fails; does not set an interpreter diagnostic. Used to identify explicit tick options in the original argument sequence, rather than inspecting only the final Tk option values.

Parameters:
  • objPtr – [in] Borrowed option-name object, possibly abbreviated.

  • optionName – [in] Borrowed NUL-terminated canonical spelling to compare after resolution.

static int SetPolarLabelAnchor(void *clientData, Tcl_Interp *interp, Tk_Window tkwin, Tcl_Obj **valuePtrPtr, char *widgRec, Tcl_Size offset, char *saveInternalPtr, int flags)

Parse the custom automatic-or-Tk anchor option.

Tk supplies the target record/offset and optional rollback storage. Saves the old value when requested, then accepts the exact word auto or a Tk anchor. Auto stores CENTER with isAuto true. Assigns the active record only on success; returns TCL_ERROR with the Tk diagnostic on invalid input. No owned allocation or Tcl callback is involved; the input object is not replaced.

Parameters:
  • clientData – [in] Unused Tk custom-option client data.

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

  • tkwin – [in] Unused Tk custom-option window argument.

  • valuePtrPtr – [in] Required pointer to the borrowed candidate object; the object pointer is not replaced.

  • widgRec – [inout] Tk option record containing the inline PolarLabelAnchor.

  • offset – [in] Byte offset of PolarLabelAnchor within widgRec.

  • saveInternalPtr – [out] Optional storage for the previous inline value; NULL skips saving.

  • flags – [in] Unused Tk custom-option flags.

static Tcl_Obj *GetPolarLabelAnchor(void *clientData, Tk_Window tkwin, char *widgRec, Tcl_Size offset)

Return the external value of a custom label anchor.

Reads the record at widgRec+offset. Returns a new zero-reference Tcl string containing auto or the Tk anchor name; ownership follows Tk’s custom-option getProc convention. Does not change the record or allocate native resources.

Parameters:
  • clientData – [in] Unused Tk custom-option client data.

  • tkwin – [in] Unused Tk custom-option window argument.

  • widgRec – [in] Borrowed record containing a valid inline PolarLabelAnchor.

  • offset – [in] Byte offset of that representation within widgRec.

static void RestorePolarLabelAnchor(void *clientData, Tk_Window tkwin, char *internalPtr, char *saveInternalPtr)

Restore the saved inline anchor representation.

Copies one PolarLabelAnchor from Tk rollback storage to internalPtr. Both pointers must refer to complete records. No pointer ownership transfer or allocation is necessary because the representation contains only values.

Parameters:
  • clientData – [in] Unused Tk custom-option client data.

  • tkwin – [in] Unused Tk custom-option window argument.

  • internalPtr – [out] Required storage for the active PolarLabelAnchor to restore.

  • saveInternalPtr – [in] Required saved PolarLabelAnchor; copied without taking ownership.

static void FreePolarLabelAnchor(void *clientData, Tk_Window tkwin, char *internalPtr)

Complete Tk custom-option cleanup for an inline value.

Intentionally a no-op: PolarLabelAnchor owns no heap or Tk resources. Tk owns the surrounding record/storage. All arguments are unused.

Parameters:
  • clientData – [in] Unused Tk custom-option client data.

  • tkwin – [in] Unused Tk custom-option window argument.

  • internalPtr – [in] Unused pointer to Tk-owned inline representation; no allocation is released.

static int ParsePolarAngleTicks(Tcl_Interp *interp, Tcl_Obj *objPtr, const char *optionName, double **ticksPtr, Tcl_Size *nTicksPtr)

Parse a finite angular tick list into an owned double array.

Resets output pointer/count to NULL/zero before parsing. Accepts values in [0,360) degrees, canonicalizes negative zero, and preserves order and duplicates. Empty lists succeed without allocation. Checks allocation size and uses Tcl_AttemptAlloc; frees scratch storage on conversion/range failure. Returns TCL_OK with caller-owned storage (release with ckfree), or TCL_ERROR with an interpreter diagnostic and NULL/zero outputs. Does not change a grid.

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

  • objPtr – [in] Borrowed list object containing angles in degrees.

  • optionName – [in] Borrowed option spelling used in range and allocation-size diagnostics.

  • ticksPtr – [out] Required output slot; receives ckfree-owned array on success, NULL for empty input or failure.

  • nTicksPtr – [out] Required output count; zero for empty input or failure.

static int ParseSmithTicks(Tcl_Interp *interp, Tcl_Obj *objPtr, const char *optionName, int allowZero, double **ticksPtr, Tcl_Size *nTicksPtr)

Parse nonnegative or positive Smith tick magnitudes.

Resets output pointer/count before parsing. allowZero selects nonnegative values for real ticks; otherwise all values must be strictly positive. Rejects non-finite values, preserves input order/duplicates, and normalizes negative zero when accepted. Empty lists return NULL/zero with TCL_OK. Checked Tcl allocation is owned by the caller on success; on TCL_ERROR the scratch buffer is freed, outputs remain NULL/zero, and interp has diagnostics.

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

  • objPtr – [in] Borrowed list of real values or imaginary magnitudes.

  • optionName – [in] Borrowed option spelling for diagnostics.

  • allowZero – [in] Nonzero accepts zero; zero requires strictly positive magnitudes.

  • ticksPtr – [out] Required output slot; receives ckfree-owned array or NULL for empty input or failure.

  • nTicksPtr – [out] Required output count; zero for empty input or failure.

static int StageGridPolarAngleTicks(Grid *gridPtr, Tcl_Obj *objPtr, int major, GridPolarAngleTicksTransaction *transactionPtr)

Replace one staged angular list after complete validation.

transactionPtr must be initialized. Parses a major or minor list using the grid interpreter. Only after success frees that slot’s earlier staged array, then takes ownership of the replacement and marks the slot staged, including an empty replacement. TCL_ERROR leaves earlier staged/live values intact; TCL_OK changes only the transaction, never active grid arrays.

Parameters:
  • gridPtr – [in] Borrowed grid supplying its graph interpreter; active arrays are unchanged.

  • objPtr – [in] Borrowed replacement list.

  • major – [in] Nonzero selects the major slot; zero selects the minor slot.

  • transactionPtr – [inout] Initialized staging record taking ownership only after the replacement parses successfully.

static int StageGridSmithTicks(Grid *gridPtr, Tcl_Obj *objPtr, int realPart, int major, GridSmithTicksTransaction *transactionPtr)

Replace one of four staged Smith tick lists.

transactionPtr must be initialized. realPart chooses real versus imaginary magnitudes (and whether zero is allowed); major chooses the tier. Completely parses the replacement before freeing earlier staged storage for that slot. Returns Tcl status; failure preserves earlier staged/live values, success transfers ownership to the transaction and marks even an empty list staged.

Parameters:
  • gridPtr – [in] Borrowed grid supplying its graph interpreter; active arrays are unchanged.

  • objPtr – [in] Borrowed replacement list.

  • realPart – [in] Nonzero selects real ticks allowing zero; zero selects positive imaginary magnitudes.

  • major – [in] Nonzero selects major ticks; zero selects minor ticks.

  • transactionPtr – [inout] Initialized transaction owning any previous staged arrays; only the selected slot is replaced.

static void FreeGridPolarAngleTicksTransaction(GridPolarAngleTicksTransaction *transactionPtr)

Discard owned angular staging storage and reset the transaction.

Requires a non-NULL initialized transaction containing only owned arrays or NULLs. Frees both non-NULL arrays regardless of flags, then zeroes the record. Safe after commit and safe to repeat on the reset record. Never frees active grid storage because commit detaches transferred pointers.

Parameters:
  • transactionPtr – [inout] Required initialized transaction; owned arrays are freed and all fields zeroed.

static void FreeGridSmithTicksTransaction(GridSmithTicksTransaction *transactionPtr)

Discard all owned Smith staging arrays and reset the record.

Requires a non-NULL initialized transaction. Frees each non-NULL array and zeroes all pointers, counts and flags. Safe after partial preparation, successful commit or previous cleanup. No grid state or Tcl result is changed.

Parameters:
  • transactionPtr – [inout] Required initialized transaction; owned arrays are freed and all fields zeroed.

static int PrepareGridPolarAngleTicksTransaction(Grid *gridPtr, GridPolarAngleTicksTransaction *transactionPtr)

Stage defaults and every explicit angular option in caller order.

Requires an even optionObjc and a valid borrowed optionObjv array in gridPtr. Zero-initializes transactionPtr, so it must not already own allocations. On first configuration, stages stored option/default values only for slots not explicitly supplied. Then parses each explicit occurrence in argument order: an invalid earlier duplicate is not hidden by a later valid value.

Returns TCL_OK with owned staged buffers, or TCL_ERROR after freeing/resetting the transaction. Live grid arrays are unchanged; Tk’s saved options are a separate transaction handled by the caller.

Parameters:
  • gridPtr – [in] Borrowed grid with an even optionObjc and valid optionObjv slice, plus stored defaults.

  • transactionPtr – [out] Required unowned storage; initialized here, owns staged arrays on success and is reset on error.

static int PrepareGridSmithTicksTransaction(Grid *gridPtr, GridSmithTicksTransaction *transactionPtr)

Stage defaults and explicit values for all four Smith lists.

Requires even optionObjc, valid borrowed optionObjv, and an empty/unowned output transaction. Initializes the record, stages non-overridden defaults only on initial configuration, then validates every explicit occurrence in caller order. Returns TCL_OK with staged ownership, or TCL_ERROR after complete staging cleanup. Does not replace active arrays or restore Tk option objects.

Parameters:
  • gridPtr – [in] Borrowed grid with an even optionObjc and valid optionObjv slice, plus stored defaults.

  • transactionPtr – [out] Required unowned storage; initialized here, owns staged arrays on success and is reset on error.

static void CommitGridPolarAngleTicksTransaction(Grid *gridPtr, GridPolarAngleTicksTransaction *transactionPtr)

Transfer staged angular arrays into active grid ownership.

For each staged slot, replaces pointer/count, clears its staging fields and frees the old active array. Unstaged slots are retained; staged NULL/zero means an explicitly empty list. Requires successful preparation. No allocation, validation, callback or redraw scheduling occurs; cleanup may run afterward.

Parameters:
  • gridPtr – [inout] Owning grid receiving staged arrays and releasing replaced active arrays.

  • transactionPtr – [inout] Successfully prepared transaction; transferred pointers and slot flags are cleared.

static void CommitGridSmithTicksTransaction(Grid *gridPtr, GridSmithTicksTransaction *transactionPtr)

Transfer staged Smith arrays into active grid ownership.

Commits each staged real/imaginary major/minor slot independently, detaches its pointer/count/flag and frees old active storage. Empty staged lists clear the slot; unstaged slots remain unchanged. Requires successful preparation; no allocation, callbacks or redraw scheduling occur.

Parameters:
  • gridPtr – [inout] Owning grid receiving staged arrays and releasing replaced active arrays.

  • transactionPtr – [inout] Successfully prepared transaction; transferred pointers and slot flags are cleared.

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

Validate list syntax without evaluating a label command.

NULL means no command and succeeds. Otherwise uses Tcl_ListObjGetElements; an empty list is accepted. Returns Tcl status and a diagnostic on invalid list syntax. Does not check command existence, invoke the prefix or retain it.

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

  • objPtr – [in] Borrowed command-prefix object, or NULL for no prefix; list syntax only is checked.

static int ConfigureGrid(Graph *graphPtr, Grid *gridPtr, int mask)

Prepare and commit derived grid resources after Tk option parsing.

Borrows graph/grid with a live Tk window and uses mask to select conversions. Prepares dashes, width, acquired axis references and tick transactions before replacing active derived state. Track-local mappings require a shared X axis and a Y axis belonging to that track. Validates label-prefix list syntax without evaluation. Creates a replacement private GC only after fallible parsing.

On TCL_ERROR, frees temporary arrays/axis references and leaves active derived resources intact; caller must restore Tk_SavedOptions separately. On TCL_OK, commits arrays, axes and GC, releases replaced resources, and marks initial configuration complete. Does not itself remap geometry or schedule redraw.

Parameters:
  • graphPtr – [in] Borrowed owning graph with live Tk configuration and axis lookup context.

  • gridPtr – [inout] Initialized owning grid with candidate Tk options and any borrowed original option slice.

  • mask – [in] GRID_*_CHANGED bits selecting derived conversions; not a rollback or redraw request.

static void DrawTrackGrids(Graph *graphPtr, Drawable drawable, Rbc_ExportContext *exportPtr)

Draw cached segments with each track’s effective grid and clip.

Requires mapped track geometry and segment caches. Selects local settings or the global inherited grid, skipping hidden/collapsed tracks independently. Pairs each entered track viewport with restoration. A non-NULL exportPtr selects export output and explicit rectangular clipping; otherwise drawable is borrowed screen storage. Renderer contexts are ended before returning.

The native fallback reuses one scratch clip context across tracks and copies only visible track rectangles, retaining original segment/dash coordinates. This clips complete strokes, not only their centerlines. Does not remap, finalize export documents or own the cached segment arrays.

Parameters:
  • graphPtr – [inout] Borrowed trackgraph with mapped visible rectangles and segment caches; temporary viewports are restored.

  • drawable – [in] Borrowed compatible screen destination when exportPtr is NULL; ignored during export.

  • exportPtr – [inout] Borrowed initialized export context, or NULL for screen output; not finalized here.

static void DestroyGrid(Graph *graphPtr, Grid *gridPtr)

Release one owning grid record while its Tk window is valid.

Accepts NULL. Otherwise releases axis references, Tk options/table, private GC, global segment arrays and all specialized tick arrays, then frees the record. Must not receive the borrowed inherited-query view. Does not clear its owner’s pointer or free per-track segment caches; outer destruction helpers perform those tasks. graphPtr->tkwin must still be valid for Tk cleanup.

Parameters:
  • graphPtr – [in] Owning graph with valid Tk window and display for resource release.

  • gridPtr – [inout] Owned grid to free, or NULL; never the shallow inherited-query view. Owner pointer is not cleared here.

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

Return one component option value.

The typed dispatcher has validated argument count. Borrows the graph-owned component and its option table, returning Tk option errors unchanged. This query does not configure resources or schedule drawing.

Parameters:
  • graphPtr – [inout] Borrowed live graph with selected grid record; enclosing dispatch owns lifetime protection.

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

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

  • objv – [in] Borrowed command vector, adapted to ordinary component form for track grids; see Tcl command arguments.

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

Query or transactionally configure the selected grid.

Three or four arguments return option metadata without mutation. Updates first stage Tk options, then expose the borrowed original argument sequence only while ConfigureGrid validates derived state. Clears that temporary sequence on both outcomes. Failure restores saved options and the diagnostic; success frees saved values and schedules masked world/backing-store invalidation.

Parameters:
  • graphPtr – [inout] Borrowed live graph with selected grid record; enclosing dispatch owns lifetime protection.

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

  • objc – [in] Command count; operation is at index two, optional arguments start at index three.

  • objv – [in] Borrowed command vector, adapted to ordinary component form for track grids; see Tcl command arguments.

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

Request visibility for the selected grid.

Changes hidden only when necessary, invalidates the backing store and schedules idle graph redraw. Does not immediately paint or remap segments. Under track dispatch, the selected grid may be a newly created local candidate.

Parameters:
  • graphPtr – [inout] Borrowed live graph with selected grid record; enclosing dispatch owns lifetime protection.

  • interp – [in] Unused by this visibility handler.

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

  • objv – [in] Unused validated command vector.

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

Hide the selected grid through deferred redraw.

Changes hidden only when currently shown, then invalidates the backing store and schedules idle redraw. Does not free segment caches or erase pixels directly.

Parameters:
  • graphPtr – [inout] Borrowed live graph with selected grid record; enclosing dispatch owns lifetime protection.

  • interp – [in] Unused by this visibility handler.

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

  • objv – [in] Unused validated command vector.

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

Invert grid visibility and schedule a backing-store redraw.

Mutates the selected grid, which can be global or temporarily selected track-local state. Always schedules redraw; does not remap or synchronously draw geometry.

Parameters:
  • graphPtr – [inout] Borrowed live graph with selected grid record; enclosing dispatch owns lifetime protection.

  • interp – [in] Unused by this visibility handler.

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

  • objv – [in] Unused validated command vector.

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

Validate and dispatch a graph grid subcommand.

Uses the typed operation table to check name and arity before accessing operation-specific arguments. Borrows graph and Tcl arguments, returns the handler result, and performs no independent drawing or option rollback.

Parameters:
  • graphPtr – [inout] Borrowed live graph with selected grid record; enclosing dispatch owns lifetime protection.

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

  • objc – [in] Command count; operation is at index two, optional arguments start at index three.

  • objv – [in] Borrowed command vector, adapted to ordinary component form for track grids; see Tcl command arguments.

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

Adapt nested track grid commands without freezing query defaults.

Owns a temporary adapted argument vector and option table, and retains a temporary Y-axis name. Inherited queries use a shallow borrowed global view with the track first Y axis when enabled. First mutation prepares an owned local candidate; only success attaches it. Temporarily selects the view or candidate through graphPtr->gridPtr, restoring the global pointer before cleanup. This synchronous path must not evaluate Tcl callbacks while temporary selection is active.

Parameters:
  • graphPtr – [inout] Owning graph; global grid selection is restored before return.

  • track – [inout] Borrowed live member of graphPtr; receives an owned local grid only after successful first mutation.

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

  • objc – [in] Full nested-command count, including widget, track, grid, track name and operation.

  • objv – [in] Borrowed full nested-command vector; operation is objv[4]. See Tcl command arguments.

struct GridPolarAngleTicksTransaction

Owned staging buffers for the two angular tick options.

Zero-initialize before staging. A staged flag distinguishes an explicitly empty replacement from an unchanged slot. Commit transfers array ownership and clears each staged slot; cleanup releases only remaining owned arrays. The record must not be copied as an independent owner while buffers exist.

Public Members

int majorStaged

Nonzero when the corresponding tick array has a staged replacement.

double *majorTicks

Owned staged tick values; transferred on commit or freed on abort.

Tcl_Size nMajorTicks

Number of values in the staged tick array.

int minorStaged

Nonzero when the corresponding tick array has a staged replacement.

double *minorTicks

Owned staged tick values; transferred on commit or freed on abort.

Tcl_Size nMinorTicks

Number of values in the staged tick array.

struct GridSmithTicksTransaction

Owned staging buffers for four independent Smith tick options.

Real/imaginary and major/minor slots each have a staged flag, owned array and count. NULL with a true flag means clear that active list. Prepare initializes the complete record; commit detaches ownership; cleanup resets all fields. This storage is separate from Tk_SavedOptions and owns no Tcl objects.

Public Members

int realMajorStaged

Nonzero when the corresponding tick array has a staged replacement.

double *realMajorTicks

Owned staged tick values; transferred on commit or freed on abort.

Tcl_Size nRealMajorTicks

Number of values in the staged tick array.

int realMinorStaged

Nonzero when the corresponding tick array has a staged replacement.

double *realMinorTicks

Owned staged tick values; transferred on commit or freed on abort.

Tcl_Size nRealMinorTicks

Number of values in the staged tick array.

int imagMajorStaged

Nonzero when the corresponding tick array has a staged replacement.

double *imagMajorTicks

Owned staged tick values; transferred on commit or freed on abort.

Tcl_Size nImagMajorTicks

Number of values in the staged tick array.

int imagMinorStaged

Nonzero when the corresponding tick array has a staged replacement.

double *imagMinorTicks

Owned staged tick values; transferred on commit or freed on abort.

Tcl_Size nImagMinorTicks

Number of values in the staged tick array.

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 GridOpSpec

Typed command dispatch entry with shared argument validation metadata.

Public Members

Rbc_OpSpecHeader header

Operation name, total argument bounds and usage suffix.

RbcGrGridOp *proc

Typed command handler for this operation.