JavaScript Reference

Local Navigation

BlackBerry extension APIs

Object

Description

Availability

blackberry

Provides network information for a BlackBerry device.

3.8 or later

blackberry.launch

Provides access to other BlackBerry applications on the device.

5.0 or later

blackberry.location

Provides access to the GPS location information for the BlackBerry device.

4.1 or later

Object: blackberry

Availability

BlackBerry Device Software version 4.0 or later

The blackberry object is a property of the Window object. It provides information about the network on which the BlackBerry device is running, and the global position of the BlackBerry device.

Back To Top

blackberry properties

Property name

Type

Description

Status

Availability

location

blackberry.location

Returns a pointer to the blackberry.location object.

This property is available for BlackBerry Device Software Version 4.1 or later.

read only

4.1 or later

network

String

Returns the wireless network on which the BlackBerry device is communicating. The value may be one of:

  • 3GPP
  • CDMA
  • iDEN
  • Wi-Fi

Multiple networks may be supported on a single BlackBerry device. If multiple networks are supported, they are returned as a comma-separated list. For example:

3GPP,Wi-Fi

read only

4.0 or later

Back To Top

Object: blackberry.launch

Availability

BlackBerry Device Software 5.0 or later

The blackberry.launch object provides methods that lets you access core and add-on BlackBerry applications through JavaScript. Depending on the application, you can either launch the application or open the application and create a new item, such as a calendar entry or a task, and prepopulate any of the entry fields. Although the methods of the blackberry.launch object can open and create new items for an application, changes are not made to the application without confirmation from the user. For example, if you use the blackberry.launch object to make a phone call to a specific phone number, the user is prompted to confirm whether the user wants to proceed with the call before the number is dialed. Similarly, if you create a new item for any application, the user must save the item before it is added to that application.

Parameters for the blackberry.launch methods are provided in the form of a single JSON object. For example, to open BlackBerry Maps and display a set of coordinates, you could use the blackberry.launch.newMap() method as follows:

blackberry.launch.newMap({"latitude":4328915, "longitude":-8032480});

When a JSON object is identified as the parameter of a method, it is required. However, the members contained within the JSON object are all optional. For example, you can specify an empty JSON object as the parameter to a method, as long as the JSON object (identified by the braces) is present. For example:

blackberry.launch.newMap({});
Back To Top

blackberry.launch methods

Method name

Description

Availability

launchCamera()

Opens the Camera application.

5.0 or later

launchVideoRecorder()

Opens the Video Camera application.

5.0 or later

launchVoicemail()

Opens the Phone application to call the voice mail account that is associated with the BlackBerry device.

5.0 or later

newAppointment()

Creates a new appointment in the Calendar application.

5.0 or later

newContact()

Adds a new contact to the Contacts list.

5.0 or later

newMap()

Opens the BlackBerry Maps application and displays the specified location.

5.0 or later

newMemo()

Creates a new memo in the Memo application.

5.0 or later

newPhoneCall()

Opens the phone application to call a specific phone number.

5.0 or later

newSMS()

Creates a new SMS text message.

5.0 or later

newTask()

Creates a new task in the Tasks application.

5.0 or later

Back To Top

Method: blackberry.launch.launchCamera()

Availability

BlackBerry Device Software 5.0 or later

The launchCamera() method permits you to open the camera application on the BlackBerry device.

Syntax

blackberry.launch.launchCamera()

Parameters

None.

Return values

None.

Code sample: Opening the camera application on the BlackBerry device

<html>
    <body>
        <div id="camera" onClick="blackberry.launch.launchCamera()">Click here to start 
                the camera application on your BlackBerry device!</div>
    </body>
</html> 
Back To Top

Method: blackberry.launch.launchVideoRecorder()

Availability

BlackBerry Device Software 5.0 or later

The launchVideoRecorder() method opens the video recorder on the BlackBerry device.

Syntax

blackberry.launch.launchVideoRecorder()

Parameters

None.

Return values

None.

Code sample: Opening the video recorder application

