Build requirements

You must include the following header files from the BlackBerry Platform Services (BPS) library:

#include <bps/bps.h>
#include <bps/dialog.h>

Discussion

The BlackBerry Platform Services dialog service allows you to
create, configure, display, and cancel dialog boxes on the BlackBerry PlayBook tablet. Dialog boxes are used to
present urgent information, warnings, or multiple choice options to the user. They
are an important UI element but should be used sparingly as they can interrupt user
workflow. For more information, you can browse the BlackBerry UI
Guidelines.

To use dialogs, you must create a handle for the dialog using the dialog_instance_t type. The first function to call is bps_initialize(), which sets up the infrastructure of the BlackBerry Platform Services library. Then, after your application registers to receive dialog events by calling dialog_request_events(), you can call dialog_create_alert() to populate the handle with an instance of an alert dialog. From there, you can configure different properties of the dialog by calling dialog_set_alert_message_text() to set the text displayed in the body of the dialog box and dialog_add_button() to add a button to the dialog box. Buttons can display pre-defined labels, such as DIALOG_CANCEL_LABEL, or display user-defined strings. Other properties include size, position, and title of the dialog window.

If you want to change the properties of a dialog box that is already displayed, you can call any function that sets those properties (such as dialog_set_alert_message_text(), dialog_set_size(), dialog_add_button(), dialog_remove_button(), etc.) followed by dialog_update_button(). You must call dialog_update_button() to update the properties of the dialog box.

The code in this recipe represents the creation of an alert dialog box, but the
following types are also available: context menu (presents a menu of buttons),
prompt (presents an input field), popup list (presents a simple popup list), file
browse (presents an interface to choose files), login (presents input fields for
login credentials), and file save (presents an interface to save files). For more
details, see the dialog.h
API reference.

After you configure the dialog, you can call dialog_show() to present the dialog to the user. Inside your main application loop, you can call bps_get_event() to retrieve the next available event from the BlackBerry Platform Services. After an event is received, you should determine whether it's a dialog event by using bps_event_get_domain() and dialog_get_domain(). If it's a dialog event, you can get various properties of the event, such as the index of the selected button, the label of the selected button, or the context associated with the selected button (set using dialog_add_button()), and process the information from there.

A dialog closes after the user presses one of its buttons. If the dialog is no longer required by the application, call dialog_destroy() to clean up its resources. If the application calls this function while the dialog is visible, the dialog closes and its resources are cleaned up.

Nice to know

You can use the dialog_set_cancel_required() function to require that the application call dialog_cancel() before closing the dialog. If true is passed in to dialog_set_cancel_required(), the dialog continues to be displayed, even if one of its buttons are pressed, until the application calls dialog_cancel(). This allows you to control when the dialog is closed.