BlackBerry Java Development EnvironmentVersion 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.

Published in Canada

Research In Motion Limited 295 Phillip Street Waterloo, ON N2L 3W8 Canada

Research In Motion UK Limited Centrum House, 36 Station Road Egham, Surrey TW20 9LF United Kingdom

Contents1 BlackBerry device simulator ............................................................................................................................... 3

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

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

3 Testing messaging applications ....................................................................................................................... 11Simulating sending and receiving messages ...............................................................................................11

1

BlackBerry device simulator

About the BlackBerry device simulatorThe 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 simulatorThe 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>.

About the BlackBerry device simulatorStart the device simulatorUsing the BlackBerry device simulator graphical user interfaceUsing the BlackBerry device simulator input controlsUsing the BlackBerry device simulator to perform common tasksUsing the advanced BlackBerry device simulator features

Simulator Guide

Using the BlackBerry device simulator graphical user interface

Viewing or hiding the BlackBerry device imageBy 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 modeFull-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 modeYou 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 image1. On the View menu, click Zoom.

2. Click a percentage.

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

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.

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 keysUse the BlackBerry® device simulator trackwheel to simulate using the trackwheel on a BlackBerry device.

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

Using the BlackBerry device simulator to perform common tasks

Simulate adding an address book contact1. On the Address Book menu, click New Address.

Note: Not all BlackBerry devices have all the keys listed

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 backlighting.

Press PAGE DOWN. Click the Power button on the BlackBerry device 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 keys.

Press the keys on your computer keyboard. Click the keys on the BlackBerry device simulator keyboard.

Press the phone/PTT (Push-to-TalkTM) button.

Press PAGE UP. —

5

Simulator Guide

2. Type contact information in the appropriate fields.

3. Open the menu.

4. Click Save.

Simulate adding a calendar entry1. 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 email1. 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 call1. 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:

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:

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.

Action Procedure

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

6

1: BlackBerry device simulator

Simulate an outgoing phone call1. 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 messageYou 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.

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

Action Procedure

7

Simulator Guide

8

2

Testing applications that require an HTTP connection

Simulating the BlackBerry MDS Connection ServiceThe 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 Simulator1. 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.

Simulating the BlackBerry MDS Connection Service

Simulator Guide

10

3

Testing messaging applications

Simulating sending and receiving messagesThe 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 simulatorThe 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 simulator1. 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 simulatorThe 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.

Simulating sending and receiving messages

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