<html>
    <body>
        <div id="video" onClick="blackberry.launch.launchVideoRecorder()">Click here to 
                launch the video recorder on your BlackBerry device!</div>
    </body>
</html> 
Back To Top

Method: blackberry.launch.launchVoicemail()

Availability

BlackBerry Device Software 5.0 or later

The launchVoicemail() method permits you to call the voice mail account that is associated with a BlackBerry device. Before the call is placed, the phone application prompts the user to confirm whether they want to proceed with the call.

Syntax

blackberry.launch.launchVoicemail()

Parameters

None.

Return values

None.

Code sample: Calling the BlackBerry device user's voice mail using JavaScript

<html>
    <body>
        <div id="voicemail" onClick="blackberry.launch.launchVoicemail()">Click here to check your messages.</div>
    </body>
</html>
Back To Top

Method: blackberry.launch.newAppointment()

Availability

BlackBerry Device Software 5.0 or later

The newAppointment() method creates a new appointment in the calendar application. The user must save the appointment before it is saved to the calendar.

Syntax

blackberry.launch.newAppointment({ summary, location, allDay, start, end, freeBusy, note })

JSON object members

Member

Type

Description

summary

String

Briefly summarizes the reason for the appointment. This value is used to identify this appointment in the calendar.

location

String

Specifies the location of the appointment.

allDay

Boolean

When true, indicates whether the appointment should be scheduled for the whole day. An all-day event is considered an entire work day, from 9:00 AM to 5:00 PM.

start

Date

Specifies the start time of the appointment.

end

Date

Specifies the end time of the appointment.

freeBusy

integer

Specifies how the time is marked in the user's calendar. You can specify one of the following values:

  • 0: free
  • 1: busy
  • 2: tentative
  • 3: out of office

note

String

Specifies text that is included as a part of the appointment.

Return values

None.

Exceptions

None.

Code sample: Creating a new appointment for the calendar application

// Define the start and end times as JavaScript Date objects
var startTime = new Date(2010,10,10,2);
var endTime = new Date(2010,0,1,3,29);

// Create the JSON object that defines all the appointment 
// information as name-value pairs 
var appointmentInfo = {
    "summary":"Meet new VP"
    "location":"Conference room 2"
    "allDay":false
    "start":startTime
    "end":endTime
    "freeBusy":1
    "note":"Refreshments will be served."
};

// Create a new appointment with the new JSON object as a parameter
blackberry.launch.newAppointment(appointmentInfo);
Back To Top

Method: blackberry.launch.newContact()

Availability

BlackBerry Device Software 5.0 or later

The newContact() method creates a contact in the BlackBerry device user's contact list. The user must save the new contact before it is added to the contact list.

Syntax

blackberry.launch.newContact({ title, firstName, lastName, 
        company, jobTitle, email, workPhone, workPhone2, homePhone, 
        homePhone2, mobilePhone, pagerPhone, faxPhone, otherPhone, 
        pin, workAddress, homeAddress, birthday, anniversary, 
        webpage, user1, user2, user3, user4, note })

JSON object members

Member

Type

Description

title

String

Specifies the contact's title, such as Mr, Mrs, or Dr.

firstName, lastName

String

Specify the contact's first name and last name.

company

integer

Specifies the organization that the contact belongs to.

jobTitle

String

Specifies a job title for the contact.

email

array

Specifies an array of email addresses for the contact. The array contains a comma-separated list of strings, each representing an email address. The contents of the array are enclosed in brackets. For example:

["email1@company1.com", "email2@company2.com"]

workPhone, workPhone2, homePhone, homePhone2, mobilePhone, pagerPhone, faxPhone, otherPhone

String

Specify assorted phone numbers for the contact.

pin

String

Specifies a BlackBerry device PIN for the contact.

workAddress, homeAddress

Address

Specify various addresses for the contact, represented by an Address JSON object.

birthday, anniversary

Date

Specify important dates for the contact, represented by a JavaScript Date object.

webpage

String

Specifies a web page for the contact.

user1, user2, user3, user4, note

