BlackBerry Java Development

Environment
Version 4.2.0

BlackBerry Simulator Quick Start Guide

BlackBerry Java Development Environment Version 4.2.0 BlackBerry Simulator Quick Start Guide

Last modified: 6 September 2006

Part number: SWD_X_JDE-004.000

At the time of publication, this documentation complies with the BlackBerry Java Development Environment Version 4.2.0.

Send us your comments on product documentation: https://www.blackberry.com/DocsFeedback.

©2006 Research In Motion Limited. All Rights Reserved. The BlackBerry and RIM families of related marks, images, and symbols are the
exclusive properties of Research In Motion Limited. RIM, Research In Motion, BlackBerry, “Always On, Always Connected” and the “envelope in
motion” symbol are registered with the U.S. Patent and Trademark Office and may be pending or registered in other countries.

Microsoft, Outlook, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other
countries. owners. Casira End point is a trademark of Bluetooth Designer. All other brands, product names, company names, trademarks and
service marks are the properties of their respective owners.

The BlackBerry device and/or associated software are protected by copyright, international treaties, and various patents, including one or more
of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D445,428; D433,460; D416,256. Other patents are
registered or pending in various countries around the world. Visit www.rim.com/patents.shtml for a list of RIM (as hereinafter defined) patents.

This document is provided “as is” and Research In Motion Limited and its affiliated companies (“RIM”) assume no responsibility for any
typographical, technical, or other inaccuracies in this document. In order to protect RIM proprietary and confidential information and/or trade
secrets, this document may describe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change
information that is contained in this document; however, RIM makes no commitment to provide any such changes, updates, enhancements, or
other additions to this document to you in a timely manner or at all. RIM MAKES NO REPRESENTATIONS, WARRANTIES, CONDITIONS, OR
COVENANTS, EITHER EXPRESS OR IMPLIED (INCLUDING WITHOUT LIMITATION, ANY EXPRESS OR IMPLIED WARRANTIES OR
CONDITIONS OF FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, MERCHANTABILITY, DURABILITY, TITLE, OR RELATED TO
THE PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE REFERENCED HEREIN OR PERFORMANCE OF ANY SERVICES
REFERENCED HEREIN). IN CONNECTION WITH YOUR USE OF THIS DOCUMENTATION, NEITHER RIM NOR ITS RESPECTIVE DIRECTORS,
OFFICERS, EMPLOYEES, OR CONSULTANTS SHALL BE LIABLE TO YOU FOR ANY DAMAGES WHATSOEVER BE THEY DIRECT, ECONOMIC,
COMMERCIAL, SPECIAL, CONSEQUENTIAL, INCIDENTAL, EXEMPLARY, OR INDIRECT DAMAGES, EVEN IF RIM HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES, INCLUDING WITHOUT LIMITATION, LOSS OF BUSINESS REVENUE OR EARNINGS, LOST DATA,
DAMAGES CAUSED BY DELAYS, LOST PROFITS, OR A FAILURE TO REALIZE EXPECTED SAVINGS.

This document might contain references to third-party sources of information, hardware or software, products or services and/or third-party
web sites (collectively the “Third-Party Information”). RIM does not control, and is not responsible for, any Third-Party Information, including,
without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any
other aspect of Third-Party Information. The inclusion of Third-Party Information in this document does not imply endorsement by RIM of the
Third-Party Information or the third-party in any way. Installation and use of Third-Party Information with RIM's products and services may
require one or more patent, trademark, or copyright licenses in order to avoid infringement of the intellectual property rights of others. Any
dealings with Third-Party Information, including, without limitation, compliance with applicable licenses and terms and conditions, are solely
between you and the third-party. You are solely responsible for determining whether such third-party licenses are required and are responsible
for acquiring any such licenses relating to Third-Party Information. To the extent that such intellectual property licenses may be required, RIM
expressly recommends that you do not install or use Third-Party Information until all such applicable licenses have been acquired by you or on
your behalf. Your use of Third-Party Information shall be governed by and subject to you agreeing to the terms of the Third-Party Information
licenses. Any Third-Party Information that is provided with RIM's products and services is provided “as is”. RIM makes no representation,
warranty or guarantee whatsoever in relation to the Third-Party Information and RIM assumes no liability whatsoever in relation to the Third-
Party Information even if RIM has been advised of the possibility of such damages or can anticipate such damages.
Research In Motion Limited Research In Motion UK Limited
295 Phillip Street Centrum House, 36 Station Road
Waterloo, ON N2L 3W8 Egham, Surrey TW20 9LF
Canada United Kingdom

