@eclipse-scout/core/dist/d.ts/src/prefs/UiPreferences.d.ts

Eclipse Scout runtime

/// <reference types="jquery" />
import { ObjectWithType, UiPreferencesDo, UiPreferencesStore, UiPreferencesUpdateDo } from '../index';
/**
 * A singleton that loads and stores all UI preferences for the current user. It is populated during the start of the
 * application, so the preferences data can be accessed synchronously. After the data is loaded, it is passed to
 * all registered {@link UiPreferencesHandler}s to handle component-specific parts the preferences data.
 */
export declare class UiPreferences implements ObjectWithType {
    /**
     * Registers a new handler to receive and provide parts of the global {@link UiPreferencesDo} object. Any value can
     * be used as the ID, as long it is the same that is later used to call {@link UiPreferences.scheduleStore}.
     *
     * If the given arguments are missing or if there is already a handler registered for the same ID, an error is thrown.
     */
    static registerHandler(handlerId: UiPreferencesHandlerId, handler: UiPreferencesHandler): void;
    /**
     * Unregisters the previously registered {@link UiPreferencesHandler}. Normally, this only has to be done to replace
     * and registered handlers with a different instance for the same ID.
     */
    static unregisterHandler(handlerId: UiPreferencesHandlerId): boolean;
    /**
     * Returns all registered {@link UiPreferencesHandler}s.
     */
    static getHandlers(): UiPreferencesHandler[];
    /**
     * Returns the {@link UiPreferencesHandler} for the given ID, or `null` if not such handler was registered.
     */
    static getHandler(handlerId: UiPreferencesHandlerId): UiPreferencesHandler;
    objectType: string;
    protected _store: UiPreferencesStore;
    protected _storeTimeoutId: number;
    protected _modifiedHandlers: Set<UiPreferencesHandler>;
    /** Loaded preferences data (never `null`) */
    protected _preferences: UiPreferencesDo;
    constructor();
    protected _initStore(): void;
    /**
     * Replaces the {@link UiPreferencesStore} for this singleton object. This is intended to be used in tests only.
     * In a normal application, the store should not be changed dynamically. Instead, register the desired store
     * implementation via {@link ObjectFactory}.
     *
     * **Important:** This method clears internal data structures, but does *not* automatically reload preferences
     * from the new store. To do so, {@link load} has to be called manually.
     *
     * @returns the old store
     */
    replaceStore(store: UiPreferencesStore): UiPreferencesStore;
    bootstrap(): JQuery.Promise<void>;
    /**
     * Loads preferences from the {@link UiPreferencesStore} into this singleton object.
     */
    load(): JQuery.Promise<void>;
    /**
     * Writes the current state of this singleton object to the {@link UiPreferencesStore}.
     */
    store(): JQuery.Promise<void>;
    /**
     * Schedules a task to call {@link store}. This method is to be called whenever a preference has been changed.
     * By scheduling a task rather than storing immediately, we can coalesce multiple store requests into a single one.
     *
     * The given argument specifies which {@link UiPreferencesHandler} has been modified. Before the data is actually
     * stored, all modified handlers will be called back to update the global {@link UiPreferencesDo} object. If this
     * method is called without argument, _all_ registered handlers are marked as modified.
     */
    scheduleStore(modifiedHandlerId?: UiPreferencesHandlerId): void;
    /**
     * Marks the given handler as modified, i.e. the handler's export method will be called before the preferences
     * data is stored. If no handler is specified, _all_ handlers are marked as modified.
     */
    protected _markHandlerAsModified(handlerId?: UiPreferencesHandlerId): void;
    /**
     * Processes the list of modified handlers, i.e. calls each handler's export method. After that, the list is reset.
     */
    protected _processModifiedHandlers(): void;
    protected _subscribeForUpdates(): JQuery.Promise<void>;
    protected _onPreferencesUpdate(update: UiPreferencesUpdateDo): void;
    protected _initPreferences(preferences: UiPreferencesDo): void;
}
export declare const uiPreferences: UiPreferences;
/**
 * An ID that identifiers a registered {@link UiPreferencesHandler}. Any value is allowed, as long as it is unique
 * (no two handlers can share the same ID) and the same value is used when calling {@link UiPreferences.scheduleStore}.
 */
export type UiPreferencesHandlerId = any;
/**
 * A small object that can extract and update parts of the global {@link UiPreferencesDo} object.
 */
export interface UiPreferencesHandler {
    /**
     * Extracts component-specific parts of the global {@link UiPreferencesDo} object into internal data structures.
     */
    importPreferences: (preferences: UiPreferencesDo) => void;
    /**
     * Updates the component-specific parts of the given {@link UiPreferencesDo} object from the internal data structures.
     */
    exportPreferences: (preferences: UiPreferencesDo) => void;
}
//# sourceMappingURL=UiPreferences.d.ts.map