Editor

The main entry point into the Ace functionality.

The Editor manages the EditSession (which manages Documents), as well as the VirtualRenderer, which draws everything to the screen.

Event sessions dealing with the mouse and keyboard are bubbled up from Document to the Editor, which decides what to do with them.

Constructors

Creates a new Editor object.

Creates a new Editor object.

Arguments

rendererVirtualRenderer

Required. Associated VirtualRenderer that draws everything

sessionEditSession

Required. The EditSession to refer to

Events

    • Editor.on("blur", function())

Emitted once the editor has been blurred.

Emitted once the editor has been blurred.

    • Editor.on("change", function(Object e))

Emitted whenever the document is changed.

Emitted whenever the document is changed.

Arguments

eObject

Required. Contains a single property, data, which has the delta of changes

    • Editor.on("changeSession", function(Object e))

Emitted whenever the EditSession changes.

Emitted whenever the EditSession changes.

Arguments

eObject

Required. An object with two properties, oldSession and session, that represent the old and new EditSessions.

    • Editor.on("copy", function(String text))

Emitted when text is copied.

Emitted when text is copied.

Arguments

textString

Required. The copied text

    • Editor.on("focus", function())

Emitted once the editor comes into focus.

Emitted once the editor comes into focus.

    • Editor.on("paste", function(Object e))

Emitted when text is pasted.

Emitted when text is pasted.

Arguments

eObject

Required. An object which contains one property, text, that represents the text to be pasted. Editing this property will alter the text that is pasted.

Methods

    • Editor.addSelectionMarker(Range orientedRange)

Adds the selection and cursor.

Adds the selection and cursor.

Arguments

orientedRangeRange

Required. A range containing a cursor

    • Editor.alignCursors()

Aligns the cursors or selected text.

Aligns the cursors or selected text.

    • Editor.blockOutdent()

Outdents the current line.

Outdents the current line.

    • Editor.blur()

Blurs the current textInput.

Blurs the current textInput.

    • Editor.centerSelection()

Attempts to center the current selection on the screen.

Attempts to center the current selection on the screen.

    • Editor.clearSelection()

Empties the selection (by de-selecting it). This function also emits the 'changeSelection' event.

Empties the selection (by de-selecting it). This function also emits the 'changeSelection' event.

    • Editor.copyLinesDown()

Copies all the selected lines down one row.

Copies all the selected lines down one row.

Copies all the selected lines up one row.

Copies all the selected lines up one row.

    • Editor.destroy()

Cleans up the entire editor.

Cleans up the entire editor.

    • Editor.duplicateSelection()
    • Undocumented
    • Editor.execCommand()
    • Undocumented
    • Editor.exitMultiSelectMode()

Removes all the selections except the last added one.

Removes all the selections except the last added one.

Attempts to find needle within the document. For more information on options, see Search.

Attempts to find needle within the document. For more information on options, see Search.

Arguments

needleString

Required. The text to search for (optional)

optionsObject

Required. An object defining various search properties

animateBoolean

Required. If true animate scrolling

Finds and selects all the occurrences of needle.

Finds and selects all the occurrences of needle.

Arguments

TheString

Required. Text to find

TheObject

Required. Search options

keepsBoolean

Required.

Performs another search for needle in the document. For more information on options, see Search.

Performs another search for needle in the document. For more information on options, see Search.

Arguments

optionsObject

Required. Search options

animateBoolean

Required. If true animate scrolling

Performs a search for needle backwards. For more information on options, see Search.

Performs a search for needle backwards. For more information on options, see Search.

Arguments

optionsObject

Required. Search options

animateBoolean

Required. If true animate scrolling

    • Editor.focus()

Brings the current textInput into focus.

Brings the current textInput into focus.

Executes a command for each selection range.

Executes a command for each selection range.

Arguments

cmdString

Required. The command to execute

argsString

Required. Any arguments for the command

    • Editor.getAnimatedScroll()
    • Undocumented
    • Editor.getBehavioursEnabled()

