vscode.proposed.d.ts 61.9 KB
Newer Older
1 2 3 4 5
/*---------------------------------------------------------------------------------------------
 *  Copyright (c) Microsoft Corporation. All rights reserved.
 *  Licensed under the MIT License. See License.txt in the project root for license information.
 *--------------------------------------------------------------------------------------------*/

6 7 8 9 10 11 12 13 14 15
/**
 * This is the place for API experiments and proposals.
 * These API are NOT stable and subject to change. They are only available in the Insiders
 * distribution and CANNOT be used in published extensions.
 *
 * To test these API in local environment:
 * - Use Insiders release of VS Code.
 * - Add `"enableProposedApi": true` to your package.json.
 * - Copy this file to your project.
 */
16

17 18
declare module 'vscode' {

J
Johannes Rieken 已提交
19 20
	// #region auth provider: https://github.com/microsoft/vscode/issues/88309

21 22 23 24 25 26 27
	/**
	 * An [event](#Event) which fires when an [AuthenticationProvider](#AuthenticationProvider) is added or removed.
	 */
	export interface AuthenticationProvidersChangeEvent {
		/**
		 * The ids of the [authenticationProvider](#AuthenticationProvider)s that have been added.
		 */
28
		readonly added: ReadonlyArray<AuthenticationProviderInformation>;
29 30

		/**
31
		 * The ids of the [authenticationProvider](#AuthenticationProvider)s that have been removed.
32
		 */
33
		readonly removed: ReadonlyArray<AuthenticationProviderInformation>;
34 35
	}

36 37 38
	/**
	* An [event](#Event) which fires when an [AuthenticationSession](#AuthenticationSession) is added, removed, or changed.
	*/
39
	export interface AuthenticationProviderAuthenticationSessionsChangeEvent {
40 41 42
		/**
		 * The ids of the [AuthenticationSession](#AuthenticationSession)s that have been added.
		*/
43
		readonly added: ReadonlyArray<string>;
44 45 46 47

		/**
		 * The ids of the [AuthenticationSession](#AuthenticationSession)s that have been removed.
		 */
48
		readonly removed: ReadonlyArray<string>;
49 50 51 52

		/**
		 * The ids of the [AuthenticationSession](#AuthenticationSession)s that have been changed.
		 */
53
		readonly changed: ReadonlyArray<string>;
54 55
	}

56 57 58 59 60
	/**
	 * **WARNING** When writing an AuthenticationProvider, `id` should be treated as part of your extension's
	 * API, changing it is a breaking change for all extensions relying on the provider. The id is
	 * treated case-sensitively.
	 */
61
	export interface AuthenticationProvider {
62 63
		/**
		 * Used as an identifier for extensions trying to work with a particular
64
		 * provider: 'microsoft', 'github', etc. id must be unique, registering
65 66
		 * another provider with the same id will fail.
		 */
67
		readonly id: string;
68

69
		/**
70
		 * The human-readable name of the provider.
71
		 */
72
		readonly label: string;
73 74 75 76 77

		/**
		 * Whether it is possible to be signed into multiple accounts at once with this provider
		*/
		readonly supportsMultipleAccounts: boolean;
78 79

		/**
80
		 * An [event](#Event) which fires when the array of sessions has changed, or data
81 82
		 * within a session has changed.
		 */
83
		readonly onDidChangeSessions: Event<AuthenticationProviderAuthenticationSessionsChangeEvent>;
84

85 86 87
		/**
		 * Returns an array of current sessions.
		 */
88
		getSessions(): Thenable<ReadonlyArray<AuthenticationSession>>;
89

90 91 92
		/**
		 * Prompts a user to login.
		 */
93
		login(scopes: string[]): Thenable<AuthenticationSession>;
94 95 96 97 98

		/**
		 * Removes the session corresponding to session id.
		 * @param sessionId The session id to log out of
		 */
99
		logout(sessionId: string): Thenable<void>;
100 101 102
	}

	export namespace authentication {
103 104 105 106 107 108 109 110 111
		/**
		 * Register an authentication provider.
		 *
		 * There can only be one provider per id and an error is being thrown when an id
		 * has already been used by another provider.
		 *
		 * @param provider The authentication provider provider.
		 * @return A [disposable](#Disposable) that unregisters this provider when being disposed.
		 */
112
		export function registerAuthenticationProvider(provider: AuthenticationProvider): Disposable;
113 114 115 116

		/**
		 * Fires with the provider id that was registered or unregistered.
		 */
117
		export const onDidChangeAuthenticationProviders: Event<AuthenticationProvidersChangeEvent>;
118

119
		/**
120
		 * @deprecated
121 122
		 * The ids of the currently registered authentication providers.
		 * @returns An array of the ids of authentication providers that are currently registered.
123
		 */
124
		export function getProviderIds(): Thenable<ReadonlyArray<string>>;
125 126

		/**
127
		 * @deprecated
128
		 * An array of the ids of authentication providers that are currently registered.
129
		 */
130
		export const providerIds: ReadonlyArray<string>;
131 132

		/**
133 134 135
		 * An array of the information of authentication providers that are currently registered.
		 */
		export const providers: ReadonlyArray<AuthenticationProviderInformation>;
136

137
		/**
138
		 * @deprecated
139 140 141 142 143 144
		* Logout of a specific session.
		* @param providerId The id of the provider to use
		* @param sessionId The session id to remove
		* provider
		*/
		export function logout(providerId: string, sessionId: string): Thenable<void>;
145 146
	}

J
Johannes Rieken 已提交
147 148
	//#endregion

A
Alex Ross 已提交
149
	//#region @alexdima - resolvers
A
Alex Dima 已提交
150

A
Tweaks  
Alex Dima 已提交
151 152 153 154
	export interface RemoteAuthorityResolverContext {
		resolveAttempt: number;
	}

A
Alex Dima 已提交
155 156 157 158 159 160 161
	export class ResolvedAuthority {
		readonly host: string;
		readonly port: number;

		constructor(host: string, port: number);
	}

162
	export interface ResolvedOptions {
R
rebornix 已提交
163
		extensionHostEnv?: { [key: string]: string | null; };
164 165
	}

166
	export interface TunnelOptions {
R
rebornix 已提交
167
		remoteAddress: { port: number, host: string; };
A
Alex Ross 已提交
168 169 170
		// The desired local port. If this port can't be used, then another will be chosen.
		localAddressPort?: number;
		label?: string;
171 172
	}

A
Alex Ross 已提交
173
	export interface TunnelDescription {
R
rebornix 已提交
174
		remoteAddress: { port: number, host: string; };
A
Alex Ross 已提交
175
		//The complete local address(ex. localhost:1234)
R
rebornix 已提交
176
		localAddress: { port: number, host: string; } | string;
A
Alex Ross 已提交
177 178 179
	}

	export interface Tunnel extends TunnelDescription {
A
Alex Ross 已提交
180 181
		// Implementers of Tunnel should fire onDidDispose when dispose is called.
		onDidDispose: Event<void>;
182
		dispose(): void;
183 184 185
	}

	/**
186 187
	 * Used as part of the ResolverResult if the extension has any candidate,
	 * published, or forwarded ports.
188 189 190 191
	 */
	export interface TunnelInformation {
		/**
		 * Tunnels that are detected by the extension. The remotePort is used for display purposes.
A
Alex Ross 已提交
192
		 * The localAddress should be the complete local address (ex. localhost:1234) for connecting to the port. Tunnels provided through
193 194
		 * detected are read-only from the forwarded ports UI.
		 */
A
Alex Ross 已提交
195
		environmentTunnels?: TunnelDescription[];
A
Alex Ross 已提交
196

197 198 199
	}

	export type ResolverResult = ResolvedAuthority & ResolvedOptions & TunnelInformation;
200

A
Tweaks  
Alex Dima 已提交
201 202 203 204 205 206 207
	export class RemoteAuthorityResolverError extends Error {
		static NotAvailable(message?: string, handled?: boolean): RemoteAuthorityResolverError;
		static TemporarilyNotAvailable(message?: string): RemoteAuthorityResolverError;

		constructor(message?: string);
	}

A
Alex Dima 已提交
208
	export interface RemoteAuthorityResolver {
209
		resolve(authority: string, context: RemoteAuthorityResolverContext): ResolverResult | Thenable<ResolverResult>;
210 211 212 213 214
		/**
		 * Can be optionally implemented if the extension can forward ports better than the core.
		 * When not implemented, the core will use its default forwarding logic.
		 * When implemented, the core will use this to forward ports.
		 */
A
Alex Ross 已提交
215
		tunnelFactory?: (tunnelOptions: TunnelOptions) => Thenable<Tunnel> | undefined;
216 217 218 219 220

		/**
		 * Provides filtering for candidate ports.
		 */
		showCandidatePort?: (host: string, port: number, detail: string) => Thenable<boolean>;
221 222 223 224
	}

	export namespace workspace {
		/**
225
		 * Forwards a port. If the current resolver implements RemoteAuthorityResolver:forwardPort then that will be used to make the tunnel.
A
Alex Ross 已提交
226
		 * By default, openTunnel only support localhost; however, RemoteAuthorityResolver:tunnelFactory can be used to support other ips.
227 228 229
		 *
		 * @throws When run in an environment without a remote.
		 *
A
Alex Ross 已提交
230
		 * @param tunnelOptions The `localPort` is a suggestion only. If that port is not available another will be chosen.
231
		 */
A
Alex Ross 已提交
232
		export function openTunnel(tunnelOptions: TunnelOptions): Thenable<Tunnel>;
233 234 235 236 237 238

