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.
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:
getTitle()
Invoke the given callback with all current and future text editors in the workspace.
Argument | Description |
---|---|
|
Function to be called with current and future text editors. |
|
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 |
Invoke the given callback with all current and future panes items in the workspace.
Argument | Description |
---|---|
|
Function to be called with current and future pane items. |
|
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 |
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 |
---|---|
|
Function to be called when the active pane item changes. |
|
The active pane item. |
Return values |
---|
Returns a Disposable on which |
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 |
---|---|
|
Function to be called when the active pane item stops changing. |
|
The active pane item. |
Return values |
---|
Returns a Disposable on which |
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 |
---|---|
|
Function to be called when the active text editor changes. |
|
The active TextEditor or undefined if there is no longer an active text editor. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback with the current active pane item and with all future active pane items in the workspace.
Argument | Description |
---|---|
|
Function to be called when the active pane item changes. |
|
The current active pane item. |
Return values |
---|
Returns a Disposable on which |
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 |
---|---|
|
Function to be called when the active text editor changes. |
|
The active TextEditor or undefined if there is not an active text editor. |
Return values |
---|
Returns a Disposable on which |
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 |
---|---|
|
Function to be called whenever an item is opened. |
|
Object with the following keys: |
|
String representing the opened URI. Could be |
|
The opened item. |
|
The pane in which the item was opened. |
|
The index of the opened item on its pane. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback when a pane is added to the workspace.
Argument | Description |
---|---|
|
Function to be called panes are added. |
|
Object with the following keys: |
|
The added pane. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback before a pane is destroyed in the workspace.
Argument | Description |
---|---|
|
Function to be called before panes are destroyed. |
|
Object with the following keys: |
|
The pane to be destroyed. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback when a pane is destroyed in the workspace.
Argument | Description |
---|---|
|
Function to be called panes are destroyed. |
|
Object with the following keys: |
|
The destroyed pane. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback with all current and future panes in the workspace.
Argument | Description |
---|---|
|
Function to be called with current and future panes. |
|
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 |
Invoke the given callback when the active pane changes.
Argument | Description |
---|---|
|
Function to be called when the active pane changes. |
|
A Pane that is the current return value of ::getActivePane. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback with the current active pane and when the active pane changes.
Argument | Description |
---|---|
|
Function to be called with the current and future active# panes. |
|
A Pane that is the current return value of ::getActivePane. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback when a pane item is added to the workspace.
Argument | Description |
---|---|
|
Function to be called when pane items are added. |
|
Object with the following keys: |
|
The added pane item. |
|
Pane containing the added item. |
|
Number indicating the index of the added item in its pane. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback when a pane item is about to be destroyed, before the user is prompted to save it.
Argument | Description |
---|---|
|
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. |
|
Object with the following keys: |
|
The item to be destroyed. |
|
Pane containing the item to be destroyed. |
|
Number indicating the index of the item to be destroyed in its pane. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback when a pane item is destroyed.
Argument | Description |
---|---|
|
Function to be called when pane items are destroyed. |
|
Object with the following keys: |
|
The destroyed item. |
|
Pane containing the destroyed item. |
|
Number indicating the index of the destroyed item in its pane. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback when a text editor is added to the workspace.
Argument | Description |
---|---|
|
Function to be called panes are added. |
|
Object with the following keys: |
|
TextEditor that was added. |
|
Pane containing the added text editor. |
|
Number indicating the index of the added text editor in its pane. |
Return values |
---|
Returns a Disposable on which |
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 |
---|---|
|
optional
A String containing a URI. |
|
optional |
|
A Number indicating which row to move the cursor to initially. Defaults to |
|
A Number indicating which column to move the cursor to initially. Defaults to |
|
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. |
|
A Boolean indicating whether to call Pane::activate on containing pane. Defaults to |
|
A Boolean indicating whether to call Pane::activateItem on containing pane. Defaults to |
|
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. |
|
A Boolean. If |
|
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. |
Search the workspace for items matching the given URI. If any are found, hide them. Otherwise, open the URL.
Argument | Description |
---|---|
|
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. |
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 |
---|---|
|
A String containing a URI. |
Return values |
---|
Returns a Promise that resolves to the TextEditor (or other item) for the given URI. |
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 |
Register an opener for a uri.
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 |
---|---|
|
A Function to be called when a path is being opened. |
Return values |
---|
Returns a Disposable on which 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 |
Get the workspace center’s active item if it is a TextEditor.
Return values |
---|
Returns a TextEditor or |
This section only has Extended methods.
Make the next pane active.
Make the previous pane active.
Get the first pane container that contains an item with the given URI.
Argument | Description |
---|---|
|
String uri |
Return values |
---|
Returns a Dock, the WorkspaceCenter, or |
Get the first pane container that contains the given item.
Argument | Description |
---|---|
|
the Item that the returned pane container must contain. |
Return values |
---|
Returns a Dock, the WorkspaceCenter, or |
Get the WorkspaceCenter at the center of the editor window.
Get the Dock to the left of the editor window.
Get the Dock to the right of the editor window.
Get the Dock below the editor window.
Get an Array of all the panel items at the bottom of the editor window.
Adds a panel item to the bottom of the editor window.
Argument | Description |
---|---|
|
|
|
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. |
|
optional
Boolean false if you want the panel to initially be hidden (default: true) |
|
optional
Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100) |
Return values |
---|
Returns a Panel |
Get an Array of all the panel items to the left of the editor window.
Adds a panel item to the left of the editor window.
Argument | Description |
---|---|
|
|
|
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. |
|
optional
Boolean false if you want the panel to initially be hidden (default: true) |
|
optional
Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100) |
Return values |
---|
Returns a Panel |
Get an Array of all the panel items to the right of the editor window.
Adds a panel item to the right of the editor window.
Argument | Description |
---|---|
|
|
|
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. |
|
optional
Boolean false if you want the panel to initially be hidden (default: true) |
|
optional
Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100) |
Return values |
---|
Returns a Panel |
Get an Array of all the panel items at the top of the editor window.
Adds a panel item to the top of the editor window above the tabs.
Argument | Description |
---|---|
|
|
|
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. |
|
optional
Boolean false if you want the panel to initially be hidden (default: true) |
|
optional
Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100) |
Return values |
---|
Returns a Panel |
Get an Array of all the panel items in the header.
Adds a panel item to the header.
Argument | Description |
---|---|
|
|
|
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. |
|
optional
Boolean false if you want the panel to initially be hidden (default: true) |
|
optional
Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100) |
Return values |
---|
Returns a Panel |
Get an Array of all the panel items in the footer.
Adds a panel item to the footer.
Argument | Description |
---|---|
|
|
|
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. |
|
optional
Boolean false if you want the panel to initially be hidden (default: true) |
|
optional
Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100) |
Return values |
---|
Returns a Panel |
Get an Array of all the modal panel items
Adds a panel item as a modal dialog.
Argument | Description |
---|---|
|
|
|
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. |
|
optional
Boolean false if you want the panel to initially be hidden (default: true) |
|
optional
Number Determines stacking order. Lower priority items are forced closer to the edges of the window. (default: 100) |
|
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 |
Argument | Description |
---|---|
|
Item the panel contains |
Return values |
---|
Returns the Panel associated with the given item. |
Returns
|
Performs a search across all files in the workspace.
Argument | Description |
---|---|
|
RegExp to search with. |
|
optional |
|
An Array of glob patterns to search within. |
|
optional
Function to be periodically called with number of paths searched. |
|
Number default |
|
Number default |
|
Function callback on each file found. |
Return values |
---|
Returns a Promise with a |
Performs a replace across all the specified files in the project.
Argument | Description |
---|---|
|
A RegExp to search with. |
|
String to replace all matches of regex with. |
|
An Array of file path strings to run the replace on. |
|
A Function callback on each file with replacements: |
|
Object with keys |
Return values |
---|
Returns a Promise. |