Workspace Essential

Represents the state of the user interface for the entire window. An instance of this class is available via the atom.workspace global.

Interact with this object to open files, be notified of current and future editors, and manipulate panes. To add panels, use Workspace::addTopPanel and friends.

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 Docks. The workspace expects items to conform to the following interface:

Required Methods

`getTitle()`

Event Subscription

::observeTextEditors(callback)

Invoke the given callback with all current and future text editors in the workspace.

Argument	Description
`callback`	Function to be called with current and future text editors.
`editor`	A TextEditor that is present in ::getTextEditors at the time of subscription or that is added at some later time.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::observePaneItems(callback)

Invoke the given callback with all current and future panes items in the workspace.

Argument	Description
`callback`	Function to be called with current and future pane items.
`item`	An item that is present in ::getPaneItems at the time of subscription or that is added at some later time.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangeActivePaneItem(callback)

Invoke the given callback when the active pane item changes.

Because observers are invoked synchronously, it’s important not to perform any expensive operations via this method. Consider ::onDidStopChangingActivePaneItem to delay operations until after changes stop occurring.

Argument	Description
`callback`	Function to be called when the active pane item changes.
`item`	The active pane item.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidStopChangingActivePaneItem(callback)

Invoke the given callback when the active pane item stops changing.

Observers are called asynchronously 100ms after the last active pane item change. Handling changes here rather than in the synchronous ::onDidChangeActivePaneItem prevents unneeded work if the user is quickly changing or closing tabs and ensures critical UI feedback, like changing the highlighted tab, gets priority over work that can be done asynchronously.

Argument	Description
`callback`	Function to be called when the active pane item stops changing.
`item`	The active pane item.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangeActiveTextEditor(callback)

Invoke the given callback when a text editor becomes the active text editor and when there is no longer an active text editor.

Argument	Description
`callback`	Function to be called when the active text editor changes.
`editor`	The active TextEditor or undefined if there is no longer an active text editor.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::observeActivePaneItem(callback)

Invoke the given callback with the current active pane item and with all future active pane items in the workspace.

Argument	Description
`callback`	Function to be called when the active pane item changes.
`item`	The current active pane item.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::observeActiveTextEditor(callback)

Invoke the given callback with the current active text editor (if any), with all future active text editors, and when there is no longer an active text editor.

Argument	Description
`callback`	Function to be called when the active text editor changes.
`editor`	The active TextEditor or undefined if there is not an active text editor.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidOpen(callback)

Invoke the given callback whenever an item is opened. Unlike ::onDidAddPaneItem, observers will be notified for items that are already present in the workspace when they are reopened.

Argument	Description
`callback`	Function to be called whenever an item is opened.
`event`	Object with the following keys:
`uri`	String representing the opened URI. Could be `undefined`.
`item`	The opened item.
`pane`	The pane in which the item was opened.
`index`	The index of the opened item on its pane.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

Extended Methods

::onDidAddPane(callback)

Invoke the given callback when a pane is added to the workspace.

Argument	Description
`callback`	Function to be called panes are added.
`event`	Object with the following keys:
`pane`	The added pane.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onWillDestroyPane(callback)

Invoke the given callback before a pane is destroyed in the workspace.

Argument	Description
`callback`	Function to be called before panes are destroyed.
`event`	Object with the following keys:
`pane`	The pane to be destroyed.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidDestroyPane(callback)

Invoke the given callback when a pane is destroyed in the workspace.

Argument	Description
`callback`	Function to be called panes are destroyed.
`event`	Object with the following keys:
`pane`	The destroyed pane.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::observePanes(callback)

Invoke the given callback with all current and future panes in the workspace.

Argument	Description
`callback`	Function to be called with current and future panes.
`pane`	A Pane that is present in ::getPanes at the time of subscription or that is added at some later time.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangeActivePane(callback)

Invoke the given callback when the active pane changes.

Argument	Description
`callback`	Function to be called when the active pane changes.
`pane`	A Pane that is the current return value of ::getActivePane.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::observeActivePane(callback)

Invoke the given callback with the current active pane and when the active pane changes.

Argument	Description
`callback`	Function to be called with the current and future active# panes.
`pane`	A Pane that is the current return value of ::getActivePane.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidAddPaneItem(callback)

Invoke the given callback when a pane item is added to the workspace.

