PIRL.Utilities

## Class Suspendable_Styled_Writer

- java.lang.Object
- - java.io.Writer
  - - PIRL.Utilities.Suspendable_Styled_Writer

All Implemented Interfaces:
  Closeable, Flushable, Appendable, AutoCloseable, Styled_Writer

    public class Suspendable_Styled_Writer
    extends Writer
    implements Styled_Writer

A Suspendable_Styled_Writer is a Writer that can have its output operations suspended.

All output methods are forwarded to the backing Writer. However, output may be suspended, in which case no output will occur until the suspension has been lifted.

The Styled_Writer interface is also implemented such that if the backing Writer implements Styled_Writer that interface is used, otherwise the usual Writer API is used instead in which case no style information will be forwarded.

See Also:
  `Writer`, `Styled_Writer`

### Field Summary

Fields
`boolean` `Active` The suspension state of the Writer.
`static String` `ID` Class identification name with source code version and date.

### Fields inherited from class java.io.Writer

`lock`

### Constructor Summary

Constructors
Constructor and Description
`Suspendable_Styled_Writer(Writer writer)` Construct a Suspendable_Styled_Writer.
`Suspendable_Styled_Writer(Writer writer, boolean active)` Construct a Suspendable_Styled_Writer with suspension specified.

### Method Summary

Methods
`void` `close()` Close the writer.
`void` `flush()` Flush the writer.
`void` `Suspend(boolean suspend)` Turn output suspension on or off.
`boolean` `Suspended()` Test if output has been suspended.
`void` `write(char[] characters)` Write an array of characters.
`void` `write(char[] characters, int offset, int amount)` Write a portion of an array of characters.
`void` `write(int character)` Write a character.
`void` `write(String string)` Write a String.
`Styled_Writer` `Write(String text)` Write plain text.
`Styled_Writer` `Write(String text, AttributeSet style)` Write styled text.
`void` `write(String string, int offset, int amount)` Write a portion of a String.
`Writer` `Writer()` Get the Writer to which all Write methods are forwarded.

### Methods inherited from class java.io.Writer

`append, append, append`

### Methods inherited from class java.lang.Object

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

### Field Detail

#### ID

    public static final String ID

Class identification name with source code version and date.

See Also:
  Constant Field Values

#### Active

    public volatile boolean Active

The suspension state of the Writer.

When Active is true all output methods will forward to the `Writer` on which the object was constructed.

### Constructor Detail

#### Suspendable_Styled_Writer

    public Suspendable_Styled_Writer(Writer writer)

Construct a Suspendable_Styled_Writer.

The intial state of the Writer is determined by the `flag`.

Parameters:
  `writer` - The Writer to use for all write operations.
Throws:
  `IllegalArgumentException` - If the writer is null.

#### Suspendable_Styled_Writer

    public Suspendable_Styled_Writer(Writer writer,
                             boolean active)

Construct a Suspendable_Styled_Writer with suspension specified.

Parameters:
  `writer` - The Writer to use for all write operations.
  `active` - The initial state of the Writer. If true writes will occure; if false writes are suspended.
Throws:
  `IllegalArgumentException` - If the writer is null.

### Method Detail

#### Writer

    public Writer Writer()

Get the Writer to which all Write methods are forwarded.

Returns:
  A Writer.

#### Suspended

    public boolean Suspended()

Test if output has been suspended.

Returns:
  true if output has been suspended; false otherwise.
See Also:
  `Suspend(boolean)`

#### Suspend

    public void Suspend(boolean suspend)

Turn output suspension on or off.

Parameters:
  `suspend` - If true subsequent output will be suspended; if false output will occur.

#### write

    public void write(char[] characters,
             int offset,
             int amount)
               throws IOException

Write a portion of an array of characters.

Nothing is done if the Writer is `suspended`.

Specified by:
  `write` in class `Writer`
Parameters:
  `characters` - The char array containing the characters to be written. If null or empty nothing is done.
  `offset` - Array offset from which to start writing characters.
  `amount` - The number of characters to write.
Throws:
  `IOException` - If the `Writer` throws an exception.

#### write

    public void write(char[] characters)
               throws IOException

Write an array of characters.

Nothing is done if the Writer is `suspended`.

Overrides:
  `write` in class `Writer`
Parameters:
  `characters` - The char array containing the characters to be written.
Throws:
  `IOException` - If the `Writer` throws an exception.

#### write

    public void write(int character)
               throws IOException

Write a character.

Nothing is done if the Writer is `suspended`.

Overrides:
  `write` in class `Writer`
Parameters:
  `character` - The character to be written in the 16 low-order bits..
Throws:
  `IOException` - If the `Writer` throws an exception.

#### write

    public void write(String string,
             int offset,
             int amount)
               throws IOException

Write a portion of a String.

Nothing is done if the Writer is `suspended`.

Overrides:
  `write` in class `Writer`
Parameters:
  `string` - The String containing the characters to be written.
  `offset` - String offset from which to start writing characters.
  `amount` - The number of characters to write.
Throws:
  `IOException` - If the `Writer` throws an exception.

#### write

    public void write(String string)
               throws IOException

Write a String.

Nothing is done if the Writer is `suspended`.

Overrides:
  `write` in class `Writer`
Parameters:
  `string` - The String containing the characters to be written. If null or empty nothing is done.
Throws:
  `IOException` - If the `Writer` throws an exception.

#### flush

    public void flush()
               throws IOException

Flush the writer.

Nothing is done if the Writer is `suspended`.

Specified by:
  `flush` in interface `Flushable`
Specified by:
  `flush` in class `Writer`
Throws:
  `IOException` - If the `Writer` throws an exception.

#### close

    public void close()
               throws IOException

Close the writer.

N.B.: The `Writer` will be closed regardless of whether writing has been `suspended` or not.

Specified by:
  `close` in interface `Closeable`
Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in class `Writer`
Throws:
  `IOException` - If the `Writer` throws an exception.

#### Write

    public Styled_Writer Write(String text,
                      AttributeSet style)
                        throws IOException

Write styled text.

Specified by:
  `Write` in interface `Styled_Writer`
Parameters:
  `text` - The text String to be written.
  `style` - The AttributeSet to be applied to the text. This may be null if plain text is to be displayed.
Returns:
  This Suspendable_Styled_Writer
Throws:
  `IOException` - If the `Writer` throws an exception.
See Also:
  `Styled_Writer.Write(String, AttributeSet)`

#### Write

    public Styled_Writer Write(String text)
                        throws IOException

Write plain text.

This is the same as `writing` text with a null style.

Specified by:
  `Write` in interface `Styled_Writer`
Parameters:
  `text` - The text String to be written.
Returns:
  This Suspendable_Styled_Writer
Throws:
  `IOException` - If the `Writer` throws an exception.