com.lowagie.text.rtf.document

## Class RtfDocumentSettings

- java.lang.Object
- - com.lowagie.text.rtf.document.RtfDocumentSettings

-     public class RtfDocumentSettings
      extends java.lang.Object

  The RtfDocumentSettings contains output specific settings. These settings modify how the actual document is then generated and some settings may mean that some RTF readers can't read the document or render it wrongly.
  Version:
    $Id$
  Author:
    Mark Hall (Mark.Hall@mail.room3b.eu), Thomas Bickel (tmb99@inode.at), Howard Shank (hgshank@yahoo.com)

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private boolean` | `alwaysGenerateSoftLinebreaks` Whether to always generate soft linebreaks for \n in Chunks.
    `private boolean` | `alwaysUseUnicode` Whether to always translate characters past 'z' into unicode representations.
    `private int` | `dataCacheStyle` How to cache the document during generation.
    `private RtfDocument` | `document` The RtfDocument this RtfDocumentSettings belongs to.
    `private boolean` | `imagePDFConformance` Whether images should be written in order to mimick the PDF output.
    `private boolean` | `imageWrittenAsBinary` Images are written as binary data and not hex encoded.
    `private boolean` | `outputDebugLineBreaks` Whether to output the line breaks that make the rtf document source more readable.
    `private boolean` | `outputTableRowDefinitionAfter` Whether to also output the table row definition after the cell content.
    `private java.lang.String` | `protectionHash` Document protection level password hash.
    `private int` | `protectionLevel` Document protection level.
    `private boolean` | `readOnlyRecommended` Document recommended to be opened in read only mode.
    `private boolean` | `writeImageScalingInformation` Whether to write image scaling information.
    `private java.lang.String` | `writereservhash` Document read password hash.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RtfDocumentSettings(RtfDocument document)` Constructs a new RtfDocumentSettings object.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `private int` | `convertProtectionLevel()` Converts protection level from internal bitmap value to protlevel output value.
    `int` | `getDataCacheStyle()` Gets the current data cache style.
    `byte[]` | `getProtectionHashBytes()` Obtain the password has as a byte array.
    `int` | `getProtectionLevel()` Author: Howard Shank (hgshank@yahoo.com)
    `byte[]` | `getProtectionLevelBytes()` Author: Howard Shank (hgshank@yahoo.com)
    `int` | `getProtectionLevelRaw()` Author: Howard Shank (hgshank@yahoo.com)
    `boolean` | `getReadOnlyRecommended()` Get the RTF flag that recommends if the the document should be opened in read only mode.
    `boolean` | `isAlwaysGenerateSoftLinebreaks()` Gets whether all linebreaks inside Chunks are generated as soft linebreaks.
    `boolean` | `isAlwaysUseUnicode()` Gets whether all characters bigger than 'z' are represented as unicode.
    `boolean` | `isDocumentProtected()` Determine if document has protection enabled.
    `boolean` | `isImagePDFConformance()` Gets the current setting on image PDF conformance.
    `boolean` | `isImageWrittenAsBinary()` Gets whether images are written as binary data or are hex encoded.
    `boolean` | `isOutputDebugLineBreaks()` Gets whether to output the line breaks for increased rtf document readability.
    `boolean` | `isOutputTableRowDefinitionAfter()` Gets whether the table row definition should also be written after the cell content.
    `boolean` | `isWriteImageScalingInformation()` Gets whether to write scaling information for images.
    `void` | `registerParagraphStyle(RtfParagraphStyle rtfParagraphStyle)` Registers the RtfParagraphStyle for further use in the document.
    `void` | `setAlwaysGenerateSoftLinebreaks(boolean alwaysGenerateSoftLinebreaks)` Sets whether to always generate soft linebreaks.
    `void` | `setAlwaysUseUnicode(boolean alwaysUseUnicode)` Sets whether to represent all characters bigger than 'z' as unicode.
    `void` | `setDataCacheStyle(int dataCacheStyle)` Sets the data cache style.
    `void` | `setImagePDFConformance(boolean imagePDFConformance)` Sets the image PDF conformance setting.
    `void` | `setImageWrittenAsBinary(boolean imageWrittenAsBinary)` Set whether images are written as binary data or are hex encoded.
    `boolean` | `setNewPassword(java.lang.String oldPwd, java.lang.String newPwd)` Author: Howard Shank (hgshank@yahoo.com)
    `void` | `setOptionsForMSWord2000And97()` Set the options required for RTF documents to display correctly in MS Word 2000 and MS Word 97.
    `void` | `setOptionsForMSWordForMac()` Set the options required for RTF documents to display correctly in MS Word for Mac.
    `void` | `setOptionsForMSWordXP()` Set the options required for RTF documents to display correctly in MS Word XP (2002).
    `void` | `setOptionsForOpenOfficeOrg()` Set the options required for RTF documents to display correctly in OpenOffice.Org Writer.
    `void` | `setOutputDebugLineBreaks(boolean outputDebugLineBreaks)` Sets whether to output the line breaks for increased rtf document readability.
    `void` | `setOutputTableRowDefinitionAfter(boolean outputTableRowDefinitionAfter)` Sets whether the table row definition should also be written after the cell content.
    `void` | `setPasswordHash(java.lang.String pwd)` This function is not intended for general use.
    `boolean` | `setProtection(int level, java.lang.String pwd)` Author: Howard Shank (hgshank@yahoo.com)
    `boolean` | `setProtectionLevel(int level)` Author: Howard Shank (hgshank@yahoo.com)
    `void` | `setReadOnlyRecommended(boolean value)` Set the RTF flag that recommends the document be opened in read only mode.
    `void` | `setWriteImageScalingInformation(boolean writeImageScalingInformation)` Sets whether image scaling information should be written.
    `boolean` | `unprotectDocument(java.lang.String pwd)` Author: Howard Shank (hgshank@yahoo.com)

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

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

