Revision 653921 of Editor

<p id="The_Editor_is_a_code-editor_component_that_can_be_embedded_in_your_addons._All_existing_Firefox_Developer_Tools_currently_use_this_component._Under_the_hood.2C_the_Editor_component_is_a_thin_wrapper_around_the_CodeMirror_open_source_editor.">The Editor is a code-editor component that can be embedded in your addons. All existing Firefox Developer Tools currently use this component. Under the hood, the Editor component is a thin wrapper around the <a href="https://codemirror.net/">CodeMirror</a> open source editor.</p>
<h2 id="Basic_Usage">Basic Usage</h2>
<p>The easiest way to use the component is to import the module, create an instance of the Editor object and use its <em>appendTo</em> method to attach the editor instance to a DOM node.</p>
<pre class="brush: js">
let Editor = require("devtools/sourceeditor/editor");
let editor = new Editor();
editor.appendTo(parentNode);</pre>
<p>The code above creates a new editor instance and attaches it to the DOM node references by the <em>parentNode</em> variable. (<strong>IMPORTANT:</strong> <em>parentNode</em> should be an element that can act as a parent.) When creating a new instance, you can pass a configuration object as an optional parameter.</p>
<pre class="brush: js">
let editor = new Editor({
  value: "// hello",
  mode: Editor.modes.js,
  lineNumbers: true
});</pre>
<p>This configuration object can hold same properties as <a href="https://codemirror.net/doc/manual.html#config">CodeMirror's configuration object</a>. The only difference is the 'mode' property. Currently, it supports these syntax highlighting modes:</p>
<ul>
 <li><em>Editor.modes.text</em> for plain text.</li>
 <li><em>Editor.modes.js</em> for JavaScript (including ES6)</li>
 <li><em>Editor.modes.css</em> for CSS</li>
 <li><em>Editor.modes.html</em> for HTML (including embedded CSS and JS)</li>
 <li><em>Editor.modes.vs</em> and <em>Editor.modes.fs</em> for WebGL shaders (x-vertex and x-fragment respectively)</li>
</ul>
<h2 id="API">API</h2>
<p>Since our Editor is a thin wrapper around CodeMirror it exposes some CodeMirror methods as-is. For more information refer to the <a href="https://codemirror.net/doc/manual.html">CodeMirror documentation page</a>. The rest of this page assumes that you're familiar with CodeMirror and its concepts. The following methods are identical to the ones provided by CodeMirror:</p>
<ul>
 <li><code>focus()</code></li>
 <li><code>hasFocus() → boolean</code></li>
 <li><code>lineCount() → integer</code></li>
 <li><code>somethingSelected() → boolean</code></li>
 <li><code>getCursor(?start: string) → {line, ch}</code></li>
 <li><code>setSelection(anchor: {line, ch}, ?head: {line, ch})</code></li>
 <li><code>getSelection() → string</code></li>
 <li><code>replaceSelection(replacement: string, ?collapse: string)</code></li>
 <li><code>extendSelection(from: {line, ch}, ?to: {line, ch})</code></li>
 <li><code>undo()</code></li>
 <li><code>redo()</code></li>
 <li><code>clearHistory()</code></li>
 <li><code>openDialog(template: element, callback: function, ?options:object)</code></li>
 <li><code>refresh()</code></li>
 <li><code>setOption(option: string, value: any)</code></li>
 <li><code>getOption(option: string) → any</code></li>
