forked from Jibo-Revival-Group/JiboOs
428 lines
17 KiB
JavaScript
428 lines
17 KiB
JavaScript
|
/**
|
||
|
|
* @interface jibo.face.views.View~ViewOptions
|
||
|
|
* @extends jibo.face.views.Component~ComponentOptions
|
||
|
|
* @description Interface - Configuration values for creating a View.
|
||
|
|
* @prop {String} [category] - Category of view.
|
||
|
|
* @prop {String} [soundSet] - Set of sounds for view sfx.
|
||
|
|
* @prop {Boolean} [ignoreSwipeDown] - Flag to block or enable swipe down gesture.
|
||
|
|
* @prop {Boolean} [transitionStageOnly] - If 'true' view transition apply to View's stage only,
|
||
|
|
* if 'false' possible for transition to be acted out by individual Components where applicable.
|
||
|
|
* @prop {Boolean | jibo.face.views.PauseOverlay#PauseOptions} [pause] - Determine if view will pause the view it is opening over.
|
||
|
|
* If 'true' will use default pause options, pass PauseOptions for custom values.
|
||
|
|
* @prop {Boolean} [pauseParent] - Deprecated.
|
||
|
|
* @prop {jibo.face.views.PauseOverlay#PauseOptions} [pauseOptions] - Deprecated.
|
||
|
|
* @prop {Boolean} [border] - Flag to turn screen border visibility true or false.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Handler for custom View transitions.
|
||
|
|
* @callback jibo.face.views.View~TransitionHandler
|
||
|
|
* @param {Function} done - Must call when transition is complete.
|
||
|
|
* @param {jibo.face.views.View} [view] View to apply the transition to.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @typedef jibo.face.views~STATE
|
||
|
|
* @description Static class with static members that describe possible states of the views.
|
||
|
|
* @prop INITIALIZED Intialize the data.
|
||
|
|
* @prop DATA_LOADED State set and emitted once initial data has been loaded and configurations set.
|
||
|
|
* @prop ASSETS_LOADED State set and emitted once initial assets have been loaded.
|
||
|
|
* @prop LOADED State set and emitted once loading is complete, at point of dispatch View should be ready for use.
|
||
|
|
* @prop OPENED State set and emitted once View has completed its opening transition.
|
||
|
|
* @prop CLOSED State set and emitted once View has completed its closing transition.
|
||
|
|
* @prop DESTROYED State set and emitted once View has been destroyed.
|
||
|
|
* @prop LOAD_ERROR Event emitted if there is a load error.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @typedef jibo.face.views~CATEGORY
|
||
|
|
* @description Static class with static members that describe possible categories of the views.
|
||
|
|
* @prop GUI Category for views that contain an interactive user interface.
|
||
|
|
* @prop DISPLAY Category for views that are primarily used for display and not for interfacing.
|
||
|
|
* @prop EYE Category for EyeView type views.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Base class for groupings of GUI elements on screen at once.
|
||
|
|
* Views are the unit which {@link jibo.face.views} acts upon.
|
||
|
|
*
|
||
|
|
* @class View
|
||
|
|
* @extends jibo.face.views.ComponentGroup
|
||
|
|
* @memberof jibo.face.views
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The default class identifier.
|
||
|
|
* Generally used to register the class.
|
||
|
|
* @name jibo.face.views.View.DEFAULT_TYPE
|
||
|
|
* @type {String}
|
||
|
|
* @readOnly
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Event dispatched when the View is going to close because of a 'back' command.
|
||
|
|
* Currently closing a View and going back to the previous view is triggered by a swipe down.
|
||
|
|
* @type {string}
|
||
|
|
* @name jibo.face.views.View#BACK
|
||
|
|
* @readOnly
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Option for setting custom transitions.
|
||
|
|
* Use with `View.defineTransitions` for transitions to be used when opening from or closing to an empty screen.
|
||
|
|
* @type {string}
|
||
|
|
* @name jibo.face.views.View.EMPTY
|
||
|
|
* @readOnly
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Option for setting custom transitions.
|
||
|
|
* Use with `View.defineTransitions` for transitions to be used when opening over a paused view or closing while being paused.
|
||
|
|
* @type {string}
|
||
|
|
* @name jibo.face.views.View.PAUSED
|
||
|
|
* @readOnly
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Reference to the paused View below this View.
|
||
|
|
* @name jibo.face.views.View#pausedParent
|
||
|
|
* @type {jibo.face.views.View}
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Overlay used when view is paused.
|
||
|
|
* @name jibo.face.views.View#pauseOverlay
|
||
|
|
* @type {jibo.face.views.PauseOverlay}
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Flag, if `true` the closure of the View on swipe down behavior will be setup.
|
||
|
|
* @name jibo.face.views.View#closeOnSwipeDown
|
||
|
|
* @type {boolean}
|
||
|
|
* @default true
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Flag that when `true` will pause, instead of closing and destroying, the current View when this View opens above it.
|
||
|
|
* Once this View finishes opening the previous View, which is now paused, is referenced here {@link jibo.face.views.View#pausedParent}
|
||
|
|
* @name jibo.face.views.View#willPauseParent
|
||
|
|
* @type {boolean}
|
||
|
|
* @default false
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Options applied to parent view when pausing.
|
||
|
|
* @name jibo.face.views.View#pauseOptions
|
||
|
|
* @type {jibo.face.views.PauseOverlay#PauseOptions}
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Set of sounds to use when triggering sfx connected to menu button clicks, view open transition, and view close transition.
|
||
|
|
*
|
||
|
|
* The global sound sets include:
|
||
|
|
* - `main` - Used for the eye view and the main menu.
|
||
|
|
* - `skill` - Default sound set for standard views.
|
||
|
|
* - `action` - Use for confirmation view overlays.
|
||
|
|
*
|
||
|
|
* The soundSet value is combined with the sound type to determine which sound to play.
|
||
|
|
* For example clicking a menu button will trigger a 'button' sfx, this is combined with the soundSet value to determine the sound id.
|
||
|
|
* So a clicking a button in a view with a soundSet of `skill` will play the sound with id `skill_button`.
|
||
|
|
*
|
||
|
|
* Example for Setting a view's soundSet value via the config:
|
||
|
|
* ```
|
||
|
|
* "viewConfig": {
|
||
|
|
* "type": "MenuView",
|
||
|
|
* "id": "confirmation_view",
|
||
|
|
* "soundSet": "action",
|
||
|
|
* ```
|
||
|
|
* @name jibo.face.views.View#soundSet
|
||
|
|
* @type {string}
|
||
|
|
* @default `skill`
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Flag to transition using only stage.
|
||
|
|
* If `true` prevents components from handling open and close individually.
|
||
|
|
* @name jibo.face.views.View#transitionStageOnly
|
||
|
|
* @type {boolean}
|
||
|
|
* @default false
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Flag, if `true` the screen border is made visible just before opening view.
|
||
|
|
* Must set before view opens to take effect.
|
||
|
|
* @name jibo.face.views.View#borderNeeded
|
||
|
|
* @type {boolean}
|
||
|
|
* @default true
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Specify a custom transition for either close or open, whichever is happening next.
|
||
|
|
* Can be set to a Function, in which case that Function will be used instead of the `open` or `close` methods,
|
||
|
|
* or set to a string, in which case that string will become the transition type checked by the `open` or `close` methods.
|
||
|
|
* @name jibo.face.views.View#transitionHandler
|
||
|
|
* @type {jibo.face.views.View~TransitionHandler | string}
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* View category, helps determine behavior and function expected from view.
|
||
|
|
* Category is not directly bound to `View.type`.
|
||
|
|
* @name jibo.face.views.View#_category
|
||
|
|
* @type {string}
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Reference to ViewState the View was created from.
|
||
|
|
* A View will may not always have a ViewState defined,
|
||
|
|
* reference to ViewState is made within applyState.
|
||
|
|
* @name jibo.face.views.View#_viewState
|
||
|
|
* @type {jibo.face.views.ViewState}
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Reference to loadAsset created by loader, kept for cleanup.
|
||
|
|
* @name jibo.face.views.View#_assetLoad
|
||
|
|
* @type {jibo.loader.AssetLoad}
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Tokens of assets loaded and cached by this loader.
|
||
|
|
* @name jibo.face.views.View#_loadedAssets
|
||
|
|
* @type {jibo.loader.AssetToken[]}
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Queue for assets that require loading.
|
||
|
|
* When _assetLoad completes a single load task queued asset are added to _assetLoad's load list.
|
||
|
|
* @name jibo.face.views.View#_assetLoadQueue
|
||
|
|
* @type {jibo.face.views~AssetDescriptor[]}
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* List of pending asset load requests.
|
||
|
|
* When _assetLoad completes asset load requests are checked,
|
||
|
|
* if requested assets have been loaded executes callback.
|
||
|
|
* @name jibo.face.views.View#_assetLoadRequests
|
||
|
|
* @type {any[]}
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Object used to store custom transitions, uses a specific structure to manage nested choices.
|
||
|
|
* @type {any}
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Get top most PIXI.Container of this View.
|
||
|
|
* @name jibo.face.views.View#stage
|
||
|
|
* @type {PIXI.Container}
|
||
|
|
* @readOnly
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The assets loaded by the View, these are returned from the loader as an Object using the asset id as keys.
|
||
|
|
* Assets available after the view has completed its load methods.
|
||
|
|
* @name jibo.face.views.View#assets
|
||
|
|
* @type {Object}
|
||
|
|
* @readOnly
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Type is equal to Class name.
|
||
|
|
* @name jibo.face.views.View#type
|
||
|
|
* @type {string}
|
||
|
|
* @readOnly
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The current state of view.
|
||
|
|
* Refer to documentation for valid states e.g. LOADED, OPENED, CLOSED
|
||
|
|
* @name jibo.face.views.View#state
|
||
|
|
* @return {String} Refer to the View static constants or ViewManager for valid values.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* View category, helps determine behavior and function expected from view.
|
||
|
|
* Category is not directly bound to `View.type`.
|
||
|
|
* @name jibo.face.views.View#category
|
||
|
|
* @type {string}
|
||
|
|
* @readOnly
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Construct View
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Method to acquire the source of data needed to setup the View.
|
||
|
|
* Once the data source is available calls internal methods to assign the data to the class appropriately.
|
||
|
|
* By default this method handles the loading of a configuration file, but could also be extended to get data from the KB, servers, or web services.
|
||
|
|
* @method jibo.face.views.View#loadData
|
||
|
|
* @param {Boolean} [loadAssetsOnComplete = true] - If `true` will call loadAssets() once data finishes loading.
|
||
|
|
* @protected
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* FOR OVERRIDE ONLY. DO NOT CALL.
|
||
|
|
*
|
||
|
|
* Loads view configuration if a configPath has been defined, but the viewConfig is undefined.
|
||
|
|
* @method jibo.face.views.View#loadConfig
|
||
|
|
* @returns {Promise<jibo.face.views.View>} Promise with View it was called from.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* FOR OVERRIDE ONLY. DO NOT CALL.
|
||
|
|
*
|
||
|
|
* Apply data once all required data has finished loading.
|
||
|
|
* Custom View classes can overrdie this class to manually create custom Components.
|
||
|
|
* @method jibo.face.views.View#applyData
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* FOR OVERRIDE ONLY. DO NOT CALL.
|
||
|
|
*
|
||
|
|
* All data and assets have finished loading, create the display and update the status.
|
||
|
|
* For classes that override View this is where a lot of the setup logic will go.
|
||
|
|
* @method jibo.face.views.View#loaded
|
||
|
|
* @protected
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Called when loaded process is completed and View is ready to become current.
|
||
|
|
* Calls ready on all child Components, which allows opportunity to do additional setup
|
||
|
|
* that may depend on other components or parent Components.
|
||
|
|
* @method jibo.face.views.View#ready
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* FOR OVERRIDE ONLY. DO NOT CALL.
|
||
|
|
*
|
||
|
|
* Pause the View and its Components.
|
||
|
|
* Pausing locks/unlocks the input and applies/removes a black overly to the stage.
|
||
|
|
* @method jibo.face.views.View#pause
|
||
|
|
* @param {Boolean} [flag = true] - Flag for pausing or un-pausing this View.
|
||
|
|
* @param {jibo.face.views.PauseOverlay#PauseOptions} [pauseOptions] - Options defining how the pause executes.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* FOR OVERRIDE ONLY. DO NOT CALL.
|
||
|
|
*
|
||
|
|
* Destroy the view, calls destroy on all child components first.
|
||
|
|
* @method jibo.face.views.View#destroy
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Load given asset descriptions.
|
||
|
|
* Callback executes once requested assets are available within the `View.assets`.
|
||
|
|
* @method jibo.face.views.View#addAssets
|
||
|
|
* @param {jibo.face.views~AssetDescriptor|jibo.face.views~AssetDescriptor[]|Object} assets
|
||
|
|
* The assets to load.
|
||
|
|
* @param {Function} [callback] - Called when requested asset are available in `View.assets`.
|
||
|
|
* If there is an error while loading callback is called with err
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Adds custom `open` and `close` transitions.
|
||
|
|
* Custom transitions to use when opening or closing from specific view types
|
||
|
|
* or certain states, such as an empty screen (`View.EMPTY`) or a paused view (`View.PAUSED`).
|
||
|
|
* @method jibo.face.views.View#addTransition
|
||
|
|
* @param {string} viewType - Type of view or state. Accepted states include `View.EMPTY` and `View.PAUSED`.
|
||
|
|
* @param {boolean} openFrom - If `true`, transitions will be used when opening from the given viewType. If `false`, when closing from that type.
|
||
|
|
* @param {jibo.face.views.View~TransitionHandler | string} [myTransition] - Handler for executing transition or transition type on owning view.
|
||
|
|
* A Function will be used instead of the `open` or `close` methods, and a string will be the transition type used by the View's `open` or `close` methods.
|
||
|
|
* @param {jibo.face.views.View~TransitionHandler | string} [theirTransition] - Handler or transition type used by matching view for their transition.
|
||
|
|
* If the owning view is closing then this will be set as the opening view's transition.
|
||
|
|
* @param {jibo.face.views~STACK_DIRECTION} [stackDirection] - Specifies the stack direction associated with the transition,
|
||
|
|
* if undefined does not take stack direction into account
|
||
|
|
* STACK_DIRECTION.ADD indicates view is being added to stack.
|
||
|
|
* STACK_DIRECTION.REMOVE indicates view is being removed.
|
||
|
|
* STACK_DIRECTION.SWAP indicates the views are being swapped and there is no change to the stack size.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Method to bubble actions up from Components.
|
||
|
|
* Actions pass through this method up to the ViewManager.
|
||
|
|
* By passing actions through the View the View can augment the action, supply additional parameters, etc.
|
||
|
|
* @method jibo.face.views.View#actionHandler
|
||
|
|
* @param {jibo.face.views.ActionData} action The action called. Contains string for type of action and data Object
|
||
|
|
* with any pertinent data dependent on action type.
|
||
|
|
* @param {jibo.face.views.Component} fromComponent The component that triggered the action (if applicable).
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Method to pass actions downward to Components.
|
||
|
|
* Passing actions through parent chain allows parents to interrupt and augment actions.
|
||
|
|
* @method jibo.face.views.View#actionEnactor
|
||
|
|
* @param {jibo.face.ActionData} action Contains string for type of action and data Object
|
||
|
|
* with any pertinent data dependent on action type.
|
||
|
|
* @return {boolean} Returns true if action is acted on by this View or any of its children.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Set up swipe down to close current view, if no other swipe actions were defined.
|
||
|
|
* This is a standard UX specification for Menus, but may want to be excluded in certain use cases.
|
||
|
|
* @method jibo.face.views.View#setupSwipeDownToClose
|
||
|
|
* @protected
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Apply default values for use by loader.
|
||
|
|
* @method jibo.face.views.View#setAssetDescriptorDefaults
|
||
|
|
* @param {jibo.face.views~AssetDescriptor} asset Description of asset.
|
||
|
|
* @return {jibo.face.views~AssetDescriptor} Description of asset.
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Adds asset to load queue if not already loaded or loading.
|
||
|
|
* @method jibo.face.views.View#addAssetToQueue
|
||
|
|
* @param {jibo.face.views~AssetDescriptor} asset - Asset to add to queue.
|
||
|
|
* @returns {boolean} `true` if asset was added to queue.
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Remove asset from manifest and `View.assets` and unload from cache.
|
||
|
|
* NOTE: Use carefully; removing shared assets can have adverse effects.
|
||
|
|
* @method jibo.face.views.View#removeAsset
|
||
|
|
* @param {jibo.face.views~AssetDescriptor} asset - Asset to remove.
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Remove asset from manifest and `View.assets` and unload from cache.
|
||
|
|
* NOTE: Use carefully; removing shared assets can have adverse effects.
|
||
|
|
* @method jibo.face.views.View#removeFromManifest
|
||
|
|
* @param {jibo.face.views~AssetDescriptor} asset - Asset descriptordescribing asset to remove
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Check if given assets exist in `View.assets`.
|
||
|
|
* @method jibo.face.views.View#checkForAssets
|
||
|
|
* @param {jibo.face.views~AssetDescriptor|jibo.face.views~AssetDescriptor[]|Object} assets
|
||
|
|
* The assets to check.
|
||
|
|
* @returns {boolean} `true` if all assets were found in `View.assets`.
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Remove assets from manifest and unload tokens if they do not exist in `View.assets`.
|
||
|
|
* @method jibo.face.views.View#removeMissingAssets
|
||
|
|
* @param {jibo.face.views~AssetDescriptor|jibo.face.views~AssetDescriptor[]|Object} assets
|
||
|
|
* The assets to check.
|
||
|
|
* @private
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Play sound, considering the View's sound set.
|
||
|
|
* @method jibo.face.views.View#playSound
|
||
|
|
* @param {string} soundType - Kind of sound to use ('button', 'enter', 'exit').
|
||
|
|
* Combined with with View's soundSet to create sound id, for example the skill button sound id is 'skill_button'.
|
||
|
|
* @private
|
||
|
|
*/
|