--- a/browser/components/customizableui/PanelMultiView.jsm
+++ b/browser/components/customizableui/PanelMultiView.jsm
@@ -15,33 +15,75 @@
* The panel should be opened asynchronously using the openPopup static method
* on the PanelMultiView object. This will display the view specified using the
* mainViewId attribute on the contained <panelmultiview> element.
*
* Specific subviews can slide in using the showSubView method, and backwards
* navigation can be done using the goBack method or through a button in the
* subview headers.
*
+ * The process of displaying the main view or a new subview requires multiple
+ * steps to be completed, hence at any given time the <panelview> element may
+ * be in different states:
+ *
+ * -- Open or closed
+ *
+ * All the <panelview> elements start "closed", meaning that they are not
+ * associated to a <panelmultiview> element and can be located anywhere in
+ * the document. When the openPopup or showSubView methods are called, the
+ * relevant view becomes "open" and the <panelview> element may be moved to
+ * ensure it is a descendant of the <panelmultiview> element.
+ *
+ * The "ViewShowing" event is fired at this point, when the view is not
+ * visible yet. The event is allowed to cancel the operation, in which case
+ * the view is closed immediately.
+ *
+ * Closing the view does not move the node back to its original position.
+ *
+ * -- Visible or invisible
+ *
+ * This indicates whether the view is visible in the document from a layout
+ * perspective, regardless of whether it is currently scrolled into view. In
+ * fact, all subviews are already visible before they start sliding in.
+ *
+ * Before scrolling into view, a view may become visible but be placed in a
+ * special off-screen area of the document where layout and measurements can
+ * take place asyncronously.
+ *
+ * When navigating forward, an open view may become invisible but stay open
+ * after sliding out of view. The last known size of these views is still
+ * taken into account for determining the overall panel size.
+ *
+ * When navigating backwards, an open subview will first become invisible and
+ * then will be closed.
+ *
+ * -- Navigating with the keyboard
+ *
+ * An open view may keep state related to keyboard navigation, even if it is
+ * invisible. When a view is closed, keyboard navigation state is cleared.
+ *
* This diagram shows how <panelview> nodes move during navigation:
*
* In this <panelmultiview> In other panels Action
* ┌───┬───┬───┐ ┌───┬───┐
* │(A)│ B │ C │ │ D │ E │ Open panel
* └───┴───┴───┘ └───┴───┘
* ┌───┬───┬───┐ ┌───┬───┐
- * │ A │(C)│ B │ │ D │ E │ Show subview C
+ * │{A}│(C)│ B │ │ D │ E │ Show subview C
* └───┴───┴───┘ └───┴───┘
* ┌───┬───┬───┬───┐ ┌───┐
- * │ A │ C │(D)│ B │ │ E │ Show subview D
+ * │{A}│{C}│(D)│ B │ │ E │ Show subview D
* └───┴───┴───┴───┘ └───┘
- * ┌───┬───┬───┬───┐ ┌───┐
- * │ A │(C)│ D │ B │ │ E │ Go back
- * └───┴───┴───┴───┘ └───┘
- * │
- * └── Currently visible view
+ * │ ┌───┬───┬───┬───┐ ┌───┐
+ * │ │{A}│(C)│ D │ B │ │ E │ Go back
+ * │ └───┴───┴───┴───┘ └───┘
+ * │ │ │
+ * │ │ └── Currently visible view
+ * │ │ │
+ * └───┴───┴── Open views
*
* If the <panelmultiview> element is "ephemeral", imported subviews will be
* moved out again to the element specified by the viewCacheId attribute, so
* that the panel element can be removed safely.
*/
"use strict";
@@ -549,42 +591,47 @@ this.PanelMultiView = class extends this
* DOM element that triggered the subview, which will be highlighted
* and whose "label" attribute will be used for the title of the
* subview when a "title" attribute is not specified.
*/
showSubView(viewIdOrNode, anchor) {
let viewNode = typeof viewIdOrNode == "string" ?
this.document.getElementById(viewIdOrNode) : viewIdOrNode;
if (!viewNode) {
- throw new Error(`Subview ${viewIdOrNode} doesn't exist.`);
+ Cu.reportError(new Error(`Subview ${viewIdOrNode} doesn't exist.`));
+ return;
}
- this._showView(viewNode, anchor);
+ let nextPanelView = PanelView.forNode(viewNode);
+ if (this.openViews.includes(nextPanelView)) {
+ Cu.reportError(new Error(`Subview ${viewNode.id} is already open.`));
+ return;
+ }
+
+ this._showView(nextPanelView, anchor);
}
/**
* Navigates backwards by sliding out the most recent subview.
*/
goBack() {
if (this.openViews.length < 2) {
// This may be called by keyboard navigation or external code when only
// the main view is open.
return;
}
- let previous = this.openViews.pop().node;
- let current = this._currentSubView;
- this._showView(current, null, previous);
+ this._showView(this.openViews[this.openViews.length - 2], null, true);
}
async showMainView() {
if (!this.node || !this._mainViewId)
return false;
- return this._showView(this._mainView);
+ return this._showView(PanelView.forNode(this._mainView));
}
/**
* Ensures that all the panelviews, that are currently part of this instance,
* are hidden, except one specifically.
*
* @param {panelview} [nextPanelView]
* The PanelView object to ensure is visible. Optional.
@@ -595,51 +642,51 @@ this.PanelMultiView = class extends this
if (panelView == nextPanelView || !this.node || panelView.node.panelMultiView != this.node)
continue;
panelView.current = false;
}
if (!this.node || !nextPanelView)
return;
- if (!this.openViews.includes(nextPanelView))
- this.openViews.push(nextPanelView);
-
nextPanelView.current = true;
this.showingSubView = nextPanelView.node.id != this._mainViewId;
}
- async _showView(viewNode, anchor, previousView) {
+ async _showView(nextPanelView, anchor, reverse) {
try {
- let nextPanelView = PanelView.forNode(viewNode);
+ let viewNode = nextPanelView.node;
this.knownViews.add(nextPanelView);
viewNode.panelMultiView = this.node;
- let previousViewNode = previousView || this._currentSubView;
+ let previousViewNode = this._currentSubView;
if (viewNode.parentNode != this._viewStack) {
this._viewStack.appendChild(viewNode);
}
// Emit the ViewShowing event so that the widget definition has a chance
// to lazily populate the subview with things or perhaps even cancel this
// whole operation.
if (await nextPanelView.dispatchAsyncEvent("ViewShowing")) {
return false;
}
+ if (!reverse) {
+ this.openViews.push(nextPanelView);
+ }
+
// If the panelview to show is the same as the previous one, the 'ViewShowing'
// event has already been dispatched. Don't do it twice.
let showingSameView = viewNode == previousViewNode;
let prevPanelView = PanelView.forNode(previousViewNode);
prevPanelView.captureKnownSize();
- let reverse = !!previousView;
if (!reverse) {
// We are opening a new view, either because we are navigating forward
// or because we are showing the main view. Some properties of the view
// may vary between panels, so we make sure to update them every time.
// Firstly, make sure that the header matches how the view was opened.
nextPanelView.headerText = viewNode.getAttribute("title") ||
(anchor && anchor.getAttribute("label"));
// The main view of a panel can be a subview in another one.
@@ -658,16 +705,20 @@ this.PanelMultiView = class extends this
await this._cleanupTransitionPhase();
if (!showingSameView && this._panel.state == "open") {
await this._transitionViews(previousViewNode, viewNode, reverse, anchor);
nextPanelView.focusSelectedElement();
} else {
this.hideAllViewsExcept(nextPanelView);
}
+ if (reverse) {
+ this.openViews.pop();
+ }
+
return true;
} catch (ex) {
Cu.reportError(ex);
return false;
}
}
/**