Object: blackberry.launch

Help Center

Search This Document

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({});

blackberry.launch methods

Method name	Description	Availability
`launchCamera()`	Opens the Camera application.	5.0 or later
`launchVideoRedorder()`	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

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>

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>

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>

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);

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);

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 })

blackberry.launch.newMap({ address })

blackberry.launch.newMap({ locationDocument })

JSON object members

Member	Type	Description
`latitude`	double	Specifies the latitude in decimal degrees to five decimal places, multiplied by 100,000. A negative value indicates a southern latitude. For example, to indicate a latitude of 43°N, specify a value of 4,300,000.
`longitude`	double	Specifies the longitude in decimal degrees to five decimal places, multiplied by 100,000. A negative value indicates a western longitude. For example, to indicate a longitude of 80°W, specify a value of -8,000,000.
`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":4346518, 
    				"longitude":-8052237
});

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>" 
});

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" });

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!" });

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>

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);

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.

Next topic: Object: blackberry.location

Previous topic: blackberry properties

Was this information helpful? Send us your comments.

Global Navigation

Help Center

Local Navigation