Class PdfLayer

  • All Implemented Interfaces:
    IPdfOCG

    public class PdfLayer
    extends PdfObjectWrapper<PdfDictionary>
    implements IPdfOCG
    An optional content group is a dictionary representing a collection of graphics that can be made visible or invisible dynamically by users of viewer applications. In iText they are referenced as layers.

    To be able to be wrapped with this PdfObjectWrapper the PdfObject must be indirect.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.List<PdfLayer> children  
      protected boolean locked  
      protected boolean on  
      protected boolean onPanel  
      protected PdfLayer parent  
      protected java.lang.String title
      Used for titling group of objects but not actually grouping them.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        PdfLayer​(PdfDictionary layerDictionary)
      Creates a new layer by existing dictionary, which must be an indirect object.
      private PdfLayer​(PdfDocument document)  
        PdfLayer​(java.lang.String name, PdfDocument document)
      Creates a new layer by its name and document.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addChild​(PdfLayer childLayer)
      Adds a child layer.
      static void addOCGRadioGroup​(PdfDocument document, java.util.List<PdfLayer> group)
      Use this method to set a collection of optional content groups whose states are intended to follow a "radio button" paradigm.
      static PdfLayer createTitle​(java.lang.String title, PdfDocument document)
      Creates a title layer.
      protected static PdfLayer createTitleSilent​(java.lang.String title, PdfDocument document)
      Creates a title layer without registering it in PdfOCProperties.
      private PdfOCProperties fetchOCProperties()  
      java.util.List<PdfLayer> getChildren()
      Gets the list of the current child layers of the layer.
      protected PdfDocument getDocument()
      Gets the PdfDocument that owns that layer.
      PdfIndirectReference getIndirectReference()
      Gets the indirect reference to the current layer object.
      java.util.Collection<PdfName> getIntents()
      Gets a collection of current intents specified for this layer.
      PdfLayer getParent()
      Gets the parent of this layer, be it a title layer, or a usual one.
      java.lang.String getTitle()
      Gets the title of the layer if it is a title layer, or null if it is a usual layer.
      protected PdfDictionary getUsage()
      Gets the /Usage dictionary, creating a new one if necessary.
      boolean isLocked()
      Gets whether the layer is currently locked or not.
      boolean isOn()
      Gets the initial visibility of the layer when the document is opened.
      boolean isOnPanel()
      Gets the layer visibility in Acrobat's layer panel
      protected boolean isWrappedObjectMustBeIndirect()
      Defines if the object behind this wrapper must be an indirect object in the resultant document.
      void setCreatorInfo​(java.lang.String creator, java.lang.String subtype)
      Used by the creating application to store application-specific data associated with this optional content group.
      void setExport​(boolean export)
      Specifies the recommended state for content in this group when the document (or part of it) is saved by a viewer application to a format that does not support optional content (for example, an earlier version of PDF or a raster image format).
      void setIntents​(java.util.List<PdfName> intents)
      Sets the intents of the layer.
      void setLanguage​(java.lang.String lang, boolean preferred)
      Specifies the language of the content controlled by this optional content group
      void setLocked​(boolean locked)
      Use this method to lock an optional content group.
      void setName​(java.lang.String name)
      Sets the name of the layer to be displayed in the Layers panel.
      void setOn​(boolean on)
      Sets the initial visibility of the layer when the document is opened.
      void setOnPanel​(boolean onPanel)
      Sets the visibility of the layer in Acrobat's layer panel.
      void setPageElement​(java.lang.String pe)
      Indicates that the group contains a pagination artifact.
      void setPrint​(java.lang.String subtype, boolean printState)
      Specifies that the content in this group is intended for use in printing
      void setUser​(java.lang.String type, java.lang.String... names)
      Specifies one or more users for whom this optional content group is primarily intended.
      void setView​(boolean view)
      Indicates that the group should be set to that state when the document is opened in a viewer application.
      void setZoom​(float min, float max)
      Specifies a range of magnifications at which the content in this optional content group is best viewed.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • title

        protected java.lang.String title
        Used for titling group of objects but not actually grouping them.
      • on

        protected boolean on
      • onPanel

        protected boolean onPanel
      • locked

        protected boolean locked
      • children

        protected java.util.List<PdfLayer> children
    • Constructor Detail

      • PdfLayer

        public PdfLayer​(PdfDictionary layerDictionary)
        Creates a new layer by existing dictionary, which must be an indirect object.
        Parameters:
        layerDictionary - the layer dictionary, must have an indirect reference.
      • PdfLayer

        public PdfLayer​(java.lang.String name,
                        PdfDocument document)
        Creates a new layer by its name and document.
        Parameters:
        name - the layer name
        document - the PdfDocument which the layer belongs to
    • Method Detail

      • createTitle

        public static PdfLayer createTitle​(java.lang.String title,
                                           PdfDocument document)
        Creates a title layer. A title layer is not really a layer but a collection of layers under the same title heading.
        Parameters:
        title - the title text
        document - the PdfDocument
        Returns:
        the title layer
      • addOCGRadioGroup

        public static void addOCGRadioGroup​(PdfDocument document,
                                            java.util.List<PdfLayer> group)
        Use this method to set a collection of optional content groups whose states are intended to follow a "radio button" paradigm. That is, the state of at most one optional content group in the array should be ON at a time: if one group is turned ON, all others must be turned OFF.
        Parameters:
        document - the PdfDocument
        group - the radio group
      • addChild

        public void addChild​(PdfLayer childLayer)
        Adds a child layer. Nested layers can only have one parent.
        Parameters:
        childLayer - the child layer
      • getParent

        public PdfLayer getParent()
        Gets the parent of this layer, be it a title layer, or a usual one.
        Returns:
        the parent of the layer, or null if it has no parent
      • setName

        public void setName​(java.lang.String name)
        Sets the name of the layer to be displayed in the Layers panel.
        Parameters:
        name - the name of the layer.
      • isOn

        public boolean isOn()
        Gets the initial visibility of the layer when the document is opened.
        Returns:
        the initial visibility of the layer
      • setOn

        public void setOn​(boolean on)
        Sets the initial visibility of the layer when the document is opened.
        Parameters:
        on - the initial visibility of the layer
      • isLocked

        public boolean isLocked()
        Gets whether the layer is currently locked or not. If the layer is locked, it will not be possible to change its state (on/off) in a viewer.
        Returns:
        true if the layer is currently locked, false otherwise.
      • setLocked

        public void setLocked​(boolean locked)
        Use this method to lock an optional content group. The state of a locked group cannot be changed through the user interface of a viewer application. Producers can use this entry to prevent the visibility of content that depends on these groups from being changed by users.
        Parameters:
        locked - sets whether the layer is currently locked or not
      • isOnPanel

        public boolean isOnPanel()
        Gets the layer visibility in Acrobat's layer panel
        Returns:
        the layer visibility in Acrobat's layer panel
      • setOnPanel

        public void setOnPanel​(boolean onPanel)
        Sets the visibility of the layer in Acrobat's layer panel. If false the layer cannot be directly manipulated by the user. Note that any children layers will also be absent from the panel.
        Parameters:
        onPanel - the visibility of the layer in Acrobat's layer panel
      • getIntents

        public java.util.Collection<PdfName> getIntents()
        Gets a collection of current intents specified for this layer. The default value is PdfName.View, so it will be the only element of the resultant collection if no intents are currently specified.
        Returns:
        the collection of intents.
      • setIntents

        public void setIntents​(java.util.List<PdfName> intents)
        Sets the intents of the layer.
        Parameters:
        intents - the list of intents.
      • setCreatorInfo

        public void setCreatorInfo​(java.lang.String creator,
                                   java.lang.String subtype)
        Used by the creating application to store application-specific data associated with this optional content group.
        Parameters:
        creator - a text string specifying the application that created the group
        subtype - a string defining the type of content controlled by the group. Suggested values include but are not limited to Artwork, for graphic-design or publishing applications, and Technical, for technical designs such as building plans or schematics
      • setLanguage

        public void setLanguage​(java.lang.String lang,
                                boolean preferred)
        Specifies the language of the content controlled by this optional content group
        Parameters:
        lang - a language string which specifies a language and possibly a locale (for example, es-MX represents Mexican Spanish)
        preferred - used by viewer applications when there is a partial match but no exact match between the system language and the language strings in all usage dictionaries
      • setExport

        public void setExport​(boolean export)
        Specifies the recommended state for content in this group when the document (or part of it) is saved by a viewer application to a format that does not support optional content (for example, an earlier version of PDF or a raster image format).
        Parameters:
        export - the export state
      • setZoom

        public void setZoom​(float min,
                            float max)
        Specifies a range of magnifications at which the content in this optional content group is best viewed.
        Parameters:
        min - the minimum recommended magnification factors at which the group should be ON. A negative value will set the default to 0
        max - the maximum recommended magnification factor at which the group should be ON. A negative value will set the largest possible magnification supported by the viewer application
      • setPrint

        public void setPrint​(java.lang.String subtype,
                             boolean printState)
        Specifies that the content in this group is intended for use in printing
        Parameters:
        subtype - a name specifying the kind of content controlled by the group; for example, Trapping, PrintersMarks and Watermark
        printState - indicates that the group should be set to that state when the document is printed from a viewer application
      • setView

        public void setView​(boolean view)
        Indicates that the group should be set to that state when the document is opened in a viewer application.
        Parameters:
        view - the view state
      • setUser

        public void setUser​(java.lang.String type,
                            java.lang.String... names)
        Specifies one or more users for whom this optional content group is primarily intended.
        Parameters:
        type - a name that can be Ind (individual), Ttl (title), or Org (organization).
        names - one or more text strings representing the name(s) of the individual, position or organization
      • setPageElement

        public void setPageElement​(java.lang.String pe)
        Indicates that the group contains a pagination artifact.
        Parameters:
        pe - one of the following names: "HF" (Header Footer), "FG" (Foreground), "BG" (Background), or "L" (Logo).
      • getIndirectReference

        public PdfIndirectReference getIndirectReference()
        Gets the indirect reference to the current layer object.
        Specified by:
        getIndirectReference in interface IPdfOCG
        Returns:
        the indirect reference to the object representing the layer
      • getTitle

        public java.lang.String getTitle()
        Gets the title of the layer if it is a title layer, or null if it is a usual layer.
        Returns:
        the title of the layer if it is a title layer, or null if it is a usual layer
      • getChildren

        public java.util.List<PdfLayer> getChildren()
        Gets the list of the current child layers of the layer. BE CAREFUL! Do not try to add a child layer using the resultant child list, use #addChild method instead.
        Returns:
        the list of the current child layers, null if the layer has no children.
      • isWrappedObjectMustBeIndirect

        protected boolean isWrappedObjectMustBeIndirect()
        Description copied from class: PdfObjectWrapper
        Defines if the object behind this wrapper must be an indirect object in the resultant document.

        If this method returns true it doesn't necessarily mean that object must be in the indirect state at any moment, but rather defines that when the object will be written to the document it will be transformed into indirect object if it's not indirect yet.

        Return value of this method shouldn't depend on any logic, it should return always true or false.
        Specified by:
        isWrappedObjectMustBeIndirect in class PdfObjectWrapper<PdfDictionary>
        Returns:
        true if in the resultant document the object behind the wrapper must be indirect, otherwise false.
      • createTitleSilent

        protected static PdfLayer createTitleSilent​(java.lang.String title,
                                                    PdfDocument document)
        Creates a title layer without registering it in PdfOCProperties.
        Parameters:
        title - the title of the layer
        document - the document this title layer belongs to
        Returns:
        the created layer
      • getUsage

        protected PdfDictionary getUsage()
        Gets the /Usage dictionary, creating a new one if necessary.
        Returns:
        the /Usage dictionary