# EditSession

Stores all the data about `Editor` state providing easy way to change editors state.

`EditSession` can be attached to only one `Document`. Same `Document` can be attached to several `EditSession`s.

### Constructors

- - new EditSession(Document | String text, TextMode mode)

Sets up a new `EditSession` and associates it with the given `Document` and `TextMode`.

Sets up a new `EditSession` and associates it with the given `Document` and `TextMode`.

#### Arguments

text | Document | String | Required. If `text` is a `Document`, it associates the `EditSession` with it. Otherwise, a new `Document` is created, with the initial text
mode | TextMode | Required. The inital language mode to use for the document

### Events

- - EditSession.on("change", function( Object e))

Emitted when the document changes.

Emitted when the document changes.

#### Arguments

e | Object | Required. An object containing a `delta` of information about the change.

- - EditSession.on("changeAnnotation", function())

Emitted when an annotation changes, like through `EditSession.setAnnotations()`.

Emitted when an annotation changes, like through `EditSession.setAnnotations()`.

- - EditSession.on("changeBackMarker", function())

Emitted when a back marker changes.

Emitted when a back marker changes.

- - EditSession.on("changeBreakpoint", function())

Emitted when the gutter changes, either by setting or removing breakpoints, or when the gutter decorations change.

Emitted when the gutter changes, either by setting or removing breakpoints, or when the gutter decorations change.

- - EditSession.on("changeFold", function())

Emitted when a code fold is added or removed.

Emitted when a code fold is added or removed.

- - EditSession.on("changeFrontMarker", function())

Emitted when a front marker changes.

Emitted when a front marker changes.

- - EditSession.on("changeMode", function())

Emitted when the current mode changes.

Emitted when the current mode changes.

- - EditSession.on("changeOverwrite", function())

Emitted when the ability to overwrite text changes, via `EditSession.setOverwrite()`.

Emitted when the ability to overwrite text changes, via `EditSession.setOverwrite()`.

- - EditSession.on("changeScrollLeft", function( Number scrollLeft))

Emitted when the scroll left changes.

Emitted when the scroll left changes.

#### Arguments

scrollLeft | Number | Required. The new scroll left value

- - EditSession.on("changeScrollTop", function( Number scrollTop))

Emitted when the scroll top changes.

Emitted when the scroll top changes.

#### Arguments

scrollTop | Number | Required. The new scroll top value

- - EditSession.on("changeTabSize", function())

Emitted when the tab size changes, via `EditSession.setTabSize()`.

Emitted when the tab size changes, via `EditSession.setTabSize()`.

- - EditSession.on("changeWrapLimit", function())

Emitted when the wrapping limit changes.

Emitted when the wrapping limit changes.

- - EditSession.on("changeWrapMode", function())

Emitted when the wrap mode changes.

Emitted when the wrap mode changes.

- - EditSession.on("tokenizerUpdate", function( Object e))

Emitted when a background tokenizer asynchronously processes new rows.

Emitted when a background tokenizer asynchronously processes new rows.

#### Arguments

e | Object | Required. An object containing one property, `"data"`, that contains information about the changing rows

### Methods

- - EditSession.addDynamicMarker(Object marker, Boolean inFront)
  - - Object

Adds a dynamic marker to the session.

Adds a dynamic marker to the session.

#### Arguments

marker | Object | Required. object with update method
inFront | Boolean | Required. Set to `true` to establish a front marker

- - EditSession.addGutterDecoration(Number row, String className)

Adds `className` to the `row`, to be used for CSS stylings and whatnot.

Adds `className` to the `row`, to be used for CSS stylings and whatnot.

#### Arguments

row | Number | Required. The row number
className | String | Required. The class to add

- - EditSession.addMarker(Range range, String clazz, Function | String type, Boolean inFront)
  - - Number

Adds a new marker to the given `Range`. If `inFront` is `true`, a front marker is defined, and the `'changeFrontMarker'` event fires; otherwise, the `'changeBackMarker'` event fires.

