Graph lifecycle C reference
These are private interfaces. Shared contracts live at their header declarations; static lifecycle helpers are documented next to their definitions. This section covers lifecycle callbacks, option transactions, command routing and screen composition helpers.
Widget ownership and layout records
-
typedef struct GraphStruct Graph
-
struct GraphStruct
Shared widget owner for graph, bar, strip, polar and track plots.
Graph is the typedef for this record. It owns component registries, layout and screen caches. Tcl callbacks can destroy the Tk window before deferred record cleanup; borrowed interp/display pointers do not extend their lifetime.
Public Members
-
int axisFormatActive
Nonzero during a synchronous axis label callback.
-
int axisFormatInvalid
Nonzero when a label callback invalidates the current mapping.
-
struct GraphRedrawSettle *redrawSettle
Owned pending resize/exposure settling state, or NULL.
-
unsigned int flags
Flags; see below for definitions.
-
Tcl_Interp *interp
Borrowed interpreter owning the widget command.
-
Tk_Window tkwin
Window that embodies the graph.
NULL means that the window has been destroyed but the data structures haven’t yet been cleaned up.
-
Display *display
Borrowed display retained for resource cleanup after tkwin is gone.
-
Tcl_Command cmdToken
Token for graph’s widget command.
-
Tk_OptionTable optionTable
Tk option table associated with this record; managed by its configuration lifecycle.
-
Tk_Window optionProxy
Owned anonymous Tk option-database lookup window for graph pseudo-components.
-
Tcl_Obj *barModeObjPtr
Tk option-managed Tcl representation for bar mode; released with option state.
-
Tcl_Obj *borderWidthObjPtr
Tk option-managed Tcl representation for border width; released with option state.
-
Tcl_Obj *bottomMarginObjPtr
Tk option-managed Tcl representation for bottom margin; released with option state.
-
Tcl_Obj *haloObjPtr
Tk option-managed Tcl representation for halo; released with option state.
-
Tcl_Obj *heightObjPtr
Tk option-managed Tcl representation for height; released with option state.
-
Tcl_Obj *highlightWidthObjPtr
Tk option-managed Tcl representation for highlight width; released with option state.
-
Tcl_Obj *leftMarginObjPtr
Tk option-managed Tcl representation for left margin; released with option state.
-
Tcl_Obj *plotBorderWidthObjPtr
Tk option-managed Tcl representation for plot border width; released with option state.
-
Tcl_Obj *plotPadXObjPtr
Tk option-managed Tcl representation for plot pad x; released with option state.
-
Tcl_Obj *plotPadYObjPtr
Tk option-managed Tcl representation for plot pad y; released with option state.
-
Tcl_Obj *rightMarginObjPtr
Tk option-managed Tcl representation for right margin; released with option state.
-
Tcl_Obj *shadowObjPtr
Tk option-managed Tcl representation for shadow; released with option state.
-
Tcl_Obj *tileObjPtr
Tk option-managed Tcl representation for tile; released with option state.
-
Tcl_Obj *topMarginObjPtr
Tk option-managed Tcl representation for top margin; released with option state.
-
Tcl_Obj *widthObjPtr
Tk option-managed Tcl representation for width; released with option state.
-
unsigned int optionMask
Change mask from the current option transaction.
-
Tcl_Size optionObjc
Number of objects in the current borrowed configure argument slice.
-
Tcl_Obj *const *optionObjv
Borrowed configure arguments, valid only during the synchronous configuration transaction.
-
int optionsConfigured
Nonzero after the first successful configuration.
-
int optionsInitialized
Nonzero once Tk option initialization has completed.
-
int tkResourcesReleased
Nonzero after the guarded Tk-resource release pass.
-
char *data
Tk option-managed application data string; interpreted by Tcl bindings, not C drawing code.
-
Tk_Cursor cursor
Tk option-managed widget cursor.
-
int inset
Sum of focus highlight and 3-D border.
Indicates how far to offset the graph from outside edge of the window.
-
int borderWidth
Width of the exterior border.
-
int relief
Relief of the exterior border.
-
Tk_3DBorder border
3-D border used to delineate the plot surface and outer edge of window
-
int highlightWidth
Width in pixels of highlight to draw around widget when it has the focus.
<= 0 means don’t draw a highlight.
-
XColor *highlightBgColor
Color for drawing traversal highlight area when highlight is off.
-
XColor *highlightColor
Color for drawing traversal highlight.
-
char *title
Tk option-managed graph title string.
-
int titleX
Mapped title anchor X in widget pixels.
-
int titleY
Mapped title anchor Y in widget pixels.
-
char *takeFocus
Tk option-managed focus traversal script/value.
-
int reqWidth
Requested widget width in pixels.
-
int reqHeight
Requested widget height in pixels.
-
int width
Current drawing width in pixels; temporarily changed during resized export.
-
int height
Current drawing height in pixels; temporarily changed during resized export.
-
Tcl_HashTable penTable
Table of pens.
-
Rbc_Uid classUid
Default element type.
-
Rbc_BindTable bindTable
Owned component binding/picking table; component pointers in it are borrowed.
-
int nextMarkerId
Tracks next marker identifier available.
-
Rbc_Chain *axisChain[4]
Chain of axes for each of the margins.
They’re separate from the margin structures to make it easier to invert the X-Y axes by simply switching chain pointers.
-
int pdfWidth
Requested PDF export width in pixels.
-
int pdfHeight
Requested PDF export height in pixels.
-
int pdfDecorations
Nonzero includes PDF plot decorations.
-
int pdfEmbedFonts
Nonzero embeds PDF font resources.
-
int svgWidth
Requested SVG export width in pixels.
-
int svgHeight
Requested SVG export height in pixels.
-
int svgDecorations
Nonzero includes SVG plot decorations.
-
int svgEmbedFonts
Nonzero embeds SVG font resources.
-
PostScript *postscript
Owned PostScript configuration record.
-
Legend *legend
Owned global legend record.
-
Rbc_BindTable trackLegendBindings
Owned binding table shared by local legends; picked records remain borrowed.
-
Crosshairs *crosshairs
Owned crosshair state.
-
int halo
Maximum distance allowed between points when searching for a point.
-
int inverted
If non-zero, indicates the x and y axis positions should be inverted.
-
Rbc_Tile tile
Retained tile client token for widget backgrounds.
-
GC drawGC
Used for drawing on the margins.
This includes the axis lines
-
GC fillGC
Used to fill the background of the margins.
The fill is governed by the background color or the tiled pixmap.
-
int plotBorderWidth
Width of interior 3-D border.
-
int plotRelief
3-d effect: TK_RELIEF_RAISED etc.
-
XColor *plotBg
Color of plotting surface.
-
GC plotFillGC
Used to fill the plotting area with a solid background color.
The fill color is stored in “plotBg”.
-
double aspect
If non-zero, force plot to conform to aspect ratio W/H.
-
int polarAutoAspect
If non-zero, Polar/Smith layout preserves equal physical X/Y data-unit scales.
-
PolarRepresentation representation
Polar or Smith presentation selector; data coordinates remain Cartesian.
-
XColor *trackSeparatorColor
NULL disables visible track dividers.
-
int trackSeparatorWidth
Track divider stroke width in pixels.
-
int trackScroll
Preserve requested track sizes instead of fitting.
-
Tcl_Obj *trackScrollCmdObj
Retained Tcl scrollbar callback prefix, or NULL; governed by widget options.
-
double trackOffset
Track-stack scroll offset in pixels along the stacking direction.
-
double trackExtent
Total laid-out track-stack extent in pixels.
-
double trackFirst
First fraction last reported to the track scrollbar callback.
-
double trackLast
Last fraction last reported to the track scrollbar callback.
-
int trackResize
Enable the optional Trackgraph class drag bindings.
-
int trackGraph
Named, vertically stacked plot regions.
-
int left
Left edge of the plot bounding box in widget pixels.
-
int right
Right edge of the plot bounding box in widget pixels.
-
int top
Top edge of the plot bounding box in widget pixels.
-
int bottom
Bottom edge of the plot bounding box in widget pixels.
-
int vRange
Positive vertical mapping span in pixels.
-
int vOffset
Vertical mapping origin below the top plot padding, in pixels.
-
int hRange
Positive horizontal mapping span in pixels.
-
int hOffset
Horizontal mapping origin after the left plot padding, in pixels.
-
double vScale
Reciprocal of vRange for normalized inverse mapping.
-
double hScale
Reciprocal of hRange for normalized inverse mapping.
-
int antialias
Rbc_Antialias; applies to Cairo geometry.
-
struct Rbc_RenderTarget *renderTarget
Borrowed active synchronous renderer marker-pass target; released by the pass owner.
-
int renderer
Rbc_Renderer selected by -renderer.
-
int doubleBuffer
If non-zero, draw the graph into a pixmap first to reduce flashing.
-
int backingStore
If non-zero, cache elements by drawing them into a pixmap.
-
Pixmap backPixmap
Pixmap used to cache elements displayed.
If backingStore is non-zero, each element is drawn into this pixmap before it is copied onto the screen. The pixmap then acts as a cache (only the pixmap is redisplayed if the none of elements have changed). This is done so that markers can be redrawn quickly over elements without redrawing each element.
-
int backWidth
Allocated backing-store width in pixels.
-
int backHeight
Allocated backing-store height in pixels.
-
double baseline
Baseline from bar chart.
-
double barWidth
Graph-level fallback bar width in data units.
-
FreqInfo *freqArr
Contains information about duplicate x-values in bar elements (malloc-ed).
This information can also be accessed by the frequency hash table
-
Tcl_HashTable freqTable
Group-key index into the graph-owned freqArr; does not separately own the array entries.
-
Tcl_Size nStacks
Number of entries in frequency array.
If zero, indicates nothing special needs to be done for “stack” or “align” modes
-
char *dataCmd
Tk option-managed data-command string; currently stored but not invoked by C code.
-
int axisFormatActive
-
struct Component
Graph-owned registry, painter order and binding-tag storage.
The graph initializes and destroys these containers; component teardown releases the records they index.
-
struct Margin
Computed and requested layout for one graph margin.
Axis chains are shared with the graph axis layout; margin output variables can invoke Tcl traces when updated.
Public Members
-
int width
Computed horizontal margin extent in pixels.
-
int height
Computed vertical margin extent in pixels.
-
int axesOffset
Pixel offset used when laying out successive margin axes.
-
int axesTitleLength
Maximum axis title length contributing to the margin requirement.
-
Tcl_Size nAxes
Number of displayed axes in this margin.
-
char *varName
Optional Tcl variable name receiving the computed margin size.
-
int reqSize
Requested margin thickness in pixels.
-
int site
MARGIN_BOTTOM, MARGIN_LEFT, MARGIN_TOP or MARGIN_RIGHT.
-
int width
Internal lifecycle callbacks
-
static void GraphEventProc(ClientData clientData, XEvent *eventPtr)
Translate Tk events into redraw requests and deferred destruction.
Expose/resize use ancestry-settled idle drawing; focus uses ordinary idle drawing. DestroyNotify releases window-dependent resources before clearing tkwin, deletes the widget command, cancels both display idle callbacks and schedules DestroyGraph through Tcl_EventuallyFree.
- Parameters:
clientData – [in] Graph record registered with Tk_CreateEventHandler.
eventPtr – [in] Borrowed event; never retained.
-
static void GraphInstCmdDeleteProc(ClientData clientData)
Release Tk-dependent resources and destroy a command’s live window.
No-op once tkwin is NULL. Clear the borrowed window cursor before releasing option resources, then clear tkwin before Tk_DestroyWindow can reenter the destruction path. DestroyNotify schedules final record disposal.
- Parameters:
clientData – [in] Graph record owned by the widget lifecycle.
-
static void DestroyGraph(DestroyData dataPtr)
Dispose of the graph record after outstanding preserves are released.
Destroy components in dependency order (markers/elements before tracks, axes and pens), then bindings, legend, drawing resources and the record. Normal window destruction has already released Tk-dependent options and cancelled idle work. The option cleanup fallback requires a valid tkwin. Does not accept NULL and must not be called on an actively used graph.
- Parameters:
dataPtr – [in] Graph record transferred to this Tcl_FreeProc.
-
static void DisplayGraphFrame(ClientData clientData)
Build one screen frame after the idle request is consumed.
Clear REDRAW_PENDING even when drawing is deferred for vector notifications or skipped during axis formatting. Sample Tk dimensions and lay out before testing whether the window is mapped. Buffered drawing composes crosshairs before presentation; direct drawing uses their erase/update/enable cycle. Successful frames queue view-change events and update margin/view callbacks.
- Parameters:
clientData – [in] Graph retained by the DisplayGraph wrapper.
-
static void DisplayGraph(ClientData clientData)
Run idle drawing with graph/interpreter lifetime and result protection.
Preserve both records and save the interpreter state around DisplayGraphFrame. Restore the interpreter state before releasing the records; do not use them after release. Preservation protects storage, not Tk resources or components that callbacks may destroy. Frame code must still validate callback state.
- Parameters:
clientData – [in] Graph record belonging to the pending idle request.
Widget option transactions
-
static int GetGraphOptionFromObj(Tcl_Obj *objPtr, const GraphOptionName *optionMap, size_t nOptions)
Classify a canonical graph option through a private map.
Borrows the object and map. Unknown or ambiguous names, and options absent from the map, return zero; this helper does not report an interpreter error.
- Parameters:
objPtr – [in] Borrowed Tcl option object; no reference is retained.
optionMap – [in] Borrowed array mapping canonical graph options to private selectors.
nOptions – [in] Number of entries accessible in optionMap.
-
static int IsGraphOption(Tcl_Obj *objPtr, const char *optionName)
Compare an option spelling with one canonical graph option.
Resolves aliases and unambiguous abbreviations through graphOptionSpecs. Returns false if resolution fails; neither argument is retained.
- Parameters:
objPtr – [in] Borrowed Tcl option object; no reference is retained.
optionName – [in] Borrowed canonical option name to compare against the resolved spelling.
-
static GraphPixelOption GetGraphPixelOption(Tcl_Obj *objPtr)
Identify a retained graph distance option.
Returns GRAPH_PIXEL_OPTION_NONE for other or unresolved options. The classification is used both for explicit-override masks and ordered parsing.
- Parameters:
objPtr – [in] Borrowed Tcl option object; no reference is retained.
-
static Tcl_Obj *GetGraphPixelObject(Graph *graphPtr, GraphPixelOption option)
Borrow the retained Tcl object for a graph distance.
Does not change its reference count. The option must be a valid distance selector; invalid selectors panic rather than returning a recoverable error.
- Parameters:
graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.
option – [in] Valid selector identifying the distance or padding field to access.
-
static int StageGraphPixelOption(Graph *graphPtr, Tcl_Obj *objPtr, GraphPixelOption option, GraphPixelTransaction *transactionPtr)
Parse one distance into a candidate transaction.
Uses the graph window for unit conversion. All distances except highlight thickness require nonnegative values; highlight thickness uses Tk conversion directly. On success sets the selected field and mask bit; on conversion error leaves that candidate unchanged and returns TCL_ERROR.
- Parameters:
graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.
objPtr – [in] Borrowed proposed option value; parsed before replacing the candidate.
option – [in] Valid selector identifying the distance or padding field to access.
transactionPtr – [inout] Initialized candidate record updated only after successful parsing; retains prior candidate on failure.
-
static int PrepareGraphPixelTransaction(Graph *graphPtr, GraphPixelTransaction *transactionPtr)
Prepare distance values without changing live numeric fields.
Requires an even borrowed option vector in the graph context. Zeroes the transaction, parses unoverridden retained defaults on first configuration, then parses every explicit occurrence in caller order. An invalid earlier occurrence fails even if a later occurrence is valid. Partial candidates on error own no resources and can be discarded.
- Parameters:
graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.
transactionPtr – [out] Caller-owned fresh candidate record, initialized here; success requires commit or cleanup as described above.
-
static void CommitGraphPixelTransaction(Graph *graphPtr, GraphPixelTransaction *transactionPtr)
Publish only staged graph distances.
Copies selected integers into graph and margin fields, then clears the mask. No conversion, geometry request or redraw occurs here.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
transactionPtr – [inout] Prepared candidate record consumed into live fields and disarmed; record storage remains caller-owned.
-
static GraphPaddingOption GetGraphPaddingOption(Tcl_Obj *objPtr)
Identify retained X or Y plot padding.
Returns GRAPH_PADDING_OPTION_NONE for other or unresolved options. The input object remains caller-owned.
- Parameters:
objPtr – [in] Borrowed Tcl option object; no reference is retained.
-
static Tcl_Obj *GetGraphPaddingObject(Graph *graphPtr, GraphPaddingOption option)
Borrow the retained Tcl object for plot padding.
Returns the X or Y object without retaining it. Invalid selectors panic.
- Parameters:
graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.
option – [in] Valid selector identifying the distance or padding field to access.
-
static int StageGraphPaddingOption(Graph *graphPtr, Tcl_Obj *objPtr, GraphPaddingOption option, GraphPaddingTransaction *transactionPtr)
Parse one plot-padding candidate.
Rbc_GetPadFromObj validates using the graph window. On success stores the padding and sets its mask bit; on error reports TCL_ERROR without publishing any live padding. The selector must be X or Y.
- Parameters:
graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.
objPtr – [in] Borrowed proposed option value; parsed before replacing the candidate.
option – [in] Valid selector identifying the distance or padding field to access.
transactionPtr – [inout] Initialized candidate record updated only after successful parsing; retains prior candidate on failure.
-
static int PrepareGraphPaddingTransaction(Graph *graphPtr, GraphPaddingTransaction *transactionPtr)
Prepare both plot-padding fields in caller order.
Zeroes the transaction and requires an even borrowed option vector. First configuration parses defaults only for axes without an explicit override. Every explicit occurrence is validated, including superseded ones. Partial candidates on failure require no resource cleanup.
- Parameters:
graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.
transactionPtr – [out] Caller-owned fresh candidate record, initialized here; success requires commit or cleanup as described above.
-
static void CommitGraphPaddingTransaction(Graph *graphPtr, GraphPaddingTransaction *transactionPtr)
Publish staged plot padding and clear its mask.
Unstaged axes keep their current padding. This helper does not request layout or redraw.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
transactionPtr – [inout] Prepared candidate record consumed into live fields and disarmed; record storage remains caller-owned.
-
static int GetGraphBarModeFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, BarMode *modePtr)
Parse a graph-wide bar mode with Tcl abbreviation rules.
Normal and infront map to MODE_INFRONT. Writes the destination only on success; invalid or ambiguous names return TCL_ERROR with a diagnostic.
- Parameters:
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objPtr – [in] Borrowed Tcl option object; no reference is retained.
modePtr – [out] Required output receiving the parsed bar mode only on success.
-
static int StageGraphBarMode(Graph *graphPtr, Tcl_Obj *objPtr, GraphBarModeTransaction *transactionPtr)
Validate and retain one candidate bar mode.
Updates the transaction only after successful conversion. Neither the input object nor a resource is retained; the live mode is unchanged.
- Parameters:
graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.
objPtr – [in] Borrowed proposed option value; parsed before replacing the candidate.
transactionPtr – [inout] Initialized candidate record updated only after successful parsing; retains prior candidate on failure.
-
static int PrepareGraphBarModeTransaction(Graph *graphPtr, GraphBarModeTransaction *transactionPtr)
Prepare the graph-wide mode from defaults and explicit options.
Zeroes the transaction. On first configuration, uses the retained default only when no explicit mode occurs. Parses all explicit occurrences in order and stops at the first error; the borrowed option vector must be even.
- Parameters:
graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.
transactionPtr – [out] Caller-owned fresh candidate record, initialized here; success requires commit or cleanup as described above.
-
static void CommitGraphBarModeTransaction(Graph *graphPtr, GraphBarModeTransaction *transactionPtr)
Publish a staged bar mode.
Leaves the live mode unchanged when unstaged and clears the staged flag after copying. No mapping or drawing is performed.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
transactionPtr – [inout] Prepared candidate record consumed into live fields and disarmed; record storage remains caller-owned.
-
static void FreeGraphShadow(Shadow *shadowPtr)
Release an owned title-shadow color and reset its value.
Accepts a non-NULL Shadow record whose color may be NULL. Clears both color and offset, allowing repeated cleanup of the same record.
- Parameters:
shadowPtr – [inout] Owned shadow value whose color is released and fields reset; record storage remains caller-owned.
-
static int StageGraphShadow(Graph *graphPtr, Tcl_Obj *objPtr, GraphShadowTransaction *transactionPtr)
Acquire a replacement title shadow before discarding a candidate.
On parse failure returns TCL_ERROR and keeps the prior candidate. On success releases any previously staged shadow, owns the new color in the transaction and marks it staged. The live title style is not changed.
- Parameters:
graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.
objPtr – [in] Borrowed proposed option value; parsed before replacing the candidate.
transactionPtr – [inout] Initialized candidate record updated only after successful parsing; retains prior candidate on failure.
-
static void FreeGraphShadowTransaction(GraphShadowTransaction *transactionPtr)
Discard an uncommitted shadow candidate.
Releases its color when staged and zeroes the complete transaction. Safe for a zero-initialized or already committed transaction.
- Parameters:
transactionPtr – [inout] Initialized candidate record whose staged resources are released and fields cleared.
-
static int PrepareGraphShadowTransaction(Graph *graphPtr, GraphShadowTransaction *transactionPtr)
Prepare an owned shadow candidate from retained options.
Requires a fresh transaction and an even borrowed argument vector. First configuration uses the default only if not overridden. Processes explicit occurrences in order. On any conversion error releases all staged ownership and returns TCL_ERROR; success leaves cleanup or commit to the caller.
- Parameters:
graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.
transactionPtr – [out] Caller-owned fresh candidate record, initialized here; success requires commit or cleanup as described above.
-
static void CommitGraphShadowTransaction(Graph *graphPtr, GraphShadowTransaction *transactionPtr)
Transfer the shadow candidate to the live title style.
An unstaged transaction is a no-op. Otherwise moves ownership to the graph, disarms the transaction and releases the old live shadow color.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
transactionPtr – [inout] Prepared candidate record consumed into live fields and disarmed; record storage remains caller-owned.
-
static int StageGraphTile(Graph *graphPtr, Tcl_Obj *objPtr, GraphTileTransaction *transactionPtr)
Acquire a candidate tile, including an explicit empty tile.
A NULL or empty object stages NULL. A nonempty name acquires a tile client. Acquisition failure keeps the prior candidate. Success frees any earlier candidate and transfers ownership to the transaction, not the graph.
- Parameters:
graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.
objPtr – [in] Borrowed proposed image name; NULL or an empty object explicitly stages no tile.
transactionPtr – [inout] Initialized candidate record updated only after successful parsing; retains prior candidate on failure.
-
static void FreeGraphTileTransaction(GraphTileTransaction *transactionPtr)
Release any uncommitted tile client and zero the transaction.
Safe for a zero-initialized or committed transaction. Does not release the graph live tile.
- Parameters:
transactionPtr – [inout] Initialized candidate record whose staged resources are released and fields cleared.
-
static int PrepareGraphTileTransaction(Graph *graphPtr, GraphTileTransaction *transactionPtr)
Prepare a tile client from retained defaults and explicit options.
Requires a fresh transaction and an even borrowed option vector. Parses the initial default only if not overridden, then every explicit occurrence in order. Failure releases staged ownership; success requires commit or cleanup by the caller.
- Parameters:
graphPtr – [in] Borrowed widget-owned graph; required configuration or mapping state is described above.
transactionPtr – [out] Caller-owned fresh candidate record, initialized here; success requires commit or cleanup as described above.
-
static void CommitGraphTileTransaction(Graph *graphPtr, GraphTileTransaction *transactionPtr)
Install the tile candidate and its graph-change callback.
Moves ownership to the graph and disarms the transaction before freeing the previous live tile. A staged NULL clears the tile; an unstaged transaction does nothing.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
transactionPtr – [inout] Prepared candidate record consumed into live fields and disarmed; record storage remains caller-owned.
-
static int InitGraphOptions(Graph *graphPtr)
Initialize Tk-managed widget options and their database defaults.
Uses the actual widget window rather than a named component. Repeated calls after success are harmless. On Tk_InitOptions failure undefines the window cursor before freeing partially initialized options and the table. Success marks resources live but does not construct derived RBC fields.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
-
static void ResetGraphOptionContext(Graph *graphPtr)
Clear borrowed configuration arguments and the active option mask.
Does not decrement object references: the argument vector is caller-owned. Used before configuration and before restoring or releasing options.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
-
static int ConfigureGraphOptions(Graph *graphPtr, Tcl_Size objc, Tcl_Obj *const objv[], int *maskPtr)
Apply Tk options and validate derived graph resources.
Requires initialized options and an even option/value vector. Exposes the borrowed original arguments only during ConfigureGraph, forcing initialization masks on the first call. Derived conversion failure clears that context and restores Tk saved options. Success frees saved options, marks the graph configured and optionally returns the Tk change mask. A successful explicit Polar aspect disables automatic aspect; a renderer change invalidates mapping and backing pixels. Rollback concerns option resources, not all auxiliary notification state touched by validation.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
objc – [in] Even number of option/value entries in objv; zero is valid.
objv – [in] Borrowed even-length option/value vector, not a widget-command vector; retained only during configuration.
maskPtr – [out] Optional output for the Tk option change mask on successful configuration.
-
static int ConfigureNewGraph(Graph *graphPtr, Tcl_Size objc, Tcl_Obj *const objv[])
Initialize widget defaults and perform the first derived configuration.
Always calls ConfigureGraphOptions, including with zero arguments. Polar uses automatic data-unit aspect only when the option database supplies no aspect; a successful explicit aspect overrides that policy. Returns TCL_ERROR on initialization or configuration failure; creation owns graph cleanup.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
objc – [in] Even number of option/value entries in objv; zero is valid.
objv – [in] Borrowed even-length option/value vector, not a widget-command vector; retained only during configuration.
-
static void ReleaseGraphOptionResources(Graph *graphPtr)
Release Tk-owned options while the graph window remains valid.
No-op before initialization or after release. Clears borrowed transaction context, frees options and deletes the table. Derived GCs, shadow and tile remain owned by the graph destruction path.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
-
static int ConfigureGraph(Graph *graphPtr)
Validate retained graph values, then commit derived resources.
Requires initialized options and active configuration context. Validates track options, renderer availability and finite aspect, bar width and baseline, then prepares distance, padding, mode, shadow and tile candidates. Reportable conversion errors precede commits; owned candidates are freed on failure. After commit normalizes nonpositive bar width, updates geometry and GCs, reconfigures text and crosshairs, invalidates affected caches and schedules redraw. Tk option rollback belongs to ConfigureGraphOptions; auxiliary track notification bookkeeping is not part of these candidate transactions.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
Commands and screen composition
-
static int XAxisOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Dispatch the X margin-axis operation.
Uses the bottom margin normally and the left margin when inverted. Borrows the original argument vector and returns Rbc_AxisOp status unchanged; axis lookup, mutation and result construction belong to that dispatcher.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int X2AxisOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Dispatch the secondary X margin-axis operation.
Uses the top margin normally and the right margin when inverted. Borrows the original argument vector and returns Rbc_AxisOp status unchanged; axis lookup, mutation and result construction belong to that dispatcher.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int YAxisOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Dispatch the Y margin-axis operation.
Uses the left margin normally and the bottom margin when inverted. Borrows the original argument vector and returns Rbc_AxisOp status unchanged; axis lookup, mutation and result construction belong to that dispatcher.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int Y2AxisOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Dispatch the secondary Y margin-axis operation.
Uses the right margin normally and the top margin when inverted. Borrows the original argument vector and returns Rbc_AxisOp status unchanged; axis lookup, mutation and result construction belong to that dispatcher.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int BarOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Dispatch a bar operation through the shared element interface.
Passes rbcBarElementUid as the element class with the original borrowed arguments. Returns the element dispatcher status unchanged; does not acquire an element reference or perform drawing itself.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int StripOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Dispatch a strip operation through the shared element interface.
Passes rbcStripElementUid as the element class with the original borrowed arguments. Returns the element dispatcher status unchanged; does not acquire an element reference or perform drawing itself.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int LineOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Dispatch a line operation through the shared element interface.
Passes rbcLineElementUid as the element class with the original borrowed arguments. Returns the element dispatcher status unchanged; does not acquire an element reference or perform drawing itself.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int ElementOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Dispatch a default element operation through the shared element interface.
Passes graphPtr->classUid as the element class with the original borrowed arguments. Returns the element dispatcher status unchanged; does not acquire an element reference or perform drawing itself.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int ConfigureOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Query option metadata or configure the graph.
With two arguments returns all Tk option descriptions; with three returns one description. Longer calls delegate option/value pairs to ConfigureGraphOptions. Requires initialized options; returns TCL_ERROR on lookup or configuration failure.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int CgetOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Return one Tk-managed option value.
Requires initialized options and dispatcher-validated arity. Installs the value as the interpreter result, or propagates a Tk lookup error. Does not convert retained values into derived graph fields.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int ExtentsOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Report cached plot, margin or legend geometry.
Accepts Tcl unambiguous abbreviations. Plot area and legend return x, y, width and height; other selectors return one integer. Plot dimensions use inclusive endpoints. Does not perform layout; invalid selectors return TCL_ERROR rather than unconditional success.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int InsideOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Test a window point against the graph plotting extents.
Converts both coordinates through Tk screen-distance parsing and returns a Tcl boolean. Conversion errors propagate. Uses current graph extents without laying out pending geometry; it does not select an individual track.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int InvtransformOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Map a window point to the first logical X/Y axis pair.
Evaluates both coordinates as Tcl expressions, synchronizes element vectors and resets dirty ranges, then returns two doubles. Does not perform full margin layout. Checks widget validity after each expression before accessing graph resources, and rejects nonfinite input coordinates.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int TransformOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Map a data point to rounded integer window coordinates.
Evaluates Tcl expressions, synchronizes element vectors and resets dirty ranges before selecting the first logical X/Y axis pair. Checks validity after each expression and rejects nonfinite input or out-of-range rounded output before integer conversion. Does not perform full layout. Trackgraphs are rejected by the enclosing dispatcher.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int SnapGraph(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Render the graph to a photo or a Windows metafile target.
Parses paired format and integer size options; sizes below two use the current Tk window dimension. Temporarily assigns graph dimensions, requests layout and draws without the element backing store. Photo output owns a temporary pixmap and releases it after capture or callback cancellation. Windows output owns a recording DC and metafile; CLIPBOARD requests transfer of the metafile to the system. The enclosing SnapOp restores screen dimensions and invalidates temporary geometry on every return, including capture errors.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int SnapOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Capture a snapshot and restore screen geometry on every return path.
Keep pre-existing dirty and idle-request flags. Restoration preserves the capture error when capture failed, and reports layout failure otherwise. A deleted window is never used for restoration or redraw scheduling.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static Rbc_GraphOpProc *GetGraphOpFromObj(Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Resolve a widget operation and validate its argument count.
Uses the shared operation-table dispatcher at argument one. Returns a borrowed static procedure pointer, or NULL with a Tcl diagnostic. Does not execute the operation or retain any arguments.
- Parameters:
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
int Rbc_GraphInstCmdProc(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Dispatch a graph widget command under graph preservation.
Rejects widget-wide transforms for trackgraphs and recursive snapshot or document output during axis formatting. Preserves the Graph allocation across the selected handler, then releases it and returns the handler status. Preservation does not keep the Tk window or separately owned components alive; handlers crossing Tcl callbacks still need validity checks.
- Parameters:
clientData – [in] Borrowed widget-owned Graph registered for this callback; no new ownership is acquired.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int NewGraph(Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[], Rbc_Uid classUid)
Create a widget and return its Tk pathname.
Requires a pathname argument, then delegates construction to CreateGraph. On failure propagates TCL_ERROR; on success installs a new pathname string as the result. The created graph belongs to the widget lifecycle.
- Parameters:
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed constructor arguments: objv[1] is the pathname, followed by option/value pairs.
classUid – [in] Interned widget/element class identifier selecting the constructor behavior.
-
static int GraphObjCmd(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Create a graph widget through the common constructor.
Passes rbcLineElementUid to NewGraph and returns its Tcl status unchanged. The clientData argument is unused; construction owns the new widget resources.
- Parameters:
clientData – [in] Unused constructor command data.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int BarchartObjCmd(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Create a barchart widget through the common constructor.
Passes rbcBarElementUid to NewGraph and returns its Tcl status unchanged. The clientData argument is unused; construction owns the new widget resources.
- Parameters:
clientData – [in] Unused constructor command data.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int StripchartObjCmd(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Create a stripchart widget through the common constructor.
Passes rbcStripElementUid to NewGraph and returns its Tcl status unchanged. The clientData argument is unused; construction owns the new widget resources.
- Parameters:
clientData – [in] Unused constructor command data.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static int PolarObjCmd(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Create a polar widget through the common constructor.
Passes rbcPolarElementUid to NewGraph and returns its Tcl status unchanged. The clientData argument is unused; construction owns the new widget resources.
- Parameters:
clientData – [in] Unused constructor command data.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
-
static void FillMarginRectangle(Graph *graphPtr, Drawable drawable, int x, int y, int width, int height)
Fill one positive-sized margin rectangle.
Borrows the drawable and graph resources. Uses the tile when present, otherwise the margin fill GC, through the screen renderer. Nonpositive width or height is a no-op; this helper does not set tile origin.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
drawable – [in] Borrowed compatible destination drawable; caller retains ownership and presentation responsibility.
x – [in] Left margin rectangle coordinate in window pixels.
y – [in] Top margin rectangle coordinate in window pixels.
width – [in] Rectangle width in pixels; nonpositive values draw nothing.
height – [in] Rectangle height in pixels; nonpositive values draw nothing.
-
static void DrawMargins(Graph *graphPtr, Drawable drawable)
Paint margins, the plot border, margin legend, title and axes.
Sets tile origin to the widget origin, fills four surrounding rectangles, then draws decorations in that order. Uses current mapped geometry and borrowed resources. Opens and closes a screen-text context for the title; does not recompute layout or present the drawable.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
drawable – [in] Borrowed compatible destination drawable; caller retains ownership and presentation responsibility.
-
static void DrawPlotRegion(Graph *graphPtr, Drawable drawable)
Compose the cacheable plot layer in drawing order.
Clears the inclusive plot rectangle, draws track separators and grids, then Polar or Smith labels. After checking callback validity, draws under markers, lowered local/global legends, axis limits and ordinary elements. Borrows the drawable and mapped geometry. A void return does not indicate callback success; callers must check Rbc_GraphCallbackValid.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
drawable – [in] Borrowed compatible destination drawable; caller retains ownership and presentation responsibility.
-
static int UpdateMarginTraces(Graph *graphPtr)
Publish cached margin dimensions to global Tcl variables.
Writes left/right widths and top/bottom heights for configured variables. Copies names and sizes before invoking traces so configuration changes cannot invalidate borrowed option strings. Stops writes and returns false if a trace destroys the widget or cancels layout. Assignment errors remain ignored for compatibility. The display wrapper preserves graph and interpreter storage.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
-
static int TrackgraphObjCmd(void *clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Create a trackgraph widget through the common constructor.
Passes trackGraphUid to NewGraph and returns its Tcl status unchanged. The clientData argument is unused; construction owns the new widget resources.
- Parameters:
clientData – [in] Unused constructor command data.
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed argument vector; command-specific positions are described above. See Tcl command arguments.
Construction and redraw support
-
static void FreeGraphRedrawSettle(Graph *graphPtr)
Release the pending ancestry-sampling record.
Frees the owned sample array and record, then clears redrawSettle. A NULL record is harmless. Does not cancel an idle call or clear REDRAW_PENDING; the caller must handle scheduling state separately.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
-
static void SettleGraphRedraw(ClientData clientData)
Wait for two unchanged ancestry samples before presenting a frame.
Requires the graph-owned redrawSettle record installed by EventuallyRedrawSettledGraph. Samples window identity, position, size and border from the widget through its toplevel; reallocates samples when the ancestry length changes. Changed geometry resets the stable-pass count. Requeues itself until two unchanged passes, then frees samples and delegates to DisplayGraph, which consumes REDRAW_PENDING. A dead window frees samples and clears the pending flag without drawing. Does not enter an event loop.
- Parameters:
clientData – [in] Borrowed widget-owned Graph registered for this callback; no new ownership is acquired.
-
static void EventuallyRedrawSettledGraph(Graph *graphPtr)
Replace ordinary idle drawing with ancestry-settled drawing.
Does nothing for a dead window or an already active settle request. Cancels a pending DisplayGraph call, allocates a fresh sampling record, sets REDRAW_PENDING and schedules SettleGraphRedraw. Also requests external legend redraw. Callers set geometry and drawing invalidation flags themselves.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
-
static void GraphWorldChanged(ClientData clientData)
Refresh derived font resources after a Tk world change.
Ignores dead or not-yet-configured graphs. Resets title style and height, notifies axes, legends, markers, line and bar elements of font changes, then invalidates geometry and backing pixels and schedules redraw. Does not reparse option objects or deliberately evaluate application scripts.
- Parameters:
clientData – [in] Borrowed widget-owned Graph registered for this callback; no new ownership is acquired.
-
static void TileChangedProc(ClientData clientData, Rbc_Tile tile)
Request margin redisplay when the graph tile changes.
The tile argument is unused. For a live window sets REDRAW_WORLD and schedules drawing; a dead window is ignored. Does not rebuild a GC or replace the tile client, whose ownership belongs to graph configuration.
- Parameters:
clientData – [in] Borrowed widget-owned Graph registered for this callback; no new ownership is acquired.
tile – [in] Borrowed changed tile token; unused by this callback.
-
static void AdjustAxisPointers(Graph *graphPtr)
Associate logical axis chains with physical margins.
Borrows the four existing chains. Normal order maps X/Y/X2/Y2 to bottom/left/top/right; inversion maps them to left/bottom/right/top. Does not change chain contents, axis classes, reference counts or axis sites, and does not itself invalidate geometry.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
-
static int InitPens(Graph *graphPtr)
Initialize the pen registry and create default active pens.
Creates activeLine and activeBar in that order. Returns TCL_ERROR if either creation fails, retaining any already-created pen for graph teardown. Must run once on a new graph; does not roll back the registry locally.
- Parameters:
graphPtr – [inout] Borrowed widget-owned graph; required configuration or mapping state is described above.
-
static Graph *CreateGraph(Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[], Rbc_Uid classUid)
Allocate a graph widget and install its components and lifecycle.
Requires a pathname at objv[1]. Creates the Tk window, zeroed Graph, registries and display lists after creating the anonymous option proxy. Trackgraphs retain a distinct Tk class and trackGraph flag but use the line element class. Installs window instance data, class procedures, widget command and event handler before component configuration. Creates pens, axes, exporters, crosshairs, legend and grid before applying widget options, and creates bindings last. Success returns a widget-owned Graph; failure returns NULL with the interpreter error and destroys the window. Anonymous-window failure destroys the parent before any Graph storage is allocated and preserves the original interpreter error; later failures use the installed event handler.
- Parameters:
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed constructor arguments: objv[1] is the pathname, followed by option/value pairs.
classUid – [in] Interned widget/element class identifier selecting the constructor behavior.
-
int Rbc_GraphInit(Tcl_Interp *interp)
Intern component class identifiers and register graph constructors.
Creates graph, barchart, stripchart, polar and trackgraph Tcl commands in the interpreter. Initializes class identifiers including the contour identifier, but does not register a contour widget constructor. Returns TCL_OK; no graph widget is created here.
- Parameters:
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
-
Graph *Rbc_GetGraphFromWindowData(Tk_Window tkwin)
Find graph instance data on a window or its ancestors.
Walks Tk_Parent until non-NULL RBC window instance data is found. Returns a borrowed Graph pointer, or NULL when the chain is empty. Does not retain the graph or verify a component class; callers must supply a window chain whose RBC instance data follows the graph convention.
- Parameters:
tkwin – [in] Borrowed starting window, or NULL for an empty ancestry chain.
-
struct GraphGeometrySample
One borrowed window identity and its sampled integer geometry.
The window handle is compared with the current ancestry, not retained or dereferenced through this record. The settle owner owns the sample array.
-
struct GraphRedrawSettle
Graph-owned state for coalescing geometry-manager idle work.
Owns count sample records; stablePasses counts consecutive unchanged samples. REDRAW_PENDING represents the scheduled work separately.
Public Members
-
int count
Number of geometry samples.
-
int stablePasses
Number of consecutive passes with unchanged geometry.
-
GraphGeometrySample *samples
Owned sample array.
-
int count
Windows metafile packaging
These private functions use the Windows extraction project. Their scope below is documentation-only and does not change the compiled symbols.
- group Windows metafile snapshots
Private placeable-WMF encoding and native snapshot file ownership.
Functions
-
static int InitMetaFileHeader(Tcl_Interp *interp, Tk_Window tkwin, int width, int height, APMHEADER *mfhPtr)
Initialize a packed 22-byte placeable-WMF header.
Converts width and height independently from pixels to 1440 units per inch. Rejects invalid screen metrics and dimensions that cannot fit positive signed 16-bit bounds before writing the output. The checksum XORs ten little-endian 16-bit words, excluding the checksum itself; no unaligned integer reads occur. Returns TCL_OK or TCL_ERROR with an interpreter diagnostic.
- Parameters:
interp – [inout] Borrowed result interpreter; see Interpreter arguments.
tkwin – [in] Borrowed live window supplying screen pixel and millimeter dimensions.
width – [in] Positive snapshot width in pixels.
height – [in] Positive snapshot height in pixels.
mfhPtr – [out] Required packed header storage, assigned only on success.
-
static int CreateAPMetaFile(Tcl_Interp *interp, HANDLE hMetaFile, HDC hDC, APMHEADER *mfhPtr, const char *fileName)
Convert a borrowed enhanced metafile and write a placeable WMF file.
Validates both native conversion calls and the global-memory lock before opening the destination. Owns and releases the temporary memory and file; does not consume the metafile or reference DC. Conversion failure leaves an existing destination untouched. Write failure may leave a partial file. Returns TCL_OK after both writes, or TCL_ERROR with a native diagnostic.
- Parameters:
interp – [inout] Borrowed result interpreter; see Interpreter arguments.
hMetaFile – [in] Borrowed non-NULL enhanced metafile to convert.
hDC – [in] Borrowed reference DC used for MM_ANISOTROPIC conversion.
mfhPtr – [in] Borrowed initialized packed placeable header.
fileName – [in] Borrowed NUL-terminated native ANSI pathname for CreateFileA.
-
static int InitMetaFileHeader(Tcl_Interp *interp, Tk_Window tkwin, int width, int height, APMHEADER *mfhPtr)
Data records and member contracts
These records describe stored state and resource ownership. Their presence in the reference does not make private layouts part of the installed C API.
-
struct GraphBarModeTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
-
struct GraphOpSpec
Typed command dispatch entry with shared argument validation metadata.
Public Members
-
Rbc_OpSpecHeader header
Operation name, total argument bounds and usage suffix.
-
Rbc_GraphOpProc *proc
Typed command handler for this operation.
-
Rbc_OpSpecHeader header
-
struct GraphOptionName
Static graph option-name lookup entry.
-
struct GraphPaddingTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
-
struct GraphPixelTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
Public Members
-
unsigned int stagedMask
Bit mask selecting staged replacements to commit or release.
-
int borderWidth
Border thickness in pixels staged for commit or abort.
-
int bottomMarginSize
Bottom margin size in pixels staged for commit or abort.
-
int halo
Picking halo in pixels staged for commit or abort.
-
int reqHeight
Requested widget height in pixels staged for commit or abort.
-
int highlightWidth
Focus-highlight thickness in pixels staged for commit or abort.
-
int leftMarginSize
Left margin size in pixels staged for commit or abort.
-
int plotBorderWidth
Plot border thickness in pixels staged for commit or abort.
-
int rightMarginSize
Right margin size in pixels staged for commit or abort.
-
int topMarginSize
Top margin size in pixels staged for commit or abort.
-
int reqWidth
Requested widget width in pixels staged for commit or abort.
-
unsigned int stagedMask
-
struct GraphShadowTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
-
struct GraphTileTransaction
Staged option replacements; commit transfers resources and abort releases uncommitted resources.
-
struct SnapData
Parsed graph snapshot destination and dimensions.
Implementation selectors
-
enum Rbc_Renderer
Selects the graph’s screen drawing backend; export format is selected separately.
Values:
-
enumerator RBC_RENDERER_NATIVE
-
enumerator RBC_RENDERER_CAIRO
-
enumerator RBC_RENDERER_NATIVE
-
enum Rbc_Antialias
Selects the requested screen antialias policy for renderers that implement it.
Values:
-
enumerator RBC_ANTIALIAS_DEFAULT
-
enumerator RBC_ANTIALIAS_NONE
-
enumerator RBC_ANTIALIAS_GRAY
-
enumerator RBC_ANTIALIAS_FAST
-
enumerator RBC_ANTIALIAS_GOOD
-
enumerator RBC_ANTIALIAS_BEST
-
enumerator RBC_ANTIALIAS_DEFAULT
-
enum GraphBindContext
Discriminates the picked component passed through the graph binding table.
Values:
-
enumerator GRAPH_BIND_CONTEXT_AXIS
-
enumerator GRAPH_BIND_CONTEXT_ELEMENT
-
enumerator GRAPH_BIND_CONTEXT_MARKER
-
enumerator GRAPH_BIND_CONTEXT_TRACK
-
enumerator GRAPH_BIND_CONTEXT_AXIS
-
enum ClassType
Legacy graph class identifiers; this list is not a registry of all current marker or element classes.
Values:
-
enumerator CLASS_UNKNOWN
-
enumerator CLASS_LINE_ELEMENT
-
enumerator CLASS_STRIP_ELEMENT
-
enumerator CLASS_BAR_ELEMENT
-
enumerator CLASS_BITMAP_MARKER
-
enumerator CLASS_IMAGE_MARKER
-
enumerator CLASS_LINE_MARKER
-
enumerator CLASS_POLYGON_MARKER
-
enumerator CLASS_TEXT_MARKER
-
enumerator CLASS_WINDOW_MARKER
-
enumerator CLASS_UNKNOWN
-
enum PolarRepresentation
Chooses polar or Smith presentation of Cartesian data.
Values:
-
enumerator POLAR_REPRESENTATION_POLAR
-
enumerator POLAR_REPRESENTATION_SMITH
-
enumerator POLAR_REPRESENTATION_POLAR
-
enum SmithGridMode
Selects impedance circles, admittance circles or both for a Smith grid.
Values:
-
enumerator SMITH_GRID_IMPEDANCE
-
enumerator SMITH_GRID_ADMITTANCE
-
enumerator SMITH_GRID_BOTH
-
enumerator SMITH_GRID_IMPEDANCE
-
enum BarModes
Chooses the placement of bars that share an abscissa, including stacking and grouped positioning.
Values:
-
enumerator MODE_INFRONT
-
enumerator MODE_STACKED
-
enumerator MODE_ALIGNED
-
enumerator MODE_OVERLAP
-
enumerator MODE_INFRONT
-
enum MonoAttribute
Legacy foreground/background identifiers for monochrome PostScript attributes.
Values:
-
enumerator PS_MONO_BACKGROUND
-
enumerator PS_MONO_FOREGROUND
-
enumerator PS_MONO_BACKGROUND
-
enum GraphPixelOption
Selects a widget dimension during staged conversion of graph pixel options.
Values:
-
enumerator GRAPH_PIXEL_OPTION_NONE
-
enumerator GRAPH_PIXEL_OPTION_BORDER_WIDTH
-
enumerator GRAPH_PIXEL_OPTION_BOTTOM_MARGIN
-
enumerator GRAPH_PIXEL_OPTION_HALO
-
enumerator GRAPH_PIXEL_OPTION_HEIGHT
-
enumerator GRAPH_PIXEL_OPTION_HIGHLIGHT_WIDTH
-
enumerator GRAPH_PIXEL_OPTION_LEFT_MARGIN
-
enumerator GRAPH_PIXEL_OPTION_PLOT_BORDER_WIDTH
-
enumerator GRAPH_PIXEL_OPTION_RIGHT_MARGIN
-
enumerator GRAPH_PIXEL_OPTION_TOP_MARGIN
-
enumerator GRAPH_PIXEL_OPTION_WIDTH
-
enumerator GRAPH_PIXEL_OPTION_NONE