github/atom
1
1
Fork 0
mirror of https://github.com/atom/atom.git synced 2026-04-28 03:01:47 -04:00
Code Issues Packages Projects Releases Wiki Activity

Shore up the docs around marker creation and invalidation

Browse Source
This commit is contained in:
Ben Ogle
2014-09-17 18:10:19 -07:00
parent bf44cf89db
commit fb7b9041ab
2 changed files with 67 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
src/display-buffer-marker.coffee
View File

@@ -10,6 +10,10 @@ Grim = require 'grim'
# targets, misspelled words, and anything else that needs to track a logical
# location in the buffer over time.
#
# ### Marker Creation
#
# You will use {Editor::markBufferRange} rather than creating Markers directly.
#
# ### Head and Tail
#
# Markers always have a *head* and sometimes have a *tail*. If you think of a
@@ -24,7 +28,21 @@ Grim = require 'grim'
# 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 {Editor::markBufferRange} for invalidation strategies.
# 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 {Editor::markBufferRange} for usage.
module.exports =
class DisplayBufferMarker
EmitterMixin.includeInto(this)

56
src/editor.coffee
View File

@@ -1691,21 +1691,61 @@ class Editor extends Model
Section: Markers
###
# Essential: Mark the given range in buffer coordinates.
# Essential: Create a marker with the given range in buffer coordinates. This
# marker will maintain its logical location as the buffer is changed, so if
# you mark a particular word, the marker will remain over that word even if
# the word's location in the buffer changes.
#
# * `range` A {Range} or range-compatible {Array}.
# * `options` (optional) See {TextBuffer::markRange}.
# * `range` A {Range} or range-compatible {Array}
# * `properties` A hash of key-value pairs to associate with the marker. There
# are also reserved property names that have marker-specific meaning.
# * `reversed` (optional) Creates the marker in a reversed orientation. (default: false)
# * `persistent` (optional) Whether to include this marker when serializing the buffer. (default: true)
# * `invalidate` (optional) 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.
#
# Returns a {DisplayBufferMarker}.
# Returns a {Marker}.
markBufferRange: (args...) ->
@displayBuffer.markBufferRange(args...)
# Essential: Mark the given range in screen coordinates.
# Essential: Create a marker with the given range in screen coordinates. This
# marker will maintain its logical location as the buffer is changed, so if
# you mark a particular word, the marker will remain over that word even if
# the word's location in the buffer changes.
#
# * `range` A {Range} or range-compatible {Array}.
# * `options` (optional) See {TextBuffer::markRange}.
# * `range` A {Range} or range-compatible {Array}
# * `properties` A hash of key-value pairs to associate with the marker. There
# are also reserved property names that have marker-specific meaning.
# * `reversed` (optional) Creates the marker in a reversed orientation. (default: false)
# * `persistent` (optional) Whether to include this marker when serializing the buffer. (default: true)
# * `invalidate` (optional) 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.
#
# Returns a {DisplayBufferMarker}.
# Returns a {Marker}.
markScreenRange: (args...) ->
@displayBuffer.markScreenRange(args...)