acm.io
Class IOConsole

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--acm.io.IOConsole

public class IOConsole extends Container implements IOModel

The IOConsole class makes it easier to interact with the user using text-based input and output in the style of a traditional console. Given a IOConsole object, you can write output to that console using the print and println methods, just as you would for the standard output stream. To request input from the user, the most common methods are

A IOConsole object is a lightweight component and must be added to an installed Frame or JFrame before it becomes visible on the screen. The usual strategy for including a console in a frame is to use the ConsoleProgram mechanism in the acm.program package. The operation of the IOConsole class is illustrated by the following test method, which generates the session shown on the right. The user input appears in blue, just as it does in the console window.

 

 public void test(IOConsole console) {
    console.println("IOConsole class test");
    int n = console.readInt("Enter an integer: ");
    console.println("That integer was " + n);
    double d = console.readDouble("Enter a real number: ");
    console.println("That number was " + d);
    boolean b = console.readBoolean("Enter a boolean value: ");
    console.println("That value was " + b);
    String line = console.readLine("Enter a line: ");
    console.println("That line was \"" + line + "\"");
 }
 


Field Summary
IOConsole SYSTEM_CONSOLE
This constant is an object that offers the functionality of the IOConsole class, but which does so using the standard I/O streams System.in and System.out.
 
Constructor Summary
IOConsole()
Creates a new IOConsole object.
 
Method Summary
void clear()
Clears the console display.
boolean getExceptionOnError()
Returns the state of the error-handling flag.
BufferedReader getInputScript()
Retrieves the input script.
BufferedReader getReader()
Returns a BufferedReader object that can be used to read from the console.
PrintWriter getWriter()
Returns a PrintWriter object that can be used to send output to the console.
void print(String value)
Displays the argument value on the console, leaving the cursor at the end of the output.
void println()
Advances the console cursor to the beginning of the next line.
void println(String value)
Displays the argument value on the console and then advances the cursor to the beginning of the next line.
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 console, without including the end-of-line characters that terminate the input.
String readLine(String prompt)
Prompts the user to enter a line of text, which is then returned as the value of this method.
void setBackground(Color color)
Sets the background color used for the console.
void setExceptionOnError(boolean flag)
Sets the error-handling mode of the console as specified by the flag parameter.
void setFont(Font font)
Sets the font for the console.
void setFont(String str)
Sets the font used for the console as specified by the string str, which is interpreted in the style of Font.decode.
void setForeground(Color color)
Sets the foreground color used for the output text.
void showErrorMessage(String msg)
Displays the error message on the console.
 

Field Detail

public static final IOConsole SYSTEM_CONSOLE

This constant is an object that offers the functionality of the IOConsole class, but which does so using the standard I/O streams System.in and System.out.
Constructor Detail

public IOConsole()

Creates a new IOConsole object.

 
Usage: IOConsole console = new IOConsole(); 
 
Method Detail

public void clear()

Clears the console display.

 
Usage: console.clear(); 
 

public boolean getExceptionOnError()

Returns the state of the error-handling flag.

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

public BufferedReader getInputScript()

Retrieves the input script. After the end of the input script has been reached, this method will return null.

 
Usage: BufferedReader rd = console.getInputScript(); 
Returns: The reader representing the current input script
 

public BufferedReader getReader()

Returns a BufferedReader object that can be used to read from the console.

 
Usage: BufferedReader rd = console.getReader(); 
Returns: A BufferedReader that reads from this console
 

public PrintWriter getWriter()

Returns a PrintWriter object that can be used to send output to the console.

 
Usage: PrintWriter wr = console.getWriter(); 
Returns: A PrintWriter that writes to this console
 

public void print(String value)

Displays the argument value on the console, leaving the cursor at the end of the output. The print method is overloaded so that value can be of any type.

 
Usage: console.print(value); 
Parameter: 
value  The value to be displayed
Specified by: print in interface IOModel
 

public void println()

Advances the console cursor to the beginning of the next line.

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

public void println(String value)

Displays the argument value on the console and then advances the cursor to the beginning of the next line. The println method is overloaded so that value can be of any type.

 
Usage: console.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 = console.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 = console.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 = console.readBoolean(prompt); 
Parameters: 
prompt  The prompt string to display to the user
trueLabel  The string used to indicate true
falseLabel  The string used to indicate 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 = console.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 = console.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 = console.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 = console.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 = console.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 = console.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 = console.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 = console.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 console, without including the end-of-line characters that terminate the input.

 
Usage: String str = console.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 line of text, 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 = console.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 setBackground(Color color)

Sets the background color used for the console.

 
Usage: console.setBackground(color); 
Parameter: 
color  The new background color
 

public void setExceptionOnError(boolean flag)

Sets the error-handling mode of the console 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: console.setExceptionOnError(flag); 
Parameter: 
flag  false to retry on errors; true to raise an exception
 

public void setFont(Font font)

Sets the font for the console.

 
Usage: console.setFont(font); 
Parameter: 
font  The font to use for the console
 

public void setFont(String str)

Sets the font used for the console as specified by the string str, which is interpreted in the style of Font.decode. The usual format of the font string is

   familycode>-stylecode>-size where both style and size are optional. If any of these parts are specified as an asterisk, the existing value is retained.


 
Usage: console.setFont(str); 
Parameter: 
str  A String specifying the new font
 

public void setForeground(Color color)

Sets the foreground color used for the output text.

 
Usage: console.setForeground(color); 
Parameter: 
color  The color to use for the output text
 

public void showErrorMessage(String msg)

Displays the error message on the console.

 
Usage: console.showErrorMessage(msg); 
Parameter: 
msg  The error msg to be displayed
Specified by: showErrorMessage in interface IOModel