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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.Manager
          extended by net.rim.device.api.ui.Screen
              extended by net.rim.device.api.ui.container.PopupScreen
                  extended by net.rim.device.api.ui.component.Dialog
All Implemented Interfaces:
FieldChangeListener

public class Dialog
extends PopupScreen
implements FieldChangeListener

Provides a dialog box with predefined configurations.

To get a standard, predefined dialog use Dialog.alert(java.lang.String), Dialog.ask(int), or Dialog.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 Dialog.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 DELETE
          Delete choice for use in dialogs.
static int DISCARD
          Discard choice for use in dialogs.
static int D_DELETE
          Standard delete confirmation dialog.
static int D_OK
          Standard OK dialog.
static int D_OK_CANCEL
          Standard OK/Cancel confirmation dialog.
static int D_SAVE
          Standard save prompt dialog.
static int D_YES_NO
          Standard Yes/No confirmation dialog.
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, NO_SYSTEM_MENU_ITEMS
 
Fields inherited from class net.rim.device.api.ui.Manager
BOTTOMMOST, DOWNWARD, HORIZONTAL_SCROLL, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_MASK, HORIZONTAL_SCROLL_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_SCROLLBAR, VERTICAL_SCROLLBAR_MASK, VERTICAL_SCROLL_MASK
 
Fields inherited from class net.rim.device.api.ui.Field
ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL
 
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 the specified style.
Dialog(int type, String message, int defaultChoice, Bitmap bitmap, long style, boolean dontAskAgain)
          Deprecated. Use setDontAskAgainPrompt
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 the specified 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 a standard inquiry dialog.
static int ask(int type, String message)
          Creates an inquiry dialog with the specified message.
static int ask(int type, String message, int defaultChoice)
          Creates an inquiry dialog with the specified message.
static int ask(String message, Object[] choices, int defaultChoice)
          Creates an inquiry dialog with the specified message and choices.
static int ask(String message, Object[] choices, int[] values, int defaultChoice)
          Creates an inquiry dialog with the specified message, choices, and values.
 void cancel()
          Cancels this dialog.
 void close()
          Closes this dialog.
 int doModal()
          Displays a modal dialog.
 void fieldChanged(Field field, int context)
          Handles button select events for this dialog.
 AccessibleContext getAccessibleContext()
          Returns accessible representation of the field for a screen reader
 boolean getDontAskAgainValue()
          Deprecated. Use isDontAskAgainChecked()
 RichTextField getLabel()
          Retrieves the label for this dialog.
 int getPreferredWidth()
          Retrieves this dialog's preferred width.
protected static String[] getResourceChoices(int type)
          Returns the array of choices associated with the resource specified by the type parameter.
protected static int getResourceDefaultValue(int type)
          Returns the default value of the resource specified by the type parameter.
protected static String getResourceMessage(int type)
          Returns the message associated with the resource specified by the type parameter.
protected static int[] getResourceValues(int type)
          Returns the array of values associated with the resource specified by the type parameter.
 int getSelectedValue()
          Returns the value of the currently selected choice.
 void inHolster()
          Invoked when the device is put in the holster.
static void inform(String message)
          Creates a notification dialog with the specified message.
 boolean isDontAskAgainChecked()
          Returns the value of the "Don't ask again" checkbox.
protected  boolean keyChar(char key, int status, int time)
          Traps key generation events for this dialog.
protected  boolean navigationClick(int status, int time)
          Handles navigation click events.
protected  void onDisplay()
          Deprecated. Use Dialog.onUiEngineAttached(boolean).
protected  void onExposed()
          Invoked when this screen is exposed.
 boolean onMenu(int instance)
          Overrides the super class method and implements only one feature: pressing the Menu key when a dialog is up will activate the focused button Please override this method if a custom dialog wants to show a menu instead.
protected  void onObscured()
          Invoked when this screen is obscured.
protected  void onUiEngineAttached(boolean attached)
          Invoked when this dialog is pushed onto the display stack.
protected  void onUndisplay()
          Deprecated. Use Dialog.onUiEngineAttached(boolean).
 void outOfHolster()
          Invoked 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 specified value.
 void setDefault(int defaultChoice)
          Sets the default choice.
 void setDialogClosedListener(DialogClosedListener listener)
          Registers a listener for dialog close events.
 void setDontAskAgainPrompt(boolean prompt)
          Shows or hides a "Don't ask again" checkbox.
 void setEscapeEnabled(boolean escapeEnabled)
          Enables ESCAPE key handling.
 void setIcon(EncodedImage image)
          Sets the icon for this dialog.
 void show()
          Displays a modeless dialog of normal priority.
 void show(int priority)
          Displays a modeless dialog with the specified priority.
