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.

The following images show a variety of dialog boxes that you can use:

Screen shot showing a dialog box with one button.

Dialog box with one button.

Screen shot showing a dialog box with discard option.

Dialog box with discard option.

Screen shot showing a dialog box with a prompt.

Dialog box with a prompt.

Screen shot showing a dialog box with cancel option.

Dialog box with cancel option.

Installation:

To use this API in your project, add the dialog plugin:

webworks plugin add com.blackberry.ui.dialog
Functions:
void standardAskAsync()
void customAskAsync()
Constants:
Number D_OK
Number D_OK_CANCEL
Number D_DELETE
Number D_YES_NO
Number D_SAVE
Number D_PROMPT

standardAskAsync()

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.

Synopsis:

void blackberry.ui.dialog.standardAskAsync(message,type,onOptionSelected,settings)

Parameters:

message {String}

The message Message to be displayed in the dialog.

type {Number}

Parameter that specifies the type of standard dialog. Constants starting with D_*.

onOptionSelected {Function}

Optional callback function that will be invoked when the user makes a selection. Expected signature: function onOptionSelected(selectedButtonObject).

return {String}

The element for the selected button, returns a string based on users choice.

promptText {String}

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 {Object}

Optional Object literal that allows the user to manipulate the title of the dialog.

settings.title {String}

Desired title of the dialog.

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>
        

customAskAsync()

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.

Synopsis:

void blackberry.ui.dialog.customAskAsync(message,buttons,onOptionSelected,settings)

Parameters:

message {String}

The message Message to be displayed in the dialog.

buttons {String[]}

The buttons Array of string choices that will be presented to the user in the form of buttons.

onOptionSelected {Function}

Optional callback function that will be invoked when the user makes a selection. Expected signature: function onOptionSelected(selectedButtonIndex).

index {Number}

The index of the selection the user has made.

settings {Object}

Optional Object literal that allows the user to manipulate the title of the dialog.

title {String}

Desired title of the dialog.

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

</script>
            

D_OK

Standard OK dialog

Synopsis:

constant
Number blackberry.ui.dialog.D_OK = 0

D_OK_CANCEL

Standard OK/Cancel dialog

Synopsis:

constant
Number blackberry.ui.dialog.D_OK_CANCEL = 4

D_DELETE

Standard Delete confirmation dialog

Synopsis:

constant
Number blackberry.ui.dialog.D_DELETE = 2

D_YES_NO

Standard Yes/No dialog

Synopsis:

constant
Number blackberry.ui.dialog.D_YES_NO = 3

D_SAVE

Standard Save dialog

Synopsis:

constant
Number blackberry.ui.dialog.D_SAVE = 1

D_PROMPT

Standard Prompt input dialog

Synopsis:

constant
Number blackberry.ui.dialog.D_PROMPT = 5

Last modified: 2014-05-14



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus