Scrolling C reference
These interfaces are private. See Scrolling and viewport policy for viewport policy.
-
int Rbc_AdjustViewport(int offset, int worldSize, int windowSize, int scrollUnits, int scrollMode)
Clamp an integer offset according to the selected legacy scroll mode.
Caller supplies meaningful nonnegative world/window sizes and positive unit size. Canvas mode permits negative offsets when the world is smaller than the window; listbox permits trailing blank space; hierbox clamps to zero when the world fits. Unknown modes leave the offset unchanged. Arithmetic uses wide intermediates and saturates the returned int; no state is mutated.
- Parameters:
offset – [in] Requested pixel offset to clamp; negative values are meaningful for some canvas layouts.
worldSize – [in] Nonnegative total content extent in pixels, supplied by the caller.
windowSize – [in] Nonnegative visible extent in pixels, supplied by the caller.
scrollUnits – [in] Positive pixel distance per scroll unit.
scrollMode – [in] RBC_SCROLL_MODE_CANVAS, RBC_SCROLL_MODE_LISTBOX or RBC_SCROLL_MODE_HIERBOX; unknown modes leave the computed offset unclamped.
-
int Rbc_ParseScrollRequest(Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[], Tcl_Size first, int legacy, Rbc_ScrollRequest *request)
Parse a finite double-valued scroll request without moving a viewport.
Requires a valid argument array, 0 <= first <= objc, and a non-NULL output. Queries are handled by callers. Legacy mode allows nonempty abbreviations and one numeric unit count; strict mode requires exact Tk-style words. Returns TCL_OK and assigns the complete request, or TCL_ERROR with a Tcl diagnostic and the output unchanged. Fractions and counts are not clamped.
- Parameters:
interp – [inout] Borrowed interpreter for conversion diagnostics; see Interpreter arguments.
objc – [in] Total number of accessible objv entries.
objv – [in] Borrowed full argument vector; requests start at first, earlier entries supply usage context. See Tcl command arguments.
first – [in] Request start index, with 0 <= first <= objc; an empty suffix reports usage rather than querying.
legacy – [in] Nonzero accepts nonempty abbreviations and a single numeric unit count; zero requires exact command words.
request – [out] Required kind/value record, assigned only on success; finite values are not clamped to a viewport.
-
int Rbc_GetScrollInfoFromObj(Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[], int *offsetPtr, int worldSize, int windowSize, int scrollUnits, int scrollMode)
Parse legacy integer scrolling and update a caller-owned pixel offset.
Unit/page counts are integers; moveto accepts a finite double fraction. A page is 90 percent of windowSize. Delta truncation precedes addition, with saturation before AdjustViewport applies mode bounds. On TCL_ERROR the offset is unchanged; some malformed-arity paths do not set a diagnostic. This is separate from the double-valued axis/track request parser.
- Parameters:
interp – [inout] Borrowed interpreter for conversion diagnostics; see Interpreter arguments.
objc – [in] Count of request objects only; standard scroll/moveto forms enforce their arity.
objv – [in] Borrowed request slice starting with scroll, moveto or a numeric count; NULL is rejected.
offsetPtr – [inout] Required current pixel offset; replaced with the saturated, mode-adjusted result only on success.
worldSize – [in] Nonnegative total content extent in pixels, supplied by the caller.
windowSize – [in] Nonnegative visible extent in pixels, supplied by the caller.
scrollUnits – [in] Positive pixel distance per scroll unit.
scrollMode – [in] RBC_SCROLL_MODE_CANVAS, RBC_SCROLL_MODE_LISTBOX or RBC_SCROLL_MODE_HIERBOX; unknown modes leave the computed offset unclamped.
Track-local axis scrolling is documented as
rbcGrAxisLayoutControl.Rbc_TrackYViewOp() in Axis control C reference.
-
void Rbc_NotifyTrackView(Graph *graphPtr)
Repick the stationary pointer and report track scrollbar fractions.
Called after native display/layout work; does nothing for non-track graphs or during export. Preserves the graph across binding callbacks, rechecks the live window, then notifies the scrollbar. Callbacks may destroy the widget; the caller must not assume the graph survives this function.
- Parameters:
graphPtr – [inout] Borrowed graph; callbacks may destroy it. A caller needing subsequent access must separately protect and revalidate it.
Implementation helpers
- group Integer scroll conversion
Private helpers; callers retain storage and lifetime responsibilities.
Functions
-
static int ClampScrollValue(long double value)
Saturate to int bounds and truncate an in-range value.
Requires a non-NaN value. Values above/below int bounds, including infinities, produce INT_MAX/INT_MIN; in-range conversion truncates toward zero. Does not round, apply viewport bounds or report errors. The scroll parser uses it first for a delta and then for offset-plus-delta to retain historical rounding.
- Parameters:
value – [in] Non-NaN value to saturate to int limits and otherwise truncate toward zero; infinities saturate.
-
static int ClampScrollValue(long double value)