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.

Event Subscription

::onDidChangeTitle(callback)

Calls your callback when the buffer’s title has changed.

Argument	Description
`callback`	Function

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangePath(callback)

Calls your callback when the buffer’s path, and therefore title, has changed.

Argument	Description
`callback`	Function

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChange(callback)

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.

Argument	Description
`callback`	Function

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidStopChanging(callback)

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.

Argument	Description
`callback`	Function

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangeCursorPosition(callback)

Calls your callback when a Cursor is moved. If there are multiple cursors, your callback will be called for each cursor.

Argument	Description
`callback`	Function
`event`	Object
`oldBufferPosition`	Point
`oldScreenPosition`	Point
`newBufferPosition`	Point
`newScreenPosition`	Point
`textChanged`	Boolean
`cursor`	Cursor that triggered the event

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangeSelectionRange(callback)

Calls your callback when a selection’s screen range changes.

Argument	Description
`callback`	Function
`event`	Object
`oldBufferRange`	Range
`oldScreenRange`	Range
`newBufferRange`	Range
`newScreenRange`	Range
`selection`	Selection that triggered the event

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidSave(callback)

Invoke the given callback after the buffer is saved to disk.

Argument	Description
`callback`	Function to be called after the buffer is saved.
`event`	Object with the following keys:
`path`	The path to which the buffer was saved.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidDestroy(callback)

Invoke the given callback when the editor is destroyed.

Argument	Description
`callback`	Function to be called when the editor is destroyed.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::observeGutters(callback)

Calls your callback when a Gutter is added to the editor. Immediately calls your callback for each existing gutter.

Argument	Description
`callback`	Function
`gutter`	Gutter that currently exists/was added.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidAddGutter(callback)

Calls your callback when a Gutter is added to the editor.

Argument	Description
`callback`	Function
`gutter`	Gutter that was added.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidRemoveGutter(callback)

Calls your callback when a Gutter is removed from the editor.

Argument	Description
`callback`	Function
`name`	The name of the Gutter that was removed.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

Extended Methods

::onDidChangeSoftWrapped(callback)

Calls your callback when soft wrap was enabled or disabled.

Argument	Description
`callback`	Function

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangeEncoding(callback)

Calls your callback when the buffer’s encoding has changed.

Argument	Description
`callback`	Function

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::observeGrammar(callback)

Calls your callback when the grammar that interprets and colorizes the text has been changed. Immediately calls your callback with the current grammar.

Argument	Description
`callback`	Function
`grammar`	Grammar

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangeGrammar(callback)

Calls your callback when the grammar that interprets and colorizes the text has been changed.

Argument	Description
`callback`	Function
`grammar`	Grammar

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangeModified(callback)

Calls your callback when the result of ::isModified changes.

Argument	Description
`callback`	Function

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidConflict(callback)

Calls your callback when the buffer’s underlying file changes on disk at a moment when the result of ::isModified is true.

Argument	Description
`callback`	Function

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onWillInsertText(callback)

Calls your callback before text has been inserted.

Argument	Description
`callback`	Function
`event`	event Object
`text`	String text to be inserted
`cancel`	Function Call to prevent the text from being inserted

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidInsertText(callback)

Calls your callback after text has been inserted.

Argument	Description
`callback`	Function
`event`	event Object
`text`	String text to be inserted

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::observeCursors(callback)

Calls your callback when a Cursor is added to the editor. Immediately calls your callback for each existing cursor.

Argument	Description
`callback`	Function
`cursor`	Cursor that was added

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidAddCursor(callback)

Calls your callback when a Cursor is added to the editor.

Argument	Description
`callback`	Function
`cursor`	Cursor that was added

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidRemoveCursor(callback)

Calls your callback when a Cursor is removed from the editor.

Argument	Description
`callback`	Function
`cursor`	Cursor that was removed

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::observeSelections(callback)

Calls your callback when a Selection is added to the editor. Immediately calls your callback for each existing selection.

Argument	Description
`callback`	Function
`selection`	Selection that was added

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidAddSelection(callback)

Calls your callback when a Selection is added to the editor.

Argument	Description
`callback`	Function
`selection`	Selection that was added

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidRemoveSelection(callback)

Calls your callback when a Selection is removed from the editor.

Argument	Description
`callback`	Function
`selection`	Selection that was removed

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::observeDecorations(callback)

Calls your callback with each Decoration added to the editor. Calls your callback immediately for any existing decorations.

Argument	Description
`callback`	Function
`decoration`	Decoration

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidAddDecoration(callback)

Calls your callback when a Decoration is added to the editor.

Argument	Description
`callback`	Function
`decoration`	Decoration that was added

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidRemoveDecoration(callback)

Calls your callback when a Decoration is removed from the editor.

Argument	Description
`callback`	Function
`decoration`	Decoration that was removed

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangePlaceholderText(callback)

Calls your callback when the placeholder text is changed.

Argument	Description
`callback`	Function
`placeholderText`	String new text

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

Buffer

::getBuffer()

Retrieves the current TextBuffer.

File Details

::getTitle()

Get the editor’s title for display in other parts of the UI such as the tabs.

If the editor’s buffer is saved, its title is the file name. If it is unsaved, its title is “untitled”.

Return values
Returns a String.

::getLongTitle()

Get unique title for display in other parts of the UI, such as the window title.

If the editor’s buffer is unsaved, its title is “untitled” If the editor’s buffer is saved, its unique title is formatted as one of the following,