Argument	Description
`callback`	Function to be called when pane items are added.
`event`	Object with the following keys:
`item`	The added pane item.
`pane`	Pane containing the added item.
`index`	Number indicating the index of the added item in its pane.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onWillDestroyPaneItem(callback)

Invoke the given callback when a pane item is about to be destroyed, before the user is prompted to save it.

Argument	Description
`callback`	Function to be called before pane items are destroyed. If this function returns a Promise, then the item will not be destroyed until the promise resolves.
`event`	Object with the following keys:
`item`	The item to be destroyed.
`pane`	Pane containing the item to be destroyed.
`index`	Number indicating the index of the item to be destroyed in its pane.

Return values
Returns a Disposable on which `.dispose` can be called to unsubscribe.

::onDidDestroyPaneItem(callback)

Invoke the given callback when a pane item is destroyed.

Argument	Description
`callback`	Function to be called when pane items are destroyed.
`event`	Object with the following keys:
`item`	The destroyed item.
`pane`	Pane containing the destroyed item.
`index`	Number indicating the index of the destroyed item in its pane.

Return values
Returns a Disposable on which `.dispose` can be called to unsubscribe.

::onDidAddTextEditor(callback)

Invoke the given callback when a text editor is added to the workspace.

Argument	Description
`callback`	Function to be called panes are added.
`event`	Object with the following keys:
`textEditor`	TextEditor that was added.
`pane`	Pane containing the added text editor.
`index`	Number indicating the index of the added text editor in its pane.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

Opening

::open(uri, options)

Opens the given URI in Atom asynchronously. If the URI is already open, the existing item for that URI will be activated. If no URI is given, or no registered opener can open the URI, a new empty TextEditor will be created.

Argument	Description
`uri`	optional A String containing a URI.
`options`	optional Object
`initialLine`	A Number indicating which row to move the cursor to initially. Defaults to `0`.
`initialColumn`	A Number indicating which column to move the cursor to initially. Defaults to `0`.
`split`	Either ‘left’, ‘right’, ‘up’ or ‘down’. If ‘left’, the item will be opened in leftmost pane of the current active pane’s row. If ‘right’, the item will be opened in the rightmost pane of the current active pane’s row. If only one pane exists in the row, a new pane will be created. If ‘up’, the item will be opened in topmost pane of the current active pane’s column. If ‘down’, the item will be opened in the bottommost pane of the current active pane’s column. If only one pane exists in the column, a new pane will be created.
`activatePane`	A Boolean indicating whether to call Pane::activate on containing pane. Defaults to `true`.
`activateItem`	A Boolean indicating whether to call Pane::activateItem on containing pane. Defaults to `true`.
`pending`	A Boolean indicating whether or not the item should be opened in a pending state. Existing pending items in a pane are replaced with new pending items when they are opened.
`searchAllPanes`	A Boolean. If `true`, the workspace will attempt to activate an existing item for the given URI on any pane. If `false`, only the active pane will be searched for an existing item for the same URI. Defaults to `false`.
`location`	optional A String containing the name of the location in which this item should be opened (one of “left”, “right”, “bottom”, or “center”). If omitted, Atom will fall back to the last location in which a user has placed an item with the same URI or, if this is a new URI, the default location specified by the item. NOTE: This option should almost always be omitted to honor user preference.

Return values
Returns a Promise that resolves to the TextEditor for the file URI.

::hide(itemOrURI)

Search the workspace for items matching the given URI and hide them.

Argument	Description
`itemOrURI`	The item to hide or a String containing the URI of the item to hide.

Return values
Returns a Boolean indicating whether any items were found (and hidden).

::toggle(itemOrURI)

Search the workspace for items matching the given URI. If any are found, hide them. Otherwise, open the URL.

Argument	Description
`itemOrURI`	optional The item to toggle or a String containing the URI of the item to toggle.

Return values
Returns a Promise that resolves when the item is shown or hidden.

::createItemForURI(uri)

Creates a new item that corresponds to the provided URI.

If no URI is given, or no registered opener can open the URI, a new empty TextEditor will be created.

Argument	Description
`uri`	A String containing a URI.

Return values
Returns a Promise that resolves to the TextEditor (or other item) for the given URI.

::isTextEditor(object)

Argument	Description
`object`	An Object you want to perform the check against.

Return values
Returns a Boolean that is `true` if `object` is a `TextEditor`.

