Represents a buffer annotation that remains logically stationary even as the buffer changes. This is used to represent cursors, folds, snippet targets, misspelled words, and anything else that needs to track a logical location in the buffer over time.
Use TextEditor::markBufferRange rather than creating Markers directly.
Markers always have a head and sometimes have a tail. If you think of a marker as an editor selection, the tail is the part that’s stationary and the head is the part that moves when the mouse is moved. A marker without a tail always reports an empty range at the head position. A marker with a head position greater than the tail is in a “normal” orientation. If the head precedes the tail the marker is in a “reversed” orientation.
Markers are considered valid when they are first created. Depending on the invalidation strategy you choose, certain changes to the buffer can cause a marker to become invalid, for example if the text surrounding the marker is deleted. The strategies, in order of descending fragility:
See TextEditor::markBufferRange for usage.
Destroys the marker, causing it to emit the ‘destroyed’ event. Once destroyed, a marker cannot be restored by undo/redo operations.
Invoke the given callback when the state of the marker changes.
| Argument | Description |
|---|---|
|
|
Function to be called when the marker changes. |
|
|
Object with the following keys: |
|
|
Point representing the former head position |
|
|
Point representing the new head position |
|
|
Point representing the former tail position |
|
|
Point representing the new tail position |
|
|
Boolean indicating whether the marker was valid before the change |
|
|
Boolean indicating whether the marker is now valid |
|
|
Boolean indicating whether the marker had a tail before the change |
|
|
Boolean indicating whether the marker now has a tail |
|
|
Object containing the marker’s custom properties before the change. |
|
|
Object containing the marker’s custom properties after the change. |
|
|
Boolean indicating whether this change was caused by a textual change to the buffer or whether the marker was manipulated directly via its public API. |
| Return values |
|---|
|
Returns a Disposable on which |
Invoke the given callback when the marker is destroyed.
| Argument | Description |
|---|---|
|
|
Function to be called when the marker is destroyed. |
| Return values |
|---|
|
Returns a Disposable on which |
| Return values |
|---|
|
Returns a Boolean indicating whether the marker is valid. Markers can be invalidated when a region surrounding them in the buffer is changed. |
| Return values |
|---|
|
Returns a Boolean indicating whether the marker has been destroyed. A marker can be invalid without being destroyed, in which case undoing the invalidating operation would restore the marker. Once a marker is destroyed by calling Marker::destroy, no undo/redo operation can ever bring it back. |
Get the invalidation strategy for this marker.
Valid values include: never, surround, overlap, inside, and touch.
| Return values |
|---|
|
Returns a String. |
Retrieves the buffer position of the marker’s start. This will always be less than or equal to the result of Marker::getEndBufferPosition.
| Return values |
|---|
|
Returns a Point. |
Retrieves the screen position of the marker’s start. This will always be less than or equal to the result of Marker::getEndScreenPosition.
| Return values |
|---|
|
Returns a Point. |
Retrieves the buffer position of the marker’s end. This will always be greater than or equal to the result of Marker::getStartBufferPosition.
| Return values |
|---|
|
Returns a Point. |
Retrieves the screen position of the marker’s end. This will always be greater than or equal to the result of Marker::getStartScreenPosition.
| Return values |
|---|
|
Returns a Point. |
Plants the marker’s tail at the current head position. After calling the marker’s tail position will be its head position at the time of the call, regardless of where the marker’s head is moved.
| Argument | Description |
|---|---|
|
|
optional
Object properties to associate with the marker. |
Removes the marker’s tail. After calling the marker’s head position will be reported as its current tail position until the tail is planted again.
| Argument | Description |
|---|---|
|
|
optional
Object properties to associate with the marker. |