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
- Supported Platform Table: Expand

Configuration Document Settings
To use all of the API described for this object, you must ensure the following settings are in your configuration document:
Feature Elements
You must declare the feature element(s) below in your configuration document:
Feature ID OS 5.0 OS 6.0 OS 7.0 PlayBook
<feature id="blackberry.ui.dialog" /> 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.

Functions


Constants

blackberry.ui.dialog.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>

blackberry.ui.dialog.customAskAsync


static void customAskAsync(message : String, buttons : String[], [onOptionSelected: function], [settings: Object])

Supported Platform(s)
 - BlackBerry PlayBook

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>

blackberry.ui.dialog.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">

blackberry.ui.dialog.standardAskAsync


static void standardAskAsync(message : String, type : Number, [onOptionSelected: function], [settings: Object])

Supported Platform(s)
 - BlackBerry PlayBook

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:


Constant Type Description Supported Platform(s)
blackberry.ui.dialog.D_OK Number = 0 Standard OK dialog  - BlackBerry OS 5.0+
 - BlackBerry PlayBook
blackberry.ui.dialog.D_SAVE Number = 1 Standard Save dialog  - BlackBerry OS 5.0+
 - BlackBerry PlayBook
blackberry.ui.dialog.D_DELETE Number = 2 Standard Delete confirmation dialog  - BlackBerry OS 5.0+
 - BlackBerry PlayBook
blackberry.ui.dialog.D_YES_NO Number = 3 Standard Yes/No dialog  - BlackBerry OS 5.0+
 - BlackBerry PlayBook
blackberry.ui.dialog.D_OK_CANCEL Number = 4 Standard OK/Cancel dialog  - BlackBerry OS 5.0+
 - BlackBerry PlayBook
blackberry.ui.dialog.C_CANCEL Number = -1 Cancel Choice for us in dialogs  - BlackBerry OS 5.0+
blackberry.ui.dialog.C_OK Number = 0 OK choice for use in dialogs  - BlackBerry OS 5.0+
blackberry.ui.dialog.C_SAVE Number = 1 SAVE choice for use in dialogs  - BlackBerry OS 5.0+
blackberry.ui.dialog.C_DISCARD Number = 2 DISCARD choice for use in dialogs  - BlackBerry OS 5.0+
blackberry.ui.dialog.C_DELETE Number = 3 DELETE choice for use in dialogs  - BlackBerry OS 5.0+
blackberry.ui.dialog.C_YES Number = 4 YES choice for use in dialogs  - BlackBerry OS 5.0+
blackberry.ui.dialog.C_NO Number = -1 NO choice for use in dialogs  - BlackBerry OS 5.0+
blackberry.ui.dialog.BOTTOM String = "bottomCenter" Bottom located dialog  - BlackBerry PlayBook
blackberry.ui.dialog.CENTER String = "middleCenter" Center located dialog  - BlackBerry PlayBook
blackberry.ui.dialog.TOP String = "topCenter" Top located dialog  - BlackBerry PlayBook
blackberry.ui.dialog.SIZE_FULL String = "full" Full size dialog  - BlackBerry PlayBook
blackberry.ui.dialog.SIZE_LARGE String = "large" Large size dialog  - BlackBerry PlayBook
blackberry.ui.dialog.SIZE_MEDIUM String = "medium" Medium size dialog  - BlackBerry PlayBook
blackberry.ui.dialog.SIZE_SMALL String = "small" Small size dialog  - BlackBerry PlayBook
blackberry.ui.dialog.SIZE_TALL String = "tall" Tall size dialog  - BlackBerry PlayBook

Documentation generated by JsDoc Toolkit 2.4.0 on Wed Sep 14 2011 09:55:31 GMT-0000 (UTC)