@theia/core/lib/browser/widget-manager.d.ts

import { Widget } from '@phosphor/widgets';
import { ILogger, Emitter, Event, ContributionProvider, MaybePromise, WaitUntilEvent } from '../common';
export declare const WidgetFactory: unique symbol;
/**
 * A {@link WidgetFactory} is used to create new widgets. Factory-specific information (options) can be passed as serializable JSON data.
 * The common {@link WidgetManager} collects  `WidgetFactory` contributions and delegates to the corresponding factory when
 * a widget should be created or restored. To identify widgets the `WidgetManager` uses a description composed of the factory id and the options.
 * The `WidgetFactory` does support both, synchronous and asynchronous widget creation.
 *
 * ### Example usage
 *
 * ```typescript
 * export class MyWidget extends BaseWidget {
 * }
 *
 * @injectable()
 * export class MyWidgetFactory implements WidgetFactory {
 *     id = 'myWidgetFactory';
 *
 *     createWidget(): MaybePromise<Widget> {
 *         return new MyWidget();
 *    }
 * }
 * ```
 */
export interface WidgetFactory {
    /**
     * The factory id.
     */
    readonly id: string;
    /**
     * Creates a widget using the given options.
     * @param options factory specific information as serializable JSON data.
     *
     * @returns the newly created widget or a promise of the widget
     */
    createWidget(options?: any): MaybePromise<Widget>;
}
/**
 * Representation of the `WidgetConstructionOptions`.
 * Defines a serializable description to create widgets.
 */
export interface WidgetConstructionOptions {
    /**
     * The id of the widget factory to use.
     */
    factoryId: string;
    /**
     * The widget factory specific information.
     */
    options?: any;
}
/**
 * Representation of a `willCreateWidgetEvent`.
 */
export interface WillCreateWidgetEvent extends WaitUntilEvent {
    /**
     * The widget which will be created.
     */
    readonly widget: Widget;
    /**
     * The widget factory id.
     */
    readonly factoryId: string;
}
/**
 * Representation of a `didCreateWidgetEvent`.
 */
export interface DidCreateWidgetEvent {
    /**
     * The widget which was created.
     */
    readonly widget: Widget;
    /**
     * The widget factory id.
     */
    readonly factoryId: string;
}
/**
 * The {@link WidgetManager} is the common component responsible for creating and managing widgets. Additional widget factories
 * can be registered by using the {@link WidgetFactory} contribution point. To identify a widget, created by a factory, the factory id and
 * the creation options are used. This key is commonly referred to as `description` of the widget.
 */
export declare class WidgetManager {
    protected _cachedFactories: Map<string, WidgetFactory>;
    protected readonly widgets: Map<string, Widget>;
    protected readonly pendingWidgetPromises: Map<string, MaybePromise<Widget>>;
    protected readonly factoryProvider: ContributionProvider<WidgetFactory>;
    protected readonly logger: ILogger;
    protected readonly onWillCreateWidgetEmitter: Emitter<WillCreateWidgetEvent>;
    /**
     * An event can be used to participate in the widget creation.
     * Listeners may not dispose the given widget.
     */
    readonly onWillCreateWidget: Event<WillCreateWidgetEvent>;
    protected readonly onDidCreateWidgetEmitter: Emitter<DidCreateWidgetEvent>;
    readonly onDidCreateWidget: Event<DidCreateWidgetEvent>;
    /**
     * Get the list of widgets created by the given widget factory.
     * @param factoryId the widget factory id.
     *
     * @returns the list of widgets created by the factory with the given id.
     */
    getWidgets(factoryId: string): Widget[];
    /**
     * Try to get the existing widget for the given description.
     * @param factoryId The widget factory id.
     * @param options The widget factory specific information.
     *
     * @returns the widget if available, else `undefined`.
     *
     * The widget is 'available' if it has been created with the same {@link factoryId} and {@link options} by the {@link WidgetManager}.
     * If the widget's creation is asynchronous, it is only available when the associated `Promise` is resolved.
     */
    tryGetWidget<T extends Widget>(factoryId: string, options?: any): T | undefined;
    /**
     * Try to get the existing widget for the given description.
     * @param factoryId The widget factory id.
     * @param options The widget factory specific information.
     *
     * @returns A promise that resolves to the widget, if any exists. The promise may be pending, so be cautious when assuming that it will not reject.
     */
    tryGetPendingWidget<T extends Widget>(factoryId: string, options?: any): MaybePromise<T> | undefined;
    /**
     * Get the widget for the given description.
     * @param factoryId The widget factory id.
     * @param options The widget factory specific information.
     *
     * @returns a promise resolving to the widget if available, else `undefined`.
     */
    getWidget<T extends Widget>(factoryId: string, options?: any): Promise<T | undefined>;
    /**
     * Finds a widget that matches the given test predicate.
     * @param factoryId The widget factory id.
     * @param predicate The test predicate.
     *
     * @returns a promise resolving to the widget if available, else `undefined`.
     */
    findWidget<T extends Widget>(factoryId: string, predicate: (options?: any) => boolean): Promise<T | undefined>;
    protected testPredicate(key: string, factoryId: string, predicate: (options?: any) => boolean): boolean;
    protected doGetWidget<T extends Widget>(key: string): MaybePromise<T> | undefined;
    /**
     * Creates a new widget or returns the existing widget for the given description.
     * @param factoryId the widget factory id.
     * @param options the widget factory specific information.
     *
     * @returns a promise resolving to the widget.
     */
    getOrCreateWidget<T extends Widget>(factoryId: string, options?: any): Promise<T>;
    /**
     * Get the widget construction options.
     * @param widget the widget.
     *
     * @returns the widget construction options if the widget was created through the manager, else `undefined`.
     */
    getDescription(widget: Widget): WidgetConstructionOptions | undefined;
    /**
     * Convert the widget construction options to string.
     * @param options the widget construction options.
     *
     * @returns the widget construction options represented as a string.
     */
    protected toKey(options: WidgetConstructionOptions): string;
    /**
     * Convert the key into the widget construction options object.
     * @param key the key.
     *
     * @returns the widget construction options object.
     */
    protected fromKey(key: string): WidgetConstructionOptions;
    protected get factories(): Map<string, WidgetFactory>;
}
//# sourceMappingURL=widget-manager.d.ts.map