“" when it is the only editing buffer with this file name.
“ — " when other buffers have this file name.

Return values
Returns a String

::getPath()

Return values
Returns the String path of this editor’s text buffer.

::isModified()

Return values
Returns Boolean `true` if this editor has been modified.

::isEmpty()

Return values
Returns Boolean `true` if this editor has no content.

Extended Methods

::getEncoding()

Return values
Returns the String character set encoding of this editor’s text buffer.

::setEncoding(encoding)

Set the character set encoding to use in this editor’s text buffer.

Argument	Description
`encoding`	The String character set encoding name such as ‘utf8’

File Operations

::save()

Saves the editor’s text buffer.

See TextBuffer::save for more details.

::saveAs(filePath)

Saves the editor’s text buffer as the given path.

See TextBuffer::saveAs for more details.

Argument	Description
`filePath`	A String path.

Reading Text

::getText()

Return values
Returns a String representing the entire contents of the editor.

::getTextInBufferRange(range)

Get the text in the given Range in buffer coordinates.

Argument	Description
`range`	A Range or range-compatible Array.

Return values
Returns a String.

::getLineCount()

Return values
Returns a Number representing the number of lines in the buffer.

::getScreenLineCount()

Return values
Returns a Number representing the number of screen lines in the editor. This accounts for folds.

::getLastBufferRow()

Return values
Returns a Number representing the last zero-indexed buffer row number of the editor.

::getLastScreenRow()

Return values
Returns a Number representing the last zero-indexed screen row number of the editor.

::lineTextForBufferRow(bufferRow)

Argument	Description
`bufferRow`	A Number representing a zero-indexed buffer row.

Return values
Returns a String representing the contents of the line at the given buffer row.

::lineTextForScreenRow(screenRow)

Argument	Description
`screenRow`	A Number representing a zero-indexed screen row.

Return values
Returns a String representing the contents of the line at the given screen row.

::getCurrentParagraphBufferRange()

Get the Range of the paragraph surrounding the most recently added cursor.

Return values
Returns a Range.

Mutating Text

::setText(text, options)

Replaces the entire contents of the buffer with the given String.

Argument	Description
`text`	A String to replace with
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor.

::setTextInBufferRange(range, text, options)

Set the text in the given Range in buffer coordinates.

Argument	Description
`range`	A Range or range-compatible Array.
`text`	A String
`options`	optional Object
`normalizeLineEndings`	optional Boolean (default: true)
`undo`	optional Deprecated String ‘skip’ will skip the undo system. This property is deprecated. Call groupLastChanges() on the TextBuffer afterward instead.
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

Return values
Returns the Range of the newly-inserted text.

::insertText(text, options)

For each selection, replace the selected text with the given text.

Argument	Description
`text`	A String representing the text to insert.
`options`	optional See Selection::insertText.

Return values
Returns a Range when the text has been inserted.
Returns a Boolean `false` when the text has not been inserted.

::insertNewline(options)

For each selection, replace the selected text with a newline.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::delete(options)

For each selection, if the selection is empty, delete the character following the cursor. Otherwise delete the selected text.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::backspace(options)

For each selection, if the selection is empty, delete the character preceding the cursor. Otherwise delete the selected text.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

Extended Methods

::mutateSelectedText(fn)

Mutate the text of all the selections in a single transaction.

All the changes made inside the given Function can be reverted with a single call to ::undo.

Argument	Description
`fn`	A Function that will be called once for each Selection. The first argument will be a Selection and the second argument will be the Number index of that selection.

::transpose(options)

For each selection, transpose the selected text.

If the selection is empty, the characters preceding and following the cursor are swapped. Otherwise, the selected characters are reversed.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::upperCase(options)

Convert the selected text to upper case.

For each selection, if the selection is empty, converts the containing word to upper case. Otherwise convert the selected text to upper case.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::lowerCase(options)

Convert the selected text to lower case.

For each selection, if the selection is empty, converts the containing word to upper case. Otherwise convert the selected text to upper case.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::toggleLineCommentsInSelection(options)

Toggle line comments for rows intersecting selections.

If the current grammar doesn’t support comments, does nothing.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::insertNewlineBelow(options)

For each cursor, insert a newline at beginning the following line.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::insertNewlineAbove(options)

For each cursor, insert a newline at the end of the preceding line.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::deleteToBeginningOfWord(options)

For each selection, if the selection is empty, delete all characters of the containing word that precede the cursor. Otherwise delete the selected text.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::deleteToPreviousWordBoundary(options)

Similar to ::deleteToBeginningOfWord, but deletes only back to the previous word boundary.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::deleteToNextWordBoundary(options)

Similar to ::deleteToEndOfWord, but deletes only up to the next word boundary.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::deleteToBeginningOfSubword(options)

For each selection, if the selection is empty, delete all characters of the containing subword following the cursor. Otherwise delete the selected text.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::deleteToEndOfSubword(options)

For each selection, if the selection is empty, delete all characters of the containing subword following the cursor. Otherwise delete the selected text.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::deleteToBeginningOfLine(options)

For each selection, if the selection is empty, delete all characters of the containing line that precede the cursor. Otherwise delete the selected text.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::deleteToEndOfLine(options)

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.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::deleteToEndOfWord(options)

For each selection, if the selection is empty, delete all characters of the containing word following the cursor. Otherwise delete the selected text.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::deleteLine(options)

Delete all lines intersecting selections.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

History

::undo(options)

Undo the last change.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

::redo(options)

