TextEditor
essential

This class represents all essential editing state for a single
TextBuffer, including cursor and selection positions, folds, and soft wraps.
If you're manipulating the state of an editor, use this class.

A single TextBuffer can belong to multiple editors. For example, if the
same file is open in two different panes, Atom creates a separate editor for
each pane. If the buffer is manipulated the changes are reflected in both
editors, but each maintains its own cursor position, folded lines, etc.

Accessing TextEditor Instances

The easiest way to get hold of TextEditor objects is by registering a callback
with ::observeTextEditors on the atom.workspace global. Your callback will
then be called with all current editor instances and also when any editor is
created in the future.

atom.workspace.observeTextEditors (editor)->

editor.insertText('Hello World')

Buffer vs. Screen Coordinates

Because editors support folds and soft-wrapping, the lines on screen don't
always match the lines in the buffer. For example, a long line that soft wraps
twice renders as three lines on screen, but only represents one line in the
buffer. Similarly, if rows 5-10 are folded, then row 6 on screen corresponds
to row 11 in the buffer.

Your choice of coordinates systems will depend on what you're trying to
achieve. For example, if you're writing a command that jumps the cursor up or
down by 10 lines, you'll want to use screen coordinates because the user
probably wants to skip lines on screen. However, if you're writing a package
that jumps between method definitions, you'll want to work in buffer
coordinates.

When in doubt, just default to buffer coordinates, then experiment with
soft wraps and folds to ensure your code interacts with them correctly.

Invoke the given callback synchronously when the content of the
buffer changes.

Because observers are invoked synchronously, it's important not to perform
any expensive operations via this method. Consider ::onDidStopChanging to
delay expensive operations until after changes stop occurring.

Invoke callback when the buffer's contents change. It is
emit asynchronously 300ms after the last buffer change. This is a good place
to handle changes to the buffer without compromising typing performance.

For each selection, if the selection is not empty, deletes the
selection; otherwise, deletes all characters of the containing line
following the cursor. If the cursor is already at the end of the line,
deletes the following newline.

History

Any group of operations that are logically grouped from the perspective of
undoing and redoing should be performed in a transaction. If you want to
abort the transaction, call ::abortTransaction to terminate the function's
execution and revert any changes performed up to the abortion.

Argument

Description

groupingInterval

optional

The Number of milliseconds for which this transaction should be considered 'groupable' after it begins. If a transaction with a positive groupingInterval is committed while the previous transaction is still 'groupable', the two transactions are merged with respect to undo and redo.

Revert the buffer to the state it was in when the given
checkpoint was created.

The redo stack will be empty following this operation, so changes since the
checkpoint will be lost. If the given checkpoint is no longer present in the
undo history, no changes will be made to the buffer and this method will
return false.

TextEditor Coordinates

The position is clipped via ::clipBufferPosition prior to the conversion.
The position is also clipped via ::clipScreenPosition following the
conversion, which only makes a difference when options are supplied.

If the given Point describes a position that is actually reachable by the
cursor based on the current contents of the buffer, it is returned
unchanged. If the Point does not describe a valid position, the closest
valid position is returned instead.

If the given Point describes a position that is actually reachable by the
cursor based on the current contents of the screen, it is returned
unchanged. If the Point does not describe a valid position, the closest
valid position is returned instead.

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

Decorations

Add a decoration that tracks a DisplayMarker. When the
marker moves, is invalidated, or is destroyed, the decoration will be
updated to reflect the marker's state.

The following are the supported decorations types:

line: Adds your CSS class to the line nodes within the range
marked by the marker

line-number: Adds your CSS class to the line number nodes within the
range marked by the marker

highlight: Adds a new highlight div to the editor surrounding the
range marked by the marker. When the user selects text, the selection is
visualized with a highlight decoration internally. The structure of this
highlight will be

<divclass="highlight <your-class>">

<!-- Will be one region for each row in the range. Spans 2 lines? There will be 2 regions. -->

<divclass="region"></div>

</div>

overlay: Positions the view associated with the given item at the head
or tail of the given DisplayMarker.

Positions the view associated with the given item before or after the row of the given TextEditorMarker, depending on the position property.

