Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - MULTIMEDIA - DEVELOPMENT... User manual

BlackBerry Java Development Environment
Version: 4.7.0
Development Guide

SWD-549284-1212112738-001

Contents
1 Creating user interfaces............................................................................................................................................................. 7
Screens............................................................................................................................................................................................. 7
Screen classes......................................................................................................................................................................... 7
Create a screen....................................................................................................................................................................... 8
How the BlackBerry JVM manages screens........................................................................................................................ 8
Provide screen navigation when using a MainScreen....................................................................................................... 8
Manage a drawing area......................................................................................................................................................... 9
Touch screen orientation and direction....................................................................................................................................... 10
Retrieve the orientation of the touch screen...................................................................................................................... 10
Restrict the touch screen direction...................................................................................................................................... 11
Receive notification when a drawable area of the touch screen changes...................................................................... 11
Receive notification when the orientation of the touch screen changes........................................................................ 11
Working with the accelerometer of a BlackBerry device............................................................................................................ 12
Types of accelerometer data................................................................................................................................................. 12
Accelerometer......................................................................................................................................................................... 12
Retrieve accelerometer data at specific intervals............................................................................................................... 13
Query the accelerometer when the application is in the foreground.............................................................................. 13
Query the accelerometer when the application is in the background............................................................................. 14
Store accelerometer readings in a buffer............................................................................................................................ 14
Retrieve accelerometer readings from a buffer.................................................................................................................. 15
Get the time a reading was taken from the accelerometer.............................................................................................. 15
UI components................................................................................................................................................................................ 15
Add a UI component to a screen.......................................................................................................................................... 15
Create a dialog box................................................................................................................................................................ 16
Creat a bitmap........................................................................................................................................................................ 16
Create a button....................................................................................................................................................................... 16
Create a list............................................................................................................................................................................. 16
Create an alphanumeric drop-down list.............................................................................................................................. 16
Create a text list that can be filtered................................................................................................................................... 17
Create a check box................................................................................................................................................................. 19
Create a radio button............................................................................................................................................................. 19
Create a date field.................................................................................................................................................................. 19
Create a text field................................................................................................................................................................... 20

Create a read-only text field that allows formatting.......................................................................................................... 20
Create an editable text field that has no formatting and accepts filters......................................................................... 20
Create an editable text field that allows special characters............................................................................................. 20
Create a password field......................................................................................................................................................... 20
Create a text field for AutoText............................................................................................................................................. 20
Create a progress bar field.................................................................................................................................................... 21
Create a text label.................................................................................................................................................................. 21
Create a list from which users can select multiple items.................................................................................................. 21
Create a field to display a parent and child relationship between items........................................................................ 22
Add a UI component to a screen.......................................................................................................................................... 23
Create a custom field............................................................................................................................................................. 23
Create a menu item................................................................................................................................................................ 27
Adding menu items to a BlackBerry device application.................................................................................................... 28
Register a menu item............................................................................................................................................................. 28
Arrange UI components................................................................................................................................................................. 29
Create a layout manager....................................................................................................................................................... 29
Align a field to a line of text.................................................................................................................................................. 30
UI events.......................................................................................................................................................................................... 30
Respond to UI navigation events......................................................................................................................................... 30
Determine the type of input method................................................................................................................................... 30
Respond to BlackBerry device user interaction.................................................................................................................. 31
Touch screen events....................................................................................................................................................................... 31
Types of touch screen events................................................................................................................................................ 31
Respond to touch screen events........................................................................................................................................... 33
Keyboard on a BlackBerry device with a touch screen............................................................................................................... 40
Change the state of the keyboard on a BlackBerry device with a touch screen............................................................. 40
Display the keyboard on a BlackBerry device with a touch screen.................................................................................. 40
Hide the keyboard on a BlackBerry device with a touch screen....................................................................................... 41
Spell check....................................................................................................................................................................................... 42
Add spell check functionality................................................................................................................................................ 42
Listen for a spell check event................................................................................................................................................ 43
2 Storing data.................................................................................................................................................................................. 45
Data management.......................................................................................................................................................................... 45
Support for APIs to store data to persistent memory................................................................................................................. 45

