org.apache.fop.render.pdf

## Class PDFContentGenerator

- java.lang.Object
- - org.apache.fop.render.pdf.PDFContentGenerator

-     public class PDFContentGenerator
      extends Object

  Generator class encapsulating all object references and state necessary to generate a PDF content stream.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected PDFPaintingState` | `currentState` drawing state
    `protected PDFTextUtil` | `textutil` Text generation utility holding the current font status
    `protected static boolean` | `WRITE_COMMENTS` Controls whether comments are written to the PDF stream.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PDFContentGenerator(PDFDocument document, OutputStream out, PDFResourceContext resourceContext)` Main constructor.
    `PDFContentGenerator(PDFDocument document, OutputStream out, PDFResourceContext resourceContext, IFContext context)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(String content)` Adds content to the stream.
    `protected void` | `beginMarkedContentSequence(String structElemType, int mcid)` Begins a new marked content sequence (BDC or BMC).
    `protected void` | `beginMarkedContentSequence(String structElemType, int mcid, String actualText)` Begins a new marked content sequence (BDC or BMC).
    `protected void` | `beginTextObject()` Indicates the beginning of a text object.
    `protected void` | `beginTextObject(String structElemType, int mcid)` Indicates the beginning of a marked-content text object.
    `protected void` | `beginTextObject(String structElemType, int mcid, String actualText)` Indicates the beginning of a marked-content text object.
    `void` | `clipRect(Rectangle rect)` Intersects the current clip region with the given rectangle.
    `protected void` | `comment(String text)` Writes out a comment.
    `void` | `concatenate(AffineTransform transform)` Concatenates the given transformation matrix with the current one.
    `protected void` | `endTextObject()` Indicates the end of a text object.
    `void` | `flushPDFDoc()` Flushes all queued PDF objects ready to be written to the output stream.
    `static String` | `format(float value)` Formats a float value (normally coordinates in points) as Strings.
    `AffineTransform` | `getAffineTransform()`
    `PDFDocument` | `getDocument()` Returns the applicable resource context for the generator.
    `OutputStream` | `getOutputStream()` Returns the output stream the PDF document is written to.
    `PDFResourceContext` | `getResourceContext()` Returns the applicable resource context for the generator.
    `PDFPaintingState` | `getState()` Returns the `PDFPaintingState` associated with this instance.
    `PDFStream` | `getStream()` Returns the `PDFStream` associated with this instance.
    `PDFTextUtil` | `getTextUtil()` Returns the `PDFTextUtil` associated with this instance.
    `void` | `placeImage(AffineTransform at, String stream)`
    `void` | `placeImage(float x, float y, float w, float h, PDFXObject xobj)` Places a previously registered image at a certain place on the page.
    `void` | `placeImage(float x, float y, float w, float h, PDFXObject xobj, String structElemType, int mcid)` Places a previously registered image at a certain place on the page, bracketing it as a marked-content sequence.
    `void` | `resetCharacterSpacing()` Resets the current character spacing (Tc) value to zero.
    `protected void` | `restoreGraphicsState()` Same as `restoreGraphicsState(boolean)`, with `true` as a parameter.
    `protected void` | `restoreGraphicsState(boolean popState)` Restored the graphics state valid before the previous `saveGraphicsState()`.
    `protected void` | `restoreGraphicsStateAccess()` Same as `restoreGraphicsState()`, additionally ending the current marked content sequence if any.
    `protected void` | `saveGraphicsState()` Save graphics state.
    `protected void` | `saveGraphicsState(String layer)` Save graphics state with optional layer.
    `protected void` | `saveGraphicsState(String structElemType, int sequenceNum)` Save graphics state.
    `void` | `setColor(Color col, boolean fill)` Establishes a new foreground or fill color.
    `void` | `setColor(Color col, boolean fill, PDFStream stream)` Establishes a new foreground or fill color.
    `protected void` | `setColor(Color col, boolean fill, StringBuffer pdf)` Establishes a new foreground or fill color.
    `void` | `updateCharacterSpacing(float value)` Sets the current character spacing (Tc) value.
    `void` | `updateColor(Color col, boolean fill, StringBuffer pdf)` Establishes a new foreground or fill color.
    `void` | `updateLineWidth(float width)` Sets the current line width in points.

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

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

