Chapter 1: Getting Started

Chapter 2: Using Atom

Chapter 3: Hacking Atom

Chapter 4: Behind Atom

Reference: API

Appendix A: Resources

Glossary

Appendix B: FAQ

Appendix C: Shadow DOM

Removing Shadow DOM styles

Appendix D: Upgrading to 1.0 APIs

Appendix E: Atom server-side APIs

mac

windows

linux

Selection Extended

Represents a selection in the TextEditor.

Event Subscription

This section only has Extended methods.

Extended Methods

::onDidChangeRange(callback)

Calls your callback when the selection was moved.

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.

::onDidDestroy(callback)

Calls your callback when the selection was destroyed

Argument	Description
`callback`	Function

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

Managing the selection range

::getScreenRange()

Return values
Returns the screen Range for the selection.

::setScreenRange(screenRange, options)

Modifies the screen range for the selection.

Argument	Description
`screenRange`	The new Range to use.
`options`	optional Object options matching those found in ::setBufferRange.

::getBufferRange()

Return values
Returns the buffer Range for the selection.

::setBufferRange(bufferRange, options)

Modifies the buffer Range for the selection.

Argument	Description
`bufferRange`	The new Range to select.
`options`	optional Object with the keys:
`reversed`	Boolean indicating whether to set the selection in a reversed orientation.
`preserveFolds`	if `true`, the fold settings are preserved after the selection moves.
`autoscroll`	Boolean indicating whether to autoscroll to the new range. Defaults to `true` if this is the most recently added selection, `false` otherwise.

::getBufferRowRange()

Return values
Returns the starting and ending buffer rows the selection is highlighting.
Returns an Array of two Numbers: the starting row, and the ending row.

Info about the selection

::isEmpty()

Determines if the selection contains anything.

::isReversed()

Determines if the ending position of a marker is greater than the starting position.

This can happen when, for example, you highlight text “up” in a TextBuffer.

::isSingleScreenLine()

Return values
Returns whether the selection is a single line or not.

::getText()

Return values
Returns the text in the selection.

::intersectsBufferRange(bufferRange)

Identifies if a selection intersects with a given buffer range.

Argument	Description
`bufferRange`	A Range to check against.

Return values
Returns a Boolean

::intersectsWith(otherSelection)

Identifies if a selection intersects with another selection.

Argument	Description
`otherSelection`	A Selection to check against.

Return values
Returns a Boolean

Modifying the selected range

::clear(options)

Clears the selection, moving the marker to the head.

Argument	Description
`options`	optional Object with the following keys:
`autoscroll`	Boolean indicating whether to autoscroll to the new range. Defaults to `true` if this is the most recently added selection, `false` otherwise.

::selectToScreenPosition(position)

Selects the text from the current cursor position to a given screen position.

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

::selectToBufferPosition(position)

Selects the text from the current cursor position to a given buffer position.

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

::selectRight(columnCount)

Selects the text one position right of the cursor.

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

::selectLeft(columnCount)

Selects the text one position left of the cursor.

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

::selectUp(rowCount)

Selects all the text one position above the cursor.

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

::selectDown(rowCount)

Selects all the text one position below the cursor.

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

::selectToTop()

Selects all the text from the current cursor position to the top of the buffer.

::selectToBottom()

Selects all the text from the current cursor position to the bottom of the buffer.

::selectAll()

Selects all the text in the buffer.

::selectToBeginningOfLine()

Selects all the text from the current cursor position to the beginning of the line.

::selectToFirstCharacterOfLine()

Selects all the text from the current cursor position to the first character of the line.

::selectToEndOfLine()

Selects all the text from the current cursor position to the end of the screen line.

::selectToEndOfBufferLine()

Selects all the text from the current cursor position to the end of the buffer line.

::selectToBeginningOfWord()

Selects all the text from the current cursor position to the beginning of the word.

::selectToEndOfWord()

Selects all the text from the current cursor position to the end of the word.

::selectToBeginningOfNextWord()

Selects all the text from the current cursor position to the beginning of the next word.

::selectToPreviousWordBoundary()

Selects text to the previous word boundary.

::selectToNextWordBoundary()

Selects text to the next word boundary.

::selectToPreviousSubwordBoundary()

Selects text to the previous subword boundary.

::selectToNextSubwordBoundary()

Selects text to the next subword boundary.

::selectToBeginningOfNextParagraph()

Selects all the text from the current cursor position to the beginning of the next paragraph.

::selectToBeginningOfPreviousParagraph()

Selects all the text from the current cursor position to the beginning of the previous paragraph.

::selectWord()

Modifies the selection to encompass the current word.

Return values
Returns a Range.

::expandOverWord()

Expands the newest selection to include the entire word on which the cursors rests.

::selectLine(row)

Selects an entire line in the buffer.

