PdfElixide.Document.Annotation (pdf_elixide v0.13.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 either that the entry is absent or that it is an empty array; those two cases are not distinguished.

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. :button is a push button specifically.
{:checkbox, checked?} — a checkbox and whether it is checked.
{:radio, selected | nil} — a radio button and its selected value, read from the widget's appearance state.
{:choice, options, selected | nil} — a dropdown/list and its choices.

Which of the three button kinds a /Btn widget is comes from its /Ff bits, the same reading PdfElixide.Form.Field.Button's :kind reports, so a field reached through either surface is classified the same way. :field_flags carries the undecoded entry; PdfElixide.Form decodes it.

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()
}