source-editor.jsm

The source-editor.jsm JavaScript code module implements an editor specifically tailored for editing source code; its primary purpose is to provide support for web developer tools to display and edit web site code. The editor provided is Eclipse Orion.

To use it, you first need to import the code module into your JavaScript scope:

Components.utils.import("resource:///modules/source-editor.jsm");

Method overview

Initialization and destruction

Search operations

Event management

Undo stack operations

Display management operations

Content management operations

Selection operations

Breakpoint management

Properties

Constants

Preference name constants

These constants define the names of preferences used by the source editor.

Editor mode constants

These constants are used to set the syntax highlighting mode for the editor by calling its setMode() method, or in the configuration object when first initializing the editor using its init() method.

Theme constants

These constants are used to identify the available themes that can be used by the syntax highlighter. Only one is provided by default at this time.

Configuration defaults constants

These constants represent the default values for each of the available configuration options. See The editor configuration object for details on configuring the editor.

Event name constants

These constants provide the names of the editor events for which you can listen.

Methods

addBreakpoint

Adds a breakpoint to be triggered at a certain line in the code, under an optional condition.

void addBreakpoint(  
  Number aLineIndex,
  [optional] String aCondition
);

Parameters

aLineIndex

The 0-based line number at which to place the breakpoint.

aCondition Optional

A string describing the condition under which the breakpoint should be triggered. This information is simply recorded as part of the breakpoint annotation. NEED LINK TO TEXT ABOUT HANDLING BREAKPOINT CONDITIONS HERE.

addEventListener()

Adds a new event listener to the editor. You can listen for any of the events listed in Event name constants. To stop listening for the event, call removeEventListener().

void addEventListener(
  String aEventType,
  Function aCallback
);

Parameters

aEventType

The name of the event type to listen for; see Event name constants for possible values.

aCallback

The function to call when the specified event occurs.

canRedo()

Determines whether or not there are changes that can be redone.

Boolean canRedo();

Parameters

None.

Return value

true if there are changes that can be redone, otherwise false.

canUndo()

Determines whether or not there are changes that can be undone.

Boolean canUndo();

Parameters

None.

Return value

true if there are changes that can be undone, otherwise false.

destroy()

Destroys the editor, releasing resource it's allocated and removing event handlers it's installed. You should call this method when you're done using the editor object.

void destroy();

Parameters

None.

dropSelection()

Deselects the currently selected text.

void dropSelection();

Parameters

None.

endCompoundChange()

Ends a compound change that was previously started by calling startCompoundChange(). All changes made to the text between the two calls is considered to be a single edit for the purposes of undo operations.

void endCompoundChange();

Parameters

None.

find()

Finds a string in the editor's text.

Number find(
  [optional] String aString
  [optional] Object aOptions
);

Parameters

aString Optional

The string for which to search. If not specified, the currently selected text in the editor is used as the search string.

aOptions Optional

An optional object containing properties customizing the search operation. See Find options for details.

Return value

Returns an integer indicating the offset into the text at which the first character of the found string is located, or -1 if the string wasn't found.

Find options

The aOptions object can customize the search operation. It may have the following properties:

findNext()

Finds the next occurrence of the search operation started by the last call to find().

Number findNext(
  Boolean aWrap
};

Parameters

aWrap

If true, the search operation will wrap around to the beginning of the text. Otherwise, the search stops if the end of the text is reached.

Return value

The offset into the text at which the next occurrence of the string begins, or -1 if the string isn't found.

findPrevious()

Finds the previous occurrence of the search operation started by the last call to find().

Number findNext(
  Boolean aWrap
};

Parameters

aWrap

If true, the search operation will wrap around to the end of the text. Otherwise, the search stops if the beginning of the text is reached.

Return value

The offset into the text at which the next occurrence of the string begins, or -1 if the string isn't found.

focus()

Makes the editor the focus for user input.

void focus();

Parameters

None.

getBreakpoints

Returns an array of all of the breakpoints currently set on the code in the editor instance.

Array getBreakpoints();

Parameters

None.

Return value

An Array of all of the breakpoints in the editor instance. Each breakpoint is an Object with the following properties:

getCaretOffset()

Returns the current caret position (insertion point) as an offset into the text.

Number getCaretOffset();

Parameters

None.

Return value

The 0-based offset into the text at which newly-typed characters will be inserted.

getCaretPosition()

