From 01556be16386facb5f60e3f16987cdca9f5e2303 Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Mon, 3 Apr 2017 13:31:08 -0600 Subject: [PATCH 1/4] Document workspace items --- src/workspace.js | 103 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/src/workspace.js b/src/workspace.js index 7e7ddbe30..a3938fcd9 100644 --- a/src/workspace.js +++ b/src/workspace.js @@ -25,8 +25,109 @@ const WorkspaceCenter = require('./workspace-center') // editors, and manipulate panes. To add panels, use {Workspace::addTopPanel} // and friends. // -// * `editor` {TextEditor} the new editor +// ## Workspace Items // +// The term "item" refers to anything that can be displayed +// in a pane within the workspace, either in the {WorkspaceCenter} or in one +// of the three {Dock}s. The workspace expects items to conform to the +// following interface: +// +// ### Required Methods +// +// #### `getTitle` Returns the title of the item to display on its associated +// #### tab. +// +// ### Optional Methods +// +// #### `getElement` +// +// If your item already *is* a DOM element, you do not need to implement this +// method. Otherwise it should return the element you want to display to +// represent this item. +// +// #### `destroy` +// +// Destroys the item. This will be called when the item is removed from its +// parent pane. +// +// #### `onDidDestroy` +// +// Called by the workspace so it can be notified when the item is destroyed. +// Must return a {Disposable}. +// +// #### `serialize` +// +// Serialize the state of the item. Must return an object that can be passed to +// `JSON.stringify`. The state should include a field called `deserializer`, +// which names a deserializer declared in your `package.json`. This method is +// invoked on items when serializing the workspace so they can be restored to +// the same location later. +// +// #### `getURI` +// +// Returns the URI associated with the item. +// +// #### `getPreferredLocation` +// +// Tells the workspace where your item should be opened in absence of a user +// override. Items can appear in the center or in a dock on the left, right, or +// bottom of the workspace. +// +// Returns a {String} with one of the following values: `'center'`, `'left'`, +// `'right'`, `'bottom'`. If this method is not defined, `'center'` is the +// default. +// +// #### `getAllowedLocations` +// +// Tells the workspace where this item can be moved. Returns an {Array} of one +// or more of the following values: `'center'`, `'left'`, `'right'`, or +// `'bottom'`. +// +// #### `isPermanentDockItem` +// +// Tells the workspace whether or not this item can be closed by the user. Use +// of this feature is discouraged unless there's a very good reason not to allow +// users to close your item. Items can be made permanent *only* when they are +// contained in docks. Center pane items can always be removed. +// +// #### `save()` +// +// Saves the item. +// +// #### `saveAs(path)` +// +// Saves the item to the specified path. +// +// #### `getPath` +// +// Returns the local path associated with this item. This is only used to set +// the initial location of the "save as" dialog. +// +// #### `isModified` +// +// Returns whether or not the item is modified to reflect modification in the +// UI. +// +// #### `onDidChangeModified` +// +// Called by the workspace so it can be notified when item's modified status +// changes. Must return a {Disposable}. +// +// #### `copy` +// +// Create a copy of the item. If defined, the workspace will call this method to +// duplicate the item when splitting panes via certain split commands. +// +// #### `onDidTerminatePendingState` +// +// If the workspace is configured to use *pending pane items*, the workspace +// will subscribe to this method to terminate the pending state of the item. +// Must return a {Disposable}. +// +// #### `shouldPromptToSave` +// +// This method indicates whether Atom should prompt the user to save this item +// when the user closes or reloads the window. Returns a boolean. module.exports = class Workspace extends Model { constructor (params) { super(...arguments) From 215f5fd1fb984497a672d70cd9547f8396b8dabd Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Tue, 4 Apr 2017 17:19:48 -0600 Subject: [PATCH 2/4] Document pane item interface on Workspace --- src/workspace.js | 42 +++++++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/src/workspace.js b/src/workspace.js index a3938fcd9..f567e83b4 100644 --- a/src/workspace.js +++ b/src/workspace.js @@ -34,28 +34,28 @@ const WorkspaceCenter = require('./workspace-center') // // ### Required Methods // -// #### `getTitle` Returns the title of the item to display on its associated +// #### `getTitle()` Returns the title of the item to display on its associated // #### tab. // // ### Optional Methods // -// #### `getElement` +// #### `getElement()` // // If your item already *is* a DOM element, you do not need to implement this // method. Otherwise it should return the element you want to display to // represent this item. // -// #### `destroy` +// #### `destroy()` // // Destroys the item. This will be called when the item is removed from its // parent pane. // -// #### `onDidDestroy` +// #### `onDidDestroy(callback)` // // Called by the workspace so it can be notified when the item is destroyed. // Must return a {Disposable}. // -// #### `serialize` +// #### `serialize()` // // Serialize the state of the item. Must return an object that can be passed to // `JSON.stringify`. The state should include a field called `deserializer`, @@ -63,11 +63,11 @@ const WorkspaceCenter = require('./workspace-center') // invoked on items when serializing the workspace so they can be restored to // the same location later. // -// #### `getURI` +// #### `getURI()` // // Returns the URI associated with the item. // -// #### `getPreferredLocation` +// #### `getDefaultLocation()` // // Tells the workspace where your item should be opened in absence of a user // override. Items can appear in the center or in a dock on the left, right, or @@ -77,18 +77,22 @@ const WorkspaceCenter = require('./workspace-center') // `'right'`, `'bottom'`. If this method is not defined, `'center'` is the // default. // -// #### `getAllowedLocations` +// #### `getAllowedLocations()` // // Tells the workspace where this item can be moved. Returns an {Array} of one // or more of the following values: `'center'`, `'left'`, `'right'`, or // `'bottom'`. // -// #### `isPermanentDockItem` +// #### `isPermanentDockItem()` // -// Tells the workspace whether or not this item can be closed by the user. Use -// of this feature is discouraged unless there's a very good reason not to allow -// users to close your item. Items can be made permanent *only* when they are -// contained in docks. Center pane items can always be removed. +// Tells the workspace whether or not this item can be closed by the user by +// clicking an `x` on its tab. Use of this feature is discouraged unless there's +// a very good reason not to allow users to close your item. Items can be made +// permanent *only* when they are contained in docks. Center pane items can +// always be removed. Note that it is currently still possible to close dock +// items via the `Close Pane` option in the context menu and via Atom APIs, so +// you should still be prepared to handle your dock items being destroyed by the +// user even if you implement this method. // // #### `save()` // @@ -98,33 +102,33 @@ const WorkspaceCenter = require('./workspace-center') // // Saves the item to the specified path. // -// #### `getPath` +// #### `getPath()` // // Returns the local path associated with this item. This is only used to set // the initial location of the "save as" dialog. // -// #### `isModified` +// #### `isModified()` // // Returns whether or not the item is modified to reflect modification in the // UI. // -// #### `onDidChangeModified` +// #### `onDidChangeModified()` // // Called by the workspace so it can be notified when item's modified status // changes. Must return a {Disposable}. // -// #### `copy` +// #### `copy()` // // Create a copy of the item. If defined, the workspace will call this method to // duplicate the item when splitting panes via certain split commands. // -// #### `onDidTerminatePendingState` +// #### `onDidTerminatePendingState(callback)` // // If the workspace is configured to use *pending pane items*, the workspace // will subscribe to this method to terminate the pending state of the item. // Must return a {Disposable}. // -// #### `shouldPromptToSave` +// #### `shouldPromptToSave()` // // This method indicates whether Atom should prompt the user to save this item // when the user closes or reloads the window. Returns a boolean. From 30f79babda20ad3a1b28326fa62724f7fb167617 Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Wed, 5 Apr 2017 10:34:42 -0600 Subject: [PATCH 3/4] Document more methods --- src/workspace.js | 43 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/src/workspace.js b/src/workspace.js index f567e83b4..7100e21d0 100644 --- a/src/workspace.js +++ b/src/workspace.js @@ -34,8 +34,10 @@ const WorkspaceCenter = require('./workspace-center') // // ### Required Methods // -// #### `getTitle()` Returns the title of the item to display on its associated -// #### tab. +// #### `getTitle()` +// +// Returns a {String} containing the title of the item to display on its +// associated tab. // // ### Optional Methods // @@ -67,6 +69,27 @@ const WorkspaceCenter = require('./workspace-center') // // Returns the URI associated with the item. // +// #### `getLongTitle()` +// +// Returns a {String} containing a longer version of the title to display in +// places like the window title or on tabs their short titles are ambiguous. +// +// #### `onDidChangeTitle` +// +// Called by the workspace so it can be notified when the item's title changes. +// Must return a {Disposable}. +// +// #### `getIconName()` +// +// Return a {String} with the name of an icon. If this method is defined and +// returns a string, the item's tab element will be rendered with the `icon` and +// `icon-${iconName}` CSS classes. +// +// ### `onDidChangeIcon(callback)` +// +// Called by the workspace so it can be notified when the item's icon changes. +// Must return a {Disposable}. +// // #### `getDefaultLocation()` // // Tells the workspace where your item should be opened in absence of a user @@ -122,6 +145,22 @@ const WorkspaceCenter = require('./workspace-center') // Create a copy of the item. If defined, the workspace will call this method to // duplicate the item when splitting panes via certain split commands. // +// #### `getPreferredInitialHeight()` +// +// If this item is displayed in the bottom {Dock}, called by the workspace when +// initially displaying the dock to set its height. Once the dock has been +// resized by the user, their height will override this value. +// +// Returns a {Number}. +// +// #### `getPreferredInitialWidth()` +// +// If this item is displayed in the left or right {Dock}, called by the +// workspace when initially displaying the dock to set its width. Once the dock +// has been resized by the user, their width will override this value. +// +// Returns a {Number}. +// // #### `onDidTerminatePendingState(callback)` // // If the workspace is configured to use *pending pane items*, the workspace From b7478e410f5f3219ae3970611be1cb0223f7fa91 Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Wed, 5 Apr 2017 14:55:49 -0600 Subject: [PATCH 4/4] Update docs for renamed methods in workspace item interface --- src/workspace.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/workspace.js b/src/workspace.js index 7100e21d0..f3dc04ff7 100644 --- a/src/workspace.js +++ b/src/workspace.js @@ -145,7 +145,7 @@ const WorkspaceCenter = require('./workspace-center') // Create a copy of the item. If defined, the workspace will call this method to // duplicate the item when splitting panes via certain split commands. // -// #### `getPreferredInitialHeight()` +// #### `getPreferredHeight()` // // If this item is displayed in the bottom {Dock}, called by the workspace when // initially displaying the dock to set its height. Once the dock has been @@ -153,7 +153,7 @@ const WorkspaceCenter = require('./workspace-center') // // Returns a {Number}. // -// #### `getPreferredInitialWidth()` +// #### `getPreferredWidth()` // // If this item is displayed in the left or right {Dock}, called by the // workspace when initially displaying the dock to set its width. Once the dock