DisplayMarker essential
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.
DisplayMarker Creation
Use DisplayMarkerLayer::markBufferRange or DisplayMarkerLayer::markScreenRange rather than creating Markers directly.
Head and Tail
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.
Validity
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:
- never: The marker is never marked as invalid. This is a good choice for markers representing selections in an editor.
- surround: The marker is invalidated by changes that completely surround it.
- overlap: The marker is invalidated by changes that surround the start or end of the marker. This is the default.
- inside: The marker is invalidated by changes that extend into the inside of the marker. Changes that end at the marker's start or start at the marker's end do not invalidate the marker.
- touch: The marker is invalidated by a change that touches the marked region in any way, including changes that end at the marker's start or start at the marker's end. This is the most fragile strategy.
See TextBuffer::markRange for usage.
Construction and Destruction
::destroy()
Destroys the marker, causing it to emit the 'destroyed' event. Once destroyed, a marker cannot be restored by undo/redo operations.
::copy([properties])
Creates and returns a new DisplayMarker with the same properties as this marker.
Selection markers (markers with a custom property type: "selection")
should be copied with a different type value, for example with
marker.copy({type: null}). Otherwise, the new marker's selection will
be merged with this marker's selection, and a null value will be
returned.
| Argument | Description |
|---|---|
properties |
optional
Object properties to associate with the new marker. The new marker's properties are computed by extending this marker's properties with |
| Return values |
|---|
Returns a DisplayMarker. |
Event Subscription
::onDidChange(callback)
Invoke the given callback when the state of the marker changes.
| Argument | Description |
|---|---|
callback(event) |
Function to be called when the marker changes. |
event |
Object with the following keys: |
.oldHeadBufferPosition |
Point representing the former head buffer position |
.newHeadBufferPosition |
Point representing the new head buffer position |
.oldTailBufferPosition |
Point representing the former tail buffer position |
.newTailBufferPosition |
Point representing the new tail buffer position |
.oldHeadScreenPosition |
Point representing the former head screen position |
.newHeadScreenPosition |
Point representing the new head screen position |
.oldTailScreenPosition |
Point representing the former tail screen position |
.newTailScreenPosition |
Point representing the new tail screen position |
.wasValid |
Boolean indicating whether the marker was valid before the change |
.isValid |
Boolean indicating whether the marker is now valid |
.hadTail |
Boolean indicating whether the marker had a tail before the change |
.hasTail |
Boolean indicating whether the marker now has a tail |
.oldProperties |
Object containing the marker's custom properties before the change. |
.newProperties |
Object containing the marker's custom properties after the change. |
.textChanged |
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 |
::onDidDestroy(callback)
Invoke the given callback when the marker is destroyed.
| Argument | Description |
|---|---|
callback() |
Function to be called when the marker is destroyed. |
| Return values |
|---|
Returns a Disposable on which |
TextEditorMarker Details
::isValid()
| 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. |
::isDestroyed()
| 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 DisplayMarker::destroy, no undo/redo operation can ever bring it back. |
::isExclusive()
| Return values |
|---|
Returns a Boolean indicating whether changes that occur exactly at the marker's head or tail cause it to move. |
::getInvalidationStrategy()
Get the invalidation strategy for this marker.
Valid values include: never, surround, overlap, inside, and touch.
| Return values |
|---|
Returns a String. |
::matchesProperties()
| Return values |
|---|
Returns whether this marker matches the given parameters. The parameters are the same as DisplayMarkerLayer::findMarkers. |
Comparing to other markers
::compare(other)
Compares this marker to another based on their ranges.
| Argument | Description |
|---|---|
other |
| Return values |
|---|
Returns a Number |
::isEqual(other)
| Argument | Description |
|---|---|
other |
DisplayMarker other marker |
| Return values |
|---|
Returns a Boolean indicating whether this marker is equivalent to another marker, meaning they have the same range and options. |
Managing the marker's range
::setScreenRange(screenRange, [options])
Modifies the screen range of this marker.
| Argument | Description |
|---|---|
screenRange |
The new Range to use |
options |
optional
An Object with the following keys: |
.reversed |
Boolean If true, the marker will to be in a reversed orientation. |
.clipDirection |
String If |
::getStartScreenPosition([options])
Retrieves the screen position of the marker's start. This will always be less than or equal to the result of DisplayMarker::getEndScreenPosition.
| Argument | Description |
|---|---|
options |
optional
An Object with the following keys: |
.clipDirection |
String If |
| Return values |
|---|
Returns a Point. |
::getEndScreenPosition([options])
Retrieves the screen position of the marker's end. This will always be greater than or equal to the result of DisplayMarker::getStartScreenPosition.
| Argument | Description |
|---|---|
options |
optional
An Object with the following keys: |
.clipDirection |
String If |
| Return values |
|---|
Returns a Point. |
::setHeadBufferPosition(bufferPosition)
Sets the buffer position of the marker's head.
| Argument | Description |
|---|---|
bufferPosition |
The new Point to use |
::getHeadScreenPosition([options])
Retrieves the screen position of the marker's head.
| Argument | Description |
|---|---|
options |
optional
An Object with the following keys: |
.clipDirection |
String If |
| Return values |
|---|
Returns a Point. |
::setHeadScreenPosition(screenPosition, [options])
Sets the screen position of the marker's head.
| Argument | Description |
|---|---|
screenPosition |
The new Point to use |
options |
optional
An Object with the following keys: |
.clipDirection |
String If |
::setTailBufferPosition(bufferPosition)
Sets the buffer position of the marker's tail.
| Argument | Description |
|---|---|
bufferPosition |
The new Point to use |
::getTailScreenPosition([options])
Retrieves the screen position of the marker's tail.
| Argument | Description |
|---|---|
options |
optional
An Object with the following keys: |
.clipDirection |
String If |
| Return values |
|---|
Returns a Point. |
::setTailScreenPosition(screenPosition, [options])
Sets the screen position of the marker's tail.
| Argument | Description |
|---|---|
screenPosition |
The new Point to use |
options |
optional
An Object with the following keys: |
.clipDirection |
String If |
::getStartBufferPosition()
Retrieves the buffer position of the marker's start. This will always be less than or equal to the result of DisplayMarker::getEndBufferPosition.
| Return values |
|---|
Returns a Point. |
::getEndBufferPosition()
Retrieves the buffer position of the marker's end. This will always be greater than or equal to the result of DisplayMarker::getStartBufferPosition.
| Return values |
|---|
Returns a Point. |
::plantTail()
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.
::clearTail()
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.