::reopenItem()

Asynchronously reopens the last-closed item’s URI if it hasn’t already been reopened.

Return values
Returns a Promise that is resolved when the item is opened

::addOpener(opener)

When a URI is opened via Workspace::open, Atom loops through its registered opener functions until one returns a value for the given uri. Openers are expected to return an object that inherits from HTMLElement or a model which has an associated view in the ViewRegistry. A TextEditor will be used if no opener returns a value.

Argument	Description
`opener`	A Function to be called when a path is being opened.

Return values

Return values
Returns a Disposable on which `.dispose()` can be called to remove the opener. Note that the opener will be called if and only if the URI is not already open in the current pane. The searchAllPanes flag expands the search from the current pane to all panes. If you wish to open a view of a different type for a file that is already open, consider changing the protocol of the URI. For example, perhaps you wish to preview a rendered version of the file `/foo/bar/baz.quux` that is already open in a text editor view. You could signal this by calling Workspace::open on the URI `quux-preview://foo/bar/baz.quux`. Then your opener can check the protocol for quux-preview and only handle those URIs that match.

Returns a Disposable on which .dispose() can be called to remove the opener.

Note that the opener will be called if and only if the URI is not already open in the current pane. The searchAllPanes flag expands the search from the current pane to all panes. If you wish to open a view of a different type for a file that is already open, consider changing the protocol of the URI. For example, perhaps you wish to preview a rendered version of the file /foo/bar/baz.quux that is already open in a text editor view. You could signal this by calling Workspace::open on the URI quux-preview://foo/bar/baz.quux. Then your opener can check the protocol for quux-preview and only handle those URIs that match.

Extended Methods

::buildTextEditor()

Create a new text editor.

Return values
Returns a TextEditor.

Pane Items

::getPaneItems()

Get all pane items in the workspace.

Return values
Returns an Array of items.

::getActivePaneItem()

Get the active Pane’s active item.

Return values
Returns an pane item Object.

::getTextEditors()

Get all text editors in the workspace.

Return values
Returns an Array of TextEditors.

::getActiveTextEditor()

Get the workspace center’s active item if it is a TextEditor.

Return values
Returns a TextEditor or `undefined` if the workspace center’s current active item is not a TextEditor.

Panes

This section only has Extended methods.

Extended Methods

::getActivePaneContainer()

Get the most recently focused pane container.

Return values
Returns a Dock or the WorkspaceCenter.

::getPanes()

Get all panes in the workspace.

Return values
Returns an Array of Panes.

::getActivePane()

Get the active Pane.

Return values
Returns a Pane.

Argument	Description
`uri`	String uri

Return values
Returns a Dock, the WorkspaceCenter, or `undefined` if no item exists with the given URI.

::paneContainerForItem(item)

Get the first pane container that contains the given item.

Argument	Description
`item`	the Item that the returned pane container must contain.

Return values
Returns a Dock, the WorkspaceCenter, or `undefined` if no item exists with the given URI.

::paneForURI(uri)

Get the first Pane that contains an item with the given URI.

Argument	Description
`uri`	String uri

Return values
Returns a Pane or `undefined` if no item exists with the given URI.

::paneForItem(item)

Get the Pane containing the given item.

Argument	Description
`item`	the Item that the returned pane must contain.

Return values
Returns a Pane or `undefined` if no pane exists for the given item.

Panels

::getBottomPanels()

Get an Array of all the panel items at the bottom of the editor window.

::addBottomPanel(options)

Adds a panel item to the bottom of the editor window.

Argument	Description
`options`	Object
`item`	Your panel content. It can be DOM element, a jQuery element, or a model with a view registered via ViewRegistry::addViewProvider. We recommend the latter. See ViewRegistry::addViewProvider for more information.
`visible`	optional Boolean false if you want the panel to initially be hidden (default: true)
`priority`	optional Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100)

Return values
Returns a Panel

::getLeftPanels()

Get an Array of all the panel items to the left of the editor window.

::addLeftPanel(options)

Adds a panel item to the left of the editor window.

Argument	Description
`options`	Object
`item`	Your panel content. It can be DOM element, a jQuery element, or a model with a view registered via ViewRegistry::addViewProvider. We recommend the latter. See ViewRegistry::addViewProvider for more information.
`visible`	optional Boolean false if you want the panel to initially be hidden (default: true)
`priority`	optional Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100)

