RtfExternalGraphic (Apache FOP 2.7 API)
Date: 2022-01-12

org.apache.fop.render.rtf.rtflib.rtfdoc

## Class RtfExternalGraphic

- java.lang.Object
- - org.apache.fop.render.rtf.rtflib.rtfdoc.RtfElement
  - - org.apache.fop.render.rtf.rtflib.rtfdoc.RtfExternalGraphic

-     public class RtfExternalGraphic
      extends RtfElement

  Creates an RTF image from an external graphic file. This class belongs to the fo:external-graphic tag processing.
  Supports relative path like "../test.gif", too (01-08-24)
  Limitations: Only the image types PNG, JPEG and EMF are supported The GIF is supported, too, but will be converted to JPG Only the attributes SRC (required), WIDTH, HEIGHT, SCALING are supported The SCALING attribute supports (uniform | non-uniform) Known Bugs: If the emf image has a desired size, the image will be clipped The emf, jpg, png image will not be displayed in correct size This work was originally authored by Andreas Putz This work was originally authored by Gianugo Rabellino gianugo@rabellino.it

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `RtfExternalGraphic.ExternalGraphicException` Exception thrown when an image file/URL cannot be read

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `graphicCompressionRate` Graphic compression rate
    `protected int` | `height` The height of the image (in pixels)
    `protected int` | `heightDesired` The desired height (in twips)
    `protected boolean` | `perCentH` Flag whether the desired height is a percentage
    `protected boolean` | `perCentW` Flag whether the desired width is a percentage
    `protected boolean` | `scaleUniform` Flag whether the image size shall be adjusted
    `protected java.net.URL` | `url` The url of the image
    `protected int` | `width` The width of the image (in pixels)
    `protected int` | `widthDesired` The desired width (in twips)

    - ### Fields inherited from class org.apache.fop.render.rtf.rtflib.rtfdoc.RtfElement

      `attrib, parent, writer`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RtfExternalGraphic(RtfContainer container, java.io.Writer writer)` Default constructor.
    `RtfExternalGraphic(RtfContainer container, java.io.Writer writer, RtfAttributes attributes)` Default constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getCompressionRate()` Gets the compression rate for the image in percent.
    `boolean` | `isEmpty()`
    `boolean` | `setCompressionRate(int percent)` Sets the compression rate for the image in percent.
    `void` | `setCropping(int left, int top, int right, int bottom)` Sets cropping values for all four edges for the \piccrop*N commands.
    `void` | `setHeight(java.lang.String theHeight)` Sets the desired height of the image.
    `void` | `setHeightTwips(int twips)` Sets the desired height of the image.
    `void` | `setImageData(byte[] data)` Sets the binary imagedata of the image.
    `void` | `setScaling(java.lang.String value)` Sets the flag whether the image size shall be adjusted.
    `void` | `setUniformScaling(boolean uniform)` Sets the flag whether the image size shall be adjusted.
    `void` | `setURL(java.lang.String urlString)` Sets the url of the image.
    `void` | `setWidth(java.lang.String theWidth)` Sets the desired width of the image.
    `void` | `setWidthTwips(int twips)` Sets the desired width of the image.
    `protected void` | `writeRtfContent()` RtfElement override - catches ExternalGraphicException and writes a warning message to the document if image cannot be read
    `protected void` | `writeRtfContentWithException()` Writes the RTF content to m_writer - this one throws ExternalGraphicExceptions

    - ### Methods inherited from class org.apache.fop.render.rtf.rtflib.rtfdoc.RtfElement

      `close, getParentOfClass, getRtfAttributes, newLine, okToWriteRtf, toString, writeAttributes, writeControlWord, writeControlWordNS, writeExceptionInRtf, writeGroupMark, writeOneAttribute, writeOneAttributeNS, writeRtf, writeRtfPrefix, writeRtfSuffix, writeStarControlWord, writeStarControlWordNS`

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

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