Published in Canada
Contents
1 BlackBerry device simulator ............................................................................................................................... 3
About the BlackBerry device simulator ......................................................................................................... 3
Start the device simulator................................................................................................................................ 3
Using the BlackBerry device simulator graphical user interface .............................................................. 4
Using the BlackBerry device simulator input controls................................................................................ 5
Using the BlackBerry device simulator to perform common tasks ........................................................... 5
Using the advanced BlackBerry device simulator features.........................................................................7

2 Testing applications that require an HTTP connection .................................................................................9

Simulating the BlackBerry MDS Connection Service.................................................................................. 9

3 Testing messaging applications ....................................................................................................................... 11

Simulating sending and receiving messages ...............................................................................................11
 1
BlackBerry device simulator
About the BlackBerry device simulator
Start the device simulator
Using the BlackBerry device simulator graphical user interface
Using the BlackBerry device simulator input controls
Using the BlackBerry device simulator to perform common tasks
Using the advanced BlackBerry device simulator features

About the BlackBerry device simulator

The BlackBerry device simulator is designed to emulate a true BlackBerry experience without actually using a real
BlackBerry device. The BlackBerry device simulator is an application that you install on your computer that shows
an image of the BlackBerry device model of your choice. This image has the look and feel of an actual BlackBerry
device. The functionality includes the same user interaction of an actual BlackBerry device (including the
trackwheel and the keyboard), the same applications, and the same features such as email messages, phone, and
Internet browsing. The BlackBerry device simulator also serves as a platform on which applications can run. This
includes the ability for the applications to make network connections, store data, and handle email messages.

Start the device simulator

The BlackBerry® device simulator is available either as a part of the BlackBerry Java Development Environment or
as a standalone installation of the BlackBerry simulator package. Visit www.blackberry.com/developers for more
information about downloading the BlackBerry device simulator.

Start the BlackBerry device simulator from the BlackBerry JDE

> On the taskbar, click Start > Programs > Research In Motion > BlackBerry JDE 4.2.0 > Device Simulator

Start the BlackBerry device simulator from a Simulator Package

> On the taskbar, click Start > Programs > Research In Motion > BlackBerry Device Simulators 4.2.0 > Device
Simulators 4.2.0 XYZ > <device_name>.
Simulator Guide

Using the BlackBerry device simulator graphical user

interface
Viewing or hiding the BlackBerry device image
By default, the BlackBerry® device simulator displays the BlackBerry device image. You can hide the BlackBerry
device image so that only the LCD screen is visible.

Hide the BlackBerry device image

> On the View menu, click LCD Only.

View the BlackBerry device image in full-screen mode

Full-screen mode allows you to maximize the view of the BlackBerry® device simulator. You can view either the full
BlackBerry device image or only the LCD image in full-screen mode. Since the BlackBerry device simulator only
uses integral multiples of the simulated LCD’s resolution, different screen resolution settings may result in full-
screen images that cover a larger percentage of the computer screen.
> On the View menu, click Full Screen.

Access menu options in Full-Screen mode

You can access the menu items on the BlackBerry® device simulator’s menu items by moving the mouse to the top
of the computer screen. The menu appears when the cursor is near the top of the computer screen.

Exit Full-screen mode

