Workspace

::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`	An TextEditor that is present in Workspace::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 Workspace::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.

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.

::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.

::onDidOpen(callback)

Invoke the given callback whenever an item is opened. Unlike Workspace::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.

::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.

::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 Workspace::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 Workspace::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 Workspace::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.
`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.

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' or 'right'. 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.
`activatePane`	A Boolean indicating whether to call Pane::activate on containing pane. Defaults to `true`.
`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`.

Return values

Returns a promise that resolves to the TextEditor for the file URI.

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

Register an opener for a uri.

An TextEditor will be used if no openers return a value.

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

Return values

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

::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 active item if it is an TextEditor.

Return values

Returns an TextEditor or `` if the current active item is not an TextEditor.

::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 Pane or `` if no pane exists for the given URI.

::paneForItem(item)

Get the Pane containing the given item.

Argument	Description
`item`	Item the returned pane contains.

Return values

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

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

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

::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.

::scan(regex, options, iterator)

Performs a search across all the files in the workspace.

Argument	Description
`regex`	RegExp to search with.
`options`	optional Object (default: {})
`paths`	An Array of glob patterns to search within
`onPathsSearched`	optional Function
`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`	Text to replace all matches of regex with
`filePaths`	List 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

API documentation

Event Subscription

Opening

Pane Items

Panes

Panels

Searching and Replacing