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 |
::findMarkers()
Find markers in the layer conforming to the given parameters.
See the documentation for TextBuffer::findMarkers.
Marker creation
::markRange(range, options)
Create a marker with the given range.
| Argument | Description |
|---|---|
range |
|
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:
|
exclusive |
Boolean indicating whether insertions at the start or end of the marked range should be interpreted as happening outside the marker. Defaults to |
| Return values |
|---|
Returns a |
::markPosition(position, [options])
Create a marker at with its head at the given position with no tail.
| Argument | Description |
|---|---|
position |
|
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:
|
.exclusive |
Boolean indicating whether insertions at the start or end of the marked range should be interpreted as happening outside the marker. Defaults to |
| Return values |
|---|
Returns a |
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 |
| Return values |
|---|
Returns a Disposable. |
::onDidDestroy()
Subscribe to be notified synchronously when this layer is destroyed.
| Return values |
|---|
Returns a Disposable. |