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 1.0+
- BlackBerry 10
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.ui.dialog.colorPickerAsync Y Y Y       
blackberry.ui.dialog.customAsk Y Y Y       
blackberry.ui.dialog.customAskAsync Y Y Y Y Y YY
blackberry.ui.dialog.dateTimeAsync Y Y Y       
blackberry.ui.dialog.selectAsync Y Y Y       
blackberry.ui.dialog.standardAsk Y Y Y       
blackberry.ui.dialog.standardAskAsync Y Y Y Y Y  Y
blackberry.ui.dialog.standardAskAsync           YY
D_OK Y Y Y Y Y YY
D_SAVE Y Y Y Y Y YY
D_DELETE Y Y Y Y Y YY
D_YES_NO Y Y Y Y Y YY
D_OK_CANCEL Y Y Y Y Y YY
D_PROMPT           YY
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  Y
CENTER       Y Y  Y
TOP       Y Y  Y
SIZE_FULL       Y Y  Y
SIZE_LARGE       Y Y  Y
SIZE_MEDIUM       Y Y  Y
SIZE_SMALL       Y Y  Y
SIZE_TALL       Y 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 IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.ui.dialog" /> Y Y Y Y Y YY

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Functions

static void blackberry.ui.dialog.colorPickerAsync (initialColor : String, onColorSelected: function(color : String))


Creates an asynchronous dialog to allow user to select a color.

The function is an asynchronous call and will not block execution. It will return the value selected by the user.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
initialColor Color that will first be selected when the color picker dialog appears in hexadecimal format.
onColorSelected Callback function that will be invoked when the user makes a selection. It will be invoked with the user's choice from the native UI.

color: The color user has selected in hexadecimal format.

Code Example:
<script type="text/javascript">

function onColorSelected(color){
  alert(color);
}

function colorPicker() {
  try {
    blackberry.ui.dialog.colorPickerAsync("000000", onColorSelected);
  } catch (e) {
    alert("Exception in colorPickerAsync: " + e);
  }
}

</script>

static Number blackberry.ui.dialog.customAsk (message : String, choices : String[], [defaultChoice : Number], [globalStatus : Boolean])


Deprecation Notice:

This API is deprecated, please use blackberry.ui.dialog.customAskAsync instead.

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.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
message Message to be displayed in the dialog.
choices Array of string choices that will be presented to the user in the form of buttons.
defaultChoice [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 [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.


Return:

The index of the choice selected by the user.



Code Example:
<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>

static void blackberry.ui.dialog.customAskAsync (message : String, buttons : String[], [onOptionSelected: function([index: Number])], [settings : Object])


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.
NOTE: function is only implemented for Ripple emulation on Playbook.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
message Message to be displayed in the dialog.
buttons Array of string choices that will be presented to the user in the form of buttons.
onOptionSelected Optional callback function that will be invoked when the user makes a selection. Expected signature: function onOptionSelected(selectedButtonIndex).

NOTE: onOptionSelected is required for BlackBerry OS5.0+.

index: The index of the selection the user has made.

settings [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.

NOTE: The settings parameter applies only to PlayBook, Ripple, and BB10. On the other devices, it has no effect.

title: Desired title of the dialog.
size: Desired size of the dialog.
position: Desired position of the dialog.
global: Specifies the global flag of the dialog window. (Your application cannot be minimized when the dialog global setting is set to true and when any dialog window is open). By default this parameter is false when not specified.
NOTE: The parameters for 'size', 'position', and 'global' are NOT implemented for BB10.


Code Example:
<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.CENTER};
    blackberry.ui.dialog.customAskAsync("Do you routinely work out?", buttons, dialogCallBack, ops);
  } catch(e) {
    alert("Exception in customDialog: " + e);
  }
}

</script>

static void blackberry.ui.dialog.dateTimeAsync (type : String, options : Object[], onDateTimeSelected: function(datetime : String))