Redo the last change.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor. (default: false)

Extended Methods

::transact(groupingInterval, fn)

Batch multiple operations as a single undo/redo step.

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.
`fn`	A Function to call inside the transaction.

::abortTransaction()

Abort an open transaction, undoing any operations performed so far within the transaction.

::createCheckpoint()

Create a pointer to the current state of the buffer for use with ::revertToCheckpoint and ::groupChangesSinceCheckpoint.

Return values
Returns a checkpoint value.

::revertToCheckpoint(checkpoint)

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.

Argument	Description
`checkpoint`	The checkpoint to revert to.

Return values
Returns a Boolean indicating whether the operation succeeded.

::groupChangesSinceCheckpoint(checkpoint)

Group all changes since the given checkpoint into a single transaction for purposes of undo/redo.

If the given checkpoint is no longer present in the undo history, no grouping will be performed and this method will return false.

Argument	Description
`checkpoint`	The checkpoint from which to group changes.

Return values
Returns a Boolean indicating whether the operation succeeded.

TextEditor Coordinates

::screenPositionForBufferPosition(bufferPosition, options)

Convert a position in buffer-coordinates to screen-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.

Argument	Description
`bufferPosition`	A Point or Array of [row, column].
`options`	optional An options hash for ::clipScreenPosition.

Return values
Returns a Point.

::bufferPositionForScreenPosition(bufferPosition, options)

Convert a position in screen-coordinates to buffer-coordinates.

The position is clipped via ::clipScreenPosition prior to the conversion.

Argument	Description
`bufferPosition`	A Point or Array of [row, column].
`options`	optional An options hash for ::clipScreenPosition.

Return values
Returns a Point.

::screenRangeForBufferRange(bufferRange)

Convert a range in buffer-coordinates to screen-coordinates.

Argument	Description
`bufferRange`	Range in buffer coordinates to translate into screen coordinates.

Return values
Returns a Range.

::bufferRangeForScreenRange(screenRange)

Convert a range in screen-coordinates to buffer-coordinates.

Argument	Description
`screenRange`	Range in screen coordinates to translate into buffer coordinates.

Return values
Returns a Range.

Extended Methods

::clipBufferPosition(bufferPosition)

Clip the given Point to a valid position in the buffer.

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.

Argument	Description
`bufferPosition`	The Point representing the position to clip.

Return values
Returns a Point.

::clipBufferRange(range)

Clip the start and end of the given range to valid positions in the buffer. See ::clipBufferPosition for more information.

Argument	Description
`range`	The Range to clip.

Return values
Returns a Range.

::clipScreenPosition(screenPosition, options)

Clip the given Point to a valid position on screen.

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.

Argument	Description
`screenPosition`	The Point representing the position to clip.
`options`	optional Object
`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 Point.

::clipScreenRange(range, options)

Clip the start and end of the given range to valid positions on screen. See ::clipScreenPosition for more information.

Argument	Description
`range`	The Range to clip.
`options`	optional See ::clipScreenPosition `options`.

Return values
Returns a Range.

Decorations

::decorateMarker(marker, decorationParams)

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 the given CSS class to the lines overlapping the rows spanned by the marker.
line-number: Adds the given CSS class to the line numbers overlapping the rows spanned by the marker
text: Injects spans into all text overlapping the marked range, then adds the given class or style to these spans. Use this to manipulate the foreground color or styling of text in a range.
highlight: Creates an absolutely-positioned .highlight div to the editor containing nested divs that cover the marked region. For example, when the user selects text, the selection is implemented with a highlight decoration. The structure of this highlight will be:
```
  <div class="highlight <your-class>">
    
    <div class="region"></div>
  </div>
```
overlay: Positions the view associated with the given item at the head or tail of the given DisplayMarker, depending on the position property.
gutter: Tracks a DisplayMarker in a Gutter. Gutter decorations are created by calling Gutter::decorateMarker on the desired Gutter instance.
block: Positions the view associated with the given item before or after the row of the given DisplayMarker, depending on the position property. Block decorations at the same screen row are ordered by their order property.
cursor: Render a cursor at the head of the DisplayMarker. If multiple cursor decorations are created for the same marker, their class strings and style objects are combined into a single cursor. This decoration type may be used to style existing cursors by passing in their markers or to render artificial cursors that don’t actually exist in the model by passing a marker that isn’t associated with a real cursor.

Argument	Description
`marker`	A DisplayMarker you want this decoration to follow.
`decorationParams`	An Object representing the decoration e.g. `{type: 'line-number', class: 'linter-error'}`
`type`	Determines the behavior and appearance of this Decoration. Supported decoration types and their uses are listed above.
`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.
`order`	optional Only applicable to decorations of type `block`. Controls where the view is positioned relative to other block decorations at the same screen row. If unspecified, block decorations render oldest to newest.
`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`.

Return values
Returns the created Decoration object.

::decorateMarkerLayer(markerLayer, decorationParams)

Add a decoration to every marker in the given marker layer. Can be used to decorate a large number of markers without having to create and manage many individual decorations.

Argument	Description
`markerLayer`	A DisplayMarkerLayer or MarkerLayer to decorate.
`decorationParams`	The same parameters that are passed to TextEditor::decorateMarker, except the `type` cannot be `overlay` or `gutter`.

Return values
Returns a LayerDecoration.

Extended Methods

::getDecorations(propertyFilter)

Get all decorations.

Argument	Description
`propertyFilter`	optional An Object containing key value pairs that the returned decorations’ properties must match.

