acm.program
Class Program

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--java.awt.Panel
                    |
                    +--java.applet.Applet
                          |
                          +--javax.swing.JApplet
                                |
                                +--acm.program.Program

Direct Known Subclasses:

ConsoleProgram, DialogProgram, GraphicsProgram

public abstract class Program

extends JApplet

implements IOModel, Runnable, MouseListener, MouseMotionListener, ActionListener

This class is the superclass for all executable programs in the acm.program package. Its principal role is to unify the concepts of applets and applications in a single class, although it also provides applications with many other useful facilities not traditionally available in applications.

In many programming environments, objects that are specific instances of a Program subclass will run automatically without any special action on your part. For maximum portability, you might want to define a static main method as described in the comments for the standard implementation of main.

Field Summary

String	CENTER Constant specifying the center of the container
String	EAST Constant specifying the east edge of the container
String	NORTH Constant specifying the north edge of the container
String	SOUTH Constant specifying the south edge of the container
String	WEST Constant specifying the west edge of the container

Method Summary

void	actionPerformed(ActionEvent e) Called when a component (typically a button) is activated.
void	addActionListeners() Adds the program as an ActionListener to every button in the structure that does not have a listener already.
void	addActionListeners(ActionListener listener) Adds the specified listener to every button in the structure that does not have a listener already.
void	addExitHook(Object obj) Requests that the program call the exit method in the specified object before exiting.
void	exit() Exits from the program.
IOConsole	getConsole() Returns the console associated with this program.
IODialog	getDialog() Returns the dialog used for user interaction.
IOModel	getInputModel() Returns the IOModel used for program input, which will typically be either the default IOConsole or IODialog object.
ProgramMenuBar	getMenuBar() Returns the menu bar associated with this program.
IOModel	getOutputModel() Returns the IOModel used for program output, which will typically be either the default IOConsole or IODialog object.
BufferedReader	getReader() Returns a BufferedReader whose input comes from the console.
String	getTitle() Gets the title of this program.
PrintWriter	getWriter() Returns a PrintWriter whose output is directed to the console.
void	init() The init method is called at startup time before the run method is called.
void	main(String[] args) Every application must either contain a "Main-Class" entry in its manifest file or include a main method that looks like this, where MyClass is the name of the program class:
void	menuAction(String cmd) Called whenever an action event is detected in the menu bar.
void	mouseClicked(MouseEvent e) Called when the mouse is clicked.
void	mouseDragged(MouseEvent e) Called when the mouse is dragged with the button down.
void	mouseEntered(MouseEvent e) Called when the mouse enters the source (which may be either a component or a GObject).
void	mouseExited(MouseEvent e) Called when the mouse exits the source (which may be either a component or a GObject).
void	mouseMoved(MouseEvent e) Called when the mouse is moved.
void	mousePressed(MouseEvent e) Called when the mouse button is pressed.
void	mouseReleased(MouseEvent e) Called when the mouse button is released.
void	pause(double milliseconds) Delays the calling thread for the specified time, which is expressed in milliseconds.
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 (true or false).
boolean	readBoolean(String prompt) Prompts the user to enter a boolean value, which is returned as the value of this method.
boolean	readBoolean(String prompt, String trueLabel, String falseLabel) Prompts the user to enter a boolean value, which is matched against the labels provided.
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.
String	readLine(String prompt) Prompts the user for a line of input.
void	run() Contains the code to be executed for each specific program subclass.
void	setConsole(IOConsole console) Sets the console associated with this program.
void	setTitle(String title) Sets the title of this program.
void	showErrorMessage(String msg) Displays the error message in the standard output model.
void	start(String[] args) Starts the program using the specified argument list.

Field Detail

public static final String CENTER

Constant specifying the center of the container

public static final String EAST

Constant specifying the east edge of the container

public static final String NORTH

Constant specifying the north edge of the container

public static final String SOUTH

Constant specifying the south edge of the container

public static final String WEST

Constant specifying the west edge of the container

Method Detail

public void actionPerformed(ActionEvent e)

Called when a component (typically a button) is activated.

Specified by:

actionPerformed in interface ActionListener

public void addActionListeners()

Adds the program as an ActionListener to every button in the structure that does not have a listener already.

Usage:

addActionListeners();

public void addActionListeners(ActionListener listener)

Adds the specified listener to every button in the structure that does not have a listener already.

Usage:

addActionListeners(listener);

Parameter:

listener

The ActionListener to be added

public void addExitHook(Object obj)

Requests that the program call the exit method in the specified object before exiting.

Usage:

program.addExitHook(obj);

public void exit()

Exits from the program. Subclasses should override this method if they need to perform any actions before shutting down the program, such as asking the user to save any unsaved files. Any clients that do override this method should call super.exit() at the end of their processing.

Usage:

program.exit();

public IOConsole getConsole()

Returns the console associated with this program.

Usage:	IOConsole console = program.getConsole();
Returns:	The IOConsole object used for this program

public IODialog getDialog()

Returns the dialog used for user interaction.

