From 8013ff77756df9aed025400c707bc154c074186c Mon Sep 17 00:00:00 2001 From: Ben Ogle Date: Wed, 9 Jul 2014 18:16:20 -0700 Subject: [PATCH] Update decoration API docs --- src/decoration.coffee | 54 ++++++++++++++++++++++++++++++++++-- src/editor.coffee | 64 +++++++++++++++++++++++++++---------------- 2 files changed, 93 insertions(+), 25 deletions(-) diff --git a/src/decoration.coffee b/src/decoration.coffee index 0ce013fd2..36a9de632 100644 --- a/src/decoration.coffee +++ b/src/decoration.coffee @@ -4,6 +4,39 @@ _ = require 'underscore-plus' idCounter = 0 nextId = -> idCounter++ +# Public: Represents a decoration that follows a {Marker}. A decoration is +# basically a visual representation of a marker. It allows you to add CSS +# classes to line numbers in the gutter, lines, and add selection-line regions +# around marked ranges of text. +# +# {Decoration} objects are not meant to be created directly, but created with +# {Editor::decorateMarker}. eg. +# +# ```coffee +# range = editor.getSelectedBufferRange() # any range you like +# marker = editor.markBufferRange(range) +# decoration = editor.decorateMarker(marker, {type: 'line', class: 'my-line-class'}) +# ``` +# +# Best practice for destorying the decoration is by destroying the {Marker}. +# +# ``` +# marker.destroy() +# ``` +# +# You should only use {Decoration::destroy} when you still need or do not own +# the marker. +# +# ### IDs +# Each {Decoration} has a unique ID available via `decoration.id`. +# +# ### Events +# A couple of events are emitted: +# +# * `destroyed`: When the {Decoration} is destroyed +# * `updated`: When the {Decoration} is updated via {Decoration::update}. +# Event object has properties `oldParams` and `newParams` +# module.exports = class Decoration Emitter.includeInto(this) @@ -20,12 +53,21 @@ class Decoration @flashQueue = null @isDestroyed = false + # Public: Destroy this marker. + # + # If you own the marker, you should use {Marker:destroy} which will destroy + # this decoration. destroy: -> return if @isDestroyed @isDestroyed = true @displayBuffer.removeDecoration(this) @emit 'destoryed' + # Public: Update the marker with new params. Allows you to change the decoration's class. + # + # ``` + # decoration.update({type: 'gutter', class: 'my-new-class'}) + # ``` update: (newParams) -> return if @isDestroyed oldParams = @params @@ -34,9 +76,17 @@ class Decoration @displayBuffer.decorationUpdated(this) @emit 'updated', {oldParams, newParams} - getParams: -> - @params + # Public: Returns the marker associated with this {Decoration} + getMarker: -> @marker + # Public: Returns the {Decoration}'s params. + getParams: -> @params + + # Public: Check if this decoration is of type `type` + # + # type - A {String} type like `'gutter'` + # + # Returns a {Boolean} isType: (type) -> Decoration.isType(@params, type) diff --git a/src/editor.coffee b/src/editor.coffee index 5e0eb0b2a..6645cdc2c 100644 --- a/src/editor.coffee +++ b/src/editor.coffee @@ -131,6 +131,10 @@ TextMateScopeSelector = require('first-mate').ScopeSelector # - {::markScreenRange} # - {::getMarker} # - {::findMarkers} +# +# ### Decorations +# - {::decorateMarker} +# - {::decorationsForScreenRowRange} module.exports = class Editor extends Model Serializable.includeInto(this) @@ -1080,8 +1084,10 @@ class Editor extends Model # startScreenRow - the {Number} beginning screen row # endScreenRow - the {Number} end screen row (inclusive) # - # Returns an {Object} of decorations in the form `{1: [{type: 'gutter', class: 'someclass'}], 2: ...}` - # where the keys are markerIds, and the values are an array of decoration objects attached to the marker. + # Returns an {Object} of decorations in the form + # `{1: [{id: 10, type: 'gutter', class: 'someclass'}], 2: ...}` + # where the keys are {Marker} IDs, and the values are an array of decoration + # params objects attached to the marker. # Returns an empty object when no decorations are found decorationsForScreenRowRange: (startScreenRow, endScreenRow) -> @displayBuffer.decorationsForScreenRowRange(startScreenRow, endScreenRow) @@ -1090,28 +1096,40 @@ class Editor extends Model # is invalidated, or is destroyed, the decoration will be updated to reflect # the marker's state. # + # There are three types of supported decorations: + # * `line`: Adds your CSS `class` to the line nodes within the range + # marked by the marker + # * `gutter`: Adds your CSS `class` to the line number nodes within the + # range marked by the marker + # * `highlight`: Adds a new highlight div to the editor surrounding the + # range marked by the marker. When the user selects text, the selection is + # visualized with a highlight decoration internally. The structure of this + # highlight will be: + # ```html + #
+ # + #
+ #
+ # ``` + # # marker - A {Marker} you want this decoration to follow. - # decoration - An {Object} representing the decoration eg. `{type: 'gutter', class: 'linter-error'}` - # The decoration can contain the following keys: - # * type: There are a few supported decoration types: - # * `gutter`: Applies the decoration to the line numbers spanned by the - # marker. - # * `line`: Applies the decoration to the lines spanned by the marker. - # * `highlight`: Applies the decoration to a "highlight" behind the - # marked range. When the user selects text, the selection is - # visualized with a highlight decoration internally. - # * class: This CSS class will be applied to the decorated line number, - # line, or highlight. - # * onlyHead: If `true`, the decoration will only be applied to the head - # of the marker. Only applicable to the `line` and `gutter` types. - # * onlyEmpty: If `true`, the decoration will only be applied if the - # associated marker is empty. Only applicable to the `line` and - # `gutter` types. - # * onlyNonEmpty: If `true`, the decoration will only be applied if the - # associated marker is non-empty. Only applicable to the `line` and - # gutter types. - decorateMarker: (marker, decoration) -> - @displayBuffer.decorateMarker(marker, decoration) + # decorationParams - An {Object} representing the decoration eg. `{type: 'gutter', class: 'linter-error'}` + # :type - There are a few supported decoration types: + # * `gutter`: Applies the decoration to the line numbers spanned by the marker. + # * `line`: Applies the decoration to the lines spanned by the marker. + # * `highlight`: Applies the decoration to a "highlight" behind the marked range. + # :class - This CSS class will be applied to the decorated line number, + # line, or highlight. + # :onlyHead - If `true`, the decoration will only be applied to the head + # of the marker. Only applicable to the `line` and `gutter` types. + # :onlyEmpty - If `true`, the decoration will only be applied if the + # associated marker is empty. Only applicable to the `line` and + # `gutter` types. + # :onlyNonEmpty - If `true`, the decoration will only be applied if the + # associated marker is non-empty. Only applicable to the `line` and + # gutter types. + decorateMarker: (marker, decorationParams) -> + @displayBuffer.decorateMarker(marker, decorationParams) decorationForId: (id) -> @displayBuffer.decorationForId(id)