Editor

Import :

const Editor = brackets.getModule("editor/Editor")

Editor

Kind: global class

• Editor
  • new Editor(document, makeMasterEditor, container, [range], options)
  • instance
    • .addInlineWidget ⇒ $.Promise
    • .removeAllInlineWidgets
    • .removeInlineWidget ⇒ $.Promise
    • .removeAllInlineWidgetsForLine
    • .getAllInlineWidgetsForLine
    • .getInlineWidgets ⇒ Object
    • .getFocusedInlineWidget ⇒ InlineWidget
    • .setInlineWidgetHeight
    • .document : Document
    • .getInlineWidgetsBelowCursor() ⇒ boolean
    • .canConsumeEscapeKeyEvent()
    • .destroy()
    • .selectAllNoScroll()
    • .isTextSubset() ⇒ boolean
    • .getFile() ⇒ File
    • .getCursorPos([expandTabs], [which]) ⇒ Object
    • .getEndingCursorPos([expandTabs]) ⇒ Object
    • .getColOffset(pos) ⇒ number
    • .getCharIndexForColumn(lineNum, column) ⇒ number
    • .setCursorPos(line, ch, [center], [expandTabs])
    • .setSize(width, height)
    • .getViewport() ⇒ Object
    • .centerOnCursor(centerOptions)
    • .indexFromPos(cursorPos) ⇒ number
    • .posFromIndex(index) ⇒ Object
    • .posWithinRange(pos, start, end, endInclusive)
    • .hasSelection() ⇒ boolean
    • .getSelection() ⇒ Object
    • .getSelections() ⇒ Object
    • .hasMultipleCursors() ⇒ boolean
    • .convertToLineSelections(selections, options) ⇒ Object
    • .getSelectedText([allSelections]) ⇒ string
    • .coordsChar(coordinates, [mode]) ⇒ Object
    • .charCoords(pos, [mode]) ⇒ Object
    • .getToken([cursor], [precise]) ⇒ Object
    • .getCharacterAtPosition(pos) ⇒ string | null
    • .getPrevCharacterAtPosition(pos) ⇒ string | null
    • .getNextToken([cursor], [skipWhitespace], [precise]) ⇒ Object
    • .getPreviousToken([cursor], [skipWhitespace], [precise]) ⇒ Object
    • .operation(execFn) ⇒ *
    • .markToken(markType, cursor, [options]) ⇒ Object
    • .setBookmark(markType, [cursorPos], [options]) ⇒ Object
    • .findMarks(cursorFrom, cursorTo, [markType]) ⇒ Array.<TextMarker>
    • .findMarksAt(cursorPos, [markType]) ⇒ Array.<TextMarker>
    • .getMarksAfter(position, markType) ⇒ Array.<TextMarker>
    • .getMarksBefore(position, markType) ⇒ Array.<TextMarker>
    • .getAllMarks([markType]) ⇒ Array.<TextMarker>
    • .clearAllMarks([markType])
    • .isSamePosition(position1, position2) ⇒ boolean
    • .getHistory() ⇒ Array
    • .setHistory()
    • .createHistoryRestorePoint(restorePointName)
    • .restoreHistoryPoint(restorePointName)
    • .setSelection(start, [end], [center], [centerOptions], [origin])
    • .replaceSelection(replacement, [select])
    • .replaceSelections(replacement, [select])
    • .replaceRange(replacement, from, [to], origin)
    • .replaceMultipleRanges(ranges, [origin])
    • .clearSelection()
    • .setSelections(selections, center, centerOptions, origin)
    • .toggleOverwrite(start)
    • .selectWordAt(pos)
    • .getTextBetween(startPos, endPos) ⇒ string
    • .getWordAt(pos) ⇒ Object
    • .getNumberAt(pos, maxDigits) ⇒ Object
    • .lineCount() ⇒ number
    • .isLineVisible(zero-based) ⇒ boolean
    • .getFirstVisibleLine() ⇒ number
    • .getLastVisibleLine() ⇒ number
    • .totalHeight() ⇒ number
    • .getScrollerElement() ⇒ HTMLDivElement
    • .getRootElement() ⇒ HTMLDivElement
    • .getScrollPos() ⇒ Object
    • .adjustScrollPos(scrollPos, heightDelta)
    • .setScrollPos(x, y)
    • .getTextHeight() ⇒ number
    • .displayErrorMessageAtCursor(errorMsg)
    • .getVirtualScrollAreaTop() ⇒ number
    • .focus()
    • .hasFocus()
    • .getViewState() ⇒ EditorViewState
    • .restoreViewState(viewState)
    • .refresh([handleResize])
    • .refreshAll([handleResize])
    • .undo()
    • .redo()
    • .notifyVisibilityChange(show, refresh)
    • .setVisible(show, refresh)
    • .isFullyVisible()
    • .getModeForRange(start, end, [knownMixed]) ⇒ Object | string
    • .getModeForSelection(selection) ⇒ Object | string
    • .getLanguageForSelection() ⇒ Language
    • .getLanguageForPosition() ⇒ Language
    • .getModeForDocument() ⇒ Object | String
    • .updateLayout([forceRefresh])
    • .setGutterMarker(lineNumber, gutterName, marker)
    • .getGutterMarker(lineNumber, gutterName)
    • .clearGutterMarker(lineNumber, gutterName)
    • .clearGutter(gutterName)
  • static
    • .getMarkOptionUnderlineError
    • .getMarkOptionUnderlineWarn
    • .getMarkOptionUnderlineInfo
    • .getMarkOptionUnderlineSpellcheck
    • .getMarkOptionHyperlinkText
    • .getMarkOptionMatchingRefs
    • .getMarkOptionRenameOutline
    • .getRegisteredGutters() ⇒ Object
    • .isGutterRegistered(gutterName) ⇒ boolean
    • .registerGutter(name, priority, [languageIds])
    • .unregisterGutter(name)
    • .setUseTabChar(value, [fullPath]) ⇒ boolean
    • .getUseTabChar([fullPath]) ⇒ boolean
    • .setTabSize(value, [fullPath]) ⇒ boolean
    • .getTabSize([fullPath]) ⇒ number
    • .getAutoTabUnits(fullPath) ⇒ number | *
    • .setAutoTabSpaces(value, [fullPath]) ⇒ boolean
    • .getAutoTabSpaces([fullPath]) ⇒ number
    • .setSpaceUnits(value, [fullPath]) ⇒ boolean
    • .getSpaceUnits([fullPath]) ⇒ number
    • .setCloseBrackets(value, [fullPath]) ⇒ boolean
    • .getCloseBrackets([fullPath]) ⇒ boolean
    • .setShowLineNumbers(value, [fullPath]) ⇒ boolean
    • .getShowLineNumbers([fullPath]) ⇒ boolean
    • .setShowActiveLine(value, [fullPath]) ⇒ boolean
    • .getShowActiveLine([fullPath]) ⇒ boolean
    • .setWordWrap(value, [fullPath]) ⇒ boolean
    • .getWordWrap([fullPath]) ⇒ boolean
    • .setIndentLineComment(value, [fullPath]) ⇒ boolean
    • .getIndentLineComment([fullPath]) ⇒ boolean
    • .forEveryEditor(callback, [fullPath])

