Palm webOS

Commander Chain

Mojo provides a model for propagating commands through the application, stage, and scene controllers called the Commander Chain. The chain is an array of handlers, ordered like a stack. The handlers, or commanders, are put onto the chain in the order that they register themselves, and commands are propagated according to this order.

Commanders are registered implicitly by declaring a handleCommand method as a stage-assistant or scene-assistant method, or for dialogs, when instantiated. The framework always adds the App-Assistants to the end of the Stage-Controller chain at instantiation.

Commanders can register explicitly by calling the pushCommander method from either the stage controller or scene controller. The commander will be removed when the scene assistant is popped or the application is closed.

The chain is really a tree of chains (see Figure 4-14). There is a chain for each stage controller, and within each stage there is a chain for each scene controller. Commands are propagated starting with the most recent commander registered in the active scene controller’s chain. After all commanders in the scene have been called, propagation continues with the most recent commander in the active stage controller chain through the rest of the chain. There are chains for each of the inactive stage controllers and scene controllers, but commands are not propagated to any inactive chains.

Figure 4-14. A Commander Chain propagation example

At any time, any commander can stop propagation by calling event.stopPropagation(). For example, a scene puts up a modal dialog box, so it’s implicitly added to the chain. It will have the opportunity to handle a back event and stop propagation before it gets back to the scene that pushed the dialog. If not, the stage controller would see the back gesture and pop the scene, which is not the desired user experience.

Commanders can always remove themselves from the chain by calling the removeCommander method of either StageController or SceneController. For example:

this.controller.removeCommander(this);

There are four types of events that propagate through the chain:

Mojo.Event.back

Indicates a back gesture.

Mojo.Event.forward

Indicates a forward gesture.

Mojo.Event.command

Is used for all menu commands.

Mojo.Event.commandEnable

Is used to enable a menu item dynamically.

Command and Command Enable events are both discussed in the section Menu Widgets. The former is used when a menu command is selected, and the latter when a menu is created for any menu item that includes the property commandEnable set to true. If any commander wants to inhibit the menu command, it can call event.preventDefault() to do so. The framework uses this to inhibit the Edit functions in the Application menu when anything other than a text field is in focus.

A common application of the Commander Chain is the consolidation of the setup and handling of the Application menu into the stage controller. An example of this consolidation using the News application is shown in the section Application menu.