From 728a8f5416e1a1cb84721639f21c22d6d16ce3c0 Mon Sep 17 00:00:00 2001 From: Jonas Helming Date: Fri, 2 Oct 2020 13:03:23 +0000 Subject: [PATCH] Added documentation for key binding, contributions and registry fixes #8636 Contributed on behalf of STMicroelectronics Signed-off-by: Jonas Helming --- packages/core/src/browser/keybinding.ts | 50 +++++++++++++++++++------ packages/core/src/common/keybinding.ts | 20 +++++++--- 2 files changed, 53 insertions(+), 17 deletions(-) diff --git a/packages/core/src/browser/keybinding.ts b/packages/core/src/browser/keybinding.ts index a92af3db14c88..8e6ed41244809 100644 --- a/packages/core/src/browser/keybinding.ts +++ b/packages/core/src/browser/keybinding.ts @@ -60,7 +60,7 @@ export interface ScopedKeybinding extends common.Keybinding { export const KeybindingContribution = Symbol('KeybindingContribution'); /** - * Representation of a keybinding contribution. + * Allows extensions to contribute {@link common.Keybinding}s */ export interface KeybindingContribution { /** @@ -168,36 +168,36 @@ export class KeybindingRegistry { * * Keybindings registered later have higher priority during evaluation. * - * @param binding + * @param binding the keybinding to be registered */ registerKeybinding(binding: common.Keybinding): Disposable { return this.doRegisterKeybinding(binding); } /** - * Register default keybindings to the registry + * Register multiple default keybindings to the registry * - * @param bindings + * @param bindings An array of keybinding to be registered */ registerKeybindings(...bindings: common.Keybinding[]): Disposable { return this.doRegisterKeybindings(bindings, KeybindingScope.DEFAULT); } /** - * Unregister keybindings from the registry using the key of the given keybinding + * Unregister all keybindings from the registry that are bound to the key of the given keybinding * - * @param binding a Keybinding specifying the key to be unregistered + * @param binding a keybinding specifying the key to be unregistered */ unregisterKeybinding(binding: common.Keybinding): void; /** - * Unregister keybindings with the given key from the registry + * Unregister all keybindings with the given key from the registry * * @param key a key to be unregistered */ unregisterKeybinding(key: string): void; /** * Unregister all existing keybindings for the given command - * @param command the command to unregister keybindings for + * @param command the command to unregister all keybindings for */ unregisterKeybinding(command: Command): void; @@ -266,6 +266,12 @@ export class KeybindingRegistry { } } + /** + * Checks whether a colliding {@link common.Keybinding} exists in a specific scope. + * @param binding the keybinding to check + * @param scope the keybinding scope to check + * @returns true if there is a colliding keybinding + */ containsKeybindingInScope(binding: common.Keybinding, scope = KeybindingScope.USER): boolean { const bindingKeySequence = this.resolveKeybinding(binding); const collisions = this.getKeySequenceCollisions(this.keymaps[scope], bindingKeySequence) @@ -283,7 +289,10 @@ export class KeybindingRegistry { } /** - * Return a user visible representation of a keybinding. + * Get a user visible representation of a {@link common.Keybinding}. + * @returns an array of strings representing all elements of the {@link KeySequence} defined by the {@link common.Keybinding} + * @param keybinding the keybinding + * @param separator the separator to be used to stringify {@link KeyCode}s that are part of the {@link KeySequence} */ acceleratorFor(keybinding: common.Keybinding, separator: string = ' '): string[] { const bindingKeySequence = this.resolveKeybinding(keybinding); @@ -291,14 +300,20 @@ export class KeybindingRegistry { } /** - * Return a user visible representation of a key sequence. + * Get a user visible representation of a {@link KeySequence}. + * @returns an array of strings representing all elements of the {@link KeySequence} + * @param keySequence the keysequence + * @param separator the separator to be used to stringify {@link KeyCode}s that are part of the {@link KeySequence} */ acceleratorForSequence(keySequence: KeySequence, separator: string = ' '): string[] { return keySequence.map(keyCode => this.acceleratorForKeyCode(keyCode, separator)); } /** - * Return a user visible representation of a key code (a key with modifiers). + * Get a user visible representation of a key code (a key with modifiers). + * @returns a string representing the {@link KeyCode} + * @param keyCode the {@link KeyCode} + * @param separator the separator used to separate keys (key and modifiers) in the returning string */ acceleratorForKeyCode(keyCode: KeyCode, separator: string = ' '): string { const keyCodeResult = []; @@ -383,9 +398,10 @@ export class KeybindingRegistry { } /** - * Get the keybindings associated to commandId. + * Get all keybindings associated to a commandId. * * @param commandId The ID of the command for which we are looking for keybindings. + * @returns an array of {@link ScopedKeybinding} */ getKeybindingsForCommand(commandId: string): ScopedKeybinding[] { const result: ScopedKeybinding[] = []; @@ -577,6 +593,11 @@ export class KeybindingRegistry { return commandId === KeybindingRegistry.PASSTHROUGH_PSEUDO_COMMAND; } + /** + * Sets a new keymap replacing all existing {@link common.Keybinding}s in the given scope. + * @param scope the keybinding scope + * @param bindings an array containing the new {@link common.Keybinding}s + */ setKeymap(scope: KeybindingScope, bindings: common.Keybinding[]): void { this.resetKeybindingsForScope(scope); this.toResetKeymap.set(scope, this.doRegisterKeybindings(bindings, scope)); @@ -605,6 +626,11 @@ export class KeybindingRegistry { } } + /** + * Get all {@link common.Keybinding}s for a {@link KeybindingScope}. + * @returns an array of {@link common.ScopedKeybinding} + * @param scope the keybinding scope to retrieve the {@link common.Keybinding}s for. + */ getKeybindingsByScope(scope: KeybindingScope): ScopedKeybinding[] { return this.keymaps[scope]; } diff --git a/packages/core/src/common/keybinding.ts b/packages/core/src/common/keybinding.ts index 497d388ad5c23..4895666178a29 100644 --- a/packages/core/src/common/keybinding.ts +++ b/packages/core/src/common/keybinding.ts @@ -13,11 +13,19 @@ * * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 ********************************************************************************/ - +/** + * A Keybinding binds a specific key sequence ({@link Keybinding#keybinding}) to trigger a command ({@link Keybinding#command}). A Keybinding optionally may + * define a "when clause" ({@link Keybinding#when}) to specify in which context it becomes active. + * @see KeyBindingRegistry + */ export interface Keybinding { - /** Command identifier, this needs to be a unique string. */ + /** + * Unique command identifier of the command to be triggered by this keybinding. + */ command: string; - /** Keybinding string as defined in packages/keymaps/README.md. */ + /** + * The key sequence for the keybinding as defined in packages/keymaps/README.md. + */ keybinding: string; /** * The optional keybinding context where this binding belongs to. @@ -28,12 +36,14 @@ export interface Keybinding { */ context?: string; /** - * https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts + * An optional clause defining the condition when the keybinding is active, e.g. based on the current focus. + * See {@link https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts} for more details. */ when?: string; /** - * Specified when the command has arguments that are passed to the command handler. + * Optional arguments that will be passed to the command when it gets triggered via this keybinding. + * Needs to be specified when the triggered command expects arguments to be passed to the command handler. */ // eslint-disable-next-line @typescript-eslint/no-explicit-any args?: any;