com.lowagie.text.pdf

## Class PdfLayer

- java.lang.Object
- - com.lowagie.text.pdf.PdfObject
  - - com.lowagie.text.pdf.PdfDictionary
    - - com.lowagie.text.pdf.PdfLayer

- All Implemented Interfaces:
    PdfOCG

      public class PdfLayer
      extends PdfDictionary
      implements PdfOCG

  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.
  Author:
    Paulo Soares (psoares@consiste.pt)

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.util.ArrayList` | `children`
    `private boolean` | `on` Holds value of property on.
    `private boolean` | `onPanel` Holds value of property onPanel.
    `protected PdfLayer` | `parent`
    `protected PdfIndirectReference` | `ref`
    `protected java.lang.String` | `title`

    - ### Fields inherited from class com.lowagie.text.pdf.PdfDictionary

      `CATALOG, FONT, hashMap, OUTLINES, PAGE, PAGES`

    - ### Fields inherited from class com.lowagie.text.pdf.PdfObject

      `ARRAY, BOOLEAN, bytes, DICTIONARY, INDIRECT, indRef, NAME, NOTHING, NULL, NUMBER, STREAM, STRING, TEXT_PDFDOCENCODING, TEXT_UNICODE, type`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PdfLayer(java.lang.String title)`
    `PdfLayer(java.lang.String name, PdfWriter writer)` Creates a new layer.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addChild(PdfLayer child)` Adds a child layer.
    `static PdfLayer` | `createTitle(java.lang.String title, PdfWriter writer)` Creates a title layer.
    `java.util.ArrayList` | `getChildren()` Gets the children layers.
    `PdfLayer` | `getParent()` Gets the parent layer.
    `PdfObject` | `getPdfObject()` Gets the dictionary representing the layer.
    `PdfIndirectReference` | `getRef()` Gets the `PdfIndirectReference` that represents this layer.
    `(package private) java.lang.String` | `getTitle()`
    `private PdfDictionary` | `getUsage()`
    `boolean` | `isOn()` Gets the initial visibility of the layer.
    `boolean` | `isOnPanel()` Gets the layer visibility in Acrobat's layer panel
    `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` | `setLanguage(java.lang.String lang, boolean preferred)` Specifies the language of the content controlled by this optional content group
    `void` | `setName(java.lang.String name)` Sets the name of this layer.
    `void` | `setOn(boolean on)` Sets the initial visibility of the layer.
    `void` | `setOnPanel(boolean onPanel)` Sets the visibility of the layer in Acrobat's layer panel.
    `void` | `setPrint(java.lang.String subtype, boolean printstate)` Specifies that the content in this group is intended for use in printing
    `(package private) void` | `setRef(PdfIndirectReference ref)` Sets the `PdfIndirectReference` that represents this layer.
    `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 com.lowagie.text.pdf.PdfDictionary

      `contains, get, getAsArray, getAsBoolean, getAsDict, getAsIndirectObject, getAsName, getAsNumber, getAsStream, getAsString, getDirectObject, getKeys, isCatalog, isFont, isOutlineTree, isPage, isPages, merge, mergeDifferent, put, putAll, putEx, remove, size, toPdf, toString`

    - ### Methods inherited from class com.lowagie.text.pdf.PdfObject

      `canBeInObjStm, getBytes, getIndRef, isArray, isBoolean, isDictionary, isIndirect, isName, isNull, isNumber, isStream, isString, length, setContent, setIndRef, type`

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

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

- - ### Field Detail

    - #### ref

          protected PdfIndirectReference ref

    - #### children

          protected java.util.ArrayList children

    - #### parent

          protected PdfLayer parent

    - #### title

          protected java.lang.String title

    - #### on

          private boolean on

      Holds value of property on.

    - #### onPanel

          private boolean onPanel

      Holds value of property onPanel.

  - ### Constructor Detail

    - #### PdfLayer

          PdfLayer(java.lang.String title)

    - #### PdfLayer

          public PdfLayer(java.lang.String name,
                  PdfWriter writer)

      Creates a new layer.
      Parameters:
        `name` - the name of the layer
        `writer` - the writer

  - ### Method Detail

    - #### createTitle

          public static PdfLayer createTitle(java.lang.String title,
                             PdfWriter writer)

      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
        `writer` - the `PdfWriter`
      Returns:
        the title layer

    - #### getTitle

          java.lang.String getTitle()

    - #### addChild

          public void addChild(PdfLayer child)

      Adds a child layer. Nested layers can only have one parent.
      Parameters:
        `child` - the child layer

    - #### getParent

          public PdfLayer getParent()

      Gets the parent layer.
      Returns:
        the parent layer or `null` if the layer has no parent

    - #### getChildren

          public java.util.ArrayList getChildren()

      Gets the children layers.
      Returns:
        the children layers or `null` if the layer has no children

    - #### getRef

          public PdfIndirectReference getRef()

      Gets the `PdfIndirectReference` that represents this layer.
      Specified by:
        `getRef` in interface `PdfOCG`
      Returns:
        the `PdfIndirectReference` that represents this layer

    - #### setRef

          void setRef(PdfIndirectReference ref)

      Sets the `PdfIndirectReference` that represents this layer. This can only be done from PdfStamperImp.
      Parameters:
        `ref` - The reference to the OCG object
      Since:
        2.1.2

    - #### setName

          public void setName(java.lang.String name)

      Sets the name of this layer.
      Parameters:
        `name` - the name of this layer

    - #### getPdfObject

          public PdfObject getPdfObject()

      Gets the dictionary representing the layer. It just returns `this`.
      Specified by:
        `getPdfObject` in interface `PdfOCG`
      Returns:
        the dictionary representing the layer

    - #### isOn

          public boolean isOn()

      Gets the initial visibility of the layer.
      Returns:
        the initial visibility of the layer

    - #### setOn

          public void setOn(boolean on)

      Sets the initial visibility of the layer.
      Parameters:
        `on` - the initial visibility of the layer

    - #### getUsage

          private PdfDictionary getUsage()

    - #### 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

    - #### 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