@playcanvas/pcui/types/components/Element/index.d.ts

User interface component library for the web

import { EventHandle, Events, Observer } from '@playcanvas/observer';
import * as React from 'react';
import { BindingBase } from '../../binding';
/**
 * The interface for bindable elements.
 */
interface IBindable {
    /**
     * Sets the value of the Element.
     */
    set value(values: any);
    /**
     * Gets the value of the Element.
     */
    get value(): any;
    /**
     * Sets multiple values on the Element. It is up to the Element to determine how to display them.
     */
    set values(values: Array<any>);
    /**
     * Gets multiple values on the Element.
     */
    get values(): Array<any>;
    /**
     * Sets whether the input should flash on changes.
     */
    set renderChanges(value: boolean);
    /**
     * Gets whether the input should flash on changes.
     */
    get renderChanges(): boolean;
}
/**
 * The interface for arguments for bindable elements.
 */
interface IBindableArgs {
    /**
     * Sets the value of the Element.
     */
    value?: any;
    /**
     * Sets multiple values to the Element. It is up to the Element to determine how to display them.
     */
    values?: Array<any>;
    /**
     * If `true` each input will flash on changes.
     */
    renderChanges?: boolean;
}
/**
 * The interface for elements that have placeholder text.
 */
interface IPlaceholder {
    /**
     * Sets the placeholder text of the input.
     */
    set placeholder(value: string);
    /**
     * Gets the placeholder text of the input.
     */
    get placeholder(): string;
}
/**
 * The interface for arguments for elements that have placeholder text.
 */
interface IPlaceholderArgs {
    /**
     * Sets the placeholder label that appears on the right of the input.
     */
    placeholder?: string;
}
/**
 * The interface for elements that can be focused.
 */
interface IFocusable {
    /**
     * Focus on the element. If the input contains text and select is provided, the text will be selected on focus.
     */
    focus(select?: boolean): void;
    /**
     * Unfocus the element
     */
    blur(): void;
}
/**
 * The interface for arguments for elements that have children.
 */
interface IParentArgs {
    /**
     * The children of the current component.
     */
    children?: React.ReactNode;
}
/**
 * The interface for arguments for elements that use flex layout.
 */
interface IFlexArgs {
    /**
     * Sets whether the element uses flex layout.
     */
    flex?: boolean;
    /**
     * Sets the element's `flexBasis` CSS property.
     */
    flexBasis?: string;
    /**
     * Sets the element's `flexDirection` CSS property.
     */
    flexDirection?: string;
    /**
     * Sets the element's `flexGrow` CSS property.
     */
    flexGrow?: string;
    /**
     * Sets the element's `flexShrink` CSS property.
     */
    flexShrink?: string;
    /**
     * Sets the element's `flexWrap` CSS property.
     */
    flexWrap?: string;
}
/**
 * The arguments for the {@link Element} constructor.
 */
interface ElementArgs {
    /**
     * The HTMLElement to create this {@link Element} with. If not provided this Element will create one.
     */
    dom?: HTMLElement | string;
    /**
     * A binding to use with this {@link Element}.
     */
    binding?: BindingBase;
    /**
     * If provided and the {@link Element} is clickable, this function will be called each time the element is clicked.
     */
    onClick?: () => void;
    /**
     * If provided and the {@link Element} is changeable, this function will be called each time the element value is changed.
     */
    onChange?: (value: any) => void;
    /**
     * If provided and the {@link Element} is removable, this function will be called each time the element is removed.
     */
    onRemove?: () => void;
    /**
     * Sets the parent {@link Element}.
     */
    parent?: Element;
    /**
     * Links the observer attribute at the path location in the given observer to this {@link Element}.
     */
    link?: {
        observer: Array<Observer> | Observer;
        path: Array<string> | string;
    };
    /**
     * The id attribute of this {@link Element}'s HTMLElement.
     */
    id?: string;
    /**
     * The class attribute of this {@link Element}'s HTMLElement.
     */
    class?: string | string[];
    /**
     * Sets whether this {@link Element} is at the root of the hierarchy.
     */
    isRoot?: boolean;
    /**
     * Sets whether it is possible to interact with this {@link Element} and its children.
     */
    enabled?: boolean;
    /**
     * Sets whether this {@link Element} is hidden. Defaults to `false`.
     */
    hidden?: boolean;
    /**
     * If `true`, this {@link Element} will ignore its parent's enabled value when determining whether this element is enabled. Defaults to `false`.
     */
    ignoreParent?: boolean;
    /**
     * Sets the initial width of the {@link Element}.
     */
    width?: number | null;
    /**
     * Sets the initial height of the {@link Element}.
     */
    height?: number | null;
    /**
     * Sets the tabIndex of the {@link Element}.
     */
    tabIndex?: number;
    /**
     * Sets whether the {@link Element} is in an error state.
     */
    error?: boolean;
    /**
     * Sets an initial value for Element.dom.style.
     */
    style?: string;
    /**
     * Whether this {@link Element} is read only or not. Defaults to `false`.
     */
    readOnly?: boolean;
}
/**
 * The base class for all UI elements.
 */
