BlackBerry Java to BlackBerry 10 Cascades Porting Series – Part 5: User Interface

Cascades

In this part of the series on porting BlackBerry Java applications to BlackBerry 10 using Cascades, we’ll examine the user interface.. Let’s take a side by side look at the UI components in both frameworks.

The Cascades framework is a rich and powerful modern UI framework build on top of the Qt application framework. The UI can be developed in C/C++ or Qt Modeling Language (QML) or both.

Lets take a look at a sample HelloWorld application in both frameworks:

HelloWorld side-by-side. A label in both Java and Cascades

// MAIN: the setup
public static void main(String[] args)    
{
      HelloApp app = new HelloApp();
      app.enterEventDispatcher();

}
	// MAIN: the setup
Q_DECL_EXPORT int main
(int argc, char **argv)
{
   Application app(argc, argv);
   new HelloWorld(&app);
   return Application::exec();
}
// HELLO WORLD CLASS

public class HelloApp extends
   UiApplication {
public HelloApp () {
 HScreen scr = new HScreen();
  pushScreen( scr );
      }
	// HELLO WORLD CLASS

HelloWorld::HelloWorld 
(bb::cascades::Application *app)
: QObject(app)
{
    QmlDocument *qml = 
QmlDocument::create("asset:///main.qml")
.parent(this);

    // create root object for the UI
    AbstractPane *root = 
qml->createRootObject();
    app->setScene(root);
}
// SCREEN CLASS: THE UI

public class HScreen 
extends MainScreen {

  private LabelField lbl;
  public HScreen()
  {
    lbl = new   LabelField( "Welcome!" );

    add( lbl );
  }}	// QML Page : THE UI

Page {
    Container {
        layout: DockLayout {}
        Label {
            text: qsTr("Hello World")
}}}

Both frameworks start with the main application and the HelloWorld class. In the case of Java a screen gets pushed on the screen stack. In the case of Cascades a QML document gets associated with root UI object.

In Java, a Screen Class gets created by extending MainScreen and adding a LabelField to it. In Cascades a Page gets declared and a Label is placed inside a container as shown on the screen.

When embarking on porting any application that include the User Interface. It’s important to review the UI guidelines for both platforms.

The BlackBerry Java UI guidelines can be found at:
https://developer.blackberry.com/design/bb7/

The BlackBerry 10 UI guidelines can be found at:
https://developer.blackberry.com/design/bb10/

A note on Java UI

The BlackBerry Java Development Environment (JDE) or the Eclipse Plugin is used to develop applications for BlackBerry OS 7.1 or lower.

There are two main supported frameworks for creating user interfaces in Java:

  • MIDP UI APIs
  • BlackBerry UI APIs

For compliance, the MIDP APIs are included for porting apps from MIDP devices. The BlackBerry UI APIs target specifically BlackBerry development and are the main focus of this article.

Rendering in Java And Cascades UI Frameworks

In Java UI rendering is done in “widgets” using the paint() functions. Normally, a list of such “widgets” will represent your entire UI. The system will go through the entire set of “widgets” and ask them to draw themselves by calling the “paint()” method. The consequences of this implementation are as follows:

Customization: You can override the paint() method. This leads to inconsistency in the UI. This is in fact how many Java UI custom components are created. This is usually an advanced activity involving drawing lines, circles and rectangles to get the desired UI look and effect.
The end result is that each application can have completely different looking UI components that behave differently.
Side Effects: UI can block If the paint() method is slow or the developer implemented their own custom component and their own paint(), the system UI can block executing a slow paint() function in one of the widgets.
Performance: Overdraw For party covered or obscured widgets, the system first has to draw the entire widget and then overdraw several times. This results in performance penalty.

In Cascades, rendering is done differently. Unlike in Java where the application is part of the rendering loop a Cascades application only manages the UI tree. The Cascades Rendering engine (which executes on a separate thread) takes care of drawing the UI. The consequences of this implementation are as follows:

Customization: You cannot override the paint() method which leads to UI Consistency. Every Cascades component is carefully crafted. These components blend and flow together and were designed to be used together. No cascades component is an island in and of itself. Thus Cascades custom components are usually composed of other existing components.
Side Effects: UI cannot block. No more hour-glassing during rendering! Slow running application has no ability to block the UI. The speed of rendering depends on the complexity of the UI tree and the ability of the application to provide data to the renderer fast enough.
Performance: GPU optimizations UI engine can get a holistic view of the entire user interface. This results in many GPU texture and state optimizations.

For more information on the topic please see this blog post.

(http://devblog.blackberry.com/2012/09/cascades-custom-ui/)

Navigation:

Single Screen

Normally a single screen Java application would extend from MainScreen as in the HelloWorld sample provided. Similarly in Cascades a Page would get created with individual components added to it.

Screen Page
Image1 Image2

Stack of Screens

In traditional Java applications flow is maintained by adding and removing screens to/from the stack, which is owned by the main application. The equivalent to this on BlackBerry 10 is the Navigation pane where individual pages can be pushed and popped from a stack. For more information on Cascades Navigation Pane please see: http://developer.blackberry.com/cascades/reference/bb__cascades__navigationpane.html

Screen, MainScreen, FullScreen              NavigationPane
The screen transitions occur through push/pop from the screen stack

Navigation pane maintains a stack of screens

Tabs and Filtering content

In Java applications Tabs are used to display filtered content and are achieved with the PaneManagerModel. This can be achieved in Cascades using Segmented Control.

Cascades tabs allow the apps to change the flow of the application. In BlackBerry Java, this effect was achieved through the use of custom components.

PaneManagerModel, Pane, HorizontalTabTitleView, PaneView, PaneManagerView SegmentedControl
http://developer.blackberry.com/cascades
/reference/bb__cascades__segmentedcontrol.html
Custom Component implementing custom Toolbarhttp://docs.blackberry.com/en/developers/
deliverables/17965/Toolbars_6_0_1137042_11.jsp
Tabbed Panehttp://developer.blackberry.com/cascades
/reference/bb__cascades__tabbedpane.html

Layout

Java:

http://btsc.webapps.blackberry.com/btsc/fetch/2000/348583/800332/800505/800508/How_To_-_Create_tabbed_view_screens.html?nodeid=1357482&vernum=0

Cascades:

http://developer.blackberry.com/cascades/reference/user_interface_layouts.html

The following tables illustrate layout mapping of the most frequently used layouts.

In BlackBerry Java, the most common approach is to use combination of HorizontalFieldManager and VerticalFieldManager. This can be achieved in Cascades using the DockLayout.

FlowFieldManager Stack Layout default behavior
HorizontalFieldmanager Stack Layout with LayoutProperties
and spaceQuota
VerticalFieldManager Stack Layout with each component having
HorizontalAlignment.Center
Combination of Horizontal
and Vertical Field Managers
Dock Layout

AbsoluteLayout

AbsoluteFieldManager AbsoluteLayout

Menus:

The Java Menus documentation can be referenced at:

http://developer.blackberry.com/java/documentation/menu_items_1970228_11.html

The Cascades Menus can be reference at:

http://developer.blackberry.com/cascades/documentation/ui/navigation/menus.html

The most common way of interacting with content in BlackBerry Java was through the BlackBerry Menu (the hardware key). On BlackBerry 10, Cascades applications would use an action in the action menu to get the equivalent functionality.

BlackBerry Key Menu vs. BlackBerry 10 Action Menu

Menu (Screenshot) ActionSet

Application “Settings” Menu. [BlackBerry 10 Only]

A swipe-down menu is accessible on BlackBerry 10 for infrequently used actions such as settings, getting customer information, managing accounts or downloads etc…

N/A Menu class and ActionItem object

Context Menu

Context menu is a common BlackBerry specific method of acting upon an item in a specific context. This can be achieved on both platforms as illustrated below.

Context Menu contextActions

Custom Menu

In certain cases you might want to create a completely custom menu that makes sense for your application. This is possible in BlackBerry 10 using the MenuManager API.

Override keyDown and then
create a custom component to display on the screen.
MenuManager

Active Home Screen Elements

In BlackBerry Java, apps would normally change the icons and the icon descriptions to keep track of the application state. For more information on the APIs please see:

http://www.blackberry.com/developers/docs/7.1.0api/

In BlackBerry 10, apps would use Active Frames to update the status of an application. For more information of Active Frames please see:

http://developer.blackberry.com/cascades/documentation/ui/active_frames/index.html

Active Home Screen App Elements

Active Icons Active Frames

Notifications

To learn more about BlackBerry 7 notifications please see:

https://developer.blackberry.com/java/documentation/message_list_1984778_11.html

To learn more about BlackBerry 10 hub notifications please see:

https://developer.blackberry.com/cascades/documentation/device_comm/notifications/index.html

MessageList Hub Notifications

Popup Dialogs

DialogFieldManager and PopupManager NotificationDialog

Custom Controls

In BlackBerry Java, custom controls are challenging to implement and often involve overriding the paint() method of native components. For more information and samples please see:

https://developer.blackberry.com/java/documentation/
advanced_ui_components_and_managers_1970227_11.html

In Cascades, custom controls are created by combining existing components and modifying their behavior. For more information on how to create a custom control in Cascades, please see:

http://developer.blackberry.com/cascades/documentation/
dev/integrating_cpp_qml/custom_control_tutorial.html

Sample Use of Custom Components Custom Control

Dialog Boxes, Prompts, Toasts

The BlackBerry Java platform supports Dialogs of different format (information, status, inquiry). For information on dialog boxes please see:

http://developer.blackberry.com/java/documentation/dialog_boxes_1970203_11.html

Cascades supports dialog boxes, prompts and toasts. For more information on how to implement them please see:

http://developer.blackberry.com/cascades/documentation/ui/dialogs_toasts/index.html

Dialog Class Dialog, SystemDialog, SystemListDialog …
Below is an example of a custom dialog box.

Lists

For reference of List implementations in Java please see:

http://developer.blackberry.com/java/documentation/lists_and_tables_1970216_11.html

For list implementation in Cascades please see:

http://developer.blackberry.com/cascades/documentation/ui/lists/

Active Home Screen App Elements

SimpleList, RichList, TableView ListView

Text

For reference on how to handle text in Cascades please see:

http://developer.blackberry.com/cascades/documentation/ui/text/index.html

Label

Labelhttp://developer.blackberry.com/java/
documentation/text_field_label_1984828_11.html
Label

Text Field

LabelField, RitchTextField, BasicEditField, PasswordEditField, EmailAddressEditField, KeywordFilterField, AutoTextEditField TextField with TextFieldInputMode
Of type:
Default, Text, EmailAddress, Password, Chat, Url, PhoneNumber, NumbersAndPunctuation,NumericPassword, Pin

Text Area

RitchTextField and ActiveRitchTextField TextArea with TextAreaInputMode of type:
Default, Text, Chat, EmailAddress

Web Content

WebView

BrowserField
http://www.blackberry.com/developers/
docs/7.1.0api/net/rim/device/api/
browser/field2/BrowserField.html

BrowserField  BrowserField browserField = 
new BrowserField();
screen.add( browserField ); 
browserField.requestContent
( "http://blackberry.com" );
WebView
http://developer.blackberry.com/
cascades/reference/bb__cascades
__webview.html

WebView {
    id: webView
    url: " http://blackberry.com "
}

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus