# `PdfElixide.Document.Annotation`
[🔗](https://github.com/r8/pdf_elixide/blob/v0.16.0/lib/pdf_elixide/document/annotation.ex#L1)

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 `t:color/0`).

# `action`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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()
}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*