Data management.......................................................................................................................................................................... 45
Access to memory........................................................................................................................................................................... 45
Persistent data storage.................................................................................................................................................................. 46
Create a persistent data store............................................................................................................................................... 46
Store persistent data.............................................................................................................................................................. 46
Retrieve persistent data......................................................................................................................................................... 47
Remove persistent data......................................................................................................................................................... 47
MIDP record storage...................................................................................................................................................................... 48
Create an MIDP record store................................................................................................................................................ 48
Add a record to a record store.............................................................................................................................................. 48
Retrieve a record from a record store.................................................................................................................................. 48
Retrieve all records from a record store............................................................................................................................... 48
Collections....................................................................................................................................................................................... 49
Retrieve a collection from persistent storage..................................................................................................................... 49
Create a collection listener to notify the system when a collection changes................................................................. 50
Remove a collection listener that notifies the system when a collection changes........................................................ 50
Notify the system when a collection changes.................................................................................................................... 51
Runtime storage.............................................................................................................................................................................. 51
Retrieve the runtime store..................................................................................................................................................... 51
Add an object in the runtime store...................................................................................................................................... 52
Replace an object in the runtime store................................................................................................................................ 52
Retrieve a registered runtime object.................................................................................................................................... 52
Retrieve an unregistered runtime object............................................................................................................................. 53
3 Creating connections.................................................................................................................................................................. 54
Network gateways.......................................................................................................................................................................... 54
Using the BlackBerry Enterprise Server as an intranet gateway...................................................................................... 54
Using the wireless service provider's Internet gateway.................................................................................................... 54
Retrieve the wireless network name.................................................................................................................................... 54
Connections..................................................................................................................................................................................... 55
Use HTTP authentication...................................................................................................................................................... 55
Use an HTTPS connection..................................................................................................................................................... 56
Use a socket connection........................................................................................................................................................ 57
Use a datagram connection.................................................................................................................................................. 58
Use a USB or serial port connection.................................................................................................................................... 60

Use a Bluetooth serial port connection............................................................................................................................... 61
Wi-Fi connections............................................................................................................................................................................ 62
Wireless access families......................................................................................................................................................... 62
Retrieve the wireless access families that a BlackBerry device supports........................................................................ 63
Determine if a BlackBerry device supports multiple wireless access families................................................................ 63
Determine the wireless access family transceivers that are turned on........................................................................... 63
Turn on the transceiver for a wireless access family.......................................................................................................... 63
Turn off the transceiver for a wireless access family.......................................................................................................... 63
Check if the Wi-Fi transceiver is turned on......................................................................................................................... 63
Check if the Wi-Fi transceiver is connected to a wireless access point........................................................................... 63
Retrieve the status of the wireless access point or the active Wi-Fi profile.................................................................... 64
Open a Wi-Fi socket connection........................................................................................................................................... 64
Open a Wi-Fi HTTP connection............................................................................................................................................ 64
Open a Wi-Fi HTTPS connection.......................................................................................................................................... 65
4 Managing applications............................................................................................................................................................... 66
Application manager...................................................................................................................................................................... 66
Retrieve information about a BlackBerry Java Application............................................................................................... 66
Communicate with another BlackBerry Java Applications................................................................................................ 66
Determine the services that are available to a BlackBerry Java Application.................................................................. 67
Application control.......................................................................................................................................................................... 67
Allow a BlackBerry device application to request access to resources............................................................................ 67
Code modules.................................................................................................................................................................................. 68
Retrieve module information................................................................................................................................................ 68
Access control messages............................................................................................................................................................... 68
Displaying a message for an operation that requires user permission............................................................................ 68
Display an application control message to a user.............................................................................................................. 69
5 Using custom messages and folders in the message list...................................................................................................... 70
Creating a module for background processes............................................................................................................................. 70
Creating a module for the UI......................................................................................................................................................... 70
Create the module for background processes............................................................................................................................. 70
Start the module for background processes or the module for the UI..................................................................................... 71
Create an icon for a custom message.......................................................................................................................................... 71
Create a custom folder in the message list.................................................................................................................................. 72
Send a notification when a custom folder changes.................................................................................................................... 73

