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 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 authored by Andreas Putz (a.putz@skynamics.com) and 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-2015 The Apache Software Foundation. All Rights Reserved.