Pane

Description

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.

API documentation

Event Subscription

::onDidChangeFlexScale(callback)

Invoke the given callback when the pane resizes.

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

Argument Description
callback

Function to be called when the pane is resized.
flexScale

Number representing the pane's 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 Pane::getFlexScale.

Argument Description
callback

Function to be called with the current and future values of the Pane::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 Pane::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 Pane::isActive property changes.

Argument Description
callback

Function to be called when the value of the Pane::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 Pane::isActive property.

Argument Description
callback

Function to be called with the current and future values of the Pane::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 Pane::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 Pane::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.

::onChooseNextMRUItem(callback)

Invoke the given callback when Pane::activateNextRecentlyUsedItem has been called, either initiating or continuing a forward MRU traversal of pane items.

Argument Description
callback

Function to be called with when the active item changes.
nextRecentlyUsedItem

The next MRU item, now being set active
Return values

  • Returns a Disposable on which .dispose() can be called to unsubscribe.

::onChooseLastMRUItem(callback)

Invoke the given callback when Pane::activatePreviousRecentlyUsedItem has been called, either initiating or continuing a reverse MRU traversal of pane items.

Argument Description
callback

Function to be called with when the active item changes.
previousRecentlyUsedItem

The previous MRU item, now being set active
Return values

  • Returns a Disposable on which .dispose() can be called to unsubscribe.

::onDoneChoosingMRUItem(callback)

Invoke the given callback when Pane::moveActiveItemToTopOfStack has been called, terminating an MRU traversal of pane items and moving the current active item to the top of the stack. Typically bound to a modifier (e.g. CTRL) key up event.

Argument Description
callback

Function to be called with when the MRU traversal is done.
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 Pane::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.

::activateNextRecentlyUsedItem()

Makes the next item in the itemStack active.

::activatePreviousRecentlyUsedItem()

Makes the previous item in the itemStack active.

::moveActiveItemToTopOfStack()

Moves the active item to the end of the item stack once a modifier key (typically Ctrl) is lifted.

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

::activateItemAtIndex(index)

Activate the item at the given index.

Argument Description
index

Number

::activateItem(item, options)

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

Argument Description
item

The item to activate
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.

Return values

  • Returns a Promise that resolves when the item is destroyed.

::destroyItem(item, force)

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.

This action can be prevented by onWillDestroyPaneItem callbacks in which case nothing happens.

Argument Description
item

Item to destroy
force optional

Boolean Destroy the item without prompting to save it, even if the item's isPermanentDockItem method returns true.
Return values

  • Returns a Promise that resolves with a Boolean indicating whether or not the item was destroyed.

::destroyItems()

Destroy all items.

::destroyInactiveItems()

Destroy all items except for the active item.

::saveActiveItem()

Save the active item.

::saveActiveItemAs(nextAction)

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

Argument Description
nextAction optional

Function which will be called after the item is successfully saved.
Return values

  • Returns a Promise that resolves when the save is complete

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

  • Returns a Promise that resolves when the save is complete

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

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

::isDestroyed()

Determine whether this pane has been destroyed.

Return values

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.