Create an indicator for the number of messages in a custom folder....................................................................................... 74
Hide an indicator for a custom folder........................................................................................................................................... 74
Remove an indicator for a custom folder..................................................................................................................................... 74
6 Applications for push content................................................................................................................................................... 76
Types of push applications............................................................................................................................................................. 76
Types of push requests................................................................................................................................................................... 76
7 Localizing BlackBerry device applications............................................................................................................................... 78
Multilanguage support................................................................................................................................................................... 78
Files required for localization........................................................................................................................................................ 78
Manage localization files for a suite of BlackBerry device applications................................................................................... 79
8 Controlling access to APIs and application data.................................................................................................................... 81
Check if a code signature is required........................................................................................................................................... 81
Java APIs with controlled access................................................................................................................................................... 81
Register to use controlled APIs..................................................................................................................................................... 82
Restrictions on code signatures.................................................................................................................................................... 82
Request a code signature............................................................................................................................................................... 83
Register a signature key using a proxy server............................................................................................................................. 83
Sign an application using a proxy server..................................................................................................................................... 84
View the signature status for an application............................................................................................................................... 84
Using keys to protect APIs and data............................................................................................................................................ 84
Protect APIs using code signing keys........................................................................................................................................... 85
Protect runtime store data using code signing keys.................................................................................................................. 85
Protect persistent data using code signing keys......................................................................................................................... 86
9 Testing a BlackBerry device application.................................................................................................................................. 87
Testing applications on a BlackBerry Smartphone Simulator................................................................................................... 87
Testing applications on a BlackBerry device............................................................................................................................... 87
Testing applications using the compiled .cod files..................................................................................................................... 87
Install and remove a .cod file for testing............................................................................................................................. 88
Save a .cod file from a device to a computer...................................................................................................................... 88
Retrieve information about a .cod file.................................................................................................................................. 88
10 Packaging and distributing a BlackBerry Java Application.................................................................................................. 90
Preverify a BlackBerry device application.................................................................................................................................... 90

Application distribution over the wireless network..................................................................................................................... 90
Wireless pull (user-initiated).......................................................................................................................................................... 90
Wireless push (server-initiated)..................................................................................................................................................... 90
Distributing BlackBerry Java Applications over the wireless network...................................................................................... 90
Extract sibling .cod files......................................................................................................................................................... 90
Modifying information for a MIDlet suite............................................................................................................................ 91
Correct the .cod file sizes listed in a .jad file....................................................................................................................... 92
Create .jad files that reference multiple .cod files............................................................................................................. 92
Distributing BlackBerry device applications with the BlackBerry Desktop Software............................................................. 93
Elements in BlackBerry device application .alx file............................................................................................................ 93
Properties of BlackBerry device application .jad files........................................................................................................ 98
Application distribution through a computer connection.......................................................................................................... 99
Distribute an application from a computer......................................................................................................................... 99
Distribute an application from a web page......................................................................................................................... 99
Distribute an application for testing.................................................................................................................................... 99
Distributing an application from a computer.............................................................................................................................. 99
Create an application loader file................................................................................................................................................... 99
Install a BlackBerry device application on a specific device...................................................................................................... 100
Specifing supported versions of the BlackBerry Device Software............................................................................................ 100
11 Glossary......................................................................................................................................................................................... 102
12 Provide feedback......................................................................................................................................................................... 104
13 Legal notice.................................................................................................................................................................................. 105

