From 081909fb45694a8b46fafe6e8c042c04ba741e03 Mon Sep 17 00:00:00 2001 From: Christof Marti Date: Mon, 23 Jul 2018 11:21:06 +0200 Subject: [PATCH] Catch up with API polish --- quickinput-sample/src/multiStepInput.ts | 10 +- quickinput-sample/src/vscode.proposed.d.ts | 464 +++++++++++++-------- 2 files changed, 286 insertions(+), 188 deletions(-) diff --git a/quickinput-sample/src/multiStepInput.ts b/quickinput-sample/src/multiStepInput.ts index 2b753ab4..9219c2ee 100644 --- a/quickinput-sample/src/multiStepInput.ts +++ b/quickinput-sample/src/multiStepInput.ts @@ -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(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(item); diff --git a/quickinput-sample/src/vscode.proposed.d.ts b/quickinput-sample/src/vscode.proposed.d.ts index e342923c..f9a3ea37 100644 --- a/quickinput-sample/src/vscode.proposed.d.ts +++ b/quickinput-sample/src/vscode.proposed.d.ts @@ -13,46 +13,255 @@ declare module 'vscode' { export function sampleFunction(): Thenable; } - //#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, token: CancellationToken): Thenable; + /** + * 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, token: CancellationToken): Thenable; + + /** + * 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, token: CancellationToken): Thenable; } + /** + * 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; + + /** + * 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; } //#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; + onDidWriteData: Event; } /** @@ -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; + 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; + readonly onDidAcceptInput: Event; /** * An event which fires when the [maximum dimensions](#TerminalRenderer.maimumDimensions) of * the terminal renderer change. */ - onDidChangeMaximumDimensions: Event; + readonly onDidChangeMaximumDimensions: Event; } 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; - /** - * An [event](#Event) which fires when a terminal has been created, either through the - * [createTerminal](#window.createTerminal) API or commands. - */ - export const onDidOpenTerminal: Event; - /** * 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 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; } //#endregion @@ -856,110 +1060,4 @@ declare module 'vscode' { export const onDidRenameFile: Event; } //#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; - } - - 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; - } - - //#endregion }