Class Editor

Defined in: ../atom/src/editor.coffee
Inherits: Model

Overview

The core model of Atom.

An Editor represents a unique view of each document, with its own {Cursor}s and scroll position.

For instance if a user creates a split, Atom creates a second Editor but both Editors interact with the same buffer underlying buffer. So if you type in either buffer it immediately appears in both but if you scroll in one it doesn't scroll the other.

Almost all packages will interact primiarily with this class as it provides access to objects you'll most commonly interact with. To access it you'll want to register a callback on {WorkspaceView} which will be fired once for every existing Editor as well as any future Editors.

Example

  atom.workspaceView.eachEditorView (editorView) ->
    editorView.insertText('Hello World')

Instance Method Summary

Instance Method Details

::addCursor(marker) Source

Adds and returns a cursor at the given {DisplayBufferMarker} position.

::addCursorAtBufferPosition(bufferPosition) Source

Adds and returns a cursor at the given buffer position.

::addCursorAtScreenPosition(screenPosition) Source

Adds and returns a cursor at the given screen position.

Selection ::addSelection(marker, options = {}) Source

Creates a new selection at the given marker.

Parameters:

  • (DisplayBufferMarker) markerThe {DisplayBufferMarker} to highlight
  • (Object) optionsAn Object that pertains to the {Selection} constructor.

Returns:

  • (Selection) — Returns the new {Selection}.

::addSelectionAbove() Source

Moves each local selection up one row.

::addSelectionBelow() Source

Moves each local selection down one row.

Selection ::addSelectionForBufferRange(bufferRange, options = {}) Source

Given a buffer range, this adds a new selection for it.

Parameters:

Returns:

  • (Selection) — Returns the new {Selection}.

::autoIndentSelectedRows() Source

Indents selected lines based on grammar's suggested indent levels.

::backspace() Source

Removes the character found behind the current cursor position.

FIXME: Does this remove content from all cursors or the last one?

::backspaceToBeginningOfLine() Source

Removes all characters from the current cursor position to the start of the line.

::backspaceToBeginningOfWord() Source

Removes all characters from the current cursor position until the beginging of the current word.

Range ::bufferRangeForBufferRow(row, options) Source

Returns the range for the given buffer row.

Parameters:

  • (Number) rowA row Number.
  • optionsAn options hash with an includeNewline key.

Returns:

  • (Range) — Returns a {Range}.

::bufferRangeForScopeAtCursor(selector) Source

?

::clearSelections() Source

Clears every selection.

TODO: Is this still to be done?

Point ::clipBufferPosition(bufferPosition) Source

Given a position, this clips it to a real position.

For example, if bufferPosition's row exceeds the row count of the buffer, or if its column goes beyond a line's length, this "sanitizes" the value to a real position.

Parameters:

  • (Point) bufferPositionThe {Point} to clip.

Returns:

  • (Point) — Returns the new, clipped {Point}. Note that this could be the same as `bufferPosition` if no clipping was performed.

Range ::clipBufferRange(range) Source

Given a range, this clips it to a real range.

For example, if range's row exceeds the row count of the buffer, or if its column goes beyond a line's length, this "sanitizes" the value to a real range.

Parameters:

  • (Range) rangeThe {Range} to clip.

Returns:

  • (Range) — Returns the new, clipped {Range}. Note that this could be the same as `range` if no clipping was performed.

::copySelectedText() Source

Copies the selected text.

::cutSelectedText() Source

Cuts the selected text.

::cutToEndOfLine() Source

Copies and removes all characters from cursor to the end of the line.

::delete() Source

Removes the current selection or the next character after the cursor.

::deleteLine() Source

Deletes the entire line.

::deleteToEndOfWord() Source

Removes all characters from the cursor until the end of the current word.

::destroyFoldsIntersectingBufferRange(bufferRange) Source

Removes any {Fold}s found that intersect the given buffer row.

::destroyMarker(args...) Source

::duplicateLine() Source

Duplicates the current line.

If more than one cursor is present, only the most recently added one is duplicated.

::findMarkers(attributes) Source

Returns all {DisplayBufferMarker}s that match all given attributes.

::foldCurrentRow() Source

Folds the current row.

::foldSelection() Source

Folds all selections.

