source-editor.jsm 编辑

This component has been removed from the platform in Firefox 28.

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.

Method overview

Initialization and destruction

void destroy();

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

Search operations

Number find(String aString, [optional] Object options);

Number findNext(Boolean aWrap);

Number findPrevious(Boolean aWrap);

Event management

void addEventListener(String aEventType, Function aCallback);

void removeEventListener(StringaEventType,FunctionaCallback);

Undo stack operations

Boolean canRedo();

Boolean canUndo();

void endCompoundChange();

Boolean redo();

void resetUndo();

void startCompoundChange();

Boolean undo();

Display management operations

void focus();

NumbergetTopIndex();

Boolean hasFocus();

void setTopIndex(Number aTopIndex);

Content management operations

NumbergetCharCount();

StringgetIndentationString();

StringgetLineDelimiter();

NumbergetLineCount();

NumbergetLineEnd(NumberaLineIndex, Boolean aIncludeDelimiter);

NumbergetLineStart(NumberaLineIndex);

StringgetMode();

StringgetText([optional]NumberaStart, [optional]NumberaEnd);

StringgetSelectedText();

void setMode(StringaMode);

void setText(StringaText, [optional]NumberaStart, [optional]NumberaEnd);

Selection operations

void dropSelection();

NumbergetCaretOffset();

ObjectgetCaretPosition();

ObjectgetSelection();

void setCaretOffset(NumberaOffset);

void setCaretPosition(NumberaLine, [optional]NumberaColumn, [optional]NumberaAlign);

void setSelection(NumberaStart,NumberaEnd);

Breakpoint management

void addBreakpoint(NumberaLineIndex, [optional]StringaCondition);

Array getBreakpoints();

Boolean removeBreakpoint(NumberaLineIndex);

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.
editorElement	Element	The element containing the editor. When using the default Orion editor, this is a XUL <xul:iframe> element. Read only.
lastFind	Object	An object describing the result of the last find operation performed using the find(), findNext(), or findPrevious() method. Read only. This object has the following properties: Property Type Description str String The last string that was searched for. index Number An integer value indicating the result of the most recent find operation; this is the index into the text at which str was found, or -1 if the string wasn't found. lastFound Number 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.

Constant	Value	Description
SourceEditor.EVENTS.BLUR	"Blur"	Fired when the editor loses focus.
SourceEditor.EVENTS.BREAKPOINT_CHANGE	"BreakpointChange"	Fired when a new breakpoint is added, or when an existing breakpoint is removed. This happens both when the API is used to make the change or when the UI is used to do it.
SourceEditor.EVENTS.CONTEXT_MENU	"ContextMenu"	Fired when the editor's context menu is invoked, but before it's opened.
SourceEditor.EVENTS.DIRTY_CHANGED	"DirtyChanged"	Fired when the dirty state of the editor is changed. The dirty state indicates whether or not there are unsaved changes to the text.
SourceEditor.EVENTS.FOCUS	"Focus"	Fired when the editor gains focus.
SourceEditor.EVENTS.MOUSE_MOVE	"MouseMove"	Fired when the user moves the mouse over a line annotation.
SourceEditor.EVENTS.MOUSE_OUT	"MouseOut"	Fired when the mouse pointer leaves a line annotation.
SourceEditor.EVENTS.MOUSE_OVER	"MouseOver"	Fired when the mouse pointer enters a line annotation.
SourceEditor.EVENTS.SELECTION	"Selection"	Fired when the current selection in the editor changes.
SourceEditor.EVENTS.TEXT_CHANGED	"TextChanged"	Fired when the editor's content changes.

Methods

addBreakpoint

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

Note: Implementing actual support for debugger features such as breakpoints is up to you. The editor simply tracks their existence and marks them with annotations in the editor.

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:

Property	Type	Description
backwards	Boolean	If true, the search begins at start (or the end of the text, if start is not specified) and progresses toward the beginning of the text. Otherwise the search progresses forward. The default is false.
ignoreCase	Boolean	If true, the search is performed in a case-insensitive manner; otherwise case is considered. The default is false.
start	Number	An integer value indicating the offset into the text at which to begin the find operation. The default is 0 if backwards is false, or text.length if backwards is true.

