Class: HexaPDF::Type::Annotation

Inherits:
Dictionary show all
Extended by:
Utils::BitField
Defined in:
lib/hexapdf/type/annotation.rb

Overview

Annotations are used to associate objects like notes, sounds or movies with a location on a PDF page or allow the user to interact with a PDF document using a keyboard or mouse.

See: PDF2.0 s12.5

Defined Under Namespace

Classes: AppearanceDictionary, Border, BorderEffect, Opacity

Constant Summary

Constants included from DictionaryFields

DictionaryFields::Boolean, DictionaryFields::PDFByteString, DictionaryFields::PDFDate

Instance Attribute Summary

Attributes inherited from Object

#data, #document, #must_be_indirect

Instance Method Summary collapse

Methods included from Utils::BitField

bit_field

Methods inherited from Dictionary

#[], #[]=, define_field, define_type, #delete, #each, each_field, #empty?, field, #key?, #to_hash, type, #type

Methods inherited from Object

#<=>, #==, #cache, #cached?, #clear_cache, deep_copy, #deep_copy, #document?, #eql?, field, #gen, #gen=, #hash, #indirect?, #initialize, #inspect, make_direct, #null?, #oid, #oid=, #type, #validate, #value, #value=

Constructor Details

This class inherits a constructor from HexaPDF::Object

Instance Method Details

#appearance(type: :normal, state_name: ) ⇒ Object Also known as: appearance?

Returns the annotation’s appearance stream of the given type (:normal, :rollover, or :down) or nil if it doesn’t exist.

The appearance state in /AS or the one provided via state_name is taken into account if necessary.



245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/hexapdf/type/annotation.rb', line 245

def appearance(type: :normal, state_name: self[:AS])
  entry = appearance_dict&.send("#{type}_appearance")
  if entry.kind_of?(HexaPDF::Dictionary) && !entry.kind_of?(HexaPDF::Stream)
    entry = entry[state_name]
  end
  return unless entry.kind_of?(HexaPDF::Stream)

  if entry.type == :XObject && entry[:Subtype] == :Form && !entry.instance_of?(HexaPDF::Stream)
    entry
  elsif (entry[:Type].nil? || entry[:Type] == :XObject) &&
      (entry[:Subtype].nil? || entry[:Subtype] == :Form) && entry[:BBox]
    document.wrap(entry, type: :XObject, subtype: :Form)
  end
end

#appearance_dict ⇒ Object

Returns the AppearanceDictionary instance associated with the annotation or nil if none is set.



236
237
238
 
# File 'lib/hexapdf/type/annotation.rb', line 236

def appearance_dict
  self[:AP]
end

#contents(text = :UNSET) ⇒ Object

:call-seq:

annot.contents        => contents or +nil+
annot.contents(text)  => annot

Returns the text of the annotation when no argument is given. Otherwise sets the text and returns self.

The contents is used differently depending on the annotation type. It is either the text that should be displayed for the annotation or an alternate description of the annotation’s contents.

A value of nil means deleting the existing contents entry.



296
297
298
299
300
301
302
303
 
# File 'lib/hexapdf/type/annotation.rb', line 296

def contents(text = :UNSET)
  if text == :UNSET
    self[:Contents]
  else
    self[:Contents] = text
    self
  end
end

#create_appearance(type: :normal, state_name: ) ⇒ Object

Creates an empty appearance stream (a Form XObject) of the given type (:normal, :rollover, or :down) and returns it. If an appearance stream already exist, it is overwritten.

If there can be multiple appearance streams for the annotation, use the state_name argument to provide the appearance state name.



266
267
268
269
270
271
272
 
# File 'lib/hexapdf/type/annotation.rb', line 266

def create_appearance(type: :normal, state_name: self[:AS])
  xobject = document.add({Type: :XObject, Subtype: :Form,
                          BBox: [0, 0, self[:Rect].width, self[:Rect].height]})
  self[:AP] ||= {}
  appearance_dict.set_appearance(xobject, type: type, state_name: state_name)
  xobject
end

#flags ⇒ Object

:method: unflag :call-seq:

flag(*flags)

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

See #flags for the list of available flags.



223
224
225
226
227
 
# File 'lib/hexapdf/type/annotation.rb', line 223

bit_field(:flags, {invisible: 0, hidden: 1, print: 2, no_zoom: 3, no_rotate: 4,
         no_view: 5, read_only: 6, locked: 7, toggle_no_view: 8,
         locked_contents: 9},
lister: "flags", getter: "flagged?", setter: "flag", unsetter: "unflag",
value_getter: "self[:F]", value_setter: "self[:F]")

#must_be_indirect? ⇒ Boolean

Returns true because annotation objects must always be indirect objects.

Returns:



230
231
232
 
# File 'lib/hexapdf/type/annotation.rb', line 230

def must_be_indirect?
  true
end

#opacity(fill_alpha: nil, stroke_alpha: nil) ⇒ Object

:call-seq:

annotation.opacity                                           => current_values
annotation.opacity(fill_alpha:)                              => annotation
annotation.opacity(stroke_alpha:)                            => annotation
annotation.opacity(fill_alpha:, stroke_alpha:)               => annotation

Returns an Opacity instance representing the fill and stroke alpha values when no arguments are given. Otherwise sets the provided alpha values and returns self.

The fill and stroke alpha values are used when regenerating the annotation’s appearance stream and determine how opaque drawn elements will be. Note that the fill alpha value applies not just to fill values but to all non-stroking operations (e.g. images, …).



322
323
324
325
326
327
328
329
330
 
# File 'lib/hexapdf/type/annotation.rb', line 322

def opacity(fill_alpha: nil, stroke_alpha: nil)
  if !fill_alpha.nil? || !stroke_alpha.nil?
    self[:CA] = stroke_alpha unless stroke_alpha.nil?
    self[:ca] = fill_alpha unless fill_alpha.nil?
    self
  else
    Opacity.new(key?(:ca) ? self[:ca] : self[:CA], self[:CA])
  end
end

#regenerate_appearance ⇒ Object

Regenerates the appearance stream of the annotation.

This uses the information stored in the annotation to regenerate the appearance.

See: Annotations::AppearanceGenerator



279
280
281
282
 
# File 'lib/hexapdf/type/annotation.rb', line 279

def regenerate_appearance
  appearance_generator_class = document.config.constantize('annotation.appearance_generator')
  appearance_generator_class.new(self).create_appearance
end