		/**
		 * Gets an array of the currently available tunnels. This does not include environment tunnels, only tunnels that have been created by the user.
		 * Note that these are of type TunnelDescription and cannot be disposed.
		 */
		export let tunnels: Thenable<TunnelDescription[]>;
A
Alex Ross 已提交
239

240 241 242 243
		/**
		 * Fired when the list of tunnels has changed.
		 */
		export const onDidChangeTunnels: Event<void>;
A
Alex Dima 已提交
244 245
	}

246 247 248 249 250 251 252 253
	export interface ResourceLabelFormatter {
		scheme: string;
		authority?: string;
		formatting: ResourceLabelFormatting;
	}

	export interface ResourceLabelFormatting {
		label: string; // myLabel:/${path}
I
isidor 已提交
254
		// For historic reasons we use an or string here. Once we finalize this API we should start using enums instead and adopt it in extensions.
J
Johannes Rieken 已提交
255
		// eslint-disable-next-line vscode-dts-literal-or-types
256 257 258 259 260
		separator: '/' | '\\' | '';
		tildify?: boolean;
		normalizeDriveLetter?: boolean;
		workspaceSuffix?: string;
		authorityPrefix?: string;
261
		stripPathStartingSeparator?: boolean;
262 263
	}

A
Alex Dima 已提交
264 265
	export namespace workspace {
		export function registerRemoteAuthorityResolver(authorityPrefix: string, resolver: RemoteAuthorityResolver): Disposable;
266
		export function registerResourceLabelFormatter(formatter: ResourceLabelFormatter): Disposable;
267
	}
268

269 270
	//#endregion

J
Johannes Rieken 已提交
271
	//#region editor insets: https://github.com/microsoft/vscode/issues/85682
272

273 274
	export interface WebviewEditorInset {
		readonly editor: TextEditor;
275 276
		readonly line: number;
		readonly height: number;
277 278 279
		readonly webview: Webview;
		readonly onDidDispose: Event<void>;
		dispose(): void;
280 281
	}

282
	export namespace window {
283
		export function createWebviewTextEditorInset(editor: TextEditor, line: number, height: number, options?: WebviewOptions): WebviewEditorInset;
A
Alex Dima 已提交
284 285 286 287
	}

	//#endregion

J
Johannes Rieken 已提交
288
	//#region read/write in chunks: https://github.com/microsoft/vscode/issues/84515
289 290

	export interface FileSystemProvider {
R
rebornix 已提交
291
		open?(resource: Uri, options: { create: boolean; }): number | Thenable<number>;
292 293 294 295 296 297 298
		close?(fd: number): void | Thenable<void>;
		read?(fd: number, pos: number, data: Uint8Array, offset: number, length: number): number | Thenable<number>;
		write?(fd: number, pos: number, data: Uint8Array, offset: number, length: number): number | Thenable<number>;
	}

	//#endregion

R
Rob Lourens 已提交
299
	//#region TextSearchProvider: https://github.com/microsoft/vscode/issues/59921
300

301 302 303
	/**
	 * The parameters of a query for text search.
	 */
304
	export interface TextSearchQuery {
305 306 307
		/**
		 * The text pattern to search for.
		 */
308
		pattern: string;
309

R
Rob Lourens 已提交
310 311 312 313 314
		/**
		 * Whether or not `pattern` should match multiple lines of text.
		 */
		isMultiline?: boolean;

315 316 317
		/**
		 * Whether or not `pattern` should be interpreted as a regular expression.
		 */
R
Rob Lourens 已提交
318
		isRegExp?: boolean;
319 320 321 322

		/**
		 * Whether or not the search should be case-sensitive.
		 */
R
Rob Lourens 已提交
323
		isCaseSensitive?: boolean;
324 325 326 327

		/**
		 * Whether or not to search for whole word matches only.
		 */
R
Rob Lourens 已提交
328
		isWordMatch?: boolean;
329 330
	}

331 332
	/**
	 * A file glob pattern to match file paths against.
333
	 * TODO@roblourens merge this with the GlobPattern docs/definition in vscode.d.ts.
334 335 336 337 338 339 340
	 * @see [GlobPattern](#GlobPattern)
	 */
	export type GlobString = string;

	/**
	 * Options common to file and text search
	 */
R
Rob Lourens 已提交
341
	export interface SearchOptions {
342 343 344
		/**
		 * The root folder to search within.
		 */
345
		folder: Uri;
346 347 348 349 350 351 352 353 354 355 356 357 358 359 360

		/**
		 * 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"`.
		 */
R
Rob Lourens 已提交
361
		useIgnoreFiles: boolean;
362 363 364 365 366

		/**
		 * Whether symlinks should be followed while searching.
		 * See the vscode setting `"search.followSymlinks"`.
		 */
R
Rob Lourens 已提交
367
		followSymlinks: boolean;
P
pkoushik 已提交
368 369 370 371 372 373

		/**
		 * Whether global files that exclude files, like .gitignore, should be respected.
		 * See the vscode setting `"search.useGlobalIgnoreFiles"`.
		 */
		useGlobalIgnoreFiles: boolean;
374
	}
375

R
Rob Lourens 已提交
376 377
	/**
	 * Options to specify the size of the result text preview.
R
Rob Lourens 已提交
378
	 * These options don't affect the size of the match itself, just the amount of preview text.
R
Rob Lourens 已提交
379
	 */
380
	export interface TextSearchPreviewOptions {
381
		/**
R
Rob Lourens 已提交
382
		 * The maximum number of lines in the preview.
R
Rob Lourens 已提交
383
		 * Only search providers that support multiline search will ever return more than one line in the match.
384
		 */
R
Rob Lourens 已提交
385
		matchLines: number;
R
Rob Lourens 已提交
386 387 388 389

		/**
		 * The maximum number of characters included per line.
		 */
R
Rob Lourens 已提交
390
		charsPerLine: number;
391 392
	}

393 394 395
	/**
	 * Options that apply to text search.
	 */
R
Rob Lourens 已提交
396
	export interface TextSearchOptions extends SearchOptions {
397
		/**
398
		 * The maximum number of results to be returned.
399
		 */
400 401
		maxResults: number;

R
Rob Lourens 已提交
402 403 404
		/**
		 * Options to specify the size of the result text preview.
		 */
405
		previewOptions?: TextSearchPreviewOptions;
406 407 408 409

		/**
		 * Exclude files larger than `maxFileSize` in bytes.
		 */
410
		maxFileSize?: number;
411 412 413 414 415

		/**
		 * Interpret files using this encoding.
		 * See the vscode setting `"files.encoding"`
		 */
416
		encoding?: string;
417 418 419 420 421 422 423 424 425 426

		/**
		 * Number of lines of context to include before each match.
		 */
		beforeContext?: number;

		/**
		 * Number of lines of context to include after each match.
		 */
		afterContext?: number;
427 428
	}

429 430 431 432 433 434 435 436 437 438 439 440 441 442
	/**
	 * Information collected when text search is complete.
	 */
	export interface TextSearchComplete {
		/**
		 * Whether the search hit the limit on the maximum number of search results.
		 * `maxResults` on [`TextSearchOptions`](#TextSearchOptions) specifies the max number of results.
		 * - If exactly that number of matches exist, this should be false.
		 * - If `maxResults` matches are returned and more exist, this should be true.
		 * - If search hits an internal limit which is less than `maxResults`, this should be true.
		 */
		limitHit?: boolean;
	}

R
Rob Lourens 已提交
443 444 445
	/**
	 * A preview of the text result.
	 */
446
	export interface TextSearchMatchPreview {
447
		/**
R
Rob Lourens 已提交
448
		 * The matching lines of text, or a portion of the matching line that contains the match.
449 450 451 452 453
		 */
		text: string;

		/**
		 * The Range within `text` corresponding to the text of the match.
454
		 * The number of matches must match the TextSearchMatch's range property.
455
		 */
456
		matches: Range | Range[];
457 458 459 460 461
	}

	/**
	 * A match from a text search
	 */
462
	export interface TextSearchMatch {
463 464 465
		/**
		 * The uri for the matching document.
		 */
466
		uri: Uri;
467 468

		/**
469
		 * The range of the match within the document, or multiple ranges for multiple matches.
470
		 */
471
		ranges: Range | Range[];
R
Rob Lourens 已提交
472

473
		/**
474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495
		 * A preview of the text match.
		 */
		preview: TextSearchMatchPreview;
	}

	/**
	 * A line of context surrounding a TextSearchMatch.
	 */
	export interface TextSearchContext {
		/**
		 * The uri for the matching document.
		 */
		uri: Uri;

		/**
		 * One line of text.
		 * previewOptions.charsPerLine applies to this
		 */
		text: string;

		/**
		 * The line number of this line of context.
496
		 */
497
		lineNumber: number;
498 499
	}

500 501
	export type TextSearchResult = TextSearchMatch | TextSearchContext;

R
Rob Lourens 已提交
502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545
	/**
	 * A TextSearchProvider provides search results for text results inside files in the workspace.
	 */
	export interface TextSearchProvider {
		/**
		 * 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): ProviderResult<TextSearchComplete>;
	}

	//#endregion

	//#region FileSearchProvider: https://github.com/microsoft/vscode/issues/73524

	/**
	 * The parameters of a query for file search.
	 */
	export interface FileSearchQuery {
		/**
		 * The search pattern to match against file paths.
		 */
		pattern: string;
	}

	/**
	 * Options that apply to file search.
	 */
	export interface FileSearchOptions extends SearchOptions {
		/**
		 * The maximum number of results to be returned.
		 */
		maxResults?: number;

