Enum AnnotSpec 

#[non_exhaustive]
pub enum AnnotSpec {
    #[non_exhaustive]
    Highlight {
        rect: Rect,
        color: Color,
        quads: Vec<Quad>,
        contents: Option<String>,
    },
    #[non_exhaustive]
    Text {
        rect: Rect,
        color: Color,
        contents: Option<String>,
        icon: Name,
        open: bool,
    },
    #[non_exhaustive]
    Square {
        rect: Rect,
        color: Color,
        contents: Option<String>,
        border: AnnotBorder,
        interior: Option<Color>,
    },
    #[non_exhaustive]
    Underline {
        rect: Rect,
        color: Color,
        quads: Vec<Quad>,
        contents: Option<String>,
    },
    #[non_exhaustive]
    StrikeOut {
        rect: Rect,
        color: Color,
        quads: Vec<Quad>,
        contents: Option<String>,
    },
    #[non_exhaustive]
    Squiggly {
        rect: Rect,
        color: Color,
        quads: Vec<Quad>,
        contents: Option<String>,
    },
    #[non_exhaustive]
    Ink {
        rect: Rect,
        color: Color,
        strokes: Vec<Vec<Point>>,
        contents: Option<String>,
        border: AnnotBorder,
    },
    #[non_exhaustive]
    FreeText {
        rect: Rect,
        color: Color,
        contents: String,
        da: String,
        align: Option<Alignment>,
    },
    #[non_exhaustive]
    Circle {
        rect: Rect,
        color: Color,
        contents: Option<String>,
        border: AnnotBorder,
        interior: Option<Color>,
    },
    #[non_exhaustive]
    Line {
        rect: Rect,
        color: Color,
        start: Point,
        end: Point,
        contents: Option<String>,
        border: AnnotBorder,
        line_endings: Option<(LineEndingStyle, LineEndingStyle)>,
        interior: Option<Color>,
    },
    #[non_exhaustive]
    Link {
        rect: Rect,
        action: AnnotLinkAction,
        contents: Option<String>,
        color: Option<Color>,
        border: AnnotBorder,
        highlight: AnnotLinkHighlight,
    },
    #[non_exhaustive]
    Caret {
        rect: Rect,
        color: Color,
        contents: Option<String>,
    },
}

What kind of annotation to create and attach to a page.

This is the write payload for add_annotation. The ISO subtype spelling itself is pdfrum_doc::Subtype (also re-exported from the facade): reading an annotation yields Subtype, while building one takes an AnnotSpec variant that carries the keys that subtype needs.

Each variant carries the keys Rotero’s write_annotations needs today. Appearance streams are generated when the subtype has a generator.

Prefer the associated constructors (highlight, text, …) over spelling every field at the call site.

use pdfrum::{Color, Document, MarkupKind, MarkupSpec, Rect, SaveOptions};

let doc = Document::open("tests/fixtures/hello_world.pdf")?;
let mut edit = doc.edit();
let rect = Rect::new(72.0, 700.0, 200.0, 720.0);
edit.add_annotation(
    0,
    MarkupSpec::new(MarkupKind::Highlight, rect, Color::from_rgb8(255, 230, 0)).contents("note"),
)?;
let mut bytes = Vec::new();
edit.write_to(&mut bytes, &SaveOptions::default())?;

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

#[non_exhaustive]

Highlight

A highlight over one or more text runs (/Subtype /Highlight).

/QuadPoints is required and must hold at least one quadrilateral.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

rect: Rect

The annotation’s /Rect in page space.

color: Color

Annotation colour /C as DeviceRGB in 0..1.

quads: Vec<Quad>

Text runs covered; each becomes eight numbers in tl, tr, bl, br order.

contents: Option<String>

Optional /Contents.

#[non_exhaustive]

Text

A sticky-note text annotation (/Subtype /Text).

Defaults to /Name /Comment and /Open false (see TextSpec).

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

rect: Rect

The annotation’s /Rect in page space.

color: Color

Annotation colour /C as DeviceRGB in 0..1.

contents: Option<String>

Optional /Contents.

icon: Name

Sticky-note icon name (/Name). Defaults to /Comment.

open: bool

Whether the pop-up starts open (/Open). Defaults to false.

#[non_exhaustive]

Square

A square / area annotation (/Subtype /Square).

Writes /BS with AnnotBorder (default width 2, solid) and /Type /Border.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

rect: Rect

The annotation’s /Rect in page space.

color: Color

Annotation colour /C as DeviceRGB in 0..1.

