Use dialog boxes to perform the following actions:
- Prompt users for information that is required to complete a user-initiated task.
- Inform users of urgent information or the status of important actions.
- Warn users of unexpected or potentially destructive conditions or situations.
Dialog boxes are modal; they interrupt the normal operation of the BlackBerry device and are pushed to the top of the stack. A dialog box includes a message, buttons that allow users to perform an action, and an indicator that indicates the type of dialog box. The size of the dialog box depends on the size of the BlackBerry device screen. The theme that users select on their BlackBerry device determines the visual style of the dialog box.
Best practice: Implementing dialog boxes
- Use buttons to confirm or cancel actions in dialog boxes. Avoid using links or other components.
- Use a standard indicator that is appropriate for the type of dialog box. Avoid using multiple indicators in a dialog box.
- Try to avoid making users scroll in a dialog box. Include scroll arrows if your dialog box message or buttons cannot be displayed fully on the dialog box. If you use standard components, scroll arrows appear automatically if necessary.
- Always allow users to use the Escape key to close a dialog box. Avoid implementing another action when users press the Escape key to close a dialog box. For example, if a dialog box allows users to change a setting, do not implement any changes when users press the Escape key. If necessary, display the dialog box at a later time.
- If users press the End/Power key when a dialog box appears on an application screen, display the Home screen or application list. If users return to the application, display the dialog box again.
Guidelines for layout
Center the dialog box on the screen. If you use standard components, the BlackBerry device automatically centers the dialog box.
Create dialog boxes that are up to, but not greater than, 90% of the width and height of the screen. If you use standard components, the BlackBerry device automatically calculates the appropriate size for dialog boxes.
Center the dialog box indicator vertically with the dialog box message.
Display messages to the right of the indicator and above any buttons for most languages.
Place buttons for confirmation actions first. For example, place "Save" before "Discard" or "Cancel."
Center buttons horizontally in dialog boxes.
Place buttons vertically in the dialog box. The vertical layout allows buttons to expand to accommodate localized button labels.
If you include a check box, match the alignment of the check box with the alignment of the dialog box message. Place the check box above the buttons. The check box should be checked by default, unless the dialog box displays a message with critical information for users.
Guidelines for messages
- Be specific. If possible, use one short sentence to clearly state the reason for displaying the dialog box and the actions that can dismiss it.
- Use complete sentences for messages where possible.
- Use vocabulary that users understand. For example, use "The file could not be saved because the media card is full" instead of "Error writing file to disk."
- Use positive language where possible and avoid blaming the user. Never write messages that blame users for errors or unexpected conditions. Instead, focus on the actions that users can take to resolve the issue.
- Use the second person (you, your) to refer to users.
- Use sentence case capitalization.
- Avoid using exclamation points (!) in messages.
- Avoid using an ellipsis (...) in messages unless you are indicating progress (for example, "Please wait...").
Guidelines for buttons
- For the default button, use the button that users are most likely to click. Avoid using a button that is associated with a destructive action as the default button. Exceptions to this rule are those cases where users initiate a minor destructive action (such as deleting a single item) and the most common user action is to continue with the action.
- Avoid using more than three buttons in a dialog box. If there are more than three, consider using an application screen instead with radio buttons.
- On BlackBerry devices with a physical keyboard, provide shortcut keys for buttons. Typically, the shortcut key is the first letter of the button label.
- Use clear, concise labels.
- Avoid using the labels "Yes" and "No." Use verbs that describe the associated action (for example, "Cancel," "Delete," "Discard," or "Save"). This approach helps users quickly and easily understand what happens when they click the button. If necessary, include more descriptive text elsewhere on the screen (for example, in an application message).
- Avoid using symbols or graphics in labels.
- Avoid using punctuation in labels. Use an ellipsis in a button label to indicate that additional information is required before the associated action can be performed.
Create a dialog box
Use alert dialog boxes to notify users of a critical action such as turning off the BlackBerry device or an error such as typing information that is not valid. An exclamation point (!) indicator appears in an alert dialog box. To close an alert dialog box, users can click OK or press the Escape key.
Import the net.rim.device.api.ui.component.Dialog class.
Create an alert dialog box specifying the alert text that you want to display.
Dialog.alert("Specify the alert text that you want to display.")