pub enum AnnotationKind {
Show 20 variants
Text {
contents: String,
icon: Option<String>,
open: bool,
},
Link {
uri: String,
},
FreeText {
contents: String,
default_appearance: Option<String>,
quadding: FreeTextQuadding,
},
Highlight {
quad_points: Vec<[f32; 8]>,
},
Underline {
quad_points: Vec<[f32; 8]>,
},
Squiggly {
quad_points: Vec<[f32; 8]>,
},
StrikeOut {
quad_points: Vec<[f32; 8]>,
},
Stamp {
icon: Option<String>,
contents: Option<String>,
},
Square {
interior_colour: Option<Vec<f32>>,
line_width: Option<f32>,
},
Circle {
interior_colour: Option<Vec<f32>>,
line_width: Option<f32>,
},
Ink {
strokes: Vec<Vec<f32>>,
},
Line {
endpoints: [f32; 4],
line_endings: Option<[String; 2]>,
interior_colour: Option<Vec<f32>>,
leader_line: Option<f32>,
leader_line_extension: Option<f32>,
leader_line_offset: Option<f32>,
cap: bool,
intent: Option<String>,
},
Polygon {
vertices: Vec<f32>,
interior_colour: Option<Vec<f32>>,
intent: Option<String>,
},
PolyLine {
vertices: Vec<f32>,
line_endings: Option<[String; 2]>,
interior_colour: Option<Vec<f32>>,
intent: Option<String>,
},
Caret {
rect_diffs: Option<[f32; 4]>,
symbol: CaretSymbol,
},
Popup {
parent_index: Option<usize>,
open: bool,
},
FileAttachment {
icon: Option<String>,
file_name: String,
file_bytes: Vec<u8>,
mime_type: Option<String>,
},
Sound {
icon: Option<String>,
sampling_rate: f32,
channels: u32,
bits_per_sample: u32,
encoding: SoundEncoding,
sound_samples: Vec<u8>,
},
PrinterMark {
mark_name: Option<String>,
},
Watermark {
fixed_print: Option<FixedPrintSpec>,
},
}Expand description
Per-subtype annotation payload — round 32 covers the five most-common interactive PDF annotation families per §12.5.6 (Text, Link, FreeText, Highlight/Underline/Squiggly/StrikeOut, Stamp) plus three additional ones (Square, Circle, Ink) that show up in markup-heavy PDFs (review / proof workflows).
Variants§
Text
/Subtype /Text — sticky-note (§12.5.6.4, Table 172).
Fields
Link
/Subtype /Link — hyperlink (§12.5.6.5, Table 173). Round 32
covers only the URI form; in-document goto-destination links
already have the richer crate::LinkAnnotationSpec surface
from round 25.
FreeText
/Subtype /FreeText — in-page text overlay (§12.5.6.6, Table 174).
Fields
default_appearance: Option<String>/DA default appearance string (a content-stream snippet
per §12.7.3.3 — /Helv 12 Tf 0 g-style). None ⇒ writer
supplies (/Helv 12 Tf 0 g).
quadding: FreeTextQuadding/Q quadding: 0 left, 1 centre, 2 right.
Highlight
/Subtype /Highlight (§12.5.6.10, Table 179).
Fields
Underline
/Subtype /Underline (§12.5.6.10, Table 179).
Squiggly
/Subtype /Squiggly (§12.5.6.10, Table 179).
StrikeOut
/Subtype /StrikeOut (§12.5.6.10, Table 179).
Stamp
/Subtype /Stamp — rubber-stamp (§12.5.6.13, Table 184).
Fields
Square
/Subtype /Square — rectangle markup (§12.5.6.8, Table 177).
Fields
Circle
/Subtype /Circle — ellipse markup (§12.5.6.8, Table 177).
Fields
Ink
/Subtype /Ink — freehand scribble (§12.5.6.13, Table 185).
Fields
Line
/Subtype /Line — straight-line markup (§12.5.6.7, Table 175,
round 227). Two-endpoint line on the page; the outer
Annotation::rect is the bounding box, the /L four-real
array carries the line itself.
Fields
endpoints: [f32; 4]/L [x1 y1 x2 y2] — line endpoints in default user space.
Required per Table 175.
line_endings: Option<[String; 2]>/LE [name1 name2] — two-element line-ending styles
(Table 176 enumerates None, Square, Circle, Diamond,
OpenArrow, ClosedArrow, Butt, ROpenArrow,
RClosedArrow, Slash). Defaults to [/None /None] per
Table 175 when None (the writer omits the entry, matching
the round-197 reader’s “absent → default” contract).
interior_colour: Option<Vec<f32>>/IC interior colour for filled line-ending shapes. Same
0/1/3/4-component layout as outer /C. None ⇒ entry
omitted.
leader_line: Option<f32>/LL leader-line length, in default user-space units.
None ⇒ entry omitted (Table 175 default 0).
leader_line_extension: Option<f32>/LLE leader-line extension length (≥ 0). None ⇒ entry
omitted (Table 175 default 0).
Polygon
/Subtype /Polygon — closed polygon markup (§12.5.6.9,
Table 178, round 227). Carries the /Vertices flat vertex
array plus the Table 178 optional fields.
Fields
vertices: Vec<f32>/Vertices [x1 y1 x2 y2 …] — alternating coordinates in
default user space. Required per Table 178.
interior_colour: Option<Vec<f32>>/IC interior colour. Same layout as the outer /C. The
spec lists /LE for both Polygon and PolyLine but Table 178
notes it “Default value: [/None /None]”; the writer omits
it on Polygon to match the more-conformant
/PolyLine-only practice — callers that need a Polygon
with explicit line endings should use Self::PolyLine
instead.
PolyLine
/Subtype /PolyLine — open polyline markup (§12.5.6.9,
Table 178, round 227). Carries the /Vertices flat vertex
array plus the Table 178 optional fields (/LE, /IC, /IT).
Fields
vertices: Vec<f32>/Vertices [x1 y1 x2 y2 …] — alternating coordinates in
default user space. Required per Table 178.
line_endings: Option<[String; 2]>/LE [name1 name2] — start/end line endings. Same name
taxonomy as Self::Line. None ⇒ entry omitted (spec
default [/None /None]).
Caret
/Subtype /Caret — text-edit caret marker (§12.5.6.11,
Table 180, round 232). Indicates the presence of text edits at
the position of the outer Annotation::rect. Optional
/RD shrinks the caret figure inside the rectangle (e.g. when
/Sy /P displays a paragraph mark whose bounds exceed the bare
caret); /Sy selects the rendered symbol.
Fields
rect_diffs: Option<[f32; 4]>/RD rectangle differences [left top right bottom],
each ≥ 0. The four values are the inset of the caret
figure inside the outer /Rect. None ⇒ entry omitted
(the caret fills the rectangle).
symbol: CaretSymbol/Sy — caret symbol selector per Table 180.
Popup
/Subtype /Popup — text-entry pop-up window (§12.5.6.14,
Table 183, round 232). A Popup is the editing surface for a
markup parent (Text, FreeText, Highlight, Caret, …); it carries
no appearance of its own and exists only to display the
parent’s /Contents for editing.
The /Parent field is normatively an indirect reference per
Table 183; the writer takes a 0-based index into the same
annotations slice as [Self::parent_index] and resolves it
to the actual on-wire object id after every annotation has
been allocated.
Fields
parent_index: Option<usize>0-based index into the annotations slice passed to
write_pdf_with_annotations identifying the parent
markup annotation whose /Contents / /M / /C / /T
fields override this Popup’s per Table 183. None ⇒
/Parent entry omitted (the spec example in §12.5.6.14
treats this as malformed — a Popup with no parent has no
editing target — but tolerant readers still surface the
dict, so the writer permits it).
FileAttachment
/Subtype /FileAttachment — embedded-file marker (§12.5.6.15
Table 184, round 238). The on-page paperclip / push-pin icon
for a file embedded inside the PDF.
Writing one of these causes the writer to additionally emit
(a) a /Type /EmbeddedFile stream object carrying
file_bytes (FlateDecode-compressed when smaller),
(b) a /Type /Filespec dictionary naming file_name and
pointing at the stream via /EF, and (c) a catalog
/Names → /EmbeddedFiles name tree entry keyed on
file_name so the round-33 read_pdf_attachments enumerator
surfaces the same file. The annotation’s /FS entry holds
the indirect reference to the filespec dict per Table 184.
Fields
icon: Option<String>/Name icon identifier — Table 184 enumerates
PushPin (default), GraphPushPin, PaperclipTag, and
the more general Graph / Paperclip / Tag names.
None ⇒ writer emits /PushPin.
file_name: StringUser-visible file name written into the filespec’s /F
(PDFDocEncoded literal when ASCII) and /UF (UTF-16BE
hex with BOM) entries per §7.11.2 Table 43, and used as
the name-tree key per §7.7.4 + §7.9.6.
Sound
/Subtype /Sound — sound annotation (§12.5.6.16 Table 185,
round 245). The annotation pins a /Sound stream object to a
page; activation plays the sample data through the viewer’s
audio output. The §13.3 stream (Table 294) is materialised by
the writer’s pre-pass, and the annotation’s /Sound entry
resolves to that stream’s indirect reference.
Fields
icon: Option<String>/Name icon identifier — Table 185 names Speaker
(default) and Mic. Authoring tools may extend this set;
None ⇒ writer emits /Speaker.
sampling_rate: f32/R sampling rate, in samples per second per channel
(§13.3 Table 294). Required. Common conforming values per
the §13.3 portability guidance are 8000, 11025, and
22050; the writer accepts any positive value.
channels: u32/C number of channels (§13.3 Table 294). Default value
1. The §13.3 portability guidance recommends 1 or 2;
the writer accepts any value ≥ 1 and omits the entry when
it equals the spec default to round-trip an
absent-equals-default reader contract.
bits_per_sample: u32/B bits per sample value per channel (§13.3 Table 294).
Default value 8. The writer accepts any value ≥ 1 and
omits the entry when it equals the spec default.
encoding: SoundEncoding/E encoding format for the sample data (§13.3 Table 294).
Default value SoundEncoding::Raw. The writer omits the
entry when this variant is set so a write-then-read cycle
surfaces an absent-equals-default reader shape.
sound_samples: Vec<u8>Raw sample bytes that form the §13.3 stream body. Byte order is big-endian for samples larger than 8 bits per the §13.3 packing rule (caller responsibility — the writer passes the buffer through verbatim). For stereo samples, the caller interleaves left then right per channel per the §13.3 interleave rule.
PrinterMark
/Subtype /PrinterMark — production printer’s mark
(§12.5.6.20 Table 362, round 257). PDF 1.4. The on-page
registration target, colour bar, cut mark, or page-information
bar a print-production tool stamps onto every output sheet.
Per Table 362 the only annotation-dict-local entry is the
optional /MN (mark-name) Name identifying the type of mark
(e.g. ColorBar, RegistrationTarget, CutMark,
PageInformation). The actual mark graphics live in the
form-XObject appearance stream referenced from /AP /N; the
/MarkStyle and /Colorants entries in Table 363 hang off
that form XObject, not the annot dict — so they are out of
scope for the round-257 writer just as they are for the
round-215 reader.
None ⇒ writer omits /MN entirely, matching the spec’s
“optional” wording and the round-215 reader’s “absent → None”
shape. Per Table 362 a PrinterMark annotation should additionally
carry /Type /PrinterMark (in addition to the §12.5.2 Table 164
/Type /Annot) — the writer emits that marker via the
/Subtype slot, which is what every observed producer relies
on (the second /Type entry is rarely emitted in the wild
because the §12.5.2 /Type /Annot slot already designates the
dictionary as an annotation).
Fields
mark_name: Option<String>/MN — arbitrary Name identifying the kind of mark
(Table 362). None ⇒ entry omitted (the spec makes it
optional). Common values include ColorBar,
RegistrationTarget, CutMark, PageInformation; the
spec does not enumerate a closed set, so the writer
passes any caller-supplied Name through verbatim.
An empty Some(String::new()) is rejected at validation
time — a Name token is required to be at least one byte
per §7.3.5, and a zero-byte mark name would not identify
any taxonomy entry.
Watermark
/Subtype /Watermark — fixed-print graphics (§12.5.6.22
Table 190, round 252). Used for content that prints at a fixed
size + position regardless of the dimensions of the printed
page — page-number stamps, copyright marks, “DRAFT” overlays
laid out per Table 191’s media-relative geometry.
Per Table 190 the only sub-entry is the optional /FixedPrint
dict (carried here as FixedPrintSpec). None leaves the
/FixedPrint entry off the annotation dict, matching the
Table 190 wording: “If this entry is not present, the
annotation shall be drawn without any special consideration for
the dimensions of the target media.”
Fields
fixed_print: Option<FixedPrintSpec>/FixedPrint sub-dict (§12.5.6.22 Table 191). None ⇒
entry omitted (the watermark draws without media-relative
positioning, per Table 190).
Trait Implementations§
Source§impl Clone for AnnotationKind
impl Clone for AnnotationKind
Source§fn clone(&self) -> AnnotationKind
fn clone(&self) -> AnnotationKind
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more