@phosphor/commands
Version:
PhosphorJS - Commands
692 lines (691 loc) • 23.9 kB
TypeScript
import { ReadonlyJSONObject } from '@phosphor/coreutils';
import { IDisposable } from '@phosphor/disposable';
import { ISignal } from '@phosphor/signaling';
/**
* An object which manages a collection of commands.
*
* #### Notes
* A command registry can be used to populate a variety of action-based
* widgets, such as command palettes, menus, and toolbars.
*/
export declare class CommandRegistry {
/**
* Construct a new command registry.
*/
constructor();
/**
* A signal emitted when a command has changed.
*
* #### Notes
* This signal is useful for visual representations of commands which
* need to refresh when the state of a relevant command has changed.
*/
readonly commandChanged: ISignal<this, CommandRegistry.ICommandChangedArgs>;
/**
* A signal emitted when a command has executed.
*
* #### Notes
* Care should be taken when consuming this signal. It is intended to
* be used largely for debugging and logging purposes. It should not
* be (ab)used for general purpose spying on command execution.
*/
readonly commandExecuted: ISignal<this, CommandRegistry.ICommandExecutedArgs>;
/**
* A signal emitted when a key binding is changed.
*/
readonly keyBindingChanged: ISignal<this, CommandRegistry.IKeyBindingChangedArgs>;
/**
* A read-only array of the key bindings in the registry.
*/
readonly keyBindings: ReadonlyArray<CommandRegistry.IKeyBinding>;
/**
* List the ids of the registered commands.
*
* @returns A new array of the registered command ids.
*/
listCommands(): string[];
/**
* Test whether a specific command is registered.
*
* @param id - The id of the command of interest.
*
* @returns `true` if the command is registered, `false` otherwise.
*/
hasCommand(id: string): boolean;
/**
* Add a command to the registry.
*
* @param id - The unique id of the command.
*
* @param options - The options for the command.
*
* @returns A disposable which will remove the command.
*
* @throws An error if the given `id` is already registered.
*/
addCommand(id: string, options: CommandRegistry.ICommandOptions): IDisposable;
/**
* Notify listeners that the state of a command has changed.
*
* @param id - The id of the command which has changed. If more than
* one command has changed, this argument should be omitted.
*
* @throws An error if the given `id` is not registered.
*
* #### Notes
* This method should be called by the command author whenever the
* application state changes such that the results of the command
* metadata functions may have changed.
*
* This will cause the `commandChanged` signal to be emitted.
*/
notifyCommandChanged(id?: string): void;
/**
* Get the display label for a specific command.
*
* @param id - The id of the command of interest.
*
* @param args - The arguments for the command.
*
* @returns The display label for the command, or an empty string
* if the command is not registered.
*/
label(id: string, args?: ReadonlyJSONObject): string;
/**
* Get the mnemonic index for a specific command.
*
* @param id - The id of the command of interest.
*
* @param args - The arguments for the command.
*
* @returns The mnemonic index for the command, or `-1` if the
* command is not registered.
*/
mnemonic(id: string, args?: ReadonlyJSONObject): number;
/**
* @deprecated Use `iconClass()` instead.
*/
icon(id: string, args?: ReadonlyJSONObject): string;
/**
* Get the icon class for a specific command.
*
* @param id - The id of the command of interest.
*
* @param args - The arguments for the command.
*
* @returns The icon class for the command, or an empty string if
* the command is not registered.
*/
iconClass(id: string, args?: ReadonlyJSONObject): string;
/**
* Get the icon label for a specific command.
*
* @param id - The id of the command of interest.
*
* @param args - The arguments for the command.
*
* @returns The icon label for the command, or an empty string if
* the command is not registered.
*/
iconLabel(id: string, args?: ReadonlyJSONObject): string;
/**
* Get the short form caption for a specific command.
*
* @param id - The id of the command of interest.
*
* @param args - The arguments for the command.
*
* @returns The caption for the command, or an empty string if the
* command is not registered.
*/
caption(id: string, args?: ReadonlyJSONObject): string;
/**
* Get the usage help text for a specific command.
*
* @param id - The id of the command of interest.
*
* @param args - The arguments for the command.
*
* @returns The usage text for the command, or an empty string if
* the command is not registered.
*/
usage(id: string, args?: ReadonlyJSONObject): string;
/**
* Get the extra class name for a specific command.
*
* @param id - The id of the command of interest.
*
* @param args - The arguments for the command.
*
* @returns The class name for the command, or an empty string if
* the command is not registered.
*/
className(id: string, args?: ReadonlyJSONObject): string;
/**
* Get the dataset for a specific command.
*
* @param id - The id of the command of interest.
*
* @param args - The arguments for the command.
*
* @returns The dataset for the command, or an empty dataset if
* the command is not registered.
*/
dataset(id: string, args?: ReadonlyJSONObject): CommandRegistry.Dataset;
/**
* Test whether a specific command is enabled.
*
* @param id - The id of the command of interest.
*
* @param args - The arguments for the command.
*
* @returns A boolean indicating whether the command is enabled,
* or `false` if the command is not registered.
*/
isEnabled(id: string, args?: ReadonlyJSONObject): boolean;
/**
* Test whether a specific command is toggled.
*
* @param id - The id of the command of interest.
*
* @param args - The arguments for the command.
*
* @returns A boolean indicating whether the command is toggled,
* or `false` if the command is not registered.
*/
isToggled(id: string, args?: ReadonlyJSONObject): boolean;
/**
* Test whether a specific command is visible.
*
* @param id - The id of the command of interest.
*
* @param args - The arguments for the command.
*
* @returns A boolean indicating whether the command is visible,
* or `false` if the command is not registered.
*/
isVisible(id: string, args?: ReadonlyJSONObject): boolean;
/**
* Execute a specific command.
*
* @param id - The id of the command of interest.
*
* @param args - The arguments for the command.
*
* @returns A promise which resolves with the result of the command.
*
* #### Notes
* The promise will reject if the command throws an exception,
* or if the command is not registered.
*/
execute(id: string, args?: ReadonlyJSONObject): Promise<any>;
/**
* Add a key binding to the registry.
*
* @param options - The options for creating the key binding.
*
* @returns A disposable which removes the added key binding.
*
* #### Notes
* If multiple key bindings are registered for the same sequence, the
* binding with the highest selector specificity is executed first. A
* tie is broken by using the most recently added key binding.
*
* Ambiguous key bindings are resolved with a timeout. As an example,
* suppose two key bindings are registered: one with the key sequence
* `['Ctrl D']`, and another with `['Ctrl D', 'Ctrl W']`. If the user
* presses `Ctrl D`, the first binding cannot be immediately executed
* since the user may intend to complete the chord with `Ctrl W`. For
* such cases, a timer is used to allow the chord to be completed. If
* the chord is not completed before the timeout, the first binding
* is executed.
*/
addKeyBinding(options: CommandRegistry.IKeyBindingOptions): IDisposable;
/**
* Process a `'keydown'` event and invoke a matching key binding.
*
* @param event - The event object for a `'keydown'` event.
*
* #### Notes
* This should be called in response to a `'keydown'` event in order
* to invoke the command for the best matching key binding.
*
* The registry **does not** install its own listener for `'keydown'`
* events. This allows the application full control over the nodes
* and phase for which the registry processes `'keydown'` events.
*/
processKeydownEvent(event: KeyboardEvent): void;
/**
* Start or restart the pending timeout.
*/
private _startTimer;
/**
* Clear the pending timeout.
*/
private _clearTimer;
/**
* Replay the keydown events which were suppressed.
*/
private _replayKeydownEvents;
/**
* Execute the command for the given key binding.
*
* If the command is missing or disabled, a warning will be logged.
*/
private _executeKeyBinding;
/**
* Clear the internal pending state.
*/
private _clearPendingState;
/**
* Handle the partial match timeout.
*/
private _onPendingTimeout;
private _timerID;
private _replaying;
private _keystrokes;
private _keydownEvents;
private _keyBindings;
private _exactKeyMatch;
private _commands;
private _commandChanged;
private _commandExecuted;
private _keyBindingChanged;
}
/**
* The namespace for the `CommandRegistry` class statics.
*/
export declare namespace CommandRegistry {
/**
* A type alias for a user-defined command function.
*/
type CommandFunc<T> = (args: ReadonlyJSONObject) => T;
/**
* A type alias for a simple immutable string dataset.
*/
type Dataset = {
readonly [key: string]: string;
};
/**
* An options object for creating a command.
*
* #### Notes
* A command is an abstract representation of code to be executed along
* with metadata for describing how the command should be displayed in
* a visual representation.
*
* A command is a collection of functions, *not* methods. The command
* registry will always invoke the command functions with a `thisArg`
* which is `undefined`.
*/
interface ICommandOptions {
/**
* The function to invoke when the command is executed.
*
* #### Notes
* This should return the result of the command (if applicable) or
* a promise which yields the result. The result is resolved as a
* promise and that promise is returned to the code which executed
* the command.
*
* This may be invoked even when `isEnabled` returns `false`.
*/
execute: CommandFunc<any | Promise<any>>;
/**
* The label for the command.
*
* #### Notes
* This can be a string literal, or a function which returns the
* label based on the provided command arguments.
*
* The label is often used as the primary text for the command.
*
* The default value is an empty string.
*/
label?: string | CommandFunc<string>;
/**
* The index of the mnemonic character in the command's label.
*
* #### Notes
* This can be an index literal, or a function which returns the
* mnemonic index based on the provided command arguments.
*
* The mnemonic character is often used by menus to provide easy
* single-key keyboard access for triggering a menu item. It is
* typically rendered as an underlined character in the label.
*
* The default value is `-1`.
*/
mnemonic?: number | CommandFunc<number>;
/**
* @deprecated Use `iconClass` instead.
*/
icon?: string | CommandFunc<string>;
/**
* The icon class for the command.
*
* #### Notes
* This class name will be added to the icon node for the visual
* representation of the command.
*
* Multiple class names can be separated with white space.
*
* This can be a string literal, or a function which returns the
* icon based on the provided command arguments.
*
* The default value is an empty string.
*/
iconClass?: string | CommandFunc<string>;
/**
* The icon label for the command.
*
* #### Notes
* This label will be added as text to the icon node for the visual
* representation of the command.
*
* This can be a string literal, or a function which returns the
* label based on the provided command arguments.
*
* The default value is an empty string.
*/
iconLabel?: string | CommandFunc<string>;
/**
* The caption for the command.
*
* #### Notes
* This should be a simple one line description of the command. It
* is used by some visual representations to show quick info about
* the command.
*
* This can be a string literal, or a function which returns the
* caption based on the provided command arguments.
*
* The default value is an empty string.
*/
caption?: string | CommandFunc<string>;
/**
* The usage text for the command.
*
* #### Notes
* This should be a full description of the command, which includes
* information about the structure of the arguments and the type of
* the return value. It is used by some visual representations when
* displaying complete help info about the command.
*
* This can be a string literal, or a function which returns the
* usage text based on the provided command arguments.
*
* The default value is an empty string.
*/
usage?: string | CommandFunc<string>;
/**
* The general class name for the command.
*
* #### Notes
* This class name will be added to the primary node for the visual
* representation of the command.
*
* Multiple class names can be separated with white space.
*
* This can be a string literal, or a function which returns the
* class name based on the provided command arguments.
*
* The default value is an empty string.
*/
className?: string | CommandFunc<string>;
/**
* The dataset for the command.
*
* #### Notes
* The dataset values will be added to the primary node for the
* visual representation of the command.
*
* This can be a dataset object, or a function which returns the
* dataset object based on the provided command arguments.
*
* The default value is an empty dataset.
*/
dataset?: Dataset | CommandFunc<Dataset>;
/**
* A function which indicates whether the command is enabled.
*
* #### Notes
* Visual representations may use this value to display a disabled
* command as grayed-out or in some other non-interactive fashion.
*
* The default value is `() => true`.
*/
isEnabled?: CommandFunc<boolean>;
/**
* A function which indicates whether the command is toggled.
*
* #### Notes
* Visual representations may use this value to display a toggled
* command in a different form, such as a check mark icon for a
* menu item or a depressed state for a toggle button.
*
* The default value is `() => false`.
*/
isToggled?: CommandFunc<boolean>;
/**
* A function which indicates whether the command is visible.
*
* #### Notes
* Visual representations may use this value to hide or otherwise
* not display a non-visible command.
*
* The default value is `() => true`.
*/
isVisible?: CommandFunc<boolean>;
}
/**
* An arguments object for the `commandChanged` signal.
*/
interface ICommandChangedArgs {
/**
* The id of the associated command.
*
* This will be `undefined` when the type is `'many-changed'`.
*/
readonly id: string | undefined;
/**
* Whether the command was added, removed, or changed.
*/
readonly type: 'added' | 'removed' | 'changed' | 'many-changed';
}
/**
* An arguments object for the `commandExecuted` signal.
*/
interface ICommandExecutedArgs {
/**
* The id of the associated command.
*/
readonly id: string;
/**
* The arguments object passed to the command.
*/
readonly args: ReadonlyJSONObject;
/**
* The promise which resolves with the result of the command.
*/
readonly result: Promise<any>;
}
/**
* An options object for creating a key binding.
*/
interface IKeyBindingOptions {
/**
* The default key sequence for the key binding.
*
* A key sequence is composed of one or more keystrokes, where each
* keystroke is a combination of modifiers and a primary key.
*
* Most key sequences will contain a single keystroke. Key sequences
* with multiple keystrokes are called "chords", and are useful for
* implementing modal input (ala Vim).
*
* Each keystroke in the sequence should be of the form:
* `[<modifier 1> [<modifier 2> [<modifier N> ]]]<primary key>`
*
* The supported modifiers are: `Accel`, `Alt`, `Cmd`, `Ctrl`, and
* `Shift`. The `Accel` modifier is translated to `Cmd` on Mac and
* `Ctrl` on all other platforms. The `Cmd` modifier is ignored on
* non-Mac platforms.
*
* Keystrokes are case sensitive.
*
* **Examples:** `['Accel C']`, `['Shift F11']`, `['D', 'D']`
*/
keys: string[];
/**
* The CSS selector for the key binding.
*
* The key binding will only be invoked when the selector matches a
* node on the propagation path of the keydown event. This allows
* the key binding to be restricted to user-defined contexts.
*
* The selector must not contain commas.
*/
selector: string;
/**
* The id of the command to execute when the binding is matched.
*/
command: string;
/**
* The arguments for the command, if necessary.
*
* The default value is an empty object.
*/
args?: ReadonlyJSONObject;
/**
* The key sequence to use when running on Windows.
*
* If provided, this will override `keys` on Windows platforms.
*/
winKeys?: string[];
/**
* The key sequence to use when running on Mac.
*
* If provided, this will override `keys` on Mac platforms.
*/
macKeys?: string[];
/**
* The key sequence to use when running on Linux.
*
* If provided, this will override `keys` on Linux platforms.
*/
linuxKeys?: string[];
}
/**
* An object which represents a key binding.
*
* #### Notes
* A key binding is an immutable object created by a registry.
*/
interface IKeyBinding {
/**
* The key sequence for the binding.
*/
readonly keys: ReadonlyArray<string>;
/**
* The CSS selector for the binding.
*/
readonly selector: string;
/**
* The command executed when the binding is matched.
*/
readonly command: string;
/**
* The arguments for the command.
*/
readonly args: ReadonlyJSONObject;
}
/**
* An arguments object for the `keyBindingChanged` signal.
*/
interface IKeyBindingChangedArgs {
/**
* The key binding which was changed.
*/
readonly binding: IKeyBinding;
/**
* Whether the key binding was added or removed.
*/
readonly type: 'added' | 'removed';
}
/**
* An object which holds the results of parsing a keystroke.
*/
interface IKeystrokeParts {
/**
* Whether `'Cmd'` appears in the keystroke.
*/
cmd: boolean;
/**
* Whether `'Ctrl'` appears in the keystroke.
*/
ctrl: boolean;
/**
* Whether `'Alt'` appears in the keystroke.
*/
alt: boolean;
/**
* Whether `'Shift'` appears in the keystroke.
*/
shift: boolean;
/**
* The primary key for the keystroke.
*/
key: string;
}
/**
* Parse a keystroke into its constituent components.
*
* @param keystroke - The keystroke of interest.
*
* @returns The parsed components of the keystroke.
*
* #### Notes
* The keystroke should be of the form:
* `[<modifier 1> [<modifier 2> [<modifier N> ]]]<primary key>`
*
* The supported modifiers are: `Accel`, `Alt`, `Cmd`, `Ctrl`, and
* `Shift`. The `Accel` modifier is translated to `Cmd` on Mac and
* `Ctrl` on all other platforms.
*
* The parsing is tolerant and will not throw exceptions. Notably:
* - Duplicate modifiers are ignored.
* - Extra primary keys are ignored.
* - The order of modifiers and primary key is irrelevant.
* - The keystroke parts should be separated by whitespace.
* - The keystroke is case sensitive.
*/
function parseKeystroke(keystroke: string): IKeystrokeParts;
/**
* Normalize a keystroke into a canonical representation.
*
* @param keystroke - The keystroke of interest.
*
* @returns The normalized representation of the keystroke.
*
* #### Notes
* This normalizes the keystroke by removing duplicate modifiers and
* extra primary keys, and assembling the parts in a canonical order.
*
* The `Cmd` modifier is ignored on non-Mac platforms.
*/
function normalizeKeystroke(keystroke: string): string;
/**
* Format a keystroke for display on the local system.
*/
function formatKeystroke(keystroke: string): string;
/**
* Create a normalized keystroke for a `'keydown'` event.
*
* @param event - The event object for a `'keydown'` event.
*
* @returns A normalized keystroke, or an empty string if the event
* does not represent a valid keystroke for the given layout.
*/
function keystrokeForKeydownEvent(event: KeyboardEvent): string;
}