::getCurrentParagraphBufferRange() Source

Returns the text of the most recent local cursor's surrounding paragraph.

::getCursor() Source

Returns the most recently added {Cursor}.

Array ::getCursorBufferPosition() Source

Gets the current buffer position of the most recently added {Cursor}.

Returns:

  • (Array) — Returns an Array of two numbers: the buffer row, and the buffer column.

Array ::getCursorScopes() Source

Retrieves the grammar's token scopes for the line with the most recently added cursor.

Returns:

Array ::getCursorScreenPosition() Source

Gets the current screen position of the most recently added local {Cursor}.

Returns:

  • (Array) — Returns an Array of two numbers: the screen row, and the screen column.

Number ::getCursorScreenRow() Source

Gets the screen row of the most recently added local {Cursor}.

Returns:

  • (Number) — Returns the screen row Number.

::getCursors() Source

Returns an Array of all local {Cursor}s.

::getLastBufferRow() Source

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

::getLastSelection() Source

Returns the most recently added {Selection}

Selection ::getLastSelectionInBuffer() Source

Gets the very last local selection in the buffer.

Returns:

  • (Selection) — Returns a {Selection}.

::getLineCount() Source

Returns a Number representing the number of lines in the editor.

String ::getLongTitle() Source

Retrieves the filename and path of the open file.

It has the follows the following format, <filename> - <directory>. If the file is brand new, the title is untitled.

Returns:

  • (String) — Returns a String.

::getMarker(id) Source

Returns a valid {DisplayBufferMarker} object for the given id.

Number ::getMarkerCount() Source

Get the number of markers in this editor's buffer.

Returns:

  • (Number) — Returns a Number.

::getMarkers() Source

Returns all {DisplayBufferMarker}s.

::getSelectedBufferRange() Source

Returns the buffer {Range} of the most recently added local {Selection}.

::getSelectedBufferRanges() Source

Gets an Array of buffer {Range}s of all the local {Selection}s.

Sorted by their position in the file itself.

::getSelectedScreenRange() Source

Returns the screen {Range} of the most recently added local {Selection}.

::getSelectedText() Source

Returns the selected text of the most recently added local {Selection}.

::getSelection(index) Source

Returns the selection at the specified index.

Array ::getSelections() Source

Gets all local selections.

Returns:

  • (Array) — Returns an Array of {Selection}s.

Array ::getSelectionsOrderedByBufferPosition() Source

Gets all local selections, ordered by their position in the buffer.

Returns:

  • (Array) — Returns an Array of {Selection}s.

::getSoftWrap() Source

Returns whether soft wrap is enabled or not.

::getSoftWrapColumn() Source

Sets the column at which columsn will soft wrap

::getTabLength() Source

Returns the current tab length.

::getTabText() Source

Returns that String used to indicate a tab.

If soft tabs are enabled, this is a space (" ") times the ::getTabLength value. Otherwise, it's a tab (\t).

::getText() Source

Returns a String representing the entire contents of the editor.

::getTextInBufferRange(range) Source

Returns the text within a given a buffer {Range}

::getTextInRange(range) Source

Returns a String of text in the given {Range}.

String ::getTitle() Source

Retrieves the filename of the open file.

This is 'untitled' if the file is new and not saved to the disk.

Returns:

  • (String) — Returns a String.

::getUri() Source

Retrieves the current buffer's URI.

::getWordUnderCursor(options) Source

Returns the word under the most recently added local {Cursor}.

Parameters:

  • optionsAn object with properties based on {Cursor::getBeginningOfCurrentWordBufferPosition}.

::hasMultipleCursors() Source

Determines if there are multiple cursors.

::indent(options = {}) Source

Indents the current line.

Parameters:

  • optionsA set of options equivalent to {Selection::indent}.

Number ::indentLevelForLine(line) Source

Returns the indentation level of the given line of text.

Parameters:

  • (String) lineA String in the current buffer.

Returns:

  • (Number) — Returns a Number or 0 if the text isn't found within the buffer.

::indentSelectedRows() Source

Indents the currently selected rows.

FIXME: what does this do if no selection?

::indentationForBufferRow(bufferRow) Source

Returns the indentation level of the given a buffer row

