Instance Methods

class HexaPDF::Type::OutlineItem

Parent	HexaPDF::Dictionary
Extended With	HexaPDF::Utils::BitField

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

Field Definitions

Name	Type/Allowed Values	Required	Default Value
Title	String	true	nil
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
Count	Integer	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]
F	Integer	false	0

Public Instance Methods

action → action ¶

action(value) → action ¶

Returns the item’s action if no argument is given. Otherwise sets the action to the given value (needs to be a valid HexaPDF::Type::Action dictionary).

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.

add_item(title, destination: nil, action: nil, position: :last, open: true, text_color: nil, flags: nil) { |item| ... }¶

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.

destination

Specifies the destination that should be activated when clicking on the outline item. See HexaPDF::Document::Destinations#use_or_create for details. The argument :action takes precedence if it is also specified,

action

Specifies the action that should be taken when clicking on the outline item. See HexaPDF::Type::Action for details. If the argument :destination is also specified, the :action argument takes precedence.

position

The position where the new child item should be inserted. Can either be:

:first: Insert as first item
:last: Insert as last item (default)
Integer: When non-negative inserts before, otherwise after, the item at the given zero-based index.

open

Specifies whether the outline item should be open (i.e. one or more children are shown) or closed. Default: true.

text_color

The text color of the outline item text which needs to be a valid RGB color (see text_color for details). If not set, the text appears in black.

flags

An array of font variants (possible values are :bold and :italic) to set for the outline item text, see flags for detail. Default is to use no variant.

Examples:

doc.destinations.add("Title") do |item|                  # no action, just container
  item.add("Second subitem", destination: doc.pages[1])  # links to page 2
  item.add("First subitem", position: :first, destination: doc.pages[0])
end

destination → destination ¶

destination(value) → destination ¶

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.

destination_page()¶

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.
Otherwise nil is returned.

each_item {|descendant_item, level| block } → item ¶

each_item → Enumerator ¶

Iterates over all descendant items of this one.

The descendant items are yielded in-order, yielding first the item itself and then its descendants.

flag(*flags, clear_existing: false) ¶

Sets the given flags on /F, given as flag names or bit indices. If clear_existing is true, all prior flags will be cleared.

See flags for the list of available flags.

flagged?(flag) ¶

Returns true if the given flag is set on /F. The argument can either be the flag name or the bit index.

See flags for the list of available flags.

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.

level()¶

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

must_be_indirect?()¶

Returns true since outline items must always be indirect objects.

open?()¶

Returns the open state of the item.

true: If this item is open, i.e. showing its child items.
false: If this item is closed, i.e. not showing its child items.
nil: If this item doesn’t (yet) have any child items.

text_color → color ¶

text_color(color) → color ¶

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 color values.

Note: The color has to be an RGB color.

title → title ¶

title(value) → title ¶

Returns the item’s title if no argument is given. Otherwise sets the title to the given value.

flag(*flags) ¶

Clears the given flags from /F, given as flag names or bit indices.

See flags for the list of available flags.

Menu

Classes and Modules

class HexaPDF::Type::OutlineItem

Field Definitions

Public Instance Methods