Return values
Returns an Array of Decorations.

::getLineDecorations(propertyFilter)

Get all decorations of type ‘line’.

Argument	Description
`propertyFilter`	optional An Object containing key value pairs that the returned decorations’ properties must match.

Return values
Returns an Array of Decorations.

::getLineNumberDecorations(propertyFilter)

Get all decorations of type ‘line-number’.

Argument	Description
`propertyFilter`	optional An Object containing key value pairs that the returned decorations’ properties must match.

Return values
Returns an Array of Decorations.

::getHighlightDecorations(propertyFilter)

Get all decorations of type ‘highlight’.

Argument	Description
`propertyFilter`	optional An Object containing key value pairs that the returned decorations’ properties must match.

Return values
Returns an Array of Decorations.

::getOverlayDecorations(propertyFilter)

Get all decorations of type ‘overlay’.

Argument	Description
`propertyFilter`	optional An Object containing key value pairs that the returned decorations’ properties must match.

Return values
Returns an Array of Decorations.

Markers

::markBufferRange(range, properties)

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.

Argument	Description
`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.
`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.

Return values
Returns a DisplayMarker.

::markScreenRange(range, properties)

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.

Argument	Description
`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.
`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.

Return values
Returns a DisplayMarker.

::markBufferPosition(bufferPosition, options)

Create a marker on the default marker layer with the given buffer position and no tail. To group multiple markers together in their own private layer, see ::addMarkerLayer.

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.

Return values
Returns a DisplayMarker.

::markScreenPosition(screenPosition, options)

Create a marker on the default marker layer with the given screen position and no tail. To group multiple markers together in their own private layer, see ::addMarkerLayer.

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

::findMarkers(properties)

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.

Return values
Returns an Array of DisplayMarkers

::addMarkerLayer(options)

Create a marker layer to group related markers.

Argument	Description
`options`	An Object containing the following keys:
`maintainHistory`	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.

Return values
Returns a DisplayMarkerLayer.

::getMarkerLayer(id)

Get a DisplayMarkerLayer by id.

Argument	Description
`id`	The id of the marker layer to retrieve.

Return values
Returns a DisplayMarkerLayer or `undefined` if no layer exists with the given id.

::getDefaultMarkerLayer()

Get the default DisplayMarkerLayer.

All marker APIs not tied to an explicit layer interact with this default layer.

Return values
Returns a DisplayMarkerLayer.

Extended Methods

::getMarker(id)

Get the DisplayMarker on the default layer for the given marker id.

Argument	Description
`id`	Number id of the marker

::getMarkers()

Get all DisplayMarkers on the default marker layer. Consider using ::findMarkers

::getMarkerCount()

Get the number of markers in the default marker layer.

Return values
Returns a Number.

Cursors

::getCursorBufferPosition()

Get the position of the most recently added cursor in buffer coordinates.

Return values
Returns a Point

::getCursorBufferPositions()

Get the position of all the cursor positions in buffer coordinates.

Return values
Returns Array of Points in the order they were added

::setCursorBufferPosition(position, options)

Move the cursor to the given position in buffer coordinates.

If there are multiple cursors, they will be consolidated to a single cursor.

Argument	Description
`position`	A Point or Array of `[row, column]`
`options`	optional An Object containing the following keys:
`autoscroll`	Determines whether the editor scrolls to the new cursor’s position. Defaults to true.

::getCursorAtScreenPosition(position)

Get a Cursor at given screen coordinates Point

Argument	Description
`position`	A Point or Array of `[row, column]`

Return values
Returns the first matched Cursor or undefined

::getCursorScreenPosition()

Get the position of the most recently added cursor in screen coordinates.

Return values
Returns a Point.

::getCursorScreenPositions()

Get the position of all the cursor positions in screen coordinates.

Return values
Returns Array of Points in the order the cursors were added

::setCursorScreenPosition(position, options)

Move the cursor to the given position in screen coordinates.

If there are multiple cursors, they will be consolidated to a single cursor.

Argument	Description
`position`	A Point or Array of `[row, column]`
`options`	optional An Object combining options for ::clipScreenPosition with:
`autoscroll`	Determines whether the editor scrolls to the new cursor’s position. Defaults to true.

::addCursorAtBufferPosition(bufferPosition)

Add a cursor at the given position in buffer coordinates.

Argument	Description
`bufferPosition`	A Point or Array of `[row, column]`

Return values
Returns a Cursor.

::addCursorAtScreenPosition(screenPosition)

Add a cursor at the position in screen coordinates.

Argument	Description
`screenPosition`	A Point or Array of `[row, column]`

Return values
Returns a Cursor.

::hasMultipleCursors()

Return values
Returns Boolean indicating whether or not there are multiple cursors.

::moveUp(lineCount)

Move every cursor up one row in screen coordinates.

Argument	Description
`lineCount`	optional Number number of lines to move

::moveDown(lineCount)

Move every cursor down one row in screen coordinates.

Argument	Description
`lineCount`	optional Number number of lines to move

::moveLeft(columnCount)

Move every cursor left one column.

Argument	Description
`columnCount`	optional Number number of columns to move (default: 1)

::moveRight(columnCount)

Move every cursor right one column.

Argument	Description
`columnCount`	optional Number number of columns to move (default: 1)

::moveToBeginningOfLine()

Move every cursor to the beginning of its line in buffer coordinates.

::moveToBeginningOfScreenLine()

