net.rim.device.api.ui.component
Class Dialog

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.Manager
              |
              +--net.rim.device.api.ui.Screen
                    |
                    +--net.rim.device.api.ui.container.PopupScreen
                          |
                          +--net.rim.device.api.ui.component.Dialog
All Implemented Interfaces:
FieldChangeListener, HolsterListener, IComponent, InputMethodListener, SoftkeyProvider

public class Dialog
extends PopupScreen
implements FieldChangeListener, HolsterListener

Provides a dialog box with predefined configurations.

To get a standard, predefined dialog use alert(java.lang.String), ask(int), or inform(java.lang.String). These pop up a predefined dialog and wait for user input. To get a more customized dialog, instantiate this class or extend it.

Pressing ESCAPE returns CANCEL, but only if it was one of the choices specified in the values array.


Field Summary
static int CANCEL
          Cancel choice for use in dialogs.
static int D_DELETE
          Standard delete confirmation dialog.
static int D_OK
          Standard OK dialog.
static int D_SAVE
          Standard save prompt dialog.
static int D_YES_NO
          Standard Yes/No confirmation dialog.
static int DELETE
          Delete choice for use in dialogs.
static int DISCARD
          Discard choice for use in dialogs.
static int GLOBAL_STATUS
          Displays the dialog as a global status.
static int LIST
          Displays the dialog choices as a list instead of buttons.
static int NO
          No choice for use in dialogs; same behaviour as CANCEL.
static int OK
          OK choice for use in dialogs.
static int SAVE
          Save choice for use in dialogs.
static int YES
          Yes choice for use in dialogs.
 
Fields inherited from class net.rim.device.api.ui.Screen
DEFAULT_CLOSE, DEFAULT_MENU
 
Fields inherited from class net.rim.device.api.ui.Manager
BOTTOMMOST, DOWNWARD, HORIZONTAL_SCROLL, HORIZONTAL_SCROLL_MASK, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_MASK, LEAVE_BLANK_SPACE, LEFTMOST, LEFTWARD, NO_HORIZONTAL_SCROLL, NO_HORIZONTAL_SCROLLBAR, NO_SCROLL_RESET, NO_VERTICAL_SCROLL, NO_VERTICAL_SCROLLBAR, QUANTA_FONT, RIGHTMOST, RIGHTWARD, TOPMOST, UPWARD, VERTICAL_SCROLL, VERTICAL_SCROLL_MASK, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_MASK
 
Fields inherited from class net.rim.device.api.ui.Field
EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, READONLY, USE_ALL_HEIGHT, USE_ALL_WIDTH
 
Fields inherited from interface net.rim.device.api.ui.FieldChangeListener
PROGRAMMATIC
 
Constructor Summary
Dialog(int type, String message, int defaultChoice, Bitmap bitmap, long style)
          Contructs a new Dialog instance with provided style.
Dialog(int type, String message, int defaultChoice, Bitmap bitmap, long style, boolean dontAskAgain)
          Contructs a new Dialog instance with provided style.
Dialog(String message, Object[] choices, int[] values, int defaultChoice, Bitmap bitmap)
          Constructs a new Dialog instance.
Dialog(String message, Object[] choices, int[] values, int defaultChoice, Bitmap bitmap, long style)
          Contructs a new Dialog instance with provided style.
 
Method Summary
 void add(Field field)
          Adds a field to this dialog.
static void alert(String message)
          Creates an alert dialog.
static int ask(int type)
          Creates an standard inquiry dialog.
static int ask(int type, String message)
          Creates an inquiry dialog with provided message.
static int ask(int type, String message, int defaultChoice)
          Creates an inquiry dialog with provided message.
static int ask(String message, Object[] choices, int defaultChoice)
          Creates an inquiry dialog with provided message and choices.
static int ask(String message, Object[] choices, int[] values, int defaultChoice)
          Creates an inquiry dialog with provided message, choices, and values.
 void cancel()
          Cancel this dialog.
 void close()
          Closes this dialog.
 int doModal()
          Shows a modal dialog.
 void fieldChanged(Field field, int context)
          Handles button select events for this dialog.
 boolean getDontAskAgainValue()
          Returns the value of the "Don't ask again" checkbox.
 RichTextField getLabel()
          Retrieves label for the dialog.
 int getPreferredWidth()
          Retrieves this dialog's preferred width.