Creates an asynchronous dialog to allow user to select a date/time for an HTML 5 input of types: date, datetime, datetime-local, month, time

The function is an asynchronous call and will not block execution. It will return the value selected by the user.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
type One of: "date", "datetime", "datetime-local", "month", "time".
options The current state of the input control.

value: String representation of the current date/time displayed in the field
min: String representation of the minimum date/time allowed in the field
max: String representation of the maximum date/time allowed in the field
onDateTimeSelected A callback that will be invoked with the user's choices from the native UI.

datetime: The date/time user has selected.

Code Example:
<script type="text/javascript">

function onDateTimeSelected(datetime){
  alert(datetime);
}

//Input argument is a reference to an input control of type: date, datetime, datetime-local, month, time
function dateTimeAsync(htmlDateTimeInput) {
  try {
    var opts = { "value" : htmlDateTimeInput.value,
                  "min"   : htmlDateTimeInput.min || "",
                  "max"   : htmlDateTimeInput.max || ""
    };

    blackberry.ui.dialog.dateTimeAsync("date", opts, window.onDateTimeSelected);
  }catch (e) {
    alert("Exception in dateTimeAsync: " + e);
  }
}

</script>

static void blackberry.ui.dialog.selectAsync (allowMultiple : Boolean, options : Object[], onSelected: function(indices : Number[]))


Creates an asynchronous dialog to allow user to select one or many items in a list.

The function is an asynchronous call and will not block JavaScript execution. It will return array of indexes that user selected.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
allowMultiple If true, the dialog will allow multiple selection.
options Array of objects representing the select items and their states.

label: The value of an item in the dropdown list
selected: Flag that indicates whether an item should be rendered as currently selected
enabled: Flag that indicates whether an item should be enabled for selection
type: Can be either "group" or "option" to indicate whether an item is a group header or an option
onSelected A callback that will be invoked with the user's choices from the native UI.

indices: The indices of the user's selections.

Code Example:
<script type="text/javascript">

function onSelected(indices) {
  var i;
  for(i = 0; i < indices.length; i++) {
    alert("Item selected: " + indices[i]);
  }
}

function selectAsync() {
  try {
    blackberry.ui.dialog.selectAsync(false,
                                     [ { label : "Animals", selected : false, enabled : false, type : "group"},
                                       { label : "cat", selected : true, enabled : true, type : "option"},
                                       { label : "dog", selected : false, enabled : true, type : "option"},
                                       { label : "mouse", selected : false, enabled : true, type : "option"},
                                       { label : "raccoon", selected : false, enabled : true, type : "option"}
                                     ],
                                     window.onSelected);
  }catch (e) {
    alert("Exception in selectAsync: " + e);
  }
}

</script>

static Number blackberry.ui.dialog.standardAsk (specifies : Number, message : String, [defaultChoice : Number], [globalStatus : Boolean])


Deprecation Notice:

This API is deprecated, please use blackberry.ui.dialog.standardAskAsync instead.

Creates a standard dialog to ask the user a question.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
specifies the type of standard dialog. Constants starting with D_*.
message Message to be displayed in the dialog.
defaultChoice [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 [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.


Return:

The index of the choice selected by the user.



Code Example:
<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">

static void blackberry.ui.dialog.standardAskAsync (message : String, type : Number, [onOptionSelected: function([index: Number])], [settings : Object])


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.
NOTE: function is only implemented for Ripple emulation on Playbook.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
message Message to be displayed in the dialog.
type Parameter that specifies the type of standard dialog. Constants starting with D_*.
onOptionSelected Optional callback function that will be invoked when the user makes a selection. Expected signature: function onOptionSelected(selectedButtonIndex).

NOTE: onOptionSelected is required for BlackBerry OS5.0+.

index: The index of the selection the user has made.

settings [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.

NOTE: The settings parameter applies only to PlayBook, Ripple, and BB10. On the other devices, it has no effect.

title: Desired title of the dialog.
size: Desired size of the dialog.
position: Desired position of the dialog.
global: Specifies the global flag of the dialog window. (Your application cannot be minimized when the dialog global setting is set to true and when any dialog window is open). By default this parameter is false when not specified.


Code Example:
<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.BOTTOM});
  }catch (e) {
    alert("Exception in standardDialog: " + e);
  }
}