Move every cursor to the beginning of its line in screen coordinates.

::moveToFirstCharacterOfLine()

Move every cursor to the first non-whitespace character of its line.

::moveToEndOfLine()

Move every cursor to the end of its line in buffer coordinates.

::moveToEndOfScreenLine()

Move every cursor to the end of its line in screen coordinates.

::moveToBeginningOfWord()

Move every cursor to the beginning of its surrounding word.

::moveToEndOfWord()

Move every cursor to the end of its surrounding word.

Extended Methods

::moveToTop()

Move every cursor to the top of the buffer.

If there are multiple cursors, they will be merged into a single cursor.

::moveToBottom()

Move every cursor to the bottom of the buffer.

If there are multiple cursors, they will be merged into a single cursor.

::moveToBeginningOfNextWord()

Move every cursor to the beginning of the next word.

::moveToPreviousWordBoundary()

Move every cursor to the previous word boundary.

::moveToNextWordBoundary()

Move every cursor to the next word boundary.

::moveToPreviousSubwordBoundary()

Move every cursor to the previous subword boundary.

::moveToNextSubwordBoundary()

Move every cursor to the next subword boundary.

::moveToBeginningOfNextParagraph()

Move every cursor to the beginning of the next paragraph.

::moveToBeginningOfPreviousParagraph()

Move every cursor to the beginning of the previous paragraph.

::getLastCursor()

Return values
Returns the most recently added Cursor

::getWordUnderCursor(options)

Argument	Description
`options`	optional See Cursor::getBeginningOfCurrentWordBufferPosition.

Return values
Returns the word surrounding the most recently added cursor.

::getCursors()

Get an Array of all Cursors.

::getCursorsOrderedByBufferPosition()

Get all Cursors, ordered by their position in the buffer instead of the order in which they were added.

Return values
Returns an Array of Selections.

Selections

::getSelectedText()

Get the selected text of the most recently added selection.

Return values
Returns a String.

::getSelectedBufferRange()

Get the Range of the most recently added selection in buffer coordinates.

Return values
Returns a Range.

::getSelectedBufferRanges()

Get the Ranges of all selections in buffer coordinates.

The ranges are sorted by when the selections were added. Most recent at the end.

Return values
Returns an Array of Ranges.

::setSelectedBufferRange(bufferRange, options)

Set the selected range in buffer coordinates. If there are multiple selections, they are reduced to a single selection with the given range.

Argument	Description
`bufferRange`	A Range or range-compatible Array.
`options`	optional An options Object:
`reversed`	A Boolean indicating whether to create the selection in a reversed orientation.
`preserveFolds`	A Boolean, which if `true` preserves the fold settings after the selection is set.

::setSelectedBufferRanges(bufferRanges, options)

Set the selected ranges in buffer coordinates. If there are multiple selections, they are replaced by new selections with the given ranges.

Argument	Description
`bufferRanges`	An Array of Ranges or range-compatible Arrays.
`options`	optional An options Object:
`reversed`	A Boolean indicating whether to create the selection in a reversed orientation.
`preserveFolds`	A Boolean, which if `true` preserves the fold settings after the selection is set.

::getSelectedScreenRange()

Get the Range of the most recently added selection in screen coordinates.

Return values
Returns a Range.

::getSelectedScreenRanges()

Get the Ranges of all selections in screen coordinates.

The ranges are sorted by when the selections were added. Most recent at the end.

Return values
Returns an Array of Ranges.

::setSelectedScreenRange(screenRange, options)

Set the selected range in screen coordinates. If there are multiple selections, they are reduced to a single selection with the given range.

Argument	Description
`screenRange`	A Range or range-compatible Array.
`options`	optional An options Object:
`reversed`	A Boolean indicating whether to create the selection in a reversed orientation.

::setSelectedScreenRanges(screenRanges, options)

Set the selected ranges in screen coordinates. If there are multiple selections, they are replaced by new selections with the given ranges.

Argument	Description
`screenRanges`	An Array of Ranges or range-compatible Arrays.
`options`	optional An options Object:
`reversed`	A Boolean indicating whether to create the selection in a reversed orientation.

::addSelectionForBufferRange(bufferRange, options)

Add a selection for the given range in buffer coordinates.

Argument	Description
`bufferRange`	A Range
`options`	optional An options Object:
`reversed`	A Boolean indicating whether to create the selection in a reversed orientation.
`preserveFolds`	A Boolean, which if `true` preserves the fold settings after the selection is set.

Return values
Returns the added Selection.

::addSelectionForScreenRange(screenRange, options)

Add a selection for the given range in screen coordinates.

Argument	Description
`screenRange`	A Range
`options`	optional An options Object:
`reversed`	A Boolean indicating whether to create the selection in a reversed orientation.
`preserveFolds`	A Boolean, which if `true` preserves the fold settings after the selection is set. Returns the added Selection.

::selectToBufferPosition(position)

Select from the current cursor position to the given position in buffer coordinates.

This method may merge selections that end up intersecting.

Argument	Description
`position`	An instance of Point, with a given `row` and `column`.

::selectToScreenPosition(position)

Select from the current cursor position to the given position in screen coordinates.

This method may merge selections that end up intersecting.

Argument	Description
`position`	An instance of Point, with a given `row` and `column`.

::selectUp(rowCount)

Move the cursor of each selection one character upward while preserving the selection’s tail position.

This method may merge selections that end up intersecting.

Argument	Description
`rowCount`	optional Number number of rows to select (default: 1)

