The Components of a BlackBerry UI BLACKBERRY

All the visible elements on screen in a BlackBerry application are of one of the three types:

  • Fields: These are the basic building blocks of the UI.Generally, each control, such as a button or text field, corresponds to an instance of a field. The Field class draws the control and handles user input.
  • Managers: These arrange fields on the screen. Each field must belong to one and only one manager. Each manager is also a field, meaning managers can contain other managers, allowing for some pretty intricate UI layouts.
  • Screens: There’s one active screen per application at any time.Screens handle field layout through a delegate manager and provide additional functionality like menus.

Fields are all derived from net.rim.device.api.ui.Field. There are a lot of useful prebuilt fields available in the net.rim.device.api.ui.component package.

Managers are derived from net.rim.device.api.ui.Manager, which you’ll find is a subclass of net.rim.device.api.ui.Field. Several useful managers are defined in the net. rim. device. api. ui. container package.

Screens all derive from net.rim.device.api.ui.Screen, which is a subclass of Manager, and therefore of Field.You’ll also find the default screens in the net.rim.device.api.ui.container package.

NOTE: Though Screen is ultimately descended from Field, you can’t add a Screen to a Manager. The hierarchy in this case represents functionality—a Screen does things that a Field and Manager do, such as painting itself, handling user input, and managing fields, but it is not actually a drop-in replacement for a Field the way a Manager is. Right now, or at some time soon, you may want to browse through the Javadocs for the packages mentioned in this section. These can give you an idea of what’s possible with the BlackBerry and maybe help with some ideas for your own applications. In this, all the fields, managers, and screens we’ll use will be those provided with the JDE. You’ll learn how to make your own in the next chapter.

Creating the Application

Using your development environment of choice, create a new BlackBerry Application project called UiFun. We’ll create the application class and main screen class as before. The main application class will be the same as the simple first version that we created a couple of chapters ago. We’ll use the package com.beginningblackberry.uifun and call the application and main screen classes UiFunApplication and UiFunMainScreen. You should know enough to create these classes now, but for reference the source code follows:

Here’s the source code for the UiFun application class:

Adding the Logo Image

The first field we add will be an instance of
net.rim.device.api.ui.component.BitmapField to show the image at the top of the screen.

The BlackBerry can use PNG, GIF, or JPEG images, but most applications use PNGs because of their reduced size, high quality, and support for transparencies. When creating images for use in your application, always consider compressing your image as much as possible using your graphics program or a PNG optimizer (several good free ones are available), because large images can very quickly increase the size of your application.

Adding the Image to the Project

If you’re using the JDE Plug-in for Eclipse, add the image file to your Eclipse project by creating a new folder called res at the same level as your source folder, copying the image into that folder and from your Eclipse workspace by right-clicking your project and clicking Refresh.You can put images in whatever folder you want, put for this example, we decided to create a specific resources folder (hence the name res).

This Eclipse workspace with the apress_logo.png image added

This Eclipse workspace with the apress_logo.png image added

If you’re using the stand-alone JDE, create a folder called res at the same level as your com folder (the root of your source tree), and copy the image file there. Then, from the Project menu, choose Add File to Project, and browse to the image file.

The JDE workspace with the apress_logo.png image added

The JDE workspace with the apress_logo.png image added

Adding the Image to the Screen

BitmapField takes a Bitmap object as an argument in its constructor, so we’ll need to load the image before constructing the field. We’ll import net.rim.device.api.system.Bitmap and add the following line to UiFunMainScreen’s constructor load the bitmap from the image resource we just added:

Bitmap logoBitmap = Bitmap.getBitmapResource("res/apress_log.png");

The path for loading bitmaps, and all other resources, is relative to the location of your project definition file (the.jdp file). We put the bitmap in a res folder at the same level as our src folder.

Finally, we want to center the bitmap horizontally at the top of the screen. MainScreen lays out fields vertically top to bottom in the order that they’re added, so the BitmapField will automatically appear at the top of the screen. But to horizontally center it, we need to specify the Field.FIELD_HCENTER style in its constructor. We’ve also elected to make the BitmapField a member field instead of just declaring it locally in the constructor. We’ll follow this pattern for all our fields—making our user interface components member fields will become important as we start to handle user input. Now, constructing the bitmap field and adding it to the screen is easy. The complete code follows:

And when this code is run, we’ll see the screen.

The BitmapField centered at the top of the screen

The BitmapField centered at the top of the screen

