jyapayne/ace
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update Events documentation

Browse source
This commit is contained in:
Garen Torikian 2012-08-30 11:30:59 -07:00
commit 039e04c160
28 changed files with 891 additions and 404 deletions
Download patch file Download diff file Expand all files Collapse all files

9
lib/ace/anchor.js
View file

@ -98,9 +98,14 @@ var Anchor = exports.Anchor = function(doc, row, column) {
/**
* Anchor@change(e)
* - e (Event): Contains data about the event
* - e (Object): An object containing information about the anchor position. It has two properties:
* `old`: An object describing the old Anchor position
* `value`: An object describing the new Anchor position
Both of these objects have a `row` and `column` property corresponding to the position.
*
* Fires whenever the anchor position changes. Events that can trigger this function include `'insertText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`.
* Fires whenever the anchor position changes.
*
* Events that can trigger this function include [[Anchor.setPosition `setPosition()`]].
*
**/

7
lib/ace/background_tokenizer.js
View file

@ -142,6 +142,13 @@ var BackgroundTokenizer = function(tokenizer, editor) {
* Emits the `'update'` event. `firstRow` and `lastRow` are used to define the boundaries of the region to be updated.
*
**/
/**
* BackgroundTokenizer@update(e)
* - e (Object): An object containing two properties, `first` and `last`, which indicate the rows of the region being updated.
*
* Fires whenever the background tokeniziers between a range of rows are going to be updated.
*
**/
this.fireUpdateEvent = function(firstRow, lastRow) {
var data = {
first: firstRow,

24
lib/ace/document.js
View file

@ -58,6 +58,7 @@ var Anchor = require("./anchor").Anchor;
* Creates a new `Document`. If `text` is included, the `Document` contains those strings; otherwise, it's empty.
*
**/
var Document = function(text) {
this.$lines = [];
@ -322,6 +323,29 @@ var Document = function(text) {
*
*
**/
/**
* Document@change(e)
* - e (Object): Contains at least one property called `"action"`. `"action"` indicates the action that triggered the change. Each action also has a set of additional properties.
*
* Fires whenever the document changes.
*
* Several methods trigger different `"change"` events. Below is a list of each action type, followed by each property that's also available:
*
* * `"insertLines"` (emitted by [[Document.insertLines]])
* * `range`: the [[Range]] of the change within the document
* * `lines`: the lines in the document that are changing
* * `"insertText"` (emitted by [[Document.insertNewLine]])
* * `range`: the [[Range]] of the change within the document
* * `text`: the text that's being added
* * `"removeLines"` (emitted by [[Document.insertLines]])
* * `range`: the [[Range]] of the change within the document
* * `lines`: the lines in the document that were removed
* * `nl`: the new line character (as defined by [[Document.getNewLineCharacter]])
* * `"removeText"` (emitted by [[Document.removeInLine]] and [[Document.removeNewLine]])
* * `range`: the [[Range]] of the change within the document
* * `text`: the text that's being removed
*
**/
this.insertLines = function(row, lines) {
if (lines.length == 0)
return {row: row, column: 0};

76
lib/ace/edit_session.js
View file

@ -63,29 +63,87 @@ var SearchHighlight = require("./search_highlight").SearchHighlight;
// events
/**
* EditSession@change(e)
* - e (Object): An object containing a `delta` of information about the change.
*
* Emitted when the document changes.
**/
/**
* EditSession@tokenizerUpdate(e)
* EditSession@changeTabSize()
*
* Emitted when a background tokenizer asynchronousely processes new rows.
* Emitted when the tab size changes, via [[EditSession.setTabSize]].
**/
/**
* EditSession@changeOverwrite()
*
* Emitted when the ability to overwrite text changes, via [[EditSession.setOverwrite]].
**/
/**
* EditSession@changeBreakpoint()
*
* Emitted when the gutter changes, either by setting or removing breakpoints, or when the gutter decorations change.
**/
/**
* EditSession@changeFrontMarker()
*
* Emitted when a front marker changes.
**/
/**
* EditSession@changeBackMarker()
*
* Emitted when a back marker changes.
**/
/**
* EditSession@changeAnnotation()
*
* Emitted when an annotation changes, like through [[EditSession.setAnnotations]].
**/
/**
* EditSession@tokenizerUpdate(e)
* - e (Object): An object containing one property, `"data"`, that contains information about the changing rows
*
* Emitted when a background tokenizer asynchronously processes new rows.
*
**/
/** hide
* EditSession@loadMode(e)
*
*
*
**/
/**
* EditSession@changeMode()
*
* Emitted when the current mode changes.
*
**/
/**
* EditSession@changeWrapMode()
*
* Emitted when the wrap mode changes.
*
**/
/**
* EditSession@changeWrapLimit()
*
* Emitted when the wrapping limit changes.
*
**/
/**
* EditSession@changeFold(e)
*
* Emitted when a code fold added or removed.
* Emitted when a code fold is added or removed.
*
**/
/**
* EditSession@changeScrollTop()
*
* EditSession@changeScrollTop(scrollTop)
* - scrollTop (Number): The new scroll top value
*
* Emitted when the scroll top changes.
**/
/**
* EditSession@changeScrollLeft()
*
* EditSession@changeScrollLeft(scrollLeft)
* - scrollLeft (Number): The new scroll left value
*
* Emitted when the scroll left changes.
**/
@ -482,7 +540,9 @@ var EditSession = function(text, mode) {
* EditSession.setOverwrite(overwrite)
* - overwrite (Boolean): Defines wheter or not to set overwrites
*
* Pass in `true` to enable overwrites in your session, or `false` to disable. If overwrites is enabled, any text you enter will type over any text after it. If the value of `overwrite` changes, this function also emites the `changeOverwrite` event.
* Pass in `true` to enable overwrites in your session, or `false` to disable.
*
* If overwrites is enabled, any text you enter will type over any text after it. If the value of `overwrite` changes, this function also emites the `changeOverwrite` event.
*
**/
this.setOverwrite = function(overwrite) {

88
lib/ace/editor.js
View file

@ -127,6 +127,12 @@ var Editor = function(renderer, session) {
*
* Sets a new editsession to use. This method also emits the `'changeSession'` event.
**/
/**
* Editor@changeSession(e)
* - e (Object): An object with two properties, `oldSession` and `session`, that represent the old and new [[EditSession]]s.
*
* Emitted whenever the [[EditSession]] changes.
**/
this.setSession = function(session) {
if (this.session == session)
return;
@ -462,9 +468,10 @@ var Editor = function(renderer, session) {
};
/**
* Editor@cursorChange()
* Editor@changeSelection()
*
* Emitted when the selection changes.
*
* Emitted when the cursor changes.
**/
this.onCursorChange = function() {
this.$cursorChange();
@ -508,12 +515,6 @@ var Editor = function(renderer, session) {
};
/**
* Editor@selectionChange(e)
* - e (Object): Contains a single property, `data`, which has the delta of changes
*
* Emitted when a selection has changed.
**/
this.onSelectionChange = function(e) {
var session = this.session;
@ -568,74 +569,39 @@ var Editor = function(renderer, session) {
return re;
};
/**
* Editor@changeFrontMarker()
*
* Emitted when a front marker changes.
**/
this.onChangeFrontMarker = function() {
this.renderer.updateFrontMarkers();
};
/**
* Editor@changeBackMarker()
*
* Emitted when a back marker changes.
**/
this.onChangeBackMarker = function() {
this.renderer.updateBackMarkers();
};
/**
* Editor@changeBreakpoint()
*
* Emitted when a breakpoint changes.
**/
this.onChangeBreakpoint = function() {
this.renderer.updateBreakpoints();
};
/**
* Editor@changeAnnotation()
*
* Emitted when an annotation changes.
**/
this.onChangeAnnotation = function() {
this.renderer.setAnnotations(this.session.getAnnotations());
};
/**
* Editor@changeMode()
*
* Emitted when the mode changes.
**/
this.onChangeMode = function() {
this.renderer.updateText();
};
/**
* Editor@changeWrapLimit()
*
* Emitted when the wrap limit changes.
**/
this.onChangeWrapLimit = function() {
this.renderer.updateFull();
};
/**
* Editor@changeWrapMode()
*
* Emitted when the wrap mode changes.
**/
this.onChangeWrapMode = function() {
this.renderer.onResize(true);
};
/**
* Editor@changeFold()
*
* Emitted when the code folds change.
**/
this.onChangeFold = function() {
// Update the active line marker as due to folding changes the current
// line range on the screen might have changed.
@ -649,6 +615,12 @@ var Editor = function(renderer, session) {
*
* Returns the string of text currently highlighted.
**/
/**
* Editor@copy(text)
* - text (String): The copied text
*
* Emitted when text is copied.
**/
this.getCopyText = function() {
var text = "";
if (!this.selection.isEmpty())
@ -677,9 +649,16 @@ var Editor = function(renderer, session) {
};
/**
* Editor.onPaste()
*
* called whenever a text "paste" happens.
* Editor.onPaste(text)
* - text (String): The pasted text
*
* Called whenever a text "paste" happens.
**/
/**
* Editor@paste(text)
* - text (String): The pasted text
*
* Emitted when text is pasted.
**/
this.onPaste = function(text) {
// todo this should change when paste becomes a command
@ -872,6 +851,13 @@ var Editor = function(renderer, session) {
* Indicates how selections should occur. By default, selections are set to "line". This function also emits the `'changeSelectionStyle'` event.
*
**/
/**
* Editor@changeSelectionStyle(data)
* - data (Object): Contains one property, `data`, which indicates the new selection style
*
* Emitted when the selection style changes, via [[Editor.setSelectionStyle]].
*
**/
this.setSelectionStyle = function(style) {
if (this.$selectionStyle == style) return;

3
lib/ace/scrollbar.js
View file

@ -82,7 +82,8 @@ var ScrollBar = function(parent) {
oop.implement(this, EventEmitter);
/**
* ScrollBar@onScroll()
* ScrollBar@scroll(e)
* - e (Object): Contains one property, `"data"`, which indicates the current scroll top position
*
* Emitted when the scroll bar, well, scrolls.
*

12
lib/ace/selection.js
View file

@ -59,6 +59,18 @@ var Range = require("./range").Range;
* Creates a new `Selection` object.
*
**/
/**
* Selection@changeCursor()
*
* Emitted when the cursor position changes.
*
**/
/**
* Selection@changeSelection()
*
* Emitted when the cursor selection changes.
*
**/
var Selection = function(session) {
this.session = session;
this.doc = session.getDocument();

72
lib/ace/virtual_renderer.js
View file

@ -203,7 +203,7 @@ var VirtualRenderer = function(container, theme) {
oop.implement(this, EventEmitter);
/**
* VirtualRenderer.setSession(session) -> Void
* VirtualRenderer.setSession(session)
*
* Associates an [[EditSession `EditSession`]].
**/
@ -222,7 +222,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.updateLines(firstRow, lastRow) -> Void
* VirtualRenderer.updateLines(firstRow, lastRow)
* - firstRow (Number): The first row to update
* - lastRow (Number): The last row to update
*
@ -255,7 +255,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.updateText() -> Void
* VirtualRenderer.updateText()
*
* Triggers a full update of the text, for all the rows.
**/
@ -264,7 +264,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.updateFull() -> Void
* VirtualRenderer.updateFull()
*
* Triggers a full update of all the layers, for all the rows.
**/
@ -278,7 +278,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.updateFontSize() -> Void
* VirtualRenderer.updateFontSize()
*
* Updates the font size.
**/
@ -287,7 +287,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.onResize(force) -> Void
* VirtualRenderer.onResize(force)
* - force (Boolean): If `true`, recomputes the size, even if the height and width haven't changed
*
* [Triggers a resize of the editor.]{: #VirtualRenderer.onResize}
@ -342,7 +342,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.adjustWrapLimit() -> Void
* VirtualRenderer.adjustWrapLimit()
*
* Adjusts the wrap limit, which is the number of characters that can fit within the width of the edit area on screen.
**/
@ -353,7 +353,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.setAnimatedScroll(shouldAnimate) -> Void
* VirtualRenderer.setAnimatedScroll(shouldAnimate)
* - shouldAnimate (Boolean): Set to `true` to show animated scrolls
*
* Identifies whether you want to have an animated scroll or not.
@ -373,7 +373,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.setShowInvisibles(showInvisibles) -> Void
* VirtualRenderer.setShowInvisibles(showInvisibles)
* - showInvisibles (Boolean): Set to `true` to show invisibles
*
* Identifies whether you want to show invisible characters or not.
@ -458,7 +458,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.setShowGutter(show) -> Void
* VirtualRenderer.setShowGutter(show)
* - show (Boolean): Set to `true` to show the gutter
*
* Identifies whether you want to show the gutter or not.
@ -626,7 +626,7 @@ var VirtualRenderer = function(container, theme) {
this.$padding = null;
/**
* VirtualRenderer.setPadding(padding) -> Void
* VirtualRenderer.setPadding(padding)
* - padding (Number): A new padding value (in pixels)
*
* Sets the padding for all the layers.
@ -652,7 +652,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.setHScrollBarAlwaysVisible(alwaysVisible) -> Void
* VirtualRenderer.setHScrollBarAlwaysVisible(alwaysVisible)
* - alwaysVisible (Boolean): Set to `true` to make the horizontal scroll bar visible
*
* Identifies whether you want to show the horizontal scrollbar or not.
@ -867,7 +867,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.updateFrontMarkers() -> Void
* VirtualRenderer.updateFrontMarkers()
*
* Schedules an update to all the front markers in the document.
**/
@ -877,7 +877,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.updateBackMarkers() -> Void
* VirtualRenderer.updateBackMarkers()
*
* Schedules an update to all the back markers in the document.
**/
@ -886,26 +886,26 @@ var VirtualRenderer = function(container, theme) {
this.$loop.schedule(this.CHANGE_MARKER_BACK);
};
/**
* VirtualRenderer.addGutterDecoration(row, className) -> Void
/** deprecated
* VirtualRenderer.addGutterDecoration(row, className)
*
* Deprecated (moved to EditSession)
* Deprecated; (moved to [[EditSession]])
**/
this.addGutterDecoration = function(row, className){
this.$gutterLayer.addGutterDecoration(row, className);
};
/**
/** deprecated
* VirtualRenderer.removeGutterDecoration(row, className)-> Void
*
* Deprecated (moved to EditSession)
* Deprecated; (moved to [[EditSession]])
**/
this.removeGutterDecoration = function(row, className){
this.$gutterLayer.removeGutterDecoration(row, className);
};
/**
* VirtualRenderer.updateBreakpoints() -> Void
* VirtualRenderer.updateBreakpoints()
*
* Redraw breakpoints.
**/
@ -914,7 +914,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.setAnnotations(annotations) -> Void
* VirtualRenderer.setAnnotations(annotations)
* - annotations (Array): An array containing annotations
*
* Sets annotations for the gutter.
@ -925,7 +925,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.updateCursor() -> Void
* VirtualRenderer.updateCursor()
*
* Updates the cursor icon.
**/
@ -934,7 +934,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.hideCursor() -> Void
* VirtualRenderer.hideCursor()
*
* Hides the cursor icon.
**/
@ -943,7 +943,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.showCursor() -> Void
* VirtualRenderer.showCursor()
*
* Shows the cursor icon.
**/
@ -958,7 +958,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.scrollCursorIntoView(cursor, offset) -> Void
* VirtualRenderer.scrollCursorIntoView(cursor, offset)
*
* Scrolls the cursor into the first visibile area of the editor
**/
@ -1030,7 +1030,7 @@ var VirtualRenderer = function(container, theme) {
};
/** related to: EditSession.setScrollTop
* VirtualRenderer.scrollToRow(row) -> Void
* VirtualRenderer.scrollToRow(row)
* - row (Number): A row id
*
* Gracefully scrolls the top of the editor to the row indicated.
@ -1066,7 +1066,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.scrollToLine(line, center, animate, callback) -> Void
* VirtualRenderer.scrollToLine(line, center, animate, callback)
* - line (Number): A line number
* - center (Boolean): If `true`, centers the editor the to indicated line
* - animate (Boolean): If `true` animates scrolling
@ -1148,7 +1148,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.scrollBy(deltaX, deltaY) -> Void
* VirtualRenderer.scrollBy(deltaX, deltaY)
* - deltaX (Number): The x value to scroll by
* - deltaY (Number): The y value to scroll by
*
@ -1220,7 +1220,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.visualizeFocus() -> Void
* VirtualRenderer.visualizeFocus()
*
* Focuses the current container.
**/
@ -1229,7 +1229,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.visualizeBlur() -> Void
* VirtualRenderer.visualizeBlur()
*
* Blurs the current container.
**/
@ -1238,7 +1238,7 @@ var VirtualRenderer = function(container, theme) {
};
/** internal, hide
* VirtualRenderer.showComposition(position) -> Void
* VirtualRenderer.showComposition(position)
* - position (Number):
*
**/
@ -1256,7 +1256,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.setCompositionText(text) -> Void
* VirtualRenderer.setCompositionText(text)
* - text (String): A string of text to use
*
* Sets the inner text of the current composition to `text`.
@ -1266,7 +1266,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.hideComposition() -> Void
* VirtualRenderer.hideComposition()
*
* Hides the current composition.
**/
@ -1288,7 +1288,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.setTheme(theme) -> Void
* VirtualRenderer.setTheme(theme)
* - theme (String): The path to a theme
*
* [Sets a new theme for the editor. `theme` should exist, and be a directory path, like `ace/theme/textmate`.]{: #VirtualRenderer.setTheme}
@ -1361,7 +1361,7 @@ var VirtualRenderer = function(container, theme) {
// a certain mode that editor is in.
/**
* VirtualRenderer.setStyle(style) -> Void
* VirtualRenderer.setStyle(style)
* - style (String): A class name
*
* [Adds a new class, `style`, to the editor.]{: #VirtualRenderer.setStyle}
@ -1371,7 +1371,7 @@ var VirtualRenderer = function(container, theme) {
};
/**
* VirtualRenderer.unsetStyle(style) -> Void
* VirtualRenderer.unsetStyle(style)
* - style (String): A class name
*
* [Removes the class `style` from the editor.]{: #VirtualRenderer.unsetStyle}