::selectDown(rowCount)

Move the cursor of each selection one character downward while preserving the selection’s tail position.

This method may merge selections that end up intersecting.

Argument	Description
`rowCount`	optional Number number of rows to select (default: 1)

::selectLeft(columnCount)

Move the cursor of each selection one character leftward while preserving the selection’s tail position.

This method may merge selections that end up intersecting.

Argument	Description
`columnCount`	optional Number number of columns to select (default: 1)

::selectRight(columnCount)

Move the cursor of each selection one character rightward while preserving the selection’s tail position.

This method may merge selections that end up intersecting.

Argument	Description
`columnCount`	optional Number number of columns to select (default: 1)

::selectToTop()

Select from the top of the buffer to the end of the last selection in the buffer.

This method merges multiple selections into a single selection.

::selectToBottom()

Selects from the top of the first selection in the buffer to the end of the buffer.

This method merges multiple selections into a single selection.

::selectAll()

Select all text in the buffer.

This method merges multiple selections into a single selection.

::selectToBeginningOfLine()

Move the cursor of each selection to the beginning of its line while preserving the selection’s tail position.

This method may merge selections that end up intersecting.

::selectToFirstCharacterOfLine()

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.

This method may merge selections that end up intersecting.

::selectToEndOfLine()

Move the cursor of each selection to the end of its line while preserving the selection’s tail position.

This method may merge selections that end up intersecting.

::selectToBeginningOfWord()

Expand selections to the beginning of their containing word.

Operates on all selections. Moves the cursor to the beginning of the containing word while preserving the selection’s tail position.

::selectToEndOfWord()

Expand selections to the end of their containing word.

Operates on all selections. Moves the cursor to the end of the containing word while preserving the selection’s tail position.

::selectLinesContainingCursors()

For each cursor, select the containing line.

This method merges selections on successive lines.

::selectWordsContainingCursors()

Select the word surrounding each cursor.

Extended Methods

::selectToPreviousSubwordBoundary()

For each selection, move its cursor to the preceding subword boundary while maintaining the selection’s tail position.

This method may merge selections that end up intersecting.

::selectToNextSubwordBoundary()

For each selection, move its cursor to the next subword boundary while maintaining the selection’s tail position.

This method may merge selections that end up intersecting.

::selectToPreviousWordBoundary()

For each selection, move its cursor to the preceding word boundary while maintaining the selection’s tail position.

This method may merge selections that end up intersecting.

::selectToNextWordBoundary()

For each selection, move its cursor to the next word boundary while maintaining the selection’s tail position.

This method may merge selections that end up intersecting.

::selectToBeginningOfNextWord()

Expand selections to the beginning of the next word.

Operates on all selections. Moves the cursor to the beginning of the next word while preserving the selection’s tail position.

::selectToBeginningOfNextParagraph()

Expand selections to the beginning of the next paragraph.

Operates on all selections. Moves the cursor to the beginning of the next paragraph while preserving the selection’s tail position.

::selectToBeginningOfPreviousParagraph()

Expand selections to the beginning of the next paragraph.

Operates on all selections. Moves the cursor to the beginning of the next paragraph while preserving the selection’s tail position.

::selectLargerSyntaxNode()

For each selection, select the syntax node that contains that selection.

::selectSmallerSyntaxNode()

Undo the effect a preceding call to ::selectLargerSyntaxNode.

::selectMarker(marker)

Select the range of the given marker if it is valid.

Argument	Description
`marker`	A DisplayMarker

Return values
Returns the selected Range or `undefined` if the marker is invalid.

::getLastSelection()

Get the most recently added Selection.

Return values
Returns a Selection.

::getSelections()

Get current Selections.

Return values
Returns: An Array of Selections.

::getSelectionsOrderedByBufferPosition()

Get all Selections, ordered by their position in the buffer instead of the order in which they were added.

Return values
Returns an Array of Selections.

::selectionIntersectsBufferRange(bufferRange)

Determine if a given range in buffer coordinates intersects a selection.

Argument	Description
`bufferRange`	A Range or range-compatible Array.

Return values
Returns a Boolean.

Searching and Replacing

::scan(regex, options, iterator)

Scan regular expression matches in the entire buffer, calling the given iterator function on each match.

::scan functions as the replace method as well via the replace

If you’re programmatically modifying the results, you may want to try ::backwardsScanInBufferRange to avoid tripping over your own changes.

Argument	Description
`regex`	A RegExp to search for.
`options`	optional Object
`leadingContextLineCount`	Number default `0`; The number of lines before the matched line to include in the results object.
`trailingContextLineCount`	Number default `0`; The number of lines after the matched line to include in the results object.
`iterator`	A Function that’s called on each match
`object`	Object
`match`	The current regular expression match.
`matchText`	A String with the text of the match.
`range`	The Range of the match.
`stop`	Call this Function to terminate the scan.
`replace`	Call this Function with a String to replace the match.

::scanInBufferRange(regex, range, iterator)

Scan regular expression matches in a given range, calling the given iterator function on each match.

Argument	Description
`regex`	A RegExp to search for.
`range`	A Range in which to search.
`iterator`	A Function that’s called on each match with an Object containing the following keys:
`match`	The current regular expression match.
`matchText`	A String with the text of the match.
`range`	The Range of the match.
`stop`	Call this Function to terminate the scan.
`replace`	Call this Function with a String to replace the match.

::backwardsScanInBufferRange(regex, range, iterator)

