diff --git a/src/gutter-container.coffee b/src/gutter-container.coffee index 4fa7c61fb..084e1e1ad 100644 --- a/src/gutter-container.coffee +++ b/src/gutter-container.coffee @@ -1,12 +1,8 @@ {Emitter} = require 'event-kit' Gutter = require './gutter' -# This class encapsulates the logic for adding and modifying a set of gutters. - module.exports = class GutterContainer - - # * `textEditor` The {TextEditor} to which this {GutterContainer} belongs. constructor: (textEditor) -> @gutters = [] @textEditor = textEditor @@ -21,14 +17,6 @@ class GutterContainer @gutters = [] @emitter.dispose() - # Creates and returns a {Gutter}. - # * `options` An {Object} with the following fields: - # * `name` (required) A unique {String} to identify this gutter. - # * `priority` (optional) A {Number} that determines stacking order between - # gutters. Lower priority items are forced closer to the edges of the - # window. (default: -100) - # * `visible` (optional) {Boolean} specifying whether the gutter is visible - # initially after being created. (default: true) addGutter: (options) -> options = options ? {} gutterName = options.name @@ -59,20 +47,13 @@ class GutterContainer if gutter.name is name then return gutter null - ### - Section: Event Subscription - ### - - # See {TextEditor::observeGutters} for details. observeGutters: (callback) -> callback(gutter) for gutter in @getGutters() @onDidAddGutter callback - # See {TextEditor::onDidAddGutter} for details. onDidAddGutter: (callback) -> @emitter.on 'did-add-gutter', callback - # See {TextEditor::onDidRemoveGutter} for details. onDidRemoveGutter: (callback) -> @emitter.on 'did-remove-gutter', callback diff --git a/src/gutter.coffee b/src/gutter.coffee index 0b3b6533b..160036e3e 100644 --- a/src/gutter.coffee +++ b/src/gutter.coffee @@ -1,19 +1,12 @@ {Emitter} = require 'event-kit' -# Public: This class represents a gutter within a TextEditor. - DefaultPriority = -100 +# Extended: Represents a gutter within a {TextEditor}. +# +# See {TextEditor::addGutter} for information on creating a gutter. module.exports = class Gutter - # * `gutterContainer` The {GutterContainer} object to which this gutter belongs. - # * `options` An {Object} with the following fields: - # * `name` (required) A unique {String} to identify this gutter. - # * `priority` (optional) A {Number} that determines stacking order between - # gutters. Lower priority items are forced closer to the edges of the - # window. (default: -100) - # * `visible` (optional) {Boolean} specifying whether the gutter is visible - # initially after being created. (default: true) constructor: (gutterContainer, options) -> @gutterContainer = gutterContainer @name = options?.name @@ -22,6 +15,11 @@ class Gutter @emitter = new Emitter + ### + Section: Gutter Destruction + ### + + # Essential: Destroys the gutter. destroy: -> if @name is 'line-number' throw new Error('The line-number gutter cannot be destroyed.') @@ -30,42 +28,63 @@ class Gutter @emitter.emit 'did-destroy' @emitter.dispose() - hide: -> - if @visible - @visible = false - @emitter.emit 'did-change-visible', this + ### + Section: Event Subscription + ### - show: -> - if not @visible - @visible = true - @emitter.emit 'did-change-visible', this - - isVisible: -> - @visible - - # * `marker` (required) A Marker object. - # * `options` (optional) An object with the following fields: - # * `class` (optional) - # * `item` (optional) A model {Object} with a corresponding view registered, - # or an {HTMLElement}. - # - # Returns a {Decoration} object. - decorateMarker: (marker, options) -> - @gutterContainer.addGutterDecoration(this, marker, options) - - # Calls your `callback` when the {Gutter}'s' visibility changes. + # Essential: Calls your `callback` when the gutter's visibility changes. # # * `callback` {Function} - # * `gutter` The {Gutter} whose visibility changed. + # * `gutter` The gutter whose visibility changed. # # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe. onDidChangeVisible: (callback) -> @emitter.on 'did-change-visible', callback - # Calls your `callback` when the {Gutter} is destroyed + # Essential: Calls your `callback` when the gutter is destroyed. # # * `callback` {Function} # # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe. onDidDestroy: (callback) -> @emitter.on 'did-destroy', callback + + ### + Section: Visibility + ### + + # Essential: Hide the gutter. + hide: -> + if @visible + @visible = false + @emitter.emit 'did-change-visible', this + + # Essential: Show the gutter. + show: -> + if not @visible + @visible = true + @emitter.emit 'did-change-visible', this + + # Essential: Determine whether the gutter is visible. + # + # Returns a {Boolean}. + isVisible: -> + @visible + + # Essential: Add a decoration that tracks a {Marker}. When the marker moves, + # is invalidated, or is destroyed, the decoration will be updated to reflect + # the marker's state. + # + # * `marker` A {Marker} you want this decoration to follow. + # * `decorationParams` An {Object} representing the decoration + # * `class` This CSS class will be applied to the decorated line number. + # * `onlyHead` (optional) If `true`, the decoration will only be applied to + # the head of the marker. + # * `onlyEmpty` (optional) If `true`, the decoration will only be applied if + # the associated marker is empty. + # * `onlyNonEmpty` (optional) If `true`, the decoration will only be applied + # if the associated marker is non-empty. + # + # Returns a {Decoration} object + decorateMarker: (marker, options) -> + @gutterContainer.addGutterDecoration(this, marker, options) diff --git a/src/text-editor.coffee b/src/text-editor.coffee index 5f6408c30..b8c2a76fb 100644 --- a/src/text-editor.coffee +++ b/src/text-editor.coffee @@ -14,7 +14,7 @@ TextMateScopeSelector = require('first-mate').ScopeSelector {Directory} = require "pathwatcher" GutterContainer = require './gutter-container' -# Public: This class represents all essential editing state for a single +# Essential: This class represents all essential editing state for a single # {TextBuffer}, including cursor and selection positions, folds, and soft wraps. # If you're manipulating the state of an editor, use this class. If you're # interested in the visual appearance of editors, use {TextEditorView} instead. @@ -341,7 +341,7 @@ class TextEditor extends Model onDidInsertText: (callback) -> @emitter.on 'did-insert-text', callback - # Public: Invoke the given callback after the buffer is saved to disk. + # Essential: Invoke the given callback after the buffer is saved to disk. # # * `callback` {Function} to be called after the buffer is saved. # * `event` {Object} with the following keys: @@ -351,7 +351,7 @@ class TextEditor extends Model onDidSave: (callback) -> @getBuffer().onDidSave(callback) - # Public: Invoke the given callback when the editor is destroyed. + # Essential: Invoke the given callback when the editor is destroyed. # # * `callback` {Function} to be called when the editor is destroyed. # @@ -470,7 +470,7 @@ class TextEditor extends Model onDidUpdateMarkers: (callback) -> @displayBuffer.onDidUpdateMarkers(callback) - # Public: Retrieves the current {TextBuffer}. + # Essential: Retrieves the current {TextBuffer}. getBuffer: -> @buffer # Retrieves the current buffer's URI. @@ -514,20 +514,7 @@ class TextEditor extends Model onDidChangeLineNumberGutterVisible: (callback) -> @emitter.on 'did-change-line-number-gutter-visible', callback - # Public: Creates and returns a {Gutter}. - # See {GutterContainer::addGutter} for more details. - addGutter: (options) -> - @gutterContainer.addGutter(options) - - # Public: Returns the {Array} of all gutters on this editor. - getGutters: -> - @gutterContainer.getGutters() - - # Public: Returns the {Gutter} with the given name, or null if it doesn't exist. - gutterWithName: (name) -> - @gutterContainer.gutterWithName(name) - - # Calls your `callback` when a {Gutter} is added to the editor. + # Essential: Calls your `callback` when a {Gutter} is added to the editor. # Immediately calls your callback for each existing gutter. # # * `callback` {Function} @@ -537,7 +524,7 @@ class TextEditor extends Model observeGutters: (callback) -> @gutterContainer.observeGutters callback - # Calls your `callback` when a {Gutter} is added to the editor. + # Essential: Calls your `callback` when a {Gutter} is added to the editor. # # * `callback` {Function} # * `gutter` {Gutter} that was added. @@ -546,7 +533,7 @@ class TextEditor extends Model onDidAddGutter: (callback) -> @gutterContainer.onDidAddGutter callback - # Calls your `callback` when a {Gutter} is removed from the editor. + # Essential: Calls your `callback` when a {Gutter} is removed from the editor. # # * `callback` {Function} # * `name` The name of the {Gutter} that was removed. @@ -629,7 +616,7 @@ class TextEditor extends Model # See {TextBuffer::save} for more details. save: -> @buffer.save(backup: atom.config.get('editor.backUpBeforeSaving')) - # Public: Saves the editor's text buffer as the given path. + # Essential: Saves the editor's text buffer as the given path. # # See {TextBuffer::saveAs} for more details. # @@ -742,7 +729,7 @@ class TextEditor extends Model # {Delegates to: TextBuffer.getEndPosition} getEofBufferPosition: -> @buffer.getEndPosition() - # Public: Get the {Range} of the paragraph surrounding the most recently added + # Essential: Get the {Range} of the paragraph surrounding the most recently added # cursor. # # Returns a {Range}. @@ -1292,7 +1279,7 @@ class TextEditor extends Model # # * __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 + # * __line-number__: 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 @@ -1305,14 +1292,12 @@ class TextEditor extends Model # # ``` # - # ## Arguments - # # * `marker` A {Marker} you want this decoration to follow. # * `decorationParams` An {Object} representing the decoration e.g. # `{type: 'line-number', class: 'linter-error'}` - # * `type` There are a few supported decoration types: `gutter`, `line`, + # * `type` There are a few supported decoration types: `line-number`, `line`, # `highlight`, and `overlay`. The behavior of the types are as follows: - # * `gutter` Adds the given `class` to the line numbers overlapping the + # * `line-number` Adds the given `class` to the line numbers overlapping the # rows spanned by the marker. # * `line` Adds the given `class` to the lines overlapping the rows # spanned by the marker. @@ -1324,19 +1309,17 @@ class TextEditor extends Model # * `class` This CSS class will be applied to the decorated line number, # line, highlight, or overlay. # * `onlyHead` (optional) If `true`, the decoration will only be applied to - # the head of the marker. Only applicable to the `line` and `gutter` + # the head of the marker. Only applicable to the `line` and `line-number` # types. # * `onlyEmpty` (optional) If `true`, the decoration will only be applied if # the associated marker is empty. Only applicable to the `line` and - # `gutter` types. + # `line-number` types. # * `onlyNonEmpty` (optional) If `true`, the decoration will only be applied # if the associated marker is non-empty. Only applicable to the `line` - # and gutter types. + # and `line-number` types. # * `position` (optional) Only applicable to decorations of type `overlay`, # controls where the overlay view is positioned relative to the marker. # Values can be `'head'` (the default), or `'tail'`. - # * `gutterName` (optional) Only applicable to the `gutter` type. If provided, - # the decoration will be applied to the gutter with the specified name. # # Returns a {Decoration} object decorateMarker: (marker, decorationParams) -> @@ -1345,7 +1328,7 @@ class TextEditor extends Model decorationParams.type = 'line-number' @displayBuffer.decorateMarker(marker, decorationParams) - # Public: Get all the decorations within a screen row range. + # Essential: Get all the decorations within a screen row range. # # * `startScreenRow` the {Number} beginning screen row # * `endScreenRow` the {Number} end screen row (inclusive) @@ -2325,7 +2308,7 @@ class TextEditor extends Model # * `replace` Call this {Function} with a {String} to replace the match. scan: (regex, iterator) -> @buffer.scan(regex, iterator) - # Public: Scan regular expression matches in a given range, calling the given + # Essential: Scan regular expression matches in a given range, calling the given # iterator function on each match. # # * `regex` A {RegExp} to search for. @@ -2339,7 +2322,7 @@ class TextEditor extends Model # * `replace` Call this {Function} with a {String} to replace the match. scanInBufferRange: (regex, range, iterator) -> @buffer.scanInRange(regex, range, iterator) - # Public: Scan regular expression matches in a given range in reverse order, + # Essential: Scan regular expression matches in a given range in reverse order, # calling the given iterator function on each match. # # * `regex` A {RegExp} to search for. @@ -2451,7 +2434,7 @@ class TextEditor extends Model # Returns a {Boolean}. toggleSoftWrapped: -> @setSoftWrapped(not @isSoftWrapped()) - # Public: Gets the column at which column will soft wrap + # Essential: Gets the column at which column will soft wrap getSoftWrapColumn: -> @displayBuffer.getSoftWrapColumn() ### @@ -2686,7 +2669,7 @@ class TextEditor extends Model @emit('did-insert-text', didInsertEvent) if includeDeprecatedAPIs @emitter.emit 'did-insert-text', didInsertEvent - # Public: For each selection, if the selection is empty, cut all characters + # Essential: For each selection, if the selection is empty, cut all characters # of the containing line following the cursor. Otherwise cut the selected # text. cutToEndOfLine: -> @@ -2834,6 +2817,36 @@ class TextEditor extends Model outermostFoldsInBufferRowRange: (startRow, endRow) -> @displayBuffer.outermostFoldsInBufferRowRange(startRow, endRow) + ### + Section: Gutters + ### + + # Essential: Add a custom {Gutter}. + # + # * `options` An {Object} with the following fields: + # * `name` (required) A unique {String} to identify this gutter. + # * `priority` (optional) A {Number} that determines stacking order between + # gutters. Lower priority items are forced closer to the edges of the + # window. (default: -100) + # * `visible` (optional) {Boolean} specifying whether the gutter is visible + # initially after being created. (default: true) + # + # Returns the newly-created {Gutter}. + addGutter: (options) -> + @gutterContainer.addGutter(options) + + # Essential: Get this editor's gutters. + # + # Returns an {Array} of {Gutter}s. + getGutters: -> + @gutterContainer.getGutters() + + # Essential: Get the gutter with the given name. + # + # Returns a {Gutter}, or `null` if no gutter exists for the given name. + gutterWithName: (name) -> + @gutterContainer.gutterWithName(name) + ### Section: Scrolling the TextEditor ### @@ -2934,13 +2947,13 @@ class TextEditor extends Model Section: TextEditor Rendering ### - # Public: Retrieves the greyed out placeholder of a mini editor. + # Essential: Retrieves the greyed out placeholder of a mini editor. # # Returns a {String}. getPlaceholderText: -> @placeholderText - # Public: Set the greyed out placeholder of a mini editor. Placeholder text + # Essential: Set the greyed out placeholder of a mini editor. Placeholder text # will be displayed when the editor has no content. # # * `placeholderText` {String} text that is displayed when the editor has no content.