acm.io
Class IODialog

java.lang.Object
  |
  +--acm.io.IODialog

public class IODialog extends Object implements IOModel

The IODialog class provides a simple, dialog-based mechanism for interacting with the user. It is therefore similar to the JOptionPane facility in Swing (which it uses in the implementation). The differences between the models are

1. The IODialog mechanism is considerably simpler, mostly because it does not try to be as general.
2. The IODialog mechanism does not use static methods; clients instantiate an IODialog object and make calls on that object, thereby emphasizing the object-oriented idea.
3. The IODialog class works even if Swing is not available.

The input methods available for IODialog are intentionally the same as those for the IOConsole class so that clients can substitute one model for another without making source changes. The input methods are therefore

• readInt
• readDouble
• readBoolean
• readLine

For example, the following code pops up the dialog shown on the right and allows the user to enter an integer:

IODialog dialog = new IODialog(); int n = dialog.readInt("Enter an integer: ");

Constructor Summary

IODialog()

IODialog(Component owner)

Method Summary

boolean	getAllowCancel() Returns the state of the cancellation mode.
boolean	getExceptionOnError() Returns the state of the error-handling flag.
void	print(String value) Displays the argument value, allowing for the possibility of more output in the same dialog.
void	println() Completes the output line and displays the dialog.
void	println(String value) Adds the value to the current output line and then displays the dialog.
boolean	readBoolean() Reads and returns a boolean value from the user, which must match either true or false, ignoring case.
boolean	readBoolean(String prompt) Prompts the user to enter a boolean value, which is then returned as the value of this method.
boolean	readBoolean(String prompt, String trueLabel, String falseLabel) Prompts the user to enter a value, which is interpreted as a boolean value by matching it against the trueLabel and falseLabel parameters.
double	readDouble() Reads and returns a double-precision value from the user.
double	readDouble(double low, double high) Reads and returns a double-precision value from the user, which is constrained to be within the specified inclusive range.
double	readDouble(String prompt) Prompts the user to enter an double-precision number, which is then returned as the value of this method.
double	readDouble(String prompt, double low, double high) Prompts the user to enter an double-precision number, which is then returned as the value of this method.
int	readInt() Reads and returns an integer value from the user.
int	readInt(int low, int high) Reads and returns an integer value from the user, which is constrained to be within the specified inclusive range.
int	readInt(String prompt) Prompts the user to enter an integer, which is then returned as the value of this method.
int	readInt(String prompt, int low, int high) Prompts the user to enter an integer, which is then returned as the value of this method.
String	readLine() Reads and returns a line of input from the dialog, without including the end-of-line characters that terminate the input.
String	readLine(String prompt) Prompts the user to enter a single character, which is then returned as the value of this method.
void	setAllowCancel(boolean flag) Sets the cancellation mode of the dialog as specified by the flag parameter.
void	setExceptionOnError(boolean flag) Sets the error-handling mode of the dialog as specified by the flag parameter.
void	showErrorMessage(String msg) Displays the error message in an error dialog.

Constructor Detail

public IODialog()

Instantiates a new IODialog object that can then be used for dialog-based input and output.

Usage:

dialog = new IODialog();

public IODialog(Component owner)

Instantiates a new IODialog object that can then be used for dialog-based input and output.

Usage:

dialog = new IODialog(owner);

Parameter:

owner

A Component used as the owner of created dialogs

Method Detail

public boolean getAllowCancel()

Returns the state of the cancellation mode.

Usage:	boolean flag = dialog.getAllowCancel();
Returns:	The current setting of the error-handling mode (false to retry on errors; true to raise an exception)

public boolean getExceptionOnError()

Returns the state of the error-handling flag.

Usage:	boolean flag = dialog.getExceptionOnError();
Returns:	The current setting of the error-handling mode (false to retry on errors; true to raise an exception)

public void print(String value)

Displays the argument value, allowing for the possibility of more output in the same dialog. The print method is overloaded so that value can be of any type.

Usage:

dialog.print(value);

Parameter:

value

The value to be displayed

Specified by:

print in interface IOModel

public void println()

Completes the output line and displays the dialog.

Usage:	dialog.println();
Specified by:	println in interface IOModel

public void println(String value)

Adds the value to the current output line and then displays the dialog. The println method is overloaded so that value can be of any type.

Usage:

dialog.println(value);

Parameter:

value

The value to be displayed

Specified by:

println in interface IOModel

public final boolean readBoolean()

Reads and returns a boolean value from the user, which must match either true or false, ignoring case. If the user types a value that is not one of these possibilities, the method ordinarily offers the user a chance to reenter the data, although this behavior can be changed using the setExceptionOnError method.

Usage:	boolean flag = dialog.readBoolean();
Returns:	The value of the input interpreted as a boolean value
Specified by:	readBoolean in interface IOModel

public final boolean readBoolean(String prompt)

Prompts the user to enter a boolean value, which is then returned as the value of this method. If the user types a value that is not a legal boolean value, the method ordinarily offers the user a chance to reenter the data, although this behavior can be changed using the setExceptionOnError method.

Usage:

boolean flag = dialog.readBoolean(prompt);

Parameter:

prompt

The prompt string to display to the user

Returns:

The value of the input interpreted as a boolean value

Specified by:

readBoolean in interface IOModel

public boolean readBoolean(String prompt, String trueLabel, String falseLabel)

Prompts the user to enter a value, which is interpreted as a boolean value by matching it against the trueLabel and falseLabel parameters. If the user types a value that is not one of the two choices, readBoolean ordinarily offers the user a chance to reenter the data, although this behavior can be changed using the setExceptionOnError method.

