github/atom
1
1
Fork 0
mirror of https://github.com/atom/atom.git synced 2026-01-23 22:08:08 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'MaximSokolov-fix-gutter-doc'

Browse Source 
References #8158
This commit is contained in:
Nathan Sobo
2015-08-28 09:47:56 -06:00
parent ff93fdf617 0a87dad747
commit 080a0c6030
3 changed files with 106 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
src/gutter-container.coffee
View File

@@ -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

89
src/gutter.coffee
View File

@@ -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)

91
src/text-editor.coffee
View File

@@ -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
# </div>
# ```
#
# ## 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.