PIRL.Viewers
Class Stream_Monitor

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JPanel
                  PIRL.Viewers.Stream_Monitor

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable, Accessible, Styled_Writer

public class Stream_Monitor
extends JPanel
implements Styled_Writer

A Stream_Monitor provides a scrolling display of styled text written to it.

Text may be provided directly to the monitor; in this case it acts like the JTextPane it employs. Or text may be written to the stream the monitor offers. Adding text to the monitor is thread safe. Text is added to the bottom of the current content. The capacity of the monitor - the amount of text that will be retained - may be controlled. When the capacity has been reached text is removed from the top of the current content in whole line increments. The text content may be edited by the user, saved to a disk file, or cleared.

The monitor JTextPane is contained within a JScrollPane initialized with the default scroll bar policies. The vertical scroll bar is actively managed such that when the thumb is located at the bottom of the scroll bar it will stay there, and text added to the monitor will scroll up keeping the end of the last text added visible. However, if the thumb is moved to any other location the thumb will remain there and the visible text will not move unless it must scroll up when the capacity is reached and excess text is removed from the top.

Text written to the monitor may be auto-styled with a table of text-to-style associations. The text-to-style associations may be managed as desired.

File and View menus configured for text file saving, capacity control and content clearing are provided for use in an application menu bar. These menus may be modified to suit the needs of the application.

Version:

1.17

Author:

Bradford Castalia - UA/PIRL

See Also:

Serialized Form

Nested Class Summary

class	Stream_Monitor.Monitor_OutputStream
class	Stream_Monitor.Monitor_Writer

Nested classes/interfaces inherited from class javax.swing.JPanel

JPanel.AccessibleJPanel

Nested classes/interfaces inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

static SimpleAttributeSet	HIGHLIGHT_STYLE A highlighted text style.
static String	ID Class name and identification.
static SimpleAttributeSet	MARKER_STYLE A marker text style.
static int	MIN_CAPACITY The lower limit on the capacity value.
static SimpleAttributeSet	NOTICE_STYLE A text style that will be noticed.
static SimpleAttributeSet	stderr_STYLE Text style attributes suitable for "stderr" auto-styling.
static SimpleAttributeSet	stdout_STYLE Text style attributes suitable for "stdout" auto-styling.
static int	Stream_Buffer_Capacity

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Stream_Monitor()
Construct a Stream_Monitor.

Method Summary

Hashtable	Auto_Style_Table() Get the text-to-style association table.
boolean	Auto_Style() Test if auto-styling mode is enabled
Stream_Monitor	Auto_Style(boolean enable) Enable or disable auto-styling.
AttributeSet	Auto_Style(String text) Get the style associated with a text prefix.
Stream_Monitor	Auto_Style(String text, AttributeSet style) Add an auto-style text-to-style association.
int	Capacity() Get the maximum number of characters to be retained for scrolling.
Stream_Monitor	Capacity(int capacity) Set the maximum number of characters to be retained for scrolling.
Stream_Monitor	Clear() Clear the monitor of all text.
static int	Default_Capacity() Get the default character capacity.
static void	Default_Capacity(int capacity) Set the default character capacity.
JMenu	File_Menu() Get the monitor's "File" menu.
void	Save_Monitor_Text() Save the current monitor text to a file.
void	Save_Monitor_Text(boolean interactive) Save the current monitor text to a file.
void	Save_Monitor_Text(String pathname) Save the current monitor text to a file.
JScrollPane	Scroll_Pane() Get the JScrollPane that contains the JTextPane where the monitor text is displayed.
Stream_Monitor.Monitor_OutputStream	Stream() Get an OutputStream for writing to the monitor display.
int	Used() Get the number of characters in the monitor.
JMenu	View_Menu() Get the monitor's "View" menu.
Stream_Monitor	Write(String text) Write text to the monitor.
Stream_Monitor	Write(String text, AttributeSet style) Write styled text to the monitor.
Stream_Monitor.Monitor_Writer	Writer() Get a Writer for writing to the monitor display.

Methods inherited from class javax.swing.JPanel

getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Field Detail

ID

public static final String ID

Class name and identification.

See Also:

Constant Field Values

stdout_STYLE

public static final SimpleAttributeSet stdout_STYLE

Text style attributes suitable for "stdout" auto-styling.

The style is a bold Monospaced font.

stderr_STYLE