Returns true if the behaviors are currently enabled. "Behaviors" in this case is the auto-pairing of special characters, like quotation marks, parenthesis, or brackets.

Returns true if the behaviors are currently enabled. "Behaviors" in this case is the auto-pairing of special characters, like quotation marks, parenthesis, or brackets.

Returns the string of text currently highlighted.

Returns the string of text currently highlighted.

    • Editor.getCursorPosition()

Gets the current position of the cursor.

Gets the current position of the cursor.

    • Editor.getCursorPositionScreen()

Returns the screen position of the cursor.

Returns the screen position of the cursor.

    • Editor.getDisplayIndentGuides()
    • Undocumented
    • Editor.getDragDelay()

Returns the current mouse drag delay.

Returns the current mouse drag delay.

    • Editor.getFadeFoldWidgets()
    • Undocumented
    • Editor.getFirstVisibleRow()

Returns the index of the first visible row.

Returns the index of the first visible row.

    • Editor.getHighlightActiveLine()

Returns true if current lines are always highlighted.

Returns true if current lines are always highlighted.

    • Editor.getHighlightGutterLine()
    • Undocumented
    • Editor.getHighlightSelectedWord()

Returns true if currently highlighted words are to be highlighted.

Returns true if currently highlighted words are to be highlighted.

    • Editor.getKeyboardHandler()

Returns the keyboard handler, such as "vim" or "windows".

Returns the keyboard handler, such as "vim" or "windows".

    • Editor.getLastSearchOptions()

Returns an object containing all the search options. For more information on options, see Search.

Returns an object containing all the search options. For more information on options, see Search.

    • Editor.getLastVisibleRow()

Returns the index of the last visible row.

Returns the index of the last visible row.

Returns true if overwrites are enabled; false otherwise.

Returns true if overwrites are enabled; false otherwise.

    • Editor.getPrintMarginColumn()

Returns the column number of where the print margin is.

Returns the column number of where the print margin is.

Returns true if the editor is set to read-only mode.

Returns true if the editor is set to read-only mode.

    • Editor.getScrollSpeed()

Returns the value indicating how fast the mouse scroll speed is (in milliseconds).

Returns the value indicating how fast the mouse scroll speed is (in milliseconds).

Returns selection object.

Returns selection object.

    • Editor.getSelectionRange()

Returns the Range for the selected text.

Returns the Range for the selected text.

    • Editor.getSelectionStyle()

Returns the current selection style.

Returns the current selection style.

Returns the current session being used.

Returns the current session being used.

    • Editor.getShowFoldWidgets()

Returns true if the fold widgets are shown.

Returns true if the fold widgets are shown.

    • Editor.getShowInvisibles()

Returns true if invisible characters are being shown.

Returns true if invisible characters are being shown.

    • Editor.getShowPrintMargin()

Returns true if the print margin is being shown.

Returns true if the print margin is being shown.

Returns the path of the current theme.

Returns the path of the current theme.

Returns the current session's content.

Returns the current session's content.

    • Editor.getWrapBehavioursEnabled()

Returns true if the wrapping behaviors are currently enabled.

Returns true if the wrapping behaviors are currently enabled.

Moves the cursor to the specified line number, and also into the indicated column.

Moves the cursor to the specified line number, and also into the indicated column.

Arguments

lineNumberNumber

Required. The line number to go to

columnNumber

Required. A column number to go to

animateBoolean

Required. If true animates scrolling

    • Editor.gotoPageDown()

Shifts the document to wherever "page down" is, as well as moving the cursor position.

Shifts the document to wherever "page down" is, as well as moving the cursor position.

    • Editor.gotoPageUp()

Shifts the document to wherever "page up" is, as well as moving the cursor position.

Shifts the document to wherever "page up" is, as well as moving the cursor position.

    • Editor.indent()

Indents the current line.

Indents the current line.

Inserts text into wherever the cursor is pointing.

Inserts text into wherever the cursor is pointing.

Arguments

textString

Required. The new text to add

Returns true if the current textInput is in focus.

