org.apache.poi.xwpf.usermodel

## Class XWPFSettings

- java.lang.Object
- - org.apache.poi.ooxml.POIXMLDocumentPart
  - - org.apache.poi.xwpf.usermodel.XWPFSettings

-     public class XWPFSettings
      extends POIXMLDocumentPart

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.apache.poi.ooxml.POIXMLDocumentPart

      `POIXMLDocumentPart.RelationPart`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XWPFSettings()`
    `XWPFSettings(PackagePart part)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `commit()` Save the content in the underlying package part.
    `boolean` | `getEvenAndOddHeadings()` Check if separate even and odd headings is turned on.
    `boolean` | `getMirrorMargins()` Check if mirrored margins is turned on
    `long` | `getZoomPercent()` Set zoom. In the zoom tag inside settings.xml file it sets the value of zoom sample snippet from settings.xml
    `boolean` | `isEnforcedWith()` Verifies the documentProtection tag inside settings.xml file if the protection is enforced (w:enforcement="1")
    `boolean` | `isEnforcedWith(org.openxmlformats.schemas.wordprocessingml.x2006.main.STDocProtect.Enum editValue)` Verifies the documentProtection tag inside settings.xml file if the protection is enforced (w:enforcement="1") and if the kind of protection equals to passed (STDocProtect.Enum editValue)
    `boolean` | `isTrackRevisions()` Check if revision tracking is turned on.
    `protected void` | `onDocumentRead()` Fired when a package part is read
    `void` | `removeEnforcement()` Removes protection enforcement. In the documentProtection tag inside settings.xml file it sets the value of enforcement to "0" (w:enforcement="0")
    `void` | `setEnforcementEditValue(org.openxmlformats.schemas.wordprocessingml.x2006.main.STDocProtect.Enum editValue)` Enforces the protection with the option specified by passed editValue. In the documentProtection tag inside settings.xml file it sets the value of enforcement to "1" (w:enforcement="1") and the value of edit to the passed editValue (w:edit="[passed editValue]") sample snippet from settings.xml
    `void` | `setEnforcementEditValue(org.openxmlformats.schemas.wordprocessingml.x2006.main.STDocProtect.Enum editValue, java.lang.String password, HashAlgorithm hashAlgo)` Enforces the protection with the option specified by passed editValue and password. sample snippet from settings.xml
    `void` | `setEvenAndOddHeadings(boolean enable)` Turn separate even-and-odd headings on or off
    `void` | `setMirrorMargins(boolean enable)` Turn mirrored margins on or off
    `void` | `setTrackRevisions(boolean enable)` Enable or disable revision tracking.
    `void` | `setUpdateFields()` Enforces fields update on document open (in Word).
    `void` | `setZoomPercent(long zoomPercent)` Set zoom. In the zoom tag inside settings.xml file it sets the value of zoom sample snippet from settings.xml
    `boolean` | `validateProtectionPassword(java.lang.String password)` Validates the existing password

    - ### Methods inherited from class org.apache.poi.ooxml.POIXMLDocumentPart

      `_invokeOnDocumentRead, addRelation, createRelationship, createRelationship, createRelationship, getNextPartNumber, getPackagePart, getParent, getRelationById, getRelationId, getRelationPartById, getRelationParts, getRelations, getTargetPart, isCommited, isCommitted, onDocumentCreate, onDocumentRemove, onSave, prepareForCommit, read, rebase, removeRelation, removeRelation, removeRelation, setCommited, setCommitted, toString`

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

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