protected  boolean trackwheelClick(int status, int time)
          Handles trackwheel click events.
 
Methods inherited from class net.rim.device.api.ui.container.PopupScreen
paint, sublayout
 
Methods inherited from class net.rim.device.api.ui.Screen
addKeyListener, addScreenUiEngineAttachedListener, addTrackwheelListener, delete, deleteRange, doPaint, ensureRegionVisible, getApplication, getDefaultMenuItem, getDelegate, getField, getFieldAtLocation, getFieldCount, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getGraphics, getLeafFieldWithFocus, getMenu, getScreenAbove, getScreenBelow, getUiEngine, getVirtualKeyboard, insert, invalidate, invalidate, invalidateAll, invalidateLayout, invokeAction, isDataValid, isDirty, isDisplayed, isFocus, isFocusable, isGlobal, isGlobalStatus, isMuddy, isSelecting, keyCharUnhandled, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layoutDelegate, makeMenu, navigationMovement, navigationUnclick, onClose, onFocus, onFocusNotify, onMenuDismissed, onMenuDismissed, onSave, onSavePrompt, onUnfocus, openDevelopmentBackdoor, openProductionBackdoor, paintBackground, removeFocus, removeKeyListener, removeScreenUiEngineAttachedListener, removeTrackwheelListener, replace, save, scroll, setBackdoorAltStatus, setDefaultClose, setDirty, setFocus, setFocus, setHorizontalQuantization, setPositionDelegate, setTrackballFilter, setTrackballSensitivityXOffset, setTrackballSensitivityYOffset, setVerticalQuantization, touchEvent, trackwheelClickUnhandled, trackwheelRoll, trackwheelUnclick, updateDisplay
 
Methods inherited from class net.rim.device.api.ui.Manager
addAll, deleteAll, getHorizontalScroll, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, getVisibleHeight, getVisibleWidth, invalidateFieldRange, isDownArrowShown, isUpArrowShown, isValidLayout, layout, layoutChild, moveFocus, moveFocus, nextFocus, nextFocus, paintChild, setFocus, setHorizontalScroll, setHorizontalScroll, setPositionChild, setScrollListener, setScrollingInertial, setVerticalScroll, setVirtualExtent, subpaint
 
Methods inherited from class net.rim.device.api.ui.Field
drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getOriginal, getPreferredHeight, getScreen, getStyle, getTop, getVisualState, getWidth, isEditable, isPasteable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setEditable, setExtent, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, setVisualState, 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.

See Also:
Constant Field Values

D_SAVE

public static final int D_SAVE
Standard save prompt dialog.

See Also:
Constant Field Values

D_DELETE

public static final int D_DELETE
Standard delete confirmation dialog.

See Also:
Constant Field Values

D_YES_NO

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

See Also:
Constant Field Values

D_OK_CANCEL

public static final int D_OK_CANCEL
Standard OK/Cancel confirmation dialog.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.0

CANCEL

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

See Also:
Constant Field Values

OK

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

See Also:
Constant Field Values

SAVE

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

See Also:
Constant Field Values

DISCARD

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

See Also:
Constant Field Values

DELETE

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

See Also:
Constant Field Values

YES

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

See Also:
Constant Field Values

NO

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

See Also:
Constant Field Values

LIST

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

See Also:
Constant Field Values

GLOBAL_STATUS

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

See Also:
Constant Field Values


Constructor Detail

Dialog

public Dialog(String message,
              Object[] choices,
              int[] values,
              int defaultChoice,
              Bitmap bitmap)
Constructs a new Dialog instance.

Parameters:
message - Message to display in the dialog.
choices - Objects selectable by the user. Each object is displayed using Object.toString().
values - If this parameter is specified, instead of returning the index selected, Dialog.doModal() returns the value associated with this index (useful for adding Dialog.CANCEL).
defaultChoice - Initial choice selected when the Dialog is displayed. If you provide a non-null values parameter, the default choice must be present in the values 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 the specified style.

Parameters:
message - Message to display in the dialog.
choices - Objects selectable by the user. Each object is displayed using Object.toString().
values - If this parameter is specified, instead of returning the index selected, Dialog.doModal() returns the value associated with this index (useful for adding Dialog.CANCEL).
defaultChoice - Initial choice selected when the Dialog is displayed. 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 the specified style.

Builds a standard inquiry dialog with the specified message.

Parameters:
type - Standard inquiry dialog type: Dialog.D_OK, Dialog.D_SAVE, Dialog.D_DELETE, Dialog.D_YES_NO, Dialog.D_OK_CANCEL.
message - Text message to display in the 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)
Deprecated. Use setDontAskAgainPrompt

Contructs a new Dialog instance with the specified style.

Builds a standard inquiry dialog with the specified message.

Parameters:
type - Standard inquiry dialog type: Dialog.D_OK, Dialog.D_SAVE, Dialog.D_DELETE, Dialog.D_YES_NO, Dialog.D_OK_CANCEL,
message - Text message to display in the 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:
BlackBerry API 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.

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.

ask

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

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

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

ask

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

Builds a standard inquiry dialog with the specified message. The dialog uses a question mark bitmap.

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

ask

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

Builds a standard inquiry dialog with the specified message. The dialog uses a question mark bitmap.

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

ask

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

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

Parameters:
message - Text message to display in the dialog.
choices - Choices selectable by the user. Each object is displayed using Object.toString().
defaultChoice - The value of the selected choice.
Returns:
The index of the selected choice.

ask

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

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

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

cancel

public void cancel()
Cancels this dialog.

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

Since:
BlackBerry API 4.0.0

doModal

public int doModal()
Displays a modal dialog.

This method is a blocking call that 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).

getAccessibleContext

public AccessibleContext getAccessibleContext()
Returns accessible representation of the field for a screen reader

Overrides:
getAccessibleContext in class Screen
Returns:
AccessibleContext instance
Since:
BlackBerry API 4.6.1

getDontAskAgainValue

public boolean getDontAskAgainValue()
Deprecated. Use isDontAskAgainChecked()

Returns the value of the "Don't ask again" checkbox.

Returns:
Value of the "Don't ask again" checkbox.
Since:
BlackBerry API 4.0.2

getLabel

public RichTextField getLabel()
Retrieves the label for this 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.

getResourceChoices

protected static String[] getResourceChoices(int type)
Returns the array of choices associated with the resource specified by the type parameter.

Parameters:
type - Standard inquiry dialog type: Dialog.D_OK, Dialog.D_SAVE, Dialog.D_DELETE, Dialog.D_YES_NO, Dialog.D_OK_CANCEL.
Returns:
The array of choices associated with the resource specified by the type parameter.
Since:
BlackBerry API 4.0.0

getResourceMessage

protected static String getResourceMessage(int type)
Returns the message associated with the resource specified by the type parameter.

Parameters:
type - Standard inquiry dialog type: Dialog.D_OK, Dialog.D_SAVE, Dialog.D_DELETE, Dialog.D_YES_NO, Dialog.D_OK_CANCEL.
Returns:
The message associated with the resource specified by the type parameter.
Since:
BlackBerry API 4.0.0

getResourceValues

protected static int[] getResourceValues(int type)
Returns the array of values associated with the resource specified by the type parameter.

Parameters:
type - Standard inquiry dialog type: Dialog.D_OK, Dialog.D_SAVE, Dialog.D_DELETE, Dialog.D_YES_NO, Dialog.D_OK_CANCEL.
Returns:
The array of values associated with the resource specified by the type parameter.
Since:
BlackBerry API 4.0.0

getResourceDefaultValue

protected static int getResourceDefaultValue(int type)
Returns the default value of the resource specified by the type parameter.

Parameters:
type - Standard inquiry dialog type: Dialog.D_OK, Dialog.D_SAVE, Dialog.D_DELETE, Dialog.D_YES_NO, Dialog.D_OK_CANCEL.
Returns:
The default value of the resource specified by the type paramter.
Since:
BlackBerry API 4.0.0

getSelectedValue

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

Returns:
Value of currently selected choice.

navigationClick

protected boolean navigationClick(int status,
                                  int time)
Handles navigation click events.

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

Otherwise, this method does not consume the event.

The source of the navigation event can be determined by checking the KeypadListener.STATUS_TRACKWHEEL and KeypadListener.STATUS_FOUR_WAY bits in the status parameter; exactly one of them will be set.

Overrides:
navigationClick in class Screen
Parameters:
status - Bitfield of values defined by KeypadListener.
time - Number of milliseconds since the device was turned on.
Returns:
True if this event was consumed; otherwise, false.
Since:
BlackBerry API 4.2.0

onUiEngineAttached

protected void onUiEngineAttached(boolean attached)
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 focused region stays on the screen).

Overrides:
onUiEngineAttached in class Screen
Parameters:
attached - true is it is an attach event, false if it is a detach event
See Also:
Screen.onExposed(), Screen.onFocusNotify(boolean)
Since:
BlackBerry API 4.3.0

onExposed