protected static String[] getResourceChoices(int type)
           
protected static int getResourceDefaultValue(int type)
           
protected static String getResourceMessage(int type)
           
protected static int[] getResourceSoftkeyMap(int type)
           
protected static int[] getResourceValues(int type)
           
 int getSelectedValue()
          Returns the value of the currently selected choice.
static void inform(String message)
          Creates a notification dialog with message.
 void inHolster()
          Invoked when the device is put in the holster.
protected  boolean keyChar(char key, int status, int time)
          Traps key generation events for this dialog.
protected  void onDisplay()
          Invoked when this dialog is pushed onto the display stack.
protected  void onExposed()
          Invoked when this screen is revealed by a screen getting popped off the display stack, or a global screen is dismissed.
protected  void onObscured()
          Invoked when this screen is obscured by a new screen pushed on the display stack, or a global screen is displayed.
protected  void onUndisplay()
          Invoked when this dialog is popped from the display stack.
 void outOfHolster()
          Invokd when the device is removed from the holster.
protected  void select()
          Activates the currently selected choice.
 void select(int value)
          Activates the choice with the provided value.
 void setDefault(int defaultChoice)
          Sets the default choice.
 void setDialogClosedListener(DialogClosedListener listener)
          Registers a listener for dialog close events.
 void setEscapeEnabled(boolean escapeEnabled)
          Set escape enabled state for this dialog.
 void show()
          Shows a modeless dialog of normal priority.
 void show(int priority)
          Shows a modeless dialog of provided priority.
protected  boolean trackwheelClick(int status, int time)
          Handles trackwheel click events.
 
Methods inherited from class net.rim.device.api.ui.container.PopupScreen
dispatchKeyEvent, paint, sublayout
 
Methods inherited from class net.rim.device.api.ui.Screen
addKeyListener, addTrackwheelListener, delete, deleteRange, doLayout, doPaint, ensureRegionVisible, getApplication, getDefaultMenuItem, getDelegate, getField, getFieldAtLocation, getFieldCount, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getGraphics, getLeafFieldWithFocus, getMenu, getScreenAbove, getScreenBelow, getUiEngine, insert, invalidate, invalidate, invalidateLayout, isDirty, isDisplayed, isFocusable, isGlobalStatus, isMuddy, isSelecting, keyCharUnhandled, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layoutDelegate, makeMenu, onClose, onFocus, onMenu, onMenuDismissed, onSave, onSavePrompt, onUnfocus, openDevelopmentBackdoor, openProductionBackdoor, paintBackground, removeFocus, removeKeyListener, removeTrackwheelListener, save, scroll, setBackdoorAltStatus, setDefaultClose, setDirty, setFocus, setFocus, setHorizontalQuantization, setPositionDelegate, setVerticalQuantization, trackwheelClickUnhandled, trackwheelRoll, trackwheelUnclick, updateDisplay
 
Methods inherited from class net.rim.device.api.ui.Manager
deleteAll, getHorizontalScroll, getVerticalScroll, getVirtualHeight, getVirtualWidth, getVisibleHeight, getVisibleWidth, invalidateFieldRange, isDownArrowShown, isUpArrowShown, isValidLayout, layout, layoutChild, moveFocus, moveFocus, nextFocus, paintChild, setFocus, setHorizontalScroll, setPositionChild, setScrollListener, setVerticalScroll, setVirtualExtent, subpaint
 
Methods inherited from class net.rim.device.api.ui.Field
drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getChangeListener, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getOriginal, getPreferredHeight, getScreen, getStyle, getTop, getWidth, isEditable, isPasteable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isStyle, isVisible, makeContextMenu, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setChangeListener, setCookie, setEditable, setExtent, setFocusListener, setFont, setMuddy, setPosition, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

D_OK

public static final int D_OK
Standard OK dialog.

D_SAVE

public static final int D_SAVE
Standard save prompt dialog.

D_DELETE

public static final int D_DELETE
Standard delete confirmation dialog.

D_YES_NO

public static final int D_YES_NO
Standard Yes/No confirmation dialog.

CANCEL

public static final int CANCEL
Cancel choice for use in dialogs.

OK

public static final int OK
OK choice for use in dialogs.

SAVE

public static final int SAVE
Save choice for use in dialogs.

