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.

Shared value parsers

See Shared value conversion and numeric policy for pixel, padding, shadow, dash, state, fill and string-list conversion. In particular, staged values do not imply owner lifetime protection across expression callbacks, and not every parser preserves its output pointer on failure.

Transactions

Tk-managed values and derived resources have separate commit points. A typical component configuration follows this sequence:

  1. Clear stale option masks and borrowed argument pointers.

  2. Call Tk_SetOptions with a Tk_SavedOptions record. On failure, return its error: Tk has already restored the option values.

  3. Validate relationships and prepare replacements for derived resources. Keep old active resources until all fallible work succeeds.

  4. 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.

  5. On success, commit prepared resources and component relationships, clear borrowed context and call Tk_FreeSavedOptions to 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).