@phosphor/application

import { CommandRegistry } from '@phosphor/commands'; import { Token } from '@phosphor/coreutils'; import { ContextMenu, Menu, Widget } from '@phosphor/widgets'; /** * A user-defined application plugin. * * #### Notes * Plugins are the foundation for building an extensible application. * * Plugins consume and provide "services", which are nothing more than * concrete implementations of interfaces and/or abstract types. * * Unlike regular imports and exports, which tie the service consumer * to a particular implementation of the service, plugins decouple the * service producer from the service consumer, allowing an application * to be easily customized by third parties in a type-safe fashion. */ export interface IPlugin<T, U> { /** * The human readable id of the plugin. * * #### Notes * This must be unique within an application. */ id: string; /** * Whether the plugin should be activated on application start. * * #### Notes * The default is `false`. */ autoStart?: boolean; /** * The types of required services for the plugin, if any. * * #### Notes * These tokens correspond to the services that are required by * the plugin for correct operation. * * When the plugin is activated, a concrete instance of each type * will be passed to the `activate()` function, in the order they * are specified in the `requires` array. */ requires?: Token<any>[]; /** * The types of optional services for the plugin, if any. * * #### Notes * These tokens correspond to the services that can be used by the * plugin if available, but are not necessarily required. * * The optional services will be passed to the `activate()` function * following all required services. If an optional service cannot be * resolved, `null` will be passed in its place. */ optional?: Token<any>[]; /** * The type of service provided by the plugin, if any. * * #### Notes * This token corresponds to the service exported by the plugin. * * When the plugin is activated, the return value of `activate()` * is used as the concrete instance of the type. */ provides?: Token; /** * A function invoked to activate the plugin. * * @param app - The application which owns the plugin. * * @param args - The services specified by the `requires` property. * * @returns The provided service, or a promise to the service. * * #### Notes * This function will be called whenever the plugin is manually * activated, or when another plugin being activated requires * the service it provides. * * This function will not be called unless all of its required * services can be fulfilled. */ activate: (app: T, ...args: any[]) => U | Promise; } /** * A class for creating pluggable applications. * * #### Notes * The `Application` class is useful when creating large, complex * UI applications with the ability to be safely extended by third * party code via plugins. */ export declare class Application<T extends Widget> { /** * Construct a new application. * * @param options - The options for creating the application. */ constructor(options: Application.IOptions<T>); /** * The application command registry. */ readonly commands: CommandRegistry; /** * The application context menu. */ readonly contextMenu: ContextMenu; /** * The application shell widget. * * #### Notes * The shell widget is the root "container" widget for the entire * application. It will typically expose an API which allows the * application plugins to insert content in a variety of places. */ readonly shell: T; /** * A promise which resolves after the application has started. * * #### Notes * This promise will resolve after the `start()` method is called, * when all the bootstrapping and shell mounting work is complete. */ readonly started: Promise<void>; /** * Test whether a plugin is registered with the application. * * @param id - The id of the plugin of interest. * * @returns `true` if the plugin is registered, `false` otherwise. */ hasPlugin(id: string): boolean; /** * List the IDs of the plugins registered with the application. * * @returns A new array of the registered plugin IDs. */ listPlugins(): string[]; /** * Register a plugin with the application. * * @param plugin - The plugin to register. * * #### Notes * An error will be thrown if a plugin with the same id is already * registered, or if the plugin has a circular dependency. * * If the plugin provides a service which has already been provided * by another plugin, the new service will override the old service. */ registerPlugin(plugin: IPlugin<this, any>): void; /** * Register multiple plugins with the application. * * @param plugins - The plugins to register. * * #### Notes * This calls `registerPlugin()` for each of the given plugins. */ registerPlugins(plugins: IPlugin<this, any>[]): void; /** * Activate the plugin with the given id. * * @param id - The ID of the plugin of interest. * * @returns A promise which resolves when the plugin is activated * or rejects with an error if it cannot be activated. */ activatePlugin(id: string): Promise<void>; /** * Resolve a required service of a given type. * * @param token - The token for the service type of interest. * * @returns A promise which resolves to an instance of the requested * service, or rejects with an error if it cannot be resolved. * * #### Notes * Services are singletons. The same instance will be returned each * time a given service token is resolved. * * If the plugin which provides the service has not been activated, * resolving the service will automatically activate the plugin. * * User code will not typically call this method directly. Instead, * the required services for the user's plugins will be resolved * automatically when the plugin is activated. */ resolveRequiredService(token: Token): Promise; /** * Resolve an optional service of a given type. * * @param token - The token for the service type of interest. * * @returns A promise which resolves to an instance of the requested * service, or `null` if it cannot be resolved. * * #### Notes * Services are singletons. The same instance will be returned each * time a given service token is resolved. * * If the plugin which provides the service has not been activated, * resolving the service will automatically activate the plugin. * * User code will not typically call this method directly. Instead, * the optional services for the user's plugins will be resolved * automatically when the plugin is activated. */ resolveOptionalService(token: Token): Promise; /** * Start the application. * * @param options - The options for starting the application. * * @returns A promise which resolves when all bootstrapping work * is complete and the shell is mounted to the DOM. * * #### Notes * This should be called once by the application creator after all * initial plugins have been registered. * * If a plugin fails to the load, the error will be logged and the * other valid plugins will continue to be loaded. * * Bootstrapping the application consists of the following steps: * 1. Activate the startup plugins * 2. Wait for those plugins to activate * 3. Attach the shell widget to the DOM * 4. Add the application event listeners */ start(options?: Application.IStartOptions): Promise<void>; /** * Handle the DOM events for the application. * * @param event - The DOM event sent to the application. * * #### Notes * This method implements the DOM `EventListener` interface and is * called in response to events registered for the application. It * should not be called directly by user code. */ handleEvent(event: Event): void; /** * Attach the application shell to the DOM. * * @param id - The id of the host node for the shell, or `''`. * * #### Notes * If the id is not provided, the document body will be the host. * * A subclass may reimplement this method as needed. */ protected attachShell(id: string): void; /** * Add the application event listeners. * * #### Notes * The default implementation of this method adds listeners for * `'keydown'` and `'resize'` events. * * A subclass may reimplement this method as needed. */ protected addEventListeners(): void; /** * A method invoked on a document `'keydown'` event. * * #### Notes * The default implementation of this method invokes the key down * processing method of the application command registry. * * A subclass may reimplement this method as needed. */ protected evtKeydown(event: KeyboardEvent): void; /** * A method invoked on a document `'contextmenu'` event. * * #### Notes * The default implementation of this method opens the application * `contextMenu` at the current mouse position. * * If the application context menu has no matching content *or* if * the shift key is pressed, the default browser context menu will * be opened instead. * * A subclass may reimplement this method as needed. */ protected evtContextMenu(event: MouseEvent): void; /** * A method invoked on a window `'resize'` event. * * #### Notes * The default implementation of this method updates the shell. * * A subclass may reimplement this method as needed. */ protected evtResize(event: Event): void; private _started; private _pluginMap; private _serviceMap; private _delegate; } /** * The namespace for the `Application` class statics. */ export declare namespace Application { /** * An options object for creating an application. */ interface IOptions<T extends Widget> { /** * The shell widget to use for the application. * * This should be a newly created and initialized widget. * * The application will attach the widget to the DOM. */ shell: T; /** * A custom renderer for the context menu. */ contextMenuRenderer?: Menu.IRenderer; } /** * An options object for application startup. */ interface IStartOptions { /** * The ID of the DOM node to host the application shell. * * #### Notes * If this is not provided, the document body will be the host. */ hostID?: string; /** * The plugins to activate on startup. * * #### Notes * These will be *in addition* to any `autoStart` plugins. */ startPlugins?: string[]; /** * The plugins to **not** activate on startup. * * #### Notes * This will override `startPlugins` and any `autoStart` plugins. */ ignorePlugins?: string[]; } }