Skip to main content

Pane

Import :​

const Pane = brackets.getModule("view/Pane")

Pane​

Kind: global class
See: MainViewManager for more information

new Pane(id, $container)​

Pane Objects are constructed by the MainViewManager object when a Pane view is needed.

ParamTypeDescription
idstringThe id to use to identify this pane.
$containerjQueryThe parent jQuery container to place the pane view.

pane.id : string​

id of the pane

Kind: instance property of Pane
Read only: true

pane.$container : JQuery​

container where the pane lives

Kind: instance property of Pane
Read only: true

pane.$el : JQuery​

the wrapped DOM node of this pane

Kind: instance property of Pane
Read only: true

pane.$header : JQuery​

the wrapped DOM node container that contains name of current view and the switch view button, or informational string if there is no view

Kind: instance property of Pane
Read only: true

pane.$headerText : JQuery​

the wrapped DOM node that contains name of current view, or informational string if there is no view

Kind: instance property of Pane
Read only: true

pane.$headerFlipViewBtn : JQuery​

the wrapped DOM node that is used to flip the view to another pane

Kind: instance property of Pane
Read only: true

pane.$headerCloseBtn : JQuery​

close button of the pane

Kind: instance property of Pane
Read only: true

pane.$content : JQuery​

the wrapped DOM node that contains views

Kind: instance property of Pane
Read only: true

pane.ITEM_NOT_FOUND​

Return value from reorderItem when the Item was not found

Kind: instance constant of Pane
See: reorderItem

pane.ITEM_FOUND_NO_SORT​

Return value from reorderItem when the Item was found at its natural index and the workingset does not need to be resorted

Kind: instance constant of Pane
See: reorderItem

pane.ITEM_FOUND_NEEDS_SORT​

Return value from reorderItem when the Item was found and reindexed and the workingset needs to be resorted

Kind: instance constant of Pane
See: reorderItem

pane.mergeFrom(other)​

Merges the another Pane object's contents into this Pane

Kind: instance method of Pane

ParamTypeDescription
otherPanePane from which to copy

pane.destroy()​

Removes the DOM node for the Pane, removes all event handlers and _resets all internal data structures

Kind: instance method of Pane

pane.getViewList() ⇒ Array.<File>​

Returns a copy of the view file list

Kind: instance method of Pane

pane.getViewListSize() ⇒ number​

Returns the number of entries in the view file list

Kind: instance method of Pane

pane.findInViewList(fullPath) ⇒ number​

Returns the index of the item in the view file list

Kind: instance method of Pane
Returns: number - index of the item or -1 if not found

ParamTypeDescription
fullPathstringthe full path of the item to look for

pane.findInViewListAddedOrder(fullPath) ⇒ number​

Returns the order in which the item was added

Kind: instance method of Pane
Returns: number - order of the item or -1 if not found

ParamTypeDescription
fullPathstringthe full path of the item to look for

pane.findInViewListMRUOrder(fullPath) ⇒ number​

Returns the order in which the item was last used

Kind: instance method of Pane
Returns: number - order of the item or -1 if not found. 0 indicates most recently used, followed by 1 and so on...

ParamTypeDescription
fullPathstringthe full path of the item to look for

pane.reorderItem(file, [index], [force]) ⇒ number​

reorders the specified file in the view list to the desired position

Kind: instance method of Pane
Returns: number - this function returns one of the following manifest constants: ITEM_NOT_FOUND : The request file object was not found ITEM_FOUND_NO_SORT : The request file object was found but it was already at the requested index ITEM_FOUND_NEEDS_SORT : The request file object was found and moved to a new index and the list should be resorted

ParamTypeDescription
fileFilethe file object of the item to reorder
[index]numberthe new position of the item
[force]booleantrue to force the item into that position, false otherwise. (Requires an index be requested)

pane.addToViewList(file, [index]) ⇒ number​

Adds the given file to the end of the workingset, if it is not already in the list Does not change which document is currently open in the editor. Completes synchronously.

Kind: instance method of Pane
Returns: number - index of where the item was added

ParamTypeDescription
fileFilefile to add
[index]numberposition where to add the item

pane.addListToViewList(fileList) ⇒ Array.<File>​

Adds the given file list to the end of the workingset.

Kind: instance method of Pane
Returns: Array.<File> - list of files added to the list

ParamType
fileListArray.<File>

pane.makeViewMostRecent(file)​

Moves the specified file to the front of the MRU (Most Recently Used) list.

Kind: instance method of Pane

ParamTypeDescription
fileFileThe file to move to the front of the MRU list.

pane.sortViewList(compareFn)​

Sorts items in the pane's view list.

Kind: instance method of Pane

