From ba6aa48b6e73761be64569a8b91220a16880e7c5 Mon Sep 17 00:00:00 2001 From: Christof Marti Date: Mon, 25 Jun 2018 17:30:51 +0200 Subject: [PATCH] Documentation (#49340) --- src/vs/vscode.proposed.d.ts | 185 ++++++++++++++++++ .../browser/parts/quickinput/quickInput.ts | 4 +- 2 files changed, 187 insertions(+), 2 deletions(-) diff --git a/src/vs/vscode.proposed.d.ts b/src/vs/vscode.proposed.d.ts index 99ece63c7de..e342923c195 100644 --- a/src/vs/vscode.proposed.d.ts +++ b/src/vs/vscode.proposed.d.ts @@ -523,90 +523,275 @@ declare module 'vscode' { export namespace window { + /** + * A back button for [QuickPick](#QuickPick) and [InputBox](#InputBox). + * + * When a navigation 'back' button is needed this one should be used for consistency. + * It comes with a predefined icon, tooltip and location. + */ export const quickInputBackButton: QuickInputButton; + /** + * Creates a [QuickPick](#QuickPick) to let the user pick an item from a list + * of items of type T. + * + * Note that in many cases the more convenient [window.showQuickPick](#window.showQuickPick) + * is easier to use. + * + * @return A new [QuickPick](#QuickPick). + */ export function createQuickPick(): QuickPick; + /** + * Creates a [InputBox](#InputBox) to let the user enter some text input. + * + * Note that in many cases the more convenient [window.showInputBox](#window.showInputBox) + * is easier to use. + * + * @return A new [InputBox](#InputBox). + */ export function createInputBox(): InputBox; } + /** + * A light-weight user input UI that is intially not visible. After + * configuring it through its properties the extension can make it + * visible by calling [QuickInput.show](#QuickInput.show). + * + * There are several reasons why this UI might have to be hidden and + * the extension will be notified through [QuickInput.onDidHide](#QuickInput.onDidHide). + * (Examples include: an explict call to [QuickInput.hide](#QuickInput.hide), + * the user pressing Esc, some other input UI opening, etc.) + * + * A user pressing Enter or some other gesture implying acceptance + * of the current state does not automatically hide this UI component. + * It is up to the extension to decide whether to accept the user's input + * and if the UI should indeed be hidden through a call to [QuickInput.hide](#QuickInput.hide). + * + * When the extension no longer needs this input UI, it should + * [QuickInput.dispose](#QuickInput.dispose) it to allow for freeing up + * any resources associated with it. + * + * See [QuickPick](#QuickPick) and [InputBox](#InputBox) for concrete UIs. + */ export interface QuickInput { + /** + * An optional title. + */ title: string | undefined; + /** + * An optional current step count. + */ step: number | undefined; + /** + * An optional total step count. + */ totalSteps: number | undefined; + /** + * If the UI should allow for user input. Defaults to true. + * + * Change this to false, e.g., while validating user input or + * loading data for the next step in user input. + */ enabled: boolean; + /** + * If the UI should show a progress indicator. Defaults to false. + * + * Change this to true, e.g., while loading more data or validating + * user input. + */ busy: boolean; + /** + * If the UI should stay open even when loosing UI focus. Defaults to false. + */ ignoreFocusOut: boolean; + /** + * Makes the input UI visible in its current configuration. Any other input + * UI will first fire an [QuickInput.onDidHide](#QuickInput.onDidHide) event. + */ show(): void; + /** + * Hides this input UI. This will also fire an [QuickInput.onDidHide](#QuickInput.onDidHide) + * event. + */ hide(): void; + /** + * An event signaling when this input UI is hidden. + * + * There are several reasons why this UI might have to be hidden and + * the extension will be notified through [QuickInput.onDidHide](#QuickInput.onDidHide). + * (Examples include: an explict call to [QuickInput.hide](#QuickInput.hide), + * the user pressing Esc, some other input UI opening, etc.) + */ onDidHide: Event; + /** + * Dispose of this input UI and any associated resources. If it is still + * visible, it is first hidden. After this call the input UI is no longer + * functional and no additional methods or properties on it should be + * accessed. Instead a new input UI should be created. + */ dispose(): void; } + /** + * A concrete [QuickInput](#QuickInput) to let the user pick an item from a + * list of items of type T. The items can be filtered through a filter text field and + * there is an option [canSelectMany](#QuickPick.canSelectMany) to allow for + * selecting multiple items. + * + * Note that in many cases the more convenient [window.showQuickPick](#window.showQuickPick) + * is easier to use. + */ export interface QuickPick extends QuickInput { + /** + * Current value of the filter text. + */ value: string; + /** + * Optional placeholder in the filter text. + */ placeholder: string | undefined; + /** + * An event signaling when the value of the filter text has changed. + */ readonly onDidChangeValue: Event; + /** + * An event signaling when the user indicated acceptance of the selected item(s). + */ readonly onDidAccept: Event; + /** + * Buttons for actions in the UI. + */ buttons: ReadonlyArray; + /** + * An event signaling when a button was triggered. + */ readonly onDidTriggerButton: Event; + /** + * Items to pick from. + */ items: ReadonlyArray; + /** + * If multiple items can be selected at the same time. Defaults to false. + */ canSelectMany: boolean; + /** + * If the filter text should also be matched against the description of the items. Defaults to false. + */ matchOnDescription: boolean; + /** + * If the filter text should also be matched against the detail of the items. Defaults to false. + */ matchOnDetail: boolean; + /** + * Active items. This can be read and updated by the extension. + */ activeItems: ReadonlyArray; + /** + * An event signaling when the active items have changed. + */ readonly onDidChangeActive: Event; + /** + * Selected items. This can be read and updated by the extension. + */ selectedItems: ReadonlyArray; + /** + * An event signaling when the selected items have changed. + */ readonly onDidChangeSelection: Event; } + /** + * A concrete [QuickInput](#QuickInput) to let the user input a text value. + * + * Note that in many cases the more convenient [window.showInputBox](#window.showInputBox) + * is easier to use. + */ export interface InputBox extends QuickInput { + /** + * Current input value. + */ value: string; + /** + * Optional placeholder in the filter text. + */ placeholder: string | undefined; + /** + * If the input value should be hidden. Defaults to false. + */ password: boolean; + /** + * An event signaling when the value has changed. + */ readonly onDidChangeValue: Event; + /** + * An event signaling when the user indicated acceptance of the input value. + */ readonly onDidAccept: Event; + /** + * Buttons for actions in the UI. + */ buttons: ReadonlyArray; + /** + * An event signaling when a button was triggered. + */ readonly onDidTriggerButton: Event; + /** + * An optional prompt text providing some ask or explanation to the user. + */ prompt: string | undefined; + /** + * An optional validation message indicating a problem with the current input value. + */ validationMessage: string | undefined; } + /** + * Button for an action in a [QuickPick](#QuickPick) or [InputBox](#InputBox). + */ export interface QuickInputButton { + + /** + * Icon for the button. + */ readonly iconPath: string | Uri | { light: string | Uri; dark: string | Uri } | ThemeIcon; + + /** + * An optional tooltip. + */ readonly tooltip?: string | undefined; } diff --git a/src/vs/workbench/browser/parts/quickinput/quickInput.ts b/src/vs/workbench/browser/parts/quickinput/quickInput.ts index 3895d568ae1..23c7d23e53e 100644 --- a/src/vs/workbench/browser/parts/quickinput/quickInput.ts +++ b/src/vs/workbench/browser/parts/quickinput/quickInput.ts @@ -285,8 +285,8 @@ class QuickPick extends QuickInput implements IQuickPi private _items: T[] = []; private itemsUpdated = false; private _canSelectMany = false; - private _matchOnDescription = true; - private _matchOnDetail = true; + private _matchOnDescription = false; + private _matchOnDetail = false; private _activeItems: T[] = []; private activeItemsUpdated = false; private onDidChangeActiveEmitter = new Emitter(); -- GitLab