panelmultiview.rst (4949B)
1 ============== 2 PanelMultiView 3 ============== 4 5 Allows a popup panel to host multiple subviews. The main view shown when the 6 panel is opened may slide out to display a subview, which in turn may lead to 7 other subviews in a cascade menu pattern. 8 9 The <panel> element should contain a <panelmultiview> element. Views are 10 declared using <panelview> elements that are usually children of the main 11 <panelmultiview> element, although they don't need to be, as views can also 12 be imported into the panel from other panels or popup sets. 13 14 The panel should be opened asynchronously using the openPopup static method 15 on the PanelMultiView object. This will display the view specified using the 16 mainViewId attribute on the contained <panelmultiview> element. 17 18 Specific subviews can slide in using the showSubView method, and backwards 19 navigation can be done using the goBack method or through a button in the 20 subview headers. 21 22 The process of displaying the main view or a new subview requires multiple 23 steps to be completed, hence at any given time the <panelview> element may 24 be in different states: 25 26 -- Open or closed 27 28 All the <panelview> elements start "closed", meaning that they are not 29 associated to a <panelmultiview> element and can be located anywhere in 30 the document. When the openPopup or showSubView methods are called, the 31 relevant view becomes "open" and the <panelview> element may be moved to 32 ensure it is a descendant of the <panelmultiview> element. 33 34 The "ViewShowing" event is fired at this point, when the view is not 35 visible yet. The event is allowed to cancel the operation, in which case 36 the view is closed immediately. 37 38 Closing the view does not move the node back to its original position. 39 40 -- Visible or invisible 41 42 This indicates whether the view is visible in the document from a layout 43 perspective, regardless of whether it is currently scrolled into view. In 44 fact, all subviews are already visible before they start sliding in. 45 46 Before scrolling into view, a view may become visible but be placed in a 47 special off-screen area of the document where layout and measurements can 48 take place asyncronously. 49 50 When navigating forward, an open view may become invisible but stay open 51 after sliding out of view. The last known size of these views is still 52 taken into account for determining the overall panel size. 53 54 When navigating backwards, an open subview will first become invisible and 55 then will be closed. 56 57 -- Active or inactive 58 59 This indicates whether the view is fully scrolled into the visible area 60 and ready to receive mouse and keyboard events. An active view is always 61 visible, but a visible view may be inactive. For example, during a scroll 62 transition, both views will be inactive. 63 64 When a view becomes active, the ViewShown event is fired synchronously, 65 and the showSubView and goBack methods can be called for navigation. 66 67 For the main view of the panel, the ViewShown event is dispatched during 68 the "popupshown" event, which means that other "popupshown" handlers may 69 be called before the view is active. Thus, code that needs to perform 70 further navigation automatically should either use the ViewShown event or 71 wait for an event loop tick, like BrowserTestUtils.waitForEvent does. 72 73 -- Navigating with the keyboard 74 75 An open view may keep state related to keyboard navigation, even if it is 76 invisible. When a view is closed, keyboard navigation state is cleared. 77 78 This diagram shows how <panelview> nodes move during navigation:: 79 80 In this <panelmultiview> In other panels Action 81 ┌───┬───┬───┐ ┌───┬───┐ 82 │(A)│ B │ C │ │ D │ E │ Open panel 83 └───┴───┴───┘ └───┴───┘ 84 ┌───┬───┬───┐ ┌───┬───┐ 85 │{A}│(C)│ B │ │ D │ E │ Show subview C 86 └───┴───┴───┘ └───┴───┘ 87 ┌───┬───┬───┬───┐ ┌───┐ 88 │{A}│{C}│(D)│ B │ │ E │ Show subview D 89 └───┴───┴───┴───┘ └───┘ 90 │ ┌───┬───┬───┬───┐ ┌───┐ 91 │ │{A}│(C)│ D │ B │ │ E │ Go back 92 │ └───┴───┴───┴───┘ └───┘ 93 │ │ │ 94 │ │ └── Currently visible view 95 │ │ │ 96 └───┴───┴── Open views 97 98 .. js:autoclass:: AssociatedToNode 99 :members: 100 :private-members: 101 102 .. js:autoclass:: PanelMultiView 103 :members: 104 :private-members: 105 106 .. js:autoclass:: PanelView 107 :members: 108 :private-members: