JiboOs/docs/rendering/gui/Component.js

/**
 * @interface jibo.face.views.Component~ComponentOptions
 * @description Interface - Configuration values for creating a Component.
 * @prop {String} [id] - Identifier for component.
 * @prop {String} [type] - Type of component.
 * @prop {jibo.face.views~AssetDescriptor[]} [assets] - List of required asset descriptors.
 * @prop {jibo.face.views~ActionDescriptor} [action] - Action triggered when user interacts with the component.
 * @prop {jibo.face.views~ActionDescriptor[]} [actions] - List of possible actions for the interactions with the component.
 */

/**
 * Base component class for GUI elements.
 * @class Component
 * @extends EventEmitter
 * @memberof jibo.face.views
 * @abstract
 */

    /**
     * String used for identification, each Component within a
     * ComponentGroup should have a unique id to help with retrieval.
     * @name jibo.face.views.Component#id
     * @type {String}
     */

    /**
     * Reference to the parent group of this Component.
     * @name jibo.face.views.Component#parentGroup
     * @type {jibo.face.views.ComponentGroup}
     */

    /**
     * Reference to the top most parent group of this Component, which is a View.
     * @name jibo.face.views.Component#_parentView
     * @type {jibo.face.views.View}
     * @private
     */

    /**
     * Subcomponent to handles interactive aspects of Component.
     * Manages actions and their gesture association.
     * @name jibo.face.views.Component#_touchInteractivity
     * @type {jibo.face.views.TouchInteractive}
     * @private
     */

    /**
     * Set to `true` class has changed its
     * state in a way that needs to be recorded between Views (e.g when a
     * list moves from one page to another).
     * @name jibo.face.views.Component#stateChanged
     * @type {Boolean}
     * @default false
     * @readOnly
     */

    /**
     * The Component type. Should equal the Class name.
     * In some case, `type` may not be equal to Class name if you're using variants.
     * Variants allow for different behavior within the class without having to extend it.
     * @name jibo.face.views.Component#type
     * @type {String}
     * @readOnly
     */

    /**
     * Holds Subcomponents.
     * @name jibo.face.views.Component#_subcomponents
     * @type {{jibo.face.views.Subcomponent}}
     * @private
     */

    /**
     * Flag determining whether to respond to input.
     * @name jibo.face.views.Component#inputLocked
     * @type {Boolean}
     */

    /**
     * Return array of objects that describe assets to be loaded.
     * Refer to {@link jibo.loader} for documentation.
     * @name jibo.face.views.Component#assetDescriptors
     * @type {jibo.face.views~AssetDescriptor[]}
     * @readOnly
     */

    /**
     * Get the View the Component is ultimately parented to.
     * @name jibo.face.views.Component#parentView
     * @type {jibo.face.views.View}
     * @readOnly
     */

    /**
     * Add a Subcomponent.
     * @method jibo.face.views.Component#addSubcomponent
     * @param {jibo.face.views.Subcomponent} subcomponent - Subcomponent to add.
     * @returns {jibo.face.views.Subcomponent} Subcomponent added.
     */

    /**
     * Retrieve a Subcomponent.
     * @method jibo.face.views.Component#getSubcomponent
     * @param {string} type - Type of SubComponent, can access type statically from class like Subcomponent.TYPE.
     * @returns {jibo.face.views.Subcomponent} Subcomponent matching given type, otherwise null.
     */

    /**
     * Applies data contained within the given `configData` object (generally derived
     * from JSON) to the class. Override this method to configure further.
     * data and/or make manual additions to the class's variables.
     * @method jibo.face.views.Component#assignConfig
     * @param {Object} configData The configuration object for the Component.
     */

    /**
     * FOR OVERRIDE ONLY. DO NOT CALL.
     *
     * Takes initial config Object that was provided to define class and updates it
     * with any necessary values regarding any new `state` of the component.
     * Returns the updated Object, though it shouldn't be necessary to reassign
     * the returned Object, since generally the updated values are assigned through `Object.assign`
     * to merge new values into original.
     * @method jibo.face.views.Component#updateConfig
     * @param {Object} configObject The configuration Object for the Component.
     * @abstract
     */

    /**
     * To be overridden, should create DisplayObjects from given assets and add the
     * to stage via the given container.
     * @method jibo.face.views.Component#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 {@link jibo.loader} for details.
     * @abstract
     */

    /**
     * Register with the parent group to enter the update loop.
     * If `true` registers for update, if `false` unregisters for update.
     * @method jibo.face.views.Component#registerUpdate
     * @param {Boolean} bool Flag to register or unregister with update.
     */

    /**
     * FOR OVERRIDE ONLY. DO NOT CALL.
     *
     * Frame enter loop update.
     * @method jibo.face.views.Component#update
     * @param {number} elapsed Time in milliseconds since the last frame update.
     * @abstract
     */

    /**
     * FOR OVERRIDE ONLY. DO NOT CALL.
     *
     * Cleanup method to assist with garbage collection.
     * @method jibo.face.views.Component#destroy
     */

    /**
     * Called by parent ComponentGroup once parent has finished its loading and setup.
     * Allows opportunity to do additional setup that may depend on other components.
     *
     * ATTENTION : This should not be called directly, the parent View {@link jibo.face.views.View}
     * will call this, which will recurse through Component tree.
     * @method jibo.face.views.Component#ready
     */

    /**
     * FOR OVERRIDE ONLY. DO NOT CALL.
     *
     * Method for `open` transition, override to custom how Component opens.
     * Method is responsible for calling the callback in all situations as
     * the parent ComponentGroup is waiting for all children to trigger the callback in oder to complete.
     *
     * ATTENTION : This should not be called directly, {@link jibo.face.views}
     * will manage when Components should close during the view process.
     * @method jibo.face.views.Component#open
     * @param {Function} callback Function to be called once open is complete.
     * @param {String} transitionType String used to determine way Component opens.
     *        Refer to {@link jibo.face.views} for constants used
     * @param {number} [duration = ViewManager.TRANS_TIME] Duration of the transition.
     */

    /**
     * FOR OVERRIDE ONLY. DO NOT CALL.
     *
     * Method for `close` transition, override to custom how Component opens.
     * Method is responsible for calling the callback in all situations as
     * the parent ComponentGroup is waiting for all children to trigger the callback in oder to comple
     *
     * ATTENTION : This should not be called directly, {@link jibo.face.views}
     * will manage when Components should close during the view process.
     * @method jibo.face.views.Component#close
     * @param {Function} callback Function to be called once open is complete.
     * @param {String} [transitionType] String used to determine way Component closes.
     *        Refer to {@link jibo.face.views} for constants used.
     * @param {number} [duration = ViewManager.TRANS_TIME] Duration of the transition.
     */

    /**
     * Manually add an asset descriptor via parameters.
     * Refer to {@link jibo.loader} for documentation.
     * @method jibo.face.views.Component#addAssetDescriptor
     * @param {String} id The id for the asset, ids must be unique, otherwise they will override each other.
     * @param {String} src The source path of the asset to be loaded
     * @param {String} type The type of asset to load. Refer to {@link jibo.loader} for valid types.
     * @param {Boolean} [upload = false] Flag determining if asset should be loaded to the CPU as part of the load process.
     * @param {String} [cache] - Cache asset is associated with. Will use the loader's current cache unless otherwise specified.
     * @returns {Object} Asset descriptor added
     */

    /**
     * Manually add an asset descriptor object. Refer to {@link jibo.loader} for documentation on format.
     * @method jibo.face.views.Component#addAssetDescriptorObject
     * @param {jibo.face.views~AssetDescriptor} assetDescriptor See {@link jibo.loader} for asset format.
     * @returns {Object} Asset descriptor object added.
     */

    /**
     * Component has interactivity.
     * NOTE: Possible that interactivity is not active, will still return `true` in this case.
     * @name jibo.face.views.Component#hasTouchInteractive
     * @type {Boolean}
     * @readOnly
     */

    /**
     * Whether Component has interactivity and it is active.
     * @name jibo.face.views.Component#isTouchInteractive
     * @type {Boolean}
     * @readOnly
     */

    /**
     * Add a {@link jibo.face.views.ActionData} and associate it with given gesture.
     * Generally these actions are triggered on a screen press (if a screen press is set up).
     * Adding an action adds interactivity to the Component.
     * @method jibo.face.views.Component#addAction
     * @param {jibo.face.views.ActionData | string} action - The action to be triggered on click,
     * can pass the ActionData or provide the action type
     * @param {any} [data] - The data Object for the action, generally used if passing the action type.
     * @param {boolean} [clearPrevious = false] Flag to determine if we should clear out the existing actions.
     * @param {boolean} [toFront = false] If `true` adds action to front of actions list, causing it to be called first when actions are triggered.
     * @param {jibo.face.views.GESTURE} [gesture = tap] - Type of gesture the actions are associated with.
     * @returns {jibo.face.views.ActionData} The ActionData added.
     */

    /**
     * Clear all actions associated with given gesture type.
     * @method jibo.face.views.Component#clearActions
     * @param {jibo.face.views.GESTURE} [gesture = tap] - Type of gesture the actions ae associated with.
     */

    /**
     * Remove all actions of given type associated with given gesture.
     * @method jibo.face.views.Component#removeActionsByType
     * @param {string} actionType - Type of ActionData to remove.
     * @param {jibo.face.views.GESTURE} [gesture = tap] - Type of gesture the actions are associated with.
     */

    /**
     * Trigger actions associated with given gesture type.
     * Calls Component or the Component parent's actionHandler for each action.
     * @method jibo.face.views.Component#triggerActions
     * @param {jibo.face.views.GESTURE} [gesture = tap] - Type of gesture the actions are associated with.
     * @return {boolean} `true` if at least one action was triggered.
     */

    /**
     * Get actions associated with given gesture type.
     * @method jibo.face.views.Component#getActions
     * @param {jibo.face.views.GESTURE} [gesture = tap] - Type of gesture the actions ae associated with.
     * @return {jibo.face.views.ActionData[]} Array of actions.
     */

    /**
     * Returns `true` if there are actions associated with given gesture type.
     * @method jibo.face.views.Component#hasActions
     * @param {jibo.face.views.GESTURE} [gesture = tap] - Gesture actions related to.
     * @return {boolean} `true` if actions found for given gesture type.
     */

    /**
     * Turn interactivity on and off.
     * @method jibo.face.views.Component#lockInput
     * @param {Boolean} flag - Flag to turn interactivity on or off.
     */