String

Specify additional information for the contact.

Return values

None.

Exceptions

None.

Code sample: Creating a new contact

var workAddress = {
    "address1":"295 Phillip Street",
    "city":"Waterloo",
    "country":"Canada",
    "stateProvince":"ON",
    "zipPostal":"N2L3WE"
};
var bday = new Date(1978,3,22);

var contactInfo={
    "title":"Ms"
    "firstName":"Karen"
    "lastName":"Moser"
    "email":[ "too_cool@internet.com", "KM_2@work.com" ]
    "pin":"2100000A"
    "workAddress":workAddress
    "birthDay":bday
};
blackberry.launch.newContact(contactInfo);
Back To Top

Method: blackberry.launch.newMap()

Availability

BlackBerry Device Software5.0 or later

The newMap() method opens BlackBerry Maps and displays a specified location on the map. You can specify a location using one of three following ways:

  • specify the latitude and longitude
  • specify an address
  • specify a location document

Syntax

blackberry.launch.newMap({ latitude, longitude })

OR

blackberry.launch.newMap({ address })

OR

blackberry.launch.newMap({ locationDocument })

JSON object members

Member

Type

Description

latitude

double

Specifies the latitude in decimal degrees to five decimal places. A positive value indicates a northern latitude; a negative value indicates a southern latitude.

For example, to indicate a latitude of 43°N, specify a value of 43. To indicate a latitude of 42.5°S, specify a value of -42.5

longitude

double

Specifies the longitude in decimal degrees to five decimal places. A positive value indicates an eastern longitiude; a negative value indicates a western longitude.

For example, to indicate a longitude of 80°W, specify a value of -80.

address

Address

Specifies address information, represented by an Address JSON object.

locationDocument

String

Specifies an XML location document. This XML structure is specific to BlackBerry Maps.

Return values

None.

Exceptions

None.

Code sample: Displaying a set of geographic coordinates in BlackBerry Maps

blackberry.launch.newMap({
        "latitude":43.46518, 
    				"longitude":-80.52237
});
var workAddress = {
    "address1":"295 Phillip Street",
    "city":"Waterloo",
    "country":"Canada",
    "stateProvince":"ON",
    "zipPostal":"N2L3WE"
};

blackberry.launch.newMap({"address":workAddress});
blackberry.launch.newMap({
    "locationDocument":"<lbs id=\"Waterloo\">
         <location x=\"-8052237\" y=\"4346518\" label=\"Waterloo, ON\" description=\"Waterloo\" zoom=\"10\" \/>
    <\/lbs>" 
});
Back To Top

Method: blackberry.launch.newMemo()

Availability

BlackBerry Device Software 5.0 or later

The newMemo() opens the memo application and creates a new memo item.

Syntax

blackberry.launch.newMemo({ title, note })

JSON object members

Member

Type

Description

title

String

Specifies the title for the memo. This value is used to identify this memo in the list of memo items in the memo application.

note

String

Specifies the memo text.

Return values

None.

Code sample: Creating a new memo

blackberry.launch.newMemo({ "title":"Note to self", "note":"The rain in spain falls mainly on the plain" });
Back To Top

Method: blackberry.launch.newSMS()

Availability

BlackBerry Device Software 5.0 or later

The newSMS() method creates a new SMS text message that a user can send to a specified phone number.

This method does not send the SMS text message. The user must send the SMS text message manually.

Syntax

blackberry.launch.newSMS({ number, text })

JSON object members

Member

Type

Description

number

String

The number to send the SMS text message to. The number is specified as a string and must be enclosed by quotation marks.

text

String

The text in the SMS text message to send to the specified number.

Return values

None.

Exceptions

None.

Code sample: Sending an SMS message

blackberry.launch.newSMS({ "number":"5198887465", "text":"This is a very important message!" });
Back To Top

Method: blackberry.launch.newPhoneCall()

Availability

BlackBerry Device Software 5.0 or later

The newPhoneCall() method opens the phone application to call a specified phone number.

Syntax

