Logo for jsDocs.io

@phosphor/commands

  • Version 1.7.2
  • Published
  • 60.8 kB
  • 6 dependencies
  • BSD-3-Clause license

Install

npm i @phosphor/commands
yarn add @phosphor/commands
pnpm add @phosphor/commands

Overview

PhosphorJS - Commands

Index

Classes

Namespaces

Classes

class CommandRegistry

class CommandRegistry {}

  • 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.

constructor

constructor();

  • Construct a new command registry.

property commandChanged

readonly commandChanged: ISignal<this, CommandRegistry.ICommandChangedArgs>;

  • 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.

property commandExecuted

readonly commandExecuted: ISignal<this, CommandRegistry.ICommandExecutedArgs>;

  • 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.

property keyBindingChanged

readonly keyBindingChanged: ISignal<
    this,
    CommandRegistry.IKeyBindingChangedArgs
>;

  • A signal emitted when a key binding is changed.

property keyBindings

readonly keyBindings: readonly CommandRegistry.IKeyBinding[];

  • A read-only array of the key bindings in the registry.

method addCommand

addCommand: (
    id: string,
    options: CommandRegistry.ICommandOptions
) => IDisposable;

  • Add a command to the registry.

    Parameter id

    The unique id of the command.

    Parameter options

    The options for the command.

    Returns

    A disposable which will remove the command.

    Throws

    An error if the given id is already registered.

method addKeyBinding

addKeyBinding: (options: CommandRegistry.IKeyBindingOptions) => IDisposable;

  • Add a key binding to the registry.

    Parameter 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.

method caption

caption: (id: string, args?: ReadonlyJSONObject) => string;

  • Get the short form caption for a specific command.

    Parameter id

    The id of the command of interest.

    Parameter args

    The arguments for the command.

    Returns

    The caption for the command, or an empty string if the command is not registered.

method className

className: (id: string, args?: ReadonlyJSONObject) => string;

  • Get the extra class name for a specific command.

    Parameter id

    The id of the command of interest.

    Parameter args

    The arguments for the command.

    Returns

    The class name for the command, or an empty string if the command is not registered.

method dataset

dataset: (id: string, args?: ReadonlyJSONObject) => CommandRegistry.Dataset;

  • Get the dataset for a specific command.

    Parameter id

    The id of the command of interest.

    Parameter args

    The arguments for the command.

    Returns

    The dataset for the command, or an empty dataset if the command is not registered.

method execute

execute: (id: string, args?: ReadonlyJSONObject) => Promise<any>;

  • Execute a specific command.

    Parameter id

    The id of the command of interest.

    Parameter 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.

method hasCommand

hasCommand: (id: string) => boolean;

  • Test whether a specific command is registered.

    Parameter id

    The id of the command of interest.

    Returns

    true if the command is registered, false otherwise.

method icon

icon: (id: string, args?: ReadonlyJSONObject) => string;

  • Deprecated

    Use iconClass() instead.

method iconClass

iconClass: (id: string, args?: ReadonlyJSONObject) => string;

  • Get the icon class for a specific command.

    Parameter id

    The id of the command of interest.

    Parameter args

    The arguments for the command.

    Returns

    The icon class for the command, or an empty string if the command is not registered.

method iconLabel

iconLabel: (id: string, args?: ReadonlyJSONObject) => string;

  • Get the icon label for a specific command.

    Parameter id

    The id of the command of interest.

    Parameter args

    The arguments for the command.

    Returns

    The icon label for the command, or an empty string if the command is not registered.

method isEnabled

isEnabled: (id: string, args?: ReadonlyJSONObject) => boolean;

  • Test whether a specific command is enabled.

    Parameter id

    The id of the command of interest.

    Parameter args

    The arguments for the command.

    Returns

    A boolean indicating whether the command is enabled, or false if the command is not registered.

method isToggled

isToggled: (id: string, args?: ReadonlyJSONObject) => boolean;

  • Test whether a specific command is toggled.

    Parameter id

    The id of the command of interest.

    Parameter args

    The arguments for the command.

    Returns

    A boolean indicating whether the command is toggled, or false if the command is not registered.

method isVisible

isVisible: (id: string, args?: ReadonlyJSONObject) => boolean;

  • Test whether a specific command is visible.

    Parameter id

    The id of the command of interest.

    Parameter args

    The arguments for the command.

    Returns

    A boolean indicating whether the command is visible, or false if the command is not registered.

method label

label: (id: string, args?: ReadonlyJSONObject) => string;

  • Get the display label for a specific command.

    Parameter id

    The id of the command of interest.

    Parameter args

    The arguments for the command.

    Returns

    The display label for the command, or an empty string if the command is not registered.

method listCommands

listCommands: () => string[];

  • List the ids of the registered commands.

    Returns

    A new array of the registered command ids.

method mnemonic

mnemonic: (id: string, args?: ReadonlyJSONObject) => number;

  • Get the mnemonic index for a specific command.

    Parameter id

    The id of the command of interest.

    Parameter args

    The arguments for the command.

    Returns

    The mnemonic index for the command, or -1 if the command is not registered.

method notifyCommandChanged

notifyCommandChanged: (id?: string) => void;

  • Notify listeners that the state of a command has changed.

    Parameter 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.