Scan regular expression matches in a given range in reverse order, calling the given iterator function on each match.

Argument	Description
`regex`	A RegExp to search for.
`range`	A Range in which to search.
`iterator`	A Function that’s called on each match with an Object containing the following keys:
`match`	The current regular expression match.
`matchText`	A String with the text of the match.
`range`	The Range of the match.
`stop`	Call this Function to terminate the scan.
`replace`	Call this Function with a String to replace the match.

Tab Behavior

::getSoftTabs()

Return values
Returns a Boolean indicating whether softTabs are enabled for this editor.

::setSoftTabs(softTabs)

Enable or disable soft tabs for this editor.

Argument	Description
`softTabs`	A Boolean

::toggleSoftTabs()

Toggle soft tabs for this editor

::getTabLength()

Get the on-screen length of tab characters.

Return values
Returns a Number.

::setTabLength(tabLength)

Set the on-screen length of tab characters. Setting this to a Number This will override the editor.tabLength setting.

Argument	Description
`tabLength`	Number length of a single tab. Setting to `null` will fallback to using the `editor.tabLength` config setting

Extended Methods

::usesSoftTabs()

Determine if the buffer uses hard or soft tabs.

Return values
Returns `true` if the first non-comment line with leading whitespace starts with a space character.
Returns `false` if it starts with a hard tab (`\t`).
Returns a Boolean or undefined if no non-comment lines had leading whitespace.

::getTabText()

Get the text representing a single level of indent.

If soft tabs are enabled, the text is composed of N spaces, where N is the tab length. Otherwise the text is a tab character (\t).

Return values
Returns a String.

Soft Wrap Behavior

::isSoftWrapped()

Determine whether lines in this editor are soft-wrapped.

Return values
Returns a Boolean.

::setSoftWrapped(softWrapped)

Enable or disable soft wrapping for this editor.

Argument	Description
`softWrapped`	A Boolean

Return values
Returns a Boolean.

::toggleSoftWrapped()

Toggle soft wrapping for this editor

Return values
Returns a Boolean.

::getSoftWrapColumn()

Gets the column at which column will soft wrap

Indentation

::indentationForBufferRow(bufferRow)

Get the indentation level of the given buffer row.

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.

Argument	Description
`bufferRow`	A Number indicating the buffer row.

Return values
Returns a Number.

::setIndentationForBufferRow(bufferRow, newLevel, options)

Set the indentation level for the given buffer row.

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.

Argument	Description
`bufferRow`	A Number indicating the buffer row.
`newLevel`	A Number indicating the new indentation level.
`options`	optional An Object with the following keys:
`preserveLeadingWhitespace`	`true` to preserve any whitespace already at the beginning of the line (default: false).

Extended Methods

::indentSelectedRows(options)

Indent rows intersecting selections by one level.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor.

::outdentSelectedRows(options)

Outdent rows intersecting selections by one level.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor.

::indentLevelForLine(line)

Get the indentation level of the given line of text.

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.

Argument	Description
`line`	A String representing a line of text.

Return values
Returns a Number.

::autoIndentSelectedRows(options)

Indent rows intersecting selections based on the grammar’s suggested indent level.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor.

Grammars

::getGrammar()

Get the current Grammar of this editor.

Managing Syntax Scopes

::getRootScopeDescriptor()

Return values
Returns a ScopeDescriptor that includes this editor’s language. e.g. `['.source.ruby']`, or `['.source.coffee']`. You can use this with Config::get to get language specific config values.

::scopeDescriptorForBufferPosition(bufferPosition)

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, this method returns a ScopeDescriptor with the following scopes array: ["source.coffee", "meta.function.inline.coffee", "meta.parameters.coffee", "variable.parameter.function.coffee"]

Argument	Description
`bufferPosition`	A Point or Array of `[row, column]`.

Return values
Returns a ScopeDescriptor.

::syntaxTreeScopeDescriptorForBufferPosition(bufferPosition)

Get the syntactic tree ScopeDescriptor for the given position in buffer coordinates or the syntactic ScopeDescriptor for TextMate language mode

For example, if called with a position inside the parameter list of a JavaScript class function, this method returns a ScopeDescriptor with the following syntax nodes array: ["source.js", "program", "expression_statement", "assignment_expression", "class", "class_body", "method_definition", "formal_parameters", "identifier"] if tree-sitter is used and the following scopes array: ["source.js"] if textmate is used

Argument	Description
`bufferPosition`	A Point or Array of `[row, column]`.

Return values
Returns a ScopeDescriptor.

Extended Methods

::bufferRangeForScopeAtCursor(scopeSelector)

Get the range in buffer coordinates of all tokens surrounding the cursor that match the given scope selector.

For example, if you wanted to find the string surrounding the cursor, you could call editor.bufferRangeForScopeAtCursor(".string.quoted").

Argument	Description
`scopeSelector`	String selector. e.g. `'.source.ruby'`

Return values
Returns a Range.

::bufferRangeForScopeAtPosition(scopeSelector, bufferPosition)

Get the range in buffer coordinates of all tokens surrounding the given position in buffer coordinates that match the given scope selector.

For example, if you wanted to find the string surrounding the cursor, you could call editor.bufferRangeForScopeAtPosition(".string.quoted", this.getCursorBufferPosition()).

Argument	Description
`scopeSelector`	String selector. e.g. `'.source.ruby'`
`bufferPosition`	A Point or Array of [row, column]

Return values
Returns a Range.

