Comparing UI elements

While there are a number of similarities between the UI elements of iOS and the BlackBerry 10 OS, there are also some differences that you must take into consideration when porting your app. The following section provides a side-by-side look at how common UI elements appear on their respective platform. Code samples are provided where applicable to demonstrate how you can incorporate these elements in your BlackBerry 10 application.

Toolbars and menus

Navigation bar

Action bar

Screen showing the Navigation bar in iOS.
Screen showing the action bar in BlackBerry 10.

Characteristics of a navigation bar

A navigation bar appears at the upper edge of an app screen, just below the status bar.

A navigation bar usually displays the title of the current screen or view, which is centered along the full width of the screen.

Users tap the back button on the left of the label to return to the previous screen.

All controls in a navigation bar include a bezel around them.

Changing device orientation from portrait to landscape changes the height of the navigation bar automatically.

A navigation bar is always displayed across the full width of the screen.

Characteristics of an action bar

An action bar appears at the bottom of the screen, and can contain actions, tabs, or both.

An action bar contains the most frequent and relevant actions for the entire screen.

An action bar supports an action menu that appears from the right and a tab menu that appears from the left.

The back button appears on the left side of the action bar. The back button appears only on the second and subsequent levels in an application hierarchy.

Changing device orientation from portrait to landscape changes the height of the action bar automatically.

The back button can contain an icon and the title of the screen or tab that users can return to. If the context is clear, you can use the label “Back” instead.

For immersive views such as pictures or video, you can allow the action bar to disappear and be displayed again when a user taps the screen.

If no actions are specified, the action bar is not displayed, and the screen content assumes the full height of the screen.

Implementing an action bar in your app

To implement an action bar in your app, specify a root control and a set of actions on a Page. All actions that you specify appear automatically in the action bar.

Page {
    actions: [
        ActionItem {
            title: "Refresh"
            onTriggered: indicator.start()
            ActionBar.placement: ActionBarPlacement.OnBar
        }
    ]
    content: Container {
        layout: DockLayout {}
        ActivityIndicator {
            id: indicator
            verticalAlignment: VerticalAlignment.Fill
            horizontalAlignment: HorizontalAlignment.Fill
        }
    }
}

For more information on adding items to the action bar, see the ActionItem reference.

Curl

Action menu

Screen showing curl in iOS.
Screen showing the action menu in BlackBerry 10.

Characteristics of a curl

A curl causes the app screen to mimic a page being turned in a book, which reveals additional options, controls, or views.

The control for a curl is usually located on the right side of the navigation bar.

Characteristics of an action menu

An action menu holds actions that you do not want to include on the action bar.

The action menu button for the action menu is located on the right side of the action bar and is represented by a vertical ellipsis.

Implementing an action menu in your app

To implement an action menu in your app, set the ActionBarPlacement enumerated type to InOverflow.

Page {
	actions: [
		ActionItem {
			title: "Refresh"
			onTriggered: indicator.start()
			ActionBar.placement: ActionBarPlacement.InOverflow
		}
	]
	content: Container {
		layout: DockLayout {}
		ActivityIndicator {
			id: indicator
			verticalAlignment: VerticalAlignment.Fill
			horizontalAlignment: HorizontalAlignment.Fill
		}
	}
}

For more information on creating an action menu, see Creating a single screen.

Settings

Application menu

Screen showing the settings interface in iOS.
Screen showing the application menu in BlackBerry 10.

Characteristics of the settings interface

App settings are accessed through the settings interface on the home screen, or using a custom UI for in-app preferences.

To add options for customizing your app to the settings interface on iOS, you need to include a settings bundle with your app.

Save preference data using the Foundation framework.

Control types for preferences include:
  • Text field
  • Title
  • Toggle switch
  • Slider
  • Multivalue
  • Group
  • Child pane

Characteristics of an application menu

An application menu is accessed in an app by swiping down from the top of the screen.

An application menu holds important but less frequently used actions that are independent of that context and are common across the application.

An application menu houses features such as view refresh and settings.

An application menu should push the UI on the screen toward the bottom of the screen. The menu should not be placed on top of the UI.

If your app contains settings or help,  put the Settings icon in the far right of the menu and the Help icon in the far left.

Including an application menu in your app is optional.

Implementing an application menu in your app

To implement an application menu, you use a property called Menu.definition and specify its value using a MenuDefinition object. This object contains the actions that you want to include in the application menu, all of which are included in the actions list property.

import bb.cascades 1.0
  