new Editor(document, makeMasterEditor, container, [range], options)

Creates a new CodeMirror editor instance bound to the given Document. The Document need not have a "master" Editor realized yet, even if makeMasterEditor is false; in that case, the first time an edit occurs we will automatically ask EditorManager to create a "master" editor to render the Document modifiable.

ALWAYS call destroy() when you are done with an Editor - otherwise it will leak a Document ref.

Param	Type	Description
document	Document
makeMasterEditor	boolean	If true, this Editor will set itself as the (secret) "master" Editor for the Document. If false, this Editor will attach to the Document as a "slave"/ secondary editor.
container	jQueryObject | DomNode	Container to add the editor to.
[range]	Object	If specified, range of lines within the document to display in this editor. Inclusive.
options	Object	If specified, contains editor options that can be passed to CodeMirror

editor.addInlineWidget ⇒ $.Promise

Adds an inline widget below the given line. If any inline widget was already open for that line, it is closed without warning.

Kind: instance property of Editor
Returns: $.Promise - A promise object that is resolved when the widget has been added (but might still be animating open). Never rejected.

Param	Type	Description
pos	Object	Position in text to anchor the inline.
inlineWidget	InlineWidget	The widget to add.
[scrollLineIntoView]	boolean	Scrolls the associated line into view. Default true.

editor.removeAllInlineWidgets

Removes all inline widgets

Kind: instance property of Editor

editor.removeInlineWidget ⇒ $.Promise

Removes the given inline widget.

Kind: instance property of Editor
Returns: $.Promise - A promise that is resolved when the inline widget is fully closed and removed from the DOM.

Param	Type	Description
inlineWidget	number	The widget to remove.

editor.removeAllInlineWidgetsForLine

Removes all inline widgets for a given line

Kind: instance property of Editor

Param	Type	Description
lineNum	number	The line number to modify

editor.getAllInlineWidgetsForLine

****** Update actual public API doc in Editor.js ***** Gets all inline widgets for a given line

Kind: instance property of Editor

Param	Type	Description
lineNum	number	The line number to modify

editor.getInlineWidgets ⇒ Object

Returns a list of all inline widgets currently open in this editor. Each entry contains the inline's id, and the data parameter that was passed to addInlineWidget().

Kind: instance property of Editor

editor.getFocusedInlineWidget ⇒ InlineWidget

Returns the currently focused inline widget, if any.

Kind: instance property of Editor

editor.setInlineWidgetHeight

Sets the height of an inline widget in this editor.

Kind: instance property of Editor

Param	Type	Description
inlineWidget	InlineWidget	The widget whose height should be set.
height	number	The height of the widget.
[ensureVisible]	boolean	Whether to scroll the entire widget into view. Default false.

editor.document : Document

The Document we're bound to

Kind: instance property of Editor

editor.getInlineWidgetsBelowCursor() ⇒ boolean

Gets the inline widgets below the current cursor position or null.

Kind: instance method of Editor

editor.canConsumeEscapeKeyEvent()

returns true if the editor can do something an escape key event. Eg. Disable multi cursor escape

Kind: instance method of Editor

editor.destroy()

Removes this editor from the DOM and detaches from the Document. If this is the "master" Editor that is secretly providing the Document's backing state, then the Document reverts to a read-only string-backed mode.

Kind: instance method of Editor

editor.selectAllNoScroll()

Selects all text and maintains the current scroll position.

Kind: instance method of Editor

editor.isTextSubset() ⇒ boolean

Kind: instance method of Editor
Returns: boolean - True if editor is not showing the entire text of the document (i.e. an inline editor)

editor.getFile() ⇒ File

Gets the file associated with this editor This is a required Pane-View interface method

Kind: instance method of Editor
Returns: File - the file associated with this editor

editor.getCursorPos([expandTabs], [which]) ⇒ Object

Gets the current cursor position within the editor.

Cursor positions can be converted to index(0 based character offsets in editor text string) using editor.indexFromPos API.

Kind: instance method of Editor

Param	Type	Description
[expandTabs]	boolean	If true, return the actual visual column number instead of the character offset in the "ch" property.
[which]	string	Optional string indicating which end of the selection to return. It may be "start", "end", "head" (the side of the selection that moves when you press shift+arrow), or "anchor" (the fixed side of the selection). Omitting the argument is the same as passing "head". A ch object will be returned.)

editor.getEndingCursorPos([expandTabs]) ⇒ Object

Gets the cursor position of the last charected in the editor.

Kind: instance method of Editor

Param	Type	Description
[expandTabs]	boolean	If true, return the actual visual column number instead of the character offset in the "ch" property.

