Marker

Description

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.

Marker Creation

Use TextEditor::markBufferRange 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 TextEditor::markBufferRange for usage.

API documentation

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 Marker with the same properties as this marker.

Argument	Description
`properties`	Object

Event Subscription

::onDidChange(callback)

Invoke the given callback when the state of the marker changes.

Argument	Description
`callback`	Function to be called when the marker changes.
`event`	Object with the following keys:
`oldHeadPosition`	Point representing the former head position
`newHeadPosition`	Point representing the new head position
`oldTailPosition`	Point representing the former tail position
`newTailPosition`	Point representing the new tail 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 .dispose() can be called to unsubscribe.

::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 .dispose() can be called to unsubscribe.

Marker 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 Marker::destroy, no undo/redo operation can ever bring it back.

::isReversed()

Return values

Returns a Boolean indicating whether the head precedes the tail.

::getInvalidationStrategy()

Get the invalidation strategy for this marker.

Valid values include: never, surround, overlap, inside, and touch.

Return values

Returns a String.

::getProperties()

Return values

Returns an Object containing any custom properties associated with the marker.

::setProperties(properties)

Merges an Object containing new properties into the marker's existing properties.

Argument	Description
`properties`	Object

Comparing to other markers

::isEqual(other)

Argument	Description
`other`	Marker other marker

Return values

Returns a Boolean indicating whether this marker is equivalent to another marker, meaning they have the same range and options.

::compare(other)

Compares this marker to another based on their ranges.

Argument	Description
`other`	Marker

Return values

Returns a Number

Managing the marker's range

::getBufferRange()

Gets the buffer range of the display marker.

Return values

Returns a Range.

::setBufferRange(bufferRange, properties)

Modifies the buffer range of the display marker.

Argument	Description
`bufferRange`	The new Range to use
`properties`	optional Object properties to associate with the marker.
`reversed`	Boolean If true, the marker will to be in a reversed orientation.

::getScreenRange()

Gets the screen range of the display marker.

Return values

Returns a Range.

::setScreenRange(screenRange, properties)

Modifies the screen range of the display marker.

Argument	Description
`screenRange`	The new Range to use
`properties`	optional Object properties to associate with the marker.
`reversed`	Boolean If true, the marker will to be in a reversed orientation.

::getStartBufferPosition()

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.

::getStartScreenPosition()

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.

::getEndBufferPosition()

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.

::getEndScreenPosition()

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.

::getHeadBufferPosition()

Retrieves the buffer position of the marker's head.

Return values

Returns a Point.

::setHeadBufferPosition(bufferPosition, properties)

Sets the buffer position of the marker's head.

Argument	Description
`bufferPosition`	The new Point to use
`properties`	optional Object properties to associate with the marker.

::getHeadScreenPosition()

Retrieves the screen position of the marker's head.

Return values

Returns a Point.

::setHeadScreenPosition(screenPosition, properties)

Sets the screen position of the marker's head.

Argument	Description
`screenPosition`	The new Point to use
`properties`	optional Object properties to associate with the marker.

::getTailBufferPosition()

Retrieves the buffer position of the marker's tail.

Return values

Returns a Point.

::setTailBufferPosition(bufferPosition, properties)

Sets the buffer position of the marker's tail.

Argument	Description
`bufferPosition`	The new Point to use
`properties`	optional Object properties to associate with the marker.

::getTailScreenPosition()

Retrieves the screen position of the marker's tail.

Return values

Returns a Point.

::setTailScreenPosition(screenPosition, properties)

Sets the screen position of the marker's tail.

Argument	Description
`screenPosition`	The new Point to use
`properties`	optional Object properties to associate with the marker.

::hasTail()

Return values

Returns a Boolean indicating whether the marker has a tail.

::plantTail(properties)

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
`properties`	optional Object properties to associate with the marker.

::clearTail(properties)

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
`properties`	optional Object properties to associate with the marker.