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

Eclipse Scout runtime

import { Column, Event, ITableCustomizerDo, IUserFilterStateDo, ObjectWithType, PropertyChangeEvent, Table, TableClientUiPreferenceProfileDo, TableClientUiPreferencesDo, TableColumnClientUiPreferenceDo } from '../index';
/**
 * A singleton that represents all {@link Table}-specific UI preferences of the current user. It is populated during the start of the
 * application, so the preferences can be accessed synchronously.
 */
export declare class TableUiPreferences implements ObjectWithType {
    /**
     * Key for the current global preferences of a table, i.e. preferences that are not stored in a specific settings profile.
     */
    static readonly PROFILE_ID_GLOBAL: string;
    /**
     * Special key used to store table settings of a bookmarked table page. The bookmark support will consider this state as
     * the "factory settings" when the page is displayed in the bookmark outline.
     */
    static readonly PROFILE_ID_BOOKMARK: string;
    objectType: string;
    /** Map of all table preferences, indexed by table identifier (see {@link _computeTablePreferencesKey}). */
    protected _tablePreferencesMap: Map<string, TableClientUiPreferencesDo>;
    /** If > 0, table events are ignored. Useful when applying preferences. */
    protected _ignoreTableEventsCounter: number;
    protected _columResizeTimeoutId: number;
    protected _tableColumnListener: (event: Event<Table>) => void;
    protected _tableTileModeListener: (event: PropertyChangeEvent<boolean, Table>) => void;
    /**
     * Imports the given data into the internal structures, so individual table preferences can be read and
     * modified by the various methods on this class. Any existing data is replaced.
     *
     * @internal should only be called from the registered {@link UiPreferencesHandler}!
     */
    _importTablePreferences(tablePreferences: TableClientUiPreferencesDo[]): void;
    /**
     * Exports the current state of the internal data structures as persistable table preferences.
     *
     * @internal should only be called from the registered {@link UiPreferencesHandler}!
     */
    _exportTablePreferences(): TableClientUiPreferencesDo[];
    /**
     * Returns the preferences for the given table. If no preferences are registered yet, a new empty
     * preferences data object is created and stored.
     */
    protected _getOrCreateTablePreferences(table: Table): TableClientUiPreferencesDo;
    protected _computeTablePreferencesKey(tableId: string, userPreferenceContext: string): string;
    protected _scheduleStore(): void;
    /**
     * Installs or uninstalls UI preference support for the given table according to its {@link Table#uiPreferencesEnabled} flag.
     */
    updateUiPreferencesEnabled(table: Table): void;
    /**
     * Installs a table listener for all preference-related changes and stores them in the {@link TableUiPreferences#PROFILE_ID_GLOBAL} profile for that table.
     */
    protected _installTableListener(table: Table): void;
    /**
     * Uninstalls the listener installed by {@link _installTableListener}.
     */
    protected _uninstallTableListener(table: Table): void;
    /**
     * Executes the specified runnable immediately. During its execution, all table events are ignored by this
     * {@link TableUiPreferences} instance. The events themselves are not suppressed, i.e. other listeners are
     * still triggered. Useful for making table adjustments that should _not_ be stored in the global profile.
     */
    withIgnoreTableEvents(runnable: () => void): void;
    protected get _ignoreTableEvents(): boolean;
    protected set _ignoreTableEvents(applyingTablePreferences: boolean);
    protected _onTableColumnEvent(event: Event<Table>): void;
    protected _onTableTileModeChange(event: PropertyChangeEvent<boolean, Table>): void;
    /**
     * Returns the preferences for the given table, or `null` if no preferences are registered yet.
     */
    get(table: Table): TableClientUiPreferencesDo;
    /**
     * Returns the profile with the given id from the given table preferences. If no such profile exists, `undefined` is returned.
     */
    getProfile(prefs: TableClientUiPreferencesDo, profileId: string): TableClientUiPreferenceProfileDo;
    /**
     * Creates a new data object consisting of all profile-independent preferences for the given table, according to its current state.
     *
     * Note: the `tablePreferences` map is *not* set automatically.
     */
    create(table: Table): TableClientUiPreferencesDo;
    /**
     * Creates a new data object consisting of all profile-dependent preferences for the given table, according to its current state.
     */
    createProfile(table: Table, options?: CreateTablePreferenceProfileOptions): TableClientUiPreferenceProfileDo;
    /**
     * Creates a list of new data objects consisting of the preferences for each column of the given table, according to their current state.
     * The result is never `null`. Invisible columns are included, while `guiOnly` and `displayable=false` columns are ignored. Non-displayable
     * columns can be included explicitly by setting the corresponding option.
     */
    createColumnPreferences(table: Table, includeNonDisplayableColumns?: boolean): TableColumnClientUiPreferenceDo[];
    /**
     * Creates a list of new data objects consisting of the state of each {@link TableUserFilter} of the given table.
     * The result is never `null`. Only user filters with a registered {@link UserFilterStateMapper} are returned.
     */
    createUserFilterStates(table: Table): IUserFilterStateDo[];
    /**
     * If the table is customizable, returns the customizer data. Otherwise, `null` is returned.
     */
    createCustomizerData(table: Table): ITableCustomizerDo;
    /**
     * Stores the given profile under the given profileId in the table preferences of the given table.
     */
    storeProfile(table: Table, profileId: string, profile: TableClientUiPreferenceProfileDo): void;
    /**
     * Renames a table preference profile and stores it.
     */
    renameProfile(table: Table, oldProfileId: string, newProfileId: string): void;
    /**
     * Removes the specified profile from the table preferences and stores it.
     */
    removeProfile(table: Table, profileId: string): void;
    /**
     * Updates and stores the profile-independent table preferences to match the current state of the table.
     */
    store(table: Table): void;
    protected _storeTableTileMode(table: Table, prefs: TableClientUiPreferencesDo): boolean;
    /**
     * Stores the current profile-dependent preferences of the given table in the {@link TableUiPreferences#PROFILE_ID_GLOBAL} profile.
     */
    storeGlobalProfile(table: Table): void;
    /**
     * Removes the {@link TableUiPreferences#PROFILE_ID_GLOBAL} profile for the given table.
     */
    clearGlobalProfile(table: Table): void;
    /**
     * Applies the given preferences to the given table, i.e. changes the table state to match the preferences. If a `profileId` is given
     * and the table preferences contain a profile with that id, it is applied as well. Otherwise, only profile-independent preferences
     * are applied.
     */
    apply(table: Table, prefs: TableClientUiPreferencesDo, profileId?: string, options?: ApplyTablePreferencesOptions): void;
    /**
     * Applies the given preference profile to the given table, i.e. changes the table state to match the profile.
     */
    applyProfile(table: Table, profile: TableClientUiPreferenceProfileDo, options?: ApplyTablePreferencesOptions): void;
    protected _applyTablePreferencesInternal(table: Table, prefs: TableClientUiPreferencesDo, options?: ApplyTablePreferencesOptions): void;
    protected _applyTablePreferenceProfileInternal(table: Table, profile: TableClientUiPreferenceProfileDo, options?: ApplyTablePreferencesOptions): void;
    protected _applyCustomizerData(table: Table, customizerData: ITableCustomizerDo, options?: ApplyTablePreferencesOptions): void;
    protected _applyColumnPreferences(table: Table, columnPreferences: TableColumnClientUiPreferenceDo[], options?: ApplyTablePreferencesOptions): void;
    protected _applyColumnPreferencesToColumn(column: Column<any>, columnPreferences: TableColumnClientUiPreferenceDo): void;
    protected _applyUserFilterStates(table: Table, userFilterStates: IUserFilterStateDo[], options?: ApplyTablePreferencesOptions): void;
    isColumnPreferencesColumn<TValue>(column: Column<TValue> & Partial<Omit<ColumnPreferencesColumn<TValue>, keyof Column<TValue>>>): column is ColumnPreferencesColumn<TValue>;
}
export interface CreateTablePreferenceProfileOptions {
    /**
     * Specifies whether to include the state of user filters ({@link IUserFilterStateDo}) in the preference profile.
     *
     * Default is false.
     */
    includeUserFilters?: boolean;
    /**
     * Specifies whether information about columns with `displayable=false` should be included in the profile. Useful to save the
     * initial state of a table. Not intended to be set when creating a profile that is to be persisted.
     *
     * Default is false.
     */
    includeNonDisplayableColumns?: boolean;
}
export interface ApplyTablePreferencesOptions {
    /**
     * Specifies whether to apply customizer data from the preference profile to the table.
     *
     * Default is true.
     */
    applyCustomizerData?: boolean;
    /**
     * Specifies whether to apply user filter states from the preference profile to the table.
     *
     * Default is false.
     */
    applyUserFilters?: boolean;
    /**
     * Specifies whether information about columns with `displayable=false` should be applied. Useful to restore the initial state
     * of a table that was previously saved with {@link CreateTablePreferenceProfileOptions#includeNonDisplayableColumns}.
     *
     * Default is false.
     */
    applyNonDisplayableColumns?: boolean;
}
export declare const tableUiPreferences: TableUiPreferences;
/**
 * Interface for {@link Column}s containing a getter and a setter for {@link TableColumnClientUiPreferenceDo}.
 * When preferences are applied to such a {@link Column} the whole {@link TableColumnClientUiPreferenceDo} is passed to the setter.
 * Later on these preferences are used as a fallback for preference values that can only be extracted from
 * specific column types (e.g. {@link NumberColumn#aggregationFunction} or {@link NumberColumn#backgroundEffect}) when the preferences are stored.
 *
 * With this one can e.g. implement placeholder columns that cache the preferences while the real columns are created asynchronously.
 */
export interface ColumnPreferencesColumn<TValue = any> extends Column<TValue> {
    getColumnPreferences: () => TableColumnClientUiPreferenceDo;
    setColumnPreferences: (columnPreferences: TableColumnClientUiPreferenceDo) => void;
}
//# sourceMappingURL=TableUiPreferences.d.ts.map