Adds a new marker to the given `Range`. If `inFront` is `true`, a front marker is defined, and the `'changeFrontMarker'` event fires; otherwise, the `'changeBackMarker'` event fires.

#### Arguments

range | Range | Required. Define the range of the marker
clazz | String | Required. Set the CSS class for the marker
type | Function | String | Required. Identify the type of the marker
inFront | Boolean | Required. Set to `true` to establish a front marker

- - EditSession.clearAnnotations()

Clears all the annotations for this session. This function also triggers the `'changeAnnotation'` event.

Clears all the annotations for this session. This function also triggers the `'changeAnnotation'` event.

- - EditSession.clearBreakpoint(Number row)

Removes a breakpoint on the row number given by `rows`. This function also emites the `'changeBreakpoint'` event.

Removes a breakpoint on the row number given by `rows`. This function also emites the `'changeBreakpoint'` event.

#### Arguments

row | Number | Required. A row index

- - EditSession.clearBreakpoints()

Removes all breakpoints on the rows. This function also emites the `'changeBreakpoint'` event.

Removes all breakpoints on the rows. This function also emites the `'changeBreakpoint'` event.

- - EditSession.documentToScreenColumn(Number row, Number docColumn)
  - - Number

For the given document row and column, returns the screen column.

For the given document row and column, returns the screen column.

#### Arguments

row | Number | Required.
docColumn | Number | Required.

- - EditSession.documentToScreenPosition(Number docRow, Number docColumn)
  - - Object

Converts document coordinates to screen coordinates. This takes into account code folding, word wrap, tab size, and any other visual modifications.

Converts document coordinates to screen coordinates. This takes into account code folding, word wrap, tab size, and any other visual modifications.

#### Arguments

docRow | Number | Required. The document row to check
docColumn | Number | Required. The document column to check

- - EditSession.documentToScreenRow(Number docRow, Number docColumn)

For the given document row and column, returns the screen row.

For the given document row and column, returns the screen row.

#### Arguments

docRow | Number | Required.
docColumn | Number | Required.

- - EditSession.duplicateLines(Number firstRow, Number lastRow)
  - - Number

Duplicates all the text between `firstRow` and `lastRow`.

Duplicates all the text between `firstRow` and `lastRow`.

#### Arguments

firstRow | Number | Required. The starting row to duplicate
lastRow | Number | Required. The final row to duplicate

- - EditSession.getAnnotations()
  - - Object

Returns the annotations for the `EditSession`.

Returns the annotations for the `EditSession`.

- - EditSession.getAWordRange(Number row, Number column)
  - - Range

Gets the range of a word, including its right whitespace.

Gets the range of a word, including its right whitespace.

#### Arguments

row | Number | Required. The row number to start from
column | Number | Required. The column number to start from

- - EditSession.getBreakpoints()
  - - Number

Returns an array of numbers, indicating which rows have breakpoints.

Returns an array of numbers, indicating which rows have breakpoints.

- - EditSession.getDocument()
  - - Document

Returns the `Document` associated with this session.

Returns the `Document` associated with this session.

- - EditSession.getDocumentLastRowColumn(Number docRow, Number docColumn)

For the given document row and column, this returns the column position of the last screen row.

For the given document row and column, this returns the column position of the last screen row.

#### Arguments

docRow | Number | Required.
docColumn | Number | Required.

- - EditSession.getDocumentLastRowColumnPosition(Number docRow, Number docColumn)

For the given document row and column, this returns the document position of the last row.

For the given document row and column, this returns the document position of the last row.

#### Arguments

docRow | Number | Required.
docColumn | Number | Required.

- - EditSession.getLength()
  - - Number

Returns the number of rows in the document.

Returns the number of rows in the document.

- - EditSession.getLine(Number row)
  - - String

Returns a verbatim copy of the given line as it is in the document

Returns a verbatim copy of the given line as it is in the document

#### Arguments

row | Number | Required. The row to retrieve from

- - EditSession.getLines(Number firstRow, Number lastRow)
  - - String

Returns an array of strings of the rows between `firstRow` and `lastRow`. This function is inclusive of `lastRow`.