- - ### Field Detail

    - #### WRITE_COMMENTS

          protected static final boolean WRITE_COMMENTS

      Controls whether comments are written to the PDF stream.
      See Also:
        Constant Field Values

    - #### currentState

          protected PDFPaintingState currentState

      drawing state

    - #### textutil

          protected PDFTextUtil textutil

      Text generation utility holding the current font status

  - ### Constructor Detail

    - #### PDFContentGenerator

          public PDFContentGenerator(PDFDocument document,
                                     OutputStream out,
                                     PDFResourceContext resourceContext)

      Main constructor. Creates a new PDF stream and additional helper classes for text painting and state management.
      Parameters:
        `document` - the PDF document
        `out` - the output stream the PDF document is generated to
        `resourceContext` - the resource context

    - #### PDFContentGenerator

          public PDFContentGenerator(PDFDocument document,
                                     OutputStream out,
                                     PDFResourceContext resourceContext,
                                     IFContext context)

  - ### Method Detail

    - #### getAffineTransform

          public AffineTransform getAffineTransform()

    - #### getDocument

          public PDFDocument getDocument()

      Returns the applicable resource context for the generator.
      Returns:
        the resource context

    - #### getOutputStream

          public OutputStream getOutputStream()

      Returns the output stream the PDF document is written to.
      Returns:
        the output stream

    - #### getResourceContext

          public PDFResourceContext getResourceContext()

      Returns the applicable resource context for the generator.
      Returns:
        the resource context

    - #### getStream

          public PDFStream getStream()

      Returns the `PDFStream` associated with this instance.
      Returns:
        the PDF stream

    - #### getState

          public PDFPaintingState getState()

      Returns the `PDFPaintingState` associated with this instance.
      Returns:
        the PDF state

    - #### getTextUtil

          public PDFTextUtil getTextUtil()

      Returns the `PDFTextUtil` associated with this instance.
      Returns:
        the text utility

    - #### flushPDFDoc

          public void flushPDFDoc()
                           throws IOException

      Flushes all queued PDF objects ready to be written to the output stream.
      Throws:
        `IOException` - if an error occurs while flushing the PDF objects

    - #### comment

          protected void comment(String text)

      Writes out a comment.
      Parameters:
        `text` - text for the comment

    - #### saveGraphicsState

          protected void saveGraphicsState()

      Save graphics state.

    - #### saveGraphicsState

          protected void saveGraphicsState(String layer)

      Save graphics state with optional layer.

    - #### saveGraphicsState

          protected void saveGraphicsState(String structElemType,
                                           int sequenceNum)

      Save graphics state.
      Parameters:
        `structElemType` - an element type
        `sequenceNum` - a sequence number

    - #### beginMarkedContentSequence

          protected void beginMarkedContentSequence(String structElemType,
                                                    int mcid)

      Begins a new marked content sequence (BDC or BMC). If `structElemType` is null, a BMC operator with an "Artifact" tag is generated. Otherwise, a BDC operator with `structElemType` as a tag is generated, and the given mcid stored in its property list.
      Parameters:
        `structElemType` - the type of the associated structure element
        `mcid` - the marked content identifier

    - #### beginMarkedContentSequence

          protected void beginMarkedContentSequence(String structElemType,
                                                    int mcid,
                                                    String actualText)

      Begins a new marked content sequence (BDC or BMC). If `structElemType` is null, a BMC operator with an "Artifact" tag is generated. Otherwise, a BDC operator with `structElemType` as a tag is generated, and the given mcid and actual text are stored in its property list.
      Parameters:
        `structElemType` - the type of the associated structure element
        `mcid` - the marked content identifier
        `actualText` - the replacement text for the marked content

    - #### restoreGraphicsState

          protected void restoreGraphicsState(boolean popState)

      Restored the graphics state valid before the previous `saveGraphicsState()`.
      Parameters:
        `popState` - true if the state should also be popped, false if only the PDF command should be issued

    - #### restoreGraphicsState

          protected void restoreGraphicsState()

      Same as `restoreGraphicsState(boolean)`, with `true` as a parameter.

    - #### restoreGraphicsStateAccess

          protected void restoreGraphicsStateAccess()

      Same as `restoreGraphicsState()`, additionally ending the current marked content sequence if any.

    - #### beginTextObject

          protected void beginTextObject()

      Indicates the beginning of a text object.

    - #### beginTextObject

          protected void beginTextObject(String structElemType,
                                         int mcid)

      Indicates the beginning of a marked-content text object.
      Parameters:
        `structElemType` - structure element type
        `mcid` - sequence number
      See Also:
        `beginTextObject()`, `beginMarkedContentSequence(String, int)`

    - #### beginTextObject

          protected void beginTextObject(String structElemType,
                                         int mcid,
                                         String actualText)

      Indicates the beginning of a marked-content text object.
      Parameters:
        `structElemType` - structure element type
        `mcid` - sequence number
        `actualText` - the replacement text for the marked content
      See Also:
        `beginTextObject()`, `beginMarkedContentSequence(java.lang.String, int)`

    - #### endTextObject

          protected void endTextObject()

      Indicates the end of a text object.

    - #### concatenate

          public void concatenate(AffineTransform transform)

      Concatenates the given transformation matrix with the current one.
      Parameters:
        `transform` - the transformation matrix (in points)

    - #### clipRect

          public void clipRect(Rectangle rect)

      Intersects the current clip region with the given rectangle.
      Parameters:
        `rect` - the clip rectangle

    - #### add

          public void add(String content)

      Adds content to the stream.
      Parameters:
        `content` - the PDF content

    - #### format

          public static final String format(float value)

      Formats a float value (normally coordinates in points) as Strings.
      Parameters:
        `value` - the value
      Returns:
        the formatted value

    - #### updateLineWidth

          public void updateLineWidth(float width)

      Sets the current line width in points.
      Parameters:
        `width` - line width in points

    - #### updateCharacterSpacing

          public void updateCharacterSpacing(float value)

      Sets the current character spacing (Tc) value.
      Parameters:
        `value` - the Tc value (in unscaled text units)

    - #### resetCharacterSpacing

          public void resetCharacterSpacing()

      Resets the current character spacing (Tc) value to zero.

    - #### setColor

          public void setColor(Color col,
                               boolean fill,
                               PDFStream stream)

      Establishes a new foreground or fill color.
      Parameters:
        `col` - the color to apply
        `fill` - true to set the fill color, false for the foreground color
        `stream` - the PDFStream to write the PDF code to

    - #### setColor

          public void setColor(Color col,
                               boolean fill)

      Establishes a new foreground or fill color.
      Parameters:
        `col` - the color to apply
        `fill` - true to set the fill color, false for the foreground color

    - #### setColor

          protected void setColor(Color col,
                                  boolean fill,
                                  StringBuffer pdf)

      Establishes a new foreground or fill color. In contrast to updateColor this method does not check the PDFState for optimization possibilities.
      Parameters:
        `col` - the color to apply
        `fill` - true to set the fill color, false for the foreground color
        `pdf` - StringBuffer to write the PDF code to, if null, the code is written to the current stream.

    - #### updateColor

          public void updateColor(Color col,
                                  boolean fill,
                                  StringBuffer pdf)

      Establishes a new foreground or fill color.
      Parameters:
        `col` - the color to apply (null skips this operation)
        `fill` - true to set the fill color, false for the foreground color
        `pdf` - StringBuffer to write the PDF code to, if null, the code is written to the current stream.

    - #### placeImage

          public void placeImage(float x,
                                 float y,
                                 float w,
                                 float h,
                                 PDFXObject xobj)

      Places a previously registered image at a certain place on the page.
      Parameters:
        `x` - X coordinate
        `y` - Y coordinate
        `w` - width for image
        `h` - height for image
        `xobj` - the image XObject

    - #### placeImage

          public void placeImage(AffineTransform at,
                                 String stream)

    - #### placeImage

          public void placeImage(float x,
                                 float y,
                                 float w,
                                 float h,
                                 PDFXObject xobj,
                                 String structElemType,
                                 int mcid)

      Places a previously registered image at a certain place on the page, bracketing it as a marked-content sequence.
      Parameters:
        `x` - X coordinate
        `y` - Y coordinate
        `w` - width for image
        `h` - height for image
        `xobj` - the image XObject
        `structElemType` - structure element type
        `mcid` - sequence number
      See Also:
        `beginMarkedContentSequence(String, int)`

Copyright © 2023 Apache Software Foundation. All rights reserved.