com.lowagie.text.pdf

## Class SimpleBookmark

- java.lang.Object
- - com.lowagie.text.pdf.SimpleBookmark

- All Implemented Interfaces:
    SimpleXMLDocHandler

      public final class SimpleBookmark
      extends java.lang.Object
      implements SimpleXMLDocHandler

  Bookmark processing in a simple way. It has some limitations, mainly the only action types supported are GoTo, GoToR, URI and Launch.

  The list structure is composed by a number of HashMap, keyed by strings, one HashMap for each bookmark. The element values are all strings with the exception of the key "Kids" that has another list for the child bookmarks.

  All the bookmarks have a "Title" with the bookmark title and optionally a "Style" that can be "bold", "italic" or a combination of both. They can also have a "Color" key with a value of three floats separated by spaces. The key "Open" can have the values "true" or "false" and signals the open status of the children. It's "true" by default.

  The actions and the parameters can be:

  - "Action" = "GoTo" - "Page" | "Named"
    - "Page" = "3 XYZ 70 400 null" - page number followed by a destination (/XYZ is also accepted)
    - "Named" = "named_destination"
  - "Action" = "GoToR" - "Page" | "Named" | "NamedN", "File", ["NewWindow"]
    - "Page" = "3 XYZ 70 400 null" - page number followed by a destination (/XYZ is also accepted)
    - "Named" = "named_destination_as_a_string"
    - "NamedN" = "named_destination_as_a_name"
    - "File" - "the_file_to_open"
    - "NewWindow" - "true" or "false"
  - "Action" = "URI" - "URI"
    - "URI" = "http://sf.net" - URI to jump to
  - "Action" = "Launch" - "File"
    - "File" - "the_file_to_open_or_execute"
  Author:
    Paulo Soares (psoares@consiste.pt)

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private java.util.Stack` | `attr`
    `private java.util.ArrayList` | `topList`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `private` | `SimpleBookmark()` Creates a new instance of SimpleBookmark

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `private static java.util.List` | `bookmarkDepth(PdfReader reader, PdfDictionary outline, IntHashtable pages)`
    `(package private) static void` | `createOutlineAction(PdfDictionary outline, java.util.HashMap map, PdfWriter writer, boolean namedAsNames)`
    `static void` | `eliminatePages(java.util.List list, int[] pageRange)` Removes the bookmark entries for a number of page ranges.
    `void` | `endDocument()` Called after the document is parsed.
    `void` | `endElement(java.lang.String tag)` Called when an end tag is found.
    `static void` | `exportToXML(java.util.List list, java.io.OutputStream out, java.lang.String encoding, boolean onlyASCII)` Exports the bookmarks to XML.
    `static void` | `exportToXML(java.util.List list, java.io.Writer wrt, java.lang.String encoding, boolean onlyASCII)` Exports the bookmarks to XML.
    `static void` | `exportToXMLNode(java.util.List list, java.io.Writer out, int indent, boolean onlyASCII)` Exports the bookmarks to XML.
    `static java.util.List` | `getBookmark(PdfReader reader)` Gets a `List` with the bookmarks.
    `private static int` | `getNumber(PdfIndirectReference indirect)` Gets number of indirect.
    `static java.util.List` | `importFromXML(java.io.InputStream in)` Import the bookmarks from XML.
    `static java.util.List` | `importFromXML(java.io.Reader in)` Import the bookmarks from XML.
    `static java.lang.Object[]` | `iterateOutlines(PdfWriter writer, PdfIndirectReference parent, java.util.List kids, boolean namedAsNames)`
    `private static java.lang.String` | `makeBookmarkParam(PdfArray dest, IntHashtable pages)`
    `private static void` | `mapGotoBookmark(java.util.HashMap map, PdfObject dest, IntHashtable pages)`
    `static void` | `shiftPageNumbers(java.util.List list, int pageShift, int[] pageRange)` For the pages in range add the `pageShift` to the page number.
    `void` | `startDocument()` Called when the document starts to be parsed.
    `void` | `startElement(java.lang.String tag, java.util.HashMap h)` Called when a start tag is found.
    `void` | `text(java.lang.String str)` Called when a text element is found.

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

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

- - ### Field Detail

    - #### topList

          private java.util.ArrayList topList

    - #### attr

          private java.util.Stack attr

  - ### Constructor Detail

    - #### SimpleBookmark

          private SimpleBookmark()

      Creates a new instance of SimpleBookmark

  - ### Method Detail

    - #### bookmarkDepth

          private static java.util.List bookmarkDepth(PdfReader reader,
                                     PdfDictionary outline,
                                     IntHashtable pages)

    - #### mapGotoBookmark

          private static void mapGotoBookmark(java.util.HashMap map,
                             PdfObject dest,
                             IntHashtable pages)

    - #### makeBookmarkParam

          private static java.lang.String makeBookmarkParam(PdfArray dest,
                                           IntHashtable pages)

    - #### getNumber

          private static int getNumber(PdfIndirectReference indirect)

      Gets number of indirect. If type of directed indirect is PAGES, it refers PAGE object through KIDS. (Contributed by Kazuya Ujihara)
      Parameters:
        `indirect` - 2004-06-13

    - #### getBookmark

          public static java.util.List getBookmark(PdfReader reader)

      Gets a `List` with the bookmarks. It returns `null` if the document doesn't have any bookmarks.
      Parameters:
        `reader` - the document
      Returns:
        a `List` with the bookmarks or `null` if the document doesn't have any

    - #### eliminatePages

          public static void eliminatePages(java.util.List list,
                            int[] pageRange)

      Removes the bookmark entries for a number of page ranges. The page ranges consists of a number of pairs with the start/end page range. The page numbers are inclusive.
      Parameters:
        `list` - the bookmarks
        `pageRange` - the page ranges, always in pairs.

    - #### shiftPageNumbers

          public static void shiftPageNumbers(java.util.List list,
                              int pageShift,
                              int[] pageRange)

      For the pages in range add the `pageShift` to the page number. The page ranges consists of a number of pairs with the start/end page range. The page numbers are inclusive.
      Parameters:
        `list` - the bookmarks
        `pageShift` - the number to add to the pages in range
        `pageRange` - the page ranges, always in pairs. It can be `null` to include all the pages

    - #### createOutlineAction

          static void createOutlineAction(PdfDictionary outline,
                                 java.util.HashMap map,
                                 PdfWriter writer,
                                 boolean namedAsNames)

    - #### iterateOutlines

          public static java.lang.Object[] iterateOutlines(PdfWriter writer,
                                           PdfIndirectReference parent,
                                           java.util.List kids,
                                           boolean namedAsNames)
                                                    throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### exportToXMLNode

          public static void exportToXMLNode(java.util.List list,
                             java.io.Writer out,
                             int indent,
                             boolean onlyASCII)
                                      throws java.io.IOException

      Exports the bookmarks to XML. Only of use if the generation is to be include in some other XML document.
      Parameters:
        `list` - the bookmarks
        `out` - the export destination. The writer is not closed
        `indent` - the indentation level. Pretty printing significant only
        `onlyASCII` - codes above 127 will always be escaped with &#nn; if `true`, whatever the encoding
      Throws:
        `java.io.IOException` - on error

    - #### exportToXML

          public static void exportToXML(java.util.List list,
                         java.io.OutputStream out,
                         java.lang.String encoding,
                         boolean onlyASCII)
                                  throws java.io.IOException

      Exports the bookmarks to XML. The DTD for this XML is:

           <?xml version='1.0' encoding='UTF-8'?>
           <!ELEMENT Title (#PCDATA|Title)*>
           <!ATTLIST Title
              Action CDATA #IMPLIED
              Open CDATA #IMPLIED
              Page CDATA #IMPLIED
              URI CDATA #IMPLIED
              File CDATA #IMPLIED
              Named CDATA #IMPLIED
              NamedN CDATA #IMPLIED
              NewWindow CDATA #IMPLIED
              Style CDATA #IMPLIED
              Color CDATA #IMPLIED
           >
           <!ELEMENT Bookmark (Title)*>

      Parameters:
        `list` - the bookmarks
        `out` - the export destination. The stream is not closed
        `encoding` - the encoding according to IANA conventions
        `onlyASCII` - codes above 127 will always be escaped with &#nn; if `true`, whatever the encoding
      Throws:
        `java.io.IOException` - on error

    - #### exportToXML

          public static void exportToXML(java.util.List list,
                         java.io.Writer wrt,
                         java.lang.String encoding,
                         boolean onlyASCII)
                                  throws java.io.IOException

      Exports the bookmarks to XML.
      Parameters:
        `list` - the bookmarks
        `wrt` - the export destination. The writer is not closed
        `encoding` - the encoding according to IANA conventions
        `onlyASCII` - codes above 127 will always be escaped with &#nn; if `true`, whatever the encoding
      Throws:
        `java.io.IOException` - on error

    - #### importFromXML

          public static java.util.List importFromXML(java.io.InputStream in)
                                              throws java.io.IOException

      Import the bookmarks from XML.
      Parameters:
        `in` - the XML source. The stream is not closed
      Returns:
        the bookmarks
      Throws:
        `java.io.IOException` - on error

    - #### importFromXML

          public static java.util.List importFromXML(java.io.Reader in)
                                              throws java.io.IOException

      Import the bookmarks from XML.
      Parameters:
        `in` - the XML source. The reader is not closed
      Returns:
        the bookmarks
      Throws:
        `java.io.IOException` - on error

    - #### endDocument

          public void endDocument()

      Description copied from interface: `SimpleXMLDocHandler`
      Called after the document is parsed.
      Specified by:
        `endDocument` in interface `SimpleXMLDocHandler`

    - #### endElement

          public void endElement(java.lang.String tag)

      Description copied from interface: `SimpleXMLDocHandler`
      Called when an end tag is found.
      Specified by:
        `endElement` in interface `SimpleXMLDocHandler`
      Parameters:
        `tag` - the tag name

    - #### startDocument

          public void startDocument()

      Description copied from interface: `SimpleXMLDocHandler`
      Called when the document starts to be parsed.
      Specified by:
        `startDocument` in interface `SimpleXMLDocHandler`

    - #### startElement

          public void startElement(java.lang.String tag,
                          java.util.HashMap h)

      Description copied from interface: `SimpleXMLDocHandler`
      Called when a start tag is found.
      Specified by:
        `startElement` in interface `SimpleXMLDocHandler`
      Parameters:
        `tag` - the tag name
        `h` - the tag's attributes

    - #### text

          public void text(java.lang.String str)

      Description copied from interface: `SimpleXMLDocHandler`
      Called when a text element is found.
      Specified by:
        `text` in interface `SimpleXMLDocHandler`
      Parameters:
        `str` - the text element, probably a fragment.