Returns an array of strings of the rows between `firstRow` and `lastRow`. This function is inclusive of `lastRow`.

#### Arguments

firstRow | Number | Required. The first row index to retrieve
lastRow | Number | Required. The final row index to retrieve

- - EditSession.getMarkers(Boolean inFront)
  - - Array

Returns an array containing the IDs of all the markers, either front or back.

Returns an array containing the IDs of all the markers, either front or back.

#### Arguments

inFront | Boolean | Required. If `true`, indicates you only want front markers; `false` indicates only back markers

- - EditSession.getMode()
  - - TextMode

Returns the current text mode.

Returns the current text mode.

- - EditSession.getNewLineMode()
  - - String

Returns the current new line mode.

Returns the current new line mode.

- - EditSession.getOverwrite()

Returns `true` if overwrites are enabled; `false` otherwise.

Returns `true` if overwrites are enabled; `false` otherwise.

- - EditSession.getRowLength(Number row)
  - - Number

Returns number of screenrows in a wrapped line.

Returns number of screenrows in a wrapped line.

#### Arguments

row | Number | Required. The row number to check

- - EditSession.getRowSplitData(Object row)
  - - String

For the given row, this returns the split data.

For the given row, this returns the split data.

#### Arguments

row | Object | Required.

- - EditSession.getScreenLastRowColumn(Number screenRow)
  - - Number

Returns the position (on screen) for the last character in the provided screen row.

Returns the position (on screen) for the last character in the provided screen row.

#### Arguments

screenRow | Number | Required. The screen row to check

- - EditSession.getScreenLength()
  - - Number

Returns the length of the screen.

Returns the length of the screen.

- - EditSession.getScreenTabSize(Number screenColumn)
  - - Number

The distance to the next tab stop at the specified screen column.

The distance to the next tab stop at the specified screen column.

#### Arguments

screenColumn | Number | Required. The screen column to check

- - EditSession.getScreenWidth()
  - - Number

Returns the width of the screen.

Returns the width of the screen.

- - EditSession.getScrollLeft()
  - - Number

Returns the value of the distance between the left of the editor and the leftmost part of the visible content.

Returns the value of the distance between the left of the editor and the leftmost part of the visible content.

- - EditSession.getScrollTop()
  - - Number

Returns the value of the distance between the top of the editor and the topmost part of the visible content.

Returns the value of the distance between the top of the editor and the topmost part of the visible content.

- - EditSession.getSelection()

Returns the string of the current selection.

Returns the string of the current selection.

- - EditSession.getState(Number row)

Returns the state of tokenization at the end of a row.

Returns the state of tokenization at the end of a row.

#### Arguments

row | Number | Required. The row to start at

- - EditSession.getTabSize()

Returns the current tab size.

Returns the current tab size.

- - EditSession.getTabString()

Returns the current value for tabs. If the user is using soft tabs, this will be a series of spaces (defined by `getTabSize()`); otherwise it's simply `'\t'`.

Returns the current value for tabs. If the user is using soft tabs, this will be a series of spaces (defined by `getTabSize()`); otherwise it's simply `'\t'`.

- - EditSession.getTextRange(Range range)
  - - String

Given a range within the document, this function returns all the text within that range as a single string.

Given a range within the document, this function returns all the text within that range as a single string.

#### Arguments

range | Range | Required. The range to work with

- - EditSession.getTokenAt(Number row, Number column)

Returns an object indicating the token at the current row. The object has two properties: `index` and `start`.

Returns an object indicating the token at the current row. The object has two properties: `index` and `start`.

#### Arguments

row | Number | Required. The row number to retrieve from
column | Number | Required. The column number to retrieve from

- - EditSession.getTokens(Number row)

Starts tokenizing at the row indicated. Returns a list of objects of the tokenized rows.

Starts tokenizing at the row indicated. Returns a list of objects of the tokenized rows.

#### Arguments

row | Number | Required. The row to start at

- - EditSession.getUndoManager()

Returns the current undo manager.

Returns the current undo manager.

- - EditSession.getUseSoftTabs()
  - - Boolean

