@eclipse-scout/core/dist/d.ts/src/util/ObjectIdProvider.d.ts

Eclipse Scout runtime

import { Constructor, ObjectModel, ObjectWithType, ObjectWithUuid, SomeRequired, Widget } from '../index';
/**
 * Helper class to extract IDs of objects and to compute uuidPaths.
 */
export declare class ObjectIdProvider implements ObjectIdProviderModel, ObjectWithType {
    model: ObjectIdProviderModel;
    initModel: SomeRequired<this['model'], 'object'>;
    self: ObjectIdProvider;
    objectType: string;
    protected _uiSeqNo: number;
    /**
     * Prefix for all ids based on the ui sequence.
     */
    static UI_SEQ_ID_PREFIX: string;
    /**
     * Delimiter for the segments of a uuidPath.
     */
    static UUID_PATH_DELIMITER: string;
    /**
     * Delimiter for dependent uuids
     */
    static DEPENDENT_UUID_DELIMITER: string;
    protected static _UI_SEQ_ID_PATTERN: RegExp;
    protected static _INSTANCE: ObjectIdProvider;
    /**
     * Modifiable set of widgets which will be skipped when building the uuidPath.
     * A widget is skipped if its class is exactly one of these (*not* `instanceof`!).
     *
     * A widget may be skipped if it is not relevant for computing the uuidPath, e.g. if it is only a layouting component.
     * For example: A group box is skipped because the id or uuid of a widget is normally unique inside a form so the group
     * box would unnecessarily enlarge the uuidPath. Also, if the widget is moved into another group box, the uuidPath won't
     * be affected. If the group box is extracted into a separate widget and gets its own class (aka. template field), it must
     * not be skipped anymore because this template can be used multiple times on the same form and must therefore be part of
     * the uuidPath. This template use-case is the reason why the subclasses of the registered widgets are not considered.
     */
    static uuidPathSkipWidgets: Set<Constructor<Widget>>;
    /**
     * Modifiable list of rules (predicates) which are used to determine if a parent should be skipped when building the uuidPath.
     *
     * These rules are always applied, even if {@link UuidPathOptions.considerSkipWidgets} is set to false.
     */
    static uuidPathAlwaysSkipRules: ((widget: Widget) => boolean)[];
    /**
     * Computes a path starting with the {@link uuid} of this object. If a parent is available, its {@link uuidPath} is appended to the right (recursively).
     * {@link UUID_PATH_DELIMITER} is used as delimiter between the segments.
     * By default, if the object is a remote (Scout Classic) object having a classId, its value is directly returned without appending the parent path,
     * because classIds typically already include their parents.
     *
     * @param object The object for which the uuidPath should be computed.
     * @param options Optional {@link UuidPathOptions} controlling the computation of the path.
     *
     * @returns the uuid path starting with this object's uuid or null if no path can be created.
     */
    uuidPath(object: ObjectUuidSource, options?: UuidPathOptions): string;
    protected _computeConsiderSkipWidgets(options: UuidPathOptions, object: ObjectUuidSource): UuidPathConsiderSkipWidgets;
    protected _findUuidPathParent(parent: Widget, considerSkipWidgets: UuidPathConsiderSkipWidgets): Widget;
    protected _isPathRelevantParent(parent: Widget, considerSkipWidgets: UuidPathConsiderSkipWidgets): boolean;
    protected _buildUuid(object: ObjectUuidSource, useFallback?: boolean): string;
    /**
     * Computes an uuid for the given object. The result may be a 'classId' for remote objects (Scout Classic) or an 'uuid' for Scout JS elements (if available).
     * If the fallback is enabled, an id might be created using the 'id' property and 'objectType' property.
     *
     * @param useFallback Specifies if a fallback identifier may be created in case the object has no specific identifier set. The fallback may be less stable. Default is true.
     * @returns the uuid for the object or null.
     */
    uuid(object: ObjectUuidSource, useFallback?: boolean): string;
    protected _considerId(object: ObjectUuidSource): boolean;
    /**
     * @returns true if the given widget should be skipped when computing the {@link uuidPath}.
     */
    protected _skipParent(obj: Widget, considerSkipWidgets?: boolean): boolean;
    /**
     * Builds the uuid of the object and prepends the given prefix.
     *
     * This is useful for objects not having an own uuid but need to be referenced nevertheless.
     */
    createDependentUuid(prefix: string, source: ObjectUuidSource): string;
    /**
     * Builds the uuid of the object, prepends it with the given prefix and sets it to the target.
     *
     * This is useful for objects not having an own uuid but need to be referenced nevertheless.
     * @see createDependentUuid
     */
    setDependentUuid(prefix: string, source: ObjectUuidSource, target: Required<ObjectUuidSource>): string;
    /**
     * Checks if the given id is an id created from the ui sequence.
     *
     * @param id The id to check or null.
     * @returns true if the id follows the format of ui sequence ids (e.g. starts with {@link UI_SEQ_ID_PREFIX}).
     */
    isUiSeqId(id: string): boolean;
    /**
     * Returns a new id based on the ui sequence.
     *
     * @returns id with prefix {@link ObjectIdProvider.UI_SEQ_ID_PREFIX}.
     */
    createUiSeqId(): string;
    /**
     * @returns current ui sequence number
     */
    get uiSeqNo(): number;
    /**
     * @returns The shared singleton {@link ObjectIdProvider} instance.
     */
    static get(): ObjectIdProvider;
}
export interface UuidPathOptions {
    /**
     * Specifies if a fallback identifier may be created in case an object has no specific identifier set.
     * The fallback may be less stable.
     *
     * Default is true.
     */
    useFallback?: boolean;
    /**
     * Specifies whether computation of the uuidPath should be aborted as soon as {@link ObjectIdProvider.uuid} returns null.
     * By default, the computation will be aborted if no uuid can be computed for the starting element.
     * If no uuid can be computed for a parent, the parent will be skipped and the computation continues with the next parent.
     */
    abortIfNoUuidFound?: boolean;
    /**
     * Specifies whether the {@link ObjectIdProvider.uuidPathSkipWidgets} should be considered when building the uuidPath.
     * By default, the skipWidgets are considered once an object (either the starting element or a parent) is found with a relevant id (id, uuid or classId).
     *
     * For example:
     * - When the starting element contains a relevant id, the skipWidgets are considered for the parents -> all parents that are part of skipWidgets will be skipped.
     * - When the starting element does not contain a relevant id, the parents are not skipped even if they are part of the skipWidgets until a parent is reached with a relevant id.
     *   All further parents may be skipped again if they are part of the skipWidgets.
     */
    considerSkipWidgets?: UuidPathConsiderSkipWidgets;
    /**
     * Specifies a {@link Widget} that should be used as parent of the given object instead of `object.parent` when building the uuidPath.
     *
     * By the default `object.parent` is used.
     */
    parent?: Widget;
}
/**
 * An object for which an uuid and/or uuidPath can be computed using {@link ObjectIdProvider}.
 */
export interface ObjectUuidSource extends Partial<ObjectWithUuid>, Partial<ObjectWithType> {
    id?: string;
    classId?: string;
    parent?: Widget;
    uuidParent?: ObjectWithUuid;
}
export interface ObjectIdProviderModel extends ObjectModel<ObjectIdProvider> {
    object?: ObjectUuidSource;
    parent?: Widget;
}
export type UuidPathConsiderSkipWidgets = boolean | 'dynamicTrue' | 'dynamicFalse';
//# sourceMappingURL=ObjectIdProvider.d.ts.map