Creating user interfaces 1
Screens
The main structure for a BlackBerry® device user interface is the Screen object. A BlackBerry Java® Application may display
more than one screen at a time, but only one screen in a BlackBerry Java Application is active at one time.
The user interface APIs initialize simple Screen objects. Once you create a screen, you can add fields and a menu to the screen
and display it to the BlackBerry device user by pushing it on to the UI stack. The menu object has associated menu items that
are runnable objects, which perform a specific task when the BlackBerry device user selects one of the items. For example, menu
items may invoke the necessary code to establish a network connection, commit a data object to memory or close the BlackBerry
Java Application. For a more sophisticated custom BlackBerry Java Application, you can customize the BlackBerry device user
interface and implement new field types, as required. You can also add custom navigation and trackwheel behavior.
The Screen class does not implement disambiguation, which is required for complex input methods, such as international
keyboards. For seamless integration of the different input methods, extend Field or one of its subclasses. Do not use
Screen objects for typing text.
For knowledge base articles about displaying and working with screens, visit the BlackBerry Developer Zone at
www.blackberry.com/developers .
Screen classes
Class Description
Screen Use the Screen class to define a manager to lay out UI components on the screen
and to define a specific type of screen using the styles that the constants on the
Field superclass define.
FullScreen By default, a FullScreen class contains a single vertical field manager. Use a
FullScreen class to provide an empty screen that you can add UI components
to in a standard vertical layout. For another layout style, such as horizontal or
diagonal, use a Screen class and add a Manager to it.
MainScreen The MainScreen class provides features that are common to standard
BlackBerry® Java® Applications. Use a MainScreen object for the first screen
of your BlackBerry Java Application to maintain consistency with other BlackBerry
Java Applications. The MainScreen class provides the following UI components:
• default position of a screen title, with a SeparatorField after the title
Development Guide Creating user interfaces
7

Class Description
• main scrollable section contained in a VerticalFieldManager
• default menu with a Close menu item
• default close action when the BlackBerry device user clicks the Close menu
item or presses the Escape key
Create a screen
1. Import the following classes:
•net.rim.device.api.ui.Screen
•net.rim.device.api.ui.container.FullScreen
•net.rim.device.api.ui.container.MainScreen
2. Extend the Screen class or one of its subclasses, FullScreen or MainScreen.
How the BlackBerry JVM manages screens
The BlackBerry® Java® Virtual Machine maintains Screen objects in a display stack, which is an ordered set of Screen
objects. The screen at the top of the stack is the active screen that the BlackBerry device user sees. When a displays a screen, it
pushes the screen to the top of the stack. When a BlackBerry Java Application closes a screen, it removes the screen off the top
of the stack and displays the next screen on the stack, redrawing it as necessary. Each screen can appear only once in the display
stack. The BlackBerry JVM throws a runtime exception if a Screen that the BlackBerry Java Application pushes to the stack
already exists. A BlackBerry Java Application must remove screens from the display stack when the BlackBerry device user finishes
interacting with them so that the BlackBerry Java Application uses memory efficiently. Use only a few modal screens at one time,
because each screen uses a separate thread.
Provide screen navigation when using a MainScreen
Creating a MainScreen object provides default navigation to your BlackBerry® device application. Avoid using buttons or
other UI elements that take up space on the screen.
Development Guide Screens
8

MainScreen mScreen = new MainScreen(DEFAULT_MENU | DEFAULT_CLOSE);
Manage a drawing area
The Graphics object represents the entire drawing surface that is available to the BlackBerry® device application. To limit
this area, divide it into XYRect objects. Each XYPoint represents a point on the screen, which is composed of an X co-
ordinate and a Y co-ordinate.
1. Import the following classes:
•net.rim.device.api.ui.Graphics
•net.rim.device.api.ui.XYRect
•net.rim.device.api.ui.XYPoint
2. Create an instance of an XYPoint object and an XYRect object.
XYPoint bottomRight = new XYPoint(50, 50);
XYRect rectangle = new XYRect(topLeft, bottomRight);
XYPoint topLeft = new XYPoint(10, 10);
3. Invoke Graphics.pushContext() to make drawing calls that specify that the region origin should not adjust the
drawing offset. In the following code sample, we create two XYPoint objects to represent the top left and bottom right
points of a rectangle. We then create a rectangular clipping region by creating an XYRect object using the XYPoint
objects. We invoke Graphics.pushContext() to push the rectangular clipping region to the context stack. We
invoke Graphics.drawRect() to draw a rectangle and invoke Graphics.fillRect() to fill a rectangle. We
invoke Graphics.popContext() to pop the current context off of the context stack.
XYPoint bottomRight = new XYPoint(50, 50);
XYPoint topLeft = new XYPoint(10, 10);
XYRect rectangle = new XYRect(topLeft, bottomRight);
graphics.pushContext(rectangle, 0, 0);
graphics.fillRect(10, 10, 30, 30);
graphics.drawRect(15, 15, 30, 30);
graphics.popContext();
graphics.drawRect(15, 15, 30, 30);
graphics.pushContext(rectangle, 0, 0);
graphics.fillRect(10, 10, 30, 30);
graphics.drawRect(15, 15, 30, 30);
graphics.popContext();
graphics.drawRect(15, 15, 30, 30);
4. Invoke pushRegion() and specify that the region origin should adjust the drawing offset. In the following code sample,
we invoke Graphics.drawRect() to draw a rectangle and invoke Graphics.fillRect() to fill a rectangle.
We invoke Graphics.popContext() to pop the current context off of the context stack.
Development Guide Screens
9

