Component configuration C reference

These are private helpers implemented in rbcConfig.c and declared in rbcInt.h. They introduce no public stubs. See Component configuration and resources for transaction ordering, resource identity and cleanup responsibilities.

Resource initialization

char *Rbc_GetComponentResourceName(const char *name)

Copy a component name using the legacy resource-name convention.

Only the first byte is lowercased using tolower. The rest is unchanged; this is not Unicode case folding. An empty name produces an empty copy.

Parameters:
  • name – Non-NULL component name; component identity is not modified.

Returns:

Allocated copy owned by the caller; release with ckfree.

int Rbc_InitComponentOptions(Tcl_Interp *interp, Tk_Window parent, Tk_Window proxy, const char *name, const char *className, char *recordPtr, Tk_OptionTable optionTable)

Initialize a component record with its option-database identity.

A matching real child is used first, retaining its class. Otherwise reuse the proxy with the supplied name and class, or use parent when proxy is NULL. No window is created or destroyed here. The temporary proxy diagnostic path is cleared before returning. Record resources and proxy lifetime remain with the caller; this helper does not configure explicit command arguments.

Parameters:
  • interp – Interpreter receiving initialization errors.

  • parent – Owning widget window.

  • proxy – Graph-owned anonymous option window, or NULL for parent fallback.

  • name – Resource name, already normalized by the caller if required.

  • className – Component resource class used for the proxy.

  • recordPtr – Component record accepted by Tk_InitOptions.

  • optionTable – Tk option table describing the record.

Returns:

Result of Tk_InitOptions (TCL_OK or TCL_ERROR).

Rollback

int Rbc_RestoreOptionsOnError(Tcl_Interp *interp, Tk_SavedOptions *savedOptionsPtr)

Roll back options after validation of a successful Tk_SetOptions fails.

Clear borrowed argument vectors and transaction context before calling. Derived resources remain the caller’s responsibility: do not commit them before all fallible validation succeeds. Do not call after Tk_SetOptions itself fails, or call Tk_FreeSavedOptions after this helper.

Parameters:
  • interp – Interpreter holding the original validation error.

  • savedOptionsPtr – Successful option transaction to consume and restore.

Returns:

TCL_ERROR with the original result and return options preserved.

Option lookup and metadata

int Rbc_GetComponentOptionIndex(Tcl_Interp *interp, Tcl_Obj *objPtr, const Tk_OptionSpec *specs, const char *message, int *indexPtr)

Look up a custom component option using Tcl’s indexed-name matching.

Arguments are interpreter, option-name object, specification array, diagnostic label and output index. The array must contain concrete options (no synonyms), terminate with TK_OPTION_END, and outlive Tcl objects caching its entries. Unique abbreviations are accepted.

Parameters:
  • interp – [inout] Borrowed interpreter for conversion diagnostics; see Interpreter arguments.

  • objPtr – [in] Borrowed non-NULL Tcl input object, kept valid by the caller; not retained here.

  • specs – [in] Persistent Tk_OptionSpec array terminated by TK_OPTION_END, containing concrete options; must outlive objects caching indexed-name lookup.

  • message – [in] Borrowed NUL-terminated label for unknown/ambiguous-option diagnostics.

  • indexPtr – [out] Required specification index output, meaningful only on TCL_OK.

Returns:

TCL_OK with the selected index, or TCL_ERROR with a diagnostic.

Tcl_Obj *Rbc_GetComponentOptionInfo(const Tk_OptionSpec *spec, Tcl_Obj *valueObj)

Build configure metadata from one specification and its live value.

Arguments are a concrete specification with non-NULL optionName, dbName, dbClass and defValue strings, and a valid Tcl value object.

No option table or synthetic component record is allocated for this query.

Returns:

New zero-reference-count list containing option name, resource name, resource class, default and supplied value. The list retains the value; the caller retains any references it already owns.

Parameters:
  • spec – [in] Borrowed concrete specification with non-NULL optionName, dbName, dbClass and defValue strings; their text is copied.

  • valueObj – [in] Required current value; the returned list retains it without consuming references already held by the caller.

const char *Rbc_GetCanonicalOptionName(Tcl_Obj *objPtr, const Tk_OptionSpec *specs)

Resolve an option spelling for configuration bookkeeping.

Resolves synonyms through their clientData canonical name. Use the same specification as Tk_SetOptions; this helper does not parse option values.

Parameters:
  • objPtr – Option-name object, or NULL.

  • specs – Complete specification table, or NULL; chained tables are followed.

Returns:

Borrowed canonical name from the specification, or NULL for an empty, missing or ambiguous match. No interpreter diagnostic is produced.

Relative child lookup

Tk_Window Rbc_FindChild(Tk_Window parent, const char *name)

Resolve a relative child path beneath a borrowed parent window.

Returns a borrowed window or NULL when lookup fails. The root parent uses a single leading dot. No window is created or retained, and lookup has no result interpreter. A dotted relative name can resolve a deeper descendant.

