• Packages
  • Themes
  • Documentation
  • Blog
  • Discuss

Chapter 1: Getting Started

  • Why Atom?
  • Installing Atom
  • Atom Basics
  • Summary

Chapter 2: Using Atom

  • Atom Packages
  • Moving in Atom
  • Atom Selections
  • Editing and Deleting Text
  • Find and Replace
  • Snippets
  • Autocomplete
  • Folding
  • Panes
  • Pending Pane Items
  • Grammar
  • Version Control in Atom
  • GitHub package
  • Writing in Atom
  • Basic Customization
  • Summary

Chapter 3: Hacking Atom

  • Tools of the Trade
  • The Init File
  • Package: Word Count
  • Package: Modifying Text
  • Package: Active Editor Info
  • Creating a Theme
  • Creating a Grammar
  • Creating a Legacy TextMate Grammar
  • Publishing
  • Iconography
  • Debugging
  • Writing specs
  • Handling URIs
  • Cross-Platform Compatibility
  • Converting from TextMate
  • Hacking on Atom Core
  • Contributing to Official Atom Packages
  • Creating a Fork of a Core Package in atom/atom
  • Maintaining a Fork of a Core Package in atom/atom
  • Summary

Chapter 4: Behind Atom

  • Configuration API
  • Keymaps In-Depth
  • Scoped Settings, Scopes and Scope Descriptors
  • Serialization in Atom
  • Developing Node Modules
  • Interacting With Other Packages Via Services
  • Maintaining Your Packages
  • How Atom Uses Chromium Snapshots
  • Summary

Reference: API

  • AtomEnvironment
  • BufferedNodeProcess
  • BufferedProcess
  • Clipboard
  • Color
  • CommandRegistry
  • CompositeDisposable
  • Config
  • ContextMenuManager
  • Cursor
  • Decoration
  • DeserializerManager
  • Directory
  • Disposable
  • Emitter
  • File
  • GitRepository
  • Grammar
  • GrammarRegistry
  • Gutter
  • KeymapManager
  • LayerDecoration
  • MarkerLayer
  • MenuManager
  • Notification
  • NotificationManager
  • Package
  • PackageManager
  • Pane
  • Panel
  • Point
  • Project
  • Range
  • ScopeDescriptor
  • Selection
  • StyleManager
  • Task
  • TextBuffer
  • TextEditor
  • TextEditorMarker
  • TextEditorMarkerLayer
  • ThemeManager
  • TooltipManager
  • ViewRegistry
  • Workspace

Appendix A: Resources

  • Glossary

Appendix B: FAQ

  • Is Atom open source?
  • What does Atom cost?
  • What platforms does Atom run on?
  • How can I contribute to Atom?
  • Why does Atom collect usage data?
  • Atom in the cloud?
  • What's the difference between an IDE and an editor?
  • How can I tell if subpixel antialiasing is working?
  • Why is Atom deleting trailing whitespace? Why is there a newline at the end of the file?
  • What does Safe Mode do?
  • I have a question about a specific Atom community package. Where is the best place to ask it?
  • I’m using an international keyboard and keys that use AltGr or Ctrl+Alt aren’t working
  • I’m having a problem with Julia! What do I do?
  • I’m getting an error about a “self-signed certificate”. What do I do?
  • I’m having a problem with PlatformIO! What do I do?
  • How do I make Atom recognize a file with extension X as language Y?
  • How do I make the Welcome screen stop showing up?
  • How do I preview web page changes automatically?
  • How do I accept input from my program or script when using the script package?
  • I am unable to update to the latest version of Atom on macOS. How do I fix this?
  • I’m trying to change my syntax colors from styles.less, but it isn’t working!
  • How do I build or execute code I've written in Atom?
  • How do I uninstall Atom on macOS?
  • macOS Mojave font rendering change
  • Why does macOS say that Atom wants to access my calendar, contacts, photos, etc.?
  • How do I turn on line wrap?
  • The menu bar disappeared, how do I get it back?
  • How do I use a newline in the result of find and replace?
  • What is this line on the right in the editor view?

Appendix C: Shadow DOM

  • Removing Shadow DOM styles

Appendix D: Upgrading to 1.0 APIs

  • Upgrading Your Package
  • Upgrading Your UI Theme Or Package Selectors
  • Upgrading Your Syntax Theme

Appendix E: Atom server-side APIs

  • Atom package server API
  • Atom update server API

  • mac
  • windows
  • linux

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. If you’re interested in the visual appearance of editors, use TextEditorElement instead.

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.

::getBuffer()

Retrieves the current TextBuffer.

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

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)

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

Argument Description

text

A String to replace with

::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

String ‘skip’ will skip the undo system

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()

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

::delete()

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

::backspace()

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

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()

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.

::upperCase()

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.

::lowerCase()

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.

::toggleLineCommentsInSelection()

Toggle line comments for rows intersecting selections.

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

::insertNewlineBelow()

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

::insertNewlineAbove()

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

::deleteToBeginningOfWord()

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

::deleteToPreviousWordBoundary()

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

::deleteToNextWordBoundary()

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

::deleteToBeginningOfSubword()

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

::deleteToEndOfSubword()

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

::deleteToBeginningOfLine()

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

::deleteToEndOfLine()

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.

::deleteToEndOfWord()

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

::deleteLine()

Delete all lines intersecting selections.

History

::undo()

Undo the last change.

::redo()

Redo the last change.

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()

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.

Return values

Returns a Boolean indicating whether the operation succeeded.

::groupChangesSinceCheckpoint()

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.

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

wrapBeyondNewlines

Boolean if true, continues wrapping past newlines