findNext()

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

Note: This ignores the value you specified for backwards in the original search; it always searches forward.

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().

Note: This ignores the value you specified for backwards in the original search; it always searches backward.

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:

Property	Type	Description
line	Number	The 0-based line number on which the breakpoint is set.
condition	String	The condition string that was specified when the breakpoint was set.

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:

Property	Type	Description
line	Number	The 0-based line number on which the caret is located.
col	Number	The 0-based column number on which the caret is located.

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:

Property	Type	Description
start	Number	0-based offset to the first character in the current selection.
end	Number	0-based offset to the end of the current selection. The character at this offset is not included in the selection; it's essentially the first character after the selection.

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:

Constant	Type	Description
contextMenu	String | Element	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 <xul:menupopup> or an Element object of type <xul: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.
initialText	String	The default initial text to be in the editor when it's created. By default, this is the empty string, indicating there should be no text on startup.
keys	Array	An array of objects defining custom keyboard bindings. See XXXXX for details.
mode	String	A string indicating the default syntax highlighting mode; by default, the content is assumed to be plain text. See Editor mode constants for permitted values.
placeholderText	String	The default initial text to be in the editor when it's created; by default, an empty string. This is deprecated starting in Firefox 13; use initialText instead. Deprecated since Gecko 13.0
readOnly	Boolean	A Boolean value indicating whether or not the source editor should be read only.
showAnnotationRuler	Boolean	A Boolean value indicating whether or not to display the annotations gutter/ruler. See XXXXX for details.
showLineNumbers	Boolean	A Boolean value indicating whether or not the line numbers gutter should be displayed.
showOverviewRuler	Boolean	A Boolean value indicating whether or not to show the overview gutter/ruler. This presents an overview of the current annotations in the editor, such as the breakpoints.
tabSize	Number	A number indicating how many spaces each tab character should occupy. This default can be overridden by the user preference named by SourceEditor.PREFS.TAB_SIZE.
theme	String	A string indicating the default syntax highlighting theme to use; you may use one of the predefined values listed in Theme constants, or you may provide your own CSS file reference.
undoLimit	Number	A number indicating how many steps the undo stack should hold.

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.

Property	Type	Description
x	Number	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.
y	Number	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.
screenX	Number	The X-coordinate at which the mouse cursor was located when the context menu was invoked, relative to the screen. This value comes from the DOM contextmenu's event.screenX property.
screenY	Number	The Y-coordinate at which the mouse cursor was located when the context menu was invoked, relative to the screen. This value comes from the DOM contextmenu's event.screenY property.

TextChanged

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

Property	Type	Description
start	Number	The character offset into the document at which the change occurred.
removedCharCount	Number	The number of characters removed from the document.
addCharCount	Number	The number of characters added to the document.

Selection

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

Property	Type	Description
oldValue	Object	The previously-selected range of text.
newValue	Object	The newly-selected range of text.

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:

Property	Type	Description
event	MouseEvent	The DOM "mousemove" event.
x	Number	The X-coordinate of the mouse pointer 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..
y	Number	The Y-coordinate of the mouse pointer relative to the document being edited; that is, 0 is the left edge of the very first column of text in the document, regardless of horizontal scroll position.

MouseOver

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

Property	Type	Description
event	MouseEvent	The DOM "mouseover" event.
x	Number	The X-coordinate of the mouse pointer 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.
y	Number	The Y-coordinate of the mouse pointer relative to the document being edited; that is, 0 is the left edge of the very first column of text in the document, regardless of horizontal scroll position.

MouseOut

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

Property	Type	Description
event	MouseEvent	The DOM "mouseout" event.
x	Number	The X-coordinate of the mouse pointer 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..
y	Number	The Y-coordinate of the mouse pointer relative to the document being edited; that is, 0 is the left edge of the very first column of text in the document, regardless of horizontal scroll position.

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:

Property	Type	Description
added	Array	An array of breakpoint objects representing all of the breakpoints that have been added; see Breakpoint objects for details.
removed	Array	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.