Returns `true` if soft tabs are being used, `false` otherwise.

Returns `true` if soft tabs are being used, `false` otherwise.

- - EditSession.getUseWorker()

Returns `true` if workers are being used.

Returns `true` if workers are being used.

- - EditSession.getUseWrapMode()
  - - Boolean

Returns `true` if wrap mode is being used; `false` otherwise.

Returns `true` if wrap mode is being used; `false` otherwise.

- - EditSession.getValue()
  - - String

Returns the current `Document` as a string.

Returns the current `Document` as a string.

- - EditSession.getWordRange(Number row, Number column)
  - - Range

Given a starting row and column, this method returns the `Range` of the first word boundary it finds.

Given a starting row and column, this method returns the `Range` of the first word boundary it finds.

#### Arguments

row | Number | Required. The row to start at
column | Number | Required. The column to start at

- - EditSession.getWrapLimit()
  - - Number

Returns the value of wrap limit.

Returns the value of wrap limit.

- - EditSession.getWrapLimitRange()
  - - Object

Returns an object that defines the minimum and maximum of the wrap limit; it looks something like this:

Returns an object that defines the minimum and maximum of the wrap limit; it looks something like this:

{ min: wrapLimitRange_min, max: wrapLimitRange_max }

- - EditSession.highlight()
  - Undocumented

- - EditSession.highlightLines()
  - Undocumented

- - EditSession.indentRows(Number startRow, Number endRow, String indentString)

Indents all the rows, from `startRow` to `endRow` (inclusive), by prefixing each row with the token in `indentString`.

Indents all the rows, from `startRow` to `endRow` (inclusive), by prefixing each row with the token in `indentString`.

If `indentString` contains the `'\t'` character, it's replaced by whatever is defined by `getTabString()`.

#### Arguments

startRow | Number | Required. Starting row
endRow | Number | Required. Ending row
indentString | String | Required. The indent token

- - EditSession.insert(Object position, String text)
  - - Object

Inserts a block of `text` and the indicated `position`.

Inserts a block of `text` and the indicated `position`.

#### Arguments

position | Object | Required. The position {row, column} to start inserting at
text | String | Required. A chunk of text to insert

- - EditSession.isTabStop(Object position)

Returns `true` if the character at the position is a soft tab.

Returns `true` if the character at the position is a soft tab.

#### Arguments

position | Object | Required. The position to check

- - EditSession.moveLinesDown(Number firstRow, Number lastRow)
  - - Number

Shifts all the lines in the document down one, starting from `firstRow` and ending at `lastRow`.

Shifts all the lines in the document down one, starting from `firstRow` and ending at `lastRow`.

#### Arguments

firstRow | Number | Required. The starting row to move down
lastRow | Number | Required. The final row to move down

- - EditSession.moveLinesUp(Number firstRow, Number lastRow)
  - - Number

Shifts all the lines in the document up one, starting from `firstRow` and ending at `lastRow`.

Shifts all the lines in the document up one, starting from `firstRow` and ending at `lastRow`.

#### Arguments

firstRow | Number | Required. The starting row to move up
lastRow | Number | Required. The final row to move up

- - EditSession.moveText(Range fromRange, Object toPosition)
  - - Range

Moves a range of text from the given range to the given position. `toPosition` is an object that looks like this:

       { row: newRowLocation, column: newColumnLocation }

Moves a range of text from the given range to the given position. `toPosition` is an object that looks like this:

       { row: newRowLocation, column: newColumnLocation }

#### Arguments

fromRange | Range | Required. The range of text you want moved within the document
toPosition | Object | Required. The location (row and column) where you want to move the text to

- - EditSession.onChange()
  - Undocumented

- - EditSession.onChangeFold()
  - Undocumented

- - EditSession.onReloadTokenizer(Object e)

Reloads all the tokens on the current session. This function calls `BackgroundTokenizer.start ()` to all the rows; it also emits the `'tokenizerUpdate'` event.

Reloads all the tokens on the current session. This function calls `BackgroundTokenizer.start ()` to all the rows; it also emits the `'tokenizerUpdate'` event.