DISCARD

public static final int DISCARD
Discard choice for use in dialogs.

DELETE

public static final int DELETE
Delete choice for use in dialogs.

YES

public static final int YES
Yes choice for use in dialogs.

NO

public static final int NO
No choice for use in dialogs; same behaviour as CANCEL.

LIST

public static final int LIST
Displays the dialog choices as a list instead of buttons.

GLOBAL_STATUS

public static final int GLOBAL_STATUS
Displays the dialog as a global status.
Constructor Detail

Dialog

public Dialog(String message,
              Object[] choices,
              int[] values,
              int defaultChoice,
              Bitmap bitmap)
Constructs a new Dialog instance.
Parameters:
message - Message to show in dialog.
choices - Objects selectable by the user; each object is showing using Object.toString().
values - Instead of returning the index selected, doModal() returns the value associated with this index (useful for adding CANCEL).
defaultChoice - Initial choice selected when the Dialog is shown. If you provide a non-null values parameter, the default choice must be present in that array. If the values parameter is null, the default choice is the index of the initially selected item.
bitmap - Image to display in the left side of the dialog.

Dialog

public Dialog(String message,
              Object[] choices,
              int[] values,
              int defaultChoice,
              Bitmap bitmap,
              long style)
Contructs a new Dialog instance with provided style.
Parameters:
message - Message to show in dialog.
choices - Objects selectable by the user; each object is showing using Object.toString().
values - Instead of returning the index selected, doModal() returns the value associated with this index (useful for adding CANCEL).
defaultChoice - Initial choice selected when the Dialog is shown. If you provide a non-null values parameter, the default choice must be present in that array. If the values parameter is null, the default choice is the index of the initially selected item.
bitmap - Image to display in the left side of the dialog.
style - Screen or Manager style.

Dialog

public Dialog(int type,
              String message,
              int defaultChoice,
              Bitmap bitmap,
              long style)
Contructs a new Dialog instance with provided style.

Builds a standard inquiry dialog with your provided message.

Parameters:
type - Standard inquiry dialog type: D_OK, D_SAVE, D_DELETE, D_YES_NO.
message - Text message to show in dialog.
defaultChoice - Initially selected choice.
bitmap - Image to display in the left side of the dialog.
style - Screen or Manager style.

Dialog

public Dialog(int type,
              String message,
              int defaultChoice,
              Bitmap bitmap,
              long style,
              boolean dontAskAgain)
Contructs a new Dialog instance with provided style.

Builds a standard inquiry dialog with your provided message.

Parameters:
type - Standard inquiry dialog type: D_OK, D_SAVE, D_DELETE, D_YES_NO.
message - Text message to show in dialog.
defaultChoice - Initially selected choice.
bitmap - Image to display in the left side of the dialog.
style - Screen or Manager style.
dontAskAgain - Adds a 'Don't ask again' checkbox.
Since:
JDE 4.0.2
Method Detail

add

public void add(Field field)
Adds a field to this dialog.

This method prompts this dialog's delegate manager to add a new field for this dialog.

Overrides:
add in class Screen
Parameters:
field - Field to add.
Since:
JDE 4.0.2

alert

public static void alert(String message)
Creates an alert dialog.

This method creates an alert dialog typically used to notify the user of an event or some important information. The dialog uses a exclamation mark bitmap.

Parameters:
message - Text to display in the alert.
Since:
JDE 4.0.2

ask

public static int ask(int type)
Creates an standard inquiry dialog.

This method creates a standard inquiry dialog. The dialog uses a question mark bitmap.

Parameters:
type - Standard inquiry dialog type: D_OK, D_SAVE, D_DELETE, D_YES_NO.
Returns:
The value(not the index) of the selected choice, as would be returned from getSelectedValue(). For example, CANCEL, OK, or DELETE are some of the possible return values.
Since:
JDE 4.0.2

ask

public static int ask(int type,
                      String message)
Creates an inquiry dialog with provided message.

Builds a standard inquiry dialog with your provided message. The dialog uses a question mark bitmap.

Parameters:
type - Standard inquiry dialog type: D_OK, D_SAVE, D_DELETE, D_YES_NO.
message - Text message to show in dialog.
Returns:
The value(not the index) of the selected choice, as would be returned from getSelectedValue(). For example, CANCEL, OK, or DELETE are some of the possible return values.
Since:
JDE 4.0.2