> On the View menu, click Full Screen.
If you are viewing the LCD screen in full-screen mode, the LCD screen stretches to its optimal zoom-level and is
padded with a black background. If you view the BlackBerry® device image in full-screen mode, the BlackBerry
device image is centered and is padded with a white background.

Change the size of the BlackBerry device image

1. On the View menu, click Zoom.
2. Click a percentage.
Note: The percentage value determines the pixel-to-pixel ratio between the simulated LCD screen and the computer screen. For
example, at 200 percent zoom level, 4 pixels on the monitor display 1 pixel of the simulated LCD screen.

Capture screen shots

The BlackBerry® device simulator can save an image of the BlackBerry that you simulate device including the LCD
screen, or the LCD screen only.

4
 1: BlackBerry device simulator

Save a screen shot

> On the Edit menu, click Save Device Snapshot or Save LCD Snapshot.
By default, the BlackBerry® device simulator saves the screen shot as the most suitable file type for the content of
the image. The BlackBerry device simulator saves a screen shot of the BlackBerry device image as a .jpg file, and a
screen shot of the LCD as a .png file. You can override the default if you click Browse and set a different file type in
the Save as type field.

Copy a screen shot to the clipboard

> On the Edit menu, click Copy Device Snapshot or Copy LCD Snapshot.

Using the BlackBerry device simulator input controls

Simulate the trackwheel and keys
Use the BlackBerry® device simulator trackwheel to simulate using the trackwheel on a BlackBerry device.

Note: Not all BlackBerry devices have all the keys listed

The BlackBerry device simulator assigns BlackBerry device functionality to the following computer keyboard and
mouse procedures:

Action Keyboard procedure Mouse procedure

Roll the trackwheel. Press the UP ARROW or DOWN ARROW key. Roll the mouse wheel button.
Click the trackwheel. Press the LEFT ARROW key. Click the mouse wheel button.
Press the Escape key. Press ESC or the RIGHT ARROW key. Click the right mouse button.
Turn on BlackBerry device Press PAGE DOWN. Click the Power button on the BlackBerry device
backlighting. simulator keyboard.
Press the Symbol key. Press DELETE. Click the Symbol key on the BlackBerry device simulator
keyboard.
Press the Alt key. Press CTRL. Click the Alt key on the BlackBerry device simulator
keyboard.
Press the BlackBerry device Press the keys on your computer keyboard. Click the keys on the BlackBerry device simulator
keys. keyboard.
Press the phone/PTT Press PAGE UP. —
(Push-to-TalkTM) button.

Using the BlackBerry device simulator to perform common

tasks
Simulate adding an address book contact
1. On the Address Book menu, click New Address.

5
Simulator Guide

2. Type contact information in the appropriate fields.

3. Open the menu.
4. Click Save.

Simulate adding a calendar entry

1. In the Calendar menu, click New.
2. Type appointment information in the appropriate fields the New Appointment screen.
3. Open the menu.
4. Click Save.

Simulate composing an email

1. In the Messages menu, click Compose Email.
2. In the To field, type an email address.
3. Set the CC, Subject, and Body fields.
4. Open the menu.
5. Click Save Draft.
The BlackBerry® email server simulator is required to simulate sending an email message. See “Simulating
sending and receiving messages” on page 11 for more information.

Simulate an incoming phone call

1. On the Simulate menu, click Incoming Voice Call.
2. In the New Incoming Call dialog box, for the originating phone number, type a new phone number or the
phone number of an existing contact.
3. Set one of the following Caller ID options:

Option Description
Allowed The BlackBerry® device can display the phone number of the originating phone.
Private The phone number of the originating phone is blocked and not available for display on the BlackBerry device.
Unknown The BlackBerry device cannot determine the phone number of the originating phone.

4. To place the phone call to the BlackBerry device simulator, click Create Call.
5. Click Answer or Ignore.
6. End the call by performing one of the following actions:

Action Procedure
Simulate the termination of the call by the originating phone. > Click Disconnect.

6
 1: BlackBerry device simulator