- - ### Field Detail

    - #### document

          private RtfDocument document

      The RtfDocument this RtfDocumentSettings belongs to.

    - #### outputTableRowDefinitionAfter

          private boolean outputTableRowDefinitionAfter

      Whether to also output the table row definition after the cell content.

    - #### outputDebugLineBreaks

          private boolean outputDebugLineBreaks

      Whether to output the line breaks that make the rtf document source more readable.

    - #### alwaysGenerateSoftLinebreaks

          private boolean alwaysGenerateSoftLinebreaks

      Whether to always generate soft linebreaks for \n in Chunks.

    - #### alwaysUseUnicode

          private boolean alwaysUseUnicode

      Whether to always translate characters past 'z' into unicode representations.

    - #### dataCacheStyle

          private int dataCacheStyle

      How to cache the document during generation. Defaults to RtfDataCache.CACHE_MEMORY;

    - #### writeImageScalingInformation

          private boolean writeImageScalingInformation

      Whether to write image scaling information. This is required for Word 2000, 97 and Word for Mac

    - #### imagePDFConformance

          private boolean imagePDFConformance

      Whether images should be written in order to mimick the PDF output.

    - #### protectionLevel

          private int protectionLevel

      Document protection level. Author: Howard Shank (hgshank@yahoo.com)
      Since:
        2.1.1

    - #### protectionHash

          private java.lang.String protectionHash

      Document protection level password hash. Author: Howard Shank (hgshank@yahoo.com)
      Since:
        2.1.1

    - #### writereservhash

          private java.lang.String writereservhash

      Document read password hash. Author: Howard Shank (hgshank@yahoo.com)
      Since:
        2.1.1

    - #### readOnlyRecommended

          private boolean readOnlyRecommended

      Document recommended to be opened in read only mode. Author: Howard Shank (hgshank@yahoo.com)
      Since:
        2.1.1

    - #### imageWrittenAsBinary

          private boolean imageWrittenAsBinary

      Images are written as binary data and not hex encoded. Author: Mark Hall (Mark.Hall@mail.room3b.eu)
      Since:
        2.1.1

  - ### Constructor Detail

    - #### RtfDocumentSettings

          public RtfDocumentSettings(RtfDocument document)

      Constructs a new RtfDocumentSettings object.
      Parameters:
        `document` - The RtfDocument this RtfDocumentSettings belong to.

  - ### Method Detail

    - #### isOutputDebugLineBreaks

          public boolean isOutputDebugLineBreaks()

      Gets whether to output the line breaks for increased rtf document readability.
      Returns:
        Whether to output line breaks.

    - #### setOutputDebugLineBreaks

          public void setOutputDebugLineBreaks(boolean outputDebugLineBreaks)

      Sets whether to output the line breaks for increased rtf document readability. Some line breaks may be added where the rtf specification demands it.
      Parameters:
        `outputDebugLineBreaks` - The outputDebugLineBreaks to set.

    - #### isOutputTableRowDefinitionAfter

          public boolean isOutputTableRowDefinitionAfter()

      Gets whether the table row definition should also be written after the cell content.
      Returns:
        Returns the outputTableRowDefinitionAfter.

    - #### setOutputTableRowDefinitionAfter

          public void setOutputTableRowDefinitionAfter(boolean outputTableRowDefinitionAfter)

      Sets whether the table row definition should also be written after the cell content. This is recommended to be set to `true` if you need Word2000 compatiblity and `false` if the document should be opened in OpenOffice.org Writer.
      Parameters:
        `outputTableRowDefinitionAfter` - The outputTableRowDefinitionAfter to set.

    - #### isAlwaysGenerateSoftLinebreaks

          public boolean isAlwaysGenerateSoftLinebreaks()

      Gets whether all linebreaks inside Chunks are generated as soft linebreaks.
      Returns:
        `True` if soft linebreaks are generated, `false` for hard linebreaks.

    - #### setAlwaysGenerateSoftLinebreaks

          public void setAlwaysGenerateSoftLinebreaks(boolean alwaysGenerateSoftLinebreaks)

      Sets whether to always generate soft linebreaks.
      Parameters:
        `alwaysGenerateSoftLinebreaks` - Whether to always generate soft linebreaks.

    - #### isAlwaysUseUnicode

          public boolean isAlwaysUseUnicode()

      Gets whether all characters bigger than 'z' are represented as unicode.
      Returns:
        `True` if unicode representation is used, `false` otherwise.

    - #### setAlwaysUseUnicode

          public void setAlwaysUseUnicode(boolean alwaysUseUnicode)

      Sets whether to represent all characters bigger than 'z' as unicode.
      Parameters:
        `alwaysUseUnicode` - `True` to use unicode representation, `false` otherwise.

    - #### registerParagraphStyle

          public void registerParagraphStyle(RtfParagraphStyle rtfParagraphStyle)

      Registers the RtfParagraphStyle for further use in the document. This does not need to be done for the default styles in the RtfParagraphStyle object. Those are added automatically.
      Parameters:
        `rtfParagraphStyle` - The RtfParagraphStyle to register.

    - #### setDataCacheStyle

          public void setDataCacheStyle(int dataCacheStyle)

      Sets the data cache style. This controls where the document is cached during generation. Two cache styles are supported:
      - RtfDataCache.CACHE_MEMORY: The document is cached in memory. This is fast, but places a limit on how big the document can get before causing OutOfMemoryExceptions.
      - RtfDataCache.CACHE_DISK: The document is cached on disk. This is slower than the CACHE_MEMORY setting, but the document size is now only constrained by the amount of free disk space.
      Parameters:
        `dataCacheStyle` - The data cache style to set. Valid constants can be found in RtfDataCache.
      See Also:
        `RtfDataCache`

    - #### getDataCacheStyle

          public int getDataCacheStyle()

      Gets the current data cache style.
      Returns:
        The current data cache style.

    - #### isImagePDFConformance

          public boolean isImagePDFConformance()

      Gets the current setting on image PDF conformance.
      Returns:
        The current image PDF conformance.

    - #### setImagePDFConformance

          public void setImagePDFConformance(boolean imagePDFConformance)

      Sets the image PDF conformance setting. By default images will be added as if they were displayed with 72dpi. Set this to `false` if images should be generated with the Word default DPI setting.
      Parameters:
        `imagePDFConformance` - `True` if PDF equivalence is desired, `false` for the default Word display.

    - #### isWriteImageScalingInformation

          public boolean isWriteImageScalingInformation()

      Gets whether to write scaling information for images.
      Returns:
        Whether to write scaling information for images.

    - #### setWriteImageScalingInformation

          public void setWriteImageScalingInformation(boolean writeImageScalingInformation)

      Sets whether image scaling information should be written. This needs to be set to `true` MS Word 2000, MS Word 97 and Word for Mac.
      Parameters:
        `writeImageScalingInformation` - Whether to write image scaling information.

    - #### setOptionsForMSWord2000And97

          public void setOptionsForMSWord2000And97()

      Set the options required for RTF documents to display correctly in MS Word 2000 and MS Word 97. Sets `outputTableRowDefinitionAfter = true` and `writeImageScalingInformation = true`.

    - #### setOptionsForMSWordForMac

          public void setOptionsForMSWordForMac()

      Set the options required for RTF documents to display correctly in MS Word for Mac. Sets `writeImageScalingInformation = true`.

    - #### setOptionsForMSWordXP

          public void setOptionsForMSWordXP()

      Set the options required for RTF documents to display correctly in MS Word XP (2002). Sets `writeImageScalingInformation = false`.

    - #### setOptionsForOpenOfficeOrg

          public void setOptionsForOpenOfficeOrg()

      Set the options required for RTF documents to display correctly in OpenOffice.Org Writer. Sets `outputTableRowDefinitionAfter = false`.

    - #### setProtection

          public boolean setProtection(int level,
                              java.lang.String pwd)

      Author: Howard Shank (hgshank@yahoo.com)
      Parameters:
        `level` - Document protecton level
        `pwd` - Document password - clear text
      Since:
        2.1.1

    - #### unprotectDocument

          public boolean unprotectDocument(java.lang.String pwd)

      Author: Howard Shank (hgshank@yahoo.com)
      Parameters:
        `pwd` - Document password - clear text
      Returns:
        true if document unprotected, false if protection is not removed.
      Since:
        2.1.1

    - #### setProtectionLevel

          public boolean setProtectionLevel(int level)

      Author: Howard Shank (hgshank@yahoo.com)
      Parameters:
        `level` - Document protection level
      Since:
        2.1.1

    - #### setPasswordHash

          public void setPasswordHash(java.lang.String pwd)

      This function is not intended for general use. Please see 'public boolean setProtection(int level, String pwd)'. Author: Howard Shank (hgshank@yahoo.com)
      Parameters:
        `pwd` - Password HASH to set the document password hash to.
      Since:
        2.1.1

    - #### convertProtectionLevel

          private int convertProtectionLevel()

      Converts protection level from internal bitmap value to protlevel output value. Author: Howard Shank (hgshank@yahoo.com)
      Returns:

             0 = Revision protection
             1 = Annotation/Comment protection
             2 = Form protection
             3 = Read only protection

      Since:
        2.1.1

    - #### getProtectionLevelRaw

          public int getProtectionLevelRaw()

      Author: Howard Shank (hgshank@yahoo.com)
      Returns:
        RTF document protection level
      Since:
        2.1.1

    - #### getProtectionLevel

          public int getProtectionLevel()

      Author: Howard Shank (hgshank@yahoo.com)
      Returns:
        RTF document protection level
      Since:
        2.1.1

    - #### getProtectionLevelBytes

          public byte[] getProtectionLevelBytes()

      Author: Howard Shank (hgshank@yahoo.com)
      Returns:
        RTF document protection level as a byte array (byte[])
      Since:
        2.1.1

    - #### setNewPassword

          public boolean setNewPassword(java.lang.String oldPwd,
                               java.lang.String newPwd)

      Author: Howard Shank (hgshank@yahoo.com)
      Parameters:
        `oldPwd` - Old password - clear text
        `newPwd` - New password - clear text
      Returns:
        true if password set, false if password not set
      Since:
        2.1.1

    - #### setReadOnlyRecommended

          public void setReadOnlyRecommended(boolean value)

      Set the RTF flag that recommends the document be opened in read only mode. Author: Howard Shank (hgshank@yahoo.com)
      Parameters:
        `value` - true if the flag is to be set, false if it is NOT to be set
      Since:
        2.1.1

    - #### getReadOnlyRecommended

          public boolean getReadOnlyRecommended()

      Get the RTF flag that recommends if the the document should be opened in read only mode. Author: Howard Shank (hgshank@yahoo.com)
      Returns:
        true if flag is set, false if it is not set
      Since:
        2.1.1

    - #### isDocumentProtected

          public boolean isDocumentProtected()

      Determine if document has protection enabled. Author: Howard Shank (hgshank@yahoo.com)
      Returns:
        true if protection is enabled, false if it is not enabled
      Since:
        2.1.1

    - #### getProtectionHashBytes

          public byte[] getProtectionHashBytes()

      Obtain the password has as a byte array. Author: Howard Shank (hgshank@yahoo.com)
      Returns:
        The bytes of the password hash as a byte array (byte[])
      Since:
        2.1.1

    - #### setImageWrittenAsBinary

          public void setImageWrittenAsBinary(boolean imageWrittenAsBinary)

      Set whether images are written as binary data or are hex encoded. Author: Mark Hall (Mark.Hall@mail.room3b.eu)
      Parameters:
        `imageWrittenAsBinary` - `True` to write images as binary data, `false` for hex encoding.
      Since:
        2.1.1

    - #### isImageWrittenAsBinary

          public boolean isImageWrittenAsBinary()

      Gets whether images are written as binary data or are hex encoded. Defaults to `true`. Author: Mark Hall (Mark.Hall@mail.room3b.eu)
      Returns:
        `True` if images are written as binary data, `false` if hex encoded.
      Since:
        2.1.1