contents: Option<String>

Optional /Contents.

border: AnnotBorder

Border style dictionary (/BS).

interior: Option<Color>

Interior fill /IC. None leaves the shape unfilled, which is what an absent or empty /IC means to a reader.

#[non_exhaustive]

Underline

An underline over one or more text runs (/Subtype /Underline).

/QuadPoints is required and must hold at least one quadrilateral.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

rect: Rect

The annotation’s /Rect in page space.

color: Color

Annotation colour /C as DeviceRGB in 0..1.

quads: Vec<Quad>

Text runs covered; each becomes eight numbers in tl, tr, bl, br order.

contents: Option<String>

Optional /Contents.

#[non_exhaustive]

StrikeOut

A strike-out over one or more text runs (/Subtype /StrikeOut).

/QuadPoints is required and must hold at least one quadrilateral.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

rect: Rect

The annotation’s /Rect in page space.

color: Color

Annotation colour /C as DeviceRGB in 0..1.

quads: Vec<Quad>

Text runs covered; each becomes eight numbers in tl, tr, bl, br order.

contents: Option<String>

Optional /Contents.

#[non_exhaustive]

Squiggly

A squiggly underline over one or more text runs (/Subtype /Squiggly).

/QuadPoints is required and must hold at least one quadrilateral.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

rect: Rect

The annotation’s /Rect in page space.

color: Color

Annotation colour /C as DeviceRGB in 0..1.

quads: Vec<Quad>

Text runs covered; each becomes eight numbers in tl, tr, bl, br order.

contents: Option<String>

Optional /Contents.

#[non_exhaustive]

Ink

Freehand ink strokes (/Subtype /Ink).

Writes /InkList as an array of strokes (each a flat array of x,y pairs) and /BS from AnnotBorder (no /Type /Border, matching prior Ink writes).

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

rect: Rect

The annotation’s /Rect in page space.

color: Color

Annotation colour /C as DeviceRGB in 0..1.

strokes: Vec<Vec<Point>>

Strokes in page space; each stroke is a sequence of points.

contents: Option<String>

Optional /Contents.

border: AnnotBorder

Border style dictionary (/BS).

#[non_exhaustive]

FreeText

A free-text annotation (/Subtype /FreeText).

/Contents and /DA are both required. See DEFAULT_DA for a common appearance string.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

rect: Rect

The annotation’s /Rect in page space.

color: Color

Annotation colour /C as DeviceRGB in 0..1.

contents: String

The visible text (/Contents).

da: String

Default appearance string (/DA), e.g. DEFAULT_DA.

align: Option<Alignment>

Text alignment, written as /Q. None writes no key, which a reader takes as flush left.

#[non_exhaustive]

Circle

A circle / ellipse annotation (/Subtype /Circle).

Writes /BS like AnnotSpec::Square (includes /Type /Border). Appearance is generated when the circle AP pipeline is available.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

rect: Rect

The annotation’s /Rect in page space.

color: Color

Annotation colour /C as DeviceRGB in 0..1.

contents: Option<String>

Optional /Contents.

border: AnnotBorder

Border style dictionary (/BS).

interior: Option<Color>

Interior fill /IC. None leaves the shape unfilled, which is what an absent or empty /IC means to a reader.

#[non_exhaustive]

Line

A straight line (/Subtype /Line) with endpoints /L.

Appearance strokes between the endpoints using /BS width and /C, with optional /LE endings and /IC interior fill for closed endings.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

rect: Rect

The annotation’s /Rect in page space.

color: Color

Annotation colour /C as DeviceRGB in 0..1.

start: Point

Line start in page space (/L x1,y1).

end: Point

Line end in page space (/L x2,y2).

contents: Option<String>

Optional /Contents.

border: AnnotBorder

Border style dictionary (/BS).

line_endings: Option<(LineEndingStyle, LineEndingStyle)>

Optional line endings (/LE start, end). None omits /LE (prior behaviour).

interior: Option<Color>

Optional interior colour (/IC) for filled line endings.

#[non_exhaustive]

Link

A link annotation (/Subtype /Link) with a typed /A action.

Appearance honours /BS / /C. /H is written for viewer click feedback only — see AnnotLinkHighlight. See AnnotLinkAction for URI, GoTo, and named-destination forms.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

rect: Rect

The annotation’s /Rect in page space.

action: AnnotLinkAction

Action dictionary payload (/A).

contents: Option<String>

Optional /Contents.

color: Option<Color>

Optional annotation colour /C. None omits /C (AP uses muted blue).

