com.softwareag.mobile.runtime.toolkit.ui.controller

Class TransitionStackController

java.lang.Object

com.softwareag.mobile.runtime.toolkit.ui.controller.AbstractViewController

com.softwareag.mobile.runtime.toolkit.ui.controller.TransitionStackController

All Implemented Interfaces:

IDialogDelegate, IController, IResourceController, IViewController

public class TransitionStackController
extends AbstractViewController

Use TransitionStackController to easily create workflows in your application.

The TransitionStackController manages a stack of AbstractViewController implementations and provides a set of methods to automatically handle transitions between the view controllers in it's stack hierarchy. To transition from one AbstractViewController to another AbstractViewController, just use pushViewController(AbstractViewController) or popViewController(), etc.

A TransitionStackController itself is also an AbstractViewController subclass. This enables you to nest TransitionStackControllers into another, for example to create sub workflows. By using popToRootViewController() you can always go back to the first AbstractViewController of the top TransitionStackController in your stack hierarchy.

Use AbstractViewController.getTransitionStackController() to get the TransitionStackController managing the view controller. In an AbstractViewController implementation use this TransitionStackController to transition to another AbstractViewController.

When transitioning between two AbstractViewControllers, TransitionStackController uses the IViewController interface to notify AbstractViewControllers about the current state of it's transition. When transitioning a AbstractViewController on to the screen, IViewController.onTransitionTo() will be called on the AbstractViewController that is about to appear on screen. The AbstractViewController transitioned off the screen will get a IViewController.onTransitionFrom() notification. This way AbstractViewController implementations can execute whatever logic needed before tranistion on or off the screen. Typically you customize the view of an AbstractViewController before displayed or save the state of a view for later recovery.

Version:

9.7.0.0000-0116

Constructor Summary

Constructors

Constructor and Description
TransitionStackController(AbstractViewController rootViewController) Creates a new TransitionStackController with the given AbstractViewController as its root.
TransitionStackController(AbstractViewController rootViewController, int pane, int transition) Creates a new TransitionStackController with the given AbstractViewController as its root.

Method Summary

Methods

Modifier and Type	Method and Description
void	addBackButton() This method is called to creat and add a back button as part of the IViewController implementation.
com.softwareag.mobile.runtime.nui.nUIViewDisplay	createView() Creates a new instance of the nUIViewDisplay subclass managed by this IViewController implementation.
AbstractViewController	getTopViewController() Returns the top AbstractViewControllers of the stack hierarchy.
java.util.Vector	getViewControllers() Returns the full stack hierarchy of AbstractViewControllers
com.softwareag.mobile.runtime.nui.nUIViewDisplay	getViewDisplay() Returns the nUIViewDisplay instance managed by this IViewController implementation.
boolean	hidesBackButton() Returns true if this IViewController implementation hides the back button even if it is not the first view controller in the TransitionStackController stack hierarchy.
void	onHideView() This methods gets called when the view becomes hidden on a pane.
void	onShowView() This method is called when the view becomes visible on a pane.
void	onTransitionFrom() This method is called right before the view is transitioned off the screen by a TransitionStackController.
void	onTransitionTo() This method is called right after the view is created and before it is transitioned on to the screen by a TransitionStackController.
void	popToRootViewController() Removes all AbstractViewController from the stack hierarchy back to the root (first) AbstractViewController in the stack.
void	popToRootViewController(boolean animated) Removes all AbstractViewController from the stack hierarchy back to the root (first) AbstractViewController in the stack.
void	popToRootViewController(int transition) Removes all AbstractViewController from the stack hierarchy back to the root (first) AbstractViewController in the stack.
void	popToViewController(AbstractViewController vc) Removes all AbstractViewController from the stack hierarchy back to the AbstractViewController instance provided as argument.
void	popToViewController(AbstractViewController vc, boolean animated) Removes all AbstractViewController from the stack hierarchy back to the AbstractViewController instance provided as argument.
void	popToViewController(AbstractViewController vc, int transition) Removes all AbstractViewController from the stack hierarchy back to the AbstractViewController instance provided as argument.
void	popViewController() Removes the top AbstractViewController from the stack hierarchy.
void	popViewController(boolean animated) Removes the top AbstractViewController from the stack hierarchy.
void	popViewController(int transition) Removes the top AbstractViewController from the stack hierarchy.
void	pushViewController(AbstractViewController controller) Pushes an AbstractViewController on top of the stack hierarchy and transitions it on the screen.
void	pushViewController(AbstractViewController controller, boolean animated) Pushes an AbstractViewController on top of the stack hierarchy.
void	pushViewController(AbstractViewController controller, int transition) Pushes an AbstractViewController on top of the stack hierarchy and transitions it on the screen using a given transition type.
void	resetView() Removes reference to the view and destroys it.
void	setWindowPane(int pane) The integer identifier of the pane will be set automatically using this method by TransitionStackController or by AbstractApplicationController.

