Package | feathers.controls |
Class | public class StackScreenNavigatorItem |
Inheritance | StackScreenNavigatorItem Object |
Implements | feathers.controls.supportClasses.IScreenNavigatorItem |
Product Version : | Feathers 2.1.0 |
StackScreenNavigator
component.
The following example creates a new
StackScreenNavigatorItem
using the
SettingsScreen
class to instantiate the screen instance.
When the screen is shown, its settings
property will be set.
When the screen instance dispatches the
SettingsScreen.SHOW_ADVANCED_SETTINGS
event, the
StackScreenNavigator
will push a screen with the ID
"advancedSettings"
onto its stack. When the screen instance
dispatches Event.COMPLETE
, the StackScreenNavigator
will pop the screen instance from its stack.
var settingsData:Object = { volume: 0.8, difficulty: "hard" }; var item:StackScreenNavigatorItem = new StackScreenNavigatorItem( SettingsScreen ); item.properties.settings = settingsData; item.setScreenIDForPushEvent( SettingsScreen.SHOW_ADVANCED_SETTINGS, "advancedSettings" ); item.addPopEvent( Event.COMPLETE ); navigator.addScreen( "settings", item );
See also
Property | Defined By | ||
---|---|---|---|
canDispose : Boolean [read-only]
Determines if a display object returned by getScreen()
can be disposed or not when a screen is no longer active. | StackScreenNavigatorItem | ||
popEvents : Vector.<String>
A list of events that will cause the screen navigator to pop this
screen off the top of the stack. | StackScreenNavigatorItem | ||
popToRootEvents : Vector.<String>
A list of events that will cause the screen navigator to clear its
stack and show the first screen added to the stack. | StackScreenNavigatorItem | ||
popTransition : Function
A custom pop transition for this screen only. | StackScreenNavigatorItem | ||
properties : Object
A set of key-value pairs representing properties to be set on the
screen when it is shown. | StackScreenNavigatorItem | ||
pushEvents : Object
A set of key-value pairs representing actions that should be
triggered when events are dispatched by the screen when it is shown. | StackScreenNavigatorItem | ||
pushTransition : Function
A custom push transition for this screen only. | StackScreenNavigatorItem | ||
replaceEvents : Object
A set of key-value pairs representing actions that should be
triggered when events are dispatched by the screen when it is shown. | StackScreenNavigatorItem | ||
screen : Object
The screen to be displayed by the ScreenNavigator. | StackScreenNavigatorItem | ||
transitionDelayEvent : String
An optional event that the screen will dispatch when it's ready for
the transition to start. | StackScreenNavigatorItem |
Method | Defined By | ||
---|---|---|---|
StackScreenNavigatorItem(screen:Object = null, pushEvents:Object = null, popEvent:String = null, properties:Object = null)
Constructor. | StackScreenNavigatorItem | ||
addPopEvent(eventType:String):void
Specifies an event dispatched by the screen that will cause the
StackScreenNavigator to pop the screen off the top of
the stack and return to the previous screen. | StackScreenNavigatorItem | ||
addPopToRootEvent(eventType:String):void
Specifies an event dispatched by the screen that will cause the
StackScreenNavigator to pop the screen off the top of
the stack and return to the previous screen. | StackScreenNavigatorItem | ||
clearPushEvent(eventType:String):void
Cancels the "push" action previously registered to be triggered when
the screen dispatches an event. | StackScreenNavigatorItem | ||
clearReplaceEvent(eventType:String):void
Cancels the "replace" action previously registered to be triggered
when the screen dispatches an event. | StackScreenNavigatorItem | ||
getScreen():DisplayObject
Returns a display object instance of this screen. | StackScreenNavigatorItem | ||
removePopEvent(eventType:String):void
Removes an event that would cause the StackScreenNavigator
to remove this screen from the top of the stack. | StackScreenNavigatorItem | ||
removePopToRootEvent(eventType:String):void
Removes an event that would have cause the StackScreenNavigator
to clear its stack to show the first screen added to the stack. | StackScreenNavigatorItem | ||
setFunctionForPushEvent(eventType:String, action:Function):void
Specifies a function to call when an event is dispatched by the
screen. | StackScreenNavigatorItem | ||
setScreenIDForPushEvent(eventType:String, screenID:String):void
Specifies another screen to push on the stack when an event is
dispatched by this screen. | StackScreenNavigatorItem | ||
setScreenIDForReplaceEvent(eventType:String, screenID:String):void
Specifies another screen to replace this screen on the top of the
stack when an event is dispatched by this screen. | StackScreenNavigatorItem |
canDispose | property |
canDispose:Boolean
[read-only]
Determines if a display object returned by getScreen()
can be disposed or not when a screen is no longer active.
public function get canDispose():Boolean
popEvents | property |
popEvents:Vector.<String>
A list of events that will cause the screen navigator to pop this screen off the top of the stack.
public function get popEvents():Vector.<String>
public function set popEvents(value:Vector.<String>):void
See also
popToRootEvents | property |
popToRootEvents:Vector.<String>
A list of events that will cause the screen navigator to clear its stack and show the first screen added to the stack.
public function get popToRootEvents():Vector.<String>
public function set popToRootEvents(value:Vector.<String>):void
See also
popTransition | property |
popTransition:Function
A custom pop transition for this screen only. If null
,
the default popTransition
defined by the
StackScreenNavigator
will be used.
In the following example, the screen navigator item is given a pop transition:
item.popTransition = Slide.createSlideRightTransition();
A number of animated transitions may be found in the feathers.motion package. However, you are not limited to only these transitions. It's possible to create custom transitions too.
The function should have the following signature:
function(oldScreen:DisplayObject, newScreen:DisplayObject, completeCallback:Function):void
Either of the oldScreen
and newScreen
arguments may be null
, but never both. The
oldScreen
argument will be null
when the
first screen is displayed or when a new screen is displayed after
clearing the screen. The newScreen
argument will
be null when clearing the screen.
The completeCallback
function must be called
when the transition effect finishes. This callback indicate to the
screen navigator that the transition has finished. This function has
the following signature:
function(cancelTransition:Boolean = false):void
The first argument defaults to false
, meaning that
the transition completed successfully. In most cases, this callback
may be called without arguments. If a transition is cancelled before
completion (perhaps through some kind of user interaction), and the
previous screen should be restored, pass true
as the
first argument to the callback to inform the screen navigator that
the transition is cancelled.
The default value is null
.
public function get popTransition():Function
public function set popTransition(value:Function):void
See also
properties | property |
properties:Object
A set of key-value pairs representing properties to be set on the screen when it is shown. A pair's key is the name of the screen's property, and a pair's value is the value to be passed to the screen's property.
public function get properties():Object
public function set properties(value:Object):void
pushEvents | property |
pushEvents:Object
A set of key-value pairs representing actions that should be
triggered when events are dispatched by the screen when it is shown.
A pair's key is the event type to listen for (or the property name of
an ISignal
instance), and a pair's value is one of two
possible types. When this event is dispatched, and a pair's value
is a String
, the StackScreenNavigator
will
show another screen with an ID equal to the string value. When this
event is dispatched, and the pair's value is a Function
,
the function will be called as if it were a listener for the event.
public function get pushEvents():Object
public function set pushEvents(value:Object):void
See also
pushTransition | property |
pushTransition:Function
A custom push transition for this screen only. If null
,
the default pushTransition
defined by the
StackScreenNavigator
will be used.
In the following example, the screen navigator item is given a push transition:
item.pushTransition = Slide.createSlideLeftTransition();
A number of animated transitions may be found in the feathers.motion package. However, you are not limited to only these transitions. It's possible to create custom transitions too.
A custom transition function should have the following signature:
function(oldScreen:DisplayObject, newScreen:DisplayObject, completeCallback:Function):void
Either of the oldScreen
and newScreen
arguments may be null
, but never both. The
oldScreen
argument will be null
when the
first screen is displayed or when a new screen is displayed after
clearing the screen. The newScreen
argument will
be null when clearing the screen.
The completeCallback
function must be called
when the transition effect finishes. This callback indicate to the
screen navigator that the transition has finished. This function has
the following signature:
function(cancelTransition:Boolean = false):void
The first argument defaults to false
, meaning that
the transition completed successfully. In most cases, this callback
may be called without arguments. If a transition is cancelled before
completion (perhaps through some kind of user interaction), and the
previous screen should be restored, pass true
as the
first argument to the callback to inform the screen navigator that
the transition is cancelled.
The default value is null
.
public function get pushTransition():Function
public function set pushTransition(value:Function):void
See also
replaceEvents | property |
replaceEvents:Object
A set of key-value pairs representing actions that should be
triggered when events are dispatched by the screen when it is shown.
A pair's key is the event type to listen for (or the property name of
an ISignal
instance), and a pair's value is a
String
that is the ID of another screen that will
replace the currently active screen.
public function get replaceEvents():Object
public function set replaceEvents(value:Object):void
See also
screen | property |
screen:Object
The screen to be displayed by the ScreenNavigator
. It
may be one of several possible types:
Class
that may be instantiated to create a DisplayObject
Function
that returns a DisplayObject
DisplayObject
that is already instantiatedIf the screen is a Class
or a Function
,
a new instance of the screen will be instantiated every time that it
is shown by the ScreenNavigator
. The screen's state
will not be saved automatically. The screen's state may be saved in
properties
, if needed.
If the screen is a DisplayObject
, the same instance
will be reused every time that it is shown by the
ScreenNavigator
When the screen is shown again, its
state will remain the same as when it was previously hidden. However,
the screen will also be kept in memory even when it isn't visible,
limiting the resources that are available for other screens.
The default value is null
.
public function get screen():Object
public function set screen(value:Object):void
transitionDelayEvent | property |
transitionDelayEvent:String
An optional event that the screen will dispatch when it's ready for
the transition to start. If null
, the transition will
start immediately.
Useful for loading assets or doing other long tasks to prepare the screen before it is shown. It is recommended to display some kind of progress indicator over the previous screen during this delay to ensure that users don't get confused and think that the app has frozen.
public function get transitionDelayEvent():String
public function set transitionDelayEvent(value:String):void
StackScreenNavigatorItem | () | Constructor |
public function StackScreenNavigatorItem(screen:Object = null, pushEvents:Object = null, popEvent:String = null, properties:Object = null)
Constructor.
Parametersscreen:Object (default = null ) — The screen to display. Must be a Class , Function , or Starling display object.
| |
pushEvents:Object (default = null ) — The screen navigator push a new screen when these events are dispatched.
| |
popEvent:String (default = null ) — An event that pops the screen from the top of the stack.
| |
properties:Object (default = null ) — A set of key-value pairs to pass to the screen when it is shown.
|
addPopEvent | () | method |
public function addPopEvent(eventType:String):void
Specifies an event dispatched by the screen that will cause the
StackScreenNavigator
to pop the screen off the top of
the stack and return to the previous screen.
If the screen is currently being displayed by a
StackScreenNavigator
, and you call
addPopEvent()
on the StackScreenNavigatorItem
,
the StackScreenNavigator
won't listen for the event
until the next time that the screen is shown.
Parameters
eventType:String |
See also
addPopToRootEvent | () | method |
public function addPopToRootEvent(eventType:String):void
Specifies an event dispatched by the screen that will cause the
StackScreenNavigator
to pop the screen off the top of
the stack and return to the previous screen.
If the screen is currently being displayed by a
StackScreenNavigator
, and you call
addPopToRootEvent()
on the StackScreenNavigatorItem
,
the StackScreenNavigator
won't listen for the event
until the next time that the screen is shown.
Parameters
eventType:String |
See also
clearPushEvent | () | method |
public function clearPushEvent(eventType:String):void
Cancels the "push" action previously registered to be triggered when the screen dispatches an event.
Parameters
eventType:String |
See also
clearReplaceEvent | () | method |
public function clearReplaceEvent(eventType:String):void
Cancels the "replace" action previously registered to be triggered when the screen dispatches an event.
Parameters
eventType:String |
See also
getScreen | () | method |
public function getScreen():DisplayObject
Returns a display object instance of this screen.
ReturnsDisplayObject |
removePopEvent | () | method |
public function removePopEvent(eventType:String):void
Removes an event that would cause the StackScreenNavigator
to remove this screen from the top of the stack.
If the screen is currently being displayed by a
StackScreenNavigator
, and you call
removePopEvent()
on the StackScreenNavigatorItem
,
the StackScreenNavigator
won't remove the listener for
the event on the currently displayed screen. The event listener won't
be added the next time that the screen is shown.
Parameters
eventType:String |
See also
removePopToRootEvent | () | method |
public function removePopToRootEvent(eventType:String):void
Removes an event that would have cause the StackScreenNavigator
to clear its stack to show the first screen added to the stack.
If the screen is currently being displayed by a
StackScreenNavigator
, and you call
removePopEvent()
on the StackScreenNavigatorItem
,
the StackScreenNavigator
won't remove the listener for
the event on the currently displayed screen. The event listener won't
be added the next time that the screen is shown.
Parameters
eventType:String |
See also
setFunctionForPushEvent | () | method |
public function setFunctionForPushEvent(eventType:String, action:Function):void
Specifies a function to call when an event is dispatched by the screen.
If the screen is currently being displayed by a
StackScreenNavigator
, and you call
setFunctionForPushEvent()
on the StackScreenNavigatorItem
,
the StackScreenNavigator
won't listen for the event
until the next time that the screen is shown.
Parameters
eventType:String | |
action:Function |
See also
setScreenIDForPushEvent | () | method |
public function setScreenIDForPushEvent(eventType:String, screenID:String):void
Specifies another screen to push on the stack when an event is
dispatched by this screen. The other screen should be specified by
its ID that was registered with a call to addScreen()
on
the StackScreenNavigator
.
If the screen is currently being displayed by a
StackScreenNavigator
, and you call
setScreenIDForPushEvent()
on the StackScreenNavigatorItem
,
the StackScreenNavigator
won't listen for the event
until the next time that the screen is shown.
Parameters
eventType:String | |
screenID:String |
See also
setScreenIDForReplaceEvent | () | method |
public function setScreenIDForReplaceEvent(eventType:String, screenID:String):void
Specifies another screen to replace this screen on the top of the
stack when an event is dispatched by this screen. The other screen
should be specified by its ID that was registered with a call to
addScreen()
on the StackScreenNavigator
.
If the screen is currently being displayed by a
StackScreenNavigator
, and you call
setScreenIDForPushEvent()
on the StackScreenNavigatorItem
,
the StackScreenNavigator
won't listen for the event
until the next time that the screen is shown.
Parameters
eventType:String | |
screenID:String |
See also