edu.neu.ccs.console
Class ConsoleGateway

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