editor.getColOffset(pos) ⇒ number

Returns the display column (zero-based) for a given string-based pos. Differs from pos.ch only when the line contains preceding \t chars. Result depends on the current tab size setting.

Kind: instance method of Editor

Param	Type
pos	Object

editor.getCharIndexForColumn(lineNum, column) ⇒ number

Returns the string-based pos for a given display column (zero-based) in given line. Differs from column only when the line contains preceding \t chars. Result depends on the current tab size setting.

Kind: instance method of Editor

Param	Type	Description
lineNum	number	Line number
column	number	Display column number

editor.setCursorPos(line, ch, [center], [expandTabs])

Sets the cursor position within the editor. Removes any selection.

Kind: instance method of Editor

Param	Type	Description
line	number	The 0 based line number.
ch	number	The 0 based character position; treated as 0 if unspecified.
[center]	boolean	True if the view should be centered on the new cursor position.
[expandTabs]	boolean	If true, use the actual visual column number instead of the character offset as the "ch" parameter.

editor.setSize(width, height)

Set the editor size in pixels or percentage

Kind: instance method of Editor

Param	Type
width	number | string
height	number | string

editor.getViewport() ⇒ Object

Returns a to object indicating the start (inclusive) and end (exclusive) of the currently rendered part of the document. In big documents, when most content is scrolled out of view, Editor will only render the visible part, and a margin around it. See also the viewportChange event fired on the editor.

This is combination with viewportChange event can be used to selectively redraw visual elements in code like syntax analyze only parts of code instead of the full code everytime.

Kind: instance method of Editor

editor.centerOnCursor(centerOptions)

Scrolls the editor viewport to vertically center the line with the cursor, but only if the cursor is currently near the edges of the viewport or entirely outside the viewport.

This does not alter the horizontal scroll position.

Kind: instance method of Editor

Param	Type	Description
centerOptions	number	Option value, or 0 for no options; one of the BOUNDARY_* constants above.

editor.indexFromPos(cursorPos) ⇒ number

Given a position, returns its index within the text (assuming \n newlines)

Kind: instance method of Editor

Param	Type
cursorPos	Object

editor.posFromIndex(index) ⇒ Object

Given a position, returns its index within the text (assuming \n newlines)

Kind: instance method of Editor

Param	Type
index	number

editor.posWithinRange(pos, start, end, endInclusive)

Returns true if pos is between start and end (INclusive at start; EXclusive at end by default, but overridable via the endInclusive flag).

Kind: instance method of Editor

Param	Type
pos	Object
start	Object
end	Object
endInclusive	boolean

editor.hasSelection() ⇒ boolean

Kind: instance method of Editor
Returns: boolean - True if there's a text selection; false if there's just an insertion point

editor.getSelection() ⇒ Object

Gets the current selection; if there is more than one selection, returns the primary selection (generally the last one made). Start is inclusive, end is exclusive. If there is no selection, returns the current cursor position as both the start and end of the range (i.e. a selection of length zero). If reversed is set, then the head of the selection (the end of the selection that would be changed if the user extended the selection) is before the anchor.

Kind: instance method of Editor

editor.getSelections() ⇒ Object

Returns an array of current selections, nonoverlapping and sorted in document order. Each selection is a start/end pair, with the start guaranteed to come before the end. Cursors are represented as a range whose start is equal to the end. If reversed is set, then the head of the selection (the end of the selection that would be changed if the user extended the selection) is before the anchor. If primary is set, then that selection is the primary selection.

Kind: instance method of Editor

editor.hasMultipleCursors() ⇒ boolean

Check if the editor has multiple cursors or selections

Kind: instance method of Editor

editor.convertToLineSelections(selections, options) ⇒ Object

Takes the given selections, and expands each selection so it encompasses whole lines. Merges adjacent line selections together. Keeps track of each original selection associated with a given line selection (there might be multiple if individual selections were merged into a single line selection). Useful for doing multiple-selection-aware line edits.

Kind: instance method of Editor
Returns: Object - The combined line selections. For each selection, selectionForEdit is the line selection, and selectionsToTrack is the set of original selections that combined to make up the given line selection. Note that the selectionsToTrack will include the original objects passed in selections, so if it is later mutated the original passed-in selections will be mutated as well.

Param	Type	Description
selections	Object	The selections to expand.
options	Object	expandEndAtStartOfLine: true if a range selection that ends at the beginning of a line should be expanded to encompass the line. Default false. mergeAdjacent: true if adjacent line ranges should be merged. Default true.

editor.getSelectedText([allSelections]) ⇒ string

