edu.neu.ccs.console
Class ConsoleGateway

java.lang.Object
  edu.neu.ccs.console.ConsoleGateway

All Implemented Interfaces:

ConsoleInputListener, EventListener, JPTConstants, Serializable, SwingConstants

public class ConsoleGateway

extends Object

implements ConsoleInputListener, JPTConstants, Serializable

Provides methods for using a console object to perform text input and output operations. An instance of this class uses the standard system streams, System.in, System.out, and System.err by default, but can be "activated". An "activated" console is a separate floating window that displays text output and gathers text input using functionality not provided by the system streams. As some Java Virtual Machines restrict access to the system streams through use of a security manager, an instance of this class may be the only way to provide a text console for an applet or application.

It is not safe to call methods of this class on the event handling thread, regardless of whether or not the console is activated. In addition to length calculations, all modal input operations, such as the ones provided by this class, should be performed on the main thread or a user thread and never the event-handling thread.

The functionality of this class is based on the principles of the C++ tools provided in "IOTools" by Richard Rasala of the Northeastern University College of Computer Science.

In 2.6.0, changed setActivated to pass this ConsoleGateway to the constructor of ConsoleWindow. This was necessitated by a bug fix to ConsoleWindow.

Version:

2.6.0

See Also:

Serialized Form

Nested Class Summary

class	ConsoleGateway.ConsoleInputStream Inner class of ConsoleGateway that provides input functionality for a console object.
class	ConsoleGateway.ConsoleOutputStream Inner class of ConsoleGateway, and derived class of OutputStream that provides output functionality for a console object.

Field Summary

protected CaseActionFilter	action Case action filter used by this console object.
static String	ACTIVATED Bound property name for the activated property.
protected SwingPropertyChangeSupport	changeAdapter Helper object for property change API.
protected String	endl The end-of-line sequence for the operating system on which the Java Virtual Machine is running.
PrintStream	err The virtual stream object providing error text output functionality.
private static int	ERR Constant index for the error stream.
static String	ERROR_COLOR Bound property name for the error color property.
ConsoleGateway.ConsoleInputStream	in The virtual stream object providing text input functionality.
private static int	IN Constant index for the input stream.
protected String	input Input text last gathered by this console object.
static String	INPUT_COLOR Bound property name for the input color property.
protected InputStream	inStream The input stream used by this console object as the default "in" stream.
PrintStream	out The virtual stream object providing text output functionality.
private static int	OUT Constant index for the output stream.
static String	OUTPUT_COLOR Bound property name for the output color property.
protected OutputStream[]	outStreams The output streams used by this console object as the default "out" and "err" streams.
protected ConsoleWindow	window The console window to use for visualization of this console object.

Fields inherited from interface edu.neu.ccs.util.JPTConstants

ABOVE, ALIGNMENT, BELOW, BOTTOM_LEFT, BOTTOM_RIGHT, DEFAULT, FONT, INPUT_PROPERTIES, MANDATORY, OPTIONAL, ORIENTATION, TOP_LEFT, TOP_RIGHT, VALUE

Fields inherited from interface javax.swing.SwingConstants

BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST

Constructor Summary

ConsoleGateway()
Constructs a console object using the system streams by default for input and output operations.

Method Summary

void	addPropertyChangeListener(PropertyChangeListener listener) Registers the given object to listen for property change events generated by this console.
void	addPropertyChangeListener(String propertyName, PropertyChangeListener listener) Registers the given object to listen for property change events generated by this console with the provided property name.
boolean	confirm(String prompt, boolean response) Prints the given prompt to the text output stream and pauses the current running thread until the user inputs "Y[es]" or "N[o]".
void	consoleInputPerformed(String text) Handles input gathered from an "activated" console window.
protected void	flush(int stream) Flushes the given output stream.
CaseActionFilter	getCaseActionFilter() Returns the current case action filter used by this console object, or null, if no case action filter is used by this console object.
Color	getErrorColor() Returns the color used to render error text.
String	getFontFamilyName() Returns the font family name of the console font if the console is activated; otherwise returns "".
int	getFontSize() Returns the actual font size if the console is activated; otherwise returns 0.
Color	getInputColor() Returns the color used to render input text.
protected String	getLineSeparator() Returns the line separator sequence used by the machine running the Java Virtual Machine.
static int	getMaximumFontSize() Get the maximum font size that may be set for the console window.
static int	getMinimumFontSize() Get the minimum font size that may be set for the console window.
static String	getMonospacedFontFamilyName() Returns the default monospaced font family name of the font that will be used in the ConsoleTextPane on this system.
protected String	getOneLine() Reads a String terminated by a line separator sequence from this console object and filters it based on the current case action filter.
Color	getOutputColor() Returns the color used to render output text.
void	iconify() If the console is activated then set the console window to its iconified state.
boolean	isActivated() Returns whether or not the console has been "activated".
void	maximize() If the console is activated then set the console window to its maximized state.
void	normal() If the console is activated then set the console window to its normal state.
void	pressReturn() Prints a default prompt to the text output stream for the user to press the Return key, and pauses the current thread until the user presses the key.
void	pressReturn(String prompt) Prints the given prompt to the text output stream and pauses the current thread until the user presses the key.
void	prompt(String text) Prints a prompt to the text output stream that is followed by a single space, but no line separator sequence.
void	prompt(String text, String response) Prints a prompt to the text output stream that is followed by a single space and a default text response in square brackets, but no line separator sequence.
void	removePropertyChangeListener(PropertyChangeListener listener) Deregisters the given object from listening for property change events generated by this console.
void	removePropertyChangeListener(String propertyName, PropertyChangeListener listener) Deregisters the given object from listening for property change events generated by this console with the provided property name.
void	selectBlackTextScheme() Sets the color for each of the three console text streams to black.
void	selectColorTextScheme() Sets the color for each of the three console text streams as follows: Output: black Input: blue Error: red
void	setActivated(boolean isActivated) Sets whether or not this console object is "activated".
void	setCaseActionFilter(CaseActionFilter filter) Sets the current case action filter for this console object to the given case action filter.
void	setErrorColor(Color error) Sets the color used to render error text to the given color.
void	setFontSize(int size) Sets the font size for the console to the given size.
void	setInputColor(Color input) Sets the color used to render input text to the given color.
void	setOutputColor(Color output) Sets the color used to render output text to the given color.
void	toggle() If the console is activated then if the current state of the console is not normal, then make it normal otherwise iconify the console.
protected void	write(String text, int stream) Writes the provided text to the given stream.

Methods inherited from class java.lang.Object

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

Field Detail

OUT

private static final int OUT

Constant index for the output stream.

See Also:

Constant Field Values

ERR

private static final int ERR

Constant index for the error stream.

See Also:

Constant Field Values

IN

private static final int IN

Constant index for the input stream.

See Also:

Constant Field Values

ACTIVATED

public static final String ACTIVATED

Bound property name for the activated property.

See Also:

Constant Field Values

INPUT_COLOR

public static final String INPUT_COLOR

Bound property name for the input color property.

See Also:

Constant Field Values

OUTPUT_COLOR

public static final String OUTPUT_COLOR

Bound property name for the output color property.

See Also:

Constant Field Values

ERROR_COLOR

public static final String ERROR_COLOR

Bound property name for the error color property.

See Also:

Constant Field Values

changeAdapter

protected SwingPropertyChangeSupport changeAdapter

Helper object for property change API.

action

protected CaseActionFilter action

Case action filter used by this console object.

input

protected String input

Input text last gathered by this console object.

inStream

protected transient InputStream inStream

The input stream used by this console object as the default "in" stream.

outStreams

protected transient OutputStream[] outStreams