public static final SimpleAttributeSet stderr_STYLE

Text style attributes suitable for "stderr" auto-styling.

The style is a bold Monospaced font with a yellow background.

NOTICE_STYLE

public static final SimpleAttributeSet NOTICE_STYLE

A text style that will be noticed.

The style is bold red text.

HIGHLIGHT_STYLE

public static final SimpleAttributeSet HIGHLIGHT_STYLE

A highlighted text style.

The style is blue text.

MARKER_STYLE

public static final SimpleAttributeSet MARKER_STYLE

A marker text style.

The style is a bold Monospaced font.

MIN_CAPACITY

public static final int MIN_CAPACITY

The lower limit on the capacity value.

See Also:

Constant Field Values

Stream_Buffer_Capacity

public static final int Stream_Buffer_Capacity

See Also:

Constant Field Values

Constructor Detail

Stream_Monitor

public Stream_Monitor()

Construct a Stream_Monitor.

Method Detail

Stream

public Stream_Monitor.Monitor_OutputStream Stream()

Get an OutputStream for writing to the monitor display.

The stream is line-oriented: Each byte written is buffered until an end-of-line sequence, or a maximum of is encountered at which point the buffer is written to the monitor display. An end-of-line line sequence is any one of a line feed ('\n', 0x0A), a carriage return ('\r', 0x0D), or a carriage return followed immediately by a linefeed.

N.B.: Because both the OutputStream returned by this method and the Writer() are buffered output to the same monitor display it is recommended that only one be used with any Stream_Monitor object; otherwise unpredictable interleaved text may be displayed.

Returns:

An OutputStream that can be used to write text to the monitor display.

Writer

public Stream_Monitor.Monitor_Writer Writer()

Get a Writer for writing to the monitor display.

The stream is line-oriented: Each character written is buffered until an end-of-line sequence is encountered at which point the buffer is written to the monitor display. An end-of-line line sequence is any one of a line feed ('\n', 0x0A), a carriage return ('\r', 0x0D), or a carriage return followed immediately by a linefeed.

N.B.: Because both the Writer returned by this method and the Stream() are buffered output to the same monitor display it is recommended that only one be used with any Stream_Monitor object; otherwise unpredictable interleaved text may be displayed.

Returns:

A Stream_Monitor.Monitor_Writer that can be used to write text to the monitor display.

Capacity

public Stream_Monitor Capacity(int capacity)

Set the maximum number of characters to be retained for scrolling.

Parameters:

capacity - The maximum number of characters to be retained. This value will be limited to not less than MIN_CAPACITY.

Capacity

public int Capacity()

Get the maximum number of characters to be retained for scrolling.

Returns:

The maximum number of characters to be retained.

See Also:

Capacity(int)

Default_Capacity

public static void Default_Capacity(int capacity)

Set the default character capacity.

When a new Stream_Monitor is constructed its initial capacity will be set to the default capacity.

Parameters:

capacity - The initial capacity for a new Stream_Monitor. This value will be limited to not less than MIN_CAPACITY.

Default_Capacity

public static int Default_Capacity()

Get the default character capacity.

Returns:

The initial capacity for a new Stream_Monitor.

See Also:

Default_Capacity(int)

Used

public int Used()

Get the number of characters in the monitor.

N.B.: The amount of capacity used may be larger than the capacity set for the monitor.

Returns:

The amount of used character space in the monitor.

See Also:

Write(String, AttributeSet)

Auto_Style

public Stream_Monitor Auto_Style(boolean enable)

Enable or disable auto-styling.

If auto-styling is enabled, and a style is not specified, all text written to the monitor display is first examined for an initial sequence that matches one of the text-to-style keys. If a match is found the associated style is applied to the displayed text.

Parameters:

enable - If true, auto-styling is enabled; false disables auto-styling.

Returns:

This Stream_Monitor.

Auto_Style

public boolean Auto_Style()

Test if auto-styling mode is enabled

Returns:

true, auto-styling is enabled; false otherwise.

See Also:

Auto_Style(boolean)

Auto_Style

public Stream_Monitor Auto_Style(String text,
                                 AttributeSet style)

Add an auto-style text-to-style association.

When auto-style is enabled each time text is written or the output stream is flushed to the monitor display the text is checked for the specified prefix text and, if found, the corresponding style is applied.

Parameters:

text - The prefix String to be associated with a style. If null no association is made.

