acm.io
Class IODialog

java.lang.Object
  acm.io.IODialog

All Implemented Interfaces:

IOModel

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 a dialog box and allows the user to enter an integer:

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

Constructor Summary

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

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

Method Summary

protected acm.io.DialogModel	createModel() Creates the input dialog model in Swing or AWT style, as appropriate.
boolean	getAllowCancel() Returns the state of the cancellation mode.
IOConsole	getAssociatedConsole() Returns the associated console for the dialog.
boolean	getExceptionOnError() Returns the state of the error-handling flag.
void	print(boolean x) Makes sure that print can display a boolean.
void	print(char x) Makes sure that print can display a char.
void	print(double x) Makes sure that print can display a double.
void	print(float x) Makes sure that print can display a float.
void	print(int x) Makes sure that print can display an int.
void	print(long x) Makes sure that print can display a long.
void	print(Object x) Makes sure that print can display an Object.
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(boolean x) Makes sure that println can display a boolean.
void	println(char x) Makes sure that println can display a char.
void	println(double x) Makes sure that println can display a double.
void	println(float x) Makes sure that println can display a float.
void	println(int x) Makes sure that println can display an int.
void	println(long x) Makes sure that println can display a long.
void	println(Object x) Makes sure that println can display an Object.
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	setAssociatedConsole(IOConsole console) Establishes an associated console for the dialog.
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.

Methods inherited from class java.lang.Object

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

Constructor Detail

IODialog

public IODialog()

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

IODialog

public IODialog(Component owner)

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

Parameters:

owner - A Component used as the owner of created dialogs

Method Detail

createModel

protected acm.io.DialogModel createModel()

Creates the input dialog model in Swing or AWT style, as appropriate.

getAllowCancel

public boolean getAllowCancel()

Returns the state of the cancellation mode.

Returns:

The current setting of the error-handling mode (false to retry on errors; true to raise an exception)

getAssociatedConsole

public IOConsole getAssociatedConsole()

Returns the associated console for the dialog.

Returns:

The associated console

getExceptionOnError

public boolean getExceptionOnError()

Returns the state of the error-handling flag.

Returns:

The current setting of the error-handling mode (false to retry on errors; true to raise an exception)

print

public final void print(boolean x)

Makes sure that print can display a boolean.

Specified by:

print in interface IOModel

print

public final void print(char x)

Makes sure that print can display a char.

Specified by:

print in interface IOModel

print

public final void print(double x)

Makes sure that print can display a double.

Specified by:

print in interface IOModel

print

public final void print(float x)

Makes sure that print can display a float.

Specified by:

print in interface IOModel

print

public final void print(int x)

Makes sure that print can display an int.

Specified by:

print in interface IOModel

print

public final void print(long x)

Makes sure that print can display a long.

Specified by:

print in interface IOModel

print

public final void print(Object x)

Makes sure that print can display an Object.

Specified by:

print in interface IOModel

print

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.

Specified by:

print in interface IOModel

Parameters:

value - The value to be displayed

println

public void println()

Completes the output line and displays the dialog.

Specified by:

println in interface IOModel

println

public final void println(boolean x)

Makes sure that println can display a boolean.

Specified by:

println in interface IOModel

println

public final void println(char x)

Makes sure that println can display a char.

Specified by:

println in interface IOModel

println

public final void println(double x)

Makes sure that println can display a double.

Specified by:

println in interface IOModel

println

public final void println(float x)

Makes sure that println can display a float.

Specified by:

println in interface IOModel

println

public final void println(int x)

Makes sure that println can display an int.

Specified by:

println in interface IOModel

println

public final void println(long x)

Makes sure that println can display a long.

Specified by:

println in interface IOModel

println

public final void println(Object x)

Makes sure that println can display an Object.

Specified by:

println in interface IOModel

println

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.

Specified by:

println in interface IOModel

Parameters:

value - The value to be displayed

readBoolean

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.

Specified by:

readBoolean in interface IOModel

Returns:

The value of the input interpreted as a boolean value

readBoolean

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.

Specified by:

readBoolean in interface IOModel

Parameters:

prompt - The prompt string to display to the user

Returns:

The value of the input interpreted as a boolean value

readBoolean

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.

Specified by:

readBoolean in interface IOModel

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

readDouble

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.

Specified by:

readDouble in interface IOModel

Returns:

The value of the input interpreted as a double

readDouble

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.

Specified by:

readDouble in interface IOModel

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

readDouble

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.

Specified by:

readDouble in interface IOModel

Parameters:

prompt - The prompt string to display to the user

Returns:

The value of the input interpreted as a double

readDouble

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.

Specified by:

readDouble in interface IOModel

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

readInt

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.

Specified by:

readInt in interface IOModel

Returns:

The value of the input interpreted as a decimal integer

readInt

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.

Specified by:

readInt in interface IOModel

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

readInt

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.

Specified by:

readInt in interface IOModel

Parameters:

prompt - The prompt string to display to the user

Returns:

The value of the input interpreted as a decimal integer

readInt

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.

Specified by:

readInt in interface IOModel

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

readLine

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.

Specified by:

readLine in interface IOModel

Returns:

The next line of input as a String

readLine

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.

Specified by:

readLine in interface IOModel

Parameters:

prompt - The prompt string to display to the user

Returns:

The next line of input as a String

setAllowCancel

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.

Parameters:

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

setAssociatedConsole

public void setAssociatedConsole(IOConsole console)

Establishes an associated console for the dialog. If the associated console is non-null and the console is reading from an input stream, then the dialog methods use the console for input instead of the dialog.

Parameters:

console - The associated console

setExceptionOnError

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.

Parameters:

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

showErrorMessage

public void showErrorMessage(String msg)

Displays the error message in an error dialog.

Specified by:

showErrorMessage in interface IOModel

Parameters:

msg - The error msg to be displayed