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

MarkerLayer Essential

Experimental: A container for a related set of markers.

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

Lifecycle

::copy()

Create a copy of this layer with markers in the same state and locations.

::destroy()

Destroy this layer.

::clear()

Remove all markers from this layer.

::isDestroyed()

Determine whether this layer has been destroyed.

Querying

::getMarker()

Get an existing marker by its id.

Return values

Returns a Marker.

::getMarkers()

Get all existing markers on the marker layer.

Return values

Returns an Array of Markers.

::getMarkerCount()

Get the number of markers in the marker layer.

Return values

Returns a Number.

::findMarkers()

Find markers in the layer conforming to the given parameters.

See the documentation for TextBuffer::findMarkers.

::getRole()

Get the role of the marker layer e.g. atom.selection.

Return values

Returns a String.

Marker creation

::markRange(range, options)

Create a marker with the given 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 Marker.

::markPosition(position, options)

Create a marker at with its head at the given position with no tail.

Argument Description

position

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

Event subscription

::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 Marker whenever a new marker is created.
Return values

Returns a Disposable.

::onDidDestroy()

Subscribe to be notified synchronously when this layer is destroyed.

Return values

Returns a Disposable.