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

Typescript retained mode GUI for the HTML canvas API

import { AxisCoupling } from '../core/AxisCoupling.js';
import { Widget, WidgetProperties } from './Widget.js';
import { SingleParent } from './SingleParent.js';
import { Rect } from '../helpers/Rect.js';
import { WidgetEvent } from '../events/WidgetEvent.js';
import type { LayoutConstraints } from '../core/LayoutConstraints.js';
import type { Viewport } from '../core/Viewport.js';
import type { Bounds } from '../helpers/Bounds.js';
import type { Root } from '../core/Root.js';
import type { WidgetAutoXML } from '../xml/WidgetAutoXML.js';
/**
 * Optional ViewportWidget constructor properties.
 *
 * @category Core
 */
export interface ViewportWidgetProperties extends WidgetProperties {
    /** Sets {@link ViewportWidget#widthCoupling}. */
    widthCoupling?: AxisCoupling;
    /** Sets {@link ViewportWidget#heightCoupling}. */
    heightCoupling?: AxisCoupling;
    /**
     * If true, then the {@link ViewportWidget} will use a
     * {@link CanvasViewport} instead of a {@link ClippedViewport}.
     */
    useCanvas?: boolean;
    /** Sets {@link ViewportWidget#offset}. */
    offset?: [number, number];
    /** Sets {@link ViewportWidget#constraints}. */
    constraints?: LayoutConstraints;
}
/**
 * A type of container widget which is allowed to be bigger or smaller than its
 * child.
 *
 * Can be constrained to a specific type of children.
 *
 * Allows setting the offset of the child, automatically clips it if neccessary.
 * Otherwise acts like a {@link Container}. Implemented by force re-painting the
 * child and clipping it or, optionally, by using a {@link Viewport} to paint
 * the child widget to a dedicated canvas.
 *
 * Note that, if using a {@link CanvasViewport} by setting
 * {@link ViewportWidget#useCanvas} to true, widgets may be blurry when the
 * offset is not aligned to the same grid as the parent viewport. This is not
 * fixable. For better quality use {@link ClippedViewport}; only use
 * {@link ViewportWidget#useCanvas} when absolutely necessary.
 *
 * @category Widget
 */
export declare class ViewportWidget<W extends Widget = Widget> extends SingleParent<W> {
    static autoXML: WidgetAutoXML;
    /** See {@link ViewportWidget#widthCoupling}. For internal use only */
    private _widthCoupling;
    /** See {@link ViewportWidget#heightCoupling}. For internal use only */
    private _heightCoupling;
    /**
     * The actual viewport object. Can be a {@link ClippedViewport} or a
     * {@link CanvasViewport}.
     */
    protected readonly internalViewport: Viewport;
    /**
     * Is the internal viewport a {@link CanvasViewport} instance? If true, then
     * the resolution of the {@link Root} will be inherited automatically.
     */
    readonly useCanvas: boolean;
    /** {@link ViewportWidget#_constraints} but for internal use. */
    private _constraints;
    /**
     * The amount of horizontal space to reserve. By default, no space is
     * reserved. Useful for situations where additional parts are needed around
     * the viewport, such as scrollbars in {@link ScrollableViewportWidget}.
     *
     * Note that if scaling is being used, then these values are expected to
     * already be scaled.
     *
     * Should be set before {@link ViewportWidget#handleResolveDimensions} is
     * called.
     */
    protected reservedX: number;
    /** Similar to {@link ViewportWidget#reservedX}, but vertical. */
    protected reservedY: number;
    constructor(child: W, properties?: Readonly<ViewportWidgetProperties>);
    /**
     * Offset of {@link SingleParent#child}. Positional events will take this
     * into account, as well as rendering. Useful for implementing scrolling.
     */
    get offset(): [number, number];
    set offset(offset: [number, number]);
    /**
     * Child constraints for resolving layout. May be different than
     * {@link ViewportWidget#internalViewport}'s constraints. By default, this
     * is 0 minimum and Infinity maximum per axis.
     *
     * Will be automatically scaled depending on the current {@link Root}'s
     * resolution.
     *
     * Will also update the constraints of the
     * {@link ViewportWidget#internalViewport | Viewport}, but may be different
     * due to {@link ViewportWidget#widthCoupling} or
     * {@link ViewportWidget#heightCoupling}.
     */
    set constraints(constraints: LayoutConstraints);
    get constraints(): LayoutConstraints;
    /**
     * Is the width coupled to the child's? If not {@link AxisCoupling.None},
     * width constraints will be ignored or augmented.
     */
    get widthCoupling(): AxisCoupling;
    set widthCoupling(widthCoupling: AxisCoupling);
    /**
     * Is the height coupled to the child's? If not {@link AxisCoupling.None},
     * height constraints will be ignored or augmented.
     */
    get heightCoupling(): AxisCoupling;
    set heightCoupling(heightCoupling: AxisCoupling);
    protected getBoundsOf(widget: Widget): Bounds;
    protected handleEvent(event: WidgetEvent): Widget | null;
    protected handlePreLayoutUpdate(): void;
    protected handlePostLayoutUpdate(): void;
    finalizeBounds(): void;
    /**
     * Resolve the dimensions of the viewport widget, taking coupling modes and
     * reserved space into account. Note that if space is reserved, then the
     * resulting {@link ViewportWidget#idealWidth} and
     * {@link ViewportWidget#idealHeight} will not include the reserved space.
     * Child classes are expected to add the reserved space to the final
     * dimensions themselves so that they can also be aware of the final
     * non-reserved space.
     */
    protected handleResolveDimensions(minWidth: number, maxWidth: number, minHeight: number, maxHeight: number): void;
    attach(root: Root, viewport: Viewport, parent: Widget | null): void;
    detach(): void;
    protected handlePainting(dirtyRects: Array<Rect>): void;
    propagateDirtyRect(rect: Rect): void;
    queryRect(rect: Rect, relativeTo?: Widget | null): Rect;
    queryPoint(x: number, y: number, relativeTo?: Widget | null): [x: number, y: number];
}