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.

Constructors

Properties

_commandChanged: Signal<CommandRegistry, ICommandChangedArgs> = ...
_commandExecuted: Signal<CommandRegistry, ICommandExecutedArgs> = ...
_commands: Map<string, ICommand> = ...
_exactKeyMatch: null | IKeyBinding = null
_holdKeyBindingPromises: Map<KeyboardEvent, Promise<boolean>> = ...
_keyBindingChanged: Signal<CommandRegistry, IKeyBindingChangedArgs> = ...
_keyBindings: IKeyBinding[] = []
_keydownEvents: KeyboardEvent[] = []
_keystrokes: string[] = []
_replaying: boolean = false
_timerID: number = 0
_timerModifierID: number = 0

Accessors

  • get commandExecuted(): ISignal<this, ICommandExecutedArgs>
  • A signal emitted when a command has executed.

    Notes

    Care should be taken when consuming this signal. The command system is used by many components for many user actions. Handlers registered with this signal must return quickly to ensure the overall application remains responsive.

    Returns ISignal<this, ICommandExecutedArgs>

Methods

  • Clear the timeout on modifier keys.

    Returns void

  • Clear the internal pending state.

    Returns void

  • Clear the pending timeout.

    Returns void

  • Execute the command for the given key binding.

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

    The execution will not proceed if any of the events leading to the keybinding matching were held with the permission resolving to false.

    Parameters

    Returns Promise<void>

  • Handle the partial match timeout.

    Returns void

  • Replay the keydown events which were suppressed.

    Returns void

  • Start or restart the timeout on the modifier keys.

    This timeout will end only if the keys are hold.

    Parameters

    Returns void

  • Start or restart the pending timeout.

    Returns void

  • Add a command to the registry.

    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.

    Throws

    An error if the given id is already registered.

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

  • Get the short form caption for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyPartialJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns string

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

  • Get the extra class name for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyPartialJSONObject = 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.

  • Execute a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyPartialJSONObject = 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.

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

  • Delay the execution of any command matched against the given 'keydown' event until the permission to execute is granted.

    Parameters

    • event: KeyboardEvent

      The event object for a 'keydown' event.

    • permission: Promise<boolean>

      The promise with value indicating whether to proceed with the execution.

      Note

      This enables the caller of processKeydownEvent to asynchronously prevent the execution of the command based on external events.

    Returns void

  • Get the icon renderer for a specific command.

    DEPRECATED: if set to a string value, the .icon field will function as an alias for the .iconClass field, for backwards compatibility. In the future when this is removed, the default return type will become undefined.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyPartialJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns undefined | VirtualElement.IRenderer

    The icon renderer for the command or undefined.

  • Get the icon class for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyPartialJSONObject = 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.

  • Get the icon label for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyPartialJSONObject = 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.

  • Test whether a specific command is enabled.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyPartialJSONObject = 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.

  • Test whether a specific command is toggleable.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns boolean

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

  • Test whether a specific command is toggled.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyPartialJSONObject = 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.

  • Test whether a specific command is visible.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyPartialJSONObject = 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.

  • Get the display label for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyPartialJSONObject = 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.

  • List the ids of the registered commands.

    Returns string[]

    A new array of the registered command ids.

  • Get the mnemonic index for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyPartialJSONObject = JSONExt.emptyObject

      The arguments for the command.

    Returns number

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

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

    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

    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.

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

      When the keydown event is processed, if the event target or any of its ancestor nodes has a data-lm-suppress-shortcuts attribute, its keydown events will not invoke commands.

    Returns void

  • Process a keyup event to clear the timer on the modifier, if it exists.

    Parameters

    Returns void

  • Get the usage help text for a specific command.

    Parameters

    • id: string

      The id of the command of interest.

    • args: ReadonlyPartialJSONObject = 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.