blackberry.launch.newPhoneCall({ dialString, smartDialing })

JSON object members

Member

Type

Description

dialString

String

Specifies the phone number to call. The phone number is specified as a string and must be enclosed by quotation marks.

smartDialing

Boolean

When true, indicates that the phone application should apply the Smart Dialing options that the BlackBerry device user specified in the Phone options. Smart dialing permits the user to configure a default country code and area code for phone numbers. The phone application prepends these values automatically when it dials a phone number.

Return values

None.

Exceptions

None.

Code sample: Making a phone call

<html>
    <body>
        <div id="phone" onClick="blackberry.launch.newPhoneCall({ 
                              "dialString":"15198887465", 
                              "smartDialing":false })">
            <p>Click here to call now!</p>
        </div>
    </body>
</html>
Back To Top

Method: blackberry.launch.newTask()

Availability

BlackBerry Device Software 5.0 or later

The newTask() method creates a new task in the tasks application.

Syntax

blackberry.launch.newTask({ summary, status, priority, due, note })

JSON object members

Member

Type

Description

summary

String

Briefly summarizes the purpose of the task. This value is used to identify this task in the tasks application.

status

integer

Specifies the current status of the task. This parameter can have one of the following values:

  • 0: Not started
  • 1: In progress
  • 2: Completed
  • 3: Waiting
  • 4: Deferred

priority

integer

Specifies the priority of the task. This parameter can have one of the following values:

  • 0: High
  • 1: Normal
  • 2: Low

due

Date

Specifies a JavaScript Date object that represents the due date of the task.

note

String

Specifies a detailed description of the task.

Return values

None.

Exceptions

None.

Code sample: Creating a new task

// set the task completion date for one week from today 
var currentDate = new Date();
var DateInMilliseconds = currentDate.getTime();
var completeDate = DateInMilliseconds + 604 800 000;

// Create a JSON object that specifies the task properties
var taskProperties = {
    "summary":"Create new business proposal",
    "status":0,
    "priority":0,
    "due":completeDate,
    "note":"Complete this proposal on time!!"
};

// create a new task with the new JSON object as a parameter
blackberry.launch.newTask(taskProperties);
Back To Top

JSON Object: Address

Availability

BlackBerry Device Software 5.0 or later

The Address object is a JSON object that contains address information used by the methods of the blackberry.launch object.

Syntax

{ address1, address2, city, stateProvince, country, zipPostal }

JSON object members

Member

Type

Description

address1

String

Specifies the street address.

address2

String

Specifies additional address information.

city

String

Specifies the city that the address is located in.

stateProvince

String

Specifies the state or province that the address is located in.

country

String

Specifies the country that the address is located in.

zipPostal

String

Specifies the zip code or postal code of the address.

Back To Top

Object: blackberry.location

Availability

BlackBerry Device Software version 4.1 or later

The blackberry.location object is a property of the blackberry object. It provides access to the GPS location of the BlackBerry device. The GPS location refers to the geographical co-ordinates, latitude and longitude, of the BlackBerry device.

Back To Top

blackberry.location properties

Property name

Type

Description

Status

Availability

GPSSupported

boolean

When true, this property indicates that GPS positioning is supported by the BlackBerry device.

read only

4.1 or later

latitude

double

Returns the current latitude, in degrees, of the BlackBerry device. Positive values indicate northern latitude, negative values indicate southern latitude.

To ensure that the most accurate co-ordinate is returned, you should register a listener using blackberry.location.onLocationUpdate() and acquire the location information within the callback.

read only

4.1 or later

longitude

double

Returns the current longitude, in degrees, of the BlackBerry device. Positive values indicate eastern longitude, negative values indicate western longitude.

To ensure that the most accurate co-ordinate is returned, you should register a listener using blackberry.location.onLocationUpdate() and read acquire the location information within the callback.

read only

4.1 or later

timestamp

unsigned long

Returns time (in milliseconds since epoch) at which the blackberry.location object was updated.

This property is only supported on BlackBerry devices running BlackBerry Device Software version 4.6 or later.