Returns true if the current textInput is in focus.

Indicates if the entire row is currently visible on the screen.

Indicates if the entire row is currently visible on the screen.

Arguments

rowNumber

Required. The row to check

Indicates if the row is currently visible on the screen.

Indicates if the row is currently visible on the screen.

Arguments

rowNumber

Required. The row to check

    • Editor.jumpToMatching(Object select)

Moves the cursor's row and column to the next matching bracket.

Moves the cursor's row and column to the next matching bracket.

Arguments

selectObject

Required.

    • Editor.modifyNumber(Number amount)

If the character before the cursor is a number, this functions changes its value by amount.

If the character before the cursor is a number, this functions changes its value by amount.

Arguments

amountNumber

Required. The value to change the numeral by (can be negative to decrease value)

Moves the cursor to the specified row and column. Note that this does not de-select the current selection.

Moves the cursor to the specified row and column. Note that this does not de-select the current selection.

Arguments

rowNumber

Required. The new row number

columnNumber

Required. The new column number

    • Editor.moveCursorToPosition(Object pos)

Moves the cursor to the position indicated by pos.row and pos.column.

Moves the cursor to the position indicated by pos.row and pos.column.

Arguments

posObject

Required. An object with two properties, row and column

    • Editor.moveLinesDown()

Shifts all the selected lines down one row.

Shifts all the selected lines down one row.

Shifts all the selected lines up one row.

Shifts all the selected lines up one row.

    • Editor.moveText()
    • Undocumented
    • Editor.navigateDown(Number times)

Moves the cursor down in the document the specified number of times. Note that this does de-select the current selection.

Moves the cursor down in the document the specified number of times. Note that this does de-select the current selection.

Arguments

timesNumber

Required. The number of times to change navigation

    • Editor.navigateFileEnd()

Moves the cursor to the end of the current file. Note that this does de-select the current selection.

Moves the cursor to the end of the current file. Note that this does de-select the current selection.

    • Editor.navigateFileStart()

Moves the cursor to the start of the current file. Note that this does de-select the current selection.

Moves the cursor to the start of the current file. Note that this does de-select the current selection.

    • Editor.navigateLeft(Number times)

Moves the cursor left in the document the specified number of times. Note that this does de-select the current selection.

Moves the cursor left in the document the specified number of times. Note that this does de-select the current selection.

Arguments

timesNumber

Required. The number of times to change navigation

    • Editor.navigateLineEnd()

Moves the cursor to the end of the current line. Note that this does de-select the current selection.

Moves the cursor to the end of the current line. Note that this does de-select the current selection.

    • Editor.navigateLineStart()

Moves the cursor to the start of the current line. Note that this does de-select the current selection.

Moves the cursor to the start of the current line. Note that this does de-select the current selection.

    • Editor.navigateRight(Number times)

Moves the cursor right in the document the specified number of times. Note that this does de-select the current selection.

Moves the cursor right in the document the specified number of times. Note that this does de-select the current selection.

Arguments

timesNumber

Required. The number of times to change navigation

Moves the cursor to the specified row and column. Note that this does de-select the current selection.

Moves the cursor to the specified row and column. Note that this does de-select the current selection.

Arguments

rowNumber

Required. The new row number

columnNumber

Required. The new column number

    • Editor.navigateUp(Number times)

Moves the cursor up in the document the specified number of times. Note that this does de-select the current selection.

Moves the cursor up in the document the specified number of times. Note that this does de-select the current selection.

Arguments

timesNumber

Required. The number of times to change navigation

    • Editor.navigateWordLeft()

Moves the cursor to the word immediately to the left of the current position. Note that this does de-select the current selection.

Moves the cursor to the word immediately to the left of the current position. Note that this does de-select the current selection.

    • Editor.navigateWordRight()

Moves the cursor to the word immediately to the right of the current position. Note that this does de-select the current selection.

