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 |
API | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
blackberry.ui.dialog.colorPickerAsync | Y | Y | Y | ||||
blackberry.ui.dialog.customAsk | Y | Y | Y | ||||
blackberry.ui.dialog.customAskAsync | Y | Y | Y | Y | Y | Y | Y |
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 | Y | Y | |||||
D_OK | Y | Y | Y | Y | Y | Y | Y |
D_SAVE | Y | Y | Y | Y | Y | Y | Y |
D_DELETE | Y | Y | Y | Y | Y | Y | Y |
D_YES_NO | Y | Y | Y | Y | Y | Y | Y |
D_OK_CANCEL | Y | Y | Y | Y | Y | Y | Y |
D_PROMPT | 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 | 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 ID | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
<feature id="blackberry.ui.dialog" /> | Y | Y | Y | Y | Y | Y | Y |
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
Constants
Number | D_OK |
Number | D_SAVE |
Number | D_DELETE |
Number | D_YES_NO |
Number | D_OK_CANCEL |
Number | D_PROMPT |
Number | C_CANCEL |
Number | C_OK |
Number | C_SAVE |
Number | C_DISCARD |
Number | C_DELETE |
Number | C_YES |
Number | C_NO |
String | BOTTOM |
String | CENTER |
String | TOP |
String | SIZE_FULL |
String | SIZE_LARGE |
String | SIZE_MEDIUM |
void | SIZE_SMALL |
String | SIZE_TALL |
** Marked for Deprecation
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:
|
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:
|
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+.
|
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.
|
Code Example:
|
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:
|
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:
|
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:
|
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+.
|
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.
|
Code Example:
|
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:
|
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.
|
Code Example:
|
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 |