Class: HexaPDF::Document::Destinations

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/hexapdf/document/destinations.rb

Overview

This class provides methods for creating and managing the destinations of a PDF file.

A destination describes a particular view of a PDF document, consisting of the page, the view location and a magnification factor. See Destination for details.

Such destinations may be directly specified where needed, e.g. for link annotations, or they may be named and later referenced through the name. This class allows to create destinations with or without a name.

See: PDF1.7 s12.3.2

Defined Under Namespace

Classes: Destination

Instance Method Summary collapse

Constructor Details

#initialize(document) ⇒ Destinations

Creates a new Destinations object for the given PDF document.



207
208
209
 
# File 'lib/hexapdf/document/destinations.rb', line 207

def initialize(document)
  @document = document
end

Instance Method Details

#[](name) ⇒ Object

:call-seq:

destinations[name]    -> destination

Returns the destination registered under the given name or nil if no destination was registered under that name.



366
367
368
 
# File 'lib/hexapdf/document/destinations.rb', line 366

def [](name)
  destinations.find_entry(name)
end

#add(name, destination) ⇒ Object

:call-seq:

destinations.add(name, destination)

Adds the given destination under name to the destinations name tree.

If the name does already exist, an error is raised.



348
349
350
 
# File 'lib/hexapdf/document/destinations.rb', line 348

def add(name, destination)
  destinations.add_entry(name, destination)
end

#create_fit_bounding_box(page, name: nil) ⇒ Object

:call-seq:

destinations.create_fit_bounding_box(page)            -> dest
destinations.create_fit_bounding_box(page, name: nil) -> name

Creates a new fit to bounding box destination array for the given arguments and returns it or, in case a name is given, the name.

The argument page is described in detail in the Destination class description.

If the argument name is given, the created destination array is added to the destinations name tree under that name for reuse later, overwriting an existing entry if there is one.



305
306
307
308
 
# File 'lib/hexapdf/document/destinations.rb', line 305

def create_fit_bounding_box(page, name: nil)
  destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_bounding_box)]
  name ? (add(name, destination); name) : destination
end

#create_fit_bounding_box_horizontal(page, name: nil, top: nil) ⇒ Object

:call-seq:

destinations.create_fit_bounding_box_horizontal(page, top: nil)            -> dest
destinations.create_fit_bounding_box_horizontal(page, name: nil, top: nil) -> name

Creates a new fit bounding box horizontal destination array for the given arguments and returns it or, in case a name is given, the name.

The arguments +page and top are described in detail in the Destination class description.

If the argument name is given, the created destination array is added to the destinations name tree under that name for reuse later, overwriting an existing entry if there is one.



321
322
323
324
 
# File 'lib/hexapdf/document/destinations.rb', line 321

def create_fit_bounding_box_horizontal(page, name: nil, top: nil)
  destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_bounding_box_horizontal), top]
  name ? (add(name, destination); name) : destination
end

#create_fit_bounding_box_vertical(page, name: nil, left: nil) ⇒ Object

:call-seq:

destinations.create_fit_bounding_box_vertical(page, left: nil)            -> dest
destinations.create_fit_bounding_box_vertical(page, name: nil, left: nil) -> name

Creates a new fit bounding box vertical destination array for the given arguments and returns it or, in case a name is given, the name.

The arguments +page and left are described in detail in the Destination class description.

If the argument name is given, the created destination array is added to the destinations name tree under that name for reuse later, overwriting an existing entry if there is one.



337
338
339
340
 
# File 'lib/hexapdf/document/destinations.rb', line 337

def create_fit_bounding_box_vertical(page, name: nil, left: nil)
  destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_bounding_box_vertical), left]
  name ? (add(name, destination); name) : destination
end

#create_fit_page(page, name: nil) ⇒ Object

:call-seq:

destinations.create_fit_page(page)            -> dest
destinations.create_fit_page(page, name: nil) -> name

Creates a new fit to page destination array for the given arguments and returns it or, in case a name is given, the name.

The argument page is described in detail in the Destination class description.

If the argument name is given, the created destination array is added to the destinations name tree under that name for reuse later, overwriting an existing entry if there is one.



239
240
241
242
 
# File 'lib/hexapdf/document/destinations.rb', line 239

