Skip to content

Commit

Permalink
Documentation (#49340)
Browse files Browse the repository at this point in the history
  • Loading branch information
@chrmarti
chrmarti committed Jun 25, 2018
1 parent db63841 commit ba6aa48
Show file tree
Hide file tree
Showing 2 changed files with 187 additions and 2 deletions.
185 changes: 185 additions & 0 deletions src/vs/vscode.proposed.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

Expand Down
4 changes: 2 additions & 2 deletions src/vs/workbench/browser/parts/quickinput/quickInput.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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[]>();
Expand Down

0 comments on commit ba6aa48

Please sign in to comment.