--- a/js/flotr2/examples/lib/codemirror/doc/manual.html +++ b/js/flotr2/examples/lib/codemirror/doc/manual.html @@ -1,1 +1,968 @@ - + + +
++/* User manual and + reference guide */ ++ +
CodeMirror is a code-editor component that can be embedded in + Web pages. The code library provides only the editor + component, no accompanying buttons, auto-completion, or other IDE + functionality. It does provide a rich API on top of which such + functionality can be straightforwardly implemented. See + the add-ons included in the distribution, + and + the CodeMirror + UI project, for reusable implementations of extra features.
+ +CodeMirror works with language-specific modes. Modes are
+ JavaScript programs that help color (and optionally indent) text
+ written in a given language. The distribution comes with a few
+ modes (see the mode/
directory), and it isn't hard
+ to write new ones for other languages.
The easiest way to use CodeMirror is to simply load the script
+ and style sheet found under lib/
in the distribution,
+ plus a mode script from one of the mode/
directories
+ and a theme stylesheet from theme/
. (See
+ also the compression helper.) For
+ example:
<script src="lib/codemirror.js"></script> +<link rel="stylesheet" href="../lib/codemirror.css"> +<script src="mode/javascript/javascript.js"></script>+ +
Having done this, an editor instance can be created like + this:
+ +var myCodeMirror = CodeMirror(document.body);+ +
The editor will be appended to the document body, will start
+ empty, and will use the mode that we loaded. To have more control
+ over the new editor, a configuration object can be passed
+ to CodeMirror
as a second argument:
var myCodeMirror = CodeMirror(document.body, { + value: "function myScript(){return 100;}\n", + mode: "javascript" +});+ +
This will initialize the editor with a piece of code already in + it, and explicitly tell it to use the JavaScript mode (which is + useful when multiple modes are loaded). + See below for a full discussion of the + configuration options that CodeMirror accepts.
+ +In cases where you don't want to append the editor to an
+ element, and need more control over the way it is inserted, the
+ first argument to the CodeMirror
function can also
+ be a function that, when given a DOM element, inserts it into the
+ document somewhere. This could be used to, for example, replace a
+ textarea with a real editor:
var myCodeMirror = CodeMirror(function(elt) { + myTextArea.parentNode.replaceChild(elt, myTextArea); +}, {value: myTextArea.value});+ +
However, for this use case, which is a common way to use + CodeMirror, the library provides a much more powerful + shortcut:
+ +var myCodeMirror = CodeMirror.fromTextArea(myTextArea);+ +
This will, among other things, ensure that the textarea's value + is updated when the form (if it is part of a form) is submitted. + See the API reference for a full + description of this method.
+ +Both the CodeMirror
function and
+ its fromTextArea
method take as second (optional)
+ argument an object containing configuration options. Any option
+ not supplied like this will be taken
+ from CodeMirror.defaults
, an object containing the
+ default options. You can update this object to change the defaults
+ on your page.
Options are not checked in any way, so setting bogus option + values is bound to lead to odd errors.
+ +These are the supported options:
+ +value (string)
mode (string or object)
name
property that names the mode (for
+ example {name: "javascript", json: true}
). The demo
+ pages for each mode contain information about what configuration
+ parameters the mode supports. You can ask CodeMirror which modes
+ and MIME types are loaded with
+ the CodeMirror.listModes
+ and CodeMirror.listMIMEs
functions.theme (string)
.cm-s-[name]
+ styles is loaded (see
+ the theme
directory in the
+ distribution). The default is "default"
, for which
+ colors are included in codemirror.css
. It is
+ possible to use multiple theming classes at once—for
+ example "foo bar"
will assign both
+ the cm-s-foo
and the cm-s-bar
classes
+ to the editor.indentUnit (integer)
tabSize (integer)
indentWithTabs (boolean)
tabSize
+ spaces should be replaced by N tabs. Default is false.electricChars (boolean)
keyMap (string)
"default"
, which is the only keymap defined
+ in codemirror.js
itself. Extra keymaps are found in
+ the keymap
directory.extraKeys (object)
Ctrl-A
, Home
,
+ and Ctrl-Alt-Left
. See
+ the CodeMirror.keyNames
object for the names of all
+ the keys. The values in this object can either be functions,
+ which will be called with the CodeMirror instance when the key
+ is pressed, or strings, which should name commands defined
+ in CodeMirror.commands
(not documented properly,
+ but looking at the source and the definition of the built-in
+ keymaps, they should be rather obvious).lineWrapping (boolean)
false
(scroll).lineNumbers (boolean)
firstLineNumber (integer)
gutter (boolean)
fixedGutter (boolean)
readOnly (boolean)
onChange (function)
{from, to, newText,
+ next}
object containing information about the changes
+ that occurred as second argument. from
+ and to
are the positions (in the pre-change
+ coordinate system) where the change started and
+ ended. newText
is an array of strings representing
+ the text that replaced the changed range (split by line). If
+ multiple changes happened during a single operation, the object
+ will have a next
property pointing to another
+ change object (which may point to another, etc).onCursorActivity (function)
onGutterClick (function)
mousedown
+ event object as third argument.onFocus, onBlur (function)
onScroll (function)
onHighlightComplete (function)
onUpdate (function)
matchBrackets (boolean)
workTime, workDelay (number)
workTime
milliseconds, and then use
+ timeout to sleep for workDelay
milliseconds. The
+ defaults are 200 and 300, you can change these options to make
+ the highlighting more or less aggressive.pollInterval (number)
undoDepth (integer)
tabindex (integer)
document (DOM document)
document
+ object.onKeyEvent (function)
keydown
, keyup
,
+ and keypress
event that CodeMirror captures. It
+ will be passed two arguments, the editor instance and the key
+ event. This key event is pretty much the raw key event, except
+ that a stop()
method is always added to it. You
+ could feed it to, for example, jQuery.Event
to
+ further normalize it.keydown
does not stop
+ the keypress
from firing, whereas on others it
+ does. If you respond to an event, you should probably inspect
+ its type
property and only do something when it
+ is keydown
(or keypress
for actions
+ that need character data).Up to a certain extent, CodeMirror's look can be changed by
+ modifying style sheet files. The style sheets supplied by modes
+ simply provide the colors for that mode, and can be adapted in a
+ very straightforward way. To style the editor itself, it is
+ possible to alter or override the styles defined
+ in codemirror.css
.
Some care must be taken there, since a lot of the rules in this + file are necessary to have CodeMirror function properly. Adjusting + colors should be safe, of course, and with some care a lot of + other things can be changed as well. The CSS classes defined in + this file serve the following roles:
+ +CodeMirror
CodeMirror-scroll
overflow:
+ auto
+ fixed height). By default, it does. Giving
+ this height: auto; overflow: visible;
will cause
+ the editor to resize to fit its content.CodeMirror-focused
CodeMirror-gutter
CodeMirror-gutter-text
for that. By default,
+ the gutter is 'fluid', meaning it will adjust its width to the
+ maximum line number or line marker width. You can also set a
+ fixed width if you want.CodeMirror-gutter-text
CodeMirror
class.CodeMirror-lines
CodeMirror-gutter
should have the same
+ padding.CodeMirror-cursor
CodeMirror-selected
span
elements
+ with this class.CodeMirror-matchingbracket
,
+ CodeMirror-nonmatchingbracket
The actual lines, as well as the cursor, are represented
+ by pre
elements. By default no text styling (such as
+ bold) that might change line height is applied. If you do want
+ such effects, you'll have to give CodeMirror pre
a
+ fixed height. Also, you must still take care that character width
+ is constant.
If your page's style sheets do funky things to
+ all div
or pre
elements (you probably
+ shouldn't do that), you'll have to define rules to cancel these
+ effects out again for elements under the CodeMirror
+ class.
Themes are also simply CSS files, which define colors for
+ various syntactic elements. See the files in
+ the theme
directory.
A lot of CodeMirror features are only available through its API. + This has the disadvantage that you need to do work to enable them, + and the advantage that CodeMirror will fit seamlessly into your + application.
+ +Whenever points in the document are represented, the API uses
+ objects with line
and ch
properties.
+ Both are zero-based. CodeMirror makes sure to 'clip' any positions
+ passed by client code so that they fit inside the document, so you
+ shouldn't worry too much about sanitizing your coordinates. If you
+ give ch
a value of null
, or don't
+ specify it, it will be replaced with the length of the specified
+ line.
getValue() → string
setValue(string)
getSelection() → string
replaceSelection(string)
focus()
setOption(option, value)
option
+ should the name of an option,
+ and value
should be a valid value for that
+ option.getOption(option) → value
cursorCoords(start) → object
{x, y, yBot}
object containing the
+ coordinates of the cursor relative to the top-left corner of the
+ page. yBot
is the coordinate of the bottom of the
+ cursor. start
is a boolean indicating whether you
+ want the start or the end of the selection.charCoords(pos) → object
cursorCoords
, but returns the position of
+ an arbitrary characters. pos
should be
+ a {line, ch}
object.coordsChar(object) → pos
{x, y}
object (in page coordinates),
+ returns the {line, ch}
position that corresponds to
+ it.undo()
redo()
historySize() → object
{undo, redo}
properties,
+ both of which hold integers, indicating the amount of stored
+ undo and redo operations.clearHistory()
indentLine(line, dir)
dir
is true) or
+ decreased (if false) by an indent
+ unit instead.getTokenAt(pos) → object
{line, ch}
object). The
+ returned object has the following properties:
+ start
end
string
className
state
markText(from, to, className) → object
from
and to
should
+ be {line, ch}
objects. The method will return an
+ object with two methods, clear()
, which removes the
+ mark, and find()
, which returns a {from,
+ to}
(both document positions), indicating the current
+ position of the marked range.setBookmark(pos) → object
find()
and clear()
. The first
+ returns the current position of the bookmark, if it is still in
+ the document, and the second explicitly removes the
+ bookmark.setMarker(line, text, className) → lineHandle
text
and className
are
+ optional. Setting text
to a Unicode character like
+ ● tends to give a nice effect. To put a picture in the gutter,
+ set text
to a space and className
to
+ something that sets a background image. If you
+ specify text
, the given text (which may contain
+ HTML) will, by default, replace the line number for that line.
+ If this is not what you want, you can include the
+ string %N%
in the text, which will be replaced by
+ the line number.clearMarker(line)
setMarker
. line
can be either a
+ number or a handle returned by setMarker
(since a
+ number may now refer to a different line if something was added
+ or deleted).setLineClass(line, className) → lineHandle
line
+ can be a number or a line handle (as returned
+ by setMarker
or this function).
+ Pass null
to clear the class for a line.hideLine(line) → lineHandle
showLine(line) → lineHandle
hideLine
—re-shows a previously
+ hidden line, by number or by handle.onDeleteLine(line, func)
lineInfo(line) → object
setMarker
. The returned object has the
+ structure {line, handle, text, markerText, markerClass}
.getLineHandle(num) → lineHandle
addWidget(pos, node, scrollIntoView)
node
, which should be an absolutely
+ positioned DOM node, into the editor, positioned right below the
+ given {line, ch}
position.
+ When scrollIntoView
is true, the editor will ensure
+ that the entire node is visible (if possible). To remove the
+ widget again, simply use DOM methods (move it somewhere else, or
+ call removeChild
on its parent).matchBrackets()
lineCount() → number
getCursor(start) → object
start
is a boolean indicating whether the start
+ or the end of the selection must be retrieved. If it is not
+ given, the current cursor pos, i.e. the side of the selection
+ that would move if you pressed an arrow key, is chosen.
+ A {line, ch}
object will be returned.somethingSelected() → boolean
setCursor(pos)
{line, ch}
object, or the line and the
+ character as two separate parameters.setSelection(start, end)
start
+ and end
should be {line, ch}
objects.getLine(n) → string
n
.setLine(n, text)
n
.removeLine(n)
getRange(from, to) → string
+ {line, ch}
objects.replaceRange(string, from, to)
from
+ and to
with the given string. from
+ and to
must be {line, ch}
+ objects. to
can be left off to simply insert the
+ string at position from
.posFromIndex(index) → object
{line, ch}
object for a
+ zero-based index
who's value is relative to the start of the
+ editor's text. If the index
is out of range of the text then
+ the returned object is clipped to start or end of the text
+ respectively.indexFromPos(object) → number
posFromIndex
.The following are more low-level methods:
+ +operation(func) → result
refresh()
getInputField() → textarea
getWrapperElement() → node
getScrollerElement() → node
height
and width
styles of this
+ element to resize an editor. (You might have to call
+ the refresh
method
+ afterwards.)getGutterElement() → node
getStateAfter(line) → state
Finally, the CodeMirror
object
+ itself has a method fromTextArea
. This takes a
+ textarea DOM node as first argument and an optional configuration
+ object as second. It will replace the textarea with a CodeMirror
+ instance, and wire up the form of that textarea (if any) to make
+ sure the editor contents are put into the textarea when the form
+ is submitted. A CodeMirror instance created this way has two
+ additional methods:
save()
toTextArea()
getTextArea() → textarea
If you want to define extra methods in terms
+ of the CodeMirror API, it is possible to
+ use CodeMirror.defineExtension(name, value)
. This
+ will cause the given value (usually a method) to be added to all
+ CodeMirror instances created from then on.
The lib/util
directory in the distribution
+ contains a number of reusable components that implement extra
+ editor functionality. In brief, they are:
dialog.js
openDialog
method to CodeMirror instances,
+ which can be called with an HTML fragment that provides the
+ prompt (should include an input
tag), and a
+ callback function that is called when text has been entered.
+ Depends on lib/util/dialog.css
.searchcursor.js
getSearchCursor(query, start, caseFold) →
+ cursor
method to CodeMirror instances, which can be used
+ to implement search/replace functionality. query
+ can be a regular expression or a string (only strings will match
+ across lines—if they contain newlines). start
+ provides the starting position of the search. It can be
+ a {line, ch}
object, or can be left off to default
+ to the start of the document. caseFold
is only
+ relevant when matching a string. It will cause the search to be
+ case-insensitive. A search cursor has the following methods:
+ findNext(), findPrevious() → boolean
match
method, in case you
+ want to extract matched groups.from(), to() → object
findNext
or findPrevious
did
+ not return false. They will return {line, ch}
+ objects pointing at the start and end of the match.replace(text)
search.js
searchcursor.js
, and will make use
+ of openDialog
when
+ available to make prompting for search queries less ugly.foldcode.js
CodeMirror.newFoldFunction
with a range-finder
+ helper function to create a function that will, when applied to
+ a CodeMirror instance and a line number, attempt to fold or
+ unfold the block starting at the given line. A range-finder is a
+ language-specific functoin that also takes an instance and a
+ line number, and returns an end line for the block, or null if
+ no block is started on that line. This file
+ provides CodeMirror.braceRangeFinder
, which finds
+ blocks in brace languages (JavaScript, C, Java, etc).runmode.js
simple-hint.js
CodeMirror.simpleHint
, which takes a
+ CodeMirror instance and a hinting function, and pops up a widget
+ that allows the user to select a completion. Hinting functions
+ are function that take an editor instance, and return
+ a {list, from, to}
object, where list
+ is an array of strings (the completions), and from
+ and to
give the start and end of the token that is
+ being completed. Depends
+ on lib/util/simple-hint.css
.javascript-hint.js
CodeMirror.javaScriptHint
, which is a
+ simple hinting function for the JavaScript mode.Modes typically consist of a single JavaScript file. This file + defines, in the simplest case, a lexer (tokenizer) for your + language—a function that takes a character stream as input, + advances it past a token, and returns a style for that token. More + advanced modes can also handle indentation for the language.
+ +The mode script should
+ call CodeMirror.defineMode
to register itself with
+ CodeMirror. This function takes two arguments. The first should be
+ the name of the mode, for which you should use a lowercase string,
+ preferably one that is also the name of the files that define the
+ mode (i.e. "xml"
is defined xml.js
). The
+ second argument should be a function that, given a CodeMirror
+ configuration object (the thing passed to
+ the CodeMirror
function) and an optional mode
+ configuration object (as in
+ the mode
option), returns
+ a mode object.
Typically, you should use this second argument
+ to defineMode
as your module scope function (modes
+ should not leak anything into the global scope!), i.e. write your
+ whole mode inside this function.
The main responsibility of a mode script is parsing + the content of the editor. Depending on the language and the + amount of functionality desired, this can be done in really easy + or extremely complicated ways. Some parsers can be stateless, + meaning that they look at one element (token) of the code + at a time, with no memory of what came before. Most, however, will + need to remember something. This is done by using a state + object, which is an object that is always passed when + reading a token, and which can be mutated by the tokenizer.
+ +Modes that use a state must define
+ a startState
method on their mode object. This is a
+ function of no arguments that produces a state object to be used
+ at the start of a document.
The most important part of a mode object is
+ its token(stream, state)
method. All modes must
+ define this method. It should read one token from the stream it is
+ given as an argument, optionally update its state, and return a
+ style string, or null
for tokens that do not have to
+ be styled. For your styles, you can either use the 'standard' ones
+ defined in the themes (without the cm-
prefix), or
+ define your own (as the diff
+ mode does) and have people include a custom CSS file for your
+ mode.
+ +
The stream object encapsulates a line of code + (tokens may never span lines) and our current position in that + line. It has the following API:
+ +eol() → boolean
sol() → boolean
peek() → character
undefined
at the end of the
+ line.next() → character
undefined
when no more characters are
+ available.eat(match) → character
match
can be a character, a regular expression,
+ or a function that takes a character and returns a boolean. If
+ the next character in the stream 'matches' the given argument,
+ it is consumed and returned. Otherwise, undefined
+ is returned.eatWhile(match) → boolean
eat
with the given argument,
+ until it fails. Returns true if any characters were eaten.eatSpace() → boolean
eatWhile
when matching
+ white-space.skipToEnd()
skipTo(ch) → boolean
match(pattern, consume, caseFold) → boolean
eat
—if consume
is true
+ or not given—or a look-ahead that doesn't update the stream
+ position—if it is false. pattern
can be either a
+ string or a regular expression starting with ^
.
+ When it is a string, caseFold
can be set to true to
+ make the match case-insensitive. When successfully matching a
+ regular expression, the returned value will be the array
+ returned by match
, in case you need to extract
+ matched groups.backUp(n)
n
characters. Backing it up
+ further than the start of the current token will cause things to
+ break, so be careful.column() → integer
indentation() → integer
current() → string
By default, blank lines are simply skipped when
+ tokenizing a document. For languages that have significant blank
+ lines, you can define a blankLine(state)
method on
+ your mode that will get called whenever a blank line is passed
+ over, so that it can update the parser state.
Because state object are mutated, and CodeMirror
+ needs to keep valid versions of a state around so that it can
+ restart a parse at any line, copies must be made of state objects.
+ The default algorithm used is that a new state object is created,
+ which gets all the properties of the old object. Any properties
+ which hold arrays get a copy of these arrays (since arrays tend to
+ be used as mutable stacks). When this is not correct, for example
+ because a mode mutates non-array properties of its state object, a
+ mode object should define a copyState
method,
+ which is given a state and should return a safe copy of that
+ state.
By default, CodeMirror will stop re-parsing
+ a document as soon as it encounters a few lines that were
+ highlighted the same in the old parse as in the new one. It is
+ possible to provide an explicit way to test whether a state is
+ equivalent to another one, which CodeMirror will use (instead of
+ the unchanged-lines heuristic) to decide when to stop
+ highlighting. You do this by providing
+ a compareStates
method on your mode object, which
+ takes two state arguments and returns a boolean indicating whether
+ they are equivalent. See the XML mode, which uses this to provide
+ reliable highlighting of bad closing tags, as an example.
If you want your mode to provide smart indentation
+ (though the indentLine
+ method and the indentAuto
+ and newlineAndIndent
commands, which keys can be
+ bound to), you must define
+ an indent(state, textAfter)
method on your mode
+ object.
The indentation method should inspect the given state object,
+ and optionally the textAfter
string, which contains
+ the text on the line that is being indented, and return an
+ integer, the amount of spaces to indent. It should usually take
+ the indentUnit
+ option into account.
Finally, a mode may define
+ an electricChars
property, which should hold a string
+ containing all the characters that should trigger the behaviour
+ described for
+ the electricChars
+ option.
So, to summarize, a mode must provide
+ a token
method, and it may
+ provide startState
, copyState
,
+ compareStates
, and indent
methods. For
+ an example of a trivial mode, see
+ the diff mode, for a more involved
+ example, see the C-like
+ mode.
Sometimes, it is useful for modes to nest—to have one
+ mode delegate work to another mode. An example of this kind of
+ mode is the mixed-mode HTML
+ mode. To implement such nesting, it is usually necessary to
+ create mode objects and copy states yourself. To create a mode
+ object, there are CodeMirror.getMode(options,
+ parserConfig)
, where the first argument is a configuration
+ object as passed to the mode constructor function, and the second
+ argument is a mode specification as in
+ the mode
option. To copy a
+ state object, call CodeMirror.copyState(mode, state)
,
+ where mode
is the mode that created the given
+ state.
To make indentation work properly in a nested parser, it is
+ advisable to give the startState
method of modes that
+ are intended to be nested an optional argument that provides the
+ base indentation for the block of code. The JavaScript and CSS
+ parser do this, for example, to allow JavaScript and CSS code
+ inside the mixed-mode HTML mode to be properly indented.
Finally, it is possible to associate your mode, or a certain
+ configuration of your mode, with
+ a MIME type. For
+ example, the JavaScript mode associates itself
+ with text/javascript
, and its JSON variant
+ with application/json
. To do this,
+ call CodeMirror.defineMIME(mime, modeSpec)
,
+ where modeSpec
can be a string or object specifying a
+ mode, as in the mode
+ option.