git add stuff
This commit is contained in:
Alan
771
simpla/design/js/codemirror/manual.html
Normal file
771
simpla/design/js/codemirror/manual.html
Normal file
@@ -0,0 +1,771 @@
|
||||
<!doctype html>
|
||||
<html>
|
||||
<head>
|
||||
<title>CodeMirror: User Manual</title>
|
||||
<link rel="stylesheet" type="text/css" href="css/docs.css"/>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
|
||||
<style>dl dl {margin: 0;}</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<h1><span class="logo-braces">{ }</span> <a href="http://codemirror.net/">CodeMirror</a></h1>
|
||||
|
||||
<pre class="grey">
|
||||
<img src="css/baboon.png" class="logo" alt="logo"/>/* User manual and
|
||||
reference guide */
|
||||
</pre>
|
||||
|
||||
<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. It 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.</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 few
|
||||
modes (see the <code>mode/</code> 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 the script and style sheet for the mode(s) you want to use.
|
||||
(See also <a href="compress.html">the compresion helper</a>.) For
|
||||
example:</p>
|
||||
|
||||
<pre><script src="lib/codemirror.js"></script>
|
||||
<link rel="stylesheet" href="lib/codemirror.css">
|
||||
<script src="mode/javascript/javascript.js"></script>
|
||||
<link rel="stylesheet" href="mode/javascript/javascript.css"></pre>
|
||||
|
||||
<p>Having done this, an editor instance can be created like
|
||||
this:</p>
|
||||
|
||||
<pre>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>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>var myCodeMirror = CodeMirror(function(elt) {
|
||||
myTextArea.parentNode.replaceChild(myTextArea, elt);
|
||||
}, {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>var myCodeMirror = CodeMirror.fromTextArea(myTextArea);</pre>
|
||||
|
||||
<p>This will, among other things, ensure that the textarea's value
|
||||
is updated 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 options 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 are loaded with
|
||||
the <code>CodeMirror.listModes</code>
|
||||
and <code>CodeMirror.listMIMEs</code> functions.</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_indentWithTabs"><code>indentWithTabs (boolean)</code></dt>
|
||||
<dd>Whether, when indenting, the first N*8 spaces should be
|
||||
replaced by N tabs. Default is false.</dd>
|
||||
|
||||
<dt id="option_tabMode"><code>tabMode (string)</code></dt>
|
||||
<dd>Determines what happens when the user presses the tab key.
|
||||
Must be one of the following:
|
||||
<dl>
|
||||
<dt><code>"classic" (the default)</code></dt>
|
||||
<dd>When nothing is selected, insert a tab. Otherwise,
|
||||
behave like the <code>"shift"</code> mode. (When shift is
|
||||
held, this behaves like the <code>"indent"</code> mode.)</dd>
|
||||
<dt><code>"shift"</code></dt>
|
||||
<dd>Indent all selected lines by
|
||||
one <a href="#option_indentUnit"><code>indentUnit</code></a>.
|
||||
If shift was held while pressing tab, un-indent all selected
|
||||
lines one unit.</dd>
|
||||
<dt><code>"indent"</code></dt>
|
||||
<dd>Indent the line the 'correctly', based on its syntactic
|
||||
context. Only works if the
|
||||
mode <a href="#indent">supports</a> it.</dd>
|
||||
<dt><code>"default"</code></dt>
|
||||
<dd>Do not capture tab presses, let the browser apply its
|
||||
default behaviour (which usually means it skips to the next
|
||||
control).</dd>
|
||||
</dl></dd>
|
||||
|
||||
<dt id="option_enterMode"><code>enterMode (string)</code></dt>
|
||||
<dd>Determines whether and how new lines are indented when the
|
||||
enter key is pressed. The following modes are supported:
|
||||
<dl>
|
||||
<dt><code>"indent" (the default)</code></dt>
|
||||
<dd>Use the mode's indentation rules to give the new line
|
||||
the correct indentation.</dd>
|
||||
<dt><code>"keep"</code></dt>
|
||||
<dd>Indent the line the same as the previous line.</dd>
|
||||
<dt><code>"flat"</code></dt>
|
||||
<dd>Do not indent the new line.</dd>
|
||||
</dl></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_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_gutter"><code>gutter (boolean)</code></dt>
|
||||
<dd>Can be used to force a 'gutter' (empty space on the left of
|
||||
the editor) to be shown even when no line numbers are active.
|
||||
This is useful for setting <a href="#setMarker">markers</a>.</dd>
|
||||
|
||||
<dt id="option_readOnly"><code>readOnly (boolean)</code></dt>
|
||||
<dd>This disables editing of the editor content by the user.
|
||||
(Changes through API functions will still be possible.)</dd>
|
||||
|
||||
<dt id="option_onChange"><code>onChange (function)</code></dt>
|
||||
<dd>When given, this function will be called every time the
|
||||
content of the editor is changed. It will be given the editor
|
||||
instance as only argument.</dd>
|
||||
|
||||
<dt id="option_onCursorActivity"><code>onCursorActivity (function)</code></dt>
|
||||
<dd>Like <code>onChange</code>, but will also be called when the
|
||||
cursor moves without any changes being made.</dd>
|
||||
|
||||
<dt id="option_onGutterClick"><code>onGutterClick (function)</code></dt>
|
||||
<dd>When given, will be called whenever the editor gutter (the
|
||||
line-number area) is clicked. Will be given the editor instance
|
||||
as first argument, and the (zero-based) number of the line that
|
||||
was clicked as second argument.</dd>
|
||||
|
||||
<dt id="option_onFocus"><code>onFocus, onBlur (function)</code></dt>
|
||||
<dd>The given functions will be called whenever the editor is
|
||||
focused or unfocused.</dd>
|
||||
|
||||
<dt id="option_onScroll"><code>onScroll (function)</code></dt>
|
||||
<dd>When given, will be called whenever the editor is
|
||||
scrolled.</dd>
|
||||
|
||||
<dt id="option_matchBrackets"><code>matchBrackets (boolean)</code></dt>
|
||||
<dd>Determines whether brackets are matched whenever the cursor
|
||||
is moved next to a bracket.</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_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_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> 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>
|
||||
</dl>
|
||||
|
||||
<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 determines whether the
|
||||
editor scrolls (<code>overflow: auto</code> + fixed height). Can
|
||||
also be used to set styles that should hold for everything
|
||||
inside the editor, or to set a background.</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_gutter"><code>CodeMirror-gutter</code></dt>
|
||||
<dd>Use this for giving a background or a border to the editor
|
||||
gutter. Don't set any padding here,
|
||||
use <code>CodeMirror-gutter-text</code> for that. By default,
|
||||
the gutter is 'fluid', meaning it will adjust its width to the
|
||||
maximum line number or line marker width. You can also set a
|
||||
fixed width if you want.</dd>
|
||||
|
||||
<dt id="class_CodeMirror_gutter_text"><code>CodeMirror-gutter-text</code></dt>
|
||||
<dd>Used to style the actual line numbers. For the numbers to
|
||||
line up, you'll want this style to use exactly the same font and
|
||||
vertical padding as normal edited text, as per
|
||||
the <code>CodeMirror-lines</code> class.</dd>
|
||||
|
||||
<dt id="class_CodeMirror_lines"><code>CodeMirror-lines</code></dt>
|
||||
<dd>The visible lines. If this has vertical
|
||||
padding, <code>CodeMirror-gutter</code> should have the same
|
||||
padding.</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-matchingbracket</code></dt>
|
||||
<dd>These are used to style matched (or unmatched) brackets.</dd>
|
||||
</dl>
|
||||
|
||||
<p>The actual lines, as well as the cursor, are represented
|
||||
by <code>pre</code> elements. By default no text styling (such as
|
||||
bold) that might change line height is applied. If you do want
|
||||
such effects, you'll have to give <code>CodeMirror pre</code> a
|
||||
fixed height. Also, you must still take care that character width
|
||||
is constant.</p>
|
||||
|
||||
<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>
|
||||
|
||||
<h2 id="api">Programming API</h2>
|
||||
|
||||
<p>A lot of CodeMirror features are only available through its API.
|
||||
This has the disadvantage that you need to do work to enable them,
|
||||
and the advantage that CodeMirror will fit seamlessly into your
|
||||
application.</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.</dd>
|
||||
<dt id="setValue"><code>setValue(string)</code></dt>
|
||||
<dd>Set the editor content.</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="focus"><code>focus()</code></dt>
|
||||
<dd>Give the editor focus.</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="cursorCoords"><code>cursorCoords(start) → object</code></dt>
|
||||
<dd>Returns an <code>{x, y, yBot}</code> object containing the
|
||||
coordinates of the cursor relative to the top-left corner of the
|
||||
page. <code>yBot</code> is the coordinate of the bottom of the
|
||||
cursor. <code>start</code> is a boolean indicating whether you
|
||||
want the start or the end of the selection.</dd>
|
||||
<dt id="charCoords"><code>charCoords(pos) → object</code></dt>
|
||||
<dd>Like <code>cursorCoords</code>, but returns the position of
|
||||
an arbitrary characters. <code>pos</code> should be
|
||||
a <code>{line, ch}</code> object.</dd>
|
||||
<dt id="coordsChar"><code>coordsChar(object) → pos</code></dt>
|
||||
<dd>Given an <code>{x, y}</code> object (in page coordinates),
|
||||
returns the <code>{line, ch}</code> position that corresponds to
|
||||
it.</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="indentLine"><code>indentLine(line)</code></dt>
|
||||
<dd>Reset the given line's indentation to the indentation
|
||||
prescribed by the mode.</dd>
|
||||
|
||||
<dt id="getSearchCursor"><code>getSearchCursor(query, start, caseFold) → cursor</code></dt>
|
||||
<dd>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>
|
||||
</dl></dd>
|
||||
|
||||
<dt id="getTokenAt"><code>getTokenAt(pos) → object</code></dt>
|
||||
<dd>Retrieves information about the token the current mode found
|
||||
at 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>className</code></dt><dd>The class the mode assigned
|
||||
to the token. (Can be null when no class was assigned.)</dd>
|
||||
</dl></dd>
|
||||
|
||||
<dt id="markText"><code>markText(from, to, className) → function</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 method will return a
|
||||
function that can be called to remove the marking.</dd>
|
||||
|
||||
<dt id="setMarker"><code>setMarker(line, text, className) → lineHandle</code></dt>
|
||||
<dd>Add a gutter marker for the given line. Gutter markers are
|
||||
shown in the line-number area (instead of the number for this
|
||||
line). Both <code>text</code> and <code>className</code> are
|
||||
optional. Setting <code>text</code> to a Unicode character like
|
||||
● tends to give a nice effect. To put a picture in the gutter,
|
||||
set <code>text</code> to a space and <code>className</code> to
|
||||
something that sets a background image. If you
|
||||
specify <code>text</code>, the given text (which may contain
|
||||
HTML) will, by default, replace the line number for that line.
|
||||
If this is not what you want, you can include the
|
||||
string <code>%N%</code> in the text, which will be replaced by
|
||||
the line number.</dd>
|
||||
<dt id="clearMarker"><code>clearMarker(line)</code></dt>
|
||||
<dd>Clears a marker created
|
||||
with <code>setMarker</code>. <code>line</code> can be either a
|
||||
number or a handle returned by <code>setMarker</code> (since a
|
||||
number may now refer to a different line if something was added
|
||||
or deleted).</dd>
|
||||
<dt id="setLineClass"><code>setLineClass(line, className) → lineHandle</code></dt>
|
||||
<dd>Set a CSS class name for the given line. <code>line</code>
|
||||
can be a number or a line handle (as returned
|
||||
by <code>setMarker</code> or this function).
|
||||
Pass <code>null</code> to clear the class for a line.</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 handle
|
||||
returned by <code>setMarker</code>. The returned object has the
|
||||
structure <code>{line, text, markerText, markerClass}</code>.</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="matchBrackets"><code>matchBrackets()</code></dt>
|
||||
<dd>Force matching-bracket-highlighting to happen.</dd>
|
||||
|
||||
<dt id="lineCount"><code>lineCount() → number</code></dt>
|
||||
<dd>Get the number of lines in the editor.</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.
|
||||
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(start, end)</code></dt>
|
||||
<dd>Set the selection range. <code>start</code>
|
||||
and <code>end</code> should be <code>{line, ch}</code> objects.</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="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.</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>
|
||||
</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="getInputField"><code>getInputField() → textarea</code></dt>
|
||||
<dd>Returns the hiden textarea used to read input.</dd>
|
||||
<dt id="getWrapperElement"><code>getWrapperElement() → node</code></dt>
|
||||
<dd>Returns the DOM node that represents the editor. Remove this
|
||||
from your tree to delete an editor instance.</dd>
|
||||
</dl>
|
||||
|
||||
<p id="fromTextArea">Finally, the <code>CodeMirror</code> object
|
||||
itself has a method <code>fromTextArea</code>. This 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 two
|
||||
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>
|
||||
</dl>
|
||||
|
||||
<h2 id="modeapi">Writing CodeMirror Modes</h2>
|
||||
|
||||
<p>Modes typically consist of a JavaScript file and a CSS file.
|
||||
The CSS file (see, for
|
||||
example <a href="mode/javascript/javascript.css"><code>javascript.css</code></a>)
|
||||
defines the classes that will be used to style the syntactic
|
||||
elements of the code, and the script contains the logic to
|
||||
actually assign these classes to the right pieces of text.</p>
|
||||
|
||||
<p>You'll usually want to use some kind of prefix for your CSS
|
||||
classes, so that they are unlikely to clash with other classes,
|
||||
both those used by other modes and those defined by the page in
|
||||
which CodeMirror is embedded.</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 <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 a 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 can be mutated every time a
|
||||
new token is read.</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
|
||||
CSS class string, or <code>null</code> for tokens that do not have
|
||||
to be styled.<p>
|
||||
|
||||
<p id="StringStream">The stream object 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 <code>undefined</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>undefined</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. 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. Can be used to find out whether a token
|
||||
starts a new line.</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="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
|
||||
(see <a href="#option_enterMode"><code>entermode</code></a>
|
||||
and <a href="#option_tabMode"><code>tabMode</code></a> when they
|
||||
have a value of <code>"indent"</code>), 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/javascript/javascript.js">JavaScript
|
||||
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>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>Finally, it is possible 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>
|
||||
|
||||
</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="#styling">Customized Styling</a></li>
|
||||
<li><a href="#api">Programming API</a></li>
|
||||
<li><a href="#modeapi">Writing CodeMirror Modes</a></li>
|
||||
</ul>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div style="height: 2em"> </div>
|
||||
|
||||
<script type="text/javascript" src="css/font.js"></script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user