PSGraphics2D
Date: 2016-04-28

org.apache.xmlgraphics.java2d.ps

## Class PSGraphics2D

- java.lang.Object
- - java.awt.Graphics
  - - java.awt.Graphics2D
    - - org.apache.xmlgraphics.java2d.AbstractGraphics2D
      - - org.apache.xmlgraphics.java2d.ps.PSGraphics2D

- All Implemented Interfaces:
    java.lang.Cloneable
  Direct Known Subclasses:
    AbstractPSDocumentGraphics2D

      public class PSGraphics2D
      extends AbstractGraphics2D

  This is a concrete implementation of `AbstractGraphics2D` (and therefore of `Graphics2D`) which is able to generate PostScript code.
  See Also:
    `Originally authored by Keiron Liddle.`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `clippingDisabled` Disable or enable clipping
    `protected java.awt.Color` | `currentColour` the current colour for use in svg
    `protected TextHandler` | `customTextHandler` Custom text handler
    `protected TextHandler` | `fallbackTextHandler` Fallback text handler
    `protected PSGenerator` | `gen` the PostScript generator being created
    `protected java.util.List<java.lang.Integer>` | `pathHashCache`
    `protected PSGraphics2D` | `rootG2D` The G2D instance that represents the root instance (used in context with create()/dispose()).
    `protected boolean` | `startCache`

    - ### Fields inherited from class org.apache.xmlgraphics.java2d.AbstractGraphics2D

      `gc, inPossibleRecursion, textAsShapes`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PSGraphics2D(boolean textAsShapes)` Create a new Graphics2D that generates PostScript code.
    `PSGraphics2D(boolean textAsShapes, PSGenerator gen)` Create a new Graphics2D that generates PostScript code.
    `PSGraphics2D(PSGraphics2D g)` Constructor for creating copies

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `applyPaint(java.awt.Paint paint, boolean fill)` Applies a new Paint object.
    `protected void` | `applyStroke(java.awt.Stroke stroke)` Applies a new Stroke object.
    `static void` | `applyStroke(java.awt.Stroke stroke, PSGenerator gen)` Applies a new Stroke object.
    `java.awt.image.BufferedImage` | `buildBufferedImage(java.awt.Dimension size)` Creates a buffered image.
    `void` | `copyArea(int x, int y, int width, int height, int dx, int dy)` Copies an area of the component by a distance specified by `dx` and `dy`.
    `java.awt.Graphics` | `create()` Creates a new `Graphics` object that is a copy of this `Graphics` object.
    `void` | `disableClipping(boolean b)` Disable clipping on each draw command.
    `void` | `dispose()` Disposes of this graphics context and releases any system resources that it is using.
    `protected void` | `doDrawing(boolean fill, boolean stroke, boolean nonzero)` Commits a painting operation.
    `void` | `draw(java.awt.Shape s)` Strokes the outline of a `Shape` using the settings of the current `Graphics2D` context.
    `boolean` | `drawImage(java.awt.Image img, int x, int y, java.awt.image.ImageObserver observer)` Draws as much of the specified image as is currently available.
    `boolean` | `drawImage(java.awt.Image img, int x, int y, int width, int height, java.awt.image.ImageObserver observer)` Draws as much of the specified image as has already been scaled to fit inside the specified rectangle.
    `void` | `drawRenderableImage(java.awt.image.renderable.RenderableImage img, java.awt.geom.AffineTransform xform)` Renders a `RenderableImage`, applying a transform from image space into user space before drawing.
    `void` | `drawRenderedImage(java.awt.image.RenderedImage img, java.awt.geom.AffineTransform xform)` Renders a `RenderedImage`, applying a transform from image space into user space before drawing.
    `void` | `drawString(java.lang.String s, float x, float y)` Renders the text specified by the specified `String`, using the current `Font` and `Paint` attributes in the `Graphics2D` context.
    `void` | `establishColor(java.awt.Color c)` Establishes the given color in the PostScript interpreter.
    `void` | `fill(java.awt.Shape s)` Fills the interior of a `Shape` using the settings of the `Graphics2D` context.
    `TextHandler` | `getCustomTextHandler()`
    `java.awt.GraphicsConfiguration` | `getDeviceConfiguration()` Returns the device configuration associated with this `Graphics2D`.
    `TextHandler` | `getFallbackTextHandler()`
    `java.awt.FontMetrics` | `getFontMetrics(java.awt.Font f)` Gets the font metrics for the specified font.
    `PSGenerator` | `getPSGenerator()`
    `void` | `handleIOException(java.io.IOException ioe)` Central handler for IOExceptions for this class.
    `void` | `preparePainting()` This method is used by AbstractPSDocumentGraphics2D to prepare a new page if necessary.
    `void` | `processPathIterator(java.awt.geom.PathIterator iter)` Processes a path iterator generating the nexessary painting operations.
    `protected void` | `processPathIteratorCached(java.awt.Shape s)`
    `protected java.lang.String` | `processPathIteratorToString(java.awt.geom.PathIterator iter)`
    `int` | `processShape(java.awt.Shape s, boolean cached)` Processes a Shape generating the necessary painting operations.
    `void` | `setCustomTextHandler(TextHandler handler)` Sets a custom TextHandler implementation that is responsible for painting text.
    `void` | `setGraphicContext(GraphicContext c)` Sets the GraphicContext
    `void` | `setPSGenerator(PSGenerator gen)` Sets the PostScript generator
    `void` | `setXORMode(java.awt.Color c1)` Sets the paint mode of this graphics context to alternate between this graphics context's current color and the new specified color.
    `boolean` | `shouldBeClipped(java.awt.Shape clip, java.awt.Shape s)` Determines if a shape interacts with a clipping region.
    `void` | `writeClip(java.awt.Shape s)` Establishes a clipping region

    - ### Methods inherited from class org.apache.xmlgraphics.java2d.AbstractGraphics2D

      `addRenderingHints, clearRect, clip, clipRect, drawArc, drawGlyphVector, drawImage, drawImage, drawImage, drawImage, drawImage, drawImage, drawLine, drawOval, drawPolygon, drawPolyline, drawRect, drawRoundRect, drawString, drawString, drawString, fillArc, fillOval, fillPolygon, fillRect, fillRoundRect, getBackground, getClip, getClipBounds, getColor, getComposite, getFont, getFontRenderContext, getGraphicContext, getPaint, getRenderingHint, getRenderingHints, getStroke, getTransform, hit, rotate, rotate, scale, setBackground, setClip, setClip, setColor, setComposite, setFont, setPaint, setPaintMode, setRenderingHint, setRenderingHints, setStroke, setTransform, shear, transform, translate, translate`

    - ### Methods inherited from class java.awt.Graphics2D

      `draw3DRect, fill3DRect`

    - ### Methods inherited from class java.awt.Graphics

      `create, drawBytes, drawChars, drawPolygon, fillPolygon, finalize, getClipBounds, getClipRect, getFontMetrics, hitClip, toString`

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

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

- - ### Field Detail

    - #### pathHashCache

          protected java.util.List<java.lang.Integer> pathHashCache

    - #### startCache

          protected boolean startCache

    - #### rootG2D

          protected PSGraphics2D rootG2D

      The G2D instance that represents the root instance (used in context with create()/dispose()). Null if this instance is the root instance.

    - #### gen

          protected PSGenerator gen

      the PostScript generator being created

    - #### clippingDisabled

          protected boolean clippingDisabled

      Disable or enable clipping

    - #### fallbackTextHandler

          protected TextHandler fallbackTextHandler

      Fallback text handler

    - #### customTextHandler

          protected TextHandler customTextHandler

      Custom text handler

    - #### currentColour

          protected java.awt.Color currentColour

      the current colour for use in svg

  - ### Constructor Detail

    - #### PSGraphics2D

          public PSGraphics2D(boolean textAsShapes)

      Create a new Graphics2D that generates PostScript code.
      Parameters:
        `textAsShapes` - True if text should be rendered as graphics
      See Also:
        `AbstractGraphics2D.AbstractGraphics2D(boolean)`

    - #### PSGraphics2D

          public PSGraphics2D(boolean textAsShapes,
                      PSGenerator gen)

      Create a new Graphics2D that generates PostScript code.
      Parameters:
        `textAsShapes` - True if text should be rendered as graphics
        `gen` - PostScript generator to use for output
      See Also:
        `AbstractGraphics2D.AbstractGraphics2D(boolean)`

    - #### PSGraphics2D

          public PSGraphics2D(PSGraphics2D g)

      Constructor for creating copies
      Parameters:
        `g` - parent PostScript Graphics2D

  - ### Method Detail

    - #### setPSGenerator

          public void setPSGenerator(PSGenerator gen)

      Sets the PostScript generator
      Parameters:
        `gen` - the PostScript generator

    - #### getPSGenerator

          public PSGenerator getPSGenerator()

      Returns:
        the PostScript generator used by this instance.

    - #### setGraphicContext

          public void setGraphicContext(GraphicContext c)

      Sets the GraphicContext
      Parameters:
        `c` - GraphicContext to use

    - #### getFallbackTextHandler

          public TextHandler getFallbackTextHandler()

      Returns:
        the fallback TextHandler implementation

    - #### getCustomTextHandler

          public TextHandler getCustomTextHandler()

      Returns:
        the custom TextHandler implementation

    - #### setCustomTextHandler

          public void setCustomTextHandler(TextHandler handler)

      Sets a custom TextHandler implementation that is responsible for painting text. The default TextHandler paints all text as shapes. A custom implementation can implement text painting using text painting operators.
      Parameters:
        `handler` - the custom TextHandler implementation

    - #### disableClipping

          public void disableClipping(boolean b)

      Disable clipping on each draw command.
      Parameters:
        `b` - set to true to disable all clipping.

    - #### create

          public java.awt.Graphics create()

      Creates a new `Graphics` object that is a copy of this `Graphics` object.
      Specified by:
        `create` in class `java.awt.Graphics`
      Returns:
        a new graphics context that is a copy of this graphics context.

    - #### handleIOException

          public void handleIOException(java.io.IOException ioe)

      Central handler for IOExceptions for this class.
      Parameters:
        `ioe` - IOException to handle

    - #### preparePainting

          public void preparePainting()

      This method is used by AbstractPSDocumentGraphics2D to prepare a new page if necessary.

    - #### drawImage

          public boolean drawImage(java.awt.Image img,
                          int x,
                          int y,
                          java.awt.image.ImageObserver observer)

      Draws as much of the specified image as is currently available. The image is drawn with its top-left corner at (x, y) in this graphics context's coordinate space. Transparent pixels in the image do not affect whatever pixels are already there.

      This method returns immediately in all cases, even if the complete image has not yet been loaded, and it has not been dithered and converted for the current output device.

      If the image has not yet been completely loaded, then `drawImage` returns `false`. As more of the image becomes available, the process that draws the image notifies the specified image observer.

      Specified by:
        `drawImage` in class `java.awt.Graphics`
      Parameters:
        `img` - the specified image to be drawn.
        `x` - the x coordinate.
        `y` - the y coordinate.
        `observer` - object to be notified as more of the image is converted.
      Returns:
        True if the image has been fully drawn/loaded
      See Also:
        `Image`, `ImageObserver`, `ImageObserver.imageUpdate(java.awt.Image, int, int, int, int, int)`

    - #### buildBufferedImage

          public java.awt.image.BufferedImage buildBufferedImage(java.awt.Dimension size)

      Creates a buffered image.
      Parameters:
        `size` - dimensions of the image to be created
      Returns:
        the buffered image

    - #### drawImage

          public boolean drawImage(java.awt.Image img,
                          int x,
                          int y,
                          int width,
                          int height,
                          java.awt.image.ImageObserver observer)

      Draws as much of the specified image as has already been scaled to fit inside the specified rectangle.

      The image is drawn inside the specified rectangle of this graphics context's coordinate space, and is scaled if necessary. Transparent pixels do not affect whatever pixels are already there.

      This method returns immediately in all cases, even if the entire image has not yet been scaled, dithered, and converted for the current output device. If the current output representation is not yet complete, then `drawImage` returns `false`. As more of the image becomes available, the process that draws the image notifies the image observer by calling its `imageUpdate` method.

      A scaled version of an image will not necessarily be available immediately just because an unscaled version of the image has been constructed for this output device. Each size of the image may be cached separately and generated from the original data in a separate image production sequence.

      Specified by:
        `drawImage` in class `java.awt.Graphics`
      Parameters:
        `img` - the specified image to be drawn.
        `x` - the x coordinate.
        `y` - the y coordinate.
        `width` - the width of the rectangle.
        `height` - the height of the rectangle.
        `observer` - object to be notified as more of the image is converted.
      Returns:
        True if the image has been fully loaded/drawn
      See Also:
        `Image`, `ImageObserver`, `ImageObserver.imageUpdate(java.awt.Image, int, int, int, int, int)`

    - #### dispose

          public void dispose()

      Disposes of this graphics context and releases any system resources that it is using. A `Graphics` object cannot be used after `dispose`has been called.

      When a Java program runs, a large number of `Graphics` objects can be created within a short time frame. Although the finalization process of the garbage collector also disposes of the same system resources, it is preferable to manually free the associated resources by calling this method rather than to rely on a finalization process which may not run to completion for a long period of time.

      Graphics objects which are provided as arguments to the `paint` and `update` methods of components are automatically released by the system when those methods return. For efficiency, programmers should call `dispose` when finished using a `Graphics` object only if it was created directly from a component or another `Graphics` object.

      Specified by:
        `dispose` in class `java.awt.Graphics`
      See Also:
        `Graphics.finalize()`, `Component.paint(java.awt.Graphics)`, `Component.update(java.awt.Graphics)`, `Component.getGraphics()`, `Graphics.create()`

    - #### processShape

          public int processShape(java.awt.Shape s,
                         boolean cached)
                           throws java.io.IOException

      Processes a Shape generating the necessary painting operations.
      Parameters:
        `s` - Shape to process
      Returns:
        the winding rule of the path defining the shape
      Throws:
        `java.io.IOException` - In case of an I/O problem.

    - #### processPathIteratorToString

          protected java.lang.String processPathIteratorToString(java.awt.geom.PathIterator iter)
                                                          throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### processPathIteratorCached

          protected void processPathIteratorCached(java.awt.Shape s)
                                            throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### processPathIterator

          public void processPathIterator(java.awt.geom.PathIterator iter)
                                   throws java.io.IOException

      Processes a path iterator generating the nexessary painting operations.
      Parameters:
        `iter` - PathIterator to process
      Throws:
        `java.io.IOException` - In case of an I/O problem.

    - #### draw

          public void draw(java.awt.Shape s)

      Strokes the outline of a `Shape` using the settings of the current `Graphics2D` context. The rendering attributes applied include the `Clip`, `Transform`, `Paint`, `Composite` and `Stroke` attributes.
      Specified by:
        `draw` in class `java.awt.Graphics2D`
      Parameters:
        `s` - the `Shape` to be rendered
      See Also:
        `AbstractGraphics2D.setStroke(java.awt.Stroke)`, `AbstractGraphics2D.setPaint(java.awt.Paint)`, `Graphics.setColor(java.awt.Color)`, `AbstractGraphics2D.transform(java.awt.geom.AffineTransform)`, `AbstractGraphics2D.setTransform(java.awt.geom.AffineTransform)`, `AbstractGraphics2D.clip(java.awt.Shape)`, `AbstractGraphics2D.setClip(int, int, int, int)`, `AbstractGraphics2D.setComposite(java.awt.Composite)`

    - #### shouldBeClipped

          public boolean shouldBeClipped(java.awt.Shape clip,
                                java.awt.Shape s)

      Determines if a shape interacts with a clipping region.
      Parameters:
        `clip` - Shape defining the clipping region
        `s` - Shape to be drawn
      Returns:
        true if code for a clipping region needs to be generated.

    - #### writeClip

          public void writeClip(java.awt.Shape s)

      Establishes a clipping region
      Parameters:
        `s` - Shape defining the clipping region

    - #### applyPaint

          protected void applyPaint(java.awt.Paint paint,
                        boolean fill)

      Applies a new Paint object.
      Parameters:
        `paint` - Paint object to use
        `fill` - True if to be applied for filling

    - #### applyStroke

          protected void applyStroke(java.awt.Stroke stroke)

      Applies a new Stroke object.
      Parameters:
        `stroke` - Stroke object to use

    - #### applyStroke

          public static void applyStroke(java.awt.Stroke stroke,
                         PSGenerator gen)
                                  throws java.io.IOException

      Applies a new Stroke object.
      Parameters:
        `stroke` - the Stroke instance
        `gen` - the PS generator
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### drawRenderedImage

          public void drawRenderedImage(java.awt.image.RenderedImage img,
                               java.awt.geom.AffineTransform xform)

      Renders a `RenderedImage`, applying a transform from image space into user space before drawing. The transformation from user space into device space is done with the current `Transform` in the `Graphics2D`. The specified transformation is applied to the image before the transform attribute in the `Graphics2D` context is applied. The rendering attributes applied include the `Clip`, `Transform`, and `Composite` attributes. Note that no rendering is done if the specified transform is noninvertible.
      Specified by:
        `drawRenderedImage` in class `java.awt.Graphics2D`
      Parameters:
        `img` - the image to be rendered
        `xform` - the transformation from image space into user space
      See Also:
        `AbstractGraphics2D.transform(java.awt.geom.AffineTransform)`, `AbstractGraphics2D.setTransform(java.awt.geom.AffineTransform)`, `AbstractGraphics2D.setComposite(java.awt.Composite)`, `AbstractGraphics2D.clip(java.awt.Shape)`, `AbstractGraphics2D.setClip(int, int, int, int)`

    - #### drawRenderableImage

          public void drawRenderableImage(java.awt.image.renderable.RenderableImage img,
                                 java.awt.geom.AffineTransform xform)

      Renders a `RenderableImage`, applying a transform from image space into user space before drawing. The transformation from user space into device space is done with the current `Transform` in the `Graphics2D`. The specified transformation is applied to the image before the transform attribute in the `Graphics2D` context is applied. The rendering attributes applied include the `Clip`, `Transform`, and `Composite` attributes. Note that no rendering is done if the specified transform is noninvertible.

      Rendering hints set on the `Graphics2D` object might be used in rendering the `RenderableImage`. If explicit control is required over specific hints recognized by a specific `RenderableImage`, or if knowledge of which hints are used is required, then a `RenderedImage` should be obtained directly from the `RenderableImage` and rendered using `drawRenderedImage`.

      Specified by:
        `drawRenderableImage` in class `java.awt.Graphics2D`
      Parameters:
        `img` - the image to be rendered
        `xform` - the transformation from image space into user space
      See Also:
        `AbstractGraphics2D.transform(java.awt.geom.AffineTransform)`, `AbstractGraphics2D.setTransform(java.awt.geom.AffineTransform)`, `AbstractGraphics2D.setComposite(java.awt.Composite)`, `AbstractGraphics2D.clip(java.awt.Shape)`, `AbstractGraphics2D.setClip(int, int, int, int)`, `drawRenderedImage(java.awt.image.RenderedImage, java.awt.geom.AffineTransform)`

    - #### establishColor

          public void establishColor(java.awt.Color c)
                              throws java.io.IOException

      Establishes the given color in the PostScript interpreter.
      Parameters:
        `c` - the color to set
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### drawString

          public void drawString(java.lang.String s,
                        float x,
                        float y)

      Renders the text specified by the specified `String`, using the current `Font` and `Paint` attributes in the `Graphics2D` context. The baseline of the first character is at position (x, y) in the User Space. The rendering attributes applied include the `Clip`, `Transform`, `Paint`, `Font` and `Composite` attributes. For characters in script systems such as Hebrew and Arabic, the glyphs can be rendered from right to left, in which case the coordinate supplied is the location of the leftmost character on the baseline.
      Specified by:
        `drawString` in class `java.awt.Graphics2D`
      Parameters:
        `s` - the `String` to be rendered
        `x` - the x-coordinate where the `String` should be rendered
        `y` - the y-coordinate where the `String` should be rendered
      See Also:
        `AbstractGraphics2D.setPaint(java.awt.Paint)`, `Graphics.setColor(java.awt.Color)`, `Graphics.setFont(java.awt.Font)`, `AbstractGraphics2D.setTransform(java.awt.geom.AffineTransform)`, `AbstractGraphics2D.setComposite(java.awt.Composite)`, `AbstractGraphics2D.setClip(int, int, int, int)`

    - #### fill

          public void fill(java.awt.Shape s)

      Fills the interior of a `Shape` using the settings of the `Graphics2D` context. The rendering attributes applied include the `Clip`, `Transform`, `Paint`, and `Composite`.
      Specified by:
        `fill` in class `java.awt.Graphics2D`
      Parameters:
        `s` - the `Shape` to be filled
      See Also:
        `AbstractGraphics2D.setPaint(java.awt.Paint)`, `Graphics.setColor(java.awt.Color)`, `AbstractGraphics2D.transform(java.awt.geom.AffineTransform)`, `AbstractGraphics2D.setTransform(java.awt.geom.AffineTransform)`, `AbstractGraphics2D.setComposite(java.awt.Composite)`, `AbstractGraphics2D.clip(java.awt.Shape)`, `AbstractGraphics2D.setClip(int, int, int, int)`

    - #### doDrawing

          protected void doDrawing(boolean fill,
                       boolean stroke,
                       boolean nonzero)
                            throws java.io.IOException

      Commits a painting operation.
      Parameters:
        `fill` - filling
        `stroke` - stroking
        `nonzero` - true if the non-zero winding rule should be used when filling
      Throws:
        `java.io.IOException` - In case of an I/O problem

    - #### getDeviceConfiguration

          public java.awt.GraphicsConfiguration getDeviceConfiguration()

      Returns the device configuration associated with this `Graphics2D`.
      Specified by:
        `getDeviceConfiguration` in class `java.awt.Graphics2D`
      Returns:
        the device configuration

    - #### getFontMetrics

          public java.awt.FontMetrics getFontMetrics(java.awt.Font f)

      Gets the font metrics for the specified font.
      Specified by:
        `getFontMetrics` in class `java.awt.Graphics`
      Parameters:
        `f` - the specified font
      Returns:
        the font metrics for the specified font.
      See Also:
        `Graphics.getFont()`, `FontMetrics`, `Graphics.getFontMetrics()`

    - #### setXORMode

          public void setXORMode(java.awt.Color c1)

      Sets the paint mode of this graphics context to alternate between this graphics context's current color and the new specified color. This specifies that logical pixel operations are performed in the XOR mode, which alternates pixels between the current color and a specified XOR color.

      When drawing operations are performed, pixels which are the current color are changed to the specified color, and vice versa.

      Pixels that are of colors other than those two colors are changed in an unpredictable but reversible manner; if the same figure is drawn twice, then all pixels are restored to their original values.

      Specified by:
        `setXORMode` in class `java.awt.Graphics`
      Parameters:
        `c1` - the XOR alternation color

    - #### copyArea

          public void copyArea(int x,
                      int y,
                      int width,
                      int height,
                      int dx,
                      int dy)

      Copies an area of the component by a distance specified by `dx` and `dy`. From the point specified by `x` and `y`, this method copies downwards and to the right. To copy an area of the component to the left or upwards, specify a negative value for `dx` or `dy`. If a portion of the source rectangle lies outside the bounds of the component, or is obscured by another window or component, `copyArea` will be unable to copy the associated pixels. The area that is omitted can be refreshed by calling the component's `paint` method.
      Specified by:
        `copyArea` in class `java.awt.Graphics`
      Parameters:
        `x` - the x coordinate of the source rectangle.
        `y` - the y coordinate of the source rectangle.
        `width` - the width of the source rectangle.
        `height` - the height of the source rectangle.
        `dx` - the horizontal distance to copy the pixels.
        `dy` - the vertical distance to copy the pixels.