playcanvas/build/playcanvas/src/framework/components/scrollbar/component.d.ts

Open-source WebGL/WebGPU 3D engine for the web

/**
 * @import { EventHandle } from '../../../core/event-handle.js'
 * @import { Entity } from '../../entity.js'
 */
/**
 * The ScrollbarComponent enables an {@link Entity} to behave like a draggable scrollbar. It is
 * typically used together with a {@link ScrollViewComponent} to allow the user to scroll the
 * contents of a scroll view area.
 *
 * You should never need to use the ScrollbarComponent constructor directly. To add a
 * ScrollbarComponent to an {@link Entity}, use {@link Entity#addComponent}. A draggable
 * scrollbar requires a child handle entity with an input-enabled {@link ElementComponent},
 * wired up via the scrollbar's {@link handleEntity} property:
 *
 * ```javascript
 * // Create a child handle entity that the user can drag
 * const handle = new pc.Entity();
 * handle.addComponent('element', {
 *     type: pc.ELEMENTTYPE_IMAGE,
 *     useInput: true
 * });
 *
 * // Create the scrollbar entity and wire in the handle
 * const entity = new pc.Entity();
 * entity.addChild(handle);
 * entity.addComponent('element', {
 *     type: pc.ELEMENTTYPE_IMAGE
 * });
 * entity.addComponent('scrollbar', {
 *     orientation: pc.ORIENTATION_VERTICAL,
 *     value: 0,
 *     handleSize: 0.5,
 *     handleEntity: handle
 * });
 * ```
 *
 * Once the ScrollbarComponent is added to the entity, you can access it via the
 * {@link Entity#scrollbar} property:
 *
 * ```javascript
 * entity.scrollbar.value = 0.25; // Scroll the bar to 25%
 *
 * console.log(entity.scrollbar.value); // Get the scroll value and print it
 * ```
 *
 * @hideconstructor
 * @category User Interface
 */
export class ScrollbarComponent extends Component {
    /**
     * Fired whenever the scroll value changes. The handler is passed a number representing the
     * current scroll value.
     *
     * @event
     * @example
     * entity.scrollbar.on('set:value', (value) => {
     *     console.log(`Scroll value is now ${value}`);
     * });
     */
    static EVENT_SETVALUE: string;
    /** @private */
    private _orientation;
    /** @private */
    private _value;
    /** @private */
    private _handleSize;
    /**
     * @type {Entity|null}
     * @private
     */
    private _handleEntity;
    /**
     * @type {EventHandle|null}
     * @private
     */
    private _evtHandleEntityElementAdd;
    /**
     * @type {EventHandle[]}
     * @private
     */
    private _evtHandleEntityChanges;
    /**
     * @type {ElementDragHelper|null}
     * @private
     */
    private _handleDragHelper;
    /**
     * Sets whether the scrollbar moves horizontally or vertically. Can be:
     *
     * - {@link ORIENTATION_HORIZONTAL}: The scrollbar animates in the horizontal axis.
     * - {@link ORIENTATION_VERTICAL}: The scrollbar animates in the vertical axis.
     *
     * Defaults to {@link ORIENTATION_HORIZONTAL}.
     *
     * @type {number}
     */
    set orientation(arg: number);
    /**
     * Gets whether the scrollbar moves horizontally or vertically.
     *
     * @type {number}
     */
    get orientation(): number;
    /**
     * Sets the current position value of the scrollbar, in the range 0 to 1. Defaults to 0.
     *
     * @type {number}
     */
    set value(arg: number);
    /**
     * Gets the current position value of the scrollbar.
     *
     * @type {number}
     */
    get value(): number;
    /**
     * Sets the size of the handle relative to the size of the track, in the range 0 to 1. For a
     * vertical scrollbar, a value of 1 means that the handle will take up the full height of the
     * track.
     *
     * @type {number}
     */
    set handleSize(arg: number);
    /**
     * Gets the size of the handle relative to the size of the track.
     *
     * @type {number}
     */
    get handleSize(): number;
    /**
     * Sets the entity to be used as the scrollbar handle. This entity must have an
     * {@link ElementComponent} (with `useInput: true` for the handle to be draggable).
     *
     * @type {Entity|string|null}
     */
    set handleEntity(arg: Entity | null);
    /**
     * Gets the entity to be used as the scrollbar handle.
     *
     * @type {Entity|null}
     */
    get handleEntity(): Entity | null;
    _handleEntitySubscribe(): void;
    _handleEntityUnsubscribe(): void;
    _handleEntityElementSubscribe(): void;
    _handleEntityElementUnsubscribe(): void;
    _onHandleElementGain(): void;
    _rebuildDragHelper(): void;
    _onHandleElementLose(): void;
    _onHandleDrag(position: any): void;
    _updateHandlePositionAndSize(): void;
    _handlePositionToScrollValue(handlePosition: any): number;
    _scrollValueToHandlePosition(value: any): number;
    _getUsableTrackLength(): number;
    _getTrackLength(): number;
    _getHandleLength(): number;
    _getHandlePosition(): number;
    _getSign(): 1 | -1;
    _getAxis(): "x" | "y";
    _getDimension(): "height" | "width";
    _getOppositeDimension(): "height" | "width";
    _destroyDragHelper(): void;
    onRemove(): void;
    resolveDuplicatedEntityReferenceProperties(oldScrollbar: any, duplicatedIdsMap: any): void;
}
import { Component } from '../component.js';
import type { Entity } from '../../entity.js';