The UI API helps you create user interfaces for BlackBerry screens.
Apps with a UI implement net.rim.device.api.ui.UiApplication, which is a subclass of net.rim.device.api.system.Application. A UIApplication object maintains a stack of Screen objects. As it pushes screens onto the stack, it draws them on top of any other screens already on the stack. When the application pops a screen off the stack, it redraws the underlying screens as necessary. Only the screen on the top of the stack receives input events.
A Field represents a rectangular region contained by a manager. Each control, such as a button, corresponds to an instance of a field. You can't instantiate Field directly, but you can use prebuilt fields and create custom fields. Each field draws the control and handles user input. Following are some of the most commonly used prebuilt fields:
- ButtonField provides a simple button
- LabelField provides a text label
- TextField provides a text label
- DateField allows you to store a date and display it in different formats in a field (such as 2011/11/17)
- MapField allows you to render a map in a field
- BrowserField allows you to display web content in a field
You can create custom fields by extending the Field class.
A Manager, also called a layout manager, handles the layout and scrolling of fields. A Manager object contains fields. There are several Manager subclasses that handle specific types of field layout.
Several useful managers are defined in the net.rim.device.api.ui.container package. The following managers are the most commonly used:
- VerticalFieldManager arranges fields in a single vertical column
- HorizontalFieldManager arranges fields in a single horizontal row
- FlowFieldManager arranges fields first horizontally, then vertically
You declare a layout manager at the top level of your screen and then add fields to it. Because layout managers are subclasses of Field, they can be embedded in other layout managers. You can also define your own layout manager.
A Screen is the top-level container for the UI elements that represent what you want to display. Screens can contain fields (such as text fields), layout managers, radio buttons, and dropdown lists.
The UI API has two main types of Screen object:
- FullScreen, which is subclassed by MainScreen and PhoneScreen
- PopupScreen, which is subclassed by Dialog, Status, LocationPicker, and AbstractLocationPicker
You can display information that is supplementary to your application in a pop-up screen without interrupting the flow of the application. As a result, you do not have to leave the main screen and then return to it later. In addition, you can prioritize which PopupScreen objects are pushed to the top of the display stack by invoking pushGlobalScreen(Screen, int, int).
Screen objects are pushed on to the display stack by the pushScreen() and pushModalScreen() methods of the UiApplication class. Because pushModalScreen() blocks until the screen is popped off the display stack (where pushScreen() returns immediately), the order of operations is crucial when you use modal screens. Do not invoke pushModalScreen() before starting the event dispatcher thread; doing so throws a RuntimeException. Other methods, such as Dialog.inform() and Dialog.alert(), also use pushModalScreen().
BlackBerry smartphones organize commands on context-sensitive menus that can be accessed by pressing the Menu key. Menu items are instances of MenuItem. You can customize the menu that is opened for your app. You can:
- Add or remove menu items depending on the screen or application state when the menu opens
- Specify the order of menu items
- Specify the menu item that is selected by default
The UI API contains a generic event listener model that lets you implement listeners for many types of events, such as when a field is changed, or when the user presses a key, clicks the trackpad or trackball, or touches the touch screen. You can set a listener for a Field object by invoking setChangeListener() of the Field class.
Model-View-Controller design pattern
Some standard components in the UI API, including activity and progress indicators in the net.rim.device.api.ui.component.progressindicator package and lists and tables in the net.rim.device.api.ui.component.table package, use the Model-View-Controller (MVC) design pattern.
Before using these components, you should be familar with the MVC design pattern. There are many print and online resources where you can learn about MVC.
You have several options for creating graphics on a BlackBerry smartphone:
- You can add predefined UI components such as text, input controls, and images to Screen objects.
- You can do simple custom drawing on a screen by overriding the paint() method of the class that represents the screen and using the methods supplied by the Graphics object to draw on the screen.
- You can draw 2D graphics with the SVG APIs: org.w3c.dom, org.w3c.dom.events, and org.w3c.dom.svg.
- You can make more sophisticated 2D images using the Graphics Utility API: OpenGL ES API or OpenVG API.
- You can create 3D images using the OpenGL ES API.