protected void onExposed()
Description copied from class: Screen
Invoked when this screen is exposed. A Screen is exposed when it becomes the topmost by means of:
  1. a screen is popped off the display stack (since 3.0)
  2. a global screen is popped (since 4.0)
  3. this screen's application receives foreground (since 4.2)
  4. this screen is pushed and it is deemed exposed by the above rules (since 4.2)

Subclasses of screen should override this method for special handling.

The complementing callback is Screen.onObscured().

Overrides:
onExposed in class Screen
See Also:
Screen.onUiEngineAttached(boolean), Field.onVisibilityChange(boolean)
Since:
BlackBerry API 4.0.0

onObscured

protected void onObscured()
Description copied from class: Screen
Invoked when this screen is obscured. A Screen is obscured when it is was the topmost and is no longer by means of:
  1. a new screen pushed on the display stack (since 3.0)
  2. a global screen is displayed above this screen (since 4.0)
  3. this screen's application goes into the background (since 4.2)
  4. this screen is pushed and it is deemed obscured by the above rules (since 4.2)

Derived classes should override this method for special handling.

The complementing callback is Screen.onExposed().

Overrides:
onObscured in class Screen
See Also:
Screen.onUiEngineAttached(boolean), Field.onVisibilityChange(boolean)
Since:
BlackBerry API 4.0.0

show

public void show()
Displays 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)
Displays a modeless dialog with the specified 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.

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.

fieldChanged

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

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

Specified by:
fieldChanged in interface FieldChangeListener
Parameters:
field - Field whose state changed.
context - Information specifying the origin of the change.

inHolster

public void inHolster()
Invoked when the device is put in the holster.

Since:
BlackBerry API 4.0.0

inform

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

This method creates a notification dialog displaying the specified message. The dialog uses the "information" bitmap.

Parameters:
message - Text to display in the dialog.

isDontAskAgainChecked

public boolean isDontAskAgainChecked()
Returns the value of the "Don't ask again" checkbox.

Returns:
Value of the "Don't ask again" checkbox.
Since:
BlackBerry API 5.0.0

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 Dialog.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.

outOfHolster

public void outOfHolster()
Invoked when the device is removed from the holster.

Since:
BlackBerry API 4.0.0

select

protected void select()
Activates the currently selected choice.


select

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

This method finds the choice with the specified 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.

close

public void close()
Closes this dialog.

Overrides:
close in class Screen
Since:
BlackBerry API 3.6.0

setDefault

public final void setDefault(int defaultChoice)
Sets the default choice.

Parameters:
defaultChoice - Choice index to set as default.

setDontAskAgainPrompt

public void setDontAskAgainPrompt(boolean prompt)
Shows or hides a "Don't ask again" checkbox.

Parameters:
prompt -
Since:
BlackBerry API 5.0.0

setEscapeEnabled

public final void setEscapeEnabled(boolean escapeEnabled)
Enables ESCAPE key handling.

Parameters:
esacpeEnabled - Provide true if this dialog should support ESCAPE key handling; otherwise, provide false.

setIcon

public void setIcon(EncodedImage image)
Sets the icon for this dialog. If the specified image is null, then setIcon(null) is invoked on this dialog's DialogFieldManager, clearing the icon. Otherwise, a BitmapField is created from the specified image and the newly-created field is specified to DialogFieldManager.setIcon() to set the icon.

Parameters:
image - the image to set for the icon of this dialog, or null to remove the icon of this dialog.
See Also:
DialogFieldManager.setIcon(BitmapField)
Since:
BlackBerry API 4.2.0

trackwheelClick

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

If this dialog was created with the Dialog.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.

onDisplay

protected void onDisplay()
Deprecated. Use Dialog.onUiEngineAttached(boolean).

Description copied from class: Screen
Invoked when this screen is pushed onto the display stack.

This method is invoked by the system after this screen 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 focused region stays on the screen).

The complementary callback is Screen.onUndisplay().

Overrides:
onDisplay in class Screen

onUndisplay

protected void onUndisplay()
Deprecated. Use Dialog.onUiEngineAttached(boolean).

Description copied from class: Screen
Invoked when this screen is popped off the display stack.

Derived classes should override this method for special handling.

The complementing callback is Screen.onDisplay().

Overrides:
onUndisplay in class Screen
Since:
BlackBerry API 4.0.0

onMenu

public boolean onMenu(int instance)
Overrides the super class method and implements only one feature: pressing the Menu key when a dialog is up will activate the focused button

Please override this method if a custom dialog wants to show a menu instead. Focused button will not be activated in this case.

Overrides:
onMenu in class Screen
Parameters:
instance - Instance of the menu to display. It is not used in this case.
Returns:
True if the menu is created; otherwise, false.
Since:
BlackBerry API 5.0.0





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.