- - ### Constructor Detail

    - #### XWPFSettings

          public XWPFSettings(PackagePart part)
                       throws java.io.IOException

      Throws:
        `java.io.IOException`
      Since:
        POI 3.14-Beta1

    - #### XWPFSettings

          public XWPFSettings()

  - ### Method Detail

    - #### onDocumentRead

          protected void onDocumentRead()
                                 throws java.io.IOException

      Description copied from class: `POIXMLDocumentPart`
      Fired when a package part is read
      Overrides:
        `onDocumentRead` in class `POIXMLDocumentPart`
      Throws:
        `java.io.IOException` - a subclass may throw an IOException when a document is read

    - #### getZoomPercent

          public long getZoomPercent()

      Set zoom.
      In the zoom tag inside settings.xml file
      it sets the value of zoom
      sample snippet from settings.xml

              <w:zoom w:percent="50" />

      Returns:
        percentage as an integer of zoom level

    - #### setZoomPercent

          public void setZoomPercent(long zoomPercent)

      Set zoom.
      In the zoom tag inside settings.xml file
      it sets the value of zoom
      sample snippet from settings.xml

              <w:zoom w:percent="50" />

    - #### isEnforcedWith

          public boolean isEnforcedWith()

      Verifies the documentProtection tag inside settings.xml file
      if the protection is enforced (w:enforcement="1")

      sample snippet from settings.xml

               <w:settings  ... >
                   <w:documentProtection w:edit="readOnly" w:enforcement="1"/>

      Returns:
        true if documentProtection is enforced with option any

    - #### isEnforcedWith

          public boolean isEnforcedWith(org.openxmlformats.schemas.wordprocessingml.x2006.main.STDocProtect.Enum editValue)

      Verifies the documentProtection tag inside settings.xml file
      if the protection is enforced (w:enforcement="1")
      and if the kind of protection equals to passed (STDocProtect.Enum editValue)

      sample snippet from settings.xml

               <w:settings  ... >
                   <w:documentProtection w:edit="readOnly" w:enforcement="1"/>

      Returns:
        true if documentProtection is enforced with option readOnly

    - #### setEnforcementEditValue

          public void setEnforcementEditValue(org.openxmlformats.schemas.wordprocessingml.x2006.main.STDocProtect.Enum editValue)

      Enforces the protection with the option specified by passed editValue.
      In the documentProtection tag inside settings.xml file
      it sets the value of enforcement to "1" (w:enforcement="1")
      and the value of edit to the passed editValue (w:edit="[passed editValue]")
      sample snippet from settings.xml

               <w:settings  ... >
                   <w:documentProtection w:edit="[passed editValue]" w:enforcement="1"/>

    - #### setEnforcementEditValue

          public void setEnforcementEditValue(org.openxmlformats.schemas.wordprocessingml.x2006.main.STDocProtect.Enum editValue,
                                              java.lang.String password,
                                              HashAlgorithm hashAlgo)

      Enforces the protection with the option specified by passed editValue and password.
      sample snippet from settings.xml

             <w:documentProtection w:edit="[passed editValue]" w:enforcement="1"
                 w:cryptProviderType="rsaAES" w:cryptAlgorithmClass="hash"
                 w:cryptAlgorithmType="typeAny" w:cryptAlgorithmSid="14"
                 w:cryptSpinCount="100000" w:hash="..." w:salt="...."
             />

      Parameters:
        `editValue` - the protection type
        `password` - the plaintext password, if null no password will be applied
        `hashAlgo` - the hash algorithm - only md2, m5, sha1, sha256, sha384 and sha512 are supported. if null, it will default default to sha1

    - #### validateProtectionPassword

          public boolean validateProtectionPassword(java.lang.String password)

      Validates the existing password
      Parameters:
        `password` -
      Returns:
        true, only if password was set and equals, false otherwise

    - #### removeEnforcement

          public void removeEnforcement()

      Removes protection enforcement.
      In the documentProtection tag inside settings.xml file
      it sets the value of enforcement to "0" (w:enforcement="0")

    - #### setUpdateFields

          public void setUpdateFields()

      Enforces fields update on document open (in Word). In the settings.xml file
      sets the updateSettings value to true (w:updateSettings w:val="true")

      NOTICES:

      - Causing Word to ask on open: "This document contains fields that may refer to other files. Do you want to update the fields in this document?" (if "Update automatic links at open" is enabled)
      - Flag is removed after saving with changes in Word

    - #### isTrackRevisions

          public boolean isTrackRevisions()

      Check if revision tracking is turned on.
      Returns:
        `true` if revision tracking is turned on

    - #### setTrackRevisions

          public void setTrackRevisions(boolean enable)

      Enable or disable revision tracking.
      Parameters:
        `enable` - `true` to turn on revision tracking, `false` to turn off revision tracking

    - #### commit

          protected void commit()
                         throws java.io.IOException

      Description copied from class: `POIXMLDocumentPart`
      Save the content in the underlying package part. Default implementation is empty meaning that the package part is left unmodified.

      Sub-classes should override and add logic to marshal the "model" into Ooxml4J.

      For example, the code saving a generic XML entry may look as follows:

           protected void commit() throws IOException {
             PackagePart part = getPackagePart();
             OutputStream out = part.getOutputStream();
             XmlObject bean = getXmlBean(); //the "model" which holds changes in memory
             bean.save(out, DEFAULT_XML_OPTIONS);
             out.close();
           }

      Overrides:
        `commit` in class `POIXMLDocumentPart`
      Throws:
        `java.io.IOException` - a subclass may throw an IOException if the changes can't be committed

    - #### getEvenAndOddHeadings

          public boolean getEvenAndOddHeadings()

      Check if separate even and odd headings is turned on.
      Returns:
        True if even and odd headings is turned on.

    - #### setEvenAndOddHeadings

          public void setEvenAndOddHeadings(boolean enable)

      Turn separate even-and-odd headings on or off
      Parameters:
        `enable` - `true` to turn on separate even and odd headings, `false` to turn off even and odd headings.

    - #### getMirrorMargins

          public boolean getMirrorMargins()

      Check if mirrored margins is turned on
      Returns:
        True if mirrored margins is turned on.

    - #### setMirrorMargins

          public void setMirrorMargins(boolean enable)

      Turn mirrored margins on or off
      Parameters:
        `enable` - `true` to turn on mirrored margins, `false` to turn off mirrored marginss.

Copyright 2020 The Apache Software Foundation or its licensors, as applicable.