PdfElixide.Document.Annotation (pdf_elixide v0.9.0)

A single annotation on a PDF page — a link, sticky note, highlight, form widget, stamp, and so on — with its zero-based :page index.

Obtain annotations with PdfElixide.Document.annotations/1 (whole document) or PdfElixide.Document.annotations/2 (a single page).

:subtype is the parsed annotation kind as an atom (:link, :text, :highlight, :widget, :three_d, :unknown, …); :raw_subtype preserves the original /Subtype name, which is useful when :subtype is :unknown. :rect is the annotation's bounding box as a PdfElixide.Geometry.Rect.

Several fields are populated only for particular subtypes:

:destination / :action — :link annotations (where the link points).
:quad_points — text-markup annotations (:highlight, :underline, :squiggly, :strike_out); each quad is a list of eight numbers.
:field_type, :field_name, :field_value, :default_value, :field_flags, :options, :appearance_state — :widget (form field) annotations. For richer form-field access see PdfElixide.Form.

:color and :interior_color are decoded from the raw /C and /IC component arrays into a PdfElixide.Color struct (see color/0).

Summary

Types

action()

A link annotation's action.

color()

An annotation color, decoded from the raw /C (or /IC) component array by its length

destination()

Where a link annotation points.

field_type()

A widget form field's type.

t()

Types

action()

@type action() ::
  {:uri, String.t()}
  | {:goto, destination()}
  | {:goto_remote, file :: String.t(), destination() | nil}
  | {:other, action_type :: String.t()}

A link annotation's action.

{:uri, url} — open a web URL.
{:goto, destination} — jump to a destination in this document.
{:goto_remote, file, destination | nil} — jump into another file.
{:other, action_type} — any other action, carrying its /S name.

color()

@type color() :: PdfElixide.Color.t()

An annotation color, decoded from the raw /C (or /IC) component array by its length:

%PdfElixide.Color.Gray{} — one component (DeviceGray).
%PdfElixide.Color.RGB{} — three components (DeviceRGB).
%PdfElixide.Color.CMYK{} — four components (DeviceCMYK).
%PdfElixide.Color.Unknown{} — any other length, preserved verbatim.

Each component is in the 0.0..1.0 range.

The colorspace is inferred from the component count, because the array itself carries none. That inference can be wrong — a one-component /C in a Separation space reads as %PdfElixide.Color.Gray{} even though the value is a tint, not an intensity.

A nil field means no color was decoded — either because the entry is absent or because it is an empty array, which upstream does not distinguish.

destination()

@type destination() ::
  {:named, String.t()}
  | {:explicit, page :: non_neg_integer(), fit_type :: String.t(),
     params :: [float()]}

Where a link annotation points.

{:named, name} — a named destination (unresolved name string).
{:explicit, page, fit_type, params} — a zero-based target page, a fit type ("XYZ", "Fit", "FitH", …), and its numeric parameters.

field_type()

@type field_type() ::
  :text
  | :button
  | :signature
  | :unknown
  | {:checkbox, boolean()}
  | {:radio, String.t() | nil}
  | {:choice, [String.t()], String.t() | nil}

A widget form field's type.

:text, :button, :signature, :unknown — bare kinds.
{:checkbox, checked?} — a checkbox and whether it is checked.
{:radio, selected | nil} — a radio button and its selected value.
{:choice, options, selected | nil} — a dropdown/list and its choices.

t()

@type t() :: %PdfElixide.Document.Annotation{
  action: action() | nil,
  appearance_state: String.t() | nil,
  author: String.t() | nil,
  border: [float()] | nil,
  color: color() | nil,
  contents: String.t() | nil,
  creation_date: String.t() | nil,
  default_value: String.t() | nil,
  destination: destination() | nil,
  field_flags: non_neg_integer() | nil,
  field_name: String.t() | nil,
  field_type: field_type() | nil,
  field_value: String.t() | nil,
  flags: PdfElixide.Document.Annotation.Flags.t(),
  interior_color: color() | nil,
  modification_date: String.t() | nil,
  opacity: float() | nil,
  options: [String.t()] | nil,
  page: non_neg_integer(),
  quad_points: [[float()]] | nil,
  raw_subtype: String.t() | nil,
  rect: PdfElixide.Geometry.Rect.t() | nil,
  subject: String.t() | nil,
  subtype: atom(),
  type: String.t()
}