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()`

Returns a String containing 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(callback)`

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.

`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(callback)`

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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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 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 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()`

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.

`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 resized by the user, their height will override this value.

Returns a Number.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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

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. 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. To defer your package’s activation until a specific URL is opened, add a `workspaceOpeners` field to your `package.json` containing an array of URL strings.

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.

To defer your package’s activation until a specific URL is opened, add a workspaceOpeners field to your package.json containing an array of URL strings.

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.

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

Workspace Essential

Workspace Items

Required Methods

getTitle()

Optional Methods

getElement()

destroy()

onDidDestroy(callback)

serialize()

getURI()

getLongTitle()

onDidChangeTitle(callback)

getIconName()

onDidChangeIcon(callback)

getDefaultLocation()

getAllowedLocations()

isPermanentDockItem()

save()

saveAs(path)

getPath()

isModified()

onDidChangeModified()

copy()

getPreferredHeight()

getPreferredWidth()

onDidTerminatePendingState(callback)

shouldPromptToSave()

Event Subscription

Extended Methods

Opening

Extended Methods

Pane Items

Panes

Extended Methods

Pane Locations

Panels

Searching and Replacing

`getTitle()`

`getElement()`

`destroy()`

`onDidDestroy(callback)`

`serialize()`

`getURI()`

`getLongTitle()`

`onDidChangeTitle(callback)`

`getIconName()`

`onDidChangeIcon(callback)`

`getDefaultLocation()`

`getAllowedLocations()`

`isPermanentDockItem()`

`save()`

`saveAs(path)`

`getPath()`

`isModified()`

`onDidChangeModified()`

`copy()`

`getPreferredHeight()`

`getPreferredWidth()`

`onDidTerminatePendingState(callback)`

`shouldPromptToSave()`