class HexaPDF::Type::Annotation

Parent
Extended With

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

Field Definitions

NameType/Allowed ValuesRequiredDefault Value
TypeSymbolfalse:Annot
SubtypeSymboltruenil
RectHexaPDF::Rectangle or Arraytruenil
ContentsStringfalsenil
PHexaPDF::Dictionary or Hashfalsenil
NMStringfalsenil
MHexaPDF::DictionaryFields::PDFDate or String or Time or Date or DateTimefalsenil
FIntegerfalse0
APHexaPDF::Type::Annotation::AppearanceDictionary or Hashfalsenil
ASSymbolfalsenil
BorderHexaPDF::PDFArray or Arrayfalse[0, 0, 1]
CHexaPDF::PDFArray or Arrayfalsenil
StructParentIntegerfalsenil
OCHexaPDF::Dictionary or Hashfalsenil
AFHexaPDF::PDFArray or Arrayfalsenil
caNumericfalse1.0
CANumericfalse1.0
BMSymbolfalsenil
LangStringfalsenil

Constants

Opacity

Describes the opacity values fill_alpha and stroke_alpha of an annotation.

See Annotation#opacity

Public Instance Methods

appearance(type: :normal, state_name: self[:AS])

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.

Also aliased as: appearance?
appearance?(type: :normal, state_name: self[:AS])
Alias for: appearance
appearance_dict()

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

contents → contents or +nil+
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.

create_appearance(type: :normal, state_name: self[:AS])

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.

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:

:invisible or 0

Applies only to non-standard annotations. If set, do not render or print the annotation.

:hidden or 1

If set, do not render the annotation or allow interactions.

:print or 2

If set, print the annotation unless the hidden flag is also set. Otherwise never print the annotation.

:no_zoom or 3

If set, do not scale the annotation’s appearance to match the magnification of the page.

:no_rotate or 4

If set, do not rotate the annotation’s appearance to match the rotation of the page.

:no_view or 5

If set, do not render the annotation on the screen or allow interactions.

:read_only or 6

If set, do not allow user interactions.

:locked or 7

If set, do not allow the annotation to be deleted or its properties be modified.

:toggle_no_view or 8

If set, invert the interpretation of the :no_view flag for annotation selection and mouse hovering.

:locked_contents or 9

If set, do not allow the contents of the annotation to be modified.

must_be_indirect?()

Returns true because annotation objects must always be indirect objects.

opacity → current_values
opacity(fill_alpha:) → annotation
opacity(stroke_alpha:) → 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, …).

regenerate_appearance()

Regenerates the appearance stream of the annotation.

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

See: Annotations::AppearanceGenerator

flag(*flags)

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

See flags for the list of available flags.