Track ownership C reference
Track records and private services are declared in rbcGrTrack.h. Static configuration helpers live in
rbcGrTrack.c. See Track ownership and layout for the lifecycle, Coordinate mapping C reference for viewport scopes and
Scrolling C reference for scroll notification.
-
RbcTrack *Rbc_FindTrack(Graph *graphPtr, const char *name)
Return a borrowed track by exact, case-sensitive name, or NULL.
Searches the owning graph list without creating or retaining an object. Reordering preserves the pointer; deletion or graph teardown invalidates it.
- Parameters:
graphPtr – [in] Borrowed graph whose track list is searched.
name – [in] Required NUL-terminated exact track name; not retained.
-
void Rbc_DestroyTracks(Graph *graphPtr)
Release all tracks during graph teardown, before destroying axes.
Removes track bindings, local grids and legends, then releases axis references, names and records. The caller must already have disposed of dependent elements and markers and retain the component cleanup resources. Unlike command deletion, this does not validate dependencies or redraw.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live component resources on its Tk thread.
-
Tcl_Obj **Rbc_CreateTrackComponentArgs(Tcl_Size objc, Tcl_Obj *const objv[])
Allocate an argument vector for nested grid or legend dispatch.
Require objc >= 5 and the widget track component name operation form. The result has objc - 2 entries and owns only a newly retained list-valued command prefix at index 1; other entries borrow input objects. Release with Rbc_FreeTrackComponentArgs() before those borrowed arguments expire.
- Parameters:
objc – [in] Number of input objects; must be at least five.
objv – [in] Borrowed full widget track component name operation argument array; keep its objects alive until the adapter is freed.
-
void Rbc_FreeTrackComponentArgs(Tcl_Obj **args)
Release the owned command prefix and array from Rbc_CreateTrackComponentArgs().
Borrowed argument objects are not decremented. Require a non-NULL result from that allocator and release it exactly once.
- Parameters:
args – [in] Non-NULL owned array returned by Rbc_CreateTrackComponentArgs; consumed by this call.
- group Track configuration and ownership
Private helpers for staged configuration, ordering and deletion.
Functions
-
static void SyncTrackAxes(Graph *graphPtr)
Rebuild the displayed Y-axis chain in track order.
Clears old chain links and on-screen flags without destroying axes, then appends each track axis in its configured order. Borrows tracks and their retained axis references. Requests a world reset and deferred redraw; caller must have committed valid ownership first.
- Parameters:
graphPtr – [inout] Borrowed live owning graph; track ownership and component resources must be valid on its Tk thread.
-
static void FreeTrack(Graph *graphPtr, RbcTrack *track)
Release one detached track and its owned resources.
Removes bindings, destroys local grid and legend state, clears axis ownership and releases retained axis references. Frees the axis array, name and record. Does not unlink the track from the graph list or validate element/marker dependencies; callers perform those steps before destruction.
- Parameters:
graphPtr – [inout] Borrowed live owning graph; track ownership and component resources must be valid on its Tk thread.
track – [inout] Detached owned track with element/marker dependencies already removed; record and owned resources are freed.
-
static int TrackOptionIndex(Tcl_Interp *interp, Tcl_Obj *obj, int *indexPtr)
Resolve a track option using shared component metadata.
Borrows the Tcl object and option specification. Returns a standard Tcl result and writes the index on success; the shared resolver owns diagnostics and accepted option-name syntax.
- Parameters:
interp – [inout] Borrowed interpreter for lookup, evaluation and diagnostics; caller keeps it valid throughout the call.
obj – [in] Borrowed option-name object; shared metadata determines accepted abbreviations.
indexPtr – [out] Required specification-index output, meaningful only on TCL_OK.
-
static Tcl_Obj *TrackOption(RbcTrack *track, const char *option)
Construct the current value of a canonical track option.
Returns a new unretained Tcl object, or NULL for an unknown option. Uses live weights/heights, including sash changes, and builds the axis-name list in configured order. Requires valid bar-mode state; neither caches values nor transfers axis ownership.
- Parameters:
track – [in] Borrowed live track with valid scalar fields and retained axes.
option – [in] Borrowed canonical option spelling; unknown names return NULL.
-
static Tcl_Obj *TrackOptionInfo(RbcTrack *track, int index)
Construct a standard five-field option description.
Requires a validated specification index. Supplies TrackOption current state to the shared metadata helper, so values changed by dragging remain visible. Returns a new Tcl object; the track and static specification remain borrowed.
- Parameters:
track – [in] Borrowed live track supplying current option values.
index – [in] Validated zero-based trackOptionSpecs index, excluding the terminator.
-
static int ConfigureTrack(Graph *graphPtr, RbcTrack *track, Tcl_Size objc, Tcl_Obj *const objv[])
Validate option pairs and axis dependencies before committing track settings.
Borrow the graph, track and arguments. A replacement axis array is temporary until every name, ownership rule and dependent component has been checked. Acquire new axis references before releasing old ones, including axes retained in both lists. On error, discard the temporary array and retain track settings. The caller synchronizes axis display order and schedules redraw after success.
- Parameters:
graphPtr – [inout] Borrowed live owning graph; track ownership and component resources must be valid on its Tk thread.
track – [inout] Borrowed live track belonging to graphPtr; its record is not retained by this helper.
objc – [in] Nonnegative number of option/value objects, excluding command words; odd counts are rejected.
objv – [in] Borrowed array of objc Tcl objects; option values are parsed without retaining the array.
-
static int InitTrackOptions(Graph *graphPtr, RbcTrack *track, Tcl_Size objc, Tcl_Obj *const objv[])
Resolve creation defaults through the named Track option-database component.
Explicit arguments override database values before ConfigureTrack validates the effective options. Temporary option objects and the option table are released on all exits. The caller owns the unlinked track and handles failed creation; this helper does not insert it into the graph.
- Parameters:
graphPtr – [inout] Borrowed live owning graph; track ownership and component resources must be valid on its Tk thread.
track – [inout] Caller-owned unlinked track initialized with valid defaults and name; caller cleans it up on failure.
objc – [in] Nonnegative number of option/value objects, excluding command words; odd counts are rejected.
objv – [in] Borrowed array of objc Tcl objects; option values are parsed without retaining the array.
-
static int OrderTracks(Graph *graphPtr, Tcl_Obj *namesObj)
Validate a complete permutation, then relink existing track objects.
Reject unknown, missing or duplicate names without changing the list. On success, preserve object identity and rebuild the track Y-axis display chain, marking the graph for remapping and eventual redraw. Borrow namesObj.
- Parameters:
graphPtr – [inout] Borrowed live owning graph; track ownership and component resources must be valid on its Tk thread.
namesObj – [in] Borrowed Tcl list containing every existing track name exactly once.
-
static int TrackStart(Graph *graphPtr, RbcTrack *track)
Read the unclipped start along the track stacking dimension.
Selects worldLeft for inverted layouts and worldTop otherwise. This is physical layout geometry, not a data-axis minimum or a clipped visible boundary.
- Parameters:
graphPtr – [in] Borrowed graph supplying the inversion flag; layout must already be current.
track – [in] Borrowed track whose unclipped world bounds are current.
-
static int TrackEnd(Graph *graphPtr, RbcTrack *track)
Read the unclipped end along the track stacking dimension.
Selects worldRight for inverted layouts and worldBottom otherwise. Pair with TrackStart when calculating sash gaps or full track sizes, including partly offscreen tracks.
- Parameters:
graphPtr – [in] Borrowed graph supplying the inversion flag; layout must already be current.
track – [in] Borrowed track whose unclipped world bounds are current.
-
static int SetTrackSash(Graph *graphPtr, RbcTrack *track, int y)
Resize at a boundary using fitted weights or scroll height.
Requires a live track with a following neighbor and current layout. An unchanged coordinate is a no- op. Scroll mode changes only the first track requested height, clamped to its minimum and the height limit. Fit mode redistributes the adjacent weight sum above their minima; compressed minima cannot resize. Validates positive weights before commit, then requests remapping and redraw.
- Parameters:
graphPtr – [inout] Borrowed live owning graph; track ownership and component resources must be valid on its Tk thread.
track – [inout] Borrowed track with a non-NULL next neighbor and current world bounds; adjacent weights may change.
y – [in] Requested sash midpoint in widget pixels along the stacking dimension: Y normally, X when inverted.
-
static void TrackViewFractions(Graph *graphPtr, double *first, double *last)
Compute viewport fractions for the track list.
Uses the physical stacking range, bounded below by one, and an extent at least that range. Clamps a local offset without changing graph state; fitted mode uses zero. Writes both output doubles and does not query or change data-axis limits.
- Parameters:
graphPtr – [in] Borrowed graph with current physical range, stack extent and scroll offset.
first – [out] Required first visible fraction output in [0,1].
last – [out] Required last visible fraction output in [0,1], distinct from first.
-
static int TrackViewOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Query or change the track-list scroll offset.
Parses modifying requests before layout, then ensures geometry is current. Queries return two fractions. Moveto uses total extent, pages use 90 percent of the visible range and units use 20 pixels. Rejects nonfinite requested/computed offsets before commit. Fitted mode stores zero; successful mutations request a world reset and deferred redraw.
- Parameters:
graphPtr – [inout] Borrowed live owning graph; track ownership and component resources must be valid on its Tk thread.
interp – [inout] Borrowed interpreter for lookup, evaluation and diagnostics; caller keeps it valid throughout the call.
objc – [in] Full command argument count, at least three; three queries and larger counts request scrolling.
objv – [in] Borrowed full command vector; scroll arguments begin at index three.
-
static void NotifyTrackScrollbar(Graph *graphPtr)
Notify a changed track-list viewport after drawing.
Skips ordinary graphs, exports, absent prefixes and unchanged fractions. Caches fractions before evaluation to suppress recursive unchanged notifications. Duplicates the validated prefix, appends fractions, preserves graph/interpreter and restores interpreter state after global evaluation. Reports failures in the background. The callback may delete the widget; no graph fields are accessed after evaluation.
- Parameters:
graphPtr – [inout] Borrowed live owning graph; track ownership and component resources must be valid on its Tk thread.
-
static int DeleteTracks(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Validate all requested tracks before unlinking any of them.
Duplicate names are ignored. Reject tracks still referenced by elements or markers. Successful deletion releases local components, bindings and axis references, then synchronizes the axis chain and schedules redraw. The enclosing command owns graph lifetime; this is not widget teardown.
- Parameters:
graphPtr – [inout] Borrowed live owning graph; track ownership and component resources must be valid on its Tk thread.
interp – [inout] Borrowed interpreter for lookup, evaluation and diagnostics; caller keeps it valid throughout the call.
objc – [in] Nonnegative count of track-name objects only; zero is a successful no-op.
objv – [in] Borrowed array of objc track names; duplicates are ignored after validation.
-
static void SyncTrackAxes(Graph *graphPtr)
Widget integration
-
int Rbc_ConfigureTrackGraph(Graph *graphPtr, int scrollCommandChanged)
Validate track-specific widget options before configuration commits.
Returns TCL_OK or TCL_ERROR with a graph-interpreter diagnostic. Failure after the cached fraction reset does not undo that reset; the caller owns option rollback.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live component resources on its Tk thread.
scrollCommandChanged – [in] Nonzero when the scroll command changed; resets the cached first fraction after validating its list syntax.
-
int Rbc_TrackOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Dispatch the widget track subcommand.
Returns Tcl status and sets the interpreter result. The enclosing widget command protects graph lifetime across layout and nested component callbacks.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live component resources on its Tk thread.
interp – [inout] Borrowed result interpreter; see Interpreter arguments.
objc – [in] Number of full widget-command arguments, including widget and track words.
objv – [in] Borrowed full command array; operation is at index 2. See Tcl command arguments.
-
void Rbc_DrawTrackSeparators(Graph *graphPtr, Drawable drawable, Rbc_ExportContext *exportPtr)
Draw dividers inside the gaps between adjacent tracks.
Uses the same centers as sash positioning. Compressed or off-viewport strokes are omitted. Does nothing for ordinary graphs or an unset separator color.
- Parameters:
graphPtr – [in] Borrowed graph with current track world bounds and plot viewport.
drawable – [in] Borrowed screen destination; used by screen rendering and native fallback.
exportPtr – [inout] Borrowed export context, or NULL for screen output.
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 TrackDefaults
Temporary track option defaults resolved through the option database.
Public Members
-
Tcl_Obj *weight
Default relative fitted-layout weight.
-
Tcl_Obj *minHeight
Default minimum stacking extent in pixels.
-
Tcl_Obj *height
Default requested stacking extent in pixels.
-
Tcl_Obj *yAxes
Tcl representation of default local Y-axis names.
-
Tcl_Obj *barMode
Default bar mode; -1 inherits the graph setting.
-
Tcl_Obj *weight
-
struct RbcTrack
Graph-owned track with local component state and retained Y-axis references.
Full world bounds drive mapping; visible bounds drive clipping after scrolling.
Public Members
-
int barMode
-1 inherits the graph bar mode.
-
struct GridSegments gridX
Owned mapped X-grid segment cache.
-
struct GridSegments gridY
Owned mapped Y-grid segment cache.
-
Legend *legend
Owned local legend, or NULL.
-
char *name
Owned track name.
-
double weight
Relative share of fitted layout space after minimum sizes.
-
int minHeight
Minimum plot extent along the stacking direction in pixels.
-
int height
Requested plot size along the track stacking direction.
-
int worldLeft
Full plot left edge before viewport clipping, in widget pixels.
-
int worldRight
Full plot right edge before viewport clipping, in widget pixels.
-
int worldTop
Full plot top edge before viewport clipping, in widget pixels.
-
int worldBottom
Full plot bottom edge before viewport clipping, in widget pixels.
-
int left
Visible intersection with the plot viewport.
-
int right
Visible intersection with the plot viewport.
-
int top
Visible intersection with the plot viewport.
-
int bottom
Visible intersection with the plot viewport.
-
int axisOffset
Accumulated local-axis layout offset in pixels.
-
Tcl_Size nAxes
Number of entries in axes.
-
int barMode