manual.html (203470B)
1 <!doctype html> 2 3 <title>CodeMirror: User Manual</title> 4 <meta charset="utf-8"/> 5 <link rel=stylesheet href="docs.css"> 6 <script src="activebookmark.js"></script> 7 8 <script src="../lib/codemirror.js"></script> 9 <link rel="stylesheet" href="../lib/codemirror.css"> 10 <script src="../addon/runmode/runmode.js"></script> 11 <script src="../addon/runmode/colorize.js"></script> 12 <script src="../mode/javascript/javascript.js"></script> 13 <script src="../mode/xml/xml.js"></script> 14 <script src="../mode/css/css.js"></script> 15 <script src="../mode/htmlmixed/htmlmixed.js"></script> 16 <style> 17 dt { text-indent: -2em; padding-left: 2em; margin-top: 1em; } 18 dd { margin-left: 1.5em; margin-bottom: 1em; } 19 dt {margin-top: 1em;} 20 dd dl, dd dt, dd dd, dd ul { margin-top: 0; margin-bottom: 0; } 21 dt + dt { margin-top: 0; } 22 dt.command { position: relative; } 23 span.keybinding { position: absolute; right: 0; font-size: 80%; color: #555; text-indent: 0; } 24 </style> 25 26 <div id=nav> 27 <a href="http://codemirror.net"><h1>CodeMirror</h1><img id=logo src="logo.png"></a> 28 <ul> 29 <li><a href="../index.html">Home</a></li> 30 <li><a href="#overview" class=active data-default="true">Manual</a></li> 31 <li><a href="https://github.com/codemirror/codemirror">Code</a></li> 32 </ul> 33 <ul> 34 <li><a href="#usage">Basic Usage</a></li> 35 <li><a href="#config">Configuration</a></li> 36 <li><a href="#events">Events</a></li> 37 <li><a href="#keymaps">Key maps</a></li> 38 <li><a href="#commands">Commands</a></li> 39 <li><a href="#styling">Customized Styling</a></li> 40 <li><a href="#api">Programming API</a> 41 <ul> 42 <li><a href="#api_constructor">Constructor</a></li> 43 <li><a href="#api_content">Content manipulation</a></li> 44 <li><a href="#api_selection">Selection</a></li> 45 <li><a href="#api_configuration">Configuration</a></li> 46 <li><a href="#api_doc">Document management</a></li> 47 <li><a href="#api_history">History</a></li> 48 <li><a href="#api_marker">Text-marking</a></li> 49 <li><a href="#api_decoration">Widget, gutter, and decoration</a></li> 50 <li><a href="#api_sizing">Sizing, scrolling, and positioning</a></li> 51 <li><a href="#api_mode">Mode, state, and tokens</a></li> 52 <li><a href="#api_misc">Miscellaneous methods</a></li> 53 <li><a href="#api_static">Static properties</a></li> 54 </ul> 55 </li> 56 <li><a href="#addons">Addons</a></li> 57 <li><a href="#modeapi">Writing CodeMirror Modes</a></li> 58 <li><a href="#vimapi">Vim Mode API</a> 59 <ul> 60 <li><a href="#vimapi_configuration">Configuration</a></li> 61 <li><a href="#vimapi_extending">Extending VIM</a></li> 62 </ul> 63 </li> 64 </ul> 65 </div> 66 67 <article> 68 69 <section class=first id=overview> 70 <h2 style="position: relative"> 71 User manual and reference guide 72 <span style="color: #888; font-size: 1rem; position: absolute; right: 0; bottom: 0">version 5.32.0</span> 73 </h2> 74 75 <p>CodeMirror is a code-editor component that can be embedded in 76 Web pages. The core library provides <em>only</em> the editor 77 component, no accompanying buttons, auto-completion, or other IDE 78 functionality. It does provide a rich API on top of which such 79 functionality can be straightforwardly implemented. See 80 the <a href="#addons">addons</a> included in the distribution, 81 and the <a href="https://github.com/codemirror/CodeMirror/wiki/CodeMirror-addons">list 82 of externally hosted addons</a>, for reusable 83 implementations of extra features.</p> 84 85 <p>CodeMirror works with language-specific modes. Modes are 86 JavaScript programs that help color (and optionally indent) text 87 written in a given language. The distribution comes with a number 88 of modes (see the <a href="../mode/"><code>mode/</code></a> 89 directory), and it isn't hard to <a href="#modeapi">write new 90 ones</a> for other languages.</p> 91 </section> 92 93 <section id=usage> 94 <h2>Basic Usage</h2> 95 96 <p>The easiest way to use CodeMirror is to simply load the script 97 and style sheet found under <code>lib/</code> in the distribution, 98 plus a mode script from one of the <code>mode/</code> directories. 99 For example:</p> 100 101 <pre data-lang="text/html"><script src="lib/codemirror.js"></script> 102 <link rel="stylesheet" href="lib/codemirror.css"> 103 <script src="mode/javascript/javascript.js"></script></pre> 104 105 <p>(Alternatively, use a module loader. <a href="#modloader">More 106 about that later.</a>)</p> 107 108 <p>Having done this, an editor instance can be created like 109 this:</p> 110 111 <pre data-lang="javascript">var myCodeMirror = CodeMirror(document.body);</pre> 112 113 <p>The editor will be appended to the document body, will start 114 empty, and will use the mode that we loaded. To have more control 115 over the new editor, a configuration object can be passed 116 to <a href="#CodeMirror"><code>CodeMirror</code></a> as a second 117 argument:</p> 118 119 <pre data-lang="javascript">var myCodeMirror = CodeMirror(document.body, { 120 value: "function myScript(){return 100;}\n", 121 mode: "javascript" 122 });</pre> 123 124 <p>This will initialize the editor with a piece of code already in 125 it, and explicitly tell it to use the JavaScript mode (which is 126 useful when multiple modes are loaded). 127 See <a href="#config">below</a> for a full discussion of the 128 configuration options that CodeMirror accepts.</p> 129 130 <p>In cases where you don't want to append the editor to an 131 element, and need more control over the way it is inserted, the 132 first argument to the <code>CodeMirror</code> function can also 133 be a function that, when given a DOM element, inserts it into the 134 document somewhere. This could be used to, for example, replace a 135 textarea with a real editor:</p> 136 137 <pre data-lang="javascript">var myCodeMirror = CodeMirror(function(elt) { 138 myTextArea.parentNode.replaceChild(elt, myTextArea); 139 }, {value: myTextArea.value});</pre> 140 141 <p>However, for this use case, which is a common way to use 142 CodeMirror, the library provides a much more powerful 143 shortcut:</p> 144 145 <pre data-lang="javascript">var myCodeMirror = CodeMirror.fromTextArea(myTextArea);</pre> 146 147 <p>This will, among other things, ensure that the textarea's value 148 is updated with the editor's contents when the form (if it is part 149 of a form) is submitted. See the <a href="#fromTextArea">API 150 reference</a> for a full description of this method.</p> 151 152 <h3 id=modloader>Module loaders</h3> 153 154 <p>The files in the CodeMirror distribution contain shims for 155 loading them (and their dependencies) in AMD or CommonJS 156 environments. If the variables <code>exports</code> 157 and <code>module</code> exist and have type object, CommonJS-style 158 require will be used. If not, but there is a 159 function <code>define</code> with an <code>amd</code> property 160 present, AMD-style (RequireJS) will be used.</p> 161 162 <p>It is possible to 163 use <a href="http://browserify.org/">Browserify</a> or similar 164 tools to statically build modules using CodeMirror. Alternatively, 165 use <a href="http://requirejs.org/">RequireJS</a> to dynamically 166 load dependencies at runtime. Both of these approaches have the 167 advantage that they don't use the global namespace and can, thus, 168 do things like load multiple versions of CodeMirror alongside each 169 other.</p> 170 171 <p>Here's a simple example of using RequireJS to load CodeMirror:</p> 172 173 <pre data-lang="javascript">require([ 174 "cm/lib/codemirror", "cm/mode/htmlmixed/htmlmixed" 175 ], function(CodeMirror) { 176 CodeMirror.fromTextArea(document.getElementById("code"), { 177 lineNumbers: true, 178 mode: "htmlmixed" 179 }); 180 });</pre> 181 182 <p>It will automatically load the modes that the mixed HTML mode 183 depends on (XML, JavaScript, and CSS). Do <em>not</em> use 184 RequireJS' <code>paths</code> option to configure the path to 185 CodeMirror, since it will break loading submodules through 186 relative paths. Use 187 the <a href="http://requirejs.org/docs/api.html#packages"><code>packages</code></a> 188 configuration option instead, as in:</p> 189 190 <pre data-lang=javascript>require.config({ 191 packages: [{ 192 name: "codemirror", 193 location: "../path/to/codemirror", 194 main: "lib/codemirror" 195 }] 196 });</pre> 197 198 </section> 199 200 <section id=config> 201 <h2>Configuration</h2> 202 203 <p>Both the <a href="#CodeMirror"><code>CodeMirror</code></a> 204 function and its <code>fromTextArea</code> method take as second 205 (optional) argument an object containing configuration options. 206 Any option not supplied like this will be taken 207 from <a href="#defaults"><code>CodeMirror.defaults</code></a>, an 208 object containing the default options. You can update this object 209 to change the defaults on your page.</p> 210 211 <p>Options are not checked in any way, so setting bogus option 212 values is bound to lead to odd errors.</p> 213 214 <p>These are the supported options:</p> 215 216 <dl> 217 <dt id="option_value"><code><strong>value</strong>: string|CodeMirror.Doc</code></dt> 218 <dd>The starting value of the editor. Can be a string, or 219 a <a href="#api_doc">document object</a>.</dd> 220 221 <dt id="option_mode"><code><strong>mode</strong>: string|object</code></dt> 222 <dd>The mode to use. When not given, this will default to the 223 first mode that was loaded. It may be a string, which either 224 simply names the mode or is 225 a <a href="http://en.wikipedia.org/wiki/MIME">MIME</a> type 226 associated with the mode. Alternatively, it may be an object 227 containing configuration options for the mode, with 228 a <code>name</code> property that names the mode (for 229 example <code>{name: "javascript", json: true}</code>). The demo 230 pages for each mode contain information about what configuration 231 parameters the mode supports. You can ask CodeMirror which modes 232 and MIME types have been defined by inspecting 233 the <code>CodeMirror.modes</code> 234 and <code>CodeMirror.mimeModes</code> objects. The first maps 235 mode names to their constructors, and the second maps MIME types 236 to mode specs.</dd> 237 238 <dt id="option_lineSeparator"><code><strong>lineSeparator</strong>: string|null</code></dt> 239 <dd>Explicitly set the line separator for the editor. By default 240 (value <code>null</code>), the document will be split on CRLFs 241 as well as lone CRs and LFs, and a single LF will be used as 242 line separator in all output (such 243 as <a href="#getValue"><code>getValue</code></a>). When a 244 specific string is given, lines will only be split on that 245 string, and output will, by default, use that same 246 separator.</dd> 247 248 <dt id="option_theme"><code><strong>theme</strong>: string</code></dt> 249 <dd>The theme to style the editor with. You must make sure the 250 CSS file defining the corresponding <code>.cm-s-[name]</code> 251 styles is loaded (see 252 the <a href="../theme/"><code>theme</code></a> directory in the 253 distribution). The default is <code>"default"</code>, for which 254 colors are included in <code>codemirror.css</code>. It is 255 possible to use multiple theming classes at once—for 256 example <code>"foo bar"</code> will assign both 257 the <code>cm-s-foo</code> and the <code>cm-s-bar</code> classes 258 to the editor.</dd> 259 260 <dt id="option_indentUnit"><code><strong>indentUnit</strong>: integer</code></dt> 261 <dd>How many spaces a block (whatever that means in the edited 262 language) should be indented. The default is 2.</dd> 263 264 <dt id="option_smartIndent"><code><strong>smartIndent</strong>: boolean</code></dt> 265 <dd>Whether to use the context-sensitive indentation that the 266 mode provides (or just indent the same as the line before). 267 Defaults to true.</dd> 268 269 <dt id="option_tabSize"><code><strong>tabSize</strong>: integer</code></dt> 270 <dd>The width of a tab character. Defaults to 4.</dd> 271 272 <dt id="option_indentWithTabs"><code><strong>indentWithTabs</strong>: boolean</code></dt> 273 <dd>Whether, when indenting, the first N*<code>tabSize</code> 274 spaces should be replaced by N tabs. Default is false.</dd> 275 276 <dt id="option_electricChars"><code><strong>electricChars</strong>: boolean</code></dt> 277 <dd>Configures whether the editor should re-indent the current 278 line when a character is typed that might change its proper 279 indentation (only works if the mode supports indentation). 280 Default is true.</dd> 281 282 <dt id="option_specialChars"><code><strong>specialChars</strong>: RegExp</code></dt> 283 <dd>A regular expression used to determine which characters 284 should be replaced by a 285 special <a href="#option_specialCharPlaceholder">placeholder</a>. 286 Mostly useful for non-printing special characters. The default 287 is <code>/[\u0000-\u001f\u007f-\u009f\u00ad\u061c\u200b-\u200f\u2028\u2029\ufeff]/</code>.</dd> 288 <dt id="option_specialCharPlaceholder"><code><strong>specialCharPlaceholder</strong>: function(char) → Element</code></dt> 289 <dd>A function that, given a special character identified by 290 the <a href="#option_specialChars"><code>specialChars</code></a> 291 option, produces a DOM node that is used to represent the 292 character. By default, a red dot (<span style="color: red">•</span>) 293 is shown, with a title tooltip to indicate the character code.</dd> 294 295 <dt id="option_rtlMoveVisually"><code><strong>rtlMoveVisually</strong>: boolean</code></dt> 296 <dd>Determines whether horizontal cursor movement through 297 right-to-left (Arabic, Hebrew) text is visual (pressing the left 298 arrow moves the cursor left) or logical (pressing the left arrow 299 moves to the next lower index in the string, which is visually 300 right in right-to-left text). The default is <code>false</code> 301 on Windows, and <code>true</code> on other platforms.</dd> 302 303 <dt id="option_keyMap"><code><strong>keyMap</strong>: string</code></dt> 304 <dd>Configures the key map to use. The default 305 is <code>"default"</code>, which is the only key map defined 306 in <code>codemirror.js</code> itself. Extra key maps are found in 307 the <a href="../keymap/"><code>key map</code></a> directory. See 308 the <a href="#keymaps">section on key maps</a> for more 309 information.</dd> 310 311 <dt id="option_extraKeys"><code><strong>extraKeys</strong>: object</code></dt> 312 <dd>Can be used to specify extra key bindings for the editor, 313 alongside the ones defined 314 by <a href="#option_keyMap"><code>keyMap</code></a>. Should be 315 either null, or a valid <a href="#keymaps">key map</a> value.</dd> 316 317 <dt id="option_configureMouse"><code><strong>configureMouse</strong>: fn(cm: CodeMirror, repeat: "single" | "double" | "triple", event: Event) → Object</code></dt> 318 <dd>Allows you to configure the behavior of mouse selection and 319 dragging. The function is called when the left mouse button is 320 pressed. The returned object may have the following properties: 321 <dl> 322 <dt><code><strong>unit</strong>: "char" | "word" | "line" | "rectangle" | fn(CodeMirror, Pos) → {from: Pos, to: Pos}</code></dt> 323 <dd>The unit by which to select. May be one of the built-in 324 units, or a function that takes a position and returns a 325 range around that, for a custom unit.</dd> 326 <dt><code><strong>extend</strong>: bool</code></dt> 327 <dd>Whether to extend the existing selection range or start a new one.</dd> 328 <dt><code><strong>addNew</strong>: bool</code></dt> 329 <dd>When enabled, this adds a new range to the existing selection, rather than replacing it.</dd> 330 <dt><code><strong>moveOnDrag</strong>: bool</code></dt> 331 <dd>When the mouse even drags content around inside the 332 editor, this controls whether it is copied (false) or moved 333 (true).</dt> 334 </dl> 335 </dd> 336 337 <dt id="option_lineWrapping"><code><strong>lineWrapping</strong>: boolean</code></dt> 338 <dd>Whether CodeMirror should scroll or wrap for long lines. 339 Defaults to <code>false</code> (scroll).</dd> 340 341 <dt id="option_lineNumbers"><code><strong>lineNumbers</strong>: boolean</code></dt> 342 <dd>Whether to show line numbers to the left of the editor.</dd> 343 344 <dt id="option_firstLineNumber"><code><strong>firstLineNumber</strong>: integer</code></dt> 345 <dd>At which number to start counting lines. Default is 1.</dd> 346 347 <dt id="option_lineNumberFormatter"><code><strong>lineNumberFormatter</strong>: function(line: integer) → string</code></dt> 348 <dd>A function used to format line numbers. The function is 349 passed the line number, and should return a string that will be 350 shown in the gutter.</dd> 351 352 <dt id="option_gutters"><code><strong>gutters</strong>: array<string></code></dt> 353 <dd>Can be used to add extra gutters (beyond or instead of the 354 line number gutter). Should be an array of CSS class names, each 355 of which defines a <code>width</code> (and optionally a 356 background), and which will be used to draw the background of 357 the gutters. <em>May</em> include 358 the <code>CodeMirror-linenumbers</code> class, in order to 359 explicitly set the position of the line number gutter (it will 360 default to be to the right of all other gutters). These class 361 names are the keys passed 362 to <a href="#setGutterMarker"><code>setGutterMarker</code></a>.</dd> 363 364 <dt id="option_fixedGutter"><code><strong>fixedGutter</strong>: boolean</code></dt> 365 <dd>Determines whether the gutter scrolls along with the content 366 horizontally (false) or whether it stays fixed during horizontal 367 scrolling (true, the default).</dd> 368 369 <dt id="option_scrollbarStyle"><code><strong>scrollbarStyle</strong>: string</code></dt> 370 <dd>Chooses a scrollbar implementation. The default 371 is <code>"native"</code>, showing native scrollbars. The core 372 library also provides the <code>"null"</code> style, which 373 completely hides the 374 scrollbars. <a href="#addon_simplescrollbars">Addons</a> can 375 implement additional scrollbar models.</dd> 376 377 <dt id="option_coverGutterNextToScrollbar"><code><strong>coverGutterNextToScrollbar</strong>: boolean</code></dt> 378 <dd>When <a href="#option_fixedGutter"><code>fixedGutter</code></a> 379 is on, and there is a horizontal scrollbar, by default the 380 gutter will be visible to the left of this scrollbar. If this 381 option is set to true, it will be covered by an element with 382 class <code>CodeMirror-gutter-filler</code>.</dd> 383 384 <dt id="option_inputStyle"><code><strong>inputStyle</strong>: string</code></dt> 385 <dd>Selects the way CodeMirror handles input and focus. The core 386 library defines the <code>"textarea"</code> 387 and <code>"contenteditable"</code> input models. On mobile 388 browsers, the default is <code>"contenteditable"</code>. On 389 desktop browsers, the default is <code>"textarea"</code>. 390 Support for IME and screen readers is better in 391 the <code>"contenteditable"</code> model. The intention is to 392 make it the default on modern desktop browsers in the 393 future.</dd> 394 395 <dt id="option_readOnly"><code><strong>readOnly</strong>: boolean|string</code></dt> 396 <dd>This disables editing of the editor content by the user. If 397 the special value <code>"nocursor"</code> is given (instead of 398 simply <code>true</code>), focusing of the editor is also 399 disallowed.</dd> 400 401 <dt id="option_showCursorWhenSelecting"><code><strong>showCursorWhenSelecting</strong>: boolean</code></dt> 402 <dd>Whether the cursor should be drawn when a selection is 403 active. Defaults to false.</dd> 404 405 <dt id="option_lineWiseCopyCut"><code><strong>lineWiseCopyCut</strong>: boolean</code></dt> 406 <dd>When enabled, which is the default, doing copy or cut when 407 there is no selection will copy or cut the whole lines that have 408 cursors on them.</dd> 409 410 <dt id="option_pasteLinesPerSelection"><code><strong>pasteLinesPerSelection</strong>: boolean</code></dt> 411 <dd>When pasting something from an external source (not from the 412 editor itself), if the number of lines matches the number of 413 selection, CodeMirror will by default insert one line per 414 selection. You can set this to <code>false</code> to disable 415 that behavior.</dd> 416 417 <dt id="option_undoDepth"><code><strong>undoDepth</strong>: integer</code></dt> 418 <dd>The maximum number of undo levels that the editor stores. 419 Note that this includes selection change events. Defaults to 420 200.</dd> 421 422 <dt id="option_historyEventDelay"><code><strong>historyEventDelay</strong>: integer</code></dt> 423 <dd>The period of inactivity (in milliseconds) that will cause a 424 new history event to be started when typing or deleting. 425 Defaults to 1250.</dd> 426 427 <dt id="option_tabindex"><code><strong>tabindex</strong>: integer</code></dt> 428 <dd>The <a href="http://www.w3.org/TR/html401/interact/forms.html#adef-tabindex">tab 429 index</a> to assign to the editor. If not given, no tab index 430 will be assigned.</dd> 431 432 <dt id="option_autofocus"><code><strong>autofocus</strong>: boolean</code></dt> 433 <dd>Can be used to make CodeMirror focus itself on 434 initialization. Defaults to off. 435 When <a href="#fromTextArea"><code>fromTextArea</code></a> is 436 used, and no explicit value is given for this option, it will be 437 set to true when either the source textarea is focused, or it 438 has an <code>autofocus</code> attribute and no other element is 439 focused.</dd> 440 </dl> 441 442 <p>Below this a few more specialized, low-level options are 443 listed. These are only useful in very specific situations, you 444 might want to skip them the first time you read this manual.</p> 445 446 <dl> 447 <dt id="option_dragDrop"><code><strong>dragDrop</strong>: boolean</code></dt> 448 <dd>Controls whether drag-and-drop is enabled. On by default.</dd> 449 450 <dt id="option_allowDropFileTypes"><code><strong>allowDropFileTypes</strong>: array<string></code></dt> 451 <dd>When set (default is <code>null</code>) only files whose 452 type is in the array can be dropped into the editor. The strings 453 should be MIME types, and will be checked against 454 the <a href="https://w3c.github.io/FileAPI/#dfn-type"><code>type</code></a> 455 of the <code>File</code> object as reported by the browser.</dd> 456 457 <dt id="option_cursorBlinkRate"><code><strong>cursorBlinkRate</strong>: number</code></dt> 458 <dd>Half-period in milliseconds used for cursor blinking. The default blink 459 rate is 530ms. By setting this to zero, blinking can be disabled. A 460 negative value hides the cursor entirely.</dd> 461 462 <dt id="option_cursorScrollMargin"><code><strong>cursorScrollMargin</strong>: number</code></dt> 463 <dd>How much extra space to always keep above and below the 464 cursor when approaching the top or bottom of the visible view in 465 a scrollable document. Default is 0.</dd> 466 467 <dt id="option_cursorHeight"><code><strong>cursorHeight</strong>: number</code></dt> 468 <dd>Determines the height of the cursor. Default is 1, meaning 469 it spans the whole height of the line. For some fonts (and by 470 some tastes) a smaller height (for example <code>0.85</code>), 471 which causes the cursor to not reach all the way to the bottom 472 of the line, looks better</dd> 473 474 <dt id="option_resetSelectionOnContextMenu"><code><strong>resetSelectionOnContextMenu</strong>: boolean</code></dt> 475 <dd>Controls whether, when the context menu is opened with a 476 click outside of the current selection, the cursor is moved to 477 the point of the click. Defaults to <code>true</code>.</dd> 478 479 <dt id="option_workTime"><code id="option_wordkDelay"><strong>workTime</strong>, <strong>workDelay</strong>: number</code></dt> 480 <dd>Highlighting is done by a pseudo background-thread that will 481 work for <code>workTime</code> milliseconds, and then use 482 timeout to sleep for <code>workDelay</code> milliseconds. The 483 defaults are 200 and 300, you can change these options to make 484 the highlighting more or less aggressive.</dd> 485 486 <dt id="option_pollInterval"><code><strong>pollInterval</strong>: number</code></dt> 487 <dd>Indicates how quickly CodeMirror should poll its input 488 textarea for changes (when focused). Most input is captured by 489 events, but some things, like IME input on some browsers, don't 490 generate events that allow CodeMirror to properly detect it. 491 Thus, it polls. Default is 100 milliseconds.</dd> 492 493 <dt id="option_flattenSpans"><code><strong>flattenSpans</strong>: boolean</code></dt> 494 <dd>By default, CodeMirror will combine adjacent tokens into a 495 single span if they have the same class. This will result in a 496 simpler DOM tree, and thus perform better. With some kinds of 497 styling (such as rounded corners), this will change the way the 498 document looks. You can set this option to false to disable this 499 behavior.</dd> 500 501 <dt id="option_addModeClass"><code><strong>addModeClass</strong>: boolean</code></dt> 502 <dd>When enabled (off by default), an extra CSS class will be 503 added to each token, indicating the 504 (<a href="#innerMode">inner</a>) mode that produced it, prefixed 505 with <code>"cm-m-"</code>. For example, tokens from the XML mode 506 will get the <code>cm-m-xml</code> class.</dd> 507 508 <dt id="option_maxHighlightLength"><code><strong>maxHighlightLength</strong>: number</code></dt> 509 <dd>When highlighting long lines, in order to stay responsive, 510 the editor will give up and simply style the rest of the line as 511 plain text when it reaches a certain position. The default is 512 10 000. You can set this to <code>Infinity</code> to turn off 513 this behavior.</dd> 514 515 <dt id="option_viewportMargin"><code><strong>viewportMargin</strong>: integer</code></dt> 516 <dd>Specifies the amount of lines that are rendered above and 517 below the part of the document that's currently scrolled into 518 view. This affects the amount of updates needed when scrolling, 519 and the amount of work that such an update does. You should 520 usually leave it at its default, 10. Can be set 521 to <code>Infinity</code> to make sure the whole document is 522 always rendered, and thus the browser's text search works on it. 523 This <em>will</em> have bad effects on performance of big 524 documents.</dd> 525 </dl> 526 </section> 527 528 <section id=events> 529 <h2>Events</h2> 530 531 <p>Various CodeMirror-related objects emit events, which allow 532 client code to react to various situations. Handlers for such 533 events can be registered with the <a href="#on"><code>on</code></a> 534 and <a href="#off"><code>off</code></a> methods on the objects 535 that the event fires on. To fire your own events, 536 use <code>CodeMirror.signal(target, name, args...)</code>, 537 where <code>target</code> is a non-DOM-node object.</p> 538 539 <p>An editor instance fires the following events. 540 The <code>instance</code> argument always refers to the editor 541 itself.</p> 542 543 <dl> 544 <dt id="event_change"><code><strong>"change"</strong> (instance: CodeMirror, changeObj: object)</code></dt> 545 <dd>Fires every time the content of the editor is changed. 546 The <code>changeObj</code> is a <code>{from, to, text, removed, 547 origin}</code> object containing information about the changes 548 that occurred as second argument. <code>from</code> 549 and <code>to</code> are the positions (in the pre-change 550 coordinate system) where the change started and ended (for 551 example, it might be <code>{ch:0, line:18}</code> if the 552 position is at the beginning of line #19). <code>text</code> is 553 an array of strings representing the text that replaced the 554 changed range (split by line). <code>removed</code> is the text 555 that used to be between <code>from</code> and <code>to</code>, 556 which is overwritten by this change. This event is 557 fired <em>before</em> the end of 558 an <a href="#operation">operation</a>, before the DOM updates 559 happen.</dd> 560 561 <dt id="event_changes"><code><strong>"changes"</strong> (instance: CodeMirror, changes: array<object>)</code></dt> 562 <dd>Like the <a href="#event_change"><code>"change"</code></a> 563 event, but batched per <a href="#operation">operation</a>, 564 passing an array containing all the changes that happened in the 565 operation. This event is fired after the operation finished, and 566 display changes it makes will trigger a new operation.</dd> 567 568 <dt id="event_beforeChange"><code><strong>"beforeChange"</strong> (instance: CodeMirror, changeObj: object)</code></dt> 569 <dd>This event is fired before a change is applied, and its 570 handler may choose to modify or cancel the change. 571 The <code>changeObj</code> object 572 has <code>from</code>, <code>to</code>, and <code>text</code> 573 properties, as with 574 the <a href="#event_change"><code>"change"</code></a> event. It 575 also has a <code>cancel()</code> method, which can be called to 576 cancel the change, and, <strong>if</strong> the change isn't 577 coming from an undo or redo event, an <code>update(from, to, 578 text)</code> method, which may be used to modify the change. 579 Undo or redo changes can't be modified, because they hold some 580 metainformation for restoring old marked ranges that is only 581 valid for that specific change. All three arguments 582 to <code>update</code> are optional, and can be left off to 583 leave the existing value for that field 584 intact. <strong>Note:</strong> you may not do anything from 585 a <code>"beforeChange"</code> handler that would cause changes 586 to the document or its visualization. Doing so will, since this 587 handler is called directly from the bowels of the CodeMirror 588 implementation, probably cause the editor to become 589 corrupted.</dd> 590 591 <dt id="event_cursorActivity"><code><strong>"cursorActivity"</strong> (instance: CodeMirror)</code></dt> 592 <dd>Will be fired when the cursor or selection moves, or any 593 change is made to the editor content.</dd> 594 595 <dt id="event_keyHandled"><code><strong>"keyHandled"</strong> (instance: CodeMirror, name: string, event: Event)</code></dt> 596 <dd>Fired after a key is handled through a 597 key map. <code>name</code> is the name of the handled key (for 598 example <code>"Ctrl-X"</code> or <code>"'q'"</code>), 599 and <code>event</code> is the DOM <code>keydown</code> 600 or <code>keypress</code> event.</dd> 601 602 <dt id="event_inputRead"><code><strong>"inputRead"</strong> (instance: CodeMirror, changeObj: object)</code></dt> 603 <dd>Fired whenever new input is read from the hidden textarea 604 (typed or pasted by the user).</dd> 605 606 <dt id="event_electricInput"><code><strong>"electricInput"</strong> (instance: CodeMirror, line: integer)</code></dt> 607 <dd>Fired if text input matched the 608 mode's <a href="#option_electricChars">electric</a> patterns, 609 and this caused the line's indentation to change.</dd> 610 611 <dt id="event_beforeSelectionChange"><code><strong>"beforeSelectionChange"</strong> (instance: CodeMirror, obj: {ranges, origin, update})</code></dt> 612 <dd>This event is fired before the selection is moved. Its 613 handler may inspect the set of selection ranges, present as an 614 array of <code>{anchor, head}</code> objects in 615 the <code>ranges</code> property of the <code>obj</code> 616 argument, and optionally change them by calling 617 the <code>update</code> method on this object, passing an array 618 of ranges in the same format. The object also contains 619 an <code>origin</code> property holding the origin string passed 620 to the selection-changing method, if any. Handlers for this 621 event have the same restriction 622 as <a href="#event_beforeChange"><code>"beforeChange"</code></a> 623 handlers — they should not do anything to directly update the 624 state of the editor.</dd> 625 626 <dt id="event_viewportChange"><code><strong>"viewportChange"</strong> (instance: CodeMirror, from: number, to: number)</code></dt> 627 <dd>Fires whenever the <a href="#getViewport">view port</a> of 628 the editor changes (due to scrolling, editing, or any other 629 factor). The <code>from</code> and <code>to</code> arguments 630 give the new start and end of the viewport.</dd> 631 632 <dt id="event_swapDoc"><code><strong>"swapDoc"</strong> (instance: CodeMirror, oldDoc: Doc)</code></dt> 633 <dd>This is signalled when the editor's document is replaced 634 using the <a href="#swapDoc"><code>swapDoc</code></a> 635 method.</dd> 636 637 <dt id="event_gutterClick"><code><strong>"gutterClick"</strong> (instance: CodeMirror, line: integer, gutter: string, clickEvent: Event)</code></dt> 638 <dd>Fires when the editor gutter (the line-number area) is 639 clicked. Will pass the editor instance as first argument, the 640 (zero-based) number of the line that was clicked as second 641 argument, the CSS class of the gutter that was clicked as third 642 argument, and the raw <code>mousedown</code> event object as 643 fourth argument.</dd> 644 645 <dt id="event_gutterContextMenu"><code><strong>"gutterContextMenu"</strong> (instance: CodeMirror, line: integer, gutter: string, contextMenu: Event: Event)</code></dt> 646 <dd>Fires when the editor gutter (the line-number area) 647 receives a <code>contextmenu</code> event. Will pass the editor 648 instance as first argument, the (zero-based) number of the line 649 that was clicked as second argument, the CSS class of the 650 gutter that was clicked as third argument, and the raw 651 <code>contextmenu</code> mouse event object as fourth argument. 652 You can <code>preventDefault</code> the event, to signal that 653 CodeMirror should do no further handling.</dd> 654 655 <dt id="event_focus"><code><strong>"focus"</strong> (instance: CodeMirror, event: Event)</code></dt> 656 <dd>Fires whenever the editor is focused.</dd> 657 658 <dt id="event_blur"><code><strong>"blur"</strong> (instance: CodeMirror, event: Event)</code></dt> 659 <dd>Fires whenever the editor is unfocused.</dd> 660 661 <dt id="event_scroll"><code><strong>"scroll"</strong> (instance: CodeMirror)</code></dt> 662 <dd>Fires when the editor is scrolled.</dd> 663 664 <dt id="event_refresh"><code><strong>"refresh"</strong> (instance: CodeMirror)</code></dt> 665 <dd>Fires when the editor is <a href="#refresh">refreshed</a> 666 or <a href="#setSize">resized</a>. Mostly useful to invalidate 667 cached values that depend on the editor or character size.</dd> 668 669 <dt id="event_optionChange"><code><strong>"optionChange"</strong> (instance: CodeMirror, option: string)</code></dt> 670 <dd>Dispatched every time an option is changed with <a href="#setOption"><code>setOption</code></a>.</dd> 671 672 <dt id="event_scrollCursorIntoView"><code><strong>"scrollCursorIntoView"</strong> (instance: CodeMirror, event: Event)</code></dt> 673 <dd>Fires when the editor tries to scroll its cursor into view. 674 Can be hooked into to take care of additional scrollable 675 containers around the editor. When the event object has 676 its <code>preventDefault</code> method called, CodeMirror will 677 not itself try to scroll the window.</dd> 678 679 <dt id="event_update"><code><strong>"update"</strong> (instance: CodeMirror)</code></dt> 680 <dd>Will be fired whenever CodeMirror updates its DOM display.</dd> 681 682 <dt id="event_renderLine"><code><strong>"renderLine"</strong> (instance: CodeMirror, line: LineHandle, element: Element)</code></dt> 683 <dd>Fired whenever a line is (re-)rendered to the DOM. Fired 684 right after the DOM element is built, <em>before</em> it is 685 added to the document. The handler may mess with the style of 686 the resulting element, or add event handlers, but 687 should <em>not</em> try to change the state of the editor.</dd> 688 689 <dt id="event_dom"><code><strong>"mousedown"</strong>, 690 <strong>"dblclick"</strong>, <strong>"touchstart"</strong>, <strong>"contextmenu"</strong>, 691 <strong>"keydown"</strong>, <strong>"keypress"</strong>, 692 <strong>"keyup"</strong>, <strong>"cut"</strong>, <strong>"copy"</strong>, <strong>"paste"</strong>, 693 <strong>"dragstart"</strong>, <strong>"dragenter"</strong>, 694 <strong>"dragover"</strong>, <strong>"dragleave"</strong>, 695 <strong>"drop"</strong> 696 (instance: CodeMirror, event: Event)</code></dt> 697 <dd>Fired when CodeMirror is handling a DOM event of this type. 698 You can <code>preventDefault</code> the event, or give it a 699 truthy <code>codemirrorIgnore</code> property, to signal that 700 CodeMirror should do no further handling.</dd> 701 </dl> 702 703 <p>Document objects (instances 704 of <a href="#Doc"><code>CodeMirror.Doc</code></a>) emit the 705 following events:</p> 706 707 <dl> 708 <dt id="event_doc_change"><code><strong>"change"</strong> (doc: CodeMirror.Doc, changeObj: object)</code></dt> 709 <dd>Fired whenever a change occurs to the 710 document. <code>changeObj</code> has a similar type as the 711 object passed to the 712 editor's <a href="#event_change"><code>"change"</code></a> 713 event.</dd> 714 715 <dt id="event_doc_beforeChange"><code><strong>"beforeChange"</strong> (doc: CodeMirror.Doc, change: object)</code></dt> 716 <dd>See the <a href="#event_beforeChange">description of the 717 same event</a> on editor instances.</dd> 718 719 <dt id="event_doc_cursorActivity"><code><strong>"cursorActivity"</strong> (doc: CodeMirror.Doc)</code></dt> 720 <dd>Fired whenever the cursor or selection in this document 721 changes.</dd> 722 723 <dt id="event_doc_beforeSelectionChange"><code><strong>"beforeSelectionChange"</strong> (doc: CodeMirror.Doc, selection: {head, anchor})</code></dt> 724 <dd>Equivalent to 725 the <a href="#event_beforeSelectionChange">event by the same 726 name</a> as fired on editor instances.</dd> 727 </dl> 728 729 <p>Line handles (as returned by, for 730 example, <a href="#getLineHandle"><code>getLineHandle</code></a>) 731 support these events:</p> 732 733 <dl> 734 <dt id="event_delete"><code><strong>"delete"</strong> ()</code></dt> 735 <dd>Will be fired when the line object is deleted. A line object 736 is associated with the <em>start</em> of the line. Mostly useful 737 when you need to find out when your <a href="#setGutterMarker">gutter 738 markers</a> on a given line are removed.</dd> 739 <dt id="event_line_change"><code><strong>"change"</strong> (line: LineHandle, changeObj: object)</code></dt> 740 <dd>Fires when the line's text content is changed in any way 741 (but the line is not deleted outright). The <code>change</code> 742 object is similar to the one passed 743 to <a href="#event_change">change event</a> on the editor 744 object.</dd> 745 </dl> 746 747 <p>Marked range handles (<code>CodeMirror.TextMarker</code>), as returned 748 by <a href="#markText"><code>markText</code></a> 749 and <a href="#setBookmark"><code>setBookmark</code></a>, emit the 750 following events:</p> 751 752 <dl> 753 <dt id="event_beforeCursorEnter"><code><strong>"beforeCursorEnter"</strong> ()</code></dt> 754 <dd>Fired when the cursor enters the marked range. From this 755 event handler, the editor state may be inspected 756 but <em>not</em> modified, with the exception that the range on 757 which the event fires may be cleared.</dd> 758 <dt id="event_clear"><code><strong>"clear"</strong> (from: {line, ch}, to: {line, ch})</code></dt> 759 <dd>Fired when the range is cleared, either through cursor 760 movement in combination 761 with <a href="#mark_clearOnEnter"><code>clearOnEnter</code></a> 762 or through a call to its <code>clear()</code> method. Will only 763 be fired once per handle. Note that deleting the range through 764 text editing does not fire this event, because an undo action 765 might bring the range back into existence. <code>from</code> 766 and <code>to</code> give the part of the document that the range 767 spanned when it was cleared.</dd> 768 <dt id="event_hide"><code><strong>"hide"</strong> ()</code></dt> 769 <dd>Fired when the last part of the marker is removed from the 770 document by editing operations.</dd> 771 <dt id="event_unhide"><code><strong>"unhide"</strong> ()</code></dt> 772 <dd>Fired when, after the marker was removed by editing, a undo 773 operation brought the marker back.</dd> 774 </dl> 775 776 <p>Line widgets (<code>CodeMirror.LineWidget</code>), returned 777 by <a href="#addLineWidget"><code>addLineWidget</code></a>, fire 778 these events:</p> 779 780 <dl> 781 <dt id="event_redraw"><code><strong>"redraw"</strong> ()</code></dt> 782 <dd>Fired whenever the editor re-adds the widget to the DOM. 783 This will happen once right after the widget is added (if it is 784 scrolled into view), and then again whenever it is scrolled out 785 of view and back in again, or when changes to the editor options 786 or the line the widget is on require the widget to be 787 redrawn.</dd> 788 </dl> 789 </section> 790 791 <section id=keymaps> 792 <h2>Key Maps</h2> 793 794 <p>Key maps are ways to associate keys and mouse buttons with 795 functionality. A key map is an object mapping strings that 796 identify the buttons to functions that implement their 797 functionality.</p> 798 799 <p>The CodeMirror distributions comes 800 with <a href="../demo/emacs.html">Emacs</a>, <a href="../demo/vim.html">Vim</a>, 801 and <a href="../demo/sublime.html">Sublime Text</a>-style keymaps.</p> 802 803 <p>Keys are identified either by name or by character. 804 The <code>CodeMirror.keyNames</code> object defines names for 805 common keys and associates them with their key codes. Examples of 806 names defined here are <code>Enter</code>, <code>F5</code>, 807 and <code>Q</code>. These can be prefixed 808 with <code>Shift-</code>, <code>Cmd-</code>, <code>Ctrl-</code>, 809 and <code>Alt-</code> to specify a modifier. So for 810 example, <code>Shift-Ctrl-Space</code> would be a valid key 811 identifier.</p> 812 813 <p>Common example: map the Tab key to insert spaces instead of a tab 814 character.</p> 815 816 <pre data-lang="javascript"> 817 editor.setOption("extraKeys", { 818 Tab: function(cm) { 819 var spaces = Array(cm.getOption("indentUnit") + 1).join(" "); 820 cm.replaceSelection(spaces); 821 } 822 });</pre> 823 824 <p>Alternatively, a character can be specified directly by 825 surrounding it in single quotes, for example <code>'$'</code> 826 or <code>'q'</code>. Due to limitations in the way browsers fire 827 key events, these may not be prefixed with modifiers.</p> 828 829 <p>To bind mouse buttons, use the names `LeftClick`, 830 `MiddleClick`, and `RightClick`. These can also be prefixed with 831 modifiers, and in addition, the word `Double` or `Triple` can be 832 put before `Click` (as in `LeftDoubleClick`) to bind a double- or 833 triple-click. The function for such a binding is passed the 834 position that was clicked as second argument.</p> 835 836 <p id="normalizeKeyMap">Multi-stroke key bindings can be specified 837 by separating the key names by spaces in the property name, for 838 example <code>Ctrl-X Ctrl-V</code>. When a map contains 839 multi-stoke bindings or keys with modifiers that are not specified 840 in the default order (<code>Shift-Cmd-Ctrl-Alt</code>), you must 841 call <code>CodeMirror.normalizeKeyMap</code> on it before it can 842 be used. This function takes a keymap and modifies it to normalize 843 modifier order and properly recognize multi-stroke bindings. It 844 will return the keymap itself.</p> 845 846 <p>The <code>CodeMirror.keyMap</code> object associates key maps 847 with names. User code and key map definitions can assign extra 848 properties to this object. Anywhere where a key map is expected, a 849 string can be given, which will be looked up in this object. It 850 also contains the <code>"default"</code> key map holding the 851 default bindings.</p> 852 853 <p>The values of properties in key maps can be either functions of 854 a single argument (the CodeMirror instance), strings, or 855 <code>false</code>. Strings refer 856 to <a href="#commands">commands</a>, which are described below. If 857 the property is set to <code>false</code>, CodeMirror leaves 858 handling of the key up to the browser. A key handler function may 859 return <code>CodeMirror.Pass</code> to indicate that it has 860 decided not to handle the key, and other handlers (or the default 861 behavior) should be given a turn.</p> 862 863 <p>Keys mapped to command names that start with the 864 characters <code>"go"</code> or to functions that have a 865 truthy <code>motion</code> property (which should be used for 866 cursor-movement actions) will be fired even when an 867 extra <code>Shift</code> modifier is present (i.e. <code>"Up": 868 "goLineUp"</code> matches both up and shift-up). This is used to 869 easily implement shift-selection.</p> 870 871 <p>Key maps can defer to each other by defining 872 a <code>fallthrough</code> property. This indicates that when a 873 key is not found in the map itself, one or more other maps should 874 be searched. It can hold either a single key map or an array of 875 key maps.</p> 876 877 <p>When a key map needs to set something up when it becomes 878 active, or tear something down when deactivated, it can 879 contain <code>attach</code> and/or <code>detach</code> properties, 880 which should hold functions that take the editor instance and the 881 next or previous keymap. Note that this only works for the 882 <a href="#option_keyMap">top-level keymap</a>, not for fallthrough 883 maps or maps added 884 with <a href="#option_extraKeys"><code>extraKeys</code></a> 885 or <a href="#addKeyMap"><code>addKeyMap</code></a>.</p> 886 </section> 887 888 <section id=commands> 889 <h2>Commands</h2> 890 891 <p>Commands are parameter-less actions that can be performed on an 892 editor. Their main use is for key bindings. Commands are defined by 893 adding properties to the <code>CodeMirror.commands</code> object. 894 A number of common commands are defined by the library itself, 895 most of them used by the default key bindings. The value of a 896 command property must be a function of one argument (an editor 897 instance).</p> 898 899 <p>Some of the commands below are referenced in the default 900 key map, but not defined by the core library. These are intended to 901 be defined by user code or addons.</p> 902 903 <p>Commands can also be run with 904 the <a href="#execCommand"><code>execCommand</code></a> 905 method.</p> 906 907 <dl> 908 <dt class=command id=command_selectAll><code><strong>selectAll</strong></code><span class=keybinding>Ctrl-A (PC), Cmd-A (Mac)</span></dt> 909 <dd>Select the whole content of the editor.</dd> 910 911 <dt class=command id=command_singleSelection><code><strong>singleSelection</strong></code><span class=keybinding>Esc</span></dt> 912 <dd>When multiple selections are present, this deselects all but 913 the primary selection.</dd> 914 915 <dt class=command id=command_killLine><code><strong>killLine</strong></code><span class=keybinding>Ctrl-K (Mac)</span></dt> 916 <dd>Emacs-style line killing. Deletes the part of the line after 917 the cursor. If that consists only of whitespace, the newline at 918 the end of the line is also deleted.</dd> 919 920 <dt class=command id=command_deleteLine><code><strong>deleteLine</strong></code><span class=keybinding>Ctrl-D (PC), Cmd-D (Mac)</span></dt> 921 <dd>Deletes the whole line under the cursor, including newline at the end.</dd> 922 923 <dt class=command id=command_delLineLeft><code><strong>delLineLeft</strong></code></dt> 924 <dd>Delete the part of the line before the cursor.</dd> 925 926 <dt class=command id=command_delWrappedLineLeft><code><strong>delWrappedLineLeft</strong></code><span class=keybinding>Cmd-Backspace (Mac)</span></dt> 927 <dd>Delete the part of the line from the left side of the visual line the cursor is on to the cursor.</dd> 928 929 <dt class=command id=command_delWrappedLineRight><code><strong>delWrappedLineRight</strong></code><span class=keybinding>Cmd-Delete (Mac)</span></dt> 930 <dd>Delete the part of the line from the cursor to the right side of the visual line the cursor is on.</dd> 931 932 <dt class=command id=command_undo><code><strong>undo</strong></code><span class=keybinding>Ctrl-Z (PC), Cmd-Z (Mac)</span></dt> 933 <dd>Undo the last change. Note that, because browsers still 934 don't make it possible for scripts to react to or customize the 935 context menu, selecting undo (or redo) from the context menu in 936 a CodeMirror instance does not work.</dd> 937 938 <dt class=command id=command_redo><code><strong>redo</strong></code><span class=keybinding>Ctrl-Y (PC), Shift-Cmd-Z (Mac), Cmd-Y (Mac)</span></dt> 939 <dd>Redo the last undone change.</dd> 940 941 <dt class=command id=command_undoSelection><code><strong>undoSelection</strong></code><span class=keybinding>Ctrl-U (PC), Cmd-U (Mac)</span></dt> 942 <dd>Undo the last change to the selection, or if there are no 943 selection-only changes at the top of the history, undo the last 944 change.</dd> 945 946 <dt class=command id=command_redoSelection><code><strong>redoSelection</strong></code><span class=keybinding>Alt-U (PC), Shift-Cmd-U (Mac)</span></dt> 947 <dd>Redo the last change to the selection, or the last text change if 948 no selection changes remain.</dd> 949 950 <dt class=command id=command_goDocStart><code><strong>goDocStart</strong></code><span class=keybinding>Ctrl-Home (PC), Cmd-Up (Mac), Cmd-Home (Mac)</span></dt> 951 <dd>Move the cursor to the start of the document.</dd> 952 953 <dt class=command id=command_goDocEnd><code><strong>goDocEnd</strong></code><span class=keybinding>Ctrl-End (PC), Cmd-End (Mac), Cmd-Down (Mac)</span></dt> 954 <dd>Move the cursor to the end of the document.</dd> 955 956 <dt class=command id=command_goLineStart><code><strong>goLineStart</strong></code><span class=keybinding>Alt-Left (PC), Ctrl-A (Mac)</span></dt> 957 <dd>Move the cursor to the start of the line.</dd> 958 959 <dt class=command id=command_goLineStartSmart><code><strong>goLineStartSmart</strong></code><span class=keybinding>Home</span></dt> 960 <dd>Move to the start of the text on the line, or if we are 961 already there, to the actual start of the line (including 962 whitespace).</dd> 963 964 <dt class=command id=command_goLineEnd><code><strong>goLineEnd</strong></code><span class=keybinding>Alt-Right (PC), Ctrl-E (Mac)</span></dt> 965 <dd>Move the cursor to the end of the line.</dd> 966 967 <dt class=command id=command_goLineRight><code><strong>goLineRight</strong></code><span class=keybinding>Cmd-Right (Mac)</span></dt> 968 <dd>Move the cursor to the right side of the visual line it is on.</dd> 969 970 <dt class=command id=command_goLineLeft><code><strong>goLineLeft</strong></code><span class=keybinding>Cmd-Left (Mac)</span></dt> 971 <dd>Move the cursor to the left side of the visual line it is on. If 972 this line is wrapped, that may not be the start of the line.</dd> 973 974 <dt class=command id=command_goLineLeftSmart><code><strong>goLineLeftSmart</strong></code></dt> 975 <dd>Move the cursor to the left side of the visual line it is 976 on. If that takes it to the start of the line, behave 977 like <a href="#command_goLineStartSmart"><code>goLineStartSmart</code></a>.</dd> 978 979 <dt class=command id=command_goLineUp><code><strong>goLineUp</strong></code><span class=keybinding>Up, Ctrl-P (Mac)</span></dt> 980 <dd>Move the cursor up one line.</dd> 981 982 <dt class=command id=command_goLineDown><code><strong>goLineDown</strong></code><span class=keybinding>Down, Ctrl-N (Mac)</span></dt> 983 <dd>Move down one line.</dd> 984 985 <dt class=command id=command_goPageUp><code><strong>goPageUp</strong></code><span class=keybinding>PageUp, Shift-Ctrl-V (Mac)</span></dt> 986 <dd>Move the cursor up one screen, and scroll up by the same distance.</dd> 987 988 <dt class=command id=command_goPageDown><code><strong>goPageDown</strong></code><span class=keybinding>PageDown, Ctrl-V (Mac)</span></dt> 989 <dd>Move the cursor down one screen, and scroll down by the same distance.</dd> 990 991 <dt class=command id=command_goCharLeft><code><strong>goCharLeft</strong></code><span class=keybinding>Left, Ctrl-B (Mac)</span></dt> 992 <dd>Move the cursor one character left, going to the previous line 993 when hitting the start of line.</dd> 994 995 <dt class=command id=command_goCharRight><code><strong>goCharRight</strong></code><span class=keybinding>Right, Ctrl-F (Mac)</span></dt> 996 <dd>Move the cursor one character right, going to the next line 997 when hitting the end of line.</dd> 998 999 <dt class=command id=command_goColumnLeft><code><strong>goColumnLeft</strong></code></dt> 1000 <dd>Move the cursor one character left, but don't cross line boundaries.</dd> 1001 1002 <dt class=command id=command_goColumnRight><code><strong>goColumnRight</strong></code></dt> 1003 <dd>Move the cursor one character right, don't cross line boundaries.</dd> 1004 1005 <dt class=command id=command_goWordLeft><code><strong>goWordLeft</strong></code><span class=keybinding>Alt-B (Mac)</span></dt> 1006 <dd>Move the cursor to the start of the previous word.</dd> 1007 1008 <dt class=command id=command_goWordRight><code><strong>goWordRight</strong></code><span class=keybinding>Alt-F (Mac)</span></dt> 1009 <dd>Move the cursor to the end of the next word.</dd> 1010 1011 <dt class=command id=command_goGroupLeft><code><strong>goGroupLeft</strong></code><span class=keybinding>Ctrl-Left (PC), Alt-Left (Mac)</span></dt> 1012 <dd>Move to the left of the group before the cursor. A group is 1013 a stretch of word characters, a stretch of punctuation 1014 characters, a newline, or a stretch of <em>more than one</em> 1015 whitespace character.</dd> 1016 1017 <dt class=command id=command_goGroupRight><code><strong>goGroupRight</strong></code><span class=keybinding>Ctrl-Right (PC), Alt-Right (Mac)</span></dt> 1018 <dd>Move to the right of the group after the cursor 1019 (see <a href="#command_goGroupLeft">above</a>).</dd> 1020 1021 <dt class=command id=command_delCharBefore><code><strong>delCharBefore</strong></code><span class=keybinding>Shift-Backspace, Ctrl-H (Mac)</span></dt> 1022 <dd>Delete the character before the cursor.</dd> 1023 1024 <dt class=command id=command_delCharAfter><code><strong>delCharAfter</strong></code><span class=keybinding>Delete, Ctrl-D (Mac)</span></dt> 1025 <dd>Delete the character after the cursor.</dd> 1026 1027 <dt class=command id=command_delWordBefore><code><strong>delWordBefore</strong></code><span class=keybinding>Alt-Backspace (Mac)</span></dt> 1028 <dd>Delete up to the start of the word before the cursor.</dd> 1029 1030 <dt class=command id=command_delWordAfter><code><strong>delWordAfter</strong></code><span class=keybinding>Alt-D (Mac)</span></dt> 1031 <dd>Delete up to the end of the word after the cursor.</dd> 1032 1033 <dt class=command id=command_delGroupBefore><code><strong>delGroupBefore</strong></code><span class=keybinding>Ctrl-Backspace (PC), Alt-Backspace (Mac)</span></dt> 1034 <dd>Delete to the left of the <a href="#command_goGroupLeft">group</a> before the cursor.</dd> 1035 1036 <dt class=command id=command_delGroupAfter><code><strong>delGroupAfter</strong></code><span class=keybinding>Ctrl-Delete (PC), Ctrl-Alt-Backspace (Mac), Alt-Delete (Mac)</span></dt> 1037 <dd>Delete to the start of the <a href="#command_goGroupLeft">group</a> after the cursor.</dd> 1038 1039 <dt class=command id=command_indentAuto><code><strong>indentAuto</strong></code><span class=keybinding>Shift-Tab</span></dt> 1040 <dd>Auto-indent the current line or selection.</dd> 1041 1042 <dt class=command id=command_indentMore><code><strong>indentMore</strong></code><span class=keybinding>Ctrl-] (PC), Cmd-] (Mac)</span></dt> 1043 <dd>Indent the current line or selection by one <a href="#option_indentUnit">indent unit</a>.</dd> 1044 1045 <dt class=command id=command_indentLess><code><strong>indentLess</strong></code><span class=keybinding>Ctrl-[ (PC), Cmd-[ (Mac)</span></dt> 1046 <dd>Dedent the current line or selection by one <a href="#option_indentUnit">indent unit</a>.</dd> 1047 1048 <dt class=command id=command_insertTab><code><strong>insertTab</strong></code></dt> 1049 <dd>Insert a tab character at the cursor.</dd> 1050 1051 <dt class=command id=command_insertSoftTab><code><strong>insertSoftTab</strong></code></dt> 1052 <dd>Insert the amount of spaces that match the width a tab at 1053 the cursor position would have.</dd> 1054 1055 <dt class=command id=command_defaultTab><code><strong>defaultTab</strong></code><span class=keybinding>Tab</span></dt> 1056 <dd>If something is selected, indent it by 1057 one <a href="#option_indentUnit">indent unit</a>. If nothing is 1058 selected, insert a tab character.</dd> 1059 1060 <dt class=command id=command_transposeChars><code><strong>transposeChars</strong></code><span class=keybinding>Ctrl-T (Mac)</span></dt> 1061 <dd>Swap the characters before and after the cursor.</dd> 1062 1063 <dt class=command id=command_newlineAndIndent><code><strong>newlineAndIndent</strong></code><span class=keybinding>Enter</span></dt> 1064 <dd>Insert a newline and auto-indent the new line.</dd> 1065 1066 <dt class=command id=command_toggleOverwrite><code><strong>toggleOverwrite</strong></code><span class=keybinding>Insert</span></dt> 1067 <dd>Flip the <a href="#toggleOverwrite">overwrite</a> flag.</dd> 1068 1069 <dt class=command id=command_save><code><strong>save</strong></code><span class=keybinding>Ctrl-S (PC), Cmd-S (Mac)</span></dt> 1070 <dd>Not defined by the core library, only referred to in 1071 key maps. Intended to provide an easy way for user code to define 1072 a save command.</dd> 1073 1074 <dt class=command id=command_find><code><strong>find</strong></code><span class=keybinding>Ctrl-F (PC), Cmd-F (Mac)</span></dt> 1075 <dt class=command id=command_findNext><code><strong>findNext</strong></code><span class=keybinding>Ctrl-G (PC), Cmd-G (Mac)</span></dt> 1076 <dt class=command id=command_findPrev><code><strong>findPrev</strong></code><span class=keybinding>Shift-Ctrl-G (PC), Shift-Cmd-G (Mac)</span></dt> 1077 <dt class=command id=command_replace><code><strong>replace</strong></code><span class=keybinding>Shift-Ctrl-F (PC), Cmd-Alt-F (Mac)</span></dt> 1078 <dt class=command id=command_replaceAll><code><strong>replaceAll</strong></code><span class=keybinding>Shift-Ctrl-R (PC), Shift-Cmd-Alt-F (Mac)</span></dt> 1079 <dd>Not defined by the core library, but defined in 1080 the <a href="#addon_search">search addon</a> (or custom client 1081 addons).</dd> 1082 1083 </dl> 1084 1085 </section> 1086 1087 <section id=styling> 1088 <h2>Customized Styling</h2> 1089 1090 <p>Up to a certain extent, CodeMirror's look can be changed by 1091 modifying style sheet files. The style sheets supplied by modes 1092 simply provide the colors for that mode, and can be adapted in a 1093 very straightforward way. To style the editor itself, it is 1094 possible to alter or override the styles defined 1095 in <a href="../lib/codemirror.css"><code>codemirror.css</code></a>.</p> 1096 1097 <p>Some care must be taken there, since a lot of the rules in this 1098 file are necessary to have CodeMirror function properly. Adjusting 1099 colors should be safe, of course, and with some care a lot of 1100 other things can be changed as well. The CSS classes defined in 1101 this file serve the following roles:</p> 1102 1103 <dl> 1104 <dt id="class_CodeMirror"><code><strong>CodeMirror</strong></code></dt> 1105 <dd>The outer element of the editor. This should be used for the 1106 editor width, height, borders and positioning. Can also be used 1107 to set styles that should hold for everything inside the editor 1108 (such as font and font size), or to set a background. Setting 1109 this class' <code>height</code> style to <code>auto</code> will 1110 make the editor <a href="../demo/resize.html">resize to fit its 1111 content</a> (it is recommended to also set 1112 the <a href="#option_viewportMargin"><code>viewportMargin</code> 1113 option</a> to <code>Infinity</code> when doing this.</dd> 1114 1115 <dt id="class_CodeMirror_focused"><code><strong>CodeMirror-focused</strong></code></dt> 1116 <dd>Whenever the editor is focused, the top element gets this 1117 class. This is used to hide the cursor and give the selection a 1118 different color when the editor is not focused.</dd> 1119 1120 <dt id="class_CodeMirror_gutters"><code><strong>CodeMirror-gutters</strong></code></dt> 1121 <dd>This is the backdrop for all gutters. Use it to set the 1122 default gutter background color, and optionally add a border on 1123 the right of the gutters.</dd> 1124 1125 <dt id="class_CodeMirror_linenumbers"><code><strong>CodeMirror-linenumbers</strong></code></dt> 1126 <dd>Use this for giving a background or width to the line number 1127 gutter.</dd> 1128 1129 <dt id="class_CodeMirror_linenumber"><code><strong>CodeMirror-linenumber</strong></code></dt> 1130 <dd>Used to style the actual individual line numbers. These 1131 won't be children of the <code>CodeMirror-linenumbers</code> 1132 (plural) element, but rather will be absolutely positioned to 1133 overlay it. Use this to set alignment and text properties for 1134 the line numbers.</dd> 1135 1136 <dt id="class_CodeMirror_lines"><code><strong>CodeMirror-lines</strong></code></dt> 1137 <dd>The visible lines. This is where you specify vertical 1138 padding for the editor content.</dd> 1139 1140 <dt id="class_CodeMirror_cursor"><code><strong>CodeMirror-cursor</strong></code></dt> 1141 <dd>The cursor is a block element that is absolutely positioned. 1142 You can make it look whichever way you want.</dd> 1143 1144 <dt id="class_CodeMirror_selected"><code><strong>CodeMirror-selected</strong></code></dt> 1145 <dd>The selection is represented by <code>span</code> elements 1146 with this class.</dd> 1147 1148 <dt id="class_CodeMirror_matchingbracket"><code><strong>CodeMirror-matchingbracket</strong></code>, 1149 <code><strong>CodeMirror-nonmatchingbracket</strong></code></dt> 1150 <dd>These are used to style matched (or unmatched) brackets.</dd> 1151 </dl> 1152 1153 <p>If your page's style sheets do funky things to 1154 all <code>div</code> or <code>pre</code> elements (you probably 1155 shouldn't do that), you'll have to define rules to cancel these 1156 effects out again for elements under the <code>CodeMirror</code> 1157 class.</p> 1158 1159 <p>Themes are also simply CSS files, which define colors for 1160 various syntactic elements. See the files in 1161 the <a href="../theme/"><code>theme</code></a> directory.</p> 1162 </section> 1163 1164 <section id=api> 1165 <h2>Programming API</h2> 1166 1167 <p>A lot of CodeMirror features are only available through its 1168 API. Thus, you need to write code (or 1169 use <a href="#addons">addons</a>) if you want to expose them to 1170 your users.</p> 1171 1172 <p>Whenever points in the document are represented, the API uses 1173 objects with <code>line</code> and <code>ch</code> properties. 1174 Both are zero-based. CodeMirror makes sure to 'clip' any positions 1175 passed by client code so that they fit inside the document, so you 1176 shouldn't worry too much about sanitizing your coordinates. If you 1177 give <code>ch</code> a value of <code>null</code>, or don't 1178 specify it, it will be replaced with the length of the specified 1179 line. Such positions may also have a <code>sticky</code> property 1180 holding <code>"before"</code> or <code>"after"</code>, whether the 1181 position is associated with the character before or after it. This 1182 influences, for example, where the cursor is drawn on a 1183 line-break or bidi-direction boundary.</p> 1184 1185 <p>Methods prefixed with <code>doc.</code> can, unless otherwise 1186 specified, be called both on <code>CodeMirror</code> (editor) 1187 instances and <code>CodeMirror.Doc</code> instances. Methods 1188 prefixed with <code>cm.</code> are <em>only</em> available 1189 on <code>CodeMirror</code> instances.</p> 1190 1191 <h3 id="api_constructor">Constructor</h3> 1192 1193 <p id="CodeMirror">Constructing an editor instance is done with 1194 the <code><strong>CodeMirror</strong>(place: Element|fn(Element), 1195 ?option: object)</code> constructor. If the <code>place</code> 1196 argument is a DOM element, the editor will be appended to it. If 1197 it is a function, it will be called, and is expected to place the 1198 editor into the document. <code>options</code> may be an element 1199 mapping <a href="#config">option names</a> to values. The options 1200 that it doesn't explicitly specify (or all options, if it is not 1201 passed) will be taken 1202 from <a href="#defaults"><code>CodeMirror.defaults</code></a>.</p> 1203 1204 <p>Note that the options object passed to the constructor will be 1205 mutated when the instance's options 1206 are <a href="#setOption">changed</a>, so you shouldn't share such 1207 objects between instances.</p> 1208 1209 <p>See <a href="#fromTextArea"><code>CodeMirror.fromTextArea</code></a> 1210 for another way to construct an editor instance.</p> 1211 1212 <h3 id="api_content">Content manipulation methods</h3> 1213 1214 <dl> 1215 <dt id="getValue"><code><strong>doc.getValue</strong>(?separator: string) → string</code></dt> 1216 <dd>Get the current editor content. You can pass it an optional 1217 argument to specify the string to be used to separate lines 1218 (defaults to <code>"\n"</code>).</dd> 1219 <dt id="setValue"><code><strong>doc.setValue</strong>(content: string)</code></dt> 1220 <dd>Set the editor content.</dd> 1221 1222 <dt id="getRange"><code><strong>doc.getRange</strong>(from: {line, ch}, to: {line, ch}, ?separator: string) → string</code></dt> 1223 <dd>Get the text between the given points in the editor, which 1224 should be <code>{line, ch}</code> objects. An optional third 1225 argument can be given to indicate the line separator string to 1226 use (defaults to <code>"\n"</code>).</dd> 1227 <dt id="replaceRange"><code><strong>doc.replaceRange</strong>(replacement: string, from: {line, ch}, to: {line, ch}, ?origin: string)</code></dt> 1228 <dd>Replace the part of the document between <code>from</code> 1229 and <code>to</code> with the given string. <code>from</code> 1230 and <code>to</code> must be <code>{line, ch}</code> 1231 objects. <code>to</code> can be left off to simply insert the 1232 string at position <code>from</code>. When <code>origin</code> 1233 is given, it will be passed on 1234 to <a href="#event_change"><code>"change"</code> events</a>, and 1235 its first letter will be used to determine whether this change 1236 can be merged with previous history events, in the way described 1237 for <a href="#selection_origin">selection origins</a>.</dd> 1238 1239 <dt id="getLine"><code><strong>doc.getLine</strong>(n: integer) → string</code></dt> 1240 <dd>Get the content of line <code>n</code>.</dd> 1241 1242 <dt id="lineCount"><code><strong>doc.lineCount</strong>() → integer</code></dt> 1243 <dd>Get the number of lines in the editor.</dd> 1244 <dt id="firstLine"><code><strong>doc.firstLine</strong>() → integer</code></dt> 1245 <dd>Get the first line of the editor. This will 1246 usually be zero but for <a href="#linkedDoc_from">linked sub-views</a>, 1247 or <a href="#api_doc">documents</a> instantiated with a non-zero 1248 first line, it might return other values.</dd> 1249 <dt id="lastLine"><code><strong>doc.lastLine</strong>() → integer</code></dt> 1250 <dd>Get the last line of the editor. This will 1251 usually be <code>doc.lineCount() - 1</code>, 1252 but for <a href="#linkedDoc_from">linked sub-views</a>, 1253 it might return other values.</dd> 1254 1255 <dt id="getLineHandle"><code><strong>doc.getLineHandle</strong>(num: integer) → LineHandle</code></dt> 1256 <dd>Fetches the line handle for the given line number.</dd> 1257 <dt id="getLineNumber"><code><strong>doc.getLineNumber</strong>(handle: LineHandle) → integer</code></dt> 1258 <dd>Given a line handle, returns the current position of that 1259 line (or <code>null</code> when it is no longer in the 1260 document).</dd> 1261 <dt id="eachLine"><code><strong>doc.eachLine</strong>(f: (line: LineHandle))</code></dt> 1262 <dt><code><strong>doc.eachLine</strong>(start: integer, end: integer, f: (line: LineHandle))</code></dt> 1263 <dd>Iterate over the whole document, or if <code>start</code> 1264 and <code>end</code> line numbers are given, the range 1265 from <code>start</code> up to (not including) <code>end</code>, 1266 and call <code>f</code> for each line, passing the line handle. 1267 This is a faster way to visit a range of line handlers than 1268 calling <a href="#getLineHandle"><code>getLineHandle</code></a> 1269 for each of them. Note that line handles have 1270 a <code>text</code> property containing the line's content (as a 1271 string).</dd> 1272 1273 <dt id="markClean"><code><strong>doc.markClean</strong>()</code></dt> 1274 <dd>Set the editor content as 'clean', a flag that it will 1275 retain until it is edited, and which will be set again when such 1276 an edit is undone again. Useful to track whether the content 1277 needs to be saved. This function is deprecated in favor 1278 of <a href="#changeGeneration"><code>changeGeneration</code></a>, 1279 which allows multiple subsystems to track different notions of 1280 cleanness without interfering.</dd> 1281 <dt id="changeGeneration"><code><strong>doc.changeGeneration</strong>(?closeEvent: boolean) → integer</code></dt> 1282 <dd>Returns a number that can later be passed 1283 to <a href="#isClean"><code>isClean</code></a> to test whether 1284 any edits were made (and not undone) in the meantime. 1285 If <code>closeEvent</code> is true, the current history event 1286 will be ‘closed’, meaning it can't be combined with further 1287 changes (rapid typing or deleting events are typically 1288 combined).</dd> 1289 <dt id="isClean"><code><strong>doc.isClean</strong>(?generation: integer) → boolean</code></dt> 1290 <dd>Returns whether the document is currently clean — not 1291 modified since initialization or the last call 1292 to <a href="#markClean"><code>markClean</code></a> if no 1293 argument is passed, or since the matching call 1294 to <a href="#changeGeneration"><code>changeGeneration</code></a> 1295 if a generation value is given.</dd> 1296 </dl> 1297 1298 <h3 id="api_selection">Cursor and selection methods</h3> 1299 1300 <dl> 1301 <dt id="getSelection"><code><strong>doc.getSelection</strong>(?lineSep: string) → string</code></dt> 1302 <dd>Get the currently selected code. Optionally pass a line 1303 separator to put between the lines in the output. When multiple 1304 selections are present, they are concatenated with instances 1305 of <code>lineSep</code> in between.</dd> 1306 <dt id="getSelections"><code><strong>doc.getSelections</strong>(?lineSep: string) → array<string></code></dt> 1307 <dd>Returns an array containing a string for each selection, 1308 representing the content of the selections.</dd> 1309 1310 <dt id="replaceSelection"><code><strong>doc.replaceSelection</strong>(replacement: string, ?select: string)</code></dt> 1311 <dd>Replace the selection(s) with the given string. By default, 1312 the new selection ends up after the inserted text. The 1313 optional <code>select</code> argument can be used to change 1314 this—passing <code>"around"</code> will cause the new text to be 1315 selected, passing <code>"start"</code> will collapse the 1316 selection to the start of the inserted text.</dd> 1317 <dt id="replaceSelections"><code><strong>doc.replaceSelections</strong>(replacements: array<string>, ?select: string)</code></dt> 1318 <dd>The length of the given array should be the same as the 1319 number of active selections. Replaces the content of the 1320 selections with the strings in the array. 1321 The <code>select</code> argument works the same as 1322 in <a href="#replaceSelection"><code>replaceSelection</code></a>.</dd> 1323 1324 <dt id="getCursor"><code><strong>doc.getCursor</strong>(?start: string) → {line, ch}</code></dt> 1325 <dd>Retrieve one end of the <em>primary</em> 1326 selection. <code>start</code> is an optional string indicating 1327 which end of the selection to return. It may 1328 be <code>"from"</code>, <code>"to"</code>, <code>"head"</code> 1329 (the side of the selection that moves when you press 1330 shift+arrow), or <code>"anchor"</code> (the fixed side of the 1331 selection). Omitting the argument is the same as 1332 passing <code>"head"</code>. A <code>{line, ch}</code> object 1333 will be returned.</dd> 1334 <dt id="listSelections"><code><strong>doc.listSelections</strong>() → array<{anchor, head}></code></dt> 1335 <dd>Retrieves a list of all current selections. These will 1336 always be sorted, and never overlap (overlapping selections are 1337 merged). Each object in the array contains <code>anchor</code> 1338 and <code>head</code> properties referring to <code>{line, 1339 ch}</code> objects.</dd> 1340 1341 <dt id="somethingSelected"><code><strong>doc.somethingSelected</strong>() → boolean</code></dt> 1342 <dd>Return true if any text is selected.</dd> 1343 <dt id="setCursor"><code><strong>doc.setCursor</strong>(pos: {line, ch}|number, ?ch: number, ?options: object)</code></dt> 1344 <dd>Set the cursor position. You can either pass a 1345 single <code>{line, ch}</code> object, or the line and the 1346 character as two separate parameters. Will replace all 1347 selections with a single, empty selection at the given position. 1348 The supported options are the same as for <a href="#setSelection"><code>setSelection</code></a>.</dd> 1349 1350 <dt id="setSelection"><code><strong>doc.setSelection</strong>(anchor: {line, ch}, ?head: {line, ch}, ?options: object)</code></dt> 1351 <dd>Set a single selection range. <code>anchor</code> 1352 and <code>head</code> should be <code>{line, ch}</code> 1353 objects. <code>head</code> defaults to <code>anchor</code> when 1354 not given. These options are supported: 1355 <dl> 1356 <dt id="selection_scroll"><code><strong>scroll</strong>: boolean</code></dt> 1357 <dd>Determines whether the selection head should be scrolled 1358 into view. Defaults to true.</dd> 1359 <dt id="selection_origin"><code><strong>origin</strong>: string</code></dt> 1360 <dd>Determines whether the selection history event may be 1361 merged with the previous one. When an origin starts with the 1362 character <code>+</code>, and the last recorded selection had 1363 the same origin and was similar (close 1364 in <a href="#option_historyEventDelay">time</a>, both 1365 collapsed or both non-collapsed), the new one will replace the 1366 old one. When it starts with <code>*</code>, it will always 1367 replace the previous event (if that had the same origin). 1368 Built-in motion uses the <code>"+move"</code> origin. User input uses the <code>"+input"</code> origin.</dd> 1369 <dt id="selection_bias"><code><strong>bias</strong>: number</code></dt> 1370 <dd>Determine the direction into which the selection endpoints 1371 should be adjusted when they fall inside 1372 an <a href="#mark_atomic">atomic</a> range. Can be either -1 1373 (backward) or 1 (forward). When not given, the bias will be 1374 based on the relative position of the old selection—the editor 1375 will try to move further away from that, to prevent getting 1376 stuck.</dd> 1377 </dl></dd> 1378 1379 <dt id="setSelections"><code><strong>doc.setSelections</strong>(ranges: array<{anchor, head}>, ?primary: integer, ?options: object)</code></dt> 1380 <dd>Sets a new set of selections. There must be at least one 1381 selection in the given array. When <code>primary</code> is a 1382 number, it determines which selection is the primary one. When 1383 it is not given, the primary index is taken from the previous 1384 selection, or set to the last range if the previous selection 1385 had less ranges than the new one. Supports the same options 1386 as <a href="#setSelection"><code>setSelection</code></a>.</dd> 1387 <dt id="addSelection"><code><strong>doc.addSelection</strong>(anchor: {line, ch}, ?head: {line, ch})</code></dt> 1388 <dd>Adds a new selection to the existing set of selections, and 1389 makes it the primary selection.</dd> 1390 1391 <dt id="extendSelection"><code><strong>doc.extendSelection</strong>(from: {line, ch}, ?to: {line, ch}, ?options: object)</code></dt> 1392 <dd>Similar 1393 to <a href="#setSelection"><code>setSelection</code></a>, but 1394 will, if shift is held or 1395 the <a href="#setExtending">extending</a> flag is set, move the 1396 head of the selection while leaving the anchor at its current 1397 place. <code>to</code> is optional, and can be passed to ensure 1398 a region (for example a word or paragraph) will end up selected 1399 (in addition to whatever lies between that region and the 1400 current anchor). When multiple selections are present, all but 1401 the primary selection will be dropped by this method. 1402 Supports the same options as <a href="#setSelection"><code>setSelection</code></a>.</dd> 1403 <dt id="extendSelections"><code><strong>doc.extendSelections</strong>(heads: array<{line, ch}>, ?options: object)</code></dt> 1404 <dd>An equivalent 1405 of <a href="#extendSelection"><code>extendSelection</code></a> 1406 that acts on all selections at once.</dd> 1407 <dt id="extendSelectionsBy"><code><strong>doc.extendSelectionsBy</strong>(f: function(range: {anchor, head}) → {line, ch}), ?options: object)</code></dt> 1408 <dd>Applies the given function to all existing selections, and 1409 calls <a href="#extendSelections"><code>extendSelections</code></a> 1410 on the result.</dd> 1411 <dt id="setExtending"><code><strong>doc.setExtending</strong>(value: boolean)</code></dt> 1412 <dd>Sets or clears the 'extending' flag, which acts similar to 1413 the shift key, in that it will cause cursor movement and calls 1414 to <a href="#extendSelection"><code>extendSelection</code></a> 1415 to leave the selection anchor in place.</dd> 1416 <dt id="getExtending"><code><strong>doc.getExtending</strong>() → boolean</code></dt> 1417 <dd>Get the value of the 'extending' flag.</dd> 1418 1419 <dt id="hasFocus"><code><strong>cm.hasFocus</strong>() → boolean</code></dt> 1420 <dd>Tells you whether the editor currently has focus.</dd> 1421 1422 <dt id="findPosH"><code><strong>cm.findPosH</strong>(start: {line, ch}, amount: integer, unit: string, visually: boolean) → {line, ch, ?hitSide: boolean}</code></dt> 1423 <dd>Used to find the target position for horizontal cursor 1424 motion. <code>start</code> is a <code>{line, ch}</code> 1425 object, <code>amount</code> an integer (may be negative), 1426 and <code>unit</code> one of the 1427 string <code>"char"</code>, <code>"column"</code>, 1428 or <code>"word"</code>. Will return a position that is produced 1429 by moving <code>amount</code> times the distance specified 1430 by <code>unit</code>. When <code>visually</code> is true, motion 1431 in right-to-left text will be visual rather than logical. When 1432 the motion was clipped by hitting the end or start of the 1433 document, the returned value will have a <code>hitSide</code> 1434 property set to true.</dd> 1435 <dt id="findPosV"><code><strong>cm.findPosV</strong>(start: {line, ch}, amount: integer, unit: string) → {line, ch, ?hitSide: boolean}</code></dt> 1436 <dd>Similar to <a href="#findPosH"><code>findPosH</code></a>, 1437 but used for vertical motion. <code>unit</code> may 1438 be <code>"line"</code> or <code>"page"</code>. The other 1439 arguments and the returned value have the same interpretation as 1440 they have in <code>findPosH</code>.</dd> 1441 1442 <dt id="findWordAt"><code><strong>cm.findWordAt</strong>(pos: {line, ch}) → {anchor: {line, ch}, head: {line, ch}}</code></dt> 1443 <dd>Returns the start and end of the 'word' (the stretch of 1444 letters, whitespace, or punctuation) at the given position.</dd> 1445 </dl> 1446 1447 <h3 id="api_configuration">Configuration methods</h3> 1448 1449 <dl> 1450 <dt id="setOption"><code><strong>cm.setOption</strong>(option: string, value: any)</code></dt> 1451 <dd>Change the configuration of the editor. <code>option</code> 1452 should the name of an <a href="#config">option</a>, 1453 and <code>value</code> should be a valid value for that 1454 option.</dd> 1455 <dt id="getOption"><code><strong>cm.getOption</strong>(option: string) → any</code></dt> 1456 <dd>Retrieves the current value of the given option for this 1457 editor instance.</dd> 1458 1459 <dt id="addKeyMap"><code><strong>cm.addKeyMap</strong>(map: object, bottom: boolean)</code></dt> 1460 <dd>Attach an additional <a href="#keymaps">key map</a> to the 1461 editor. This is mostly useful for addons that need to register 1462 some key handlers without trampling on 1463 the <a href="#option_extraKeys"><code>extraKeys</code></a> 1464 option. Maps added in this way have a higher precedence than 1465 the <code>extraKeys</code> 1466 and <a href="#option_keyMap"><code>keyMap</code></a> options, 1467 and between them, the maps added earlier have a lower precedence 1468 than those added later, unless the <code>bottom</code> argument 1469 was passed, in which case they end up below other key maps added 1470 with this method.</dd> 1471 <dt id="removeKeyMap"><code><strong>cm.removeKeyMap</strong>(map: object)</code></dt> 1472 <dd>Disable a keymap added 1473 with <a href="#addKeyMap"><code>addKeyMap</code></a>. Either 1474 pass in the key map object itself, or a string, which will be 1475 compared against the <code>name</code> property of the active 1476 key maps.</dd> 1477 1478 <dt id="addOverlay"><code><strong>cm.addOverlay</strong>(mode: string|object, ?options: object)</code></dt> 1479 <dd>Enable a highlighting overlay. This is a stateless mini-mode 1480 that can be used to add extra highlighting. For example, 1481 the <a href="../demo/search.html">search addon</a> uses it to 1482 highlight the term that's currently being 1483 searched. <code>mode</code> can be a <a href="#option_mode">mode 1484 spec</a> or a mode object (an object with 1485 a <a href="#token"><code>token</code></a> method). 1486 The <code>options</code> parameter is optional. If given, it 1487 should be an object, optionally containing the following options: 1488 <dl> 1489 <dt><code><strong>opaque</strong>: bool</code></dt> 1490 <dd>Defaults to off, but can be given to allow the overlay 1491 styling, when not <code>null</code>, to override the styling of 1492 the base mode entirely, instead of the two being applied 1493 together.</dd> 1494 <dt><code><strong>priority</strong>: number</code></dt> 1495 <dd>Determines the ordering in which the overlays are 1496 applied. Those with high priority are applied after those 1497 with lower priority, and able to override the opaqueness of 1498 the ones that come before. Defaults to 0.</dd> 1499 </dl> 1500 </dd> 1501 1502 <dt id="removeOverlay"><code><strong>cm.removeOverlay</strong>(mode: string|object)</code></dt> 1503 <dd>Pass this the exact value passed for the <code>mode</code> 1504 parameter to <a href="#addOverlay"><code>addOverlay</code></a>, 1505 or a string that corresponds to the <code>name</code> property of 1506 that value, to remove an overlay again.</dd> 1507 1508 <dt id="on"><code><strong>cm.on</strong>(type: string, func: (...args))</code></dt> 1509 <dd>Register an event handler for the given event type (a 1510 string) on the editor instance. There is also 1511 a <code>CodeMirror.on(object, type, func)</code> version 1512 that allows registering of events on any object.</dd> 1513 <dt id="off"><code><strong>cm.off</strong>(type: string, func: (...args))</code></dt> 1514 <dd>Remove an event handler on the editor instance. An 1515 equivalent <code>CodeMirror.off(object, type, 1516 func)</code> also exists.</dd> 1517 </dl> 1518 1519 <h3 id="api_doc">Document management methods</h3> 1520 1521 <p id="Doc">Each editor is associated with an instance 1522 of <code>CodeMirror.Doc</code>, its document. A document 1523 represents the editor content, plus a selection, an undo history, 1524 and a <a href="#option_mode">mode</a>. A document can only be 1525 associated with a single editor at a time. You can create new 1526 documents by calling the <code>CodeMirror.Doc(text, mode, 1527 firstLineNumber)</code> constructor. The last two arguments are 1528 optional and can be used to set a mode for the document and make 1529 it start at a line number other than 0, respectively.</p> 1530 1531 <dl> 1532 <dt id="getDoc"><code><strong>cm.getDoc</strong>() → Doc</code></dt> 1533 <dd>Retrieve the currently active document from an editor.</dd> 1534 <dt id="getEditor"><code><strong>doc.getEditor</strong>() → CodeMirror</code></dt> 1535 <dd>Retrieve the editor associated with a document. May 1536 return <code>null</code>.</dd> 1537 1538 <dt id="swapDoc"><code><strong>cm.swapDoc</strong>(doc: CodeMirror.Doc) → Doc</code></dt> 1539 <dd>Attach a new document to the editor. Returns the old 1540 document, which is now no longer associated with an editor.</dd> 1541 1542 <dt id="copy"><code><strong>doc.copy</strong>(copyHistory: boolean) → Doc</code></dt> 1543 <dd>Create an identical copy of the given doc. 1544 When <code>copyHistory</code> is true, the history will also be 1545 copied. Can not be called directly on an editor.</dd> 1546 1547 <dt id="linkedDoc"><code><strong>doc.linkedDoc</strong>(options: object) → Doc</code></dt> 1548 <dd>Create a new document that's linked to the target document. 1549 Linked documents will stay in sync (changes to one are also 1550 applied to the other) until <a href="#unlinkDoc">unlinked</a>. 1551 These are the options that are supported: 1552 <dl> 1553 <dt id="linkedDoc_sharedHist"><code><strong>sharedHist</strong>: boolean</code></dt> 1554 <dd>When turned on, the linked copy will share an undo 1555 history with the original. Thus, something done in one of 1556 the two can be undone in the other, and vice versa.</dd> 1557 <dt id="linkedDoc_from"><code><strong>from</strong>: integer</code></dt> 1558 <dt id="linkedDoc_to"><code><strong>to</strong>: integer</code></dt> 1559 <dd>Can be given to make the new document a subview of the 1560 original. Subviews only show a given range of lines. Note 1561 that line coordinates inside the subview will be consistent 1562 with those of the parent, so that for example a subview 1563 starting at line 10 will refer to its first line as line 10, 1564 not 0.</dd> 1565 <dt id="linkedDoc_mode"><code><strong>mode</strong>: string|object</code></dt> 1566 <dd>By default, the new document inherits the mode of the 1567 parent. This option can be set to 1568 a <a href="#option_mode">mode spec</a> to give it a 1569 different mode.</dd> 1570 </dl></dd> 1571 <dt id="unlinkDoc"><code><strong>doc.unlinkDoc</strong>(doc: CodeMirror.Doc)</code></dt> 1572 <dd>Break the link between two documents. After calling this, 1573 changes will no longer propagate between the documents, and, if 1574 they had a shared history, the history will become 1575 separate.</dd> 1576 <dt id="iterLinkedDocs"><code><strong>doc.iterLinkedDocs</strong>(function: (doc: CodeMirror.Doc, sharedHist: boolean))</code></dt> 1577 <dd>Will call the given function for all documents linked to the 1578 target document. It will be passed two arguments, the linked document 1579 and a boolean indicating whether that document shares history 1580 with the target.</dd> 1581 </dl> 1582 1583 <h3 id="api_history">History-related methods</h3> 1584 1585 <dl> 1586 <dt id="undo"><code><strong>doc.undo</strong>()</code></dt> 1587 <dd>Undo one edit (if any undo events are stored).</dd> 1588 <dt id="redo"><code><strong>doc.redo</strong>()</code></dt> 1589 <dd>Redo one undone edit.</dd> 1590 1591 <dt id="undoSelection"><code><strong>doc.undoSelection</strong>()</code></dt> 1592 <dd>Undo one edit or selection change.</dd> 1593 <dt id="redoSelection"><code><strong>doc.redoSelection</strong>()</code></dt> 1594 <dd>Redo one undone edit or selection change.</dd> 1595 1596 <dt id="historySize"><code><strong>doc.historySize</strong>() → {undo: integer, redo: integer}</code></dt> 1597 <dd>Returns an object with <code>{undo, redo}</code> properties, 1598 both of which hold integers, indicating the amount of stored 1599 undo and redo operations.</dd> 1600 <dt id="clearHistory"><code><strong>doc.clearHistory</strong>()</code></dt> 1601 <dd>Clears the editor's undo history.</dd> 1602 <dt id="getHistory"><code><strong>doc.getHistory</strong>() → object</code></dt> 1603 <dd>Get a (JSON-serializable) representation of the undo history.</dd> 1604 <dt id="setHistory"><code><strong>doc.setHistory</strong>(history: object)</code></dt> 1605 <dd>Replace the editor's undo history with the one provided, 1606 which must be a value as returned 1607 by <a href="#getHistory"><code>getHistory</code></a>. Note that 1608 this will have entirely undefined results if the editor content 1609 isn't also the same as it was when <code>getHistory</code> was 1610 called.</dd> 1611 </dl> 1612 1613 <h3 id="api_marker">Text-marking methods</h3> 1614 1615 <dl> 1616 <dt id="markText"><code><strong>doc.markText</strong>(from: {line, ch}, to: {line, ch}, ?options: object) → TextMarker</code></dt> 1617 <dd>Can be used to mark a range of text with a specific CSS 1618 class name. <code>from</code> and <code>to</code> should 1619 be <code>{line, ch}</code> objects. The <code>options</code> 1620 parameter is optional. When given, it should be an object that 1621 may contain the following configuration options: 1622 <dl> 1623 <dt id="mark_className"><code><strong>className</strong>: string</code></dt> 1624 <dd>Assigns a CSS class to the marked stretch of text.</dd> 1625 <dt id="mark_inclusiveLeft"><code><strong>inclusiveLeft</strong>: boolean</code></dt> 1626 <dd>Determines whether 1627 text inserted on the left of the marker will end up inside 1628 or outside of it.</dd> 1629 <dt id="mark_inclusiveRight"><code><strong>inclusiveRight</strong>: boolean</code></dt> 1630 <dd>Like <code>inclusiveLeft</code>, 1631 but for the right side.</dd> 1632 <dt id="mark_atomic"><code><strong>atomic</strong>: boolean</code></dt> 1633 <dd>Atomic ranges act as a single unit when cursor movement is 1634 concerned—i.e. it is impossible to place the cursor inside of 1635 them. In atomic ranges, <code>inclusiveLeft</code> 1636 and <code>inclusiveRight</code> have a different meaning—they 1637 will prevent the cursor from being placed respectively 1638 directly before and directly after the range.</dd> 1639 <dt id="mark_collapsed"><code><strong>collapsed</strong>: boolean</code></dt> 1640 <dd>Collapsed ranges do not show up in the display. Setting a 1641 range to be collapsed will automatically make it atomic.</dd> 1642 <dt id="mark_clearOnEnter"><code><strong>clearOnEnter</strong>: boolean</code></dt> 1643 <dd>When enabled, will cause the mark to clear itself whenever 1644 the cursor enters its range. This is mostly useful for 1645 text-replacement widgets that need to 'snap open' when the 1646 user tries to edit them. The 1647 <a href="#event_clear"><code>"clear"</code></a> event 1648 fired on the range handle can be used to be notified when this 1649 happens.</dd> 1650 <dt id="mark_clearWhenEmpty"><code><strong>clearWhenEmpty</strong>: boolean</code></dt> 1651 <dd>Determines whether the mark is automatically cleared when 1652 it becomes empty. Default is true.</dd> 1653 <dt id="mark_replacedWith"><code><strong>replacedWith</strong>: Element</code></dt> 1654 <dd>Use a given node to display this range. Implies both 1655 collapsed and atomic. The given DOM node <em>must</em> be an 1656 inline element (as opposed to a block element).</dd> 1657 <dt><code><strong>handleMouseEvents</strong>: boolean</code></dt> 1658 <dd>When <code>replacedWith</code> is given, this determines 1659 whether the editor will capture mouse and drag events 1660 occurring in this widget. Default is false—the events will be 1661 left alone for the default browser handler, or specific 1662 handlers on the widget, to capture.</dd> 1663 <dt id="mark_readOnly"><code><strong>readOnly</strong>: boolean</code></dt> 1664 <dd>A read-only span can, as long as it is not cleared, not be 1665 modified except by 1666 calling <a href="#setValue"><code>setValue</code></a> to reset 1667 the whole document. <em>Note:</em> adding a read-only span 1668 currently clears the undo history of the editor, because 1669 existing undo events being partially nullified by read-only 1670 spans would corrupt the history (in the current 1671 implementation).</dd> 1672 <dt id="mark_addToHistory"><code><strong>addToHistory</strong>: boolean</code></dt> 1673 <dd>When set to true (default is false), adding this marker 1674 will create an event in the undo history that can be 1675 individually undone (clearing the marker).</dd> 1676 <dt id="mark_startStyle"><code><strong>startStyle</strong>: string</code></dt><dd>Can be used to specify 1677 an extra CSS class to be applied to the leftmost span that 1678 is part of the marker.</dd> 1679 <dt id="mark_endStyle"><code><strong>endStyle</strong>: string</code></dt><dd>Equivalent 1680 to <code>startStyle</code>, but for the rightmost span.</dd> 1681 <dt id="mark_css"><code><strong>css</strong>: string</code></dt> 1682 <dd>A string of CSS to be applied to the covered text. For example <code>"color: #fe3"</code>.</dd> 1683 <dt id="mark_title"><code><strong>title</strong>: 1684 string</code></dt><dd>When given, will give the nodes created 1685 for this span a HTML <code>title</code> attribute with the 1686 given value.</dd> 1687 <dt id="mark_shared"><code><strong>shared</strong>: boolean</code></dt><dd>When the 1688 target document is <a href="#linkedDoc">linked</a> to other 1689 documents, you can set <code>shared</code> to true to make the 1690 marker appear in all documents. By default, a marker appears 1691 only in its target document.</dd> 1692 </dl> 1693 The method will return an object that represents the marker 1694 (with constructor <code>CodeMirror.TextMarker</code>), which 1695 exposes three methods: 1696 <code><strong>clear</strong>()</code>, to remove the mark, 1697 <code><strong>find</strong>()</code>, which returns 1698 a <code>{from, to}</code> object (both holding document 1699 positions), indicating the current position of the marked range, 1700 or <code>undefined</code> if the marker is no longer in the 1701 document, and finally <code><strong>changed</strong>()</code>, 1702 which you can call if you've done something that might change 1703 the size of the marker (for example changing the content of 1704 a <a href="#mark_replacedWith"><code>replacedWith</code></a> 1705 node), and want to cheaply update the display.</dd> 1706 1707 <dt id="setBookmark"><code><strong>doc.setBookmark</strong>(pos: {line, ch}, ?options: object) → TextMarker</code></dt> 1708 <dd>Inserts a bookmark, a handle that follows the text around it 1709 as it is being edited, at the given position. A bookmark has two 1710 methods <code>find()</code> and <code>clear()</code>. The first 1711 returns the current position of the bookmark, if it is still in 1712 the document, and the second explicitly removes the bookmark. 1713 The options argument is optional. If given, the following 1714 properties are recognized: 1715 <dl> 1716 <dt><code><strong>widget</strong>: Element</code></dt><dd>Can be used to display a DOM 1717 node at the current location of the bookmark (analogous to 1718 the <a href="#mark_replacedWith"><code>replacedWith</code></a> 1719 option to <a href="#markText"><code>markText</code></a>).</dd> 1720 <dt><code><strong>insertLeft</strong>: boolean</code></dt><dd>By default, text typed 1721 when the cursor is on top of the bookmark will end up to the 1722 right of the bookmark. Set this option to true to make it go 1723 to the left instead.</dd> 1724 <dt><code><strong>shared</strong>: boolean</code></dt><dd>See 1725 the corresponding <a href="#mark_shared">option</a> 1726 to <code>markText</code>.</dd> 1727 <dt><code><strong>handleMouseEvents</strong>: boolean</code></dt> 1728 <dd>As with <a href="#markText"><code>markText</code></a>, 1729 this determines whether mouse events on the widget inserted 1730 for this bookmark are handled by CodeMirror. The default is 1731 false.</dd> 1732 </dl></dd> 1733 1734 <dt id="findMarks"><code><strong>doc.findMarks</strong>(from: {line, ch}, to: {line, ch}) → array<TextMarker></code></dt> 1735 <dd>Returns an array of all the bookmarks and marked ranges 1736 found between the given positions (non-inclusive).</dd> 1737 <dt id="findMarksAt"><code><strong>doc.findMarksAt</strong>(pos: {line, ch}) → array<TextMarker></code></dt> 1738 <dd>Returns an array of all the bookmarks and marked ranges 1739 present at the given position.</dd> 1740 <dt id="getAllMarks"><code><strong>doc.getAllMarks</strong>() → array<TextMarker></code></dt> 1741 <dd>Returns an array containing all marked ranges in the document.</dd> 1742 </dl> 1743 1744 <h3 id="api_decoration">Widget, gutter, and decoration methods</h3> 1745 1746 <dl> 1747 <dt id="setGutterMarker"><code><strong>doc.setGutterMarker</strong>(line: integer|LineHandle, gutterID: string, value: Element) → LineHandle</code></dt> 1748 <dd>Sets the gutter marker for the given gutter (identified by 1749 its CSS class, see 1750 the <a href="#option_gutters"><code>gutters</code></a> option) 1751 to the given value. Value can be either <code>null</code>, to 1752 clear the marker, or a DOM element, to set it. The DOM element 1753 will be shown in the specified gutter next to the specified 1754 line.</dd> 1755 1756 <dt id="clearGutter"><code><strong>doc.clearGutter</strong>(gutterID: string)</code></dt> 1757 <dd>Remove all gutter markers in 1758 the <a href="#option_gutters">gutter</a> with the given ID.</dd> 1759 1760 <dt id="addLineClass"><code><strong>doc.addLineClass</strong>(line: integer|LineHandle, where: string, class: string) → LineHandle</code></dt> 1761 <dd>Set a CSS class name for the given line. <code>line</code> 1762 can be a number or a line handle. <code>where</code> determines 1763 to which element this class should be applied, can can be one 1764 of <code>"text"</code> (the text element, which lies in front of 1765 the selection), <code>"background"</code> (a background element 1766 that will be behind the selection), <code>"gutter"</code> (the 1767 line's gutter space), or <code>"wrap"</code> (the wrapper node 1768 that wraps all of the line's elements, including gutter 1769 elements). <code>class</code> should be the name of the class to 1770 apply.</dd> 1771 1772 <dt id="removeLineClass"><code><strong>doc.removeLineClass</strong>(line: integer|LineHandle, where: string, class: string) → LineHandle</code></dt> 1773 <dd>Remove a CSS class from a line. <code>line</code> can be a 1774 line handle or number. <code>where</code> should be one 1775 of <code>"text"</code>, <code>"background"</code>, 1776 or <code>"wrap"</code> 1777 (see <a href="#addLineClass"><code>addLineClass</code></a>). <code>class</code> 1778 can be left off to remove all classes for the specified node, or 1779 be a string to remove only a specific class.</dd> 1780 1781 <dt id="lineInfo"><code><strong>doc.lineInfo</strong>(line: integer|LineHandle) → object</code></dt> 1782 <dd>Returns the line number, text content, and marker status of 1783 the given line, which can be either a number or a line handle. 1784 The returned object has the structure <code>{line, handle, text, 1785 gutterMarkers, textClass, bgClass, wrapClass, widgets}</code>, 1786 where <code>gutterMarkers</code> is an object mapping gutter IDs 1787 to marker elements, and <code>widgets</code> is an array 1788 of <a href="#addLineWidget">line widgets</a> attached to this 1789 line, and the various class properties refer to classes added 1790 with <a href="#addLineClass"><code>addLineClass</code></a>.</dd> 1791 1792 <dt id="addWidget"><code><strong>cm.addWidget</strong>(pos: {line, ch}, node: Element, scrollIntoView: boolean)</code></dt> 1793 <dd>Puts <code>node</code>, which should be an absolutely 1794 positioned DOM node, into the editor, positioned right below the 1795 given <code>{line, ch}</code> position. 1796 When <code>scrollIntoView</code> is true, the editor will ensure 1797 that the entire node is visible (if possible). To remove the 1798 widget again, simply use DOM methods (move it somewhere else, or 1799 call <code>removeChild</code> on its parent).</dd> 1800 1801 <dt id="addLineWidget"><code><strong>doc.addLineWidget</strong>(line: integer|LineHandle, node: Element, ?options: object) → LineWidget</code></dt> 1802 <dd>Adds a line widget, an element shown below a line, spanning 1803 the whole of the editor's width, and moving the lines below it 1804 downwards. <code>line</code> should be either an integer or a 1805 line handle, and <code>node</code> should be a DOM node, which 1806 will be displayed below the given line. <code>options</code>, 1807 when given, should be an object that configures the behavior of 1808 the widget. The following options are supported (all default to 1809 false): 1810 <dl> 1811 <dt><code><strong>coverGutter</strong>: boolean</code></dt> 1812 <dd>Whether the widget should cover the gutter.</dd> 1813 <dt><code><strong>noHScroll</strong>: boolean</code></dt> 1814 <dd>Whether the widget should stay fixed in the face of 1815 horizontal scrolling.</dd> 1816 <dt><code><strong>above</strong>: boolean</code></dt> 1817 <dd>Causes the widget to be placed above instead of below 1818 the text of the line.</dd> 1819 <dt><code><strong>handleMouseEvents</strong>: boolean</code></dt> 1820 <dd>Determines whether the editor will capture mouse and 1821 drag events occurring in this widget. Default is false—the 1822 events will be left alone for the default browser handler, 1823 or specific handlers on the widget, to capture.</dd> 1824 <dt><code><strong>insertAt</strong>: integer</code></dt> 1825 <dd>By default, the widget is added below other widgets for 1826 the line. This option can be used to place it at a different 1827 position (zero for the top, N to put it after the Nth other 1828 widget). Note that this only has effect once, when the 1829 widget is created. 1830 </dl> 1831 Note that the widget node will become a descendant of nodes with 1832 CodeMirror-specific CSS classes, and those classes might in some 1833 cases affect it. This method returns an object that represents 1834 the widget placement. It'll have a <code>line</code> property 1835 pointing at the line handle that it is associated with, and the following methods: 1836 <dl> 1837 <dt id="widget_clear"><code><strong>clear</strong>()</code></dt><dd>Removes the widget.</dd> 1838 <dt id="widget_changed"><code><strong>changed</strong>()</code></dt><dd>Call 1839 this if you made some change to the widget's DOM node that 1840 might affect its height. It'll force CodeMirror to update 1841 the height of the line that contains the widget.</dd> 1842 </dl> 1843 </dd> 1844 </dl> 1845 1846 <h3 id="api_sizing">Sizing, scrolling and positioning methods</h3> 1847 1848 <dl> 1849 <dt id="setSize"><code><strong>cm.setSize</strong>(width: number|string, height: number|string)</code></dt> 1850 <dd>Programmatically set the size of the editor (overriding the 1851 applicable <a href="#css-resize">CSS 1852 rules</a>). <code>width</code> and <code>height</code> 1853 can be either numbers (interpreted as pixels) or CSS units 1854 (<code>"100%"</code>, for example). You can 1855 pass <code>null</code> for either of them to indicate that that 1856 dimension should not be changed.</dd> 1857 1858 <dt id="scrollTo"><code><strong>cm.scrollTo</strong>(x: number, y: number)</code></dt> 1859 <dd>Scroll the editor to a given (pixel) position. Both 1860 arguments may be left as <code>null</code> 1861 or <code>undefined</code> to have no effect.</dd> 1862 <dt id="getScrollInfo"><code><strong>cm.getScrollInfo</strong>() → {left, top, width, height, clientWidth, clientHeight}</code></dt> 1863 <dd>Get an <code>{left, top, width, height, clientWidth, 1864 clientHeight}</code> object that represents the current scroll 1865 position, the size of the scrollable area, and the size of the 1866 visible area (minus scrollbars).</dd> 1867 <dt id="scrollIntoView"><code><strong>cm.scrollIntoView</strong>(what: {line, ch}|{left, top, right, bottom}|{from, to}|null, ?margin: number)</code></dt> 1868 <dd>Scrolls the given position into view. <code>what</code> may 1869 be <code>null</code> to scroll the cursor into view, 1870 a <code>{line, ch}</code> position to scroll a character into 1871 view, a <code>{left, top, right, bottom}</code> pixel range (in 1872 editor-local coordinates), or a range <code>{from, to}</code> 1873 containing either two character positions or two pixel squares. 1874 The <code>margin</code> parameter is optional. When given, it 1875 indicates the amount of vertical pixels around the given area 1876 that should be made visible as well.</dd> 1877 1878 <dt id="cursorCoords"><code><strong>cm.cursorCoords</strong>(where: boolean|{line, ch}, mode: string) → {left, top, bottom}</code></dt> 1879 <dd>Returns an <code>{left, top, bottom}</code> object 1880 containing the coordinates of the cursor position. 1881 If <code>mode</code> is <code>"local"</code>, they will be 1882 relative to the top-left corner of the editable document. If it 1883 is <code>"page"</code> or not given, they are relative to the 1884 top-left corner of the page. If <code>mode</code> 1885 is <code>"window"</code>, the coordinates are relative to the 1886 top-left corner of the currently visible (scrolled) 1887 window. <code>where</code> can be a boolean indicating whether 1888 you want the start (<code>true</code>) or the end 1889 (<code>false</code>) of the selection, or, if a <code>{line, 1890 ch}</code> object is given, it specifies the precise position at 1891 which you want to measure.</dd> 1892 <dt id="charCoords"><code><strong>cm.charCoords</strong>(pos: {line, ch}, ?mode: string) → {left, right, top, bottom}</code></dt> 1893 <dd>Returns the position and dimensions of an arbitrary 1894 character. <code>pos</code> should be a <code>{line, ch}</code> 1895 object. This differs from <code>cursorCoords</code> in that 1896 it'll give the size of the whole character, rather than just the 1897 position that the cursor would have when it would sit at that 1898 position.</dd> 1899 <dt id="coordsChar"><code><strong>cm.coordsChar</strong>(object: {left, top}, ?mode: string) → {line, ch}</code></dt> 1900 <dd>Given an <code>{left, top}</code> object (e.g. coordinates of a mouse event) returns 1901 the <code>{line, ch}</code> position that corresponds to it. The 1902 optional <code>mode</code> parameter determines relative to what 1903 the coordinates are interpreted. It may 1904 be <code>"window"</code>, <code>"page"</code> (the default), 1905 or <code>"local"</code>.</dd> 1906 <dt id="lineAtHeight"><code><strong>cm.lineAtHeight</strong>(height: number, ?mode: string) → number</code></dt> 1907 <dd>Computes the line at the given pixel 1908 height. <code>mode</code> can be one of the same strings 1909 that <a href="#coordsChar"><code>coordsChar</code></a> 1910 accepts.</dd> 1911 <dt id="heightAtLine"><code><strong>cm.heightAtLine</strong>(line: integer|LineHandle, ?mode: string, ?includeWidgets: bool) → number</code></dt> 1912 <dd>Computes the height of the top of a line, in the coordinate 1913 system specified by <code>mode</code> 1914 (see <a href="#coordsChar"><code>coordsChar</code></a>), which 1915 defaults to <code>"page"</code>. When a line below the bottom of 1916 the document is specified, the returned value is the bottom of 1917 the last line in the document. By default, the position of the 1918 actual text is returned. If `includeWidgets` is true and the 1919 line has line widgets, the position above the first line widget 1920 is returned.</dd> 1921 <dt id="defaultTextHeight"><code><strong>cm.defaultTextHeight</strong>() → number</code></dt> 1922 <dd>Returns the line height of the default font for the editor.</dd> 1923 <dt id="defaultCharWidth"><code><strong>cm.defaultCharWidth</strong>() → number</code></dt> 1924 <dd>Returns the pixel width of an 'x' in the default font for 1925 the editor. (Note that for non-monospace fonts, this is mostly 1926 useless, and even for monospace fonts, non-ascii characters 1927 might have a different width).</dd> 1928 1929 <dt id="getViewport"><code><strong>cm.getViewport</strong>() → {from: number, to: number}</code></dt> 1930 <dd>Returns a <code>{from, to}</code> object indicating the 1931 start (inclusive) and end (exclusive) of the currently rendered 1932 part of the document. In big documents, when most content is 1933 scrolled out of view, CodeMirror will only render the visible 1934 part, and a margin around it. See also 1935 the <a href="#event_viewportChange"><code>viewportChange</code></a> 1936 event.</dd> 1937 1938 <dt id="refresh"><code><strong>cm.refresh</strong>()</code></dt> 1939 <dd>If your code does something to change the size of the editor 1940 element (window resizes are already listened for), or unhides 1941 it, you should probably follow up by calling this method to 1942 ensure CodeMirror is still looking as intended. See also 1943 the <a href="#addon_autorefresh">autorefresh addon</a>.</dd> 1944 </dl> 1945 1946 <h3 id="api_mode">Mode, state, and token-related methods</h3> 1947 1948 <p>When writing language-aware functionality, it can often be 1949 useful to hook into the knowledge that the CodeMirror language 1950 mode has. See <a href="#modeapi">the section on modes</a> for a 1951 more detailed description of how these work.</p> 1952 1953 <dl> 1954 <dt id="getMode"><code><strong>doc.getMode</strong>() → object</code></dt> 1955 <dd>Gets the (outer) mode object for the editor. Note that this 1956 is distinct from <code>getOption("mode")</code>, which gives you 1957 the mode specification, rather than the resolved, instantiated 1958 <a href="#defineMode">mode object</a>.</dd> 1959 1960 <dt id="getModeAt"><code><strong>cm.getModeAt</strong>(pos: {line, ch}) → object</code></dt> 1961 <dd>Gets the inner mode at a given position. This will return 1962 the same as <a href="#getMode"><code>getMode</code></a> for 1963 simple modes, but will return an inner mode for nesting modes 1964 (such as <code>htmlmixed</code>).</dd> 1965 1966 <dt id="getTokenAt"><code><strong>cm.getTokenAt</strong>(pos: {line, ch}, ?precise: boolean) → object</code></dt> 1967 <dd>Retrieves information about the token the current mode found 1968 before the given position (a <code>{line, ch}</code> object). The 1969 returned object has the following properties: 1970 <dl> 1971 <dt><code><strong>start</strong></code></dt><dd>The character (on the given line) at which the token starts.</dd> 1972 <dt><code><strong>end</strong></code></dt><dd>The character at which the token ends.</dd> 1973 <dt><code><strong>string</strong></code></dt><dd>The token's string.</dd> 1974 <dt><code><strong>type</strong></code></dt><dd>The token type the mode assigned 1975 to the token, such as <code>"keyword"</code> 1976 or <code>"comment"</code> (may also be null).</dd> 1977 <dt><code><strong>state</strong></code></dt><dd>The mode's state at the end of this token.</dd> 1978 </dl> 1979 If <code>precise</code> is true, the token will be guaranteed to be accurate based on recent edits. If false or 1980 not specified, the token will use cached state information, which will be faster but might not be accurate if 1981 edits were recently made and highlighting has not yet completed. 1982 </dd> 1983 1984 <dt id="getLineTokens"><code><strong>cm.getLineTokens</strong>(line: integer, ?precise: boolean) → array<{start, end, string, type, state}></code></dt> 1985 <dd>This is similar 1986 to <a href="#getTokenAt"><code>getTokenAt</code></a>, but 1987 collects all tokens for a given line into an array. It is much 1988 cheaper than repeatedly calling <code>getTokenAt</code>, which 1989 re-parses the part of the line before the token for every call.</dd> 1990 1991 <dt id="getTokenTypeAt"><code><strong>cm.getTokenTypeAt</strong>(pos: {line, ch}) → string</code></dt> 1992 <dd>This is a (much) cheaper version 1993 of <a href="#getTokenAt"><code>getTokenAt</code></a> useful for 1994 when you just need the type of the token at a given position, 1995 and no other information. Will return <code>null</code> for 1996 unstyled tokens, and a string, potentially containing multiple 1997 space-separated style names, otherwise.</dd> 1998 1999 <dt id="getHelpers"><code><strong>cm.getHelpers</strong>(pos: {line, ch}, type: string) → array<helper></code></dt> 2000 <dd>Fetch the set of applicable helper values for the given 2001 position. Helpers provide a way to look up functionality 2002 appropriate for a mode. The <code>type</code> argument provides 2003 the helper namespace (see 2004 <a href="#registerHelper"><code>registerHelper</code></a>), in 2005 which the values will be looked up. When the mode itself has a 2006 property that corresponds to the <code>type</code>, that 2007 directly determines the keys that are used to look up the helper 2008 values (it may be either a single string, or an array of 2009 strings). Failing that, the mode's <code>helperType</code> 2010 property and finally the mode's name are used.</dd> 2011 <dd>For example, the JavaScript mode has a 2012 property <code>fold</code> containing <code>"brace"</code>. When 2013 the <code>brace-fold</code> addon is loaded, that defines a 2014 helper named <code>brace</code> in the <code>fold</code> 2015 namespace. This is then used by 2016 the <a href="#addon_foldcode"><code>foldcode</code></a> addon to 2017 figure out that it can use that folding function to fold 2018 JavaScript code.</dd> 2019 <dd>When any <a href="#registerGlobalHelper">'global'</a> 2020 helpers are defined for the given namespace, their predicates 2021 are called on the current mode and editor, and all those that 2022 declare they are applicable will also be added to the array that 2023 is returned.</dd> 2024 2025 <dt id="getHelper"><code><strong>cm.getHelper</strong>(pos: {line, ch}, type: string) → helper</code></dt> 2026 <dd>Returns the first applicable helper value. 2027 See <a href="#getHelpers"><code>getHelpers</code></a>.</dd> 2028 2029 <dt id="getStateAfter"><code><strong>cm.getStateAfter</strong>(?line: integer, ?precise: boolean) → object</code></dt> 2030 <dd>Returns the mode's parser state, if any, at the end of the 2031 given line number. If no line number is given, the state at the 2032 end of the document is returned. This can be useful for storing 2033 parsing errors in the state, or getting other kinds of 2034 contextual information for a line. <code>precise</code> is defined 2035 as in <code>getTokenAt()</code>.</dd> 2036 </dl> 2037 2038 <h3 id="api_misc">Miscellaneous methods</h3> 2039 2040 <dl> 2041 <dt id="operation"><code><strong>cm.operation</strong>(func: () → any) → any</code></dt> 2042 <dd>CodeMirror internally buffers changes and only updates its 2043 DOM structure after it has finished performing some operation. 2044 If you need to perform a lot of operations on a CodeMirror 2045 instance, you can call this method with a function argument. It 2046 will call the function, buffering up all changes, and only doing 2047 the expensive update after the function returns. This can be a 2048 lot faster. The return value from this method will be the return 2049 value of your function.</dd> 2050 2051 <dt id="startOperation"><code><strong>cm.startOperation</strong>()</code></dt> 2052 <dt id="endOperation"><code><strong>cm.endOperation</strong>()</code></dt> 2053 <dd>In normal circumstances, use the above <code>operation</code> 2054 method. But if you want to buffer operations happening asynchronously, 2055 or that can't all be wrapped in a callback function, you can 2056 call <code>startOperation</code> to tell CodeMirror to start 2057 buffering changes, and <code>endOperation</code> to actually 2058 render all the updates. <em>Be careful:</em> if you use this 2059 API and forget to call <code>endOperation</code>, the editor will 2060 just never update.</dd> 2061 2062 <dt id="indentLine"><code><strong>cm.indentLine</strong>(line: integer, ?dir: string|integer)</code></dt> 2063 <dd>Adjust the indentation of the given line. The second 2064 argument (which defaults to <code>"smart"</code>) may be one of: 2065 <dl> 2066 <dt><code><strong>"prev"</strong></code></dt> 2067 <dd>Base indentation on the indentation of the previous line.</dd> 2068 <dt><code><strong>"smart"</strong></code></dt> 2069 <dd>Use the mode's smart indentation if available, behave 2070 like <code>"prev"</code> otherwise.</dd> 2071 <dt><code><strong>"add"</strong></code></dt> 2072 <dd>Increase the indentation of the line by 2073 one <a href="#option_indentUnit">indent unit</a>.</dd> 2074 <dt><code><strong>"subtract"</strong></code></dt> 2075 <dd>Reduce the indentation of the line.</dd> 2076 <dt><code><strong><integer></strong></code></dt> 2077 <dd>Add (positive number) or reduce (negative number) the 2078 indentation by the given amount of spaces.</dd> 2079 </dl></dd> 2080 2081 <dt id="toggleOverwrite"><code><strong>cm.toggleOverwrite</strong>(?value: boolean)</code></dt> 2082 <dd>Switches between overwrite and normal insert mode (when not 2083 given an argument), or sets the overwrite mode to a specific 2084 state (when given an argument).</dd> 2085 2086 <dt id="isReadOnly"><code><strong>cm.isReadOnly</strong>() → boolean</code></dt> 2087 <dd>Tells you whether the editor's content can be edited by the 2088 user.</dd> 2089 2090 <dt id="lineSeparator"><code><strong>doc.lineSeparator</strong>()</code></dt> 2091 <dd>Returns the preferred line separator string for this 2092 document, as per the <a href="#option_lineSeparator">option</a> 2093 by the same name. When that option is <code>null</code>, the 2094 string <code>"\n"</code> is returned.</dd> 2095 2096 <dt id="execCommand"><code><strong>cm.execCommand</strong>(name: string)</code></dt> 2097 <dd>Runs the <a href="#commands">command</a> with the given name on the editor.</dd> 2098 2099 <dt id="posFromIndex"><code><strong>doc.posFromIndex</strong>(index: integer) → {line, ch}</code></dt> 2100 <dd>Calculates and returns a <code>{line, ch}</code> object for a 2101 zero-based <code>index</code> who's value is relative to the start of the 2102 editor's text. If the <code>index</code> is out of range of the text then 2103 the returned object is clipped to start or end of the text 2104 respectively.</dd> 2105 <dt id="indexFromPos"><code><strong>doc.indexFromPos</strong>(object: {line, ch}) → integer</code></dt> 2106 <dd>The reverse of <a href="#posFromIndex"><code>posFromIndex</code></a>.</dd> 2107 2108 <dt id="focus"><code><strong>cm.focus</strong>()</code></dt> 2109 <dd>Give the editor focus.</dd> 2110 2111 <dt id="getInputField"><code><strong>cm.getInputField</strong>() → Element</code></dt> 2112 <dd>Returns the input field for the editor. Will be a textarea 2113 or an editable div, depending on the value of 2114 the <a href="#option_inputStyle"><code>inputStyle</code></a> 2115 option.</dd> 2116 <dt id="getWrapperElement"><code><strong>cm.getWrapperElement</strong>() → Element</code></dt> 2117 <dd>Returns the DOM node that represents the editor, and 2118 controls its size. Remove this from your tree to delete an 2119 editor instance.</dd> 2120 <dt id="getScrollerElement"><code><strong>cm.getScrollerElement</strong>() → Element</code></dt> 2121 <dd>Returns the DOM node that is responsible for the scrolling 2122 of the editor.</dd> 2123 <dt id="getGutterElement"><code><strong>cm.getGutterElement</strong>() → Element</code></dt> 2124 <dd>Fetches the DOM node that contains the editor gutters.</dd> 2125 </dl> 2126 2127 <h3 id="api_static">Static properties</h3> 2128 <p>The <code>CodeMirror</code> object itself provides 2129 several useful properties.</p> 2130 2131 <dl> 2132 <dt id="version"><code><strong>CodeMirror.version</strong>: string</code></dt> 2133 <dd>It contains a string that indicates the version of the 2134 library. This is a triple of 2135 integers <code>"major.minor.patch"</code>, 2136 where <code>patch</code> is zero for releases, and something 2137 else (usually one) for dev snapshots.</dd> 2138 2139 <dt id="fromTextArea"><code><strong>CodeMirror.fromTextArea</strong>(textArea: TextAreaElement, ?config: object)</code></dt> 2140 <dd>This method provides another way to initialize an editor. It 2141 takes a textarea DOM node as first argument and an optional 2142 configuration object as second. It will replace the textarea 2143 with a CodeMirror instance, and wire up the form of that 2144 textarea (if any) to make sure the editor contents are put into 2145 the textarea when the form is submitted. The text in the 2146 textarea will provide the content for the editor. A CodeMirror 2147 instance created this way has three additional methods: 2148 <dl> 2149 <dt id="save"><code><strong>cm.save</strong>()</code></dt> 2150 <dd>Copy the content of the editor into the textarea.</dd> 2151 2152 <dt id="toTextArea"><code><strong>cm.toTextArea</strong>()</code></dt> 2153 <dd>Remove the editor, and restore the original textarea (with 2154 the editor's current content). If you dynamically create and 2155 destroy editors made with `fromTextArea`, without destroying 2156 the form they are part of, you should make sure to call 2157 `toTextArea` to remove the editor, or its `"submit"` handler 2158 on the form will cause a memory leak.</dd> 2159 2160 <dt id="getTextArea"><code><strong>cm.getTextArea</strong>() → TextAreaElement</code></dt> 2161 <dd>Returns the textarea that the instance was based on.</dd> 2162 </dl> 2163 </dd> 2164 2165 <dt id="defaults"><code><strong>CodeMirror.defaults</strong>: object</code></dt> 2166 <dd>An object containing default values for 2167 all <a href="#config">options</a>. You can assign to its 2168 properties to modify defaults (though this won't affect editors 2169 that have already been created).</dd> 2170 2171 <dt id="defineExtension"><code><strong>CodeMirror.defineExtension</strong>(name: string, value: any)</code></dt> 2172 <dd>If you want to define extra methods in terms of the 2173 CodeMirror API, it is possible to 2174 use <code>defineExtension</code>. This will cause the given 2175 value (usually a method) to be added to all CodeMirror instances 2176 created from then on.</dd> 2177 2178 <dt id="defineDocExtension"><code><strong>CodeMirror.defineDocExtension</strong>(name: string, value: any)</code></dt> 2179 <dd>Like <a href="#defineExtension"><code>defineExtension</code></a>, 2180 but the method will be added to the interface 2181 for <a href="#Doc"><code>Doc</code></a> objects instead.</dd> 2182 2183 <dt id="defineOption"><code><strong>CodeMirror.defineOption</strong>(name: string, 2184 default: any, updateFunc: function)</code></dt> 2185 <dd>Similarly, <code>defineOption</code> can be used to define new options for 2186 CodeMirror. The <code>updateFunc</code> will be called with the 2187 editor instance and the new value when an editor is initialized, 2188 and whenever the option is modified 2189 through <a href="#setOption"><code>setOption</code></a>.</dd> 2190 2191 <dt id="defineInitHook"><code><strong>CodeMirror.defineInitHook</strong>(func: function)</code></dt> 2192 <dd>If your extension just needs to run some 2193 code whenever a CodeMirror instance is initialized, 2194 use <code>CodeMirror.defineInitHook</code>. Give it a function as 2195 its only argument, and from then on, that function will be called 2196 (with the instance as argument) whenever a new CodeMirror instance 2197 is initialized.</dd> 2198 2199 <dt id="registerHelper"><code><strong>CodeMirror.registerHelper</strong>(type: string, name: string, value: helper)</code></dt> 2200 <dd>Registers a helper value with the given <code>name</code> in 2201 the given namespace (<code>type</code>). This is used to define 2202 functionality that may be looked up by mode. Will create (if it 2203 doesn't already exist) a property on the <code>CodeMirror</code> 2204 object for the given <code>type</code>, pointing to an object 2205 that maps names to values. I.e. after 2206 doing <code>CodeMirror.registerHelper("hint", "foo", 2207 myFoo)</code>, the value <code>CodeMirror.hint.foo</code> will 2208 point to <code>myFoo</code>.</dd> 2209 2210 <dt id="registerGlobalHelper"><code><strong>CodeMirror.registerGlobalHelper</strong>(type: string, name: string, predicate: fn(mode, CodeMirror), value: helper)</code></dt> 2211 <dd>Acts 2212 like <a href="#registerHelper"><code>registerHelper</code></a>, 2213 but also registers this helper as 'global', meaning that it will 2214 be included by <a href="#getHelpers"><code>getHelpers</code></a> 2215 whenever the given <code>predicate</code> returns true when 2216 called with the local mode and editor.</dd> 2217 2218 <dt id="Pos"><code><strong>CodeMirror.Pos</strong>(line: integer, ?ch: integer, ?sticky: string)</code></dt> 2219 <dd>A constructor for the objects that are used to represent 2220 positions in editor documents. <code>sticky</code> defaults to 2221 null, but can be set to <code>"before"</code> 2222 or <code>"after"</code> to make the position explicitly 2223 associate with the character before or after it.</dd> 2224 2225 <dt id="changeEnd"><code><strong>CodeMirror.changeEnd</strong>(change: object) → {line, ch}</code></dt> 2226 <dd>Utility function that computes an end position from a change 2227 (an object with <code>from</code>, <code>to</code>, 2228 and <code>text</code> properties, as passed to 2229 various <a href="#event_change">event handlers</a>). The 2230 returned position will be the end of the changed 2231 range, <em>after</em> the change is applied.</dd> 2232 2233 <dt id="countColumn"><code><strong>CodeMirror.countColumn</strong>(line: string, index: number, tabSize: number) → number</code></dt> 2234 <dd>Find the column position at a given string index using a given tabsize.</dd> 2235 </dl> 2236 </section> 2237 2238 <section id=addons> 2239 <h2 id="addons">Addons</h2> 2240 2241 <p>The <code>addon</code> directory in the distribution contains a 2242 number of reusable components that implement extra editor 2243 functionality (on top of extension functions 2244 like <a href="#defineOption"><code>defineOption</code></a>, <a href="#defineExtension"><code>defineExtension</code></a>, 2245 and <a href="#registerHelper"><code>registerHelper</code></a>). In 2246 brief, they are:</p> 2247 2248 <dl> 2249 <dt id="addon_dialog"><a href="../addon/dialog/dialog.js"><code>dialog/dialog.js</code></a></dt> 2250 <dd>Provides a very simple way to query users for text input. 2251 Adds the <strong><code>openDialog(template, callback, options) → 2252 closeFunction</code></strong> method to CodeMirror instances, 2253 which can be called with an HTML fragment or a detached DOM 2254 node that provides the prompt (should include an <code>input</code> 2255 or <code>button</code> tag), and a callback function that is called 2256 when the user presses enter. It returns a function <code>closeFunction</code> 2257 which, if called, will close the dialog immediately. 2258 <strong><code>openDialog</code></strong> takes the following options: 2259 <dl> 2260 <dt><code><strong>closeOnEnter</strong>: bool</code></dt> 2261 <dd>If true, the dialog will be closed when the user presses 2262 enter in the input. Defaults to <code>true</code>.</dd> 2263 <dt><code><strong>closeOnBlur</strong>: bool</code></dt> 2264 <dd>Determines whether the dialog is closed when it loses focus. Defaults to <code>true</code>.</dd> 2265 <dt><code><strong>onKeyDown</strong>: fn(event: KeyboardEvent, value: string, close: fn()) → bool</code></dt> 2266 <dd>An event handler that will be called whenever <code>keydown</code> fires in the 2267 dialog's input. If your callback returns <code>true</code>, 2268 the dialog will not do any further processing of the event.</dd> 2269 <dt><code><strong>onKeyUp</strong>: fn(event: KeyboardEvent, value: string, close: fn()) → bool</code></dt> 2270 <dd>Same as <code>onKeyDown</code> but for the 2271 <code>keyup</code> event.</dd> 2272 <dt><code><strong>onInput</strong>: fn(event: InputEvent, value: string, close: fn()) → bool</code></dt> 2273 <dd>Same as <code>onKeyDown</code> but for the 2274 <code>input</code> event.</dd> 2275 <dt><code><strong>onClose</strong>: fn(instance)</code>:</dt> 2276 <dd>A callback that will be called after the dialog has been closed and 2277 removed from the DOM. No return value.</dd> 2278 </dl> 2279 2280 <p>Also adds an <strong><code>openNotification(template, options) → 2281 closeFunction</code></strong> function that simply shows an HTML 2282 fragment as a notification at the top of the editor. It takes a 2283 single option: <code>duration</code>, the amount of time after 2284 which the notification will be automatically closed. If <code> 2285 duration</code> is zero, the dialog will not be closed automatically.</p> 2286 2287 <p>Depends on <code>addon/dialog/dialog.css</code>.</p></dd> 2288 2289 <dt id="addon_searchcursor"><a href="../addon/search/searchcursor.js"><code>search/searchcursor.js</code></a></dt> 2290 <dd>Adds the <code>getSearchCursor(query, start, options) → 2291 cursor</code> method to CodeMirror instances, which can be used 2292 to implement search/replace functionality. <code>query</code> 2293 can be a regular expression or a string. <code>start</code> 2294 provides the starting position of the search. It can be 2295 a <code>{line, ch}</code> object, or can be left off to default 2296 to the start of the document. <code>options</code> is an 2297 optional object, which can contain the property `caseFold: 2298 false` to disable case folding when mathing a string, or the 2299 property `multiline: disable` to disable multi-line matching for 2300 regular expressions (which may help performance). A search 2301 cursor has the following methods: 2302 <dl> 2303 <dt><code><strong>findNext</strong>() → boolean</code></dt> 2304 <dt><code><strong>findPrevious</strong>() → boolean</code></dt> 2305 <dd>Search forward or backward from the current position. 2306 The return value indicates whether a match was found. If 2307 matching a regular expression, the return value will be the 2308 array returned by the <code>match</code> method, in case you 2309 want to extract matched groups.</dd> 2310 <dt><code><strong>from</strong>() → {line, ch}</code></dt> 2311 <dt><code><strong>to</strong>() → {line, ch}</code></dt> 2312 <dd>These are only valid when the last call 2313 to <code>findNext</code> or <code>findPrevious</code> did 2314 not return false. They will return <code>{line, ch}</code> 2315 objects pointing at the start and end of the match.</dd> 2316 <dt><code><strong>replace</strong>(text: string, ?origin: string)</code></dt> 2317 <dd>Replaces the currently found match with the given text 2318 and adjusts the cursor position to reflect the 2319 replacement.</dd> 2320 </dl></dd> 2321 2322 <dt id="addon_search"><a href="../addon/search/search.js"><code>search/search.js</code></a></dt> 2323 <dd>Implements the search commands. CodeMirror has keys bound to 2324 these by default, but will not do anything with them unless an 2325 implementation is provided. Depends 2326 on <code>searchcursor.js</code>, and will make use 2327 of <a href="#addon_dialog"><code>openDialog</code></a> when 2328 available to make prompting for search queries less ugly.</dd> 2329 2330 <dt id="addon_jump-to-line"><a href="../addon/search/jump-to-line.js"><code>search/jump-to-line.js</code></a></dt> 2331 <dd>Implements a <code>jumpToLine</code> command and binding <code>Alt-G</code> to it. 2332 Accepts <code>linenumber</code>, <code>+/-linenumber</code>, <code>line:char</code>, 2333 <code>scroll%</code> and <code>:linenumber</code> formats. 2334 This will make use of <a href="#addon_dialog"><code>openDialog</code></a> 2335 when available to make prompting for line number neater.</dd> 2336 2337 <dt id="addon_matchesonscrollbar"><a href="../addon/search/matchesonscrollbar.js"><code>search/matchesonscrollbar.js</code></a></dt> 2338 <dd>Adds a <code>showMatchesOnScrollbar</code> method to editor 2339 instances, which should be given a query (string or regular 2340 expression), optionally a case-fold flag (only applicable for 2341 strings), and optionally a class name (defaults 2342 to <code>CodeMirror-search-match</code>) as arguments. When 2343 called, matches of the given query will be displayed on the 2344 editor's vertical scrollbar. The method returns an object with 2345 a <code>clear</code> method that can be called to remove the 2346 matches. Depends on 2347 the <a href="#addon_annotatescrollbar"><code>annotatescrollbar</code></a> 2348 addon, and 2349 the <a href="../addon/search/matchesonscrollbar.css"><code>matchesonscrollbar.css</code></a> 2350 file provides a default (transparent yellowish) definition of 2351 the CSS class applied to the matches. Note that the matches are 2352 only perfectly aligned if your scrollbar does not have buttons 2353 at the top and bottom. You can use 2354 the <a href="#addon_simplescrollbars"><code>simplescrollbar</code></a> 2355 addon to make sure of this. If this addon is loaded, 2356 the <a href="#addon_search"><code>search</code></a> addon will 2357 automatically use it.</dd> 2358 2359 <dt id="addon_matchbrackets"><a href="../addon/edit/matchbrackets.js"><code>edit/matchbrackets.js</code></a></dt> 2360 <dd>Defines an option <code>matchBrackets</code> which, when set 2361 to true or an options object, causes matching brackets to be 2362 highlighted whenever the cursor is next to them. It also adds a 2363 method <code>matchBrackets</code> that forces this to happen 2364 once, and a method <code>findMatchingBracket</code> that can be 2365 used to run the bracket-finding algorithm that this uses 2366 internally. It takes a start position and an optional config 2367 object. By default, it will find the match to a matchable 2368 character either before or after the cursor (preferring the one 2369 before), but you can control its behavior with these options: 2370 <dl> 2371 <dt><strong><code>afterCursor</code></strong></dt> 2372 <dd>Only use the character after the start position, never the one before it.</dd> 2373 <dt><strong><code>strict</code></strong></dt> 2374 <dd>Causes only matches where both brackets are at the same side of the start position to be considered.</dd> 2375 <dt><strong><code>maxScanLines</code></strong></dt> 2376 <dd>Stop after scanning this amount of lines without a successful match. Defaults to 1000.</dd> 2377 <dt><strong><code>maxScanLineLength</code></strong></dt> 2378 <dd>Ignore lines longer than this. Defaults to 10000.</dd> 2379 </dl></dd> 2380 2381 <dt id="addon_closebrackets"><a href="../addon/edit/closebrackets.js"><code>edit/closebrackets.js</code></a></dt> 2382 <dd>Defines an option <code>autoCloseBrackets</code> that will 2383 auto-close brackets and quotes when typed. By default, it'll 2384 auto-close <code>()[]{}''""</code>, but you can pass it a string 2385 similar to that (containing pairs of matching characters), or an 2386 object with <code>pairs</code> and 2387 optionally <code>explode</code> properties to customize 2388 it. <code>explode</code> should be a similar string that gives 2389 the pairs of characters that, when enter is pressed between 2390 them, should have the second character also moved to its own 2391 line. By default, if the active mode has 2392 a <code>closeBrackets</code> property, that overrides the 2393 configuration given in the option. But you can add 2394 an <code>override</code> property with a truthy value to 2395 override mode-specific 2396 configuration. <a href="../demo/closebrackets.html">Demo 2397 here</a>.</dd> 2398 2399 <dt id="addon_matchtags"><a href="../addon/edit/matchtags.js"><code>edit/matchtags.js</code></a></dt> 2400 <dd>Defines an option <code>matchTags</code> that, when enabled, 2401 will cause the tags around the cursor to be highlighted (using 2402 the <code>CodeMirror-matchingtag</code> class). Also 2403 defines 2404 a <a href="#commands">command</a> <code>toMatchingTag</code>, 2405 which you can bind a key to in order to jump to the tag matching 2406 the one under the cursor. Depends on 2407 the <code>addon/fold/xml-fold.js</code> 2408 addon. <a href="../demo/matchtags.html">Demo here.</a></dd> 2409 2410 <dt id="addon_trailingspace"><a href="../addon/edit/trailingspace.js"><code>edit/trailingspace.js</code></a></dt> 2411 <dd>Adds an option <code>showTrailingSpace</code> which, when 2412 enabled, adds the CSS class <code>cm-trailingspace</code> to 2413 stretches of whitespace at the end of lines. 2414 The <a href="../demo/trailingspace.html">demo</a> has a nice 2415 squiggly underline style for this class.</dd> 2416 2417 <dt id="addon_closetag"><a href="../addon/edit/closetag.js"><code>edit/closetag.js</code></a></dt> 2418 <dd>Defines an <code>autoCloseTags</code> option that will 2419 auto-close XML tags when '<code>></code>' or '<code>/</code>' 2420 is typed, and 2421 a <code>closeTag</code> <a href="#commands">command</a> that 2422 closes the nearest open tag. Depends on 2423 the <code>fold/xml-fold.js</code> addon. See 2424 the <a href="../demo/closetag.html">demo</a>.</dd> 2425 2426 <dt id="addon_continuelist"><a href="../addon/edit/continuelist.js"><code>edit/continuelist.js</code></a></dt> 2427 <dd>Markdown specific. Defines 2428 a <code>"newlineAndIndentContinueMarkdownList"</code> <a href="#commands">command</a> 2429 that can be bound to <code>enter</code> to automatically 2430 insert the leading characters for continuing a list. See 2431 the <a href="../mode/markdown/index.html">Markdown mode 2432 demo</a>.</dd> 2433 2434 <dt id="addon_comment"><a href="../addon/comment/comment.js"><code>comment/comment.js</code></a></dt> 2435 <dd>Addon for commenting and uncommenting code. Adds four 2436 methods to CodeMirror instances: 2437 <dl> 2438 <dt id="toggleComment"><code><strong>toggleComment</strong>(from: {line, ch}, to: {line, ch}, ?options: object)</code></dt> 2439 <dd>Tries to uncomment the current selection, and if that 2440 fails, line-comments it.</dd> 2441 <dt id="lineComment"><code><strong>lineComment</strong>(from: {line, ch}, to: {line, ch}, ?options: object)</code></dt> 2442 <dd>Set the lines in the given range to be line comments. Will 2443 fall back to <code>blockComment</code> when no line comment 2444 style is defined for the mode.</dd> 2445 <dt id="blockComment"><code><strong>blockComment</strong>(from: {line, ch}, to: {line, ch}, ?options: object)</code></dt> 2446 <dd>Wrap the code in the given range in a block comment. Will 2447 fall back to <code>lineComment</code> when no block comment 2448 style is defined for the mode.</dd> 2449 <dt id="uncomment"><code><strong>uncomment</strong>(from: {line, ch}, to: {line, ch}, ?options: object) → boolean</code></dt> 2450 <dd>Try to uncomment the given range. 2451 Returns <code>true</code> if a comment range was found and 2452 removed, <code>false</code> otherwise.</dd> 2453 </dl> 2454 The <code>options</code> object accepted by these methods may 2455 have the following properties: 2456 <dl> 2457 <dt><code>blockCommentStart, blockCommentEnd, blockCommentLead, lineComment: string</code></dt> 2458 <dd>Override the <a href="#mode_comment">comment string 2459 properties</a> of the mode with custom comment strings.</dd> 2460 <dt><code><strong>padding</strong>: string</code></dt> 2461 <dd>A string that will be inserted after opening and leading 2462 markers, and before closing comment markers. Defaults to a 2463 single space.</dd> 2464 <dt><code><strong>commentBlankLines</strong>: boolean</code></dt> 2465 <dd>Whether, when adding line comments, to also comment lines 2466 that contain only whitespace.</dd> 2467 <dt><code><strong>indent</strong>: boolean</code></dt> 2468 <dd>When adding line comments and this is turned on, it will 2469 align the comment block to the current indentation of the 2470 first line of the block.</dd> 2471 <dt><code><strong>fullLines</strong>: boolean</code></dt> 2472 <dd>When block commenting, this controls whether the whole 2473 lines are indented, or only the precise range that is given. 2474 Defaults to <code>true</code>.</dd> 2475 </dl> 2476 The addon also defines 2477 a <code>toggleComment</code> <a href="#commands">command</a>, 2478 which is a shorthand command for calling 2479 <code>toggleComment</code> with no options.</dd> 2480 2481 <dt id="addon_foldcode"><a href="../addon/fold/foldcode.js"><code>fold/foldcode.js</code></a></dt> 2482 <dd>Helps with code folding. Adds a <code>foldCode</code> method 2483 to editor instances, which will try to do a code fold starting 2484 at the given line, or unfold the fold that is already present. 2485 The method takes as first argument the position that should be 2486 folded (may be a line number or 2487 a <a href="#Pos"><code>Pos</code></a>), and as second optional 2488 argument either a range-finder function, or an options object, 2489 supporting the following properties: 2490 <dl> 2491 <dt><code><strong>rangeFinder</strong>: fn(CodeMirror, Pos)</code></dt> 2492 <dd id="helper_fold_auto">The function that is used to find 2493 foldable ranges. If this is not directly passed, it will 2494 default to <code>CodeMirror.fold.auto</code>, which 2495 uses <a href="#getHelpers"><code>getHelpers</code></a> with 2496 a <code>"fold"</code> type to find folding functions 2497 appropriate for the local mode. There are files in 2498 the <a href="../addon/fold/"><code>addon/fold/</code></a> 2499 directory providing <code>CodeMirror.fold.brace</code>, which 2500 finds blocks in brace languages (JavaScript, C, Java, 2501 etc), <code>CodeMirror.fold.indent</code>, for languages where 2502 indentation determines block structure (Python, Haskell), 2503 and <code>CodeMirror.fold.xml</code>, for XML-style languages, 2504 and <code>CodeMirror.fold.comment</code>, for folding comment 2505 blocks.</dd> 2506 <dt><code><strong>widget</strong>: string|Element</code></dt> 2507 <dd>The widget to show for folded ranges. Can be either a 2508 string, in which case it'll become a span with 2509 class <code>CodeMirror-foldmarker</code>, or a DOM node.</dd> 2510 <dt><code><strong>scanUp</strong>: boolean</code></dt> 2511 <dd>When true (default is false), the addon will try to find 2512 foldable ranges on the lines above the current one if there 2513 isn't an eligible one on the given line.</dd> 2514 <dt><code><strong>minFoldSize</strong>: integer</code></dt> 2515 <dd>The minimum amount of lines that a fold should span to be 2516 accepted. Defaults to 0, which also allows single-line 2517 folds.</dd> 2518 </dl> 2519 See <a href="../demo/folding.html">the demo</a> for an 2520 example.</dd> 2521 2522 <dt id="addon_foldgutter"><a href="../addon/fold/foldgutter.js"><code>fold/foldgutter.js</code></a></dt> 2523 <dd>Provides an option <code>foldGutter</code>, which can be 2524 used to create a gutter with markers indicating the blocks that 2525 can be folded. Create a gutter using 2526 the <a href="#option_gutters"><code>gutters</code></a> option, 2527 giving it the class <code>CodeMirror-foldgutter</code> or 2528 something else if you configure the addon to use a different 2529 class, and this addon will show markers next to folded and 2530 foldable blocks, and handle clicks in this gutter. Note that 2531 CSS styles should be applied to make the gutter, and the fold 2532 markers within it, visible. A default set of CSS styles are 2533 available in: 2534 <a href="../addon/fold/foldgutter.css"> 2535 <code>addon/fold/foldgutter.css</code> 2536 </a>. 2537 The option 2538 can be either set to <code>true</code>, or an object containing 2539 the following optional option fields: 2540 <dl> 2541 <dt><code><strong>gutter</strong>: string</code></dt> 2542 <dd>The CSS class of the gutter. Defaults 2543 to <code>"CodeMirror-foldgutter"</code>. You will have to 2544 style this yourself to give it a width (and possibly a 2545 background). See the default gutter style rules above.</dd> 2546 <dt><code><strong>indicatorOpen</strong>: string | Element</code></dt> 2547 <dd>A CSS class or DOM element to be used as the marker for 2548 open, foldable blocks. Defaults 2549 to <code>"CodeMirror-foldgutter-open"</code>.</dd> 2550 <dt><code><strong>indicatorFolded</strong>: string | Element</code></dt> 2551 <dd>A CSS class or DOM element to be used as the marker for 2552 folded blocks. Defaults to <code>"CodeMirror-foldgutter-folded"</code>.</dd> 2553 <dt><code><strong>rangeFinder</strong>: fn(CodeMirror, Pos)</code></dt> 2554 <dd>The range-finder function to use when determining whether 2555 something can be folded. When not 2556 given, <a href="#helper_fold_auto"><code>CodeMirror.fold.auto</code></a> 2557 will be used as default.</dd> 2558 </dl> 2559 The <code>foldOptions</code> editor option can be set to an 2560 object to provide an editor-wide default configuration. 2561 Demo <a href="../demo/folding.html">here</a>.</dd> 2562 2563 <dt id="addon_runmode"><a href="../addon/runmode/runmode.js"><code>runmode/runmode.js</code></a></dt> 2564 <dd>Can be used to run a CodeMirror mode over text without 2565 actually opening an editor instance. 2566 See <a href="../demo/runmode.html">the demo</a> for an example. 2567 There are alternate versions of the file available for 2568 running <a href="../addon/runmode/runmode-standalone.js">stand-alone</a> 2569 (without including all of CodeMirror) and 2570 for <a href="../addon/runmode/runmode.node.js">running under 2571 node.js</a> (see <code>bin/source-highlight</code> for an example of using the latter).</dd> 2572 2573 <dt id="addon_colorize"><a href="../addon/runmode/colorize.js"><code>runmode/colorize.js</code></a></dt> 2574 <dd>Provides a convenient way to syntax-highlight code snippets 2575 in a webpage. Depends on 2576 the <a href="#addon_runmode"><code>runmode</code></a> addon (or 2577 its standalone variant). Provides 2578 a <code>CodeMirror.colorize</code> function that can be called 2579 with an array (or other array-ish collection) of DOM nodes that 2580 represent the code snippets. By default, it'll get 2581 all <code>pre</code> tags. Will read the <code>data-lang</code> 2582 attribute of these nodes to figure out their language, and 2583 syntax-color their content using the relevant CodeMirror mode 2584 (you'll have to load the scripts for the relevant modes 2585 yourself). A second argument may be provided to give a default 2586 mode, used when no language attribute is found for a node. Used 2587 in this manual to highlight example code.</dd> 2588 2589 <dt id="addon_overlay"><a href="../addon/mode/overlay.js"><code>mode/overlay.js</code></a></dt> 2590 <dd>Mode combinator that can be used to extend a mode with an 2591 'overlay' — a secondary mode is run over the stream, along with 2592 the base mode, and can color specific pieces of text without 2593 interfering with the base mode. 2594 Defines <code>CodeMirror.overlayMode</code>, which is used to 2595 create such a mode. See <a href="../demo/mustache.html">this 2596 demo</a> for a detailed example.</dd> 2597 2598 <dt id="addon_multiplex"><a href="../addon/mode/multiplex.js"><code>mode/multiplex.js</code></a></dt> 2599 <dd>Mode combinator that can be used to easily 'multiplex' 2600 between several modes. 2601 Defines <code>CodeMirror.multiplexingMode</code> which, when 2602 given as first argument a mode object, and as other arguments 2603 any number of <code>{open, close, mode [, delimStyle, innerStyle, parseDelimiters]}</code> 2604 objects, will return a mode object that starts parsing using the 2605 mode passed as first argument, but will switch to another mode 2606 as soon as it encounters a string that occurs in one of 2607 the <code>open</code> fields of the passed objects. When in a 2608 sub-mode, it will go back to the top mode again when 2609 the <code>close</code> string is encountered. 2610 Pass <code>"\n"</code> for <code>open</code> or <code>close</code> 2611 if you want to switch on a blank line. 2612 <ul><li>When <code>delimStyle</code> is specified, it will be the token 2613 style returned for the delimiter tokens (as well as 2614 <code>[delimStyle]-open</code> on the opening token and 2615 <code>[delimStyle]-close</code> on the closing token).</li> 2616 <li>When <code>innerStyle</code> is specified, it will be the token 2617 style added for each inner mode token.</li> 2618 <li>When <code>parseDelimiters</code> is true, the content of 2619 the delimiters will also be passed to the inner mode. 2620 (And <code>delimStyle</code> is ignored.)</li></ul> The outer 2621 mode will not see the content between the delimiters. 2622 See <a href="../demo/multiplex.html">this demo</a> for an 2623 example.</dd> 2624 2625 <dt id="addon_show-hint"><a href="../addon/hint/show-hint.js"><code>hint/show-hint.js</code></a></dt> 2626 <dd>Provides a framework for showing autocompletion hints. 2627 Defines <code>editor.showHint</code>, which takes an optional 2628 options object, and pops up a widget that allows the user to 2629 select a completion. Finding hints is done with a hinting 2630 functions (the <code>hint</code> option), which is a function 2631 that take an editor instance and options object, and return 2632 a <code>{list, from, to}</code> object, where <code>list</code> 2633 is an array of strings or objects (the completions), 2634 and <code>from</code> and <code>to</code> give the start and end 2635 of the token that is being completed as <code>{line, ch}</code> 2636 objects. An optional <code>selectedHint</code> property (an 2637 integer) can be added to the completion object to control the 2638 initially selected hint.</dd> 2639 <dd>If no hinting function is given, the addon will 2640 use <code>CodeMirror.hint.auto</code>, which 2641 calls <a href="#getHelpers"><code>getHelpers</code></a> with 2642 the <code>"hint"</code> type to find applicable hinting 2643 functions, and tries them one by one. If that fails, it looks 2644 for a <code>"hintWords"</code> helper to fetch a list of 2645 completable words for the mode, and 2646 uses <code>CodeMirror.hint.fromList</code> to complete from 2647 those.</dd> 2648 <dd>When completions aren't simple strings, they should be 2649 objects with the following properties: 2650 <dl> 2651 <dt><code><strong>text</strong>: string</code></dt> 2652 <dd>The completion text. This is the only required 2653 property.</dd> 2654 <dt><code><strong>displayText</strong>: string</code></dt> 2655 <dd>The text that should be displayed in the menu.</dd> 2656 <dt><code><strong>className</strong>: string</code></dt> 2657 <dd>A CSS class name to apply to the completion's line in the 2658 menu.</dd> 2659 <dt><code><strong>render</strong>: fn(Element, self, data)</code></dt> 2660 <dd>A method used to create the DOM structure for showing the 2661 completion by appending it to its first argument.</dd> 2662 <dt><code><strong>hint</strong>: fn(CodeMirror, self, data)</code></dt> 2663 <dd>A method used to actually apply the completion, instead of 2664 the default behavior.</dd> 2665 <dt><code><strong>from</strong>: {line, ch}</code></dt> 2666 <dd>Optional <code>from</code> position that will be used by <code>pick()</code> instead 2667 of the global one passed with the full list of completions.</dd> 2668 <dt><code><strong>to</strong>: {line, ch}</code></dt> 2669 <dd>Optional <code>to</code> position that will be used by <code>pick()</code> instead 2670 of the global one passed with the full list of completions.</dd> 2671 </dl></dd> 2672 2673 <dd>The plugin understands the following options, which may be 2674 either passed directly in the argument to <code>showHint</code>, 2675 or provided by setting an <code>hintOptions</code> editor 2676 option to an object (the former takes precedence). The options 2677 object will also be passed along to the hinting function, which 2678 may understand additional options. 2679 <dl> 2680 <dt><code><strong>hint</strong>: function</code></dt> 2681 <dd>A hinting function, as specified above. It is possible to 2682 set the <code>async</code> property on a hinting function to 2683 true, in which case it will be called with 2684 arguments <code>(cm, callback, ?options)</code>, and the 2685 completion interface will only be popped up when the hinting 2686 function calls the callback, passing it the object holding the 2687 completions. 2688 The hinting function can also return a promise, and the completion 2689 interface will only be popped when the promise resolves. 2690 By default, hinting only works when there is no 2691 selection. You can give a hinting function 2692 a <code>supportsSelection</code> property with a truthy value 2693 to indicate that it supports selections.</dd> 2694 <dt><code><strong>completeSingle</strong>: boolean</code></dt> 2695 <dd>Determines whether, when only a single completion is 2696 available, it is completed without showing the dialog. 2697 Defaults to true.</dd> 2698 <dt><code><strong>alignWithWord</strong>: boolean</code></dt> 2699 <dd>Whether the pop-up should be horizontally aligned with the 2700 start of the word (true, default), or with the cursor (false).</dd> 2701 <dt><code><strong>closeOnUnfocus</strong>: boolean</code></dt> 2702 <dd>When enabled (which is the default), the pop-up will close 2703 when the editor is unfocused.</dd> 2704 <dt><code><strong>customKeys</strong>: keymap</code></dt> 2705 <dd>Allows you to provide a custom key map of keys to be active 2706 when the pop-up is active. The handlers will be called with an 2707 extra argument, a handle to the completion menu, which 2708 has <code>moveFocus(n)</code>, <code>setFocus(n)</code>, <code>pick()</code>, 2709 and <code>close()</code> methods (see the source for details), 2710 that can be used to change the focused element, pick the 2711 current element or close the menu. Additionally <code>menuSize()</code> 2712 can give you access to the size of the current dropdown menu, 2713 <code>length</code> give you the number of available completions, and 2714 <code>data</code> give you full access to the completion returned by the 2715 hinting function.</dd> 2716 <dt><code><strong>extraKeys</strong>: keymap</code></dt> 2717 <dd>Like <code>customKeys</code> above, but the bindings will 2718 be added to the set of default bindings, instead of replacing 2719 them.</dd> 2720 </dl> 2721 The following events will be fired on the completions object 2722 during completion: 2723 <dl> 2724 <dt><code><strong>"shown"</strong> ()</code></dt> 2725 <dd>Fired when the pop-up is shown.</dd> 2726 <dt><code><strong>"select"</strong> (completion, Element)</code></dt> 2727 <dd>Fired when a completion is selected. Passed the completion 2728 value (string or object) and the DOM node that represents it 2729 in the menu.</dd> 2730 <dt><code><strong>"pick"</strong> (completion)</code></dt> 2731 <dd>Fired when a completion is picked. Passed the completion value 2732 (string or object).</dd> 2733 <dt><code><strong>"close"</strong> ()</code></dt> 2734 <dd>Fired when the completion is finished.</dd> 2735 </dl> 2736 This addon depends on styles 2737 from <code>addon/hint/show-hint.css</code>. Check 2738 out <a href="../demo/complete.html">the demo</a> for an 2739 example.</dd> 2740 2741 <dt id="addon_javascript-hint"><a href="../addon/hint/javascript-hint.js"><code>hint/javascript-hint.js</code></a></dt> 2742 <dd>Defines a simple hinting function for JavaScript 2743 (<code>CodeMirror.hint.javascript</code>) and CoffeeScript 2744 (<code>CodeMirror.hint.coffeescript</code>) code. This will 2745 simply use the JavaScript environment that the editor runs in as 2746 a source of information about objects and their properties.</dd> 2747 2748 <dt id="addon_xml-hint"><a href="../addon/hint/xml-hint.js"><code>hint/xml-hint.js</code></a></dt> 2749 <dd>Defines <code>CodeMirror.hint.xml</code>, which produces 2750 hints for XML tagnames, attribute names, and attribute values, 2751 guided by a <code>schemaInfo</code> option (a property of the 2752 second argument passed to the hinting function, or the third 2753 argument passed to <code>CodeMirror.showHint</code>).<br>The 2754 schema info should be an object mapping tag names to information 2755 about these tags, with optionally a <code>"!top"</code> property 2756 containing a list of the names of valid top-level tags. The 2757 values of the properties should be objects with optional 2758 properties <code>children</code> (an array of valid child 2759 element names, omit to simply allow all tags to appear) 2760 and <code>attrs</code> (an object mapping attribute names 2761 to <code>null</code> for free-form attributes, and an array of 2762 valid values for restricted 2763 attributes). <a href="../demo/xmlcomplete.html">Demo 2764 here.</a></dd> 2765 2766 <dt id="addon_html-hint"><a href="../addon/hint/html-hint.js"><code>hint/html-hint.js</code></a></dt> 2767 <dd>Provides schema info to 2768 the <a href="#addon_xml-hint">xml-hint</a> addon for HTML 2769 documents. Defines a schema 2770 object <code>CodeMirror.htmlSchema</code> that you can pass to 2771 as a <code>schemaInfo</code> option, and 2772 a <code>CodeMirror.hint.html</code> hinting function that 2773 automatically calls <code>CodeMirror.hint.xml</code> with this 2774 schema data. See 2775 the <a href="../demo/html5complete.html">demo</a>.</dd> 2776 2777 <dt id="addon_css-hint"><a href="../addon/hint/css-hint.js"><code>hint/css-hint.js</code></a></dt> 2778 <dd>A hinting function for CSS, SCSS, or LESS code. 2779 Defines <code>CodeMirror.hint.css</code>.</dd> 2780 2781 <dt id="addon_anyword-hint"><a href="../addon/hint/anyword-hint.js"><code>hint/anyword-hint.js</code></a></dt> 2782 <dd>A very simple hinting function 2783 (<code>CodeMirror.hint.anyword</code>) that simply looks for 2784 words in the nearby code and completes to those. Takes two 2785 optional options, <code>word</code>, a regular expression that 2786 matches words (sequences of one or more character), 2787 and <code>range</code>, which defines how many lines the addon 2788 should scan when completing (defaults to 500).</dd> 2789 2790 <dt id="addon_sql-hint"><a href="../addon/hint/sql-hint.js"><code>hint/sql-hint.js</code></a></dt> 2791 <dd>A simple SQL hinter. Defines <code>CodeMirror.hint.sql</code>. 2792 Takes two optional options, <code>tables</code>, a object with 2793 table names as keys and array of respective column names as values, 2794 and <code>defaultTable</code>, a string corresponding to a 2795 table name in <code>tables</code> for autocompletion.</dd> 2796 2797 <dt id="addon_match-highlighter"><a href="../addon/search/match-highlighter.js"><code>search/match-highlighter.js</code></a></dt> 2798 <dd>Adds a <code>highlightSelectionMatches</code> option that 2799 can be enabled to highlight all instances of a currently 2800 selected word. Can be set either to true or to an object 2801 containing the following options: <code>minChars</code>, for the 2802 minimum amount of selected characters that triggers a highlight 2803 (default 2), <code>style</code>, for the style to be used to 2804 highlight the matches (default <code>"matchhighlight"</code>, 2805 which will correspond to CSS 2806 class <code>cm-matchhighlight</code>), <code>trim</code>, which 2807 controls whether whitespace is trimmed from the selection, 2808 and <code>showToken</code> which can be set to <code>true</code> 2809 or to a regexp matching the characters that make up a word. When 2810 enabled, it causes the current word to be highlighted when 2811 nothing is selected (defaults to off). 2812 Demo <a href="../demo/matchhighlighter.html">here</a>.</dd> 2813 2814 <dt id="addon_lint"><a href="../addon/lint/lint.js"><code>lint/lint.js</code></a></dt> 2815 <dd>Defines an interface component for showing linting warnings, 2816 with pluggable warning sources 2817 (see <a href="../addon/lint/html-lint.js"><code>html-lint.js</code></a>, 2818 <a href="../addon/lint/json-lint.js"><code>json-lint.js</code></a>, 2819 <a href="../addon/lint/javascript-lint.js"><code>javascript-lint.js</code></a>, 2820 <a href="../addon/lint/coffeescript-lint.js"><code>coffeescript-lint.js</code></a>, 2821 and <a href="../addon/lint/css-lint.js"><code>css-lint.js</code></a> 2822 in the same directory). Defines a <code>lint</code> option that 2823 can be set to an annotation source (for 2824 example <code>CodeMirror.lint.javascript</code>), to an options 2825 object (in which case the <code>getAnnotations</code> field is 2826 used as annotation source), or simply to <code>true</code>. When 2827 no annotation source is 2828 specified, <a href="#getHelper"><code>getHelper</code></a> with 2829 type <code>"lint"</code> is used to find an annotation function. 2830 An annotation source function should, when given a document 2831 string, an options object, and an editor instance, return an 2832 array of <code>{message, severity, from, to}</code> objects 2833 representing problems. When the function has 2834 an <code>async</code> property with a truthy value, it will be 2835 called with an additional second argument, which is a callback 2836 to pass the array to. 2837 The linting function can also return a promise, in that case the linter 2838 will only be executed when the promise resolves. 2839 By default, the linter will run (debounced) whenever the document is changed. 2840 You can pass a <code>lintOnChange: false</code> option to disable that. 2841 Depends on <code>addon/lint/lint.css</code>. A demo can be 2842 found <a href="../demo/lint.html">here</a>.</dd> 2843 2844 <dt id="addon_mark-selection"><a href="../addon/selection/mark-selection.js"><code>selection/mark-selection.js</code></a></dt> 2845 <dd>Causes the selected text to be marked with the CSS class 2846 <code>CodeMirror-selectedtext</code> when the <code>styleSelectedText</code> option 2847 is enabled. Useful to change the colour of the selection (in addition to the background), 2848 like in <a href="../demo/markselection.html">this demo</a>.</dd> 2849 2850 <dt id="addon_active-line"><a href="../addon/selection/active-line.js"><code>selection/active-line.js</code></a></dt> 2851 <dd>Defines a <code>styleActiveLine</code> option that, when 2852 enabled, gives the wrapper of the line that contains the cursor 2853 the class <code>CodeMirror-activeline</code>, adds a background 2854 with the class <code>CodeMirror-activeline-background</code>, 2855 and adds the class <code>CodeMirror-activeline-gutter</code> to 2856 the line's gutter space is enabled. The option's value may be a 2857 boolean or an object specifying the following options: 2858 <dl> 2859 <dt><code><strong>nonEmpty</strong>: bool</code></dt> 2860 <dd>Controls whether single-line selections, or just cursor 2861 selections, are styled. Defaults to false (only cursor 2862 selections).</dd> 2863 </dl> 2864 See the <a href="../demo/activeline.html">demo</a>.</dd> 2865 2866 <dt id="addon_selection-pointer"><a href="../addon/selection/selection-pointer.js"><code>selection/selection-pointer.js</code></a></dt> 2867 <dd>Defines a <code>selectionPointer</code> option which you can 2868 use to control the mouse cursor appearance when hovering over 2869 the selection. It can be set to a string, 2870 like <code>"pointer"</code>, or to true, in which case 2871 the <code>"default"</code> (arrow) cursor will be used. You can 2872 see a demo <a href="../mode/htmlmixed/index.html">here</a>.</dd> 2873 2874 <dt id="addon_loadmode"><a href="../addon/mode/loadmode.js"><code>mode/loadmode.js</code></a></dt> 2875 <dd>Defines a <code>CodeMirror.requireMode(modename, 2876 callback)</code> function that will try to load a given mode and 2877 call the callback when it succeeded. You'll have to 2878 set <code>CodeMirror.modeURL</code> to a string that mode paths 2879 can be constructed from, for 2880 example <code>"mode/%N/%N.js"</code>—the <code>%N</code>'s will 2881 be replaced with the mode name. Also 2882 defines <code>CodeMirror.autoLoadMode(instance, mode)</code>, 2883 which will ensure the given mode is loaded and cause the given 2884 editor instance to refresh its mode when the loading 2885 succeeded. See the <a href="../demo/loadmode.html">demo</a>.</dd> 2886 2887 <dt id="addon_meta"><a href="../mode/meta.js"><code>mode/meta.js</code></a></dt> 2888 <dd>Provides meta-information about all the modes in the 2889 distribution in a single file. 2890 Defines <code>CodeMirror.modeInfo</code>, an array of objects 2891 with <code>{name, mime, mode}</code> properties, 2892 where <code>name</code> is the human-readable 2893 name, <code>mime</code> the MIME type, and <code>mode</code> the 2894 name of the mode file that defines this MIME. There are optional 2895 properties <code>mimes</code>, which holds an array of MIME 2896 types for modes with multiple MIMEs associated, 2897 and <code>ext</code>, which holds an array of file extensions 2898 associated with this mode. Four convenience 2899 functions, <code>CodeMirror.findModeByMIME</code>, 2900 <code>CodeMirror.findModeByExtension</code>, 2901 <code>CodeMirror.findModeByFileName</code> 2902 and <code>CodeMirror.findModeByName</code> are provided, which 2903 return such an object given a MIME, extension, file name or mode name 2904 string. Note that, for historical reasons, this file resides in the 2905 top-level <code>mode</code> directory, not 2906 under <code>addon</code>. <a href="../demo/loadmode.html">Demo</a>.</dd> 2907 2908 <dt id="addon_continuecomment"><a href="../addon/comment/continuecomment.js"><code>comment/continuecomment.js</code></a></dt> 2909 <dd>Adds a <code>continueComments</code> option, which sets whether the 2910 editor will make the next line continue a comment when you press Enter 2911 inside a comment block. Can be set to a boolean to enable/disable this 2912 functionality. Set to a string, it will continue comments using a custom 2913 shortcut. Set to an object, it will use the <code>key</code> property for 2914 a custom shortcut and the boolean <code>continueLineComment</code> 2915 property to determine whether single-line comments should be continued 2916 (defaulting to <code>true</code>).</dd> 2917 2918 <dt id="addon_placeholder"><a href="../addon/display/placeholder.js"><code>display/placeholder.js</code></a></dt> 2919 <dd>Adds a <code>placeholder</code> option that can be used to 2920 make content appear in the editor when it is empty and not 2921 focused. It can hold either a string or a DOM node. Also gives 2922 the editor a <code>CodeMirror-empty</code> CSS class whenever it 2923 doesn't contain any text. 2924 See <a href="../demo/placeholder.html">the demo</a>.</dd> 2925 2926 <dt id="addon_fullscreen"><a href="../addon/display/fullscreen.js"><code>display/fullscreen.js</code></a></dt> 2927 <dd>Defines an option <code>fullScreen</code> that, when set 2928 to <code>true</code>, will make the editor full-screen (as in, 2929 taking up the whole browser window). Depends 2930 on <a href="../addon/display/fullscreen.css"><code>fullscreen.css</code></a>. <a href="../demo/fullscreen.html">Demo 2931 here</a>.</dd> 2932 2933 <dt id="addon_autorefresh"><a href="../addon/display/autorefresh.js"><code>display/autorefresh.js</code></a></dt> 2934 <dd>This addon can be useful when initializing an editor in a 2935 hidden DOM node, in cases where it is difficult to 2936 call <a href="#refresh"><code>refresh</code></a> when the editor 2937 becomes visible. It defines an option <code>autoRefresh</code> 2938 which you can set to true to ensure that, if the editor wasn't 2939 visible on initialization, it will be refreshed the first time 2940 it becomes visible. This is done by polling every 250 2941 milliseconds (you can pass a value like <code>{delay: 2942 500}</code> as the option value to configure this). Note that 2943 this addon will only refresh the editor <em>once</em> when it 2944 first becomes visible, and won't take care of further restyling 2945 and resizing.</dd> 2946 2947 <dt id="addon_simplescrollbars"><a href="../addon/scroll/simplescrollbars.js"><code>scroll/simplescrollbars.js</code></a></dt> 2948 <dd>Defines two additional scrollbar 2949 models, <code>"simple"</code> and <code>"overlay"</code> 2950 (see <a href="../demo/simplescrollbars.html">demo</a>) that can 2951 be selected with 2952 the <a href="#option_scrollbarStyle"><code>scrollbarStyle</code></a> 2953 option. Depends 2954 on <a href="../addon/scroll/simplescrollbars.css"><code>simplescrollbars.css</code></a>, 2955 which can be further overridden to style your own 2956 scrollbars.</dd> 2957 2958 <dt id="addon_annotatescrollbar"><a href="../addon/scroll/annotatescrollbar.js"><code>scroll/annotatescrollbar.js</code></a></dt> 2959 <dd>Provides functionality for showing markers on the scrollbar 2960 to call out certain parts of the document. Adds a 2961 method <code>annotateScrollbar</code> to editor instances that 2962 can be called, with a CSS class name as argument, to create a 2963 set of annotations. The method returns an object 2964 whose <code>update</code> method can be called with a sorted array 2965 of <code>{from: Pos, to: Pos}</code> objects marking the ranges 2966 to be highlighted. To detach the annotations, call the 2967 object's <code>clear</code> method.</dd> 2968 2969 <dt id="addon_rulers"><a href="../addon/display/rulers.js"><code>display/rulers.js</code></a></dt> 2970 <dd>Adds a <code>rulers</code> option, which can be used to show 2971 one or more vertical rulers in the editor. The option, if 2972 defined, should be given an array of <code>{column [, className, 2973 color, lineStyle, width]}</code> objects or numbers (which 2974 indicate a column). The ruler will be displayed at the column 2975 indicated by the number or the <code>column</code> property. 2976 The <code>className</code> property can be used to assign a 2977 custom style to a ruler. <a href="../demo/rulers.html">Demo 2978 here</a>.</dd> 2979 2980 <dt id="addon_panel"><a href="../addon/display/panel.js"><code>display/panel.js</code></a></dt> 2981 <dd>Defines an <code>addPanel</code> method for CodeMirror 2982 instances, which places a DOM node above or below an editor, and 2983 shrinks the editor to make room for the node. The method takes 2984 as first argument as DOM node, and as second an optional options 2985 object. The <code>Panel</code> object returned by this method 2986 has a <code>clear</code> method that is used to remove the 2987 panel, and a <code>changed</code> method that can be used to 2988 notify the addon when the size of the panel's DOM node has 2989 changed.<br/> 2990 The method accepts the following options: 2991 <dl> 2992 <dt><code><strong>position</strong>: string</code></dt> 2993 <dd>Controls the position of the newly added panel. The 2994 following values are recognized: 2995 <dl> 2996 <dt><code><strong>top</strong> (default)</code></dt> 2997 <dd>Adds the panel at the very top.</dd> 2998 <dt><code><strong>after-top</strong></code></dt> 2999 <dd>Adds the panel at the bottom of the top panels.</dd> 3000 <dt><code><strong>bottom</strong></code></dt> 3001 <dd>Adds the panel at the very bottom.</dd> 3002 <dt><code><strong>before-bottom</strong></code></dt> 3003 <dd>Adds the panel at the top of the bottom panels.</dd> 3004 </dl> 3005 </dd> 3006 <dt><code><strong>before</strong>: Panel</code></dt> 3007 <dd>The new panel will be added before the given panel.</dd> 3008 <dt><code><strong>after</strong>: Panel</code></dt> 3009 <dd>The new panel will be added after the given panel.</dd> 3010 <dt><code><strong>replace</strong>: Panel</code></dt> 3011 <dd>The new panel will replace the given panel.</dd> 3012 <dt><code><strong>stable</strong>: bool</code></dt> 3013 <dd>Whether to scroll the editor to keep the text's vertical 3014 position stable, when adding a panel above it. Defaults to false.</dd> 3015 </dl> 3016 When using the <code>after</code>, <code>before</code> or <code>replace</code> options, 3017 if the panel doesn't exists or has been removed, 3018 the value of the <code>position</code> option will be used as a fallback. 3019 <br> 3020 A demo of the addon is available <a href="../demo/panel.html">here</a>. 3021 </dd> 3022 3023 <dt id="addon_hardwrap"><a href="../addon/wrap/hardwrap.js"><code>wrap/hardwrap.js</code></a></dt> 3024 <dd>Addon to perform hard line wrapping/breaking for paragraphs 3025 of text. Adds these methods to editor instances: 3026 <dl> 3027 <dt><code><strong>wrapParagraph</strong>(?pos: {line, ch}, ?options: object)</code></dt> 3028 <dd>Wraps the paragraph at the given position. 3029 If <code>pos</code> is not given, it defaults to the cursor 3030 position.</dd> 3031 <dt><code><strong>wrapRange</strong>(from: {line, ch}, to: {line, ch}, ?options: object)</code></dt> 3032 <dd>Wraps the given range as one big paragraph.</dd> 3033 <dt><code><strong>wrapParagraphsInRange</strong>(from: {line, ch}, to: {line, ch}, ?options: object)</code></dt> 3034 <dd>Wraps the paragraphs in (and overlapping with) the 3035 given range individually.</dd> 3036 </dl> 3037 The following options are recognized: 3038 <dl> 3039 <dt><code><strong>paragraphStart</strong>, <strong>paragraphEnd</strong>: RegExp</code></dt> 3040 <dd>Blank lines are always considered paragraph boundaries. 3041 These options can be used to specify a pattern that causes 3042 lines to be considered the start or end of a paragraph.</dd> 3043 <dt><code><strong>column</strong>: number</code></dt> 3044 <dd>The column to wrap at. Defaults to 80.</dd> 3045 <dt><code><strong>wrapOn</strong>: RegExp</code></dt> 3046 <dd>A regular expression that matches only those 3047 two-character strings that allow wrapping. By default, the 3048 addon wraps on whitespace and after dash characters.</dd> 3049 <dt><code><strong>killTrailingSpace</strong>: boolean</code></dt> 3050 <dd>Whether trailing space caused by wrapping should be 3051 preserved, or deleted. Defaults to true.</dd> 3052 </dl> 3053 A demo of the addon is available <a href="../demo/hardwrap.html">here</a>. 3054 </dd> 3055 3056 <dt id="addon_merge"><a href="../addon/merge/merge.js"><code>merge/merge.js</code></a></dt> 3057 <dd>Implements an interface for merging changes, using either a 3058 2-way or a 3-way view. The <code>CodeMirror.MergeView</code> 3059 constructor takes arguments similar to 3060 the <a href="#CodeMirror"><code>CodeMirror</code></a> 3061 constructor, first a node to append the interface to, and then 3062 an options object. Options are passed through to the editors 3063 inside the view. These extra options are recognized: 3064 <dl> 3065 <dt><code><strong>origLeft</strong></code> and <code><strong>origRight</strong>: string</code></dt> 3066 <dd>If given these provide original versions of the 3067 document, which will be shown to the left and right of the 3068 editor in non-editable CodeMirror instances. The merge 3069 interface will highlight changes between the editable 3070 document and the original(s). To create a 2-way (as opposed 3071 to 3-way) merge view, provide only one of them.</dd> 3072 <dt><code><strong>revertButtons</strong>: boolean</code></dt> 3073 <dd>Determines whether buttons that allow the user to revert 3074 changes are shown. Defaults to true.</dd> 3075 <dt><code><strong>revertChunk</strong>: fn(mv: MergeView, from: CodeMirror, fromStart: Pos, fromEnd: Pos, to: CodeMirror, toStart: Pos, toEnd: Pos)</code></dt> 3076 <dd>Can be used to define custom behavior when the user 3077 reverts a changed chunk.</dd> 3078 <dt><code><strong>connect</strong>: string</code></dt> 3079 <dd>Sets the style used to connect changed chunks of code. 3080 By default, connectors are drawn. When this is set 3081 to <code>"align"</code>, the smaller chunk is padded to 3082 align with the bigger chunk instead.</dd> 3083 <dt><code><strong>collapseIdentical</strong>: boolean|number</code></dt> 3084 <dd>When true (default is false), stretches of unchanged 3085 text will be collapsed. When a number is given, this 3086 indicates the amount of lines to leave visible around such 3087 stretches (which defaults to 2).</dd> 3088 <dt><code><strong>allowEditingOriginals</strong>: boolean</code></dt> 3089 <dd>Determines whether the original editor allows editing. 3090 Defaults to false.</dd> 3091 <dt><code><strong>showDifferences</strong>: boolean</code></dt> 3092 <dd>When true (the default), changed pieces of text are 3093 highlighted.</dd> 3094 <dt><code><strong>chunkClassLocation</strong>: string|Array</code></dt> 3095 <dd>By default the chunk highlights are added 3096 using <a href="#addLineClass"><code>addLineClass</code></a> 3097 with "background". Override this to customize it to be any 3098 valid `where` parameter or an Array of valid `where` 3099 parameters.</dd> 3100 </dl> 3101 The addon also defines commands <code>"goNextDiff"</code> 3102 and <code>"goPrevDiff"</code> to quickly jump to the next 3103 changed chunk. <a href="../demo/merge.html">Demo 3104 here</a>.</dd> 3105 3106 <dt id="addon_tern"><a href="../addon/tern/tern.js"><code>tern/tern.js</code></a></dt> 3107 <dd>Provides integration with 3108 the <a href="http://ternjs.net">Tern</a> JavaScript analysis 3109 engine, for completion, definition finding, and minor 3110 refactoring help. See the <a href="../demo/tern.html">demo</a> 3111 for a very simple integration. For more involved scenarios, see 3112 the comments at the top of 3113 the <a href="../addon/tern/tern.js">addon</a> and the 3114 implementation of the 3115 (multi-file) <a href="http://ternjs.net/doc/demo.html">demonstration 3116 on the Tern website</a>.</dd> 3117 </dl> 3118 </section> 3119 3120 <section id=modeapi> 3121 <h2>Writing CodeMirror Modes</h2> 3122 3123 <p>Modes typically consist of a single JavaScript file. This file 3124 defines, in the simplest case, a lexer (tokenizer) for your 3125 language—a function that takes a character stream as input, 3126 advances it past a token, and returns a style for that token. More 3127 advanced modes can also handle indentation for the language.</p> 3128 3129 <p>This section describes the low-level mode interface. Many modes 3130 are written directly against this, since it offers a lot of 3131 control, but for a quick mode definition, you might want to use 3132 the <a href="../demo/simplemode.html">simple mode addon</a>.</p> 3133 3134 <p id="defineMode">The mode script should 3135 call <code><strong>CodeMirror.defineMode</strong></code> to 3136 register itself with CodeMirror. This function takes two 3137 arguments. The first should be the name of the mode, for which you 3138 should use a lowercase string, preferably one that is also the 3139 name of the files that define the mode (i.e. <code>"xml"</code> is 3140 defined in <code>xml.js</code>). The second argument should be a 3141 function that, given a CodeMirror configuration object (the thing 3142 passed to the <code>CodeMirror</code> function) and an optional 3143 mode configuration object (as in 3144 the <a href="#option_mode"><code>mode</code></a> option), returns 3145 a mode object.</p> 3146 3147 <p>Typically, you should use this second argument 3148 to <code>defineMode</code> as your module scope function (modes 3149 should not leak anything into the global scope!), i.e. write your 3150 whole mode inside this function.</p> 3151 3152 <p>The main responsibility of a mode script is <em>parsing</em> 3153 the content of the editor. Depending on the language and the 3154 amount of functionality desired, this can be done in really easy 3155 or extremely complicated ways. Some parsers can be stateless, 3156 meaning that they look at one element (<em>token</em>) of the code 3157 at a time, with no memory of what came before. Most, however, will 3158 need to remember something. This is done by using a <em>state 3159 object</em>, which is an object that is always passed when 3160 reading a token, and which can be mutated by the tokenizer.</p> 3161 3162 <p id="startState">Modes that use a state must define 3163 a <code><strong>startState</strong></code> method on their mode 3164 object. This is a function of no arguments that produces a state 3165 object to be used at the start of a document.</p> 3166 3167 <p id="token">The most important part of a mode object is 3168 its <code><strong>token</strong>(stream, state)</code> method. All 3169 modes must define this method. It should read one token from the 3170 stream it is given as an argument, optionally update its state, 3171 and return a style string, or <code>null</code> for tokens that do 3172 not have to be styled. For your styles, you are encouraged to use 3173 the 'standard' names defined in the themes (without 3174 the <code>cm-</code> prefix). If that fails, it is also possible 3175 to come up with your own and write your own CSS theme file.<p> 3176 3177 <p id="token_style_line">A typical token string would 3178 be <code>"variable"</code> or <code>"comment"</code>. Multiple 3179 styles can be returned (separated by spaces), for 3180 example <code>"string error"</code> for a thing that looks like a 3181 string but is invalid somehow (say, missing its closing quote). 3182 When a style is prefixed by <code>"line-"</code> 3183 or <code>"line-background-"</code>, the style will be applied to 3184 the whole line, analogous to what 3185 the <a href="#addLineClass"><code>addLineClass</code></a> method 3186 does—styling the <code>"text"</code> in the simple case, and 3187 the <code>"background"</code> element 3188 when <code>"line-background-"</code> is prefixed.</p> 3189 3190 <p id="StringStream">The stream object that's passed 3191 to <code>token</code> encapsulates a line of code (tokens may 3192 never span lines) and our current position in that line. It has 3193 the following API:</p> 3194 3195 <dl> 3196 <dt><code><strong>eol</strong>() → boolean</code></dt> 3197 <dd>Returns true only if the stream is at the end of the 3198 line.</dd> 3199 <dt><code><strong>sol</strong>() → boolean</code></dt> 3200 <dd>Returns true only if the stream is at the start of the 3201 line.</dd> 3202 3203 <dt><code><strong>peek</strong>() → string</code></dt> 3204 <dd>Returns the next character in the stream without advancing 3205 it. Will return a <code>null</code> at the end of the 3206 line.</dd> 3207 <dt><code><strong>next</strong>() → string</code></dt> 3208 <dd>Returns the next character in the stream and advances it. 3209 Also returns <code>null</code> when no more characters are 3210 available.</dd> 3211 3212 <dt><code><strong>eat</strong>(match: string|regexp|function(char: string) → boolean) → string</code></dt> 3213 <dd><code>match</code> can be a character, a regular expression, 3214 or a function that takes a character and returns a boolean. If 3215 the next character in the stream 'matches' the given argument, 3216 it is consumed and returned. Otherwise, <code>undefined</code> 3217 is returned.</dd> 3218 <dt><code><strong>eatWhile</strong>(match: string|regexp|function(char: string) → boolean) → boolean</code></dt> 3219 <dd>Repeatedly calls <code>eat</code> with the given argument, 3220 until it fails. Returns true if any characters were eaten.</dd> 3221 <dt><code><strong>eatSpace</strong>() → boolean</code></dt> 3222 <dd>Shortcut for <code>eatWhile</code> when matching 3223 white-space.</dd> 3224 <dt><code><strong>skipToEnd</strong>()</code></dt> 3225 <dd>Moves the position to the end of the line.</dd> 3226 <dt><code><strong>skipTo</strong>(str: string) → boolean</code></dt> 3227 <dd>Skips to the start of the next occurrence of the given string, if 3228 found on the current line (doesn't advance the stream if the 3229 string does not occur on the line). Returns true if the 3230 string was found.</dd> 3231 <dt><code><strong>match</strong>(pattern: string, ?consume: boolean, ?caseFold: boolean) → boolean</code></dt> 3232 <dt><code><strong>match</strong>(pattern: regexp, ?consume: boolean) → array<string></code></dt> 3233 <dd>Act like a 3234 multi-character <code>eat</code>—if <code>consume</code> is true 3235 or not given—or a look-ahead that doesn't update the stream 3236 position—if it is false. <code>pattern</code> can be either a 3237 string or a regular expression starting with <code>^</code>. 3238 When it is a string, <code>caseFold</code> can be set to true to 3239 make the match case-insensitive. When successfully matching a 3240 regular expression, the returned value will be the array 3241 returned by <code>match</code>, in case you need to extract 3242 matched groups.</dd> 3243 3244 <dt><code><strong>backUp</strong>(n: integer)</code></dt> 3245 <dd>Backs up the stream <code>n</code> characters. Backing it up 3246 further than the start of the current token will cause things to 3247 break, so be careful.</dd> 3248 <dt><code><strong>column</strong>() → integer</code></dt> 3249 <dd>Returns the column (taking into account tabs) at which the 3250 current token starts.</dd> 3251 <dt><code><strong>indentation</strong>() → integer</code></dt> 3252 <dd>Tells you how far the current line has been indented, in 3253 spaces. Corrects for tab characters.</dd> 3254 3255 <dt><code><strong>current</strong>() → string</code></dt> 3256 <dd>Get the string between the start of the current token and 3257 the current stream position.</dd> 3258 3259 <dt><code><strong>lookAhead</strong>(n: number) → ?string</code></dt> 3260 <dd>Get the line <code>n</code> (>0) lines after the current 3261 one, in order to scan ahead across line boundaries. Note that 3262 you want to do this carefully, since looking far ahead will make 3263 mode state caching much less effective.</dd> 3264 3265 <dt id="baseToken"><code><strong>baseToken</strong>() → ?{type: ?string, size: number}</code></dt> 3266 <dd>Modes added 3267 through <a href="#addOverlay"><code>addOverlay</code></a> 3268 (and <em>only</em> such modes) can use this method to inspect 3269 the current token produced by the underlying mode.</dd> 3270 </dl> 3271 3272 <p id="blankLine">By default, blank lines are simply skipped when 3273 tokenizing a document. For languages that have significant blank 3274 lines, you can define 3275 a <code><strong>blankLine</strong>(state)</code> method on your 3276 mode that will get called whenever a blank line is passed over, so 3277 that it can update the parser state.</p> 3278 3279 <p id="copyState">Because state object are mutated, and CodeMirror 3280 needs to keep valid versions of a state around so that it can 3281 restart a parse at any line, copies must be made of state objects. 3282 The default algorithm used is that a new state object is created, 3283 which gets all the properties of the old object. Any properties 3284 which hold arrays get a copy of these arrays (since arrays tend to 3285 be used as mutable stacks). When this is not correct, for example 3286 because a mode mutates non-array properties of its state object, a 3287 mode object should define 3288 a <code><strong>copyState</strong></code> method, which is given a 3289 state and should return a safe copy of that state.</p> 3290 3291 <p id="indent">If you want your mode to provide smart indentation 3292 (through the <a href="#indentLine"><code>indentLine</code></a> 3293 method and the <code>indentAuto</code> 3294 and <code>newlineAndIndent</code> commands, to which keys can be 3295 <a href="#option_extraKeys">bound</a>), you must define 3296 an <code><strong>indent</strong>(state, textAfter)</code> method 3297 on your mode object.</p> 3298 3299 <p>The indentation method should inspect the given state object, 3300 and optionally the <code>textAfter</code> string, which contains 3301 the text on the line that is being indented, and return an 3302 integer, the amount of spaces to indent. It should usually take 3303 the <a href="#option_indentUnit"><code>indentUnit</code></a> 3304 option into account. An indentation method may 3305 return <code>CodeMirror.Pass</code> to indicate that it 3306 could not come up with a precise indentation.</p> 3307 3308 <p id="mode_comment">To work well with 3309 the <a href="#addon_comment">commenting addon</a>, a mode may 3310 define <code><strong>lineComment</strong></code> (string that 3311 starts a line 3312 comment), <code><strong>blockCommentStart</strong></code>, <code><strong>blockCommentEnd</strong></code> 3313 (strings that start and end block comments), 3314 and <code>blockCommentLead</code> (a string to put at the start of 3315 continued lines in a block comment). All of these are 3316 optional.</p> 3317 3318 <p id="electricChars">Finally, a mode may define either 3319 an <code>electricChars</code> or an <code>electricInput</code> 3320 property, which are used to automatically reindent the line when 3321 certain patterns are typed and 3322 the <a href="#option_electricChars"><code>electricChars</code></a> 3323 option is enabled. <code>electricChars</code> may be a string, and 3324 will trigger a reindent whenever one of the characters in that 3325 string are typed. Often, it is more appropriate to 3326 use <code>electricInput</code>, which should hold a regular 3327 expression, and will trigger indentation when the part of the 3328 line <em>before</em> the cursor matches the expression. It should 3329 usually end with a <code>$</code> character, so that it only 3330 matches when the indentation-changing pattern was just typed, not when something was 3331 typed after the pattern.</p> 3332 3333 <p>So, to summarize, a mode <em>must</em> provide 3334 a <code>token</code> method, and it <em>may</em> 3335 provide <code>startState</code>, <code>copyState</code>, 3336 and <code>indent</code> methods. For an example of a trivial mode, 3337 see the <a href="../mode/diff/diff.js">diff mode</a>, for a more 3338 involved example, see the <a href="../mode/clike/clike.js">C-like 3339 mode</a>.</p> 3340 3341 <p>Sometimes, it is useful for modes to <em>nest</em>—to have one 3342 mode delegate work to another mode. An example of this kind of 3343 mode is the <a href="../mode/htmlmixed/htmlmixed.js">mixed-mode HTML 3344 mode</a>. To implement such nesting, it is usually necessary to 3345 create mode objects and copy states yourself. To create a mode 3346 object, there are <code>CodeMirror.getMode(options, 3347 parserConfig)</code>, where the first argument is a configuration 3348 object as passed to the mode constructor function, and the second 3349 argument is a mode specification as in 3350 the <a href="#option_mode"><code>mode</code></a> option. To copy a 3351 state object, call <code>CodeMirror.copyState(mode, state)</code>, 3352 where <code>mode</code> is the mode that created the given 3353 state.</p> 3354 3355 <p id="innerMode">In a nested mode, it is recommended to add an 3356 extra method, <code><strong>innerMode</strong></code> which, given 3357 a state object, returns a <code>{state, mode}</code> object with 3358 the inner mode and its state for the current position. These are 3359 used by utility scripts such as the <a href="#addon_closetag">tag 3360 closer</a> to get context information. Use 3361 the <code>CodeMirror.innerMode</code> helper function to, starting 3362 from a mode and a state, recursively walk down to the innermost 3363 mode and state.</p> 3364 3365 <p>To make indentation work properly in a nested parser, it is 3366 advisable to give the <code>startState</code> method of modes that 3367 are intended to be nested an optional argument that provides the 3368 base indentation for the block of code. The JavaScript and CSS 3369 parser do this, for example, to allow JavaScript and CSS code 3370 inside the mixed-mode HTML mode to be properly indented.</p> 3371 3372 <p id="defineMIME">It is possible, and encouraged, to associate 3373 your mode, or a certain configuration of your mode, with 3374 a <a href="http://en.wikipedia.org/wiki/MIME">MIME</a> type. For 3375 example, the JavaScript mode associates itself 3376 with <code>text/javascript</code>, and its JSON variant 3377 with <code>application/json</code>. To do this, 3378 call <code><strong>CodeMirror.defineMIME</strong>(mime, 3379 modeSpec)</code>, where <code>modeSpec</code> can be a string or 3380 object specifying a mode, as in 3381 the <a href="#option_mode"><code>mode</code></a> option.</p> 3382 3383 <p>If a mode specification wants to add some properties to the 3384 resulting mode object, typically for use 3385 with <a href="#getHelpers"><code>getHelpers</code></a>, it may 3386 contain a <code>modeProps</code> property, which holds an object. 3387 This object's properties will be copied to the actual mode 3388 object.</p> 3389 3390 <p id="extendMode">Sometimes, it is useful to add or override mode 3391 object properties from external code. 3392 The <code><strong>CodeMirror.extendMode</strong></code> function 3393 can be used to add properties to mode objects produced for a 3394 specific mode. Its first argument is the name of the mode, its 3395 second an object that specifies the properties that should be 3396 added. This is mostly useful to add utilities that can later be 3397 looked up through <a href="#getMode"><code>getMode</code></a>.</p> 3398 </section> 3399 3400 <section id="vimapi"> 3401 <h2>VIM Mode API</h2> 3402 3403 <p>CodeMirror has a robust VIM mode that attempts to faithfully 3404 emulate VIM's most useful features. It can be enabled by 3405 including <a href="../keymap/vim.js"><code>keymap/vim.js</code> 3406 </a> and setting the <code>keyMap</code> option to 3407 <code>"vim"</code>.</p> 3408 3409 <h3 id="vimapi_configuration">Configuration</h3> 3410 3411 <p>VIM mode accepts configuration options for customizing 3412 behavior at run time. These methods can be called at any time 3413 and will affect all existing CodeMirror instances unless 3414 specified otherwise. The methods are exposed on the 3415 <code><strong>CodeMirror.Vim</strong></code> object.</p> 3416 3417 <dl> 3418 <dt id="vimapi_setOption"><code><strong>setOption(name: string, value: any, ?cm: CodeMirror, ?cfg: object)</strong></code></dt> 3419 <dd>Sets the value of a VIM option. <code>name</code> should 3420 be the name of an option. If <code>cfg.scope</code> is not set 3421 and <code>cm</code> is provided, then sets the global and 3422 instance values of the option. Otherwise, sets either the 3423 global or instance value of the option depending on whether 3424 <code>cfg.scope</code> is <code>global</code> or 3425 <code>local</code>.</dd> 3426 <dt id="vimapi_getOption"><code><strong>getOption(name: string, ?cm: CodeMirror: ?cfg: object)</strong></code></dt> 3427 <dd>Gets the current value of a VIM option. If 3428 <code>cfg.scope</code> is not set and <code>cm</code> is 3429 provided, then gets the instance value of the option, falling 3430 back to the global value if not set. If <code>cfg.scope</code> is provided, then gets the <code>global</code> or 3431 <code>local</code> value without checking the other.</dd> 3432 3433 <dt id="vimapi_map"><code><strong>map(lhs: string, rhs: string, ?context: string)</strong></code></dt> 3434 <dd>Maps a key sequence to another key sequence. Implements 3435 VIM's <code>:map</code> command. To map ; to : in VIM would be 3436 <code><strong>:map ; :</strong></code>. That would translate to 3437 <code><strong>CodeMirror.Vim.map(';', ':');</strong></code>. 3438 The <code>context</code> can be <code>normal</code>, 3439 <code>visual</code>, or <code>insert</code>, which correspond 3440 to <code>:nmap</code>, <code>:vmap</code>, and 3441 <code>:imap</code> 3442 respectively.</dd> 3443 3444 <dt id="vimapi_mapCommand"><code><strong>mapCommand(keys: string, type: string, name: string, ?args: object, ?extra: object)</strong></code></dt> 3445 <dd>Maps a key sequence to a <code>motion</code>, 3446 <code>operator</code>, or <code>action</code> type command. 3447 The args object is passed through to the command when it is 3448 invoked by the provided key sequence. 3449 <code>extras.context</code> can be <code>normal</code>, 3450 <code>visual</code>, or <code>insert</code>, to map the key 3451 sequence only in the corresponding mode. 3452 <code>extras.isEdit</code> is applicable only to actions, 3453 determining whether it is recorded for replay for the 3454 <code>.</code> single-repeat command. 3455 </dl> 3456 3457 <h3 id="vimapi_extending">Extending VIM</h3> 3458 3459 <p>CodeMirror's VIM mode implements a large subset of VIM's core 3460 editing functionality. But since there's always more to be 3461 desired, there is a set of APIs for extending VIM's 3462 functionality. As with the configuration API, the methods are 3463 exposed on <code><strong>CodeMirror.Vim</strong></code> and may 3464 be called at any time.</p> 3465 3466 <dl> 3467 <dt id="vimapi_defineOption"><code><strong>defineOption(name: string, default: any, type: string, ?aliases: array<string>, ?callback: function (?value: any, ?cm: CodeMirror) → ?any)</strong></code></dt> 3468 <dd>Defines a VIM style option and makes it available to the 3469 <code>:set</code> command. Type can be <code>boolean</code> or 3470 <code>string</code>, used for validation and by 3471 <code>:set</code> to determine which syntax to accept. If a 3472 <code>callback</code> is passed in, VIM does not store the value of the 3473 option itself, but instead uses the callback as a setter/getter. If the 3474 first argument to the callback is <code>undefined</code>, then the 3475 callback should return the value of the option. Otherwise, it should set 3476 instead. Since VIM options have global and instance values, whether a 3477 <code>CodeMirror</code> instance is passed in denotes whether the global 3478 or local value should be used. Consequently, it's possible for the 3479 callback to be called twice for a single <code>setOption</code> or 3480 <code>getOption</code> call. Note that right now, VIM does not support 3481 defining buffer-local options that do not have global values. If an 3482 option should not have a global value, either always ignore the 3483 <code>cm</code> parameter in the callback, or always pass in a 3484 <code>cfg.scope</code> to <code>setOption</code> and 3485 <code>getOption</code>.</dd> 3486 3487 <dt id="vimapi_defineMotion"><code><strong>defineMotion(name: string, fn: function(cm: CodeMirror, head: {line, ch}, ?motionArgs: object}) → {line, ch})</strong></code></dt> 3488 <dd>Defines a motion command for VIM. The motion should return 3489 the desired result position of the cursor. <code>head</code> 3490 is the current position of the cursor. It can differ from 3491 <code>cm.getCursor('head')</code> if VIM is in visual mode. 3492 <code>motionArgs</code> is the object passed into 3493 <strong><code>mapCommand()</code></strong>.</dd> 3494 3495 <dt id="vimapi_defineOperator"><strong><code>defineOperator(name: string, fn: function(cm: CodeMirror, ?operatorArgs: object, ranges: array<{anchor, head}>) → ?{line, ch})</code></strong></dt> 3496 <dd>Defines an operator command, similar to <strong><code> 3497 defineMotion</code></strong>. <code>ranges</code> is the range 3498 of text the operator should operate on. If the cursor should 3499 be set to a certain position after the operation finishes, it 3500 can return a cursor object.</dd> 3501 3502 <dt id="vimapi_defineActon"><strong><code>defineAction(name: string, fn: function(cm: CodeMirror, ?actionArgs: object))</code></strong></dt> 3503 <dd>Defines an action command, similar to 3504 <strong><code>defineMotion</code></strong>. Action commands 3505 can have arbitrary behavior, making them more flexible than 3506 motions and operators, at the loss of orthogonality.</dd> 3507 3508 <dt id="vimapi_defineEx"><strong><code>defineEx(name: string, ?prefix: string, fn: function(cm: CodeMirror, ?params: object))</code></strong></dt> 3509 <dd>Defines an Ex command, and maps it to <code>:name</code>. 3510 If a prefix is provided, it, and any prefixed substring of the 3511 <code>name</code> beginning with the <code>prefix</code> can 3512 be used to invoke the command. If the <code>prefix</code> is 3513 falsy, then <code>name</code> is used as the prefix. <code> 3514 params.argString</code> contains the part of the prompted 3515 string after the command name. <code>params.args</code> is 3516 <code>params.argString</code> split by whitespace. If the 3517 command was prefixed with a 3518 <code><strong><a href="http://vimdoc.sourceforge.net/htmldoc/cmdline.html#cmdline-ranges">line range</a></strong></code>, 3519 <code>params.line</code> and <code>params.lineEnd</code> will 3520 be set. 3521 </dl> 3522 3523 </section> 3524 3525 </article> 3526 3527 <script>setTimeout(function(){CodeMirror.colorize();}, 20);</script>