# PanelMultiView

Allows a popup panel to host multiple subviews. The main view shown when the
panel is opened may slide out to display a subview, which in turn may lead to
other subviews in a cascade menu pattern.

The \<panel> element should contain a \<panelmultiview> element. Views are
declared using \<panelview> elements that are usually children of the main
\<panelmultiview> element, although they don't need to be, as views can also
be imported into the panel from other panels or popup sets.

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.

-- Active or inactive

This indicates whether the view is fully scrolled into the visible area
and ready to receive mouse and keyboard events. An active view is always
visible, but a visible view may be inactive. For example, during a scroll
transition, both views will be inactive.

When a view becomes active, the ViewShown event is fired synchronously,
and the showSubView and goBack methods can be called for navigation.

For the main view of the panel, the ViewShown event is dispatched during
the "popupshown" event, which means that other "popupshown" handlers may
be called before the view is active. Thus, code that needs to perform
further navigation automatically should either use the ViewShown event or
wait for an event loop tick, like BrowserTestUtils.waitForEvent does.

-- 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}│(D)│ B │            │ E │              Show subview D
  └───┴───┴───┴───┘            └───┘
    │ ┌───┬───┬───┬───┐        ┌───┐
    │ │{A}│(C)│ D │ B │        │ E │              Go back
    │ └───┴───┴───┴───┘        └───┘
    │   │   │
    │   │   └── Currently visible view
    │   │   │
    └───┴───┴── Open views
```

```{js:autoclass} AssociatedToNode
:members:
:private-members:
```

```{js:autoclass} PanelMultiView
:members:
:private-members:
```

```{js:autoclass} PanelView
:members:
:private-members:
```
