Options
All
  • Public
  • Public/Protected
  • All
Menu

Class CommandRegistry

An object which manages a collection of commands. The namespace for the CommandRegistry class statics.

Notes

A command registry can be used to populate a variety of action-based widgets, such as command palettes, menus, and toolbars.

Hierarchy

  • CommandRegistry

Index

Interfaces

Type aliases

Constructors

Properties

Accessors

Methods

Type aliases

Static CommandFunc

CommandFunc: function

A type alias for a user-defined command function.

Type declaration

    • (args: ReadonlyJSONObject): T

    • Parameters

      • args: ReadonlyJSONObject

      Returns T

Static Dataset

Dataset: object

A type alias for a simple immutable string dataset.

Type declaration

  • [key: string]: string

Constructors

constructor

Properties

Private _commandChanged

_commandChanged: Signal<this, ICommandChangedArgs> = new Signal<this, CommandRegistry.ICommandChangedArgs>(this)

Private _commandExecuted

_commandExecuted: Signal<this, ICommandExecutedArgs> = new Signal<this, CommandRegistry.ICommandExecutedArgs>(this)

Private _commands

_commands: object = Object.create(null)

Type declaration

  • [id: string]: ICommand

Private _exactKeyMatch

_exactKeyMatch: IKeyBinding | null = null

Private _keyBindingChanged

_keyBindingChanged: Signal<this, IKeyBindingChangedArgs> = new Signal<this, CommandRegistry.IKeyBindingChangedArgs>(this)

Private _keyBindings

_keyBindings: IKeyBinding[] = []

Private _keydownEvents

_keydownEvents: KeyboardEvent[] = []

Private _keystrokes

_keystrokes: string[] = []

Private _replaying

_replaying: boolean = false

Private _timerID

_timerID: number = 0

Accessors

commandChanged

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

    Returns ISignal<this, ICommandChangedArgs>

commandExecuted

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

    Returns ISignal<this, ICommandExecutedArgs>

keyBindingChanged

keyBindings

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

    Returns ReadonlyArray<IKeyBinding>

Methods

Private _clearPendingState

  • _clearPendingState(): void

  • Clear the internal pending state.

    Returns void

Private _clearTimer

  • _clearTimer(): void

  • Clear the pending timeout.

    Returns void

Private _executeKeyBinding

  • Execute the command for the given key binding.

    If the command is missing or disabled, a warning will be logged.

    Parameters

    Returns void

Private _onPendingTimeout

  • _onPendingTimeout(): void

  • Handle the partial match timeout.

    Returns void

Private _replayKeydownEvents

  • _replayKeydownEvents(): void

  • Replay the keydown events which were suppressed.

    Returns void

Private _startTimer

  • _startTimer(): void

  • Start or restart the pending timeout.

    Returns void

addCommand

  • Add a command to the registry.

    throws

    An error if the given id is already registered.

    Parameters

    • id: string

      The unique id of the command.

    • options: ICommandOptions

      The options for the command.

    Returns IDisposable

    A disposable which will remove the command.

addKeyBinding

  • Add a key binding to the registry.

    Parameters

    Returns IDisposable

    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.

caption

  • caption(id: string, args?: ReadonlyJSONObject): string

  • Get the short form caption for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns string

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

className

  • className(id: string, args?: ReadonlyJSONObject): string

  • Get the extra class name for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns string

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

dataset

  • dataset(id: string, args?: ReadonlyJSONObject): Dataset

  • Get the dataset for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns Dataset

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

execute

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

  • Execute a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns Promise<any>

    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.

hasCommand

  • hasCommand(id: string): boolean

  • Test whether a specific command is registered.

    Parameters

    • id: string

      The id of the command of interest.

    Returns boolean

    true if the command is registered, false otherwise.

icon

  • icon(id: string, args?: ReadonlyJSONObject): string
  • deprecated

    Use iconClass() instead.

    Parameters

    • id: string
    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

    Returns string

iconClass

  • iconClass(id: string, args?: ReadonlyJSONObject): string

  • Get the icon class for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns string

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

iconLabel

  • iconLabel(id: string, args?: ReadonlyJSONObject): string

  • Get the icon label for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns string

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

isEnabled

  • isEnabled(id: string, args?: ReadonlyJSONObject): boolean

  • Test whether a specific command is enabled.

    Parameters

    • id: string

      The id of the command of interest.

    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns boolean

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

isToggled

  • isToggled(id: string, args?: ReadonlyJSONObject): boolean

  • Test whether a specific command is toggled.

    Parameters

    • id: string

      The id of the command of interest.

    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns boolean

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

isVisible

  • isVisible(id: string, args?: ReadonlyJSONObject): boolean

  • Test whether a specific command is visible.

    Parameters

    • id: string

      The id of the command of interest.

    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns boolean

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

label

  • label(id: string, args?: ReadonlyJSONObject): string

  • Get the display label for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns string

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

listCommands

  • listCommands(): string[]

  • List the ids of the registered commands.

    Returns string[]

    A new array of the registered command ids.

mnemonic

  • mnemonic(id: string, args?: ReadonlyJSONObject): number

  • Get the mnemonic index for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns number

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

notifyCommandChanged

  • notifyCommandChanged(id?: string): void

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

    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.

    Parameters

    • Optional id: string

      The id of the command which has changed. If more than one command has changed, this argument should be omitted.

    Returns void

processKeydownEvent

  • processKeydownEvent(event: KeyboardEvent): void

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

    Parameters

    • event: KeyboardEvent

      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.

    Returns void

usage

  • usage(id: string, args?: ReadonlyJSONObject): string

  • Get the usage help text for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • Default value args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns string

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

Static keystrokeForKeydownEvent

  • keystrokeForKeydownEvent(event: KeyboardEvent): string

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

    Parameters

    • event: KeyboardEvent

      The event object for a 'keydown' event.

    Returns string

    A normalized keystroke, or an empty string if the event does not represent a valid keystroke for the given layout.

Static normalizeKeystroke

  • normalizeKeystroke(keystroke: string): string

  • Normalize a keystroke into a canonical representation.

    Parameters

    • keystroke: string

      The keystroke of interest.

    Returns string

    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.

Static parseKeystroke

  • Parse a keystroke into its constituent components.

    Parameters

    • keystroke: string

      The keystroke of interest.

    Returns IKeystrokeParts

    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.

Generated using TypeDoc