Methods inherited from class com.softwareag.mobile.runtime.toolkit.ui.controller.AbstractViewController

getBackButtonText, getDefaultPlaceHolderImage, getMappedTransitionStackControllers, getTransitionStackController, getWindowPane, isVisible, loadImage, loadImage, loadImage, loadWWWResource, onAlertDialogButtonPressed, onBackButtonEvent, resizeImage, setVisible, stackTransition, transition

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TransitionStackController

public TransitionStackController(AbstractViewController rootViewController)

Creates a new TransitionStackController with the given AbstractViewController as its root. When calling popToRootViewController(), TransitionStackController will transition back to given root AbstractViewController.

Parameters:

rootViewController - the root AbstractViewController of the TransitionStackControllers stack hierarchy.

TransitionStackController

public TransitionStackController(AbstractViewController rootViewController,
                         int pane,
                         int transition)

Creates a new TransitionStackController with the given AbstractViewController as its root. By providing a pane ID, the TransitionStackController will be do all transitions on the pane provided. By specifying a transition type you can also control how the AbstractViewController is transitioned on the pane provided.

Parameters:

rootViewController - the root AbstractViewController of the TransitionStackControllers stack hierarchy.

pane - the ID of the pane the TransitionStackController will use for transitions.

transition - the transition type to use for the initial transition on the pane

Method Detail

pushViewController

public void pushViewController(AbstractViewController controller)

Pushes an AbstractViewController on top of the stack hierarchy and transitions it on the screen. If it is the first AbstractViewController on the stack, the nUIController.TRANSITION_APPEAR will be used for transitioning, otherwise TransitionStackController will automatically choose the best transition based on platform and app directionality. The AbstractViewControllercurrently on the screen will be transitioned off.

After the AbstractViewController and its view are created, but before it is transitioned to the screen, IViewController.onTransitionTo() will be called. For the AbstractViewController transitioned off IViewController.onTransitionFrom() is called just before the transition.

Parameters:

controller - the new AbstractViewController to transition on screen.

pushViewController

public void pushViewController(AbstractViewController controller,
                      int transition)

Pushes an AbstractViewController on top of the stack hierarchy and transitions it on the screen using a given transition type. Use this method to overwrite the default transitioning sryle of pushViewController(AbstractViewController).

Parameters:

controller - the new AbstractViewController to transition on screen.

transition - the ID of the transition to use. Check nUIController constants for supported transition styles and it's IDs.

See Also:

#pushViewController(AbstractViewController)}

pushViewController

public void pushViewController(AbstractViewController controller,
                      boolean animated)

Pushes an AbstractViewController on top of the stack hierarchy. By setting the animated argument to false, always nUIController.TRANSITION_APPEAR will be used, if true TransitionStackController will choose the transition type automatically based on the platform and app directionality. This method overwrites the default transition style of pushViewController(AbstractViewController)

Parameters:

controller - the new AbstractViewController to transition on screen.

animated - true if the transition should animate, false if the AbstractViewController should just appear on screen without any animation

See Also:

#pushViewController(AbstractViewController)}

popViewController

public void popViewController()

Removes the top AbstractViewController from the stack hierarchy. The top AbstractViewController is most likely the one currently visible on the screen. When removed from the stack hierarchy, the popped AbstractViewController will be automatically transitioned off and the previous AbstractViewController in the stack hierarchy will be transitioned back on to the screen.