</script>

static void blackberry.ui.dialog.standardAskAsync (message : String, type : Number, [onOptionSelected: function([return: String], [promptText: String])], [settings : Object])


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 an object containing the selected button, and the input values.
NOTE: function is only implemented for Ripple emulation on Playbook.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Parameters
message Message to be displayed in the dialog.
type Parameter that specifies the type of standard dialog. Constants starting with D_*.
onOptionSelected Optional callback function that will be invoked when the user makes a selection. Expected signature: function onOptionSelected(selectedButtonObject).

return: The element for the selected button, returns a string based on users choice.
promptText: The element for entered text. Returns the user's entered string. If cancel is selected set to null. (This property is only used for select dialogs: D_PROMPT).

Example returns for each dialog type:
  1. D_OK
    • Ok selected: {return: "Ok"}
  2. D_SAVE
    • Save selected: {return: "Save"}
    • Discard selected: {return: "Discard"}
  3. D_DELETE
    • Delete selected: {return: "Delete"}
    • Cancel selected: {return: "Cancel"}
  4. D_YES_NO
    • Yes selected: {return: "Yes"}
    • No selected: {return: "No"}
  5. D_OK_CANCEL
    • Ok selected: {return: "Ok"}
    • Cancel selected: {return: "Cancel"}
  6. D_PROMPT
    • Ok selected with input: {return: "Ok", promptText: "test input"}
    • Ok selected with empty input: {return: "Ok", promptText: null}
    • Cancel selected: {return: "Cancel", promptText: null}
settings [Default Value: null]

Optional Object literal that allows the user to manipulate the title and optional buttons of the dialog. It is not required to provide all parameters, and these do not have to be specified in any particular order.

NOTE: The settings parameter applies only to PlayBook, Ripple, and BB10. On the other devices, it has no effect.

title: Desired title of the dialog.


Code Example:
<script type="text/javascript">

function dialogCallBack(selection){
  alert(selection.return);
}

function standardDialog() {
  try {
    blackberry.ui.dialog.standardAskAsync("Save?", blackberry.ui.dialog.D_SAVE, dialogCallBack, {title : "Save Dialog"});
  }catch (e) {
    alert("Exception in standardDialog: " + e);
  }
}

</script>

Constants

static Number D_OK = 0


Standard OK dialog


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number D_SAVE = 1


Standard Save dialog


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number D_DELETE = 2


Standard Delete confirmation dialog


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number D_YES_NO = 3


Standard Yes/No dialog


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number D_OK_CANCEL = 4


Standard OK/Cancel dialog


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Number D_PROMPT = 5


Standard OK/Cancel dialog


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static Number C_CANCEL = -1


Standard Prompt input dialog


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number C_OK = 0


OK choice for use in dialogs


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number C_SAVE = 1


SAVE choice for use in dialogs


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number C_DISCARD = 2


DISCARD choice for use in dialogs


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number C_DELETE = 3


DELETE choice for use in dialogs


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number C_YES = 4


YES choice for use in dialogs


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number C_NO = -1


NO choice for use in dialogs


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static String BOTTOM = "bottomCenter"


Bottom located dialog


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator

static String CENTER = "middleCenter"


Center located dialog


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator

static String TOP = "topCenter"


Top located dialog


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator

static String SIZE_FULL = "full"


Full size dialog


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator

static String SIZE_LARGE = "large"


Large size dialog


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator

static String SIZE_MEDIUM = "medium"


Medium size dialog


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator

static void SIZE_SMALL = "small"


Small size dialog


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator

static String SIZE_TALL = "tall"


Tall size dialog


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:36 GMT-0500 (EST)