Represents an outline item dictionary.
An item has a title and some optional attributes: the action that is activated when clicking (either a simple destination or an explicit action object), the text color, and flags (whether the text should appear bold and/or italic).
Additionally, items may have child items which makes it possible to create a hierarchy of items.
If no destination/action is set, the item just acts as kind of a header. It usually only makes sense to do this when the item has children.
Outline item dictionaries are connected together in the form of a linked list using the /Next and /Prev keys. Each item may have descendant items. If so, the /First and /Last keys point to respectively the first and last descendant items.
Since many dictionary keys need to be kept up-to-date when manipulating the outline item tree, it is not recommended to manually do this but to rely on the provided convenience methods.
See: PDF2.0 s12.3.3
|Name||Type/Allowed Values||Required||Default Value|
|Parent||HexaPDF::Dictionary or Hash||true||nil|
|Prev||HexaPDF::Type::OutlineItem or Hash||false||nil|
|Next||HexaPDF::Type::OutlineItem or Hash||false||nil|
|First||HexaPDF::Type::OutlineItem or Hash||false||nil|
|Last||HexaPDF::Type::OutlineItem or Hash||false||nil|
|Dest||Symbol or HexaPDF::DictionaryFields::PDFByteString or HexaPDF::PDFArray or String or Array||false||nil|
|A||HexaPDF::Type::Action or Hash||false||nil|
|SE||HexaPDF::Dictionary or Hash||false||nil|
|C||HexaPDF::PDFArray or Array||false||[0, 0, 0]|
Public Instance Methods
Returns the item's action if no argument is given. Otherwise sets the action to the given value (needs to be a valid
If an action is set, the destination has to be unset; and vice versa. So when setting an action value, the destination is automatically deleted.
Adds, as child to this item, a new outline item with the given title that performs the provided action on clicking. Returns the newly added item.
Alternatively, it is possible to provide an already initialized outline item instead of the title. If so, the only other argument that is used is
position. Existing fields /Prev, /Next, /First, /Last, /Parent and /Count are deleted from the given item and set appropriately.
If neither :destination nor :action is specified, the outline item has no associated action. This is only meaningful if the new item will have children as it then acts just as a container.
If a block is specified, the newly created item is yielded.
Specifies the destination that should be activated when clicking on the outline item. See
HexaPDF::Document::Destinations#use_or_createfor details. The argument :action takes precedence if it is also specified,
Specifies the action that should be taken when clicking on the outline item. See
HexaPDF::Type::Actionfor details. If the argument :destination is also specified, the :action argument takes precedence.
The position where the new child item should be inserted. Can either be:
Insert as first item
Insert as last item (default)
When non-negative inserts before, otherwise after, the item at the given zero-based index.
Specifies whether the outline item should be open (i.e. one or more children are shown) or closed. Default:
The text color of the outline item text which needs to be a valid RGB color (see
text_colorfor details). If not set, the text appears in black.
An array of font variants (possible values are :bold and :italic) to set for the outline item text, see
flagsfor detail. Default is to use no variant.
doc.destinations.add("Title") do |item| # no action, just container item.add("Second subitem", destination: doc.pages) # links to page 2 item.add("First subitem", position: :first, destination: doc.pages) end
Returns the item's destination if no argument is given. Otherwise sets the destination to the given value (see
HexaPDF::Document::Destinations#use_or_create for the posssible values).
If an action is set, the destination has to be unset; and vice versa. So when setting a destination value, the action is automatically deleted.
Returns the destination page if there is any.
If a destination is set, the associated page is returned.
If an action is set and it is a GoTo action, the associated page is returned.
Iterates over all descendant items of this one.
The descendant items are yielded in-order, yielding first the item itself and then its descendants.
Sets the given flags on /F, given as flag names or bit indices. If
true, all prior flags will be cleared.
flags for the list of available flags.
true if the given flag is set on /F. The argument can either be the flag name or the bit index.
flags for the list of available flags.
Returns an array of flag names representing the set bit flags for /F.
The available flags are:
- :italic or 0
The text is displayed in italic.
- :bold or 1
The text is displayed in bold.
Returns the outline level this item is one.
The level of the items in the main outline dictionary, the root level, is 1.
Here is an illustrated example of items contained in a document outline with their associated level:
Outline dictionary 0 Outline item 1 1 |- Sub item 1 2 |- Sub item 2 2 |- Sub sub item 1 3 |- Sub item 3 2 Outline item 2 1
true since outline items must always be indirect objects.
Returns the open state of the item.
If this item is open, i.e. showing its child items.
If this item is closed, i.e. not showing its child items.
If this item doesn't (yet) have any child items.
Returns the item's text color as
HexaPDF::Content::ColorSpace::DeviceRGB::Color object if no argument is given. Otherwise sets the text color, see
HexaPDF::Content::ColorSpace.device_color_from_specification for possible
Note: The color has to be an RGB color.
Returns the item's title if no argument is given. Otherwise sets the title to the given value.