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.