ask

public static int ask(int type,
                      String message,
                      int defaultChoice)
Creates an inquiry dialog with provided message.

Builds a standard inquiry dialog with your provided message. The dialog uses a question mark bitmap.

Parameters:
type - Standard inquiry dialog type: D_OK, D_SAVE, D_DELETE, D_YES_NO.
message - Text message to show in dialog.
defaultChoice - The value of the selected choice.
Returns:
The value(not the index) of the selected choice, as would be returned from getSelectedValue(). For example, CANCEL, OK, or DELETE are some of the possible return values.
Since:
JDE 4.0.2

ask

public static int ask(String message,
                      Object[] choices,
                      int defaultChoice)
Creates an inquiry dialog with provided message and choices.

Builds an inquiry dialog from scratch with provided message and choices array. The dialog uses a question mark bitmap.

Parameters:
message - Text message to show in dialog.
choices - Choices selectable by the user (show using Object.toString().
defaultChoice - The value of the selected choice.
Returns:
The value(not the index) of the selected choice, as would be returned from getSelectedValue(). For example, CANCEL, OK, or DELETE are some of the possible return values.
Since:
JDE 4.0.2

ask

public static int ask(String message,
                      Object[] choices,
                      int[] values,
                      int defaultChoice)
Creates an inquiry dialog with provided message, choices, and values.

Builds an inquiry dialog from scratch with provided message, and choices and values arrays. The dialog uses a question mark bitmap.

Parameters:
message - Text message to show in dialog.
choices - Choices selectable by the user (show using Object.toString().
values - Instead of returning the selected index, doModal() returns the value associated with this index (useful for adding CANCEL.
defaultChoice - The value of the selected choice.
Returns:
The value(not the index) of the selected choice, as would be returned from getSelectedValue(). For example, CANCEL, OK, or DELETE are some of the possible return values.
Since:
JDE 4.0.2

cancel

public void cancel()
Cancel this dialog.

This method closes this dialog programatically after setting the return value to CANCEL.

Since:
JDE 4.0.0

doModal

public int doModal()
Shows a modal dialog.

This method displays this dialog, waits for the user to select a choice, and then removes the dialog.

Returns:
Returns either the index of the selected choice, or the value associated with this index (depending on how this dialog was built).

getResourceChoices

protected static String[] getResourceChoices(int type)
Since:
JDE 4.0.2

getResourceMessage

protected static String getResourceMessage(int type)
Since:
JDE 4.0.2

getResourceValues

protected static int[] getResourceValues(int type)
Since:
JDE 4.0.2

getResourceDefaultValue

protected static int getResourceDefaultValue(int type)
Since:
JDE 4.0.2

getResourceSoftkeyMap

protected static int[] getResourceSoftkeyMap(int type)
Since:
JDE 4.0.2

onDisplay

protected void onDisplay()
Invoked when this dialog is pushed onto the display stack.

The system invokes this method after this dialog is pushed onto the stack and layout has been done, but before any painting occurs.

If no controlled field has the focus, this method attempts to assign the focus to the first field that will accept it, starting with the first field in the delegate manager's field list. Additionally, this method makes the focus visible, and resets scrolling to 0 if possible (ensuring the focussed region stays on the screen).

Overrides:
onDisplay in class Screen
Following copied from class: net.rim.device.api.ui.Screen
See Also:
Screen.onExposed(), Field.onVisibilityChange(boolean)

onExposed

protected void onExposed()
Description copied from class: Screen
Invoked when this screen is revealed by a screen getting popped off the display stack, or a global screen is dismissed.

Subclasses of screen should override this method for special handling.

The complimenting callback is Screen.onObscured().

Overrides:
onExposed in class Screen
Since:
JDE 4.0.0

onObscured

protected void onObscured()
Description copied from class: Screen
Invoked when this screen is obscured by a new screen pushed on the display stack, or a global screen is displayed.

Derived classes should override this method for special handling.

The complimenting callback is Screen.onExposed().

Overrides:
onObscured in class Screen
Since:
JDE 4.0.0

onUndisplay

protected void onUndisplay()
Invoked when this dialog is popped from the display stack.
Overrides:
onUndisplay in class Screen
Since:
JDE 4.0.0

show

public void show()
Shows a modeless dialog of normal priority.

This method displays this dialog, but does not wait for user input before returning. The DialogClosedListener is notified when this dialog closes.


show

public void show(int priority)
Shows a modeless dialog of provided priority.

This method displays this dialog, but does not wait for user input before returning. The DialogClosedListener is notified when this dialog closes.

Parameters:
priority - Display priority for this dialog, if it is a GLOBAL_STATUS screen.
Since:
JDE 4.0.2

setDialogClosedListener

public void setDialogClosedListener(DialogClosedListener listener)
Registers a listener for dialog close events.

Provide a listener object to handle dialog close events for dialogs created modelessly.

Parameters:
listener - Listener object for dialog close events.
Since:
JDE 4.0.2

fieldChanged

public void fieldChanged(Field field,
                         int context)
Handles button select events for this dialog.

If the provided field is a ButtonField, this method invokes select() to signal a button push.

Parameters:
field - Field whose state changed.
context - Information specifying the origin of the change.
Since:
JDE 4.0.2

getLabel

public RichTextField getLabel()
Retrieves label for the dialog.
Returns:
A rich text field containing this dialog's label.

getPreferredWidth

public int getPreferredWidth()
Retrieves this dialog's preferred width.

This dialog's manager invokes this method to assist in its layout.

Overrides:
getPreferredWidth in class Field
Returns:
Preferred width (in pixels) of this field.

inHolster

public void inHolster()
Invoked when the device is put in the holster.
Since:
JDE 4.0.0

inform

public static void inform(String message)
Creates a notification dialog with message.

This method creates a notification dialog showing the provided message. The dialog uses the "information" bitmap.

Parameters:
message - Text to display in dialog.
Since:
JDE 4.0.2

keyChar

protected boolean keyChar(char key,
                          int status,
                          int time)
Traps key generation events for this dialog.

If the character generated is ESCAPE, and this dialog provides a CANCEL choice, then this method selects that choice.

If the character generated is ENTER, this method selects this dialog's default choice.

If the character generated is a letter, this method does simple prefix searching to find the first choice past the default selection that matches the letter generated. If it finds such a choice, this method then selects that choice.

Overrides:
keyChar in class Screen
Parameters:
key - Character generated by the event.
status - State of the modifier keys.
time - Number of milliseconds since the device was turned on.
Returns:
True if event was consumed; otherwise, false.
Since:
JDE 4.0.2

outOfHolster

public void outOfHolster()
Invokd when the device is removed from the holster.
Since:
JDE 4.0.0

select

protected void select()
Activates the currently selected choice.

select

public void select(int value)
Activates the choice with the provided value.

This method finds the choice with the provided value, and selects that choice; then, it closes this dialog. If this dialog was not built with a range of values, then the value parameter indicates the index of the choice to select.

Parameters:
value - Value (or choice index) to select.
Since:
JDE 4.0.2

getSelectedValue

public int getSelectedValue()
Returns the value of the currently selected choice.
Returns:
Value of currently selected choice.

getDontAskAgainValue

public boolean getDontAskAgainValue()
Returns the value of the "Don't ask again" checkbox.
Returns:
Value of the "Don't ask again" checkbox.
Since:
JDE 4.0.2

close

public void close()
Closes this dialog.
Overrides:
close in class Screen
Since:
JDE 3.6.0

setDefault

public final void setDefault(int defaultChoice)
Sets the default choice.
Parameters:
defaultChoice - Choice index to set as default.
Since:
JDE 4.0.2

setEscapeEnabled

public final void setEscapeEnabled(boolean escapeEnabled)
Set escape enabled state for this dialog.
Parameters:
esacpeEnabled - Provide true if this dialog should support ESCAPE key handling; otherwise, provide false.
Since:
JDE 4.0.2

trackwheelClick

protected boolean trackwheelClick(int status,
                                  int time)
Handles trackwheel click events.

If this dialog was created with the LIST style, this method allows a trackwheel click to activate the currently selected dialog choice, consuming the event.

Otherwise, this method does not consume the event.

Overrides:
trackwheelClick in class Screen
Parameters:
status - Modifier key status.
time - Number of milliseconds since the device was turned on.
Returns:
True if this event was consumed; otherwise, false.
Since:
JDE 4.0.2


Copyright 1999-2004 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.