Value conversion C reference
See Shared value conversion and numeric policy for lifetime and failure policy.
-
int Rbc_GetPixels(Tcl_Interp*, Tk_Window, const char*, int, int*)
Parse a Tk screen distance and validate its converted integer value.
Borrow window/string. Apply PIXELS_ANY, PIXELS_NONNEGATIVE or PIXELS_POSITIVE after Tk_GetPixels succeeds; these flags do not override Tk parser policy. Commit valuePtr only on success. Return Tcl status with an error diagnostic.
- Parameters:
interp – [inout] Borrowed interpreter for conversion diagnostics; see Interpreter arguments.
tkwin – [in] Borrowed live Tk window supplying screen-unit and resource context; no ownership is acquired.
string – [in] Borrowed NUL-terminated Tk screen-distance text.
check – [in] PIXELS_ANY, PIXELS_NONNEGATIVE or PIXELS_POSITIVE, applied after successful Tk conversion.
valuePtr – [out] Required converted pixel output; unchanged on conversion or sign-check failure.
-
int Rbc_GetPixelsFromObj(Tcl_Interp*, Tk_Window, Tcl_Obj*, int, int*)
Parse an object screen distance with the same checks as Rbc_GetPixels.
Borrow object/window and use Tk_GetPixelsFromObj before RBC range checks. Only success assigns valuePtr; the object may acquire Tk conversion state. No expression evaluation or graph-axis conversion is performed here.
- Parameters:
interp – [inout] Borrowed interpreter for conversion diagnostics; see Interpreter arguments.
tkwin – [in] Borrowed live Tk window supplying screen-unit and resource context; no ownership is acquired.
pixelsObj – [in] Borrowed non-NULL Tcl input object, kept valid by the caller; not retained here.
check – [in] PIXELS_ANY, PIXELS_NONNEGATIVE or PIXELS_POSITIVE, applied after successful Tk conversion.
valuePtr – [out] Required converted pixel output; unchanged on conversion or sign-check failure.
-
int Rbc_GetPadFromObj(Tcl_Interp *interp, Tk_Window tkwin, Tcl_Obj *objPtr, Rbc_Pad *padPtr)
Parse one or two nonnegative screen distances into a staged padding value.
One distance sets both sides; two preserve order. Borrow the Tcl list and window. Only assign padPtr after all conversions succeed; errors leave the previous padding unchanged. No resources are allocated into the result.
- Parameters:
interp – [inout] Borrowed interpreter for conversion diagnostics; see Interpreter arguments.
tkwin – [in] Borrowed live Tk window supplying screen-unit and resource context; no ownership is acquired.
objPtr – [in] Borrowed non-NULL Tcl input object, kept valid by the caller; not retained here.
padPtr – [out] Required padding output; both sides are committed together only on success.
-
int Rbc_GetShadowFromObj(Tcl_Interp *interp, Tk_Window tkwin, Tcl_Obj *objPtr, Shadow *shadowPtr)
Parse a color and optional nonnegative pixel offset into an owned shadow.
NULL or empty input yields no color and offset zero. A color alone defaults to offset one. Acquire a Tk color reference and release it on offset failure. Only success assigns shadowPtr. The caller must release any previous shadow separately and ultimately Tk_FreeColor the returned non-NULL color.
- Parameters:
interp – [inout] Borrowed interpreter for conversion diagnostics; see Interpreter arguments.
tkwin – [in] Borrowed live Tk window supplying screen-unit and resource context; no ownership is acquired.
objPtr – [in] Borrowed color/offset list, or NULL or empty to disable the shadow.
shadowPtr – [out] Required result receiving an owned Tk color reference on success; previous contents are not released.
-
int Rbc_GetDashesFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, Rbc_Dashes *dashesPtr)
Parse named or expression-valued dashes into a staged descriptor.
NULL/empty input or the singleton zero yields solid lines. Named patterns are exact matches; lists have at most RBC_MAX_DASH_VALUES entries in 1..255. Evaluate list entries through Tcl_ExprLongObj, so arbitrary Tcl callbacks are possible. Commit only on success and reset the descriptor offset to zero. The helper does not preserve the owning component across those callbacks.
- Parameters:
interp – [inout] Borrowed interpreter for conversion diagnostics; see Interpreter arguments.
objPtr – [in] Borrowed pattern or expression-list object; NULL or empty selects solid lines. Caller keeps the input and destination valid across expression callbacks.
dashesPtr – [out] Required descriptor; changed only on success, with offset reset to zero.
-
int Rbc_GetFillFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, int *fillPtr)
Parse a nonempty fill-name prefix into an integer mode.
Accept none (also legacy no), x, y or both using case-sensitive prefix matching. Commit fillPtr only on success. This is directional fill selection, not the graph area-fill brush or uncertainty-band parser.
- 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.
fillPtr – [out] Required FILL_* mode output; unchanged on failure.
-
int Rbc_GetStateFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, int *statePtr)
Parse an exact normal, active or disabled state name.
Borrow objPtr and commit statePtr only on success. Abbreviations and case variants are not accepted. Return TCL_ERROR with a diagnostic otherwise.
- 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.
statePtr – [out] Required STATE_NORMAL, STATE_ACTIVE or STATE_DISABLED output; unchanged on failure.
-
int Rbc_GetStringListFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, char ***listPtrPtr)
Copy a Tcl list into one caller-owned pointer-and-string allocation.
NULL input and an empty list yield NULL. Set listPtrPtr to NULL before parsing, including on failure; do not pass the sole owning field of an existing list unless its storage is managed separately. Release a nonempty result with one ckfree, never by freeing individual entries. Input strings are NUL-terminated.
- Parameters:
interp – [inout] Borrowed interpreter for conversion diagnostics; see Interpreter arguments.
objPtr – [in] Borrowed Tcl list object, or NULL for an empty list; string bytes are copied.
listPtrPtr – [out] Required output cleared before parsing; receives one ckfree-owned pointer/string block for a nonempty list, not separate entry allocations.
-
int Rbc_GetXY(Tcl_Interp *interp, Tk_Window tkwin, const char *string, int *x, int *y)
Parse an optional @x,y position using Tk screen-distance conversion.
NULL/empty input succeeds with both outputs set to -SHRT_MAX. Otherwise copy the X substring without modifying the input and parse both components. Commit x/y only after both succeed. These are screen pixels, not graph coordinates; conversion errors append position context to the interpreter diagnostic.
- Parameters:
interp – [inout] Borrowed interpreter for conversion diagnostics; see Interpreter arguments.
tkwin – [in] Borrowed live Tk window supplying screen-unit and resource context; no ownership is acquired.
string – [in] Borrowed NUL-terminated
@x,yscreen-position text; NULL or empty selects the unspecified-position sentinel.x – [out] Required X pixel output; failure leaves it unchanged, empty input assigns -SHRT_MAX.
y – [out] Required distinct Y pixel output; committed with X only after both conversions succeed.
-
int Rbc_ClampToInt(Tcl_WideInt value)
Saturate an already-computed wide integer to INT_MIN..INT_MAX.
Pure conversion with no interpreter state. Does not round floating values, check finiteness or impose widget-specific minimum sizes.
- Parameters:
value – [in] Already-computed wide integer to saturate; this function does not protect earlier arithmetic from overflow.
Private parsing and legacy Tk adapters
These string adapters implement Tk_CustomOption callbacks, not the newer Tk_OptionSpec transaction protocol. See
Shared value conversion and numeric policy for the replacement and printer ownership differences.
- group rbcConfig helper contracts
Shared implementation helpers and legacy adapters.
Functions
-
static int IsFillPrefix(const char *string, Tcl_Size length, const char *fullName)
Test a nonempty, case-sensitive prefix of a fill keyword.
- Parameters:
string – Borrowed bytes with at least length bytes available.
length – Byte count of the candidate, not a character count.
fullName – Borrowed NUL-terminated keyword.
- Returns:
Nonzero only when the candidate fits and matches the keyword. Does not modify inputs, allocate resources or set an interpreter result.
-
static int DoCheck(Tcl_Interp *interp, int length, int check)
Apply the RBC sign policy to an already converted pixel distance.
- Parameters:
interp – Interpreter receiving a diagnostic on failure.
length – Converted integer distance.
check – PIXELS_ANY, PIXELS_NONNEGATIVE or PIXELS_POSITIVE.
- Returns:
TCL_OK when accepted; TCL_ERROR for a violated sign restriction. No unit conversion or rounding occurs here. Unrecognized check values fall through successfully; callers must supply an established policy constant.
-
static int StringToDistance(void *clientData, Tcl_Interp *interp, Tk_Window tkwin, const char *string, char *widgRec, Tcl_Size offset)
Parse a legacy Tk custom-option distance into an integer field.
- Parameters:
clientData – Pixel sign policy encoded as client data.
interp – Interpreter for conversion errors.
tkwin – Window supplying screen-unit conversion context.
string – Borrowed distance string.
widgRec – Writable record containing the integer destination.
offset – Byte offset of that field.
- Returns:
TCL_OK on commit, TCL_ERROR with the old field unchanged on failure. Delegates to Rbc_GetPixels; this adapter does not evaluate Tcl scripts.
-
static const char *DistanceToString(ClientData clientData, Tk_Window tkwin, char *widgRec, Tcl_Size offset, Tcl_FreeProc **freeProcPtr)
Format a legacy distance field as an owned decimal string.
- Parameters:
clientData – Unused.
tkwin – Unused.
widgRec – Borrowed record containing an integer field.
offset – Byte offset of that field.
freeProcPtr – [out] Receives Tcl_Free for the allocated result.
- Returns:
Newly allocated string; Tk releases it through freeProcPtr. Copies the shared Rbc_Itoa buffer immediately. Does not change the field.
-
static int StringToShadow(ClientData clientData, Tcl_Interp *interp, Tk_Window tkwin, const char *string, char *widgRec, Tcl_Size offset)
Replace a legacy shadow field after parsing color and offset.
- Parameters:
clientData – Unused.
interp – Interpreter for list, color and distance errors.
tkwin – Window supplying color and screen-unit context.
string – Borrowed Tcl list string, or NULL/empty to disable the shadow.
widgRec – Writable record containing an initialized Shadow.
offset – Byte offset of that field.
- Returns:
TCL_OK on replacement, TCL_ERROR with the old shadow unchanged. Accepts one color and an optional nonnegative distance; offset defaults to one. Releases temporary list storage and any staged color on error. On success releases the old field’s color and transfers the new reference. Unlike Rbc_GetShadowFromObj, this adapter owns replacement cleanup itself.
-
static const char *ShadowToString(ClientData clientData, Tk_Window tkwin, char *widgRec, Tcl_Size offset, Tcl_FreeProc **freeProcPtr)
Serialize a legacy shadow as a color/offset Tcl list.
- Parameters:
clientData – Unused.
tkwin – Unused.
widgRec – Borrowed record containing an initialized Shadow.
offset – Byte offset of that field.
freeProcPtr – [inout] Receives Tcl_Free only for an allocated result.
- Returns:
Static empty string if disabled; otherwise a new two-element list. The disabled path leaves freeProcPtr untouched. The Tk caller must initialize its free policy for static results. Color names are quoted by Tcl_Merge.
-
static int GetState(Tcl_Interp *interp, const char *string, int *statePtr)
Parse an exact legacy state name without abbreviation.
- Parameters:
interp – Interpreter receiving an error diagnostic.
string – Non-NULL NUL-terminated normal, active or disabled name.
statePtr – [out] Receives the matching STATE constant only on success.
- Returns:
TCL_OK on success, TCL_ERROR with the destination unchanged otherwise. Matching is case-sensitive and does not execute Tcl.
-
static int GetStringList(Tcl_Interp *interp, const char *string, char ***listPtrPtr)
Split a Tcl list string into one caller-owned allocation.
- Parameters:
interp – Interpreter for list syntax errors.
string – Borrowed list string; NULL and empty input are accepted.
listPtrPtr – [out] Cleared first; receives the pointer array on success.
- Returns:
TCL_OK on success, TCL_ERROR on malformed list syntax. An empty list leaves NULL. Nonempty output contains pointers and characters in one Tcl_SplitList allocation; release it once with ckfree. This helper neither preserves nor frees a previous destination, including on error.
-
static int IsFillPrefix(const char *string, Tcl_Size length, const char *fullName)
- group rbcGrMisc helper contracts
Shared implementation helpers and legacy adapters.
Functions
-
static int GetColorPair(Tcl_Interp *interp, Tk_Window tkwin, const char *fgStr, const char *bgStr, ColorPair *pairPtr, int allowDefault)
Acquire a staged foreground/background pair.
- Parameters:
interp – Interpreter for Tk color errors.
tkwin – Window supplying color context.
fgStr – Non-NULL foreground name; empty means no color.
bgStr – Non-NULL background name; empty means no color.
pairPtr – [out] Receives both fields only after successful acquisition.
allowDefault – Accept nonempty prefixes of defcolor when nonzero.
- Returns:
TCL_OK on success; TCL_ERROR with destination unchanged on failure. Failure of the background lookup releases an acquired foreground reference. Success transfers both references, even for identical names, but does not release any previous destination. NULL and COLOR_DEFAULT are not references.
-
void Rbc_FreeColorPair(ColorPair *pairPtr)
Release both owned color references and clear a pair.
- Parameters:
pairPtr – [inout] Initialized pair, with one reference per real color field. Skips NULL and COLOR_DEFAULT. Identical real pointers still represent two acquisitions and are released twice. Both fields become NULL, making another call safe. The pair record itself is not freed.
-
static int StringToColorPair(ClientData clientData, Tcl_Interp *interp, Tk_Window tkwin, const char *string, char *widgRec, Tcl_Size offset)
Transactionally replace a legacy color-pair option field.
- Parameters:
clientData – Nonzero permits the default-color sentinel.
interp – Interpreter for list and color diagnostics.
tkwin – Window supplying color context.
string – Borrowed list of zero, one or two names; NULL/empty clears it.
widgRec – Writable record containing an initialized ColorPair.
offset – Byte offset of that field.
- Returns:
TCL_OK on replacement; TCL_ERROR leaves the old pair intact. One name sets only the foreground. Stages acquisition, releases the temporary list on all parsed paths, then frees the old pair and commits the new one.
-
static const char *NameOfColor(XColor *colorPtr)
Obtain the borrowed printable name of a color or sentinel.
- Parameters:
colorPtr – Real Tk color, NULL or COLOR_DEFAULT.
- Returns:
Empty string for NULL, defcolor for the sentinel, otherwise Tk’s name. No reference is acquired. Do not free the returned characters; copy them if they must outlive the color’s ownership.
-
static const char *ColorPairToString(ClientData clientData, Tk_Window tkwin, char *widgRec, Tcl_Size offset, Tcl_FreeProc **freeProcPtr)
Serialize two color fields into an owned two-element Tcl list.
- Parameters:
clientData – Unused.
tkwin – Unused.
widgRec – Borrowed record containing a ColorPair.
offset – Byte offset of that field.
freeProcPtr – [out] Receives Tcl_Free for the returned string.
- Returns:
Allocated list, including empty or defcolor sentinel elements. Copies an inline DString buffer or transfers its heap buffer to the caller. The local DString is intentionally not freed after that ownership transfer.
-
void Rbc_GraphExtents(Graph *graphPtr, Extents2D *extsPtr)
Read the padded mapping viewport as a clipping rectangle.
For a scrolling active track, intersects the padded rectangle with its visible bounds. Does not install a renderer clip or normalize an empty intersection.
- Parameters:
graphPtr – [in] Borrowed graph with current mapping offsets, ranges and padding; enter the owning track before calling.
extsPtr – [out] Required output receiving double-precision screen-coordinate bounds.
-
static int GetColorPair(Tcl_Interp *interp, Tk_Window tkwin, const char *fgStr, const char *bgStr, ColorPair *pairPtr, int allowDefault)