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