wrapAtSoftNewlines

Boolean if true, continues wrapping past soft newlines

screenLine

Boolean if true, indicates that you’re using a line number, not a row number

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. Returns a Range.

Decorations

::decorateMarker(marker, decorationParams)

Add a decoration that tracks a TextEditorMarker. 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
      <div class="highlight <your-class>">
        <!-- Will be one region for each row in the range. Spans 2 lines? There will be 2 regions. -->
        <div class="region"></div>
      </div>
    
  • overlay: Positions the view associated with the given item at the head or tail of the given TextEditorMarker.
  • gutter: A decoration that tracks a TextEditorMarker 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 TextEditorMarker.
Argument Description

marker

A TextEditorMarker you want this decoration to follow.

decorationParams

An Object representing the decoration e.g. {type: 'line-number', class: 'linter-error'}

type

There are several supported decoration types. The behavior of the types are as follows:

line

Adds the given class to the lines overlapping the rows spanned by the TextEditorMarker.

line-number

Adds the given class to the line numbers overlapping the rows spanned by the TextEditorMarker.

highlight

Creates a .highlight div with the nested class with up to 3 nested regions that fill the area spanned by the TextEditorMarker.

overlay

Positions the view associated with the given item at the head or tail of the given TextEditorMarker, depending on the position property.

gutter

Tracks a TextEditorMarker in a Gutter. 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 TextEditorMarker, depending on the position property.

class

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

item

optional

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

onlyHead

optional

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

onlyEmpty

optional

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

onlyNonEmpty

optional

If true, the decoration will only be applied if the associated TextEditorMarker is non-empty. Only applicable to the gutter, line, and line-number 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.

Return values

Returns a Decoration object

::decorateMarkerLayer(markerLayer, decorationParams)

Experimental: 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.

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

Argument Description

markerLayer

A TextEditorMarkerLayer 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)

persistent

optional

Boolean Whether to include this marker when serializing the buffer. (default: true)

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

::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)

persistent

optional

Boolean Whether to include this marker when serializing the buffer. (default: true)

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

::markBufferPosition(position, options)

Mark the given position in buffer coordinates on the default marker layer.

Argument Description

position

A Point or Array of [row, column].

options

optional

See TextBuffer::markRange.

Return values

Returns a TextEditorMarker.

::markScreenPosition(position, options)

Mark the given position in screen coordinates on the default marker layer.

Argument Description

position

A Point or Array of [row, column].

options

optional

See TextBuffer::markRange.

Return values

Returns a TextEditorMarker.

::findMarkers(properties)

Find all TextEditorMarkers 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.

::getMarkerLayer(id)

Experimental: Get a TextEditorMarkerLayer by id.

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

Argument Description

id

The id of the marker layer to retrieve.

Return values

Returns a MarkerLayer or `` if no layer exists with the given id.

::getDefaultMarkerLayer()

Experimental: Get the default TextEditorMarkerLayer.

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

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

Return values

Returns a TextEditorMarkerLayer.

Extended Methods

::getMarker(id)

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

Argument Description

id

Number id of the marker

::getMarkers()

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

::getMarkerCount()

Get the number of markers in the default marker layer.

Return values

Returns a Number.

::addMarkerLayer(options)

Experimental: Create a marker layer to group related markers.

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

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.

Return values

Returns a TextEditorMarkerLayer.

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 combining options for ::clipScreenPosition with:

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

::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 Cursorss, 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.

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.

Return values

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

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

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

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

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

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

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

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

::selectMarker(marker)

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

Argument Description

marker

A TextEditorMarker

Return values

Returns the selected Range or `` 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, 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.

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 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()

Get the indentation level of the given a buffer row.

Return values

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

  • bufferRow A Number indicating the buffer row.

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()

Indent rows intersecting selections by one level.

::outdentSelectedRows()

Outdent rows intersecting selections by one level.

::indentLevelForLine()

Get the indentation level of the given line of text.

Return values

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

  • line A String representing a line of text.

Returns a Number.

::autoIndentSelectedRows()

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

Grammars

::getGrammar()

Get the current Grammar of this editor.

::setGrammar(grammar)

Set the current Grammar of this editor.

Assigning a grammar will cause the editor to re-tokenize based on the new grammar.

Argument Description

grammar

Grammar

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

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.

::isBufferRowCommented()

Determine if the given row is entirely a comment

Clipboard Operations

::copySelectedText()

For each selection, copy the selected text.

::cutSelectedText()

For each selection, cut the selected text.

::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()

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

::cutToEndOfBufferLine()

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

Folds

::foldCurrentRow()

Fold the most recent cursor’s row based on its indentation level.

The fold will extend from the nearest preceding line with a lower indentation level up to the nearest following row with a lower indentation level.

::unfoldCurrentRow()

Unfold the most recent cursor’s row by one level.

::foldBufferRow(bufferRow)

Fold the given row in buffer coordinates based on its indentation level.

If the given row is foldable, the fold will begin there. Otherwise, it will begin at the first foldable row preceding the given row.

Argument Description

bufferRow

A Number.

::unfoldBufferRow(bufferRow)

Unfold all folds containing the given row in buffer coordinates.

Argument Description

bufferRow

A Number

Extended Methods

::foldSelectedLines()

For each selection, fold the rows it intersects.

::foldAll()

Fold all foldable lines.

::unfoldAll()

Unfold all existing folds.

::foldAllAtIndentLevel(level)

Fold all foldable lines at the given indent level.

Argument Description

level

A Number.

::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)

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.

  • Terms of Use
  • Privacy
  • Code of Conduct
  • Releases
  • FAQ
  • Contact
  • Contribute!
with by