graphics.pushRegion(rectangle);
graphics.fillRect(10, 10, 30, 30);
graphics.drawRect(15, 15, 30, 30);
graphics.popContext();
5. Invert a specified XYRect object.
6. Specify the portion of the Graphics object to push onto the stack.
7. After you invoke pushContext() (or pushRegion()), provide the portion of the Graphics object to invert.
graphics.pushContext(rectangle);
graphics.invert(rectangle);
graphics.popContext();
8. Invoke translate(). The XYRect is translated from its origin of (1, 1) to an origin of (20, 20). After translation, the
bottom portion of the XYRect object extends past the bounds of the graphics context and clips it.
XYRect rectangle = new XYRect(1, 1, 100, 100);
XYPoint newLocation = new XYPoint(20, 20);
rectangle.translate(newLocation);
Touch screen orientation and direction
You can specify the orientation and direction of the Screen in a BlackBerry® device application.
Orientation refers to the Screen aspect ratio, relative to the ground, where the left, right, top, bottom, front, or back of the
device are furthest from the ground.
Direction refers to the top of the drawing area of the screen, relative to the location of the BlackBerry logo. If you change the
direction that a Screen supports, the change takes effect the next time the Screen orientation of the device changes.
A Screen for a BlackBerry device application can have the following directions and orientations:
Direction
• DIRECTION_NORTH - the top of the drawable area is the screen side closest to the BlackBerry logo
• DIRECTION_WEST - the top of the drawable area is to the left of the logo
• DIRECTION_EAST - the top of the drawable area is to the right of the logo
• DIRECTION_SOUTH - the top of the drawable area is the screen side farthest from the BlackBerry logo
Orientation
• DIRECTION_LANDSCAPE - the top of the drawable area is the screen side farthest from the BlackBerry logo
• DIRECTION_PORTRAIT - the screen is display in protrait view
Retrieve the orientation of the touch screen
1. Import the net.rim.device.api.system.Display class.
Development Guide Touch screen orientation and direction
10