Returns an object describing the position of the caret (insertion point) in terms of its line number and column.

Object getCaretPosition();

Parameters

None.

Return value

The returned object describes the caret position:

getCharCount()

Returns the number of characters in the editor's content.

Number getCharCount();

Parameters

None.

Return value

The number of characters in the editor's text.

getIndentationString

Returns a string containing the character or characters that are inserted when the user presses the tab key.

String getIndentationString();

Parameters

None.

Return value

If tabs are configured to be expanded into spaces (that is, the expandTab property is true), the returned string is comprised of the number of spaces specified by the tabSize property when the editor was initialized by calling init(). Otherwise, the returned string is simply "\t".

getLineCount()

Returns the number of lines of text in the editor.

Number getLineCount();

Parameters

None.

Return value

The number of lines of text in the document being edited.

getLineDelimiter()

Returns a string containing the character or characters that are used as the end of each line of text. This may be, for example, "\n", "\r", or "\r\n".

String getLineDelimiter();

Parameters

None.

Return value

A string containing the character or characters that delineate lines of text.

getLineEnd

Returns the character offset of the character after the specified line number in the text.

Number getLineEnd(
  Number aLineIndex,
  [optional] Boolean aIncludeDelimiter
);

Parameters

aLineIndex

Zero-based offset to the line number to which to return the end offset.

aIncludeDelimiter Optional

If false, the returned offset is to the first character of the end-of-line delimiter if the specified line (this is the default). If true, the returned offset is the offset to the first character of the following line.

Return value

The offset to the last character in the specified line, or -1 if the specified line number is out of range.

getLineStart

Returns the character offset of the first character of the specified line in the text.

Number getLineStart(
  Number aLineIndex
);

Parameters

aLineIndex

Zero-based offset to the line number to which to return the end offset.

Return value

The offset to the first character in the specified line, or -1 if the specified line number is out of range.

getMode()

Returns the current syntax highlighting mode for the document's contents.

String getMode();

Parameters

None.

Return value

A string indicating the type of file being edited, as previously set using either the mode property when configuring the editor, or by a call to setMode(). See Editor mode constants for possible values.

getSelectedText()

Returns the currently-selected text.

String getSelectedText();

Parameters

None.

Return value

The currently-selected text in the editor.

getSelection()

Returns an object indicating the offsets to the first and last characters that are currently selected.

Object getSelection();

Parameters

None.

Return value

An object describing the currently selected range of text in the editor:

If there's no selection, the current caret position is returned for both start and end.

getText()

Returns the text in the specified range within the editor, or all of the editor's text if no range is given.

String getText(
  [optional] Number aStart,
  [optional] Number aEnd
);

Parameters

aStart Optional

The offset to the first character to retrieve.

aEnd Optional

The offset to the last character to retrieve. If this isn't provided, all text from aStart (or the beginning of the document, if that wasn't provided either) to the end of the text is returned.

Return value

