bingyi/vscode-extension-samples
1
0
Fork 0
mirror of https://github.com/microsoft/vscode-extension-samples.git synced 2026-04-27 16:55:44 +08:00
Code Issues Packages Projects Releases Wiki Activity

Catch up with API polish

Browse Source
This commit is contained in:
Christof Marti
2018-07-23 11:21:06 +02:00
parent 252e6b2f71
commit 081909fb45
2 changed files with 286 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
quickinput-sample/src/multiStepInput.ts
View File

@ -3,7 +3,7 @@
* Licensed under the MIT License. See License.txt in the project root for license information.
*--------------------------------------------------------------------------------------------*/
import { QuickPickItem, window, Disposable, CancellationToken, QuickInputButton, QuickInput, ExtensionContext } from 'vscode';
import { QuickPickItem, window, Disposable, CancellationToken, QuickInputButton, QuickInput, ExtensionContext, QuickInputButtons } from 'vscode';
/**
* A multi-step input using window.createQuickPick() and window.createInputBox().
@ -216,12 +216,12 @@ class MultiStepInput {
input.activeItems = [activeItem];
}
input.buttons = [
...(this.steps.length > 1 ? [window.quickInputBackButton] : []),
...(this.steps.length > 1 ? [QuickInputButtons.Back] : []),
...(buttons || [])
];
disposables.push(
input.onDidTriggerButton(item => {
if (item === window.quickInputBackButton) {
if (item === QuickInputButtons.Back) {
reject(InputFlowAction.back);
} else {
resolve(<any>item);
@ -257,13 +257,13 @@ class MultiStepInput {
input.value = value || '';
input.prompt = prompt;
input.buttons = [
...(this.steps.length > 1 ? [window.quickInputBackButton] : []),
...(this.steps.length > 1 ? [QuickInputButtons.Back] : []),
...(buttons || [])
];
let validating = validate('');
disposables.push(
input.onDidTriggerButton(item => {
if (item === window.quickInputBackButton) {
if (item === QuickInputButtons.Back) {
reject(InputFlowAction.back);
} else {
resolve(<any>item);

464
quickinput-sample/src/vscode.proposed.d.ts vendored
View File

@ -13,46 +13,255 @@ declare module 'vscode' {
export function sampleFunction(): Thenable<any>;
}
//#region Joh: remote, search provider
//#region Rob: search provider
/**
* The parameters of a query for text search.
*/
export interface TextSearchQuery {
/**
* The text pattern to search for.
*/
pattern: string;
isRegExp: boolean;
isCaseSensitive: boolean;
isWordMatch: boolean;
/**
* Whether or not `pattern` should be interpreted as a regular expression.
*/
isRegExp?: boolean;
/**
* Whether or not the search should be case-sensitive.
*/
isCaseSensitive?: boolean;
/**
* Whether or not to search for whole word matches only.
*/
isWordMatch?: boolean;
}
/**
* A file glob pattern to match file paths against.
* TODO@roblou - merge this with the GlobPattern docs/definition in vscode.d.ts.
* @see [GlobPattern](#GlobPattern)
*/
export type GlobString = string;
/**
* Options common to file and text search
*/
export interface SearchOptions {
/**
* The root folder to search within.
*/
folder: Uri;
includes: string[]; // paths relative to folder
excludes: string[];
/**
* Files that match an `includes` glob pattern should be included in the search.
*/
includes: GlobString[];
/**
* Files that match an `excludes` glob pattern should be excluded from the search.
*/
excludes: GlobString[];
/**
* Whether external files that exclude files, like .gitignore, should be respected.
* See the vscode setting `"search.useIgnoreFiles"`.
*/
useIgnoreFiles?: boolean;
/**
* Whether symlinks should be followed while searching.
* See the vscode setting `"search.followSymlinks"`.
*/
followSymlinks?: boolean;
/**
* The maximum number of results to be returned.
*/
maxResults?: number;
}
/**
* Options that apply to text search.
*/
export interface TextSearchOptions extends SearchOptions {
previewOptions?: any; // total length? # of context lines? leading and trailing # of chars?
/**
* TODO@roblou - total length? # of context lines? leading and trailing # of chars?
*/
previewOptions?: any;
/**
* Exclude files larger than `maxFileSize` in bytes.
*/
maxFileSize?: number;
/**
* Interpret files using this encoding.
* See the vscode setting `"files.encoding"`
*/
encoding?: string;
}
export interface FileSearchOptions extends SearchOptions { }
/**
* The parameters of a query for file search.
*/
export interface FileSearchQuery {
/**
* The search pattern to match against file paths.
*/
pattern: string;
export interface TextSearchResult {
path: string;
range: Range;
// For now, preview must be a single line of text
preview: { text: string, match: Range };
/**
* `cacheKey` has the same value when `provideFileSearchResults` is invoked multiple times during a single quickopen session.
* Providers can optionally use this to cache results at the beginning of a quickopen session and filter results as the user types.
* It will have a different value for each folder searched.
*/
cacheKey?: string;
}
/**
* Options that apply to file search.
*/
export interface FileSearchOptions extends SearchOptions { }
export interface TextSearchResultPreview {
/**
* The matching line of text, or a portion of the matching line that contains the match.
* For now, this can only be a single line.
*/
text: string;
/**
* The Range within `text` corresponding to the text of the match.
*/
match: Range;
}
/**
* A match from a text search
*/
export interface TextSearchResult {
/**
* The uri for the matching document.
*/
uri: Uri;
/**
* The range of the match within the document.
*/
range: Range;
/**
* A preview of the matching line
*/
preview: TextSearchResultPreview;
}
/**
* A SearchProvider provides search results for files or text in files. It can be invoked by quickopen, the search viewlet, and other extensions.
*/
export interface SearchProvider {
provideFileSearchResults?(options: FileSearchOptions, progress: Progress<string>, token: CancellationToken): Thenable<void>;
/**
* Provide the set of files that match a certain file path pattern.
* @param query The parameters for this query.
* @param options A set of options to consider while searching files.
* @param progress A progress callback that must be invoked for all results.
* @param token A cancellation token.
*/
provideFileSearchResults?(query: FileSearchQuery, options: FileSearchOptions, progress: Progress<Uri>, token: CancellationToken): Thenable<void>;
/**
* Optional - if the provider makes use of `query.cacheKey`, it can implement this method which is invoked when the cache can be cleared.
* @param cacheKey The same key that was passed as `query.cacheKey`.
*/
clearCache?(cacheKey: string): void;
/**
* Provide results that match the given text pattern.
* @param query The parameters for this query.
* @param options A set of options to consider while searching.
* @param progress A progress callback that must be invoked for all results.
* @param token A cancellation token.
*/
provideTextSearchResults?(query: TextSearchQuery, options: TextSearchOptions, progress: Progress<TextSearchResult>, token: CancellationToken): Thenable<void>;
}
/**
* Options that can be set on a findTextInFiles search.
*/
export interface FindTextInFilesOptions {
/**
* A [glob pattern](#GlobPattern) that defines the files to search for. The glob pattern
* will be matched against the file paths of files relative to their workspace. Use a [relative pattern](#RelativePattern)
* to restrict the search results to a [workspace folder](#WorkspaceFolder).
*/
include?: GlobPattern;
/**
* A [glob pattern](#GlobPattern) that defines files and folders to exclude. The glob pattern
* will be matched against the file paths of resulting matches relative to their workspace. When `undefined` only default excludes will
* apply, when `null` no excludes will apply.
*/
exclude?: GlobPattern | null;
/**
* The maximum number of results to search for
*/
maxResults?: number;
/**
* Whether external files that exclude files, like .gitignore, should be respected.
* See the vscode setting `"search.useIgnoreFiles"`.
*/
useIgnoreFiles?: boolean;
/**
* Whether symlinks should be followed while searching.
* See the vscode setting `"search.followSymlinks"`.
*/
followSymlinks?: boolean;
/**
* Interpret files using this encoding.
* See the vscode setting `"files.encoding"`
*/
encoding?: string;
}
export namespace workspace {
/**
* Register a search provider.
*
* Only one provider can be registered per scheme.
*
* @param scheme The provider will be invoked for workspace folders that have this file scheme.
* @param provider The provider.
* @return A [disposable](#Disposable) that unregisters this provider when being disposed.
*/
export function registerSearchProvider(scheme: string, provider: SearchProvider): Disposable;
/**
* Search text in files across all [workspace folders](#workspace.workspaceFolders) in the workspace.
* @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words.
* @param callback A callback, called for each result
* @param token A token that can be used to signal cancellation to the underlying search engine.
* @return A thenable that resolves when the search is complete.
*/
export function findTextInFiles(query: TextSearchQuery, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable<void>;
/**
* Search text in files across all [workspace folders](#workspace.workspaceFolders) in the workspace.
* @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words.
* @param options An optional set of query options. Include and exclude patterns, maxResults, etc.
* @param callback A callback, called for each result
* @param token A token that can be used to signal cancellation to the underlying search engine.
* @return A thenable that resolves when the search is complete.
*/
export function findTextInFiles(query: TextSearchQuery, options: FindTextInFilesOptions, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable<void>;
}
//#endregion
@ -341,7 +550,7 @@ declare module 'vscode' {
* provides access to the raw data stream from the process running within the terminal,
* including VT sequences.
*/
onData: Event<string>;
onDidWriteData: Event<string>;
}
/**
@ -351,12 +560,12 @@ declare module 'vscode' {
/**
* The number of columns in the terminal.
*/
cols: number;
readonly columns: number;
/**
* The number of rows in the terminal.
*/
rows: number;
readonly rows: number;
}
/**
@ -368,10 +577,10 @@ declare module 'vscode' {
* created with all its APIs available for use by extensions. When using the Terminal object
* of a TerminalRenderer it acts just like normal only the extension that created the
* TerminalRenderer essentially acts as a process. For example when an
* [Terminal.onData](#Terminal.onData) listener is registered, that will fire when
* [TerminalRenderer.write](#TerminalRenderer.write) is called. Similarly when
* [Terminal.onDidWriteData](#Terminal.onDidWriteData) listener is registered, that will fire
* when [TerminalRenderer.write](#TerminalRenderer.write) is called. Similarly when
* [Terminal.sendText](#Terminal.sendText) is triggered that will fire the
* [TerminalRenderer.onInput](#TerminalRenderer.onInput) event.
* [TerminalRenderer.onDidAcceptInput](#TerminalRenderer.onDidAcceptInput) event.
*
* **Example:** Create a terminal renderer, show it and write hello world in red
* ```typescript
@ -399,7 +608,7 @@ declare module 'vscode' {
* };
* ```
*/
dimensions: TerminalDimensions;
dimensions: TerminalDimensions | undefined;
/**
* The maximum dimensions of the terminal, this will be undefined immediately after a
@ -407,12 +616,12 @@ declare module 'vscode' {
* Listen to [onDidChangeMaximumDimensions](TerminalRenderer.onDidChangeMaximumDimensions)
* to get notified when this value changes.
*/
readonly maximumDimensions: TerminalDimensions;
readonly maximumDimensions: TerminalDimensions | undefined;
/**
* The corressponding [Terminal](#Terminal) for this TerminalRenderer.
*/
readonly terminal: Thenable<Terminal>;
readonly terminal: Terminal;
/**
* Write text to the terminal. Unlike [Terminal.sendText](#Terminal.sendText) which sends
@ -441,50 +650,35 @@ declare module 'vscode' {
* workbench command such as `workbench.action.terminal.runSelectedText`
* ```typescript
* const terminalRenderer = window.createTerminalRenderer('test');
* terminalRenderer.onInput(data => {
* terminalRenderer.onDidAcceptInput(data => {
* cosole.log(data); // 'Hello world'
* });
* terminalRenderer.terminal.then(t => t.sendText('Hello world'));
* ```
*/
onInput: Event<string>;
readonly onDidAcceptInput: Event<string>;
/**
* An event which fires when the [maximum dimensions](#TerminalRenderer.maimumDimensions) of
* the terminal renderer change.
*/
onDidChangeMaximumDimensions: Event<TerminalDimensions>;
readonly onDidChangeMaximumDimensions: Event<TerminalDimensions>;
}
export namespace window {
/**
* The currently opened terminals or an empty array.
*
* @readonly
*/
export let terminals: Terminal[];
/**
* The currently active terminal or `undefined`. The active terminal is the one that
* currently has focus or most recently had focus.
*
* @readonly
*/
export let activeTerminal: Terminal | undefined;
export const activeTerminal: Terminal | undefined;
/**
* An [event](#Event) which fires when the [active terminal](#window.activeTerminal)
* has changed. *Note* that the event also fires when the active editor changes
* has changed. *Note* that the event also fires when the active terminal changes
* to `undefined`.
*/
export const onDidChangeActiveTerminal: Event<Terminal | undefined>;
/**
* An [event](#Event) which fires when a terminal has been created, either through the
* [createTerminal](#window.createTerminal) API or commands.
*/
export const onDidOpenTerminal: Event<Terminal>;
/**
* Create a [TerminalRenderer](#TerminalRenderer).
*
@ -495,22 +689,6 @@ declare module 'vscode' {
//#endregion
//#region URLs
export interface ProtocolHandler {
handleUri(uri: Uri): void;
}
export namespace window {
/**
* Registers a protocol handler capable of handling system-wide URIs.
*/
export function registerProtocolHandler(handler: ProtocolHandler): Disposable;
}
//#endregion
//#region Joh -> exclusive document filters
export interface DocumentFilter {
@ -523,20 +701,13 @@ 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.
* is easier to use. [window.createQuickPick](#window.createQuickPick) should be used
* when [window.showQuickPick](#window.showQuickPick) does not offer the required flexibility.
*
* @return A new [QuickPick](#QuickPick).
*/
@ -546,7 +717,8 @@ declare module 'vscode' {
* 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.
* is easier to use. [window.createInputBox](#window.createInputBox) should be used
* when [window.showInputBox](#window.showInputBox) does not offer the required flexibility.
*
* @return A new [InputBox](#InputBox).
*/
@ -650,7 +822,8 @@ declare module 'vscode' {
* selecting multiple items.
*
* Note that in many cases the more convenient [window.showQuickPick](#window.showQuickPick)
* is easier to use.
* is easier to use. [window.createQuickPick](#window.createQuickPick) should be used
* when [window.showQuickPick](#window.showQuickPick) does not offer the required flexibility.
*/
export interface QuickPick<T extends QuickPickItem> extends QuickInput {
@ -729,7 +902,8 @@ declare module 'vscode' {
* 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.
* is easier to use. [window.createInputBox](#window.createInputBox) should be used
* when [window.showInputBox](#window.showInputBox) does not offer the required flexibility.
*/
export interface InputBox extends QuickInput {
@ -795,6 +969,20 @@ declare module 'vscode' {
readonly tooltip?: string | undefined;
}
/**
* Predefined buttons for [QuickPick](#QuickPick) and [InputBox](#InputBox).
*/
export namespace QuickInputButtons {
/**
* 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 Back: QuickInputButton;
}
//#endregion
//#region joh: https://github.com/Microsoft/vscode/issues/10659
@ -808,6 +996,11 @@ declare module 'vscode' {
*/
export interface WorkspaceEdit {
/**
* The number of affected resources of textual or resource changes.
*/
readonly size: number;
/**
* Create a regular file.
*
@ -821,7 +1014,7 @@ declare module 'vscode' {
*
* @param uri The uri of the file that is to be deleted.
*/
deleteFile(uri: Uri): void;
deleteFile(uri: Uri, options?: { recursive?: boolean, ignoreIfNotExists?: boolean }): void;
/**
* Rename a file or folder.
@ -830,11 +1023,22 @@ declare module 'vscode' {
* @param newUri The new location.
* @param options Defines if existing files should be overwritten.
*/
renameFile(oldUri: Uri, newUri: Uri, options?: { overwrite?: boolean }): void;
renameFile(oldUri: Uri, newUri: Uri, options?: { overwrite?: boolean, ignoreIfExists?: boolean }): void;
}
// replaceText(uri: Uri, range: Range, newText: string): void;
// insertText(uri: Uri, position: Position, newText: string): void;
// deleteText(uri: Uri, range: Range): void;
export namespace workspace {
/**
* Make changes to one or many resources as defined by the given
* [workspace edit](#WorkspaceEdit).
*
* The editor implements an 'all-or-nothing'-strategy and that means failure to modify,
* delete, rename, or create one file will abort the operation. In that case, the thenable returned
* by this function resolves to `false`.
*
* @param edit A workspace edit.
* @return A thenable that resolves when the edit could be applied.
*/
export function applyEdit(edit: WorkspaceEdit): Thenable<boolean>;
}
//#endregion
@ -856,110 +1060,4 @@ declare module 'vscode' {
export const onDidRenameFile: Event<FileRenameEvent>;
}
//#endregion
//#region Matt: WebView Serializer
/**
* Restore webview panels that have been persisted when vscode shuts down.
*
* There are two types of webview persistence:
*
* - Persistence within a session.
* - Persistence across sessions (across restarts of VS Code).
*
* A `WebviewPanelSerializer` is only required for the second case: persisting a webview across sessions.
*
* Persistence within a session allows a webview to save its state when it becomes hidden
* and restore its content from this state when it becomes visible again. It is powered entirely
* by the webview content itself. To save off a persisted state, call `acquireVsCodeApi().setState()` with
* any json serializable object. To restore the state again, call `getState()`
*
* ```js
* // Within the webview
* const vscode = acquireVsCodeApi();
*
* // Get existing state
* const oldState = vscode.getState() || { value: 0 };
*
* // Update state
* setState({ value: oldState.value + 1 })
* ```
*
* A `WebviewPanelSerializer` extends this persistence across restarts of VS Code. When the editor is shutdown, VS Code will save off the state from `setState` of all webviews that have a serializer. When the
* webview first becomes visible after the restart, this state is passed to `deserializeWebviewPanel`.
* The extension can then restore the old `WebviewPanel` from this state.
*/
interface WebviewPanelSerializer {
/**
* Restore a webview panel from its seriailzed `state`.
*
* Called when a serialized webview first becomes visible.
*
* @param webviewPanel Webview panel to restore. The serializer should take ownership of this panel.
* @param state Persisted state.
*
* @return Thanble indicating that the webview has been fully restored.
*/
deserializeWebviewPanel(webviewPanel: WebviewPanel, state: any): Thenable<void>;
}
namespace window {
/**
* Registers a webview panel serializer.
*
* Extensions that support reviving should have an `"onWebviewPanel:viewType"` activation method and
* make sure that [registerWebviewPanelSerializer](#registerWebviewPanelSerializer) is called during activation.
*
* Only a single serializer may be registered at a time for a given `viewType`.
*
* @param viewType Type of the webview panel that can be serialized.
* @param serializer Webview serializer.
*/
export function registerWebviewPanelSerializer(viewType: string, serializer: WebviewPanelSerializer): Disposable;
}
//#endregion
//#region Matt: Deinition range
/**
* Information about where a symbol is defined.
*
* Provides additional metadata over normal [location](#Location) definitions, including the range of
* the defining symbol
*/
export interface DefinitionLink {
/**
* Span of the symbol being defined in the source file.
*
* Used as the underlined span for mouse definition hover. Defaults to the word range at
* the definition position.
*/
origin?: Range;
/**
* The resource identifier of the definition.
*/
uri: Uri;
/**
* The full range of the definition.
*
* For a class definition for example, this would be the entire body of the class definition.
*/
range: Range;
/**
* The span of the symbol definition.
*
* For a class definition, this would be the class name itself in the class definition.
*/
selectionRange?: Range;
}
export interface DefinitionProvider {
provideDefinition2?(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | DefinitionLink[]>;
}
//#endregion
}