Chapter 1: Getting Started

Chapter 2: Using Atom

Chapter 3: Hacking Atom

Chapter 4: Behind Atom

Reference: API

Appendix A: Resources

Appendix B: FAQ

Appendix C: Shadow DOM

Appendix D: Upgrading to 1.0 APIs

Appendix E: Atom server-side APIs

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 properties.
Return values

Returns a DisplayMarker.

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:

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

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.

::isReversed()

Return values

Returns a Boolean indicating whether the head precedes the tail.

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

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

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

DisplayMarker
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

::getBufferRange()

Gets the buffer range of this marker.

Return values

Returns a Range.

::getScreenRange()

Gets the screen range of this marker.

Return values

Returns a Range.

::setBufferRange(bufferRange, properties)

Modifies the buffer range of this 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.

::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 'backward', returns the first valid position preceding an invalid position. If 'forward', returns the first valid position following an invalid position. If 'closest', returns the first valid position closest to an invalid position. Defaults to 'closest'. Applies to the start and end of the given range.

::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 'backward', returns the first valid position preceding an invalid position. If 'forward', returns the first valid position following an invalid position. If 'closest', returns the first valid position closest to an invalid position. Defaults to 'closest'. Applies to the start and end of the given range.
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 'backward', returns the first valid position preceding an invalid position. If 'forward', returns the first valid position following an invalid position. If 'closest', returns the first valid position closest to an invalid position. Defaults to 'closest'. Applies to the start and end of the given range.
Return values

Returns a Point.

Extended Methods

::getHeadBufferPosition()

Retrieves the buffer position of the marker’s head.

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 'backward', returns the first valid position preceding an invalid position. If 'forward', returns the first valid position following an invalid position. If 'closest', returns the first valid position closest to an invalid position. Defaults to 'closest'. Applies to the start and end of the given range.
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 'backward', returns the first valid position preceding an invalid position. If 'forward', returns the first valid position following an invalid position. If 'closest', returns the first valid position closest to an invalid position. Defaults to 'closest'. Applies to the start and end of the given range.

::getTailBufferPosition()

Retrieves the buffer position of the marker’s tail.

Return values

Returns a Point.

::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 'backward', returns the first valid position preceding an invalid position. If 'forward', returns the first valid position following an invalid position. If 'closest', returns the first valid position closest to an invalid position. Defaults to 'closest'. Applies to the start and end of the given range.
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 'backward', returns the first valid position preceding an invalid position. If 'forward', returns the first valid position following an invalid position. If 'closest', returns the first valid position closest to an invalid position. Defaults to 'closest'. Applies to the start and end of the given range.

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

::hasTail()

Return values

Returns a Boolean indicating whether the marker has a tail.

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