PSGenerator
Date: 2016-04-28

org.apache.xmlgraphics.ps

## Class PSGenerator

- java.lang.Object
- - org.apache.xmlgraphics.ps.PSGenerator

- All Implemented Interfaces:
    PSCommandMap

      public class PSGenerator
      extends java.lang.Object
      implements PSCommandMap

  This class is used to output PostScript code to an OutputStream. This class assumes that the `PSProcSets.STD_PROCSET` has been added to the PostScript file.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.Object` | `ATEND` Deprecated. Please use DSCConstants.ATEND. This constant was in the wrong place.
    `static int` | `DEFAULT_LANGUAGE_LEVEL` Default postscript language level
    `static char` | `LF` Line feed used by PostScript

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PSGenerator(java.io.OutputStream out)` Creates a new instance.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `commentln(java.lang.String comment)` Writes a comment to the stream and ends the line.
    `void` | `concatMatrix(java.awt.geom.AffineTransform at)` Concats the transformations matric.
    `void` | `concatMatrix(double[] matrix)` Concats the transformations matrix.
    `void` | `concatMatrix(double a, double b, double c, double d, double e, double f)` Concats the transformation matrix.
    `static java.lang.String` | `convertRealToDSC(float value)` Converts a <real> value for use in DSC comments.
    `static java.lang.String` | `convertStringToDSC(java.lang.String text)` Converts text by applying escaping rules established in the DSC specs.
    `static java.lang.String` | `convertStringToDSC(java.lang.String text, boolean forceParentheses)` Converts text by applying escaping rules established in the DSC specs.
    `void` | `defineRect(double x, double y, double w, double h)` Adds a rectangle to the current path.
    `boolean` | `embedIdentityH()` Embeds the Identity-H CMap file into the output stream, if that has not already been done.
    `static void` | `escapeChar(char c, java.lang.StringBuffer target)` Escapes a character conforming to the rules established in the PostScript Language Reference (Search for "Literal Text Strings").
    `void` | `flush()` Flushes the OutputStream.
    `java.lang.String` | `formatDouble(double value)` Formats a double value for PostScript output.
    `java.lang.String` | `formatDouble5(double value)` Formats a double value for PostScript output (higher resolution).
    `java.lang.String` | `formatMatrix(java.awt.geom.AffineTransform at)` Formats a transformation matrix.
    `java.lang.String` | `formatRectangleToArray(java.awt.geom.Rectangle2D rect)` Formats a Rectangle2D to an array.
    `PSState` | `getCurrentState()` Returns the current graphics state.
    `PSResource` | `getIdentityHCMapResource()` Returns the PSResource instance corresponding to the Identity-H CMap resource.
    `java.io.OutputStream` | `getOutputStream()` Returns the OutputStream the PSGenerator writes to.
    `PSResource` | `getProcsetCIDInitResource()` Returns the PSResource instance corresponding to the CIDInit ProcSet resource.
    `int` | `getPSLevel()` Returns the selected PostScript level.
    `ResourceTracker` | `getResourceTracker()` Resturns the ResourceTracker instance associated with this PSGenerator.
    `void` | `includeProcsetCIDInitResource()` Adds a PostScript DSC comment to the output stream requiring the inclusion of the CIDInit ProcSet resource.
    `boolean` | `isCommentsEnabled()` Indicates whether this instance allows to write comments.
    `boolean` | `isCompactMode()` Indicates whether this instance is in compact mode.
    `boolean` | `isResourceSupplied(PSResource res)` Deprecated. Use the isResourceSupplied() on ResourceTracker instead.
    `java.lang.String` | `mapCommand(java.lang.String command)` Maps a standard PostScript command (like "setlinejoin" or "setrgbcolor") to a macro.
    `void` | `newLine()` Writes a newline character to the OutputStream.
    `void` | `notifyResourceUsage(PSResource res, boolean needed)` Deprecated. Use the notifyResourceUsageOnPage() on ResourceTracker instead
    `void` | `notifyStartNewPage()` Deprecated. Use the notifyStartNewPage() on ResourceTracker instead.
    `javax.xml.transform.Source` | `resolveURI(java.lang.String uri)` Attempts to resolve the given URI.
    `boolean` | `restoreGraphicsState()` Restores the last graphics state of the rendering engine.
    `void` | `saveGraphicsState()` Saves the graphics state of the rendering engine.
    `void` | `setCommentsEnabled(boolean value)` Controls whether this instance allows to write comments using the `commentln(String)` method.
    `void` | `setCompactMode(boolean value)` Controls whether this instance shall produce compact PostScript (omitting comments and using short macros).
    `void` | `setPSLevel(int level)` Sets the PostScript level that is used to generate the current document.
    `void` | `setResourceTracker(ResourceTracker resTracker)` Sets the ResourceTracker instance to be associated with this PSGenerator.
    `void` | `showPage()` Issues the "showpage" command and resets the painting state accordingly.
    `void` | `useColor(java.awt.Color col)` Establishes the specified color.
    `void` | `useDash(java.lang.String pattern)` Establishes the specified dash pattern.
    `void` | `useFont(java.lang.String name, float size)` Establishes the specified font and size.
    `void` | `useLineCap(int linecap)` Establishes the specified line cap style.
    `void` | `useLineJoin(int linejoin)` Establishes the specified line join style.
    `void` | `useLineWidth(double width)` Establishes the specified line width.
    `void` | `useMiterLimit(float miterlimit)` Establishes the specified miter limit.
    `void` | `useRGBColor(java.awt.Color col)` Deprecated. use useColor method instead
    `void` | `write(int n)` Writes the given number to the stream in decimal format.
    `void` | `write(java.lang.String cmd)` Writes a PostScript command to the stream.
    `void` | `writeByteArr(byte[] cmd)` Writes encoded data to the PostScript stream.
    `void` | `writeDSCComment(java.lang.String name)` Writes a DSC comment to the output stream.
    `void` | `writeDSCComment(java.lang.String name, java.lang.Object param)` Writes a DSC comment to the output stream.
    `void` | `writeDSCComment(java.lang.String name, java.lang.Object[] params)` Writes a DSC comment to the output stream.
    `void` | `writeln(java.lang.String cmd)` Writes a PostScript command to the stream and ends the line.
    `void` | `writeResources(boolean pageLevel)` Deprecated. Use the writeResources() on ResourceTracker instead.

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

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