Parameters:

  • (Number) bufferRowA Number indicating the buffer row.

::insertNewline() Source

Inserts a new line at the current cursor positions.

::insertNewlineAbove() Source

Inserts a new line above the current cursor positions.

::insertNewlineBelow() Source

Inserts a new line below the current cursor positions.

::insertText(text, options = {}) Source

Inserts text at the current cursor positions

Parameters:

  • (String) textA String representing the text to insert.
  • optionsA set of options equivalent to {Selection::insertText}.

::isBufferRowCommented(bufferRow) Source

Determine if the given row is entirely a comment

Boolean ::isEqual(other) Source

Compares two Editors to determine equality.

Equality is based on the condition that:

  • the two {TextBuffer}s are the same
  • the two scrollTop and scrollLeft property are the same
  • the two {Cursor} screen positions are the same

Returns:

::isFoldedAtBufferRow(bufferRow) Source

Returns whether a given buffer row if folded

::isFoldedAtCursorRow() Source

Returns whether the current row is folded.

::isFoldedAtScreenRow(screenRow) Source

Returns whether a given screen row if folded

::joinLine() Source

Joins the current line with the one below it.

FIXME: Needs more clarity.

Multiple cursors are considered equally. If there's a selection in the editor, all the lines are joined together.

::lineForBufferRow(row) Source

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

Parameters:

  • (Number) rowA Number representing a zero-indexed buffer row.

::lineLengthForBufferRow(row) Source

Returns a Number representing the line length for the given buffer row, exclusive of its line-ending character(s).

Parameters:

  • (Number) rowA Number indicating the buffer row.

::lowerCase() Source

Lowercases all locally selected text.

::markBufferPosition(args...) Source

::markBufferRange(args...) Source

::markScreenPosition(args...) Source

::markScreenRange(args...) Source

::moveCursorDown(lineCount) Source

Moves every local cursor down one row.

::moveCursorLeft() Source

Moves every local cursor left one column.

::moveCursorRight() Source

Moves every local cursor right one column.

::moveCursorToBeginningOfLine() Source

Moves every local cursor to the beginning of the buffer line.

::moveCursorToBeginningOfNextWord() Source

Moves every local cursor to the beginning of the next word.

::moveCursorToBeginningOfScreenLine() Source

Moves every local cursor to the beginning of the line.

::moveCursorToBeginningOfWord() Source

Moves every local cursor to the beginning of the current word.

::moveCursorToBottom() Source

Moves every local cursor to the bottom of the buffer.

::moveCursorToEndOfLine() Source

Moves every local cursor to the end of the buffer line.

::moveCursorToEndOfScreenLine() Source

Moves every local cursor to the end of the line.

::moveCursorToEndOfWord() Source

Moves every local cursor to the end of the current word.

::moveCursorToFirstCharacterOfLine() Source

Moves every local cursor to the first non-whitespace character of the line.

::moveCursorToNextWordBoundary() Source

Moves every local cursor to the next word boundary.

::moveCursorToPreviousWordBoundary() Source

Moves every local cursor to the previous word boundary.

::moveCursorToTop() Source

Moves every local cursor to the top of the buffer.

::moveCursorUp(lineCount) Source

Moves every local cursor up one row.

::moveLineDown() Source

Moves the selected lines down one screen row.

::moveLineUp() Source

Moves the selected lines up one screen row.

::normalizeTabsInBufferRange(bufferRange) Source

Converts all indents to the current ::getTabText given a {Range}.

::outdentSelectedRows() Source

Outdents the selected rows.

FIXME: what does this do if no selection?

::pasteText(options = {}) Source

Pastes the text in the clipboard.

Parameters:

  • optionsA set of options equivalent to {Selection::insertText}.

::removeCursor(cursor) Source

Removes and returns a cursor from the Editor.

::removeSelection(selection) Source

Unselects a given selection.

Parameters:

  • (Selection) selectionThe {Selection} to remove.

::selectAll() Source

Selects all the text in the buffer.

::selectDown(rowCount) Source

Selects all the text one position below all local cursors.

::selectLeft() Source

Selects the text one position left of all local cursors.

::selectLine() Source

Selects the current line from each local cursor.

Range ::selectMarker(marker) Source

Selects the range associated with the given marker if it is valid.

