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.

See Also:
  Serialized Form

### Nested Class Summary

Nested Classes
`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

Fields
`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

Constructors
Constructor and Description
`Stream_Monitor()` Construct a Stream_Monitor.

### Method Summary

Methods
`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, isPaintingOrigin, 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, 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, transferFocusBackward, 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 `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 `write`s 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`