- - ### Field Detail

    - #### DEFAULT_LANGUAGE_LEVEL

          public static final int DEFAULT_LANGUAGE_LEVEL

      Default postscript language level
      See Also:
        Constant Field Values

    - #### ATEND

          @Deprecated
          public static final java.lang.Object ATEND

      Deprecated. Please use DSCConstants.ATEND. This constant was in the wrong place.
      Indicator for the PostScript interpreter that the value is provided later in the document (mostly in the %%Trailer section).

    - #### LF

          public static final char LF

      Line feed used by PostScript
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### PSGenerator

          public PSGenerator(java.io.OutputStream out)

      Creates a new instance.
      Parameters:
        `out` - the OutputStream to write the generated PostScript code to

  - ### Method Detail

    - #### isCompactMode

          public boolean isCompactMode()

      Indicates whether this instance is in compact mode. See `setCompactMode(boolean)` for details.
      Returns:
        true if compact mode is enabled (the default)

    - #### setCompactMode

          public void setCompactMode(boolean value)

      Controls whether this instance shall produce compact PostScript (omitting comments and using short macros). Enabling this mode requires that the standard procset (`PSProcSets.STD_PROCSET`) is included in the PostScript file. Setting this to false produces more verbose PostScript suitable for debugging.
      Parameters:
        `value` - true to enable compact mode, false for verbose mode

    - #### isCommentsEnabled

          public boolean isCommentsEnabled()

      Indicates whether this instance allows to write comments. See `setCommentsEnabled(boolean)` for details.
      Returns:
        true if comments are enabled (the default)

    - #### setCommentsEnabled

          public void setCommentsEnabled(boolean value)

      Controls whether this instance allows to write comments using the `commentln(String)` method.
      Parameters:
        `value` - true to enable comments, false to disable them

    - #### getOutputStream

          public java.io.OutputStream getOutputStream()

      Returns the OutputStream the PSGenerator writes to.
      Returns:
        the OutputStream

    - #### getPSLevel

          public int getPSLevel()

      Returns the selected PostScript level.
      Returns:
        the PostScript level

    - #### setPSLevel

          public void setPSLevel(int level)

      Sets the PostScript level that is used to generate the current document.
      Parameters:
        `level` - the PostScript level (currently 1, 2 and 3 are known)

    - #### resolveURI

          public javax.xml.transform.Source resolveURI(java.lang.String uri)

      Attempts to resolve the given URI. PSGenerator should be subclasses to provide more sophisticated URI resolution.
      Parameters:
        `uri` - URI to access
      Returns:
        A `Source` object, or null if the URI cannot be resolved.

    - #### newLine

          public final void newLine()
                             throws java.io.IOException

      Writes a newline character to the OutputStream.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### formatDouble

          public java.lang.String formatDouble(double value)

      Formats a double value for PostScript output.
      Parameters:
        `value` - value to format
      Returns:
        the formatted value

    - #### formatDouble5

          public java.lang.String formatDouble5(double value)

      Formats a double value for PostScript output (higher resolution).
      Parameters:
        `value` - value to format
      Returns:
        the formatted value

    - #### write

          public void write(java.lang.String cmd)
                     throws java.io.IOException

      Writes a PostScript command to the stream.
      Parameters:
        `cmd` - The PostScript code to be written.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### write

          public void write(int n)
                     throws java.io.IOException

      Writes the given number to the stream in decimal format.
      Parameters:
        `n` - a number
      Throws:
        `java.io.IOException` - in case of an I/O problem

    - #### writeln

          public void writeln(java.lang.String cmd)
                       throws java.io.IOException

      Writes a PostScript command to the stream and ends the line.
      Parameters:
        `cmd` - The PostScript code to be written.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### commentln

          public void commentln(java.lang.String comment)
                         throws java.io.IOException

      Writes a comment to the stream and ends the line. Output of comments can be disabled to reduce the size of the generated file.
      Parameters:
        `comment` - comment to write
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### mapCommand

          public java.lang.String mapCommand(java.lang.String command)

      Maps a standard PostScript command (like "setlinejoin" or "setrgbcolor") to a macro. If no mapping is available, the command itself is returned again.
      Specified by:
        `mapCommand` in interface `PSCommandMap`
      Parameters:
        `command` - the command
      Returns:
        the mapped command (or the "command" parameter if no mapping is available)

    - #### writeByteArr

          public void writeByteArr(byte[] cmd)
                            throws java.io.IOException

      Writes encoded data to the PostScript stream.
      Parameters:
        `cmd` - The encoded PostScript code to be written.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### flush

          public void flush()
                     throws java.io.IOException

      Flushes the OutputStream.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### escapeChar

          public static final void escapeChar(char c,
                        java.lang.StringBuffer target)

      Escapes a character conforming to the rules established in the PostScript Language Reference (Search for "Literal Text Strings").
      Parameters:
        `c` - character to escape
        `target` - target StringBuffer to write the escaped character to

    - #### convertStringToDSC

          public static final java.lang.String convertStringToDSC(java.lang.String text)

      Converts text by applying escaping rules established in the DSC specs.
      Parameters:
        `text` - Text to convert
      Returns:
        String The resulting String

    - #### convertRealToDSC

          public static final java.lang.String convertRealToDSC(float value)

      Converts a <real> value for use in DSC comments.
      Parameters:
        `value` - the value to convert
      Returns:
        String The resulting String

    - #### convertStringToDSC

          public static final java.lang.String convertStringToDSC(java.lang.String text,
                                            boolean forceParentheses)

      Converts text by applying escaping rules established in the DSC specs.
      Parameters:
        `text` - Text to convert
        `forceParentheses` - Force the use of parentheses
      Returns:
        String The resulting String

    - #### writeDSCComment

          public void writeDSCComment(java.lang.String name)
                               throws java.io.IOException

      Writes a DSC comment to the output stream.
      Parameters:
        `name` - Name of the DSC comment
      Throws:
        `java.io.IOException` - In case of an I/O problem
      See Also:
        `DSCConstants`

    - #### writeDSCComment

          public void writeDSCComment(java.lang.String name,
                             java.lang.Object param)
                               throws java.io.IOException

      Writes a DSC comment to the output stream. The parameter to the DSC comment can be any object. The object is converted to a String as necessary.
      Parameters:
        `name` - Name of the DSC comment
        `param` - Single parameter to the DSC comment
      Throws:
        `java.io.IOException` - In case of an I/O problem
      See Also:
        `DSCConstants`

    - #### writeDSCComment

          public void writeDSCComment(java.lang.String name,
                             java.lang.Object[] params)
                               throws java.io.IOException

      Writes a DSC comment to the output stream. The parameters to the DSC comment can be any object. The objects are converted to Strings as necessary. Please see the source code to find out what parameters are currently supported.
      Parameters:
        `name` - Name of the DSC comment
        `params` - Array of parameters to the DSC comment
      Throws:
        `java.io.IOException` - In case of an I/O problem
      See Also:
        `DSCConstants`

    - #### saveGraphicsState

          public void saveGraphicsState()
                                 throws java.io.IOException

      Saves the graphics state of the rendering engine.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### restoreGraphicsState

          public boolean restoreGraphicsState()
                                       throws java.io.IOException

      Restores the last graphics state of the rendering engine.
      Returns:
        true if the state was restored, false if there's a stack underflow.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### getCurrentState

          public PSState getCurrentState()

      Returns the current graphics state.
      Returns:
        the current graphics state

    - #### showPage

          public void showPage()
                        throws java.io.IOException

      Issues the "showpage" command and resets the painting state accordingly.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### concatMatrix

          public void concatMatrix(double a,
                          double b,
                          double c,
                          double d,
                          double e,
                          double f)
                            throws java.io.IOException

      Concats the transformation matrix.
      Parameters:
        `a` - A part
        `b` - B part
        `c` - C part
        `d` - D part
        `e` - E part
        `f` - F part
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### concatMatrix

          public void concatMatrix(double[] matrix)
                            throws java.io.IOException

      Concats the transformations matrix.
      Parameters:
        `matrix` - Matrix to use
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### formatMatrix

          public java.lang.String formatMatrix(java.awt.geom.AffineTransform at)

      Formats a transformation matrix.
      Parameters:
        `at` - the AffineTransform with the matrix
      Returns:
        the formatted transformation matrix (example: "[1 0 0 1 0 0]")

    - #### concatMatrix

          public void concatMatrix(java.awt.geom.AffineTransform at)
                            throws java.io.IOException

      Concats the transformations matric.
      Parameters:
        `at` - the AffineTransform whose matrix to use
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### formatRectangleToArray

          public java.lang.String formatRectangleToArray(java.awt.geom.Rectangle2D rect)

      Formats a Rectangle2D to an array.
      Parameters:
        `rect` - the rectangle
      Returns:
        the formatted array

    - #### defineRect

          public void defineRect(double x,
                        double y,
                        double w,
                        double h)
                          throws java.io.IOException

      Adds a rectangle to the current path.
      Parameters:
        `x` - upper left corner
        `y` - upper left corner
        `w` - width
        `h` - height
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### useLineCap

          public void useLineCap(int linecap)
                          throws java.io.IOException

      Establishes the specified line cap style.
      Parameters:
        `linecap` - the line cap style (0, 1 or 2) as defined by the setlinecap command.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### useLineJoin

          public void useLineJoin(int linejoin)
                           throws java.io.IOException

      Establishes the specified line join style.
      Parameters:
        `linejoin` - the line join style (0, 1 or 2) as defined by the setlinejoin command.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### useMiterLimit

          public void useMiterLimit(float miterlimit)
                             throws java.io.IOException

      Establishes the specified miter limit.
      Parameters:
        `miterlimit` - the miter limit as defined by the setmiterlimit command.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### useLineWidth

          public void useLineWidth(double width)
                            throws java.io.IOException

      Establishes the specified line width.
      Parameters:
        `width` - the line width as defined by the setlinewidth command.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### useDash

          public void useDash(java.lang.String pattern)
                       throws java.io.IOException

      Establishes the specified dash pattern.
      Parameters:
        `pattern` - the dash pattern as defined by the setdash command.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### useRGBColor

          @Deprecated
          public void useRGBColor(java.awt.Color col)
                           throws java.io.IOException

      Deprecated. use useColor method instead
      Establishes the specified color (RGB).
      Parameters:
        `col` - the color as defined by the setrgbcolor command.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### useColor

          public void useColor(java.awt.Color col)
                        throws java.io.IOException

      Establishes the specified color.
      Parameters:
        `col` - the color.
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### useFont

          public void useFont(java.lang.String name,
                     float size)
                       throws java.io.IOException

      Establishes the specified font and size.
      Parameters:
        `name` - name of the font for the "F" command (see FOP Std Proc Set)
        `size` - size of the font
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### getResourceTracker

          public ResourceTracker getResourceTracker()

      Resturns the ResourceTracker instance associated with this PSGenerator.
      Returns:
        the ResourceTracker instance or null if none is assigned

    - #### setResourceTracker

          public void setResourceTracker(ResourceTracker resTracker)

      Sets the ResourceTracker instance to be associated with this PSGenerator.
      Parameters:
        `resTracker` - the ResourceTracker instance

    - #### notifyStartNewPage

          @Deprecated
          public void notifyStartNewPage()

      Deprecated. Use the notifyStartNewPage() on ResourceTracker instead.
      Notifies the generator that a new page has been started and that the page resource set can be cleared.

    - #### notifyResourceUsage

          @Deprecated
          public void notifyResourceUsage(PSResource res,
                                            boolean needed)

      Deprecated. Use the notifyResourceUsageOnPage() on ResourceTracker instead
      Notifies the generator about the usage of a resource on the current page.
      Parameters:
        `res` - the resource being used
        `needed` - true if this is a needed resource, false for a supplied resource

    - #### writeResources

          @Deprecated
          public void writeResources(boolean pageLevel)
                              throws java.io.IOException

      Deprecated. Use the writeResources() on ResourceTracker instead.
      Writes a DSC comment for the accumulated used resources, either at page level or at document level.
      Parameters:
        `pageLevel` - true if the DSC comment for the page level should be generated, false for the document level (in the trailer)
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### isResourceSupplied

          @Deprecated
          public boolean isResourceSupplied(PSResource res)

      Deprecated. Use the isResourceSupplied() on ResourceTracker instead.
      Indicates whether a particular resource is supplied, rather than needed.
      Parameters:
        `res` - the resource
      Returns:
        true if the resource is registered as being supplied.

    - #### embedIdentityH

          public boolean embedIdentityH()
                                 throws java.io.IOException

      Embeds the Identity-H CMap file into the output stream, if that has not already been done.
      Returns:
        true if embedding has actually been performed, false otherwise (which means that a call to this method had already been made earlier)
      Throws:
        `java.io.IOException` - in case of an I/O problem

    - #### getIdentityHCMapResource

          public PSResource getIdentityHCMapResource()

      Returns the PSResource instance corresponding to the Identity-H CMap resource.
      Returns:
        the Identity-H CMap resource.

    - #### getProcsetCIDInitResource

          public PSResource getProcsetCIDInitResource()

      Returns the PSResource instance corresponding to the CIDInit ProcSet resource.
      Returns:
        the ProcSet CIDInit resource

    - #### includeProcsetCIDInitResource

          public void includeProcsetCIDInitResource()
                                             throws java.io.IOException

      Adds a PostScript DSC comment to the output stream requiring the inclusion of the CIDInit ProcSet resource.
      Throws:
        `java.io.IOException` - in case of an I/O problem