The output streams used by this console object as the default "out" and "err" streams.

endl

protected transient String endl

The end-of-line sequence for the operating system on which the Java Virtual Machine is running.

window

protected ConsoleWindow window

The console window to use for visualization of this console object. If null, input and output operations are performed using the default stream objects.

in

public ConsoleGateway.ConsoleInputStream in

The virtual stream object providing text input functionality.

out

public PrintStream out

The virtual stream object providing text output functionality.

err

public PrintStream err

The virtual stream object providing error text output functionality.

Constructor Detail

ConsoleGateway

public ConsoleGateway()

Constructs a console object using the system streams by default for input and output operations. It is not necessary to directly call this constructor, unless interested in creating a console object for specific individual use. For access to the shared console object, implement the ConsoleAware interface and use the console object reference that interface makes accessible.

See Also:

ConsoleAware

Method Detail

consoleInputPerformed

public void consoleInputPerformed(String text)

Handles input gathered from an "activated" console window.

Specified by:

consoleInputPerformed in interface ConsoleInputListener

Parameters:

text - the input text gathered from the stream

prompt

public void prompt(String text)

Prints a prompt to the text output stream that is followed by a single space, but no line separator sequence. If the prompt text is null or is the empty String, this method does nothing.

Parameters:

text - the prompt String to display

See Also:

prompt(String, String)

prompt

public void prompt(String text,
                   String response)

Prints a prompt to the text output stream that is followed by a single space and a default text response in square brackets, but no line separator sequence. If the prompt text is null or is the empty String, the prompt portion will be omitted from the output. If the default response is null or is the empty String the response portion will be omitted from the output.

Parameters:

text - the prompt String to display

response - the default response text

See Also:

prompt(String)

pressReturn

public void pressReturn()

Prints a default prompt to the text output stream for the user to press the Return key, and pauses the current thread until the user presses the key.

See Also:

pressReturn(String)

pressReturn

public void pressReturn(String prompt)

Prints the given prompt to the text output stream and pauses the current thread until the user presses the key.

Parameters:

prompt - the prompt String to display

See Also:

pressReturn()

confirm

public boolean confirm(String prompt,
                       boolean response)

Prints the given prompt to the text output stream and pauses the current running thread until the user inputs "Y[es]" or "N[o]".

Parameters:

prompt - the prompt String to display

response - the default response to the confirmation: true for "Y[es]" or false for "N[o]

Returns:

true if the user input "Y[es]" or false if the user input "N[o]"

setCaseActionFilter

public void setCaseActionFilter(CaseActionFilter filter)

Sets the current case action filter for this console object to the given case action filter. If null, no case action filter will be used by this console object.

Parameters:

filter - the desired case action filter

See Also:

getCaseActionFilter()

getCaseActionFilter

public CaseActionFilter getCaseActionFilter()

Returns the current case action filter used by this console object, or null, if no case action filter is used by this console object.

See Also:

setCaseActionFilter(CaseActionFilter)

setActivated

public void setActivated(boolean isActivated)

Sets whether or not this console object is "activated". An "activated" console is a separate floating window that displays text output and gathers text input using functionality not provided by the system streams.

Parameters:

isActivated - whether or not this console object is "activated"

See Also:

isActivated()

isActivated

public boolean isActivated()

Returns whether or not the console has been "activated". An "activated" console is a separate floating window that displays text output and gathers text input using functionality not provided by the system streams.

See Also:

setActivated(boolean)

normal

public void normal()

If the console is activated then set the console window to its normal state.

iconify

public void iconify()

If the console is activated then set the console window to its iconified state.

maximize

public void maximize()

If the console is activated then set the console window to its maximized state.

toggle

public void toggle()

If the console is activated then if the current state of the console is not normal, then make it normal otherwise iconify the console.

setInputColor

public void setInputColor(Color input)

Sets the color used to render input text to the given color. This operation only affects an "activated" console.

