Dialog
The Dialog object contains functions for manipulating system dialog boxes.
The functionality in this object allows you to integrate standard system dialog boxes into your BlackBerry WebWorks Application and control your application flow based on user responses.Supported Platform(s)
- BlackBerry OS 5.0+
- BlackBerry PlayBook
- Ripple Emulator
| API | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
|---|---|---|---|---|---|
| customAsk | Y | Y | Y | ||
| customAskAsync | Y | Y | |||
| standardAsk | Y | Y | Y | ||
| standardAskAsync | Y | Y | |||
| D_OK | Y | Y | Y | Y | Y |
| D_SAVE | Y | Y | Y | Y | Y |
| D_DELETE | Y | Y | Y | Y | Y |
| D_YES_NO | Y | Y | Y | Y | Y |
| D_OK_CANCEL | Y | Y | Y | Y | Y |
| C_CANCEL | Y | Y | Y | Y | |
| C_OK | Y | Y | Y | Y | |
| C_SAVE | Y | Y | Y | Y | |
| C_DISCARD | Y | Y | Y | Y | |
| C_DELETE | Y | Y | Y | Y | |
| C_YES | Y | Y | Y | Y | |
| C_NO | Y | Y | Y | Y | |
| BOTTOM | Y | Y | |||
| CENTER | Y | Y | |||
| TOP | Y | Y | |||
| SIZE_FULL | Y | Y | |||
| SIZE_LARGE | Y | Y | |||
| SIZE_MEDIUM | Y | Y | |||
| SIZE_SMALL | Y | Y | |||
| SIZE_TALL | Y | Y |
Configuration Document Settings
To use all of the API described for this object, you must ensure the following settings are in your configuration document:
You must declare the feature element(s) below in your configuration document:
| Feature ID | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
|---|---|---|---|---|---|
| <feature id="blackberry.ui.dialog" /> | Y | Y | Y | Y | Y |
| Permission Elements (PlayBook Only) |
|---|
| This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application. |
API Summary
Functions
customAsk
| static Number customAsk(message : String, choices : String[], [defaultChoice: Number], [globalStatus: Boolean]) |
Supported Platform(s)
- BlackBerry OS 5.0+Description
Creates a dialog to ask the user a question. The dialog uses the standard question mark bitmap. The function will block execution and when the user selects an option it will return the index of the choice selected by the user.
Returns
The index of the choice selected by the user.| Parameter | Type | Description |
|---|---|---|
| message | String | Message to be displayed in the dialog. |
| choices | String[] | Array of string choices that will be presented to the user in the form of buttons. |
| defaultChoice |
Number
Optional |
[Default Value: 0] Optional parameter that specifies what choice should be selected by default. This is a number value representing the index of the choice provided in the choices parameter. |
| globalStatus |
Boolean
Optional |
[Default Value: false]
If set to true it adds a screen to the queue of displayed global status screens. Global status screens appear on top of all other screens on the PlayBook, even if the current application is not in the foreground. If no other status screens are currently displayed, your provided screen appears immediately. NOTE: If the app is in the background and globalStatus is set to true, the app WILL NOT be brought to the foreground. |
Code Example(s)
<script type="text/javascript">
function globalDialog() {
var ss = ["Saab", "Volvo", "BMW", "Subaru"];
var ret = blackberry.ui.dialog.customAsk("Select your favorite car", ss, 2, true);
document.getElementById('carSelect').innerHTML = ss[ret]
}
</script>
customAskAsync
| static void customAskAsync(message : String, buttons : String[], [onOptionSelected: function], [settings: Object]) |
Supported Platform(s)
- BlackBerry PlayBook- Ripple Emulator
Description
Creates an asynchronous custom dialog to ask the user a question.
Uses the custom dialog. The function is an asynchronous call and will not block execution. It will return the 0-based index of the user's choice.| Parameter | Type | Description |
|---|---|---|
| message | String | Message to be displayed in the dialog. |
| buttons | String[] | Array of string choices that will be presented to the user in the form of buttons. |
| onOptionSelected |
function([index: Number])
Optional |
Optional callback function that will be invoked when the user makes a selection. Expected signature: function onOptionSelected(selectedButtonIndex).
index: The index of the selection the user has made. |
| settings |
Object
Optional |
[Default Value: null]
Optional Object literal that allows the user to manipulate the size, location, title of the dialog, and whether this is a global dialog (your application cannot be minimized when a global dialog is active; by default when the 'global' flag is not passed, dialog will be modal only for your application). It is not required to provide all parameters, and these do not have to be specified in any particular order.
title: Desired title of the dialog. size: Desired size of the dialog. position: Desired position of the dialog. |
Code Example(s)
<script type="text/javascript">
function dialogCallBack(index){
alert(index);
}
function customDialog() {
try {
var buttons = ["Yes", "No", "Sometimes", "NA"];
var ops = {title : "Choose the answer that describes you best", size : blackberry.ui.dialog.SIZE_TALL, position : blackberry.ui.dialog.LOC_CENTER};
blackberry.ui.dialog.customAskAsync("Do you routinely work out?", buttons, dialogCallBack, ops);
} catch(e) {
alert("Exception in customDialog: " + e);
}
}
</script>
standardAsk
| static Number standardAsk(specifies : Number, message : String, [defaultChoice: Number], [globalStatus: Boolean]) |
Supported Platform(s)
- BlackBerry OS 5.0+Description
Creates a standard dialog to ask the user a question.
Returns
The index of the choice selected by the user.| Parameter | Type | Description |
|---|---|---|
| specifies | Number | the type of standard dialog. Constants starting with D_*. |
| message | String | Message to be displayed in the dialog. |
| defaultChoice |
Number
Optional |
[Default Value: 0] Optional parameter that specifies what choice should be selected by default. For the standard dialogs, these options can be one of the constants starting with C_*. |
| globalStatus |
Boolean
Optional |
[Default Value: false]
If set to true it adds a screen to the queue of displayed global status screens. Global status screens appear on top of all other screens on the PlayBook, even if the current application is not in the foreground. If no other status screens are currently displayed, your provided screen appears immediately. NOTE: If the app is in the background and globalStatus is set to true, the app WILL NOT be brought to the foreground. |
Code Example(s)
<script type="text/javascript">
function launchDialog() {
setTimeout(globalDialog, 5000);
return;
}
function globalDialog() {
var ss = ["Saab", "Volvo", "BMW"];
var ret = blackberry.ui.dialog.customAsk("Select your favorite car", ss, 2, true);
blackberry.ui.dialog.standardAsk(blackberry.ui.dialog.D_OK, "You selected " + ss[ret], 0, true);
}
</script">
standardAskAsync
| static void standardAskAsync(message : String, type : Number, [onOptionSelected: function], [settings: Object]) |
Supported Platform(s)
- BlackBerry PlayBook- Ripple Emulator
Description
Creates an asynchronous standard dialog to ask the user a question.
Uses the standard dialog. The function is an asynchronous call and will not block execution. It will return the 0-based index of the user's choice.| Parameter | Type | Description |
|---|---|---|
| message | String | Message to be displayed in the dialog. |
| type | Number | Parameter that specifies the type of standard dialog. Constants starting with D_*. |
| onOptionSelected |
function([index: Number])
Optional |
Optional callback function that will be invoked when the user makes a selection. Expected signature: function onOptionSelected(selectedButtonIndex).
index: The index of the selection the user has made. |
| settings |
Object
Optional |
[Default Value: null]
Optional Object literal that allows the user to manipulate the size, location, title of the dialog, and whether this is a global dialog (your application cannot be minimized when a global dialog is active; by default when the 'global' flag is not passed, dialog will be modal only for your application). It is not required to provide all parameters, and these do not have to be specified in any particular order.
title: Desired title of the dialog. size: Desired size of the dialog. position: Desired position of the dialog. |
Code Example(s)
<script type="text/javascript">
function dialogCallBack(index){
alert(index);
}
function standardDialog() {
try {
blackberry.ui.dialog.standardAskAsync("Save?", blackberry.ui.dialog.D_SAVE, dialogCallBack, {title : "Save Dialog", size: blackberry.ui.dialog.SIZE_MEDIUM, position : blackberry.ui.dialog.LOC_BOTTOM});
}catch (e) {
alert("Exception in standardDialog: " + e);
}
}
</script>
Constants:
| Property | Type | Description | Supported Platform(s) |
|---|---|---|---|
| D_OK default: 0 | Number |
Standard OK dialog
|
- BlackBerry OS 5.0+
- BlackBerry PlayBook - Ripple Emulator |
| D_SAVE default: 1 | Number |
Standard Save dialog
|
- BlackBerry OS 5.0+
- BlackBerry PlayBook - Ripple Emulator |
| D_DELETE default: 2 | Number |
Standard Delete confirmation dialog
|
- BlackBerry OS 5.0+
- BlackBerry PlayBook - Ripple Emulator |
| D_YES_NO default: 3 | Number |
Standard Yes/No dialog
|
- BlackBerry OS 5.0+
- BlackBerry PlayBook - Ripple Emulator |
| D_OK_CANCEL default: 4 | Number |
Standard OK/Cancel dialog
|
- BlackBerry OS 5.0+
- BlackBerry PlayBook - Ripple Emulator |
| C_CANCEL default: -1 | Number |
Cancel Choice for us in dialogs
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| C_OK default: 0 | Number |
OK choice for use in dialogs
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| C_SAVE default: 1 | Number |
SAVE choice for use in dialogs
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| C_DISCARD default: 2 | Number |
DISCARD choice for use in dialogs
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| C_DELETE default: 3 | Number |
DELETE choice for use in dialogs
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| C_YES default: 4 | Number |
YES choice for use in dialogs
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| C_NO default: -1 | Number |
NO choice for use in dialogs
|
- BlackBerry OS 5.0+
- Ripple Emulator |
| BOTTOM default: "bottomCenter" | String |
Bottom located dialog
|
- BlackBerry PlayBook
- Ripple Emulator |
| CENTER default: "middleCenter" | String |
Center located dialog
|
- BlackBerry PlayBook
- Ripple Emulator |
| TOP default: "topCenter" | String |
Top located dialog
|
- BlackBerry PlayBook
- Ripple Emulator |
| SIZE_FULL default: "full" | String |
Full size dialog
|
- BlackBerry PlayBook
- Ripple Emulator |
| SIZE_LARGE default: "large" | String |
Large size dialog
|
- BlackBerry PlayBook
- Ripple Emulator |
| SIZE_MEDIUM default: "medium" | String |
Medium size dialog
|
- BlackBerry PlayBook
- Ripple Emulator |
| SIZE_SMALL default: "small" | String |
Small size dialog
|
- BlackBerry PlayBook
- Ripple Emulator |
| SIZE_TALL default: "tall" | String |
Tall size dialog
|
- BlackBerry PlayBook
- Ripple Emulator |
Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:17 GMT-0500 (EST)