1
>
/*---------------------------------------------------------------------------------------------
editorService.ts
2
>
* Copyright (c) Microsoft Corporation. All rights reserved.
3
>
* Licensed under the MIT License. See License.txt in the project root for license information.
4
>
*--------------------------------------------------------------------------------------------*/
5
>
6
>
import { createDecorator } from '../../../../platform/instantiation/common/instantiation.js';
7
>
import { IResourceEditorInput, IEditorOptions, IResourceEditorInputIdentifier, ITextResourceEditorInput } from '../../../../platform/editor/common/editor.js';
8
>
import { IEditorPane, GroupIdentifier, IUntitledTextResourceEditorInput, IResourceDiffEditorInput, ITextDiffEditorPane, IEditorIdentifier, ISaveOptions, IRevertOptions, EditorsOrder, IVisibleEditorPane, IEditorCloseEvent, IUntypedEditorInput, IFindEditorOptions, IEditorWillOpenEvent, ITextResourceDiffEditorInput } from '../../../common/editor.js';
9
>
import { EditorInput } from '../../../common/editor/editorInput.js';
10
>
import { Event } from '../../../../base/common/event.js';
11
>
import { IEditor, IDiffEditor } from '../../../../editor/common/editorCommon.js';
12
>
import { ICloseEditorOptions, IEditorGroup, IEditorGroupsContainer, isEditorGroup } from './editorGroupsService.js';
13
>
import { URI } from '../../../../base/common/uri.js';
14
>
import { IGroupModelChangeEvent } from '../../../common/editor/editorGroupModel.js';
15
>
import { DisposableStore } from '../../../../base/common/lifecycle.js';
16
>
17
>
export const IEditorService = createDecorator<IEditorService>('editorService');
18
>
19
>
/**
20
>
* Open an editor in the currently active group.
21
>
*/
22
>
export const ACTIVE_GROUP = -1;
23
>
export type ACTIVE_GROUP_TYPE = typeof ACTIVE_GROUP;
24
>
25
>
/**
26
>
* Open an editor to the side of the active group.
27
>
*/
28
>
export const SIDE_GROUP = -2;
29
>
export type SIDE_GROUP_TYPE = typeof SIDE_GROUP;
30
>
31
>
/**
32
>
* Open an editor in a new auxiliary window.
33
>
*/
34
>
export const AUX_WINDOW_GROUP = -3;
35
>
export type AUX_WINDOW_GROUP_TYPE = typeof AUX_WINDOW_GROUP;
36
>
37
>
/**
38
>
* Open an editor in a modal overlay on top of the workbench.
39
>
*/
40
>
export const MODAL_GROUP = -4;
41
>
export type MODAL_GROUP_TYPE = typeof MODAL_GROUP;
42
>
43
>
/**
44
>
* Setting that controls whether editors open in a modal editor part.
45
>
*/
46
>
export const USE_MODAL_EDITOR_SETTING = 'workbench.editor.useModal';
47
>
48
>
/**
49
>
* Possible values for the `workbench.editor.useModal` setting:
50
>
* - `'off'`: never open editors modal (user opt-out, honored over `RequiresModal`)
51
>
* - `'some'`: open modal only for editors that request it (e.g. `RequiresModal`)
52
>
* - `'all'`: open all editors modal
53
>
*/
54
>
export type UseModalEditorMode = 'off' | 'some' | 'all';
55
>
56
>
export type PreferredGroup = IEditorGroup | GroupIdentifier | SIDE_GROUP_TYPE | ACTIVE_GROUP_TYPE | AUX_WINDOW_GROUP_TYPE | MODAL_GROUP_TYPE;
57
>
58
>
export function isPreferredGroup(obj: unknown): obj is PreferredGroup {
59
const candidate = obj as PreferredGroup | undefined;
60
61
return typeof obj === 'number' || isEditorGroup(candidate);
62
}
64
>
export interface ISaveEditorsOptions extends ISaveOptions {
65
>
66
>
/**
67
>
* If true, will ask for a location of the editor to save to.
68
>
*/
69
>
readonly saveAs?: boolean;
70
>
}
71
>
72
>
export interface ISaveEditorsResult {
73
>
74
>
/**
75
>
* Whether the save operation was successful.
76
>
*/
77
>
readonly success: boolean;
78
>
79
>
/**
80
>
* Resulting editors after the save operation.
81
>
*/
82
>
readonly editors: Array<EditorInput | IUntypedEditorInput>;
83
>
}
84
>
85
>
export interface IUntypedEditorReplacement {
86
>
87
>
/**
88
>
* The editor to replace.
89
>
*/
90
>
readonly editor: EditorInput;
91
>
92
>
/**
93
>
* The replacement for the editor.
94
>
*/
95
>
readonly replacement: IUntypedEditorInput;
96
>
97
>
/**
98
>
* Skips asking the user for confirmation and doesn't
99
>
* save the document. Only use this if you really need to!
100
>
*/
101
>
forceReplaceDirty?: boolean;
102
>
}
103
>
104
>
export interface IBaseSaveRevertAllEditorOptions {
105
>
106
>
/**
107
>
* Whether to include untitled editors as well.
108
>
*/
109
>
readonly includeUntitled?: {
110
>
111
>
/**
112
>
* Whether to include scratchpad editors.
113
>
* Scratchpads are not included if not specified.
114
>
*/
115
>
readonly includeScratchpad: boolean;
116
>
117
>
} | boolean;
118
>
119
>
/**
120
>
* Whether to exclude sticky editors.
121
>
*/
122
>
readonly excludeSticky?: boolean;
123
>
}
124
>
125
>
export interface ISaveAllEditorsOptions extends ISaveEditorsOptions, IBaseSaveRevertAllEditorOptions { }
126
>
127
>
export interface IRevertAllEditorsOptions extends IRevertOptions, IBaseSaveRevertAllEditorOptions { }
128
>
129
>
export interface IOpenEditorsOptions {
130
>
131
>
/**
132
>
* Whether to validate trust when opening editors
133
>
* that are potentially not inside the workspace.
134
>
*/
135
>
readonly validateTrust?: boolean;
136
>
}
137
>
138
>
export interface IEditorsChangeEvent {
139
>
/**
140
>
* The group which had the editor change
141
>
*/
142
>
groupId: GroupIdentifier;
143
>
/*
144
>
* The event fired from the model
145
>
*/
146
>
event: IGroupModelChangeEvent;
147
>
}
148
>
149
>
export interface IVisibleEditorsChangeEvent {
150
>
151
>
/**
152
>
* Indicates whether the visibility change is the result of an explicit
153
>
* user action (`true`) or happened automatically as a side effect
154
>
* (e.g. the chat agent opening files it has edited).
155
>
*/
156
>
readonly isExplicit: boolean;
157
>
}
158
>
159
>
export interface IEditorService {
160
>
161
>
readonly _serviceBrand: undefined;
162
>
163
>
/**
164
>
* Emitted when the currently active editor changes.
165
>
*
166
>
* @see {@link IEditorService.activeEditorPane}
167
>
*/
168
>
readonly onDidActiveEditorChange: Event<void>;
169
>
170
>
/**
171
>
* Emitted when any of the current visible editors changes.
172
>
*
173
>
* @see {@link IEditorService.visibleEditorPanes}
174
>
*/
175
>
readonly onDidVisibleEditorsChange: Event<IVisibleEditorsChangeEvent>;
176
>
177
>
/**
178
>
* An aggregated event for any change to any editor across
179
>
* all groups.
180
>
*/
181
>
readonly onDidEditorsChange: Event<IEditorsChangeEvent>;
182
>
183
>
/**
184
>
* Emitted when an editor is about to open.
185
>
*/
186
>
readonly onWillOpenEditor: Event<IEditorWillOpenEvent>;
187
>
188
>
/**
189
>
* Emitted when an editor is closed.
190
>
*/
191
>
readonly onDidCloseEditor: Event<IEditorCloseEvent>;
192
>
193
>
/**
194
>
* The currently active editor pane or `undefined` if none. The editor pane is
195
>
* the workbench container for editors of any kind.
196
>
*
197
>
* @see {@link IEditorService.activeEditor} for access to the active editor input
198
>
*/
199
>
readonly activeEditorPane: IVisibleEditorPane | undefined;
200
>
201
>
/**
202
>
* The currently active editor or `undefined` if none. An editor is active when it is
203
>
* located in the currently active editor group. It will be `undefined` if the active
204
>
* editor group has no editors open.
205
>
*/
206
>
readonly activeEditor: EditorInput | undefined;
207
>
208
>
/**
209
>
* The currently active text editor control or `undefined` if there is currently no active
210
>
* editor or the active editor widget is neither a text nor a diff editor.
211
>
*
212
>
* @see {@link IEditorService.activeEditor}
213
>
*/
214
>
readonly activeTextEditorControl: IEditor | IDiffEditor | undefined;
215
>
216
>
/**
217
>
* The currently active text editor language id or `undefined` if there is currently no active
218
>
* editor or the active editor control is neither a text nor a diff editor. If the active
219
>
* editor is a diff editor, the modified side's language id will be taken.
220
>
*/
221
>
readonly activeTextEditorLanguageId: string | undefined;
222
>
223
>
/**
224
>
* All editor panes that are currently visible across all editor groups.
225
>
*
226
>
* @see {@link IEditorService.visibleEditors} for access to the visible editor inputs
227
>
*/
228
>
readonly visibleEditorPanes: readonly IVisibleEditorPane[];
229
>
230
>
/**
231
>
* All editors that are currently visible. An editor is visible when it is opened in an
232
>
* editor group and active in that group. Multiple editor groups can be opened at the same time.
233
>
*/
234
>
readonly visibleEditors: readonly EditorInput[];
235
>
236
>
/**
237
>
* All text editor widgets that are currently visible across all editor groups. A text editor
238
>
* widget is either a text or a diff editor.
239
>
*
240
>
* This property supports side-by-side editors as well, by returning both sides if they are
241
>
* text editor widgets.
242
>
*/
243
>
readonly visibleTextEditorControls: readonly (IEditor | IDiffEditor)[];
244
>
245
>
/**
246
>
* All text editor widgets that are currently visible across all editor groups. A text editor
247
>
* widget is either a text or a diff editor.
248
>
*
249
>
* This property supports side-by-side editors as well, by returning both sides if they are
250
>
* text editor widgets.
251
>
*
252
>
* @param order the order of the editors to use
253
>
*/
254
>
getVisibleTextEditorControls(order: EditorsOrder): readonly (IEditor | IDiffEditor)[];
255
>
256
>
/**
257
>
* All editors that are opened across all editor groups in sequential order
258
>
* of appearance.
259
>
*
260
>
* This includes active as well as inactive editors in each editor group.
261
>
*/
262
>
readonly editors: readonly EditorInput[];
263
>
264
>
/**
265
>
* The total number of editors that are opened either inactive or active.
266
>
*/
267
>
readonly count: number;
268
>
269
>
/**
270
>
* All editors that are opened across all editor groups with their group
271
>
* identifier.
272
>
*
273
>
* @param order the order of the editors to use
274
>
* @param options whether to exclude sticky editors or not
275
>
*/
276
>
getEditors(order: EditorsOrder, options?: { excludeSticky?: boolean }): readonly IEditorIdentifier[];
277
>
278
>
/**
279
>
* Open an editor in an editor group.
280
>
*
281
>
* @param editor the editor to open
282
>
* @param options the options to use for the editor
283
>
* @param group the target group. If unspecified, the editor will open in the currently
284
>
* active group. Use `SIDE_GROUP` to open the editor in a new editor group to the side
285
>
* of the currently active group.
286
>
*
287
>
* @returns the editor that opened or `undefined` if the operation failed or the editor was not
288
>
* opened to be active.
289
>
*/
290
>
openEditor(editor: IResourceEditorInput, group?: PreferredGroup): Promise<IEditorPane | undefined>;
291
>
openEditor(editor: ITextResourceEditorInput | IUntitledTextResourceEditorInput, group?: PreferredGroup): Promise<IEditorPane | undefined>;
292
>
openEditor(editor: ITextResourceDiffEditorInput | IResourceDiffEditorInput, group?: PreferredGroup): Promise<ITextDiffEditorPane | undefined>;
293
>
openEditor(editor: IUntypedEditorInput, group?: PreferredGroup): Promise<IEditorPane | undefined>;
294
>
295
>
/**
296
>
* Using this method is a sign that your editor has not adopted the editor
297
>
* resolver yet. Please use `IEditorResolverService.registerEditor` to make your editor
298
>
* known to the workbench and then use untyped editor inputs for opening:
299
>
*
300
>
* ```ts
301
>
* editorService.openEditor({ resource });
302
>
* ```
303
>
*
304
>
* If you already have an `EditorInput` in hand and must use it for opening, use `group.openEditor`
305
>
* instead, via `IEditorGroupsService`.
306
>
*/
307
>
openEditor(editor: EditorInput, options?: IEditorOptions, group?: PreferredGroup): Promise<IEditorPane | undefined>;
308
>
309
>
/**
310
>
* Open editors in an editor group.
311
>
*
312
>
* @param editors the editors to open with associated options
313
>
* @param group the target group. If unspecified, the editor will open in the currently
314
>
* active group. Use `SIDE_GROUP` to open the editor in a new editor group to the side
315
>
* of the currently active group.
316
>
*
317
>
* @returns the editors that opened. The array can be empty or have less elements for editors
318
>
* that failed to open or were instructed to open as inactive.
319
>
*/
320
>
openEditors(editors: IUntypedEditorInput[], group?: PreferredGroup, options?: IOpenEditorsOptions): Promise<readonly IEditorPane[]>;
321
>
322
>
/**
323
>
* Replaces editors in an editor group with the provided replacement.
324
>
*
325
>
* @param replacements the editors to replace
326
>
* @param group the editor group
327
>
*
328
>
* @returns a promise that is resolved when the replaced active
329
>
* editor (if any) has finished loading.
330
>
*/
331
>
replaceEditors(replacements: IUntypedEditorReplacement[], group: IEditorGroup | GroupIdentifier): Promise<void>;
332
>
333
>
/**
334
>
* Find out if the provided editor is opened in any editor group.
335
>
*
336
>
* Note: An editor can be opened but not actively visible.
337
>
*
338
>
* Note: This method will return `true` if a side by side editor
339
>
* is opened where the `primary` editor matches too.
340
>
*/
341
>
isOpened(editor: IResourceEditorInputIdentifier): boolean;
342
>
343
>
/**
344
>
* Find out if the provided editor is visible in any editor group.
345
>
*/
346
>
isVisible(editor: EditorInput): boolean;
347
>
348
>
/**
349
>
* Close an editor in a specific editor group.
350
>
*/
351
>
closeEditor(editor: IEditorIdentifier, options?: ICloseEditorOptions): Promise<void>;
352
>
353
>
/**
354
>
* Close multiple editors in specific editor groups.
355
>
*/
356
>
closeEditors(editors: readonly IEditorIdentifier[], options?: ICloseEditorOptions): Promise<void>;
357
>
358
>
/**
359
>
* This method will return an entry for each editor that reports
360
>
* a `resource` that matches the provided one in the group or
361
>
* across all groups.
362
>
*
363
>
* It is possible that multiple editors are returned in case the
364
>
* same resource is opened in different editors. To find the specific
365
>
* editor, use the `IResourceEditorInputIdentifier` as input.
366
>
*/
367
>
findEditors(resource: URI, options?: IFindEditorOptions): readonly IEditorIdentifier[];
368
>
findEditors(editor: IResourceEditorInputIdentifier, options?: IFindEditorOptions): readonly IEditorIdentifier[];
369
>
370
>
/**
371
>
* Save the provided list of editors.
372
>
*/
373
>
save(editors: IEditorIdentifier | readonly IEditorIdentifier[], options?: ISaveEditorsOptions): Promise<ISaveEditorsResult>;
374
>
375
>
/**
376
>
* Save all editors.
377
>
*/
378
>
saveAll(options?: ISaveAllEditorsOptions): Promise<ISaveEditorsResult>;
379
>
380
>
/**
381
>
* Reverts the provided list of editors.
382
>
*
383
>
* @returns `true` if all editors reverted and `false` otherwise.
384
>
*/
385
>
revert(editors: IEditorIdentifier | readonly IEditorIdentifier[], options?: IRevertOptions): Promise<boolean>;
386
>
387
>
/**
388
>
* Reverts all editors.
389
>
*
390
>
* @returns `true` if all editors reverted and `false` otherwise.
391
>
*/
392
>
revertAll(options?: IRevertAllEditorsOptions): Promise<boolean>;
393
>
394
>
/**
395
>
* Create a scoped editor service that only operates on the provided
396
>
* editor group container. Use `main` to create a scoped editor service
397
>
* to the main editor group container of the main window.
398
>
*/
399
>
createScoped(editorGroupsContainer: IEditorGroupsContainer, disposables: DisposableStore): IEditorService;
400
>
}