[TIMOB-12294] BlackBerry: Implement App-Level Navigation

As a developer I need the ability to design the navigation between the various components (windows) in my application in a way that is native to the underlying platform.

Concepts

Scenes

A scene on BlackBerry is the "root" pane displayed in the application's main window. Only one scene may be presented at any given time. While Cascades provides no "stack" concept, we do provide our own as the SceneManager and Scene classes. This allows us to push or pop scenes as needed when developers present Windows, Navigation Groups, and TabGroups. There are various Scene sub-classes for each BlackBerry AbstractPane type. The scenes help coordinate events and presentation between Cascades and the scene manager.

Panes

A pane in Cascades act as the "root" component in the UI hierarchy. There are three pane types: Page, Navigation, and Tabbed. Page panes present a single control (content). A set of action items can also be associated with the page and presented in the action bar. Page panes are also used in Navigation and Tabbed panes to display the "active" content. Navigation panes present a stack of page panes. New panes can be "pushed" on later "popped" off. A "back" button can be presented to allow the user to pop the top pane and navigate back to the previous pane. Only Page panes can be pushed onto a navigation stack. Tabbed panes presents a set of "tabs" that the user can switch between. The tabs can be used to either completely replace displayed content by setting new panes or to filter existing content in a single pane based on which tab is currently selected. Tabs may have content panes associated with them which will be presented when the tab is selected. Only Page and Navigation panes may be used as tab content.

Features

NavigationGroup

Navigation panes fit very closely to the existing NavigationGroup API used in iOS and MobileWeb Titanium. A BlackBerry flavor of this API would be a good start for exposing the navigation pane concept to Titanium developers. One major difference with BlackBerry is navigation panes don't require inserting a navigation bar within the content UI. Any controls (ex: back button) are just appended into the action bar as action items. So the developer will not need to add the navigation group to a window.

TabGroup

The tabbed pane concept in BlackBerry best maps to the existing Titanium TabGroup. This is mostly implemented already in the BlackBerry Titanium port. The remaining work is to further implement common APIs and also expose BlackBerry specific features based on priorities and requirements. Currently each tab in the group uses a Page pane as its content. The root control for these pages is the container from the Window associated with the tab ("window" property). Tab changes switch the active Page pane and fires off the proper events (ex: focus, blur) to the affected windows and tabs. Supporting "filtering" style tab groups may eventually be supported. This will most likely exposing an property to set a window as the "active content" of the tab group. The developer can then use tab events (ex: focus) to update their UI (ex: filter data).

Windows

Windows best map to the Page pane concept on BlackBerry. A page pane will be presented as the new active scene whenever a window is opened. Panes on BlackBerry can only be "fullscreen" so windows cannot be sized or positioned like views.