ParamTypeDescription
compareFnfunctionThe function used to compare items in the view list.

pane.swapViewListIndexes(index1, index2) ⇒ boolean​

Swaps two items in the file view list (used while dragging items in the working set view)

Kind: instance method of Pane
Returns: boolean - } true

ParamTypeDescription
index1numberthe index of the first item to swap
index2numberthe index of the second item to swap

pane.traverseViewListByMRU(direction, [current]) ⇒ File​

Traverses the list and returns the File object of the next item in the MRU order

Kind: instance method of Pane
Returns: File - The File object of the next item in the travesal order or null if there isn't one.

ParamTypeDescription
directionnumberMust be 1 or -1 to traverse forward or backward
[current]stringthe fullPath of the item where traversal is to start. If this parameter is omitted then the path of the current view is used. If the current view is a temporary view then the first item in the MRU list is returned

pane.showInterstitial(show)​

Shows the pane's interstitial page

Kind: instance method of Pane

ParamTypeDescription
showbooleanshow or hide the interstitial page

pane.getViewForPath(path) ⇒ boolean​

retrieves the view object for the given path

Kind: instance method of Pane
Returns: boolean - show - show or hide the interstitial page

ParamTypeDescription
pathstringthe fullPath of the view to retrieve

pane.addView(view, show)​

Adds a view to the pane

Kind: instance method of Pane

ParamTypeDescription
viewViewthe View object to add
showbooleantrue to show the view right away, false otherwise

pane.showView(view)​

Swaps the current view with the requested view. If the interstitial page is shown, it is hidden. If the currentView is a temporary view, it is destroyed.

Kind: instance method of Pane

ParamTypeDescription
viewViewthe to show

pane.updateLayout(forceRefresh)​

Sets pane content height. Updates the layout causing the current view to redraw itself

Kind: instance method of Pane

ParamTypeDescription
forceRefreshbooleantrue to force a resize and refresh of the current view, false if just to resize forceRefresh is only used by Editor views to force a relayout of all editor DOM elements. Custom View implementations should just ignore this flag.

pane.getCurrentlyViewedFile() ⇒ File​

Retrieves the File object of the current view

Kind: instance method of Pane
Returns: File - the File object of the current view or null if there isn't one

pane.getCurrentlyViewedEditor() ⇒ File​

Retrieves the File object of the current view

Kind: instance method of Pane
Returns: File - the File object of the current view or null if there isn't one

pane.getCurrentlyViewedPath() ⇒ string​

Retrieves the path of the current view

Kind: instance method of Pane
Returns: string - the path of the current view or null if there isn't one

pane.destroyViewIfNotNeeded(view)​

destroys the view if it isn't needed

Kind: instance method of Pane

ParamTypeDescription
viewViewthe view to destroy

pane.removeView(file, suppressOpenNextFile, preventViewChange) ⇒ boolean​

Removes the view and opens the next view

Kind: instance method of Pane
Returns: boolean - true if the file was removed from the working set This function will remove a temporary view of a file but will return false in that case

ParamTypeDescription
fileFilethe file to close
suppressOpenNextFilebooleansuppresses opening the next file in MRU order
preventViewChangebooleanif suppressOpenNextFile is truthy, this flag can be used to prevent the current view from being destroyed. Ignored if suppressOpenNextFile is falsy

pane.removeViews(list) ⇒ Array.<File>​

Removes the specifed file from all internal lists, destroys the view of the file (if there is one) and shows the interstitial page if the current view is destroyed.

Kind: instance method of Pane
Returns: Array.<File> - Array of File objects removed from the working set. This function will remove temporary views but the file objects for those views will not be found in the result set. Only the file objects removed from the working set are returned.

ParamTypeDescription
listArray.<File>Array of files to remove

pane.focus()​

Gives focus to the last thing that had focus, the current view or the pane in that order

Kind: instance method of Pane

pane.loadState(state) ⇒ jQuery.Promise​

serializes the pane state from JSON

Kind: instance method of Pane
Returns: jQuery.Promise - A promise which resolves to {fullPath:string, paneId:string} which can be passed as command data to FILE_OPEN

ParamTypeDescription
stateObjectthe state to load

pane.saveState() ⇒ Object​

Returns the JSON-ified state of the object so it can be serialize

Kind: instance method of Pane
Returns: Object - state - the state to save

pane.getScrollState() ⇒ Object​

gets the current view's scroll state data

Kind: instance method of Pane
Returns: Object - scroll state - the current scroll state

pane.restoreAndAdjustScrollState([state], [heightDelta])​

tells the current view to restore its scroll state from cached data and apply a height delta

Kind: instance method of Pane

