Documentation (#49340)

Author: chrmarti

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<T extends QuickPickItem>(): QuickPick<T>;
 
+		/**
+		 * 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<void>;
 
+		/**
+		 * 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<T extends QuickPickItem> 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<string>;
 
+		/**
+		 * An event signaling when the user indicated acceptance of the selected item(s).
+		 */
 		readonly onDidAccept: Event<void>;
 
+		/**
+		 * Buttons for actions in the UI.
+		 */
 		buttons: ReadonlyArray<QuickInputButton>;
 
+		/**
+		 * An event signaling when a button was triggered.
+		 */
 		readonly onDidTriggerButton: Event<QuickInputButton>;
 
+		/**
+		 * Items to pick from.
+		 */
 		items: ReadonlyArray<T>;
 
+		/**
+		 * 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<T>;
 
+		/**
+		 * An event signaling when the active items have changed.
+		 */
 		readonly onDidChangeActive: Event<T[]>;
 
+		/**
+		 * Selected items. This can be read and updated by the extension.
+		 */
 		selectedItems: ReadonlyArray<T>;
 
+		/**
+		 * An event signaling when the selected items have changed.
+		 */
 		readonly onDidChangeSelection: Event<T[]>;
 	}
 
+	/**
+	 * 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<string>;
 
+		/**
+		 * An event signaling when the user indicated acceptance of the input value.
+		 */
 		readonly onDidAccept: Event<void>;
 
+		/**
+		 * Buttons for actions in the UI.
+		 */
 		buttons: ReadonlyArray<QuickInputButton>;
 
+		/**
+		 * An event signaling when a button was triggered.
+		 */
 		readonly onDidTriggerButton: Event<QuickInputButton>;
 
+		/**
+		 * 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;
 	}
 

src/vs/workbench/browser/parts/quickinput/quickInput.ts

@@ -285,8 +285,8 @@ class QuickPick<T extends IQuickPickItem> 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<T[]>();