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, 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.

[View source]

233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/hexapdf/type/annotation.rb', line 233

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.

[View source]

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

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.

[View source]

284
285
286
287
288
289
290
291
 
# File 'lib/hexapdf/type/annotation.rb', line 284

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.

[View source]

254
255
256
257
258
259
260
 
# File 'lib/hexapdf/type/annotation.rb', line 254

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.

[View source]

211
212
213
214
215
 
# File 'lib/hexapdf/type/annotation.rb', line 211

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:

[View source]

218
219
220
 
# File 'lib/hexapdf/type/annotation.rb', line 218

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, …).

[View source]

310
311
312
313
314
315
316
317
318
 
# File 'lib/hexapdf/type/annotation.rb', line 310

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

[View source]

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

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