Displaying a dialog

How to

Display an alert dialog box (a popup message used to display system-level or application-level alerts to the user) and receive dialog events on the BlackBerry 10 device.

Solution

dialog_instance_t alert_dialog = NULL;
int shutdown = 0;

bps_initialize();
                
dialog_request_events(0);    //0 indicates that all events are requested

if (dialog_create_alert(&alert_dialog) != BPS_SUCCESS) {
    fprintf(stderr, "Failed to create alert dialog.\n");
    return EXIT_FAILURE;
}

if (dialog_set_alert_message_text(alert_dialog, "Hello World!")
    != BPS_SUCCESS) {
      fprintf(stderr, "Failed to set alert dialog message text.\n");
      dialog_destroy(alert_dialog);
      alert_dialog = 0;
      return EXIT_FAILURE;
}

char* cancel_button_context = "Canceled";

if (dialog_add_button(alert_dialog, DIALOG_CANCEL_LABEL, true,
    cancel_button_context, true) != BPS_SUCCESS) {
      fprintf(stderr, "Failed to add button to alert dialog.\n");
      dialog_destroy(alert_dialog);
      alert_dialog = 0;
      return EXIT_FAILURE;
}

if (dialog_add_button(alert_dialog, "Submit", true, 0, true)
    != BPS_SUCCESS) {
      fprintf(stderr, "Failed to add button to alert dialog.\n");
      dialog_destroy(alert_dialog);
      alert_dialog = 0;
      return EXIT_FAILURE;
}

if (dialog_show(alert_dialog) != BPS_SUCCESS) {
    fprintf(stderr, "Failed to show alert dialog.\n");
    dialog_destroy(alert_dialog);
    alert_dialog = 0;
    return EXIT_FAILURE;
}

while (!shutdown) {
    bps_event_t *event = NULL;
    bps_get_event(&event, -1);    // -1 means that the function waits 
                                  // for an event before returning

    if (event) {
        if (bps_event_get_domain(event) == dialog_get_domain()) {
                
            int selectedIndex =
                dialog_event_get_selected_index(event);
            const char* label =
                dialog_event_get_selected_label(event);
            const char* context =
                dialog_event_get_selected_context(event);

            // Process dialog event here
        }
    }
}

if (alert_dialog) {
    dialog_destroy(alert_dialog);
}

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 10 device. 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.

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. Note that the following types of dialogs are 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
  • file save - presents an interface to save files
  • alert - presents a popup message used to display system-level or application-level alerts to the user

For more details, see the dialog.h API.

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 is pressed, until the application calls dialog_cancel(). This allows you to control when the dialog is closed.

Related resources

Last modified: 2013-12-21

comments powered by Disqus