Argument	Description
`row`	The line Number to select (default: the row of the cursor).

::expandOverLine()

Expands the newest selection to include the entire line on which the cursor currently rests.

It also includes the newline character.

Modifying the selected text

::insertText(text, options)

Replaces text at the current selection.

Argument	Description
`text`	A String representing the text to add
`options`	optional Object with keys:
`select`	If `true`, selects the newly added text.
`autoIndent`	If `true`, indents all inserted text appropriately.
`autoIndentNewline`	If `true`, indent newline appropriately.
`autoDecreaseIndent`	If `true`, decreases indent level appropriately (for example, when a closing bracket is inserted).
`preserveTrailingLineIndentation`	By default, when pasting multiple lines, Atom attempts to preserve the relative indent level between the first line and trailing lines, even if the indent level of the first line has changed from the copied text. If this option is `true`, this behavior is suppressed. level between the first lines and the trailing lines.
`normalizeLineEndings`	optional Boolean (default: true)
`undo`	Deprecated If `skip`, skips the undo stack for this operation. 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)

::backspace(options)

Removes the first character before the selection if the selection is empty otherwise it deletes the selection.

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

::deleteToPreviousWordBoundary(options)

Removes the selection or, if nothing is selected, then all characters from the start of the selection back to the previous word boundary.

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

::deleteToNextWordBoundary(options)

Removes the selection or, if nothing is selected, then all characters from the start of the selection up to the next word boundary.

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

::deleteToBeginningOfWord(options)

Removes from the start of the selection to the beginning of the current word if the selection is empty otherwise it deletes the selection.

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

::deleteToBeginningOfLine(options)

Removes from the beginning of the line which the selection begins on all the way through to the end of the selection.

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

::delete(options)

Removes the selection or the next character after the start of the selection if the selection is empty.

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

::deleteToEndOfLine(options)

If the selection is empty, removes all text from the cursor to the end of the line. If the cursor is already at the end of the line, it removes the following newline. If the selection isn’t empty, only deletes the contents of the selection.

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

::deleteToEndOfWord(options)

Removes the selection or all characters from the start of the selection to the end of the current word if nothing is selected.

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

::deleteToBeginningOfSubword(options)

Removes the selection or all characters from the start of the selection to the end of the current word if nothing is selected.

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

::deleteToEndOfSubword(options)

Removes the selection or all characters from the start of the selection to the end of the current word if nothing is selected.

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

::deleteSelectedText(options)

Removes only the selected text.

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

::deleteLine(options)

Removes the line at the beginning of the selection if the selection is empty unless the selection spans multiple lines in which case all lines are removed.

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

::joinLines(options)

Joins the current line with the one below it. Lines will be separated by a single space.

If there selection spans more than one line, all the lines are joined together.

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

::outdentSelectedRows(options)

Removes one level of indent from the currently selected rows.

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

::autoIndentSelectedRows(options)

Sets the indentation level of all selected rows to values suggested by the relevant grammars.

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

::toggleLineComments(options)

Wraps the selected lines in comments if they aren’t currently part of a comment.

Removes the comment if they are currently wrapped in a comment.

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

::cutToEndOfLine(maintainClipboard, options)

Cuts the selection until the end of the screen line.

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

::cutToEndOfBufferLine(maintainClipboard, options)

Cuts the selection until the end of the buffer line.

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

::cut(maintainClipboard, fullLine, bypassReadOnly)

Copies the selection to the clipboard and then deletes it.

Argument	Description
`maintainClipboard`	Boolean (default: false) See ::copy
`fullLine`	Boolean (default: false) See ::copy
`bypassReadOnly`	Boolean (default: false) Must be `true` to modify text within a read-only editor.

::copy(maintainClipboard, fullLine)

Copies the current selection to the clipboard.

Argument	Description
`maintainClipboard`	Boolean if `true`, a specific metadata property is created to store each content copied to the clipboard. The clipboard `text` still contains the concatenation of the clipboard with the current selection. (default: false)
`fullLine`	Boolean if `true`, the copied text will always be pasted at the beginning of the line containing the cursor, regardless of the cursor’s horizontal position. (default: false)

::fold()

Creates a fold containing the current selection.

::indentSelectedRows(options)

If the selection spans multiple rows, indent all of them.

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

Managing multiple selections

::addSelectionBelow()

Moves the selection down one row.

::addSelectionAbove()

Moves the selection up one row.

::merge(otherSelection, options)

Combines the given selection into this selection and then destroys the given selection.

Argument	Description
`otherSelection`	A Selection to merge with.
`options`	optional Object options matching those found in ::setBufferRange.

Comparing to other selections

::compare(otherSelection)

Compare this selection’s buffer range to another selection’s buffer range.

See Range::compare for more details.

Argument	Description
`otherSelection`	A Selection to compare against