Pane Extended

A container for presenting content in the center of the workspace. Panes can contain multiple items, one of which is active at a given time. The view corresponding to the active item is displayed in the interface. In the default configuration, tabs are also displayed for each item.

Each pane may also contain one pending item. When a pending item is added to a pane, it will replace the currently pending item, if any, instead of simply being added. In the default configuration, the text in the tab for pending items is shown in italics.

Event Subscription

::onDidChangeFlexScale(callback)

Invoke the given callback when the pane resizes

The callback will be invoked when pane’s flexScale property changes. Use ::getFlexScale to get the current value.

Argument	Description
`callback`	Function to be called when the pane is resized
`flexScale`	Number representing the panes `flex-grow`; ability for a flex item to grow if necessary.

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

::observeFlexScale(callback)

Invoke the given callback with the current and future values of ::getFlexScale.

Argument	Description
`callback`	Function to be called with the current and future values of the ::getFlexScale property.
`flexScale`	Number representing the panes `flex-grow`; ability for a flex item to grow if necessary.

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

::onDidActivate(callback)

Invoke the given callback when the pane is activated.

The given callback will be invoked whenever ::activate is called on the pane, even if it is already active at the time.

Argument	Description
`callback`	Function to be called when the pane is activated.

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

::onWillDestroy(callback)

Invoke the given callback before the pane is destroyed.

Argument	Description
`callback`	Function to be called before the pane is destroyed.

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

::onDidDestroy(callback)

Invoke the given callback when the pane is destroyed.

Argument	Description
`callback`	Function to be called when the pane is destroyed.

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

::onDidChangeActive(callback)

Invoke the given callback when the value of the ::isActive property changes.

Argument	Description
`callback`	Function to be called when the value of the ::isActive property changes.
`active`	Boolean indicating whether the pane is active.

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

::observeActive(callback)

Invoke the given callback with the current and future values of the ::isActive property.

Argument	Description
`callback`	Function to be called with the current and future values of the ::isActive property.
`active`	Boolean indicating whether the pane is active.

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

::onDidAddItem(callback)

Invoke the given callback when an item is added to the pane.

Argument	Description
`callback`	Function to be called with when items are added.
`event`	Object with the following keys:
`item`	The added pane item.
`index`	Number indicating where the item is located.

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

::onDidRemoveItem(callback)

Invoke the given callback when an item is removed from the pane.

Argument	Description
`callback`	Function to be called with when items are removed.
`event`	Object with the following keys:
`item`	The removed pane item.
`index`	Number indicating where the item was located.

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

::onWillRemoveItem(callback)

Invoke the given callback before an item is removed from the pane.

Argument	Description
`callback`	Function to be called with when items are removed.
`event`	Object with the following keys:
`item`	The pane item to be removed.
`index`	Number indicating where the item is located.

::onDidMoveItem(callback)

Invoke the given callback when an item is moved within the pane.

Argument	Description
`callback`	Function to be called with when items are moved.
`event`	Object with the following keys:
`item`	The removed pane item.
`oldIndex`	Number indicating where the item was located.
`newIndex`	Number indicating where the item is now located.

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

::observeItems(callback)

Invoke the given callback with all current and future items.

Argument	Description
`callback`	Function to be called with current and future items.
`item`	An item that is present in ::getItems 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.

::onDidChangeActiveItem(callback)

Invoke the given callback when the value of ::getActiveItem changes.

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

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

::observeActiveItem(callback)

Invoke the given callback with the current and future values of ::getActiveItem.

Argument	Description
`callback`	Function to be called with the current and future active items.
`activeItem`	The current active item.

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

::onWillDestroyItem(callback)

Invoke the given callback before items are destroyed.

Argument	Description
`callback`	Function to be called before items are destroyed.
`event`	Object with the following keys:
`item`	The item that will be destroyed.
`index`	The location of the item.

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

Items

::getItems()

Get the items in this pane.

Return values
Returns an Array of items.

::getActiveItem()

Get the active pane item in this pane.

Return values
Returns a pane item.

::itemAtIndex(index)

Return the item at the given index.

Argument	Description
`index`	Number

Return values
Returns an item or `null` if no item exists at the given index.

::activateNextItem()

Makes the next item active.

::activatePreviousItem()

Makes the previous item active.

::moveItemRight()

