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.

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. See TextBuffer::markRange for invalidation strategies.

API documentation

Event Subscription

::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.

::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.

::getRange()

Return values

Returns the current Range of the marker. The range is immutable.

::setRange(range, params)

Sets the range of the marker.

Argument	Description
`range`	A Range or range-compatible Array. The range will be clipped before it is assigned.
`params`	optional An Object with the following keys:
`reversed`	Boolean indicating the marker will to be in a reversed orientation.
`exclusive`	Boolean indicating that changes occurring at either end of the marker will be considered outside the marker rather than inside. This defaults to `false` unless the marker's invalidation strategy is `inside` or the marker has no tail, in which case it defaults to `true`.

::getHeadPosition()

Return values

Returns a Point representing the marker's current head position.

::setHeadPosition(position)

Sets the head position of the marker.

Argument	Description
`position`	A Point or point-compatible Array. The position will be clipped before it is assigned.

::getTailPosition()

Return values

Returns a Point representing the marker's current tail position. If the marker has no tail, the head position will be returned instead.

::setTailPosition(position)

Sets the tail position of the marker. If the marker doesn't have a tail, it will after calling this method.

Argument	Description
`position`	A Point or point-compatible Array. The position will be clipped before it is assigned.

::getStartPosition()

Return values

Returns a Point representing the start position of the marker, which could be the head or tail position, depending on its orientation.

::getEndPosition()

Return values

Returns a Point representing the end position of the marker, which could be the head or tail position, depending on its orientation.

Return values

Returns a Boolean indicating whether the head precedes the tail.

::hasTail()

Return values

Returns a Boolean indicating whether the marker has a tail.

::isValid()

Is the marker valid?

Return values

Returns a Boolean.

::isDestroyed()

Is the marker destroyed?

Return values

Returns a Boolean.

::isExclusive()

Return values

Returns a Boolean indicating whether changes that occur exactly at the marker's head or tail cause it to move.

::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.

::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

::copy(params)

Creates and returns a new Marker with the same properties as this marker.

Argument	Description
`params`	Object

::destroy()

Destroys the marker, causing it to emit the 'destroyed' event.

::compare(other)

Compares this marker to another based on their ranges.

Argument	Description
`other`	Marker