Skip to contents

Stage annotation style defaults

Source: R/stage.R
pz_stage_annotate.Rd

Sets style defaults for new annotations in screenshots and recordings. An omitted argument leaves its setting alone, an explicit NULL restores the built-in default, and a value sets it. The defaults apply to the pipeline the staged context flows through: pz_find*() contexts inherit them, while a fresh pipeline from the original context starts from the defaults – assign the result (page <- page |> pz_stage_annotate(...)) to set page-wide defaults. Per-call annotation style arguments override these defaults; note the per-call names on pz_annotate() differ (label_fill/label_text_color) from the staged names (fill/text_color), and the staged fill and text color style callout chrome only, not mark badges.

Usage

pz_stage_annotate(
  ctx,
  ...,
  color = NULL,
  fill = NULL,
  text_color = NULL,
  stroke_width = NULL,
  distance = NULL,
  font_family = NULL,
  font_size = NULL,
  caption_side = NULL
)

Arguments

ctx

A paparazzi context.

...

Checked empty; reserved for future use.

color

CSS accent color for new annotations: mark outlines, callout bubble borders, leader lines and decorations. The default is "#e11d48". Supply NULL to restore the default.

fill

CSS background color for new callout bubbles and their badges. By default, the fill follows each callout's resolved color. Supply NULL to restore this default. Callout chrome only: pz_annotate() mark badges follow their mark's color unless overridden per call with label_fill.

text_color

CSS text color for new callout bubbles and their badges. By default, paparazzi chooses black or white for the higher WCAG contrast ratio against the resolved fill. Supply NULL to restore this default. Callout chrome only, like fill.

stroke_width

Stroke width in CSS pixels for new annotation marks and callout leader lines; decoration sizes scale with it. The default is 3. Supply NULL to restore the default.

distance

Bubble-to-target gap in CSS pixels for new callouts, with or without a leader. By default the gap is 24 with a leader and 8 without one. Supply NULL to restore the default.

font_family

CSS font family for new annotation badges and key callouts. The default is "sans-serif". Supply NULL to restore the 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. The default is 14. Supply NULL to restore the default.

caption_side

Default side for new pz_annotate_caption() captions: "bottom" (the default) or "top". Supply NULL to restore the default.

Value

ctx, invisibly.

See also

pz_stage(), pz_stage_frame(), pz_annotate()

Examples

page <- pz_open(pz_example("tasks"))
path <- file.path(tempdir(), "tasks.png")

# Assignment makes these styles page-wide defaults for new annotations
page <- page |> pz_stage_annotate(color = "#2563eb", font_size = 16)
page |> pz_annotate("#add-task", label = TRUE) |> pz_screenshot(path)

# A one-off pipeline can undo a default with NULL: its callout uses
# the built-in red again
page |>
  pz_stage_annotate(color = NULL) |>
  pz_annotate("#task-title", label = TRUE) |>
  pz_screenshot(path, frame = pz_frame("#task-title", pad = 16, target_box = "annotated"))
pz_close(page)