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

DisplayMarkerLayer Essential

Experimental: A container for a related set of markers at the DisplayLayer level. Wraps an underlying MarkerLayer on the TextBuffer.

This API is experimental and subject to change on any release.

Lifecycle

::destroy()

Destroy this layer.

::clear()

Destroy all markers in this layer.

::isDestroyed()

Determine whether this layer has been destroyed.

Return values

Returns a Boolean.

Event Subscription

::onDidDestroy()

Subscribe to be notified synchronously when this layer is destroyed.

Return values

Returns a Disposable.

::onDidUpdate(callback)

Subscribe to be notified asynchronously whenever markers are created, updated, or destroyed on this layer. Prefer this method for optimal performance when interacting with layers that could contain large numbers of markers.

Subscribers are notified once, asynchronously when any number of changes occur in a given tick of the event loop. You should re-query the layer to determine the state of markers in which you’re interested in. It may be counter-intuitive, but this is much more efficient than subscribing to events on individual markers, which are expensive to deliver.

Argument Description

callback

A Function that will be called with no arguments when changes occur on this layer.
Return values

Returns a Disposable.

::onDidCreateMarker(callback)

Subscribe to be notified synchronously whenever markers are created on this layer. Avoid this method for optimal performance when interacting with layers that could contain large numbers of markers.

You should prefer ::onDidUpdate when synchronous notifications aren’t absolutely necessary.

Argument Description

callback

A Function that will be called with a TextEditorMarker whenever a new marker is created.
Return values

Returns a Disposable.

Marker creation

::markScreenRange(range, options)

Create a marker with the given screen range.

Argument Description

range

A Range or range-compatible Array

options

A hash of key-value pairs to associate with the marker. There are also reserved property names that have marker-specific meaning.

reversed

 optional

Boolean Creates the marker in a reversed orientation. (default: false)

invalidate

 optional

String Determines the rules by which changes to the buffer invalidate the marker. (default: ‘overlap’) It can be any of the following strategies, in order of 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.

exclusive

Boolean indicating whether insertions at the start or end of the marked range should be interpreted as happening outside the marker. Defaults to false, except when using the inside invalidation strategy or when when the marker has no tail, in which case it defaults to true. Explicitly assigning this option overrides behavior in all circumstances.

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

::markScreenPosition(screenPosition, options)

Create a marker on this layer with its head at the given screen position and no tail.

Argument Description

screenPosition

A Point or point-compatible Array

options

 optional

An Object with the following keys:

invalidate

 optional

String Determines the rules by which changes to the buffer invalidate the marker. (default: ‘overlap’) It can be any of the following strategies, in order of 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.

exclusive

Boolean indicating whether insertions at the start or end of the marked range should be interpreted as happening outside the marker. Defaults to false, except when using the inside invalidation strategy or when when the marker has no tail, in which case it defaults to true. Explicitly assigning this option overrides behavior in all circumstances.

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

Returns a DisplayMarker.

::markBufferRange(range, options)

Create a marker with the given buffer range.

Argument Description

range

A Range or range-compatible Array

options

A hash of key-value pairs to associate with the marker. There are also reserved property names that have marker-specific meaning.

reversed

 optional

Boolean Creates the marker in a reversed orientation. (default: false)

invalidate

 optional

String Determines the rules by which changes to the buffer invalidate the marker. (default: ‘overlap’) It can be any of the following strategies, in order of 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.

exclusive

Boolean indicating whether insertions at the start or end of the marked range should be interpreted as happening outside the marker. Defaults to false, except when using the inside invalidation strategy or when when the marker has no tail, in which case it defaults to true. Explicitly assigning this option overrides behavior in all circumstances.
Return values

Returns a DisplayMarker.

::markBufferPosition(bufferPosition, options)

Create a marker on this layer with its head at the given buffer position and no tail.

Argument Description

bufferPosition

A Point or point-compatible Array

options

 optional

An Object with the following keys:

invalidate

 optional

String Determines the rules by which changes to the buffer invalidate the marker. (default: ‘overlap’) It can be any of the following strategies, in order of 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.

exclusive

Boolean indicating whether insertions at the start or end of the marked range should be interpreted as happening outside the marker. Defaults to false, except when using the inside invalidation strategy or when when the marker has no tail, in which case it defaults to true. Explicitly assigning this option overrides behavior in all circumstances.
Return values

Returns a DisplayMarker.

Querying

::getMarker()

Get an existing marker by its id.

Return values

Returns a DisplayMarker.

::getMarkers()

Get all markers in the layer.

Return values

Returns an Array of DisplayMarkers.

::getMarkerCount()

Get the number of markers in the marker layer.

Return values

Returns a Number.

::findMarkers(properties)

Find markers in the layer conforming to the given parameters.

This method finds markers based on the given properties. Markers can be associated with custom properties that will be compared with basic equality. In addition, there are several special properties that will be compared with the range of the markers rather than their properties.

Argument Description

properties

An Object containing properties that each returned marker must satisfy. Markers can be associated with custom properties, which are compared with basic equality. In addition, several reserved properties can be used to filter markers based on their current range:

startBufferPosition

Only include markers starting at this Point in buffer coordinates.

endBufferPosition

Only include markers ending at this Point in buffer coordinates.

startScreenPosition

Only include markers starting at this Point in screen coordinates.

endScreenPosition

Only include markers ending at this Point in screen coordinates.

startsInBufferRange

Only include markers starting inside this Range in buffer coordinates.

endsInBufferRange

Only include markers ending inside this Range in buffer coordinates.

startsInScreenRange

Only include markers starting inside this Range in screen coordinates.

endsInScreenRange

Only include markers ending inside this Range in screen coordinates.

startBufferRow

Only include markers starting at this row in buffer coordinates.

endBufferRow

Only include markers ending at this row in buffer coordinates.

startScreenRow

Only include markers starting at this row in screen coordinates.

endScreenRow

Only include markers ending at this row in screen coordinates.

intersectsBufferRowRange

Only include markers intersecting this Array of [startRow, endRow] in buffer coordinates.

intersectsScreenRowRange

Only include markers intersecting this Array of [startRow, endRow] in screen coordinates.

containsBufferRange

Only include markers containing this Range in buffer coordinates.

containsBufferPosition

Only include markers containing this Point in buffer coordinates.

containedInBufferRange

Only include markers contained in this Range in buffer coordinates.

containedInScreenRange

Only include markers contained in this Range in screen coordinates.

intersectsBufferRange

Only include markers intersecting this Range in buffer coordinates.

intersectsScreenRange

Only include markers intersecting this Range in screen coordinates.
Return values

Returns an Array of DisplayMarkers