Page {
    // Add the application menu using a MenuDefinition
    Menu.definition: MenuDefinition {
      
        // Specify the actions that should be included in the menu
        actions: [
            ActionItem {
                title: "Action 1"
                imageSource: "images/actionOneIcon.png"
                  
                onTriggered: {
                    textField.text = "Action 1 selected!"
                }
            },
            ActionItem {
                title: "Action 2"
                imageSource: "images/actionTwoIcon.png"
                  
                onTriggered: {
                    textField.text = "Action 2 selected!"
                }
            },
            ActionItem {
                title: "Action 3"
                  
                onTriggered: {
                    textField.text = "Action 3 selected!"
                }
            }
        ] // end of actions list
    } // end of MenuDefinition
      
    Container {
      
        // Add a text field to display which action is selected
        TextField {
            id: textField
            text: "No action selected."
        }
    }
} // end of Page

For more information on the application menu, see Adding menus.

Tab bar

Tabs that appear on the action bar

Screen showing the tab bar in iOS.
Screen showing tabs that appear on the action bar in BlackBerry 10.

Characteristics of a tab bar

A tab bar is used to organize features or apps that are related.

When a user taps a tab, the corresponding view controller displays the view associated with tab.

You must configure the tab bar item of each view controller before the tab bar is displayed.

Characteristics of tabs that appear on the action bar

The action bar can be used to display actions, tabs, or a combination of the two.

Placing tabs on the action bar lets you organize multiple screens in an app.

The appearance of a tab can be customized using AbstractActionItem.

Implementing tabs in your app

To implement tabs in your app, you first create a TabbedPane as the root element of your app and add a Tab component to it. Next, set showTabsOnActionBar to true to display the tabs on the action bar.

import bb.cascades 1.0
  
TabbedPane {
    id: tabbedPane
    showTabsOnActionBar: true
     
    Tab {
        title: "Tab 1"
         
        content: Page {
            content: Label {
                text: "This is tab 1."
            }
        }
    } // end of first Tab
      
    Tab {
        title: "Tab 2"
         
        content: Page {
            content: Label {
                text: "This is tab 2."
            }
        }
    } // end of second Tab
} // end of TabbedPane

You can use the imageSource attribute to define an icon for each of your tabs. Alternatively, if you define an icon, the default one is used.

For more information on adding tabs to the action bar, see Creating tabs for screens.

Tab overflow

Tab menu

Screen showing a tab overflow in iOS.
Screen showing the tab menu in BlackBerry 10.

Characteristics of the tab overflow

A tab overflow is used to house selections not appearing on the Tab bar.

Tapping the tab overflow icon will display an additional view which holds the overflow items.

Characteristics of the tab menu

The tab menu is used to house selections not appearing on the action bar.

Tapping the tab overflow button will display a view from the left which holds the overflow items.

Implementing a tab menu in your app

To implement a tab menu in your app, set the showTabsOnActionBar property to false. Alternatively, you can add more than four tabs to a control, and the tab menu is created automatically.

For more information on the tab menu, see the TabbedPane reference.

Custom buttons on the navigation bar

Context menu

Screen showing custom buttons on the navigation bar in iOS.
Screen showing the context menu in BlackBerry 10.

Characteristics of Custom buttons

Custom buttons allow you to add custom titles, views and controls to a Navigation bar.

Characteristics of a context menu

A context menu is displayed when a user touches and holds a UI control in your app.

You can add a context menu to any Cascades component that extends the Control class, including custom components you create by extending the CustomControl class.

A context menu appears from the right side of the screen and shows only the icons associated with each action. Users can then swipe the partial menu to the left to display the entire menu.

Users can touch and hold a control to display the context menu, and then drag their finger directly to an action in the partial context menu to select that action.

Implementing a context menu in your app

To add a context menu to a control in QML, you use the contextActions list property. You add the ActionSet that contains your ActionItem objects to this list. When you add your ActionItem objects, you use the actions list property to hold the actions. Here's how to create a blue Container with a context menu. The menu includes three actions.

import bb.cascades 1.0
 
Page {
    content: Container {   
        Container {
            preferredWidth: 200
            preferredHeight: 200
            background: Color.Blue
             
            contextActions: [
                ActionSet {
                    title: "Action Set"
                    subtitle: "This is an action set."
                     
                    actions: [
                        ActionItem {
                            title: "Action 1"
                        },
                        ActionItem {
                            title: "Action 2"
                        },
                        ActionItem {
                            title: "Action 3"
                        }
                    ]
                } // end of ActionSet   
            ] // end of contextActions list
        } // end of blue Container
    } // end of top-level Container
} // end of Page

For more information on context menus, see Adding menus.

Additional views

Action sheets

