Shared drawing and window C reference
See Shared drawing and window services for ownership, failure and platform boundaries. These are private implementation interfaces.
-
GC Rbc_GetPrivateGC(Tk_Window tkwin, unsigned long gcMask, XGCValues *valuePtr)
Allocate an unshared GC compatible with a Tk window depth.
Borrow tkwin and XGCValues. For an unrealized window use the root drawable at matching depth, otherwise a temporary 1x1 pixmap. Release that temporary pixmap before returning. The caller owns the GC and must use Rbc_FreePrivateGC(), not Tk_FreeGC(). Does not force window realization.
- Parameters:
tkwin – [in] Borrowed Tk window supplying screen and depth; need not be realized.
gcMask – [in] XCreateGC mask selecting the fields to read from valuePtr.
valuePtr – [in] Borrowed XGCValues with all mask-selected fields initialized.
-
GC Rbc_GetPrivateGCFromDrawable(Display *display, Drawable drawable, unsigned long gcMask, XGCValues *valuePtr)
Allocate an unshared GC using a borrowed compatible drawable.
Pass gcMask and valuePtr to XCreateGC. The caller owns the returned GC; release it with Rbc_FreePrivateGC(). No Tk GC-cache reference is created.
- Parameters:
display – [in] Borrowed display owning drawable.
drawable – [in] Borrowed valid drawable supplying GC depth compatibility.
gcMask – [in] XCreateGC mask selecting fields in valuePtr.
valuePtr – [in] Borrowed XGCValues with all selected fields initialized.
-
void Rbc_FreePrivateGC(Display *display, GC gc)
Release a non-NULL private GC with XFreeGC.
Borrow display. Do not pass a Tk_GetGC cache reference or reuse the GC after release. No resource-ownership tracking or NULL check is performed.
- Parameters:
display – [in] Borrowed display that owns gc.
gc – [in] Owned non-NULL private GC consumed by XFreeGC; never a Tk GC-cache reference.
-
void Rbc_SetDashes(Display *display, GC gc, Rbc_Dashes *dashesPtr)
Set dash bytes and offset on a caller-mutable GC.
Read at most RBC_MAX_DASH_VALUES bytes, stopping at zero, and call XSetDashes. Borrow the descriptor; do not alter a shared Tk GC unless its owner explicitly permits mutation. This helper does not select the GC line style.
- Parameters:
display – [in] Borrowed display owning gc.
gc – [inout] Caller-mutable GC receiving dash bytes and offset; ownership is unchanged.
dashesPtr – [in] Borrowed dash descriptor with a readable RBC_MAX_DASH_VALUES array and pixel offset.
-
int Rbc_MaxRequestSize(Display *display, unsigned int elemSize)
Estimate how many elemSize-byte records fit in an X request.
Use the extended limit when supported and nonzero, otherwise the ordinary limit. Reserve four protocol words, convert to bytes and divide by elemSize. Return zero for zero element size, unusable limits or multiplication overflow; clamp the count to INT_MAX. Callers still own request batching and headers.
- Parameters:
display – [in] Borrowed live display queried for the protocol request limit.
elemSize – [in] Bytes per element; zero returns zero rather than dividing.
-
void Rbc_Draw3DRectangle(Tk_Window tkwin, Drawable drawable, Tk_3DBorder border, int x, int y, int width, int height, int borderWidth, int relief)
Draw the legacy RBC native relief border inside a rectangle.
Borrow window, drawable and border. For raised/sunken borders wider than one pixel and dimensions above two, draw an outer edge before delegating the inset to Tk_Draw3DRectangle. Edge GCs differ between X11 and Windows. This shared Tk utility does not establish a graph renderer context or clipping region.
- Parameters:
tkwin – [in] Borrowed Tk window supplying display and compatible resources.
drawable – [in] Borrowed destination drawable.
border – [in] Borrowed Tk border supplying relief colors.
x – [in] Rectangle left edge in drawable pixels.
y – [in] Rectangle top edge in drawable pixels.
width – [in] Rectangle width in pixels.
height – [in] Rectangle height in pixels.
borderWidth – [in] Requested border thickness in pixels.
relief – [in] Tk relief selector passed through to native/Tk border drawing.
-
Window Rbc_GetRealWindowId(Tk_Window tkwin)
Return a native client or toplevel-wrapper identifier.
May realize the borrowed Tk window. X11 queries the toplevel parent; Windows returns a raw HWND cast to Window. It is not a portable Tk drawable token. No ownership transfers. X11 keeps the realized client if parent lookup fails; callers must still distinguish native wrapper IDs from Tk drawable tokens.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread; may be realized to obtain a native ID, but is not retained.
-
void Rbc_SetWindowInstanceData(Tk_Window tkwin, ClientData instanceData)
Associate a borrowed payload with a Tk window in its interpreter.
Lazily allocate a one-word-key table as Tcl associated data. Replacing a value does not free the old payload. The caller must remove the entry before the window/payload becomes invalid; interpreter cleanup frees only the table.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.
instanceData – [in] Borrowed payload stored without a reference or destructor; replacement does not release the previous payload.
-
ClientData Rbc_GetWindowInstanceData(Tk_Window tkwin)
Look up a borrowed per-window payload.
Return NULL for a missing entry or an absent interpreter table. Lookup does not allocate a table and does not retain the payload or Tk window. Require a live Tk_Window even when no association exists.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.
-
void Rbc_DeleteWindowInstanceData(Tk_Window tkwin)
Remove a per-window association without freeing its payload.
Require a live window. An absent table or missing entry is a no-op and does not allocate storage. The window owner is responsible for removing its association during teardown.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.
Window lookup and table cleanup internals
- group Window association and X11 lookup internals
Functions
-
static Window rbcGetParent(Display *display, Window window)
Query an X window parent and release the returned child array.
Returns None when XQueryTree reports failure. Owns the query child array only on success and releases it with XFree before returning. The returned parent identifier is borrowed; no window is realized or retained here.
- Parameters:
display – [in] Borrowed live X display owning the supplied drawable and resources.
window – [in] Existing X window ID on display; queried without realizing or retaining it.
-
static Window GetWindowId(Tk_Window tkwin)
Realize a Tk client and select its immediate X11 parent for a toplevel.
Non-toplevel windows retain their client ID. For toplevels, a successful non-None parent replaces it; failed lookup retains the client ID. This does not guarantee a particular window-manager decoration ancestor. Requires a live window and does not change ownership or map it explicitly.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread; may be realized to obtain a native ID, but is not retained.
-
static void AssocDataCleanup(void *assocData, Tcl_Interp *interp)
Release the interpreter-owned association table and its allocation.
Registered as a Tcl associated-data delete callback. Hash entries contain borrowed Tk_Window keys and borrowed payloads; neither is dereferenced or released. The interp argument is unused. Requires the table allocation installed by Rbc_SetWindowInstanceData, not a caller-owned hash table.
- Parameters:
assocData – [inout] Owned hash-table allocation installed as interpreter associated data; entries and allocation are released, payloads remain borrowed.
interp – [in] Unused interpreter-delete callback argument; no interpreter result or variables are accessed.
-
static Window rbcGetParent(Display *display, Window window)
The Windows handle lookup is extracted separately in Windows native backend C reference.
Native stroke setup
-
static inline int Rbc_NativeLineWidth(int width)
Convert integer width to the native thin-line convention.
Returns a native GC line width. Does not convert physical units or mutate a GC.
- Parameters:
width – [in] Requested integer width; values at most one map to zero, larger values are unchanged.
Dash descriptor scanning
- group Shared native drawing helpers
Private GC and dash support beneath component drawing.
Functions
-
static int GetDashCount(const Rbc_Dashes *dashesPtr)
Count dash bytes up to the first zero or the fixed descriptor capacity.
Returns a count from zero through RBC_MAX_DASH_VALUES. Does not validate dash lengths or alter the descriptor.
- Parameters:
dashesPtr – [in] Borrowed descriptor with readable values array; offset is not examined.
-
static int GetDashCount(const Rbc_Dashes *dashesPtr)