Move the active tab to the right.

::moveItemLeft()

Move the active tab to the left

::getActiveItemIndex()

Get the index of the active item.

Return values
Returns a Number.

::activateItemAtIndex(index)

Activate the item at the given index.

Argument	Description
`index`	Number

::activateItem(options)

Make the given item active, causing it to be displayed by the pane’s view.

Argument	Description
`options`	optional Object
`pending`	optional Boolean indicating that the item should be added in a pending state if it does not yet exist in the pane. Existing pending items in a pane are replaced with new pending items when they are opened.

::addItem(item, options)

Add the given item to the pane.

Argument	Description
`item`	The item to add. It can be a model with an associated view or a view.
`options`	optional Object
`index`	optional Number indicating the index at which to add the item. If omitted, the item is added after the current active item.
`pending`	optional Boolean indicating that the item should be added in a pending state. Existing pending items in a pane are replaced with new pending items when they are opened.

Return values
Returns the added item.

::addItems(items, index)

Add the given items to the pane.

Argument	Description
`items`	An Array of items to add. Items can be views or models with associated views. Any objects that are already present in the pane’s current items will not be added again.
`index`	optional Number index at which to add the items. If omitted, the item is # added after the current active item.

Return values
Returns an Array of added items.

::moveItem(item, index)

Move the given item to the given index.

Argument	Description
`item`	The item to move.
`index`	Number indicating the index to which to move the item.

::moveItemToPane(item, pane, index)

Move the given item to the given index on another pane.

Argument	Description
`item`	The item to move.
`pane`	Pane to which to move the item.
`index`	Number indicating the index to which to move the item in the given pane.

::destroyActiveItem()

Destroy the active item and activate the next item.

::destroyItem(item)

Destroy the given item.

If the item is active, the next item will be activated. If the item is the last item, the pane will be destroyed if the core.destroyEmptyPanes config setting is true.

Argument	Description
`item`	Item to destroy

Argument	Description
`nextAction`	optional Function which will be called after the item is successfully saved.

::saveItem(item, nextAction)

Save the given item.

Argument	Description
`item`	The item to save.
`nextAction`	optional Function which will be called with no argument after the item is successfully saved, or with the error if it failed. The return value will be that of `nextAction` or `undefined` if it was not provided

::saveItemAs(item, nextAction)

Prompt the user for a location and save the active item with the path they select.

Argument	Description
`item`	The item to save.
`nextAction`	optional Function which will be called with no argument after the item is successfully saved, or with the error if it failed. The return value will be that of `nextAction` or `undefined` if it was not provided

::saveItems()

Save all items.

::itemForURI(uri)

Return the first item that matches the given URI or undefined if none exists.

Argument	Description
`uri`	String containing a URI.

::activateItemForURI(uri)

Activate the first item that matches the given URI.

Argument	Description
`uri`	String containing a URI.

Return values
Returns a Boolean indicating whether an item matching the URI was found.

Lifecycle

::isActive()

Determine whether the pane is active.

Return values
Returns a Boolean.

::activate()

Makes this pane the active pane, causing it to gain focus.

::destroy()

Close the pane and destroy all its items.

If this is the last pane, all the items will be destroyed but the pane itself will not be destroyed.

Splitting

::splitLeft(params)

Create a new pane to the left of this pane.

Argument	Description
`params`	optional Object with the following keys:
`items`	optional Array of items to add to the new pane.
`copyActiveItem`	optional Boolean true will copy the active item into the new split pane

Return values
Returns the new Pane.

::splitRight(params)

Create a new pane to the right of this pane.

Argument	Description
`params`	optional Object with the following keys:
`items`	optional Array of items to add to the new pane.
`copyActiveItem`	optional Boolean true will copy the active item into the new split pane

Return values
Returns the new Pane.

::splitUp(params)

Creates a new pane above the receiver.

Argument	Description
`params`	optional Object with the following keys:
`items`	optional Array of items to add to the new pane.
`copyActiveItem`	optional Boolean true will copy the active item into the new split pane

Return values
Returns the new Pane.

::splitDown(params)

Creates a new pane below the receiver.

Argument	Description
`params`	optional Object with the following keys:
`items`	optional Array of items to add to the new pane.
`copyActiveItem`	optional Boolean true will copy the active item into the new split pane

Return values
Returns the new Pane.