border: AnnotBorder

Border style dictionary (/BS). Default width 1, solid.

highlight: AnnotLinkHighlight

Highlight mode (/H). Default AnnotLinkHighlight::Invert.

#[non_exhaustive]

Caret

A caret / insertion-point annotation (/Subtype /Caret).

Appearance draws a simple caret mark inside /Rect.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

rect: Rect

The annotation’s /Rect in page space.

color: Color

Annotation colour /C as DeviceRGB in 0..1.

contents: Option<String>

Optional /Contents.

Implementations

impl AnnotSpec

pub fn with_contents(self, contents: impl Into<String>) -> Self

Sets /Contents on variants that take optional contents.

AnnotSpec::FreeText already requires contents at construction; this leaves it unchanged.

use pdfrum_edit::{AnnotSpec, TextSpec};
use kurbo::Rect;
use peniko::Color;

let spec: AnnotSpec = TextSpec::new(Rect::new(0.0, 0.0, 1.0, 1.0), Color::from_rgb8(255, 255, 0))
    .contents("sticky")
    .into();
assert!(matches!(
    spec,
    AnnotSpec::Text {
        contents: Some(ref c),
        ..
    } if c == "sticky"
));

pub fn with_meta(self, meta: AnnotMeta) -> AnnotWrite

Attach author (/T), unique name (/NM), and/or modification date (/M).

pub fn with_author(self, author: impl Into<String>) -> AnnotWrite

Sets the annotation author (/T).

pub fn with_name(self, name: impl Into<String>) -> AnnotWrite

Sets the annotation unique name (/NM), typically a stable id.

pub fn with_modified(self, modified: impl Into<String>) -> AnnotWrite

Sets /M from a PDF date string (e.g. from crate::pdf_date).

pub fn with_flags(self, flags: AnnotFlags) -> AnnotWrite

Sets /F annotation flags (default when omitted is Print).

use pdfrum_doc::AnnotFlags;
use pdfrum_edit::{AnnotSpec, TextSpec};
use kurbo::Rect;
use peniko::Color;

let write = TextSpec::new(Rect::new(0.0, 0.0, 1.0, 1.0), Color::from_rgb8(255, 255, 0))
    .flags(AnnotFlags::PRINT | AnnotFlags::NO_ZOOM);
assert_eq!(write.meta.flags, Some(AnnotFlags::PRINT | AnnotFlags::NO_ZOOM));

pub fn with_opacity(self, opacity: f32) -> AnnotWrite

Sets /CA, the constant opacity, from 0.0 to 1.0.

Applies to every subtype: the generator folds it into the appearance’s /ExtGState, so a translucent highlight is written the same way an opaque one is.

use pdfrum_edit::{AnnotSpec, MarkupKind, MarkupSpec};
use kurbo::Rect;
use peniko::Color;

let spec = MarkupSpec::new(
    MarkupKind::Highlight,
    Rect::new(0.0, 0.0, 10.0, 2.0),
    Color::from_rgb8(255, 255, 0),
);
let write = AnnotSpec::from(spec).with_opacity(0.4);
assert_eq!(write.meta.opacity, Some(0.4));

Trait Implementations

impl Clone for AnnotSpec

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AnnotSpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<AnnotSpec> for AnnotWrite

fn from(spec: AnnotSpec) -> Self

Converts to this type from the input type.

impl From<CaretSpec> for AnnotSpec

fn from(b: CaretSpec) -> Self

Converts to this type from the input type.

impl From<CircleSpec> for AnnotSpec

fn from(b: CircleSpec) -> Self

Converts to this type from the input type.

impl From<FreeTextSpec> for AnnotSpec

fn from(b: FreeTextSpec) -> Self

Converts to this type from the input type.

impl From<InkSpec> for AnnotSpec

fn from(b: InkSpec) -> Self

Converts to this type from the input type.

impl From<LineSpec> for AnnotSpec

fn from(b: LineSpec) -> Self

Converts to this type from the input type.

impl From<LinkSpec> for AnnotSpec

fn from(b: LinkSpec) -> Self

Converts to this type from the input type.

impl From<MarkupSpec> for AnnotSpec

fn from(b: MarkupSpec) -> Self

Converts to this type from the input type.

impl From<SquareSpec> for AnnotSpec

fn from(b: SquareSpec) -> Self

Converts to this type from the input type.

impl From<TextSpec> for AnnotSpec

fn from(b: TextSpec) -> Self

Converts to this type from the input type.

impl PartialEq for AnnotSpec

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for AnnotSpec