Moves the cursor to the word immediately to the right of the current position. Note that this does de-select the current selection.

    • Editor.onBlur()
    • Undocumented
    • Editor.onChangeAnnotation()
    • Undocumented
    • Editor.onChangeBackMarker()
    • Undocumented
    • Editor.onChangeBreakpoint()
    • Undocumented
    • Editor.onChangeFold()
    • Undocumented
    • Editor.onChangeFrontMarker()
    • Undocumented
    • Editor.onChangeMode()
    • Undocumented
    • Editor.onChangeWrapLimit()
    • Undocumented
    • Editor.onChangeWrapMode()
    • Undocumented
    • Editor.onCommandKey()
    • Undocumented
    • Editor.onCompositionEnd()
    • Undocumented
    • Editor.onCompositionStart()
    • Undocumented
    • Editor.onCompositionUpdate()
    • Undocumented
    • Editor.onCopy()

Called whenever a text "copy" happens.

Called whenever a text "copy" happens.

    • Editor.onCursorChange()

Emitted when the selection changes.

Emitted when the selection changes.

    • Editor.onCut()

Called whenever a text "cut" happens.

Called whenever a text "cut" happens.

    • Editor.onDocumentChange()
    • Undocumented
    • Editor.onFocus()
    • Undocumented

Called whenever a text "paste" happens.

Called whenever a text "paste" happens.

Arguments

textString

Required. The pasted text

    • Editor.onScrollLeftChange()
    • Undocumented
    • Editor.onScrollTopChange()
    • Undocumented
    • Editor.onSelectionChange()
    • Undocumented
    • Editor.onTextInput()
    • Undocumented
    • Editor.onTokenizerUpdate()
    • Undocumented
    • Editor.redo()

Perform a redo operation on the document, reimplementing the last change.

Perform a redo operation on the document, reimplementing the last change.

Removes words of text from the editor. A "word" is defined as a string of characters bookended by whitespace.

Removes words of text from the editor. A "word" is defined as a string of characters bookended by whitespace.

Arguments

dirString

Required. The direction of the deletion to occur, either "left" or "right"

    • Editor.removeLines()

Removes all the lines in the current selection

Removes all the lines in the current selection

    • Editor.removeSelectionMarker(Range The)

Removes the selection marker.

Removes the selection marker.

Arguments

TheRange

Required. selection range added with addSelectionMarker().

    • Editor.removeToLineEnd()

Removes all the words to the right of the current selection, until the end of the line.

Removes all the words to the right of the current selection, until the end of the line.

    • Editor.removeToLineStart()

Removes all the words to the left of the current selection, until the start of the line.

Removes all the words to the left of the current selection, until the start of the line.

    • Editor.removeWordLeft()

Removes the word directly to the left of the current selection.

Removes the word directly to the left of the current selection.

    • Editor.removeWordRight()

Removes the word directly to the right of the current selection.

Removes the word directly to the right of the current selection.

Replaces the first occurrence of options.needle with the value in replacement.

Replaces the first occurrence of options.needle with the value in replacement.

Arguments

replacementString

Required. The text to replace with

optionsObject

Required. The Search options to use

Replaces all occurrences of options.needle with the value in replacement.

Replaces all occurrences of options.needle with the value in replacement.

Arguments

replacementString

Required. The text to replace with

optionsObject

Required. The Search options to use

Triggers a resize of the editor.

Triggers a resize of the editor.

Arguments

forceBoolean

Required. If true, recomputes the size, even if the height and width haven't changed

    • Editor.revealRange()
    • Undocumented
    • Editor.scrollPageDown()

Scrolls the document to wherever "page down" is, without changing the cursor position.

Scrolls the document to wherever "page down" is, without changing the cursor position.

    • Editor.scrollPageUp()

Scrolls the document to wherever "page up" is, without changing the cursor position.

Scrolls the document to wherever "page up" is, without changing the cursor position.

Scrolls to a line. If center is true, it puts the line in middle of screen (or attempts to).

Scrolls to a line. If center is true, it puts the line in middle of screen (or attempts to).

Arguments

lineNumber

Required. The line to scroll to

centerBoolean

Required. If true

animateBoolean