Field Style Flags

Almost all fields and managers have a constructor that takes a style parameter. The style is a mask of various style flags concatenated with the bitwise or operator (|). These flags are defined throughout the API, although most are in Field and Manager, and they can influence many different aspects of field appearance, positioning, and behavior. You can apply any style to any field, but whether the style has an effect depends on the field and sometimes the manager that contains that field.

Generally, anything defined within the Field class is applicable to any field (including managers); anything defined within the Manager class is applicable to any manager, and anything defined within the Screen class is applicable to any screen. Flags defined within a specific subclass of field usually only apply to that field and any field that subclasses it; examples include the ButtonField.CONSUME_CLICK style and the various styles associated with TextField, BasicEditField, and their subclasses.

There are unfortunately no guarantees about how a specific style flag will affect different fields. Generally, flags work the way you’d expect them to, but remember that just setting a particular alignment flag on a field does not guarantee that you’ll get exactly what you want. For example, some managers ignore the alignment flags, which will become clear when we build our own manager later on. The Javadocs provide more information for specific fields.

Adding a Few More Fields

Next, we’ll add our screen’s remaining controls: the username and password fields,the domain drop-down list, the check box, and the Login and Clear buttons.

Creating the Username and Password Fields

We’ll use an EditField for the username and a PasswordEditField (which automatically hides characters as they are typed) for the password field. Each of these fields can display its own label, specified in the constructor. We don’t need to apply any special styles to these fields. Add the following import statement to the top of UiFunMainScreen.java, just under the other import statements:

import net.rim.device.api.ui.component.EditField;

Then, add the following declarations to the top of the UiFunMainScreen class:

And add the following lines go in the constructor:

Creating the Domain Field and Check Box

The Domain field should be a drop-down list. For the BlackBerry, this is accomplished by an instance of net.rim.device.api.ui.component.ChoiceField. You can implement the interface directly, but for this application, the net.rim.device.api.ui.component. ObjectChoiceField component will do just fine; it allows us to specify an array of Objects, which will be used to populate the field (the toString method will be used for the display string). If you want a list of numbers, net.rim.device.api.ui.component. NumericChoiceField is also often useful.

We’ll add the imports for both of these fields first:

Then, we add the declaration of the member variables, again at the top of the
UiFunMainScreen class:

ObjectChoiceField domainField;
CheckboxField rememberCheckbox;

Because we’re just using hard-coded values for this application, instantiating our
ObjectChoiceField is easy:

And by this point, you can probably figure out how to use net. rim. device. api. ui. component. CheckboxField to create a check box on screen; there’s nothing special to note about CheckboxField except that you have to specify the state of the check box (true for checked or false for unchecked) when you instantiate it:

Creating the Buttons

To create the Login and Clear buttons that go beneath these text fields, we’ll use—as you might expect—the ButtonField class. A warning with ButtonFields: when creating a ButtonField, you should always specify the style ButtonField.CONSUME_CLICK. If you don’t, the click event will be passed onto the screen, and a menu will open when the user clicks the button, though your button will still cause an action to be performed.

First, we’ll import ButtonField:

import net.rim.device.api.ui.component.ButtonField;;

Next, we add the declarations for our two buttons:

Finally, the following lines go in the UiFunMainScreen constructor:

Now, if you run the application, you’ll see something similar to Figure.

The fields for the UiFun application

The fields for the UiFun application

We’re pretty close to being done! But we want those two buttons to be beside each other instead of one on top of the other.

Arranging the Buttons Horizontally

Remember that MainScreen (which UiFunMainScreen is derived from) lays out its fields vertically. To put two fields beside each other, we need to place them in an instance of net.rim.device.api.ui.container.HorizontalFieldManager and add that manager to the screen. We’ll give the HorizontalFieldManager the Field.FIELD_RIGHT style, to put the buttons on the right side of the screen.

Add the following import:

import net.rim.device.api.ui.container.HorizontalFieldManager;

Erase the two add calls for the buttons, and replace them with this:

We’ll also add a couple of instances of net.rim.device.api.ui.component.SeparatorField, which draws a horizontal line across the screen, and of LabelField, which contains our login instructions. The full code for the UiFunMainScreen constructor at this point follows (remember to add an import statement for SeparatorField):

Running the application, we’ll see our screen looking the way we intended it, as Figure illustrates.

The final look for the login screen

The final look for the login screen


All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

BLACKBERRY Topics