Component configuration and resources
Configuration belongs to the component that owns the record. Shared helpers in rbcConfig.c provide name lookup,
option-database initialization and rollback; they do not own graph scheduling or component-derived resources. Their
private declarations are in rbcInt.h. The similarly named rbcConfig.h contains legacy configuration macros, not
this helper interface. See Component configuration C reference for the extracted contracts.
Default values in option tables
Write simple component defaults directly in the option table, including string values and NULL. Use shared
STD_* and RGB_* constants from rbcDefaults.h directly when applicable; avoid component-specific
DEF_* aliases that only repeat those constants or literals. Shared option-entry macros can likewise contain
these defaults directly.
Keep named defaults when they select platform or build policy, such as DEF_AXIS_TICK_FONT and
DEF_GRAPH_RENDERER. Preserve the shared colour and font selections in rbcDefaults.h, including Windows
system resources. Algorithm constants such as DEF_NUM_TICKS and DEF_ARRAY_SIZE are separate from option-table
defaults and remain named.
Default strings are part of the configure metadata. Preserve their exact spelling, units and the distinction between
NULL and an empty string when moving them into a table; do not normalize equivalent boolean or numeric spellings.
Resource identity
A component’s command name and its option-database resource name serve different
purposes. Rbc_GetComponentResourceName() creates an allocated resource-name copy with only the first byte
lowercased. Callers release the copy with ckfree; the component retains its original command identity. This
preserves legacy child-name matching rather than applying Unicode case folding.
Rbc_InitComponentOptions() receives the resource name and class separately. It first looks for an existing real
child of the graph with that name. When found, initialization uses that child’s existing class. Otherwise the helper
reuses the graph’s anonymous option proxy, setting its name and class for this lookup. A NULL proxy falls back to the
parent window’s option hierarchy. Explicit command arguments are applied separately after initialization.
The proxy is not a visible component widget and has no registered Tk pathname. A temporary pathname supplies meaningful initialization errors and is cleared before returning. The helper refreshes the parent’s option-database cache before changing the proxy identity, so an intervening option-database update is not lost when Tk rebuilds the lookup stack. These Tk window details stay inside the helper; callers own the proxy lifetime.
Do not infer a separate option-database component from every Tcl subcommand. For example, a track has a named Track
component, whereas a local grid materializes inherited grid settings through its own initialization path. Local-grid
queries use a temporary view without creating a persistent local grid or freezing its inherited defaults.
Transactions
Tk-managed values and derived resources have separate commit points. A typical component configuration follows this sequence:
Clear stale option masks and borrowed argument pointers.
Call
Tk_SetOptionswith aTk_SavedOptionsrecord. On failure, return its error: Tk has already restored the option values.Validate relationships and prepare replacements for derived resources. Keep old active resources until all fallible work succeeds.
On validation failure, clear borrowed transaction context and call
Rbc_RestoreOptionsOnError(). It consumes the saved transaction while preserving the original interpreter result, error code and error information.On success, commit prepared resources and component relationships, clear borrowed context and call
Tk_FreeSavedOptionsto discard old option values. Schedule mapping or redraw through the owning component’s normal path.
The rollback helper does not undo arbitrary C mutations, restore graphics contexts or reverse callbacks. Calling it after committing a derived resource cannot make that resource transactional. Likewise, do not free saved options again after rollback. Initialization failure and destruction have their own cleanup paths; a saved configuration transaction is not a general destructor.
rbcGrElemLifecycle.ConfigureElementOptions() in rbcGrElem.c is a concrete example. It exposes the
changed-option mask and borrowed original argument vector to the concrete element configurator. For trackgraphs it first
validates that the requested track exists and that the mapped Y axis belongs to it. Only successful configuration
commits the element’s track pointer. Both success and failure clear the borrowed arguments before releasing or restoring
saved options. Graph configuration additionally stages resources such as tiles and title shadows; consult its
implementation rather than assuming that Tk rollback covers those resources.
Lookup and configure metadata
Ordinary Tk option records use Tk’s query machinery. Custom component commands can share a concrete Tk_OptionSpec
array between initialization, lookup and metadata without constructing a temporary live record for each query.
Rbc_GetComponentOptionIndex() accepts unique abbreviations through Tcl’s indexed-name lookup. Its array contains
no synonyms and must outlive option-name objects that cache references to it.
Rbc_GetComponentOptionInfo() combines one specification with a caller-supplied live value to produce the usual
five fields: option name, resource name, resource class, default and current value. The returned list owns a reference
to the value, without taking away any reference already held by the caller.
Rbc_GetCanonicalOptionName() serves configuration bookkeeping for full Tk specification tables, including
chained tables and synonym entries. It returns a borrowed specification string, with no interpreter diagnostic on
failure. It is not a value parser and does not replace Tk_SetOptions validation.
Cleanup boundaries
Tk option resources must be released with the matching option table while the required Tk window context is still available. Derived resources, observers, bindings and record storage remain with the owning component. Avoid freeing the same resource both through Tk and through manual component cleanup.
For example, rbcGraphOptions.ReleaseGraphOptionResources() uses initialization and release flags to guard
repeated cleanup. It clears configuration argument context, calls Tk_FreeConfigOptions, releases the option table,
and clears the table pointer. Graphics contexts, the title shadow and tile are handled separately. See
Graph lifecycle and redisplay for cleanup around window destruction and deferred record release.
When changing a component, check failed initialization as well as failed reconfiguration. Review custom option set, restore and free procedures together: they form one ownership protocol. Existing tests should cover rejected values without losing the previous live configuration, resource-database defaults, metadata consistency and destruction after partial setup.
Root and nested child lookup
Rbc_FindChild() joins a relative child name to a borrowed parent path. The root parent . needs no extra
separator: child resolves to .child. Other parents add one dot; .container plus child resolves to
.container.child. Dotted relative names can select descendants. Missing windows and a NULL parent return
NULL; successful results remain Tk-owned. This also preserves the real-child path used by
Rbc_InitComponentOptions() before its anonymous proxy fallback.
Reading an option table
Start with the table passed to the component’s option-table constructor. A Tk option specification associates a Tcl switch and resource-database name/class with its default, conversion policy and offsets in the receiving record. Object and internal offsets refer to different representations; a negative offset means that slot is unused. A change mask reports which parts of the component may need attention. The component decides when to remap, rebuild resources or redraw after a successful commit.
For example, graphGridOptionSpecs associates grid colour with a
field of Grid and with redraw/GC change flags. A polar grid takes
its visibility default from polarGridOptionSpecs, whose end entry
points to the base table. A track instead uses trackGridOptionSpecs.
Do not flatten these three tables into a single list of defaults.
trackLegendOptionSpecs is another example of an end entry which
chains to a base table. A normal end entry terminates lookup.
Two exceptions matter when adding options. SVG and PDF share an output dispatcher whose option accessors understand concrete integer-backed fields; placing a resource-owning field in their tables would also require changing the accessors and cleanup policy (see Export orchestration and document ownership). The EPS canvas item uses legacy Tk configuration specifications, not the Tk option-table transaction used by graph components (see EPS canvas item implementation).