1 | import { Disposable } from '../../../index';
|
2 | import { Point, PointCompatible, Range, RangeCompatible } from './text-buffer';
|
3 |
|
4 | /**
|
5 | * Represents a buffer annotation that remains logically stationary even as
|
6 | * the buffer changes.
|
7 | */
|
8 | export interface Marker {
|
9 | /** The identifier for this Marker. */
|
10 | readonly id: number;
|
11 |
|
12 | // Lifecycle
|
13 | /**
|
14 | * Creates and returns a new Marker with the same properties as this
|
15 | * marker.
|
16 | */
|
17 | copy(options?: CopyMarkerOptions): Marker;
|
18 |
|
19 | /** Destroys the marker, causing it to emit the "destroyed" event. */
|
20 | destroy(): void;
|
21 |
|
22 | // Event Subscription
|
23 | /** Invoke the given callback when the marker is destroyed. */
|
24 | onDidDestroy(callback: () => void): Disposable;
|
25 |
|
26 | /** Invoke the given callback when the state of the marker changes. */
|
27 | onDidChange(callback: (event: MarkerChangedEvent) => void): Disposable;
|
28 |
|
29 | // Marker Details
|
30 | /** Returns the current range of the marker. The range is immutable. */
|
31 | getRange(): Range;
|
32 |
|
33 | /** Returns a point representing the marker's current head position. */
|
34 | getHeadPosition(): Point;
|
35 |
|
36 | /** Returns a point representing the marker's current tail position. */
|
37 | getTailPosition(): Point;
|
38 |
|
39 | /**
|
40 | * Returns a point representing the start position of the marker, which
|
41 | * could be the head or tail position, depending on its orientation.
|
42 | */
|
43 | getStartPosition(): Point;
|
44 |
|
45 | /**
|
46 | * Returns a point representing the end position of the marker, which
|
47 | * could be the head or tail position, depending on its orientation.
|
48 | */
|
49 | getEndPosition(): Point;
|
50 |
|
51 | /** Returns a boolean indicating whether the head precedes the tail. */
|
52 | isReversed(): boolean;
|
53 |
|
54 | /** Returns a boolean indicating whether the marker has a tail. */
|
55 | hasTail(): boolean;
|
56 |
|
57 | /** Is the marker valid? */
|
58 | isValid(): boolean;
|
59 |
|
60 | /** Is the marker destroyed? */
|
61 | isDestroyed(): boolean;
|
62 |
|
63 | /**
|
64 | * Returns a boolean indicating whether changes that occur exactly at
|
65 | * the marker's head or tail cause it to move.
|
66 | */
|
67 | isExclusive(): boolean;
|
68 |
|
69 | /** Get the invalidation strategy for this marker. */
|
70 | getInvalidationStrategy(): string;
|
71 |
|
72 | // Mutating Markers
|
73 | /**
|
74 | * Sets the range of the marker.
|
75 | * Returns a boolean indicating whether or not the marker was updated.
|
76 | */
|
77 | setRange(range: RangeCompatible, params?: { reversed?: boolean | undefined; exclusive?: boolean | undefined }): boolean;
|
78 |
|
79 | /**
|
80 | * Sets the head position of the marker.
|
81 | * Returns a boolean indicating whether or not the marker was updated.
|
82 | */
|
83 | setHeadPosition(position: PointCompatible): boolean;
|
84 |
|
85 | /**
|
86 | * Sets the tail position of the marker.
|
87 | * Returns a boolean indicating whether or not the marker was updated.
|
88 | */
|
89 | setTailPosition(position: PointCompatible): boolean;
|
90 |
|
91 | /**
|
92 | * Removes the marker's tail.
|
93 | * Returns a boolean indicating whether or not the marker was updated.
|
94 | */
|
95 | clearTail(): boolean;
|
96 |
|
97 | /**
|
98 | * Plants the marker's tail at the current head position.
|
99 | * Returns a boolean indicating whether or not the marker was updated.
|
100 | */
|
101 | plantTail(): boolean;
|
102 |
|
103 | // Comparison
|
104 | /**
|
105 | * Returns a boolean indicating whether this marker is equivalent to
|
106 | * another marker, meaning they have the same range and options.
|
107 | */
|
108 | isEqual(other: Marker): boolean;
|
109 |
|
110 | /**
|
111 | * Compares this marker to another based on their ranges.
|
112 | * Returns "-1" if this marker precedes the argument.
|
113 | * Returns "0" if this marker is equivalent to the argument.
|
114 | * Returns "1" if this marker follows the argument.
|
115 | */
|
116 | compare(other: Marker): number;
|
117 | }
|
118 |
|
119 | export interface CopyMarkerOptions {
|
120 | /** Whether or not the marker should be tailed. */
|
121 | tailed?: boolean | undefined;
|
122 |
|
123 | /** Creates the marker in a reversed orientation. */
|
124 | reversed?: boolean | undefined;
|
125 |
|
126 | /** Determines the rules by which changes to the buffer invalidate the marker. */
|
127 | invalidate?: 'never' | 'surround' | 'overlap' | 'inside' | 'touch' | undefined;
|
128 |
|
129 | /**
|
130 | * Indicates whether insertions at the start or end of the marked range should
|
131 | * be interpreted as happening outside the marker.
|
132 | */
|
133 | exclusive?: boolean | undefined;
|
134 |
|
135 | /** Custom properties to be associated with the marker. */
|
136 | properties?: object | undefined;
|
137 | }
|
138 |
|
139 | export interface MarkerChangedEvent {
|
140 | /** Point representing the former head position. */
|
141 | oldHeadPosition: Point;
|
142 |
|
143 | /** Point representing the new head position. */
|
144 | newHeadPosition: Point;
|
145 |
|
146 | /** Point representing the former tail position. */
|
147 | oldTailPosition: Point;
|
148 |
|
149 | /** Point representing the new tail position. */
|
150 | newTailPosition: Point;
|
151 |
|
152 | /** Boolean indicating whether the marker was valid before the change. */
|
153 | wasValid: boolean;
|
154 |
|
155 | /** Boolean indicating whether the marker is now valid. */
|
156 | isValid: boolean;
|
157 |
|
158 | /** Boolean indicating whether the marker had a tail before the change. */
|
159 | hadTail: boolean;
|
160 |
|
161 | /** Boolean indicating whether the marker now has a tail. */
|
162 | hasTail: boolean;
|
163 |
|
164 | /**
|
165 | * -DEPRECATED- Object containing the marker's custom properties before the change.
|
166 | * @deprecated
|
167 | */
|
168 | oldProperties: object;
|
169 |
|
170 | /**
|
171 | * -DEPRECATED- Object containing the marker's custom properties after the change.
|
172 | * @deprecated
|
173 | */
|
174 | newProperties: object;
|
175 |
|
176 | /**
|
177 | * Boolean indicating whether this change was caused by a textual
|
178 | * change to the buffer or whether the marker was manipulated directly
|
179 | * via its public API.
|
180 | */
|
181 | textChanged: boolean;
|
182 | }
|