@arcgis/map-components/dist/controllers/useHandles.d.ts

ArcGIS Map Components

import { IHandle } from '@arcgis/components-utils';
import { Controller } from '@arcgis/components-controllers';
/**
 * Avoid accidentally adding objects that look like handles because they have a `remove` method,
 * but are not because they can be destroyed e.g. the Handles object.
 */
export type SafeHandle = IHandle & {
    destroy?: null;
};
/** Avoid accidentally using a handle as a group key. */
export type GroupKey<T> = Exclude<T, IHandle>;
declare class HandleManager extends Controller {
    destroyed: boolean;
    private _handles;
    constructor(removeOn: "destroy" | "disconnect");
    /**
     * Adds one or more handles which are to be tied to the lifecycle of the object. The handles will
     * be removed when the object is destroyed.
     *
     * ```js
     * // Manually manage handles
     * const handle = reactiveUtils.when(
     *   () => !view.updating,
     *   () => {
     *     wkidSelect.disabled = false;
     *   },
     *   { once: true }
     * );
     *
     * this.addHandles(handle);
     *
     * // Destroy the object
     * this.destroy();
     * ```
     *
     * @method addHandles
     * @since 4.25
     * @instance
     * @param {module:esri/core/Accessor~WatchHandle | module:esri/core/Accessor~WatchHandle[]} handleOrHandles
     *    Handles marked for removal once the object is destroyed.
     * @param {*} [groupKey]
     *    Key identifying the group to which the handles should be added. All the handles in the group
     *    can later be removed with {@link module:esri/core/Accessor#removeHandles Accessor.removeHandles()}.
     *    If no key is provided the handles are added to a default group.
     */
    addHandles<T>(handleOrHandles: SafeHandle | SafeHandle[], groupKey?: GroupKey<T>): void;
    /**
     * Removes a group of handles owned by the object.
     *
     * @method removeHandles
     * @since 4.25
     * @instance
     * @param {*} [groupKey] - A group key or an array or collection of group keys to remove.
     *
     * @example
     * obj.removeHandles(); // removes handles from default group
     *
     * obj.removeHandles("handle-group");
     * obj.removeHandles("other-handle-group");
     */
    removeHandles<T>(groupKey?: GroupKey<T>): void;
    /**
     * Removes all the handles currently associated with the object.
     *
     * @private
     */
    removeAllHandles(): void;
    destroy(): void;
    /**
     * Returns true if a named group of handles exist.
     *
     * @method hasHandles
     * @since 4.25
     * @instance
     * @param {*} [groupKey] - A group key.
     * @return {boolean} Returns `true` if a named group of handles exist.
     *
     * @example
     * // Remove a named group of handles if they exist.
     * if (obj.hasHandles("watch-view-updates")) {
     *   obj.removeHandles("watch-view-updates");
     * }
     */
    hasHandles<T>(groupKey?: GroupKey<T>): boolean;
}
/**
 * Note: you might not need useHandles. See manager.onLifecycle instead.
 *
 * useHandles() implements the following methods from JS API's Accessor class:
 * addHandles - https://developers.arcgis.com/javascript/latest/api-reference/esri-core-Accessor.html#addHandles
 * hasHandles - https://developers.arcgis.com/javascript/latest/api-reference/esri-core-Accessor.html#hasHandles
 * removeHandles - https://developers.arcgis.com/javascript/latest/api-reference/esri-core-Accessor.html#removeHandles
 * removeAllHandles - (hidden from the JS API's JSDoc)
 *
 * Except, to adapt these to web-components, you have an option of picking
 * whether handles should get removed on component disconnect or destroy.
 *
 * destroy() is an opt-in lifecycle event provided by the controllers API.
 * Read controllers documentation for instructions on how to opt it.
 *
 * Prefer using "disconnect" over "destroy" when possible
 */
export declare const useHandles: (removeOn: "destroy" | "disconnect") => HandleManager;
export {};