Parameters:
  • parent – [in] Borrowed parent window, or NULL to return NULL immediately.

  • name – [in] Borrowed NUL-terminated relative child path, without a leading dot; not retained.

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 ColorPair

Foreground/background color pair; ownership belongs to the option or drawing owner.

Public Members

XColor *fgColor

Foreground color, possibly a component-specific sentinel.

XColor *bgColor

Background color, or NULL when no background is requested.

struct Rbc_ScrollRequest

Parsed scrollbar request, independent of axis application.

Public Members

Rbc_ScrollKind kind

Request kind: absolute fraction, unit increment or page increment.

double value

Fraction for moveto, or signed count for scrolling.

Component option tables

These static arrays describe how a particular record is configured. Their initializers remain in the source; the Tcl command manual describes option syntax and defaults. See Component configuration and resources for save, restore and commit.

static const Tk_OptionSpec postScriptOptionSpecs[]

PostScript component configuration, including page layout and printer-specific settings.

static const Tk_OptionSpec svgOptionSpecs[]

SVG command policy: dimensions, decorations and font embedding, backed by fields of Graph.

static const Tk_OptionSpec pdfOptionSpecs[]

PDF command policy: dimensions, decorations and font embedding, backed by separate PDF fields of Graph.

static const Tk_OptionSpec graphOptionSpecs[]

Widget options stored in Graph; change masks identify work to schedule after configuration succeeds.

static const Tk_OptionSpec graphGridOptionSpecs[]

Graph grid settings, including Cartesian and polar presentation fields.

static const Tk_OptionSpec trackGridOptionSpecs[]

Cartesian options for an individual track grid; lookup uses the track view, not the global grid table.

static const Tk_OptionSpec polarGridOptionSpecs[]

Polar grid visibility override; the end entry chains to graphGridOptionSpecs for the remaining options.

static const Tk_OptionSpec barGridOptionSpecs[]

Options selected for a bar graph grid; use the table selected at construction when querying defaults.

static const Tk_OptionSpec crosshairsOptionSpecs[]

Crosshair visibility, location and stroke resources used by the screen overlay.

static const Tk_OptionSpec lineElemOptionSpecs[]

Line element options composed from the shared line data and presentation entries.

static const Tk_OptionSpec stripElemOptionSpecs[]

Strip element configuration; the element retains strip-specific mapping and drawing callbacks.

static const Tk_OptionSpec normalLinePenOptionSpecs[]

Line pen stroke and symbol entries using the normal colour default.

static const Tk_OptionSpec activeLinePenOptionSpecs[]

Line pen entries using the active colour default.

static const Tk_OptionSpec polarElemOptionSpecs[]

Polar element data and presentation options, including complex-data interpretation.

static const Tk_OptionSpec barElemOptionSpecs[]

Bar element data bindings, placement, error presentation and pen selection.

static const Tk_OptionSpec normalBarPenOptionSpecs[]

Shared bar pen entries instantiated with normal foreground and background defaults.

static const Tk_OptionSpec activeBarPenOptionSpecs[]

The same bar pen entries instantiated with active foreground and background defaults.

static const Tk_OptionSpec trackOptionSpecs[]

Per-track layout, axis and bar-placement settings stored independently of the enclosing graph.

static const Tk_OptionSpec legendOptionSpecs[]

Graph-wide legend placement, entry styling and selection settings.

static const Tk_OptionSpec trackLegendOptionSpecs[]

Track-local legend defaults and overrides; the end entry chains to legendOptionSpecs.

static const Tk_OptionSpec textMarkerOptionSpecs[]

Text marker content, placement and text presentation resources.

static const Tk_OptionSpec windowMarkerOptionSpecs[]

Embedded window, requested dimensions and placement within the marker.

static const Tk_OptionSpec bitmapMarkerOptionSpecs[]

Bitmap marker resource and foreground/background presentation.

static const Tk_OptionSpec imageMarkerOptionSpecs[]

Image marker resource and placement; the table does not own the application image master.

static const Tk_OptionSpec lineMarkerOptionSpecs[]

Line marker coordinates, endpoint arrows and stroke options.

static const Tk_OptionSpec polygonMarkerOptionSpecs[]

Polygon marker boundary and interior options for a colour display.

static const Tk_OptionSpec polygonMarkerMonoOptionSpecs[]

Monochrome polygon marker defaults for the same marker record layout.

static const Tk_OptionSpec arcMarkerOptionSpecs[]

Arc marker ellipse, sweep, closure and fill/outline options for a colour display.

static const Tk_OptionSpec arcMarkerMonoOptionSpecs[]

Monochrome arc marker defaults for the same marker record layout.

static const Tk_OptionSpec axisOptionSpecs[]

Axis limits, ticks and presentation; retained option objects feed the axis configuration transaction.

static Tk_ConfigSpec configSpecs[]

Legacy Tk_ConfigSpec table used by the EPS canvas item; its offsets address the item rather than a graph component.