Phase 3: page setup and printing (#121)

* Add xl_page_setup() with the scalar print options

xl_sheet(page =) takes an xl_page_setup() describing how the sheet prints:
orientation, paper size, margins, scaling, fit-to-pages, centring, starting
page number, page-layout view, and the print options (across, black and white,
row and column headings). None of it touches the cells.

paper accepts friendly names mapped to Excel's numeric types, and a raw index
for the envelope and specialist sizes not worth naming; the range is capped at
libxlsxwriter's real 0-118, since outside it worksheet_set_paper() warns and
ignores the value, which from R would be a silent no-op.

worksheet_set_start_page() is the one setter in libxlsxwriter that does not
raise page_setup_changed, so a first_page on its own emitted no <pageSetup>
element and was silently dropped. worksheet_set_paper() does raise it, and
paper size 0 writes no attribute, so it is called alongside first_page as a
harmless way to mark the sheet as having a page setup.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* Add page headers and footers

xl_page_setup() gains header, footer, header_margin and footer_margin, reaching
worksheet_set_header/_opt and worksheet_set_footer/_opt. Excel's own &-codes
are passed through untouched; the plain setter is used when no margin is given
and the _opt form only when one is.

Two libxlsxwriter behaviours are surfaced in R rather than left to fail
obscurely. A margin is applied only when greater than zero, so a zero would be
silently ignored and is now an error naming Excel's 0.3 default. An &G or
&[Picture] placeholder needs a matching image, which writexl cannot supply
until images land, so it is rejected with a message that says so instead of
libxlsxwriter's opaque parameter-validation error.

The 255-character cap is enforced in R, counting characters rather than bytes
as lxw_utf8_strlen() does.

Header and footer images are deliberately deferred: lxw_header_footer_options
carries image_left/center/right, and those belong with the rest of the image
handling rather than being built twice.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* Add print area, repeat rows/columns, and page breaks

xl_page_setup() gains print_area, repeat_rows, repeat_cols, h_breaks and
v_breaks, completing the page-setup surface.

print_area goes through the Phase 0 range resolver, so it takes an A1 string or
a list(rows =, cols =) spec like every other range argument. repeat_rows and
repeat_cols take either a count or a range string, and count *sheet* rows with
the header included rather than data rows -- repeating the header row is the
usual reason to reach for them, and data-row numbering could not name it.

Page breaks are given as 1-based positions where a new page starts, matching
how Excel describes them, and converted to libxlsxwriter's 0-based form. A
break at position 1 is refused: libxlsxwriter terminates its break array with a
0, so a 0-based break of 0 would silently discard every break rather than
merely doing nothing. Breaks are sorted and deduplicated, and capped at Excel's
limit of 1023. Setting breaks together with fit_to warns, since Excel ignores
manual breaks when fit-to-page is on.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* Document page setup in the vignette and NEWS

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: billdenney

NAMESPACE

@@ -9,6 +9,7 @@ S3method(length,xl_cell_general)
 S3method(print,xl_cell_general)
 S3method(print,xl_comment)
 S3method(print,xl_format)
+S3method(print,xl_page_setup)
 S3method(print,xl_properties)
 S3method(print,xl_rich_run)
 S3method(print,xl_rich_string)
@@ -33,6 +34,7 @@ export(xl_formula)
 export(xl_hyperlink)
 export(xl_hyperlink_cell)
 export(xl_num_format)
+export(xl_page_setup)
 export(xl_properties)
 export(xl_protection)
 export(xl_rich_run)

NEWS.md

@@ -24,6 +24,11 @@
 * **Rich strings** — one cell whose text is split into differently formatted
   runs — via `xl_rich_string()` and `xl_rich_run()`.
 
+* **Page setup and printing** via `xl_sheet(page = xl_page_setup(...))`:
+  orientation, paper size, margins, scaling and fit-to-pages, centring, headers
+  and footers, print area, repeating heading rows/columns, manual page breaks,
+  and the print options.
+
 * `xl_properties(hyperlink_format = NULL)` writes hyperlinks with no styling at
   all, which was previously impossible.
 

R/xl_page_setup.R

@@ -141,6 +141,9 @@ xl_row_spec <- function(rows, height = NA, hidden = NA, level = NA,
 #'   per-comment `author` overrides it).
 #' @param show_comments If `TRUE`, all comments on the sheet are initially
 #'   shown (individual comments can still be forced via `xl_comment(visible=)`).
+#' @param page An [xl_page_setup()] describing how the sheet prints
+#'   (orientation, paper size, margins, scaling, header and footer). Affects
+#'   printing only, never the cell data.
 #' @return An `xl_sheet` object.
 #' @family writexl
 #' @seealso [xl_col_spec], [xl_row_spec], [write_xlsx]
@@ -158,7 +161,8 @@ xl_sheet <- function(data, cols = NULL, rows = NULL, freeze = NULL,
                      gridlines = NA, tab_color = NA, zoom = NA,
                      default_row_height = NA, auto_colwidth = FALSE,
                      autofilter = FALSE, protect = FALSE,
-                     comment_author = NA, show_comments = FALSE) {
+                     comment_author = NA, show_comments = FALSE,
+                     page = NULL) {
   if (!is.data.frame(data))
     stop("`data` must be a data frame", call. = FALSE)
   if (!is.logical(auto_colwidth) || length(auto_colwidth) != 1L || is.na(auto_colwidth))
@@ -184,7 +188,8 @@ xl_sheet <- function(data, cols = NULL, rows = NULL, freeze = NULL,
       autofilter = autofilter,
       protect    = protect,
       comment_author = comment_author,
-      show_comments  = show_comments
+      show_comments  = show_comments,
+      page           = page
     ),
     class = "xl_sheet"
   )
@@ -368,6 +373,7 @@ print.xl_sheet <- function(x, ...) {
   # author overrides the sheet default
   comment_author <- NA_character_
   show_comments <- FALSE
+  page_payload <- NULL
 
   if (inherits(el, "xl_sheet")) {
     # column specs
@@ -410,6 +416,7 @@ print.xl_sheet <- function(x, ...) {
     }
     overlay <- c(overlay, .as_overlay_list(el$overlay))
     protect <- .resolve_protect(el$protect)
+    page_payload <- .page_setup_payload(el$page, df, header_offset)
     comment_author <- el$comment_author
     show_comments <- isTRUE(el$show_comments)
     # auto column widths (for columns the user did not size explicitly)
@@ -435,6 +442,7 @@ print.xl_sheet <- function(x, ...) {
     overlay = overlay, protect = protect$flag,
     protect_password = protect$password, protect_options = protect$options,
     comment_author = as.character(comment_author),
-    show_comments = as.integer(show_comments)
+    show_comments = as.integer(show_comments),
+    page = page_payload
   )
 }