Returns the currently selected text, or "" if no selection. Includes \n if the selection spans multiple lines (does NOT reflect the Document's line-endings style). By default, returns only the contents of the primary selection, unless allSelections is true.

Kind: instance method of Editor
Returns: string - The selected text.

Param	Type	Description
[allSelections]	boolean	Whether to return the contents of all selections (separated by newlines) instead of just the primary selection. Default false.

editor.coordsChar(coordinates, [mode]) ⇒ Object

Given an top object (e.g. coordinates of a mouse event) returns the ch position that corresponds to it. The optional mode parameter determines relative to what the coordinates are interpreted.

Kind: instance method of Editor
Returns: Object - for the given coordinates

Param	Type	Description
coordinates	Object	can be obtained from Eg. coordinates of a mouse event
[mode]	string	It may be "window", "page" (the default), or "local".

editor.charCoords(pos, [mode]) ⇒ Object

Returns the position and dimensions of an arbitrary character given a cursor (Eg. from getCursorPos()). It'll give the size of the whole character, rather than just the position that the cursor would have when it would sit at that position.

Kind: instance method of Editor
Returns: Object - coordinates for the given character position

Param	Type	Description
pos	Object	A cursor, can be obtained from Eg. getCursorPos()
[mode]	string	It may be "window", "page" (the default), or "local".

editor.getToken([cursor], [precise]) ⇒ Object

Get the token at the given cursor position, or at the current cursor if none is given.

Kind: instance method of Editor
Returns: Object - - the CodeMirror token at the given cursor position

Param	Type	Description
[cursor]	Object	Optional cursor position at which to retrieve a token. If not provided, the current position will be used.
[precise]	boolean	If given, results in more current results. Suppresses caching.

editor.getCharacterAtPosition(pos) ⇒ string | null

Retrieves a single character from the specified position in the editor. x|y where | is the cursor, will return y

Kind: instance method of Editor
Returns: string | null - The character at the given position if within bounds, otherwise null if the position is out of range.

Param	Type	Description
pos	CodeMirror.Position	The position from which to retrieve the character. This should be an object with line and ch properties.

editor.getPrevCharacterAtPosition(pos) ⇒ string | null

Retrieves a single character previous to the specified position in the editor in the same line if possible. x|y where | is the cursor, will return x

Kind: instance method of Editor
Returns: string | null - The character previous to the given position if within bounds, otherwise null if the position is out of range.

Param	Type	Description
pos	CodeMirror.Position	The position from which to retrieve the character. This should be an object with line and ch properties.

editor.getNextToken([cursor], [skipWhitespace], [precise]) ⇒ Object

Get the token after the one at the given cursor position

Kind: instance method of Editor
Returns: Object - - the CodeMirror token after the one at the given cursor position

Param	Type	Description
[cursor]	Object	Optional cursor position after which a token should be retrieved
[skipWhitespace]	boolean	true if this should skip over whitespace tokens. Default is true.
[precise]	boolean	If given, results in more current results. Suppresses caching.

editor.getPreviousToken([cursor], [skipWhitespace], [precise]) ⇒ Object

Get the token before the one at the given cursor position

Kind: instance method of Editor
Returns: Object - - the CodeMirror token before the one at the given cursor position

Param	Type	Description
[cursor]	Object	Optional cursor position before which a token should be retrieved
[skipWhitespace]	boolean	true if this should skip over whitespace tokens. Default is true.
[precise]	boolean	If given, results in more current results. Suppresses caching.

editor.operation(execFn) ⇒ *

Use This if you are making large number of editor changes in a single workflow to improve performance. The editor internally buffers changes and only updates its DOM structure after it has finished performing some operation. If you need to perform a lot of operations on a CodeMirror instance, you can call this method with a function argument. It will call the function, buffering up all changes, and only doing the expensive update after the function returns. This can be a lot faster. The return value from this method will be the return value of your function.

Kind: instance method of Editor

Param	Description
execFn	The function that will be called to make all editor changes.

editor.markToken(markType, cursor, [options]) ⇒ Object

Same as markText, but will apply to the token at the given position or current position

Kind: instance method of Editor
Returns: Object - TextMarker

Param	Type	Description
markType	string	A String that can be used to label the mark type.
cursor	Object	The position of the token
[options]		same as markText

editor.setBookmark(markType, [cursorPos], [options]) ⇒ Object

Inserts a bookmark, a handle that follows the text around it as it is being edited, at the given position. Similar to mark text, but for just a point instead of range.

Kind: instance method of Editor
Returns: Object - TextMarker- A bookmark has two methods find() and clear(). find returns the current position of the bookmark, if it is still in the document, and clear explicitly removes the bookmark.

Param	Type	Description
markType	string	A String that can be used to label the mark type.
[cursorPos]	Object	Where to place the mark. Optional, if not specified, will use current pos
[options]	Object	When given, it should be an object that may contain the following configuration options:
[options.widget]	Element	Can be used to display a DOM node at the current location of the bookmark (analogous to the replacedWith option to markText).
[options.insertLeft]	boolean	By default, text typed when the cursor is on top of the bookmark will end up to the right of the bookmark. Set this option to true to make it go to the left instead.
[options.handleMouseEvents]	boolean	As with markText, this determines whether mouse events on the widget inserted for this bookmark are handled by CodeMirror. The default is false.

editor.findMarks(cursorFrom, cursorTo, [markType]) ⇒ Array.<TextMarker>

Returns an array of all the bookmarks and marked ranges found between the given positions (non-inclusive).

Kind: instance method of Editor
Returns: Array.<TextMarker> - TextMarker - A text marker array

Param	Type	Description
cursorFrom	Object	Mark start position
cursorTo	Object	Mark end position
[markType]	string	Optional, if given will only return marks of that type. Else returns everything.

editor.findMarksAt(cursorPos, [markType]) ⇒ Array.<TextMarker>

Returns an array of all the bookmarks and marked ranges present at the given position.

Kind: instance method of Editor
Returns: Array.<TextMarker> - TextMarker - A text marker array

Param	Type	Description
cursorPos	Object	cursor position
[markType]	string	Optional, if given will only return marks of that type. Else returns everything.

editor.getMarksAfter(position, markType) ⇒ Array.<TextMarker>

Returns the first mark of a specific type found after the given position.

Kind: instance method of Editor
Returns: Array.<TextMarker> - The array of text markers found, or an empty array if none are found.

Param	Type	Description
position	Object	The starting position to search from.
markType	string	The type of mark to look for.

editor.getMarksBefore(position, markType) ⇒ Array.<TextMarker>

Returns the first mark of a specific type found before the given position.

Kind: instance method of Editor
Returns: Array.<TextMarker> - The array of text markers found, or an empty array if none are found.

Param	Type	Description
position	Object	The ending position to search up to.
markType	string	The type of mark to look for.

editor.getAllMarks([markType]) ⇒ Array.<TextMarker>

Returns an array containing all marked ranges in the document.

Kind: instance method of Editor
Returns: Array.<TextMarker> - TextMarker - A text marker array

Param	Type	Description
[markType]	string	Optional, if given will only return marks of that type. Else returns everything.

editor.clearAllMarks([markType])

Clears all mark of the given type. If nothing is given, clears all marks(Don't use this API without types!).

Kind: instance method of Editor

Param	Type	Description
[markType]	string	Optional, if given will only delete marks of that type. Else delete everything.

editor.isSamePosition(position1, position2) ⇒ boolean

Checks if two positions in the editor are the same.

Kind: instance method of Editor
Returns: boolean - True if both positions are the same, false otherwise.

Param	Type	Description
position1	Object	cursor position
position2	Object	cursor position

editor.getHistory() ⇒ Array

Get a (JSON-serializable) representation of the undo history.

Kind: instance method of Editor
Returns: Array - The history of the editor.

editor.setHistory()

Replace the editor's undo history with the one provided, which must be a value as returned by getHistory. Note that this will have entirely undefined results if the editor content isn't also the same as it was when getHistory was called.

Kind: instance method of Editor

editor.createHistoryRestorePoint(restorePointName)

Creates a named restore point in undo history. this can be later be restored to undo all changed till the named restore point in one go.

Kind: instance method of Editor

Param	Type	Description
restorePointName	string	The name of the restore point to revert to.

editor.restoreHistoryPoint(restorePointName)

To restore the editor to a named restore point if the restore point is found, it reverts all changes made after that point.

Kind: instance method of Editor

Param	Type	Description
restorePointName	string	The name of the restore point to revert to.

editor.setSelection(start, [end], [center], [centerOptions], [origin])

Sets the current selection. Start is inclusive, end is exclusive. Places the cursor at the end of the selection range. Optionally centers around the cursor after making the selection

Kind: instance method of Editor

Param	Type	Description
start	Object
[end]	Object	If not specified, defaults to start.
[center]	boolean	true to center the viewport
[centerOptions]	number	Option value, or 0 for no options; one of the BOUNDARY_* constants above.
[origin]	string	An optional string that describes what other selection or edit operations this should be merged with for the purposes of undo. See Document::Document#replaceRange for more details.

editor.replaceSelection(replacement, [select])

Replace the selection with the given string.

Kind: instance method of Editor

Param	Type	Description
replacement	string	the text to replace the current selection
[select]	string	The optional select argument can be used to change selection. Passing "around" will cause the new text to be selected, passing "start" will collapse the selection to the start of the inserted text.

editor.replaceSelections(replacement, [select])

Replaces the content of multiple selections with the strings in the array. The length of the given array should be the same as the number of active selections.

Kind: instance method of Editor

Param	Type	Description
replacement	Array.<string>	the text array to replace the current selections with
[select]	string	The optional select argument can be used to change selection. Passing "around" will cause the new text to be selected, passing "start" will collapse the selection to the start of the inserted text.

editor.replaceRange(replacement, from, [to], origin)

Replace the part of the document between from and to with the given string.

Kind: instance method of Editor

Param	Type	Description
replacement	string	the text to replace the current selection
from	Object	the strat position to replace
[to]	Object	the end position to replace. to can be left off to simply insert the string at position from.
origin	string	When origin is given, it will be passed on to "change" events, and its first letter will be used to determine whether this change can be merged with previous history events of the inserted text.

editor.replaceMultipleRanges(ranges, [origin])

Replaces multiple ranges in the editor with the specified texts.

Kind: instance method of Editor

Param	Type	Description
ranges	Array	An array of range objects, each containing from, to, and text properties.
ranges[].from	Object	The start position of the range to be replaced. It should have line and ch properties.
ranges[].to	Object	The end position of the range to be replaced. It should have line and ch properties.
ranges[].text	string	The text to replace the specified range.
[origin]	string	An optional origin identifier to be associated with the changes.

Example

editor.replaceMultipleRanges([
  { from: { line: 0, ch: 0 }, to: { line: 0, ch: 5 }, text: 'Hello' },
  { from: { line: 1, ch: 0 }, to: { line: 1, ch: 4 }, text: 'World' }
], 'exampleOrigin');

editor.clearSelection()

Clears any active selection if present.

Kind: instance method of Editor

editor.setSelections(selections, center, centerOptions, origin)

Sets a multiple selection, with the "primary" selection (the one returned by getSelection() and getCursorPos()) defaulting to the last if not specified. Overlapping ranges will be automatically merged, and the selection will be sorted. Optionally centers around the primary selection after making the selection.

Kind: instance method of Editor

Param	Type	Description
selections	Object	The selection ranges to set. If the start and end of a range are the same, treated as a cursor. If reversed is true, set the anchor of the range to the end instead of the start. If primary is true, this is the primary selection. Behavior is undefined if more than one selection has primary set to true. If none has primary set to true, the last one is primary.
center	boolean	true to center the viewport around the primary selection.
centerOptions	number	Option value, or 0 for no options; one of the BOUNDARY_* constants above.
origin	string	An optional string that describes what other selection or edit operations this should be merged with for the purposes of undo. See Document::Document#replaceRange for more details.

editor.toggleOverwrite(start)

Sets the editors overwrite mode state. If null is passed, the state is toggled.

Kind: instance method of Editor

Param	Type
start	boolean

editor.selectWordAt(pos)

Selects word that the given pos lies within or adjacent to. If pos isn't touching a word (e.g. within a token like "//"), moves the cursor to pos without selecting a range.

Kind: instance method of Editor

Param	Type
pos	Object

editor.getTextBetween(startPos, endPos) ⇒ string

To get the text between the starting position and the ending position

Kind: instance method of Editor
Returns: string - The text between the starting position and the ending position

Param	Type	Description
startPos	Object
endPos	Object

editor.getWordAt(pos) ⇒ Object

Gets word at the given pos lies within or adjacent to. If pos isn't touching a word (e.g. within a token like "//"), returns null

Kind: instance method of Editor

Param
pos

editor.getNumberAt(pos, maxDigits) ⇒ Object

Gets number string of (upto 10 digits default) at the given pos lies within or adjacent to. If pos isn't touching a number, returns null. If the number in string is greater than max digits returns null.

Kind: instance method of Editor

Param	Type	Description
pos
maxDigits	number	number of digits allowed. This is to prevent massive digit strings.

editor.lineCount() ⇒ number

Gets the total number of lines in the document (includes lines not visible in the viewport)

Kind: instance method of Editor

editor.isLineVisible(zero-based) ⇒ boolean

Deterines if line is fully visible.

Kind: instance method of Editor
Returns: boolean - true if the line is fully visible, false otherwise

Param	Type	Description
zero-based	number	index of the line to test

editor.getFirstVisibleLine() ⇒ number

Gets the number of the first visible line in the editor.

Kind: instance method of Editor
Returns: number - The 0-based index of the first visible line.

editor.getLastVisibleLine() ⇒ number

Gets the number of the last visible line in the editor.

Kind: instance method of Editor
Returns: number - The 0-based index of the last visible line.

editor.totalHeight() ⇒ number

Gets the total height of the document in pixels (not the viewport)

Kind: instance method of Editor
Returns: number - height in pixels

editor.getScrollerElement() ⇒ HTMLDivElement

Gets the scroller element from the editor.

Kind: instance method of Editor
Returns: HTMLDivElement - scroller

editor.getRootElement() ⇒ HTMLDivElement

Gets the root DOM node of the editor.

Kind: instance method of Editor
Returns: HTMLDivElement - The editor's root DOM node.

editor.getScrollPos() ⇒ Object

Returns the current scroll position of the editor.

Kind: instance method of Editor
Returns: Object - The x,y scroll position in pixels

editor.adjustScrollPos(scrollPos, heightDelta)

Restores and adjusts the current scroll position of the editor.

Kind: instance method of Editor

Param	Type	Description
scrollPos	Object	The x,y scroll position in pixels
heightDelta	number	The amount of delta H to apply to the scroll position

editor.setScrollPos(x, y)

Sets the current scroll position of the editor.

Kind: instance method of Editor

Param	Type	Description
x	number	scrollLeft position in pixels
y	number	scrollTop position in pixels

editor.getTextHeight() ⇒ number

Returns the current text height of the editor.

Kind: instance method of Editor
Returns: number - Height of the text in pixels

editor.displayErrorMessageAtCursor(errorMsg)

Display temporary popover message at current cursor position. Display message above cursor if space allows, otherwise below.

Kind: instance method of Editor

Param	Type	Description
errorMsg	string	Error message to display

editor.getVirtualScrollAreaTop() ⇒ number

Returns the offset of the top of the virtual scroll area relative to the browser window (not the editor itself). Mainly useful for calculations related to scrollIntoView(), where you're starting with the offset() of a child widget (relative to the browser window) and need to figure out how far down it is from the top of the virtual scroll area (excluding the top padding).

Kind: instance method of Editor

editor.focus()

Gives focus to the editor control

Kind: instance method of Editor

editor.hasFocus()

Returns true if the editor has focus

Kind: instance method of Editor

editor.getViewState() ⇒ EditorViewState

returns the view state for the editor

Kind: instance method of Editor

editor.restoreViewState(viewState)

Restores the view state

Kind: instance method of Editor

Param	Type	Description
viewState	EditorViewState	the view state object to restore

editor.refresh([handleResize])

Re-renders the editor UI

Kind: instance method of Editor

Param	Type	Description
[handleResize]	boolean	true if this is in response to resizing the editor. Default false.

editor.refreshAll([handleResize])

Re-renders the editor, and all children inline editors.

Kind: instance method of Editor

Param	Type	Description
[handleResize]	boolean	true if this is in response to resizing the editor. Default false.

editor.undo()

Undo the last edit.

Kind: instance method of Editor

editor.redo()

Redo the last un-done edit.

Kind: instance method of Editor

editor.notifyVisibilityChange(show, refresh)

View API Visibility Change Notification handler. This is also called by the native "setVisible" API which refresh can be optimized

Kind: instance method of Editor

Param	Type	Description
show	boolean	true to show the editor, false to hide it
refresh	boolean	true (default) to refresh the editor, false to skip refreshing it

editor.setVisible(show, refresh)

Shows or hides the editor within its parent. Does not force its ancestors to become visible.

Kind: instance method of Editor

Param	Type	Description
show	boolean	true to show the editor, false to hide it
refresh	boolean	true (default) to refresh the editor, false to skip refreshing it

editor.isFullyVisible()

Returns true if the editor is fully visible--i.e., is in the DOM, all ancestors are visible, and has a non-zero width/height.

Kind: instance method of Editor

editor.getModeForRange(start, end, [knownMixed]) ⇒ Object | string

Gets the syntax-highlighting mode for the given range. Returns null if the mode at the start of the selection differs from the mode at the end - an approximation of whether the mode is consistent across the whole range (a pattern like A-B-A would return A as the mode, not null).

Kind: instance method of Editor
Returns: Object | string - Name of syntax-highlighting mode, or object containing a "name" property naming the mode along with configuration options required by the mode.
See: LanguageManager::#getLanguageForPath and LanguageManager::Language#getMode.

Param	Type	Description
start	Object	The start of the range to check.
end	Object	The end of the range to check.
[knownMixed]	boolean	Whether we already know we're in a mixed mode and need to check both the start and end.

editor.getModeForSelection(selection) ⇒ Object | string

Gets the syntax-highlighting mode for the current selection or cursor position. (The mode may vary within one file due to embedded languages, e.g. JS embedded in an HTML script block). See getModeForRange() for how this is determined for a single selection.

If there are multiple selections, this will return a mode only if all the selections are individually consistent and resolve to the same mode.

Kind: instance method of Editor
Returns: Object | string - Name of syntax-highlighting mode, or object containing a "name" property naming the mode along with configuration options required by the mode.
See: LanguageManager::#getLanguageForPath and LanguageManager::Language#getMode.

Param	Type
selection	Object

editor.getLanguageForSelection() ⇒ Language

gets the language for the selection. (Javascript selected from an HTML document or CSS selected from an HTML document, etc...)

Kind: instance method of Editor

editor.getLanguageForPosition() ⇒ Language

gets the language for the selection. (Javascript selected from an HTML document or CSS selected from an HTML document, etc...)

Kind: instance method of Editor

editor.getModeForDocument() ⇒ Object | String

Gets the syntax-highlighting mode for the document.

Kind: instance method of Editor
Returns: Object | String - Object or Name of syntax-highlighting mode
See: LanguageManager.getLanguageForPath and Language.getMode.

editor.updateLayout([forceRefresh])

resizes the editor to fill its parent container should not be used on inline editors

Kind: instance method of Editor

Param	Type	Description
[forceRefresh]	boolean	forces the editor to update its layout even if it already matches the container's height / width

editor.setGutterMarker(lineNumber, gutterName, marker)

Sets the marker for the specified gutter on the specified line number

Kind: instance method of Editor

Param	Type	Description
lineNumber	number	The line number for the inserted gutter marker
gutterName	string	The name of the gutter
marker	object	The dom element representing the marker to the inserted in the gutter

editor.getGutterMarker(lineNumber, gutterName)

Gets the gutter marker of the given name if found on the current line, else returns undefined.

Kind: instance method of Editor

Param	Type	Description
lineNumber	number	The line number for the inserted gutter marker
gutterName	string	The name of the gutter

editor.clearGutterMarker(lineNumber, gutterName)

Clears the marker for the specified gutter on the specified line number. Does nothing if there was no marker on the line.

Kind: instance method of Editor

Param	Type	Description
lineNumber	number	The line number for the inserted gutter marker
gutterName	string	The name of the gutter

editor.clearGutter(gutterName)

Clears all marks from the gutter with the specified name.

Kind: instance method of Editor

Param	Type	Description
gutterName	string	The name of the gutter to clear.

Editor.getMarkOptionUnderlineError

Mark option to underline errors.

Kind: static property of Editor

Editor.getMarkOptionUnderlineWarn

Mark option to underline warnings.

Kind: static property of Editor

Editor.getMarkOptionUnderlineInfo

Mark option to underline informational text.

Kind: static property of Editor

Editor.getMarkOptionUnderlineSpellcheck

Mark option to underline spelling errors.

Kind: static property of Editor

Editor.getMarkOptionHyperlinkText

Mark option to highlight hyperlinks.

Kind: static property of Editor

Editor.getMarkOptionMatchingRefs

Mark option for matching references.

Kind: static property of Editor

Editor.getMarkOptionRenameOutline

Mark option for renaming outlines.

Kind: static property of Editor

Editor.getRegisteredGutters() ⇒ Object

Returns the list of gutters current registered on all editors.

Kind: static method of Editor

Editor.isGutterRegistered(gutterName) ⇒ boolean

Return true if gutter of the given name is registered

Kind: static method of Editor

Param	Type	Description
gutterName	string	The name of the gutter

Editor.registerGutter(name, priority, [languageIds])

Registers the gutter with the specified name at the given priority.

Kind: static method of Editor

Param	Type	Description
name	string	The name of the gutter.
priority	number	A number denoting the priority of the gutter. Priorities higher than LINE_NUMBER_GUTTER_PRIORITY appear after the line numbers. Priority less than LINE_NUMBER_GUTTER_PRIORITY appear before.
[languageIds]	Array.<string>	A list of language ids that this gutter is valid for. If no language ids are passed, then the gutter is valid in all languages.

Editor.unregisterGutter(name)

Unregisters the gutter with the specified name and removes it from the UI.

Kind: static method of Editor

Param	Type	Description
name	string	The name of the gutter to be unregistered.

Editor.setUseTabChar(value, [fullPath]) ⇒ boolean

Sets whether to use tab characters (vs. spaces) when inserting new text. Affects any editors that share the same preference location.

Kind: static method of Editor
Returns: boolean - true if value was valid

Param	Type	Description
value	boolean
[fullPath]	string	Path to file to get preference for

Editor.getUseTabChar([fullPath]) ⇒ boolean

Gets whether the specified or current file uses tab characters (vs. spaces) when inserting new text

Kind: static method of Editor

Param	Type	Description
[fullPath]	string	Path to file to get preference for

Editor.setTabSize(value, [fullPath]) ⇒ boolean

Sets tab character width. Affects any editors that share the same preference location.

Kind: static method of Editor
Returns: boolean - true if value was valid

Param	Type	Description
value	number
[fullPath]	string	Path to file to get preference for

Editor.getTabSize([fullPath]) ⇒ number

Get indent unit

Kind: static method of Editor

Param	Type	Description
[fullPath]	string	Path to file to get preference for

Editor.getAutoTabUnits(fullPath) ⇒ number | *

Gets the number of tabs for the file. Will

Kind: static method of Editor

Param
fullPath

Editor.setAutoTabSpaces(value, [fullPath]) ⇒ boolean

When set, the tabs and spaces to be used will be auto detected from the current file or fall back to defaults. Affects any editors that share the same preference location.

Kind: static method of Editor
Returns: boolean - true if value was valid

Param	Type	Description
value	boolean
[fullPath]	string	Path to file to get preference for

Editor.getAutoTabSpaces([fullPath]) ⇒ number

Get auto tabbing/spacing option

Kind: static method of Editor

Param	Type	Description
[fullPath]	string	Path to file to get preference for

Editor.setSpaceUnits(value, [fullPath]) ⇒ boolean

Sets indentation width. Affects any editors that share the same preference location.

Kind: static method of Editor
Returns: boolean - true if value was valid

Param	Type	Description
value	number
[fullPath]	string	Path to file to get preference for

Editor.getSpaceUnits([fullPath]) ⇒ number

Get indentation width

Kind: static method of Editor

Param	Type	Description
[fullPath]	string	Path to file to get preference for

Editor.setCloseBrackets(value, [fullPath]) ⇒ boolean

Sets the auto close brackets. Affects any editors that share the same preference location.

Kind: static method of Editor
Returns: boolean - true if value was valid

Param	Type	Description
value	boolean
[fullPath]	string	Path to file to get preference for

Editor.getCloseBrackets([fullPath]) ⇒ boolean

Gets whether the specified or current file uses auto close brackets

Kind: static method of Editor

Param	Type	Description
[fullPath]	string	Path to file to get preference for

Editor.setShowLineNumbers(value, [fullPath]) ⇒ boolean

Sets show line numbers option. Affects any editors that share the same preference location.

Kind: static method of Editor
Returns: boolean - true if value was valid

Param	Type	Description
value	boolean
[fullPath]	string	Path to file to get preference for

Editor.getShowLineNumbers([fullPath]) ⇒ boolean

Returns true if show line numbers is enabled for the specified or current file

Kind: static method of Editor

Param	Type	Description
[fullPath]	string	Path to file to get preference for

Editor.setShowActiveLine(value, [fullPath]) ⇒ boolean

Sets show active line option. Affects any editors that share the same preference location.

Kind: static method of Editor
Returns: boolean - true if value was valid

Param	Type	Description
value	boolean
[fullPath]	string	Path to file to get preference for

Editor.getShowActiveLine([fullPath]) ⇒ boolean

Returns true if show active line is enabled for the specified or current file

Kind: static method of Editor

Param	Type	Description
[fullPath]	string	Path to file to get preference for

Editor.setWordWrap(value, [fullPath]) ⇒ boolean

Sets word wrap option. Affects any editors that share the same preference location.

Kind: static method of Editor
Returns: boolean - true if value was valid

Param	Type	Description
value	boolean
[fullPath]	string	Path to file to get preference for

Editor.getWordWrap([fullPath]) ⇒ boolean

Returns true if word wrap is enabled for the specified or current file

Kind: static method of Editor

Param	Type	Description
[fullPath]	string	Path to file to get preference for

Editor.setIndentLineComment(value, [fullPath]) ⇒ boolean

Sets indentLineComment option. Affects any editors that share the same preference location.

Kind: static method of Editor
Returns: boolean - true if value was valid

Param	Type	Description
value	boolean
[fullPath]	string	Path to file to get preference for

Editor.getIndentLineComment([fullPath]) ⇒ boolean

Returns true if indentLineComment is enabled for the specified or current file

Kind: static method of Editor

Param	Type	Description
[fullPath]	string	Path to file to get preference for

Editor.forEveryEditor(callback, [fullPath])

Runs callback for every Editor instance that currently exists or only the editors matching the given fullPath.

Kind: static method of Editor

Param	Type	Description
callback	function
[fullPath]	string	an optional second argument, if given will only callback for all editors that is editing the file for the given fullPath

CommandManager

Editor is a 1-to-1 wrapper for a CodeMirror editor instance. It layers on Brackets-specific functionality and provides APIs that cleanly pass through the bits of CodeMirror that the rest of our codebase may want to interact with. An Editor is always backed by a Document, and stays in sync with its content; because Editor keeps the Document alive, it's important to always destroy() an Editor that's going away so it can release its Document ref.

For now, there's a distinction between the "master" Editor for a Document - which secretly acts as the Document's internal model of the text state - and the multitude of secondary Editors which, via Document, sync their changes to and from that master.

For now, direct access to the underlying CodeMirror object is still possible via _codeMirror -- but this is considered deprecated and may go away.

The Editor object dispatches the following events: (available as Editor.EVENT_* constants. see below)

• keydown, keypress, keyup -- When any key event happens in the editor (whether it changes the text or not). Handlers are passed (BracketsEvent, Editor, KeyboardEvent). The 3nd arg is the raw DOM event. Note: most listeners will only want to listen for "keypress".
• change - Triggered with an array of change objects. Parameters: (editor, changeList)
• beforeChange - (self, changeObj)
• beforeSelectionChange - (selectionObj)
• focus - Fired when an editor is focused
• blur - Fired when an editor loses focused
• update - Will be fired whenever Editor updates its DOM display.
• cursorActivity -- When the user moves the cursor or changes the selection, or an edit occurs. Note: do not listen to this in order to be generally informed of edits--listen to the "change" event on Document instead.
• scroll -- When the editor is scrolled, either by user action or programmatically.
• viewportChange - (from: number, to: number) Fires whenever the view port of the editor changes (due to scrolling, editing, or any other factor). The from and to arguments give the new start and end of the viewport. This is combination with editorInstance.getViewPort() can be used to selectively redraw visual elements in code like syntax analyze only parts of code instead of the full code everytime.
• lostContent -- When the backing Document changes in such a way that this Editor is no longer able to display accurate text. This occurs if the Document's file is deleted, or in certain Document->editor syncing edge cases that we do not yet support (the latter cause will eventually go away).
• optionChange -- Triggered when an option for the editor is changed. The 2nd arg to the listener is a string containing the editor option that is changing. The 3rd arg, which can be any data type, is the new value for the editor option.
• beforeDestroy - Triggered before the object is about to dispose of all its internal state data so that listeners can cache things like scroll pos, etc...

The Editor also dispatches "change" events internally, but you should listen for those on Documents, not Editors.

To listen for events, do something like this: (see EventDispatcher for details on this pattern) editorInstance.on("eventname", handler);

Kind: global variable

BOUNDARY_CHECK_NORMAL : number

Constant: Normal boundary check when centering text.

Kind: global constant

BOUNDARY_IGNORE_TOP : number

Constant: Ignore the upper boundary when centering text.

Kind: global constant

BOUNDARY_BULLSEYE : number

Constant: Bulls-eye mode, strictly center the text always.

Kind: global constant

CENTERING_MARGIN

Kind: global constant