lazy-widgets/dist/drivers/PointerDriver.d.ts

Typescript retained mode GUI for the HTML canvas API

import { PointerWheelMode } from '../events/PointerWheelEvent.js';
import { FocusType } from '../core/FocusType.js';
import { PointerHint } from './PointerHint.js';
import type { Widget } from '../widgets/Widget.js';
import type { Driver } from '../core/Driver.js';
import type { Root } from '../core/Root.js';
/**
 * A container which has the state associated with a specific {@link Root} for
 * use in a {@link PointerDriver}.
 *
 * @category Driver
 */
export interface PointerDriverState {
    pointer: number | null;
    pressing: number;
    hovering: boolean;
    dragLast: [number, number] | null;
    dragOrigin: [number, number];
}
/**
 * A generic pointer {@link Driver | driver}.
 *
 * Does nothing on its own, but provides an API for sending pointer events to
 * registered roots and (un)registering pointers.
 *
 * @category Driver
 */
export declare class PointerDriver implements Driver {
    /**
     * The current state for each registered and enabled root. Contains whether
     * each root is pressing, hovering, and which pointer is bound to it
     */
    protected states: Map<Root, PointerDriverState>;
    /**
     * The next available pointer ID. See {@link PointerDriver#registerPointer}
     */
    private nextPointerID;
    /**
     * The {@link PointerHint | hints} for each pointer. The keys are pointer
     * IDs, while the values are that pointer's hint.
     *
     * See {@link PointerDriver#getPointerHint}
     */
    protected hints: Map<number, PointerHint>;
    /**
     * The dragToScroll value of every pointer ID. See
     * {@link PointerDriver#registerPointer}.
     */
    private dragToScroll;
    /** Unassign a pointer from a given root and its state. */
    private unassignPointer;
    /**
     * Register a new pointer.
     *
     * @param dragToScroll - If true, then dragging will result in PointerWheelEvent events if no widget captures the events.
     * @returns Returns {@link PointerDriver#nextPointerID} and increments it
     */
    registerPointer(dragToScroll?: boolean): number;
    /**
     * Unregister a pointer.
     *
     * If a root has this pointer bound to it, the pointer is unbound from the
     * root, a LeaveRootEvent event is dispatched to the root and the hovering
     * and pressing state of the root is set to false.
     */
    unregisterPointer(pointer: number): void;
    /**
     * Check if a given pointer can dispatch an event to a given root. Also
     * automatically assigns pointer to root if possible. For internal use only.
     *
     * @param state - The root's state. Although the function could technically get the state itself, it's passed to avoid repetition since you will need the state yourself
     * @param givingActiveInput - Is the pointer giving active input (pressing button or scrolling)? If so, then it can auto-assign if the root is not being pressed by another pointer
     */
    private canDispatchEvent;
    /** Denormalise normalised pointer coordinates. Internal use only. */
    private denormaliseCoords;
    /**
     * Dispatch a pointer event to a given root. The type of
     * {@link PointerEvent} is decided automatically based on the root's state
     * and whether its pressing or not.
     *
     * If null, the last pressing state is used, meaning that the pressing state
     * has not changed. Useful if getting pointer movement in an event based
     * environment where you only know when a pointer press occurs, but not if
     * the pointer is pressed or not
     *
     * @param pointer - The registered pointer ID
     * @param xNorm - The normalised (non-integer range from 0 to 1) X coordinate of the pointer event. 0 is the left edge of the root, while 1 is the right edge of the root.
     * @param yNorm - The normalised (non-integer range from 0 to 1) Y coordinate of the pointer event. 0 is the top edge of the root, while 1 is the bottom edge of the root.
     * @param pressing - Is the pointer pressed? If null, then the last pressing state will be used. A bitmask where each set bit represents a different button being pressed
     * @param shift - Is shift being pressed?
     * @param ctrl - Is control being pressed?
     * @param alt - Is alt being pressed?
     * @returns Returns true if the pointer event was captured.
     */
    movePointer(root: Root, pointer: number, xNorm: number, yNorm: number, pressing: number | null, shift: boolean, ctrl: boolean, alt: boolean): boolean;
    /**
     * Dispatch a {@link LeaveRootEvent} event to a given root. Event will only
     * be dispatched if the root was being hovered.
     *
     * @param pointer - The registered pointer ID
     * @returns Returns true if the event was captured
     */
    leavePointer(root: Root, pointer: number): boolean;
    /**
     * Dispatch a {@link LeaveRootEvent} event to any root with the given
     * pointer assigned. Event will only be dispatched if the root was being
     * hovered. Pointer will also be unassigned from root.
     *
     * @param pointer - The registered pointer ID
     */
    leaveAnyPointer(pointer: number): void;
    /**
     * Dispatch a mouse wheel event in a given 2D direction. Event will only be
     * dispatched if the root was being hovered.
     *
     * @param pointer - The registered pointer ID
     * @param xNorm - The normalised (non-integer range from 0 to 1) X coordinate of the pointer event. 0 is the left edge of the root, while 1 is the right edge of the root.
     * @param yNorm - The normalised (non-integer range from 0 to 1) Y coordinate of the pointer event. 0 is the top edge of the root, while 1 is the bottom edge of the root.
     * @param deltaX - How much was scrolled horizontally, in pixels
     * @param deltaY - How much was scrolled vertically, in pixels
     * @param deltaZ - How much was scrolled in the Z axis, in pixels. Rarely used
     * @param deltaMode - How the delta values should be interpreted
     * @param shift - Is shift being pressed?
     * @param ctrl - Is control being pressed?
     * @param alt - Is alt being pressed?
     * @returns Returns true if the pointer event was captured.
     */
    wheelPointer(root: Root, pointer: number, xNorm: number, yNorm: number, deltaX: number, deltaY: number, deltaZ: number, deltaMode: PointerWheelMode, shift: boolean, ctrl: boolean, alt: boolean): boolean;
    /**
     * Set a pointer's {@link PointerHint | hint}.
     *
     * @param pointer - The registered pointer ID
     * @param hint - The new pointer hint
     * @returns Returns true if the pointer hint changed, else, false
     */
    protected setPointerHint(pointer: number, hint: PointerHint): boolean;
    /**
     * Get a pointer's {@link PointerHint | hint}.
     *
     * @param pointer - The registered pointer ID
     *
     * @returns Returns the given pointer ID's hint. If the pointer ID is not registered, {@link PointerHint.None} is returned.
     */
    getPointerHint(pointer: number): PointerHint;
    /**
     * Creates a state for the enabled root in {@link PointerDriver#states}.
     */
    onEnable(root: Root): void;
    /**
     * Dispatches a leave-root event for the disabled root and deletes the state
     * of the disabled root from {@link PointerDriver#states}.
     */
    onDisable(root: Root): void;
    update(_root: Root): void;
    /**
     * Dispatch an event to a root.
     *
     * @returns Returns true if the event was captured
     */
    private dispatchEvent;
    onFocusChanged(_root: Root, _focusType: FocusType, _newFocus: Widget | null): void;
    onFocusCapturerChanged(_root: Root, _focusType: FocusType, _oldCapturer: Widget | null, _newCapturer: Widget | null): void;
}