style - The AttributeSet to be associated with the text. If null no association is made.

Returns:

This Stream_Monitor.

See Also:

Auto_Style(boolean), Write(String, AttributeSet)

Auto_Style

public AttributeSet Auto_Style(String text)

Get the style associated with a text prefix.

Parameters:

text - The prefix text that is associated with a style.

Returns:

The AttributeSet associated with the text. This will be null if there is no text-to-style association.

See Also:

Auto_Style(boolean)

Auto_Style_Table

public Hashtable Auto_Style_Table()

Get the text-to-style association table.

Returns:

The Hastable containing the text-to-style associations.

See Also:

Auto_Style(boolean)

File_Menu

public JMenu File_Menu()

Get the monitor's "File" menu.

The File menu has "Save" and "Save As ..." menu items, in that order, that have action listeners that will save the monitor text. They have no mnemonics or accelerators.

Returns:

A JMenu.

View_Menu

public JMenu View_Menu()

Get the monitor's "View" menu.

The View menu has "Capacity ..." and "Clear" menu items, in that order, that have action listeners that will interactively set the monitor character capacity and clear the monitor contents, respectively. They have no mnemonics or accelerators.

Returns:

A JMenu.

Scroll_Pane

public JScrollPane Scroll_Pane()

Get the JScrollPane that contains the JTextPane where the monitor text is displayed.

The StyledDocument managing the text can be obtained by:

Stream_Monitor monitor = new Stream_Monitor(); ... StyledDocument document = (JTextPane)(monitor.Scroll_Pane().getViewport().getView()) .getStyledDocument();

Returns:

The JScrollPane that contains the JTextPane where the monitor text is displayed.

Save_Monitor_Text

public void Save_Monitor_Text(boolean interactive)

Save the current monitor text to a file.

If interactive is true a JFileChooser will be used to select the file where the text will be saved. Otherwise the text will be saved to the previously selected file. If no file has been previously selected interactive mode will be used.

The current monitor contents are written as plain text.

If there was a problem writing the text to the file an error dialog will display the exception message.

Parameters:

interactive - If interactive file selection is to be used.

Save_Monitor_Text

public void Save_Monitor_Text(String pathname)

Save the current monitor text to a file.

Parameters:

pathname - The pathname to the file where the text is to be save. If null, interactive file selection will be used.

See Also:

Save_Monitor_Text(boolean)

Save_Monitor_Text

public void Save_Monitor_Text()

Save the current monitor text to a file.

If a file has previously been selected for saving the monitor text then it is overwritten. Otherwise interactive file selection is used.

See Also:

Save_Monitor_Text(boolean)

Clear

public Stream_Monitor Clear()

Clear the monitor of all text.

Write

public Stream_Monitor Write(String text)

Write text to the monitor.

This method writes the text with a null style.

Specified by:

Write in interface Styled_Writer

Parameters:

text - A text String to be added to the end of the monitor display.

Returns:

This Styled_Writer

See Also:

Write(String, AttributeSet)

Write

public Stream_Monitor Write(String text,
                            AttributeSet style)

Write styled text to the monitor.

If the style is null and auto-styling is enabled the initial portion of the text will be checked for an auto-style key. If one is found the associated style will be applied. N.B.: The style is applied to all of the text specified; auto-styling is not limited to the single line which begins with an auto-style prefix.

If the amount of space used is greater than the capacity plus a MIN_CAPACITY margin, monitor text is removed from the top (FIFO) up to and including the end-of-line characters to bring the amount used below the capacity.

The text is appended to the bottom of the monitor with the style, if any, applied. The scroll pane is moved up so that the end of the text appears at the bottom of the display.

A style is assembled using combinations of the numerous StyleConstants setXXX functions applied to a SimpleAttributeSet. For example:

SimpleAttributeSet bold_red_text = new SimpleAttributeSet ();
StyleConstants.setBold       (bold_red_text, true);
StyleConstants.setForeground (bold_red_text, Color.RED);
StyleConstants.setFontFamily (bold_red_text, "Monospaced");

assembles a style that will produce text in a bold, red, monospaced font.

Specified by:

Write in interface Styled_Writer

Parameters:

text - The text String to be appended to the monitor.

style - The AttributeSet to be applied to the text. This may be null if plain text is to be displayed.

Returns:

This Styled_Writer

See Also:

StyleConstants