Parameters:

input - the desired input color

See Also:

getInputColor()

getInputColor

public Color getInputColor()

Returns the color used to render input text. This color only affects an "activated" console.

See Also:

setInputColor(Color)

setOutputColor

public void setOutputColor(Color output)

Sets the color used to render output text to the given color. This operation only affects an "activated" console.

Parameters:

output - the desired output color

See Also:

getOutputColor()

getOutputColor

public Color getOutputColor()

Returns the color used to render output text. This color only affects an "activated" console.

See Also:

setOutputColor(Color)

setErrorColor

public void setErrorColor(Color error)

Sets the color used to render error text to the given color. This operation only affects an "activated" console.

Parameters:

error - the desired error color

See Also:

getErrorColor()

getErrorColor

public Color getErrorColor()

Returns the color used to render error text. This color only affects an "activated" console.

See Also:

setErrorColor(Color)

selectBlackTextScheme

public void selectBlackTextScheme()

Sets the color for each of the three console text streams to black.

See Also:

selectColorTextScheme(), setOutputColor(Color), setInputColor(Color), setErrorColor(Color)

selectColorTextScheme

public void selectColorTextScheme()

Sets the color for each of the three console text streams as follows:

• Output: black
• Input: blue
• Error: red

See Also:

selectBlackTextScheme(), setOutputColor(Color), setInputColor(Color), setErrorColor(Color)

getMonospacedFontFamilyName

public static String getMonospacedFontFamilyName()

Returns the default monospaced font family name of the font that will be used in the ConsoleTextPane on this system.

This method, added in 2.3.3, returns the font family name even if the console is not activated.

Returns the same font family name as the method of the same name in Fonts.

The order of the names tested as of 2.5.0 is:

• Lucida Console
• Lucida Sans Typewriter
• Andale Mono
• Courier New
• Consolas
• Monospaced
• monospaced

The first font name that is found is returned.

getFontFamilyName

public final String getFontFamilyName()

Returns the font family name of the console font if the console is activated; otherwise returns "".

This method is retained for backward compatibility.

getFontSize

public final int getFontSize()

Returns the actual font size if the console is activated; otherwise returns 0.

getMinimumFontSize

public static final int getMinimumFontSize()

Get the minimum font size that may be set for the console window.

getMaximumFontSize

public static final int getMaximumFontSize()

Get the maximum font size that may be set for the console window.

setFontSize

public final void setFontSize(int size)

Sets the font size for the console to the given size.

Point sizes smaller than 10 are set to 10 points.

Point sizes larger than 72 are set to 72 points.

Keep in mind that very large font sizes will lead to very few characters per line in the console window.

Does nothing if the console is not activated.

Parameters:

size - the desired font size

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Registers the given object to listen for property change events generated by this console.

Parameters:

listener - the listener to be registered

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                                      PropertyChangeListener listener)

Registers the given object to listen for property change events generated by this console with the provided property name.

Parameters:

propertyName - the name of the desired property

listener - the listener to be registered

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Deregisters the given object from listening for property change events generated by this console.

Parameters:

listener - the listener to be deregistered

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                         PropertyChangeListener listener)

Deregisters the given object from listening for property change events generated by this console with the provided property name.

Parameters:

propertyName - the name of the desired property

listener - the listener to be deregistered

getOneLine

protected String getOneLine()

Reads a String terminated by a line separator sequence from this console object and filters it based on the current case action filter. The line separator sequence is not included in the returned String.

getLineSeparator

protected String getLineSeparator()

Returns the line separator sequence used by the machine running the Java Virtual Machine.

flush

protected void flush(int stream)
              throws IOException

Flushes the given output stream.

Parameters:

stream - the output stream to flush

Throws:

IOException

Since:

1.0

write

protected void write(String text,
                     int stream)

Writes the provided text to the given stream.

Parameters:

text - the text to be written

stream - the output stream to write the data