acm.io
Class IODialog

java.lang.Object
  extended by 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 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
 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