Mark page elements

Draws an annotation for each element matched by target. Annotations follow their elements as the page scrolls or changes layout, and appear in screenshots and recordings until cleared with pz_annotate_clear(). Annotations belong to the current document; navigating away removes them. Marks respect the target's overflow containers (axis-aligned clipping only, not a custom overflow-clip-margin). Badges prefer a position above the visible mark's top-left corner, outside those clips. For targets inside the viewport, paparazzi shifts settled badges just enough to fit, overlapping the target if needed at the top edge. Badges larger than the viewport align with its top or left edge and may still be clipped; paparazzi does not resize them. Off-viewport targets keep their badges attached, and a screenshot's frame crop can still exclude a badge. Badges size to their labels, wrapping long labels at 20em rather than at the target's width. On sides where the target is not cut off, the clip leaves room for the mark's pad so its outline stays intact. A mark and its badge hide while the target is disconnected, not rendered, visibility: hidden with no visible descendants, or entirely clipped, even if its padding would reach into view. Zero-size targets on a clipping edge also stay hidden.

Usage

pz_annotate(
  ctx,
  target = NULL,
  ...,
  type = "box",
  label = NULL,
  pad = 0,
  reveal = c("auto", "fade", "draw", "pop", "slide", "wipe", "none"),
  id = NULL,
  color = NULL,
  label_fill = NULL,
  label_text_color = NULL,
  stroke_width = NULL,
  font_family = NULL,
  font_size = NULL
)

Arguments

ctx: A paparazzi context.
target: A selector, pz_loc() spec, or list of targets. NULL uses the current scope, or document.body at the root.
...: Checked empty; reserved for future use.
type: "box" (outline), "circle" (ellipse), "underline" (bottom stroke), or "highlight" (translucent fill blended over the page).
label: Optional badge. TRUE numbers the matches 1, 2, ...; one string or number repeats on each match. NULL omits the badge.
pad: Extra CSS pixels around each element: one number or c(top, right, bottom, left). Defaults to zero.
reveal: "auto" (the default) uses "fade" for boxes and "draw" for other types. Other choices are "fade", "draw", "pop", "slide", "wipe", or "none". Reveals animate only during an active, unpaused recording; clearing reverses the reveal. Wipe sweeps clockwise from 12 o'clock.
id: Optional nonempty id. Reusing it replaces its annotations; NULL generates a unique id, so calls accumulate annotations. "spotlight" and "caption" are reserved for other types.
color: CSS accent color for the mark outline, or NULL for the staged default from pz_stage_annotate().
label_fill, label_text_color: CSS colors for the badge background and text. NULL (the default) fills the badge with the mark's color and uses white text. The fill and text_color set by pz_stage_annotate() style callouts, not mark badges.
stroke_width: Mark stroke width in CSS pixels, or NULL for the staged stroke_width from pz_stage_annotate().
font_family: CSS font family for the badge, or NULL for the staged default. A font object staged with pz_stage_fonts() is also accepted and resolves to its family with a sans-serif fallback.
font_size: Badge font size in CSS pixels, or NULL for the page default.

Value

ctx, invisibly.

Usage

Arguments

Value

See also