31
&& typeof candidate?.isResolved === 'function';
32
}
34
>
export interface IBaseUntypedEditorInput {
35
>
36
>
/**
37
>
* Optional options to use when opening the input.
38
>
*/
39
>
options?: IEditorOptions;
40
>
41
>
/**
42
>
* Label to show for the input.
43
>
*/
44
>
readonly label?: string;
45
>
46
>
/**
47
>
* Description to show for the input.
48
>
*/
49
>
readonly description?: string;
50
>
}
51
>
52
>
export interface IBaseResourceEditorInput extends IBaseUntypedEditorInput {
53
>
54
>
/**
55
>
* Hint to indicate that this input should be treated as a
56
>
* untitled file.
57
>
*
58
>
* Without this hint, the editor service will make a guess by
59
>
* looking at the scheme of the resource(s).
60
>
*
61
>
* Use `forceUntitled: true` when you pass in a `resource` that
62
>
* does not use the `untitled` scheme. The `resource` will then
63
>
* be used as associated path when saving the untitled file.
64
>
*/
65
>
readonly forceUntitled?: boolean;
66
>
}
67
>
68
>
export interface IBaseTextResourceEditorInput extends IBaseResourceEditorInput {
69
>
70
>
/**
71
>
* Optional options to use when opening the text input.
72
>
*/
73
>
options?: ITextEditorOptions;
74
>
75
>
/**
76
>
* The contents of the text input if known. If provided,
77
>
* the input will not attempt to load the contents from
78
>
* disk and may appear dirty.
79
>
*/
80
>
contents?: string;
81
>
82
>
/**
83
>
* The encoding of the text input if known.
84
>
*/
85
>
encoding?: string;
86
>
87
>
/**
88
>
* The identifier of the language id of the text input
89
>
* if known to use when displaying the contents.
90
>
*/
91
>
languageId?: string;
92
>
}
93
>
94
>
export interface IResourceEditorInput extends IBaseResourceEditorInput {
95
>
96
>
/**
97
>
* The resource URI of the resource to open.
98
>
*/
99
>
readonly resource: URI;
100
>
}
101
>
102
>
export interface ITextResourceEditorInput extends IResourceEditorInput, IBaseTextResourceEditorInput {
103
>
104
>
/**
105
>
* Optional options to use when opening the text input.
106
>
*/
107
>
options?: ITextEditorOptions;
108
>
}
109
>
110
>
/**
111
>
* This identifier allows to uniquely identify an editor with a
112
>
* resource, type and editor identifier.
113
>
*/
114
>
export interface IResourceEditorInputIdentifier {
115
>
116
>
/**
117
>
* The type of the editor.
118
>
*/
119
>
readonly typeId: string;
120
>
121
>
/**
122
>
* The identifier of the editor if provided.
123
>
*/
124
>
readonly editorId: string | undefined;
125
>
126
>
/**
127
>
* The resource URI of the editor.
128
>
*/
129
>
readonly resource: URI;
130
>
}
131
>
132
>
export enum EditorActivation {
133
>
134
>
/**
135
>
* Activate the editor after it opened. This will automatically restore
136
>
* the editor if it is minimized.
137
>
*/
138
>
ACTIVATE = 1,
139
>
140
>
/**
141
>
* Only restore the editor if it is minimized but do not activate it.
142
>
*
143
>
* Note: will only work in combination with the `preserveFocus: true` option.
144
>
* Otherwise, if focus moves into the editor, it will activate and restore
145
>
* automatically.
146
>
*/
147
>
RESTORE,
148
>
149
>
/**
150
>
* Preserve the current active editor.
151
>
*
152
>
* Note: will only work in combination with the `preserveFocus: true` option.
153
>
* Otherwise, if focus moves into the editor, it will activate and restore
154
>
* automatically.
155
>
*/
156
>
PRESERVE
157
>
}
158
>
159
>
export enum EditorResolution {
160
>
161
>
/**
162
>
* Displays a picker and allows the user to decide which editor to use.
163
>
*/
164
>
PICK,
165
>
166
>
/**
167
>
* Only exclusive editors are considered.
168
>
*/
169
>
EXCLUSIVE_ONLY
170
>
}
171
>
172
>
export enum EditorOpenSource {
173
>
174
>
/**
175
>
* Default: the editor is opening via a programmatic call
176
>
* to the editor service API.
177
>
*/
178
>
API,
179
>
180
>
/**
181
>
* Indicates that a user action triggered the opening, e.g.
182
>
* via mouse or keyboard use.
183
>
*/
184
>
USER
185
>
}
186
>
187
>
export interface IEditorOptions {
188
>
189
>
/**
190
>
* Tells the editor to not receive keyboard focus when the editor is being opened.
191
>
*
192
>
* Will also not activate the group the editor opens in unless the group is already
193
>
* the active one. This behaviour can be overridden via the `activation` option.
194
>
*/
195
>
preserveFocus?: boolean;
196
>
197
>
/**
198
>
* This option is only relevant if an editor is opened into a group that is not active
199
>
* already and allows to control if the inactive group should become active, restored
200
>
* or preserved.
201
>
*
202
>
* By default, the editor group will become active unless `preserveFocus` or `inactive`
203
>
* is specified.
204
>
*/
205
>
activation?: EditorActivation;
206
>
207
>
/**
208
>
* Tells the editor to reload the editor input in the editor even if it is identical to the one
209
>
* already showing. By default, the editor will not reload the input if it is identical to the
210
>
* one showing.
211
>
*/
212
>
forceReload?: boolean;
213
>
214
>
/**
215
>
* Will reveal the editor if it is already opened and visible in any of the opened editor groups.
216
>
*
217
>
* Note that this option is just a hint that might be ignored if the user wants to open an editor explicitly
218
>
* to the side of another one or into a specific editor group.
219
>
*/
220
>
revealIfVisible?: boolean;
221
>
222
>
/**
223
>
* Will reveal the editor if it is already opened (even when not visible) in any of the opened editor groups.
224
>
*
225
>
* Note that this option is just a hint that might be ignored if the user wants to open an editor explicitly
226
>
* to the side of another one or into a specific editor group.
227
>
*/
228
>
revealIfOpened?: boolean;
229
>
230
>
/**
231
>
* An editor that is pinned remains in the editor stack even when another editor is being opened.
232
>
* An editor that is not pinned will always get replaced by another editor that is not pinned.
233
>
*/
234
>
pinned?: boolean;
235
>
236
>
/**
237
>
* An editor that is sticky moves to the beginning of the editors list within the group and will remain
238
>
* there unless explicitly closed. Operations such as "Close All" will not close sticky editors.
239
>
*/
240
>
sticky?: boolean;
241
>
242
>
/**
243
>
* The index in the document stack where to insert the editor into when opening.
244
>
*/
245
>
index?: number;
246
>
247
>
/**
248
>
* An active editor that is opened will show its contents directly. Set to true to open an editor
249
>
* in the background without loading its contents.
250
>
*
251
>
* Will also not activate the group the editor opens in unless the group is already
252
>
* the active one. This behaviour can be overridden via the `activation` option.
253
>
*/
254
>
inactive?: boolean;
255
>
256
>
/**
257
>
* In case of an error opening the editor, will not present this error to the user (e.g. by showing
258
>
* a generic placeholder in the editor area). So it is up to the caller to provide error information
259
>
* in that case.
260
>
*
261
>
* By default, an error when opening an editor will result in a placeholder editor that shows the error.
262
>
* In certain cases a modal dialog may be presented to ask the user for further action.
263
>
*/
264
>
ignoreError?: boolean;
265
>
266
>
/**
267
>
* Allows to override the editor that should be used to display the input:
268
>
* - `undefined`: let the editor decide for itself
269
>
* - `string`: specific override by id
270
>
* - `EditorResolution`: specific override handling
271
>
*/
272
>
override?: string | EditorResolution;
273
>
274
>
/**
275
>
* A optional hint to signal in which context the editor opens.
276
>
*
277
>
* If configured to be `EditorOpenSource.USER`, this hint can be
278
>
* used in various places to control the experience. For example,
279
>
* if the editor to open fails with an error, a notification could
280
>
* inform about this in a modal dialog. If the editor opened through
281
>
* some background task, the notification would show in the background,
282
>
* not as a modal dialog.
283
>
*/
284
>
source?: EditorOpenSource;
285
>
286
>
/**
287
>
* Indicates whether the editor is being opened due to an explicit user
288
>
* action (`true`) or automatically (`false`) as a side effect of another
289
>
* action (e.g. the chat agent opening files it has edited).
290
>
*
291
>
* When omitted, callers should be treated as explicit. Layout logic may
292
>
* use this to decide whether to react to the visibility change (for
293
>
* example, by leaving the auxiliary side bar maximized when the change
294
>
* was not initiated by the user).
295
>
*/
296
>
isExplicit?: boolean;
297
>
298
>
/**
299
>
* An optional property to signal that certain view state should be
300
>
* applied when opening the editor.
301
>
*/
302
>
viewState?: object;
303
>
304
>
/**
305
>
* A transient editor will attempt to appear as preview and certain components
306
>
* (such as history tracking) may decide to ignore the editor when it becomes
307
>
* active.
308
>
* This option is meant to be used only when the editor is used for a short
309
>
* period of time, for example when opening a preview of the editor from a
310
>
* picker control in the background while navigating through results of the picker.
311
>
*
312
>
* Note: an editor that is already opened in a group that is not transient, will
313
>
* not turn transient.
314
>
*/
315
>
transient?: boolean;
316
>
317
>
/**
318
>
* Options that only apply when `AUX_WINDOW_GROUP` is used for opening.
319
>
*/
320
>
auxiliary?: {
321
>
322
>
/**
323
>
* Define the bounds of the editor window.
324
>
*/
325
>
bounds?: Partial<IRectangle>;
326
>
327
>
/**
328
>
* Show editor compact, hiding unnecessary elements.
329
>
*/
330
>
compact?: boolean;
331
>
332
>
/**
333
>
* Show the editor always on top of other windows.
334
>
*/
335
>
alwaysOnTop?: boolean;
336
>
};
337
>
338
>
/**
339
>
* Options that only apply when `MODAL_GROUP` is used for opening.
340
>
*/
341
>
modal?: IModalEditorPartOptions;
342
>
}
343
>
344
>
export interface IModalEditorPartOptions {
345
>
346
>
/**
347
>
* Whether the modal editor should be maximized.
348
>
*/
349
>
readonly maximized?: boolean;
350
>
351
>
/**
352
>
* Size of the modal editor part unless it is maximized.
353
>
*/
354
>
readonly size?: { readonly width: number; readonly height: number };
355
>
356
>
/**
357
>
* Position of the modal editor part unless it is maximized.
358
>
*/
359
>
readonly position?: { readonly left: number; readonly top: number };
360
>
361
>
/**
362
>
* The navigation context for navigating between items
363
>
* within this modal editor. Pass `undefined` to clear.
364
>
*/
365
>
readonly navigation?: IModalEditorNavigation;
366
>
367
>
/**
368
>
* Optional sidebar content to render on the left side of the
369
>
* modal editor. The caller provides a render callback that
370
>
* receives a container element and a layout callback, and
371
>
* returns a disposable to clean up when the modal closes.
372
>
*
373
>
* Note: the sidebar will only be shown when provided during
374
>
* opening and cannot currently be added, removed, or updated
375
>
* after the modal editor is opened.
376
>
*/
377
>
readonly sidebar?: IModalEditorSidebar;
378
>
}
379
>
380
>
/**
381
>
* Per-editor modal options provided by an editor input that wants to influence
382
>
* how it is rendered inside the modal editor part. Unlike
383
>
* {@link IModalEditorPartOptions}, these options are scoped to a single editor
384
>
* and resolved from the active editor (not from the part-level options API).
385
>
*/
386
>
export interface IModalEditorOptions {
387
>
388
>
/**
389
>
* When true, the modal editor renders a simplified header:
390
>
* uses the editor background, hides the title icon, removes the
391
>
* bottom border and uses a slightly taller fixed height. Useful
392
>
* for editors that provide their own header chrome.
393
>
*/
394
>
readonly compactHeader?: boolean;
395
>
}
396
>
397
>
/**
398
>
* Marker interface for editor inputs that want to customize how they are
399
>
* rendered when opened in the modal editor part (see {@link IModalEditorOptions}).
400
>
*/
401
>
export interface IModalEditorOptionsProvider {
402
>
getModalEditorOptions(): IModalEditorOptions | undefined;
403
>
}
404
>
405
>
export function isModalEditorOptionsProvider(obj: unknown): obj is IModalEditorOptionsProvider {
406
return !!obj && typeof (obj as IModalEditorOptionsProvider).getModalEditorOptions === 'function';
407
}
409
>
/**
410
>
* Modal sidebar supports rendering custom content in a sidebar next to the main editor content.
411
>
*/
412
>
export interface IModalEditorSidebar {
413
>
414
>
/**
415
>
* Sidebar width set by the user via resizing, if any.
416
>
*/
417
>
readonly sidebarWidth?: number;
418
>
419
>
/**
420
>
* Whether the sidebar is hidden.
421
>
*/
422
>
readonly sidebarHidden?: boolean;
423
>
424
>
/**
425
>
* Render the sidebar content into the given container.
426
>
*
427
>
* @param container The DOM element to render into.
428
>
* @param onDidLayout An event that fires when the sidebar is
429
>
* laid out with the available dimensions.
430
>
* @param contextKeyService A context key service scoped to the modal
431
>
* that content should descend from (e.g. when creating lists/trees)
432
>
* so that modal-level context keys remain active while the content
433
>
* has focus.
434
>
* @returns A disposable to clean up when the modal closes.
435
>
*/
436
>
readonly render: (container: unknown /* HTMLElement */, onDidLayout: Event<{ readonly height: number; readonly width: number }>, contextKeyService: IContextKeyService) => IDisposable;
437
>
}
438
>
439
>
/**
440
>
* Context for navigating between items within a modal editor.
441
>
*/
442
>
export interface IModalEditorNavigation {
443
>
444
>
/**
445
>
* Total number of items in the navigation list.
446
>
*/
447
>
readonly total: number;
448
>
449
>
/**
450
>
* Current 0-based index in the navigation list.
451
>
*/
452
>
readonly current: number;
453
>
454
>
/**
455
>
* Navigate to the item at the given 0-based index.
456
>
*/
457
>
readonly navigate: (index: number) => void;
458
>
}
459
>
460
>
export interface ITextEditorSelection {
461
>
readonly startLineNumber: number;
462
>
readonly startColumn: number;
463
>
readonly endLineNumber?: number;
464
>
readonly endColumn?: number;
465
>
}
466
>
467
>
export const enum TextEditorSelectionRevealType {
468
>
/**
469
>
* Option to scroll vertically or horizontally as necessary and reveal a range centered vertically.
470
>
*/
471
>
Center = 0,
472
>
473
>
/**
474
>
* Option to scroll vertically or horizontally as necessary and reveal a range centered vertically only if it lies outside the viewport.
475
>
*/
476
>
CenterIfOutsideViewport = 1,
477
>
478
>
/**
479
>
* Option to scroll vertically or horizontally as necessary and reveal a range close to the top of the viewport, but not quite at the top.
480
>
*/
481
>
NearTop = 2,
482
>
483
>
/**
484
>
* Option to scroll vertically or horizontally as necessary and reveal a range close to the top of the viewport, but not quite at the top.
485
>
* Only if it lies outside the viewport
486
>
*/
487
>
NearTopIfOutsideViewport = 3,
488
>
}
489
>
490
>
export const enum TextEditorSelectionSource {
491
>
492
>
/**
493
>
* Programmatic source indicates a selection change that
494
>
* was not triggered by the user via keyboard or mouse
495
>
* but through text editor APIs.
496
>
*/
497
>
PROGRAMMATIC = 'api',
498
>
499
>
/**
500
>
* Navigation source indicates a selection change that
501
>
* was caused via some command or UI component such as
502
>
* an outline tree.
503
>
*/
504
>
NAVIGATION = 'code.navigation',
505
>
506
>
/**
507
>
* Jump source indicates a selection change that
508
>
* was caused from within the text editor to another
509
>
* location in the same or different text editor such
510
>
* as "Go to definition".
511
>
*/
512
>
JUMP = 'code.jump'
513
>
}
514
>
515
>
export interface ITextEditorOptions extends IEditorOptions {
516
>
517
>
/**
518
>
* Text editor selection.
519
>
*/
520
>
selection?: ITextEditorSelection;
521
>
522
>
/**
523
>
* Option to control the text editor selection reveal type.
524
>
* Defaults to TextEditorSelectionRevealType.Center
525
>
*/
526
>
selectionRevealType?: TextEditorSelectionRevealType;
527
>
528
>
/**
529
>
* Source of the call that caused the selection.
530
>
*/
531
>
selectionSource?: TextEditorSelectionSource | string;
532
>
}
533
>
534
>
export type ITextEditorChange = [
535
>
originalStartLineNumber: number,
536
>
originalEndLineNumberExclusive: number,
537
>
modifiedStartLineNumber: number,
538
>
modifiedEndLineNumberExclusive: number
539
>
];
540
>
541
>
export interface ITextEditorDiffInformation {
542
>
readonly documentVersion: number;
543
>
readonly original: URI | undefined;
544
>
readonly modified: URI;
545
>
readonly changes: readonly ITextEditorChange[];
546
>
}
547
>
548
>
export function isTextEditorDiffInformationEqual(
549
uriIdentityService: IUriIdentityService,
550
diff1: ITextEditorDiffInformation | undefined,