JiboOs/docs/rendering/gui/components/List.js

/**
 * @interface jibo.face.views.List~ListOptions
 * @extends jibo.face.views.Element~ElementOptions
 * @description Interface - Configuration values for creating a List.
 * @prop {String} [axis] - Orientation of the list. Can be either `horizontal` or `vertical`.
 * @prop {jibo.face.views.Element~ElementOptions[]} [componentConfigs] - Object containing list of element configurations contain within list.
 * @prop {Boolean} [noPan = false] - If `true` disables gesture for panning left and right on list.
 * @prop {Number} [elementsPerPage] - Number of elements that will appear fully on screen at a time.
 * @prop {Number} [pageIndex] - Index of active page of list.
 * @prop {Number} [indexOfAction] - Index of the element within list that last triggered an action.
 * @prop {jibo.face.views.Element~DimensionData} [elementDimensions] - Width and height of the elements.
 * @prop {Number} [elementBuffer] - Minimum space between the elements in the list.
 * @prop {jibo.face.views.Element~ElementOptions} [defaultElement] - Default configuration for the elements in the list.
 * @prop {Boolean} [dynamic = false] - If `true`, list elements will load as needed. If `false`, all elements assets are loaded with view.
 * @prop {Boolean} [dynamicPreload = true] -  Use only when `dynamic` is `true`.
 * If `true` will load the assets for active elements prior to open, if `false` assets for active elements start laod after open is called.
 * @prop {Number} [dynamicBuffer] - Use only when `dynamic` is `true`. Number of pages on either side of current page that will be loaded.
 */

/**
 * Format for methods that will handle destroy transitioning for an Element
 * @callback jibo.face.views.List~ElementTransition
 * @param {jibo.face.views.Element} element - Element to transition.
 * @param {Function} done - Called once transition is complete.
 */