#### Arguments

e | Object | Required.

- - EditSession.outdentRows(Range range)

Outdents all the rows defined by the `start` and `end` properties of `range`.

Outdents all the rows defined by the `start` and `end` properties of `range`.

#### Arguments

range | Range | Required. A range of rows

- - EditSession.redo()
  - Undocumented

- - EditSession.redoChanges(Array deltas, Boolean dontSelect)
  - - Range

Re-implements a previously undone change to your document.

Re-implements a previously undone change to your document.

#### Arguments

deltas | Array | Required. An array of previous changes
dontSelect | Boolean | Required. If `true`, doesn't select the range of where the change occured

- - EditSession.remove(Range range)
  - - Object

Removes the `range` from the document.

Removes the `range` from the document.

#### Arguments

range | Range | Required. A specified Range to remove

- - EditSession.removeGutterDecoration(Number row, String className)

Removes `className` from the `row`.

Removes `className` from the `row`.

#### Arguments

row | Number | Required. The row number
className | String | Required. The class to add

- - EditSession.removeMarker(Number markerId)

Removes the marker with the specified ID. If this marker was in front, the `'changeFrontMarker'` event is emitted. If the marker was in the back, the `'changeBackMarker'` event is emitted.

Removes the marker with the specified ID. If this marker was in front, the `'changeFrontMarker'` event is emitted. If the marker was in the back, the `'changeBackMarker'` event is emitted.

#### Arguments

markerId | Number | Required. A number representing a marker

- - EditSession.replace(Range range, String text)
  - - Object

Replaces a range in the document with the new `text`.

Replaces a range in the document with the new `text`.

#### Arguments

range | Range | Required. A specified Range to replace
text | String | Required. The new text to use as a replacement

- - EditSession.reset()
  - Undocumented

- - EditSession.resetCaches()
  - Undocumented

- - EditSession.screenToDocumentColumn()
  - Undocumented

- - EditSession.screenToDocumentPosition(Number screenRow, Number screenColumn)
  - - Object

Converts characters coordinates on the screen to characters coordinates within the document. This takes into account code folding, word wrap, tab size, and any other visual modifications.

Converts characters coordinates on the screen to characters coordinates within the document. This takes into account code folding, word wrap, tab size, and any other visual modifications.

#### Arguments

screenRow | Number | Required. The screen row to check
screenColumn | Number | Required. The screen column to check

- - EditSession.screenToDocumentRow()
  - Undocumented

- - EditSession.setAnnotations(Array annotations)

Sets annotations for the `EditSession`. This functions emits the `'changeAnnotation'` event.

Sets annotations for the `EditSession`. This functions emits the `'changeAnnotation'` event.

#### Arguments

annotations | Array | Required. A list of annotations

- - EditSession.setBreakpoint(Number row, String className)

Sets a breakpoint on the row number given by `rows`. This function also emites the `'changeBreakpoint'` event.

Sets a breakpoint on the row number given by `rows`. This function also emites the `'changeBreakpoint'` event.

#### Arguments

row | Number | Required. A row index
className | String | Required. Class of the breakpoint

- - EditSession.setBreakpoints(Array rows)

Sets a breakpoint on every row number given by `rows`. This function also emites the `'changeBreakpoint'` event.

Sets a breakpoint on every row number given by `rows`. This function also emites the `'changeBreakpoint'` event.

#### Arguments

rows | Array | Required. An array of row indices

- - EditSession.setDocument(Document doc)

Sets the `EditSession` to point to a new `Document`. If a `BackgroundTokenizer` exists, it also points to `doc`.

Sets the `EditSession` to point to a new `Document`. If a `BackgroundTokenizer` exists, it also points to `doc`.

#### Arguments

doc | Document | Required. The new `Document` to use

- - EditSession.setMode()
  - Undocumented

- - EditSession.setNewLineMode(String newLineMode)

Sets the new line mode.

Sets the new line mode.

#### Arguments

newLineMode | String | Required. The newline mode to use; can be either `windows`, `unix`, or `auto`