		/**
		 * A CancellationToken that represents the session for this search query. If the provider chooses to, this object can be used as the key for a cache,
		 * and searches with the same session object can search the same cache. When the token is cancelled, the session is complete and the cache can be cleared.
		 */
		session?: CancellationToken;
	}

546
	/**
R
Rob Lourens 已提交
547 548 549 550 551 552 553
	 * A FileSearchProvider provides search results for files in the given folder that match a query string. It can be invoked by quickopen or other extensions.
	 *
	 * A FileSearchProvider is the more powerful of two ways to implement file search in VS Code. Use a FileSearchProvider if you wish to search within a folder for
	 * all files that match the user's query.
	 *
	 * The FileSearchProvider will be invoked on every keypress in quickopen. When `workspace.findFiles` is called, it will be invoked with an empty query string,
	 * and in that case, every file in the folder should be returned.
554
	 */
555
	export interface FileSearchProvider {
556 557 558 559 560 561
		/**
		 * 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 token A cancellation token.
		 */
562
		provideFileSearchResults(query: FileSearchQuery, options: FileSearchOptions, token: CancellationToken): ProviderResult<Uri[]>;
563
	}
564

R
Rob Lourens 已提交
565
	export namespace workspace {
566
		/**
R
Rob Lourens 已提交
567 568 569 570 571 572 573
		 * 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.
574
		 */
R
Rob Lourens 已提交
575 576 577 578 579 580 581 582 583 584 585 586
		export function registerFileSearchProvider(scheme: string, provider: FileSearchProvider): Disposable;

		/**
		 * Register a text 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 registerTextSearchProvider(scheme: string, provider: TextSearchProvider): Disposable;
587 588
	}

R
Rob Lourens 已提交
589 590 591 592
	//#endregion

	//#region findTextInFiles: https://github.com/microsoft/vscode/issues/59924

593 594 595
	/**
	 * Options that can be set on a findTextInFiles search.
	 */
R
Rob Lourens 已提交
596
	export interface FindTextInFilesOptions {
597 598 599 600 601
		/**
		 * 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).
		 */
602
		include?: GlobPattern;
603 604 605

		/**
		 * A [glob pattern](#GlobPattern) that defines files and folders to exclude. The glob pattern
606 607
		 * will be matched against the file paths of resulting matches relative to their workspace. When `undefined`, default excludes will
		 * apply.
608
		 */
609 610 611 612
		exclude?: GlobPattern;

		/**
		 * Whether to use the default and user-configured excludes. Defaults to true.
613
		 */
614
		useDefaultExcludes?: boolean;
615 616 617 618

		/**
		 * The maximum number of results to search for
		 */
R
Rob Lourens 已提交
619
		maxResults?: number;
620 621 622 623 624

		/**
		 * Whether external files that exclude files, like .gitignore, should be respected.
		 * See the vscode setting `"search.useIgnoreFiles"`.
		 */
R
Rob Lourens 已提交
625
		useIgnoreFiles?: boolean;
626

P
pkoushik 已提交
627 628 629 630
		/**
		 * Whether global files that exclude files, like .gitignore, should be respected.
		 * See the vscode setting `"search.useGlobalIgnoreFiles"`.
		 */
631
		useGlobalIgnoreFiles?: boolean;
P
pkoushik 已提交
632

633 634 635 636
		/**
		 * Whether symlinks should be followed while searching.
		 * See the vscode setting `"search.followSymlinks"`.
		 */
R
Rob Lourens 已提交
637
		followSymlinks?: boolean;
638 639 640 641 642

		/**
		 * Interpret files using this encoding.
		 * See the vscode setting `"files.encoding"`
		 */
R
Rob Lourens 已提交
643
		encoding?: string;
644

R
Rob Lourens 已提交
645 646 647
		/**
		 * Options to specify the size of the result text preview.
		 */
648
		previewOptions?: TextSearchPreviewOptions;
649 650 651 652 653 654 655 656 657 658

		/**
		 * Number of lines of context to include before each match.
		 */
		beforeContext?: number;