2. Invoke net.rim.device.api.system.Display.getOrientation().
int orientation = Display.getOrientation();
Restrict the touch screen direction
1. Import the following classes:
•net.rim.device.api.ui.Ui
•net.rim.device.api.ui.UiEngineInstance
2. Invoke net.rim.device.api.ui.Ui.getUiEngineInstance().
UiEngineInstance _ue;
_ue = Ui.getUiEngineInstance();
3. Invoke
net.rim.device.api.ui.UiEngineInstance.setAcceptableDirections(byte flags)
and pass the argument for the direction of the Screen.
_ue.setAcceptableDirections(Display.DIRECTION_WEST);
Receive notification when a drawable area of the touch screen changes
1. Import the javax.microedition.lcdui.Canvas class.
2. Extend javax.microedition.lcdui.Canvas.
3. Override Canvas.sizeChanged(int, int).
protected void sizeChanged(int w, int h) {
Dialog.alert("The size of the Canvas has changed);
}
}
Receive notification when the orientation of the touch screen changes
1. Import the net.rim.device.api.ui.Manager class.
2. Invoke net.rim.device.api.ui.Manager.sublayout(int, int).
protected void sublayout(int width, int height) {
int x = 0;
int y = 0;
Field field;
int numberOfFields = getFieldCount();
for (int i=0; i<numberOfFields; ++i) {
field = getField(i);
layoutChild(field, width, height);
setPositionChild(field, x, y);
field.setPosition(x,y);
Development Guide Touch screen orientation and direction
11

x += field.getPreferredWidth();
y += field.getPreferredHeight();
}
setExtent(width,height);
}
Working with the accelerometer of a BlackBerry device
On a BlackBerry® device with an accelerometer, you can create a BlackBerry device application that listens for accelerometer
events and retrieves data about the orientation of the BlackBerry device.
The BlackBerry OS converts accelerometer readings into orientation coordinates such as TOP_UP, FACE_UP, and
LEFT_UP. The BlackBerry OS may also rotate the screen in response to accelerometer readings.
Querying the accelerometer consumes battery power. Connections to the accelerometer should not be kept open for long periods
of time.
Types of accelerometer data
A BlackBerry® device application can retrieve data from the accelerometer.
Data type Description
orientation The orientation of the BlackBerry device with respect to the ground.
acceleration The acceleration of the rotation of the BlackBerry device.
For more information about types of data from the accelerometer, see the API reference for the BlackBerry® Java® Development
Environment
Accelerometer
The BlackBerry® Storm device includes an acclerometer that senses the orientation and acceleration of the device. When a
BlackBerry device user moves the device, the accelerometer senses the movement in 3-D space along the x, y, and z axis. A
BlackBerrydeviceusercanchangetheorientationofthedevicewhichcanchangethedisplaydirectionofascreenforaBlackBerry
device application between portrait and landscape.
The Accelerometer APIs in the net.rim.device.api.system package let a BlackBerry device application respond to
the orientation and acceleration of a BlackBerry device. For example, you can manipulate a game application to change the
direction and speed of a moving object on the screen as a BlackBerry device user moves and rotates the BlackBerry device at
different speeds.
Development Guide Working with the accelerometer of a BlackBerry device
12

