Chapter 1: Getting Started

Chapter 2: Using Atom

Chapter 3: Hacking Atom

Chapter 4: Behind Atom

Reference: API

Appendix A: Resources

Glossary

Appendix B: FAQ

Appendix C: Shadow DOM

Removing Shadow DOM styles

Appendix D: Upgrading to 1.0 APIs

Appendix E: Atom server-side APIs

mac

windows

linux

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.

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

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

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

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

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

Panes

This section only has Extended methods.

Extended Methods

::getPanes()

Get all panes in the workspace.

Return values
Returns an Array of Panes.

::getActivePane()

Get the active Pane.

Return values
Returns a Pane.

::activateNextPane()

Make the next pane active.

::activatePreviousPane()

Make the previous pane active.

::paneForURI(uri)

Get the first Pane with an item for the given URI.

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.

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

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

Searching and Replacing

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