When popped from stack hierarchy and transitioned off the screen IViewControlleronTransitionFrom() is called just before the transition.

Using this method, the transition will be chosen automatically depending on the platform and the app directionality.

popViewController

public void popViewController(int transition)

Removes the top AbstractViewController from the stack hierarchy. Use this method to overwrite the default transition style used by popViewController().

Parameters:

transition - the ID of the transition to use. Check nUIController constants for supported transition styles and it's IDs.

See Also:

#popViewController()}

popViewController

public void popViewController(boolean animated)

Removes the top AbstractViewController from the stack hierarchy. Using this method, the transition will be chosen automatically depending on the platform and the app directionality if the animated argument is true. If not using animation, nUIController.TRANSITION_APPEAR will be used.

Parameters:

animated - true if the transition should animate, false if the AbstractViewController should just appear on screen without any animation

See Also:

#popViewController()}

popToRootViewController

public void popToRootViewController()

Removes all AbstractViewController from the stack hierarchy back to the root (first) AbstractViewController in the stack. When removed from the stack hierarchy, the currently visible AbstractViewController will be automatically transitioned off and the root AbstractViewController in the stack hierarchy will be transitioned back on to the screen. All AbstractViewController in between the current and root AbstractViewController will be removed from stack hierarchy.

When popped from stack hierarchy and transitioned off the screen IViewControlleronTransitionFrom() is called for the current top AbstractViewController just before the transition. For the root AbstractViewController that will be transitioned back on to the screen IViewController.onTransitionTo() will be called.

Using this method, the transition will be chosen automatically depending on the platform and the app directionality.

popToRootViewController

public void popToRootViewController(int transition)

Removes all AbstractViewController from the stack hierarchy back to the root (first) AbstractViewController in the stack. Use this method to overwrite the default transition style of popToRootViewController().

Parameters:

transition - the ID of the transition to use. Check nUIController constants for supported transition styles and it's IDs.

See Also:

#popToRootViewController()}

popToRootViewController

public void popToRootViewController(boolean animated)

Removes all AbstractViewController from the stack hierarchy back to the root (first) AbstractViewController in the stack. Using this method, the transition will be chosen automatically depending on the platform and the app directionality if the animated argument is true. If not using animation, nUIController.TRANSITION_APPEAR will be used.

Parameters:

animated - true if the transition should animate, false if the AbstractViewController should just appear on screen without any animation

See Also:

#popToRootViewController()}

popToViewController

public void popToViewController(AbstractViewController vc)

Removes all AbstractViewController from the stack hierarchy back to the AbstractViewController instance provided as argument. If vc is not in the stack hierarchy, TransitionStackController will just skip and do nothing.

When removed from the stack hierarchy, the currently visible AbstractViewController will be automatically transitioned off and the given AbstractViewController will be transitioned back on to the screen. All AbstractViewController in between the current and given AbstractViewController will be removed from stack hierarchy.

When popped from stack hierarchy and transitioned off the screen IViewControlleronTransitionFrom() is called for the current top AbstractViewController just before the transition. For the root AbstractViewController that will be transitioned back on to the screen IViewController.onTransitionTo() will be called.

Using this method, the transition will be chosen automatically depending on the platform and the app directionality.

Parameters:

vc - the AbstractViewController instance of the stack hierarchy to transition to.

popToViewController

public void popToViewController(AbstractViewController vc,
                       int transition)

Removes all AbstractViewController from the stack hierarchy back to the AbstractViewController instance provided as argument. Use this method to overwrite the default transition style of popToViewController(AbstractViewController)

Parameters:

vc - the AbstractViewController instance of the stack hierarchy to transition to.

transition - the ID of the transition to use. Check nUIController constants for supported transition styles and it's IDs.

See Also:

#popToViewController(AbstractViewController)}

popToViewController

public void popToViewController(AbstractViewController vc,
                       boolean animated)

Removes all AbstractViewController from the stack hierarchy back to the AbstractViewController instance provided as argument. Using this method, the transition will be chosen automatically depending on the platform and the app directionality if the animated argument is true. If not using animation, nUIController.TRANSITION_APPEAR will be used.

Parameters:

vc - the AbstractViewController instance of the stack hierarchy to transition to.

animated - true if the transition should animate, false if the AbstractViewController should just appear on screen without any animation

See Also:

#popToViewController(AbstractViewController)}

getViewControllers

public java.util.Vector getViewControllers()

Returns the full stack hierarchy of AbstractViewControllers

Returns:

all AbstractViewController in the stack hierarchy

getTopViewController

public AbstractViewController getTopViewController()

Returns the top AbstractViewControllers of the stack hierarchy. This is the AbstractViewController usually visible on the sreen.

Returns:

the top AbstractViewController in the stack hierarchy

getViewDisplay

public com.softwareag.mobile.runtime.nui.nUIViewDisplay getViewDisplay()

Description copied from interface: IViewController

Returns the nUIViewDisplay instance managed by this IViewController implementation.

Returns:

current nUIViewDisplay instance associated with this controller.

See Also:

#createView()}

createView

public com.softwareag.mobile.runtime.nui.nUIViewDisplay createView()

Description copied from interface: IViewController

Creates a new instance of the nUIViewDisplay subclass managed by this IViewController implementation. Overwrite this method if you want to be notified when a view is created or if you need to do any changes programmatically at runtime.

If you want to get the IViewController managing a given view, use AbstractApplicationController#getViewController(nUIViewDisplay)

Returns:

the view created and associated with IViewController

resetView

public void resetView()

Description copied from interface: IViewController

Removes reference to the view and destroys it.

Specified by:

resetView in interface IViewController

Overrides:

resetView in class AbstractViewController

See Also:

#createView()}

onTransitionTo

public void onTransitionTo()

Description copied from interface: IViewController

This method is called right after the view is created and before it is transitioned on to the screen by a TransitionStackController. Overwrite to add, remove or customize controls programmatically or load data in the background. This is the entry point for all business logic that needs to be executed for a view.

Specified by:

onTransitionTo in interface IViewController

Overrides:

onTransitionTo in class AbstractViewController

See Also:

TransitionStackController}

onTransitionFrom

public void onTransitionFrom()

Description copied from interface: IViewController

This method is called right before the view is transitioned off the screen by a TransitionStackController. Overwrite to save data or execute any logic needed right before the view will be removed.

Specified by:

onTransitionFrom in interface IViewController

Overrides:

onTransitionFrom in class AbstractViewController

See Also:

TransitionStackController}

onShowView

public void onShowView()

Description copied from interface: IViewController

This method is called when the view becomes visible on a pane. AbstractApplicationController#showPane(int) triggers this call.

Specified by:

onShowView in interface IViewController

Overrides:

onShowView in class AbstractViewController

onHideView

public void onHideView()

Description copied from interface: IViewController

This methods gets called when the view becomes hidden on a pane. AbstractApplicationController#hidePane(int) triggers this call.

Specified by:

onHideView in interface IViewController

Overrides:

onHideView in class AbstractViewController

hidesBackButton

public boolean hidesBackButton()

Description copied from interface: IViewController

Returns true if this IViewController implementation hides the back button even if it is not the first view controller in the TransitionStackController stack hierarchy.

Overwrite to change the default behavior of adding back buttons. To customize the back button overwrite IViewController.addBackButton(). If you are not using TransitionStackController, use IViewController.addBackButton() to add back buttons programmatically.

Returns:

true if the back button should not be added

See Also:

TransitionStackController}

addBackButton

public void addBackButton()

Description copied from interface: IViewController

This method is called to creat and add a back button as part of the IViewController implementation. The default implementation in AbstractViewController, based on TransitionStackController, uses the header text of the previous AbstractViewController in the stack hierarchy. If there is no header text to be used, BACKBUTTON_DEFAULT value from the language text resources will be loaded and used.

setWindowPane

public void setWindowPane(int pane)

Description copied from interface: IViewController

The integer identifier of the pane will be set automatically using this method by TransitionStackController or by AbstractApplicationController. This value is accessible by IController.getWindowPane()

Specified by:

setWindowPane in interface IViewController

Overrides:

setWindowPane in class AbstractViewController

Parameters:

pane - integer identifier of pane defined in Constants