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
- .getLine(lineNumber) ⇒
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)
- .addInlineWidget ⇒
- 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.getLine(lineNumber) ⇒ string
| null
Retrieves a single line text
Kind: instance method of Editor
Returns: string
| null
- The text at the given position if within bounds,
otherwise null
if the position is out of range.
Param | Type | Description |
---|---|---|
lineNumber | number | The lineNumber to extract text from |
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