From aebdfb4cf607e15b86fde8fa4528c2b7083accf4 Mon Sep 17 00:00:00 2001 From: Ben Ogle Date: Tue, 9 Sep 2014 10:39:41 -0700 Subject: [PATCH] Event docs --- src/editor.coffee | 214 +++++++++++++++++++--------------------------- 1 file changed, 88 insertions(+), 126 deletions(-) diff --git a/src/editor.coffee b/src/editor.coffee index 055b6d94b..cb95f3e14 100644 --- a/src/editor.coffee +++ b/src/editor.coffee @@ -52,126 +52,6 @@ TextMateScopeSelector = require('first-mate').ScopeSelector # # **When in doubt, just default to buffer coordinates**, then experiment with # soft wraps and folds to ensure your code interacts with them correctly. -# -# ## Events -# -# ### path-changed -# -# Essential: Emit when the buffer's path, and therefore title, has changed. -# -# ### title-changed -# -# Essential: Emit when the buffer's path, and therefore title, has changed. -# -# ### modified-status-changed -# -# Extended: Emit when the result of {::isModified} changes. -# -# ### soft-wrap-changed -# -# Extended: Emit when soft wrap was enabled or disabled. -# -# * `softWrapped` {Boolean} indicating whether soft wrap is enabled or disabled. -# -# ### grammar-changed -# -# Extended: Emit when the grammar that interprets and colorizes the text has -# been changed. -# -# -# -# ### contents-modified -# -# Essential: Emit when the buffer's contents change. It is emit asynchronously -# 300ms after the last buffer change. This is a good place to handle changes to -# the buffer without compromising typing performance. -# -# ### contents-conflicted -# -# Extended: Emitted when the buffer's underlying file changes on disk at a -# moment when the result of {::isModified} is true. -# -# ### will-insert-text -# -# Extended: Emit before the text has been inserted. -# -# * `event` event {Object} -# * `text` {String} text to be inserted -# * `cancel` {Function} Call to prevent the text from being inserted -# -# ### did-insert-text -# -# Extended: Emit after the text has been inserted. -# -# * `event` event {Object} -# * `text` {String} text to be inserted -# -# -# -# ### cursor-moved -# -# Essential: Emit when a cursor has been moved. If there are multiple cursors, -# it will be emit for each cursor. -# -# * `event` {Object} -# * `oldBufferPosition` {Point} -# * `oldScreenPosition` {Point} -# * `newBufferPosition` {Point} -# * `newScreenPosition` {Point} -# * `textChanged` {Boolean} -# -# ### cursor-added -# -# Extended: Emit when a cursor has been added. -# -# * `cursor` {Cursor} that was added -# -# ### cursor-removed -# -# Extended: Emit when a cursor has been removed. -# -# * `cursor` {Cursor} that was removed -# -# -# -# ### selection-screen-range-changed -# -# Essential: Emit when a selection's screen range changes. -# -# * `selection`: {Selection} object that has a changed range -# -# ### selection-added -# -# Extended: Emit when a selection's was added. -# -# * `selection`: {Selection} object that was added -# -# ### selection-removed -# -# Extended: Emit when a selection's was removed. -# -# * `selection`: {Selection} object that was removed -# -# -# -# ### decoration-added -# -# Extended: Emit when a {Decoration} is added to the editor. -# -# * `decoration` {Decoration} that was added -# -# ### decoration-removed -# -# Extended: Emit when a {Decoration} is removed from the editor. -# -# * `decoration` {Decoration} that was removed -# -# ### decoration-updated -# -# Extended: Emit when a {Decoration} is updated via the {Decoration::update} method. -# -# * `decoration` {Decoration} that was updated -# module.exports = class Editor extends Model Serializable.includeInto(this) @@ -292,63 +172,145 @@ class Editor extends Model @displayBuffer.destroy() @languageMode.destroy() + ### + Section: Events + ### + + # Essential: Calls your `callback` when the buffer's title has changed. + # + # * `callback` {Function} onDidChangeTitle: (callback) -> @emitter.on 'did-change-title', callback + # Essential: Calls your `callback` when the buffer's path, and therefore title, has changed. + # + # * `callback` {Function} onDidChangePath: (callback) -> @emitter.on 'did-change-path', callback - onDidChangeModified: (callback) -> - @getBuffer().onDidChangeModified(callback) - + # Extended: Calls your `callback` when soft wrap was enabled or disabled. + # + # * `callback` {Function} onDidChangeSoftWrapped: (callback) -> @displayBuffer.onDidChangeSoftWrapped(callback) + # Extended: Calls your `callback` when the grammar that interprets and colorizes the text has + # been changed. + # + # * `callback` {Function} onDidChangeGrammar: (callback) -> @emitter.on 'did-change-grammar', callback - onDidChangeCharacterWidths: (callback) -> - @displayBuffer.onDidChangeCharacterWidths(callback) - + # Essential: Calls your `callback` when the buffer's contents change. It is + # emit asynchronously 300ms after the last buffer change. This is a good place + # to handle changes to the buffer without compromising typing performance. + # + # * `callback` {Function} onDidStopChanging: (callback) -> @getBuffer().onDidStopChanging(callback) + # Extended: Calls your `callback` when the result of {::isModified} changes. + # + # * `callback` {Function} + onDidChangeModified: (callback) -> + @getBuffer().onDidChangeModified(callback) + + # Extended: Calls your `callback` when the buffer's underlying file changes on + # disk at a moment when the result of {::isModified} is true. + # + # * `callback` {Function} onDidConflict: (callback) -> @getBuffer().onDidConflict(callback) + # Extended: Calls your `callback` before text has been inserted. + # + # * `callback` {Function} + # * `event` event {Object} + # * `text` {String} text to be inserted + # * `cancel` {Function} Call to prevent the text from being inserted onWillInsertText: (callback) -> @emitter.on 'will-insert-text', callback + # Extended: Calls your `callback` adter text has been inserted. + # + # * `callback` {Function} + # * `event` event {Object} + # * `text` {String} text to be inserted onDidInsertText: (callback) -> @emitter.on 'did-insert-text', callback + # Extended: Calls your `callback` when a {Cursor} is added to the editor. + # + # * `callback` {Function} + # * `cursor` {Cursor} that was added onDidAddCursor: (callback) -> @emitter.on 'did-add-cursor', callback + # Extended: Calls your `callback` when a {Cursor} is removed to the editor. + # + # * `callback` {Function} + # * `cursor` {Cursor} that was removed onDidRemoveCursor: (callback) -> @emitter.on 'did-remove-cursor', callback + # Essential: Calls your `callback` when a {Cursor} is removed to the editor. + # + # * `callback` {Function} + # * `event` {Object} + # * `oldBufferPosition` {Point} + # * `oldScreenPosition` {Point} + # * `newBufferPosition` {Point} + # * `newScreenPosition` {Point} + # * `textChanged` {Boolean} onDidMoveCursor: (callback) -> @emitter.on 'did-move-cursor', callback + # Extended: Calls your `callback` when a {Selection} is added to the editor. + # + # * `callback` {Function} + # * `selection` {Selection} that was added onDidAddSelection: (callback) -> @emitter.on 'did-add-selection', callback + # Extended: Calls your `callback` when a {Selection} is removed from the editor. + # + # * `callback` {Function} + # * `selection` {Selection} that was removed onDidRemoveSelection: (callback) -> @emitter.on 'did-remove-selection', callback + # Essential: Calls your `callback` when a selection's screen range changes. + # + # * `callback` {Function} + # * `selection` {Selection} that moved onDidChangeSelectionScreenRange: (callback) -> @emitter.on 'did-change-selection-screen-range', callback + # Extended: Calls your `callback` with each {Decoration} added to the editor. + # Calls your `callback` immediately for any existing decorations. + # + # * `callback` {Function} + # * `decoration` {Decoration} observeDecorations: (callback) -> @displayBuffer.observeDecorations(callback) + # Extended: Calls your `callback` when a {Decoration} is added to the editor. + # + # * `callback` {Function} + # * `decoration` {Decoration} that was added onDidAddDecoration: (callback) -> @displayBuffer.onDidAddDecoration(callback) + # Extended: Calls your `callback` when a {Decoration} is removed from the editor. + # + # * `callback` {Function} + # * `decoration` {Decoration} that was removed onDidRemoveDecoration: (callback) -> @displayBuffer.onDidRemoveDecoration(callback) + onDidChangeCharacterWidths: (callback) -> + @displayBuffer.onDidChangeCharacterWidths(callback) + onDidChangeScreenLines: (callback) -> @emitter.on 'did-change-screen-lines', callback