read only

4.6 or later

Back To Top

blackberry.location methods

Method name

Description

Availability

onLocationUpdate()

Registers a callback method that is called when the location is updated using blackberry.location.refreshLocation().

4.1 or later

refreshLocation()

Requests an update of the location of the BlackBerry device.

4.1 or later

removeLocationUpdate()

Removes a previously registered callback method.

4.6 or later

setAidMode()

Specifies which method the BlackBerry device will use to obtain the GPS location.

4.1 or later

Back To Top

Method: blackberry.location.onLocationUpdate()

Availability

BlackBerry Device Software version 4.1 or later

The onLocationUpdate() method registers a listener that evaluates a string or calls a function whenever the BlackBerry device receives updated location information.

On BlackBerry devices running versions of BlackBerry Device Software earlier than version 4.6, this method must be passed as a string that is evaluated each time the location is refreshed. On BlackBerry devices running BlackBerry Device Software version 4.6 or later, you can pass a string, or use the method to register a callback function.

Once onlocationUpdate() has been invoked, the callback occurs whenever there is an update to the location information. This can be as frequent as once every several seconds. If you have passed the method a function, you can cancel the callback using blackberry.location.removeLocationUpdate(). If you have passed a string, the callback cannot be removed.

Syntax

blackberry.location.onLocationUpdate( callbackFunction | callbackString )

Parameters

Parameter

Type

Description

callbackFunction

Function

A JavaScript function.

For BlackBerry devices running versions of the BlackBerry Device Software that are earlier than version 4.6, you must specify the callback as a string.

callbackString

String

A string to be evaluated when the location information is updated.

Return values

None.

Exceptions

None.

Back To Top

Method: blackberry.location.refreshLocation()

Availability

BlackBerry Device Software version 4.1 or later

The refreshLocation() method requests an update of the location of the BlackBerry device.

This method is asynchronous, so the script continues regardless of whether updated location information has been received. To ensure that location information is updated before reading it, you should first register a listener using blackberry.location.onLocationUpdate() that reads blackberry.location.latitude and blackberry.location.longitude , and then call refreshLocation() afterwards.

Syntax

blackberry.location.refreshLocation()

Parameters

None.

Return values

Returns true if the GPS location of the BlackBerry device is successfully updated; otherwise, returns false.

Exceptions

None.

Back To Top

Method: blackberry.location.removeLocationUpdate()

Availability

BlackBerry Device Software version 4.6 or later

The removeLocationUpdate() method removes a previously registered callback method.

This method is only supported on BlackBerry devices running BlackBerry Device Software version 4.6 or later.

Syntax

blackberry.location.removeLocationUpdate( callbackFunction )

Parameters

Parameter

Type

Description

callbackFunction

Function

A JavaScript function previously registered by blackberry.location.onLocationUpdate().

Return values

None.

Exceptions

None.

Back To Top

Method: blackberry.location.setAidMode()

Availability

BlackBerry Device Software version 4.1 or later

The setAidMode() method specifies which method the BlackBerry device will use to obtain the GPS location.

The device can obtain location information in one of three ways.

Aid Mode

Value

Description

Cellsite

0

This method uses the GPS location of the active cellsite tower to provide first order GPS information. It provides the least accurate location information; however, it is the fastest location mode.

This location method requires network connectivity and carrier support.

Assisted

1

This method uses the network to provide ephemeris satellite data to the device chip. It provides the GPS location faster than the autonomous mode and more accurately than the cellsite mode.

This location method requires network connectivity and carrier support.

Autonomous

2

This method uses the GPS chip on the BlackBerry device without assistance from the network. The autonomous mode provides the first GPS location in the slowest amount of time.

Syntax

blackberry.location.setAidMode( aidMode )

Parameters

Parameter

Type

Description

aidMode

int

The method used to obtain the GPS location. The value for this parameter may be one of:

  • 0 — Cellsite

  • 1 — Assisted

  • 2 — Autonomous

Return values

None.

Back To Top

Was this information helpful? Send us your comments.