Required. If true animates scrolling

callbackFunction

Required. Function to be called when the animation has finished

    • Editor.scrollToRow(Object row)

Moves the editor to the specified row.

Moves the editor to the specified row.

Arguments

rowObject

Required.

    • Editor.selectAll()

Selects all the text in editor.

Selects all the text in editor.

Finds the next occurrence of text in an active selection and adds it to the selections.

Finds the next occurrence of text in an active selection and adds it to the selections.

Arguments

dirNumber

Required. The direction of lines to select: -1 for up, 1 for down

skipBoolean

Required. If true, removes the active selection range

Adds a cursor above or below the active cursor.

Adds a cursor above or below the active cursor.

Arguments

dirNumber

Required. The direction of lines to select: -1 for up, 1 for down

skipBoolean

Required. If true, removes the active selection range

    • Editor.selectPageDown()

Selects the text from the current position of the document until where a "page down" finishes.

Selects the text from the current position of the document until where a "page down" finishes.

    • Editor.selectPageUp()

Selects the text from the current position of the document until where a "page up" finishes.

Selects the text from the current position of the document until where a "page up" finishes.

    • Editor.setAnimatedScroll()
    • Undocumented
    • Editor.setBehavioursEnabled(Boolean enabled)

Specifies whether to use behaviors or not. "Behaviors" in this case is the auto-pairing of special characters, like quotation marks, parenthesis, or brackets.

Specifies whether to use behaviors or not. "Behaviors" in this case is the auto-pairing of special characters, like quotation marks, parenthesis, or brackets.

Arguments

enabledBoolean

Required. Enables or disables behaviors

    • Editor.setDisplayIndentGuides()
    • Undocumented
    • Editor.setDragDelay(Number dragDelay)

Sets the delay (in milliseconds) of the mouse drag.

Sets the delay (in milliseconds) of the mouse drag.

Arguments

dragDelayNumber

Required. A value indicating the new delay

    • Editor.setFadeFoldWidgets()
    • Undocumented
    • Editor.setFontSize(Number size)

Set a new font size (in pixels) for the editor text.

Set a new font size (in pixels) for the editor text.

Arguments

sizeNumber

Required. A font size

    • Editor.setHighlightActiveLine(Boolean shouldHighlight)

Determines whether or not the current line should be highlighted.

Determines whether or not the current line should be highlighted.

Arguments

shouldHighlightBoolean

Required. Set to true to highlight the current line

    • Editor.setHighlightGutterLine()
    • Undocumented
    • Editor.setHighlightSelectedWord(Boolean shouldHighlight)

Determines if the currently selected word should be highlighted.

Determines if the currently selected word should be highlighted.

Arguments

shouldHighlightBoolean

Required. Set to true to highlight the currently selected word

    • Editor.setKeyboardHandler(String keyboardHandler)

Sets a new key handler, such as "vim" or "windows".

Sets a new key handler, such as "vim" or "windows".

Arguments

keyboardHandlerString

Required. The new key handler

    • Editor.setOverwrite(Boolean overwrite)

Pass in true to enable overwrites in your session, or false to disable. If overwrites is enabled, any text you enter will type over any text after it. If the value of overwrite changes, this function also emits the changeOverwrite event.

Pass in true to enable overwrites in your session, or false to disable. If overwrites is enabled, any text you enter will type over any text after it. If the value of overwrite changes, this function also emits the changeOverwrite event.

Arguments

overwriteBoolean

Required. Defines whether or not to set overwrites

    • Editor.setPrintMarginColumn(Number showPrintMargin)

Sets the column defining where the print margin should be.

Sets the column defining where the print margin should be.

Arguments

showPrintMarginNumber

Required. Specifies the new print margin

    • Editor.setReadOnly(Boolean readOnly)

If readOnly is true, then the editor is set to read-only mode, and none of the content can change.

If readOnly is true, then the editor is set to read-only mode, and none of the content can change.

Arguments

readOnlyBoolean

Required. Specifies whether the editor can be modified or not

    • Editor.setScrollSpeed(Number speed)

