class Prawn::Outline

# File lib/prawn/outline.rb, line 31
def initialize(document)
  @document = document
  @parent = root
  @prev = nil
  @items = {}
end

@param document [Prawn::Document]

# File lib/prawn/outline.rb, line 115
def add_subsection_to(title, position = :last, &block)
  @parent = items[title]
  unless @parent
    raise Prawn::Errors::UnknownOutlineTitle,
      "\n No outline item with title: '#{title}' exists in the outline tree"
  end
  @prev = position == :first ? nil : @parent.data.last
  nxt = position == :first ? @parent.data.first : nil
  insert_section(nxt, &block)
end

Inserts an outline section to the outline tree (see {define}).

Although you will probably choose to exclusively use {define} so that your outline tree is contained and easy to manage, this method gives you the option to insert sections to the outline tree at any point during document generation. This method allows you to add a child subsection to any other item at any level in the outline tree. Currently the only way to locate the place of entry is with the title for the item. If your title names are not unique consider using {define}.

Consider using this method instead of {update} if you want to have the outline object to be scoped as self (see {insert_section_after} example).

“‘ruby go_to_page 2 start_new_page text “Inserted Page” outline.add_subsection_to title: ’Page 2’, :first do

outline.page destination: page_number, title: "Inserted Page"

end “‘

@param title [String] An outline title to add the subsection to. @param position [:first, :last] (:last)

Where the subsection will be placed relative to other child elements. If
you need to position your subsection in between other elements then
consider using {insert_section_after}.

@yield Uses the same DSL syntax as {define} @return [void]

# File lib/prawn/outline.rb, line 80
def define(&block)
  instance_eval(&block) if block
end

Defines/Updates an outline for the document.

The outline is an optional nested index that appears on the side of a PDF document usually with direct links to pages. The outline DSL is defined by nested blocks involving two methods: {section} and {page}. Note that one can also use {update} to add more sections to the end of the outline tree using the same syntax and scope.

The syntax is best illustrated with an example:

“‘ruby Prawn::Document.generate(’outlined_document.pdf’) do

text "Page 1. This is the first Chapter. "
start_new_page
text "Page 2. More in the first Chapter. "
start_new_page
outline.define do
  section 'Chapter 1', destination: 1, closed: true do
    page destination: 1, title: 'Page 1'
    page destination: 2, title: 'Page 2'
  end
end
start_new_page do
outline.update do
  section 'Chapter 2', destination: 2, do
    page destination: 3, title: 'Page 3'
  end
end

end “‘

@yield @return [void]

# File lib/prawn/outline.rb, line 151
def insert_section_after(title, &block)
  @prev = items[title]
  unless @prev
    raise Prawn::Errors::UnknownOutlineTitle,
      "\n No outline item with title: '#{title}' exists in the outline tree"
  end
  @parent = @prev.data.parent
  nxt = @prev.data.next
  insert_section(nxt, &block)
end

Inserts an outline section to the outline tree (see {define}).

Although you will probably choose to exclusively use {define} so that your outline tree is contained and easy to manage, this method gives you the option to insert sections to the outline tree at any point during document generation. Unlike {add_subsection_to}, this method allows you to enter a section after any other item at any level in the outline tree. Currently the only way to locate the place of entry is with the title for the item. If your title names are not unique consider using {define}.

@example

go_to_page 2
start_new_page
text "Inserted Page"
update_outline do
  insert_section_after :title => 'Page 2' do
    page :destination => page_number, :title => "Inserted Page"
  end
end

@param title [String]

The title of other section or page to insert new section after.

@yield Uses the same DSL syntax as {define}. @return [void]

# File lib/prawn/outline.rb, line 219
def page(options = {})
  if options[:title]
    title = options[:title]
  else
    raise Prawn::Errors::RequiredOption,
      "\nTitle is a required option for page"
  end
  add_outline_item(title, options)
end

Adds a page to the outline.

Although you will probably choose to exclusively use {define} so that your outline tree is contained and easy to manage, this method also gives you the option to add pages to the root of outline tree at any point during document generation. Note that the page will be added at the top level after the other root outline elements. For more flexible placement try using {insert_section_after} and/or {add_subsection_to}.

@note This method is almost identical to {section} except that it does not

accept a block thereby defining the outline item as a leaf on the
outline tree structure.

@example

outline.page title: "Very Last Page"

@param options [Hash{Symbol => any}] @option options :title [String] REQUIRED.

The outline text that appears for the page.

@option options :destination [Integer, Array]

- The page number for a destination link to the top of the page (using
  a `:FIT` destination).
- An array with a custom destination (see the `#dest_*` methods of the
  `PDF::Core::Destination` module).

@option options :closed [Boolean] (false)

Whether the section should show its nested outline elements.

@return [void]

# File lib/prawn/outline.rb, line 43
def page_number
  @document.page_number
end

Returns the current page number of the document.

@return [Integer]

# File lib/prawn/outline.rb, line 188
def section(title, options = {}, &block)
  add_outline_item(title, options, &block)
end

Adds an outline section to the outline tree.

Although you will probably choose to exclusively use {define} so that your outline tree is contained and easy to manage, this method gives you the option to add sections to the outline tree at any point during document generation. When not being called from within another {section} block the section will be added at the top level after the other root elements of the outline. For more flexible placement try using {insert_section_after} and/or {add_subsection_to}.

@example

outline.section 'Added Section', destination: 3 do
  outline.page destionation: 3, title: 'Page 3'
end

@param title [String] The outline text that appears for the section. @param options [Hash{Symbol => any}] @option options :destination [Integer, Array]

- Optional page number for a destination link to the top of the page
  (using a `:FIT` destination).
- An array with a custom destination (see the `#dest_*` methods of the
  `PDF::Core::Destination` module).

@option options :closed [Boolean] (false)

Whether the section should show its nested outline elements.

@yield More nested subsections and/or page blocks. @return [void]