method processKeydownEvent

processKeydownEvent: (event: KeyboardEvent) => void;

  • Process a 'keydown' event and invoke a matching key binding.

    Parameter 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.

method usage

usage: (id: string, args?: ReadonlyJSONObject) => string;

  • Get the usage help text for a specific command.

    Parameter id

    The id of the command of interest.

    Parameter args

    The arguments for the command.

    Returns

    The usage text for the command, or an empty string if the command is not registered.

Namespaces

namespace CommandRegistry

namespace CommandRegistry {}

  • The namespace for the CommandRegistry class statics.

function formatKeystroke

formatKeystroke: (keystroke: string) => string;

  • Format a keystroke for display on the local system.

function keystrokeForKeydownEvent

keystrokeForKeydownEvent: (event: KeyboardEvent) => string;

  • Create a normalized keystroke for a 'keydown' event.

    Parameter 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 normalizeKeystroke

normalizeKeystroke: (keystroke: string) => string;

  • Normalize a keystroke into a canonical representation.

    Parameter 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 parseKeystroke

parseKeystroke: (keystroke: string) => IKeystrokeParts;

  • Parse a keystroke into its constituent components.

    Parameter 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.

interface ICommandChangedArgs

interface ICommandChangedArgs {}

  • An arguments object for the commandChanged signal.

property id

readonly id: string | undefined;

  • The id of the associated command.

    This will be undefined when the type is 'many-changed'.

property type

readonly type: 'added' | 'removed' | 'changed' | 'many-changed';

  • Whether the command was added, removed, or changed.

interface ICommandExecutedArgs

interface ICommandExecutedArgs {}

  • An arguments object for the commandExecuted signal.

property args

readonly args: ReadonlyJSONObject;

  • The arguments object passed to the command.

property id

readonly id: string;

  • The id of the associated command.

property result

readonly result: Promise<any>;

  • The promise which resolves with the result of the command.

interface ICommandOptions

interface ICommandOptions {}

  • 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.

property caption

caption?: 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.

property className

className?: 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.

property dataset

dataset?: Dataset | CommandFunc<Dataset>;

  • 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.

property execute

execute: CommandFunc<any | Promise<any>>;

  • 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.

property icon

icon?: string | CommandFunc<string>;

  • Deprecated

    Use iconClass instead.

property iconClass

iconClass?: 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.

property iconLabel

iconLabel?: 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.

property isEnabled

isEnabled?: CommandFunc<boolean>;

  • 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.

property isToggled

isToggled?: 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.

property isVisible

isVisible?: 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.

property label

label?: string | CommandFunc<string>;

  • 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.

property mnemonic

mnemonic?: number | CommandFunc<number>;

  • 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.

property usage

usage?: 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.

interface IKeyBinding

interface IKeyBinding {}

  • An object which represents a key binding.

    #### Notes A key binding is an immutable object created by a registry.

property args

readonly args: ReadonlyJSONObject;

  • The arguments for the command.

property command

readonly command: string;

  • The command executed when the binding is matched.

property keys

readonly keys: ReadonlyArray<string>;

  • The key sequence for the binding.

property selector

readonly selector: string;

  • The CSS selector for the binding.

interface IKeyBindingChangedArgs

interface IKeyBindingChangedArgs {}

  • An arguments object for the keyBindingChanged signal.

property binding

readonly binding: IKeyBinding;

  • The key binding which was changed.

property type

readonly type: 'added' | 'removed';

  • Whether the key binding was added or removed.

interface IKeyBindingOptions

interface IKeyBindingOptions {}

  • An options object for creating a key binding.

property args

args?: ReadonlyJSONObject;

  • The arguments for the command, if necessary.

    The default value is an empty object.

property command

command: string;

  • The id of the command to execute when the binding is matched.

property keys

keys: string[];

  • 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']

property linuxKeys

linuxKeys?: string[];

  • The key sequence to use when running on Linux.

    If provided, this will override keys on Linux platforms.

property macKeys

macKeys?: string[];

  • The key sequence to use when running on Mac.

    If provided, this will override keys on Mac platforms.

property selector

selector: 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.

property winKeys

winKeys?: string[];

  • The key sequence to use when running on Windows.

    If provided, this will override keys on Windows platforms.

interface IKeystrokeParts

interface IKeystrokeParts {}

  • An object which holds the results of parsing a keystroke.

property alt

alt: boolean;

  • Whether 'Alt' appears in the keystroke.

property cmd

cmd: boolean;

  • Whether 'Cmd' appears in the keystroke.

property ctrl

ctrl: boolean;

  • Whether 'Ctrl' appears in the keystroke.

property key

key: string;

  • The primary key for the keystroke.

property shift

shift: boolean;

  • Whether 'Shift' appears in the keystroke.

type CommandFunc

type CommandFunc<T> = (args: ReadonlyJSONObject) => T;

  • A type alias for a user-defined command function.

type Dataset

type Dataset = {
    readonly [key: string]: string;
};

  • A type alias for a simple immutable string dataset.

Package Files (1)

Dependencies (6)

Dev Dependencies (16)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@phosphor/commands.

  • Markdown
    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@phosphor/commands)
  • HTML
    <a href="https://www.jsdocs.io/package/@phosphor/commands"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>