declare class Element extends Events {
    /**
     * Fired when the Element gets enabled.
     *
     * @event
     * @example
     * ```ts
     * const element = new Element();
     * element.on('enable', () => {
     *     console.log('Element enabled');
     * });
     * ```
     */
    static readonly EVENT_ENABLE = "enable";
    /**
     * Fired when the Element gets disabled.
     *
     * @event
     * @example
     * ```ts
     * const element = new Element();
     * element.on('disable', () => {
     *     console.log('Element disabled');
     * });
     * ```
     */
    static readonly EVENT_DISABLE = "disable";
    /**
     * Fired when the Element gets hidden.
     *
     * @event
     * @example
     * ```ts
     * const element = new Element();
     * element.on('hide', () => {
     *     console.log('Element hidden');
     * });
     * ```
     */
    static readonly EVENT_HIDE = "hide";
    /**
     * Fired when the Element or any of its parent get hidden.
     *
     * @event
     * @example
     * ```ts
     * const element = new Element();
     * element.on('hideToRoot', () => {
     *     console.log('Element or one of its parents hidden');
     * });
     * ```
     */
    static readonly EVENT_HIDE_TO_ROOT = "hideToRoot";
    /**
     * Fired when the Element stops being hidden.
     *
     * @event
     * @example
     * ```ts
     * const element = new Element();
     * element.on('show', () => {
     *     console.log('Element shown');
     * });
     * ```
     */
    static readonly EVENT_SHOW = "show";
    /**
     * Fired when the Element and all of its parents become visible.
     *
     * @event
     * @example
     * ```ts
     * const element = new Element();
     * element.on('showToRoot', () => {
     *     console.log('Element and all of its parents shown');
     * });
     * ```
     */
    static readonly EVENT_SHOW_TO_ROOT = "showToRoot";
    /**
     * Fired when the readOnly property of an Element changes.
     *
     * @event
     * @example
     * ```ts
     * const element = new Element();
     * element.on('readOnly', (readOnly: boolean) => {
     *     console.log(`Element is now ${readOnly ? 'read only' : 'editable'}`);
     * });
     * ```
     */
    static readonly EVENT_READ_ONLY = "readOnly";
    /**
     * Fired when the Element's parent gets set.
     *
     * @event
     * @example
     * ```ts
     * const element = new Element();
     * element.on('parent', (parent: Element) => {
     *     console.log(`Element's parent is now ${parent}`);
     * });
     * ```
     */
    static readonly EVENT_PARENT = "parent";
    /**
     * Fired when the mouse is clicked on the Element but only if the Element is enabled. The
     * native DOM MouseEvent is passed as a parameter to the event handler.
     *
     * @event
     * @example
     * ```ts
     * const element = new Element();
     * element.on('click', (evt: MouseEvent) => {
     *     console.log('Element clicked');
     * });
     * ```
     */
    static readonly EVENT_CLICK = "click";
    /**
     * Fired when the mouse starts hovering on the Element. The native DOM MouseEvent is passed as a
     * parameter to the event handler.
     *
     * @event
     * @example
     * ```ts
     * const element = new Element();
     * element.on('hover', (evt: MouseEvent) => {
     *     console.log('Element hovered');
     * });
     * ```
     */
    static readonly EVENT_HOVER = "hover";
    /**
     * Fired when the mouse stops hovering on the Element. The native DOM MouseEvent is passed as a
     * parameter to the event handler.
     *
     * @event
     * @example
     * ```ts
     * const element = new Element();
     * element.on('hoverend', (evt: MouseEvent) => {
     *     console.log('Element hover ended');
     * });
     * ```
     */
    static readonly EVENT_HOVER_END = "hoverend";
    /**
     * Fired after the element has been destroyed. Both the DOM element and the owner Element
     * instance are passed as parameters to the event handler.
     *
     * @event
     * @example
     * ```ts
     * const element = new Element();
     * element.on('destroy', (dom: HTMLElement, element: Element) => {
     *     console.log('Element destroyed');
     * });
     * ```
     */
    static readonly EVENT_DESTROY = "destroy";
    /**
     * Stores Element types by name and default arguments.
     */
    private static registry;
    protected _destroyed: boolean;
    protected _parent: Element;
    protected _eventsParent: EventHandle[];
    protected _dom: HTMLElement;
    protected _hiddenParents: boolean;
    protected _flashTimeout: number;
    protected _suppressChange: boolean;
    protected _binding: BindingBase;
    protected _ignoreParent: boolean;
    protected _enabled: boolean;
    protected _readOnly: boolean;
    protected _hidden: boolean;
    protected _hasError: boolean;
    protected _domContent: HTMLElement;
    protected _onClickEvt: () => void;
    /**
     * Creates a new Element.
     *
     * @param args - The arguments.
     */
    constructor(args?: Readonly<ElementArgs>);
    /**
     * Destroys the Element and its events.
     */
    destroy(): void;
    /**
     * Links the specified observers and paths to the Element's data binding.
     *
     * @param observers - An array of observers or a single observer.
     * @param paths - A path for the observer(s) or an array of paths that maps to each separate observer.
     */
    link(observers: Observer | Observer[], paths: string | string[]): void;
    /**
     * Unlinks the Element from its observers.
     */
    unlink(): void;
    /**
     * Triggers a flash animation on the Element.
     */
    flash(): void;
    protected _onClick(evt: Event): void;
    protected _onMouseOver: (evt: MouseEvent) => void;
    protected _onMouseOut: (evt: MouseEvent) => void;
    protected _onHiddenToRootChange(hiddenToRoot: boolean): void;
    protected _onEnabledChange(enabled: boolean): void;
    protected _onParentDestroy(): void;
    protected _onParentDisable(): void;
    protected _onParentEnable(): void;
    protected _onParentShowToRoot(): void;
    protected _onParentHideToRoot(): void;
    protected _onReadOnlyChange(readOnly: boolean): void;
    protected _onParentReadOnlyChange(readOnly: boolean): void;
    /**
     * @param type - The type we want to reference this Element by.
     * @param cls - The actual class of the Element.
     * @param defaultArguments - Default arguments when creating this type.
     */
    static register<Type extends Element>(type: string, cls: new () => Type, defaultArguments?: any): void;
    /**
     * @param type - The type we want to unregister.
     */
    static unregister(type: string): void;
    /**
     * Creates a new Element of the desired type.
     *
     * @param type - The type of the Element (registered by Element#register).
     * @param args - Arguments for the Element.
     * @returns The new Element or undefined if type is not found.
     */
    static create(type: string, args: ElementArgs): any;
    /**
     * Sets whether the Element or its parent chain is enabled or not. Defaults to `true`.
     */
    set enabled(value: boolean);
    /**
     * Gets whether the Element or its parent chain is enabled or not.
     */
    get enabled(): boolean;
    /**
     * Sets whether the Element will ignore parent events & variable states.
     */
    set ignoreParent(value: boolean);
    /**
     * Gets whether the Element will ignore parent events & variable states.
     */
    get ignoreParent(): boolean;
    /**
     * Gets the root DOM node for this Element.
     */
    get dom(): HTMLElement;
    /**
     * Sets the parent Element.
     */
    set parent(value: Element);
    /**
     * Gets the parent Element.
     */
    get parent(): Element;
    /**
     * Sets whether the Element is hidden.
     */
    set hidden(value: boolean);
    /**
     * Gets whether the Element is hidden.
     */
    get hidden(): boolean;
    /**
     * Gets whether the Element is hidden all the way up to the root. If the Element itself or any of its parents are hidden then this is true.
     */
    get hiddenToRoot(): boolean;
    /**
     * Sets whether the Element is read only.
     */
    set readOnly(value: boolean);
    /**
     * Gets whether the Element is read only.
     */
    get readOnly(): boolean;
    /**
     * Sets whether the Element is in an error state.
     */
    set error(value: boolean);
    /**
     * Gets whether the Element is in an error state.
     */
    get error(): boolean;
    /**
     * Shortcut to Element.dom.style.
     */
    get style(): CSSStyleDeclaration;
    /**
     * Get the `DOMTokenList` of the underlying DOM element. This is essentially a shortcut to
     * `element.dom.classList`.
     */
    get class(): DOMTokenList;
    /**
     * Sets the width of the Element in pixels. Can also be an empty string to remove it.
     */
    set width(value: number | string);
    /**
     * Gets the width of the Element in pixels.
     */
    get width(): number;
    /**
     * Sets the height of the Element in pixels. Can also be an empty string to remove it.
     */
    set height(value: number | string);
    /**
     * Gets the height of the Element in pixels.
     */
    get height(): number;
    /**
     * Sets the tabIndex of the Element.
     */
    set tabIndex(value: number);
    /**
     * Gets the tabIndex of the Element.
     */
    get tabIndex(): number;
    /**
     * Sets the Binding object for the element.
     */
    set binding(value: BindingBase);
    /**
     * Gets the Binding object for the element.
     */
    get binding(): BindingBase;
    get destroyed(): boolean;
    /**
     * Sets the flex-direction CSS property.
     */
    set flexDirection(value: string);
    /**
     * Gets the flex-direction CSS property.
     */
    get flexDirection(): string;
    /**
     * Sets the flex-grow CSS property.
     */
    set flexGrow(value: string);
    /**
     * Gets the flex-grow CSS property.
     */
    get flexGrow(): string;
    /**
     * Sets the flex-basis CSS property.
     */
    set flexBasis(value: string);
    /**
     * Gets the flex-basis CSS property.
     */
    get flexBasis(): string;
    /**
     * Sets the flex-shrink CSS property.
     */
    set flexShrink(value: string);
    /**
     * Gets the flex-shrink CSS property.
     */
    get flexShrink(): string;
    /**
     * Sets the flex-wrap CSS property.
     */
    set flexWrap(value: string);
    /**
     * Gets the flex-wrap CSS property.
     */
    get flexWrap(): string;
    /**
     * Sets the align-items CSS property.
     */
    set alignItems(value: string);
    /**
     * Gets the align-items CSS property.
     */
    get alignItems(): string;
    /**
     * Sets the align-self CSS property.
     */
    set alignSelf(value: string);
    /**
     * Gets the align-self CSS property.
     */
    get alignSelf(): string;
    /**
     * Sets the justify-content CSS property.
     */
    set justifyContent(value: string);
    /**
     * Gets the justify-content CSS property.
     */
    get justifyContent(): string;
    /**
     * Sets the justify-self CSS property.
     */
    set justifySelf(value: string);
    /**
     * Gets the justify-self CSS property.
     */
    get justifySelf(): string;
    /** @ignore */
    set disabled(value: boolean);
    /** @ignore */
    get disabled(): boolean;
    /** @ignore */
    set element(value: HTMLElement);
    /** @ignore */
    get element(): HTMLElement;
    /** @ignore */
    set innerElement(value: HTMLElement);
    /** @ignore */
    get innerElement(): HTMLElement;
}
declare global {
    interface Node {
        ui: Element;
    }
}
export { Element, ElementArgs, IBindable, IBindableArgs, IPlaceholder, IPlaceholderArgs, IFocusable, IParentArgs, IFlexArgs };