A string containing the specified range of text (or all of the text, if a range wasn't provided).

getTopIndex()

Returns the line number of the first line currently visible in the editor, based on the current scroll position of the editor.

Number getTopIndex();

Parameters

None.

Return value

The line number of the first visible line; this is a 0-based value, so the first line of the document is line number 0.

init()

Initializes the editor. You must call this, and wait until your callback is called, before calling any other Source Editor methods.

void init(
  Element aElement,
  Object aConfig
  Function aCallback
);

Parameters

aElement

The DOM element in which to place the editor.

aConfig

An object containing a set of properties used to configure the editor. See The editor configuration object for details.

aCallback

A function that will be called when the editor has been fully loaded and initialized.

hasFocus()

Determines whether or not the editor is currently focused.

Boolean hasFocus();

Parameters

None.

Return value

true if the editor is currently focused, otherwise false.

redo()

Redoes the most recently undone change in the editor.

Boolean redo();

Parameters

None.

Return value

true if a change was redone, otherwise false.

removeBreakpoint

Removes the breakpoint from the specified line of code.

Boolean removeBreakpoint(
  Number aLineIndex
);

Parameters

aLineIndex

The 0-based line number from which to remove the breakpoint.

Return value

true if a breakpoint was removed, otherwise false.

removeEventListener()

Removes an event listener (previously established by calling addEventListener() from the editor.

void removeEventListener(
  String aEventType,
  Function aCallback
);

Parameters

aEventType

The name of the event type to stop listening for; see Event name constants for possible values.

aCallback

The function to stop calling when the specified event occurs.

resetUndo

Resets the undo stack, removing all possible undo and redo operations from the stack.

void resetUndo();

Parameters

None.

setCaretOffset()

Sets the current caret position (insertion point) for newly-entered text.

void setCaretOffset(
  Number aOffset
);

Parameters

aOffset

The 0-based offset into the text at which to place the caret.

setCaretPosition()

Sets the current caret position given a line number and column number.

void setCaretPosition(
  Number aLine,
  [optional] Number aColumn,
  [optional] Number aAlign
);

Parameters

aLine

The 0-based line number on which to place the caret.

aColumn Optional

The 0-based column number at which to place the caret; if you don't provide this parameter, the caret is placed at the beginning of the line specified by aLine.

aAlign Optional

How to position the line with respect to the viewport when scrolling the line into view. This may be one of SourceEditor.VERTICAL_ALIGN.TOP, SourceEditor.VERTICAL_ALIGN.CENTER, and SourceEditor.VERTICAL_ALIGN_BOTTOM. See Alignment constants for details. The default is SourceEditor.VERTICAL_ALIGN.TOP.

setMode()

Sets the current syntax highlighting mode for the text being edited.

void setMode(
  String aMode
);

Parameters

aMode

A string indicating the file type being edited. See Editor mode constants for possible values.

setSelection()

Selects the specified range of text.

void setSelection(
  Number aStart,
  Number aEnd
);

Parameters

aStart

The 0-based offset to the first character to select in the text.

aEnd

The offset to the first character after the range you wish to select.

Remarks

It's important to note that the character at offset aEnd is not included in the selection.

setText()

Replaces a range of text in the editor with the specified string. If you don't specify a range, the entire text is replaced.

void setText(
  String aString,
  [optional] Number aStart,
  [optional] Number aEnd
);

Parameters

aString

The text to put into the editor.

aStart Optional

The 0-based offset to the first character in the text to replace.

aEnd Optional

The offset to the last character to replace. If you don't specify this value, the entire string from aStart (or the first character in the text, if you don't specify aStart) to the end of the text is replaced.

setTopIndex()

Scrolls the text as necessary to place the specified line number at the top of the view.

void setTopIndex(
  Number aTopIndex
);

Parameters

aTopIndex

The 0-based line number to place at the top of the editor's view.

startCompoundChange()

Begins a compound change in the editor. All changes made between a call to startCompoundChange() and its corresponding call to endCompoundChange() are considered to be a single operation on the undo stack.

void startCompoundChange();

Parameters

None.

undo()

Undoes the most recent change made in the editor.

Boolean undo();

Parameters

None.

Return value

true if a change was undone or false if there were no changes to undo.

The editor configuration object

When you call init() to initialize the editor, you pass in an object that contains properties configuring the editor's features. That object may contain any combination of the following properties:

See Configuration defaults constants for a list of the default values for these configuration options.

Events

There are a number of events that can be sent by the source editor, as listed in Event name constants. This section provides details on each of those events and their properties.

ContextMenu

The "ContextMenu" event is sent when the editor's context menu is invoked, and has the following properties.

TextChanged

The "TextChanged" event is sent when the contents of the editor change. It has the following properties:

Selection

The "Selection" element is sent when the selection within the editor changes. It has the following properties:

The objects used for oldValue and newValue each have two properties of type Number: start and end, describing the start and end positions of the range of characters.

The "Focus" event is sent when the editor is focused. It has no properties.

The "Blur" event is sent when the editor loses focus. It has no properties.

MouseMove

The "MouseMove" event is sent when the user moves the mouse pointer over a line of text content. It has the following properties:

MouseOver

The "MouseOver" event is sent when the user moves the mouse pointer enters a line of text content. It has the following properties:

MouseOut

The "MouseOut" event is sent when the user moves the mouse pointer over a line of text content. It has the following properties:

The "BreakpointChange" event is sent when a breakpoint is changed. This can be any of the following changes:

• One or more new breakpoints were added, using either the API or editor user interface.
• One or more breakpoints were removed, using either the API or editor user interface.

The event has the following properties:

The "DirtyChanged" event is sent when the dirty state of the editor changes. This state indicates whether or not there have been changes to the text since the last time the content was saved. This event has the following properties:

If the dirty flag is true, the document has not been saved since the last time its text was changed. You can set the dirty state of the document by setting the value of the dirty attribute.