Shared drawing and window services
These are private Tk support services, not another graph renderer. They are used by graph components, image code and standalone canvas/window operations. All handles belong to the owning Tk thread; none of these functions supplies locking, reference-counted widget lifetime or automatic callback protection.
Graphics-context ownership
rbcDraw.c creates private GCs directly through XCreateGC. Unlike Tk_GetGC, these do not share a cache entry
with other widgets. Use them for mutable dash state or other settings that cannot be represented by the Tk cache key.
Acquisition |
Ownership |
Release |
|---|---|---|
Exclusive caller-owned GC |
||
|
Reference to Tk’s shared cache |
|
|
Borrowed GC |
No release by borrower |
An unrealized Tk window is not forced into existence merely to obtain a GC. Rbc_GetPrivateGC() uses the screen
root when depths agree, or a temporary 1x1 pixmap at the window depth otherwise. The pixmap is released before returning
and the GC remains caller-owned. The drawable form requires the caller to supply a compatible drawable. Neither
destructor accepts arbitrary ownership or makes repeated release safe.
Rbc_SetDashes() reads a bounded, zero-terminated byte sequence and changes the GC dash offset/pattern. It does
not choose the line style. Do not use this as permission to mutate a borrowed shared GC.
Request sizing and relief
Rbc_MaxRequestSize() reports an element count, not bytes. It reserves four 32-bit protocol words, converts the
remaining limit to bytes and divides by the caller’s element size. It prefers the extended X request limit when
available, falls back to the ordinary limit, returns zero for unusable inputs and saturates the result at INT_MAX. A
caller still needs to account for its actual request format and split batches. See Native renderer internals.
Rbc_Draw3DRectangle() preserves RBC’s historical raised/sunken outer-edge appearance, then delegates the inset
to Tk_Draw3DRectangle. Its X11 and Windows edge GCs differ. It borrows all drawing resources and establishes no clipping
region. Graph paths should enter through their renderer service where one exists; standalone canvas callers do not
acquire a graph context merely to use this utility. See Rendering architecture and contracts for the module boundary.
Native identifiers
rbcWindow.c distinguishes a Tk client from its window-manager wrapper. Rbc_GetRealWindowId() can realize the
client and returns the parent for a toplevel. On Windows its result is a raw HWND cast to Window, not Tk’s drawable
wrapper. Passing that value to an API expecting a Tk drawable is incorrect. The winop snapshot path deliberately uses
Tk_WindowId for Tk path arguments.
On X11 the helper queries the tree and releases the returned child array. If the parent lookup fails or returns None, the helper keeps the realized client window as its fallback. Windows retains its platform-specific wrapper lookup; the X11 fallback does not change the Windows handle representation.
Window instance associations
The same module stores window-to-payload associations in an interpreter-owned Tcl hash table using one-word Tk_Window keys. It replaces older reliance on private Tk instance fields. Setting a value creates the table lazily. Getting a value borrows it; replacing or deleting an entry never destroys its payload. Interpreter cleanup releases the table storage only.
The owner must delete its association while the Tk window is still valid. There is no automatic per-window destroy
handler in this service. A missing entry or an absent table returns NULL from lookup. Deletion is a no-op in both
cases and does not allocate a table. A live Tk window is still required; these guards do not make a stale Tk_Window
valid.
Identifier and table lifetime details
Neither platform recursively searches for a decoration window. The helpers select the immediate parent only for Tk toplevels. Realizing a native client is distinct from explicitly mapping it; these calls do not request mapping or wait for a window manager to finish reparenting it. A returned ID is therefore a current native identity, not a retained resource or a stable wrapper promise.
On X11, rbcWindowHelpers.rbcGetParent() owns only the child-array allocation returned by XQueryTree. It
frees that array before returning the parent ID. rbcWindowHelpers.GetWindowId() retains the realized client when
the parent query fails. On Windows, rbcWindowsHandles.GetWindowHandle() uses Tk_GetHWND and GetParent
directly; a NULL parent is not replaced by the client. The shared Window return type does not erase this platform
difference. Callers needing Tk drawing operations must use Tk’s own drawable token, not reinterpret a returned HWND
as one.
Association storage is attached to the interpreter obtained from the supplied Tk window. It is not a global path-name
registry: keys are Tk_Window pointer identities, and another interpreter has its own table. A NULL stored payload is
allowed but indistinguishable from a missing entry through the lookup API. Replacing a payload neither calls its
destructor nor informs its former owner.
Deleting the final entry leaves the empty table attached to the interpreter.
rbcWindowHelpers.AssocDataCleanup() eventually deletes hash entries and the table allocation; it does not visit,
release or notify payloads. Owners must remove associations while their Tk windows are still live, before pointer
identities can become stale or be reused. There is no reference acquisition, weak-reference mechanism or automatic
per-window cleanup in this layer. These requirements also apply when lookup happens during component teardown or
callbacks.
Maintenance checks
Keep GC acquisition/release pairs explicit, preserve depth selection for unrealized windows, and review both platform
branches when changing native identifiers. Run make test-headers after declaration changes. Window capture
regressions belong in the existing winop.snap*.test files; renderer changes also need the appropriate component
drawing tests.
make test-resources exercises lookup/deletion before the first setter, payload replacement, repeated deletion and
the X11 parent-query fallback. The private harness injects parent-query failure only on X11; other tests also run on
Windows. Ordinary suite runs skip it unless RBC_RESOURCE_TEST_LIB is set.
Resource and stroke argument boundaries
Rbc_GetPrivateGC() and Rbc_GetPrivateGCFromDrawable() create uncached, caller-owned GCs. Their value
masks select which XGCValues fields must be initialized. Release these GCs with Rbc_FreePrivateGC(); a cached Tk
GC is a different ownership contract.
Rbc_NativeLineWidth() maps widths at most one to the native zero-width representation. Rbc_SetDashes()
changes dash bytes and offset on a caller-mutable GC without choosing its line style. Rbc_MaxRequestSize()
returns a record count, using a byte size per record, not a byte allocation size. Rbc_Draw3DRectangle() takes
drawable pixel coordinates and preserves the native relief border policy.
Dash storage boundary
GetDashCount() reads at most RBC_MAX_DASH_VALUES bytes and stops at the first zero. Rbc_SetDashes()
uses that count with the descriptor offset; this scan does not parse or validate a Tcl dash expression.