Usage:

boolean flag = dialog.readBoolean(prompt);

Parameters:

prompt	The prompt string to display to the user
trueLabel	The label for the button indicating true
falseLabel	The label for the button indicating false

Returns:

The value of the input interpreted as a boolean value

Specified by:

readBoolean in interface IOModel

public final double readDouble()

Reads and returns a double-precision value from the user. If the user types a value that is not a legal number, the method ordinarily offers the user a chance to reenter the data, although this behavior can be changed using the setExceptionOnError method.

Usage:	double d = dialog.readDouble();
Returns:	The value of the input interpreted as a double
Specified by:	readDouble in interface IOModel

public final double readDouble(double low, double high)

Reads and returns a double-precision value from the user, which is constrained to be within the specified inclusive range. If the user types a value that is not a legal number, the method ordinarily offers the user a chance to reenter the data, although this behavior can be changed using the setExceptionOnError method.

Usage:

double d = dialog.readDouble(low, high);

Parameters:

low	The lowest value in the permitted range
high	The highest value in the permitted range

Returns:

The value of the input interpreted as a double

Specified by:

readDouble in interface IOModel

public final double readDouble(String prompt)

Prompts the user to enter an double-precision number, which is then returned as the value of this method. If the user types a value that is not a legal number, the method ordinarily offers the user a chance to reenter the data, although this behavior can be changed using the setExceptionOnError method.

Usage:

double d = dialog.readDouble(prompt);

Parameter:

prompt

The prompt string to display to the user

Returns:

The value of the input interpreted as a double

Specified by:

readDouble in interface IOModel

public double readDouble(String prompt, double low, double high)

Prompts the user to enter an double-precision number, which is then returned as the value of this method. The value must be within the inclusive range between low and high. If the user types a value that is not a legal number, the method ordinarily offers the user a chance to reenter the data, although this behavior can be changed using the setExceptionOnError method.

Usage:

d = dialog.readDouble(prompt, low, high);

Parameters:

prompt	The prompt string to display to the user
low	The lowest value in the permitted range
high	The highest value in the permitted range

Returns:

The value of the input interpreted as a double

Specified by:

readDouble in interface IOModel

public final int readInt()

Reads and returns an integer value from the user. If the user types a value that is not a legal integer, the method ordinarily offers the user a chance to reenter the data, although this behavior can be changed using the setExceptionOnError method.

Usage:	int n = dialog.readInt();
Returns:	The value of the input interpreted as a decimal integer
Specified by:	readInt in interface IOModel

public final int readInt(int low, int high)

Reads and returns an integer value from the user, which is constrained to be within the specified inclusive range. If the user types a value that is not a legal integer, the method ordinarily offers the user a chance to reenter the data, although this behavior can be changed using the setExceptionOnError method.

Usage:

int n = dialog.readInt(low, high);

Parameters:

low	The lowest value in the permitted range
high	The highest value in the permitted range

Returns:

The value of the input interpreted as a decimal integer

Specified by:

readInt in interface IOModel

public final int readInt(String prompt)

Prompts the user to enter an integer, which is then returned as the value of this method. If the user types a value that is not a legal integer, the method ordinarily offers the user a chance to reenter the data, although this behavior can be changed using the setExceptionOnError method.

Usage:

int n = dialog.readInt(prompt);

Parameter:

prompt

The prompt string to display to the user

Returns:

The value of the input interpreted as a decimal integer

Specified by:

readInt in interface IOModel

public int readInt(String prompt, int low, int high)

Prompts the user to enter an integer, which is then returned as the value of this method. The value must be within the inclusive range between low and high. If the user types a value that is not a legal integer or is outside the specified range, the method ordinarily offers the user a chance to reenter the data, although this behavior can be changed using the setExceptionOnError method.

Usage:

int n = dialog.readInt(prompt, low, high);

Parameters:

prompt	The prompt string to display to the user
low	The lowest value in the permitted range
high	The highest value in the permitted range

Returns:

The value of the input interpreted as a decimal integer

Specified by:

readInt in interface IOModel

public final String readLine()

Reads and returns a line of input from the dialog, without including the end-of-line characters that terminate the input.

Usage:	String str = dialog.readLine();
Returns:	The next line of input as a String
Specified by:	readLine in interface IOModel

public String readLine(String prompt)

Prompts the user to enter a single character, which is then returned as the value of this method. The end-of-line characters that terminate the input are not included in the returned string.

Usage:

String str = dialog.readLine(prompt);

Parameter:

prompt

The prompt string to display to the user

Returns:

The next line of input as a String

Specified by:

readLine in interface IOModel

public void setAllowCancel(boolean flag)

Sets the cancellation mode of the dialog as specified by the flag parameter. If flag is false (which is the default), the input methods do not include a "Cancel" button. If this value is set to to true, a "Cancel" button appears, which throws a CancelledException if it is invoked.

Usage:

dialog.setAllowCancel(flag);

Parameter:

flag	false to remove "Cancel" button; true to enable it

public void setExceptionOnError(boolean flag)

Sets the error-handling mode of the dialog as specified by the flag parameter. If flag is false (which is the default), the input methods give the user a chance to retry after erroneous input. If this value is set to true, illegal input raises an ErrorException instead.

Usage:

dialog.setExceptionOnError(flag);

Parameter:

flag	false to retry on errors; true to raise an exception

public void showErrorMessage(String msg)

Displays the error message in an error dialog.

Usage:

dialog.showErrorMessage(msg);

Parameter:

msg	The error msg to be displayed

Specified by:

showErrorMessage in interface IOModel