/**
 * Manage lists of elements using pagination.
 *
 * @class List
 * @extends jibo.face.views.ComponentGroup
 * @memberof jibo.face.views
 */

    /**
     * The default class identifier.
     * Generally used to register the class.
     * @name jibo.face.views.List.DEFAULT_TYPE
     * @type {String}
     * @readOnly
     */

    /**
     * Action type triggered when page changes.
     * @name jibo.face.views.List.PAN
     * @type {String}
     * @readOnly
     */

    /**
     * Action type triggered/Event string dispatched when page changes.
     * @name jibo.face.views.List.PAGED
     * @type {String}
     * @readOnly
     */

    /**
     * Event dispatched when page forward attempt is made from end of list.
     * @name jibo.face.views.List.AT_END
     * @type {String}
     * @readOnly
     */

    /**
     * Event dispatched when page backward attempt is made from front of list.
     * @name jibo.face.views.List.AT_FRONT
     * @type {String}
     * @readOnly
     */

    /**
     * Number of elements that will appear fully on screen at a time.
     * @name jibo.face.views.List#elementsPerPage
     * @type {number}
     */

    /**
     * Number of elements permitted to remain active at
     * the edge of the 'page' in addition to the elements per page,
     * a value of 1 will allow the elements on either end to remain visible and active.
     * @name jibo.face.views.List#numElementsAtEdge
     * @type {number}
     * @default 1
     */

    /**
     * The width and height of the elements.
     * @name jibo.face.views.List#elementDimensions
     * @type {jibo.face.views.Element~DimensionData}
     */

    /**
     * Minimum space between the elements in the list.
     * Buffer is calculated during List creation to guarantee appropriate page positioning,
     * and uses this value as the minimum allowable spacing between elements.
     * @name jibo.face.views.List#elementBuffer
     * @type {number}
     * @default 20
     */

    /**
     * Default configuration for the elements within the list.
     * Properties of `defaultElementData` are merged into the element configs on List creation,
     * filling in any unspecified values.
     * @name jibo.face.views.List#defaultElementData
     * @type {Object}
     */

    /**
     * Position of list axis.
     * Only horizontal lists are currently supported.
     * @name jibo.face.views.List#axisPosition
     * @type {number}
     */

    /**
     * In case of dynamic element lists, the number of pages on either side of current page that will be loaded.
     * @name jibo.face.views.List#dynamicLoadBuffer
     * @type {number}
     * @default 1
     */

    /**
     * Flag to disable gestures for panning left and right on list.
     * Set value before List's `createDisplay` is called to take effect.
     * @name jibo.face.views.List#noPan
     * @type {boolean}
     * @default false
     */

    /**
     * Flag to determine if all the list elements will be created dynamically.
     * Dynamic elements within the list are not supported yet, so this should remain false.
     * The use case for dynmic creation be for a list with a large or unknown number of elements.
     * @name jibo.face.views.List#dynamicElements
     * @type {boolean}
     * @default false
     */

    /**
     * Flag to include assets for elements that are in initial load range as part of the assets included in the View setup.
     * This guarantees that the initially visible elements will have their required assets when the View is opened.
     * @name jibo.face.views.List#dynamicPreload
     * @type {boolean}
     * @default false
     */

    /**
     * `true` to allow automatic recalculation of elementsPerPage to fit as many elements on page as possible, `false` to respect elementsPerPage
     * @name jibo.face.views.List#autoFitElements
     * @type {Boolean}
     * @default true
     */

    /**
     * `true` to display portion of elements from next pages at edge of screen, `false` to disable it
     * @name jibo.face.views.List#pageHinting
     * @type {Boolean}
     * @default true
     */

    /**
     * Get the standard distance between element positions, calculated from element dimensions and buffer.
     * @name jibo.face.views.List#elementSpacing
     * @type {number}
     */

    /**
     * Whether the list requires a pan or not, determine at ready.
     * @name jibo.face.views.List#_requiresPan
     * @type {Boolean}
     * @private
     */

    /**
     * In case of list with multiple pages, amount element for next page appears on screen.
     * Determines amount element shows to indicate there are more elements in that direction.
     * @name jibo.face.views.List#EDGE_HINT
     * @type {Number}
     * @constant
     * @private
     */

    /**
     * The max distance of buffer 'spread' when scrolling.
     * @name jibo.face.views.List#BUFFER_SPREAD
     * @type {number}
     * @constant
     * @private
     */

    /**
     * Minimum amount of pan distance required for page change.
     * @name jibo.face.views.List#PAN_THRESHOLD
     * @type {int}
     * @constant
     * @private
     */

    /**
     * The max distance of buffer 'spread' when panning.
     * @name jibo.face.views.List#PAN_SPREAD
     * @type {number}
     * @constant
     * @private
     */

    /**
     * Constant springs value used for spring movement.
     * @name jibo.face.views.List#SPRING
     * @type {number}
     * @constant
     * @private
     */

    /**
     * Constant friction value applied to spring movement.
     * @name jibo.face.views.List#FRICTION
     * @type {int}
     * @type {number}
     * @constant
     * @private
     */

    /**
     * The threshold the velocity must surpass in order to start the 'spread' between elements.
     * Assume a velocity of 0 if the velocity gets below or equal to this threshold.
     * @name jibo.face.views.List#REST_THRESHOLD
     * @type {number}
     * @constant
     * @private
     */

    /**
     * The x delta that all list elements must be below in order to unlock inputs during a swipe.
     * @name jibo.face.views.List#SWIPE_THRESHOLD
     * @type {number}
     * @constant
     * @private
     */

    /**
     * The axis of the list, only supports horizontal for now.
     * @name jibo.face.views.List#_axis
     * @type {String}
     * @default 'horizontal'
     * @private
     */

    /**
     * List of Elements currently awaiting assets to load.
     * @name jibo.face.views.List#_loadingElements
     * @type {jibo.face.views.Element[]}
     * @private
     */

    /**
     * left page bound
     * @name jibo.face.views.List#_leftPageBound
     * @type {number}
     * @private
     */

    /**
     * right page bound
     * @name jibo.face.views.List#_leftPageBound
     * @type {number}
     * @private
     */

    /**
     * Current page the list is on, 0 being the first page.
     * @name jibo.face.views.List#_pageIndex
     * @type {int}
     * @private
     */

    /**
     * The current element offset of the pages.
     * @name jibo.face.views.List#_pageElementOffset
     * @type {int}
     * @private
     */

    /**
     * The list index of the element that last triggered an action.
     * @name jibo.face.views.List#_indexOfAction
     * @type {number}
     * @private
     */

    /**
     * The current page the list is on, 0 being the first page.
     * @name jibo.face.views.List#pageIndex
     * @type {number}
     * @readOnly
     */

    /**
     * Maximum buffer distance, this is the standard buffer plus the max distance of buffer 'spread' when scrolling
     * @name jibo.face.views.List#_bufferMax
     * @type {int}
     * @private
     */

    /**
     * Current type of movement, refer to Movement enum for values.
     * @name jibo.face.views.List#_currentMovement
     * @type {int}
     * @private
     */

    /**
     * Total distance of the list has mpved from when pan began.
     * This is reset to zeroed once the pan stops.
     * @name jibo.face.views.List#_panTotalDelta
     * @type {number}
     * @private
     */

    /**
     * Holds index range for active elements.
     * For use in dynamic lists where we don't want to keep calculating the active range.
     * @name jibo.face.views.List#_dynamicActiveIndexRange
     * @type {number[]}
     * @private
     */

    /**
     * Create List from configuration.
     * @method jibo.face.views.List#createFromConfig
     * @param {Object} configData Configuration to create list from.
     * @returns {jibo.face.views.List}
     */

    /**
     * Add Element to the List.
     * Assigns the Element's index within the list to the Element.index variable.
     * @method jibo.face.views.List#addComponent
     * @param {jibo.face.views.Element} element The Element to add this group's component list and library.
     * @param {String} [elementId] The id to assign to the Element, if specified will overwrite existing id,
     *                  if none is specified an id will be automatically generated and assigned.
     * @returns {jibo.face.views.Element} Returns the given Element.
     */

    /**
     * Remove Element from list, ultimately destroying the Element.
     * @method jibo.face.views.List#removeComponent
     * @param {jibo.face.views.Component|Number|String} componentDeterminer - Provide Component, index of component, or id of component to remove.
     * @param {Function} [done] - Callback for when element has been fully removed.
     * @param {jibo.face.views.List~ElementTransition} [transition] - Optional method to transition element prior to destruction, if not defined uses default.
     * @returns {jibo.face.views.Component}
     */

    /**
     * Compiles together Objects that describe the assets to load from this Component and its children.
     * If list is dynamic, only loads an asset to display loading, the element asset are then loaded on the fly.
     * @name jibo.face.views.List#assetDescriptors
     * @type {jibo.face.views~AssetDescriptor[]}
     */

    /**
     * FOR OVERRIDE ONLY. DO NOT CALL.
     *
     * Updates the indexes, so list can remember which page it was on when it closed and what element closed it.
     * @method jibo.face.views.List#updateConfig
     * @param {Object} [configData] Object defining configuration.
     * @returns {Object}
     */

    /**
     * FOR OVERRIDE ONLY. DO NOT CALL.
     *
     * Create the display, sets up touch controls.
     * @method jibo.face.views.List#createDisplay
     * @param {PIXI.Container} container Parent Container which all DisplayObject
     *        created within this Component should be added to.
     * @param {Object} [assets] Object passed back from loader namespace load method,
     *        refer to loader namespace within jibo for details.
     */

    /**
     * Called by parent ComponentGroup once parent has finished its loading and setup.
     * Allows opportunity to do additional setup that may depend on other components.
     * Register for update if multiple pages are required. Also register for panning if its not disabled.
     *
     * ATTENTION: This should not be called directly, the top level View {@link jibo.face.views.View}
     * will call this, which will recurse through Component tree.
     * @method jibo.face.views.List#ready
     */

    /**
     * Destroy, unregister for update, remove gestures.
     * Should not be called directly, is called through the owning ComponentGroup
     * @method jibo.face.views.List#destroy
     */

    /**
     * Lock input for List and all child Components,
     * and activate or deactivate gestures.
     * @method jibo.face.views.List#lockInput
     * @param {Boolean} [flag = true] - Flag for pausing or un-pausing the Component.
     */

    /**
     * Turn the interactivity of the child components off or on.
     * @method jibo.face.views.List#lockChildInput
     * @param {boolean} flag - flag to turn interactivity on or off.
     * @protected
     */

    /**
     * Open the list, has unique implementation for vertical transitions (TRANS_UP, TRANS_DOWN, & TRANS_EYE).
     * Once open is complete start registering for pans if criteria are met.
     * Should not be called directly, is called through the owning ComponentGroup
     * @method jibo.face.views.List#open
     * @param {Function} callback Function to be called once open is complete.
     * @param {String} transitionType String used to determine way Component opens,
     *        refer to ViewManager for constants used
     * @param {number} [duration = ViewManager.TRANS_TIME] Duration of the transition.
     * @param {String} [tweenType = 'backOut'] Type of tween used.
     */

    /**
     * FOR OVERRIDE ONLY. DO NOT CALL.
     *
     * Close the list, has unique implementation for vertical transitions (TRANS_UP, TRANS_DOWN, & TRANS_EYE).
     * Should not be called directly, is called through the owning ComponentGroup.
     * @method jibo.face.views.List#close
     * @param {Function} callback Function to be called once open is complete.
     * @param {String} [transitionType] String used to determine way Component closes,
     *        refer to ViewManager for constants used.
     * @param {number} [duration = ViewManager.TRANS_TIME] Duration of the transition.
     * @param {String} [tweenType = 'backIn'] Type of tween used.
     */

    /**
     * Bubble up action to parent, keep a reference to the index of the element that triggered action for later use with transitions.
     * @method jibo.face.views.List#actionHandler
     * @param {jibo.face.views.ActionData} action Contains string for type of action and Object with any pertinent data required for that action type.
     * @param {jibo.face.views.Component} [fromComponent] Component that triggered action.
     */

    /**
     * Blocks actions from reaching child Elements.
     * Listens for actions that will effect the page to change,
     * namely ActionData.SWIPE_RIGHT, ActionData.SWIPE_LEFT
     * @method jibo.face.views.List#actionEnactor
     * @param {jibo.face.views.ActionData} action Contains string for type of action and data Object with any pertinent data dependent on action type.
     * @return {boolean} Returns true if given action is acted on.
     */

    /**
     * Move forward or backward one page.
     * @method jibo.face.views.List#changePage
     * @param {Boolean} [pageForward = true] - If `true` moves forward through the list, if `false` moves backwards.
     * @return {Boolean} `true` if list was able to change pages
     */

    /**
     * Move to start or end of list.
     * @method jibo.face.views.List#pageToEnd
     * @param {Boolean} [pageToFront = false] - If `true` moves to the beginning of the list, if `false` moves to end of the list.
     * @return {Boolean} `true` if list was able to change pages
     */

    /**
     * Get the start index of the element for the given page index.
     * Make sure page index is set before using as it to guarantees offsets is correct.
     * The offset guarantees that pages will always show the max elements per page,
     * leaving no 'empty' slots when the page displays.
     * @method jibo.face.views.List#getStartIndexByPage
     * @param {number} pageIndex The index of the page.
     * @return {number} The adjusted start index for the page, so that the page is always 'full'.
     * @public
     */

    /**
     * Set the active page index.
     * Updates variables that keep track of element offset and range for dynamic elements.
     * @method jibo.face.views.List#setActivePage
     * @param {number} index - index of page
     * @protected
     */

    /**
     * FOR OVERRIDE ONLY. DO NOT CALL FROM EXTERNAL CLASS.
     *
     * Custom list open for opening vertically.
     * Should not be called directly, but from within List.open()
     * @method jibo.face.views.List#openVertical
     * @param {Function} callback Function to be called once open is complete.
     * @param {String} [transitionType] String used to determine way Component closes,
     *        refer to ViewManager for constants used.
     * @param {number} [duration = ViewManager.TRANS_TIME] Duration of the transition.
     * @param {String} [tweenType = 'backIn'] Type of tween used.
     * @private
     */

    /**
     * FOR OVERRIDE ONLY. DO NOT CALL FROM EXTERNAL CLASS.
     *
     * Custom list close for closing vertically.
     * Should not be called directly, but from within List.close()
     * @method jibo.face.views.List#closeVertical
     * @param {Function} callback Function to be called once open is complete.
     * @param {String} [transitionType] String used to determine way Component closes,
     *        refer to ViewManager for constants used.
     * @param {number} [duration = ViewManager.TRANS_TIME] Duration of the transition.
     * @param {String} [tweenType = 'backIn'] Type of tween used.
     * @private
     */

    /**
     * FOR OVERRIDE ONLY. DO NOT CALL FROM EXTERNAL CLASS.
     *
     * Custom list open for opening from an EyeView.
     * Should not be called directly, but from within List.open()
     * @method jibo.face.views.List#openFromEye
     * @param {Function} callback Function to be called once open is complete.
     * @param {number} [duration = ViewManager.TRANS_TIME] Duration of the transition.
     * @private
     */

    /**
     * FOR OVERRIDE ONLY. DO NOT CALL FROM EXTERNAL CLASS.
     *
     * Custom list close for closing an EyeView.
     * Should not be called directly, but from within List.close()
     * @method jibo.face.views.List#closeToEye
     * @param {Function} callback Function to be called once open is complete.
     * @param {number} [duration = ViewManager.TRANS_TIME] Duration of the transition.
     * @private
     */

    /**
     * Load and destroy elements dynamically based on page index.
     * @method jibo.face.views.List#dynamicElementsPageChange
     * @param {number} pageIndex - Page index to reference for dynamic loading, generally the current page.
     * @private
     */

    /**
     * Enables recursive iteration through each asset descriptor in given object, loading each individually.
     * This is to reduce the impact of one bad asset corrupting a load batch.
     * @method jibo.face.views.List#iterativeLoad
     * @param {any} assetsToLoad Object containing AssetDescriptors using their id as key
     * @private
     */

    /**
     * Run through list of loading components and check to see if their required assets have been loaded.
     * If assets are available update display.
     * @method jibo.face.views.List#assignElementAssets
     * @private
     */

    /**
     * Remove loader display and create Element's display now that assets are available.
     * @method jibo.face.views.List#updateElementDisplay
     * @param {jibo.face.views.Element} element - Element to update.
     * @private
     */

    /**
     * Remove loader stand-in and create Element's display now that assets are available.
     * @method jibo.face.views.List#emptyElementDisplay
     * @param {jibo.face.views.Element} element - Element to empty display.
     * @private
     */

    /**
     * Set the list element targets based on page index.
     * This is used in conjunction with changePage().
     * @method jibo.face.views.List#setTargetsByPage
     * @param {number} pageIndex - we can expect that the pageIndex is possible
     * @private
     */

    /**
     * Set the list element targets based on touch input.
     * This is used when panning the list.
     * @method jibo.face.views.List#setTargetsByInput
     * @param {number} panState The t of the pan, refer to Pan Case enum for valid states
     * @param {number} velocity The velocity of the pan, equal to the delta of the mouse x position since last update
     * @param {number} inputX - Position x of input.
     * @private
     */

    /**
     * Updates the position of the list elements by springing them toward their targets.
     * @method jibo.face.views.List#springUpdate
     * @private
     */

    /**
     * Setup panning, determining the pan state and setting spring strength.
     * The parameters are supplied by the GestureManager.
     * @method jibo.face.views.List#pan
     * @param {number} inputX - Position x of input.
     * @param {number} velocity - Distance input has moved since last GestureManager dispatch.
     * @private
     */

    /**
     * Stop panning.
     * @method jibo.face.views.List#panStop
     * @private
     */

    /**
     * Handler for events sent from pan gesture.
     * @method jibo.face.views.List#onPanEvent
     * @param {Object} event - Event object sent from HammerJS's Pan gesture.
     * @private
     */

    /**
     * Check the input events received from the gesture manager.
     * @method jibo.face.views.List#checkGestureInput
     * @param {Boolean} active - Flag determining if pan is active.
     * @param {Number} [inputX = 0] - Current x position of pan input.
     * @param {Number} [deltaX = 0] - Difference between start position on current position of pan input.
     * @private
     */

    /**
     * Default transition for removing a list element.
     * @method jibo.face.views.List#elementRemovalTransition
     * @param {jibo.face.views.Element} element - Element from list to destroy
     * @param {Function} done - Callback when transition is complete
     * @private
     */

    /**
     * Destroy a single element, removal of element form the list is handle in List.
     * Removes assets associated with Element, while checking for asset conflicts.
     * @method jibo.face.views.List#destroyElement
     * @param {jibo.face.views.Element} element - Element from list to destroy
     * @param {Function} [done] - Callback when destruction of element is complete
     * @private
     */

    /**
     * Merge Component configurations together.
     * @method jibo.face.views.List#mergeConfigs
     * @param {Object} data - Object that defaultData is merging into and that will be returned.
     * @param Object} defaultData - Object to merge into data
     * @param {Boolean} [mergeArrays = true] - if `true` will merge Arrays together, if 'false' arrays will overwrite each other.
     * @returns {Object} - resulting object from merge.
     * @private
     */

    /**
     * Returns page index that has been tested against the number of elements in list.
     * Does not adjust the original parameter.
     * @method jibo.face.views.List#normalizePageIndex
     * @param {Number} pageIndex The index of the page
     * @return {Number} the normalized page index
     * @private
     */