</ul>
<p>These methods either don't exist in CodeMirror or behave differently:</p>
<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Description</th>
   <th scope="col">Status</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>appendTo(el: element, ?env: iframe) → promise</code><br />
    Appends the current <em>Editor</em> instance to the element specified by <em>el</em>. You can also provide your own iframe to host the editor as an optional second parameter (otherwise, <em>Editor</em> will create a new iframe).</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>getMode() <code>→</code> object</code><br />
    Returns the current active syntax mode. See above for the list of all supported modes.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>setMode(mode: object)</code><br />
    Sets the syntax mode. See above for the list of all supported modes.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>getText(?line: number) → string</code><br />
    Returns the current editor's content. If line argument is provided, the method returns only that line.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>setText(value: string)</code><br />
    Replaces the text content of the editor with the provided <em>value</em>.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>replaceText(value: string, ?from:{ch, line}, ?to:{ch, line})</code><br />
    Replaces the editor's content within the specified <em>from</em>/<em>to</em> range with the provided <em>value</em>. If neither <em>from</em> nor <em>to</em> arguments are provided, then this method works exactly like setText. If only <em>from</em> object is provided, inserts text at that point, <strong>overwriting</strong> as many characters as needed.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>insertText(value: string, at: {ch, line})</code><br />
    Inserts text at the specified <em>at</em> position, shifting existing contents as necessary.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>dropSelection()</code><br />
    Deselects the current editor content.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>getFirstVisibleLine() → number</code><br />
    Returns the line number of the first visible line.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>setFirstVisibleLine(line: number)</code><br />
    Scrolls the editor's contents such that the given <em>line</em> is the first visible line at the top of the editor.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>setCursor(pos: {line, ch}, align: string)</code><br />
    Sets the cursor to the specified <em>{line, ch}</em> position with an additional option to align the line at the "top", "center" or "bottom" of the editor with "top" being the default value.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>alignLine(line: number, align: string)</code><br />
    Aligns the provided line to either "top", "center" or "bottom" of the editor view with a maximum margin of three lines from top or bottom.</td>
   <td><span style="color: #ff8c00;">Unstable</span></td>
  </tr>
  <tr>
   <td><code>hasMarker(line: number, gutterName: string, markerClass: string) → boolean</code><br />
    Returns whether a marker of a specified class exists in a line's gutter.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>addMarker(line: number, gutterName: string, markerClass: string)</code><br />
    Adds a marker with a specified class to a line's gutter. If another marker exists on that line, the new marker class is added to its class list.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>removeMarker(line: number, gutterName: string, markerClass: string)</code><br />
    Removes a marker of a specified class from a line's gutter.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>removeAllMarkers(gutterName: string)</code><br />
    Removes all gutter markers in the gutter with the given name.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>setMarkerListeners(line: number, gutterName: string, markerClass: string, events: object, data: object)</code><br />
    Handles attaching a set of events listeners on a marker. They should be passed as an object literal with keys as event names and values as function listeners. The line number, marker node and optional data will be passed as arguments to the function listener. You don't need to worry about removing these event listeners. They're automatically orphaned when clearing markers.</td>
   <td><span style="color: #ff8c00;">Unstable</span></td>
  </tr>
  <tr>
   <td><code>hasLineClass(line: number, className: string) → boolean</code><br />
    Returns whether a line is decorated using the specified class name.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>addLineClass(line: number, className: string)</code><br />
    Sets a CSS class name for the given <em>line</em>, including the text and gutter.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>removeLineClass(line: number, className: string)</code><br />
    Removes a CSS class name for the given <em>line</em>.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>markText(from: {line,ch}, to: {line,ch}, className: string) → { anchor: element, clear: function }</code><br />
    Marks a range of text inside the two <em>{line, ch}</em> bounds. Since the range may be modified, for example, when typing text, this method returns a function that can be used to remove the mark.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>getPosition(index: number|list) → {line, ch}|list</code><br />
    Calculates and returns one or more <em>{line, ch}</em> objects for a zero-based index who's value is relative to the start of the editor's text. If only one argument is given, this method returns a single <em>{line, ch}</em> object. Otherwise it returns an array.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>getOffset(pos: {line, ch}|list) → number|list</code><br />
    The reverse of <em>getPosition</em>. Similarly to <em>getPosition</em> this method returns a single value only if one argument was given, and an array otherwise.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>getPositionFromCoords(coord: {left, top}) → {line, ch}</code><br />
    Returns a <em>{line, ch}</em> object that corresponds to the <em>left</em> and <em>top</em> coordinates.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>getCoordsFromPosition(pos: {line, ch}) → {left, top}</code><br />
    The reverse of <em>getPositionFromCoords</em>. Similarly, returns a <em>{left, top}</em> object that corresponds to the specified line and character number.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>canUndo() → boolean</code><br />
    Returns true if there's something to undo and false otherwise.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>canRedo() → boolean</code><br />
    Returns true if there's something to redo and false otherwise.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>setClean() → number</code><br />
    Marks the contents as clean and returns the current version number.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>isClean() → boolean</code><br />
    Returns true if contents of the text area are clean i.e. no changes were made since the last version.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>jumpToLine()</code><br />
    Opens an in-editor dialog asking for a line to jump to. Once given, it changes cursor to that line.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>moveLineUp()</code><br />
    Moves the content of the current line or the lines selected up a line.</td>
   <td><span style="color: #ff8c00;">Unstable</span></td>
  </tr>
  <tr>
   <td><code>moveLineDown()</code><br />
    Moves the content of the current line or the lines selected down a line.</td>
   <td><span style="color: #ff8c00;">Unstable</span></td>
  </tr>
  <tr>
   <td>
    <p><code>extend(funcs: object)</code><br />
     Extends an instance of the Editor object with additional functions. Each function will be called with conext as the first argument. Context is a {ed, cm} object where 'ed' is an instance of the Editor object and 'cm' is an instance of the CodeMirror object. Example:</p>
    <pre class="brush: js">
function hello(ctx, name) {
  let { cm, ed } = ctx;
  cm; // CodeMirror instance
  ed; // Editor instance
  name; // "Mozilla"
}

editor.extend({ hello: hello });
editor.hello("Mozilla");</pre>
    This is the recommended way to write Editor extensions.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>destroy()</code><br />
    Cleans up all the references and emits a 'destroy' event.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
 </tbody>
</table>
<h3 id="Static_Methods">Static Methods</h3>
<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Description</th>
   <th scope="col">Status</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>Editor.accel(key: string, ?modifiers:object) → string</code><br />
    Returns a string representation of a shortcut <em>key</em> with an OS specific modfiier. Cmd- for Macs, Ctrl- for other platforms. You can also toggle Shift- and Alt- modifiers by passing the <em>modifiers</em> object. Examples:<br />
    <br />
    <pre class="brush: js">
