123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007 |
- <!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="../addon/runmode/runmode.js"></script>
- <script src="../addon/runmode/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>
- <style>
- dt { text-indent: -1.5em; padding-left: 1.5em; }
- </style>
- </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 <a href="#CodeMirror"><code>CodeMirror</code></a> 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 <a href="#CodeMirror"><code>CodeMirror</code></a>
- 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 <a href="#defaults"><code>CodeMirror.defaults</code></a>, 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><strong>value</strong>: string|CodeMirror.Doc</code></dt>
- <dd>The starting value of the editor. Can be a string, or
- a <a href="#api_doc">document object</a>.</dd>
- <dt id="option_mode"><code><strong>mode</strong>: string|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><strong>theme</strong>: 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><strong>indentUnit</strong>: 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><strong>smartIndent</strong>: 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><strong>tabSize</strong>: integer</code></dt>
- <dd>The width of a tab character. Defaults to 4.</dd>
- <dt id="option_indentWithTabs"><code><strong>indentWithTabs</strong>: 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><strong>electricChars</strong>: 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><strong>rtlMoveVisually</strong>: 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><strong>keyMap</strong>: 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><strong>extraKeys</strong>: 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><strong>lineWrapping</strong>: 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><strong>lineNumbers</strong>: boolean</code></dt>
- <dd>Whether to show line numbers to the left of the editor.</dd>
- <dt id="option_firstLineNumber"><code><strong>firstLineNumber</strong>: integer</code></dt>
- <dd>At which number to start counting lines. Default is 1.</dd>
- <dt id="option_lineNumberFormatter"><code><strong>lineNumberFormatter</strong>: function(line: integer) → string</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><strong>gutters</strong>: array<string></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_fixedGutter"><code><strong>fixedGutter</strong>: boolean</code></dt>
- <dd>Determines whether the gutter scrolls along with the content
- horizontally (false) or whether it stays fixed during horizontal
- scrolling (true, the default).</dd>
- <dt id="option_coverGutterNextToScrollbar"><code><strong>coverGutterNextToScrollbar</strong>: boolean</code></dt>
- <dd>When <a href="#option_fixedGutter"><code>fixedGutter</code></a>
- is on, and there is a horizontal scrollbar, by default the
- gutter will be visible to the left of this scrollbar. If this
- option is set to true, it will be covered by an element with
- class <code>CodeMirror-gutter-filler</code>.</dd>
- <dt id="option_readOnly"><code><strong>readOnly</strong>: boolean|string</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><strong>showCursorWhenSelecting</strong>: boolean</code></dt>
- <dd>Whether the cursor should be drawn when a selection is
- active. Defaults to false.</dd>
- <dt id="option_undoDepth"><code><strong>undoDepth</strong>: integer</code></dt>
- <dd>The maximum number of undo levels that the editor stores.
- Defaults to 40.</dd>
- <dt id="option_historyEventDelay"><code><strong>historyEventDelay</strong>: integer</code></dt>
- <dd>The period of inactivity (in milliseconds) that will cause a
- new history event to be started when typing or deleting.
- Defaults to 500.</dd>
- <dt id="option_tabindex"><code><strong>tabindex</strong>: 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><strong>autofocus</strong>: 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><strong>dragDrop</strong>: boolean</code></dt>
- <dd>Controls whether drag-and-drop is enabled. On by default.</dd>
- <dt id="option_onDragEvent"><code><strong>onDragEvent</strong>: function(instance: CodeMirror, event: Event) → boolean</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><strong>onKeyEvent</strong>: function(instance: CodeMirror, event: Event) → boolean</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><strong>cursorBlinkRate</strong>: number</code></dt>
- <dd>Half-period in milliseconds used for cursor blinking. The default blink
- rate is 530ms.</dd>
- <dt id="option_cursorScrollMargin"><code><strong>cursorScrollMargin</strong>: number</code></dt>
- <dd>How much extra space to always keep above and below the
- cursor when approaching the top or bottom of the visible view in
- a scrollable document. Default is 0.</dd>
- <dt id="option_cursorHeight"><code><strong>cursorHeight</strong>: 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><strong>workTime</strong>, <strong>workDelay</strong>: 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_workDelay"><code><strong>workDelay</strong>: number</code></dt>
- <dd>See <a href="#option_workTime"><code>workTime</code></a>.</dd>
- <dt id="option_pollInterval"><code><strong>pollInterval</strong>: 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><strong>flattenSpans</strong>: 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_maxHighlightLength"><code><strong>maxHighlightLength</strong>: number</code></dt>
- <dd>When highlighting long lines, in order to stay responsive,
- the editor will give up and simply style the rest of the line as
- plain text when it reaches a certain position. The default is
- 10000. You can set this to <code>Infinity</code> to turn off
- this behavior.</dd>
- <dt id="option_viewportMargin"><code><strong>viewportMargin</strong>: 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, 10. 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><strong>"change"</strong> (instance: CodeMirror, changeObj: object)</code></dt>
- <dd>Fires every time the content of the editor is changed.
- The <code>changeObj</code> is a <code>{from, to, text, removed,
- 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). <code>removed</code> is the text
- that used to be between <code>from</code> and <code>to</code>,
- which is overwritten by this change. 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_beforeChange"><code><strong>"beforeChange"</strong> (instance: CodeMirror, changeObj: object)</code></dt>
- <dd>This event is fired before a change is applied, and its
- handler may choose to modify or cancel the change.
- The <code>changeObj</code> object
- has <code>from</code>, <code>to</code>, and <code>text</code>
- properties, as with
- the <a href="#event_change"><code>"change"</code></a> event, but
- never a <code>next</code> property, since this is fired for each
- individual change, and not batched per operation. It also
- has <code>update(from, to, text)</code>
- and <code>cancel()</code> methods, which may be used to modify
- or cancel the change. All three arguments to <code>update</code>
- are optional, and can be left off to leave the existing value
- for that field intact. <strong>Note:</strong> you may not do
- anything from a <code>"beforeChange"</code> handler that would
- cause changes to the document or its visualization. Doing so
- will, since this handler is called directly from the bowels of
- the CodeMirror implementation, probably cause the editor to
- become corrupted.</dd>
- <dt id="event_cursorActivity"><code><strong>"cursorActivity"</strong> (instance: CodeMirror)</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_beforeSelectionChange"><code><strong>"beforeSelectionChange"</strong> (instance: CodeMirror, selection: {head, anchor})</code></dt>
- <dd>This event is fired before the selection is moved. Its
- handler may modify the resulting selection head and anchor.
- The <code>selection</code> parameter is an object
- with <code>head</code> and <code>anchor</code> properties
- holding <code>{line, ch}</code> objects, which the handler can
- read and update. Handlers for this event have the same
- restriction
- as <a href="#event_beforeChange"><code>"beforeChange"</code></a>
- handlers — they should not do anything to directly update the
- state of the editor.</dd>
- <dt id="event_viewportChange"><code><strong>"viewportChange"</strong> (instance: CodeMirror, from: number, to: number)</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><strong>"gutterClick"</strong> (instance: CodeMirror, line: integer, gutter: string, clickEvent: Event)</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><strong>"focus"</strong> (instance: CodeMirror)</code></dt>
- <dd>Fires whenever the editor is focused.</dd>
- <dt id="event_blur"><code><strong>"blur"</strong> (instance: CodeMirror)</code></dt>
- <dd>Fires whenever the editor is unfocused.</dd>
- <dt id="event_scroll"><code><strong>"scroll"</strong> (instance: CodeMirror)</code></dt>
- <dd>Fires when the editor is scrolled.</dd>
- <dt id="event_update"><code><strong>"update"</strong> (instance: CodeMirror)</code></dt>
- <dd>Will be fired whenever CodeMirror updates its DOM display.</dd>
- <dt id="event_renderLine"><code><strong>"renderLine"</strong> (instance: CodeMirror, line: LineHandle, element: Element)</code></dt>
- <dd>Fired whenever a line is (re-)rendered to the DOM. Fired
- right after the DOM element is built, <em>before</em> it is
- added to the document. The handler may mess with the style of
- the resulting element, or add event handlers, but
- should <em>not</em> try to change the state of the editor.</dd>
- </dl>
- <p>It is also possible to <a href="#on">register</a> events on
- other objects. Use <code>CodeMirror.on(handle, "eventName",
- func)</code> to register handlers on objects that don't have their
- own <code>on</code> method. Document objects (instances
- of <a href="#Doc"><code>CodeMirror.Doc</code></a>) emit the
- following events:</p>
- <dl>
- <dt id="event_doc_change"><code><strong>"change"</strong> (doc: CodeMirror.Doc, changeObj: object)</code></dt>
- <dd>Fired whenever a change occurs to the
- document. <code>changeObj</code> has a similar type as the
- object passed to the
- editor's <a href="#event_change"><code>"change"</code></a>
- event, but it never has a <code>next</code> property, because
- document change events are not batched (whereas editor change
- events are).</dd>
- <dt id="event_doc_beforeChange"><code><strong>"beforeChange"</strong> (doc: CodeMirror.Doc, change: object)</code></dt>
- <dd>See the <a href="#event_beforeChange">description of the
- same event</a> on editor instances.</dd>
- <dt id="event_doc_cursorActivity"><code><strong>"cursorActivity"</strong> (doc: CodeMirror.Doc)</code></dt>
- <dd>Fired whenever the cursor or selection in this document
- changes.</dd>
- <dt id="event_doc_beforeSelectionChange"><code><strong>"beforeSelectionChange"</strong> (doc: CodeMirror.Doc, selection: {head, anchor})</code></dt>
- <dd>Equivalent to
- the <a href="#event_beforeSelectionChange">event by the same
- name</a> as fired on editor instances.</dd>
- </dl>
- <p>Line handles (as returned by, for
- example, <a href="#getLineHandle"><code>getLineHandle</code></a>)
- support these events:</p>
- <dl>
- <dt id="event_delete"><code><strong>"delete"</strong> ()</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><strong>"change"</strong> (line: LineHandle, changeObj: object)</code></dt>
- <dd>Fires when the line's text content is changed in any way
- (but the line is not deleted outright). The <code>change</code>
- object is similar to the one passed
- to <a href="#event_change">change event</a> on the editor
- object.</dd>
- </dl>
- <p>Marked range handles (<code>CodeMirror.TextMarker</code>), as returned
- by <a href="#markText"><code>markText</code></a>
- and <a href="#setBookmark"><code>setBookmark</code></a>, emit the
- following events:</p>
- <dl>
- <dt id="event_beforeCursorEnter"><code><strong>"beforeCursorEnter"</strong> ()</code></dt>
- <dd>Fired when the cursor enters the marked range. From this
- event handler, the editor state may be inspected
- but <em>not</em> modified, with the exception that the range on
- which the event fires may be cleared.</dd>
- <dt id="event_clear"><code><strong>"clear"</strong> ()</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>
- <dt id="event_hide"><code><strong>"hide"</strong> ()</code></dt>
- <dd>Fired when the last part of the marker is removed from the
- document by editing operations.</dd>
- <dt id="event_unhide"><code><strong>"unhide"</strong> ()</code></dt>
- <dd>Fired when, after the marker was removed by editing, a undo
- operation brought the marker back.</dd>
- </dl>
- <p>Line widgets (<code>CodeMirror.LineWidget</code>), returned
- by <a href="#addLineWidget"><code>addLineWidget</code></a>, fire
- these events:</p>
- <dl>
- <dt id="event_redraw"><code><strong>"redraw"</strong> ()</code></dt>
- <dd>Fired whenever the editor re-adds the widget to the DOM.
- This will happen once right after the widget is added (if it is
- scrolled into view), and then again whenever it is scrolled out
- of view and back in again, or when changes to the editor options
- or the line the widget is on require the widget to be
- redrawn.</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>Common example: map the Tab key to insert spaces instead of a tab
- character.</p>
- <pre data-lang="javascript">
- {
- Tab: function(cm) {
- var spaces = Array(cm.getOption("indentUnit") + 1).join(" ");
- cm.replaceSelection(spaces, "end", "+input");
- }
- }</pre>
- <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 return <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><strong>CodeMirror</strong></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><strong>CodeMirror-scroll</strong></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><strong>CodeMirror-focused</strong></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><strong>CodeMirror-gutters</strong></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><strong>CodeMirror-linenumbers</strong></code></dt>
- <dd>Use this for giving a background or width to the line number
- gutter.</dd>
- <dt id="class_CodeMirror_linenumber"><code><strong>CodeMirror-linenumber</strong></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><strong>CodeMirror-lines</strong></code></dt>
- <dd>The visible lines. This is where you specify vertical
- padding for the editor content.</dd>
- <dt id="class_CodeMirror_cursor"><code><strong>CodeMirror-cursor</strong></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><strong>CodeMirror-selected</strong></code></dt>
- <dd>The selection is represented by <code>span</code> elements
- with this class.</dd>
- <dt id="class_CodeMirror_matchingbracket"><code><strong>CodeMirror-matchingbracket</strong></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>
- <p>Methods prefixed with <code>doc.</code> can, unless otherwise
- specified, be called both on <code>CodeMirror</code> (editor)
- instances and <code>CodeMirror.Doc</code> instances. Methods
- prefixed with <code>cm.</code> are <em>only</em> available
- on <code>CodeMirror</code> instances.</p>
- <h3 id="api_constructor">Constructor</h3>
- <p id="CodeMirror">Constructing an editor instance is done with
- the <code><strong>CodeMirror</strong>(place: Element|fn(Element),
- ?option: object)</code> constructor. If the <code>place</code>
- argument is a DOM element, the editor will be appended to it. If
- it is a function, it will be called, and is expected to place the
- editor into the document. <code>options</code> may be an element
- mapping <a href="#config">option names</a> to values. The options
- that it doesn't explicitly specify (or all options, if it is not
- passed) will be taken
- from <a href="#defaults"><code>CodeMirror.defaults</code></a>.</p>
- <p>Note that the options object passed to the constructor will be
- mutated when the instance's options
- are <a href="#setOption">changed</a>, so you shouldn't share such
- objects between instances.</p>
- <p>See <a href="#fromTextArea"><code>CodeMirror.fromTextArea</code></a>
- for another way to construct an editor instance.</p>
- <h3 id="api_content">Content manipulation methods</h3>
- <dl>
- <dt id="getValue"><code><strong>doc.getValue</strong>(?seperator: string) → 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><strong>doc.setValue</strong>(content: string)</code></dt>
- <dd>Set the editor content.</dd>
- <dt id="getRange"><code><strong>doc.getRange</strong>(from: {line, ch}, to: {line, ch}, ?seperator: string) → string</code></dt>
- <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><strong>doc.replaceRange</strong>(replacement: string, from: {line, ch}, to: {line, ch})</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="getLine"><code><strong>doc.getLine</strong>(n: integer) → string</code></dt>
- <dd>Get the content of line <code>n</code>.</dd>
- <dt id="setLine"><code><strong>doc.setLine</strong>(n: integer, text: string)</code></dt>
- <dd>Set the content of line <code>n</code>.</dd>
- <dt id="removeLine"><code><strong>doc.removeLine</strong>(n: integer)</code></dt>
- <dd>Remove the given line from the document.</dd>
- <dt id="lineCount"><code><strong>doc.lineCount</strong>() → integer</code></dt>
- <dd>Get the number of lines in the editor.</dd>
- <dt id="firstLine"><code><strong>doc.firstLine</strong>() → integer</code></dt>
- <dd>Get the first line of the editor. This will
- usually be zero but for <a href="#linkedDoc_from">linked sub-views</a>,
- or <a href="#api_doc">documents</a> instantiated with a non-zero
- first line, it might return other values.</dd>
- <dt id="lastLine"><code><strong>doc.lastLine</strong>() → integer</code></dt>
- <dd>Get the last line of the editor. This will
- usually be <code>doc.lineCount() - 1</code>,
- but for <a href="#linkedDoc_from">linked sub-views</a>,
- it might return other values.</dd>
- <dt id="getLineHandle"><code><strong>doc.getLineHandle</strong>(num: integer) → LineHandle</code></dt>
- <dd>Fetches the line handle for the given line number.</dd>
- <dt id="getLineNumber"><code><strong>doc.getLineNumber</strong>(handle: LineHandle) → 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="eachLine"><code><strong>doc.eachLine</strong>(f: (line: LineHandle))</code></dt>
- <dt><code><strong>doc.eachLine</strong>(start: integer, end: integer, f: (line: LineHandle))</code></dt>
- <dd>Iterate over the whole document, or if <code>start</code>
- and <code>end</code> line numbers are given, the range
- from <code>start</code> up to (not including) <code>end</code>,
- and call <code>f</code> for each line, passing the line handle.
- This is a faster way to visit a range of line handlers than
- calling <a href="#getLineHandle"><code>getLineHandle</code></a>
- for each of them. Note that line handles have
- a <code>text</code> property containing the line's content (as a
- string).</dd>
- <dt id="markClean"><code><strong>doc.markClean</strong>()</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><strong>doc.isClean</strong>() → 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>
- </dl>
- <h3 id="api_selection">Cursor and selection methods</h3>
- <dl>
- <dt id="getSelection"><code><strong>doc.getSelection</strong>() → string</code></dt>
- <dd>Get the currently selected code.</dd>
- <dt id="replaceSelection"><code><strong>doc.replaceSelection</strong>(replacement: string, ?collapse: string)</code></dt>
- <dd>Replace the selection with the given string. By default, the
- new selection will span the inserted text. The
- optional <code>collapse</code> argument can be used to change
- this—passing <code>"start"</code> or <code>"end"</code> will
- collapse the selection to the start or end of the inserted
- text.</dd>
- <dt id="getCursor"><code><strong>doc.getCursor</strong>(?start: string) → {line, ch}</code></dt>
- <dd><code>start</code> is a an optional string indicating which
- end of the selection to return. It may
- be <code>"start"</code>, <code>"end"</code>, <code>"head"</code>
- (the side of the selection that moves when you press
- shift+arrow), or <code>"anchor"</code> (the fixed side of the
- selection). Omitting the argument is the same as
- passing <code>"head"</code>. A <code>{line, ch}</code> object
- will be returned.</dd>
- <dt id="somethingSelected"><code><strong>doc.somethingSelected</strong>() → boolean</code></dt>
- <dd>Return true if any text is selected.</dd>
- <dt id="setCursor"><code><strong>doc.setCursor</strong>(pos: {line, ch})</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><strong>doc.setSelection</strong>(anchor: {line, ch}, head: {line, ch})</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 given.</dd>
- <dt id="extendSelection"><code><strong>doc.extendSelection</strong>(from: {line, ch}, ?to: {line, ch})</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><strong>doc.setExtending</strong>(value: boolean)</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="hasFocus"><code><strong>cm.hasFocus</strong>() → boolean</code></dt>
- <dd>Tells you whether the editor currently has focus.</dd>
- <dt id="findPosH"><code><strong>cm.findPosH</strong>(start: {line, ch}, amount: integer, unit: string, visually: boolean) → {line, ch, ?hitSide: boolean}</code></dt>
- <dd>Used to find the target position for horizontal cursor
- motion. <code>start</code> is a <code>{line, ch}</code>
- object, <code>amount</code> an integer (may be negative),
- and <code>unit</code> one of the
- string <code>"char"</code>, <code>"column"</code>,
- or <code>"word"</code>. Will return a position that is produced
- by moving <code>amount</code> times the distance specified
- by <code>unit</code>. When <code>visually</code> is true, motion
- in right-to-left text will be visual rather than logical. When
- the motion was clipped by hitting the end or start of the
- document, the returned value will have a <code>hitSide</code>
- property set to true.</dd>
- <dt id="findPosV"><code><strong>cm.findPosV</strong>(start: {line, ch}, amount: integer, unit: string) → {line, ch, ?hitSide: boolean}</code></dt>
- <dd>Similar to <a href="#findPosH"><code>findPosH</code></a>,
- but used for vertical motion. <code>unit</code> may
- be <code>"line"</code> or <code>"page"</code>. The other
- arguments and the returned value have the same interpretation as
- they have in <code>findPosH</code>.</dd>
- </dl>
- <h3 id="api_configuration">Configuration methods</h3>
- <dl>
- <dt id="setOption"><code><strong>cm.setOption</strong>(option: string, value: any)</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><strong>cm.getOption</strong>(option: string) → any</code></dt>
- <dd>Retrieves the current value of the given option for this
- editor instance.</dd>
- <dt id="addKeyMap"><code><strong>cm.addKeyMap</strong>(map: object, bottom: boolean)</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 higher precedence than
- the <code>extraKeys</code>
- and <a href="#option_keyMap"><code>keyMap</code></a> options,
- and between them, the maps added earlier have a lower precedence
- than those added later, unless the <code>bottom</code> argument
- was passed, in which case they end up below other keymaps added
- with this method.</dd>
- <dt id="removeKeyMap"><code><strong>cm.removeKeyMap</strong>(map: object)</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><strong>cm.addOverlay</strong>(mode: string|object, ?options: object)</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>options</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><strong>cm.removeOverlay</strong>(mode: string|object)</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><strong>cm.on</strong>(type: string, func: (...args))</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><strong>cm.off</strong>(type: string, func: (...args))</code></dt>
- <dd>Remove an event handler on the editor instance. An
- equivalent <code>CodeMirror.off(object, type,
- func)</code> also exists.</dd>
- </dl>
- <h3 id="api_doc">Document management methods</h3>
- <p id="Doc">Each editor is associated with an instance
- of <code>CodeMirror.Doc</code>, its document. A document
- represents the editor content, plus a selection, an undo history,
- and a <a href="#option_mode">mode</a>. A document can only be
- associated with a single editor at a time. You can create new
- documents by calling the <code>CodeMirror.Doc(text, mode,
- firstLineNumber)</code> constructor. The last two arguments are
- optional and can be used to set a mode for the document and make
- it start at a line number other than 0, respectively.</p>
- <dl>
- <dt id="getDoc"><code><strong>cm.getDoc</strong>() → Doc</code></dt>
- <dd>Retrieve the currently active document from an editor.</dd>
- <dt id="getEditor"><code><strong>doc.getEditor</strong>() → CodeMirror</code></dt>
- <dd>Retrieve the editor associated with a document. May
- return <code>null</code>.</dd>
- <dt id="swapDoc"><code><strong>cm.swapDoc</strong>(doc: CodeMirror.Doc) → Doc</code></dt>
- <dd>Attach a new document to the editor. Returns the old
- document, which is now no longer associated with an editor.</dd>
- <dt id="copy"><code><strong>doc.copy</strong>(copyHistory: boolean) → Doc</code></dt>
- <dd>Create an identical copy of the given doc.
- When <code>copyHistory</code> is true, the history will also be
- copied. Can not be called directly on an editor.</dd>
- <dt id="linkedDoc"><code><strong>doc.linkedDoc</strong>(options: object) → Doc</code></dt>
- <dd>Create a new document that's linked to the target document.
- Linked documents will stay in sync (changes to one are also
- applied to the other) until <a href="#unlinkDoc">unlinked</a>.
- These are the options that are supported:
- <dl>
- <dt id="linkedDoc_sharedHist"><code><strong>sharedHist</strong>: boolean</code></dt>
- <dd>When turned on, the linked copy will share an undo
- history with the original. Thus, something done in one of
- the two can be undone in the other, and vice versa.</dd>
- <dt id="linkedDoc_from"><code><strong>from</strong>: integer</code></dt>
- <dt id="linkedDoc_to"><code><strong>to</strong>: integer</code></dt>
- <dd>Can be given to make the new document a subview of the
- original. Subviews only show a given range of lines. Note
- that line coordinates inside the subview will be consistent
- with those of the parent, so that for example a subview
- starting at line 10 will refer to its first line as line 10,
- not 0.</dd>
- <dt id="linkedDoc_mode"><code><strong>mode</strong>: string|object</code></dt>
- <dd>By default, the new document inherits the mode of the
- parent. This option can be set to
- a <a href="#option_mode">mode spec</a> to give it a
- different mode.</dd>
- </dl></dd>
- <dt id="unlinkDoc"><code><strong>doc.unlinkDoc</strong>(doc: CodeMirror.Doc)</code></dt>
- <dd>Break the link between two documents. After calling this,
- changes will no longer propagate between the documents, and, if
- they had a shared history, the history will become
- separate.</dd>
- <dt id="iterLinkedDocs"><code><strong>doc.iterLinkedDocs</strong>(function: (doc: CodeMirror.Doc, sharedHist: boolean))</code></dt>
- <dd>Will call the given function for all documents linked to the
- target document. It will be passed two arguments, the linked document
- and a boolean indicating whether that document shares history
- with the target.</dd>
- </dl>
- <h3 id="api_history">History-related methods</h3>
- <dl>
- <dt id="undo"><code><strong>doc.undo</strong>()</code></dt>
- <dd>Undo one edit (if any undo events are stored).</dd>
- <dt id="redo"><code><strong>doc.redo</strong>()</code></dt>
- <dd>Redo one undone edit.</dd>
- <dt id="historySize"><code><strong>doc.historySize</strong>() → {undo: integer, redo: integer}</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><strong>doc.clearHistory</strong>()</code></dt>
- <dd>Clears the editor's undo history.</dd>
- <dt id="getHistory"><code><strong>doc.getHistory</strong>() → object</code></dt>
- <dd>Get a (JSON-serializeable) representation of the undo history.</dd>
- <dt id="setHistory"><code><strong>doc.setHistory</strong>(history: 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>
- </dl>
- <h3 id="api_marker">Text-marking methods</h3>
- <dl>
- <dt id="markText"><code><strong>doc.markText</strong>(from: {line, ch}, to: {line, ch}, ?options: object) → TextMarker</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><strong>className</strong>: string</code></dt>
- <dd>Assigns a CSS class to the marked stretch of text.</dd>
- <dt id="mark_inclusiveLeft"><code><strong>inclusiveLeft</strong>: 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><strong>inclusiveRight</strong>: boolean</code></dt>
- <dd>Like <code>inclusiveLeft</code>,
- but for the right side.</dd>
- <dt id="mark_atomic"><code><strong>atomic</strong>: 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><strong>collapsed</strong>: 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><strong>clearOnEnter</strong>: 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. 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><strong>replacedWith</strong>: Element</code></dt>
- <dd>Use a given node to display this range. Implies both
- collapsed and atomic. The given DOM node <em>must</em> be an
- inline element (as opposed to a block element).</dd>
- <dt id="mark_readOnly"><code><strong>readOnly</strong>: boolean</code></dt>
- <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_addToHistory"><code><strong>addToHistory</strong>: boolean</code></dt>
- <dd>When set to true (default is false), adding this marker
- will create an event in the undo history that can be
- individually undone (clearing the marker).</dd>
- <dt id="mark_startStyle"><code><strong>startStyle</strong>: string</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><strong>endStyle</strong>: string</code></dt><dd>Equivalent
- to <code>startStyle</code>, but for the rightmost span.</dd>
- <dt id="mark_shared"><code><strong>shared</strong>: boolean</code></dt><dd>When the
- target document is <a href="#linkedDoc">linked</a> to other
- documents, you can set <code>shared</code> to true to make the
- marker appear in all documents. By default, a marker appears
- only in its target document.</dd>
- </dl>
- The method will return an object that represents the marker
- (with constuctor <code>CodeMirror.TextMarker</code>), which
- exposes three methods:
- <code><strong>clear</strong>()</code>, to remove the mark,
- <code><strong>find</strong>()</code>, which returns
- a <code>{from, to}</code> object (both holding document
- positions), indicating the current position of the marked range,
- or <code>undefined</code> if the marker is no longer in the
- document, and finally <code><strong>changed</strong>()</code>,
- which you can call if you've done something that might change
- the size of the marker (for example changing the content of
- a <a href="#mark_replacedWith"><code>replacedWith</code></a>
- node), and want to cheaply update the display.</dd>
- <dt id="setBookmark"><code><strong>doc.setBookmark</strong>(pos: {line, ch}, ?options: object) → TextMarker</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 options argument is optional. If given, the following
- properties are recognized:
- <dl>
- <dt><code><strong>widget</strong>: Element</code></dt><dd>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><code><strong>insertLeft</strong>: boolean</code></dt><dd>By default, text typed
- when the cursor is on top of the bookmark will end up to the
- right of the bookmark. Set this option to true to make it go
- to the left instead.</dd>
- </dl></dd>
- <dt id="findMarksAt"><code><strong>doc.findMarksAt</strong>(pos: {line, ch}) → array<TextMarker></code></dt>
- <dd>Returns an array of all the bookmarks and marked ranges
- present at the given position.</dd>
- <dt id="getAllMarks"><code><strong>doc.getAllMarks</strong>() → array<TextMarker></code></dt>
- <dd>Returns an array containing all marked ranges in the document.</dd>
- </dl>
- <h3 id="api_decoration">Widget, gutter, and decoration methods</h3>
-
- <dl>
- <dt id="setGutterMarker"><code><strong>cm.setGutterMarker</strong>(line: integer|LineHandle, gutterID: string, value: Element) → 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><strong>cm.clearGutter</strong>(gutterID: string)</code></dt>
- <dd>Remove all gutter markers in
- the <a href="#option_gutters">gutter</a> with the given ID.</dd>
- <dt id="addLineClass"><code><strong>cm.addLineClass</strong>(line: integer|LineHandle, where: string, class: string) → 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><strong>cm.removeLineClass</strong>(line: integer|LineHandle, where: string, class: string) → 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><strong>cm.lineInfo</strong>(line: integer|LineHandle) → 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="addWidget"><code><strong>cm.addWidget</strong>(pos: {line, ch}, node: Element, scrollIntoView: boolean)</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><strong>cm.addLineWidget</strong>(line: integer|LineHandle, node: Element, ?options: object) → LineWidget</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><strong>coverGutter</strong>: boolean</code></dt>
- <dd>Whether the widget should cover the gutter.</dd>
- <dt><code><strong>noHScroll</strong>: boolean</code></dt>
- <dd>Whether the widget should stay fixed in the face of
- horizontal scrolling.</dd>
- <dt><code><strong>above</strong>: boolean</code></dt>
- <dd>Causes the widget to be placed above instead of below
- the text of the line.</dd>
- <dt><code><strong>showIfHidden</strong>: boolean</code></dt>
- <dd>When true, will cause the widget to be rendered even if
- the line it is associated with is hidden.</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 the following methods:
- <dl>
- <dt id="widget_clear"><code><strong>clear</strong>()</code></dt><dd>Removes the widget.</dd>
- <dt id="widget_changed"><code><strong>changed</strong>()</code></dt><dd>Call
- this if you made some change to the widget's DOM node that
- might affect its height. It'll force CodeMirror to update
- the height of the line that contains the widget.</dd>
- </dl>
- </dd>
- </dl>
- <h3 id="api_sizing">Sizing, scrolling and positioning methods</h3>
- <dl>
- <dt id="setSize"><code><strong>cm.setSize</strong>(width: number|string, height: number|string)</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="scrollTo"><code><strong>cm.scrollTo</strong>(x: number, y: number)</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><strong>cm.getScrollInfo</strong>() → {left, top, width, height, clientWidth, clientHeight}</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><strong>cm.scrollIntoView</strong>(pos: {line, ch}|{left, top, right, bottom}, ?margin: number)</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. The <code>margin</code> parameter is
- optional. When given, it indicates the amount of pixels around
- the given area that should be made visible as well.</dd>
- <dt id="cursorCoords"><code><strong>cm.cursorCoords</strong>(where: boolean|{line, ch}, mode: string) → {left, top, bottom}</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><strong>cm.charCoords</strong>(pos: {line, ch}, mode: string) → {left, right, top, bottom}</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><strong>cm.coordsChar</strong>(object: {left, top}, ?mode: string) → {line, ch}</code></dt>
- <dd>Given an <code>{left, top}</code> object, returns
- the <code>{line, ch}</code> position that corresponds to it. The
- optional <code>mode</code> parameter determines relative to what
- the coordinates are interpreted. It may
- be <code>"window"</code>, <code>"page"</code> (the default),
- or <code>"local"</code>.</dd>
- <dt id="defaultTextHeight"><code><strong>cm.defaultTextHeight</strong>() → number</code></dt>
- <dd>Returns the line height of the default font for the editor.</dd>
- <dt id="defaultCharWidth"><code><strong>cm.defaultCharWidth</strong>() → number</code></dt>
- <dd>Returns the pixel width of an 'x' in the default font for
- the editor. (Note that for non-monospace fonts, this is mostly
- useless, and even for monospace fonts, non-ascii characters
- might have a different width).</dd>
- <dt id="getViewport"><code><strong>cm.getViewport</strong>() → {from: number, to: number}</code></dt>
- <dd>Returns a <code>{from, to}</code> object indicating the
- start (inclusive) and end (exclusive) of the currently rendered
- 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="refresh"><code><strong>cm.refresh</strong>()</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>
- </dl>
- <h3 id="api_mode">Mode, state, and token-related methods</h3>
- <p>When writing language-aware functionality, it can often be
- useful to hook into the knowledge that the CodeMirror language
- mode has. See <a href="#modeapi">the section on modes</a> for a
- more detailed description of how these work.</p>
- <dl>
- <dt id="getMode"><code><strong>doc.getMode</strong>() → 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="getTokenAt"><code><strong>cm.getTokenAt</strong>(pos: {line, ch}) → 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><strong>start</strong></code></dt><dd>The character (on the given line) at which the token starts.</dd>
- <dt><code><strong>end</strong></code></dt><dd>The character at which the token ends.</dd>
- <dt><code><strong>string</strong></code></dt><dd>The token's string.</dd>
- <dt><code><strong>type</strong></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><strong>state</strong></code></dt><dd>The mode's state at the end of this token.</dd>
- </dl></dd>
- <dt id="getStateAfter"><code><strong>cm.getStateAfter</strong>(?line: integer) → object</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>
- <h3 id="api_misc">Miscellaneous methods</h3>
- <dl>
- <dt id="operation"><code><strong>cm.operation</strong>(func: () → any) → any</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="indentLine"><code><strong>cm.indentLine</strong>(line: integer, ?dir: string)</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><strong>"prev"</strong></code></dt>
- <dd>Base indentation on the indentation of the previous line.</dd>
- <dt><code><strong>"smart"</strong></code></dt>
- <dd>Use the mode's smart indentation if available, behave
- like <code>"prev"</code> otherwise.</dd>
- <dt><code><strong>"add"</strong></code></dt>
- <dd>Increase the indentation of the line by
- one <a href="#option_indentUnit">indent unit</a>.</dd>
- <dt><code><strong>"subtract"</strong></code></dt>
- <dd>Reduce the indentation of the line.</dd>
- </dl></dd>
- <dt id="toggleOverwrite"><code><strong>cm.toggleOverwrite</strong>(?value: bool)</code></dt>
- <dd>Switches between overwrite and normal insert mode (when not
- given an argument), or sets the overwrite mode to a specific
- state (when given an argument).</dd>
- <dt id="posFromIndex"><code><strong>doc.posFromIndex</strong>(index: integer) → {line, ch}</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><strong>doc.indexFromPos</strong>(object: {line, ch}) → integer</code></dt>
- <dd>The reverse of <a href="#posFromIndex"><code>posFromIndex</code></a>.</dd>
- <dt id="focus"><code><strong>cm.focus</strong>()</code></dt>
- <dd>Give the editor focus.</dd>
- <dt id="getInputField"><code><strong>cm.getInputField</strong>() → TextAreaElement</code></dt>
- <dd>Returns the hidden textarea used to read input.</dd>
- <dt id="getWrapperElement"><code><strong>cm.getWrapperElement</strong>() → Element</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><strong>cm.getScrollerElement</strong>() → Element</code></dt>
- <dd>Returns the DOM node that is responsible for the scrolling
- of the editor.</dd>
- <dt id="getGutterElement"><code><strong>cm.getGutterElement</strong>() → Element</code></dt>
- <dd>Fetches the DOM node that contains the editor gutters.</dd>
- </dl>
- <h3 id="api_static">Static properties</h3>
- <p>The <code>CodeMirror</code> object itself provides
- several useful properties.</p>
- <dl>
- <dt id="version"><code><strong>CodeMirror.version</strong>: string</code></dt>
- <dd>It 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.</dd>
- <dt id="fromTextArea"><code><strong>CodeMirror.fromTextArea</strong>(textArea: TextAreaElement, ?config: object)</code></dt>
- <dd>
- The 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:
- <dl>
- <dt id="save"><code><strong>cm.save</strong>()</code></dt>
- <dd>Copy the content of the editor into the textarea.</dd>
- <dt id="toTextArea"><code><strong>cm.toTextArea</strong>()</code></dt>
- <dd>Remove the editor, and restore the original textarea (with
- the editor's current content).</dd>
- <dt id="getTextArea"><code><strong>cm.getTextArea</strong>() → TextAreaElement</code></dt>
- <dd>Returns the textarea that the instance was based on.</dd>
- </dl>
- </dd>
- <dt id="defaults"><code><strong>CodeMirror.defaults</strong>: object</code></dt>
- <dd>An object containing default values for
- all <a href="#config">options</a>. You can assign to its
- properties to modify defaults (though this won't affect editors
- that have already been created).</dd>
- <dt id="defineExtension"><code><strong>CodeMirror.defineExtension</strong>(name: string, value: any)</code></dt>
- <dd>If you want to define extra methods in terms of the
- CodeMirror API, it is possible to
- use <code>defineExtension</code>. This will cause the given
- value (usually a method) to be added to all CodeMirror instances
- created from then on.</dd>
- <dt id="defineDocExtension"><code><strong>CodeMirror.defineDocExtension</strong>(name: string, value: any)</code></dt>
- <dd>Like <a href="#defineExtenstion"><code>defineExtension</code></a>,
- but the method will be added to the interface
- for <a href="#Doc"><code>Doc</code></a> objects instead.</dd>
- <dt id="defineOption"><code><strong>CodeMirror.defineOption</strong>(name: string,
- default: any, updateFunc: function)</code></dt>
- <dd>Similarly, <code>defineOption</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>.</dd>
- <dt id="defineInitHook"><code><strong>CodeMirror.defineInitHook</strong>(func: function)</code></dt>
- <dd>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.</dd>
- </dl>
- <h2 id="addons">Add-ons</h2>
- <p>The <code>addon</code> directory in the distribution contains a
- number of reusable components that implement extra editor
- functionality. In brief, they are:</p>
- <dl>
- <dt id="addon_dialog"><a href="../addon/dialog/dialog.js"><code>dialog/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>addon/dialog/dialog.css</code>.</dd>
- <dt id="addon_searchcursor"><a href="../addon/search/searchcursor.js"><code>search/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><strong>findNext</strong>() → boolean</code></dt>
- <dt><code><strong>findPrevious</strong>() → 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><strong>from</strong>() → {line, ch}</code></dt>
- <dt><code><strong>to</strong>() → {line, ch}</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><strong>replace</strong>(text: string)</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="addon_search"><a href="../addon/search/search.js"><code>search/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="#addon_dialog"><code>openDialog</code></a> when
- available to make prompting for search queries less ugly.</dd>
- <dt id="addon_matchbrackets"><a href="../addon/edit/matchbrackets.js"><code>edit/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="addon_closebrackets"><a href="../addon/edit/closebrackets.js"><code>edit/closebrackets.js</code></a></dt>
- <dd>Defines an option <code>autoCloseBrackets</code> that will
- auto-close brackets and quotes when typed. By default, it'll
- auto-close <code>()[]{}''""</code>, but you can pass it a
- string similar to that (containing pairs of matching characters)
- to customize it. <a href="../demo/closebrackets.html">Demo
- here</a>.</dd>
- <dt id="addon_comment"><a href="../addon/comment/comment.js"><code>comment/comment.js</code></a></dt>
- <dd>Addon for commenting and uncommenting code. Adds three
- methods to CodeMirror instances:
- <dl>
- <dt id="lineComment"><code><strong>lineComment</strong>(from: {line, ch}, to: {line, ch}, ?options: object)</code></dt>
- <dd>Set the lines in the given range to be line comments. Will
- fall back to <code>blockComment</code> when no line comment
- style is defined for the mode.</dd>
- <dt id="blockComment"><code><strong>blockComment</strong>(from: {line, ch}, to: {line, ch}, ?options: object)</code></dt>
- <dd>Wrap the code in the given range in a block comment. Will
- fall back to <code>lineComment</code> when no block comment
- style is defined for the mode.</dd>
- <dt id="uncomment"><code><strong>uncomment</strong>(from: {line, ch}, to: {line, ch}, ?options: object) → boolean</code></dt>
- <dd>Try to uncomment the given range.
- Returns <code>true</code> if a comment range was found and
- removed, <code>false</code> otherwise.</dd>
- </dl>
- The <code>options</code> object accepted by these methods may
- have the following properties:
- <dl>
- <dt><code>blockCommentStart, blockCommentEnd, blockCommentLead, lineComment: string</code></dt>
- <dd>Override the <a href="#mode_comment">comment string
- properties</a> of the mode with custom comment strings.</dd>
- <dt><code>padding</code></dt>
- <dd>A string that will be inserted after opening and before
- closing comment markers. Defaults to a single space.</dd>
- <dt><code>commentBlankLines</code></dt>
- <dd>Whether, when adding line comments, to also comment lines
- that contain only whitespace.</dd>
- <dt><code>indent</code></dt>
- <dd>When adding line comments and this is turned on, it will
- align the comment block to the current indentation of the
- first line of the block.</dd>
- <dt><code>fullLines</code></dt>
- <dd>When block commenting, this controls whether the whole
- lines are indented, or only the precise range that is given.
- Defaults to <code>true</code>.</dd>
- </dl>
- The addon also defines
- a <code>toggleComment</code> <a href="#commands">command</a>,
- which will try to uncomment the current selection, and if that
- fails, line-comments it.</dd>
- <dt id="addon_foldcode"><a href="../addon/fold/foldcode.js"><code>fold/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. There are files in
- the <a href="../addon/fold/"><code>addon/fold/</code></a>
- directory providing <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="addon_runmode"><a href="../addon/runmode/runmode.js"><code>runmode/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.
- There are alternate versions of the file avaible for
- running <a href="../addon/runmode/runmode-standalone.js">stand-alone</a>
- (without including all of CodeMirror) and
- for <a href="../addon/runmode/runmode.node.js">running under
- node.js</a>.</dd>
- <dt id="addon_overlay"><a href="../addon/mode/overlay.js"><code>mode/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="addon_multiplex"><a href="../addon/mode/multiplex.js"><code>mode/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="addon_show-hint"><a href="../addon/hint/show-hint.js"><code>hint/show-hint.js</code></a></dt>
- <dd>Provides a framework for showing autocompletion hints.
- Defines <code>CodeMirror.showHint</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>addon/hint/show-hint.css</code>. See the other files in
- the <a href="../addon/hint/"><code>addon/hint</code></a> for
- hint sources for various languages. Check
- out <a href="../demo/complete.html">the demo</a> for an
- example.</dd>
- <dt id="addon_match-highlighter"><a href="../addon/search/match-highlighter.js"><code>match-highlighter.js</code></a></dt>
- <dd>Adds a <code>highlightSelectionMatches</code> option that
- can be enabled to highlight all instances of a currently
- selected word.
- Demo <a href="../demo/matchhighlighter.html">here</a>.</dd>
- <dt id="addon_lint"><a href="../addon/lint/lint.js"><code>lint/lint.js</code></a></dt>
- <dd>Defines an interface component for showing linting warnings,
- with pluggable warning sources
- (see <a href="../addon/lint/json-lint.js"><code>json-lint.js</code></a>
- and <a href="../addon/lint/javascript-lint.js"><code>javascript-lint.js</code></a>
- in the same directory). Defines a <code>lintWith</code> option
- that can be set to a warning source (for
- example <code>CodeMirror.javascriptValidator</code>). Depends
- on <code>addon/lint/lint.css</code>. A demo can be
- found <a href="../demo/lint.html">here</a>.</dd>
- <dt id="addon_mark-selection"><a href="../addon/selection/mark-selection.js"><code>selection/mark-selection.js</code></a></dt>
- <dd>Causes the selected text to be marked with the CSS class
- <code>CodeMirror-selectedtext</code> when the <code>styleSelectedText</code> option
- is enabled. Useful to change the colour of the selection (in addition to the background),
- like in <a href="../demo/markselection.html">this demo</a>.</dd>
- <dt id="addon_active-line"><a href="../addon/selection/active-line.js"><code>selection/active-line.js</code></a></dt>
- <dd>Defines a <code>styleActiveLine</code> option that, when enabled,
- gives the wrapper of the active line the class <code>CodeMirror-activeline</code>,
- and adds a background with the class <code>CodeMirror-activeline-background</code>.
- is enabled. See the <a href="../demo/activeline.html">demo</a>.</dd>
- <dt id="addon_closetag"><a href="../addon/edit/closetag.js"><code>edit/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="addon_loadmode"><a href="../addon/mode/loadmode.js"><code>mode/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="addon_continuecomment"><a href="../addon/edit/continuecomment.js"><code>edit/continuecomment.js</code></a></dt>
- <dd>Adds an <code>continueComments</code> option, which can be
- set to true to have the editor prefix new lines inside C-like
- block comments with an asterisk when Enter is pressed. It can
- also be set to a string in order to bind this functionality to a
- specific key..</dd>
- <dt id="addon_placeholder"><a href="../addon/display/placeholder.js"><code>display/placeholder.js</code></a></dt>
- <dd>Adds a <code>placeholder</code> option that can be used to
- make text appear in the editor when it is empty and not focused.
- Also gives the editor a <code>CodeMirror-empty</code> CSS class
- whenever it doesn't contain any text.
- See <a href="../demo/placeholder.html">the demo</a>.</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><strong></strong><strong>eol</strong>() → boolean</code></dt>
- <dd>Returns true only if the stream is at the end of the
- line.</dd>
- <dt><code><strong></strong><strong>sol</strong>() → boolean</code></dt>
- <dd>Returns true only if the stream is at the start of the
- line.</dd>
- <dt><code><strong>peek</strong>() → string</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><strong>next</strong>() → string</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><strong>eat</strong>(match: string|regexp|function(char: string) → boolean) → string</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><strong>eatWhile</strong>(match: string|regexp|function(char: string) → boolean) → 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><strong>eatSpace</strong>() → boolean</code></dt>
- <dd>Shortcut for <code>eatWhile</code> when matching
- white-space.</dd>
- <dt><code><strong>skipToEnd</strong>()</code></dt>
- <dd>Moves the position to the end of the line.</dd>
- <dt><code><strong>skipTo</strong>(ch: string) → 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><strong>match</strong>(pattern: string, ?consume: boolean, ?caseFold: boolean) → boolean</code></dt>
- <dt><code><strong>match</strong>(pattern: regexp, ?consume: boolean) → array<string></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><strong>backUp</strong>(n: integer)</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><strong>column</strong>() → integer</code></dt>
- <dd>Returns the column (taking into account tabs) at which the
- current token starts.</dd>
- <dt><code><strong>indentation</strong>() → integer</code></dt>
- <dd>Tells you how far the current line has been indented, in
- spaces. Corrects for tab characters.</dd>
- <dt><code><strong>current</strong>() → 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, to which keys can be
- <a href="#option_extraKeys">bound</a>), 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. An indentation method may
- return <code>CodeMirror.Pass</code> to indicate that it
- could not come up with a precise indentation.</p>
- <p id="mode_comment">To work well with
- the <a href="#addon_comment">commenting addon</a>, a mode may
- define <code>lineComment</code> (string that starts a line
- comment), <code>blockCommentStart</code>, <code>blockCommentEnd</code>
- (strings that start and end block comments),
- and <code>blockCommentLead</code> (a string to put at the start of
- continued lines in a block comment). All of these are
- optional.</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="#addon_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>
- <ul>
- <li><a href="#constructor">Constructor</a></li>
- <li><a href="#api_content">Content manipulation</a></li>
- <li><a href="#api_selection">Selection</a></li>
- <li><a href="#api_configuration">Configuration</a></li>
- <li><a href="#api_doc">Document management</a></li>
- <li><a href="#api_history">History</a></li>
- <li><a href="#api_marker">Text-marking</a></li>
- <li><a href="#api_decoration">Widget, gutter, and decoration</a></li>
- <li><a href="#api_sizing">Sizing, scrolling, and positioning</a></li>
- <li><a href="#api_mode">Mode, state, and tokens</a></li>
- <li><a href="#api_misc">Miscellaneous methods</a></li>
- <li><a href="#api_static">Static properties</a></li>
- </ul>
- </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>
|