Retrieve accelerometer data at specific intervals
If a BlackBerry® device application opens a channel to the accelerometer when the application is in the foreground, when the
application is in the background, the channel pauses and the accelerometer is not queried. If a BlackBerry device application
invokes AccelerometerSensor.Channel. getLastAccelerationData(short[]) at close intervals or
when the BlackBerry device is not in motion, the method might return duplicate values.
1. Import the following classes:
•net.rim.device.api.system.AccelerometerSensor.Channel;
•net.rim.device.api.system.AccelerometerSensor;
2. Openachanneltotheaccelerometer.Whilea channel is open,theBlackBerrydevice application will querytheaccelerometer
for information.
Channel rawDataChannel = AccelerometerSensor.openRawDataChannel
( Application.getApplication() );
3. Create a vector with three elements.
short[] xyz = new short[ 3 ];
4. Create a thread.
while( running ) {
5. Invoke Channel.getLastAccelerationData(short[]) to retrieve data from the accelerometer.
rawDataChannel.getLastAccelerationData( xyz );
6. Invoke Thread.sleep() to specify the interval between queries to the accelerometer, in milliseconds.
Thread.sleep( 500 );
7. Invoke Channel.close() to close the channel to the accelerometer.
rawDataChannel.close();
Query the accelerometer when the application is in the foreground
1. Import the following classes:
•net.rim.device.api.system.AccelerometerChannelConfig
•net.rim.device.api.system.AccelerometerSensor.Channel
2. Open a channel to retrieve acceleration data from the accelerometer.
Channel channel = AccelerometerSensor.openRawAccelerationChannel
( Application.getApplication());
3. Invoke Thread.sleep() to specify the interval between queries to the accelerometer, in milliseconds.
short[] xyz = new short[ 3 ];
while( running ) {
channel.getLastAccelerationData( xyz );
Thread.sleep( 500 );
}
Development Guide Working with the accelerometer of a BlackBerry device
13

4. Invoke Channel.close() to close the channel to the accelerometer.
channel.close();
Query the accelerometer when the application is in the background
1. Import the following classes:
•net.rim.device.api.system.AccelerometerChannelConfig;
•net.rim.device.api.system.AccelerometerSensor.Channel;
2. Create a configuration for a channel to the accelerometer.
AccelerometerChannelConfig channelConfig = new AccelerometerChannelConfig
( AccelerometerChannelConfig.TYPE_RAW );
3. Invoke AccelerometerChannelConfig.setBackgroundMode(Boolean), to specify support for an
application that is in the background.
channelConfig.setBackgroundMode( true );
4. Invoke AccelerometerSensor.openChannel(), to open a background channel to the accelerometer.
Channel channel = AccelerometerSensor.openChannel
( Application.getApplication(), channelConfig );
5. Invoke Thread.sleep() to specify the interval between queries to the accelerometer, in milliseconds.
short[] xyz = new short[ 3 ];
while( running ) {
channel.getLastAccelerationData( xyz );
Thread.sleep( 500 );
}
6. Invoke Channel.close() to close the channel to the accelerometer.
channel.close();
Store accelerometer readings in a buffer
1. Import the following classes:
•net.rim.device.api.system.AccelerometerChannelConfig;
•net.rim.device.api.system.AccelerometerSensor.Channel;
2. Create a configuration for a channel to the accelerometer.
AccelerometerChannelConfig channelConfig = new AccelerometerChannelConfig
( AccelerometerChannelConfig.TYPE_RAW );
3. Invoke AccelerometerChannelConfig.setSamplesCount(), to specify the number of acceleration
readings to store in the buffer. Each element in the buffer contains acceleration readings for the X, Y, and Z axes and data
on when the reading took place.
channelConfig.setSamplesCount( 500 );
Development Guide Working with the accelerometer of a BlackBerry device
14

4. Invoke AccelerometerSensor.openChannel() to open a channel to the accelerometer.
Channel bufferedChannel = AccelerometerSensor.openChannel
( Application.getApplication(), channelConfig );
Retrieve accelerometer readings from a buffer
1. Import the following classes:
•net.rim.device.api.system.AccelerometerData;
•net.rim.device.api.system.AccelerometerSensor.Channel;
2. Query the buffer for accelerometer data.
AccelerometerData accData;
accData = bufferedChannel.getAccelerometerData();
3. Invoke AccelerometerData.getNewBatchLength(), to get the number of readings retrieved since the last
query.
int newBatchSize = accData.getNewBatchLength();
4. Invoke AccelerometerData.getXAccHistory(), AccelerometerData.getYAccHistory(),
and AccelerometerData.getZAccHistory(), to retrieve accelerometer data from the buffer for each axis.
short[] xAccel = accData.getXAccHistory();
short[] yAccel = accData.getYAccHistory();
short[] zAccel = accData.getZAccHistory();
Get the time a reading was taken from the accelerometer
1. Import the net.rim.device.api.system.AccelerometerData class.
2. Query the buffer for accelerometer data.
AccelerometerData accData;
accData = bufferedChannel.getAccelerometerData();
3. Invoke AccelerometerData.getSampleTsHistory().
long[] queryTimestamps = accData.getSampleTsHistory();
UI components
Add a UI component to a screen
1. Import the following classes:
•net.rim.device.api.ui.component.CheckboxField
•net.rim.device.api.ui.container.MainScreen
2. Create an instance of a UI component.
Development Guide UI components
15

CheckboxField myCheckbox = new CheckboxField("First checkbox", true);
3. Add the UI component to your extension of a Screen class.
mainScreen.add(myCheckbox);
Create a dialog box
1. Import the following classes:
•net.rim.device.api.ui.Manager
•net.rim.device.api.ui.container.HorizontalFieldManager
•net.rim.device.api.ui.container.PopupScreen
2. Create an instance of a subclass of the Manager class.
Manager manageLayout = new HorizontalFieldManager( VERTICAL_SCROLLBAR);
3. Create an instance of a PopupScreen using the Manager object.
PopupScreen popUp = new PopupScreen(manageLayout);
Creat a bitmap
1. Import the net.rim.device.api.ui.component.BitmapField class.
2. Create an instance of a BitmapField.
BitmapField myBitmapField = new BitmapField();
Create a button
1. Import the net.rim.device.api.ui.component.ButtonField class.
2. Create an instance of a ButtonField using a style parameter.
ButtonField mySubmitButton = new ButtonField("Submit");
Create a list
Create an alphanumeric drop-down list
1. Import the following classes:
•java.lang.String
•net.rim.device.api.ui.component.ObjectChoiceField
•net.rim.device.api.ui.container.MainScreen
2. Create an instance of an ObjectChoiceField, providing an object array as a parameter to create a drop-down list
that contains objects.
Development Guide UI components
16

String choiceItems[] = {"Option one","Option two", "Option three"};
mainScreen.add(new ObjectChoiceField("Select an option:", choiceItems));
Create a text list that can be filtered
You can create an application that uses the KeywordFilterField class, included in the
net.rim.device.api.ui.component package, to provide a UI field that consists of a single text input field and a
list of selectable elements. A word that a BlackBerry® device user enters into the text input field filters the elements in the list.
For more information about using the KeywordFilterField class, see the KeywordFilterFieldDemo sample, included
with the BlackBerry® Java® Development Environment version 4.3.1.
1. Import the following classes:
•net.rim.device.api.ui.component.KeywordFilterField
•net.rim.device.api.collection.util.SortedReadableList
•net.rim.device.api.collection.util.SortedReadableList
•java.util.Vector
•java.io.InputStream
•net.rim.device.api.io.LineReader
•java.lang.String
2. Import the net.rim.device.api.ui.component.KeywordProvider interface.
3. Create variables. In the following code sample, CountryList extends the SortedReadableList class and
implements the KeywordProvider interface.
private KeywordFilterField _keywordField;
private CountryList _CountryList;
private Vector _countries;
4. To create a list of selectable text items, populate a vector with data from a text file.
_countries = getDataFromFile();
5. Create an instance of a class that extends the SortedReadableList class.
_CountryList = new CountryList(StringComparator.getInstance
(true),_countries);
6. To specify the elements of the list, create a new instance of a KeywordFilterField object.
_keywordField = new KeywordFilterField();
7. Invoke KeywordFilterField.setList().
_keywordField.setList(_CountryList, _CountryList);
8. Set a label for the input field of the KeywordFilterFIeld.
_keywordField.setLabel("Search: ");
9. Create the main screen of the application and add a KeywordFilterField to the main screen.
Development Guide UI components
17

KeywordFilterDemoScreen screen = new KeywordFilterDemoScreen
(this,_keywordField);
screen.add(_keywordField.getKeywordField());
screen.add(_keywordField);
pushScreen(screen);
10. To create a method that populates and returns a vector of Country objects containing data from text file, In the method
signature, specify Vector as the return type.
public Vector getDataFromFile()
{
11. Create and store a reference to a new Vector object.
Vector countries = new Vector();
12. Create an input stream to the text file.
InputStream stream = getClass().getResourceAsStream("/Data/
CountryData.txt");
13. Read CRLF delimited lines from the input stream.
LineReader lineReader = new LineReader(stream);
14. Read data from the input stream one line at a time until you reach the end of file flag. Each line is parsed to extract data
that is used to construct Country objects.
for(;;)
{ //Obtain a line of text from the text file
String line = new String(lineReader.readLine());
//If we are not at the end of the file, parse the line of text
if(!line.equals("EOF"))
{int space1 = line.indexOf(" ");
String country = line.substring(0,space1);
int space2 = line.indexOf(" ",space1+1);
String population = line.substring(space1
+1,space2);
String capital = line.substring(space2+1,line.length());
// Create a new Country object.
countries.addElement(new Country
(country,population,capital));
}
else
{
break;
}
} // end the for loop
return countries;
}
15. To add a keyword to the list of selectable text items, invoke SortedReadableList.doAdd(element).
Development Guide UI components
18