ParamTypeDescription
[state]Objectthe current scroll state
[heightDelta]numberthe amount to add or subtract from the state

_​

Pane objects host views of files, editors, etc... Clients cannot access Pane objects directly. Instead the implementation is protected by the MainViewManager -- however View Factories are given a Pane object which they can use to add views. References to Pane objects should not be kept as they may be destroyed and removed from the DOM.

To get a custom view, there are two components:

  1. A View Factory
  2. A View Object

View objects are anonymous object that have a particular interface.

Views can be added to a pane but do not have to exist in the Pane object's view list. Such views are "temporary views". Temporary views are not serialized with the Pane state or reconstituted when the pane is serialized from disk. They are destroyed at the earliest opportunity.

Temporary views are added by calling Pane.showView() and passing it the view object. The view will be destroyed when the next view is shown, the pane is mereged with another pane or the "Close All" command is exectuted on the Pane. Temporary Editor Views do not contain any modifications and are added to the workingset (and are no longer tempoary views) once the document has been modified. They will remain in the working set until closed from that point on.

Views that have a longer life span are added by calling addView to associate the view with a filename in the _views object. These views are not destroyed until they are removed from the pane by calling one of the following: removeView, removeViews, or _reset

Pane Object Events:

  • viewListChange - Whenever there is a file change to a file in the working set. These 2 events: DocumentManager.pathRemove and DocumentManager.fileNameChange will cause a viewListChange event so the WorkingSetView can update.

  • currentViewChange - Whenever the current view changes. (e, newView:View, oldView:View)

  • viewDestroy - Whenever a view has been destroyed (e, view:View)

View Interface:

The view is an anonymous object which has the following method signatures. see ImageViewer for an example or the sample provided with Brackets src/extensions/samples/BracketsConfigCentral

    {
        $el:jQuery
        getFile: function ():!File
        updateLayout: function(forceRefresh:boolean)
        destroy: function()
        getScrollPos: function():*=
        adjustScrollPos: function(state:Object=, heightDelta:number)=
        notifyContainerChange: function()=
        notifyVisibilityChange: function(boolean)=
        focus:function()=
    }

When views are created they can be added to the pane by calling pane.addView(). Views can be created and parented by attaching directly to pane.$el

this._codeMirror = new CodeMirror(pane.$el, ...)

Factories can create a view that's initially hidden by calling pane.addView(view) and passing false for the show parameter. Hidden views can be later shown by calling pane.showView(view)

$el:jQuery!

property that stores the jQuery wrapped DOM element of the view. All views must have one so pane objects can manipulate the DOM element when necessary (e.g. showView, _reparent, etc...)

getFile():File!

Called throughout the life of a View when the current file is queried by the system.

updateLayout(forceRefresh:boolean)

Called to notify the view that it should be resized to fit its parent container. This may be called several times or only once. Views can ignore the forceRefresh flag. It is used for editor views to force a relayout of the editor which probably isn't necessary for most views. Views should implement their html to be dynamic and not rely on this function to be called whenever possible.

destroy()

Views must implement a destroy method to remove their DOM element at the very least. There is no default implementation and views are hidden before this method is called. The Pane object doesn't make assumptions about when it is safe to remove a node. In some instances other cleanup must take place before a the DOM node is destroyed so the implementation details are left to the view.

Views can implement a simple destroy by calling

this.$el.remove()

These members are optional and need not be implemented by Views

getScrollPos() adjustScrollPos()

The system at various times will want to save and restore a view's scroll position. The data returned by getScrollPos() is specific to the view and will be passed back to adjustScrollPos() when the scroll position needs to be restored.

When Modal Bars are invoked, the system calls getScrollPos() so that the current scroll psotion of all visible Views can be cached. That cached scroll position is later passed to adjustScrollPos() along with a height delta. The height delta is used to scroll the view so that it doesn't appear to have "jumped" when invoking the Modal Bar.

Height delta will be a positive when the Modal Bar is being shown and negative number when the Modal Bar is being hidden.

getViewState() is another optional member that is used to cache a view's state when hiding or destroying a view or closing the project. The data returned by this member is stored in ViewStateManager and is saved with the project.

Views or View Factories are responsible for restoring the view state when the view of that file is created by recalling the cached state

var view = createIconView(file, pane); view.restoreViewState(ViewStateManager.getViewState(file.fullPath));

Notifications The following optional methods receive notifications from the Pane object when certain events take place which affect the view:

notifyContainerChange()

Optional Notification callback called when the container changes. The view can perform any synchronization or state update it needs to do when its parent container changes.

notifyVisiblityChange()

Optional Notification callback called when the view's vsibility changes. The view can perform any synchronization or state update it needs to do when its visiblity state changes.

Kind: global variable