From 35fd19f3ef6598997b7bb5a2432872fb9d6da08d Mon Sep 17 00:00:00 2001 From: Ben Ogle Date: Wed, 30 Jul 2014 15:33:04 -0700 Subject: [PATCH] :memo: Add docs for current public methods --- src/react-editor-view.coffee | 107 ++++++++++++++++++++++++++++++++++- 1 file changed, 106 insertions(+), 1 deletion(-) diff --git a/src/react-editor-view.coffee b/src/react-editor-view.coffee index 3f724322b..9b27272b1 100644 --- a/src/react-editor-view.coffee +++ b/src/react-editor-view.coffee @@ -4,7 +4,33 @@ React = require 'react-atom-fork' TextBuffer = require 'text-buffer' Editor = require './editor' EditorComponent = require './editor-component' +{deprecate} = require 'grim' +# Public: Represents the entire visual pane in Atom. +# +# The EditorView manages the {Editor}, which manages the file buffers. +# +# ## Requiring in packages +# +# ```coffee +# {EditorView} = require 'atom' +# +# miniEditorView = new EditorView(mini: true) +# ``` +# +# ## Iterating over the open editor views +# +# ```coffee +# for editorView in atom.workspaceView.getEditorViews() +# console.log(editorView.getModel().getPath()) +# ``` +# +# ## Subscribing to every current and future editor +# +# ```coffee +# atom.workspace.eachEditorView (editorView) -> +# console.log(editorView.getModel().getPath()) +# ``` module.exports = class EditorView extends View @configDefaults: @@ -33,6 +59,13 @@ class EditorView extends View focusOnAttach: false + # The constructor for setting up an `EditorView` instance. + # + # editorOrParams - Either an {Editor}, or an object with one property, `mini`. + # If `mini` is `true`, a "miniature" `Editor` is constructed. + # Typically, this is ideal for scenarios where you need an Atom editor, + # but without all the chrome, like scrollbars, gutter, _e.t.c._. + # constructor: (editorOrParams, props) -> super @@ -81,8 +114,13 @@ class EditorView extends View else @focusOnAttach = true - getEditor: -> @editor + getEditor: -> + deprecate("Use EditorView::getModel instead") + @editor + # Public: Get the underlying editor model for this view. + # + # Returns an {Editor}. getModel: -> @editor Object.defineProperty @::, 'lineHeight', get: -> @editor.getLineHeightInPixels() @@ -122,12 +160,23 @@ class EditorView extends View else @editor.getScrollLeft() + # Public: Scrolls the editor to the bottom. scrollToBottom: -> @editor.setScrollBottom(Infinity) + # Public: Scrolls the editor to the given screen position. + # + # screenPosition - An object that represents a buffer position. It can be either + # an {Object} (`{row, column}`), {Array} (`[row, column]`), or {Point} + # options - A hash matching the options available to {::scrollToScreenPosition} scrollToScreenPosition: (screenPosition, options) -> @editor.scrollToScreenPosition(screenPosition, options) + # Public: Scrolls the editor to the given buffer position. + # + # bufferPosition - An object that represents a buffer position. It can be either + # an {Object} (`{row, column}`), {Array} (`[row, column]`), or {Point} + # options - A hash matching the options available to {::scrollToBufferPosition} scrollToBufferPosition: (bufferPosition, options) -> @editor.scrollToBufferPosition(bufferPosition, options) @@ -138,9 +187,21 @@ class EditorView extends View screenPosition = screenPositionForPixelPosition(pixelPosition) @editor.scrollToScreenPosition(screenPosition) + # Public: Converts a buffer position to a pixel position. + # + # position - An object that represents a buffer position. It can be either + # an {Object} (`{row, column}`), {Array} (`[row, column]`), or {Point} + # + # Returns an object with two values: `top` and `left`, representing the pixel positions. pixelPositionForBufferPosition: (bufferPosition) -> @editor.pixelPositionForBufferPosition(bufferPosition) + # Public: Converts a screen position to a pixel position. + # + # position - An object that represents a screen position. It can be either + # an {Object} (`{row, column}`), {Array} (`[row, column]`), or {Point} + # + # Returns an object with two values: `top` and `left`, representing the pixel positions. pixelPositionForScreenPosition: (screenPosition) -> @editor.pixelPositionForScreenPosition(screenPosition) @@ -175,6 +236,9 @@ class EditorView extends View pane = @getPane() pane?.splitDown(pane?.copyActiveItem()).activeView + # Public: Get this view's pane. + # + # Returns a {Pane}. getPane: -> @parent('.item-views').parents('.pane').view() @@ -199,36 +263,72 @@ class EditorView extends View pageUp: -> @editor.pageUp() + # Public: Retrieves the number of the row that is visible and currently at the + # top of the editor. + # + # Returns a {Number}. getFirstVisibleScreenRow: -> @editor.getVisibleRowRange()[0] + # Public: Retrieves the number of the row that is visible and currently at the + # bottom of the editor. + # + # Returns a {Number}. getLastVisibleScreenRow: -> @editor.getVisibleRowRange()[1] + # Public: Gets the font family for the editor. + # + # Returns a {String} identifying the CSS `font-family`. getFontFamily: -> @component?.getFontFamily() + # Public: Sets the font family for the editor. + # + # fontFamily - A {String} identifying the CSS `font-family`. setFontFamily: (fontFamily) -> @component?.setFontFamily(fontFamily) + # Public: Retrieves the font size for the editor. + # + # Returns a {Number} indicating the font size in pixels. getFontSize: -> @component?.getFontSize() + # Public: Sets the font size for the editor. + # + # fontSize - A {Number} indicating the font size in pixels. setFontSize: (fontSize) -> @component?.setFontSize(fontSize) setWidthInChars: (widthInChars) -> @component.getDOMNode().style.width = (@editor.getDefaultCharWidth() * widthInChars) + 'px' + # Public: Sets the line height of the editor. + # + # Calling this method has no effect when called on a mini editor. + # + # lineHeight - A {Number} without a unit suffix identifying the CSS + # `line-height`. setLineHeight: (lineHeight) -> @component.setLineHeight(lineHeight) + # Public: Sets whether you want to show the indentation guides. + # + # showIndentGuide - A {Boolean} you can set to `true` if you want to see the + # indentation guides. setShowIndentGuide: (showIndentGuide) -> @component.setShowIndentGuide(showIndentGuide) + # Public: Enables/disables soft wrap on the editor. + # + # softWrap - A {Boolean} which, if `true`, enables soft wrap setSoftWrap: (softWrap) -> @editor.setSoftWrap(softWrap) + # Public: Set whether invisible characters are shown. + # + # showInvisibles - A {Boolean} which, if `true`, show invisible characters. setShowInvisibles: (showInvisibles) -> @component.setShowInvisibles(showInvisibles) @@ -261,6 +361,11 @@ class EditorView extends View redraw: -> # No-op shim + # Public: Set the text to appear in the editor when it is empty. + # + # This only affects mini editors. + # + # placeholderText - A {String} of text to display when empty. setPlaceholderText: (placeholderText) -> if @component? @component.setProps({placeholderText})