Sheets

Screen showing an action sheet in iOS.
Screen showing sheets in BlackBerry 10.

Characteristics of action sheets

Action sheets display a set of choices related to the task a user initiates.

An action sheet always emerges from the bottom of the screen.

The sides of an action sheet are anchored to the sides of the screen.

Characteristics of sheets

Sheets are full-screen views that appear as separate layers on top of the current screen context.

You can use sheets to display a UI that's related to creating or selecting content, such as composing an email, creating a contact, or selecting content using a picker.

A sheet includes a set of buttons at the top of the screen. The buttons should represent actions specific to that sheet, such as Cancel and Send for an email sheet.

Implementing a sheet in your app

To implement a sheet in your app, you create a Sheet and add it to your app using an attachedObjects list. The following sample demonstrates how to create and show a sheet.

import bb.cascades 1.0
 
Page {
    attachedObjects: [
        Sheet {
            id: mySheet
            content: Page {
                Label {
                    text: "This is a sheet."
                }
                 
                actions: [
                    ActionItem {
                        title: "Close Sheet"
                        ActionBar.placement: ActionBarPlacement.OnBar
                         
                        // When this action is selected, close
                        // the sheet
                        onTriggered: {
                            mySheet.close();
                        }
                    }
                ]
            }
        }    
    ]
     
    actions: [
        ActionItem {
            title: "Open Sheet"
            ActionBar.placement: ActionBarPlacement.OnBar
             
            // When this action is selected, open
            // the sheet
            onTriggered: {
               mySheet.open();
            }
        }
    ]
}

Cards

Cards are a feature unique to BlackBerry 10, so they do not have an iOS equivalent. Cards allow an application to expose a particular feature of an app so that another app can use it using the invocation framework. A card typically provides functions such as picking a contact, composing an email, or previewing an image.

A card appears in full screen mode and may include the status bar. Once the card's function is completed, the user returns to the screen of the parent application automatically. This functionality allows the cards to appear as if they're part of the same application. Managing cards is done by the BlackBerry 10 OS, so you can use a card simply by invoking it.

Screen showing cards in BlackBerry 10.

Implementing cards in your app

Cards are packaged in the bar-descriptor.xml file of an application. To implement a card you must delcare the application as an invocation target in the bar-descriptor.xml. Additionally, you must declare any metadata for a card that acts as a target in the bar-descriptor.xml.

When you declare a card, you must specify the style of the card that your application exports. You specify the style of the card in the type attribute of the target declaration. For example, card.previewer exports a previewer style. You can choose among previewer, composer, and picker styles for your application's card.

For more information on cards, see Cards.

Control mapping

The following is a list of commonly used controls in iOS and their equivalents in BlackBerry 10.

iOS

Cascades

Description of the Cascades control

UIButton

Button

A clickable button with a fixed height, and optional image and optional text parts.

UIImagePickerController

Camera

A viewfinder control that provides access to the camera hardware.

UIButton customized as a checkbox

CheckBox

A checkbox control with two states.

No direct equivalent

DropDown

A control that lets users select an item from a dropdown list.

No direct equivalent

ImageToggleButton

A switch control with six visual states.

UIImageView

ImageView

A control that displays images.

UILabel

Label

A control that displays text that users cannot edit.

UITableView

ListView

A scrollable list of items.

UINavigationController

NavigationPane

A class that stacks Page objects. Not a visual control.

UIViewController

Page

A class that encapsulates a set of controls on an individual view in an app. Page is not a direct equivalent to UIViewController. Not a visual control.

UIProgressView

ProgressIndicator

A control that displays the progress of a defined activity, such as connecting to a server.

UIButton customized as a radio button

RadioGroup

Groups a set of Option controls that are rendered as radio buttons.

UISegmentedControl

SegmentedControl

A control that displays up to four options in a horizontal orientation.

UISlider

Slider

A standard slider control that allows the selection of a value between a minimum and a maximum.

UIStepper

Not applicable

No direct equivalent. Consider using two Button controls placed side-by-side instead.

UITabBarController

TabbedPane

A navigation control that lets users select one of a number of Tab controls.

UITextArea

TextArea

A text control with multiple lines that users can edit.

UITextField

TextField

A text control with a single line that users can edit.

UISwitch

ToggleButton

A switch control of a fixed size with checked or unchecked states.

UIWebView

WebView

A control that displays web content.

UIDatePicker

DateTimePicker

A control that selects the date and time.

UIPickerView

Not applicable

No direct equivalent. Consider using a DropDown or ListView control instead.

Last modified: 2013-12-21

comments powered by Disqus