org.eclipse.ercp.swt.mobile
Class QueryDialog

java.lang.Object
  org.eclipse.swt.widgets.Dialog
      org.eclipse.ercp.swt.mobile.QueryDialog

public class QueryDialog

extends Dialog

A modal window used to prompt the end-user for data input.

A QueryDialog contains a prompt text and an entry field. The QueryDialog supports five types of entry fields: STANDARD, NUMERIC, PASSWORD, TIME and DATE. The position and size of the dialog is implementation-dependent.

Styles:

APPLICATION_MODAL, PRIMARY_MODAL

Query types:

STANDARD: alphanumeric data input

NUMERIC: numerical only data input

PASSWORD: a platform-dependent way for sensitive information input. The initial input mode is set to allow entry of digit characters

TIME: time input. The default and return values are strings in the international standard time notation (ISO 8601), hh:mm:ss, where hh is the number of complete hours that have passed since midnight (00-24), mm is the number of complete minutes that have passed since the start of the hour (00-59), and ss is the number of complete seconds since the start of the minute (00-60). If the hour value is 24, then the minute and second values must be zero. The visual representation of the time is locale specific. If the implementation does not display the number of seconds, the second value returned is zero.

DATE: date input. The default and return values are strings in the international standard date notation (ISO 8601) "YYYY-MM-DD", where YYYY is the year in the Gregorian calendar, MM is the month of the year between 01 (January) and 12 (December), and DD is the day of the month between 01 and 31. The visual representation of the date is locale specific.

Events:

(none)

Note: When the style is either DATE or TIME, the date or time input is locale specific. User entered data is constrained to a valid date or time and is converted to an ISO 8601 string format to be returned from open().

Example:

 QueryDialog dialog = new QueryDialog(shell, SWT.NONE, QueryDialog.STANDARD);
 dialog.setPromptText("Enter name:", "game1");
 String gameName = dialog.open();
 if (gameName != null) {
 	// OK
 	// do something
 } else {
 	// Cancelled
 	// do something else
 }
 

IMPORTANT: This class is not intended to be subclassed.

Field Summary

static int	DATE Date entry type.
static int	NUMERIC Numerical data entry type.
static int	PASSWORD Password entry type.
static int	STANDARD Alphanumeric data entry type
static int	TIME Time entry type.

Constructor Summary

QueryDialog(Shell parent)
Constructs a new instance of this class given its parent.

QueryDialog(Shell parent, int style)
Constructs a new instance of this class given its parent and style .

QueryDialog(Shell parent, int style, int queryType)
Constructs a new instance of this class given its parent, style and query type.

Method Summary

java.lang.String	open() Creates the prompt dialog in front of its parent shell and waits for input.
void	setMaximum(int maximum) Defines the maximum number of characters that can be entered.
void	setMinimum(int minimum) Defines the minimum number of characters that must be entered before the dialog can be completed (not cancelled).
void	setPromptText(java.lang.String promptText, java.lang.String defaultValue) Sets the prompt text and default input value.

Methods inherited from class org.eclipse.swt.widgets.Dialog

checkSubclass, getParent, getStyle, getText, setText

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

STANDARD

public static final int STANDARD

Alphanumeric data entry type

See Also:

Constant Field Values

PASSWORD

public static final int PASSWORD

Password entry type. The input method and resulting string value are platform-dependent.

See Also:

Constant Field Values

NUMERIC

public static final int NUMERIC

Numerical data entry type. Only locale-dependent digit characters are allowed.

See Also:

Constant Field Values

TIME

public static final int TIME

Time entry type. The implementation can decide to use either 12 or 24 hour mode for input, but the return value is in 24 hour format.

See Also:

Constant Field Values

DATE

public static final int DATE

Date entry type.

See Also:

Constant Field Values

Constructor Detail

QueryDialog

public QueryDialog(Shell parent)

Constructs a new instance of this class given its parent.

By default, APPLICATION_MODAL style and STANDARD query type is used.

Parameters:

parent - a shell which will be the parent of the new instance

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the parent is null

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

See Also:

QueryDialog(Shell, int, int)

QueryDialog

public QueryDialog(Shell parent,
                   int style)

Constructs a new instance of this class given its parent and style .

The style value is either one of the style constants defined in class Dialog. By default STANDARD query type is used.

Parameters:

parent - a shell which will be the parent of the new instance

style - the style of control to construct

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the parent is null

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

SWT.APPLICATION_MODAL, SWT.PRIMARY_MODAL, QueryDialog(Shell, int, int)

QueryDialog

public QueryDialog(Shell parent,
                   int style,
                   int queryType)

Constructs a new instance of this class given its parent, style and query type.

The style value is either one of the style constants defined in class Dialog.

Parameters:

parent - a shell which will be the parent of the new instance

style - the style of control to construct

queryType - one of STANDARD, NUMERIC, PASSWORD, TIME, or DATE.

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the parent is null
• ERROR_INVALID_ARGUMENT - if the queryType is invalid

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

See Also:

SWT.APPLICATION_MODAL, SWT.PRIMARY_MODAL, STANDARD, PASSWORD, NUMERIC, TIME, DATE

Method Detail

open

public java.lang.String open()

Creates the prompt dialog in front of its parent shell and waits for input. This method will return when the input is finished or cancelled.

Returns:

String the value entered. Null means that input was cancelled, regardless of whether a default value was specified. For STANDARD, NUMERIC, and PASSWORD types, the string contains precisely the characters entered without any formatting, up to the maximum number of characters. For DATE and TIME types, the string contains an ISO 8601 formatted value.

Throws:

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_WIDGET_DISPOSED - if the dialog has been disposed

setMaximum

public void setMaximum(int maximum)

Defines the maximum number of characters that can be entered. If the input string already exceeds the maximum, the excessive part of the value is not displayed. Usually the maximum length is system-dependent, and applications should not specify it. Note: This method has no effect for DATE and TIME types.

Parameters:

maximum - the maximum character length. Must be equal or greater than zero. Zero means no limit.

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if maximum is negative, or less than the minimum length defined by setMinimum(int).
• ERROR_INVALID_ARGUMENT - if maximum is greater than the real maximum length the receiver can hold. Typically the real maximum length is defined by Text.LIMIT

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_WIDGET_DISPOSED - if the dialog has been disposed

See Also:

setMinimum(int)

setMinimum

public void setMinimum(int minimum)

Defines the minimum number of characters that must be entered before the dialog can be completed (not cancelled). Note: This method has no effect for DATE and TIME types.

Parameters:

minimum - the minimum number of characters. Must be equal or greater than zero. Zero means no limit.

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if minimum is negative, or greater than the maximum length defined by setMaximum(int).

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_WIDGET_DISPOSED - if the dialog has been disposed

See Also:

setMaximum(int)

setPromptText

public void setPromptText(java.lang.String promptText,
                          java.lang.String defaultValue)

Sets the prompt text and default input value.

Parameters:

promptText - the prompt text. Can be null.

defaultValue - the initial value. Cannot be null. The open() method may return the same value even when no input is received from the end-user. If the value length is greater than the maximum number of characters, only the maximum will be displayed.

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if defaultValue is null
• ERROR_INVALID_ARGUMENT - if defaultValue format is invalid (only for DATE and TIME styles)

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_WIDGET_DISPOSED - if the dialog has been disposed