From 533146bc6a1a3b75008ff9472e8360cd86e4ca77 Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Wed, 4 Nov 2015 15:58:00 -0800 Subject: [PATCH] Document new APIs --- src/display-buffer.coffee | 2 + src/layer-decoration.coffee | 20 ++++ src/text-editor-marker-layer.coffee | 139 +++++++++++++++++++++++----- src/text-editor.coffee | 100 ++++++++++++-------- 4 files changed, 199 insertions(+), 62 deletions(-) diff --git a/src/display-buffer.coffee b/src/display-buffer.coffee index e1bfff70f..f5a7bd853 100644 --- a/src/display-buffer.coffee +++ b/src/display-buffer.coffee @@ -926,6 +926,8 @@ class DisplayBuffer extends Model else if bufferLayer = @buffer.getMarkerLayer(id) @customMarkerLayersById[id] = new TextEditorMarkerLayer(this, bufferLayer) + getDefaultMarkerLayer: -> @defaultMarkerLayer + findFoldMarker: (params) -> @findFoldMarkers(params)[0] diff --git a/src/layer-decoration.coffee b/src/layer-decoration.coffee index a33c9e1a3..1f76140a3 100644 --- a/src/layer-decoration.coffee +++ b/src/layer-decoration.coffee @@ -3,6 +3,8 @@ _ = require 'underscore-plus' idCounter = 0 nextId = -> idCounter++ +# Essential: Represents a decoration that applies to every marker on a given +# layer. Created via {TextEditor::decorateMarkerLayer}. module.exports = class LayerDecoration constructor: (@markerLayer, @displayBuffer, @properties) -> @@ -11,6 +13,7 @@ class LayerDecoration @markerLayerDestroyedDisposable = @markerLayer.onDidDestroy => @destroy() @overridePropertiesByMarkerId = {} + # Essential: Destroys the decoration. destroy: -> return if @destroyed @markerLayerDestroyedDisposable.dispose() @@ -18,20 +21,37 @@ class LayerDecoration @destroyed = true @displayBuffer.didDestroyLayerDecoration(this) + # Essential: Determine whether this decoration is destroyed. + # + # Returns a {Boolean}. isDestroyed: -> @destroyed getId: -> @id getMarkerLayer: -> @markerLayer + # Essential: Get this decoration's properties. + # + # Returns an {Object}. getProperties: -> @properties + # Essential: Set this decoration's properties. + # + # * `newProperties` See {TextEditor::decorateMarker} for more information on + # the properties. The `type` of `gutter` and `overlay` are not supported on + # layer decorations. setProperties: (newProperties) -> return if @destroyed @properties = newProperties @displayBuffer.scheduleUpdateDecorationsEvent() + # Essential: Override the decoration properties for a specific marker. + # + # * `marker` The {TextEditorMarker} or {Marker} for which to override + # properties. + # * `properties` An {Object} containing properties to apply to this marker. + # Pass `null` to clear the override. setPropertiesForMarker: (marker, properties) -> return if @destroyed if properties? diff --git a/src/text-editor-marker-layer.coffee b/src/text-editor-marker-layer.coffee index 9b099637c..29ba3c8ef 100644 --- a/src/text-editor-marker-layer.coffee +++ b/src/text-editor-marker-layer.coffee @@ -1,43 +1,139 @@ TextEditorMarker = require './text-editor-marker' +# Public: *Experimental:* A container for a related set of markers at the +# {TextEditor} level. Wraps an underlying {MarkerLayer} on the editor's +# {TextBuffer}. +# +# This API is experimental and subject to change on any release. module.exports = class TextEditorMarkerLayer constructor: (@displayBuffer, @bufferMarkerLayer, @isDefaultLayer) -> @id = @bufferMarkerLayer.id @markersById = {} + ### + Section: Lifecycle + ### + + # Essential: Destroy this layer. + destroy: -> + if @isDefaultLayer + marker.destroy() for id, marker of @markersById + else + @bufferMarkerLayer.destroy() + + ### + Section: Querying + ### + + # Essential: Get an existing marker by its id. + # + # Returns a {TextEditorMarker}. getMarker: (id) -> if editorMarker = @markersById[id] editorMarker else if bufferMarker = @bufferMarkerLayer.getMarker(id) @markersById[id] = new TextEditorMarker(this, bufferMarker) + # Essential: Get all markers in the layer. + # + # Returns an {Array} of {TextEditorMarker}s. getMarkers: -> @bufferMarkerLayer.getMarkers().map ({id}) => @getMarker(id) - markBufferRange: (bufferRange, options) -> - @getMarker(@bufferMarkerLayer.markRange(bufferRange, options).id) - - markScreenRange: (screenRange, options) -> - bufferRange = @displayBuffer.bufferRangeForScreenRange(screenRange) - @markBufferRange(bufferRange, options) - - markBufferPosition: (bufferPosition, options) -> - @getMarker(@bufferMarkerLayer.markPosition(bufferPosition, options).id) - - markScreenPosition: (screenPosition, options) -> - bufferPosition = @displayBuffer.bufferPositionForScreenPosition(screenPosition) - @markBufferPosition(bufferPosition, options) + # Public: Get the number of markers in the marker layer. + # + # Returns a {Number}. + getMarkerCount: -> + @bufferMarkerLayer.getMarkerCount() + # Public: Find markers in the layer conforming to the given parameters. + # + # See the documentation for {TextEditor::findMarkers}. findMarkers: (params) -> params = @translateToBufferMarkerParams(params) @bufferMarkerLayer.findMarkers(params).map (stringMarker) => @getMarker(stringMarker.id) - destroy: -> - if @isDefaultLayer - marker.destroy() for id, marker of @markersById - else - @bufferMarkerLayer.destroy() + ### + Section: Marker creation + ### + + # Essential: Create a marker on this layer with the given range in buffer + # coordinates. + # + # See the documentation for {TextEditor::markBufferRange} + markBufferRange: (bufferRange, options) -> + @getMarker(@bufferMarkerLayer.markRange(bufferRange, options).id) + + # Essential: Create a marker on this layer with the given range in screen + # coordinates. + # + # See the documentation for {TextEditor::markScreenRange} + markScreenRange: (screenRange, options) -> + bufferRange = @displayBuffer.bufferRangeForScreenRange(screenRange) + @markBufferRange(bufferRange, options) + + # Public: Create a marker on this layer with the given buffer position and no + # tail. + # + # See the documentation for {TextEditor::markBufferPosition} + markBufferPosition: (bufferPosition, options) -> + @getMarker(@bufferMarkerLayer.markPosition(bufferPosition, options).id) + + # Public: Create a marker on this layer with the given screen position and no + # tail. + # + # See the documentation for {TextEditor::markScreenPosition} + markScreenPosition: (screenPosition, options) -> + bufferPosition = @displayBuffer.bufferPositionForScreenPosition(screenPosition) + @markBufferPosition(bufferPosition, options) + + ### + Section: Event Subscription + ### + + # Public: Subscribe to be notified asynchronously whenever markers are + # created, updated, or destroyed on this layer. *Prefer this method for + # optimal performance when interacting with layers that could contain large + # numbers of markers.* + # + # * `callback` A {Function} that will be called with no arguments when changes + # occur on this layer. + # + # Subscribers are notified once, asynchronously when any number of changes + # occur in a given tick of the event loop. You should re-query the layer + # to determine the state of markers in which you're interested in. It may + # be counter-intuitive, but this is much more efficient than subscribing to + # events on individual markers, which are expensive to deliver. + # + # Returns a {Disposable}. + onDidUpdate: (callback) -> + @bufferMarkerLayer.onDidUpdate(callback) + + # Public: Subscribe to be notified synchronously whenever markers are created + # on this layer. *Avoid this method for optimal performance when interacting + # with layers that could contain large numbers of markers.* + # + # * `callback` A {Function} that will be called with a {TextEditorMarker} + # whenever a new marker is created. + # + # You should prefer {onDidUpdate} when synchronous notifications aren't + # absolutely necessary. + # + # Returns a {Disposable}. + onDidCreateMarker: (callback) -> + @bufferMarkerLayer.onDidCreateMarker (bufferMarker) => + callback(@getMarker(bufferMarker.id)) + + # Public: Subscribe to be notified synchronously when this layer is destroyed. + # + # Returns a {Disposable}. + onDidDestroy: (callback) -> + @bufferMarkerLayer.onDidDestroy(callback) + + ### + Section: Private + ### refreshMarkerScreenPositions: -> for marker in @getMarkers() @@ -84,10 +180,3 @@ class TextEditorMarkerLayer bufferMarkerParams[key] = value bufferMarkerParams - - onDidCreateMarker: (callback) -> - @bufferMarkerLayer.onDidCreateMarker (bufferMarker) => - callback(@getMarker(bufferMarker.id)) - - onDidUpdate: (callback) -> - @bufferMarkerLayer.onDidUpdate(callback) diff --git a/src/text-editor.coffee b/src/text-editor.coffee index 8cc80f142..d44791013 100644 --- a/src/text-editor.coffee +++ b/src/text-editor.coffee @@ -1403,9 +1403,9 @@ class TextEditor extends Model Section: Decorations ### - # Essential: Adds a decoration that tracks a {TextEditorMarker}. When the marker moves, - # is invalidated, or is destroyed, the decoration will be updated to reflect - # the marker's state. + # Essential: Add a decoration that tracks a {TextEditorMarker}. When the + # marker moves, is invalidated, or is destroyed, the decoration will be + # updated to reflect the marker's state. # # The following are the supported decorations types: # @@ -1469,10 +1469,22 @@ class TextEditor extends Model decorateMarker: (marker, decorationParams) -> @displayBuffer.decorateMarker(marker, decorationParams) + # Essential: *Experimental:* Add a decoration to every marker in the given + # marker layer. Can be used to decorate a large number of markers without + # having to create and manage many individual decorations. + # + # * `markerLayer` A {TextEditorMarkerLayer} or {MarkerLayer} to decorate. + # * `decorationParams` The same parameters that are passed to + # {decorateMarker}, except the `type` cannot be `overlay` or `gutter`. + # + # This API is experimental and subject to change on any release. + # + # Returns a {LayerDecoration}. decorateMarkerLayer: (markerLayer, decorationParams) -> @displayBuffer.decorateMarkerLayer(markerLayer, decorationParams) - # Essential: Get all the decorations within a screen row range. + # Deprecated: Get all the decorations within a screen row range on the default + # layer. # # * `startScreenRow` the {Number} beginning screen row # * `endScreenRow` the {Number} end screen row (inclusive) @@ -1543,10 +1555,10 @@ class TextEditor extends Model Section: Markers ### - # Essential: Create a marker with the given range in buffer coordinates. This - # marker will maintain its logical location as the buffer is changed, so if - # you mark a particular word, the marker will remain over that word even if - # the word's location in the buffer changes. + # Essential: Create a marker on the default marker layer with the given range + # in buffer coordinates. This marker will maintain its logical location as the + # buffer is changed, so if you mark a particular word, the marker will remain + # over that word even if the word's location in the buffer changes. # # * `range` A {Range} or range-compatible {Array} # * `properties` A hash of key-value pairs to associate with the marker. There @@ -1578,10 +1590,10 @@ class TextEditor extends Model markBufferRange: (args...) -> @displayBuffer.markBufferRange(args...) - # Essential: Create a marker with the given range in screen coordinates. This - # marker will maintain its logical location as the buffer is changed, so if - # you mark a particular word, the marker will remain over that word even if - # the word's location in the buffer changes. + # Essential: Create a marker on the default marker layer with the given range + # in screen coordinates. This marker will maintain its logical location as the + # buffer is changed, so if you mark a particular word, the marker will remain + # over that word even if the word's location in the buffer changes. # # * `range` A {Range} or range-compatible {Array} # * `properties` A hash of key-value pairs to associate with the marker. There @@ -1613,7 +1625,8 @@ class TextEditor extends Model markScreenRange: (args...) -> @displayBuffer.markScreenRange(args...) - # Essential: Mark the given position in buffer coordinates. + # Essential: Mark the given position in buffer coordinates on the default + # marker layer. # # * `position` A {Point} or {Array} of `[row, column]`. # * `options` (optional) See {TextBuffer::markRange}. @@ -1622,7 +1635,8 @@ class TextEditor extends Model markBufferPosition: (args...) -> @displayBuffer.markBufferPosition(args...) - # Essential: Mark the given position in screen coordinates. + # Essential: Mark the given position in screen coordinates on the default + # marker layer. # # * `position` A {Point} or {Array} of `[row, column]`. # * `options` (optional) See {TextBuffer::markRange}. @@ -1631,7 +1645,8 @@ class TextEditor extends Model markScreenPosition: (args...) -> @displayBuffer.markScreenPosition(args...) - # Essential: Find all {TextEditorMarker}s that match the given properties. + # Essential: Find all {TextEditorMarker}s on the default marker layer that + # match the given properties. # # This method finds markers based on the given properties. Markers can be # associated with custom properties that will be compared with basic equality. @@ -1653,36 +1668,19 @@ class TextEditor extends Model findMarkers: (properties) -> @displayBuffer.findMarkers(properties) - # Extended: Observe changes in the set of markers that intersect a particular - # region of the editor. - # - # * `callback` A {Function} to call whenever one or more {TextEditorMarker}s appears, - # disappears, or moves within the given region. - # * `event` An {Object} with the following keys: - # * `insert` A {Set} containing the ids of all markers that appeared - # in the range. - # * `update` A {Set} containing the ids of all markers that moved within - # the region. - # * `remove` A {Set} containing the ids of all markers that disappeared - # from the region. - # - # Returns a {MarkerObservationWindow}, which allows you to specify the region - # of interest by calling {MarkerObservationWindow::setBufferRange} or - # {MarkerObservationWindow::setScreenRange}. - observeMarkers: (callback) -> - @displayBuffer.observeMarkers(callback) - - # Extended: Get the {TextEditorMarker} for the given marker id. + # Extended: Get the {TextEditorMarker} on the default layer for the given + # marker id. # # * `id` {Number} id of the marker getMarker: (id) -> @displayBuffer.getMarker(id) - # Extended: Get all {TextEditorMarker}s. Consider using {::findMarkers} + # Extended: Get all {TextEditorMarker}s on the default marker layer. Consider + # using {::findMarkers} getMarkers: -> @displayBuffer.getMarkers() - # Extended: Get the number of markers in this editor's buffer. + # Extended: Get the number of markers in the default marker layer. # # Returns a {Number}. getMarkerCount: -> @@ -1691,12 +1689,40 @@ class TextEditor extends Model destroyMarker: (id) -> @getMarker(id)?.destroy() + # Extended: *Experimental:* Create a marker layer to group related markers. + # + # * `options` An {Object} containing the following keys: + # * `maintainHistory` A {Boolean} indicating whether marker state should be + # restored on undo/redo. Defaults to `false`. + # + # This API is experimental and subject to change on any release. + # + # Returns a {TextEditorMarkerLayer}. addMarkerLayer: (options) -> @displayBuffer.addMarkerLayer(options) + # Public: *Experimental:* Get a {TextEditorMarkerLayer} by id. + # + # * `id` The id of the marker layer to retrieve. + # + # This API is experimental and subject to change on any release. + # + # Returns a {MarkerLayer} or `undefined` if no layer exists with the given + # id. getMarkerLayer: (id) -> @displayBuffer.getMarkerLayer(id) + # Public: *Experimental:* Get the default {TextEditorMarkerLayer}. + # + # All marker APIs not tied to an explicit layer interact with this default + # layer. + # + # This API is experimental and subject to change on any release. + # + # Returns a {TextEditorMarkerLayer}. + getDefaultMarkerLayer: -> + @displayBuffer.getDefaultMarkerLayer() + ### Section: Cursors ###