108 lines
4.8 KiB
ReStructuredText
108 lines
4.8 KiB
ReStructuredText
==============
|
|
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:
|