Returns:

  • (Range) — Returns the selected {Range} or a falsy value if the marker is invalid.

::selectRight() Source

Selects the text one position right of all local cursors.

::selectToBeginningOfLine() Source

Selects all the text from all local cursors to the beginning of each of their lines.

::selectToBeginningOfNextWord() Source

Selects all the text from all local cursors to the beginning of the next word.

::selectToBeginningOfWord() Source

Selects all the text from all local cursors to the beginning of their current words.

::selectToBottom() Source

Selects all the text from all local cursors to the bottom of the buffer.

::selectToEndOfLine() Source

Selects all the text from each local cursor to the end of their lines.

::selectToEndOfWord() Source

Selects all the text from all local cursors to the end of their current words.

::selectToFirstCharacterOfLine() Source

Selects to the first non-whitespace character of the line of all local cursors.

::selectToNextWordBoundary() Source

Selects all text from each local cursor to their next word boundary.

::selectToPreviousWordBoundary() Source

Selects all text from each local cursor to their previous word boundary.

::selectToScreenPosition(position) Source

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

Parameters:

  • (Point) positionAn instance of {Point}, with a given row and column.

::selectToTop() Source

Selects all the text from all local cursors to the top of the buffer.

::selectUp(rowCount) Source

Selects all the text one position above all local cursors.

::selectWord() Source

Selects the current word of each local cursor.

Boolean ::selectionIntersectsBufferRange(bufferRange) Source

Determines if a given buffer range is included in a {Selection}.

Parameters:

  • (Range) bufferRangeThe {Range} you're checking against.

Returns:

::setCursorBufferPosition(position, options) Source

Moves every cursor to a given buffer position.

Parameters:

  • (Array) positionAn Array of two numbers: the buffer row, and the buffer column.
  • optionsAn object with properties based on {Cursor::setBufferPosition}.

::setCursorScreenPosition(position, options) Source

Moves every local cursor to a given screen position.

Parameters:

  • (Array) positionAn Array of two numbers: the screen row, and the screen column.
  • (Object) optionsAn Object with properties based on {Cursor::setScreenPosition}.

::setEditorWidthInChars(editorWidthInChars) Source

Set the number of characters that can be displayed horizontally in the editor.

Parameters:

  • (Number) editorWidthInCharsA Number of characters

::setIndentationForBufferRow(bufferRow, newLevel) Source

Sets the indentation level for the given buffer row.

Parameters:

  • (Number) bufferRowA Number indicating the buffer row.
  • (Number) newLevelA Number indicating the new indentation level.

::setSelectedBufferRange(bufferRange, options) Source

Given a buffer range, this removes all previous selections and creates a new selection for it.

Parameters:

::setSelectedBufferRanges(bufferRanges, options = {}) Source

Given an array of buffer ranges, this removes all previous selections and creates new selections for them.

Parameters:

::setSoftWrap(softWrap) Source

Controls whether soft tabs are enabled or not.

::setTabLength(tabLength) Source

Sets the current tab length.

::setText(text) Source

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

::setVisible(visible) Source

Controls visiblity based on the given Boolean.

::shouldPromptToSave() Source

Determines if the user should be prompted to save before closing.

::splitSelectionsIntoLines() Source

Split any multi-line selections into one selection per line.

This methods break apart all multi-line selections to create multiple single-line selections that cumulatively cover the same original area.

::toggleFoldAtBufferRow(bufferRow) Source

Folds the given buffer row if it's not currently folded, and unfolds it otherwise.

Array ::toggleLineCommentsInSelection() Source

Wraps the lines within a selection in comments.

If the language doesn't have comments, nothing happens.

Returns:

  • (Array) — Returns an Array of the commented {Range}s.

::transact(fn) Source

Performs all editor actions from the given function within a single undo step.

Useful for implementing complex operations while still ensuring that the undo stack remains relevant.

::transpose() Source

Transposes the current text selections.

The text in each selection is reversed so abcd would become dcba. The characters before and after the cursor are swapped when the selection is empty so x|y would become y|x where | is the cursor location.

::undo() Source

Undoes the last change.

::unfoldCurrentRow() Source

Unfolds the current row.

::upperCase() Source

Uppercases all locally selected text.