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.
Creates and returns a new TextEditorMarker 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 |
|---|---|
|
|
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 TextEditorMarker. |
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 buffer position |
|
|
Point representing the new head buffer position |
|
|
Point representing the former tail buffer position |
|
|
Point representing the new tail buffer position |
|
|
Point representing the former head screen position |
|
|
Point representing the new head screen position |
|
|
Point representing the former tail screen position |
|
|
Point representing the new tail screen 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 TextEditorMarker::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. |
| Argument | Description |
|---|---|
|
|
TextEditorMarker other marker |
| Return values |
|---|
|
Returns a Boolean indicating whether this marker is equivalent to another marker, meaning they have the same range and options. |
Compares this marker to another based on their ranges.
| Argument | Description |
|---|---|
|
|
| Return values |
|---|
|
Returns a Number |
Retrieves the buffer position of the marker’s start. This will always be less than or equal to the result of TextEditorMarker::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 TextEditorMarker::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 TextEditorMarker::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 TextEditorMarker::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. |