cursor

Renders a cursor at the head of the given marker. If multiple decorations are created for the same marker, their class strings and style objects are combined into a single cursor. You can use this decoration type to style existing cursors by passing in their markers or render artificial cursors that don't actually exist in the model by passing a marker that isn't actually associated with a cursor.

.class

This CSS class will be applied to the decorated line number, line, text spans, highlight regions, cursors, or overlay.

.style

An Object containing CSS style properties to apply to the relevant DOM node. Currently this only works with a type of cursor or text.

.item

optional

An HTMLElement or a model Object with a corresponding view registered. Only applicable to the gutter, overlay and block decoration types.

.onlyHead

optional

If true, the decoration will only be applied to the head of the DisplayMarker. Only applicable to the line and line-number decoration types.

.onlyEmpty

optional

If true, the decoration will only be applied if the associated DisplayMarker is empty. Only applicable to the gutter, line, and line-number decoration types.

.onlyNonEmpty

optional

If true, the decoration will only be applied if the associated DisplayMarker is non-empty. Only applicable to the gutter, line, and line-number decoration types.

.omitEmptyLastRow

optional

If false, the decoration will be applied to the last row of a non-empty range, even if it ends at column 0. Defaults to true. Only applicable to the gutter, line, and line-number decoration types.

.position

optional

Only applicable to decorations of type overlay and block. Controls where the view is positioned relative to the TextEditorMarker. Values can be 'head' (the default) or 'tail' for overlay decorations, and 'before' (the default) or 'after' for block decorations.

.avoidOverflow

optional

Only applicable to decorations of type overlay. Determines whether the decoration adjusts its horizontal or vertical position to remain fully visible when it would otherwise overflow the editor. Defaults to true.

Markers

Create a marker on the default marker layer 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.

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

maintainHistory

optional

Boolean Whether to store this marker's range before and after each change in the undo history. This allows the marker's position to be restored more accurately for certain undo/redo operations, but uses more time and memory. (default: false)

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.

Create a marker on the default marker layer 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.

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

maintainHistory

optional

Boolean Whether to store this marker's range before and after each change in the undo history. This allows the marker's position to be restored more accurately for certain undo/redo operations, but uses more time and memory. (default: false)

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.

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.

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.

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

Find all DisplayMarkers on the default marker layer that
match the given properties.

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:

.startBufferRow

Only include markers starting at this row in buffer coordinates.

.endBufferRow

Only include markers ending at this row in buffer coordinates.

.containsBufferRange

Only include markers containing this Range or in range-compatible Array in buffer coordinates.

.containsBufferPosition

Only include markers containing this Point or Array of [row, column] in buffer coordinates.

A Boolean indicating whether marker state should be restored on undo/redo. Defaults to false.

.persistent

A Boolean indicating whether or not this marker layer should be serialized and deserialized along with the rest of the buffer. Defaults to false. If true, the marker layer's id will be maintained across the serialization boundary, allowing you to retrieve it via ::getMarkerLayer.

Move the cursor of each selection to the first non-whitespace
character of its line while preserving the selection's tail position. If the
cursor is already on the first character of the line, move it to the
beginning of the line.

Indentation

Determines how deeply the given row is indented based on the soft tabs and
tab length settings of this editor. Note that if soft tabs are enabled and
the tab length is 2, a row with 4 leading spaces would have an indentation
level of 2.

Inserts or removes hard tabs or spaces based on the soft tabs and tab length
settings of this editor in order to bring it to the given indentation level.
Note that if soft tabs are enabled and the tab length is 2, a row with 4
leading spaces would have an indentation level of 2.

Determines how deeply the given line is indented based on the soft tabs and
tab length settings of this editor. Note that if soft tabs are enabled and
the tab length is 2, a row with 4 leading spaces would have an indentation
level of 2.

Get the syntactic scopeDescriptor for the given position in buffer
coordinates. Useful with Config::get.

For example, if called with a position inside the parameter list of an
anonymous CoffeeScript function, the method returns the following array:
["source.coffee", "meta.inline.function.coffee", "variable.parameter.function.coffee"]