Skip to content

Commit ee62e57

Browse files
DanTupCommit Queue
authored andcommitted
[dtd] Add a common definition for an editor event for tracking active position changes
Allows other tools to know where the user is currently active. Change-Id: If32fa9514d79730a2e41763c529c5fdeacaa0127 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/392908 Commit-Queue: Brian Wilkerson <[email protected]> Reviewed-by: Brian Wilkerson <[email protected]> Reviewed-by: Elliott Brooks <[email protected]>
1 parent 691b939 commit ee62e57

File tree

1 file changed

+101
-6
lines changed

1 file changed

+101
-6
lines changed

pkg/dtd_impl/dtd_common_services_editor.md

Lines changed: 101 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,23 @@ The following events are sent over the `Editor` stream. See `streamListen` in
8484
[dtd_protocol](./dtd_protocol.md) for information on subscribing to streams.
8585

8686

87+
## activeLocationChanged
88+
`ActiveLocationChangedEvent`
89+
90+
An event sent by an editor when the document/location where the user is
91+
active (or the document itself) changes.
92+
93+
Only the active document is tracked, even if multiple documents are
94+
open/visible at the same time. A new event replaces the active document and
95+
previous selections from an earlier event.
96+
97+
Edits to the document are considered location changes even if the line/column
98+
remain the same because they they are locations in a different document version.
99+
100+
This event may be debounced by the editor to avoid sending frequent events
101+
during typing.
102+
103+
87104
## deviceAdded
88105
`DeviceAddedEvent`
89106

@@ -148,6 +165,31 @@ and dark mode or increase/decrease font size.
148165
# Type Definitions
149166

150167
```dart
168+
/// An event sent by an editor when the document/location where the user is
169+
/// active changes.
170+
///
171+
/// Only the active document is tracked, even if multiple documents are
172+
/// open/visible at the same time. A new event replaces the active document and
173+
/// previous selections from an earlier event.
174+
/// This event may be debounced by the editor to avoid sending frequent events
175+
/// during typing.
176+
class ActiveLocationChangedEvent {
177+
/// An identifier that represents the active document.
178+
///
179+
/// `null` is there is no active document.
180+
OptionalVersionedTextDocumentIdentifier? textDocument;
181+
182+
/// The set of selections in the document.
183+
///
184+
/// There will always be at least one selection if there is an active document
185+
/// (textDocument != null), but there may also be more if a user has multiple
186+
/// selections active.
187+
///
188+
/// The first selection is always the primary selection for actions that only
189+
/// support one location.
190+
List<EditorSelection> selections;
191+
}
192+
151193
/// An event sent by an editor when a debug session is changed.
152194
///
153195
/// This could be happen when a VM Service URI becomes available for a session
@@ -231,12 +273,29 @@ class EditorDevice {
231273
bool supported;
232274
}
233275
234-
/// The description of an editor's theme.
235-
class Theme {
236-
bool isDarkMode;
237-
String? backgroundColor;
238-
String? foregroundColor;
239-
int? fontSize;
276+
277+
/// A position inside a document.
278+
class EditorPosition {
279+
/// The zero-based line number of this position.
280+
int line;
281+
282+
/// The zero-based character number of this position.
283+
int character;
284+
}
285+
286+
/// A selection inside a document.
287+
class EditorSelection {
288+
/// The start/anchor position of a selection.
289+
///
290+
/// This will be the same as [active] if this is just a single position and
291+
/// not a selection.
292+
///
293+
/// This position may be before, after, or the same as [active] depending on
294+
/// the selection.
295+
EditorPosition anchor;
296+
297+
/// The end/active position of a selection.
298+
EditorPosition active;
240299
}
241300
242301
/// Parameters for the `enablePlatformTypeParams` request.
@@ -322,4 +381,40 @@ class SelectDeviceParams {
322381
/// The ID of the device to select (or `null` to unselect the current device).
323382
String? deviceId;
324383
}
384+
385+
/// The description of an editor's theme.
386+
class Theme {
387+
bool isDarkMode;
388+
String? backgroundColor;
389+
String? foregroundColor;
390+
int? fontSize;
391+
}
392+
393+
/// An identifier for a document with an optional version number.
394+
class OptionalVersionedTextDocumentIdentifier {
395+
/// The URI that represents the document.
396+
///
397+
/// This URI could be of any scheme and clients should ignore those they do
398+
/// not understand. It is always a URI and never a bare file path.
399+
///
400+
/// Clients should take care to handle paths that should be case-insensitive
401+
/// or include escaping. In particular, Windows drive letters may be cased
402+
/// inconsistently and the colon may be escaped as `%3a` or `%3A`.
403+
///
404+
/// Examples:
405+
///
406+
/// - file:///c:/foo/bar/baz.dart
407+
/// - file:///C%3A/foo/bar/baz.dart
408+
/// - file:///foo/bar/baz.dart
409+
/// - dart-macro+file:///c:/foo/bar/baz.dart
410+
/// - dart-macro+file:///C%3A/foo/bar/baz.dart
411+
/// - dart-macro+file:///foo/bar/baz.dart
412+
/// - vsls:///foo/bar/baz.dart
413+
String uri;
414+
415+
/// The current version of this document, if the document is versioned. The
416+
/// version is used to to ensure locations within a document are only applied
417+
/// to the correct version of that document but not all editors provide it.
418+
int? version;
419+
}
325420
```

0 commit comments

Comments
 (0)