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

public class Dialog

extends PopupScreen

implements FieldChangeListener

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_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 object with provided style.

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

Dialog(String message, Object[] choices, int[] values, int defaultChoice, Bitmap bitmap, long style)
Contructs a new Dialog object 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	close() Implements Screen.close().
int	doModal() Shows a modal dialog.
void	fieldChanged(Field field, int context) Handles button select events for this dialog.
RichTextField	getLabel() Retrieves label for the dialog.
int	getPreferredWidth() Retrieves this dialog's preferred width.
int	getSelectedValue() Returns the value of the currently selected choice.
static void	inform(String message) Creates a nofitication dialog with message.
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	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

paint, sublayout

Methods inherited from class net.rim.device.api.ui.Screen

addKeyListener, addTrackwheelListener, delete, deleteRange, doLayout, doPaint, ensureRegionVisible, getDelegate, getField, getFieldAtLocation, getFieldCount, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getGraphics, getLeafFieldWithFocus, getUiEngine, insert, invalidate, invalidateLayout, isDirty, isDisplayed, isFocusable, isGlobalStatus, isMuddy, isSelecting, keyCharUnhandled, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layoutDelegate, makeMenu, onClose, onExposed, onFocus, onMenu, onObscured, onSave, onSavePrompt, onUndisplay, onUnfocus, paintBackground, removeFocus, removeKeyListener, removeTrackwheelListener, save, scroll, 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, invalidate, 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, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getOriginal, getPreferredHeight, getScreen, getStyle, getTop, getWidth, isEditable, isPasteable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, 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 object.

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

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 3.6

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 3.6

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 getSelectedChoice(). For example, CANCEL, OK, or DELETE are some of the possible return values.

Since:

JDE 3.6

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 getSelectedChoice(). For example, CANCEL, OK, or DELETE are some of the possible return values.

Since:

JDE 3.6

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 - Initially selected choice.

Returns:

The value(not the index) of the selected choice, as would be returned from getSelectedChoice(). For example, CANCEL, OK, or DELETE are some of the possible return values.

Since:

JDE 3.6

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 - Index of initially selected choice.

Returns:

The value(not the index) of the selected choice, as would be returned from getSelectedChoice(). For example, CANCEL, OK, or DELETE are some of the possible return values.

Since:

JDE 3.6

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 - Index of initially selected choice.

Returns:

The value(not the index) of the selected choice, as would be returned from getSelectedChoice(). For example, CANCEL, OK, or DELETE are some of the possible return values.

Since:

JDE 3.6

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

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.onUndisplay(), Screen.onExposed(), Field.onVisibilityChange(boolean)

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 listener when this dialog closes.

Parameters:

priority - Display priority for this dialog, if it is an GLOBAL_STATUS screen.

Since:

JDE 3.6

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 3.6

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.

Specified by:

fieldChanged in interface FieldChangeListener

Parameters:

field - Field whose state changed.

context - Information specifying the origin of the change.

Since:

JDE 3.6

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.

inform

public static void inform(String message)

Creates a nofitication 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 3.6

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 - Ticks since device reset.

Returns:

True if event was consumed; otherwise, false.

Since:

JDE 3.6

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 3.6

getSelectedValue

public int getSelectedValue()

Returns the value of the currently selected choice.

close

public void close()

Implements Screen.close().

Overrides:

close in class Screen

setDefault

public final void setDefault(int defaultChoice)

Sets the default choice.

Parameters:

defaultChoice - Choice index to set as default.

Since:

JDE 3.6

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 3.6

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 - Ticks since device reset.

Returns:

True if this event was consumed; otherwise, false.

Since:

JDE 3.6