Graph lifecycle and redisplay
rbcGraph.c owns the common widget lifecycle for graph, barchart, stripchart, polar and trackgraph. Components own
their data and mapped geometry; renderers consume that geometry. All of this work runs on the owning Tk thread. The
Graph lifecycle C reference records the contracts for the entry points below.
Creation and ownership
rbcGraphCommands.NewGraph() validates the command arguments and delegates to
rbcGraphLifecycle.CreateGraph(). Creation allocates a zeroed Graph, creates the Tk window,
initializes tables and display lists, selects the widget class and installs instance data. A trackgraph uses
line-element class behavior with its separate trackGraph flag. Its public Tk class remains Trackgraph.
The widget command and event handler are installed before component creation and initial configuration. Thus geometry requests and queued redisplay from configuration participate in the normal destruction path if later setup fails. Pens, axes, export options, crosshairs, legend and grid precede graph configuration, since configuration uses their resources. The binding table is created after successful configuration.
The graph record owns its component registries, drawing resources and backing pixmap. tkwin and interp identify
the associated Tk/Tcl objects; holding those pointers is not a lifetime guarantee. Components can be deleted while the
graph record remains alive.
Widget option transactions
The widget itself uses Tk_InitOptions with its real window. Unlike axes, tracks and export components, it does not
create a synthetic named component for resource-database lookup. Initialization and derived configuration are separate:
defaults may have been installed successfully while their retained values still need conversion. Initial configuration
therefore runs even with an empty explicit option list and forces the initialization masks.
Tk owns the option objects and ordinary option resources. RBC retains several values as objects and converts them into separate live fields:
Candidate |
Stored result |
Ownership at commit |
|---|---|---|
Distances |
Borders, margins, halo and requested size |
Copy integers selected by a staged mask. |
Padding |
X/Y two-sided plot padding |
Copy only staged axes. |
Bar mode |
Internal mode enumeration |
Copy the staged mode; normal aliases infront. |
Shadow |
Title-shadow color and offset |
Move the acquired color, then release the old shadow. |
Tile |
Tile client or |
Move the client, register the callback, then release the old client. |
The transaction context borrows the original option/value vector. It must have an even length and remain valid throughout configuration; it is cleared before return or rollback. Canonical option lookup recognizes aliases and unambiguous abbreviations. Each prepare helper first determines which options were supplied explicitly. On initial configuration, only unoverridden defaults are parsed. It then processes every explicit occurrence in caller order, rather than only the last value retained by Tk. An invalid earlier occurrence is consequently not concealed by a later valid occurrence.
Scalar candidates own no resources. Shadow and tile staging acquire a new candidate before releasing an earlier one, and
prepare failure cleans up that candidate. An empty tile is a staged NULL, distinct from an unstaged value. Commit
transfers resource ownership and disarms the candidate; cleanup must never release a successfully transferred resource a
second time.
rbcGraphOptions.ConfigureGraphOptions() applies Tk options with saved-option support, then calls
rbcGraphOptions.ConfigureGraph() to prepare derived values. That function validates track options and renderer
availability, rejects nonfinite aspect, bar width and baseline, and prepares the selected candidate families before
committing any of them. All reportable retained-value conversion failures precede this commit boundary. Failure returns
to the wrapper to restore Tk-managed fields. Success frees the saved options and marks initial configuration complete.
This is not a snapshot of every graph field. For example, track-option validation can invalidate the cached scrollbar fraction before a later validation fails. That notification bookkeeping is outside both Tk’s saved options and the five candidate records. Likewise, candidate preparation is not a general lifetime barrier around external resource-provider callbacks. Code extending configuration must review those boundaries explicitly.
After commit, configuration normalizes nonpositive bar width to 0.1, updates requested window geometry and internal border, rebuilds graph GCs and text style, and reconfigures crosshairs. Inversion adjusts physical axis pointers and marks ranges dirty. Layout and representation masks request world recomputation; plot background, renderer and separator changes invalidate backing pixels as appropriate. Successful configuration always requests a redraw. A renderer change additionally requests remapping because automatic decimation density depends on the renderer.
Polar’s default aspect policy is tracked separately from its public numeric aspect value. An option-database aspect disables automatic data-unit aspect at creation. A successful explicit aspect option also disables it; a failed configuration does not perform that success-only transition.
Option teardown must occur while the Tk window is valid. It clears the borrowed context, frees Tk-owned options and deletes the option table, and is safe to repeat. Derived GCs, title shadow and tile are released by graph destruction instead. Partial initialization undefines the window cursor before freeing its option resource, so the window does not retain a freed cursor.
Redraw requests and dirty state
Rbc_EventuallyRedrawGraph() coalesces requests with REDRAW_PENDING. It schedules work, but does not itself
invalidate mapped geometry or the backing store. A component mutator must set the appropriate dirty flags first.
Scheduling does not require a mapped window; presentation checks mapping later. An active axis formatter also makes a
redraw request a cancellation signal for the current layout.
Flag |
Role |
|---|---|
|
Recompute axis ranges before layout/mapping. |
|
Recompute margins; formatting may evaluate Tcl. |
|
Request remapping of components rather than only dirty items. |
|
Combination of |
|
Invalidate cached plot pixels independently of geometry. |
|
Combination of |
|
Combination of |
|
An ordinary or geometry-settled display request is outstanding. |
|
Retain a native view/element change until a completed screen display can queue
|
|
Distinguish temporary export layout from an on-screen view change. |
Expose and configure events use rbcGraphLifecycle.EventuallyRedrawSettledGraph(). It replaces an ordinary
pending display with rbcGraphLifecycle.SettleGraphRedraw(), which samples the widget and its Tk ancestors
through the toplevel. Presentation waits for two successive unchanged geometry samples. This coalesces nested
geometry-manager work without entering a recursive event loop; it does not wait for arbitrary application timers or
future geometry changes. Focus changes use ordinary redraw scheduling.
Layout and cancellation
Rbc_LayoutGraph() rejects recursive layout from an axis formatter, resets the cancellation flag, checks the
window, and processes pending work:
Retain a screen view-change indication, except during export.
Reset axis ranges when requested.
Compute margins when needed, then validate callback state.
If both plot ranges exceed one pixel, map axes as required, then elements, markers, grid and local legends; consume the remapping flags.
A successful return with an unusably small plot does not imply that all mapping flags were consumed. An error does not roll back partial layout. Callers must stop before using cached component pointers after cancellation.
Rbc_GraphCallbackValid() checks that tkwin still exists and that axisFormatInvalid is false. It reports
RBC GRAPH CALLBACK on failure. It is a specific axis-format/window guard, not a general validation of every
component pointer. Preservation and validation serve different purposes:
Tcl_Preservedelays final freeing of the graph record.Revalidation prevents use of window resources or layout invalidated by Tcl.
rbcGraphCommands.Rbc_GraphInstCmdProc() preserves the graph around operation dispatch. It also rejects
snapshot/export rendering from an active formatter before temporary output dimensions can disturb the outer layout. Idle
drawing has no such command scope: DisplayGraph() separately preserves the graph and interpreter and
saves/restores interpreter state around DisplayGraphFrame().
Frame drawing and presentation
The frame callback consumes REDRAW_PENDING first. It returns if the window is gone, an axis formatter is active, or
an element has a pending vector notification. Waiting for vector notification avoids drawing from vector data whose
corresponding geometry has not yet caught up.
It samples the actual Tk dimensions, requests world reset on a size change, and lays out. An unmapped widget updates
crosshair geometry without presenting. For a mapped widget, Rbc_DrawGraph() draws already-mapped content.
The plot backing store and full-frame double buffer have different roles:
The backing store caches the plot background, separators, grids, polar labels, under-markers, lowered legends, axis limits and ordinary elements.
The frame adds above-markers, active elements, requested margins, raised legends, widget border and focus highlight.
Crosshairs are not part of the backing store. Double-buffered presentation composes them into the final pixmap and presents once. Direct drawing erases old crosshairs, updates their geometry, draws the graph and enables them again.
The drawing path checks cancellation after callback-capable plot drawing. A cancelled frame is not presented as a completed buffered frame. Direct drawing can already have changed window pixels; it is not transactional.
After a completed frame, usable screen geometry can trigger the queued <<RbcGraphChanged>> event and axis-change
notifications. Margin-variable updates and track-view notification follow. The virtual event is queued, not executed
synchronously at the point it is sent. Tcl variable traces and other notification callbacks remain reentry boundaries in
their own right.
Destruction
Deleting the Tcl widget command and destroying the Tk window converge on the same lifecycle, with two distinct cleanup phases:
While the Tk window is valid, release option-owned Tk resources. The command deletion path first undefines the borrowed cursor: destroying a not-yet-created window may realize it, so a freed cursor must not remain installed. Clear
tkwinbefore a recursive command/window deletion can repeat this work.DestroyNotifycancels both ordinary and settled display idle callbacks, frees geometry-settle state, and usesTcl_EventuallyFreeto request final graph disposal. Outstanding preserves defer that final disposal.
DestroyGraph() then destroys markers and elements before tracks, axes and pens; releases remaining components,
bindings and drawing resources; and frees the record. Keeping that order matters because components refer to other
components. Do not move Tk-dependent resource release into the final free callback: the Tk window can already be gone
when it runs.
Contributor checks
When changing this code, exercise destruction from format callbacks, creation failure, nested resize, vector updates, snapshots and resized exports. Check both direct and buffered drawing, track reorder/scroll, and stationary-pointer repicking. Windows crosshairs additionally depend on preserving the single presentation step; separating erase and redraw can reintroduce flicker. These are behavioral checks for future code changes; this documentation change only adds contracts and prose.
Widget commands and geometry queries
The instance dispatcher resolves an operation and validates its argument count before preserving the graph allocation around the handler. Component commands retain their own dispatchers. Explicit bar, line and strip operations supply a class identifier; the generic element operation supplies the graph’s default class. Logical X/X2/Y/Y2 operations select their physical margins according to inversion before entering the margin-axis dispatcher.
Preservation delays freeing the graph record, not destruction of its window or component registries. A handler which evaluates Tcl cannot infer component validity from that preservation alone. The dispatcher blocks snapshot and document-output recursion during axis label formatting before those operations can alter dimensions. It also rejects widget-wide transform and invtransform on trackgraphs: callers must select a track through the track interface.
Geometry queries do not all have the same freshness guarantee:
Operation |
Preparation |
Result |
|---|---|---|
extents |
Reads cached geometry without layout. |
Scalar size or x/y/width/height; plot sizes include both endpoints. |
inside |
Parses Tk screen distances and reads graph extents. |
Boolean for the overall plot region, not a track selection. |
transform |
Evaluates expressions, synchronizes vectors and resets dirty ranges. |
Rounded integer screen coordinates on the first logical X/Y pair. |
invtransform |
Same expression and range preparation. |
Double data coordinates on that axis pair. |
Range synchronization is not full margin layout. Widget transforms can therefore use scales from an earlier layout while other changes are pending. Each Tcl expression is followed by a widget-validity check before the next expression or graph-resource access. Inputs must be finite. Forward mapping rounds in double precision and checks the integer range before conversion; ordinary coordinate rounding remains unchanged.
Screen composition and snapshot capture
rbcGraphCommands.DrawPlotRegion() constructs the cacheable layer: background, track separators, grids,
Polar/Smith labels, under markers, lowered legends, axis-limit annotations and ordinary elements. It checks callback
validity after the Polar label stage. Its caller must also check validity because a void drawing return does not
communicate cancellation. Rbc_DrawGraph() adds above markers, active elements, margins, raised legends, outer
border and focus decoration around that layer.
Margin drawing sets a shared tile origin and fills four rectangles surrounding the plot. Nonpositive rectangles are skipped at the fill helper. The plot border, margin legend, graph title and axes follow. These helpers consume mapped geometry and borrowed renderer resources; they do not lay out or present a frame.
A photo snapshot is a new rendering into a temporary pixmap, not a readback of the displayed window. Width and height are parsed as integers; values below two use the current Tk dimension. The handler assigns those dimensions to the graph, requests layout, marks the world dirty and draws without the element backing store. Callback cancellation releases the pixmap before returning an error. The normal photo path captures into the named photo and releases the pixmap.
On Windows the same command also supports EMF and WMF. It records drawing into an enhanced-metafile DC, then copies an
EMF or converts the recording to a placeable WMF file. The special CLIPBOARD target requests system ownership of the
enhanced metafile. These are native recording paths, separate from the renderer-independent document exporters.
The snapshot wrapper saves graph dimensions and existing flags before capture. It marks temporary rendering as export work, forces layout at the requested size, then restores dimensions and merges dirty flags on every return path. A surviving, uncancelled widget is immediately laid out at its original size; a later redraw also invalidates backing pixels. Existing pending-idle flags are retained. Capture errors survive restoration, while a restoration failure is reported when capture itself succeeded. Destroyed windows are never used for restoration or redraw scheduling.
Margin reporting copies configured variable names and cached sizes before the first traced write. Reconfiguration cannot invalidate those names mid-loop. After each write it checks whether the widget survives and layout remains valid, stopping both further writes and the subsequent track-view notification on cancellation. Assignment errors continue to be ignored for compatibility.
Construction helpers and notification ownership
rbcGraphLifecycle.InitPens() initializes the registry and creates activeLine before activeBar. A failure
leaves already-created resources for the enclosing graph teardown; it is not an independently repeatable initialization
operation. The successful constructor creates bindings only after all components and widget options have been
configured. Trackgraph selection is initially a distinct constructor UID, then becomes a line-element class plus the
trackGraph flag on the instance.
rbcGraphLifecycle.AdjustAxisPointers() changes only which logical chains each physical margin borrows. It does
not change axis classes or sites, relink axes or acquire references. Configuration separately invalidates ranges after
inversion. Likewise, the tile callback only requests margin redisplay: despite its former comment, it does not rebuild
a graphics context. Tile-client replacement and callback registration belong to the option transaction.
Tk’s world-change hook refreshes title metrics and component font resources without replaying configuration. It ignores partially configured graphs and requests both geometry recomputation and backing-store invalidation once live. This separates named-font changes from ordinary option parsing and ownership.
The geometry-settling record owns its sample array but only borrows window identities. Each idle pass walks the current
ancestry and compares identity, position, size and border width. It never dereferences a previously sampled window
handle. Two consecutive unchanged passes are required after the latest change. A pending settle request absorbs later
ordinary redraw requests via REDRAW_PENDING. Freeing the sampling record alone does not cancel an idle call;
destruction must cancel scheduling separately before releasing it.
rbcGraphLifecycle.Rbc_GetGraphFromWindowData() searches the supplied window and its ancestors for RBC instance
data. The result is borrowed, with no added preservation or class check. This supports graph descendants but is not a
generic checked conversion of arbitrary RBC instance data into a graph.
The parent window class and anonymous option proxy are established before any Graph storage or registries are
allocated. If proxy creation fails, the parent window is destroyed directly while the original interpreter error is
preserved. No deferred Graph destructor is needed on that path. After Graph allocation, instance
data, command and event-handler setup establish the normal ownership path before fallible component initialization
begins.
Windows metafile layout and ownership
rbcWindowsSnapshot.InitMetaFileHeader() writes the packed placeable-WMF header with zero origin, horizontal
width in Right and vertical height in Bottom. Both axes use their own screen pixel/millimeter ratio and 1440 units per
inch. Bounds must fit positive signed 16-bit values; invalid dimensions fail before header output is committed. The
checksum XORs the ten preceding little-endian 16-bit words, as specified by Microsoft’s META_PLACEABLE record.
rbcWindowsSnapshot.CreateAPMetaFile() completes native conversion before opening the destination. A zero size,
allocation/lock failure or incomplete conversion returns an error without truncating an existing file. Both writes check
their byte count. A write failure can leave a partial file; the helper releases its file and temporary memory but
borrows the recording and reference DC. The file path still uses the native ANSI API, as does EMF copying.
The snapshot command builds the EMF description as application-name/NUL, picture-name/NUL, followed by the DString
terminator. Reference-DC acquisition, recording completion and EMF copy failures now produce diagnostics. Clipboard
ownership transfers only when SetClipboardData succeeds; otherwise RBC deletes the recording. These checks preserve
the existing snapshot wrapper’s screen geometry restoration and do not alter the SVG/PDF/PostScript exporters.