- - ### Field Detail

    - #### url

          protected java.net.URL url

      The url of the image

    - #### height

          protected int height

      The height of the image (in pixels)

    - #### heightDesired

          protected int heightDesired

      The desired height (in twips)

    - #### perCentH

          protected boolean perCentH

      Flag whether the desired height is a percentage

    - #### width

          protected int width

      The width of the image (in pixels)

    - #### widthDesired

          protected int widthDesired

      The desired width (in twips)

    - #### perCentW

          protected boolean perCentW

      Flag whether the desired width is a percentage

    - #### scaleUniform

          protected boolean scaleUniform

      Flag whether the image size shall be adjusted

    - #### graphicCompressionRate

          protected int graphicCompressionRate

      Graphic compression rate

  - ### Constructor Detail

    - #### RtfExternalGraphic

          public RtfExternalGraphic(RtfContainer container,
                                    java.io.Writer writer)
                             throws java.io.IOException

      Default constructor. Create an RTF element as a child of given container.
      Parameters:
        `container` - a `RtfContainer` value
        `writer` - a `Writer` value
      Throws:
        `java.io.IOException` - for I/O problems

    - #### RtfExternalGraphic

          public RtfExternalGraphic(RtfContainer container,
                                    java.io.Writer writer,
                                    RtfAttributes attributes)
                             throws java.io.IOException

      Default constructor.
      Parameters:
        `container` - a `RtfContainer` value
        `writer` - a `Writer` value
        `attributes` - a `RtfAttributes` value
      Throws:
        `java.io.IOException` - for I/O problems

  - ### Method Detail

    - #### writeRtfContent

          protected void writeRtfContent()
                                  throws java.io.IOException

      RtfElement override - catches ExternalGraphicException and writes a warning message to the document if image cannot be read
      Specified by:
        `writeRtfContent` in class `RtfElement`
      Throws:
        `java.io.IOException` - for I/O problems

    - #### writeRtfContentWithException

          protected void writeRtfContentWithException()
                                               throws java.io.IOException

      Writes the RTF content to m_writer - this one throws ExternalGraphicExceptions
      Throws:
        `java.io.IOException` - On error

    - #### setHeight

          public void setHeight(java.lang.String theHeight)

      Sets the desired height of the image.
      Parameters:
        `theHeight` - The desired image height (as a string in twips or as a percentage)

    - #### setWidth

          public void setWidth(java.lang.String theWidth)

      Sets the desired width of the image.
      Parameters:
        `theWidth` - The desired image width (as a string in twips or as a percentage)

    - #### setWidthTwips

          public void setWidthTwips(int twips)

      Sets the desired width of the image.
      Parameters:
        `twips` - The desired image width (in twips)

    - #### setHeightTwips

          public void setHeightTwips(int twips)

      Sets the desired height of the image.
      Parameters:
        `twips` - The desired image height (in twips)

    - #### setScaling

          public void setScaling(java.lang.String value)

      Sets the flag whether the image size shall be adjusted.
      Parameters:
        `value` - true image width or height shall be adjusted automatically\n false no adjustment

    - #### setUniformScaling

          public void setUniformScaling(boolean uniform)

      Sets the flag whether the image size shall be adjusted.
      Parameters:
        `uniform` - true image width or height shall be adjusted automatically\n false no adjustment

    - #### setCropping

          public void setCropping(int left,
                                  int top,
                                  int right,
                                  int bottom)

      Sets cropping values for all four edges for the \piccrop*N commands. A positive value crops toward the center of the picture; a negative value crops away from the center, adding a space border around the picture
      Parameters:
        `left` - left cropping value (in twips)
        `top` - top cropping value (in twips)
        `right` - right cropping value (in twips)
        `bottom` - bottom cropping value (in twips)

    - #### setImageData

          public void setImageData(byte[] data)
                            throws java.io.IOException

      Sets the binary imagedata of the image.
      Parameters:
        `data` - binary imagedata as read from file.
      Throws:
        `java.io.IOException` - On error

    - #### setURL

          public void setURL(java.lang.String urlString)
                      throws java.io.IOException

      Sets the url of the image.
      Parameters:
        `urlString` - Image url like "file://..."
      Throws:
        `java.io.IOException` - On error

    - #### getCompressionRate

          public int getCompressionRate()

      Gets the compression rate for the image in percent.
      Returns:
        Compression rate

    - #### setCompressionRate

          public boolean setCompressionRate(int percent)

      Sets the compression rate for the image in percent.
      Parameters:
        `percent` - Compression rate
      Returns:
        true if the compression rate is valid (0..100), false if invalid

    - #### isEmpty

          public boolean isEmpty()

      Specified by:
        `isEmpty` in class `RtfElement`
      Returns:
        true if this element would generate no "useful" RTF content

Copyright 1999-2022 The Apache Software Foundation. All Rights Reserved.