def create_fit_page(page, name: nil)
  destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_page)]
  name ? (add(name, destination); name) : destination
end

#create_fit_page_horizontal(page, name: nil, top: nil) ⇒ Object

:call-seq:

destinations.create_fit_page_horizontal(page, top: nil)            -> dest
destinations.create_fit_page_horizontal(page, name: nil, top: nil) -> name

Creates a new fit page horizontal destination array for the given arguments and returns it or, in case a name is given, the name.

The arguments +page and top are described in detail in the Destination class description.

If the argument name is given, the created destination array is added to the destinations name tree under that name for reuse later, overwriting an existing entry if there is one.



255
256
257
258
 
# File 'lib/hexapdf/document/destinations.rb', line 255

def create_fit_page_horizontal(page, name: nil, top: nil)
  destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_page_horizontal), top]
  name ? (add(name, destination); name) : destination
end

#create_fit_page_vertical(page, name: nil, left: nil) ⇒ Object

:call-seq:

destinations.create_fit_page_vertical(page, left: nil)            -> dest
destinations.create_fit_page_vertical(page, name: nil, left: nil) -> name

Creates a new fit page vertical destination array for the given arguments and returns it or, in case a name is given, the name.

The arguments +page and left are described in detail in the Destination class description.

If the argument name is given, the created destination array is added to the destinations name tree under that name for reuse later, overwriting an existing entry if there is one.



271
272
273
274
 
# File 'lib/hexapdf/document/destinations.rb', line 271

def create_fit_page_vertical(page, name: nil, left: nil)
  destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_page_vertical), left]
  name ? (add(name, destination); name) : destination
end

#create_fit_rectangle(page, left:, bottom:, right:, top:, name: nil) ⇒ Object

:call-seq:

destinations.create_fit_rectangle(page, left:, bottom:, right:, top:)            -> dest
destinations.create_fit_rectangle(page, name: nil, left:, bottom:, right:, top:) -> name

Creates a new fit to rectangle destination array for the given arguments and returns it or, in case a name is given, the name.

The arguments page, left, bottom, right and top are described in detail in the Destination class description.

If the argument name is given, the created destination array is added to the destinations name tree under that name for reuse later, overwriting an existing entry if there is one.



288
289
290
291
292
 
# File 'lib/hexapdf/document/destinations.rb', line 288

def create_fit_rectangle(page, left:, bottom:, right:, top:, name: nil)
  destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_rectangle),
                 left, bottom, right, top]
  name ? (add(name, destination); name) : destination
end

#create_xyz(page, name: nil, left: nil, top: nil, zoom: nil) ⇒ Object

:call-seq:

destinations.create_xyz(page, left: nil, top: nil, zoom: nil)            -> dest
destinations.create_xyz(page, name: nil, left: nil, top: nil, zoom: nil) -> name

Creates a new xyz destination array for the given arguments and returns it or, in case a name is given, the name.

The arguments page, left, top and zoom are described in detail in the Destination class description.

If the argument name is given, the created destination array is added to the destinations name tree under that name for reuse later, overwriting an existing entry if there is one.



223
224
225
226
 
# File 'lib/hexapdf/document/destinations.rb', line 223

def create_xyz(page, name: nil, left: nil, top: nil, zoom: nil)
  destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:xyz), left, top, zoom]
  name ? (add(name, destination); name) : destination
end

#delete(name) ⇒ Object

:call-seq:

destinations.delete(name)    -> destination

Deletes the given destination from the destinations name tree and returns it or nil if no destination was registered under that name.



357
358
359
 
# File 'lib/hexapdf/document/destinations.rb', line 357

def delete(name)
  destinations.delete_entry(name)
end

#each ⇒ Object

:call-seq:

destinations.each {|name, dest| block }  -> destinations
destinations.each                        -> Enumerator

Iterates over all named destinations of the PDF, yielding the name and the destination

wrapped into a Destination object.



376
377
378
379
380
381
382
383
384
 
# File 'lib/hexapdf/document/destinations.rb', line 376

def each
  return to_enum(__method__) unless block_given?

  destinations.each_entry do |name, dest|
    yield(name, Destination.new(dest))
  end

  self
end