Sets how fast the mouse scrolling should do.

Sets how fast the mouse scrolling should do.

Arguments

speedNumber

Required. A value indicating the new speed (in milliseconds)

    • Editor.setSelectionStyle(String style)

Indicates how selections should occur.

Indicates how selections should occur.

By default, selections are set to "line". There are no other styles at the moment, although this code change in the future.

This function also emits the 'changeSelectionStyle' event.

Arguments

styleString

Required. The new selection style

Sets a new editsession to use. This method also emits the 'changeSession' event.

Sets a new editsession to use. This method also emits the 'changeSession' event.

Arguments

sessionEditSession

Required. The new session to use

    • Editor.setShowFoldWidgets(Boolean show)

Indicates whether the fold widgets are shown or not.

Indicates whether the fold widgets are shown or not.

Arguments

showBoolean

Required. Specifies whether the fold widgets are shown

    • Editor.setShowInvisibles(Boolean showInvisibles)

If showInvisibles is set to true, invisible characters—like spaces or new lines—are show in the editor.

If showInvisibles is set to true, invisible characters—like spaces or new lines—are show in the editor.

Arguments

showInvisiblesBoolean

Required. Specifies whether or not to show invisible characters

    • Editor.setShowPrintMargin(Boolean showPrintMargin)

If showPrintMargin is set to true, the print margin is shown in the editor.

If showPrintMargin is set to true, the print margin is shown in the editor.

Arguments

showPrintMarginBoolean

Required. Specifies whether or not to show the print margin

    • Editor.setStyle(String style)

Adds a new class, style, to the editor.

Adds a new class, style, to the editor.

Arguments

styleString

Required. A class name

    • Editor.setTheme(String theme)

Sets a new theme for the editor. theme should exist, and be a directory path, like ace/theme/textmate.

Sets a new theme for the editor. theme should exist, and be a directory path, like ace/theme/textmate.

Arguments

themeString

Required. The path to a theme

Sets the current document to val.

Sets the current document to val.

Arguments

valString

Required. The new value to set for the document

cursorPosNumber

Required. Where to set the new value. undefined or 0 is selectAll, -1 is at the document start, and 1 is at the end

    • Editor.setWrapBehavioursEnabled(Boolean enabled)

Specifies whether to use wrapping behaviors or not, i.e. automatically wrapping the selection with characters such as brackets when such a character is typed in.

Specifies whether to use wrapping behaviors or not, i.e. automatically wrapping the selection with characters such as brackets when such a character is typed in.

Arguments

enabledBoolean

Required. Enables or disables wrapping behaviors

    • Editor.sortLines()
    • Undocumented
    • Editor.splitLine()

Splits the line at the current selection (by inserting an '\n').

Splits the line at the current selection (by inserting an '\n').

    • Editor.toggleCommentLines()

Given the currently selected range, this function either comments all the lines, or uncomments all of them.

Given the currently selected range, this function either comments all the lines, or uncomments all of them.

    • Editor.toggleOverwrite()

Sets the value of overwrite to the opposite of whatever it currently is.

Sets the value of overwrite to the opposite of whatever it currently is.

    • Editor.toLowerCase()

Converts the current selection entirely into lowercase.

Converts the current selection entirely into lowercase.

    • Editor.toUpperCase()

Converts the current selection entirely into uppercase.

Converts the current selection entirely into uppercase.

    • Editor.transposeLetters()

Transposes current line.

Transposes current line.

    • Editor.transposeSelections(Number dir)

Transposes the selected ranges.

Transposes the selected ranges.

Arguments

dirNumber

Required. The direction to rotate selections

    • Editor.undo()

Perform an undo operation on the document, reverting the last change.

Perform an undo operation on the document, reverting the last change.

    • Editor.unsetStyle(Object style)

Removes the class style from the editor.

Removes the class style from the editor.

Arguments

styleObject

Required.

    • Editor.updateSelectionMarkers()

Updates the cursor and marker layers.

Updates the cursor and marker layers.