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");

Warning: Much of the functionality of the source editor is implemented by a secondary code module (by default, source-editor-orion.jsm). You must not directly import that code module; it is essentially an implementation detail. Its functionality is all exposed through source-editor.jsm.

Breakpoint management

Properties

Attribute

Type

Description

dirty

Boolean

Set this value to false whenever you save the text; the editor will update it to true when the content is changed. You can then use this value to detect when the contents of the text are different from your most recent save. In addition, when this value changes, the "DirtyChanged" event is sent.

The index of the previous location at which str was found, for multiple find operations (such as find() followed by findNext()). This can be -1 if the string was never found.

ignoreCase

Boolean

true if the search was case sensitive; otherwise false.

readOnly

Boolean

Set this value to true to make the editor read only, thereby preventing the user from making changes. Set it to false to allow editing.

Constants

Preference name constants

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

Constant

Value

Description

SourceEditor.PREFS.COMPONENT

"devtools.editor.component"

A string indicating the name of the source editor engine to use; this is "orion" by default. The source editor code module loads a module by the name "source-editor-<component>.jsm" and exposes its API as part of the SourceEditor object.

SourceEditor.PREFS.EXPAND_TAB

"devtools.editor.expandtab"

A Boolean value that indicates whether or not to automatically expand tabs out to a series of spaces.

SourceEditor.PREFS.TAB_SIZE

"devtools.editor.tabsize"

An integer value that specifies the number of spaces per tab.

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.

Constant

Value

Description

SourceEditor.MODES.CSS

"css"

Cascading Style Sheet.

SourceEditor.MODES.HTML

"html"

HTML document.

SourceEditor.MODES.JAVASCRIPT

"js"

JavaScript source code.

SourceEditor.MODES.TEXT

"text"

UTF-8 text document.

SourceEditor.MODES.XML

"xml"

XML document.

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.

Constant

Value

Description

SourceEditor.THEMES.MOZILLA

"mozilla"

The default Mozilla syntax highlighter theme.

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.

Constant

Value

SourceEditor.DEFAULTS.contextMenu

"sourceEditorContextMenu"

SourceEditor.DEFAULTS.expandTab

true

SourceEditor.DEFAULTS.highlightCurrentLine

true

SourceEditor.DEFAULTS.initialText

""

SourceEditor.DEFAULTS.keys

null

SourceEditor.DEFAULTS.mode

SourceEditor.MODES.TEXT

SourceEditor.DEFAULTS.readOnly

false

SourceEditor.DEFAULTS.showAnnotationRuler

false

SourceEditor.DEFAULTS.showLineNumbers

false

SourceEditor.DEFAULTS.showOverviewRuler

false

SourceEditor.DEFAULTS.tabSize

4

SourceEditor.DEFAULTS.theme

SourceEditor.THEMES.MOZILLA

SourceEditor.DEFAULTS.undoLimit

200

Event name constants

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

Parameters

aLineIndex

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

aConditionOptional

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.

canUndo()

Parameters

Return value

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

aStringOptional

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

getCharCount()

Parameters

Return value

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.

Parameters

aLineIndex

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

aIncludeDelimiterOptional

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:

Parameters

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.

aAlignOptional

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.

Parameters

aString

The text to put into the editor.

aStartOptional

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

aEndOptional

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:

A reference to the context menu to display when the user right-clicks in the editor. This may be either a string providing the ID of a XUL menupopup or an Element object of type menupopup. See XXXXX for details on how to work with the context menu.

expandTab

Boolean

A Boolean value indicating whether or not tab characters should be expanded out to spaces. This value is overridden by the user preference named by SourceEditor.PREFS.EXPAND_TAB.

highlightCurrentLine

Boolean

A Boolean value indicating whether or not to highlight the line on which the text caret is currently located.

ContextMenu

The X-coordinate at which the mouse cursor was located when the context menu was invoked. This value is relative to the document being edited; that is, 0 is the top of the very first line of text in the document, regardless of vertical scroll position.

The Y-coordinate at which the mouse cursor was located when the context menu was invoked. This value is relative to the document being edited; that is, 0 is the left edge of the document, regardless of horizontal scroll position.

An array of breakpoint objects representing all of the breakpoints that have been removed; see Breakpoint objects for details.

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:

Property

Type

Description

oldValue

Boolean

The previous state of the dirty flag.

newValue

Boolean

The new state of the dirty flag.

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.