Dialog windows (dialog.h)

Functions and structures to manipulate dialog windows.

This file defines the dialog service, which provides an API to create, configure, display, update, and cancel dialog windows.

Dialog Usage

Before you can use the dialog service to show dialogs, you must create a window group. You create a window group by calling screen_create_window(), followed by calling screen_create_window_group(). Both functions are declared in screen/screen.h. screen_create_window_group() should be called immediately after screen_create_window(), and before any other screen functions are called. You do not need to provide the dialog service with the window group's ID - the window group must simply exist before you attempt to display dialogs.

In general, to display a dialog, use the following steps:

Create a specific type of dialog using the appropriate dialog creation function.

Customize the dialog by setting its attributes.

Display the dialog.

Clean up dialog resources.

For example, to create, customize, and display an alert dialog:

   dialog_instance_t dialog = 0;
   dialog_create_alert(&dialog);
   dialog_set_alert_message_text(dialog, "Here's a message...");

   dialog_set_group_id(dialog, "yourWindowId");

   dialog_add_button(dialog, "CANCEL", true, NULL, true);
   dialog_add_button(dialog, "OK", true, NULL, true);
   dialog_show(dialog);

To decode the response from a dialog:

   dialog_instance_t dialog = dialog_event_get_dialog_instance(event);
   int selected_index = dialog_event_get_selected_index(event);
   const char *label = dialog_event_get_selected_label(event);

To clean up dialog resources:

   dialog_destroy(dialog);

Since:: BlackBerry 10.0.0