Return values
Returns a Panel

::getRightPanels()

Get an Array of all the panel items to the right of the editor window.

::addRightPanel(options)

Adds a panel item to the right of the editor window.

Argument	Description
`options`	Object
`item`	Your panel content. It can be DOM element, a jQuery element, or a model with a view registered via ViewRegistry::addViewProvider. We recommend the latter. See ViewRegistry::addViewProvider for more information.
`visible`	optional Boolean false if you want the panel to initially be hidden (default: true)
`priority`	optional Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100)

Return values
Returns a Panel

::getTopPanels()

Get an Array of all the panel items at the top of the editor window.

::addTopPanel(options)

Adds a panel item to the top of the editor window above the tabs.

Argument	Description
`options`	Object
`item`	Your panel content. It can be DOM element, a jQuery element, or a model with a view registered via ViewRegistry::addViewProvider. We recommend the latter. See ViewRegistry::addViewProvider for more information.
`visible`	optional Boolean false if you want the panel to initially be hidden (default: true)
`priority`	optional Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100)

Return values
Returns a Panel

::getHeaderPanels()

Get an Array of all the panel items in the header.

::addHeaderPanel(options)

Adds a panel item to the header.

Argument	Description
`options`	Object
`item`	Your panel content. It can be DOM element, a jQuery element, or a model with a view registered via ViewRegistry::addViewProvider. We recommend the latter. See ViewRegistry::addViewProvider for more information.
`visible`	optional Boolean false if you want the panel to initially be hidden (default: true)
`priority`	optional Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100)

Return values
Returns a Panel

::getFooterPanels()

Get an Array of all the panel items in the footer.

::addFooterPanel(options)

Adds a panel item to the footer.

Argument	Description
`options`	Object
`item`	Your panel content. It can be DOM element, a jQuery element, or a model with a view registered via ViewRegistry::addViewProvider. We recommend the latter. See ViewRegistry::addViewProvider for more information.
`visible`	optional Boolean false if you want the panel to initially be hidden (default: true)
`priority`	optional Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100)

Return values
Returns a Panel

::getModalPanels()

Get an Array of all the modal panel items

::addModalPanel(options)

Adds a panel item as a modal dialog.

Argument	Description
`options`	Object
`item`	Your panel content. It can be a DOM element, a jQuery element, or a model with a view registered via ViewRegistry::addViewProvider. We recommend the model option. See ViewRegistry::addViewProvider for more information.
`visible`	optional Boolean false if you want the panel to initially be hidden (default: true)
`priority`	optional Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100)
`autoFocus`	optional Boolean true if you want modal focus managed for you by Atom. Atom will automatically focus your modal panel’s first tabbable element when the modal opens and will restore the previously selected element when the modal closes. Atom will also automatically restrict user tab focus within your modal while it is open. (default: false)

Return values
Returns a Panel

::panelForItem(item)

Argument	Description
`item`	Item the panel contains

Return values
Returns the Panel associated with the given item.
Returns `null` when the item has no panel.

Searching and Replacing

::scan(regex, options, iterator)

Performs a search across all files in the workspace.

Argument	Description
`regex`	RegExp to search with.
`options`	optional Object
`paths`	An Array of glob patterns to search within.
`onPathsSearched`	optional Function to be periodically called with number of paths searched.
`leadingContextLineCount`	Number default `0`; The number of lines before the matched line to include in the results object.
`trailingContextLineCount`	Number default `0`; The number of lines after the matched line to include in the results object.
`iterator`	Function callback on each file found.

Return values
Returns a Promise with a `cancel()` method that will cancel all of the underlying searches that were started as part of this scan.

::replace(regex, replacementText, filePaths, iterator)

Performs a replace across all the specified files in the project.

Argument	Description
`regex`	A RegExp to search with.
`replacementText`	String to replace all matches of regex with.
`filePaths`	An Array of file path strings to run the replace on.
`iterator`	A Function callback on each file with replacements:
`options`	Object with keys `filePath` and `replacements`.

Return values
Returns a Promise.

Workspace Essential

Workspace Items

Required Methods

getTitle()

Event Subscription

Extended Methods

Opening

Extended Methods

Pane Items

Panes

Extended Methods

Pane Locations

Panels

Searching and Replacing

`getTitle()`