1494 lines
77 KiB
HTML
1494 lines
77 KiB
HTML
<!doctype html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8"/>
|
|
<title>CodeMirror: User Manual</title>
|
|
<link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Droid+Sans|Droid+Sans:bold"/>
|
|
<link rel="stylesheet" type="text/css" href="docs.css"/>
|
|
<style>dl dl {margin: 0;}</style>
|
|
<script src="../lib/codemirror.js"></script>
|
|
<link rel="stylesheet" href="../lib/codemirror.css">
|
|
<script src="../lib/util/runmode.js"></script>
|
|
<script src="../lib/util/colorize.js"></script>
|
|
<script src="../mode/javascript/javascript.js"></script>
|
|
<script src="../mode/xml/xml.js"></script>
|
|
<script src="../mode/css/css.js"></script>
|
|
<script src="../mode/htmlmixed/htmlmixed.js"></script>
|
|
</head>
|
|
<body>
|
|
|
|
<h1><span class="logo-braces">{ }</span> <a href="http://codemirror.net/">CodeMirror</a></h1>
|
|
|
|
<div class="grey">
|
|
<img src="baboon.png" class="logo" alt="logo"/>
|
|
<pre>
|
|
/* User manual and
|
|
reference guide */
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="clear"><div class="leftbig blk">
|
|
|
|
<h2 id="overview">Overview</h2>
|
|
|
|
<p>CodeMirror is a code-editor component that can be embedded in
|
|
Web pages. The core library provides <em>only</em> the editor
|
|
component, no accompanying buttons, auto-completion, or other IDE
|
|
functionality. It does provide a rich API on top of which such
|
|
functionality can be straightforwardly implemented. See
|
|
the <a href="#addons">add-ons</a> included in the distribution,
|
|
and
|
|
the <a href="https://github.com/jagthedrummer/codemirror-ui">CodeMirror
|
|
UI</a> project, for reusable implementations of extra features.</p>
|
|
|
|
<p>CodeMirror works with language-specific modes. Modes are
|
|
JavaScript programs that help color (and optionally indent) text
|
|
written in a given language. The distribution comes with a number
|
|
of modes (see the <a href="../mode/"><code>mode/</code></a>
|
|
directory), and it isn't hard to <a href="#modeapi">write new
|
|
ones</a> for other languages.</p>
|
|
|
|
<h2 id="usage">Basic Usage</h2>
|
|
|
|
<p>The easiest way to use CodeMirror is to simply load the script
|
|
and style sheet found under <code>lib/</code> in the distribution,
|
|
plus a mode script from one of the <code>mode/</code> directories.
|
|
(See <a href="compress.html">the compression helper</a> for an
|
|
easy way to combine scripts.) For example:</p>
|
|
|
|
<pre data-lang="text/html"><script src="lib/codemirror.js"></script>
|
|
<link rel="stylesheet" href="../lib/codemirror.css">
|
|
<script src="mode/javascript/javascript.js"></script></pre>
|
|
|
|
<p>Having done this, an editor instance can be created like
|
|
this:</p>
|
|
|
|
<pre data-lang="javascript">var myCodeMirror = CodeMirror(document.body);</pre>
|
|
|
|
<p>The editor will be appended to the document body, will start
|
|
empty, and will use the mode that we loaded. To have more control
|
|
over the new editor, a configuration object can be passed
|
|
to <code>CodeMirror</code> as a second argument:</p>
|
|
|
|
<pre data-lang="javascript">var myCodeMirror = CodeMirror(document.body, {
|
|
value: "function myScript(){return 100;}\n",
|
|
mode: "javascript"
|
|
});</pre>
|
|
|
|
<p>This will initialize the editor with a piece of code already in
|
|
it, and explicitly tell it to use the JavaScript mode (which is
|
|
useful when multiple modes are loaded).
|
|
See <a href="#config">below</a> for a full discussion of the
|
|
configuration options that CodeMirror accepts.</p>
|
|
|
|
<p>In cases where you don't want to append the editor to an
|
|
element, and need more control over the way it is inserted, the
|
|
first argument to the <code>CodeMirror</code> function can also
|
|
be a function that, when given a DOM element, inserts it into the
|
|
document somewhere. This could be used to, for example, replace a
|
|
textarea with a real editor:</p>
|
|
|
|
<pre data-lang="javascript">var myCodeMirror = CodeMirror(function(elt) {
|
|
myTextArea.parentNode.replaceChild(elt, myTextArea);
|
|
}, {value: myTextArea.value});</pre>
|
|
|
|
<p>However, for this use case, which is a common way to use
|
|
CodeMirror, the library provides a much more powerful
|
|
shortcut:</p>
|
|
|
|
<pre data-lang="javascript">var myCodeMirror = CodeMirror.fromTextArea(myTextArea);</pre>
|
|
|
|
<p>This will, among other things, ensure that the textarea's value
|
|
is updated with the editor's contents when the form (if it is part
|
|
of a form) is submitted. See the <a href="#fromTextArea">API
|
|
reference</a> for a full description of this method.</p>
|
|
|
|
<h2 id="config">Configuration</h2>
|
|
|
|
<p>Both the <code>CodeMirror</code> function and
|
|
its <code>fromTextArea</code> method take as second (optional)
|
|
argument an object containing configuration options. Any option
|
|
not supplied like this will be taken
|
|
from <code>CodeMirror.defaults</code>, an object containing the
|
|
default options. You can update this object to change the defaults
|
|
on your page.</p>
|
|
|
|
<p>Options are not checked in any way, so setting bogus option
|
|
values is bound to lead to odd errors.</p>
|
|
|
|
<p>These are the supported options:</p>
|
|
|
|
<dl>
|
|
<dt id="option_value"><code>value (string)</code></dt>
|
|
<dd>The starting value of the editor.</dd>
|
|
|
|
<dt id="option_mode"><code>mode (string or object)</code></dt>
|
|
<dd>The mode to use. When not given, this will default to the
|
|
first mode that was loaded. It may be a string, which either
|
|
simply names the mode or is
|
|
a <a href="http://en.wikipedia.org/wiki/MIME">MIME</a> type
|
|
associated with the mode. Alternatively, it may be an object
|
|
containing configuration options for the mode, with
|
|
a <code>name</code> property that names the mode (for
|
|
example <code>{name: "javascript", json: true}</code>). The demo
|
|
pages for each mode contain information about what configuration
|
|
parameters the mode supports. You can ask CodeMirror which modes
|
|
and MIME types have been defined by inspecting
|
|
the <code>CodeMirror.modes</code>
|
|
and <code>CodeMirror.mimeModes</code> objects. The first maps
|
|
mode names to their constructors, and the second maps MIME types
|
|
to mode specs.</dd>
|
|
|
|
<dt id="option_theme"><code>theme (string)</code></dt>
|
|
<dd>The theme to style the editor with. You must make sure the
|
|
CSS file defining the corresponding <code>.cm-s-[name]</code>
|
|
styles is loaded (see
|
|
the <a href="../theme/"><code>theme</code></a> directory in the
|
|
distribution). The default is <code>"default"</code>, for which
|
|
colors are included in <code>codemirror.css</code>. It is
|
|
possible to use multiple theming classes at once—for
|
|
example <code>"foo bar"</code> will assign both
|
|
the <code>cm-s-foo</code> and the <code>cm-s-bar</code> classes
|
|
to the editor.</dd>
|
|
|
|
<dt id="option_indentUnit"><code>indentUnit (integer)</code></dt>
|
|
<dd>How many spaces a block (whatever that means in the edited
|
|
language) should be indented. The default is 2.</dd>
|
|
|
|
<dt id="option_smartIndent"><code>smartIndent (boolean)</code></dt>
|
|
<dd>Whether to use the context-sensitive indentation that the
|
|
mode provides (or just indent the same as the line before).
|
|
Defaults to true.</dd>
|
|
|
|
<dt id="option_tabSize"><code>tabSize (integer)</code></dt>
|
|
<dd>The width of a tab character. Defaults to 4.</dd>
|
|
|
|
<dt id="option_indentWithTabs"><code>indentWithTabs (boolean)</code></dt>
|
|
<dd>Whether, when indenting, the first N*<code>tabSize</code>
|
|
spaces should be replaced by N tabs. Default is false.</dd>
|
|
|
|
<dt id="option_electricChars"><code>electricChars (boolean)</code></dt>
|
|
<dd>Configures whether the editor should re-indent the current
|
|
line when a character is typed that might change its proper
|
|
indentation (only works if the mode supports indentation).
|
|
Default is true.</dd>
|
|
|
|
<dt id="option_rtlMoveVisually"><code>rtlMoveVisually (boolean)</code></dt>
|
|
<dd>Determines whether horizontal cursor movement through
|
|
right-to-left (Arabic, Hebrew) text is visual (pressing the left
|
|
arrow moves the cursor left) or logical (pressing the left arrow
|
|
moves to the next lower index in the string, which is visually
|
|
right in right-to-left text). The default is <code>false</code>
|
|
on Windows, and <code>true</code> on other platforms.</dd>
|
|
|
|
<dt id="option_keyMap"><code>keyMap (string)</code></dt>
|
|
<dd>Configures the keymap to use. The default
|
|
is <code>"default"</code>, which is the only keymap defined
|
|
in <code>codemirror.js</code> itself. Extra keymaps are found in
|
|
the <a href="../keymap/"><code>keymap</code></a> directory. See
|
|
the <a href="#keymaps">section on keymaps</a> for more
|
|
information.</dd>
|
|
|
|
<dt id="option_extraKeys"><code>extraKeys (object)</code></dt>
|
|
<dd>Can be used to specify extra keybindings for the editor,
|
|
alongside the ones defined
|
|
by <a href="#option_keyMap"><code>keyMap</code></a>. Should be
|
|
either null, or a valid <a href="#keymaps">keymap</a> value.</dd>
|
|
|
|
<dt id="option_lineWrapping"><code>lineWrapping (boolean)</code></dt>
|
|
<dd>Whether CodeMirror should scroll or wrap for long lines.
|
|
Defaults to <code>false</code> (scroll).</dd>
|
|
|
|
<dt id="option_lineNumbers"><code>lineNumbers (boolean)</code></dt>
|
|
<dd>Whether to show line numbers to the left of the editor.</dd>
|
|
|
|
<dt id="option_firstLineNumber"><code>firstLineNumber (integer)</code></dt>
|
|
<dd>At which number to start counting lines. Default is 1.</dd>
|
|
|
|
<dt id="option_lineNumberFormatter"><code>lineNumberFormatter (function)</code></dt>
|
|
<dd>A function used to format line numbers. The function is
|
|
passed the line number, and should return a string that will be
|
|
shown in the gutter.</dd>
|
|
|
|
<dt id="option_gutters"><code>gutters (array)</code></dt>
|
|
<dd>Can be used to add extra gutters (beyond or instead of the
|
|
line number gutter). Should be an array of CSS class names, each
|
|
of which defines a <code>width</code> (and optionally a
|
|
background), and which will be used to draw the background of
|
|
the gutters. <em>May</em> include
|
|
the <code>CodeMirror-linenumbers</code> class, in order to
|
|
explicitly set the position of the line number gutter (it will
|
|
default to be to the right of all other gutters). These class
|
|
names are the keys passed
|
|
to <a href="#setGutterMarker"><code>setGutterMarker</code></a>.</dd>
|
|
|
|
<dt id="option_readOnly"><code>readOnly (boolean)</code></dt>
|
|
<dd>This disables editing of the editor content by the user. If
|
|
the special value <code>"nocursor"</code> is given (instead of
|
|
simply <code>true</code>), focusing of the editor is also
|
|
disallowed.</dd>
|
|
|
|
<dt id="option_showCursorWhenSelecting"><code>showCursorWhenSelecting (boolean)</code></dt>
|
|
<dd>Whether the cursor should be drawn when a selection is
|
|
active. Defaults to false.</dd>
|
|
|
|
<dt id="option_undoDepth"><code>undoDepth (integer)</code></dt>
|
|
<dd>The maximum number of undo levels that the editor stores.
|
|
Defaults to 40.</dd>
|
|
|
|
<dt id="option_tabindex"><code>tabindex (integer)</code></dt>
|
|
<dd>The <a href="http://www.w3.org/TR/html401/interact/forms.html#adef-tabindex">tab
|
|
index</a> to assign to the editor. If not given, no tab index
|
|
will be assigned.</dd>
|
|
|
|
<dt id="option_autofocus"><code>autofocus (boolean)</code></dt>
|
|
<dd>Can be used to make CodeMirror focus itself on
|
|
initialization. Defaults to off.
|
|
When <a href="#fromTextArea"><code>fromTextArea</code></a> is
|
|
used, and no explicit value is given for this option, it will be
|
|
set to true when either the source textarea is focused, or it
|
|
has an <code>autofocus</code> attribute and no other element is
|
|
focused.</dd>
|
|
</dl>
|
|
|
|
<p>Below this a few more specialized, low-level options are
|
|
listed. These are only useful in very specific situations, you
|
|
might want to skip them the first time you read this manual.</p>
|
|
|
|
<dl>
|
|
<dt id="option_dragDrop"><code>dragDrop (boolean)</code></dt>
|
|
<dd>Controls whether drag-and-drop is enabled. On by default.</dd>
|
|
|
|
<dt id="option_onDragEvent"><code>onDragEvent (function)</code></dt>
|
|
<dd>When given, this will be called when the editor is handling
|
|
a <code>dragenter</code>, <code>dragover</code>,
|
|
or <code>drop</code> event. It will be passed the editor instance
|
|
and the event object as arguments. The callback can choose to
|
|
handle the event itself, in which case it should
|
|
return <code>true</code> to indicate that CodeMirror should not
|
|
do anything further.</dd>
|
|
|
|
<dt id="option_onKeyEvent"><code>onKeyEvent (function)</code></dt>
|
|
<dd>This provides a rather low-level hook into CodeMirror's key
|
|
handling. If provided, this function will be called on
|
|
every <code>keydown</code>, <code>keyup</code>,
|
|
and <code>keypress</code> event that CodeMirror captures. It
|
|
will be passed two arguments, the editor instance and the key
|
|
event. This key event is pretty much the raw key event, except
|
|
that a <code>stop()</code> method is always added to it. You
|
|
could feed it to, for example, <code>jQuery.Event</code> to
|
|
further normalize it.<br>This function can inspect the key
|
|
event, and handle it if it wants to. It may return true to tell
|
|
CodeMirror to ignore the event. Be wary that, on some browsers,
|
|
stopping a <code>keydown</code> does not stop
|
|
the <code>keypress</code> from firing, whereas on others it
|
|
does. If you respond to an event, you should probably inspect
|
|
its <code>type</code> property and only do something when it
|
|
is <code>keydown</code> (or <code>keypress</code> for actions
|
|
that need character data).</dd>
|
|
|
|
<dt id="option_cursorBlinkRate"><code>cursorBlinkRate (number)</code></dt>
|
|
<dd>Half-period in milliseconds used for cursor blinking. The default blink
|
|
rate is 530ms.</dd>
|
|
|
|
<dt id="option_cursorHeight"><code>cursorHeight (number)</code></dt>
|
|
<dd>Determines the height of the cursor. Default is 1, meaning
|
|
it spans the whole height of the line. For some fonts (and by
|
|
some tastes) a smaller height (for example <code>0.85</code>),
|
|
which causes the cursor to not reach all the way to the bottom
|
|
of the line, looks better</dd>
|
|
|
|
<dt id="option_workTime"><code>workTime, workDelay (number)</code></dt>
|
|
<dd>Highlighting is done by a pseudo background-thread that will
|
|
work for <code>workTime</code> milliseconds, and then use
|
|
timeout to sleep for <code>workDelay</code> milliseconds. The
|
|
defaults are 200 and 300, you can change these options to make
|
|
the highlighting more or less aggressive.</dd>
|
|
|
|
<dt id="option_pollInterval"><code>pollInterval (number)</code></dt>
|
|
<dd>Indicates how quickly CodeMirror should poll its input
|
|
textarea for changes (when focused). Most input is captured by
|
|
events, but some things, like IME input on some browsers, don't
|
|
generate events that allow CodeMirror to properly detect it.
|
|
Thus, it polls. Default is 100 milliseconds.</dd>
|
|
|
|
<dt id="option_flattenSpans"><code>flattenSpans (boolean)</code></dt>
|
|
<dd>By default, CodeMirror will combine adjacent tokens into a
|
|
single span if they have the same class. This will result in a
|
|
simpler DOM tree, and thus perform better. With some kinds of
|
|
styling (such as rounded corners), this will change the way the
|
|
document looks. You can set this option to false to disable this
|
|
behavior.</dd>
|
|
|
|
<dt id="option_viewportMargin"><code>viewportMargin (integer)</code></dt>
|
|
<dd>Specifies the amount of lines that are rendered above and
|
|
below the part of the document that's currently scrolled into
|
|
view. This affects the amount of updates needed when scrolling,
|
|
and the amount of work that such an update does. You should
|
|
usually leave it at its default, 100. Can be set
|
|
to <code>Infinity</code> to make sure the whole document is
|
|
always rendered, and thus the browser's text search works on it.
|
|
This <em>will</em> have bad effects on performance of big
|
|
documents.</dd>
|
|
</dl>
|
|
|
|
<h2 id="events">Events</h2>
|
|
|
|
<p>A CodeMirror instance emits a number of events, which allow
|
|
client code to react to various situations. These are registered
|
|
with the <a href="#on"><code>on</code></a> method (and
|
|
removed with the <a href="#off"><code>off</code></a>
|
|
method). These are the events that fire on the instance object.
|
|
The name of the event is followed by the arguments that will be
|
|
passed to the handler. The <code>instance</code> argument always
|
|
refers to the editor instance.</p>
|
|
|
|
<dl>
|
|
<dt id="event_change"><code>"change" (instance, changeObj)</code></dt>
|
|
<dd>Fires every time the content of the editor is changed.
|
|
The <code>changeObj</code> is a <code>{from, to, text,
|
|
next}</code> object containing information about the changes
|
|
that occurred as second argument. <code>from</code>
|
|
and <code>to</code> are the positions (in the pre-change
|
|
coordinate system) where the change started and ended (for
|
|
example, it might be <code>{ch:0, line:18}</code> if the
|
|
position is at the beginning of line #19). <code>text</code> is
|
|
an array of strings representing the text that replaced the
|
|
changed range (split by line). If multiple changes happened
|
|
during a single operation, the object will have
|
|
a <code>next</code> property pointing to another change object
|
|
(which may point to another, etc).</dd>
|
|
|
|
<dt id="event_cursorActivity"><code>"cursorActivity" (instance)</code></dt>
|
|
<dd>Will be fired when the cursor or selection moves, or any
|
|
change is made to the editor content.</dd>
|
|
|
|
<dt id="event_viewportChange"><code>"viewportChange" (instance, from, to)</code></dt>
|
|
<dd>Fires whenever the <a href="#getViewport">view port</a> of
|
|
the editor changes (due to scrolling, editing, or any other
|
|
factor). The <code>from</code> and <code>to</code> arguments
|
|
give the new start and end of the viewport.</dd>
|
|
|
|
<dt id="event_gutterClick"><code>"gutterClick" (instance, line, gutter, clickEvent)</code></dt>
|
|
<dd>Fires when the editor gutter (the line-number area) is
|
|
clicked. Will pass the editor instance as first argument, the
|
|
(zero-based) number of the line that was clicked as second
|
|
argument, the CSS class of the gutter that was clicked as third
|
|
argument, and the raw <code>mousedown</code> event object as
|
|
fourth argument.</dd>
|
|
|
|
<dt id="event_focus"><code>"focus", "blur" (instance)</code></dt>
|
|
<dd>These fire whenever the editor is focused or unfocused.</dd>
|
|
|
|
<dt id="event_scroll"><code>"scroll" (instance)</code></dt>
|
|
<dd>Fires when the editor is scrolled.</dd>
|
|
|
|
<dt id="event_update"><code>"update" (instance)</code></dt>
|
|
<dd>Will be fired whenever CodeMirror updates its DOM display.</dd>
|
|
</dl>
|
|
|
|
<p>It is also possible to <a href="#on">register</a> events
|
|
on other objects. Line handles (as returned by, for
|
|
example, <a href="#getLineHandle"><code>getLineHandle</code></a>)
|
|
can be listened on with <code>CodeMirror.on(handle, "delete",
|
|
myFunc)</code>. They support the following events:</p>
|
|
|
|
<dl>
|
|
<dt id="event_delete"><code>"delete" ()</code></dt>
|
|
<dd>Will be fired when the line object is deleted. A line object
|
|
is associated with the <em>start</em> of the line. Mostly useful
|
|
when you need to find out when your <a href="#setGutterMarker">gutter
|
|
markers</a> on a given line are removed.</dd>
|
|
<dt id="event_line_change"><code>"change" ()</code></dt>
|
|
<dd>Fires when the line's text content is changed in any way
|
|
(but the line is not deleted outright).</dd>
|
|
</dl>
|
|
|
|
<p>Marked range handles, as returned
|
|
by <a href="#markText"><code>markText</code></a>, emit the
|
|
following event:</p>
|
|
|
|
<dl>
|
|
<dt id="event_clear"><code>"clear" ()</code></dt>
|
|
<dd>Fired when the range is cleared, either through cursor
|
|
movement in combination
|
|
with <a href="#mark_clearOnEnter"><code>clearOnEnter</code></a>
|
|
or through a call to its <code>clear()</code> method. Will only
|
|
be fired once per handle. Note that deleting the range through
|
|
text editing does not fire this event, because an undo
|
|
action might bring the range back into existence.</dd>
|
|
</dl>
|
|
|
|
<h2 id="keymaps">Keymaps</h2>
|
|
|
|
<p>Keymaps are ways to associate keys with functionality. A keymap
|
|
is an object mapping strings that identify the keys to functions
|
|
that implement their functionality.</p>
|
|
|
|
<p>Keys are identified either by name or by character.
|
|
The <code>CodeMirror.keyNames</code> object defines names for
|
|
common keys and associates them with their key codes. Examples of
|
|
names defined here are <code>Enter</code>, <code>F5</code>,
|
|
and <code>Q</code>. These can be prefixed
|
|
with <code>Shift-</code>, <code>Cmd-</code>, <code>Ctrl-</code>,
|
|
and <code>Alt-</code> (in that order!) to specify a modifier. So
|
|
for example, <code>Shift-Ctrl-Space</code> would be a valid key
|
|
identifier.</p>
|
|
|
|
<p>Alternatively, a character can be specified directly by
|
|
surrounding it in single quotes, for example <code>'$'</code>
|
|
or <code>'q'</code>. Due to limitations in the way browsers fire
|
|
key events, these may not be prefixed with modifiers.</p>
|
|
|
|
<p>The <code>CodeMirror.keyMap</code> object associates keymaps
|
|
with names. User code and keymap definitions can assign extra
|
|
properties to this object. Anywhere where a keymap is expected, a
|
|
string can be given, which will be looked up in this object. It
|
|
also contains the <code>"default"</code> keymap holding the
|
|
default bindings.</p>
|
|
|
|
<p id="commands">The values of properties in keymaps can be either functions of
|
|
a single argument (the CodeMirror instance), strings, or
|
|
<code>false</code>. Such strings refer to properties of the
|
|
<code>CodeMirror.commands</code> object, which defines a number of
|
|
common commands that are used by the default keybindings, and maps
|
|
them to functions. If the property is set to <code>false</code>,
|
|
CodeMirror leaves handling of the key up to the browser. A key
|
|
handler function may throw <code>CodeMirror.Pass</code> to indicate
|
|
that it has decided not to handle the key, and other handlers (or
|
|
the default behavior) should be given a turn.</p>
|
|
|
|
<p>Keys mapped to command names that start with the
|
|
characters <code>"go"</code> (which should be used for
|
|
cursor-movement actions) will be fired even when an
|
|
extra <code>Shift</code> modifier is present (i.e. <code>"Up":
|
|
"goLineUp"</code> matches both up and shift-up). This is used to
|
|
easily implement shift-selection.</p>
|
|
|
|
<p>Keymaps can defer to each other by defining
|
|
a <code>fallthrough</code> property. This indicates that when a
|
|
key is not found in the map itself, one or more other maps should
|
|
be searched. It can hold either a single keymap or an array of
|
|
keymaps.</p>
|
|
|
|
<p>When a keymap contains a <code>nofallthrough</code> property
|
|
set to <code>true</code>, keys matched against that map will be
|
|
ignored if they don't match any of the bindings in the map (no
|
|
further child maps will be tried, and the default effect of
|
|
inserting a character will not occur).</p>
|
|
|
|
<h2 id="styling">Customized Styling</h2>
|
|
|
|
<p>Up to a certain extent, CodeMirror's look can be changed by
|
|
modifying style sheet files. The style sheets supplied by modes
|
|
simply provide the colors for that mode, and can be adapted in a
|
|
very straightforward way. To style the editor itself, it is
|
|
possible to alter or override the styles defined
|
|
in <a href="../lib/codemirror.css"><code>codemirror.css</code></a>.</p>
|
|
|
|
<p>Some care must be taken there, since a lot of the rules in this
|
|
file are necessary to have CodeMirror function properly. Adjusting
|
|
colors should be safe, of course, and with some care a lot of
|
|
other things can be changed as well. The CSS classes defined in
|
|
this file serve the following roles:</p>
|
|
|
|
<dl>
|
|
<dt id="class_CodeMirror"><code>CodeMirror</code></dt>
|
|
<dd>The outer element of the editor. This should be used for the
|
|
editor width, height, borders and positioning. Can also be used
|
|
to set styles that should hold for everything inside the editor
|
|
(such as font and font size), or to set a background.</dd>
|
|
|
|
<dt id="class_CodeMirror_scroll"><code>CodeMirror-scroll</code></dt>
|
|
<dd>Whether the editor scrolls (<code>overflow: auto</code> +
|
|
fixed height). By default, it does. Setting
|
|
the <code>CodeMirror</code> class to have <code>height:
|
|
auto</code> and giving this class <code>overflow-x: auto;
|
|
overflow-y: hidden;</code> will cause the editor
|
|
to <a href="../demo/resize.html">resize to fit its
|
|
content</a>.</dd>
|
|
|
|
<dt id="class_CodeMirror_focused"><code>CodeMirror-focused</code></dt>
|
|
<dd>Whenever the editor is focused, the top element gets this
|
|
class. This is used to hide the cursor and give the selection a
|
|
different color when the editor is not focused.</dd>
|
|
|
|
<dt id="class_CodeMirror_gutters"><code>CodeMirror-gutters</code></dt>
|
|
<dd>This is the backdrop for all gutters. Use it to set the
|
|
default gutter background color, and optionally add a border on
|
|
the right of the gutters.</dd>
|
|
|
|
<dt id="class_CodeMirror_linenumbers"><code>CodeMirror-linenumbers</code></dt>
|
|
<dd>Use this for giving a background or width to the line number
|
|
gutter.</dd>
|
|
|
|
<dt id="class_CodeMirror_linenumber"><code>CodeMirror-linenumber</code></dt>
|
|
<dd>Used to style the actual individual line numbers. These
|
|
won't be children of the <code>CodeMirror-linenumbers</code>
|
|
(plural) element, but rather will be absolutely positioned to
|
|
overlay it. Use this to set alignment and text properties for
|
|
the line numbers.</dd>
|
|
|
|
<dt id="class_CodeMirror_lines"><code>CodeMirror-lines</code></dt>
|
|
<dd>The visible lines. This is where you specify vertical
|
|
padding for the editor content.</dd>
|
|
|
|
<dt id="class_CodeMirror_cursor"><code>CodeMirror-cursor</code></dt>
|
|
<dd>The cursor is a block element that is absolutely positioned.
|
|
You can make it look whichever way you want.</dd>
|
|
|
|
<dt id="class_CodeMirror_selected"><code>CodeMirror-selected</code></dt>
|
|
<dd>The selection is represented by <code>span</code> elements
|
|
with this class.</dd>
|
|
|
|
<dt id="class_CodeMirror_matchingbracket"><code>CodeMirror-matchingbracket</code>,
|
|
<code>CodeMirror-nonmatchingbracket</code></dt>
|
|
<dd>These are used to style matched (or unmatched) brackets.</dd>
|
|
</dl>
|
|
|
|
<p>If your page's style sheets do funky things to
|
|
all <code>div</code> or <code>pre</code> elements (you probably
|
|
shouldn't do that), you'll have to define rules to cancel these
|
|
effects out again for elements under the <code>CodeMirror</code>
|
|
class.</p>
|
|
|
|
<p>Themes are also simply CSS files, which define colors for
|
|
various syntactic elements. See the files in
|
|
the <a href="../theme/"><code>theme</code></a> directory.</p>
|
|
|
|
<h2 id="api">Programming API</h2>
|
|
|
|
<p>A lot of CodeMirror features are only available through its
|
|
API. Thus, you need to write code (or
|
|
use <a href="#addons">add-ons</a>) if you want to expose them to
|
|
your users.</p>
|
|
|
|
<p>Whenever points in the document are represented, the API uses
|
|
objects with <code>line</code> and <code>ch</code> properties.
|
|
Both are zero-based. CodeMirror makes sure to 'clip' any positions
|
|
passed by client code so that they fit inside the document, so you
|
|
shouldn't worry too much about sanitizing your coordinates. If you
|
|
give <code>ch</code> a value of <code>null</code>, or don't
|
|
specify it, it will be replaced with the length of the specified
|
|
line.</p>
|
|
|
|
<dl>
|
|
<dt id="getValue"><code>getValue() → string</code></dt>
|
|
<dd>Get the current editor content. You can pass it an optional
|
|
argument to specify the string to be used to separate lines
|
|
(defaults to <code>"\n"</code>).</dd>
|
|
<dt id="setValue"><code>setValue(string)</code></dt>
|
|
<dd>Set the editor content.</dd>
|
|
|
|
<dt id="lineCount"><code>lineCount() → number</code></dt>
|
|
<dd>Get the number of lines in the editor.</dd>
|
|
|
|
<dt id="getRange"><code>getRange(from, to) → string</code></td>
|
|
<dd>Get the text between the given points in the editor, which
|
|
should be <code>{line, ch}</code> objects. An optional third
|
|
argument can be given to indicate the line separator string to
|
|
use (defaults to <code>"\n"</code>).</dd>
|
|
<dt id="replaceRange"><code>replaceRange(string, from, to)</code></dt>
|
|
<dd>Replace the part of the document between <code>from</code>
|
|
and <code>to</code> with the given string. <code>from</code>
|
|
and <code>to</code> must be <code>{line, ch}</code>
|
|
objects. <code>to</code> can be left off to simply insert the
|
|
string at position <code>from</code>.</dd>
|
|
|
|
<dt id="getSelection"><code>getSelection() → string</code></dt>
|
|
<dd>Get the currently selected code.</dd>
|
|
<dt id="replaceSelection"><code>replaceSelection(string)</code></dt>
|
|
<dd>Replace the selection with the given string.</dd>
|
|
|
|
<dt id="getCursor"><code>getCursor(start) → object</code></dt>
|
|
<dd><code>start</code> is a boolean indicating whether the start
|
|
or the end of the selection must be retrieved. If it is not
|
|
given, the current cursor pos, i.e. the side of the selection
|
|
that would move if you pressed an arrow key, is chosen.
|
|
Alternatively, you can pass one of the
|
|
strings <code>"start"</code>, <code>"end"</code>, <code>"head"</code>
|
|
(same as not passing anything), or <code>"anchor"</code> (the
|
|
opposite). A <code>{line, ch}</code> object will be
|
|
returned.</dd>
|
|
<dt id="somethingSelected"><code>somethingSelected() → boolean</code></dt>
|
|
<dd>Return true if any text is selected.</dd>
|
|
<dt id="setCursor"><code>setCursor(pos)</code></dt>
|
|
<dd>Set the cursor position. You can either pass a
|
|
single <code>{line, ch}</code> object, or the line and the
|
|
character as two separate parameters.</dd>
|
|
<dt id="setSelection"><code>setSelection(anchor, head)</code></dt>
|
|
<dd>Set the selection range. <code>anchor</code>
|
|
and <code>head</code> should be <code>{line, ch}</code>
|
|
objects. <code>head</code> defaults to <code>anchor</code> when
|
|
not givne.</dd>
|
|
|
|
<dt id="getLine"><code>getLine(n) → string</code></dt>
|
|
<dd>Get the content of line <code>n</code>.</dd>
|
|
<dt id="setLine"><code>setLine(n, text)</code></dt>
|
|
<dd>Set the content of line <code>n</code>.</dd>
|
|
<dt id="removeLine"><code>removeLine(n)</code></dt>
|
|
<dd>Remove the given line from the document.</dd>
|
|
|
|
<dt id="setSize"><code>setSize(width, height)</code></dt>
|
|
<dd>Programatically set the size of the editor (overriding the
|
|
applicable <a href="#css-resize">CSS
|
|
rules</a>). <code>width</code> and <code>height</code> height
|
|
can be either numbers (interpreted as pixels) or CSS units
|
|
(<code>"100%"</code>, for example). You can
|
|
pass <code>null</code> for either of them to indicate that that
|
|
dimension should not be changed.</dd>
|
|
<dt id="focus"><code>focus()</code></dt>
|
|
<dd>Give the editor focus.</dd>
|
|
<dt id="scrollTo"><code>scrollTo(x, y)</code></dt>
|
|
<dd>Scroll the editor to a given (pixel) position. Both
|
|
arguments may be left as <code>null</code>
|
|
or <code>undefined</code> to have no effect.</dd>
|
|
<dt id="getScrollInfo"><code>getScrollInfo()</code></dt>
|
|
<dd>Get an <code>{left, top, width, height, clientWidth,
|
|
clientHeight}</code> object that represents the current scroll
|
|
position, the size of the scrollable area, and the size of the
|
|
visible area (minus scrollbars).</dd>
|
|
<dt id="scrollIntoView"><code>scrollIntoView(pos)</code></dt>
|
|
<dd>Scrolls the given element into view. <code>pos</code> may be
|
|
either a <code>{line, ch}</code> position, referring to a given
|
|
character, <code>null</code>, to refer to the cursor, or
|
|
a <code>{left, top, right, bottom}</code> object, in
|
|
editor-local coordinates.</dd>
|
|
|
|
<dt id="setOption"><code>setOption(option, value)</code></dt>
|
|
<dd>Change the configuration of the editor. <code>option</code>
|
|
should the name of an <a href="#config">option</a>,
|
|
and <code>value</code> should be a valid value for that
|
|
option.</dd>
|
|
<dt id="getOption"><code>getOption(option) → value</code></dt>
|
|
<dd>Retrieves the current value of the given option for this
|
|
editor instance.</dd>
|
|
<dt id="getMode"><code>getMode() → object</code></dt>
|
|
<dd>Gets the mode object for the editor. Note that this is
|
|
distinct from <code>getOption("mode")</code>, which gives you
|
|
the mode specification, rather than the resolved, instantiated
|
|
<a href="#defineMode">mode object</a>.</dd>
|
|
|
|
<dt id="addKeyMap"><code>addKeyMap(map)</code></dt>
|
|
<dd>Attach an additional <a href="#keymaps">keymap</a> to the editor. This is mostly
|
|
useful for add-ons that need to register some key handlers
|
|
without trampling on
|
|
the <a href="#option_extraKeys"><code>extraKeys</code></a>
|
|
option. Maps added in this way have a lower precedence
|
|
than <code>extraKeys</code>, a higher precedence than the
|
|
base <a href="#option_keyMap"><code>keyMap</code></a>, and
|
|
between them, the maps added earlier have a higher precedence
|
|
than those added later.</dd>
|
|
<dt id="removeKeyMap"><code>removeKeyMap(map)</code></dt>
|
|
<dd>Disable a keymap added
|
|
with <a href="#addKeyMap"><code>addKeyMap</code></a>. Either
|
|
pass in the keymap object itself, or a string, which will be
|
|
compared against the <code>name</code> property of the active
|
|
keymaps.</dd>
|
|
|
|
<dt id="addOverlay"><code>addOverlay(mode, options)</code></dt>
|
|
<dd>Enable a highlighting overlay. This is a stateless mini-mode
|
|
that can be used to add extra highlighting. For example,
|
|
the <a href="../demo/search.html">search add-on</a> uses it to
|
|
highlight the term that's currently being
|
|
searched. <code>mode</code> can be a <a href="#option_mode">mode
|
|
spec</a> or a mode object (an object with
|
|
a <a href="#token"><code>token</code></a> method).
|
|
The <code>option</code> parameter is optional. If given it
|
|
should be an object. Currently, only the <code>opaque</code>
|
|
option is recognized. This defaults to off, but can be given to
|
|
allow the overlay styling, when not <code>null</code>, to
|
|
override the styling of the base mode entirely, instead of the
|
|
two being applied together.</dd>
|
|
<dt id="removeOverlay"><code>removeOverlay(mode)</code></dt>
|
|
<dd>Pass this the exact argument passed for
|
|
the <code>mode</code> parameter
|
|
to <a href="#addOverlay"><code>addOverlay</code></a> to remove
|
|
an overlay again.</dd>
|
|
|
|
<dt id="on"><code>on(type, func)</code></dt>
|
|
<dd>Register an event handler for the given event type (a
|
|
string) on the editor instance. There is also
|
|
a <code>CodeMirror.on(object, type, func)</code> version
|
|
that allows registering of events on any object.</dd>
|
|
<dt id="off"><code>off(type, func)</code></dt>
|
|
<dd>Remove an event handler on the editor instance. An
|
|
equivalent <code>CodeMirror.off(object, type,
|
|
func)</code> also exists.</dd>
|
|
|
|
<dt id="cursorCoords"><code>cursorCoords(where, mode) → object</code></dt>
|
|
<dd>Returns an <code>{left, top, bottom}</code> object
|
|
containing the coordinates of the cursor position.
|
|
If <code>mode</code> is <code>"local"</code>, they will be
|
|
relative to the top-left corner of the editable document. If it
|
|
is <code>"page"</code> or not given, they are relative to the
|
|
top-left corner of the page. <code>where</code> can be a boolean
|
|
indicating whether you want the start (<code>true</code>) or the
|
|
end (<code>false</code>) of the selection, or, if a <code>{line,
|
|
ch}</code> object is given, it specifies the precise position at
|
|
which you want to measure.</dd>
|
|
<dt id="charCoords"><code>charCoords(pos, mode) → object</code></dt>
|
|
<dd>Returns the position and dimensions of an arbitrary
|
|
character. <code>pos</code> should be a <code>{line, ch}</code>
|
|
object. This differs from <code>cursorCoords</code> in that
|
|
it'll give the size of the whole character, rather than just the
|
|
position that the cursor would have when it would sit at that
|
|
position.</dd>
|
|
<dt id="coordsChar"><code>coordsChar(object) → pos</code></dt>
|
|
<dd>Given an <code>{left, top}</code> object (in page coordinates),
|
|
returns the <code>{line, ch}</code> position that corresponds to
|
|
it.</dd>
|
|
<dt id="defaultTextHeight"><code>defaultTextHeight() → number</code></dt>
|
|
<dd>Returns the line height of the default font for the editor.</dd>
|
|
|
|
<dt id="markClean"><code>markClean()</code></dt>
|
|
<dd>Set the editor content as 'clean', a flag that it will
|
|
retain until it is edited, and which will be set again when such
|
|
an edit is undone again. Useful to track whether the content
|
|
needs to be saved.</dd>
|
|
<dt id="isClean"><code>isClean() → boolean</code></dt>
|
|
<dd>Returns whether the document is currently clean (not
|
|
modified since initialization or the last call
|
|
to <a href="#markClean"><code>markClean</code></a>).</dd>
|
|
|
|
<dt id="undo"><code>undo()</code></dt>
|
|
<dd>Undo one edit (if any undo events are stored).</dd>
|
|
<dt id="redo"><code>redo()</code></dt>
|
|
<dd>Redo one undone edit.</dd>
|
|
<dt id="historySize"><code>historySize() → object</code></dt>
|
|
<dd>Returns an object with <code>{undo, redo}</code> properties,
|
|
both of which hold integers, indicating the amount of stored
|
|
undo and redo operations.</dd>
|
|
<dt id="clearHistory"><code>clearHistory()</code></dt>
|
|
<dd>Clears the editor's undo history.</dd>
|
|
<dt id="getHistory"><code>getHistory() → object</code></dt>
|
|
<dd>Get a (JSON-serializeable) representation of the undo history.</dd>
|
|
<dt id="setHistory"><code>setHistory(object)</code></dt>
|
|
<dd>Replace the editor's undo history with the one provided,
|
|
which must be a value as returned
|
|
by <a href="#getHistory"><code>getHistory</code></a>. Note that
|
|
this will have entirely undefined results if the editor content
|
|
isn't also the same as it was when <code>getHistory</code> was
|
|
called.</dd>
|
|
|
|
<dt id="indentLine"><code>indentLine(line, dir)</code></dt>
|
|
<dd>Adjust the indentation of the given line. The second
|
|
argument (which defaults to <code>"smart"</code>) may be one of:
|
|
<dl>
|
|
<dt><code>"prev"</code></dt>
|
|
<dd>Base indentation on the indentation of the previous line.</dd>
|
|
<dt><code>"smart"</code></dt>
|
|
<dd>Use the mode's smart indentation if available, behave
|
|
like <code>"prev"</code> otherwise.</dd>
|
|
<dt><code>"add"</code></dt>
|
|
<dd>Increase the indentation of the line by
|
|
one <a href="#option_indentUnit">indent unit</a>.</dd>
|
|
<dt><code>"subtract"</code></dt>
|
|
<dd>Reduce the indentation of the line.</dd>
|
|
</dl></dd>
|
|
|
|
<dt id="getTokenAt"><code>getTokenAt(pos) → object</code></dt>
|
|
<dd>Retrieves information about the token the current mode found
|
|
before the given position (a <code>{line, ch}</code> object). The
|
|
returned object has the following properties:
|
|
<dl>
|
|
<dt><code>start</code></dt><dd>The character (on the given line) at which the token starts.</dd>
|
|
<dt><code>end</code></dt><dd>The character at which the token ends.</dd>
|
|
<dt><code>string</code></dt><dd>The token's string.</dd>
|
|
<dt><code>type</code></dt><dd>The token type the mode assigned
|
|
to the token, such as <code>"keyword"</code>
|
|
or <code>"comment"</code> (may also be null).</dd>
|
|
<dt><code>state</code></dt><dd>The mode's state at the end of this token.</dd>
|
|
</dl></dd>
|
|
|
|
<dt id="markText"><code>markText(from, to, options) → object</code></dt>
|
|
<dd>Can be used to mark a range of text with a specific CSS
|
|
class name. <code>from</code> and <code>to</code> should
|
|
be <code>{line, ch}</code> objects. The <code>options</code>
|
|
parameter is optional. When given, it should be an object that
|
|
may contain the following configuration options:
|
|
<dl>
|
|
<dt id="mark_className"><code>className (string)</code></dt>
|
|
<dd>Assigns a CSS class to the marked stretch of text.</dd>
|
|
<dt id="mark_inclusiveLeft"><code>inclusiveLeft (boolean)</code></dt><dd>Determines whether
|
|
text inserted on the left of the marker will end up inside
|
|
or outside of it.</dd>
|
|
<dt id="mark_inclusiveRight"><code>inclusiveRight</code> (boolean)</dt><dd>Like <code>inclusiveLeft</code>,
|
|
but for the right side.</dd>
|
|
<dt id="mark_atomic"><code>atomic (boolean)</code></dt>
|
|
<dd>Atomic ranges act as a single unit when cursor movement is
|
|
concerned—i.e. it is impossible to place the cursor inside of
|
|
them. In atomic ranges, <code>inclusiveLeft</code>
|
|
and <code>inclusiveRight</code> have a different meaning—they
|
|
will prevent the cursor from being placed respectively
|
|
directly before and directly after the range.</dd>
|
|
<dt id="mark_collapsed"><code>collapsed (boolean)</code></dt>
|
|
<dd>Collapsed ranges do not show up in the display. Setting a
|
|
range to be collapsed will automatically make it atomic.</dd>
|
|
<dt id="mark_clearOnEnter"><code>clearOnEnter (boolean)</code></dt>
|
|
<dd>When enabled, will cause the mark to clear itself whenever
|
|
the cursor enters its range. This is mostly useful for
|
|
text-replacement widgets that need to 'snap open' when the
|
|
user tries to edit them. A
|
|
the <a href="#event_clear"><code>"clear"</code></a> event
|
|
fired on the range handle can be used to be notified when this
|
|
happens.</dd>
|
|
<dt id="mark_replacedWith"><code>replacedWith (dom node)</code></dt>
|
|
<dd>Use a given node to display this range. Implies both
|
|
collapsed and atomic.</dd>
|
|
<dt id="mark_readOnly"><code>readOnly</code></td>
|
|
<dd>A read-only span can, as long as it is not cleared, not be
|
|
modified except by
|
|
calling <a href="#setValue"><code>setValue</code></a> to reset
|
|
the whole document. <em>Note:</em> adding a read-only span
|
|
currently clears the undo history of the editor, because
|
|
existing undo events being partially nullified by read-only
|
|
spans would corrupt the history (in the current
|
|
implementation).</dd>
|
|
<dt id="mark_startStyle"><code>startStyle</code></dt><dd>Can be used to specify
|
|
an extra CSS class to be applied to the leftmost span that
|
|
is part of the marker.</dd>
|
|
<dt id="mark_endStyle"><code>endStyle</code></dt><dd>Equivalent
|
|
to <code>startStyle</code>, but for the rightmost span.</dd>
|
|
</dl>
|
|
The method will return an object with two methods,
|
|
<code>clear()</code>, which removes the mark,
|
|
and <code>find()</code>, which returns a <code>{from, to}</code>
|
|
(both document positions), indicating the current position of
|
|
the marked range, or <code>undefined</code> if the marker is no
|
|
longer in the document.</dd>
|
|
|
|
<dt id="setBookmark"><code>setBookmark(pos, widget) → object</code></dt>
|
|
<dd>Inserts a bookmark, a handle that follows the text around it
|
|
as it is being edited, at the given position. A bookmark has two
|
|
methods <code>find()</code> and <code>clear()</code>. The first
|
|
returns the current position of the bookmark, if it is still in
|
|
the document, and the second explicitly removes the bookmark.
|
|
The widget argument is optional, and can be used to display a
|
|
DOM node at the current location of the bookmark (analogous to
|
|
the <a href="#mark_replacedWith"><code>replacedWith</code></a>
|
|
option to <code>markText</code>).</dd>
|
|
|
|
<dt id="findMarksAt"><code>findMarksAt(pos) → array</code></dt>
|
|
<dd>Returns an array of all the bookmarks and marked ranges
|
|
present at the given position.</dd>
|
|
|
|
<dt id="setGutterMarker"><code>setGutterMarker(line, gutterID, value) → lineHandle</code></dt>
|
|
<dd>Sets the gutter marker for the given gutter (identified by
|
|
its CSS class, see
|
|
the <a href="#option_gutters"><code>gutters</code></a> option)
|
|
to the given value. Value can be either <code>null</code>, to
|
|
clear the marker, or a DOM element, to set it. The DOM element
|
|
will be shown in the specified gutter next to the specified
|
|
line.</dd>
|
|
|
|
<dt id="clearGutter"><code>clearGutter(gutterID)</code></dt>
|
|
<dd>Remove all gutter markers in
|
|
the <a href="#option_gutters">gutter</a> with the given ID.</dd>
|
|
|
|
<dt id="addLineClass"><code>addLineClass(line, where, class) → lineHandle</code></dt>
|
|
<dd>Set a CSS class name for the given line. <code>line</code>
|
|
can be a number or a line handle. <code>where</code> determines
|
|
to which element this class should be applied, can can be one
|
|
of <code>"text"</code> (the text element, which lies in front of
|
|
the selection), <code>"background"</code> (a background element
|
|
that will be behind the selection), or <code>"wrap"</code> (the
|
|
wrapper node that wraps all of the line's elements, including
|
|
gutter elements). <code>class</code> should be the name of the
|
|
class to apply.</dd>
|
|
|
|
<dt id="removeLineClass"><code>removeLineClass(line, where, class) → lineHandle</code></dt>
|
|
<dd>Remove a CSS class from a line. <code>line</code> can be a
|
|
line handle or number. <code>where</code> should be one
|
|
of <code>"text"</code>, <code>"background"</code>,
|
|
or <code>"wrap"</code>
|
|
(see <a href="#addLineClass"><code>addLineClass</code></a>). <code>class</code>
|
|
can be left off to remove all classes for the specified node, or
|
|
be a string to remove only a specific class.</dd>
|
|
|
|
<dt id="lineInfo"><code>lineInfo(line) → object</code></dt>
|
|
<dd>Returns the line number, text content, and marker status of
|
|
the given line, which can be either a number or a line handle.
|
|
The returned object has the structure <code>{line, handle, text,
|
|
gutterMarkers, textClass, bgClass, wrapClass, widgets}</code>,
|
|
where <code>gutterMarkers</code> is an object mapping gutter IDs
|
|
to marker elements, and <code>widgets</code> is an array
|
|
of <a href="#addLineWidget">line widgets</a> attached to this
|
|
line, and the various class properties refer to classes added
|
|
with <a href="#addLineClass"><code>addLineClass</code></a>.</dd>
|
|
|
|
<dt id="getLineHandle"><code>getLineHandle(num) → lineHandle</code></dt>
|
|
<dd>Fetches the line handle for the given line number.</dd>
|
|
|
|
<dt id="getLineNumber"><code>getLineNumber(handle) → integer</code></dt>
|
|
<dd>Given a line handle, returns the current position of that
|
|
line (or <code>null</code> when it is no longer in the
|
|
document).</dd>
|
|
|
|
<dt id="getViewport"><code>getViewport() → object</code></dt>
|
|
<dd>Returns a <code>{from, to}</code> object indicating the
|
|
start (inclusive) and end (exclusive) of the currently displayed
|
|
part of the document. In big documents, when most content is
|
|
scrolled out of view, CodeMirror will only render the visible
|
|
part, and a margin around it. See also
|
|
the <a href="#event_viewportChange"><code>viewportChange</code></a>
|
|
event.</dd>
|
|
|
|
<dt id="addWidget"><code>addWidget(pos, node, scrollIntoView)</code></dt>
|
|
<dd>Puts <code>node</code>, which should be an absolutely
|
|
positioned DOM node, into the editor, positioned right below the
|
|
given <code>{line, ch}</code> position.
|
|
When <code>scrollIntoView</code> is true, the editor will ensure
|
|
that the entire node is visible (if possible). To remove the
|
|
widget again, simply use DOM methods (move it somewhere else, or
|
|
call <code>removeChild</code> on its parent).</dd>
|
|
|
|
<dt id="addLineWidget"><code>addLineWidget(line, node, options) → object</code></dt>
|
|
<dd>Adds a line widget, an element shown below a line, spanning
|
|
the whole of the editor's width, and moving the lines below it
|
|
downwards. <code>line</code> should be either an integer or a
|
|
line handle, and <code>node</code> should be a DOM node, which
|
|
will be displayed below the given line. <code>options</code>,
|
|
when given, should be an object that configures the behavior of
|
|
the widget. The following options are supported (all default to
|
|
false):
|
|
<dl>
|
|
<dt><code>coverGutter (boolean)</code></dt>
|
|
<dd>Whether the widget should cover the gutter.</dd>
|
|
<dt><code>noHScroll (boolean)</code></dt>
|
|
<dd>Whether the widget should stay fixed in the face of
|
|
horizontal scrolling.</dd>
|
|
<dt><code>above (boolean)</code></dt>
|
|
<dd>Causes the widget to be placed above instead of below
|
|
the text of the line.</dd>
|
|
</dl>
|
|
Note that the widget node will become a descendant of nodes with
|
|
CodeMirror-specific CSS classes, and those classes might in some
|
|
cases affect it. This method returns an object that represents
|
|
the widget placement. It'll have a <code>line</code> property
|
|
pointing at the line handle that it is associated with, and it
|
|
can be passed to <code>removeLineWidget</code> to remove the
|
|
widget.</dd>
|
|
|
|
<dt id="removeLineWidget"><code>removeLineWidget(widget)</code></dt>
|
|
<dd>Removes the given line widget.</dd>
|
|
|
|
<dt id="posFromIndex"><code>posFromIndex(index) → object</code></dt>
|
|
<dd>Calculates and returns a <code>{line, ch}</code> object for a
|
|
zero-based <code>index</code> who's value is relative to the start of the
|
|
editor's text. If the <code>index</code> is out of range of the text then
|
|
the returned object is clipped to start or end of the text
|
|
respectively.</dd>
|
|
<dt id="indexFromPos"><code>indexFromPos(object) → number</code></dt>
|
|
<dd>The reverse of <a href="#posFromIndex"><code>posFromIndex</code></a>.</dd>
|
|
</dl>
|
|
|
|
<p>The following are more low-level methods:</p>
|
|
|
|
<dl>
|
|
<dt id="operation"><code>operation(func) → result</code></dt>
|
|
<dd>CodeMirror internally buffers changes and only updates its
|
|
DOM structure after it has finished performing some operation.
|
|
If you need to perform a lot of operations on a CodeMirror
|
|
instance, you can call this method with a function argument. It
|
|
will call the function, buffering up all changes, and only doing
|
|
the expensive update after the function returns. This can be a
|
|
lot faster. The return value from this method will be the return
|
|
value of your function.</dd>
|
|
|
|
<dt id="refresh"><code>refresh()</code></dt>
|
|
<dd>If your code does something to change the size of the editor
|
|
element (window resizes are already listened for), or unhides
|
|
it, you should probably follow up by calling this method to
|
|
ensure CodeMirror is still looking as intended.</dd>
|
|
|
|
<dt id="extendSelection"><code>extendSelection(pos, pos2)</code></dt>
|
|
<dd>Similar
|
|
to <a href="#setSelection"><code>setSelection</code></a>, but
|
|
will, if shift is held or
|
|
the <a href="#setExtending">extending</a> flag is set, move the
|
|
head of the selection while leaving the anchor at its current
|
|
place. <code>pos2</code> is optional, and can be passed to
|
|
ensure a region (for example a word or paragraph) will end up
|
|
selected (in addition to whatever lies between that region and
|
|
the current anchor).</dd>
|
|
<dt id="setExtending"><code>setExtending(bool)</code></dt>
|
|
<dd>Sets or clears the 'extending' flag, which acts similar to
|
|
the shift key, in that it will cause cursor movement and calls
|
|
to <a href="#extendSelection"><code>extendSelection</code></a>
|
|
to leave the selection anchor in place.</dd>
|
|
|
|
<dt id="getInputField"><code>getInputField() → textarea</code></dt>
|
|
<dd>Returns the hidden textarea used to read input.</dd>
|
|
<dt id="getWrapperElement"><code>getWrapperElement() → node</code></dt>
|
|
<dd>Returns the DOM node that represents the editor, and
|
|
controls its size. Remove this from your tree to delete an
|
|
editor instance.</dd>
|
|
<dt id="getScrollerElement"><code>getScrollerElement() → node</code></dt>
|
|
<dd>Returns the DOM node that is responsible for the scrolling
|
|
of the editor.</dd>
|
|
<dt id="getGutterElement"><code>getGutterElement() → node</code></dt>
|
|
<dd>Fetches the DOM node that contains the editor gutters.</dd>
|
|
|
|
<dt id="getStateAfter"><code>getStateAfter(line) → state</code></dt>
|
|
<dd>Returns the mode's parser state, if any, at the end of the
|
|
given line number. If no line number is given, the state at the
|
|
end of the document is returned. This can be useful for storing
|
|
parsing errors in the state, or getting other kinds of
|
|
contextual information for a line.</dd>
|
|
</dl>
|
|
|
|
<p id="version">The <code>CodeMirror</code> object itself provides
|
|
several useful properties. Firstly, its <code>version</code>
|
|
property contains a string that indicates the version of the
|
|
library. For releases, this simply
|
|
contains <code>"major.minor"</code> (for
|
|
example <code>"2.33"</code>. For beta versions, <code>" B"</code>
|
|
(space, capital B) is added at the end of the string, for
|
|
development snapshots, <code>" +"</code> (space, plus) is
|
|
added.</p>
|
|
|
|
<p id="fromTextArea">The <code>CodeMirror.fromTextArea</code>
|
|
method provides another way to initialize an editor. It takes a
|
|
textarea DOM node as first argument and an optional configuration
|
|
object as second. It will replace the textarea with a CodeMirror
|
|
instance, and wire up the form of that textarea (if any) to make
|
|
sure the editor contents are put into the textarea when the form
|
|
is submitted. A CodeMirror instance created this way has three
|
|
additional methods:</p>
|
|
|
|
<dl>
|
|
<dt id="save"><code>save()</code></dt>
|
|
<dd>Copy the content of the editor into the textarea.</dd>
|
|
|
|
<dt id="toTextArea"><code>toTextArea()</code></dt>
|
|
<dd>Remove the editor, and restore the original textarea (with
|
|
the editor's current content).</dd>
|
|
|
|
<dt id="getTextArea"><code>getTextArea() → textarea</code></dt>
|
|
<dd>Returns the textarea that the instance was based on.</dd>
|
|
</dl>
|
|
|
|
<p id="defineExtension">If you want to define extra methods in terms
|
|
of the CodeMirror API, it is possible to
|
|
use <code>CodeMirror.defineExtension(name, value)</code>. This
|
|
will cause the given value (usually a method) to be added to all
|
|
CodeMirror instances created from then on.</p>
|
|
|
|
<p id="defineOption">Similarly, <code>CodeMirror.defineOption(name,
|
|
default, updateFunc)</code> can be used to define new options for
|
|
CodeMirror. The <code>updateFunc</code> will be called with the
|
|
editor instance and the new value when an editor is initialized,
|
|
and whenever the option is modified
|
|
through <a href="#setOption"><code>setOption</code></a>.</p>
|
|
|
|
<p id="defineInitHook">If your extention just needs to run some
|
|
code whenever a CodeMirror instance is initialized,
|
|
use <code>CodeMirror.defineInitHook</code>. Give it a function as
|
|
its only argument, and from then on, that function will be called
|
|
(with the instance as argument) whenever a new CodeMirror instance
|
|
is initialized.</p>
|
|
|
|
<h2 id="addons">Add-ons</h2>
|
|
|
|
<p>The <code>lib/util</code> directory in the distribution
|
|
contains a number of reusable components that implement extra
|
|
editor functionality. In brief, they are:</p>
|
|
|
|
<dl>
|
|
<dt id="util_dialog"><a href="../lib/util/dialog.js"><code>dialog.js</code></a></dt>
|
|
<dd>Provides a very simple way to query users for text input.
|
|
Adds an <code>openDialog</code> method to CodeMirror instances,
|
|
which can be called with an HTML fragment that provides the
|
|
prompt (should include an <code>input</code> tag), and a
|
|
callback function that is called when text has been entered.
|
|
Depends on <code>lib/util/dialog.css</code>.</dd>
|
|
<dt id="util_searchcursor"><a href="../lib/util/searchcursor.js"><code>searchcursor.js</code></a></dt>
|
|
<dd>Adds the <code>getSearchCursor(query, start, caseFold) →
|
|
cursor</code> method to CodeMirror instances, which can be used
|
|
to implement search/replace functionality. <code>query</code>
|
|
can be a regular expression or a string (only strings will match
|
|
across lines—if they contain newlines). <code>start</code>
|
|
provides the starting position of the search. It can be
|
|
a <code>{line, ch}</code> object, or can be left off to default
|
|
to the start of the document. <code>caseFold</code> is only
|
|
relevant when matching a string. It will cause the search to be
|
|
case-insensitive. A search cursor has the following methods:
|
|
<dl>
|
|
<dt><code>findNext(), findPrevious() → boolean</code></dt>
|
|
<dd>Search forward or backward from the current position.
|
|
The return value indicates whether a match was found. If
|
|
matching a regular expression, the return value will be the
|
|
array returned by the <code>match</code> method, in case you
|
|
want to extract matched groups.</dd>
|
|
<dt><code>from(), to() → object</code></dt>
|
|
<dd>These are only valid when the last call
|
|
to <code>findNext</code> or <code>findPrevious</code> did
|
|
not return false. They will return <code>{line, ch}</code>
|
|
objects pointing at the start and end of the match.</dd>
|
|
<dt><code>replace(text)</code></dt>
|
|
<dd>Replaces the currently found match with the given text
|
|
and adjusts the cursor position to reflect the
|
|
replacement.</dd>
|
|
</dl></dd>
|
|
|
|
<dt id="util_search"><a href="../lib/util/search.js"><code>search.js</code></a></dt>
|
|
<dd>Implements the search commands. CodeMirror has keys bound to
|
|
these by default, but will not do anything with them unless an
|
|
implementation is provided. Depends
|
|
on <code>searchcursor.js</code>, and will make use
|
|
of <a href="#util_dialog"><code>openDialog</code></a> when
|
|
available to make prompting for search queries less ugly.</dd>
|
|
<dt id="util_matchbrackets"><a href="../lib/util/matchbrackets.js"><code>matchbrackets.js</code></a></dt>
|
|
<dd>Defines an option <code>matchBrackets</code> which, when set
|
|
to true, causes matching brackets to be highlighted whenever the
|
|
cursor is next to them. It also adds a
|
|
method <code>matchBrackets</code> that forces this to happen
|
|
once, and a method <code>findMatchingBracket</code> that can be
|
|
used to run the bracket-finding algorithm that this uses
|
|
internally.</dd>
|
|
<dt id="util_foldcode"><a href="../lib/util/foldcode.js"><code>foldcode.js</code></a></dt>
|
|
<dd>Helps with code folding.
|
|
See <a href="../demo/folding.html">the demo</a> for an example.
|
|
Call <code>CodeMirror.newFoldFunction</code> with a range-finder
|
|
helper function to create a function that will, when applied to
|
|
a CodeMirror instance and a line number, attempt to fold or
|
|
unfold the block starting at the given line. A range-finder is a
|
|
language-specific function that also takes an instance and a
|
|
line number, and returns an range to be folded, or null if
|
|
no block is started on that line. This file
|
|
provides <code>CodeMirror.braceRangeFinder</code>, which finds
|
|
blocks in brace languages (JavaScript, C, Java,
|
|
etc), <code>CodeMirror.indentRangeFinder</code>, for languages
|
|
where indentation determines block structure (Python, Haskell),
|
|
and <code>CodeMirror.tagRangeFinder</code>, for XML-style
|
|
languages.</dd>
|
|
<dt id="util_runmode"><a href="../lib/util/runmode.js"><code>runmode.js</code></a></dt>
|
|
<dd>Can be used to run a CodeMirror mode over text without
|
|
actually opening an editor instance.
|
|
See <a href="../demo/runmode.html">the demo</a> for an
|
|
example.</dd>
|
|
<dt id="util_overlay"><a href="../lib/util/overlay.js"><code>overlay.js</code></a></dt>
|
|
<dd>Mode combinator that can be used to extend a mode with an
|
|
'overlay' — a secondary mode is run over the stream, along with
|
|
the base mode, and can color specific pieces of text without
|
|
interfering with the base mode.
|
|
Defines <code>CodeMirror.overlayMode</code>, which is used to
|
|
create such a mode. See <a href="../demo/mustache.html">this
|
|
demo</a> for a detailed example.</dd>
|
|
<dt id="util_multiplex"><a href="../lib/util/multiplex.js"><code>multiplex.js</code></a></dt>
|
|
<dd>Mode combinator that can be used to easily 'multiplex'
|
|
between several modes.
|
|
Defines <code>CodeMirror.multiplexingMode</code> which, when
|
|
given as first argument a mode object, and as other arguments
|
|
any number of <code>{open, close, mode [, delimStyle]}</code>
|
|
objects, will return a mode object that starts parsing using the
|
|
mode passed as first argument, but will switch to another mode
|
|
as soon as it encounters a string that occurs in one of
|
|
the <code>open</code> fields of the passed objects. When in a
|
|
sub-mode, it will go back to the top mode again when
|
|
the <code>close</code> string is encountered.
|
|
Pass <code>"\n"</code> for <code>open</code> or <code>close</code>
|
|
if you want to switch on a blank line.
|
|
When <code>delimStyle</code> is specified, it will be the token
|
|
style returned for the delimiter tokens. The outer mode will not
|
|
see the content between the delimiters.
|
|
See <a href="../demo/multiplex.html">this demo</a> for an
|
|
example.</dd>
|
|
<dt id="util_simple-hint"><a href="../lib/util/simple-hint.js"><code>simple-hint.js</code></a></dt>
|
|
<dd>Provides a framework for showing autocompletion hints.
|
|
Defines <code>CodeMirror.simpleHint</code>, which takes a
|
|
CodeMirror instance and a hinting function, and pops up a widget
|
|
that allows the user to select a completion. Hinting functions
|
|
are function that take an editor instance, and return
|
|
a <code>{list, from, to}</code> object, where <code>list</code>
|
|
is an array of strings (the completions), and <code>from</code>
|
|
and <code>to</code> give the start and end of the token that is
|
|
being completed. Depends
|
|
on <code>lib/util/simple-hint.css</code>.</dd>
|
|
<dt id="util_javascript-hint"><a href="../lib/util/javascript-hint.js"><code>javascript-hint.js</code></a></dt>
|
|
<dd>Defines <code>CodeMirror.javascriptHint</code>
|
|
and <code>CodeMirror.coffeescriptHint</code>, which are simple
|
|
hinting functions for the JavaScript and CoffeeScript
|
|
modes.</dd>
|
|
<dt id="util_match-highlighter"><a href="../lib/util/match-highlighter.js"><code>match-highlighter.js</code></a></dt>
|
|
<dd>Adds a <code>matchHighlight</code> method to CodeMirror
|
|
instances that can be called (typically from
|
|
a <a href="#event_cursorActivity"><code>cursorActivity</code></a>
|
|
handler) to highlight all instances of a currently selected word
|
|
with the a classname given as a first argument to the method.
|
|
Depends on
|
|
the <a href="#util_searchcursor"><code>searchcursor</code></a>
|
|
add-on. Demo <a href="../demo/matchhighlighter.html">here</a>.</dd>
|
|
<dt id="util_formatting"><a href="../lib/util/formatting.js"><code>formatting.js</code></a></dt>
|
|
<dd>Adds <code>commentRange</code>, <code>autoIndentRange</code>,
|
|
and <code>autoFormatRange</code> methods that, respectively,
|
|
comment (or uncomment), indent, or format (add line breaks) a
|
|
range of code. <a href="../demo/formatting.html">Demo here.</a></dd>
|
|
<dt id="util_closetag"><a href="../lib/util/closetag.js"><code>closetag.js</code></a></dt>
|
|
<dd>Provides utility functions for adding automatic tag closing
|
|
to XML modes. See
|
|
the <a href="../demo/closetag.html">demo</a>.</dd>
|
|
<dt id="util_loadmode"><a href="../lib/util/loadmode.js"><code>loadmode.js</code></a></dt>
|
|
<dd>Defines a <code>CodeMirror.requireMode(modename,
|
|
callback)</code> function that will try to load a given mode and
|
|
call the callback when it succeeded. You'll have to
|
|
set <code>CodeMirror.modeURL</code> to a string that mode paths
|
|
can be constructed from, for
|
|
example <code>"mode/%N/%N.js"</code>—the <code>%N</code>'s will
|
|
be replaced with the mode name. Also
|
|
defines <code>CodeMirror.autoLoadMode(instance, mode)</code>,
|
|
which will ensure the given mode is loaded and cause the given
|
|
editor instance to refresh its mode when the loading
|
|
succeeded. See the <a href="../demo/loadmode.html">demo</a>.</dd>
|
|
<dt id="util_continuecomment"><a href="../lib/util/continuecomment.js"><code>continuecomment.js</code></a></dt>
|
|
<dd>Adds a <a href="#commands">command</a>
|
|
called <code>newlineAndIndentContinueComment</code> that you can
|
|
bind <code>Enter</code> to in order to have the editor prefix
|
|
new lines inside C-like block comments with an asterisk.</dd>
|
|
</dl>
|
|
|
|
<h2 id="modeapi">Writing CodeMirror Modes</h2>
|
|
|
|
<p>Modes typically consist of a single JavaScript file. This file
|
|
defines, in the simplest case, a lexer (tokenizer) for your
|
|
language—a function that takes a character stream as input,
|
|
advances it past a token, and returns a style for that token. More
|
|
advanced modes can also handle indentation for the language.</p>
|
|
|
|
<p id="defineMode">The mode script should
|
|
call <code>CodeMirror.defineMode</code> to register itself with
|
|
CodeMirror. This function takes two arguments. The first should be
|
|
the name of the mode, for which you should use a lowercase string,
|
|
preferably one that is also the name of the files that define the
|
|
mode (i.e. <code>"xml"</code> is defined in <code>xml.js</code>). The
|
|
second argument should be a function that, given a CodeMirror
|
|
configuration object (the thing passed to
|
|
the <code>CodeMirror</code> function) and an optional mode
|
|
configuration object (as in
|
|
the <a href="#option_mode"><code>mode</code></a> option), returns
|
|
a mode object.</p>
|
|
|
|
<p>Typically, you should use this second argument
|
|
to <code>defineMode</code> as your module scope function (modes
|
|
should not leak anything into the global scope!), i.e. write your
|
|
whole mode inside this function.</p>
|
|
|
|
<p>The main responsibility of a mode script is <em>parsing</em>
|
|
the content of the editor. Depending on the language and the
|
|
amount of functionality desired, this can be done in really easy
|
|
or extremely complicated ways. Some parsers can be stateless,
|
|
meaning that they look at one element (<em>token</em>) of the code
|
|
at a time, with no memory of what came before. Most, however, will
|
|
need to remember something. This is done by using a <em>state
|
|
object</em>, which is an object that is always passed when
|
|
reading a token, and which can be mutated by the tokenizer.</p>
|
|
|
|
<p id="startState">Modes that use a state must define
|
|
a <code>startState</code> method on their mode object. This is a
|
|
function of no arguments that produces a state object to be used
|
|
at the start of a document.</p>
|
|
|
|
<p id="token">The most important part of a mode object is
|
|
its <code>token(stream, state)</code> method. All modes must
|
|
define this method. It should read one token from the stream it is
|
|
given as an argument, optionally update its state, and return a
|
|
style string, or <code>null</code> for tokens that do not have to
|
|
be styled. For your styles, you are encouraged to use the
|
|
'standard' names defined in the themes (without
|
|
the <code>cm-</code> prefix). If that fails, it is also possible
|
|
to come up with your own and write your own CSS theme file.<p>
|
|
|
|
<p id="StringStream">The stream object that's passed
|
|
to <code>token</code> encapsulates a line of code (tokens may
|
|
never span lines) and our current position in that line. It has
|
|
the following API:</p>
|
|
|
|
<dl>
|
|
<dt><code>eol() → boolean</code></dt>
|
|
<dd>Returns true only if the stream is at the end of the
|
|
line.</dd>
|
|
<dt><code>sol() → boolean</code></dt>
|
|
<dd>Returns true only if the stream is at the start of the
|
|
line.</dd>
|
|
|
|
<dt><code>peek() → character</code></dt>
|
|
<dd>Returns the next character in the stream without advancing
|
|
it. Will return an <code>null</code> at the end of the
|
|
line.</dd>
|
|
<dt><code>next() → character</code></dt>
|
|
<dd>Returns the next character in the stream and advances it.
|
|
Also returns <code>null</code> when no more characters are
|
|
available.</dd>
|
|
|
|
<dt><code>eat(match) → character</code></dt>
|
|
<dd><code>match</code> can be a character, a regular expression,
|
|
or a function that takes a character and returns a boolean. If
|
|
the next character in the stream 'matches' the given argument,
|
|
it is consumed and returned. Otherwise, <code>undefined</code>
|
|
is returned.</dd>
|
|
<dt><code>eatWhile(match) → boolean</code></dt>
|
|
<dd>Repeatedly calls <code>eat</code> with the given argument,
|
|
until it fails. Returns true if any characters were eaten.</dd>
|
|
<dt><code>eatSpace() → boolean</code></dt>
|
|
<dd>Shortcut for <code>eatWhile</code> when matching
|
|
white-space.</dd>
|
|
<dt><code>skipToEnd()</code></dt>
|
|
<dd>Moves the position to the end of the line.</dd>
|
|
<dt><code>skipTo(ch) → boolean</code></dt>
|
|
<dd>Skips to the next occurrence of the given character, if
|
|
found on the current line (doesn't advance the stream if the
|
|
character does not occur on the line). Returns true if the
|
|
character was found.</dd>
|
|
<dt><code>match(pattern, consume, caseFold) → boolean</code></dt>
|
|
<dd>Act like a
|
|
multi-character <code>eat</code>—if <code>consume</code> is true
|
|
or not given—or a look-ahead that doesn't update the stream
|
|
position—if it is false. <code>pattern</code> can be either a
|
|
string or a regular expression starting with <code>^</code>.
|
|
When it is a string, <code>caseFold</code> can be set to true to
|
|
make the match case-insensitive. When successfully matching a
|
|
regular expression, the returned value will be the array
|
|
returned by <code>match</code>, in case you need to extract
|
|
matched groups.</dd>
|
|
|
|
<dt><code>backUp(n)</code></dt>
|
|
<dd>Backs up the stream <code>n</code> characters. Backing it up
|
|
further than the start of the current token will cause things to
|
|
break, so be careful.</dd>
|
|
<dt><code>column() → integer</code></dt>
|
|
<dd>Returns the column (taking into account tabs) at which the
|
|
current token starts.</dd>
|
|
<dt><code>indentation() → integer</code></dt>
|
|
<dd>Tells you how far the current line has been indented, in
|
|
spaces. Corrects for tab characters.</dd>
|
|
|
|
<dt><code>current() → string</code></dt>
|
|
<dd>Get the string between the start of the current token and
|
|
the current stream position.</dd>
|
|
</dl>
|
|
|
|
<p id="blankLine">By default, blank lines are simply skipped when
|
|
tokenizing a document. For languages that have significant blank
|
|
lines, you can define a <code>blankLine(state)</code> method on
|
|
your mode that will get called whenever a blank line is passed
|
|
over, so that it can update the parser state.</p>
|
|
|
|
<p id="copyState">Because state object are mutated, and CodeMirror
|
|
needs to keep valid versions of a state around so that it can
|
|
restart a parse at any line, copies must be made of state objects.
|
|
The default algorithm used is that a new state object is created,
|
|
which gets all the properties of the old object. Any properties
|
|
which hold arrays get a copy of these arrays (since arrays tend to
|
|
be used as mutable stacks). When this is not correct, for example
|
|
because a mode mutates non-array properties of its state object, a
|
|
mode object should define a <code>copyState</code> method,
|
|
which is given a state and should return a safe copy of that
|
|
state.</p>
|
|
|
|
<p id="indent">If you want your mode to provide smart indentation
|
|
(through the <a href="#indentLine"><code>indentLine</code></a>
|
|
method and the <code>indentAuto</code>
|
|
and <code>newlineAndIndent</code> commands, which keys can be
|
|
<a href="#option_extraKeys">bound</a> to), you must define
|
|
an <code>indent(state, textAfter)</code> method on your mode
|
|
object.</p>
|
|
|
|
<p>The indentation method should inspect the given state object,
|
|
and optionally the <code>textAfter</code> string, which contains
|
|
the text on the line that is being indented, and return an
|
|
integer, the amount of spaces to indent. It should usually take
|
|
the <a href="#option_indentUnit"><code>indentUnit</code></a>
|
|
option into account.</p>
|
|
|
|
<p id="electricChars">Finally, a mode may define
|
|
an <code>electricChars</code> property, which should hold a string
|
|
containing all the characters that should trigger the behaviour
|
|
described for
|
|
the <a href="#option_electricChars"><code>electricChars</code></a>
|
|
option.</p>
|
|
|
|
<p>So, to summarize, a mode <em>must</em> provide
|
|
a <code>token</code> method, and it <em>may</em>
|
|
provide <code>startState</code>, <code>copyState</code>,
|
|
and <code>indent</code> methods. For an example of a trivial mode,
|
|
see the <a href="../mode/diff/diff.js">diff mode</a>, for a more
|
|
involved example, see the <a href="../mode/clike/clike.js">C-like
|
|
mode</a>.</p>
|
|
|
|
<p>Sometimes, it is useful for modes to <em>nest</em>—to have one
|
|
mode delegate work to another mode. An example of this kind of
|
|
mode is the <a href="../mode/htmlmixed/htmlmixed.js">mixed-mode HTML
|
|
mode</a>. To implement such nesting, it is usually necessary to
|
|
create mode objects and copy states yourself. To create a mode
|
|
object, there are <code>CodeMirror.getMode(options,
|
|
parserConfig)</code>, where the first argument is a configuration
|
|
object as passed to the mode constructor function, and the second
|
|
argument is a mode specification as in
|
|
the <a href="#option_mode"><code>mode</code></a> option. To copy a
|
|
state object, call <code>CodeMirror.copyState(mode, state)</code>,
|
|
where <code>mode</code> is the mode that created the given
|
|
state.</p>
|
|
|
|
<p id="innerMode">In a nested mode, it is recommended to add an
|
|
extra methods, <code>innerMode</code> which, given a state object,
|
|
returns a <code>{state, mode}</code> object with the inner mode
|
|
and its state for the current position. These are used by utility
|
|
scripts such as the <a href="#util_formatting">autoformatter</a>
|
|
and the <a href="#util_closetag">tag closer</a> to get context
|
|
information. Use the <code>CodeMirror.innerMode</code> helper
|
|
function to, starting from a mode and a state, recursively walk
|
|
down to the innermost mode and state.</p>
|
|
|
|
<p>To make indentation work properly in a nested parser, it is
|
|
advisable to give the <code>startState</code> method of modes that
|
|
are intended to be nested an optional argument that provides the
|
|
base indentation for the block of code. The JavaScript and CSS
|
|
parser do this, for example, to allow JavaScript and CSS code
|
|
inside the mixed-mode HTML mode to be properly indented.</p>
|
|
|
|
<p>It is possible, and encouraged, to associate your mode, or a
|
|
certain configuration of your mode, with
|
|
a <a href="http://en.wikipedia.org/wiki/MIME">MIME</a> type. For
|
|
example, the JavaScript mode associates itself
|
|
with <code>text/javascript</code>, and its JSON variant
|
|
with <code>application/json</code>. To do this,
|
|
call <code>CodeMirror.defineMIME(mime, modeSpec)</code>,
|
|
where <code>modeSpec</code> can be a string or object specifying a
|
|
mode, as in the <a href="#option_mode"><code>mode</code></a>
|
|
option.</p>
|
|
|
|
<p id="extendMode">Sometimes, it is useful to add or override mode
|
|
object properties from external code.
|
|
The <code>CodeMirror.extendMode</code> can be used to add
|
|
properties to mode objects produced for a specific mode. Its first
|
|
argument is the name of the mode, its second an object that
|
|
specifies the properties that should be added. This is mostly
|
|
useful to add utilities that can later be looked
|
|
up through <a href="#getMode"><code>getMode</code></a>.</p>
|
|
|
|
</div><div class="rightsmall blk">
|
|
|
|
<h2>Contents</h2>
|
|
|
|
<ul>
|
|
<li><a href="#overview">Overview</a></li>
|
|
<li><a href="#usage">Basic Usage</a></li>
|
|
<li><a href="#config">Configuration</a></li>
|
|
<li><a href="#events">Events</a></li>
|
|
<li><a href="#keymaps">Keymaps</a></li>
|
|
<li><a href="#styling">Customized Styling</a></li>
|
|
<li><a href="#api">Programming API</a></li>
|
|
<li><a href="#addons">Add-ons</a></li>
|
|
<li><a href="#modeapi">Writing CodeMirror Modes</a></li>
|
|
</ul>
|
|
|
|
</div></div>
|
|
|
|
<div style="height: 2em"> </div>
|
|
|
|
<script>setTimeout(function(){CodeMirror.colorize();}, 20);</script>
|
|
|
|
</body>
|
|
</html>
|