Pens and style palettes
Named pens are graph-owned reusable drawing resources. rbcGrPen.c manages their registry, commands, reference counts
and option lifecycle. Concrete line and bar implementations provide their drawing attributes and derived resources.
Strip and polar elements use the line-pen implementation. Shared Pen state and declarations live in
rbcGraph.h; palette services are in rbcGrElem.c and rbcGrElem.h. See Pen and palette C reference for selected
contracts.
Named and embedded pens
A named pen belongs to the graph’s pen table. Successful Rbc_GetPen() lookup checks its type and increments its
reference count. Each acquisition must be paired with Rbc_FreePen(). Lookup maps strip and polar requirements to
the line class; a bar pen is not interchangeable with a line pen.
Elements also have a built-in pen and may select named normal or active pens. Do not apply named-pen reference operations indiscriminately to an embedded pen. Likewise, an alias to a pen pointer does not itself acquire another reference. Element pen transactions stage references before committing them; failed preparation must release the staged acquisitions.
Deletion is deferred while a named pen is referenced. The delete command sets PEN_DELETE_PENDING and destroys the
record immediately only when its count is zero. Existing users can keep using the retained record, while ordinary name
lookup no longer returns it. Releasing the last reference destroys a pending pen; releasing the last reference to a live
named pen leaves the registry’s pen available for later use.
Creation with the name of an in-use delete-pending pen can revive that record when the requested concrete type matches. It is not necessarily a new C entity. Changing its type is rejected while that old record remains. Code must not assume that command-level deletion immediately invalidates every pen pointer, or that recreating the name necessarily creates independent drawing state.
Configuration and redraw
Pen initialization uses the named Pen option-database component and the shared resource-name convention. Explicit
configuration uses Tk_SetOptions followed by the concrete pen configurator. If that configurator fails, saved Tk
options are restored. Derived resources must be prepared transactionally before replacing the active resources; see
Component configuration and resources.
The pen configure command requests backing-store and margin redraw when a successfully configured pen has references. A command naming multiple pens configures them in sequence; a later failure does not roll back earlier pens. The per-pen option transaction must not be described as a transaction over the entire multi-pen command.
Palette ownership
An element palette is a chain of style entries. The first entry represents the normal style and borrows the element’s normal pen. Additional entries acquire named-pen references and carry weight ranges. The palette’s first entry must remain present for style selection, even with no additional styles.
Rbc_FreePalette() releases the counted references and removes entries after the first. Despite its name, it does
not destroy the chain or release that first borrowed pen. The private DestroyPalette() helper performs the full
chain destruction after releasing those entries. Confusing these two operations can either leak a chain or release a
reference the palette never owned.
Palette parsing builds a candidate chain before replacing the live one. An entry that fails to parse is freed before it has been attached; earlier candidate entries and their references are then released. Styles transactions apply the same prepare/commit/cleanup ordering as other element resources. See Element data and dispatch for the shared transaction model.
Selecting a style
Rbc_StyleMap() allocates one pointer per effective data point and initializes all entries to the normal
style. It considers weights only up to the smaller of the weight length and the point count. Missing weights and
unmatched values therefore leave the normal style selected.
For each weighted point, the palette is searched from last to first. The first matching range wins, so later entries
take precedence where ranges overlap. Membership uses a normalized range comparison with DBL_EPSILON tolerance near
endpoints, rather than a strict half-open interval. Nonpositive range widths are skipped. Preserve this ordering and
tolerance when changing palette selection; adjacent boundaries and overlapping styles depend on them.
The returned array owns only the pointer storage. Its entries borrow palette styles and acquire no new pen
references. Callers free the array with ckfree and must not retain it after the underlying palette entries are
replaced. Even the zero-point case returns an allocation so callers can release it unconditionally. Size overflow
follows the allocator’s fatal-error convention.
Resource teardown
Rbc_ReleasePenTkResources() releases derived resources through the concrete pen destructor before freeing
Tk-managed colors, fonts, borders or bitmaps. It retains pen records and the registry, and guards against repeated
resource release. This pass needs a live Tk window and covers registered named pens; embedded pens belong to element
cleanup.
Rbc_DestroyPens() finally destroys the remaining records and hash table. It does not wait for reference counts,
so element references must already have been released. See Graph lifecycle and redisplay for graph teardown ordering.
Useful regression cases include several elements sharing one pen, deletion while referenced, compatible revival, rejected type changes, failed style replacement, overlapping ranges, exact range boundaries and empty data. These exercise ownership and selection behavior that a simple rendered sample cannot fully demonstrate.
Creation and command boundaries
rbcGrPen.Rbc_CreatePen() returns a graph-owned pointer without acquiring a counted reference. It scans explicit
option pairs for -type before selecting the concrete constructor; the accepted preliminary prefixes have three
through five bytes, and the last recognized occurrence determines construction. Explicit bar, line and
strip types are accepted by this scan; strip uses line storage. A supplied polar or strip default class is likewise
normalized to line. Subsequent Tk configuration still validates the options.
A new record is registered before initialization. rbcGrPen.InitPenOptions() creates its option table and
initializes the named Pen component, freeing partially initialized Tk resources if initialization fails. Explicit
options pass through rbcGrPen.ConfigurePenOptions(); with no explicit options the concrete configurator still
runs to build derived resources from defaults. Failure destroys a newly created record and removes its registry entry.
A compatible delete-pending record remains hidden during revival configuration. Only successful configuration clears its pending flag. Failure keeps the old record pending and its existing users retain their references and drawing state. A later valid create can retry revival; releasing the last reference instead destroys the pending record normally. This visibility commit is separate from the Tk option transaction, which restores the record’s option values.
Operation |
Lookup/result |
Mutation boundary |
|---|---|---|
|
Borrowed lookup, value or normalized class result |
No reference acquisition or mutation |
|
First named pen only |
Zero options returns all metadata; one option returns its metadata |
|
Names checked before applying option pairs |
Per-pen commit; later failure retains earlier changes |
|
Original name object returned on success |
New allocation or compatible retained-record revival |
|
Names processed in argument order |
Earlier deletions survive later failure |
|
Visible names matching any supplied glob |
Hash traversal order; each name appears at most once |
Configure identifies the start of options by the first argument beginning with a dash. Querying multiple names does not assemble multiple results: the first query returns immediately. Deleting the same name twice fails at the second lookup, since pending names are hidden. Neither lookup nor listing acquires a reference that could keep a pen alive after command processing.
The dispatcher checks subcommand and argument-count bounds. It does not add an independent graph/pen preservation boundary around concrete configuration. Callers and concrete configurators remain responsible for callback lifetimes; ordinary option rollback must not be used as evidence of callback safety.
Candidate palettes and default ranges
ParseStylesObj() clears its output pointer before doing any work. It always constructs the reserved normal-style
entry, including for NULL or empty style lists, and borrows the element’s current normal pen there. Additional entries
use the concrete record size supplied by the caller, which must accommodate PenStyle. The first additional
entry defaults to range 0 through 1, the second to 1 through 2, and so on.
GetPenStyleFromObj() accepts exactly one or three list elements. The three-item form converts both endpoints
before acquiring a named pen, so invalid numeric input cannot leak that reference. It uses Tcl numeric conversion rather
than expression evaluation. A one-item specification retains the initialized default range; three items replace it using
SetWeight. Endpoint ordering is not rejected: SetRange uses DBL_EPSILON when max is not greater than min. This
compatibility behavior differs from rejecting reversed ranges or treating them as empty. Keep it distinct from the style
mapper’s check for a stored nonpositive range.
Palette pen compatibility is checked against the element’s class. The penType argument retained by
StageElemStyles() is currently unused; it does not override that class check. Stage helpers acquire/parse a
successor before releasing the earlier candidate. This matters for repeated options and for delete-pending pens whose
last reference could otherwise disappear.
StageElemPen() similarly records NULL as an explicitly staged choice: normal NULL selects the built-in
pen at commit, whereas active NULL disables the active pen. An unsuccessful lookup retains the previous
candidate. The outer transaction decides whether to continue, commit, or release all staged values.
An unattached palette entry that fails parsing is freed separately. Entries already attached are cleaned through
DestroyPalette(), which releases counted style pens and destroys the chain without releasing the borrowed first
pen. Neither staging nor cleanup implicitly replaces the live element palette.