Packagefeathers.controls
Classpublic class StackScreenNavigatorItem
InheritanceStackScreenNavigatorItem Inheritance Object
Implements feathers.controls.supportClasses.IScreenNavigatorItem

Product Version : Feathers 2.1.0

Data for an individual screen that will be displayed by a 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

How to use the Feathers StackScreenNavigator component
feathers.controls.StackScreenNavigator


Public Properties
 PropertyDefined 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
Public Methods
 MethodDefined 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
Property Detail
canDisposeproperty
canDispose:Boolean  [read-only]

Determines if a display object returned by getScreen() can be disposed or not when a screen is no longer active.


Implementation
    public function get canDispose():Boolean
popEventsproperty 
popEvents:Vector.<String>

A list of events that will cause the screen navigator to pop this screen off the top of the stack.


Implementation
    public function get popEvents():Vector.<String>
    public function set popEvents(value:Vector.<String>):void

See also

popToRootEventsproperty 
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.


Implementation
    public function get popToRootEvents():Vector.<String>
    public function set popToRootEvents(value:Vector.<String>):void

See also

popTransitionproperty 
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.


Implementation
    public function get popTransition():Function
    public function set popTransition(value:Function):void

See also

propertiesproperty 
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.


Implementation
    public function get properties():Object
    public function set properties(value:Object):void
pushEventsproperty 
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.


Implementation
    public function get pushEvents():Object
    public function set pushEvents(value:Object):void

See also

pushTransitionproperty 
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.


Implementation
    public function get pushTransition():Function
    public function set pushTransition(value:Function):void

See also

replaceEventsproperty 
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.


Implementation
    public function get replaceEvents():Object
    public function set replaceEvents(value:Object):void

See also

screenproperty 
screen:Object

The screen to be displayed by the ScreenNavigator. It may be one of several possible types:

If 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.


Implementation
    public function get screen():Object
    public function set screen(value:Object):void
transitionDelayEventproperty 
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.


Implementation
    public function get transitionDelayEvent():String
    public function set transitionDelayEvent(value:String):void
Constructor Detail
StackScreenNavigatorItem()Constructor
public function StackScreenNavigatorItem(screen:Object = null, pushEvents:Object = null, popEvent:String = null, properties:Object = null)

Constructor.

Parameters
screen: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.
Method Detail
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.

Returns
DisplayObject
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