Action Procedure
Simulate a network failure. > Set a reason for failure. Click Fail.

Simulate an outgoing phone call

1. In the Phone menu, click Compose From Address Book.
2. In the Call field, type a new phone number or set a contact.
3. Press the Enter key.
4. Open the menu.
5. Click Continue.
6. In the Call to dialog box, perform one of the following actions:
• Click Answer.
• To simulate a failed connection, set a reason for failure. Click Fail.

Using the advanced BlackBerry device simulator features

Simulate sending an SMS text message
You can use the BlackBerry® device simulator to simulate sending an SMS text message to a server side
application. Verify that you have installed the BlackBerry Java Development Environment.
1. Clikc the Call Log icon.
2. Type the destination phone number for the SMS text message.
3. Open the menu.
4. Click SMS Text <number>.
5. Type your message.
6. Open the menu.
7. Click Send.

7
Simulator Guide

8
 2
Testing applications that require an HTTP
connection
Simulating the BlackBerry MDS Connection Service

Simulating the BlackBerry MDS Connection Service

The BlackBerry® MDS simulator is designed to simulate the BlackBerry MDS Connection Service component of
the BlackBerry Enterprise Server. Using the BlackBerry device simulator with the BlackBerry MDS simulator
enables you to test network, push, and browser applications that are designed for use with a BlackBerry Enterprise
Server. If you are testing applications that require an HTTP connection, you will require the BlackBerry device
simulator and the BlackBerry MDS simulator. The BlackBerry MDS simulator is available for download from the
BlackBerry Developer Zone web site at http://www.blackberry.com/developers.

Starting the BlackBerry MDS Simulator

> On the taskbar, click Start > Programs > Research In Motion > BlackBerry Email and MDS Services
Simulators 4.1.2 > MDS.

Testing Starting the BlackBerry MDS Simulator

1. Start the BlackBerry device simulator.
2. In the BlackBerry device simulator, open the BlackBerry Browser.
3. Open the menu.
4. Click Go To.
5. Type http://www.blackberry.com/go/mobile/.
6. Click OK.
If the BlackBerry home page appears, the BlackBerry MDS simulator is working.
If an error message indicates that the browser cannot connect to the BlackBerry MDS simulator, verify that
you started the BlackBerry MDS simulator.
Simulator Guide

10
 3
Testing messaging applications
Simulating sending and receiving messages

Simulating sending and receiving messages

The BlackBerry email server simulator is designed to send and receive messages between the BlackBerry device
simulator and either a messaging application, such as Microsoft® Outlook®, or POP3 and SMTP servers. You do
not require a BlackBerry Enterprise Server. The BlackBerry email server simulator is available for download from
the BlackBerry Developer Zone web site at http://www.blackberry.com/developers.

Sending and receiving messages using the BlackBerry device simulator

The following instructions assume you have access to a BlackBerry device simulator. The BlackBerry device
simulator and accompanying documentation are available for download from the RIM BlackBerry developer web
site.

Send a message using the BlackBerry device simulator

1. Start the email server simulator.
2. In the Email Server Simulator window, ensure the Standalone mode option radio button is selected.
3. Click Launch.
4. Start the BlackBerry device simulator.
5. Navigate to the Messages icon.
6. Open the Messages Application.
7. Open the menu.
8. Click Compose Email.
9. In the To field, type an email address.
10. Fill in the Cc, Subject, and Body fields.
11. Open the menu.
12. Click Send.

Receive a message using the BlackBerry device simulator

The following instructions assume you have access to a BlackBerry device simulator. The BlackBerry device
simulator and accompanying documentation are available for download from the RIM BlackBerry developer web
site.
Simulator Guide

1. Start the email server simulator.

2. In the Email Server Simulator window, ensure the Standalone mode option radio button is selected.
3. Click Launch.
4. Start the BlackBerry device simulator. See "Start the device simulator" on page 3 for more information.
5. When the BlackBerry device simulator receives an email, open the Messages application.

12