// Assuming Mac platform
Editor.accel("F"); // Cmd-F
Editor.accel("F", { shift: true }); // Shift-Cmd-F
Editor.accel("F", { alt: true }); // Cmd-Alt-F</pre>
   </td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
  <tr>
   <td><code>Editor.keyFor(cmd: string) → string</code><br />
    Returns a localized string representation of a shortcut for a command specified by <em>cmd</em> and defined in <a href="https://dxr.mozilla.org/mozilla-central/source/browser/locales/en-US/chrome/browser/devtools/sourceeditor.properties">sourceeditor.properties</a>.</td>
   <td><span style="color: #008000;">Stable</span></td>
  </tr>
 </tbody>
</table>
<h2 id="Addons">Addons</h2>
<p>We include a few <a href="https://codemirror.net/addon/">CodeMirror addons</a> with our distribution. To use them all you need to do is enable the following configuration options:</p>
<ul>
 <li><code>styleActiveLine</code>: highlights the currently active line <em>(<span style="color: #008000;">on</span> by default)</em></li>
 <li><code>autoCloseBrackets</code>: automatically adds a closing bracket <em>(<span style="color: #008000;">on</span> by default)</em></li>
 <li><code>matchBrackets</code>: highlights matching brackets <em>(<span style="color: #008000;">on</span> by default)</em></li>
 <li><code>showTrailingSpace</code>: highlights trailing spaces <em>(<span style="color: #ff8c00;">off</span> by default)</em></li>
 <li><code>enableCodeFolding</code>: enables code folding <em>(<span style="color: #ff8c00;">off</span> by default)</em></li>
</ul>
<h2 id="Keymaps">Keymaps</h2>
<p>We also include three additional keymaps, for VIM, Emacs, and Sublime Text modes. To enable them, set the <em>keyMap</em> configuration option to either <em>emacs</em>, <em>vim</em>, or <em>sublime</em>. In addition to that, the default keymap can be controlled by the <code>devtools.editor.keymap</code> option in <a href="/about:config">about:config</a>.</p>
<h2 id="Feedback">Feedback</h2>
<p>For feedback please use <a href="https://lists.mozilla.org/listinfo/dev-developer-tools">Developer Tools mailing list</a>. And if you think you found a bug, <a href="https://bugzilla.mozilla.org/enter_bug.cgi?alias=&amp;assigned_to=nobody%40mozilla.org&amp;attach_text=&amp;blocked=&amp;bug_file_loc=http%3A%2F%2F&amp;bug_ignored=0&amp;bug_severity=normal&amp;bug_status=NEW&amp;cf_blocking_b2g=---&amp;cf_crash_signature=&amp;cf_status_b2g18=---&amp;cf_status_b2g_1_1_hd=---&amp;cf_status_b2g_1_2=---&amp;cf_status_b2g_1_3=---&amp;cf_status_b2g_1_4=---&amp;cf_status_firefox26=---&amp;cf_status_firefox27=---&amp;cf_status_firefox28=---&amp;cf_status_firefox29=---&amp;cf_status_firefox_esr24=---&amp;cf_tracking_b2g18=---&amp;cf_tracking_firefox26=---&amp;cf_tracking_firefox27=---&amp;cf_tracking_firefox28=---&amp;cf_tracking_firefox29=---&amp;cf_tracking_firefox_esr24=---&amp;cf_tracking_firefox_relnote=---&amp;cf_tracking_relnote_b2g=---&amp;comment=&amp;component=Developer%20Tools%3A%20Source%20Editor&amp;contenttypeentry=&amp;contenttypemethod=autodetect&amp;contenttypeselection=text%2Fplain&amp;data=&amp;defined_groups=1&amp;dependson=&amp;description=&amp;flag_type-203=X&amp;flag_type-37=X&amp;flag_type-41=X&amp;flag_type-5=X&amp;flag_type-607=X&amp;flag_type-720=X&amp;flag_type-721=X&amp;flag_type-737=X&amp;flag_type-748=X&amp;flag_type-781=X&amp;flag_type-787=X&amp;flag_type-791=X&amp;flag_type-799=X&amp;flag_type-800=X&amp;flag_type-803=X&amp;flag_type-809=X&amp;flag_type-825=X&amp;flag_type-834=X&amp;flag_type-835=X&amp;flag_type-836=X&amp;flag_type-842=X&amp;form_name=enter_bug&amp;keywords=&amp;maketemplate=Remember%20values%20as%20bookmarkable%20template&amp;op_sys=Mac%20OS%20X&amp;priority=P3&amp;product=Firefox&amp;qa_contact=&amp;rep_platform=x86&amp;requestee_type-203=&amp;requestee_type-41=&amp;requestee_type-5=&amp;requestee_type-607=&amp;requestee_type-748=&amp;requestee_type-781=&amp;requestee_type-787=&amp;requestee_type-791=&amp;requestee_type-800=&amp;short_desc=&amp;status_whiteboard=&amp;target_milestone=---&amp;version=Trunk">let us know about it</a>.</p>