Merge pull request #1360 from atom/cj-add-prepend-append-methods-to-workspace

Add prepend/append methods to WorkspaceView

docs/internals/view-system.md

@@ -40,25 +40,18 @@ window, and contains every other view. If you open Atom's inspector with
 
 #### Panes
 
-The `WorkspaceView` contains a `#horizontal` and a `#vertical` axis surrounding
-`#panes`. Elements in the horizontal axis will tile across the window
-horizontally, appearing to have a vertical orientation. Items in the vertical
-axis will tile across the window vertically, appearing to have a horizontal
-orientation. You would typically attach tool panels to the root view's primary
-axes. Tool panels are elements which take up some screen real estate that isn't
-devoted to direct editing. In the example above, the `TreeView` is present in
-the `#horizontal` axis to the left of the `#panes`, and the `CommandPanel` is
-present in the `#vertical` axis below the `#panes`.
-
-You can attach a tool panel to an axis using the `horizontal` or `vertical`
-outlets as follows:
+The `WorkspaceView` contains `prependToBottom/Top/Left/Right` and
+`appendToBottom/Top/Left/Right` methods, which are used to add Tool Panels. Tool
+panels are elements that take up screen real estate not devoted to text editing.
+In the example above, the `TreeView` is appended to the left, and the
+`CommandPanel` is appended to the top.
 
 ```coffeescript
-# place a view to the left of the panes (or use .append() to place it to the right)
-atom.workspaceView.horizontal.prepend(new MyView)
+# place a view to the left of the panes
+atom.workspaceView.appendToLeft(new MyView)
 
-# place a view below the panes (or use .prepend() to place it above)
-atom.workspaceView.vertical.append(new MyOtherView)
+# place a view below the panes
+atom.workspaceView.appendToBottom(new MyOtherView)
 ```
 
 [spacepen]: http://github.com/nathansobo/space-pen

docs/your-first-package.md

@@ -177,32 +177,33 @@ ul.modified-files-list {
 }
 ```
 
-We'll add one more line to the end of the `magic` method to make this pane appear:
+We'll add one more line to the end of the `magic` method to make this pane
+appear:
 
 ```coffeescript
-atom.workspaceView.vertical.append(this)
+atom.workspaceView.prependToBottom(this)
 ```
 
-If you refresh Atom and hit the key command, you'll see a box appear right underneath
-the editor:
+If you refresh Atom and hit the key command, you'll see a box appear right
+underneath the editor:
 
 ![Changer_Panel_Append]
 
-As you might have guessed, `atom.workspaceView.vertical.append` tells Atom to append `this`
-item (_i.e._, whatever is defined by`@content`) _vertically_ to the editor. If
-we had called `atom.workspaceView.horizontal.append`, the pane would be attached to the
-right-hand side of the editor.
+As you might have guessed, `atom.workspaceView.prependToBottom` tells Atom to
+prepend `this` item (_i.e._, whatever is defined by`@content`). If we had called
+`atom.workspaceView.appendToBottom`, the pane would be attached below the status
+bar.
 
-Before we populate this panel for real, let's apply some logic to toggle the pane
-off and on, just like we did with the tree view. Replace the `atom.workspaceView.vertical.append`
-call with this code:
+Before we populate this panel for real, let's apply some logic to toggle the
+pane off and on, just like we did with the tree view. Replace the
+`atom.workspaceView.prependToBottom` call with this code:
 
 ```coffeescript
 # toggles the pane
 if @hasParent()
-  atom.workspaceView.vertical.children().last().remove()
+  @remove()
 else
-  atom.workspaceView.vertical.append(this)
+  atom.workspaceView.prependToBottom(this)
 ```
 
 There are about a hundred different ways to toggle a pane on and off, and this
@@ -261,13 +262,13 @@ appending it to `modifiedFilesList`:
 ```coffeescript
 # toggles the pane
 if @hasParent()
-  atom.workspaceView.vertical.children().last().remove()
+  @remove()
 else
   for file in modifiedFiles
     stat = fs.lstatSync(file)
     mtime = stat.mtime
     @modifiedFilesList.append("<li>#{file} - Modified at #{mtime}")
-  atom.workspaceView.vertical.append(this)
+  atom.workspaceView.prependToBottom(this)
 ```
 
 When you toggle the modified files list, your pane is now populated with the
@@ -283,13 +284,13 @@ this demonstration, we'll just clear the `modifiedFilesList` each time it's clos
 # toggles the pane
 if @hasParent()
   @modifiedFilesList.empty() # added this to clear the list on close
-  atom.workspaceView.vertical.children().last().remove()
+  @remove()
 else
   for file in modifiedFiles
     stat = fs.lstatSync(file)
     mtime = stat.mtime
     @modifiedFilesList.append("<li>#{file} - Modified at #{mtime}")
-  atom.workspaceView.vertical.append(this)
+  atom.workspaceView.prependToBottom(this)
 ```
 
 ## Coloring UI Elements

spec/workspace-view-spec.coffee

@@ -111,7 +111,7 @@ describe "WorkspaceView", ->
         it "passes focus to the first focusable element", ->
           focusable1 = $$ -> @div "One", id: 'one', tabindex: -1
           focusable2 = $$ -> @div "Two", id: 'two', tabindex: -1
-          atom.workspaceView.horizontal.append(focusable1, focusable2)
+          atom.workspaceView.appendToLeft(focusable1, focusable2)
           expect(document.activeElement).toBe document.body
 
           atom.workspaceView.focus()
@@ -120,7 +120,7 @@ describe "WorkspaceView", ->
       describe "when there are no visible focusable elements", ->
         it "surrenders focus to the body", ->
           focusable = $$ -> @div "One", id: 'one', tabindex: -1
-          atom.workspaceView.horizontal.append(focusable)
+          atom.workspaceView.appendToLeft(focusable)
           focusable.hide()
           expect(document.activeElement).toBe document.body
 

src/workspace-view.coffee

@@ -272,6 +272,38 @@ class WorkspaceView extends View
   getOpenBufferPaths: ->
     _.uniq(_.flatten(@getEditorViews().map (editorView) -> editorView.getOpenBufferPaths()))
 
+  # Public: Prepends the element to the top of the window.
+  prependToTop: (element) ->
+    @vertical.prepend(element)
+
+  # Public: Appends the element to the top of the window.
+  appendToTop: (element) ->
+    @panes.before(element)
+
+  # Public: Prepends the element to the bottom of the window.
+  prependToBottom: (element) ->
+    @panes.after(element)
+
+  # Public: Appends the element to bottom of the window.
+  appendToBottom: (element) ->
+    @vertical.append(element)
+
+  # Public: Prepends the element to the left side of the window.
+  prependToLeft: (element) ->
+    @horizontal.prepend(element)
+
+  # Public: Appends the element to the left side of the window.
+  appendToLeft: (element) ->
+    @vertical.before(element)
+
+  # Public: Prepends the element to the right side of the window.
+  prependToRight: (element) ->
+    @vertical.after(element)
+
+  # Public: Appends the element to the right side of the window.
+  appendToRight: (element) ->
+    @horizontal.append(element)
+
   # Public: Returns the currently focused {Pane}.
   getActivePane: ->
     @panes.getActivePane()