		/**
		 * Number of lines of context to include after each match.
		 */
		afterContext?: number;
R
Rob Lourens 已提交
659 660
	}

661
	export namespace workspace {
662 663 664 665 666 667 668
		/**
		 * 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.
		 */
669
		export function findTextInFiles(query: TextSearchQuery, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable<TextSearchComplete>;
670 671 672 673 674 675 676 677 678

		/**
		 * 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.
		 */
679
		export function findTextInFiles(query: TextSearchQuery, options: FindTextInFilesOptions, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable<TextSearchComplete>;
680 681
	}

J
Johannes Rieken 已提交
682
	//#endregion
683

J
Johannes Rieken 已提交
684
	//#region diff command: https://github.com/microsoft/vscode/issues/84899
P
Pine Wu 已提交
685

J
Joao Moreno 已提交
686 687 688
	/**
	 * The contiguous set of modified lines in a diff.
	 */
J
Joao Moreno 已提交
689 690 691 692 693 694 695
	export interface LineChange {
		readonly originalStartLineNumber: number;
		readonly originalEndLineNumber: number;
		readonly modifiedStartLineNumber: number;
		readonly modifiedEndLineNumber: number;
	}

696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713
	export namespace commands {

		/**
		 * Registers a diff information command that can be invoked via a keyboard shortcut,
		 * a menu item, an action, or directly.
		 *
		 * Diff information commands are different from ordinary [commands](#commands.registerCommand) as
		 * they only execute when there is an active diff editor when the command is called, and the diff
		 * information has been computed. Also, the command handler of an editor command has access to
		 * the diff information.
		 *
		 * @param command A unique identifier for the command.
		 * @param callback A command handler function with access to the [diff information](#LineChange).
		 * @param thisArg The `this` context used when invoking the handler function.
		 * @return Disposable which unregisters this command on disposal.
		 */
		export function registerDiffInformationCommand(command: string, callback: (diff: LineChange[], ...args: any[]) => any, thisArg?: any): Disposable;
	}
714

J
Johannes Rieken 已提交
715 716
	//#endregion

J
Johannes Rieken 已提交
717
	//#region file-decorations: https://github.com/microsoft/vscode/issues/54938
718

719
	export class Decoration {
720
		letter?: string;
721 722 723
		title?: string;
		color?: ThemeColor;
		priority?: number;
724
		bubble?: boolean;
725 726
	}

727
	export interface DecorationProvider {
728
		onDidChangeDecorations: Event<undefined | Uri | Uri[]>;
729
		provideDecoration(uri: Uri, token: CancellationToken): ProviderResult<Decoration>;
730 731 732
	}

	export namespace window {
733
		export function registerDecorationProvider(provider: DecorationProvider): Disposable;
734 735 736
	}

	//#endregion
737

738
	//#region debug
739

740 741 742 743 744 745 746 747
	/**
	 * A DebugProtocolBreakpoint is an opaque stand-in type for the [Breakpoint](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Breakpoint) type defined in the Debug Adapter Protocol.
	 */
	export interface DebugProtocolBreakpoint {
		// Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Breakpoint).
	}

	export interface DebugSession {
748 749 750 751 752 753 754 755
		/**
		 * Maps a VS Code breakpoint to the corresponding Debug Adapter Protocol (DAP) breakpoint that is managed by the debug adapter of the debug session.
		 * If no DAP breakpoint exists (either because the VS Code breakpoint was not yet registered or because the debug adapter is not interested in the breakpoint), the value `undefined` is returned.
		 *
		 * @param breakpoint A VS Code [breakpoint](#Breakpoint).
		 * @return A promise that resolves to the Debug Adapter Protocol breakpoint or `undefined`.
		 */
		getDebugProtocolBreakpoint(breakpoint: Breakpoint): Thenable<DebugProtocolBreakpoint | undefined>;
756 757
	}

758
	// deprecated debug API
A
Andre Weinand 已提交
759

760
	export interface DebugConfigurationProvider {
761
		/**
A
Andre Weinand 已提交
762 763
		 * Deprecated, use DebugAdapterDescriptorFactory.provideDebugAdapter instead.
		 * @deprecated Use DebugAdapterDescriptorFactory.createDebugAdapterDescriptor instead
764 765
		 */
		debugAdapterExecutable?(folder: WorkspaceFolder | undefined, token?: CancellationToken): ProviderResult<DebugAdapterExecutable>;
766 767
	}

J
Johannes Rieken 已提交
768 769
	//#endregion

R
Rob Lourens 已提交
770
	//#region LogLevel: https://github.com/microsoft/vscode/issues/85992
J
Johannes Rieken 已提交
771

772
	/**
773
	 * @deprecated DO NOT USE, will be removed
774 775 776 777 778 779 780 781 782 783 784
	 */
	export enum LogLevel {
		Trace = 1,
		Debug = 2,
		Info = 3,
		Warning = 4,
		Error = 5,
		Critical = 6,
		Off = 7
	}

M
Matt Bierner 已提交
785 786
	export namespace env {
		/**
787
		 * @deprecated DO NOT USE, will be removed
M
Matt Bierner 已提交
788 789
		 */
		export const logLevel: LogLevel;
790 791

		/**
792
		 * @deprecated DO NOT USE, will be removed
793 794
		 */
		export const onDidChangeLogLevel: Event<LogLevel>;
M
Matt Bierner 已提交
795 796
	}

J
Johannes Rieken 已提交
797 798
	//#endregion

799
	//#region @joaomoreno: SCM validation
800

J
Joao Moreno 已提交
801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845
	/**
	 * Represents the validation type of the Source Control input.
	 */
	export enum SourceControlInputBoxValidationType {

		/**
		 * Something not allowed by the rules of a language or other means.
		 */
		Error = 0,

		/**
		 * Something suspicious but allowed.
		 */
		Warning = 1,

		/**
		 * Something to inform about but not a problem.
		 */
		Information = 2
	}

	export interface SourceControlInputBoxValidation {

		/**
		 * The validation message to display.
		 */
		readonly message: string;

		/**
		 * The validation type.
		 */
		readonly type: SourceControlInputBoxValidationType;
	}

	/**
	 * Represents the input box in the Source Control viewlet.
	 */
	export interface SourceControlInputBox {

		/**
		 * A validation function for the input box. It's possible to change
		 * the validation provider simply by setting this property to a different function.
		 */
		validateInput?(value: string, cursorPosition: number): ProviderResult<SourceControlInputBoxValidation | undefined | null>;
	}
M
Matt Bierner 已提交
846

J
Johannes Rieken 已提交
847 848
	//#endregion

849
	//#region @joaomoreno: SCM selected provider
850 851 852 853 854 855 856 857 858 859 860 861

	export interface SourceControl {

		/**
		 * Whether the source control is selected.
		 */
		readonly selected: boolean;

		/**
		 * An event signaling when the selection state changes.
		 */
		readonly onDidChangeSelection: Event<boolean>;
862 863 864 865
	}

	//#endregion

D
Daniel Imms 已提交
866
	//#region Terminal data write event https://github.com/microsoft/vscode/issues/78502
867

868 869 870 871 872 873 874 875 876 877 878
	export interface TerminalDataWriteEvent {
		/**
		 * The [terminal](#Terminal) for which the data was written.
		 */
		readonly terminal: Terminal;
		/**
		 * The data being written.
		 */
		readonly data: string;
	}

D
Daniel Imms 已提交
879 880
	namespace window {
		/**
D
Daniel Imms 已提交
881 882 883
		 * An event which fires when the terminal's child pseudo-device is written to (the shell).
		 * In other words, this provides access to the raw data stream from the process running
		 * within the terminal, including VT sequences.
D
Daniel Imms 已提交
884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904
		 */
		export const onDidWriteTerminalData: Event<TerminalDataWriteEvent>;
	}

	//#endregion

	//#region Terminal dimensions property and change event https://github.com/microsoft/vscode/issues/55718

	/**
	 * An [event](#Event) which fires when a [Terminal](#Terminal)'s dimensions change.
	 */
	export interface TerminalDimensionsChangeEvent {
		/**
		 * The [terminal](#Terminal) for which the dimensions have changed.
		 */
		readonly terminal: Terminal;
		/**
		 * The new value for the [terminal's dimensions](#Terminal.dimensions).
		 */
		readonly dimensions: TerminalDimensions;
	}
905

D
Daniel Imms 已提交
906
	export namespace window {
D
Daniel Imms 已提交
907 908 909 910 911 912 913
		/**
		 * An event which fires when the [dimensions](#Terminal.dimensions) of the terminal change.
		 */
		export const onDidChangeTerminalDimensions: Event<TerminalDimensionsChangeEvent>;
	}

	export interface Terminal {
914
		/**
915 916 917
		 * The current dimensions of the terminal. This will be `undefined` immediately after the
		 * terminal is created as the dimensions are not known until shortly after the terminal is
		 * created.
918
		 */
919
		readonly dimensions: TerminalDimensions | undefined;
D
Daniel Imms 已提交
920 921
	}

922 923
	//#endregion

924
	//#region @jrieken -> exclusive document filters
925 926 927 928 929 930

	export interface DocumentFilter {
		exclusive?: boolean;
	}

	//#endregion
C
Christof Marti 已提交
931

932
	//#region @alexdima - OnEnter enhancement
933 934 935 936 937 938 939
	export interface OnEnterRule {
		/**
		 * This rule will only execute if the text above the this line matches this regular expression.
		 */
		oneLineAboveText?: RegExp;
	}
	//#endregion
940

941
	//#region Tree View: https://github.com/microsoft/vscode/issues/61313
942 943 944 945 946 947 948 949 950 951 952
	/**
	 * Label describing the [Tree item](#TreeItem)
	 */
	export interface TreeItemLabel {

		/**
		 * A human-readable string describing the [Tree item](#TreeItem).
		 */
		label: string;

		/**
S
Sandeep Somavarapu 已提交
953
		 * Ranges in the label to highlight. A range is defined as a tuple of two number where the
S
Sandeep Somavarapu 已提交
954
		 * first is the inclusive start index and the second the exclusive end index
955
		 */
S
Sandeep Somavarapu 已提交
956
		highlights?: [number, number][];
957 958 959

	}

A
Alex Ross 已提交
960 961 962 963 964
	// https://github.com/microsoft/vscode/issues/100741
	export interface TreeDataProvider<T> {
		resolveTreeItem?(element: T, item: TreeItem2): TreeItem2 | Thenable<TreeItem2>;
	}

965 966 967 968 969 970
	export class TreeItem2 extends TreeItem {
		/**
		 * Label describing this item. When `falsy`, it is derived from [resourceUri](#TreeItem.resourceUri).
		 */
		label?: string | TreeItemLabel | /* for compilation */ any;

971 972 973 974 975
		/**
		 * Content to be shown when you hover over the tree item.
		 */
		tooltip?: string | MarkdownString | /* for compilation */ any;

976 977 978 979 980 981
		/**
		 * @param label Label describing this item
		 * @param collapsibleState [TreeItemCollapsibleState](#TreeItemCollapsibleState) of the tree item. Default is [TreeItemCollapsibleState.None](#TreeItemCollapsibleState.None)
		 */
		constructor(label: TreeItemLabel, collapsibleState?: TreeItemCollapsibleState);
	}
982
	//#endregion
983 984 985 986

	/**
	 * A task to execute
	 */
G
Gabriel DeBacker 已提交
987
	export class Task2 extends Task {
988
		detail?: string;
989
	}
G
Gabriel DeBacker 已提交
990

991
	//#region Task presentation group: https://github.com/microsoft/vscode/issues/47265
992 993 994 995 996 997 998
	export interface TaskPresentationOptions {
		/**
		 * Controls whether the task is executed in a specific terminal group using split panes.
		 */
		group?: string;
	}
	//#endregion
999

1000
	//#region Status bar item with ID and Name: https://github.com/microsoft/vscode/issues/74972
1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022

	export namespace window {

		/**
		 * Options to configure the status bar item.
		 */
		export interface StatusBarItemOptions {

			/**
			 * A unique identifier of the status bar item. The identifier
			 * is for example used to allow a user to show or hide the
			 * status bar item in the UI.
			 */
			id: string;

			/**
			 * A human readable name of the status bar item. The name is
			 * for example used as a label in the UI to show or hide the
			 * status bar item.
			 */
			name: string;

1023 1024 1025 1026 1027
			/**
			 * Accessibility information used when screen reader interacts with this status bar item.
			 */
			accessibilityInformation?: AccessibilityInformation;

1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051
			/**
			 * The alignment of the status bar item.
			 */
			alignment?: StatusBarAlignment;

			/**
			 * The priority of the status bar item. Higher value means the item should
			 * be shown more to the left.
			 */
			priority?: number;
		}

		/**
		 * Creates a status bar [item](#StatusBarItem).
		 *
		 * @param options The options of the item. If not provided, some default values
		 * will be assumed. For example, the `StatusBarItemOptions.id` will be the id
		 * of the extension and the `StatusBarItemOptions.name` will be the extension name.
		 * @return A new status bar item.
		 */
		export function createStatusBarItem(options?: StatusBarItemOptions): StatusBarItem;
	}

	//#endregion
1052

A
Alexandru Dima 已提交
1053
	//#region OnTypeRename: https://github.com/microsoft/vscode/issues/88424
1054

M
Matt Bierner 已提交
1055
	/**
P
Pine Wu 已提交
1056 1057
	 * The rename provider interface defines the contract between extensions and
	 * the live-rename feature.
1058
	 */
A
Alexandru Dima 已提交
1059
	export interface OnTypeRenameProvider {
1060
		/**
P
Pine Wu 已提交
1061
		 * Provide a list of ranges that can be live renamed together.
1062
		 *
P
Pine Wu 已提交
1063 1064 1065 1066 1067
		 * @param document The document in which the command was invoked.
		 * @param position The position at which the command was invoked.
		 * @param token A cancellation token.
		 * @return A list of ranges that can be live-renamed togehter. The ranges must have
		 * identical length and contain identical text content. The ranges cannot overlap.
1068
		 */
A
Alexandru Dima 已提交
1069
		provideOnTypeRenameRanges(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Range[]>;
1070 1071
	}

A
Alexandru Dima 已提交
1072
	namespace languages {
P
Pine Wu 已提交
1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085
		/**
		 * Register a rename provider that works on type.
		 *
		 * Multiple providers can be registered for a language. In that case providers are sorted
		 * by their [score](#languages.match) and the best-matching provider is used. Failure
		 * of the selected provider will cause a failure of the whole operation.
		 *
		 * @param selector A selector that defines the documents this provider is applicable to.
		 * @param provider An on type rename provider.
		 * @param stopPattern Stop on type renaming when input text matches the regular expression. Defaults to `^\s`.
		 * @return A [disposable](#Disposable) that unregisters this provider when being disposed.
		 */
		export function registerOnTypeRenameProvider(selector: DocumentSelector, provider: OnTypeRenameProvider, stopPattern?: RegExp): Disposable;
A
Alexandru Dima 已提交
1086 1087 1088 1089
	}

	//#endregion

1090
	//#region Custom editor move https://github.com/microsoft/vscode/issues/86146
1091

1092
	// TODO: Also for custom editor
1093

1094
	export interface CustomTextEditorProvider {
M
Matt Bierner 已提交
1095

1096 1097 1098 1099 1100 1101 1102 1103
		/**
		 * Handle when the underlying resource for a custom editor is renamed.
		 *
		 * This allows the webview for the editor be preserved throughout the rename. If this method is not implemented,
		 * VS Code will destory the previous custom editor and create a replacement one.
		 *
		 * @param newDocument New text document to use for the custom editor.
		 * @param existingWebviewPanel Webview panel for the custom editor.
1104
		 * @param token A cancellation token that indicates the result is no longer needed.
1105 1106 1107
		 *
		 * @return Thenable indicating that the webview editor has been moved.
		 */
1108
		moveCustomTextEditor?(newDocument: TextDocument, existingWebviewPanel: WebviewPanel, token: CancellationToken): Thenable<void>;
1109 1110 1111
	}

	//#endregion
1112

J
Johannes Rieken 已提交
1113
	//#region allow QuickPicks to skip sorting: https://github.com/microsoft/vscode/issues/73904
P
Peter Elmers 已提交
1114 1115 1116

	export interface QuickPick<T extends QuickPickItem> extends QuickInput {
		/**
1117 1118
		 * An optional flag to sort the final results by index of first query match in label. Defaults to true.
		 */
P
Peter Elmers 已提交
1119 1120 1121 1122
		sortByLabel: boolean;
	}

	//#endregion
M
Matt Bierner 已提交
1123

1124
	//#region @rebornix: Notebook
R
rebornix 已提交
1125

R
rebornix 已提交
1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136
	export enum CellKind {
		Markdown = 1,
		Code = 2
	}

	export enum CellOutputKind {
		Text = 1,
		Error = 2,
		Rich = 3
	}

R
rebornix 已提交
1137
	export interface CellStreamOutput {
R
rebornix 已提交
1138
		outputKind: CellOutputKind.Text;
R
rebornix 已提交
1139 1140 1141
		text: string;
	}

R
rebornix 已提交
1142
	export interface CellErrorOutput {
R
rebornix 已提交
1143
		outputKind: CellOutputKind.Error;
R
rebornix 已提交
1144 1145 1146 1147 1148 1149 1150
		/**
		 * Exception Name
		 */
		ename: string;
		/**
		 * Exception Value
		 */
R
rebornix 已提交
1151
		evalue: string;
R
rebornix 已提交
1152 1153 1154
		/**
		 * Exception call stack
		 */
R
rebornix 已提交
1155 1156 1157
		traceback: string[];
	}

R
rebornix 已提交
1158 1159 1160 1161 1162 1163 1164
	export interface NotebookCellOutputMetadata {
		/**
		 * Additional attributes of a cell metadata.
		 */
		custom?: { [key: string]: any };
	}

R
rebornix 已提交
1165
	export interface CellDisplayOutput {
R
rebornix 已提交
1166
		outputKind: CellOutputKind.Rich;
R
rebornix 已提交
1167 1168 1169 1170 1171 1172
		/**
		 * { mime_type: value }
		 *
		 * Example:
		 * ```json
		 * {
R
rebornix 已提交
1173
		 *   "outputKind": vscode.CellOutputKind.Rich,
R
rebornix 已提交
1174 1175 1176 1177 1178 1179 1180 1181 1182 1183
		 *   "data": {
		 *      "text/html": [
		 *          "<h1>Hello</h1>"
		 *       ],
		 *      "text/plain": [
		 *        "<IPython.lib.display.IFrame at 0x11dee3e80>"
		 *      ]
		 *   }
		 * }
		 */
R
rebornix 已提交
1184
		data: { [key: string]: any; };
R
rebornix 已提交
1185 1186

		readonly metadata?: NotebookCellOutputMetadata;
R
rebornix 已提交
1187 1188
	}

R
rebornix 已提交
1189
	export type CellOutput = CellStreamOutput | CellErrorOutput | CellDisplayOutput;
R
rebornix 已提交
1190

R
Rob Lourens 已提交
1191 1192 1193 1194 1195 1196 1197
	export enum NotebookCellRunState {
		Running = 1,
		Idle = 2,
		Success = 3,
		Error = 4
	}

R
Rob Lourens 已提交
1198 1199 1200 1201 1202
	export enum NotebookRunState {
		Running = 1,
		Idle = 2
	}

R
rebornix 已提交
1203
	export interface NotebookCellMetadata {
1204 1205 1206
		/**
		 * Controls if the content of a cell is editable or not.
		 */
R
rebornix 已提交
1207
		editable?: boolean;
R
rebornix 已提交
1208 1209 1210 1211 1212

		/**
		 * Controls if the cell is executable.
		 * This metadata is ignored for markdown cell.
		 */
R
rebornix 已提交
1213
		runnable?: boolean;
R
rebornix 已提交
1214

1215 1216 1217 1218 1219 1220
		/**
		 * Controls if the cell has a margin to support the breakpoint UI.
		 * This metadata is ignored for markdown cell.
		 */
		breakpointMargin?: boolean;

1221 1222 1223 1224 1225 1226
		/**
		 * Whether the [execution order](#NotebookCellMetadata.executionOrder) indicator will be displayed.
		 * Defaults to true.
		 */
		hasExecutionOrder?: boolean;

R
rebornix 已提交
1227
		/**
1228
		 * The order in which this cell was executed.
R
rebornix 已提交
1229
		 */
1230
		executionOrder?: number;
R
Rob Lourens 已提交
1231 1232 1233 1234 1235 1236 1237 1238 1239 1240

		/**
		 * A status message to be shown in the cell's status bar
		 */
		statusMessage?: string;

		/**
		 * The cell's current run state
		 */
		runState?: NotebookCellRunState;
1241 1242 1243 1244 1245 1246 1247 1248 1249 1250

		/**
		 * If the cell is running, the time at which the cell started running
		 */
		runStartTime?: number;

		/**
		 * The total duration of the cell's last run
		 */
		lastRunDuration?: number;
R
rebornix 已提交
1251

1252 1253 1254 1255 1256 1257 1258 1259 1260 1261
		/**
		 * Whether a code cell's editor is collapsed
		 */
		inputCollapsed?: boolean;

		/**
		 * Whether a code cell's outputs are collapsed
		 */
		outputCollapsed?: boolean;

R
rebornix 已提交
1262 1263 1264
		/**
		 * Additional attributes of a cell metadata.
		 */
R
rebornix 已提交
1265
		custom?: { [key: string]: any };
R
rebornix 已提交
1266 1267
	}

R
rebornix 已提交
1268
	export interface NotebookCell {
1269
		readonly notebook: NotebookDocument;
1270
		readonly uri: Uri;
R
rebornix 已提交
1271
		readonly cellKind: CellKind;
1272
		readonly document: TextDocument;
1273
		readonly language: string;
R
rebornix 已提交
1274
		outputs: CellOutput[];
R
rebornix 已提交
1275
		metadata: NotebookCellMetadata;
R
rebornix 已提交
1276 1277 1278
	}

	export interface NotebookDocumentMetadata {
1279 1280
		/**
		 * Controls if users can add or delete cells
1281
		 * Defaults to true
1282
		 */
1283
		editable?: boolean;
R
rebornix 已提交
1284

1285 1286 1287 1288 1289 1290
		/**
		 * Controls whether the full notebook can be run at once.
		 * Defaults to true
		 */
		runnable?: boolean;

1291 1292
		/**
		 * Default value for [cell editable metadata](#NotebookCellMetadata.editable).
1293
		 * Defaults to true.
1294
		 */
1295
		cellEditable?: boolean;
R
rebornix 已提交
1296 1297 1298

		/**
		 * Default value for [cell runnable metadata](#NotebookCellMetadata.runnable).
1299
		 * Defaults to true.
R
rebornix 已提交
1300
		 */
1301
		cellRunnable?: boolean;
R
rebornix 已提交
1302

1303
		/**
1304
		 * Default value for [cell hasExecutionOrder metadata](#NotebookCellMetadata.hasExecutionOrder).
1305 1306
		 * Defaults to true.
		 */
1307
		cellHasExecutionOrder?: boolean;
R
rebornix 已提交
1308 1309

		displayOrder?: GlobPattern[];
R
rebornix 已提交
1310 1311

		/**
1312
		 * Additional attributes of the document metadata.
R
rebornix 已提交
1313
		 */
1314
		custom?: { [key: string]: any };
R
Rob Lourens 已提交
1315 1316 1317 1318 1319

		/**
		 * The document's current run state
		 */
		runState?: NotebookRunState;
R
rebornix 已提交
1320 1321
	}

R
rebornix 已提交
1322 1323 1324
	export interface NotebookDocument {
		readonly uri: Uri;
		readonly fileName: string;
R
rebornix 已提交
1325
		readonly viewType: string;
R
rebornix 已提交
1326
		readonly isDirty: boolean;
R
rebornix 已提交
1327
		readonly isUntitled: boolean;
R
rebornix 已提交
1328
		readonly cells: NotebookCell[];
R
rebornix 已提交
1329
		languages: string[];
R
rebornix 已提交
1330
		displayOrder?: GlobPattern[];
1331
		metadata: NotebookDocumentMetadata;
R
rebornix 已提交
1332 1333
	}

1334
	export interface NotebookConcatTextDocument {
J
Johannes Rieken 已提交
1335
		uri: Uri;
1336 1337
		isClosed: boolean;
		dispose(): void;
1338
		onDidChange: Event<void>;
1339 1340 1341
		version: number;
		getText(): string;
		getText(range: Range): string;
1342

1343 1344
		offsetAt(position: Position): number;
		positionAt(offset: number): Position;
1345 1346 1347
		validateRange(range: Range): Range;
		validatePosition(position: Position): Position;

1348 1349
		locationAt(positionOrRange: Position | Range): Location;
		positionAt(location: Location): Position;
1350
		contains(uri: Uri): boolean
R
rebornix 已提交
1351 1352
	}

R
rebornix 已提交
1353
	export interface NotebookEditorCellEdit {
R
rebornix 已提交
1354
		insert(index: number, content: string | string[], language: string, type: CellKind, outputs: CellOutput[], metadata: NotebookCellMetadata | undefined): void;
R
rebornix 已提交
1355 1356 1357
		delete(index: number): void;
	}

R
rebornix 已提交
1358
	export interface NotebookEditor {
R
rebornix 已提交
1359 1360 1361
		/**
		 * The document associated with this notebook editor.
		 */
R
rebornix 已提交
1362
		readonly document: NotebookDocument;
R
rebornix 已提交
1363 1364 1365 1366 1367

		/**
		 * The primary selected cell on this notebook editor.
		 */
		readonly selection?: NotebookCell;
1368

R
rebornix 已提交
1369 1370 1371
		/**
		 * The column in which this editor shows.
		 */
R
rebornix 已提交
1372
		viewColumn?: ViewColumn;
1373

R
rebornix 已提交
1374 1375 1376 1377 1378 1379 1380 1381 1382 1383
		/**
		 * Whether the panel is active (focused by the user).
		 */
		readonly active: boolean;

		/**
		 * Whether the panel is visible.
		 */
		readonly visible: boolean;

R
rebornix 已提交
1384 1385 1386 1387 1388
		/**
		 * Fired when the panel is disposed.
		 */
		readonly onDidDispose: Event<void>;

1389 1390 1391 1392 1393
		/**
		 * Active kernel used in the editor
		 */
		readonly kernel?: NotebookKernel;

1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406
		/**
		 * Fired when the output hosting webview posts a message.
		 */
		readonly onDidReceiveMessage: Event<any>;
		/**
		 * Post a message to the output hosting webview.
		 *
		 * Messages are only delivered if the editor is live.
		 *
		 * @param message Body of the message. This must be a string or other json serilizable object.
		 */
		postMessage(message: any): Thenable<boolean>;

R
rebornix 已提交
1407 1408 1409 1410 1411
		/**
		 * Convert a uri for the local file system to one that can be used inside outputs webview.
		 */
		asWebviewUri(localResource: Uri): Uri;

R
rebornix 已提交
1412
		edit(callback: (editBuilder: NotebookEditorCellEdit) => void): Thenable<boolean>;
R
rebornix 已提交
1413 1414
	}

R
rebornix 已提交
1415
	export interface NotebookOutputSelector {
R
rebornix 已提交
1416
		mimeTypes?: string[];
R
rebornix 已提交
1417 1418
	}

1419 1420 1421 1422
	export interface NotebookRenderRequest {
		output: CellDisplayOutput;
		mimeType: string;
		outputId: string;
R
rebornix 已提交
1423 1424 1425
	}

	export interface NotebookOutputRenderer {
R
rebornix 已提交
1426 1427 1428
		/**
		 *
		 * @returns HTML fragment. We can probably return `CellOutput` instead of string ?
1429
		 *
R
rebornix 已提交
1430
		 */
1431 1432
		render(document: NotebookDocument, request: NotebookRenderRequest): string;

1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446
		/**
		 * Call before HTML from the renderer is executed, and will be called for
		 * every editor associated with notebook documents where the renderer
		 * is or was used.
		 *
		 * The communication object will only send and receive messages to the
		 * render API, retrieved via `acquireNotebookRendererApi`, acquired with
		 * this specific renderer's ID.
		 *
		 * If you need to keep an association between the communication object
		 * and the document for use in the `render()` method, you can use a WeakMap.
		 */
		resolveNotebook?(document: NotebookDocument, communication: NotebookCommunication): void;

1447
		readonly preloads?: Uri[];
R
rebornix 已提交
1448 1449
	}

1450
	export interface NotebookCellsChangeData {
R
rebornix 已提交
1451 1452
		readonly start: number;
		readonly deletedCount: number;
1453
		readonly deletedItems: NotebookCell[];
R
rebornix 已提交
1454
		readonly items: NotebookCell[];
R
rebornix 已提交
1455 1456
	}

R
rebornix 已提交
1457
	export interface NotebookCellsChangeEvent {
R
rebornix 已提交
1458 1459 1460 1461 1462

		/**
		 * The affected document.
		 */
		readonly document: NotebookDocument;
1463
		readonly changes: ReadonlyArray<NotebookCellsChangeData>;
R
rebornix 已提交
1464 1465
	}

R
rebornix 已提交
1466
	export interface NotebookCellMoveEvent {
R
rebornix 已提交
1467 1468

		/**
R
rebornix 已提交
1469
		 * The affected document.
R
rebornix 已提交
1470
		 */
R
rebornix 已提交
1471
		readonly document: NotebookDocument;
R
rebornix 已提交
1472
		readonly index: number;
R
rebornix 已提交
1473
		readonly newIndex: number;
R
rebornix 已提交
1474 1475
	}

1476
	export interface NotebookCellOutputsChangeEvent {
R
rebornix 已提交
1477 1478 1479 1480 1481

		/**
		 * The affected document.
		 */
		readonly document: NotebookDocument;
1482
		readonly cells: NotebookCell[];
R
rebornix 已提交
1483 1484 1485
	}

	export interface NotebookCellLanguageChangeEvent {
R
rebornix 已提交
1486 1487

		/**
R
rebornix 已提交
1488
		 * The affected document.
R
rebornix 已提交
1489
		 */
R
rebornix 已提交
1490 1491 1492
		readonly document: NotebookDocument;
		readonly cell: NotebookCell;
		readonly language: string;
R
rebornix 已提交
1493 1494
	}

1495 1496 1497
	export interface NotebookCellMetadataChangeEvent {
		readonly document: NotebookDocument;
		readonly cell: NotebookCell;
R
rebornix 已提交
1498 1499
	}

R
rebornix 已提交
1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513
	export interface NotebookCellData {
		readonly cellKind: CellKind;
		readonly source: string;
		language: string;
		outputs: CellOutput[];
		metadata: NotebookCellMetadata;
	}

	export interface NotebookData {
		readonly cells: NotebookCellData[];
		readonly languages: string[];
		readonly metadata: NotebookDocumentMetadata;
	}

1514 1515 1516 1517 1518 1519 1520 1521
	interface NotebookDocumentContentChangeEvent {

		/**
		 * The document that the edit is for.
		 */
		readonly document: NotebookDocument;
	}

R
rebornix 已提交
1522 1523 1524 1525 1526 1527
	interface NotebookDocumentEditEvent {

		/**
		 * The document that the edit is for.
		 */
		readonly document: NotebookDocument;
1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552

		/**
		 * Undo the edit operation.
		 *
		 * This is invoked by VS Code when the user undoes this edit. To implement `undo`, your
		 * extension should restore the document and editor to the state they were in just before this
		 * edit was added to VS Code's internal edit stack by `onDidChangeCustomDocument`.
		 */
		undo(): Thenable<void> | void;

		/**
		 * Redo the edit operation.
		 *
		 * This is invoked by VS Code when the user redoes this edit. To implement `redo`, your
		 * extension should restore the document and editor to the state they were in just after this
		 * edit was added to VS Code's internal edit stack by `onDidChangeCustomDocument`.
		 */
		redo(): Thenable<void> | void;

		/**
		 * Display name describing the edit.
		 *
		 * This will be shown to users in the UI for undo/redo operations.
		 */
		readonly label?: string;
R
rebornix 已提交
1553 1554
	}

1555 1556 1557 1558
	interface NotebookDocumentBackup {
		/**
		 * Unique identifier for the backup.
		 *
R
rebornix 已提交
1559
		 * This id is passed back to your extension in `openCustomDocument` when opening a notebook editor from a backup.
1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579
		 */
		readonly id: string;

		/**
		 * Delete the current backup.
		 *
		 * This is called by VS Code when it is clear the current backup is no longer needed, such as when a new backup
		 * is made or when the file is saved.
		 */
		delete(): void;
	}

	interface NotebookDocumentBackupContext {
		readonly destination: Uri;
	}

	interface NotebookDocumentOpenContext {
		readonly backupId?: string;
	}

1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609
	/**
	 * Communication object passed to the {@link NotebookContentProvider} and
	 * {@link NotebookOutputRenderer} to communicate with the webview.
	 */
	export interface NotebookCommunication {
		/**
		 * ID of the editor this object communicates with. A single notebook
		 * document can have multiple attached webviews and editors, when the
		 * notebook is split for instance. The editor ID lets you differentiate
		 * between them.
		 */
		readonly editorId: string;

		/**
		 * Fired when the output hosting webview posts a message.
		 */
		readonly onDidReceiveMessage: Event<any>;
		/**
		 * Post a message to the output hosting webview.
		 *
		 * Messages are only delivered if the editor is live.
		 *
		 * @param message Body of the message. This must be a string or other json serilizable object.
		 */
		postMessage(message: any): Thenable<boolean>;

		/**
		 * Convert a uri for the local file system to one that can be used inside outputs webview.
		 */
		asWebviewUri(localResource: Uri): Uri;
R
rebornix 已提交
1610 1611
	}

R
rebornix 已提交
1612
	export interface NotebookContentProvider {
1613 1614 1615 1616
		/**
		 * Content providers should always use [file system providers](#FileSystemProvider) to
		 * resolve the raw content for `uri` as the resouce is not necessarily a file on disk.
		 */
1617
		openNotebook(uri: Uri, openContext: NotebookDocumentOpenContext): NotebookData | Promise<NotebookData>;
1618
		resolveNotebook(document: NotebookDocument, webview: NotebookCommunication): Promise<void>;
R
rebornix 已提交
1619 1620
		saveNotebook(document: NotebookDocument, cancellation: CancellationToken): Promise<void>;
		saveNotebookAs(targetResource: Uri, document: NotebookDocument, cancellation: CancellationToken): Promise<void>;
R
rebornix 已提交
1621
		readonly onDidChangeNotebook: Event<NotebookDocumentContentChangeEvent | NotebookDocumentEditEvent>;
R
rebornix 已提交
1622
		backupNotebook(document: NotebookDocument, context: NotebookDocumentBackupContext, cancellation: CancellationToken): Promise<NotebookDocumentBackup>;
R
rebornix 已提交
1623

R
rebornix 已提交
1624
		kernel?: NotebookKernel;
R
rebornix 已提交
1625 1626
	}

R
rebornix 已提交
1627
	export interface NotebookKernel {
R
rebornix 已提交
1628
		readonly id?: string;
R
rebornix 已提交
1629
		label: string;
R
rebornix 已提交
1630 1631
		description?: string;
		isPreferred?: boolean;
R
rebornix 已提交
1632
		preloads?: Uri[];
R
Rob Lourens 已提交
1633 1634 1635 1636
		executeCell(document: NotebookDocument, cell: NotebookCell): void;
		cancelCellExecution(document: NotebookDocument, cell: NotebookCell): void;
		executeAllCells(document: NotebookDocument): void;
		cancelAllCellsExecution(document: NotebookDocument): void;
R
rebornix 已提交
1637 1638
	}

R
rebornix 已提交
1639 1640 1641 1642 1643 1644 1645 1646 1647 1648
	export interface NotebookDocumentFilter {
		viewType?: string;
		filenamePattern?: GlobPattern;
		excludeFileNamePattern?: GlobPattern;
	}

	export interface NotebookKernelProvider<T extends NotebookKernel = NotebookKernel> {
		onDidChangeKernels?: Event<void>;
		provideKernels(document: NotebookDocument, token: CancellationToken): ProviderResult<T[]>;
		resolveKernel?(kernel: T, document: NotebookDocument, webview: NotebookCommunication, token: CancellationToken): ProviderResult<void>;
R
rebornix 已提交
1649 1650
	}

R
rebornix 已提交
1651
	export namespace notebook {
R
rebornix 已提交
1652
		export function registerNotebookContentProvider(
R
rebornix 已提交
1653
			notebookType: string,
R
rebornix 已提交
1654 1655 1656
			provider: NotebookContentProvider
		): Disposable;

R
rebornix 已提交
1657 1658 1659 1660 1661
		export function registerNotebookKernelProvider(
			selector: NotebookDocumentFilter,
			provider: NotebookKernelProvider
		): Disposable;

R
rebornix 已提交
1662 1663 1664 1665 1666 1667
		export function registerNotebookKernel(
			id: string,
			selectors: GlobPattern[],
			kernel: NotebookKernel
		): Disposable;

R
rebornix 已提交
1668
		export function registerNotebookOutputRenderer(
R
rebornix 已提交
1669
			id: string,
R
rebornix 已提交
1670 1671
			outputSelector: NotebookOutputSelector,
			renderer: NotebookOutputRenderer
R
rebornix 已提交
1672
		): Disposable;
R
rebornix 已提交
1673

R
rebornix 已提交
1674
		export const onDidOpenNotebookDocument: Event<NotebookDocument>;
R
rebornix 已提交
1675
		export const onDidCloseNotebookDocument: Event<NotebookDocument>;
R
rebornix 已提交
1676
		export const onDidSaveNotebookDocument: Event<NotebookDocument>;
R
rebornix 已提交
1677

1678 1679 1680 1681
		/**
		 * All currently known notebook documents.
		 */
		export const notebookDocuments: ReadonlyArray<NotebookDocument>;
R
rebornix 已提交
1682

R
rebornix 已提交
1683 1684
		export let visibleNotebookEditors: NotebookEditor[];
		export const onDidChangeVisibleNotebookEditors: Event<NotebookEditor[]>;
1685

R
rebornix 已提交
1686
		export let activeNotebookEditor: NotebookEditor | undefined;
R
rebornix 已提交
1687
		export const onDidChangeActiveNotebookEditor: Event<NotebookEditor | undefined>;
R
rebornix 已提交
1688
		export const onDidChangeNotebookCells: Event<NotebookCellsChangeEvent>;
1689
		export const onDidChangeCellOutputs: Event<NotebookCellOutputsChangeEvent>;
R
rebornix 已提交
1690
		export const onDidChangeCellLanguage: Event<NotebookCellLanguageChangeEvent>;
1691
		export const onDidChangeCellMetadata: Event<NotebookCellMetadataChangeEvent>;
1692
		/**
J
Johannes Rieken 已提交
1693 1694
		 * Create a document that is the concatenation of all  notebook cells. By default all code-cells are included
		 * but a selector can be provided to narrow to down the set of cells.
1695 1696 1697 1698 1699
		 *
		 * @param notebook
		 * @param selector
		 */
		export function createConcatTextDocument(notebook: NotebookDocument, selector?: DocumentSelector): NotebookConcatTextDocument;
M
Martin Aeschlimann 已提交
1700

R
rebornix 已提交
1701
		export const onDidChangeActiveNotebookKernel: Event<{ document: NotebookDocument, kernel: NotebookKernel | undefined }>;
M
Martin Aeschlimann 已提交
1702 1703
	}

1704 1705 1706 1707
	//#endregion

	//#region https://github.com/microsoft/vscode/issues/39441

P
label2  
Pine Wu 已提交
1708 1709 1710 1711
	export interface CompletionItem {
		/**
		 * Will be merged into CompletionItem#label
		 */
P
Pine Wu 已提交
1712
		label2?: CompletionItemLabel;
P
label2  
Pine Wu 已提交
1713 1714
	}

1715 1716
	export interface CompletionItemLabel {
		/**
P
Pine Wu 已提交
1717
		 * The function or variable. Rendered leftmost.
1718
		 */
P
Pine Wu 已提交
1719
		name: string;
1720

P
Pine Wu 已提交
1721
		/**
1722
		 * The parameters without the return type. Render after `name`.
P
Pine Wu 已提交
1723
		 */
1724
		parameters?: string;
P
Pine Wu 已提交
1725 1726

		/**
P
Pine Wu 已提交
1727
		 * The fully qualified name, like package name or file path. Rendered after `signature`.
P
Pine Wu 已提交
1728 1729
		 */
		qualifier?: string;
1730

P
Pine Wu 已提交
1731
		/**
P
Pine Wu 已提交
1732
		 * The return-type of a function or type of a property/variable. Rendered rightmost.
P
Pine Wu 已提交
1733
		 */
P
Pine Wu 已提交
1734
		type?: string;
1735 1736 1737 1738
	}

	//#endregion

1739
	//#region @eamodio - timeline: https://github.com/microsoft/vscode/issues/84297
1740 1741 1742

	export class TimelineItem {
		/**
1743
		 * A timestamp (in milliseconds since 1 January 1970 00:00:00) for when the timeline item occurred.
1744
		 */
E
Eric Amodio 已提交
1745
		timestamp: number;
1746 1747

		/**
1748
		 * A human-readable string describing the timeline item.
1749 1750 1751 1752
		 */
		label: string;

		/**
1753
		 * Optional id for the timeline item. It must be unique across all the timeline items provided by this source.
1754
		 *
1755
		 * If not provided, an id is generated using the timeline item's timestamp.
1756 1757 1758 1759
		 */
		id?: string;

		/**
1760
		 * The icon path or [ThemeIcon](#ThemeIcon) for the timeline item.
1761
		 */
R
rebornix 已提交
1762
		iconPath?: Uri | { light: Uri; dark: Uri; } | ThemeIcon;
1763 1764

		/**
1765
		 * A human readable string describing less prominent details of the timeline item.
1766 1767 1768 1769 1770 1771
		 */
		description?: string;

		/**
		 * The tooltip text when you hover over the timeline item.
		 */
1772
		detail?: string;
1773 1774 1775 1776 1777 1778 1779

		/**
		 * The [command](#Command) that should be executed when the timeline item is selected.
		 */
		command?: Command;

		/**
1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795
		 * Context value of the timeline item. This can be used to contribute specific actions to the item.
		 * For example, a timeline item is given a context value as `commit`. When contributing actions to `timeline/item/context`
		 * using `menus` extension point, you can specify context value for key `timelineItem` in `when` expression like `timelineItem == commit`.
		 * ```
		 *	"contributes": {
		 *		"menus": {
		 *			"timeline/item/context": [
		 *				{
		 *					"command": "extension.copyCommitId",
		 *					"when": "timelineItem == commit"
		 *				}
		 *			]
		 *		}
		 *	}
		 * ```
		 * This will show the `extension.copyCommitId` action only for items where `contextValue` is `commit`.
1796 1797 1798
		 */
		contextValue?: string;

1799 1800 1801 1802 1803
		/**
		 * Accessibility information used when screen reader interacts with this timeline item.
		 */
		accessibilityInformation?: AccessibilityInformation;

1804 1805
		/**
		 * @param label A human-readable string describing the timeline item
E
Eric Amodio 已提交
1806
		 * @param timestamp A timestamp (in milliseconds since 1 January 1970 00:00:00) for when the timeline item occurred
1807
		 */
E
Eric Amodio 已提交
1808
		constructor(label: string, timestamp: number);
1809 1810
	}

1811
	export interface TimelineChangeEvent {
E
Eric Amodio 已提交
1812
		/**
1813
		 * The [uri](#Uri) of the resource for which the timeline changed.
E
Eric Amodio 已提交
1814
		 */
E
Eric Amodio 已提交
1815
		uri: Uri;
1816

E
Eric Amodio 已提交
1817
		/**
1818
		 * A flag which indicates whether the entire timeline should be reset.
E
Eric Amodio 已提交
1819
		 */
1820 1821
		reset?: boolean;
	}
E
Eric Amodio 已提交
1822

1823 1824 1825
	export interface Timeline {
		readonly paging?: {
			/**
E
Eric Amodio 已提交
1826
			 * A provider-defined cursor specifying the starting point of timeline items which are after the ones returned.
E
Eric Amodio 已提交
1827
			 * Use `undefined` to signal that there are no more items to be returned.
1828
			 */
E
Eric Amodio 已提交
1829
			readonly cursor: string | undefined;
R
rebornix 已提交
1830
		};
E
Eric Amodio 已提交
1831 1832

		/**
1833
		 * An array of [timeline items](#TimelineItem).
E
Eric Amodio 已提交
1834
		 */
1835
		readonly items: readonly TimelineItem[];
E
Eric Amodio 已提交
1836 1837
	}

1838
	export interface TimelineOptions {
E
Eric Amodio 已提交
1839
		/**
E
Eric Amodio 已提交
1840
		 * A provider-defined cursor specifying the starting point of the timeline items that should be returned.
E
Eric Amodio 已提交
1841
		 */
1842
		cursor?: string;
E
Eric Amodio 已提交
1843 1844

		/**
1845 1846
		 * An optional maximum number timeline items or the all timeline items newer (inclusive) than the timestamp or id that should be returned.
		 * If `undefined` all timeline items should be returned.
E
Eric Amodio 已提交
1847
		 */
R
rebornix 已提交
1848
		limit?: number | { timestamp: number; id?: string; };
E
Eric Amodio 已提交
1849 1850
	}

1851
	export interface TimelineProvider {
1852
		/**
1853 1854
		 * An optional event to signal that the timeline for a source has changed.
		 * To signal that the timeline for all resources (uris) has changed, do not pass any argument or pass `undefined`.
1855
		 */
E
Eric Amodio 已提交
1856
		onDidChange?: Event<TimelineChangeEvent | undefined>;
1857 1858

		/**
1859
		 * An identifier of the source of the timeline items. This can be used to filter sources.
1860
		 */
1861
		readonly id: string;
1862

E
Eric Amodio 已提交
1863
		/**
1864
		 * A human-readable string describing the source of the timeline items. This can be used as the display label when filtering sources.
E
Eric Amodio 已提交
1865
		 */
1866
		readonly label: string;
1867 1868

		/**
E
Eric Amodio 已提交
1869
		 * Provide [timeline items](#TimelineItem) for a [Uri](#Uri).
1870
		 *
1871
		 * @param uri The [uri](#Uri) of the file to provide the timeline for.
1872
		 * @param options A set of options to determine how results should be returned.
1873
		 * @param token A cancellation token.
E
Eric Amodio 已提交
1874
		 * @return The [timeline result](#TimelineResult) or a thenable that resolves to such. The lack of a result
1875 1876
		 * can be signaled by returning `undefined`, `null`, or an empty array.
		 */
1877
		provideTimeline(uri: Uri, options: TimelineOptions, token: CancellationToken): ProviderResult<Timeline>;
1878 1879 1880 1881 1882 1883 1884 1885 1886 1887
	}

	export namespace workspace {
		/**
		 * Register a timeline provider.
		 *
		 * Multiple providers can be registered. In that case, providers are asked in
		 * parallel and the results are merged. A failing provider (rejected promise or exception) will
		 * not cause a failure of the whole operation.
		 *
1888
		 * @param scheme A scheme or schemes that defines which documents this provider is applicable to. Can be `*` to target all documents.
1889 1890
		 * @param provider A timeline provider.
		 * @return A [disposable](#Disposable) that unregisters this provider when being disposed.
E
Eric Amodio 已提交
1891
		*/
1892
		export function registerTimelineProvider(scheme: string | string[], provider: TimelineProvider): Disposable;
1893 1894 1895
	}

	//#endregion
1896

1897
	//#region https://github.com/microsoft/vscode/issues/91555
1898

1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912
	export enum StandardTokenType {
		Other = 0,
		Comment = 1,
		String = 2,
		RegEx = 4
	}

	export interface TokenInformation {
		type: StandardTokenType;
		range: Range;
	}

	export namespace languages {
		export function getTokenInformationAtPosition(document: TextDocument, position: Position): Promise<TokenInformation>;
1913 1914 1915
	}

	//#endregion
1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940

	//#region Support `scmResourceState` in `when` clauses #86180 https://github.com/microsoft/vscode/issues/86180

	export interface SourceControlResourceState {
		/**
		 * Context value of the resource state. This can be used to contribute resource specific actions.
		 * For example, if a resource is given a context value as `diffable`. When contributing actions to `scm/resourceState/context`
		 * using `menus` extension point, you can specify context value for key `scmResourceState` in `when` expressions, like `scmResourceState == diffable`.
		 * ```
		 *	"contributes": {
		 *		"menus": {
		 *			"scm/resourceState/context": [
		 *				{
		 *					"command": "extension.diff",
		 *					"when": "scmResourceState == diffable"
		 *				}
		 *			]
		 *		}
		 *	}
		 * ```
		 * This will show action `extension.diff` only for resources with `contextValue` is `diffable`.
		 */
		readonly contextValue?: string;
	}

1941
	//#endregion
1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960

	//#region https://github.com/microsoft/vscode/issues/104436

	export enum ExtensionRuntime {
		/**
		 * The extension is running in a NodeJS extension host. Runtime access to NodeJS APIs is available.
		 */
		Node = 1,
		/**
		 * The extension is running in a Webworker extension host. Runtime access is limited to Webworker APIs.
		 */
		Webworker = 2
	}

	export interface ExtensionContext {
		readonly extensionRuntime: ExtensionRuntime;
	}

	//#endregion
1961 1962 1963 1964 1965


	//#region https://github.com/microsoft/vscode/issues/102091

	export interface TextDocument {
1966 1967 1968 1969 1970

		/**
		 * The [notebook](#NotebookDocument) that contains this document as a notebook cell or `undefined` when
		 * the document is not contained by a notebook (this should be the more frequent case).
		 */
1971 1972 1973
		notebook: NotebookDocument | undefined;
	}
	//#endregion
1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110


	//#region https://github.com/microsoft/vscode/issues/46585

	/**
	 * A webview based view.
	 */
	export interface WebviewView {
		/**
		 * Identifies the type of the webview view, such as `'hexEditor.dataView'`.
		 */
		readonly viewType: string;

		/**
		 * The underlying webview for the view.
		 */
		readonly webview: Webview;

		/**
		 * View title displayed in the UI.
		 *
		 * The view title is initially taken from the extension `package.json` contribution.
		 */
		title?: string;

		/**
		 * Event fired when the view is disposed.
		 *
		 * Views are disposed of in a few cases:
		 *
		 * - When a view is collapsed and `retainContextWhenHidden` has not been set.
		 * - When a view is hidden by a user.
		 *
		 * Trying to use the view after it has been disposed throws an exception.
		 */
		readonly onDidDispose: Event<void>;

		/**
		 * Tracks if the webview is currently visible.
		 *
		 * Views are visible when they are on the screen and expanded.
		 */
		readonly visible: boolean;

		/**
		 * Event fired when the visibility of the view changes
		 */
		readonly onDidChangeVisibility: Event<void>;
	}

	interface WebviewViewResolveContext<T = unknown> {
		/**
		 * Persisted state from the webview content.
		 *
		 * To save resources, VS Code normally deallocates webview views that are not visible. For example, if the user
		 * collapse a view or switching to another top level activity, the underlying webview document is deallocates.
		 *
		 * You can prevent this behavior by setting `retainContextWhenHidden` in the `WebviewOptions`. However this
		 * increases resource usage and should be avoided wherever possible. Instead, you can use persisted state to
		 * save off a webview's state so that it can be quickly recreated as needed.
		 *
		 * To save off a persisted state, inside the webview call `acquireVsCodeApi().setState()` with
		 * any json serializable object. To restore the state again, call `getState()`. For example:
		 *
		 * ```js
		 * // Within the webview
		 * const vscode = acquireVsCodeApi();
		 *
		 * // Get existing state
		 * const oldState = vscode.getState() || { value: 0 };
		 *
		 * // Update state
		 * setState({ value: oldState.value + 1 })
		 * ```
		 *
		 * VS Code ensures that the persisted state is saved correctly when a webview is hidden and across
		 * editor restarts.
		 */
		readonly state: T | undefined;
	}

	/**
	 * Provider for creating `WebviewView` elements.
	 */
	export interface WebviewViewProvider {
		/**
		 * Revolves a webview view.
		 *
		 * `resolveWebviewView` is called when a view first becomes visible. This may happen when the view is
		 * first loaded or when the user hides and then shows a view again.
		 *
		 * @param webviewView Webview panel to restore. The serializer should take ownership of this panel. The
		 *    provider must set the webview's `.html` and hook up all webview events it is interested in.
		 * @param context Additional metadata about the view being resolved.
		 * @param token Cancellation token indicating that the view being provided is no longer needed.
		 *
		 * @return Optional thenable indicating that the view has been fully resolved.
		 */
		resolveWebviewView(webviewView: WebviewView, context: WebviewViewResolveContext, token: CancellationToken): Thenable<void> | void;
	}

	namespace window {
		/**
		 * Register a new provider for webview views.
		 *
		 * @param viewId Unique id of the view. This should match the `id` from the
		 *   `views` contribution in the package.json.
		 * @param provider Provider for the webview views.
		 *
		 * @return Disposable that unregisters the provider.
		 */
		export function registerWebviewViewProvider(viewId: string, provider: WebviewViewProvider, options?: {
			/**
			 * Content settings for the webview created for this view.
			 */
			readonly webviewOptions?: {
				/**
				 * Controls if the webview panel's content (iframe) is kept around even when the panel
				 * is no longer visible.
				 *
				 * Normally the webview's html context is created when the panel becomes visible
				 * and destroyed when it is hidden. Extensions that have complex state
				 * or UI can set the `retainContextWhenHidden` to make VS Code keep the webview
				 * context around, even when the webview moves to a background tab. When a webview using
				 * `retainContextWhenHidden` becomes hidden, its scripts and other dynamic content are suspended.
				 * When the panel becomes visible again, the context is automatically restored
				 * in the exact same state it was in originally. You cannot send messages to a
				 * hidden webview, even with `retainContextWhenHidden` enabled.
				 *
				 * `retainContextWhenHidden` has a high memory overhead and should only be used if
				 * your panel's context cannot be quickly saved and restored.
				 */
				readonly retainContextWhenHidden?: boolean;
			};
		}): Disposable;
	}
	//#endregion
J
Johannes Rieken 已提交
2111
}