::isBufferRowCommented()

Determine if the given row is entirely a comment

Clipboard Operations

::copySelectedText()

For each selection, copy the selected text.

::cutSelectedText(options)

For each selection, cut the selected text.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor.

::pasteText(options)

For each selection, replace the selected text with the contents of the clipboard.

If the clipboard contains the same number of selections as the current editor, each selection will be replaced with the content of the corresponding clipboard selection text.

Argument	Description
`options`	optional See Selection::insertText.

::cutToEndOfLine(options)

For each selection, if the selection is empty, cut all characters of the containing screen line following the cursor. Otherwise cut the selected text.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor.

::cutToEndOfBufferLine(options)

For each selection, if the selection is empty, cut all characters of the containing buffer line following the cursor. Otherwise cut the selected text.

Argument	Description
`options`	optional Object
`bypassReadOnly`	optional Boolean Must be `true` to modify a read-only editor.

Argument	Description
`bufferRow`	A Number.

::unfoldBufferRow(bufferRow)

Unfold all folds containing the given row in buffer coordinates.

Argument	Description
`bufferRow`	A Number

Argument	Description
`level`	A Number starting at 0.

::isFoldableAtBufferRow(bufferRow)

Determine whether the given row in buffer coordinates is foldable.

A foldable row is a row that starts a row range that can be folded.

Argument	Description
`bufferRow`	A Number

Return values
Returns a Boolean.

::isFoldableAtScreenRow(bufferRow)

Determine whether the given row in screen coordinates is foldable.

A foldable row is a row that starts a row range that can be folded.

Argument	Description
`bufferRow`	A Number

Return values
Returns a Boolean.

::toggleFoldAtBufferRow()

Fold the given buffer row if it isn’t currently folded, and unfold it otherwise.

::isFoldedAtCursorRow()

Determine whether the most recently added cursor’s row is folded.

Return values
Returns a Boolean.

::isFoldedAtBufferRow(bufferRow)

Determine whether the given row in buffer coordinates is folded.

Argument	Description
`bufferRow`	A Number

Return values
Returns a Boolean.

::isFoldedAtScreenRow(screenRow)

Determine whether the given row in screen coordinates is folded.

Argument	Description
`screenRow`	A Number

Return values
Returns a Boolean.

Gutters

::addGutter(options)

Add a custom Gutter.

Argument	Description
`options`	An Object with the following fields:
`name`	(required) A unique String to identify this gutter.
`priority`	optional A Number that determines stacking order between gutters. Lower priority items are forced closer to the edges of the window. (default: -100)
`visible`	optional Boolean specifying whether the gutter is visible initially after being created. (default: true)
`type`	optional String specifying the type of gutter to create. `'decorated'` gutters are useful as a destination for decorations created with Gutter::decorateMarker. `'line-number'` gutters.
`class`	optional String added to the CSS classnames of the gutter’s root DOM element.
`labelFn`	optional Function called by a `'line-number'` gutter to generate the label for each line number element. Should return a String that will be used to label the corresponding line.
`lineData`	an Object containing information about each line to label.
`bufferRow`	Number indicating the zero-indexed buffer index of this line.
`screenRow`	Number indicating the zero-indexed screen index.
`foldable`	Boolean that is `true` if a fold may be created here.
`softWrapped`	Boolean if this screen row is the soft-wrapped continuation of the same buffer row.
`maxDigits`	Number the maximum number of digits necessary to represent any known screen row.
`onMouseDown`	optional Function to be called when a mousedown event is received by a line-number element within this `type: 'line-number'` Gutter. If unspecified, the default behavior is to select the clicked buffer row.
`lineData`	an Object containing information about the line that’s being clicked.
`bufferRow`	Number of the originating line element
`screenRow`	Number
`onMouseMove`	optional Function to be called when a mousemove event occurs on a line-number element within within this `type: 'line-number'` Gutter.
`lineData`	an Object containing information about the line that’s being clicked.
`bufferRow`	Number of the originating line element
`screenRow`	Number

Return values
Returns the newly-created Gutter.

::getGutters()

Get this editor’s gutters.

Return values
Returns an Array of Gutters.

::gutterWithName()

Get the gutter with the given name.

Return values
Returns a Gutter, or `null` if no gutter exists for the given name.

Scrolling the TextEditor

::scrollToCursorPosition(options)

Scroll the editor to reveal the most recently added cursor if it is off-screen.

Argument	Description
`options`	optional Object
`center`	Center the editor around the cursor if possible. (default: true)

::scrollToBufferPosition(bufferPosition, options)

Scrolls the editor to the given buffer position.

Argument	Description
`bufferPosition`	An object that represents a buffer position. It can be either an Object (`{row, column}`), Array (`[row, column]`), or Point
`options`	optional Object
`center`	Center the editor around the position if possible. (default: false)

::scrollToScreenPosition(screenPosition, options)

Scrolls the editor to the given screen position.

Argument	Description
`screenPosition`	An object that represents a screen position. It can be either an Object (`{row, column}`), Array (`[row, column]`), or Point
`options`	optional Object
`center`	Center the editor around the position if possible. (default: false)

TextEditor Rendering

::getPlaceholderText()

Retrieves the greyed out placeholder of a mini editor.

Return values
Returns a String.

::setPlaceholderText(placeholderText)

Set the greyed out placeholder of a mini editor. Placeholder text will be displayed when the editor has no content.

Argument	Description
`placeholderText`	String text that is displayed when the editor has no content.