- - EditSession.setOverwrite(Boolean overwrite)

Pass in `true` to enable overwrites in your session, or `false` to disable.

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 emites the `changeOverwrite` event.

#### Arguments

overwrite | Boolean | Required. Defines wheter or not to set overwrites

- - EditSession.setScrollLeft(Object scrollLeft)

Sets the value of the distance between the left of the editor and the leftmost part of the visible content.

Sets the value of the distance between the left of the editor and the leftmost part of the visible content.

#### Arguments

scrollLeft | Object | Required.

- - EditSession.setScrollTop(Number scrollTop)

This function sets the scroll top value. It also emits the `'changeScrollTop'` event.

This function sets the scroll top value. It also emits the `'changeScrollTop'` event.

#### Arguments

scrollTop | Number | Required. The new scroll top value

- - EditSession.setTabSize(Number tabSize)

Set the number of spaces that define a soft tab; for example, passing in `4` transforms the soft tabs to be equivalent to four spaces. This function also emits the `changeTabSize` event.

Set the number of spaces that define a soft tab; for example, passing in `4` transforms the soft tabs to be equivalent to four spaces. This function also emits the `changeTabSize` event.

#### Arguments

tabSize | Number | Required. The new tab size

- - EditSession.setUndoManager(UndoManager undoManager)

Sets the undo manager.

Sets the undo manager.

#### Arguments

undoManager | UndoManager | Required. The new undo manager

- - EditSession.setUndoSelect(Boolean enable)

Enables or disables highlighting of the range where an undo occured.

Enables or disables highlighting of the range where an undo occured.

#### Arguments

enable | Boolean | Required. If `true`, selects the range of the reinserted change

- - EditSession.setUseSoftTabs(Boolean useSoftTabs)

Pass `true` to enable the use of soft tabs. Soft tabs means you're using spaces instead of the tab character (`'\t'`).

Pass `true` to enable the use of soft tabs. Soft tabs means you're using spaces instead of the tab character (`'\t'`).

#### Arguments

useSoftTabs | Boolean | Required. Value indicating whether or not to use soft tabs

- - EditSession.setUseWorker(Boolean useWorker)

Identifies if you want to use a worker for the `EditSession`.

Identifies if you want to use a worker for the `EditSession`.

#### Arguments

useWorker | Boolean | Required. Set to `true` to use a worker

- - EditSession.setUseWrapMode(Boolean useWrapMode)

Sets whether or not line wrapping is enabled. If `useWrapMode` is different than the current value, the `'changeWrapMode'` event is emitted.

Sets whether or not line wrapping is enabled. If `useWrapMode` is different than the current value, the `'changeWrapMode'` event is emitted.

#### Arguments

useWrapMode | Boolean | Required. Enable (or disable) wrap mode

- - EditSession.setValue(String text)

Sets the session text.

Sets the session text.

#### Arguments

text | String | Required. The new text to place

- - EditSession.setWrapLimitRange(Number min, Number max)

Sets the boundaries of wrap. Either value can be `null` to have an unconstrained wrap, or, they can be the same number to pin the limit. If the wrap limits for `min` or `max` are different, this method also emits the `'changeWrapMode'` event.

Sets the boundaries of wrap. Either value can be `null` to have an unconstrained wrap, or, they can be the same number to pin the limit. If the wrap limits for `min` or `max` are different, this method also emits the `'changeWrapMode'` event.

#### Arguments

min | Number | Required. The minimum wrap value (the left side wrap)
max | Number | Required. The maximum wrap value (the right side wrap)

- - EditSession.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.

- - EditSession.toString()
  - - String

Returns the current `Document` as a string.

Returns the current `Document` as a string.

- - EditSession.undo()
  - Undocumented

- - EditSession.undoChanges(Array deltas, Boolean dontSelect)
  - - Range

Reverts previous changes to your document.

Reverts previous changes to your document.

#### Arguments

deltas | Array | Required. An array of previous changes
dontSelect | Boolean | Required. If `true`, doesn't select the range of where the change occured