Kmenger has uploaded a new change for review.
https://gerrit.wikimedia.org/r/200224
Change subject: StackLayout: Add description and example
......................................................................
StackLayout: Add description and example
Change-Id: I87e168d5cf60a83927dd11faa539f75567791bd9
---
M src/layouts/StackLayout.js
1 file changed, 46 insertions(+), 20 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/24/200224/1
diff --git a/src/layouts/StackLayout.js b/src/layouts/StackLayout.js
index 8b0f580..58f35d3 100644
--- a/src/layouts/StackLayout.js
+++ b/src/layouts/StackLayout.js
@@ -1,5 +1,26 @@
/**
- * Layout containing a series of mutually exclusive pages.
+ * StackLayouts contain a series of {@link OO.ui.PanelLayout panel layouts}.
By default, only one panel is displayed
+ * at a time, though the stack layout can also be configured to show all
contained panels, one after another,
+ * by setting the #continuous option to 'true'.
+ *
+ * @example
+ * // A stack layout with two panels, configured to be displayed
continously
+ * var myStack = new OO.ui.StackLayout( {
+ * items: [
+ * new OO.ui.PanelLayout( {
+ * $content: $( '<p>Panel One</p>' ),
+ * padded: true,
+ * framed: true
+ * } ),
+ * new OO.ui.PanelLayout( {
+ * $content: $( '<p>Panel Two</p>' ),
+ * padded: true,
+ * framed: true
+ * } )
+ * ],
+ * continuous: true
+ * } );
+ * $( 'body' ).append( myStack.$element );
*
* @class
* @extends OO.ui.PanelLayout
@@ -7,8 +28,8 @@
*
* @constructor
* @param {Object} [config] Configuration options
- * @cfg {boolean} [continuous=false] Show all pages, one after another
- * @cfg {OO.ui.Layout[]} [items] Layouts to add
+ * @cfg {boolean} [continuous=false] Show all panels, one after another. By
default, only one panel is displayed at a time.
+ * @cfg {OO.ui.Layout[]} [items] Panel layouts to add to the stack layout.
*/
OO.ui.StackLayout = function OoUiStackLayout( config ) {
// Configuration initialization
@@ -42,14 +63,17 @@
/* Events */
/**
+ * A 'set' event is emitted when panels are {@link #addItems added}, {@link
#removeItems removed},
+ * {@link #clearItems cleared} or {@link #setItem displayed}.
+ *
* @event set
- * @param {OO.ui.Layout|null} item Current item or null if there is no longer
a layout shown
+ * @param {OO.ui.Layout|null} item Current panel or `null` if no panel is shown
*/
/* Methods */
/**
- * Get the current item.
+ * Get the current panel.
*
* @return {OO.ui.Layout|null}
*/
@@ -75,12 +99,14 @@
};
/**
- * Add items.
+ * Add panel layouts to the stack layout.
*
- * Adding an existing item (by value) will move it.
+ * Panels will be added to the end of the stack layout array unless the
optional index parameter specifies a different
+ * insertion point. Adding a panel that is already in the stack will move it
to the end of the array or the point specified
+ * by the index.
*
- * @param {OO.ui.Layout[]} items Items to add
- * @param {number} [index] Index to insert items after
+ * @param {OO.ui.Layout[]} items Panels to add
+ * @param {number} [index] Index of the insertion point
* @chainable
*/
OO.ui.StackLayout.prototype.addItems = function ( items, index ) {
@@ -98,11 +124,12 @@
};
/**
- * Remove items.
+ * Remove the specified panels from the stack layout.
*
- * Items will be detached, not removed, so they can be used later.
+ * Removed panels are detached from the DOM, not removed, so that they may be
reused. To remove all panels,
+ * you may wish to use the #clearItems method instead.
*
- * @param {OO.ui.Layout[]} items Items to remove
+ * @param {OO.ui.Layout[]} items Panels to remove
* @chainable
* @fires set
*/
@@ -122,9 +149,10 @@
};
/**
- * Clear all items.
+ * Clear all panels from the stack layout.
*
- * Items will be detached, not removed, so they can be used later.
+ * Cleared panels are detached from the DOM, not removed, so that they may be
reused. To remove only
+ * a subset of panels, use the #removeItems method.
*
* @chainable
* @fires set
@@ -137,14 +165,11 @@
};
/**
- * Show item.
+ * Show the specified panel.
*
- * Any currently shown item will be hidden.
+ * If another panel is currently displayed, it will be hidden.
*
- * FIXME: If the passed item to show has not been added in the items list, then
- * this method drops it and unsets the current item.
- *
- * @param {OO.ui.Layout} item Item to show
+ * @param {OO.ui.Layout} item Panel to show
* @chainable
* @fires set
*/
@@ -169,6 +194,7 @@
* Ensure all items are hidden except for the selected one.
* This method does nothing when the stack is continuous.
*
+ * @private
* @param {OO.ui.Layout[]} items Item list iterate over
* @param {OO.ui.Layout} [selectedItem] Selected item to show
*/
--
To view, visit https://gerrit.wikimedia.org/r/200224
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I87e168d5cf60a83927dd11faa539f75567791bd9
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Kmenger <kmen...@wikimedia.org>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