Usage:	IODialog dialog = program.getDialog();
Returns:	The IODialog object used for this program

public IOModel getInputModel()

Returns the IOModel used for program input, which will typically be either the default IOConsole or IODialog object.

Usage:	IOModel io = program.getInputModel();
Returns:	The IOModel used for program input

public ProgramMenuBar getMenuBar()

Returns the menu bar associated with this program. Note that this menu bar cannot be set by clients, although it can be changed initially by overriding the createMenuBar factory method.

Usage:	ProgramMenuBar mbar = getMenuBar();
Returns:	The menu bar in use for this program

public IOModel getOutputModel()

Returns the IOModel used for program output, which will typically be either the default IOConsole or IODialog object.

Usage:	IOModel io = program.getOutputModel();
Returns:	The IOModel used for program output

public BufferedReader getReader()

Returns a BufferedReader whose input comes from the console.

Usage:	BufferedReader rd = getReader();
Returns:	A Reader for use with this console

public String getTitle()

Gets the title of this program.

Usage:	String title = getTitle();
Returns:	The title in use for this program

public PrintWriter getWriter()

Returns a PrintWriter whose output is directed to the console.

Usage:	PrintWriter wr = getWriter();
Returns:	A PrintWriter for use with this console

public void init()

The init method is called at startup time before the run method is called. Subclasses can override this method to perform any initialization code that would ordinarily be included in an applet init method. This method is used only for certain styles of application development that have their roots in the applet world; other styles will not ordinarily use or override this method.

Usage:

program.init();

public static void main(String[] args)

Every application must either contain a "Main-Class" entry in its manifest file or include a main method that looks like this, where MyClass is the name of the program class:

public static void main(String[] args)
{
new MyClass().start();
}

If the program needs the command line arguments, the args array can be passed to the start method and then retrieved using the getArgumentArray method.

Parameter:

args	An array of string arguments

public void menuAction(String cmd)

Called whenever an action event is detected in the menu bar. Most of these actions are simply passed on to the appropriate console.

public void mouseClicked(MouseEvent e)

Called when the mouse is clicked. A call to mouseClicked is always preceded by both a mousePressed and a mouseReleased event for the same source.

Specified by:

mouseClicked in interface MouseListener

public void mouseDragged(MouseEvent e)

Called when the mouse is dragged with the button down. Java makes several guarantees about dragging. First, a mouseDragged call is always preceded by a mousePressed call for the same source. If the mouse is pressed elsewhere and then enters a source with the button down, no drag event occurs. Moreover, once the mouse button goes down in a particular source, only that source will receive mouse events until the button goes up. Those events, moreover, are reported even in the mouse travels outside the domain of the object.

Specified by:

mouseDragged in interface MouseMotionListener

public void mouseEntered(MouseEvent e)

Called when the mouse enters the source (which may be either a component or a GObject).

Specified by:

mouseEntered in interface MouseListener

public void mouseExited(MouseEvent e)

Called when the mouse exits the source (which may be either a component or a GObject).

Specified by:

mouseExited in interface MouseListener

public void mouseMoved(MouseEvent e)

Called when the mouse is moved.

Specified by:

mouseMoved in interface MouseMotionListener

public void mousePressed(MouseEvent e)

Called when the mouse button is pressed.

Specified by:

mousePressed in interface MouseListener

public void mouseReleased(MouseEvent e)

Called when the mouse button is released.

Specified by:

mouseReleased in interface MouseListener

public void pause(double milliseconds)

Delays the calling thread for the specified time, which is expressed in milliseconds. Unlike Thread.sleep, this method never throws an exception.

Usage:

program.pause(milliseconds);

Parameter:

milliseconds

The sleep time in milliseconds

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:

program.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:	program.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:

program.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 (true or false). The input must match one of these strings, 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 = program.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 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 = program.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 boolean value, which is matched against the labels provided. If the user enters 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 = program.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 = program.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 = program.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 = program.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 = program.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 = program.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 = program.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 = program.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. The end-of-line characters that terminate the input are not included in the returned string.

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

public String readLine(String prompt)

Prompts the user for a line of input. The end-of-line characters that terminate the input are not included in the returned string.

Usage:

String str = program.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 run()

Contains the code to be executed for each specific program subclass. If you are defining your own program, you need to override the definition of run so that it contains the code for your application.

Specified by:

run in interface Runnable

public void setConsole(IOConsole console)

Sets the console associated with this program.

Usage:

program.setConsole(console);

Parameter:

console

The IOConsole object used for this program

public void setTitle(String title)

Sets the title of this program. The title appears in the title bar when the program is running as an application.

Usage:

setTitle(title);

Parameter:

title

The title for this program

public void showErrorMessage(String msg)

Displays the error message in the standard output model.

Usage:

showErrorMessage(msg);

Parameter:

msg	The error msg to be displayed

Specified by:

showErrorMessage in interface IOModel

public void start(String[] args)

Starts the program using the specified argument list.

Usage:

program.start(args);

Parameter:

args	An array of strings passed to the program