lazy-widgets/dist/widgets/ScrollableViewportWidget.d.ts

Typescript retained mode GUI for the HTML canvas API

import { ViewportWidget, ViewportWidgetProperties } from './ViewportWidget.js';
import { AxisCoupling } from '../core/AxisCoupling.js';
import { PointerWheelEvent } from '../events/PointerWheelEvent.js';
import { ClickHelper } from '../helpers/ClickHelper.js';
import { Root } from '../core/Root.js';
import { WidgetEvent } from '../events/WidgetEvent.js';
import type { Bounds } from '../helpers/Bounds.js';
import type { TricklingEvent } from '../events/TricklingEvent.js';
import type { Widget } from './Widget.js';
import type { Rect } from '../helpers/Rect.js';
import type { WidgetAutoXML } from '../xml/WidgetAutoXML.js';
/**
 * The mode for how a scrollbar is shown in a {@link ScrollableViewportWidget}.
 *
 * @category Widget
 */
export declare enum ScrollbarMode {
    /** The scrollbar is an overlay and therefore only shown when needed */
    Overlay = 0,
    /** The scrollbar is part of the layout and therefore always shown */
    Layout = 1,
    /** The scrollbar is hidden, but the content can still be scrolled */
    Hidden = 2
}
/**
 * Optional ScrollableViewportWidget constructor properties.
 *
 * @category Widget
 */
export interface ScrollableViewportWidgetProperties extends ViewportWidgetProperties {
    /** Sets {@link ScrollableViewportWidget#scrollbarMode}. */
    scrollbarMode?: ScrollbarMode;
}
/**
 * A wrapper for a {@link ViewportWidget} with scrollbars.
 *
 * Can be constrained to a specific type of children.
 *
 * If an axis is bi-coupled, that axis will not have a scrollbar.
 *
 * @category Widget
 */
export declare class ScrollableViewportWidget<W extends Widget = Widget> extends ViewportWidget<W> {
    static autoXML: WidgetAutoXML;
    /**
     * See {@link ScrollableViewportWidget#scrollbarMode}. For internal use only
     */
    private _scrollbarMode;
    /**
     * The effective viewport width (ideal width not occupied by a non-overlay
     * scrollbar), for scrollbar calculations. For internal use only.
     */
    protected effectiveWidth: number;
    /**
     * The effective viewport height (ideal height not occupied by a non-overlay
     * scrollbar), for scrollbar calculations. For internal use only.
     */
    protected effectiveHeight: number;
    /**
     * ClickHelper used for checking if the horizontal scrollbar has been
     * dragged
     */
    protected horizontalClickHelper: ClickHelper;
    /**
     * ClickHelper used for checking if the vertical scrollbar has been dragged
     */
    protected verticalClickHelper: ClickHelper;
    /** Is the vertical scrollbar being dragged? If null, none is */
    protected verticalDragged: boolean | null;
    /** What was the starting scroll value before dragging? */
    protected startingScroll: number;
    /** What was the normalised offset when starting drag? */
    protected startingOffset: number;
    /**
     * When was the last scroll attempt in milliseconds since Unix epoch? If 0,
     * then there hasn't been a valid scroll recently.
     */
    protected lastScroll: number;
    /** What was the child width on the last layout finalization? */
    protected prevChildWidth: number;
    /** What was the child height on the last layout finalization? */
    protected prevChildHeight: number;
    /** Was the horizontal scrollbar painted last frame? */
    protected horizWasPainted: boolean;
    /** Was the vertical scrollbar painted last frame? */
    protected vertWasPainted: boolean;
    /**
     * The line height used for scrolling via wheel events.
     *
     * Should only be read from, instead of written. Use
     * {@link ScrollableViewportWidget#updateScrollLineHeight} to update this
     * value instead.
     */
    protected scrollLineHeight: number;
    constructor(child: W, properties?: Readonly<ScrollableViewportWidgetProperties>);
    /** The mode for how the scrollbar is shown. */
    get scrollbarMode(): ScrollbarMode;
    set scrollbarMode(scrollbarMode: ScrollbarMode);
    /**
     * Offset of {@link SingleParent#child}. Positional events will take this
     * into account, as well as rendering. Unlike {@link ViewportWidget#offset},
     * this will clamp to possible scroll values to avoid issues.
     */
    get offset(): [number, number];
    set offset(offset: [number, number]);
    get widthCoupling(): AxisCoupling;
    set widthCoupling(widthCoupling: AxisCoupling);
    get heightCoupling(): AxisCoupling;
    set heightCoupling(heightCoupling: AxisCoupling);
    /**
     * The current scroll values. Similar to
     * {@link ScrollableViewportWidget#offset}, but with normalised values (from
     * 0 to 1).
     */
    get scroll(): [number, number];
    set scroll(scroll: [number, number]);
    /** Get the ClickHelper of a scrollbar */
    protected getClickHelper(vertical: boolean): ClickHelper;
    /**
     * Handle a pointer/leave event for a given scrollbar.
     *
     * @returns Returns true if the event was captured
     */
    protected handleEventScrollbar(vertical: boolean, corner: boolean, event: TricklingEvent, root: Root): boolean;
    /** Clamp offset in-place to valid scroll values. For internal use only. */
    protected clampOffset(offset: [number, number]): void;
    /**
     * Handle a wheel scroll event. If scrolling fails due to being at the
     * limit, this returns true if the last scroll attempt happened less than
     * 200 milliseconds ago.
     *
     * @returns Returns true if this changed scroll was successful
     */
    protected handleWheelEvent(event: PointerWheelEvent): boolean;
    protected updateScrollLineHeight(): void;
    protected onThemeUpdated(property?: string | null): void;
    protected handleEvent(event: WidgetEvent): Widget | null;
    protected handleResolveDimensions(minWidth: number, maxWidth: number, minHeight: number, maxHeight: number): void;
    finalizeBounds(): void;
    protected handlePostLayoutUpdate(): void;
    protected handlePreLayoutUpdate(): void;
    protected handlePainting(dirtyRects: Array<Rect>): void;
    /**
     * Get the rectangles (filled and background) of a scrollbar
     *
     * @returns Returns a 2-tuple with 2 4-tuples. The first one is the scrollbar fill rectangle and the second one is the background fill rectangle. Each rectangle 4-tuple contains, respectively, horizontal offset, vertical offset, width and height
     */
    protected getScrollbarRects(vertical: boolean, corner: boolean): [Bounds, Bounds];
    /** Check if a scrollbar needs to be painted */
    protected scrollbarNeedsPaint(vertical: boolean, needed: boolean): boolean;
    /** Paint a scrollbar. For internal use only */
    protected paintScrollbar(vertical: boolean, needed: boolean, corner: boolean): void;
    protected static invisiblePadWarned: boolean;
    protected static warnInvisiblePad(): void;
}