From fa43a8415badc6c34e65e30ea22e67124331d969 Mon Sep 17 00:00:00 2001 From: Jan Marvin Garbuszus Date: Wed, 23 Aug 2023 11:16:53 +0200 Subject: [PATCH 1/2] fix wb_add_data_validation() --- R/class-workbook-wrappers.R | 1 + 1 file changed, 1 insertion(+) diff --git a/R/class-workbook-wrappers.R b/R/class-workbook-wrappers.R index 132f0db37..0b393d59d 100644 --- a/R/class-workbook-wrappers.R +++ b/R/class-workbook-wrappers.R @@ -1943,6 +1943,7 @@ wb_add_data_validation <- function( assert_workbook(wb) wb$clone(deep = TRUE)$add_data_validation( sheet = sheet, + dims = dims, type = type, operator = operator, value = value, From 612b3974710917ed23a64aae66829bc112726c9a Mon Sep 17 00:00:00 2001 From: olivroy <52606734+olivroy@users.noreply.github.com> Date: Wed, 23 Aug 2023 13:54:36 -0400 Subject: [PATCH 2/2] Review documentation and examples (#749) * Separate add/remove comment from `create_comment()` as they do not return the same thing. Tweak docs as well. * Wrap long lines, combine remove add row heights together * progress * progress * progress * Another round of tweaks to docs and examples * Updates to docs * Progress * progress * last tweaks * fix r cmd check * Revert unintended change * Tweaks to pass R CMD check * More cleanup using `@inheritParams` for removing duplicated documentation for similar and deprecated functions * Tweaks * Unify function titles * Revert unintended change * Add possibility to interact with metadata * Improve warning * Address review comments * Revert --- R/class-comment.R | 14 +- R/class-workbook-wrappers.R | 1185 +++++++++-------- R/class-workbook.R | 21 +- R/get-named-regions.R | 29 +- R/helper-functions.R | 13 +- R/read.R | 37 +- R/utils.R | 4 +- R/wb_functions.R | 5 +- R/wb_load.R | 38 +- R/write.R | 129 +- R/xl_open.R | 19 +- _pkgdown.yml | 128 +- man/{comment.Rd => create_comment.Rd} | 33 +- man/create_sparklines.Rd | 13 +- man/delete_data.Rd | 21 + man/dims_helper.Rd | 6 +- man/named_region.Rd | 118 -- man/select_active_sheet.Rd | 42 - man/wbWorkbook.Rd | 12 +- man/wb_active_sheet.Rd | 43 + man/wb_add_border.Rd | 19 +- man/wb_add_cell_style.Rd | 17 +- man/wb_add_chart_xml.Rd | 4 +- man/wb_add_chartsheet.Rd | 14 +- man/wb_add_comment.Rd | 49 + man/wb_add_conditional_formatting.Rd | 53 +- man/wb_add_data.Rd | 35 +- man/wb_add_data_table.Rd | 47 +- man/wb_add_data_validation.Rd | 11 +- man/wb_add_drawing.Rd | 6 +- man/wb_add_dxfs_style.Rd | 20 +- man/wb_add_fill.Rd | 9 +- man/wb_add_font.Rd | 22 +- man/wb_add_form_control.Rd | 19 +- man/wb_add_formula.Rd | 36 +- man/wb_add_ignore_error.Rd | 15 +- man/wb_add_image.Rd | 3 +- man/wb_add_named_style.Rd | 24 +- man/wb_add_numfmt.Rd | 14 +- man/wb_add_pivot_table.Rd | 36 +- man/wb_add_sparklines.Rd | 10 +- man/wb_add_style.Rd | 25 +- man/wb_add_thread.Rd | 11 +- man/wb_add_worksheet.Rd | 75 +- man/wb_base_font.Rd | 34 +- man/{cell_style.Rd => wb_cell_style.Rd} | 26 +- man/{cleanup.Rd => wb_clean_sheet.Rd} | 21 +- man/wb_clone_sheet_style.Rd | 18 +- man/wb_clone_worksheet.Rd | 21 +- man/wb_col_widths.Rd | 37 +- man/wb_copy_cells.Rd | 27 +- man/wb_creators.Rd | 7 +- man/wb_data.Rd | 9 +- man/wb_filter.Rd | 2 +- man/wb_freeze_pane.Rd | 18 +- man/wb_get_named_regions.Rd | 35 +- man/wb_get_tables.Rd | 10 +- man/wb_grouping.Rd | 8 +- man/wb_load.Rd | 20 +- man/wb_merge_cells.Rd | 12 +- man/wb_named_region.Rd | 90 ++ man/wb_open.Rd | 7 +- man/wb_order.Rd | 2 +- man/wb_page_setup.Rd | 26 +- man/wb_protect.Rd | 16 +- man/wb_remove_row_heights.Rd | 28 - man/wb_remove_tables.Rd | 30 +- man/wb_remove_worksheet.Rd | 9 +- ...b_set_row_heights.Rd => wb_row_heights.Rd} | 22 +- man/wb_save.Rd | 10 +- man/wb_set_bookview.Rd | 6 +- man/wb_set_grid_lines.Rd | 6 +- man/wb_set_header_footer.Rd | 70 +- man/wb_set_last_modified_by.Rd | 6 +- man/wb_set_sheetview.Rd | 48 +- man/wb_sheet_names.Rd | 8 +- ...t_visibility.Rd => wb_sheet_visibility.Rd} | 20 +- man/wb_to_df.Rd | 25 +- man/wb_update_table.Rd | 15 +- man/wb_workbook.Rd | 8 +- man/write_data.Rd | 74 +- man/write_datatable.Rd | 69 +- man/xl_open.Rd | 16 +- 83 files changed, 1786 insertions(+), 1614 deletions(-) rename man/{comment.Rd => create_comment.Rd} (57%) create mode 100644 man/delete_data.Rd delete mode 100644 man/named_region.Rd delete mode 100644 man/select_active_sheet.Rd create mode 100644 man/wb_active_sheet.Rd create mode 100644 man/wb_add_comment.Rd rename man/{cell_style.Rd => wb_cell_style.Rd} (56%) rename man/{cleanup.Rd => wb_clean_sheet.Rd} (60%) create mode 100644 man/wb_named_region.Rd delete mode 100644 man/wb_remove_row_heights.Rd rename man/{wb_set_row_heights.Rd => wb_row_heights.Rd} (65%) rename man/{sheet_visibility.Rd => wb_sheet_visibility.Rd} (58%) diff --git a/R/class-comment.R b/R/class-comment.R index b2f0c96fb..a61333bcc 100644 --- a/R/class-comment.R +++ b/R/class-comment.R @@ -84,13 +84,9 @@ wbComment <- R6::R6Class( # TODO write_comment() should leverage wbWorkbook$addComment() more # TODO remove_comment() should leverage wbWorkbook$remove_comment() more -#' Create, write and remove comments +#' Create a comment #' -#' The comment functions (create, write and remove) allow the -#' modification of comments. In newer spreadsheet software they are called -#' notes, while they are called comments in openxml. Modification of what -#' newer spreadsheet software now calls comment is possible via -#' [wb_add_thread()]. +#' Creates a `wbComment` object. Use with [wb_add_comment()] to add to a worksheet location. #' #' @param text Comment text. Character vector. #' @param author Author of comment. A string. @@ -98,8 +94,9 @@ wbComment <- R6::R6Class( #' @param visible `TRUE` or `FALSE`. Is comment visible? #' @param width Textbox integer width in number of cells #' @param height Textbox integer height in number of cells +#' @returns a `wbComment` object +#' @seealso [wb_add_comment()] #' @export -#' @rdname comment #' @examples #' wb <- wb_workbook() #' wb$add_worksheet("Sheet 1") @@ -118,9 +115,6 @@ wbComment <- R6::R6Class( #' c3 <- create_comment(text = c("This Part Bold red\n\n", "This part black"), style = c(s1, s2)) #' #' wb$add_comment(sheet = 1, dims = wb_dims(3, 6), comment = c3) -#' -#' # remove the first comment c1 -#' wb$remove_comment(1, dims = "B10") create_comment <- function(text, author = Sys.info()[["user"]], style = NULL, diff --git a/R/class-workbook-wrappers.R b/R/class-workbook-wrappers.R index 0b393d59d..29007e3a9 100644 --- a/R/class-workbook-wrappers.R +++ b/R/class-workbook-wrappers.R @@ -1,7 +1,7 @@ #' Create a new Workbook object #' -#' Create a new Workbook object +#' Initialize a [wbWorkbook] object. You can set workbook properties as well. #' #' `theme` can be one of #' "Atlas", "Badge", "Berlin", "Celestial", "Crop", "Depth", "Droplet", @@ -16,7 +16,7 @@ #' @param theme Optional theme identified by string or number. #' See **Details** for options. #' @param ... additional arguments -#' @return A [wbWorkbook] object +#' @return A `wbWorkbook` object #' #' @export #' @family workbook wrappers @@ -53,12 +53,12 @@ wb_workbook <- function( } -#' Save Workbook to file +#' Save a workbook to file #' #' @param wb A `wbWorkbook` object to write to file #' @param file A path to save the workbook to -#' @param overwrite If `FALSE`, will not overwrite when `path` exists -#' @param path Deprecated argument previously used for file. Please use file in new code. +#' @param overwrite If `FALSE`, will not overwrite when `file` already exists. +#' @param path Deprecated argument. Please use `file` in new code. #' #' @export #' @family workbook wrappers @@ -89,28 +89,33 @@ wb_save <- function(wb, file = NULL, overwrite = TRUE, path = NULL) { #' @param wb A Workbook object containing a worksheet. #' @param sheet The worksheet to write to. Can be the worksheet index or name. #' @param x Object to be written. For classes supported look at the examples. -#' @param dims Spreadsheet dimensions that will determine `start_col` and `start_row`: "A1", "A1:B2", "A:B" -#' @param start_col A vector specifying the starting column to write to. -#' @param start_row A vector specifying the starting row to write to. +#' @param dims Spreadsheet cell range that will determine `start_col` and `start_row`: "A1", "A1:B2", "A:B" +#' @param start_col A vector specifying the starting column to write `x` to. +#' @param start_row A vector specifying the starting row to write `x` to. #' @param array A bool if the function written is of type array #' @param col_names If `TRUE`, column names of `x` are written. -#' @param row_names If `TRUE`, data.frame row names of `x` are written. -#' @param with_filter If `TRUE`, add filters to the column name row. NOTE can only have one filter per worksheet. -#' @param name If not NULL, a named region is defined. -#' @param sep Only applies to list columns. The separator used to collapse list columns to a character vector e.g. sapply(x$list_column, paste, collapse = sep). +#' @param row_names If `TRUE`, the row names of `x` are written. +#' @param with_filter If `TRUE`, add filters to the column name row. +#' NOTE: can only have one filter per worksheet. +#' @param name The name of a named region if specified. +#' @param sep Only applies to list columns. The separator used to collapse list +#' columns to a character vector e.g. `sapply(x$list_column, paste, collapse = sep)`. #' @param apply_cell_style Should we write cell styles to the workbook #' @param remove_cell_style keep the cell style? #' @param na.strings Value used for replacing `NA` values from `x`. Default -#' `na_strings()` uses the special `#N/A` value within the workbook. +#' [na_strings()] uses the special `#N/A` value within the workbook. #' @param inline_strings write characters as inline strings #' @param ... additional arguments #' @export -#' @details Formulae written using write_formula to a Workbook object will not get picked up by read_xlsx(). -#' This is because only the formula is written and left to Excel to evaluate the formula when the file is opened in Excel. -#' The string `"_openxlsx_NA"` is reserved for `openxlsx2`. If the data frame contains this string, the output will be broken. -#' Many base classes are covered, though not all and far from all third-party classes. When data of an unknown class is written, it is handled with `as.character()`. +#' @details Formulae written using [wb_add_formula()] to a Workbook object will +#' not get picked up by `read_xlsx()`. This is because only the formula is written +#' and left to Excel to evaluate the formula when the file is opened in Excel. +#' The string `"_openxlsx_NA"` is reserved for `openxlsx2`. +#' If the data frame contains this string, the output will be broken. +#' Many base classes are covered, though not all and far from all third-party classes. +#' When data of an unknown class is written, it is handled with `as.character()`. #' @family workbook wrappers -#' @return A clone of `wb` +#' @return A `wbWorkbook`, invisibly. #' @examples #' ## See formatting vignette for further examples. #' @@ -137,7 +142,7 @@ wb_save <- function(wb, file = NULL, overwrite = TRUE, path = NULL) { #' v <- rep("https://CRAN.R-project.org/", 4) #' names(v) <- paste0("Hyperlink", 1:4) # Optional: names will be used as display text #' class(v) <- "hyperlink" -#' wb$add_data("Cars", x = v, dims = c("B32")) +#' wb$add_data("Cars", x = v, dims = "B32") #' #' ############################################################################# #' ## Formulas @@ -202,47 +207,36 @@ wb_add_data <- function( ) } -#' Add data to a worksheet as an Excel table +#' Add a data table to a worksheet #' -#' Add data to a worksheet and format as an Excel table +#' Add data to a worksheet and format as an Excel table. #' -#' @param wb A Workbook object containing a #' worksheet. -#' @param sheet The worksheet to write to. Can be the worksheet index or name. -#' @param x A dataframe. -#' @param start_col A vector specifying the starting column to write df -#' @param start_row A vector specifying the starting row to write df -#' @param dims Spreadsheet dimensions that will determine `start_col` and `start_row`: "A1", "A1:B2", "A:B" -#' @param col_names If `TRUE`, column names of `x` are written. -#' @param row_names If `TRUE`, row names of `x` are written. -#' @param table_style Any excel table style name or "none" (see "formatting" -#' vignette). -#' @param table_name name of table in workbook. The table name must be unique. +#' The columns of `x` with class Date/POSIXt, currency, accounting, hyperlink, +#' percentage are automatically styled as dates, currency, accounting, hyperlinks, +#' percentages respectively. +#' +#' The string `"_openxlsx_NA"` is reserved for `openxlsx2`. If `x` contains this +#' string, the output will be broken. +#' +#' @inheritParams wb_add_data +#' @param x A data frame +#' @param table_style Any table style name or "none" (see `vignette("openxlsx2_style_manual")`) +#' @param table_name Name of table in workbook. The table name must be unique. #' @param with_filter If `TRUE`, columns with have filters in the first row. #' @param sep Only applies to list columns. The separator used to collapse list -#' columns to a character vector e.g. `sapply(x$list_column, paste, collapse = -#' sep)`. +#' columns to a character vector e.g. +#' `sapply(x$list_column, paste, collapse = sep)`. #' \cr\cr #' \cr**The below options correspond to Excel table options:** #' \cr #' \if{html}{\figure{tableoptions.png}{options: width="40\%" alt="Figure: table_options.png"}} #' \if{latex}{\figure{tableoptions.pdf}{options: width=7cm}} -#' -#' @param first_column logical. If TRUE, the first column is bold -#' @param last_column logical. If TRUE, the last column is bold -#' @param banded_rows logical. If TRUE, rows are color banded -#' @param banded_cols logical. If TRUE, the columns are color banded -#' @param apply_cell_style Should we write cell styles to the workbook -#' @param remove_cell_style keep the cell style? -#' @param na.strings Value used for replacing `NA` values from `x`. Default -#' `na_strings()` uses the special `#N/A` value within the workbook. -#' @param inline_strings write characters as inline strings +#' @param first_column logical. If `TRUE`, the first column is bold. +#' @param last_column logical. If `TRUE`, the last column is bold. +#' @param banded_rows logical. If `TRUE`, rows are color banded. +#' @param banded_cols logical. If `TRUE`, the columns are color banded. #' @param ... additional arguments #' -#' @details columns of `x` with class Date/POSIXt, currency, accounting, -#' hyperlink, percentage are automatically styled as dates, currency, -#' accounting, hyperlinks, percentages respectively. The string `"_openxlsx_NA"` -#' is reserved for `openxlsx2`. If the data frame contains this string, the -#' output will be broken. #' @family workbook wrappers #' @export wb_add_data_table <- function( @@ -293,32 +287,36 @@ wb_add_data_table <- function( ) } -#' Add pivot table to a worksheet +#' Add a pivot table to a worksheet #' -#' @description add pivot table -#' @param wb A Workbook object containing a #' worksheet. -#' @param x a `wb_data` object -#' @param sheet a worksheet -#' @param dims the worksheet cell where the pivot table is placed -#' @param filter a character object with names used to filter -#' @param rows a character object with names used as rows -#' @param cols a character object with names used as cols -#' @param data a character object with names used as data -#' @param fun a character object of functions to be used with the data -#' @param params a list of parameters to modify pivot table creation -#' @details -#' `fun` can be either of `AVERAGE`, `COUNT`, `COUNTA`, `MAX`, `MIN`, +#' Add a pivot table to a worksheet. The data must be specified using [wb_data()] +#' to ensure the function works. +#' +#' `fun` can be any of `AVERAGE`, `COUNT`, `COUNTA`, `MAX`, `MIN`, #' `PRODUCT`, `STDEV`, `STDEVP`, `SUM`, `VAR`, `VARP`. #' #' The sheet will be empty unless it is opened in spreadsheet software. +#' +#' @param wb A Workbook object containing a #' worksheet. +#' @param x A `data.frame` that inherits the [`wb_data`][wb_data()] class. +#' @param sheet A worksheet containing a #' +#' @param dims The worksheet cell where the pivot table is placed +#' @param filter The column name(s) of `x` used for filter. +#' @param rows The column name(s) of `x` used as rows +#' @param cols The column names(s) of `x` used as cols +#' @param data The column name(s) of `x` used as data +#' @param fun A vector of functions to be used with `data` +#' @param params A list of parameters to modify pivot table creation. +#' @seealso [wb_data()] #' @examples #' wb <- wb_workbook() %>% wb_add_worksheet() %>% wb_add_data(x = mtcars) #' -#' df <- wb_data(wb) +#' df <- wb_data(wb, sheet = 1) #' #' wb <- wb %>% -#' wb_add_pivot_table(df, dims = "A3", -#' filter = "am", rows = "cyl", cols = "gear", data = "disp") +#' wb_add_pivot_table(df, dims = "A3", +#' filter = "am", rows = "cyl", cols = "gear", data = "disp" +#' ) #' @family workbook wrappers #' @export wb_add_pivot_table <- function( @@ -356,11 +354,15 @@ wb_add_pivot_table <- function( } -#' Add a character vector as an Excel Formula +#' Add a formula to a cell range in a worksheet +#' +#' This function can be used to add a formula to a worksheet. +#' In `wb_add_formula()`, you can provide the formula as a character vector. #' -#' Add a character vector containing Excel formula to a worksheet. +#' @details +#' Currently, the local translations of formulas are not supported. +#' Only the English functions work. #' -#' @details Currently only the English version of functions are supported. Please don't use the local translation. #' The examples below show a small list of possible formulas: #' #' * SUM(B2:B4) @@ -370,18 +372,27 @@ wb_add_pivot_table <- function( #' * ... #' #' @param wb A Workbook object containing a worksheet. -#' @param sheet The worksheet to write to. Can be the worksheet index or name. -#' @param x A character vector. -#' @param dims Spreadsheet dimensions that will determine startCol and startRow: "A1", "A1:B2", "A:B" +#' @param sheet The worksheet to write to. (either as index or name) +#' @param x A formula as character vector. +#' @param dims Spreadsheet dimensions that will determine where `x` spans: "A1", "A1:B2", "A:B" #' @param start_col A vector specifying the starting column to write to. #' @param start_row A vector specifying the starting row to write to. #' @param array A bool if the function written is of type array -#' @param cm A special kind of array function that hides the curly braces in the cell. Add this, if you see "@" inserted into your formulas -#' @param apply_cell_style Should we write cell styles to the workbook -#' @param remove_cell_style keep the cell style?, +#' @param cm A special kind of array function that hides the curly braces in the cell. +#' Add this, if you see "@" inserted into your formulas. +#' @param apply_cell_style Should we write cell styles to the workbook? +#' @param remove_cell_style Should we keep the cell style? #' @param ... additional arguments +#' @return The workbook, invisibly. #' @family workbook wrappers #' @export +#' @examples +#' wb <- wb_workbook()$add_worksheet() +#' wb$add_data(dims = wb_dims(rows = 1, cols = 1:3), x = t(c(4, 5, 8)), col_names = FALSE) +#' +#' # calculate the sum of elements. +#' wb$add_formula(dims = "D1", x = "SUM(A1:C1)") +#' wb_add_formula <- function( wb, sheet = current_sheet(), @@ -410,12 +421,17 @@ wb_add_formula <- function( ) } -#' update a data_table -#' @param wb workbook -#' @param sheet a worksheet -#' @param dims cell used as start -#' @param tabname a tablename -#' @details Be aware that this function does not alter any filter. Excluding or adding rows does not make rows appear nor will it hide them. +#' Update a data table position in a worksheet +#' +#' Update the position of a data table, possibly written using [wb_add_data_table()] +#' @param wb A workbook +#' @param sheet A worksheet +#' @param dims Cell range used for new data table. +#' @param tabname A table name +#' +#' @details +#' Be aware that this function does not alter any filter. +#' Excluding or adding rows does not make rows appear nor will it hide them. #' @examples #' wb <- wb_workbook()$add_worksheet()$add_data_table(x = mtcars) #' wb$update_table(tabname = "Table1", dims = "A1:J4") @@ -425,29 +441,30 @@ wb_update_table <- function(wb, sheet = current_sheet(), dims = "A1", tabname) { wb$clone()$update_table(sheet = sheet, dims = dims, tabname = tabname) } -#' copy cells around -#' @param wb workbook +#' Copy cells around within a worksheet +#' +#' @param wb A workbook #' @param sheet a worksheet -#' @param dims cell used as start -#' @param data a wb_data object -#' @param as_value should a copy of the value be written -#' @param as_ref should references to the cell be written -#' @param transpose should the data be written transposed +#' @param dims A cell where to place the copy +#' @param data A [`wb_data`][wb_data()] object containing cells to copy +#' @param as_value Should a copy of the value be written? +#' @param as_ref Should references to the cell be written? +#' @param transpose Should the data be written transposed? #' @examples #' wb <- wb_workbook()$ #' add_worksheet()$ #' add_data(x = mtcars)$ #' add_fill(dims = "A1:F1", color = wb_color("yellow")) #' -#' dat <- wb_data(wb, dims = "A1:D4", colNames = FALSE) -#' +#' dat <- wb_data(wb, dims = "A1:D4", col_names = FALSE) +#' # 1:1 copy to M2 #' wb$ -#' # 1:1 copy to M2 #' clone_worksheet(old = 1, new = "Clone1")$ #' copy_cells(data = dat, dims = "M2") #' @family workbook wrappers +#' @seealso [wb_data()] #' @export -#' @returns the wbWorkbook invisibly +#' @returns the `wbWorkbook` invisibly wb_copy_cells <- function( wb, sheet = current_sheet(), @@ -470,16 +487,18 @@ wb_copy_cells <- function( ) } -# merge cells ------------------------------------------------------------- +# merge cells ------------------------------------------------------------------ -#' Worksheet cell merging #' #' Merge cells within a worksheet #' -#' @details As merged region must be rectangular, only min and max of cols and -#' rows are used. +#' Worksheet cell merging #' -#' @param wb A workbook object +#' @details +#' If using the deprecated arguments `rows` and `cols` with a merged region must be rectangular, +#' only min and max of `cols` and `rows` are used. +#' +#' @param wb A Workbook object #' @param sheet A name or index of a worksheet #' @param dims worksheet cells #' @param solve logical if intersecting merges should be solved @@ -534,18 +553,18 @@ wb_unmerge_cells <- function(wb, sheet = current_sheet(), dims = NULL, ...) { #' Add a chartsheet to a workbook #' -#' @param wb A Workbook object to attach the new worksheet -#' @param sheet A name for the new worksheet -#' @param tab_color Color of the worksheet tab. A valid color (belonging to -#' colors()) or a valid hex color beginning with "#" +#' @param wb A Workbook object to attach the new chartsheet +#' @param sheet A name for the new chartsheet +#' @param tab_color Color of the chartsheet tab. A valid color (belonging to +#' `colors()`) or a valid hex color beginning with "#" #' @param zoom A numeric between 10 and 400. Worksheet zoom level as a #' percentage. -#' @param visible If FALSE, sheet is hidden else visible. +#' @param visible If `FALSE`, sheet is hidden else visible. #' @param ... ... #' @details After chartsheet creation a chart must be added to the sheet. #' Otherwise the chartsheet will break the workbook. #' @family workbook wrappers -#' @seealso [wb_add_mschart()] +#' @seealso [wb_add_mschart()] [wbChartSheet] #' @export wb_add_chartsheet <- function( wb, @@ -567,66 +586,77 @@ wb_add_chartsheet <- function( #' Add a worksheet to a workbook #' -#' @param wb A Workbook object to attach the new worksheet +#' Add a worksheet to a [wbWorkbook] is the first step to build a workbook. +#' With the function, you can also set the sheet view with `zoom`, set headers +#' and footers as well as other features. See the function arguments. +#' +#' @details +#' Headers and footers can contain special tags +#' * **&\[Page\]** Page number +#' * **&\[Pages\]** Number of pages +#' * **&\[Date\]** Current date +#' * **&\[Time\]** Current time +#' * **&\[Path\]** File path +#' * **&\[File\]** File name +#' * **&\[Tab\]** Worksheet name +#' +#' @param wb A `wbWorkbook` object to attach the new worksheet #' @param sheet A name for the new worksheet #' @param grid_lines A logical. If `FALSE`, the worksheet grid lines will be #' hidden. #' @param row_col_headers A logical. If `FALSE`, the worksheet colname and rowname will be #' hidden. -#' @param tab_color Color of the worksheet tab. A valid color (belonging to -#' colors()) or a valid hex color beginning with "#" -#' @param zoom A numeric between 10 and 400. Worksheet zoom level as a -#' percentage. +#' @param tab_color Color of the worksheet tab. A [wb_color()], a valid color (belonging to +#' `grDevices::colors()`) or a valid hex color beginning with "#". +#' @param zoom The worksheet zoom level, a numeric between 10 and 400 as a +#' percentage. (A zoom value smaller than 10 will default to 10.) #' @param header,odd_header,even_header,first_header,footer,odd_footer,even_footer,first_footer #' Character vector of length 3 corresponding to positions left, center, #' right. `header` and `footer` are used to default additional arguments. #' Setting `even`, `odd`, or `first`, overrides `header`/`footer`. Use `NA` to #' skip a position. -#' @param visible If FALSE, sheet is hidden else visible. -#' @param has_drawing If TRUE prepare a drawing output (TODO does this work?) +#' @param visible If `FALSE`, sheet is hidden else visible. +#' @param has_drawing If `TRUE` prepare a drawing output (TODO does this work?) #' @param paper_size An integer corresponding to a paper size. See [wb_page_setup()] for #' details. #' @param orientation One of "portrait" or "landscape" -#' @param hdpi Horizontal DPI. Can be set with options("openxlsx2.dpi" = X) or -#' options("openxlsx2.hdpi" = X) -#' @param vdpi Vertical DPI. Can be set with options("openxlsx2.dpi" = X) or -#' options("openxlsx2.vdpi" = X) -#' @param ... ... -#' @details Headers and footers can contain special tags \itemize{ -#' \item{**&\[Page\]**}{ Page number} \item{**&\[Pages\]**}{ Number of pages} -#' \item{**&\[Date\]**}{ Current date} \item{**&\[Time\]**}{ Current time} -#' \item{**&\[Path\]**}{ File path} \item{**&\[File\]**}{ File name} -#' \item{**&\[Tab\]**}{ Worksheet name} } -#' @return The [wbWorkbook] object `wb` +#' @param hdpi,vdpi Horizontal and vertical DPI. Can be set with `options("openxlsx2.dpi" = X)`, +#' `options("openxlsx2.hdpi" = X)` or `options("openxlsx2.vdpi" = X)` +#' @param ... Additional arguments +#' @return The `wbWorkbook` object, invisibly. #' #' @export #' @family workbook wrappers #' #' @examples #' ## Create a new workbook -#' wb <- wb_workbook("Fred") +#' wb <- wb_workbook() #' -#' ## Add 3 worksheets +#' ## Add a worksheet #' wb$add_worksheet("Sheet 1") -#' wb$add_worksheet("Sheet 2", gridLines = FALSE) -#' wb$add_worksheet("Sheet 3", tabColor = "red") -#' wb$add_worksheet("Sheet 4", gridLines = FALSE, tabColor = "#4F81BD") -#' +#' ## No grid lines +#' wb$add_worksheet("Sheet 2", grid_lines = FALSE) +#' ## A red tab color +#' wb$add_worksheet("Sheet 3", tab_color = wb_color("red")) +#' ## All options combined with a zoom of 40% +#' wb$add_worksheet("Sheet 4", grid_lines = FALSE, tab_color = wb_color(hex = "#4F81BD"), zoom = 40) +#' +# TODO maybe leave the special cases to wb_set_header_footer? #' ## Headers and Footers #' wb$add_worksheet("Sheet 5", #' header = c("ODD HEAD LEFT", "ODD HEAD CENTER", "ODD HEAD RIGHT"), #' footer = c("ODD FOOT RIGHT", "ODD FOOT CENTER", "ODD FOOT RIGHT"), -#' evenHeader = c("EVEN HEAD LEFT", "EVEN HEAD CENTER", "EVEN HEAD RIGHT"), -#' evenFooter = c("EVEN FOOT RIGHT", "EVEN FOOT CENTER", "EVEN FOOT RIGHT"), -#' firstHeader = c("TOP", "OF FIRST", "PAGE"), -#' firstFooter = c("BOTTOM", "OF FIRST", "PAGE") +#' even_header = c("EVEN HEAD LEFT", "EVEN HEAD CENTER", "EVEN HEAD RIGHT"), +#' even_footer = c("EVEN FOOT RIGHT", "EVEN FOOT CENTER", "EVEN FOOT RIGHT"), +#' first_header = c("TOP", "OF FIRST", "PAGE"), +#' first_footer = c("BOTTOM", "OF FIRST", "PAGE") #' ) #' #' wb$add_worksheet("Sheet 6", #' header = c("&[Date]", "ALL HEAD CENTER 2", "&[Page] / &[Pages]"), #' footer = c("&[Path]&[File]", NA, "&[Tab]"), -#' firstHeader = c(NA, "Center Header of First Page", NA), -#' firstFooter = c(NA, "Center Footer of First Page", NA) +#' first_header = c(NA, "Center Header of First Page", NA), +#' first_footer = c(NA, "Center Footer of First Page", NA) #' ) #' #' wb$add_worksheet("Sheet 7", @@ -635,8 +665,8 @@ wb_add_chartsheet <- function( #' ) #' #' wb$add_worksheet("Sheet 8", -#' firstHeader = c("FIRST ONLY L", NA, "FIRST ONLY R"), -#' firstFooter = c("FIRST ONLY L", NA, "FIRST ONLY R") +#' first_header = c("FIRST ONLY L", NA, "FIRST ONLY R"), +#' first_footer = c("FIRST ONLY L", NA, "FIRST ONLY R") #' ) #' #' ## Need data on worksheet to see all headers and footers @@ -667,6 +697,7 @@ wb_add_worksheet <- function( vdpi = getOption("openxlsx2.vdpi", default = getOption("openxlsx2.dpi", default = 300)), ... ) { + assert_workbook(wb) wb$clone()$add_worksheet( sheet = sheet, @@ -690,30 +721,32 @@ wb_add_worksheet <- function( } -#' Clone a worksheet to a workbook +#' Create copies of a worksheet within a workbook #' -#' Clone a worksheet to a Workbook object +#' @description +#' Create a copy of a worksheet in the same `wbWorkbook` object. #' -#' @details #' Cloning is possible only to a limited extent. References to sheet names in #' formulas, charts, pivot tables, etc. may not be updated. Some elements like #' named ranges and slicers cannot be cloned yet. #' -#' @param wb A [wbWorkbook] object +#' @param wb A `wbWorkbook` object #' @param old Name of existing worksheet to copy -#' @param new Name of New worksheet to create -#' @return The `wb` object +#' @param new Name of the new worksheet to create +#' @return The `wbWorkbook` object, invisibly. #' #' @export #' @family workbook wrappers #' #' @examples #' # Create a new workbook -#' wb <- wb_workbook("Fred") +#' wb <- wb_workbook() #' #' # Add worksheets #' wb$add_worksheet("Sheet 1") -#' wb$clone_worksheet("Sheet 1", "Sheet 2") +#' wb$clone_worksheet("Sheet 1", new = "Sheet 2") +#' # Take advantage of waiver functions +#' wb$clone_worksheet(old = "Sheet 1") wb_clone_worksheet <- function(wb, old = current_sheet(), new = next_sheet()) { assert_workbook(wb) wb$clone()$clone_worksheet(old = old, new = new) @@ -721,15 +754,16 @@ wb_clone_worksheet <- function(wb, old = current_sheet(), new = next_sheet()) { # worksheets -------------------------------------------------------------- -#' @name wb_freeze_pane -#' @title Freeze a worksheet pane -#' @description Freeze a worksheet pane +#' Freeze pane of a worksheet +#' +#' Add a Freeze pane in a worksheet. +#' #' @param wb A workbook object #' @param sheet A name or index of a worksheet #' @param first_active_row Top row of active region #' @param first_active_col Furthest left column of active region -#' @param first_row If `TRUE`, freezes the first row (equivalent to firstActiveRow = 2) -#' @param first_col If `TRUE`, freezes the first column (equivalent to firstActiveCol = 2) +#' @param first_row If `TRUE`, freezes the first row (equivalent to `first_active_row = 2`) +#' @param first_col If `TRUE`, freezes the first column (equivalent to `first_active_col = 2`) #' @param ... additional arguments #' #' @export @@ -746,10 +780,10 @@ wb_clone_worksheet <- function(wb, old = current_sheet(), new = next_sheet()) { #' wb$add_worksheet("Sheet 4") #' #' ## Freeze Panes -#' wb$freeze_pane("Sheet 1", firstActiveRow = 5, firstActiveCol = 3) -#' wb$freeze_pane("Sheet 2", firstCol = TRUE) ## shortcut to firstActiveCol = 2 -#' wb$freeze_pane(3, firstRow = TRUE) ## shortcut to firstActiveRow = 2 -#' wb$freeze_pane(4, firstActiveRow = 1, firstActiveCol = "D") +#' wb$freeze_pane("Sheet 1", first_active_row = 5, first_active_col = 3) +#' wb$freeze_pane("Sheet 2", first_col = TRUE) ## shortcut to first_active_col = 2 +#' wb$freeze_pane(3, first_row = TRUE) ## shortcut to first_active_row = 2 +#' wb$freeze_pane(4, first_active_row = 1, first_active_col = "D") wb_freeze_pane <- function( wb, sheet = current_sheet(), @@ -772,21 +806,18 @@ wb_freeze_pane <- function( # heights and columns ----------------------------------------------------- -# TODO order these... -#' Set worksheet row heights +#' Modify row heights of a worksheet #' -#' Set worksheet row heights +#' Set / remove custom worksheet row heights #' #' @param wb A [wbWorkbook] object -#' @param sheet A name or index of a worksheet -#' @param rows Indices of rows to set height -#' @param heights Heights to set rows to specified in Excel column height units. -#' @param hidden Option to hide rows. -#' -#' @export +#' @param sheet A name or index of a worksheet. (A vector is accepted for `remove_row_heights()`) +#' @param rows Indices of rows to set / remove (if any) custom height. +#' @param heights Heights to set `rows` to specified in a spreadsheet column height units. +#' @param hidden Option to hide rows. A logical vector of length 1 or lengt of `rows` +#' @name wb_row_heights #' @family workbook wrappers -#' @seealso [wb_remove_row_heights()] #' #' @examples #' ## Create a new workbook @@ -804,33 +835,49 @@ wb_freeze_pane <- function( #' #' ## overwrite row 1 height #' wb <- wb_set_row_heights(wb, 1, rows = 1, heights = 40) +#' ## remove any custom row heights in row 1 +#' wb$remove_row_heights(sheet = 1, rows = 1) +NULL +#' @rdname wb_row_heights +#' @export wb_set_row_heights <- function(wb, sheet = current_sheet(), rows, heights = NULL, hidden = FALSE) { assert_workbook(wb) wb$clone()$set_row_heights(sheet = sheet, rows, heights, hidden) } +#' @rdname wb_row_heights +#' @export +wb_remove_row_heights <- function(wb, sheet = current_sheet(), rows) { + assert_workbook(wb) + wb$clone()$remove_row_heights(sheet = sheet, rows = rows) +} - -#' Modify worksheet column widths +#' Modify column widths of a worksheet #' -#' Remove / set worksheet column widths to specific width or "auto". -#' @param wb A `wbWorkbook` object -#' @param sheet A name or index of a worksheet, a vector in the case of `remove` -#' @param cols Indices of cols to set/remove width -#' @param widths width to set cols to specified in Excel column width units or "auto" for automatic sizing. The widths argument is -#' recycled to the length of cols. The default width is 8.43. Though there is no specific default width for Excel, it depends on -#' Excel version, operating system and DPI settings used. Setting it to specific value also is no guarantee that the output will be -#' of the selected width. -#' @param hidden Logical vector. If `TRUE` the column is hidden. -#' @details The global min and max column width for "auto" columns is set by (default values show): -#' \itemize{ -#' \item{options("openxlsx2.minWidth" = 3)} -#' \item{options("openxlsx2.maxWidth" = 250)} ## This is the maximum width allowed in Excel -#' } +#' Remove / set worksheet column widths to specified width or "auto". +#' +#' @details +#' The global min and max column width for "auto" columns is set by (default values show): +#' * `options("openxlsx2.minWidth" = 3)` +#' * `options("openxlsx2.maxWidth" = 250)` Maximum width allowed in Excel #' -#' NOTE: The calculation of column widths can be slow for large worksheets. +#' NOTE: The calculation of column widths can be slow for large worksheets. #' -#' NOTE: The `hidden` parameter may conflict with the one set in -#' [wb_group_cols()]; changing one will update the other. +#' NOTE: The `hidden` parameter may conflict with the one set in [wb_group_cols()]; +#' changing one will update the other. +#' +#' NOTE: The default column width varies by spreadsheet software, operating system, +#' and DPI settings used. Setting `widths` to specific value also is no guarantee +#' that the output will have consistent column widths. +#' +#' @param wb A `wbWorkbook` object. +#' @param sheet A name or index of a worksheet, a vector in the case of `remove_` +#' @param cols Indices of cols to set/remove column widths. +#' @param widths Width to set `cols` to specified column width or `"auto"` for +#' automatic sizing. `widths` is recycled to the length of `cols`. openxlsx2 +#' sets the default width is 8.43, as this is the standard in some spreadsheet +#' software. See **Details** for general information on column widths. +#' @param hidden Logical vector recycled to the length of `cols`. +#' If `TRUE`, the columns are hidden. #' #' @family workbook wrappers #' @@ -842,7 +889,7 @@ wb_set_row_heights <- function(wb, sheet = current_sheet(), rows, heights = NULL #' wb$add_worksheet("Sheet 1") #' #' ## set col widths -#' wb$set_col_widths(1, cols = c(1, 4, 6, 7, 9), widths = c(16, 15, 12, 18, 33)) +#' wb$set_col_widths(cols = c(1, 4, 6, 7, 9), widths = c(16, 15, 12, 18, 33)) #' #' ## auto columns #' wb$add_worksheet("Sheet 2") @@ -876,25 +923,6 @@ wb_remove_col_widths <- function(wb, sheet = current_sheet(), cols) { assert_workbook(wb) wb$clone()$remove_col_widths(sheet = sheet, cols = cols) } -#' Remove custom row heights from a worksheet -#' -#' Remove row heights from a worksheet -#' -#' @param wb A workbook object -#' @param sheet A name or index of a worksheet -#' @param rows Indices of rows to remove custom height (if any) from. -#' @seealso [wb_set_row_heights()] -#' @export -#' @examples -#' ## Create a new workbook -#' wb <- wb_load(file = system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2")) -#' -#' ## remove any custom row heights in rows 1 to 10 -#' wb$remove_row_heights(1, rows = 1:10) -wb_remove_row_heights <- function(wb, sheet = current_sheet(), rows) { - assert_workbook(wb) - wb$clone()$remove_row_heights(sheet = sheet, rows = rows) -} # images ------------------------------------------------------------------ @@ -972,9 +1000,9 @@ wb_add_plot <- function( } #' add drawings to workbook -#' @param wb a `wbWorkbook` -#' @param sheet a sheet in the workbook -#' @param dims the dimension where the drawing is added. Can be `NULL` +#' @param wb A `wbWorkbook` +#' @param sheet A sheet in the workbook +#' @param dims The dimension where the drawing is added. #' @param xml the drawing xml as character or file #' @param col_offset,row_offset offsets for column and row #' @param ... additional arguments @@ -1076,11 +1104,10 @@ wb_add_mschart <- function( ) } -#' @title Remove a worksheet from a workbook -#' @description Remove a worksheet from a Workbook object -#' @param wb A workbook object -#' @param sheet A name or index of a worksheet -#' @description Remove a worksheet from a workbook +#' Remove a worksheet from a workbook +#' @param wb A wbWorkbook object +#' @param sheet The sheet name or index to remove +#' @returns The `wbWorkbook` object, invisibly. #' @export #' @examples #' ## load a workbook @@ -1096,39 +1123,37 @@ wb_remove_worksheet <- function(wb, sheet = current_sheet()) { # base font --------------------------------------------------------------- -#' Get / set the default font in a workbook +#' Set the default font in a workbook #' -#' Modify / get the default font for the workbook. +#' Modify / get the default font for the workbook. The base font in a workbook +#' does not affect the font in data tables. #' #' The font name is not validated in anyway. Excel replaces unknown font names -#' with Arial. Base font is black, size 11, Calibri. -#' @family workbook wrappers +#' with Arial. The default base font is Calibri, black, size 11. +#' #' @param wb A workbook object -#' @param font_size font size -#' @param font_color font color +#' @param font_size Font size +#' @param font_color Font color #' @param font_name Name of a font -#' @param ... additional arguments -#' +#' @param ... Additional arguments +#' @family workbook styling functions +#' @family workbook wrappers #' @name wb_base_font #' @examples #' ## create a workbook #' wb <- wb_workbook() #' wb$add_worksheet("S1") #' ## modify base font to size 10 Arial Narrow in red -#' wb$set_base_font(fontSize = 10, fontColor = "#FF0000", fontName = "Arial Narrow") +#' wb$set_base_font(font_size = 10, font_color = wb_color("red"), font_name = "Arial Narrow") +#' +#' wb$add_data(x = iris) #' -#' wb$add_data("S1", iris) -#' wb$add_data_table("S1", x = iris, startCol = 10) ## font color does not affect tables +#' ## font color does not affect tables +#' wb$add_data_table(x = iris, dims = wb_dims(from_col = 10)) #' #' ## get the base font -#' ## create a workbook -#' wb <- wb_workbook() #' wb_get_base_font(wb) #' -#' ## modify base font to size 10 Arial Narrow in red -#' wb$set_base_font(fontSize = 10, fontColor = "#FF0000", fontName = "Arial Narrow") -#' -#' wb_get_base_font(wb) NULL #' @export #' @rdname wb_base_font @@ -1158,11 +1183,10 @@ wb_get_base_font <- function(wb) { #' Set the workbook position, size and filter #' -#' Get the base font used in the workbook. #' @param wb A [wbWorkbook] object #' @param active_tab activeTab #' @param auto_filter_date_grouping autoFilterDateGrouping -#' @param first_sheet firstSheet +#' @param first_sheet The first sheet to be displayed #' @param minimized minimized #' @param show_horizontal_scroll showHorizontalScroll #' @param show_sheet_tabs showSheetTabs @@ -1174,7 +1198,7 @@ wb_get_base_font <- function(wb) { #' @param x_window xWindow #' @param y_window yWindow #' @param ... additional arguments -#' @return The `wbWorkbook` object +#' @return The Workbook object #' @export wb_set_bookview <- function( wb, @@ -1212,60 +1236,56 @@ wb_set_bookview <- function( ) } -#' Set document headers and footers +#' Set headers and footers of a worksheet #' -#' Set document headers and footers +#' Set document headers and footers. You can also do this when adding a worksheet +#' with [wb_add_worksheet()] with the `header`, `footer` arguments and friends. +#' These will show up when printing an xlsx file. #' -#' @param wb A workbook object +#' Headers and footers can contain special tags +#' * **&\[Page\]** Page number +#' * **&\[Pages\]** Number of pages +#' * **&\[Date\]** Current date +#' * **&\[Time\]** Current time +#' * **&\[Path\]** File path +#' * **&\[File\]** File name +#' * **&\[Tab\]** Worksheet name +#' +#' @param wb A Workbook object #' @param sheet A name or index of a worksheet -#' @param header document header. Character vector of length 3 corresponding to positions left, center, right. Use NA to skip a position. -#' @param footer document footer. Character vector of length 3 corresponding to positions left, center, right. Use NA to skip a position. -#' @param even_header document header for even pages. -#' @param even_footer document footer for even pages. -#' @param first_header document header for first page only. -#' @param first_footer document footer for first page only. +#' @param header,even_header,first_header,footer,even_footer,first_footer +#' Character vector of length 3 corresponding to positions left, center, +#' right. `header` and `footer` are used to default additional arguments. +#' Setting `even`, `odd`, or `first`, overrides `header`/`footer`. Use `NA` to +#' skip a position. +# #' @inheritParams wb_add_worksheet #' @param ... additional arguments -#' @details Headers and footers can contain special tags -#' \itemize{ -#' \item{**&\[Page\]**}{ Page number} -#' \item{**&\[Pages\]**}{ Number of pages} -#' \item{**&\[Date\]**}{ Current date} -#' \item{**&\[Time\]**}{ Current time} -#' \item{**&\[Path\]**}{ File path} -#' \item{**&\[File\]**}{ File name} -#' \item{**&\[Tab\]**}{ Worksheet name} -#' } #' @export -#' @seealso [wb_add_worksheet()] to set headers and footers when adding a worksheet #' @examples #' wb <- wb_workbook() #' -#' wb$add_worksheet("S1") -#' wb$add_worksheet("S2") -#' wb$add_worksheet("S3") -#' wb$add_worksheet("S4") -#' -#' wb$add_data(1, 1:400) -#' wb$add_data(2, 1:400) -#' wb$add_data(3, 3:400) -#' wb$add_data(4, 3:400) +#' # Add example data +#' wb$add_worksheet("S1")$add_data(x = 1:400) +#' wb$add_worksheet("S2")$add_data(x = 1:400) +#' wb$add_worksheet("S3")$add_data(x = 3:400) +#' wb$add_worksheet("S4")$add_data(x = 3:400) #' #' wb$set_header_footer( #' sheet = "S1", #' header = c("ODD HEAD LEFT", "ODD HEAD CENTER", "ODD HEAD RIGHT"), #' footer = c("ODD FOOT RIGHT", "ODD FOOT CENTER", "ODD FOOT RIGHT"), -#' evenHeader = c("EVEN HEAD LEFT", "EVEN HEAD CENTER", "EVEN HEAD RIGHT"), -#' evenFooter = c("EVEN FOOT RIGHT", "EVEN FOOT CENTER", "EVEN FOOT RIGHT"), -#' firstHeader = c("TOP", "OF FIRST", "PAGE"), -#' firstFooter = c("BOTTOM", "OF FIRST", "PAGE") +#' even_header = c("EVEN HEAD LEFT", "EVEN HEAD CENTER", "EVEN HEAD RIGHT"), +#' even_footer = c("EVEN FOOT RIGHT", "EVEN FOOT CENTER", "EVEN FOOT RIGHT"), +#' first_header = c("TOP", "OF FIRST", "PAGE"), +#' first_footer = c("BOTTOM", "OF FIRST", "PAGE") #' ) #' #' wb$set_header_footer( #' sheet = 2, #' header = c("&[Date]", "ALL HEAD CENTER 2", "&[Page] / &[Pages]"), #' footer = c("&[Path]&[File]", NA, "&[Tab]"), -#' firstHeader = c(NA, "Center Header of First Page", NA), -#' firstFooter = c(NA, "Center Footer of First Page", NA) +#' first_header = c(NA, "Center Header of First Page", NA), +#' first_footer = c(NA, "Center Footer of First Page", NA) #' ) #' #' wb$set_header_footer( @@ -1276,8 +1296,8 @@ wb_set_bookview <- function( #' #' wb$set_header_footer( #' sheet = 4, -#' firstHeader = c("FIRST ONLY L", NA, "FIRST ONLY R"), -#' firstFooter = c("FIRST ONLY L", NA, "FIRST ONLY R") +#' first_header = c("FIRST ONLY L", NA, "FIRST ONLY R"), +#' first_footer = c("FIRST ONLY L", NA, "FIRST ONLY R") #' ) wb_set_header_footer <- function( wb, @@ -1305,30 +1325,24 @@ wb_set_header_footer <- function( -#' @name wb_page_setup -#' @title Set page margins, orientation and print scaling -#' @description Set page margins, orientation and print scaling +#' Set page margins, orientation and print scaling of a worksheet +#' +#' Set page margins, orientation and print scaling. #' @param wb A workbook object #' @param sheet A name or index of a worksheet #' @param orientation Page orientation. One of "portrait" or "landscape" #' @param scale Print scaling. Numeric value between 10 and 400 -#' @param left left page margin in inches -#' @param right right page margin in inches -#' @param top top page margin in inches -#' @param bottom bottom page margin in inches -#' @param header header margin in inches -#' @param footer footer margin in inches -#' @param fit_to_width If `TRUE`, worksheet is scaled to fit to page width on printing. -#' @param fit_to_height If `TRUE`, worksheet is scaled to fit to page height on printing. +#' @param left,right,top,bottom Page margin in inches +#' @param header,footer Margin in inches +#' @param fit_to_width,fit_to_height If `TRUE`, worksheet is scaled to fit to page width /height on printing. #' @param paper_size See details. Default value is 9 (A4 paper). -#' @param print_title_rows Rows to repeat at top of page when printing. Integer vector. -#' @param print_title_cols Columns to repeat at left when printing. Integer vector. +#' @param print_title_rows,print_title_cols Rows / columns to repeat at top of page when printing. Integer vector. #' @param summary_row Location of summary rows in groupings. One of "Above" or "Below". #' @param summary_col Location of summary columns in groupings. One of "Right" or "Left". #' @param ... additional arguments #' @export #' @details -#' paperSize is an integer corresponding to: +#' `paper_size` is an integer corresponding to: #' \itemize{ #' \item{**1**}{ Letter paper (8.5 in. by 11 in.)} #' \item{**2**}{ Letter small paper (8.5 in. by 11 in.)} @@ -1463,7 +1477,7 @@ wb_page_setup <- function( } -# protect ----------------------------------------------------------------- +# protect ---------------------------------------------------------------------- #' Protect a worksheet from modifications #' @@ -1524,8 +1538,8 @@ wb_protect_worksheet <- function( #' Protect or unprotect a workbook from modifications by the user in the #' graphical user interface. Replaces an existing protection. #' -#' @param wb A workbook object -#' @param protect Whether to protect or unprotect the sheet (default=TRUE) +#' @param wb A Workbook object +#' @param protect Whether to protect or unprotect the sheet (default `TRUE`) #' @param password (optional) password required to unprotect the workbook #' @param lock_structure Whether the workbook structure should be locked #' @param lock_windows Whether the window position of the spreadsheet should be @@ -1533,9 +1547,9 @@ wb_protect_worksheet <- function( #' @param type Lock type (see details) #' @param file_sharing Whether to enable a popup requesting the unlock password #' is prompted -#' @param username The username for the `fileSharing` popup +#' @param username The username for the `file_sharing` popup #' @param read_only_recommended Whether or not a post unlock message appears -#' stating that the workbook is recommended to be opened in readonly mode. +#' stating that the workbook is recommended to be opened in read-only mode. #' @param ... additional arguments #' #' @details @@ -1552,7 +1566,7 @@ wb_protect_worksheet <- function( #' @examples #' wb <- wb_workbook() #' wb$add_worksheet("S1") -#' wb_protect(wb, protect = TRUE, password = "Password", lockStructure = TRUE) +#' wb_protect(wb, protect = TRUE, password = "Password", lock_structure = TRUE) #' #' # Remove the protection #' wb_protect(wb, protect = FALSE) @@ -1561,11 +1575,11 @@ wb_protect_worksheet <- function( #' wb, #' protect = TRUE, #' password = "Password", -#' lockStructure = TRUE, +#' lock_structure = TRUE, #' type = 2L, -#' fileSharing = TRUE, +#' file_sharing = TRUE, #' username = "Test", -#' readOnlyRecommended = TRUE +#' read_only_recommended = TRUE #' ) #' wb_protect <- function( @@ -1597,9 +1611,11 @@ wb_protect <- function( # grid lines -------------------------------------------------------------- -#' Set worksheet gridlines to show or hide. +#' Modify grid lines visibility in a worksheet #' -#' Set worksheet gridlines to show or hide. +#' Set worksheet grid lines to show or hide. +#' You can also add / remove grid lines when creating a worksheeet with +#' [`wb_add_worksheet(grid_lines = FALSE)`][wb_add_worksheet()] #' #' @param wb A workbook object #' @param sheet A name or index of a worksheet @@ -1628,7 +1644,7 @@ wb_grid_lines <- function(wb, sheet = current_sheet(), show = FALSE, print = sho # worksheet order --------------------------------------------------------- -#' Order of worksheets in xlsx file +#' Order worksheets in a workbook #' #' Get/set order of worksheets in a Workbook object #' @@ -1674,72 +1690,53 @@ wb_set_order <- function(wb, sheets) { # named region ------------------------------------------------------------ -#' Create / delete a named region +#' Modify named regions in a worksheet #' -#' Create / delete a named region +#' Create / delete a named region. You can also specify a named region by using +#' the `name` argument in `wb_add_data(x = iris, name = "my-region")`. +#' It is important to note that named regions are not case-sensitive and must be unique. #' -#' @param wb A workbook object +#' You can use the [wb_dims()] helper to specify the cell range of the named region +#' +#' @param wb A Workbook object #' @param sheet A name or index of a worksheet -#' @param dims Worksheet dimension, single cell ("A1") or cell range ("A1:D4") -#' @param name Name for region. A character vector of length 1. Note region names musts be case-insensitive unique. -#' @param overwrite Boolean. Overwrite if exists? Default to FALSE +#' @param dims Worksheet cell range of the region ("A1:D4"). +#' @param name Name for region. A character vector of length 1. Note that region +#' names musts be case-insensitive unique. +#' @param overwrite Boolean. Overwrite if exists? Default to `FALSE`. #' @param local_sheet If `TRUE` the named region will be local for this sheet #' @param comment description text for named region -#' @param custom_menu customMenu (unknown xml feature) -#' @param description description (unknown xml feature) -#' @param is_function function (unknown xml feature) -#' @param function_group_id function group id (unknown xml feature) -#' @param help help (unknown xml feature) -#' @param hidden hidden if the named region should be hidden -#' @param local_name localName (unknown xml feature) -#' @param publish_to_server publish to server (unknown xml feature) -#' @param status_bar status bar (unknown xml feature) -#' @param vb_procedure wbProcedure (unknown xml feature) -#' @param workbook_parameter workbookParameter (unknown xml feature) -#' @param xml xml (unknown xml feature) +#' @param hidden Should the named region be hidden? +#' @param custom_menu,description,is_function,function_group_id,help,local_name,publish_to_server,status_bar,vb_procedure,workbook_parameter,xml Unknown XML feature #' @param ... additional arguments -#' @details Region is given by: min(cols):max(cols) X min(rows):max(rows) +#' @seealso [wb_get_named_regions()] #' @examples #' ## create named regions #' wb <- wb_workbook() #' wb$add_worksheet("Sheet 1") #' #' ## specify region -#' wb$add_data(sheet = 1, x = iris, startCol = 1, startRow = 1) +#' wb$add_data(x = iris, start_col = 1, start_row = 1) #' wb$add_named_region( -#' sheet = 1, #' name = "iris", -#' dims = wb_dims( -#' rows = seq_len(nrow(iris) + 1), -#' cols = seq_along(iris) -#' ) +#' dims = wb_dims(x = iris) #' ) #' -#' -#' ## using write_data 'name' argument -#' wb$add_data(sheet = 1, x = iris, name = "iris2", startCol = 10) -#' -#' out_file <- temp_xlsx() -#' wb_save(wb, out_file, overwrite = TRUE) -#' -#' ## see named regions -#' wb_get_named_regions(wb) ## From Workbook object -#' wb_get_named_regions(out_file) ## From xlsx file +#' ## using add_data 'name' argument +#' wb$add_data(sheet = 1, x = iris, name = "iris2", start_col = 10) #' #' ## delete one #' wb$remove_named_region(name = "iris2") #' wb_get_named_regions(wb) #' #' ## read named regions -#' df <- read_xlsx(wb, namedRegion = "iris") +#' df <- wb_to_df(wb, named_region = "iris") #' head(df) #' -#' df <- read_xlsx(out_file, namedRegion = "iris2") -#' head(df) -#' @name named_region +#' @name wb_named_region NULL -#' @rdname named_region +#' @rdname wb_named_region #' @export wb_add_named_region <- function( wb, @@ -1749,12 +1746,12 @@ wb_add_named_region <- function( local_sheet = FALSE, overwrite = FALSE, comment = NULL, + hidden = NULL, custom_menu = NULL, description = NULL, is_function = NULL, function_group_id = NULL, help = NULL, - hidden = NULL, local_name = NULL, publish_to_server = NULL, status_bar = NULL, @@ -1787,7 +1784,7 @@ wb_add_named_region <- function( ) } -#' @rdname named_region +#' @rdname wb_named_region #' @export wb_remove_named_region <- function(wb, sheet = current_sheet(), name = NULL) { assert_workbook(wb) @@ -1834,7 +1831,7 @@ wb_remove_named_region <- function(wb, sheet = current_sheet(), name = NULL) { #' wb_add_filter(wb, 1, row = 1, cols = seq_along(iris)) #' #' ## Equivalently -#' wb$add_data(2, x = iris, withFilter = TRUE) +#' wb$add_data(2, x = iris, with_filter = TRUE) #' #' ## Similarly #' wb$add_data_table(3, iris) @@ -1858,23 +1855,26 @@ wb_remove_filter <- function(wb, sheet = current_sheet()) { } -# validations ------------------------------------------------------------- +# validations ------------------------------------------------------------------ -#' Add data validation to cells +#' Add data validation to cells in a worksheet #' #' Add Excel data validation to cells #' -#' @param wb A workbook object +#' @param wb A Workbook object #' @param sheet A name or index of a worksheet #' @param dims A cell dimension ("A1" or "A1:B2") -#' @param type One of 'whole', 'decimal', 'date', 'time', 'textLength', 'list' (see examples) +#' @param type One of 'whole', 'decimal', 'date', 'time', 'textLength', 'list' +#' (see examples) #' @param operator One of 'between', 'notBetween', 'equal', #' 'notEqual', 'greaterThan', 'lessThan', 'greaterThanOrEqual', 'lessThanOrEqual' #' @param value a vector of length 1 or 2 depending on operator (see examples) #' @param allow_blank logical #' @param show_input_msg logical #' @param show_error_msg logical -#' @param error_style The icon shown and the options how to deal with such inputs. Default "stop" (cancel), else "information" (prompt popup) or "warning" (prompt accept or change input) +#' @param error_style The icon shown and the options how to deal with such inputs. +#' Default "stop" (cancel), else "information" (prompt popup) or +#' "warning" (prompt accept or change input) #' @param error_title The error title #' @param error The error text #' @param prompt_title The prompt title @@ -1962,12 +1962,15 @@ wb_add_data_validation <- function( # visibility -------------------------------------------------------------- -#' Get/set worksheet visible state +#' Get/set worksheet visible state in a workbook #' -#' Get and set worksheet visible state +#' Get and set worksheet visible state. This allows to hide worksheets from the workbook. +#' The visibility of a worksheet can either be "visible", "hidden", or "veryHidden". +#' You can set this when creating a worksheet with `wb_add_worksheet(visible = FALSE)` #' -#' @return Character vector of worksheet names. -#' @return Vector of "hidden", "visible", "veryHidden" +#' @return +#' * `wb_set_sheet_visibility`: The Worbook object, invisibly. +#' * `wb_get_sheet_visibility()`: A character vector of the worksheet visibility value #' @examples #' #' wb <- wb_workbook() @@ -1980,10 +1983,10 @@ wb_add_data_validation <- function( #' wb$set_sheet_visibility(2, FALSE) ## hide sheet 2 #' wb$set_sheet_visibility(3, "hidden") ## hide sheet 3 #' wb$set_sheet_visibility(3, "veryHidden") ## hide sheet 3 from UI -#' @name sheet_visibility +#' @name wb_sheet_visibility NULL -#' @rdname sheet_visibility +#' @rdname wb_sheet_visibility #' @param wb A `wbWorkbook` object #' @export wb_get_sheet_visibility <- function(wb) { @@ -1991,9 +1994,10 @@ wb_get_sheet_visibility <- function(wb) { wb$get_sheet_visibility() } -#' @rdname sheet_visibility +#' @rdname wb_sheet_visibility #' @param sheet Worksheet identifier -#' @param value a logical/character vector the same length as sheet +#' @param value a logical/character vector the same length as sheet, +#' if provding a character vector, you can provide any of "hidden", "visible", or "veryHidden" #' @export wb_set_sheet_visibility <- function(wb, sheet = current_sheet(), value) { assert_workbook(wb) @@ -2026,18 +2030,17 @@ wb_add_page_break <- function(wb, sheet = current_sheet(), row = NULL, col = NUL } -#' @name wb_get_tables -#' @title List Excel tables in a workbook -#' @description List Excel tables in a workbook +#' List Excel tables in a worksheet +#' #' @param wb A workbook object #' @param sheet A name or index of a worksheet -#' @return character vector of table names on the specified sheet +#' @return A character vector of table names on the specified sheet #' @examples #' #' wb <- wb_workbook() #' wb$add_worksheet(sheet = "Sheet 1") -#' wb$add_data_table(sheet = "Sheet 1", x = iris) -#' wb$add_data_table(sheet = 1, x = mtcars, tableName = "mtcars", startCol = 10) +#' wb$add_data_table(x = iris) +#' wb$add_data_table(x = mtcars, table_name = "mtcars", start_col = 10) #' #' wb$get_tables(sheet = "Sheet 1") #' @export @@ -2048,37 +2051,37 @@ wb_get_tables <- function(wb, sheet = current_sheet()) { -#' Remove an Excel table in a workbook +#' Remove a data table from a worksheet #' -#' List Excel tables in a workbook +#' Remove Excel tables in a workbook using its name. #' -#' @param wb A workbook object +#' @param wb A Workbook object #' @param sheet A name or index of a worksheet -#' @param table Name of table to remove. See [wb_get_tables()] -#' @param remove_data Removes the data as well -#' @return character vector of table names on the specified sheet +#' @param table Name of table to remove. Use [wb_get_tables()] to view the +#' tables present in the worksheet. +#' @param remove_data Default `TRUE`. If `FALSE`, will only remove the data table attributes +#' but will keep the data in the worksheet. +#' @return The `wbWorkbook`, invisibly #' @examples -#' #' wb <- wb_workbook() #' wb$add_worksheet(sheet = "Sheet 1") #' wb$add_worksheet(sheet = "Sheet 2") -#' wb$add_data_table(sheet = "Sheet 1", x = iris, tableName = "iris") -#' wb$add_data_table(sheet = 1, x = mtcars, tableName = "mtcars", startCol = 10) -#' +#' wb$add_data_table(sheet = "Sheet 1", x = iris, table_name = "iris") +#' wb$add_data_table(sheet = 1, x = mtcars, table_name = "mtcars", start_col = 10) #' -#' wb <- wb_remove_worksheet(wb, sheet = 1) ## delete worksheet removes table objects +#' ## delete worksheet removes table objects +#' wb <- wb_remove_worksheet(wb, sheet = 1) #' -#' wb$add_data_table(sheet = 1, x = iris, tableName = "iris") -#' wb$add_data_table(sheet = 1, x = mtcars, tableName = "mtcars", startCol = 10) +#' wb$add_data_table(sheet = 1, x = iris, table_name = "iris") +#' wb$add_data_table(sheet = 1, x = mtcars, table_name = "mtcars", start_col = 10) #' #' ## wb_remove_tables() deletes table object and all data #' wb_get_tables(wb, sheet = 1) #' wb$remove_tables(sheet = 1, table = "iris") -#' wb$add_data_table(sheet = 1, x = iris, tableName = "iris", startCol = 1) +#' wb$add_data_table(sheet = 1, x = iris, table_name = "iris") #' #' wb_get_tables(wb, sheet = 1) #' wb$remove_tables(sheet = 1, table = "iris") -#' wb$add_data_table(sheet = 1, x = iris, tableName = "iris", startCol = 1) #' @export wb_remove_tables <- function(wb, sheet = current_sheet(), table, remove_data = TRUE) { assert_workbook(wb) @@ -2088,13 +2091,13 @@ wb_remove_tables <- function(wb, sheet = current_sheet(), table, remove_data = T # grouping ---------------------------------------------------------------- -#' Group Rows and Columns +#' Group rows and columns in a worksheet #' #' Group a selection of rows or cols #' -#' @details If row was previously hidden, it will now be shown +#' @details If row was previously hidden, it will now be shown. #' -#' @param wb A [wbWorkbook] object +#' @param wb A `wbWorkbook` object #' @param sheet A name or index of a worksheet #' @param rows,cols Indices of rows and columns to group #' @param collapsed If `TRUE` the grouped columns are collapsed @@ -2191,7 +2194,7 @@ wb_ungroup_rows <- function(wb, sheet = current_sheet(), rows) { # creators ---------------------------------------------------------------- -#' Workbook creators +#' Modify creators of a workbook #' #' Modify and get workbook creators #' @@ -2211,7 +2214,8 @@ wb_ungroup_rows <- function(wb, sheet = current_sheet(), rows) { #' wb_get_creators(wb) #' #' @return -#' * `wb_set_creators()`, `wb_add_creators()`, and `wb_remove_creators()` return the `wbWorkbook` object +#' * `wb_set_creators()`, `wb_add_creators()`, and `wb_remove_creators()` return +#' the `wbWorkbook` object #' * `wb_get_creators()` returns a `character` vector of creators #' #' @name wb_creators @@ -2256,16 +2260,16 @@ wb_get_creators <- function(wb) { #' Gets / Sets the worksheet names for a [wbWorkbook] object. #' #' This only changes the sheet name as shown in spreadsheet software -#' and will not alter it anywhere else. Not in formulas, chart references, +#' and will not alter it elsewhere. Not in formulas, chart references, #' named regions, pivot tables or anywhere else. #' -#' @param wb A `wbWorkbook` object +#' @param wb A [wbWorkbook] object #' @param old The name (or index) of the old sheet name. If `NULL` will assume #' all worksheets are to be renamed. #' @param new The name of the new sheet #' @name wb_sheet_names #' @returns -#' * `set_`: The [wbWorkbook] object. +#' * `set_`: The `wbWorkbook` object. #' * `get_`: A named character vector of sheet names in order. The #' names represent the original value of the worksheet prior to any character #' substitutions. @@ -2278,7 +2282,7 @@ wb_set_sheet_names <- function(wb, old = NULL, new) { wb$clone()$set_sheet_names(old = old, new = new) } #' @rdname wb_sheet_names -#' @param escape Logical if the xml special characters are escaped +#' @param escape Should the xml special characters be escaped? #' @export wb_get_sheet_names <- function(wb, escape = FALSE) { assert_workbook(wb) @@ -2287,17 +2291,15 @@ wb_get_sheet_names <- function(wb, escape = FALSE) { # others? ----------------------------------------------------------------- -#' Add another author to the meta data of the file. +#' Modify author in the metadata of a workbook #' -#' Just a wrapper of wb$set_last_modified_by() +#' Just a wrapper of `wb$set_last_modified_by()` #' #' @param wb A workbook object #' @param name A string object with the name of the LastModifiedBy-User #' @param ... additional arguments -#' -#' @export #' @family workbook wrappers -#' +#' @export #' @examples #' wb <- wb_workbook() #' wb_set_last_modified_by(wb, "test") @@ -2307,13 +2309,12 @@ wb_set_last_modified_by <- function(wb, name, ...) { wb$clone()$set_last_modified_by(name, ...) } -#' Insert an image into a worksheet -#' #' Insert an image into a worksheet #' #' @param wb A workbook object #' @param sheet A name or index of a worksheet -#' @param dims Dimensions where to plot. Default absolute anchor, single cell (eg. "A1") oneCellAnchor, cell range (eg. "A1:D4") twoCellAnchor +#' @param dims Dimensions where to plot. Default absolute anchor, single cell (eg. "A1") +#' oneCellAnchor, cell range (eg. "A1:D4") twoCellAnchor #' @param file An image file. Valid file types are:` "jpeg"`, `"png"`, `"bmp"` #' @param width Width of figure. #' @param height Height of figure. @@ -2363,7 +2364,8 @@ wb_add_image <- function( } -#' add a chart xml to a workbook +#' Add a chart XML to a worksheet +#' #' @param wb a workbook #' @param sheet the sheet on which the graph will appear #' @param dims the dimensions where the sheet will appear @@ -2393,16 +2395,18 @@ wb_add_chart_xml <- function( } -#' clean sheet (remove all values) +#' Remove all values in a worksheet +#' +#' Remove content of a worksheet completely, or a region if specifying `dims`. #' -#' @param wb workbook +#' @param wb A Workbook object #' @param sheet sheet to clean #' @param dims spreadsheet dimensions (optional) #' @param numbers remove all numbers #' @param characters remove all characters #' @param styles remove all styles #' @param merged_cells remove all merged_cells -#' @name cleanup +#' @return A Workbook object #' @export wb_clean_sheet <- function( wb, @@ -2424,26 +2428,39 @@ wb_clean_sheet <- function( ) } -#' little worksheet opener -#' @param wb a workbook +#' Preview a workbook in a spreadsheet software +#' +#' You can also use the shorter `wb$open()` as a replacement. +#' To open xlsx files, see [xl_open()]. +#' +#' @param wb a [wbWorkbook] object #' @export wb_open <- function(wb) { assert_workbook(wb) wb$open() } -#' add style to workbook +#' Set the default style in a workbook +#' +#' wb wrapper to add style to workbook #' -#' @description wb wrapper to add style to workbook -#' @param wb workbook -#' @param style style xml character +#' @param wb A workbook +#' @param style style xml character, created by a `create_*()` function. #' @param style_name style name used optional argument -#' @seealso [create_border()], [create_cell_style()], [create_dxfs_style()], [create_fill()], [create_font()], [create_numfmt()] +#' @return The `wbWorkbook` object, invisibly. +#' @seealso +#' * [create_border()] +#' * [create_cell_style()] +#' * [create_dxfs_style()] +#' * [create_fill()] +#' * [create_font()] +#' * [create_numfmt()] +#' @family workbook styling functions #' @examples #' yellow_f <- wb_color(hex = "FF9C6500") #' yellow_b <- wb_color(hex = "FFFFEB9C") #' -#' yellow <- create_dxfs_style(font_color = yellow_f, bgFill = yellow_b) +#' yellow <- create_dxfs_style(font_color = yellow_f, bg_fill = yellow_b) #' wb <- wb_workbook() %>% wb_add_style(yellow) #' @export wb_add_style <- function(wb, style = NULL, style_name = NULL) { @@ -2453,11 +2470,13 @@ wb_add_style <- function(wb, style = NULL, style_name = NULL) { wb$clone()$add_style(style, style_name) } -#' get and set cell style -#' @name cell_style -#' @param wb wb +#' Apply styling to a cell region +#' +#' @name wb_cell_style +#' @param wb A `wbWorkbook` object #' @param sheet sheet -#' @param dims dims +#' @param dims A cell range in the worksheet +#' @family styles #' @examples #' # set a style in b1 #' wb <- wb_workbook()$add_worksheet()$ @@ -2475,9 +2494,9 @@ wb_get_cell_style <- function(wb, sheet = current_sheet(), dims) { wb$clone()$get_cell_style(sheet, dims) } -#' @rdname cell_style -#' @param style style -#' @return wb_set_cell_style returns the workbook invisible +#' @rdname wb_cell_style +#' @param style A style +#' @return wb_set_cell_style returns the workbook invisibly. #' @export wb_set_cell_style <- function(wb, sheet = current_sheet(), dims, style) { assert_workbook(wb) @@ -2485,15 +2504,18 @@ wb_set_cell_style <- function(wb, sheet = current_sheet(), dims, style) { wb$clone(deep = TRUE)$set_cell_style(sheet, dims, style) } -#' add border for cell region +#' Modify borders in a cell region #' -#' @description wb wrapper to create borders for cell region -#' @param wb workbook -#' @param sheet a worksheet -#' @param dims dimensions on the worksheet e.g. "A1", "A1:A5", "A1:H5" -#' @param bottom_color,left_color,right_color,top_color,inner_hcolor,inner_vcolor a color, either something openxml knows or some RGB color -#' @param left_border,right_border,top_border,bottom_border,inner_hgrid,inner_vgrid the border style, if NULL no border is drawn. See create_border for possible border styles -#' @param ... ... +#' wb wrapper to create borders for cell regions. +#' @param wb A `wbWorkbook` +#' @param sheet A worksheet +#' @param dims Cell range in the worksheet e.g. "A1", "A1:A5", "A1:H5" +#' @param bottom_color,left_color,right_color,top_color,inner_hcolor,inner_vcolor +#' a color, either something openxml knows or some RGB color +#' @param left_border,right_border,top_border,bottom_border,inner_hgrid,inner_vgrid +#' the border style, if `NULL` no border is drawn. +#' See [create_border()] for possible border styles +#' @param ... additional arguments #' @seealso [create_border()] #' @examples #' wb <- wb_workbook() %>% wb_add_worksheet("S1") %>% wb_add_data("S1", mtcars) @@ -2505,6 +2527,7 @@ wb_set_cell_style <- function(wb, sheet = current_sheet(), dims, style) { #' top_border = "hair", bottom_border = "thick") #' wb <- wb_add_border(wb, 1, dims = "C2:C5") #' wb <- wb_add_border(wb, 1, dims = "G2:H3") +#' #' wb <- wb_add_border(wb, 1, dims = "G12:H13", #' left_color = wb_color(hex = "FF9400D3"), right_color = wb_color(hex = "FF4B0082"), #' top_color = wb_color(hex = "FF0000FF"), bottom_color = wb_color(hex = "FF00FF00")) @@ -2554,9 +2577,10 @@ wb_add_border <- function( } -#' add fill for cell region +#' Modify the background fill color in a cell region +#' +#' Add fill to a cell region. #' -#' @description wb wrapper to create fill for cell region #' @param wb a workbook #' @param sheet the worksheet #' @param dims the cell range @@ -2588,7 +2612,7 @@ wb_add_border <- function( #' #' ' #' wb <- wb %>% wb_add_fill("S2", dims = "A7:K10", gradient_fill = gradient_fill2) -#' @return The `wbWorksheetObject`, invisibly +#' @return The `wbWorkbook` object, invisibly #' @family styles #' @export wb_add_fill <- function( @@ -2615,14 +2639,20 @@ wb_add_fill <- function( ) } -#' add font for cell region -#' @details add_font provides all the options openxml accepts for a font node, not all have to be set. Usually name, size and color should be what the user wants. -#' @param wb a workbook +#' Modify font in a cell region +#' +#' Modify the font in a cell region with more precision +#' You can specify the font in a cell with other cell styling functions, +#' but `wb_add_font()` gives you more control. +#' +#' `wb_add_font()` provides all the options openxml accepts for a font node, +#' not all have to be set. Usually `name`, `size` and `color` should be what the user wants. +#' @param wb A Workbook object #' @param sheet the worksheet #' @param dims the cell range -#' @param name font name: default "Calibri" -#' @param color rgb color: default "FF000000" -#' @param size font size: default "11", +#' @param name Font name: default "Calibri" +#' @param color An object created by [wb_color()] +#' @param size Font size: default "11", #' @param bold bold, "single" or "double", default: "" #' @param italic italic #' @param outline outline @@ -2639,7 +2669,7 @@ wb_add_fill <- function( #' @examples #' wb <- wb_workbook() %>% wb_add_worksheet("S1") %>% wb_add_data("S1", mtcars) #' wb %>% wb_add_font("S1", "A1:K1", name = "Arial", color = wb_color(theme = "4")) -#' @return The `wbWorksheetObject`, invisibly +#' @return A `wbWorkbook`, invisibly #' @family styles #' @export wb_add_font <- function( @@ -2688,17 +2718,23 @@ wb_add_font <- function( ) } -#' add numfmt for cell region -#' @param wb a workbook +#' Modify number formatting in a cell region +#' +#' Add number formatting to a cell region. You can use a number format created +#' by [create_numfmt()]. +#' +#' @param wb A Workbook #' @param sheet the worksheet #' @param dims the cell range #' @param numfmt either an id or a character #' @examples #' wb <- wb_workbook() %>% wb_add_worksheet("S1") %>% wb_add_data("S1", mtcars) #' wb %>% wb_add_numfmt("S1", dims = "F1:F33", numfmt = "#.0") -#' @return The `wbWorksheetObject`, invisibly +#' @return The `wbWorkbook` object, invisibly. +#' @seealso [create_numfmt()] #' @family styles #' @export + wb_add_numfmt <- function( wb, sheet = current_sheet(), @@ -2713,7 +2749,9 @@ wb_add_numfmt <- function( ) } -#' add cell style for cell region +#' Modify the style in a cell region +#' +#' Add cell style to a cell region #' @param wb a workbook #' @param sheet the worksheet #' @param dims the cell range @@ -2731,14 +2769,14 @@ wb_add_numfmt <- function( #' @param text_rotation degrees of text rotation #' @param vertical vertical alignment of content ('top', 'center', 'bottom') #' @param wrap_text wrap text in cell -# alignments +## alignments #' @param apply_alignment logical apply alignment #' @param apply_border logical apply border #' @param apply_fill logical apply fill #' @param apply_font logical apply font #' @param apply_number_format logical apply number format #' @param apply_protection logical apply protection -# ids +## ids #' @param border_id border ID to apply #' @param fill_id fill ID to apply #' @param font_id font ID to apply @@ -2749,18 +2787,18 @@ wb_add_numfmt <- function( #' wb <- #' wb_workbook() %>% #' wb_add_worksheet("S1") %>% -#' wb_add_data("S1", mtcars) +#' wb_add_data("S1", x = mtcars) #' #' wb %>% #' wb_add_cell_style( #' "S1", -#' "A1:K1", -#' textRotation = "45", +#' dims = "A1:K1", +#' text_rotation = "45", #' horizontal = "center", #' vertical = "center", -#' wrapText = "1" +#' wrap_text = "1" #' ) -#' @return The `wbWorksheetObject`, invisibly +#' @return The `wbWorkbook` object, invisibly #' @family styles #' @export wb_add_cell_style <- function( @@ -2827,11 +2865,16 @@ wb_add_cell_style <- function( ) } -#' add named style for cell region -#' @param wb wbWorkbook -#' @param sheet sheet -#' @param dims dims -#' @param name name +#' Apply styling to a cell region with a named style +#' +#' Set the styling to a named style for a cell region. Use [wb_add_cell_style()] +#' to style a cell region with custom parameters. +#' A named style is the one in spreadsheet software, like "Normal", "Warning". +#' @param wb A `wbWorkbook` object +#' @param sheet A worksheet +#' @param dims A cell range +#' @param name The named style name. +#' @family styles #' @param font_name,font_size optional else the default of the theme #' @return The `wbWorkbook`, invisibly #' @export @@ -2854,9 +2897,11 @@ wb_add_named_style <- function( ) } -#' add dxfs style -#' These styles are used with conditional formatting and custom table styles -#' @param wb wbWorkbook +#' Set a dxfs styling for the workbook +#' +#' These styles are used with conditional formatting and custom table styles. +#' +#' @param wb A Workbook object. #' @param name the style name #' @param font_name the font name #' @param font_size the font size @@ -2870,15 +2915,16 @@ wb_add_named_style <- function( #' @param text_bold logical if text is bold #' @param text_italic logical if text is italic #' @param text_underline logical if text is underlined -#' @param ... additional arguments passed to `create_dxfs_style()` -#' @return The `wbWorkbookObject`, invisibly +#' @param ... additional arguments passed to [create_dxfs_style()] +#' @family workbook styling functions +#' @return The Workbook object, invisibly #' @examples #' wb <- wb_workbook() %>% #' wb_add_worksheet() %>% #' wb_add_dxfs_style( #' name = "nay", #' font_color = wb_color(hex = "FF9C0006"), -#' bgFill = wb_color(hex = "FFFFC7CE") +#' bg_fill = wb_color(hex = "FFFFC7CE") #' ) #' @export wb_add_dxfs_style <- function( @@ -2919,16 +2965,39 @@ wb_add_dxfs_style <- function( } -#' Add comment to worksheet -#' @param wb A workbook object +#' Add / remove comment in a worksheet +#' +#' @description +#' The comment functions (add and remove) allow the modification of comments. +#' In more recent spreadsheet software they are called notes, while they are called +#' comments in openxml. Modification of what newer spreadsheet software now calls +#' comment is possible via [wb_add_thread()]. +#' +#' `comment` can be created with [create_comment()] to add styling. +#' +#' @param wb A Workbook object #' @param sheet A worksheet of the workbook -#' @param dims Optional row and column as spreadsheet dimension, e.g. "A1" +#' @param dims Row and column as spreadsheet dimension, e.g. "A1" #' @param comment A comment to apply to the worksheet -# To fit, maybe comment, can be `x` +# TODO To fit, maybe comment, can be `x` #' @param ... additional arguments -#' @returns The `wbWorkbook` object -#' @seealso [wb_add_thread()] -#' @rdname comment +#' @returns The Workbook object, invisibly. +#' @seealso [create_comment()], [wb_add_thread()] +#' @name wb_add_comment +#' @keywords comments +#' @examples +#' wb <- wb_workbook() +#' wb$add_worksheet("Sheet 1") +#' # add a comment without author +#' c1 <- create_comment(text = "this is a comment", author = "") +#' wb$add_comment(dims = "B10", comment = c1) +#' #' # Remove comment +#' wb$remove_comment(sheet = "Sheet 1", dims = "B10") +#' # Write another comment with author information +#' c2 <- create_comment(text = "this is another comment", author = "Marco Polo") +#' wb$add_comment(sheet = 1, dims = "C10", comment = c2) +NULL +#' @rdname wb_add_comment #' @export wb_add_comment <- function( wb, @@ -2949,8 +3018,7 @@ wb_add_comment <- function( ) } -#' Remove comment from worksheet -#' @rdname comment +#' @rdname wb_add_comment #' @export wb_remove_comment <- function( wb, @@ -2970,9 +3038,13 @@ wb_remove_comment <- function( #' @rdname wb_add_thread #' @details -#' If a threaded comment is added, it needs a person attached with it. The default is to create a person with provider id `"None"`. Other providers are possible with specific values for `id` and `user_id`. If you require the following, create a workbook via spreadsheet software load it and get the values with [wb_get_person()] -#' @param wb a workbook -#' @param name the name to display +#' If a threaded comment is added, it needs a person attached with it. +#' The default is to create a person with provider id `"None"`. +#' Other providers are possible with specific values for `id` and `user_id`. +#' If you require the following, create a workbook via spreadsheet software load +#' it and get the values with [wb_get_person()] +#' @param wb a Workbook +#' @param name the name of the person to display. #' @param id (optional) the display id #' @param user_id (optional) the user id #' @param provider_id (optional) the provider id @@ -3003,7 +3075,8 @@ wb_get_person <- function(wb, name = NULL) { #' add threaded comment to worksheet #' -#' These functions allow adding thread comments to spreadsheets. This is not yet supported by all spreadsheet software. +#' These functions allow adding thread comments to spreadsheets. +#' This is not yet supported by all spreadsheet software. #' @param wb a workbook #' @param sheet a worksheet #' @param dims a cell @@ -3012,7 +3085,6 @@ wb_get_person <- function(wb, name = NULL) { #' @param reply logical if the comment is a reply #' @param resolve logical if the comment should be marked as resolved #' @seealso [wb_add_comment()] -#' @name wb_add_thread #' @examples #' wb <- wb_workbook()$add_worksheet()$ #' add_person(name = "openxlsx2") @@ -3050,31 +3122,36 @@ wb_add_thread <- function( ) } -#' Add form control Checkbox, Radiobuttons or Dropmenu -#' @param wb A workbook object +#' Add a checkbox, radio button or drop menu to a cell in a worksheet +#' +#' You can add Form Control to a cell. The three supported types are a Checkbox, +#' a Radio button, or a Drop menu. +#' +#' @param wb A Workbook object #' @param sheet A worksheet of the workbook -#' @param dims Optional row and column as spreadsheet dimension, e.g. "A1" +#' @param dims A single cell as spreadsheet dimension, e.g. "A1". #' @param type A type "Checkbox" (the default), "Radio" a radio button or "Drop" a drop down menu -#' @param text A text to be shown next to the Checkbox or radio button +#' @param text A text to be shown next to the Checkbox or radio button (optional) #' @param link A cell range to link to #' @param range A cell range used as input -#' @param checked A logical indicating if the Checkbox or radio button is checked -#' @returns The `wbWorkbook` object +#' @param checked A logical indicating if the Checkbox or Radio button is checked +#' @returns The `wbWorkbook` object, invisibly. #' @examples #' wb <- wb_workbook() %>% wb_add_worksheet() %>% #' wb_add_form_control() +#' # Add +#' wb$add_form_control(dims = "C5", type = "Radio", checked = TRUE) #' @export wb_add_form_control <- function( wb, sheet = current_sheet(), dims = "A1", - type = NULL, + type = c("Checkbox", "Radio", "Drop"), text = NULL, link = NULL, range = NULL, checked = FALSE ) { - assert_workbook(wb) wb$clone()$add_form_control( sheet = sheet, @@ -3088,64 +3165,65 @@ wb_add_form_control <- function( } -#' Add conditional formatting to cells +#' Add conditional formatting to cells in a worksheet #' -#' Add conditional formatting to cells -#' @param wb A workbook object +#' Add conditional formatting to cells. +#' You can find more details in `vignette("conditional-formatting")`. +#' +#' openxml uses the alpha channel first then RGB, whereas the usual default is RGBA. +#' @param wb A Workbook object #' @param sheet A name or index of a worksheet #' @param dims A cell or cell range like "A1" or "A1:B2" -#' @param rule The condition under which to apply the formatting. See examples. -#' @param style A style to apply to those cells that satisfy the rule. Default is 'font_color = "FF9C0006"' and 'bgFill = "FFFFC7CE"' -#' @param type The type of conditional formatting rule to apply. -#' @param params Additional parameters passed. See **Details** for more +#' @param rule The condition under which to apply the formatting. See **Examples**. +#' @param style A style to apply to those cells that satisfy the rule. +#' Default is `font_color = "FF9C0006"` and `bg_fill = "FFFFC7CE"` +#' @param type The type of conditional formatting rule to apply. One of `"expression"`, `"colorScale"` or others mentioned in **Details**. +#' @param params A list of additional parameters passed. See **Details** for more. #' @param ... additional arguments -#' @details See Examples. -#' #' @details -#' Conditional formatting types accept different parameters. Unless noted, +#' Conditional formatting `type` accept different parameters. Unless noted, #' unlisted parameters are ignored. -#' #' \describe{ #' \item{`expression`}{ #' `[style]`\cr A `Style` object\cr\cr #' `[rule]`\cr An Excel expression (as a character). Valid operators are: `<`, `<=`, `>`, `>=`, `==`, `!=` #' } -#' \item{colorScale}{ +#' \item{`colorScale`}{ #' `[style]`\cr A `character` vector of valid colors with length `2` or `3`\cr\cr #' `[rule]`\cr `NULL` or a `character` vector of valid colors of equal length to `styles` #' } -#' \item{dataBar}{ +#' \item{`dataBar`}{ #' `[style]`\cr A `character` vector of valid colors with length `2` or `3`\cr\cr #' `[rule]`\cr A `numeric` vector specifying the range of the databar colors. Must be equal length to `style`\cr\cr #' `[params$showValue]`\cr If `FALSE` the cell value is hidden. Default `TRUE`\cr\cr #' `[params$gradient]`\cr If `FALSE` color gradient is removed. Default `TRUE`\cr\cr #' `[params$border]`\cr If `FALSE` the border around the database is hidden. Default `TRUE` #' } -#' \item{duplicatedValues/uniqueValues/containsErrors}{ +#' \item{`duplicatedValues` / `uniqueValues` / `containsErrors`}{ #' `[style]`\cr A `Style` object #' } -#' \item{contains}{ +#' \item{`contains`}{ #' `[style]`\cr A `Style` object\cr\cr #' `[rule]`\cr The text to look for within cells #' } -#' \item{between}{ -#' `[style]`\cr A Style object.\cr\cr +#' \item{`between`}{ +#' `[style]`\cr A `Style` object.\cr\cr #' `[rule]`\cr A `numeric` vector of length `2` specifying lower and upper bound (Inclusive) #' } -#' \item{topN}{ +#' \item{`topN`}{ #' `[style]`\cr A `Style` object\cr\cr #' `[params$rank]`\cr A `numeric` vector of length `1` indicating number of highest values. Default `5L`\cr\cr -#' `[params$percent]` If `TRUE` uses percentage +#' `[params$percent]` If `TRUE`, uses percentage #' } -#' \item{bottomN}{ +#' \item{`bottomN`}{ #' `[style]`\cr A `Style` object\cr\cr #' `[params$rank]`\cr A `numeric` vector of length `1` indicating number of lowest values. Default `5L`\cr\cr -#' `[params$percent]`\cr If `TRUE` uses percentage +#' `[params$percent]`\cr If `TRUE`, uses percentage #' } -#' \item{iconSet}{ -#' `[params$showValue]`\cr If `FALSE` the cell value is hidden. Default `TRUE`\cr\cr -#' `[params$reverse]`\cr If `TRUE` the order is reversed. Default `FALSE`\cr\cr -#' `[params$percent]`\cr If `TRUE` uses percentage\cr\cr +#' \item{`iconSet`}{ +#' `[params$showValue]`\cr If `FALSE`, the cell value is hidden. Default `TRUE`\cr\cr +#' `[params$reverse]`\cr If `TRUE`, the order is reversed. Default `FALSE`\cr\cr +#' `[params$percent]`\cr If `TRUE`, uses percentage\cr\cr #' `[params$iconSet]`\cr Uses one of the implemented icon sets. Values must match the length of the icons #' in the set 3Arrows, 3ArrowsGray, 3Flags, 3Signs, 3Symbols, 3Symbols2, 3TrafficLights1, 3TrafficLights2, #' 4Arrows, 4ArrowsGray, 4Rating, 4RedToBlack, 4TrafficLights, 5Arrows, 5ArrowsGray, 5Quarters, 5Rating. The @@ -3156,8 +3234,8 @@ wb_add_form_control <- function( #' @examples #' wb <- wb_workbook() #' wb$add_worksheet("a") -#' wb$add_data("a", 1:4, colNames = FALSE) -#' wb$add_conditional_formatting("a", cols = 1, rows = 1:4, rule = ">2") +#' wb$add_data(x = 1:4, col_names = FALSE) +#' wb$add_conditional_formatting(dims = wb_dims(cols = "A", rows = 1:4), rule = ">2") #' @export wb_add_conditional_formatting <- function( wb, @@ -3196,26 +3274,27 @@ wb_add_conditional_formatting <- function( ) } -#' clone sheets style +#' Apply styling from a sheet to another within a workbook #' -#' @param wb workbook +#' This function can be used to apply styling from a cell range, and apply it +#' to another cell range. +#' @param wb A workbook #' @param from sheet we select the style from -#' @param to sheet we apply the style from -#' @family styles +#' @param to sheet to apply the style to #' @export wb_clone_sheet_style <- function(wb, from = current_sheet(), to) { assert_workbook(wb) wb$clone()$clone_sheet_style(from, to) } -#' add sparklines to workbook +#' Add sparklines to a worksheet #' -#' @param wb workbook +#' @param wb A `wbWorkbook` #' @param sheet sheet to add the sparklines to -#' @param sparklines sparklines object created with `create_sparklines()` +#' @param sparklines sparklines object created with [create_sparklines()] #' @seealso [create_sparklines()] #' @examples -#' sl <- create_sparklines("Sheet 1", "A3:K3", "L3") +#' sl <- create_sparklines("Sheet 1", dims = "A3:K3", sqref = "L3") #' wb <- wb_workbook() %>% #' wb_add_worksheet() %>% #' wb_add_data(x = mtcars) %>% @@ -3226,21 +3305,23 @@ wb_add_sparklines <- function(wb, sheet = current_sheet(), sparklines) { wb$clone(deep = TRUE)$add_sparklines(sheet, sparklines) } -#' Ignore error on worksheet +#' Ignore error types on worksheet #' -#' @param wb workbook -#' @param sheet sheet -#' @param dims dims +#' This function allows to hide / ignore certain types of errors shown in a worksheet. +#' @param wb A workbook +#' @param sheet A sheet name or index. +#' @param dims Cell range to ignore the error #' @param calculated_column calculatedColumn #' @param empty_cell_reference emptyCellReference #' @param eval_error evalError #' @param formula formula #' @param formula_range formulaRange #' @param list_data_validation listDataValidation -#' @param number_stored_as_text numberStoredAsText +#' @param number_stored_as_text If `TRUE`, will not display the error if numbers are stored as text. #' @param two_digit_text_year twoDigitTextYear #' @param unlocked_formula unlockedFormula #' @param ... additional arguments +#' @return The `wbWorkbook` object, invisibly. wb_add_ignore_error <- function( wb, sheet = current_sheet(), @@ -3273,43 +3354,47 @@ wb_add_ignore_error <- function( ) } -#' add sheetview -#' @param wb workbook +#' Modify the default view of a worksheet +#' +#' This helps set a worksheet's appearance, such as the zoom, whether to show grid lines +#' +#' @param wb A Workbook object #' @param sheet sheet #' @param color_id,default_grid_color Integer: A color, default is 64 -#' @param right_to_left Logical: if TRUE column ordering is right to left -#' @param show_formulas Logical: if TRUE cell formulas are shown -#' @param show_grid_lines Logical: if TRUE the worksheet grid is shown -#' @param show_outline_symbols Logical: if TRUE outline symbols are shown -#' @param show_row_col_headers Logical: if TRUE row and column headers are shown -#' @param show_ruler Logical: if TRUE a ruler is shown in page layout view -#' @param show_white_space Logical: if TRUE margins are shown in page layout view -#' @param show_zeros Logical: if FALSE cells containing zero are shown blank if !showFormulas +#' @param right_to_left Logical: if `TRUE` column ordering is right to left +#' @param show_formulas Logical: if `TRUE` cell formulas are shown +#' @param show_grid_lines Logical: if `TRUE` the worksheet grid is shown +#' @param show_outline_symbols Logical: if `TRUE` outline symbols are shown +#' @param show_row_col_headers Logical: if `TRUE` row and column headers are shown +#' @param show_ruler Logical: if `TRUE` a ruler is shown in page layout view +#' @param show_white_space Logical: if `TRUE` margins are shown in page layout view +#' @param show_zeros Logical: if `FALSE` cells containing zero are shown blank if `show_formulas = FALSE` #' @param tab_selected Integer: zero vector indicating the selected tab #' @param top_left_cell Cell: the cell shown in the top left corner / or top right with rightToLeft #' @param view View: "normal", "pageBreakPreview" or "pageLayout" -#' @param window_protection Logical: if TRUE the panes are protected +#' @param window_protection Logical: if `TRUE` the panes are protected #' @param workbook_view_id integer: Pointing to some other view inside the workbook -#' @param zoom_scale,zoom_scale_normal,zoom_scale_page_layout_view,zoom_scale_sheet_layout_view Integer: the zoom scale should be between 10 and 400. These are values for current, normal etc. +#' @param zoom_scale,zoom_scale_normal,zoom_scale_page_layout_view,zoom_scale_sheet_layout_view +#' Integer: the zoom scale should be between 10 and 400. These are values for current, normal etc. #' @param ... additional arguments #' @examples #' wb <- wb_workbook()$add_worksheet() #' #' wb$set_sheetview( -#' zoomScale = 75, -#' rightToLeft = FALSE, -#' showFormulas = TRUE, -#' showGridLines = TRUE, -#' showOutlineSymbols = FALSE, -#' showRowColHeaders = TRUE, -#' showRuler = TRUE, -#' showWhiteSpace = FALSE, -#' tabSelected = 1, -#' topLeftCell = "B1", +#' zoom_scale = 75, +#' right_to_left = FALSE, +#' show_formulas = TRUE, +#' show_grid_lines = TRUE, +#' show_outline_symbols = FALSE, +#' show_row_col_headers = TRUE, +#' show_ruler = TRUE, +#' show_white_space = FALSE, +#' tab_selected = 1, +#' top_left_cell = "B1", #' view = "normal", -#' windowProtection = TRUE +#' window_protection = TRUE #' ) -#' @return The `wbWorksheetObject`, invisibly +#' @return The `wbWorkbook` object, invisibly #' @export wb_set_sheetview <- function( wb, @@ -3361,30 +3446,34 @@ wb_set_sheetview <- function( ) } -#' get and set table of sheets and their state as selected and active -#' @description Multiple sheets can be selected, but only a single one can be -#' active (visible). The visible sheet, must not necessarily be a selected -#' sheet. +#' Modify the state of active and selected sheets in a workbook +#' +#' @description +#' Get and set table of sheets and their state as selected and active in a workbook +#' +#' Multiple sheets can be selected, but only a single one can be active (visible). +#' The visible sheet, must not necessarily be a selected sheet. +#' #' @param wb a workbook #' @returns a data frame with tabSelected and names #' @export #' @examples -#' wb <- wb_load(file = system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2")) -#' # testing is the selected sheet -#' wb_get_selected(wb) -#' # change the selected sheet to Sheet2 -#' wb <- wb_set_selected(wb, "Sheet2") -#' # get the active sheet -#' wb_get_active_sheet(wb) -#' # change the selected sheet to Sheet2 -#' wb <- wb_set_active_sheet(wb, sheet = "Sheet2") -#' @name select_active_sheet +#' wb <- wb_load(file = system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2")) +#' # testing is the selected sheet +#' wb_get_selected(wb) +#' # change the selected sheet to Sheet2 +#' wb <- wb_set_selected(wb, "Sheet2") +#' # get the active sheet +#' wb_get_active_sheet(wb) +#' # change the selected sheet to Sheet2 +#' wb <- wb_set_active_sheet(wb, sheet = "Sheet2") +#' @name wb_active_sheet wb_get_active_sheet <- function(wb) { assert_workbook(wb) wb$get_active_sheet() } -#' @rdname select_active_sheet +#' @rdname wb_active_sheet #' @param sheet a sheet name of the workbook #' @export wb_set_active_sheet <- function(wb, sheet) { @@ -3393,14 +3482,14 @@ wb_set_active_sheet <- function(wb, sheet) { wb$clone()$set_active_sheet(sheet = sheet) } -#' @name select_active_sheet +#' @rdname wb_active_sheet #' @export wb_get_selected <- function(wb) { assert_workbook(wb) wb$get_selected() } -#' @name select_active_sheet +#' @rdname wb_active_sheet #' @export wb_set_selected <- function(wb, sheet) { assert_workbook(wb) diff --git a/R/class-workbook.R b/R/class-workbook.R index 6dcd68c63..c2a6c54ea 100644 --- a/R/class-workbook.R +++ b/R/class-workbook.R @@ -2,7 +2,7 @@ # R6 class ---------------------------------------------------------------- # Lines 7 and 8 are needed until r-lib/roxygen2#1504 is fixed -#' R6 class for a Workbook +#' R6 class for a workbook #' #' @description #' A workbook @@ -73,7 +73,7 @@ wbWorkbook <- R6::R6Class( #' @field media media media = NULL, - #' @field metadata metadata + #' @field metadata contains cell/value metadata imported on load from xl/metadata.xml metadata = NULL, #' @field persons persons @@ -4821,13 +4821,12 @@ wbWorkbook <- R6::R6Class( add_form_control = function( sheet = current_sheet(), dims = "A1", - type = NULL, + type = c("Checkbox", "Radio", "Drop"), text = NULL, link = NULL, range = NULL, checked = FALSE ) { - sheet <- private$get_sheet_index(sheet) if (!is.null(dims)) { @@ -4849,13 +4848,10 @@ wbWorkbook <- R6::R6Class( } } - if (is.null(text)) { - text <- "" - } + text <- text %||% "" + + type <- match.arg(type) - if (is.null(type)) { - type <- "Checkbox" - } clientData <- genClientDataFC(left, top, right, bottom, link, range, type, checked) @@ -5630,12 +5626,12 @@ wbWorkbook <- R6::R6Class( local_sheet = FALSE, overwrite = FALSE, comment = NULL, + hidden = NULL, custom_menu = NULL, description = NULL, is_function = NULL, function_group_id = NULL, help = NULL, - hidden = NULL, local_name = NULL, publish_to_server = NULL, status_bar = NULL, @@ -7161,7 +7157,8 @@ wbWorkbook <- R6::R6Class( } if (tolower(sheet) %in% self$sheet_names) { - warning("Fixing: a sheet with name '", sheet, '"already exists. Creating a unique sheetname"') + warning('Attempted to add a worksheet that is invalid or already exists.\n', + 'Fixing: a sheet with name "', sheet, '" already exists. Creating a unique sheetname"', call. = FALSE) ## We simply append (1), while spreadsheet software would increase ## the integer as: Sheet, Sheet (1), Sheet (2) etc. sheet <- paste(sheet, "(1)") diff --git a/R/get-named-regions.R b/R/get-named-regions.R index 6d7d8bb59..f8d55a27f 100644 --- a/R/get-named-regions.R +++ b/R/get-named-regions.R @@ -54,12 +54,33 @@ wb_get_named_regions_tab <- function(wb) { ) } -#' Get create or remove named regions +#' Get named regions in a workbook or an xlsx file #' -#' Return a vector of named regions in a xlsx file or `wbWorkbook` object -#' @param x An xlsx file or `wbWorkbook` object -#' @param tables add tables too if `TRUE` +#' @returns A vector of named regions in `x`. +#' @param x An xlsx file or a`wbWorkbook` object +#' @param tables Should data tables be included in the result? +#' @seealso [wb_add_named_region()], [wb_get_tables()] #' @export +#' @examples +#' wb <- wb_workbook() +#' wb$add_worksheet("Sheet 1") +#' +#' ## specify region +#' wb$add_data(x = iris, start_col = 1, start_row = 1) +#' wb$add_named_region( +#' name = "iris", +#' dims = wb_dims(x = iris) +#' )$add_data(sheet = 1, x = iris, name = "iris2", start_col = 10) +#' +#' out_file <- temp_xlsx() +#' wb_save(wb, out_file, overwrite = TRUE) +#' +#' ## see named regions +#' wb_get_named_regions(wb) ## From Workbook object +#' wb_get_named_regions(out_file) ## From xlsx file +#' +#' df <- read_xlsx(out_file, named_region = "iris2") +#' head(df) wb_get_named_regions <- function(x, tables = FALSE) { if (inherits(x, "wbWorkbook")) { wb <- x diff --git a/R/helper-functions.R b/R/helper-functions.R index 9bc1948fb..a12f904c7 100644 --- a/R/helper-functions.R +++ b/R/helper-functions.R @@ -391,12 +391,15 @@ hashPassword <- function(password) { format(as.hexmode(hash), upper.case = TRUE) } -#' create sparklines used in `add_sparline()` -#' @details the colors are all predefined to be rgb. Maybe theme colors can be +#' Create sparklines object +#' +#' Create a sparkline to be added a workbook with [wb_add_sparklines()] +#' +#' Colors are all predefined to be rgb. Maybe theme colors can be #' used too. #' @param sheet sheet -#' @param dims dims -#' @param sqref sqref +#' @param dims Cell range of cells used to create the sparklines +#' @param sqref Cell range of the destination of the sparklines. #' @param type type #' @param negative negative #' @param displayEmptyCellsAs displayEmptyCellsAs @@ -413,6 +416,7 @@ hashPassword <- function(password) { #' @param colorLast colorLast #' @param colorHigh colorHigh #' @param colorLow colorLow +#' @return A string containing XML code #' @examples #' # create sparklineGroup #' sparklines <- c( @@ -452,6 +456,7 @@ create_sparklines <- function( colorHigh = wb_color(hex = "FFD00000"), colorLow = wb_color(hex = "FFD00000") ) { + # TODO change arguments to snake case? assert_class(dims, "character") assert_class(sqref, "character") diff --git a/R/read.R b/R/read.R index 84d1d95e2..6f8191bb7 100644 --- a/R/read.R +++ b/R/read.R @@ -1,9 +1,9 @@ # `wb_to_df()` ---------------------------------------- -#' Create Dataframe from Workbook +#' Create a data frame from a Workbook #' #' Simple function to create a `data.frame` from a workbook. Simple as in simply -#' written down. [read_xlsx()] and [wb_read()] are just internal wrappers for -#' [wb_to_df()] intended for people coming from other packages. +#' written down. `read_xlsx()` and `wb_read()` are just internal wrappers of +#' `wb_to_df()` intended for people coming from other packages. #' #' @details #' Depending if the R package `hms` is loaded, `wb_to_df()` returns @@ -13,11 +13,17 @@ #' * 0: character #' * 1: numeric #' * 2: date -#' * 3: posixt +#' * 3: posixt (datetime) #' * 4: logical +#' +#' `read_xlsx()` will not pick up formulas added to a Workbook object +#' via [wb_add_formula()]. This is because only the formula is written and left +#' to be evaluated when the file is opened in a spreadsheet software. +#' Opening, saving and closing the file in a spreadsheet software will resolve this. +#' #' @seealso [wb_get_named_regions()] #' -#' @param file An xlsx file, Workbook object or URL to xlsx file. +#' @param file An xlsx file, [wbWorkbook] object or URL to xlsx file. #' @param sheet Either sheet name or index. When missing the first sheet in the workbook is selected. #' @param col_names If `TRUE`, the first row of data will be used as column names. #' @param row_names If `TRUE`, the first col of data will be used as row names. @@ -31,12 +37,12 @@ #' @param skip_hidden_rows If `TRUE`, hidden rows are skipped. #' @param start_row first row to begin looking for data. #' @param start_col first column to begin looking for data. -#' @param rows A numeric vector specifying which rows in the Excel file to read. +#' @param rows A numeric vector specifying which rows in the xlsx file to read. #' If `NULL`, all rows are read. -#' @param cols A numeric vector specifying which columns in the Excel file to read. +#' @param cols A numeric vector specifying which columns in the xlsx file to read. #' If `NULL`, all columns are read. #' @param named_region Character string with a `named_region` (defined name or table). -#' If no sheet is selected, the first appearance will be selected. +#' If no sheet is selected, the first appearance will be selected. See [wb_get_named_regions()] #' @param types A named numeric indicating, the type of the data. #' Names must match the returned data. See **Details** for more. #' @param na.strings A character vector of strings which are to be interpreted as `NA`. @@ -97,7 +103,7 @@ #' wb_to_df(wb1, na.strings = "a") #' #' ########################################################################### -#' # named_region // namedRegion +#' # Named regions #' file_named_region <- system.file("extdata", "namedRegions3.xlsx", package = "openxlsx2") #' wb2 <- wb_load(file_named_region) #' @@ -599,11 +605,6 @@ wb_to_df <- function( # `read_xlsx()` ----------------------------------------------------------------- # Ignored by roxygen2 when combining documentation # #' Read from an Excel file or Workbook object -#' -#' @details -#' Formulae written using write_formula to a Workbook object will not get picked up by `read_xlsx()`. -#' This is because only the formula is written and left to be evaluated when the file is opened in Excel. -#' Opening, saving and closing the file with Excel will resolve this. #' @rdname wb_to_df #' @export read_xlsx <- function( @@ -702,13 +703,17 @@ wb_read <- function( } +#' Add the `wb_data` attribute to a data frame in a worksheet +#' #' provide wb_data object as mschart input +#' #' @param wb a workbook #' @param sheet a sheet in the workbook either name or index #' @param dims the dimensions -#' @param ... additional arguments for wb_to_df. Be aware that not every +#' @param ... additional arguments for `wb_to_df()`. Be aware that not every #' argument is valid. -#' @seealso [wb_to_df()] [wb_add_mschart()] +#' @returns A data frame of class `wb_data`. +#' @seealso [wb_to_df()] [wb_add_mschart()], [wb_add_pivot_table()] #' @examples #' wb <- wb_workbook() %>% #' wb_add_worksheet() %>% diff --git a/R/utils.R b/R/utils.R index 53ca5a1ca..f773622f9 100644 --- a/R/utils.R +++ b/R/utils.R @@ -185,8 +185,10 @@ random_string <- function(n = 1, length = 16, pattern = "[A-Za-z0-9]", keep_seed #' * A list of rows and columns for `to_rowcol` #' @examples #' dims_to_rowcol("A1:J10") -#' rowcol_to_dims(1:10, 1:10) +#' wb_dims(1:10, 1:10) +#' #' @name dims_helper +#' @seealso [wb_dims()] NULL #' @rdname dims_helper #' @export diff --git a/R/wb_functions.R b/R/wb_functions.R index 77cdfd87f..ac075a821 100644 --- a/R/wb_functions.R +++ b/R/wb_functions.R @@ -262,12 +262,15 @@ style_is_hms <- function(cellXfs, numfmt_date) { } -#' @rdname cleanup +#' Delete data +#' +#' This function is deprecated. Use [wb_clean_sheet()]. #' @param wb workbook #' @param sheet sheet to clean #' @param cols numeric column vector #' @param rows numeric row vector #' @export +#' @keywords internal delete_data <- function(wb, sheet, cols, rows) { .Deprecated(old = "delete_data", new = "wb_clean_sheet", package = "openxlsx2") diff --git a/R/wb_load.R b/R/wb_load.R index d33887961..66f885b88 100644 --- a/R/wb_load.R +++ b/R/wb_load.R @@ -1,26 +1,28 @@ -#' @name wb_load -#' @title Load an existing .xlsx file +#' Load an existing .xlsx file +#' +#' `wb_load()` returns a [wbWorkbook] object conserving styles and +#' formatting of the original input file. +#' +#' A warning is displayed if an xml namespace for main is found in the xlsx file. +#' Certain xlsx files created by third-party applications contain a namespace +#' (usually `x`). This namespace is not required for the file to work in spreadsheet +#' software and is not expected by `openxlsx2`. Therefore it is removed when the +#' file is loaded into a workbook. Removal is generally expected to be safe, +#' but the feature is still experimental. +#' #' @param file A path to an existing .xlsx or .xlsm file #' @param sheet optional sheet parameter. if this is applied, only the selected -#' sheet will be loaded. +#' sheet will be loaded. #' @param data_only mode to import if only a data frame should be returned. This -#' strips the wbWorkbook to a bare minimum. +#' strips the `wbWorkbook` to a bare minimum. #' @param calc_chain optionally you can keep the calculation chain intact. This -#' is used by spreadsheet software to identify the order in which formulas are -#' evaluated. Removing the calculation chain is considered harmless. The calc -#' chain will be created upon the next time the worksheet is loaded in -#' spreadsheet software. Keeping it, might only speed loading time in said -#' software. +#' is used by spreadsheet software to identify the order in which formulas are +#' evaluated. Removing the calculation chain is considered harmless. The calc +#' chain will be created upon the next time the worksheet is loaded in +#' spreadsheet software. Keeping it, might only speed loading time in said +#' software. #' @param ... additional arguments -#' @description wb_load returns a workbook object conserving styles and -#' formatting of the original .xlsx file. -#' @details A warning is displayed if an xml namespace for main is found in the -#' xlsx file. Certain xlsx files created by third-party applications contain a -#' namespace (usually `x`). This namespace is not required for the file to work -#' in spreadsheet software and is not expected by `openxlsx2`. Therefore it is -#' removed when the file is loaded into a workbook. Removal is generally -#' expected to be safe, but the feature is still experimental. -#' @return Workbook object. +#' @return A Workbook object. #' @export #' @seealso [wb_remove_worksheet()] #' @examples diff --git a/R/write.R b/R/write.R index 6e1110f45..976498d6b 100644 --- a/R/write.R +++ b/R/write.R @@ -946,83 +946,23 @@ write_data_table <- function( # `write_data()` --------------------------------------------------------------- #' Write an object to a worksheet #' -#' Write an object to worksheet with optional styling. Use [wb_add_data()] in new code. +#' Write an object to worksheet with optional styling. Use [wb_add_data()] or [write_xlsx()] in new code. #' -#' Formulae written using write_formula to a Workbook object will not get picked up by read_xlsx(). +#' Formulae written using [wb_add_formula()] to a Workbook object will not get picked up by `read_xlsx()`. #' This is because only the formula is written and left to Excel to evaluate the formula when the file is opened in Excel. #' The string `"_openxlsx_NA"` is reserved for `openxlsx2`. If the data frame contains this string, the output will be broken. #' -#' @param wb A Workbook object containing a worksheet. -#' @param sheet The worksheet to write to. Can be the worksheet index or name. -#' @param x Object to be written. For classes supported look at the examples. -#' @param start_col A vector specifying the starting column to write to. -#' @param start_row A vector specifying the starting row to write to. -#' @param dims Spreadsheet dimensions that will determine startCol and startRow: "A1", "A1:B2", "A:B" -#' @param array A bool if the function written is of type array -#' @param col_names If `TRUE`, column names of x are written. -#' @param row_names If `TRUE`, data.frame row names of x are written. -#' @param with_filter If `TRUE`, add filters to the column name row. NOTE can only have one filter per worksheet. -#' @param sep Only applies to list columns. The separator used to collapse list columns to a character vector e.g. sapply(x$list_column, paste, collapse = sep). -#' @param name If not NULL, a named region is defined. -#' @param apply_cell_style apply styles when writing on the sheet -#' @param remove_cell_style if writing into existing cells, should the cell style be removed? -#' @param na.strings Value used for replacing `NA` values from `x`. Default -#' `na_strings()` uses the special `#N/A` value within the workbook. -#' @param inline_strings write characters as inline strings -#' @param ... additional arguments -#' @seealso [wb_add_data()], [wb_add_data_table()] +#' @inheritParams wb_add_data +#' @seealso [wb_add_data()], [write_xlsx()] #' @return invisible(0) -# TODO examples them from here, as docs of `wb_add_data()` and `write_data()` are now separated. #' @examples -#' ## See formatting vignette for further examples. -#' -#' ## Options for default styling (These are the defaults) -#' options("openxlsx2.dateFormat" = "mm/dd/yyyy") -#' options("openxlsx2.datetimeFormat" = "yyyy-mm-dd hh:mm:ss") -#' options("openxlsx2.numFmt" = NULL) -#' -#' ############################################################################# -#' ## Create Workbook object and add worksheets -#' wb <- wb_workbook() -#' -#' ## Add worksheets -#' wb$add_worksheet("Cars") -#' wb$add_worksheet("Formula") -#' -#' x <- mtcars[1:6, ] -#' wb$add_data("Cars", x, startCol = 2, startRow = 3, rowNames = TRUE) -#' -#' ############################################################################# -#' ## Hyperlinks -#' ## - vectors/columns with class 'hyperlink' are written as hyperlinks' -#' -#' v <- rep("https://CRAN.R-project.org/", 4) -#' names(v) <- paste0("Hyperlink", 1:4) # Optional: names will be used as display text -#' class(v) <- "hyperlink" -#' wb$add_data("Cars", x = v, dims = c("B32")) -#' -#' ############################################################################# -#' ## Formulas -#' ## - vectors/columns with class 'formula' are written as formulas' -#' -#' df <- data.frame( -#' x = 1:3, y = 1:3, -#' z = paste(paste0("A", 1:3 + 1L), paste0("B", 1:3 + 1L), sep = "+"), -#' stringsAsFactors = FALSE -#' ) -#' -#' class(df$z) <- c(class(df$z), "formula") -#' -#' wb$add_data(sheet = "Formula", x = df) -#' -#' ############################################################################# #' # update cell range and add mtcars #' xlsxFile <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2") #' wb2 <- wb_load(xlsxFile) #' #' # read dataset with inlinestr #' wb_to_df(wb2) -#' write_data(wb2, 1, mtcars, startCol = 4, startRow = 4) +#' write_data(wb2, 1, mtcars, start_col = 4, start_row = 4) #' wb_to_df(wb2) #' @export #' @keywords internal @@ -1270,39 +1210,8 @@ write_formula <- function( #' #' Write to a worksheet and format as an Excel table. Use [wb_add_data_table()] in new code. #' -#' @param wb A Workbook object containing a worksheet. -#' @param sheet The worksheet to write to. Can be the worksheet index or name. -#' @param x A data frame. -#' @param start_col A vector specifying the starting column to write df -#' @param start_row A vector specifying the starting row to write df -#' @param dims Spreadsheet dimensions that will determine startCol and startRow: "A1", "A1:B2", "A:B" -#' @param col_names If `TRUE`, column names of x are written. -#' @param row_names If `TRUE`, row names of x are written. -#' @param table_style Any excel table style name or "none" (see "formatting" vignette). -#' @param table_name name of table in workbook. The table name must be unique. -#' @param with_filter If `TRUE`, columns with have filters in the first row. -#' @param sep Only applies to list columns. The separator used to collapse list columns to a character vector e.g. sapply(x$list_column, paste, collapse = sep). -#' \cr\cr -#' \cr**The below options correspond to Excel table options:** -#' \cr -#' \if{html}{\figure{tableoptions.png}{options: width="40\%" alt="Figure: table_options.png"}} -#' \if{latex}{\figure{tableoptions.pdf}{options: width=7cm}} -#' -#' @param first_column logical. If TRUE, the first column is bold -#' @param last_column logical. If TRUE, the last column is bold -#' @param banded_rows logical. If TRUE, rows are color banded -#' @param banded_cols logical. If TRUE, the columns are color banded -#' @param apply_cell_style apply styles when writing on the sheet -#' @param remove_cell_style if writing into existing cells, should the cell style be removed? -#' @param na.strings Value used for replacing `NA` values from `x`. Default -#' `na_strings()` uses the special `#N/A` value within the workbook. -#' @param inline_strings write characters as inline strings -#' @param ... additional arguments -#' @details columns of x with class Date/POSIXt, currency, accounting, -#' hyperlink, percentage are automatically styled as dates, currency, accounting, -#' hyperlinks, percentages respectively. -#' The string `"_openxlsx_NA"` is reserved for `openxlsx2`. If the data frame -#' contains this string, the output will be broken. +#' @inheritParams wb_add_data_table +#' @inherit wb_add_data_table details #' @seealso #' [wb_add_worksheet()] #' [wb_add_data_table()] @@ -1325,8 +1234,8 @@ write_formula <- function( #' wb$add_data_table("S1", x = iris) #' #' wb$add_data_table("S2", -#' x = mtcars, dims = c("B3"), rowNames = TRUE, -#' tableStyle = "TableStyleLight9" +#' x = mtcars, dims = c("B3"), row_names = TRUE, +#' table_style = "TableStyleLight9" #' ) #' #' df <- data.frame( @@ -1346,7 +1255,7 @@ write_formula <- function( #' class(df$Percentage) <- c(class(df$Percentage), "percentage") #' class(df$TinyNumbers) <- c(class(df$TinyNumbers), "scientific") #' -#' wb$add_data_table("S3", x = df, startRow = 4, rowNames = TRUE, tableStyle = "TableStyleMedium9") +#' wb$add_data_table("S3", x = df, start_row = 4, row_names = TRUE, table_style = "TableStyleMedium9") #' #' ##################################################################################### #' ## Additional Header Styling and remove column filters @@ -1354,12 +1263,12 @@ write_formula <- function( #' write_datatable(wb, #' sheet = 1, #' x = iris, -#' startCol = 7, -#' withFilter = FALSE, -#' firstColumn = TRUE, -#' lastColumn = TRUE, -#' bandedRows = TRUE, -#' bandedCols = TRUE +#' start_col = 7, +#' with_filter = FALSE, +#' first_column = TRUE, +#' last_column = TRUE, +#' banded_rows = TRUE, +#' banded_cols = TRUE #' ) #' #' ##################################################################################### @@ -1371,7 +1280,7 @@ write_formula <- function( #' style <- paste0("TableStyleLight", i) #' write_datatable(wb, #' x = data.frame(style), sheet = 1, -#' tableStyle = style, startRow = 1, startCol = i * 3 - 2 +#' table_style = style, start_row = 1, start_col = i * 3 - 2 #' ) #' } #' @@ -1379,7 +1288,7 @@ write_formula <- function( #' style <- paste0("TableStyleMedium", i) #' write_datatable(wb, #' x = data.frame(style), sheet = 1, -#' tableStyle = style, startRow = 4, startCol = i * 3 - 2 +#' table_style = style, start_row = 4, start_col = i * 3 - 2 #' ) #' } #' @@ -1387,7 +1296,7 @@ write_formula <- function( #' style <- paste0("TableStyleDark", i) #' write_datatable(wb, #' x = data.frame(style), sheet = 1, -#' tableStyle = style, startRow = 7, startCol = i * 3 - 2 +#' table_style = style, start_row = 7, start_col = i * 3 - 2 #' ) #' } #' @export diff --git a/R/xl_open.R b/R/xl_open.R index 5fd516d8d..2be464e9c 100644 --- a/R/xl_open.R +++ b/R/xl_open.R @@ -1,15 +1,15 @@ -#' Open a Microsoft Excel file (xls/xlsx) or an openxlsx2 wbWorkbook +#' Open an xlsx file or a `wbWorkbook` object #' #' @description #' This function tries to open a Microsoft Excel (xls/xlsx) file or, -#' an openxlsx2 wbWorkbook with the proper application, in a portable manner. +#' an [openxlsx2::wbWorkbook] with the proper application, in a portable manner. #' #' On Windows it uses `base::shell.exec()` (Windows only function) to #' determine the appropriate program. #' -#' In Mac (c) it uses system default handlers, given the file type. +#' On Mac, (c) it uses system default handlers, given the file type. #' -#' In Linux it searches (via `which`) for available xls/xlsx reader +#' On Linux, it searches (via `which`) for available xls/xlsx reader #' applications (unless `options('openxlsx2.excelApp')` is set to the app bin #' path), and if it finds anything, sets `options('openxlsx2.excelApp')` to the #' program chosen by the user via a menu (if many are present, otherwise it @@ -17,26 +17,27 @@ #' Libreoffice/Openoffice (`soffice` bin), Gnumeric (`gnumeric`) and Calligra #' Sheets (`calligrasheets`). #' -#' @param x A path to the Excel (xls/xlsx) file or Workbook object. +#' @param x A path to the Excel (xls/xlsx) file or wbWorkbook object. #' @param interactive If `FALSE` will throw a warning and not open the path. #' This can be manually set to `TRUE`, otherwise when `NA` (default) uses the #' value returned from [base::interactive()] #' @examples #' \donttest{ #' if (interactive()) { -#' xlsxFile <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2") -#' xl_open(xlsxFile) +#' xlsx_file <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2") +#' xl_open(xlsx_file) #' #' # (not yet saved) Workbook example #' wb <- wb_workbook() #' x <- mtcars[1:6, ] #' wb$add_worksheet("Cars") -#' wb$add_data("Cars", x, startCol = 2, startRow = 3, rowNames = TRUE) +#' wb$add_data("Cars", x, start_col = 2, start_row = 3, row_names = TRUE) #' xl_open(wb) #' } #' } #' @export xl_open <- function(x, interactive = NA) { + # one of the only functions like wb_get_named_regions() to accept a wbWorkbook or a file UseMethod("xl_open") } @@ -60,7 +61,7 @@ xl_open.default <- function(x, interactive = NA) { # nocov end if (!isTRUE(interactive)) { - warning("will not open file when not interactive") + warning("will not open file when not interactive", call. = FALSE) return() } diff --git a/_pkgdown.yml b/_pkgdown.yml index fe664006c..1fb5579ed 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -13,45 +13,112 @@ reference: contents: - wb_to_df - write_xlsx - - wbWorkbook - wb_workbook - wb_load + - wbWorkbook + - wb_open - wb_save -- title: wb add and remove functions +- title: Main functions to interact with the contents of a Workbook object +- subtitle: Add content to a worksheet + desc: > + These functions help you write in worksheets. They invisibly return the + `wbWorkbook` object, except for `get_` functions, who return a character vector, + unless specified otherwise. + contents: + - wb_add_worksheet + - wb_add_data + - wb_add_data_table + - wb_col_widths + - wb_row_heights + - wb_add_comment + - wb_add_thread + - wb_filter + - wb_freeze_pane + - wb_add_formula + - wb_add_conditional_formatting + - wb_add_pivot_table + - wb_add_data_validation + - wb_add_page_break + +- subtitle: Add styling to a cell region in a worksheet + desc: > + These functions are related to styling of a region or cells of a worksheet. contents: - - starts_with("wb_add_") - - starts_with("wb_remove_") + - has_concept("styles") -- title: wb get and set functions +- subtitle: Add styling to the workbook + desc: > + These styling functions apply formatting to the workbook globally. contents: - - starts_with("wb_get_") - - starts_with("wb_set_") + - has_concept("workbook styling functions") -- title: wb Misc +- subtitle: Interact with the workbook + desc: > + These functions are used to modify the workbook as a whole. + contents: + - wb_set_last_modified_by + - wb_creators + - wb_order + - wb_sheet_names + - wb_remove_worksheet + - wb_active_sheet + - wb_sheet_visibility + - wb_set_bookview + - wb_protect + - wb_get_tables + - wb_remove_tables + - wb_get_named_regions + +- subtitle: Add content to a chartsheet Interact with mschart and images + desc: > + These functions help you interact with chartsheets. They invisibly return the + wbWorkbook object. They help interact with the mschart package. + contents: + - wbChartSheet + - wb_data + - wb_add_chartsheet + - wb_add_mschart + - wb_add_drawing + - wb_add_plot + - wb_add_image + - wb_add_sparklines + - wb_add_chart_xml + +- title: Helpers to specify wb function arguments + desc: > + These functions are helpers to create an intermediate R6 class object to use + with `wb_*` functions. contents: - wb_dims - - starts_with("wb_protect") + - wb_color - wb_hyperlink - - cleanup - - wb_freeze_pane - - wb_open + - starts_with("create_") + + +- title: Other functions + desc: > + These functions can be used to achieve more specialized operations. + +- subtitle: Other tools to interact with worksheets + contents: - starts_with("wb_clone") - starts_with("wb_copy") - - wb_color - - wb_data - - wb_grid_lines - - wb_update_table - - wb_copy_cells + - wb_set_sheetview - wb_merge_cells - - wb_page_setup - wb_grouping + - wb_add_form_control + - wb_add_ignore_error + - wb_set_header_footer + - wb_set_grid_lines + - wb_update_table + - wb_named_region + - wb_protect_worksheet + - wb_clean_sheet + - wb_add_form_control + - wb_page_setup -- title: create functions - contents: - - starts_with("create_") - -- title: XML functions +- subtitle: XML functions desc: > A curated list of XML functions used in openxlsx2. contents: @@ -60,26 +127,21 @@ reference: - as_xml - starts_with("print.pugi") -- title: R6 Classes - contents: - - wbWorkbook - - wbChartSheet - -- title: Misc and helpers +- subtitle: Misc and helpers contents: - openxlsx2_options - int2col - col2int - fmt_txt - starts_with("convert_") + - xl_open - temp_xlsx - - clean_worksheet_name - - styles_on_sheet - waivers - - xl_open - dims_helper + - clean_worksheet_name + - styles_on_sheet -- title: Deprecated +- subtitle: Deprecated contents: - openxlsx2-deprecated diff --git a/man/comment.Rd b/man/create_comment.Rd similarity index 57% rename from man/comment.Rd rename to man/create_comment.Rd index 4b264a9c8..53749ddb1 100644 --- a/man/comment.Rd +++ b/man/create_comment.Rd @@ -1,10 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/class-comment.R, R/class-workbook-wrappers.R +% Please edit documentation in R/class-comment.R \name{create_comment} \alias{create_comment} -\alias{wb_add_comment} -\alias{wb_remove_comment} -\title{Create, write and remove comments} +\title{Create a comment} \usage{ create_comment( text, @@ -14,10 +12,6 @@ create_comment( width = 2, height = 4 ) - -wb_add_comment(wb, sheet = current_sheet(), dims = "A1", comment, ...) - -wb_remove_comment(wb, sheet = current_sheet(), dims = "A1", ...) } \arguments{ \item{text}{Comment text. Character vector.} @@ -31,26 +25,12 @@ wb_remove_comment(wb, sheet = current_sheet(), dims = "A1", ...) \item{width}{Textbox integer width in number of cells} \item{height}{Textbox integer height in number of cells} - -\item{wb}{A workbook object} - -\item{sheet}{A worksheet of the workbook} - -\item{dims}{Optional row and column as spreadsheet dimension, e.g. "A1"} - -\item{comment}{A comment to apply to the worksheet} - -\item{...}{additional arguments} } \value{ -The \code{wbWorkbook} object +a \code{wbComment} object } \description{ -The comment functions (create, write and remove) allow the -modification of comments. In newer spreadsheet software they are called -notes, while they are called comments in openxml. Modification of what -newer spreadsheet software now calls comment is possible via -\code{\link[=wb_add_thread]{wb_add_thread()}}. +Creates a \code{wbComment} object. Use with \code{\link[=wb_add_comment]{wb_add_comment()}} to add to a worksheet location. } \examples{ wb <- wb_workbook() @@ -70,10 +50,7 @@ s2 <- create_font(color = wb_color(hex = "FF000000"), sz = "9") c3 <- create_comment(text = c("This Part Bold red\n\n", "This part black"), style = c(s1, s2)) wb$add_comment(sheet = 1, dims = wb_dims(3, 6), comment = c3) - -# remove the first comment c1 -wb$remove_comment(1, dims = "B10") } \seealso{ -\code{\link[=wb_add_thread]{wb_add_thread()}} +\code{\link[=wb_add_comment]{wb_add_comment()}} } diff --git a/man/create_sparklines.Rd b/man/create_sparklines.Rd index b8c756df1..31bfc215b 100644 --- a/man/create_sparklines.Rd +++ b/man/create_sparklines.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/helper-functions.R \name{create_sparklines} \alias{create_sparklines} -\title{create sparklines used in \code{add_sparline()}} +\title{Create sparklines object} \usage{ create_sparklines( sheet = current_sheet(), @@ -29,9 +29,9 @@ create_sparklines( \arguments{ \item{sheet}{sheet} -\item{dims}{dims} +\item{dims}{Cell range of cells used to create the sparklines} -\item{sqref}{sqref} +\item{sqref}{Cell range of the destination of the sparklines.} \item{type}{type} @@ -65,11 +65,14 @@ create_sparklines( \item{colorLow}{colorLow} } +\value{ +A string containing XML code +} \description{ -create sparklines used in \code{add_sparline()} +Create a sparkline to be added a workbook with \code{\link[=wb_add_sparklines]{wb_add_sparklines()}} } \details{ -the colors are all predefined to be rgb. Maybe theme colors can be +Colors are all predefined to be rgb. Maybe theme colors can be used too. } \examples{ diff --git a/man/delete_data.Rd b/man/delete_data.Rd new file mode 100644 index 000000000..694280b08 --- /dev/null +++ b/man/delete_data.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/wb_functions.R +\name{delete_data} +\alias{delete_data} +\title{Delete data} +\usage{ +delete_data(wb, sheet, cols, rows) +} +\arguments{ +\item{wb}{workbook} + +\item{sheet}{sheet to clean} + +\item{cols}{numeric column vector} + +\item{rows}{numeric row vector} +} +\description{ +This function is deprecated. Use \code{\link[=wb_clean_sheet]{wb_clean_sheet()}}. +} +\keyword{internal} diff --git a/man/dims_helper.Rd b/man/dims_helper.Rd index 38b16e8c7..6a73c3ca3 100644 --- a/man/dims_helper.Rd +++ b/man/dims_helper.Rd @@ -31,5 +31,9 @@ vector. Exported for user convenience. } \examples{ dims_to_rowcol("A1:J10") -rowcol_to_dims(1:10, 1:10) +wb_dims(1:10, 1:10) + +} +\seealso{ +\code{\link[=wb_dims]{wb_dims()}} } diff --git a/man/named_region.Rd b/man/named_region.Rd deleted file mode 100644 index 9d0dbe343..000000000 --- a/man/named_region.Rd +++ /dev/null @@ -1,118 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/class-workbook-wrappers.R -\name{named_region} -\alias{named_region} -\alias{wb_add_named_region} -\alias{wb_remove_named_region} -\title{Create / delete a named region} -\usage{ -wb_add_named_region( - wb, - sheet = current_sheet(), - dims = "A1", - name, - local_sheet = FALSE, - overwrite = FALSE, - comment = NULL, - custom_menu = NULL, - description = NULL, - is_function = NULL, - function_group_id = NULL, - help = NULL, - hidden = NULL, - local_name = NULL, - publish_to_server = NULL, - status_bar = NULL, - vb_procedure = NULL, - workbook_parameter = NULL, - xml = NULL, - ... -) - -wb_remove_named_region(wb, sheet = current_sheet(), name = NULL) -} -\arguments{ -\item{wb}{A workbook object} - -\item{sheet}{A name or index of a worksheet} - -\item{dims}{Worksheet dimension, single cell ("A1") or cell range ("A1:D4")} - -\item{name}{Name for region. A character vector of length 1. Note region names musts be case-insensitive unique.} - -\item{local_sheet}{If \code{TRUE} the named region will be local for this sheet} - -\item{overwrite}{Boolean. Overwrite if exists? Default to FALSE} - -\item{comment}{description text for named region} - -\item{custom_menu}{customMenu (unknown xml feature)} - -\item{description}{description (unknown xml feature)} - -\item{is_function}{function (unknown xml feature)} - -\item{function_group_id}{function group id (unknown xml feature)} - -\item{help}{help (unknown xml feature)} - -\item{hidden}{hidden if the named region should be hidden} - -\item{local_name}{localName (unknown xml feature)} - -\item{publish_to_server}{publish to server (unknown xml feature)} - -\item{status_bar}{status bar (unknown xml feature)} - -\item{vb_procedure}{wbProcedure (unknown xml feature)} - -\item{workbook_parameter}{workbookParameter (unknown xml feature)} - -\item{xml}{xml (unknown xml feature)} - -\item{...}{additional arguments} -} -\description{ -Create / delete a named region -} -\details{ -Region is given by: min(cols):max(cols) X min(rows):max(rows) -} -\examples{ -## create named regions -wb <- wb_workbook() -wb$add_worksheet("Sheet 1") - -## specify region -wb$add_data(sheet = 1, x = iris, startCol = 1, startRow = 1) -wb$add_named_region( - sheet = 1, - name = "iris", - dims = wb_dims( - rows = seq_len(nrow(iris) + 1), - cols = seq_along(iris) - ) -) - - -## using write_data 'name' argument -wb$add_data(sheet = 1, x = iris, name = "iris2", startCol = 10) - -out_file <- temp_xlsx() -wb_save(wb, out_file, overwrite = TRUE) - -## see named regions -wb_get_named_regions(wb) ## From Workbook object -wb_get_named_regions(out_file) ## From xlsx file - -## delete one -wb$remove_named_region(name = "iris2") -wb_get_named_regions(wb) - -## read named regions -df <- read_xlsx(wb, namedRegion = "iris") -head(df) - -df <- read_xlsx(out_file, namedRegion = "iris2") -head(df) -} diff --git a/man/select_active_sheet.Rd b/man/select_active_sheet.Rd deleted file mode 100644 index 3c00fe6f9..000000000 --- a/man/select_active_sheet.Rd +++ /dev/null @@ -1,42 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/class-workbook-wrappers.R -\name{select_active_sheet} -\alias{select_active_sheet} -\alias{wb_get_active_sheet} -\alias{wb_set_active_sheet} -\alias{wb_get_selected} -\alias{wb_set_selected} -\title{get and set table of sheets and their state as selected and active} -\usage{ -wb_get_active_sheet(wb) - -wb_set_active_sheet(wb, sheet) - -wb_get_selected(wb) - -wb_set_selected(wb, sheet) -} -\arguments{ -\item{wb}{a workbook} - -\item{sheet}{a sheet name of the workbook} -} -\value{ -a data frame with tabSelected and names -} -\description{ -Multiple sheets can be selected, but only a single one can be -active (visible). The visible sheet, must not necessarily be a selected -sheet. -} -\examples{ - wb <- wb_load(file = system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2")) - # testing is the selected sheet - wb_get_selected(wb) - # change the selected sheet to Sheet2 - wb <- wb_set_selected(wb, "Sheet2") - # get the active sheet - wb_get_active_sheet(wb) - # change the selected sheet to Sheet2 - wb <- wb_set_active_sheet(wb, sheet = "Sheet2") -} diff --git a/man/wbWorkbook.Rd b/man/wbWorkbook.Rd index 64e685258..ab87929ef 100644 --- a/man/wbWorkbook.Rd +++ b/man/wbWorkbook.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook.R \name{wbWorkbook} \alias{wbWorkbook} -\title{R6 class for a Workbook} +\title{R6 class for a workbook} \description{ A workbook } @@ -114,7 +114,7 @@ create_border \item{\code{media}}{media} -\item{\code{metadata}}{metadata} +\item{\code{metadata}}{contains cell/value metadata imported on load from xl/metadata.xml} \item{\code{persons}}{persons} @@ -1952,7 +1952,7 @@ add form control to workbook \if{html}{\out{
}}\preformatted{wbWorkbook$add_form_control( sheet = current_sheet(), dims = "A1", - type = NULL, + type = c("Checkbox", "Radio", "Drop"), text = NULL, link = NULL, range = NULL, @@ -2416,12 +2416,12 @@ add a named region local_sheet = FALSE, overwrite = FALSE, comment = NULL, + hidden = NULL, custom_menu = NULL, description = NULL, is_function = NULL, function_group_id = NULL, help = NULL, - hidden = NULL, local_name = NULL, publish_to_server = NULL, status_bar = NULL, @@ -2447,6 +2447,8 @@ add a named region \item{\code{comment}}{comment} +\item{\code{hidden}}{hidden} + \item{\code{custom_menu}}{custom_menu} \item{\code{description}}{description} @@ -2457,8 +2459,6 @@ add a named region \item{\code{help}}{help} -\item{\code{hidden}}{hidden} - \item{\code{local_name}}{localName} \item{\code{publish_to_server}}{publish to server} diff --git a/man/wb_active_sheet.Rd b/man/wb_active_sheet.Rd new file mode 100644 index 000000000..f5de33198 --- /dev/null +++ b/man/wb_active_sheet.Rd @@ -0,0 +1,43 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class-workbook-wrappers.R +\name{wb_active_sheet} +\alias{wb_active_sheet} +\alias{wb_get_active_sheet} +\alias{wb_set_active_sheet} +\alias{wb_get_selected} +\alias{wb_set_selected} +\title{Modify the state of active and selected sheets in a workbook} +\usage{ +wb_get_active_sheet(wb) + +wb_set_active_sheet(wb, sheet) + +wb_get_selected(wb) + +wb_set_selected(wb, sheet) +} +\arguments{ +\item{wb}{a workbook} + +\item{sheet}{a sheet name of the workbook} +} +\value{ +a data frame with tabSelected and names +} +\description{ +Get and set table of sheets and their state as selected and active in a workbook + +Multiple sheets can be selected, but only a single one can be active (visible). +The visible sheet, must not necessarily be a selected sheet. +} +\examples{ +wb <- wb_load(file = system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2")) +# testing is the selected sheet +wb_get_selected(wb) +# change the selected sheet to Sheet2 +wb <- wb_set_selected(wb, "Sheet2") +# get the active sheet +wb_get_active_sheet(wb) +# change the selected sheet to Sheet2 +wb <- wb_set_active_sheet(wb, sheet = "Sheet2") +} diff --git a/man/wb_add_border.Rd b/man/wb_add_border.Rd index 131799335..1cd9f6425 100644 --- a/man/wb_add_border.Rd +++ b/man/wb_add_border.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_border} \alias{wb_add_border} -\title{add border for cell region} +\title{Modify borders in a cell region} \usage{ wb_add_border( wb, @@ -24,20 +24,21 @@ wb_add_border( ) } \arguments{ -\item{wb}{workbook} +\item{wb}{A \code{wbWorkbook}} -\item{sheet}{a worksheet} +\item{sheet}{A worksheet} -\item{dims}{dimensions on the worksheet e.g. "A1", "A1:A5", "A1:H5"} +\item{dims}{Cell range in the worksheet e.g. "A1", "A1:A5", "A1:H5"} \item{bottom_color, left_color, right_color, top_color, inner_hcolor, inner_vcolor}{a color, either something openxml knows or some RGB color} -\item{left_border, right_border, top_border, bottom_border, inner_hgrid, inner_vgrid}{the border style, if NULL no border is drawn. See create_border for possible border styles} +\item{left_border, right_border, top_border, bottom_border, inner_hgrid, inner_vgrid}{the border style, if \code{NULL} no border is drawn. +See \code{\link[=create_border]{create_border()}} for possible border styles} -\item{...}{...} +\item{...}{additional arguments} } \description{ -wb wrapper to create borders for cell region +wb wrapper to create borders for cell regions. } \examples{ wb <- wb_workbook() \%>\% wb_add_worksheet("S1") \%>\% wb_add_data("S1", mtcars) @@ -49,6 +50,7 @@ wb <- wb_add_border(wb, 1, dims = "A5", top_border = "hair", bottom_border = "thick") wb <- wb_add_border(wb, 1, dims = "C2:C5") wb <- wb_add_border(wb, 1, dims = "G2:H3") + wb <- wb_add_border(wb, 1, dims = "G12:H13", left_color = wb_color(hex = "FF9400D3"), right_color = wb_color(hex = "FF4B0082"), top_color = wb_color(hex = "FF0000FF"), bottom_color = wb_color(hex = "FF00FF00")) @@ -65,7 +67,8 @@ Other styles: \code{\link{wb_add_cell_style}()}, \code{\link{wb_add_fill}()}, \code{\link{wb_add_font}()}, +\code{\link{wb_add_named_style}()}, \code{\link{wb_add_numfmt}()}, -\code{\link{wb_clone_sheet_style}()} +\code{\link{wb_cell_style}} } \concept{styles} diff --git a/man/wb_add_cell_style.Rd b/man/wb_add_cell_style.Rd index 4e7f74c4b..01bce8a55 100644 --- a/man/wb_add_cell_style.Rd +++ b/man/wb_add_cell_style.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_cell_style} \alias{wb_add_cell_style} -\title{add cell style for cell region} +\title{Modify the style in a cell region} \usage{ wb_add_cell_style( wb, @@ -96,25 +96,25 @@ wb_add_cell_style( \item{...}{additional arguments} } \value{ -The \code{wbWorksheetObject}, invisibly +The \code{wbWorkbook} object, invisibly } \description{ -add cell style for cell region +Add cell style to a cell region } \examples{ wb <- wb_workbook() \%>\% wb_add_worksheet("S1") \%>\% - wb_add_data("S1", mtcars) + wb_add_data("S1", x = mtcars) wb \%>\% wb_add_cell_style( "S1", - "A1:K1", - textRotation = "45", + dims = "A1:K1", + text_rotation = "45", horizontal = "center", vertical = "center", - wrapText = "1" + wrap_text = "1" ) } \seealso{ @@ -122,7 +122,8 @@ Other styles: \code{\link{wb_add_border}()}, \code{\link{wb_add_fill}()}, \code{\link{wb_add_font}()}, +\code{\link{wb_add_named_style}()}, \code{\link{wb_add_numfmt}()}, -\code{\link{wb_clone_sheet_style}()} +\code{\link{wb_cell_style}} } \concept{styles} diff --git a/man/wb_add_chart_xml.Rd b/man/wb_add_chart_xml.Rd index 51e66432c..66fd127df 100644 --- a/man/wb_add_chart_xml.Rd +++ b/man/wb_add_chart_xml.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_chart_xml} \alias{wb_add_chart_xml} -\title{add a chart xml to a workbook} +\title{Add a chart XML to a worksheet} \usage{ wb_add_chart_xml( wb, @@ -28,7 +28,7 @@ wb_add_chart_xml( \item{...}{additional arguments} } \description{ -add a chart xml to a workbook +Add a chart XML to a worksheet } \seealso{ \code{\link[=wb_add_drawing]{wb_add_drawing()}} \code{\link[=wb_add_image]{wb_add_image()}} \code{\link[=wb_add_mschart]{wb_add_mschart()}} \code{\link[=wb_add_plot]{wb_add_plot()}} diff --git a/man/wb_add_chartsheet.Rd b/man/wb_add_chartsheet.Rd index 60389e568..e5c823c4a 100644 --- a/man/wb_add_chartsheet.Rd +++ b/man/wb_add_chartsheet.Rd @@ -14,17 +14,17 @@ wb_add_chartsheet( ) } \arguments{ -\item{wb}{A Workbook object to attach the new worksheet} +\item{wb}{A Workbook object to attach the new chartsheet} -\item{sheet}{A name for the new worksheet} +\item{sheet}{A name for the new chartsheet} -\item{tab_color}{Color of the worksheet tab. A valid color (belonging to -colors()) or a valid hex color beginning with "#"} +\item{tab_color}{Color of the chartsheet tab. A valid color (belonging to +\code{colors()}) or a valid hex color beginning with "#"} \item{zoom}{A numeric between 10 and 400. Worksheet zoom level as a percentage.} -\item{visible}{If FALSE, sheet is hidden else visible.} +\item{visible}{If \code{FALSE}, sheet is hidden else visible.} \item{...}{...} } @@ -36,7 +36,7 @@ After chartsheet creation a chart must be added to the sheet. Otherwise the chartsheet will break the workbook. } \seealso{ -\code{\link[=wb_add_mschart]{wb_add_mschart()}} +\code{\link[=wb_add_mschart]{wb_add_mschart()}} \link{wbChartSheet} Other workbook wrappers: \code{\link{wb_add_data_table}()}, @@ -52,9 +52,9 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_add_comment.Rd b/man/wb_add_comment.Rd new file mode 100644 index 000000000..d3bad2814 --- /dev/null +++ b/man/wb_add_comment.Rd @@ -0,0 +1,49 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class-workbook-wrappers.R +\name{wb_add_comment} +\alias{wb_add_comment} +\alias{wb_remove_comment} +\title{Add / remove comment in a worksheet} +\usage{ +wb_add_comment(wb, sheet = current_sheet(), dims = "A1", comment, ...) + +wb_remove_comment(wb, sheet = current_sheet(), dims = "A1", ...) +} +\arguments{ +\item{wb}{A Workbook object} + +\item{sheet}{A worksheet of the workbook} + +\item{dims}{Row and column as spreadsheet dimension, e.g. "A1"} + +\item{comment}{A comment to apply to the worksheet} + +\item{...}{additional arguments} +} +\value{ +The Workbook object, invisibly. +} +\description{ +The comment functions (add and remove) allow the modification of comments. +In more recent spreadsheet software they are called notes, while they are called +comments in openxml. Modification of what newer spreadsheet software now calls +comment is possible via \code{\link[=wb_add_thread]{wb_add_thread()}}. + +\code{comment} can be created with \code{\link[=create_comment]{create_comment()}} to add styling. +} +\examples{ +wb <- wb_workbook() +wb$add_worksheet("Sheet 1") +# add a comment without author +c1 <- create_comment(text = "this is a comment", author = "") +wb$add_comment(dims = "B10", comment = c1) +#' # Remove comment +wb$remove_comment(sheet = "Sheet 1", dims = "B10") +# Write another comment with author information +c2 <- create_comment(text = "this is another comment", author = "Marco Polo") +wb$add_comment(sheet = 1, dims = "C10", comment = c2) +} +\seealso{ +\code{\link[=create_comment]{create_comment()}}, \code{\link[=wb_add_thread]{wb_add_thread()}} +} +\keyword{comments} diff --git a/man/wb_add_conditional_formatting.Rd b/man/wb_add_conditional_formatting.Rd index 0580b0fa6..58d53b6e4 100644 --- a/man/wb_add_conditional_formatting.Rd +++ b/man/wb_add_conditional_formatting.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_conditional_formatting} \alias{wb_add_conditional_formatting} -\title{Add conditional formatting to cells} +\title{Add conditional formatting to cells in a worksheet} \usage{ wb_add_conditional_formatting( wb, @@ -20,72 +20,73 @@ wb_add_conditional_formatting( ) } \arguments{ -\item{wb}{A workbook object} +\item{wb}{A Workbook object} \item{sheet}{A name or index of a worksheet} \item{dims}{A cell or cell range like "A1" or "A1:B2"} -\item{rule}{The condition under which to apply the formatting. See examples.} +\item{rule}{The condition under which to apply the formatting. See \strong{Examples}.} -\item{style}{A style to apply to those cells that satisfy the rule. Default is 'font_color = "FF9C0006"' and 'bgFill = "FFFFC7CE"'} +\item{style}{A style to apply to those cells that satisfy the rule. +Default is \code{font_color = "FF9C0006"} and \code{bg_fill = "FFFFC7CE"}} -\item{type}{The type of conditional formatting rule to apply.} +\item{type}{The type of conditional formatting rule to apply. One of \code{"expression"}, \code{"colorScale"} or others mentioned in \strong{Details}.} -\item{params}{Additional parameters passed. See \strong{Details} for more} +\item{params}{A list of additional parameters passed. See \strong{Details} for more.} \item{...}{additional arguments} } \description{ -Add conditional formatting to cells +Add conditional formatting to cells. +You can find more details in \code{vignette("conditional-formatting")}. } \details{ -See Examples. +openxml uses the alpha channel first then RGB, whereas the usual default is RGBA. -Conditional formatting types accept different parameters. Unless noted, +Conditional formatting \code{type} accept different parameters. Unless noted, unlisted parameters are ignored. - \describe{ \item{\code{expression}}{ \verb{[style]}\cr A \code{Style} object\cr\cr \verb{[rule]}\cr An Excel expression (as a character). Valid operators are: \code{<}, \code{<=}, \code{>}, \code{>=}, \code{==}, \code{!=} } -\item{colorScale}{ +\item{\code{colorScale}}{ \verb{[style]}\cr A \code{character} vector of valid colors with length \code{2} or \code{3}\cr\cr \verb{[rule]}\cr \code{NULL} or a \code{character} vector of valid colors of equal length to \code{styles} } -\item{dataBar}{ +\item{\code{dataBar}}{ \verb{[style]}\cr A \code{character} vector of valid colors with length \code{2} or \code{3}\cr\cr \verb{[rule]}\cr A \code{numeric} vector specifying the range of the databar colors. Must be equal length to \code{style}\cr\cr \verb{[params$showValue]}\cr If \code{FALSE} the cell value is hidden. Default \code{TRUE}\cr\cr \verb{[params$gradient]}\cr If \code{FALSE} color gradient is removed. Default \code{TRUE}\cr\cr \verb{[params$border]}\cr If \code{FALSE} the border around the database is hidden. Default \code{TRUE} } -\item{duplicatedValues/uniqueValues/containsErrors}{ +\item{\code{duplicatedValues} / \code{uniqueValues} / \code{containsErrors}}{ \verb{[style]}\cr A \code{Style} object } -\item{contains}{ +\item{\code{contains}}{ \verb{[style]}\cr A \code{Style} object\cr\cr \verb{[rule]}\cr The text to look for within cells } -\item{between}{ -\verb{[style]}\cr A Style object.\cr\cr +\item{\code{between}}{ +\verb{[style]}\cr A \code{Style} object.\cr\cr \verb{[rule]}\cr A \code{numeric} vector of length \code{2} specifying lower and upper bound (Inclusive) } -\item{topN}{ +\item{\code{topN}}{ \verb{[style]}\cr A \code{Style} object\cr\cr \verb{[params$rank]}\cr A \code{numeric} vector of length \code{1} indicating number of highest values. Default \code{5L}\cr\cr -\verb{[params$percent]} If \code{TRUE} uses percentage +\verb{[params$percent]} If \code{TRUE}, uses percentage } -\item{bottomN}{ +\item{\code{bottomN}}{ \verb{[style]}\cr A \code{Style} object\cr\cr \verb{[params$rank]}\cr A \code{numeric} vector of length \code{1} indicating number of lowest values. Default \code{5L}\cr\cr -\verb{[params$percent]}\cr If \code{TRUE} uses percentage +\verb{[params$percent]}\cr If \code{TRUE}, uses percentage } -\item{iconSet}{ -\verb{[params$showValue]}\cr If \code{FALSE} the cell value is hidden. Default \code{TRUE}\cr\cr -\verb{[params$reverse]}\cr If \code{TRUE} the order is reversed. Default \code{FALSE}\cr\cr -\verb{[params$percent]}\cr If \code{TRUE} uses percentage\cr\cr +\item{\code{iconSet}}{ +\verb{[params$showValue]}\cr If \code{FALSE}, the cell value is hidden. Default \code{TRUE}\cr\cr +\verb{[params$reverse]}\cr If \code{TRUE}, the order is reversed. Default \code{FALSE}\cr\cr +\verb{[params$percent]}\cr If \code{TRUE}, uses percentage\cr\cr \verb{[params$iconSet]}\cr Uses one of the implemented icon sets. Values must match the length of the icons in the set 3Arrows, 3ArrowsGray, 3Flags, 3Signs, 3Symbols, 3Symbols2, 3TrafficLights1, 3TrafficLights2, 4Arrows, 4ArrowsGray, 4Rating, 4RedToBlack, 4TrafficLights, 5Arrows, 5ArrowsGray, 5Quarters, 5Rating. The @@ -96,6 +97,6 @@ default is 3TrafficLights1. \examples{ wb <- wb_workbook() wb$add_worksheet("a") -wb$add_data("a", 1:4, colNames = FALSE) -wb$add_conditional_formatting("a", cols = 1, rows = 1:4, rule = ">2") +wb$add_data(x = 1:4, col_names = FALSE) +wb$add_conditional_formatting(dims = wb_dims(cols = "A", rows = 1:4), rule = ">2") } diff --git a/man/wb_add_data.Rd b/man/wb_add_data.Rd index 3cfd6002a..03c38525b 100644 --- a/man/wb_add_data.Rd +++ b/man/wb_add_data.Rd @@ -31,46 +31,51 @@ wb_add_data( \item{x}{Object to be written. For classes supported look at the examples.} -\item{dims}{Spreadsheet dimensions that will determine \code{start_col} and \code{start_row}: "A1", "A1:B2", "A:B"} +\item{dims}{Spreadsheet cell range that will determine \code{start_col} and \code{start_row}: "A1", "A1:B2", "A:B"} -\item{start_col}{A vector specifying the starting column to write to.} +\item{start_col}{A vector specifying the starting column to write \code{x} to.} -\item{start_row}{A vector specifying the starting row to write to.} +\item{start_row}{A vector specifying the starting row to write \code{x} to.} \item{array}{A bool if the function written is of type array} \item{col_names}{If \code{TRUE}, column names of \code{x} are written.} -\item{row_names}{If \code{TRUE}, data.frame row names of \code{x} are written.} +\item{row_names}{If \code{TRUE}, the row names of \code{x} are written.} -\item{with_filter}{If \code{TRUE}, add filters to the column name row. NOTE can only have one filter per worksheet.} +\item{with_filter}{If \code{TRUE}, add filters to the column name row. +NOTE: can only have one filter per worksheet.} -\item{name}{If not NULL, a named region is defined.} +\item{name}{The name of a named region if specified.} -\item{sep}{Only applies to list columns. The separator used to collapse list columns to a character vector e.g. sapply(x$list_column, paste, collapse = sep).} +\item{sep}{Only applies to list columns. The separator used to collapse list +columns to a character vector e.g. \code{sapply(x$list_column, paste, collapse = sep)}.} \item{apply_cell_style}{Should we write cell styles to the workbook} \item{remove_cell_style}{keep the cell style?} \item{na.strings}{Value used for replacing \code{NA} values from \code{x}. Default -\code{na_strings()} uses the special \verb{#N/A} value within the workbook.} +\code{\link[=na_strings]{na_strings()}} uses the special \verb{#N/A} value within the workbook.} \item{inline_strings}{write characters as inline strings} \item{...}{additional arguments} } \value{ -A clone of \code{wb} +A \code{wbWorkbook}, invisibly. } \description{ Add data to worksheet with optional styling. } \details{ -Formulae written using write_formula to a Workbook object will not get picked up by read_xlsx(). -This is because only the formula is written and left to Excel to evaluate the formula when the file is opened in Excel. -The string \code{"_openxlsx_NA"} is reserved for \code{openxlsx2}. If the data frame contains this string, the output will be broken. -Many base classes are covered, though not all and far from all third-party classes. When data of an unknown class is written, it is handled with \code{as.character()}. +Formulae written using \code{\link[=wb_add_formula]{wb_add_formula()}} to a Workbook object will +not get picked up by \code{read_xlsx()}. This is because only the formula is written +and left to Excel to evaluate the formula when the file is opened in Excel. +The string \code{"_openxlsx_NA"} is reserved for \code{openxlsx2}. +If the data frame contains this string, the output will be broken. +Many base classes are covered, though not all and far from all third-party classes. +When data of an unknown class is written, it is handled with \code{as.character()}. } \examples{ ## See formatting vignette for further examples. @@ -98,7 +103,7 @@ wb$add_data("Cars", x, start_col = 2, start_row = 3, row_names = TRUE) v <- rep("https://CRAN.R-project.org/", 4) names(v) <- paste0("Hyperlink", 1:4) # Optional: names will be used as display text class(v) <- "hyperlink" -wb$add_data("Cars", x = v, dims = c("B32")) +wb$add_data("Cars", x = v, dims = "B32") ############################################################################# ## Formulas @@ -139,9 +144,9 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_add_data_table.Rd b/man/wb_add_data_table.Rd index efb0d0143..ffd624008 100644 --- a/man/wb_add_data_table.Rd +++ b/man/wb_add_data_table.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_data_table} \alias{wb_add_data_table} -\title{Add data to a worksheet as an Excel table} +\title{Add a data table to a worksheet} \usage{ wb_add_data_table( wb, @@ -29,65 +29,66 @@ wb_add_data_table( ) } \arguments{ -\item{wb}{A Workbook object containing a #' worksheet.} +\item{wb}{A Workbook object containing a worksheet.} \item{sheet}{The worksheet to write to. Can be the worksheet index or name.} -\item{x}{A dataframe.} +\item{x}{A data frame} -\item{dims}{Spreadsheet dimensions that will determine \code{start_col} and \code{start_row}: "A1", "A1:B2", "A:B"} +\item{dims}{Spreadsheet cell range that will determine \code{start_col} and \code{start_row}: "A1", "A1:B2", "A:B"} -\item{start_col}{A vector specifying the starting column to write df} +\item{start_col}{A vector specifying the starting column to write \code{x} to.} -\item{start_row}{A vector specifying the starting row to write df} +\item{start_row}{A vector specifying the starting row to write \code{x} to.} \item{col_names}{If \code{TRUE}, column names of \code{x} are written.} -\item{row_names}{If \code{TRUE}, row names of \code{x} are written.} +\item{row_names}{If \code{TRUE}, the row names of \code{x} are written.} -\item{table_style}{Any excel table style name or "none" (see "formatting" -vignette).} +\item{table_style}{Any table style name or "none" (see \code{vignette("openxlsx2_style_manual")})} -\item{table_name}{name of table in workbook. The table name must be unique.} +\item{table_name}{Name of table in workbook. The table name must be unique.} \item{with_filter}{If \code{TRUE}, columns with have filters in the first row.} \item{sep}{Only applies to list columns. The separator used to collapse list -columns to a character vector e.g. \code{sapply(x$list_column, paste, collapse = sep)}. +columns to a character vector e.g. +\code{sapply(x$list_column, paste, collapse = sep)}. \cr\cr \cr\strong{The below options correspond to Excel table options:} \cr \if{html}{\figure{tableoptions.png}{options: width="40\%" alt="Figure: table_options.png"}} \if{latex}{\figure{tableoptions.pdf}{options: width=7cm}}} -\item{first_column}{logical. If TRUE, the first column is bold} +\item{first_column}{logical. If \code{TRUE}, the first column is bold.} -\item{last_column}{logical. If TRUE, the last column is bold} +\item{last_column}{logical. If \code{TRUE}, the last column is bold.} -\item{banded_rows}{logical. If TRUE, rows are color banded} +\item{banded_rows}{logical. If \code{TRUE}, rows are color banded.} -\item{banded_cols}{logical. If TRUE, the columns are color banded} +\item{banded_cols}{logical. If \code{TRUE}, the columns are color banded.} \item{apply_cell_style}{Should we write cell styles to the workbook} \item{remove_cell_style}{keep the cell style?} \item{na.strings}{Value used for replacing \code{NA} values from \code{x}. Default -\code{na_strings()} uses the special \verb{#N/A} value within the workbook.} +\code{\link[=na_strings]{na_strings()}} uses the special \verb{#N/A} value within the workbook.} \item{inline_strings}{write characters as inline strings} \item{...}{additional arguments} } \description{ -Add data to a worksheet and format as an Excel table +Add data to a worksheet and format as an Excel table. } \details{ -columns of \code{x} with class Date/POSIXt, currency, accounting, -hyperlink, percentage are automatically styled as dates, currency, -accounting, hyperlinks, percentages respectively. The string \code{"_openxlsx_NA"} -is reserved for \code{openxlsx2}. If the data frame contains this string, the -output will be broken. +The columns of \code{x} with class Date/POSIXt, currency, accounting, hyperlink, +percentage are automatically styled as dates, currency, accounting, hyperlinks, +percentages respectively. + +The string \code{"_openxlsx_NA"} is reserved for \code{openxlsx2}. If \code{x} contains this +string, the output will be broken. } \seealso{ Other workbook wrappers: @@ -104,9 +105,9 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_add_data_validation.Rd b/man/wb_add_data_validation.Rd index 27794e422..ce705f905 100644 --- a/man/wb_add_data_validation.Rd +++ b/man/wb_add_data_validation.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_data_validation} \alias{wb_add_data_validation} -\title{Add data validation to cells} +\title{Add data validation to cells in a worksheet} \usage{ wb_add_data_validation( wb, @@ -23,13 +23,14 @@ wb_add_data_validation( ) } \arguments{ -\item{wb}{A workbook object} +\item{wb}{A Workbook object} \item{sheet}{A name or index of a worksheet} \item{dims}{A cell dimension ("A1" or "A1:B2")} -\item{type}{One of 'whole', 'decimal', 'date', 'time', 'textLength', 'list' (see examples)} +\item{type}{One of 'whole', 'decimal', 'date', 'time', 'textLength', 'list' +(see examples)} \item{operator}{One of 'between', 'notBetween', 'equal', 'notEqual', 'greaterThan', 'lessThan', 'greaterThanOrEqual', 'lessThanOrEqual'} @@ -42,7 +43,9 @@ wb_add_data_validation( \item{show_error_msg}{logical} -\item{error_style}{The icon shown and the options how to deal with such inputs. Default "stop" (cancel), else "information" (prompt popup) or "warning" (prompt accept or change input)} +\item{error_style}{The icon shown and the options how to deal with such inputs. +Default "stop" (cancel), else "information" (prompt popup) or +"warning" (prompt accept or change input)} \item{error_title}{The error title} diff --git a/man/wb_add_drawing.Rd b/man/wb_add_drawing.Rd index da4a5882b..5b29e3cf5 100644 --- a/man/wb_add_drawing.Rd +++ b/man/wb_add_drawing.Rd @@ -15,11 +15,11 @@ wb_add_drawing( ) } \arguments{ -\item{wb}{a \code{wbWorkbook}} +\item{wb}{A \code{wbWorkbook}} -\item{sheet}{a sheet in the workbook} +\item{sheet}{A sheet in the workbook} -\item{dims}{the dimension where the drawing is added. Can be \code{NULL}} +\item{dims}{The dimension where the drawing is added.} \item{xml}{the drawing xml as character or file} diff --git a/man/wb_add_dxfs_style.Rd b/man/wb_add_dxfs_style.Rd index 70832f165..d116d8a97 100644 --- a/man/wb_add_dxfs_style.Rd +++ b/man/wb_add_dxfs_style.Rd @@ -2,8 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_dxfs_style} \alias{wb_add_dxfs_style} -\title{add dxfs style -These styles are used with conditional formatting and custom table styles} +\title{Set a dxfs styling for the workbook} \usage{ wb_add_dxfs_style( wb, @@ -24,7 +23,7 @@ wb_add_dxfs_style( ) } \arguments{ -\item{wb}{wbWorkbook} +\item{wb}{A Workbook object.} \item{name}{the style name} @@ -52,14 +51,13 @@ wb_add_dxfs_style( \item{text_underline}{logical if text is underlined} -\item{...}{additional arguments passed to \code{create_dxfs_style()}} +\item{...}{additional arguments passed to \code{\link[=create_dxfs_style]{create_dxfs_style()}}} } \value{ -The \code{wbWorkbookObject}, invisibly +The Workbook object, invisibly } \description{ -add dxfs style -These styles are used with conditional formatting and custom table styles +These styles are used with conditional formatting and custom table styles. } \examples{ wb <- wb_workbook() \%>\% @@ -67,6 +65,12 @@ wb <- wb_workbook() \%>\% wb_add_dxfs_style( name = "nay", font_color = wb_color(hex = "FF9C0006"), - bgFill = wb_color(hex = "FFFFC7CE") + bg_fill = wb_color(hex = "FFFFC7CE") ) } +\seealso{ +Other workbook styling functions: +\code{\link{wb_add_style}()}, +\code{\link{wb_base_font}} +} +\concept{workbook styling functions} diff --git a/man/wb_add_fill.Rd b/man/wb_add_fill.Rd index b1c6770c4..9cec62d54 100644 --- a/man/wb_add_fill.Rd +++ b/man/wb_add_fill.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_fill} \alias{wb_add_fill} -\title{add fill for cell region} +\title{Modify the background fill color in a cell region} \usage{ wb_add_fill( wb, @@ -40,10 +40,10 @@ wb_add_fill( \item{...}{...} } \value{ -The \code{wbWorksheetObject}, invisibly +The \code{wbWorkbook} object, invisibly } \description{ -wb wrapper to create fill for cell region +Add fill to a cell region. } \examples{ wb <- wb_workbook() \%>\% wb_add_worksheet("S1") \%>\% wb_add_data("S1", mtcars) @@ -69,7 +69,8 @@ Other styles: \code{\link{wb_add_border}()}, \code{\link{wb_add_cell_style}()}, \code{\link{wb_add_font}()}, +\code{\link{wb_add_named_style}()}, \code{\link{wb_add_numfmt}()}, -\code{\link{wb_clone_sheet_style}()} +\code{\link{wb_cell_style}} } \concept{styles} diff --git a/man/wb_add_font.Rd b/man/wb_add_font.Rd index d92408429..b1f30e11e 100644 --- a/man/wb_add_font.Rd +++ b/man/wb_add_font.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_font} \alias{wb_add_font} -\title{add font for cell region} +\title{Modify font in a cell region} \usage{ wb_add_font( wb, @@ -27,17 +27,17 @@ wb_add_font( ) } \arguments{ -\item{wb}{a workbook} +\item{wb}{A Workbook object} \item{sheet}{the worksheet} \item{dims}{the cell range} -\item{name}{font name: default "Calibri"} +\item{name}{Font name: default "Calibri"} -\item{color}{rgb color: default "FF000000"} +\item{color}{An object created by \code{\link[=wb_color]{wb_color()}}} -\item{size}{font size: default "11",} +\item{size}{Font size: default "11",} \item{bold}{bold, "single" or "double", default: ""} @@ -66,13 +66,16 @@ wb_add_font( \item{...}{...} } \value{ -The \code{wbWorksheetObject}, invisibly +A \code{wbWorkbook}, invisibly } \description{ -add font for cell region +Modify the font in a cell region with more precision +You can specify the font in a cell with other cell styling functions, +but \code{wb_add_font()} gives you more control. } \details{ -add_font provides all the options openxml accepts for a font node, not all have to be set. Usually name, size and color should be what the user wants. +\code{wb_add_font()} provides all the options openxml accepts for a font node, +not all have to be set. Usually \code{name}, \code{size} and \code{color} should be what the user wants. } \examples{ wb <- wb_workbook() \%>\% wb_add_worksheet("S1") \%>\% wb_add_data("S1", mtcars) @@ -83,7 +86,8 @@ Other styles: \code{\link{wb_add_border}()}, \code{\link{wb_add_cell_style}()}, \code{\link{wb_add_fill}()}, +\code{\link{wb_add_named_style}()}, \code{\link{wb_add_numfmt}()}, -\code{\link{wb_clone_sheet_style}()} +\code{\link{wb_cell_style}} } \concept{styles} diff --git a/man/wb_add_form_control.Rd b/man/wb_add_form_control.Rd index 02369e1f3..2f164a8f2 100644 --- a/man/wb_add_form_control.Rd +++ b/man/wb_add_form_control.Rd @@ -2,13 +2,13 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_form_control} \alias{wb_add_form_control} -\title{Add form control Checkbox, Radiobuttons or Dropmenu} +\title{Add a checkbox, radio button or drop menu to a cell in a worksheet} \usage{ wb_add_form_control( wb, sheet = current_sheet(), dims = "A1", - type = NULL, + type = c("Checkbox", "Radio", "Drop"), text = NULL, link = NULL, range = NULL, @@ -16,29 +16,32 @@ wb_add_form_control( ) } \arguments{ -\item{wb}{A workbook object} +\item{wb}{A Workbook object} \item{sheet}{A worksheet of the workbook} -\item{dims}{Optional row and column as spreadsheet dimension, e.g. "A1"} +\item{dims}{A single cell as spreadsheet dimension, e.g. "A1".} \item{type}{A type "Checkbox" (the default), "Radio" a radio button or "Drop" a drop down menu} -\item{text}{A text to be shown next to the Checkbox or radio button} +\item{text}{A text to be shown next to the Checkbox or radio button (optional)} \item{link}{A cell range to link to} \item{range}{A cell range used as input} -\item{checked}{A logical indicating if the Checkbox or radio button is checked} +\item{checked}{A logical indicating if the Checkbox or Radio button is checked} } \value{ -The \code{wbWorkbook} object +The \code{wbWorkbook} object, invisibly. } \description{ -Add form control Checkbox, Radiobuttons or Dropmenu +You can add Form Control to a cell. The three supported types are a Checkbox, +a Radio button, or a Drop menu. } \examples{ wb <- wb_workbook() \%>\% wb_add_worksheet() \%>\% wb_add_form_control() +# Add +wb$add_form_control(dims = "C5", type = "Radio", checked = TRUE) } diff --git a/man/wb_add_formula.Rd b/man/wb_add_formula.Rd index b6bcdd16c..a0db878dc 100644 --- a/man/wb_add_formula.Rd +++ b/man/wb_add_formula.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_formula} \alias{wb_add_formula} -\title{Add a character vector as an Excel Formula} +\title{Add a formula to a cell range in a worksheet} \usage{ wb_add_formula( wb, @@ -21,11 +21,11 @@ wb_add_formula( \arguments{ \item{wb}{A Workbook object containing a worksheet.} -\item{sheet}{The worksheet to write to. Can be the worksheet index or name.} +\item{sheet}{The worksheet to write to. (either as index or name)} -\item{x}{A character vector.} +\item{x}{A formula as character vector.} -\item{dims}{Spreadsheet dimensions that will determine startCol and startRow: "A1", "A1:B2", "A:B"} +\item{dims}{Spreadsheet dimensions that will determine where \code{x} spans: "A1", "A1:B2", "A:B"} \item{start_col}{A vector specifying the starting column to write to.} @@ -33,19 +33,26 @@ wb_add_formula( \item{array}{A bool if the function written is of type array} -\item{cm}{A special kind of array function that hides the curly braces in the cell. Add this, if you see "@" inserted into your formulas} +\item{cm}{A special kind of array function that hides the curly braces in the cell. +Add this, if you see "@" inserted into your formulas.} -\item{apply_cell_style}{Should we write cell styles to the workbook} +\item{apply_cell_style}{Should we write cell styles to the workbook?} -\item{remove_cell_style}{keep the cell style?,} +\item{remove_cell_style}{Should we keep the cell style?} \item{...}{additional arguments} } +\value{ +The workbook, invisibly. +} \description{ -Add a character vector containing Excel formula to a worksheet. +This function can be used to add a formula to a worksheet. +In \code{wb_add_formula()}, you can provide the formula as a character vector. } \details{ -Currently only the English version of functions are supported. Please don't use the local translation. +Currently, the local translations of formulas are not supported. +Only the English functions work. + The examples below show a small list of possible formulas: \itemize{ \item SUM(B2:B4) @@ -54,6 +61,15 @@ The examples below show a small list of possible formulas: \item MAX(B2:B4) \item ... } + +} +\examples{ +wb <- wb_workbook()$add_worksheet() +wb$add_data(dims = wb_dims(rows = 1, cols = 1:3), x = t(c(4, 5, 8)), col_names = FALSE) + +# calculate the sum of elements. +wb$add_formula(dims = "D1", x = "SUM(A1:C1)") + } \seealso{ Other workbook wrappers: @@ -70,9 +86,9 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_add_ignore_error.Rd b/man/wb_add_ignore_error.Rd index 2ca40c513..de8dc4297 100644 --- a/man/wb_add_ignore_error.Rd +++ b/man/wb_add_ignore_error.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_ignore_error} \alias{wb_add_ignore_error} -\title{Ignore error on worksheet} +\title{Ignore error types on worksheet} \usage{ wb_add_ignore_error( wb, @@ -21,11 +21,11 @@ wb_add_ignore_error( ) } \arguments{ -\item{wb}{workbook} +\item{wb}{A workbook} -\item{sheet}{sheet} +\item{sheet}{A sheet name or index.} -\item{dims}{dims} +\item{dims}{Cell range to ignore the error} \item{calculated_column}{calculatedColumn} @@ -39,7 +39,7 @@ wb_add_ignore_error( \item{list_data_validation}{listDataValidation} -\item{number_stored_as_text}{numberStoredAsText} +\item{number_stored_as_text}{If \code{TRUE}, will not display the error if numbers are stored as text.} \item{two_digit_text_year}{twoDigitTextYear} @@ -47,6 +47,9 @@ wb_add_ignore_error( \item{...}{additional arguments} } +\value{ +The \code{wbWorkbook} object, invisibly. +} \description{ -Ignore error on worksheet +This function allows to hide / ignore certain types of errors shown in a worksheet. } diff --git a/man/wb_add_image.Rd b/man/wb_add_image.Rd index adc2ea304..87040a6bc 100644 --- a/man/wb_add_image.Rd +++ b/man/wb_add_image.Rd @@ -23,7 +23,8 @@ wb_add_image( \item{sheet}{A name or index of a worksheet} -\item{dims}{Dimensions where to plot. Default absolute anchor, single cell (eg. "A1") oneCellAnchor, cell range (eg. "A1:D4") twoCellAnchor} +\item{dims}{Dimensions where to plot. Default absolute anchor, single cell (eg. "A1") +oneCellAnchor, cell range (eg. "A1:D4") twoCellAnchor} \item{file}{An image file. Valid file types are:\code{ "jpeg"}, \code{"png"}, \code{"bmp"}} diff --git a/man/wb_add_named_style.Rd b/man/wb_add_named_style.Rd index 8ed7a84a2..6266cc5a0 100644 --- a/man/wb_add_named_style.Rd +++ b/man/wb_add_named_style.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_named_style} \alias{wb_add_named_style} -\title{add named style for cell region} +\title{Apply styling to a cell region with a named style} \usage{ wb_add_named_style( wb, @@ -14,13 +14,13 @@ wb_add_named_style( ) } \arguments{ -\item{wb}{wbWorkbook} +\item{wb}{A \code{wbWorkbook} object} -\item{sheet}{sheet} +\item{sheet}{A worksheet} -\item{dims}{dims} +\item{dims}{A cell range} -\item{name}{name} +\item{name}{The named style name.} \item{font_name, font_size}{optional else the default of the theme} } @@ -28,5 +28,17 @@ wb_add_named_style( The \code{wbWorkbook}, invisibly } \description{ -add named style for cell region +Set the styling to a named style for a cell region. Use \code{\link[=wb_add_cell_style]{wb_add_cell_style()}} +to style a cell region with custom parameters. +A named style is the one in spreadsheet software, like "Normal", "Warning". } +\seealso{ +Other styles: +\code{\link{wb_add_border}()}, +\code{\link{wb_add_cell_style}()}, +\code{\link{wb_add_fill}()}, +\code{\link{wb_add_font}()}, +\code{\link{wb_add_numfmt}()}, +\code{\link{wb_cell_style}} +} +\concept{styles} diff --git a/man/wb_add_numfmt.Rd b/man/wb_add_numfmt.Rd index b6b795928..9df4b39e1 100644 --- a/man/wb_add_numfmt.Rd +++ b/man/wb_add_numfmt.Rd @@ -2,12 +2,12 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_numfmt} \alias{wb_add_numfmt} -\title{add numfmt for cell region} +\title{Modify number formatting in a cell region} \usage{ wb_add_numfmt(wb, sheet = current_sheet(), dims = "A1", numfmt) } \arguments{ -\item{wb}{a workbook} +\item{wb}{A Workbook} \item{sheet}{the worksheet} @@ -16,21 +16,25 @@ wb_add_numfmt(wb, sheet = current_sheet(), dims = "A1", numfmt) \item{numfmt}{either an id or a character} } \value{ -The \code{wbWorksheetObject}, invisibly +The \code{wbWorkbook} object, invisibly. } \description{ -add numfmt for cell region +Add number formatting to a cell region. You can use a number format created +by \code{\link[=create_numfmt]{create_numfmt()}}. } \examples{ wb <- wb_workbook() \%>\% wb_add_worksheet("S1") \%>\% wb_add_data("S1", mtcars) wb \%>\% wb_add_numfmt("S1", dims = "F1:F33", numfmt = "#.0") } \seealso{ +\code{\link[=create_numfmt]{create_numfmt()}} + Other styles: \code{\link{wb_add_border}()}, \code{\link{wb_add_cell_style}()}, \code{\link{wb_add_fill}()}, \code{\link{wb_add_font}()}, -\code{\link{wb_clone_sheet_style}()} +\code{\link{wb_add_named_style}()}, +\code{\link{wb_cell_style}} } \concept{styles} diff --git a/man/wb_add_pivot_table.Rd b/man/wb_add_pivot_table.Rd index 2f9355b87..4fd97e4da 100644 --- a/man/wb_add_pivot_table.Rd +++ b/man/wb_add_pivot_table.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_pivot_table} \alias{wb_add_pivot_table} -\title{Add pivot table to a worksheet} +\title{Add a pivot table to a worksheet} \usage{ wb_add_pivot_table( wb, @@ -20,29 +20,30 @@ wb_add_pivot_table( \arguments{ \item{wb}{A Workbook object containing a #' worksheet.} -\item{x}{a \code{wb_data} object} +\item{x}{A \code{data.frame} that inherits the \code{\link[=wb_data]{wb_data}} class.} -\item{sheet}{a worksheet} +\item{sheet}{A worksheet containing a #'} -\item{dims}{the worksheet cell where the pivot table is placed} +\item{dims}{The worksheet cell where the pivot table is placed} -\item{filter}{a character object with names used to filter} +\item{filter}{The column name(s) of \code{x} used for filter.} -\item{rows}{a character object with names used as rows} +\item{rows}{The column name(s) of \code{x} used as rows} -\item{cols}{a character object with names used as cols} +\item{cols}{The column names(s) of \code{x} used as cols} -\item{data}{a character object with names used as data} +\item{data}{The column name(s) of \code{x} used as data} -\item{fun}{a character object of functions to be used with the data} +\item{fun}{A vector of functions to be used with \code{data}} -\item{params}{a list of parameters to modify pivot table creation} +\item{params}{A list of parameters to modify pivot table creation.} } \description{ -add pivot table +Add a pivot table to a worksheet. The data must be specified using \code{\link[=wb_data]{wb_data()}} +to ensure the function works. } \details{ -\code{fun} can be either of \code{AVERAGE}, \code{COUNT}, \code{COUNTA}, \code{MAX}, \code{MIN}, +\code{fun} can be any of \code{AVERAGE}, \code{COUNT}, \code{COUNTA}, \code{MAX}, \code{MIN}, \code{PRODUCT}, \code{STDEV}, \code{STDEVP}, \code{SUM}, \code{VAR}, \code{VARP}. The sheet will be empty unless it is opened in spreadsheet software. @@ -50,13 +51,16 @@ The sheet will be empty unless it is opened in spreadsheet software. \examples{ wb <- wb_workbook() \%>\% wb_add_worksheet() \%>\% wb_add_data(x = mtcars) -df <- wb_data(wb) +df <- wb_data(wb, sheet = 1) wb <- wb \%>\% -wb_add_pivot_table(df, dims = "A3", - filter = "am", rows = "cyl", cols = "gear", data = "disp") + wb_add_pivot_table(df, dims = "A3", + filter = "am", rows = "cyl", cols = "gear", data = "disp" + ) } \seealso{ +\code{\link[=wb_data]{wb_data()}} + Other workbook wrappers: \code{\link{wb_add_chartsheet}()}, \code{\link{wb_add_data_table}()}, @@ -71,9 +75,9 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_add_sparklines.Rd b/man/wb_add_sparklines.Rd index 0b7b3b686..4b6c1580a 100644 --- a/man/wb_add_sparklines.Rd +++ b/man/wb_add_sparklines.Rd @@ -2,22 +2,22 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_sparklines} \alias{wb_add_sparklines} -\title{add sparklines to workbook} +\title{Add sparklines to a worksheet} \usage{ wb_add_sparklines(wb, sheet = current_sheet(), sparklines) } \arguments{ -\item{wb}{workbook} +\item{wb}{A \code{wbWorkbook}} \item{sheet}{sheet to add the sparklines to} -\item{sparklines}{sparklines object created with \code{create_sparklines()}} +\item{sparklines}{sparklines object created with \code{\link[=create_sparklines]{create_sparklines()}}} } \description{ -add sparklines to workbook +Add sparklines to a worksheet } \examples{ - sl <- create_sparklines("Sheet 1", "A3:K3", "L3") + sl <- create_sparklines("Sheet 1", dims = "A3:K3", sqref = "L3") wb <- wb_workbook() \%>\% wb_add_worksheet() \%>\% wb_add_data(x = mtcars) \%>\% diff --git a/man/wb_add_style.Rd b/man/wb_add_style.Rd index 0672b5915..e11aa41a7 100644 --- a/man/wb_add_style.Rd +++ b/man/wb_add_style.Rd @@ -2,17 +2,20 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_style} \alias{wb_add_style} -\title{add style to workbook} +\title{Set the default style in a workbook} \usage{ wb_add_style(wb, style = NULL, style_name = NULL) } \arguments{ -\item{wb}{workbook} +\item{wb}{A workbook} -\item{style}{style xml character} +\item{style}{style xml character, created by a \verb{create_*()} function.} \item{style_name}{style name used optional argument} } +\value{ +The \code{wbWorkbook} object, invisibly. +} \description{ wb wrapper to add style to workbook } @@ -20,9 +23,21 @@ wb wrapper to add style to workbook yellow_f <- wb_color(hex = "FF9C6500") yellow_b <- wb_color(hex = "FFFFEB9C") -yellow <- create_dxfs_style(font_color = yellow_f, bgFill = yellow_b) +yellow <- create_dxfs_style(font_color = yellow_f, bg_fill = yellow_b) wb <- wb_workbook() \%>\% wb_add_style(yellow) } \seealso{ -\code{\link[=create_border]{create_border()}}, \code{\link[=create_cell_style]{create_cell_style()}}, \code{\link[=create_dxfs_style]{create_dxfs_style()}}, \code{\link[=create_fill]{create_fill()}}, \code{\link[=create_font]{create_font()}}, \code{\link[=create_numfmt]{create_numfmt()}} +\itemize{ +\item \code{\link[=create_border]{create_border()}} +\item \code{\link[=create_cell_style]{create_cell_style()}} +\item \code{\link[=create_dxfs_style]{create_dxfs_style()}} +\item \code{\link[=create_fill]{create_fill()}} +\item \code{\link[=create_font]{create_font()}} +\item \code{\link[=create_numfmt]{create_numfmt()}} +} + +Other workbook styling functions: +\code{\link{wb_add_dxfs_style}()}, +\code{\link{wb_base_font}} } +\concept{workbook styling functions} diff --git a/man/wb_add_thread.Rd b/man/wb_add_thread.Rd index 103941708..ea7f8ddf7 100644 --- a/man/wb_add_thread.Rd +++ b/man/wb_add_thread.Rd @@ -23,7 +23,7 @@ wb_add_thread( \arguments{ \item{wb}{a workbook} -\item{name}{the name to display} +\item{name}{the name of the person to display.} \item{id}{(optional) the display id} @@ -44,10 +44,15 @@ wb_add_thread( \item{resolve}{logical if the comment should be marked as resolved} } \description{ -These functions allow adding thread comments to spreadsheets. This is not yet supported by all spreadsheet software. +These functions allow adding thread comments to spreadsheets. +This is not yet supported by all spreadsheet software. } \details{ -If a threaded comment is added, it needs a person attached with it. The default is to create a person with provider id \code{"None"}. Other providers are possible with specific values for \code{id} and \code{user_id}. If you require the following, create a workbook via spreadsheet software load it and get the values with \code{\link[=wb_get_person]{wb_get_person()}} +If a threaded comment is added, it needs a person attached with it. +The default is to create a person with provider id \code{"None"}. +Other providers are possible with specific values for \code{id} and \code{user_id}. +If you require the following, create a workbook via spreadsheet software load +it and get the values with \code{\link[=wb_get_person]{wb_get_person()}} } \examples{ wb <- wb_workbook()$add_worksheet()$ diff --git a/man/wb_add_worksheet.Rd b/man/wb_add_worksheet.Rd index 02c922d87..f8a048fb6 100644 --- a/man/wb_add_worksheet.Rd +++ b/man/wb_add_worksheet.Rd @@ -29,7 +29,7 @@ wb_add_worksheet( ) } \arguments{ -\item{wb}{A Workbook object to attach the new worksheet} +\item{wb}{A \code{wbWorkbook} object to attach the new worksheet} \item{sheet}{A name for the new worksheet} @@ -39,72 +39,79 @@ hidden.} \item{row_col_headers}{A logical. If \code{FALSE}, the worksheet colname and rowname will be hidden.} -\item{tab_color}{Color of the worksheet tab. A valid color (belonging to -colors()) or a valid hex color beginning with "#"} +\item{tab_color}{Color of the worksheet tab. A \code{\link[=wb_color]{wb_color()}}, a valid color (belonging to +\code{grDevices::colors()}) or a valid hex color beginning with "#".} -\item{zoom}{A numeric between 10 and 400. Worksheet zoom level as a -percentage.} +\item{zoom}{The worksheet zoom level, a numeric between 10 and 400 as a +percentage. (A zoom value smaller than 10 will default to 10.)} \item{header, odd_header, even_header, first_header, footer, odd_footer, even_footer, first_footer}{Character vector of length 3 corresponding to positions left, center, right. \code{header} and \code{footer} are used to default additional arguments. Setting \code{even}, \code{odd}, or \code{first}, overrides \code{header}/\code{footer}. Use \code{NA} to skip a position.} -\item{visible}{If FALSE, sheet is hidden else visible.} +\item{visible}{If \code{FALSE}, sheet is hidden else visible.} -\item{has_drawing}{If TRUE prepare a drawing output (TODO does this work?)} +\item{has_drawing}{If \code{TRUE} prepare a drawing output (TODO does this work?)} \item{paper_size}{An integer corresponding to a paper size. See \code{\link[=wb_page_setup]{wb_page_setup()}} for details.} \item{orientation}{One of "portrait" or "landscape"} -\item{hdpi}{Horizontal DPI. Can be set with options("openxlsx2.dpi" = X) or -options("openxlsx2.hdpi" = X)} +\item{hdpi, vdpi}{Horizontal and vertical DPI. Can be set with \code{options("openxlsx2.dpi" = X)}, +\code{options("openxlsx2.hdpi" = X)} or \code{options("openxlsx2.vdpi" = X)}} -\item{vdpi}{Vertical DPI. Can be set with options("openxlsx2.dpi" = X) or -options("openxlsx2.vdpi" = X)} - -\item{...}{...} +\item{...}{Additional arguments} } \value{ -The \link{wbWorkbook} object \code{wb} +The \code{wbWorkbook} object, invisibly. } \description{ -Add a worksheet to a workbook +Add a worksheet to a \link{wbWorkbook} is the first step to build a workbook. +With the function, you can also set the sheet view with \code{zoom}, set headers +and footers as well as other features. See the function arguments. } \details{ -Headers and footers can contain special tags \itemize{ -\item{\strong{&[Page]}}{ Page number} \item{\strong{&[Pages]}}{ Number of pages} -\item{\strong{&[Date]}}{ Current date} \item{\strong{&[Time]}}{ Current time} -\item{\strong{&[Path]}}{ File path} \item{\strong{&[File]}}{ File name} -\item{\strong{&[Tab]}}{ Worksheet name} } +Headers and footers can contain special tags +\itemize{ +\item \strong{&[Page]} Page number +\item \strong{&[Pages]} Number of pages +\item \strong{&[Date]} Current date +\item \strong{&[Time]} Current time +\item \strong{&[Path]} File path +\item \strong{&[File]} File name +\item \strong{&[Tab]} Worksheet name +} } \examples{ ## Create a new workbook -wb <- wb_workbook("Fred") +wb <- wb_workbook() -## Add 3 worksheets +## Add a worksheet wb$add_worksheet("Sheet 1") -wb$add_worksheet("Sheet 2", gridLines = FALSE) -wb$add_worksheet("Sheet 3", tabColor = "red") -wb$add_worksheet("Sheet 4", gridLines = FALSE, tabColor = "#4F81BD") +## No grid lines +wb$add_worksheet("Sheet 2", grid_lines = FALSE) +## A red tab color +wb$add_worksheet("Sheet 3", tab_color = wb_color("red")) +## All options combined with a zoom of 40\% +wb$add_worksheet("Sheet 4", grid_lines = FALSE, tab_color = wb_color(hex = "#4F81BD"), zoom = 40) ## Headers and Footers wb$add_worksheet("Sheet 5", header = c("ODD HEAD LEFT", "ODD HEAD CENTER", "ODD HEAD RIGHT"), footer = c("ODD FOOT RIGHT", "ODD FOOT CENTER", "ODD FOOT RIGHT"), - evenHeader = c("EVEN HEAD LEFT", "EVEN HEAD CENTER", "EVEN HEAD RIGHT"), - evenFooter = c("EVEN FOOT RIGHT", "EVEN FOOT CENTER", "EVEN FOOT RIGHT"), - firstHeader = c("TOP", "OF FIRST", "PAGE"), - firstFooter = c("BOTTOM", "OF FIRST", "PAGE") + even_header = c("EVEN HEAD LEFT", "EVEN HEAD CENTER", "EVEN HEAD RIGHT"), + even_footer = c("EVEN FOOT RIGHT", "EVEN FOOT CENTER", "EVEN FOOT RIGHT"), + first_header = c("TOP", "OF FIRST", "PAGE"), + first_footer = c("BOTTOM", "OF FIRST", "PAGE") ) wb$add_worksheet("Sheet 6", header = c("&[Date]", "ALL HEAD CENTER 2", "&[Page] / &[Pages]"), footer = c("&[Path]&[File]", NA, "&[Tab]"), - firstHeader = c(NA, "Center Header of First Page", NA), - firstFooter = c(NA, "Center Footer of First Page", NA) + first_header = c(NA, "Center Header of First Page", NA), + first_footer = c(NA, "Center Footer of First Page", NA) ) wb$add_worksheet("Sheet 7", @@ -113,8 +120,8 @@ wb$add_worksheet("Sheet 7", ) wb$add_worksheet("Sheet 8", - firstHeader = c("FIRST ONLY L", NA, "FIRST ONLY R"), - firstFooter = c("FIRST ONLY L", NA, "FIRST ONLY R") + first_header = c("FIRST ONLY L", NA, "FIRST ONLY R"), + first_footer = c("FIRST ONLY L", NA, "FIRST ONLY R") ) ## Need data on worksheet to see all headers and footers @@ -138,9 +145,9 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_base_font.Rd b/man/wb_base_font.Rd index 9c42eeb46..2bfb71f9b 100644 --- a/man/wb_base_font.Rd +++ b/man/wb_base_font.Rd @@ -4,7 +4,7 @@ \alias{wb_base_font} \alias{wb_set_base_font} \alias{wb_get_base_font} -\title{Get / set the default font in a workbook} +\title{Set the default font in a workbook} \usage{ wb_set_base_font( wb, @@ -19,42 +19,43 @@ wb_get_base_font(wb) \arguments{ \item{wb}{A workbook object} -\item{font_size}{font size} +\item{font_size}{Font size} -\item{font_color}{font color} +\item{font_color}{Font color} \item{font_name}{Name of a font} -\item{...}{additional arguments} +\item{...}{Additional arguments} } \description{ -Modify / get the default font for the workbook. +Modify / get the default font for the workbook. The base font in a workbook +does not affect the font in data tables. } \details{ The font name is not validated in anyway. Excel replaces unknown font names -with Arial. Base font is black, size 11, Calibri. +with Arial. The default base font is Calibri, black, size 11. } \examples{ ## create a workbook wb <- wb_workbook() wb$add_worksheet("S1") ## modify base font to size 10 Arial Narrow in red -wb$set_base_font(fontSize = 10, fontColor = "#FF0000", fontName = "Arial Narrow") +wb$set_base_font(font_size = 10, font_color = wb_color("red"), font_name = "Arial Narrow") -wb$add_data("S1", iris) -wb$add_data_table("S1", x = iris, startCol = 10) ## font color does not affect tables +wb$add_data(x = iris) + +## font color does not affect tables +wb$add_data_table(x = iris, dims = wb_dims(from_col = 10)) ## get the base font -## create a workbook -wb <- wb_workbook() wb_get_base_font(wb) -## modify base font to size 10 Arial Narrow in red -wb$set_base_font(fontSize = 10, fontColor = "#FF0000", fontName = "Arial Narrow") - -wb_get_base_font(wb) } \seealso{ +Other workbook styling functions: +\code{\link{wb_add_dxfs_style}()}, +\code{\link{wb_add_style}()} + Other workbook wrappers: \code{\link{wb_add_chartsheet}()}, \code{\link{wb_add_data_table}()}, @@ -69,9 +70,10 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } +\concept{workbook styling functions} \concept{workbook wrappers} diff --git a/man/cell_style.Rd b/man/wb_cell_style.Rd similarity index 56% rename from man/cell_style.Rd rename to man/wb_cell_style.Rd index 785905da2..5001ca476 100644 --- a/man/cell_style.Rd +++ b/man/wb_cell_style.Rd @@ -1,31 +1,31 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/class-workbook-wrappers.R -\name{cell_style} -\alias{cell_style} +\name{wb_cell_style} +\alias{wb_cell_style} \alias{wb_get_cell_style} \alias{wb_set_cell_style} -\title{get and set cell style} +\title{Apply styling to a cell region} \usage{ wb_get_cell_style(wb, sheet = current_sheet(), dims) wb_set_cell_style(wb, sheet = current_sheet(), dims, style) } \arguments{ -\item{wb}{wb} +\item{wb}{A \code{wbWorkbook} object} \item{sheet}{sheet} -\item{dims}{dims} +\item{dims}{A cell range in the worksheet} -\item{style}{style} +\item{style}{A style} } \value{ wb_get_cell_style returns the style id as character -wb_set_cell_style returns the workbook invisible +wb_set_cell_style returns the workbook invisibly. } \description{ -get and set cell style +Apply styling to a cell region } \examples{ # set a style in b1 @@ -38,3 +38,13 @@ numfmt <- wb$get_cell_style(dims = "B1") # assign style to a1 wb$set_cell_style(dims = "A1", style = numfmt) } +\seealso{ +Other styles: +\code{\link{wb_add_border}()}, +\code{\link{wb_add_cell_style}()}, +\code{\link{wb_add_fill}()}, +\code{\link{wb_add_font}()}, +\code{\link{wb_add_named_style}()}, +\code{\link{wb_add_numfmt}()} +} +\concept{styles} diff --git a/man/cleanup.Rd b/man/wb_clean_sheet.Rd similarity index 60% rename from man/cleanup.Rd rename to man/wb_clean_sheet.Rd index 7dd17d347..9bc8077c5 100644 --- a/man/cleanup.Rd +++ b/man/wb_clean_sheet.Rd @@ -1,10 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/class-workbook-wrappers.R, R/wb_functions.R -\name{cleanup} -\alias{cleanup} +% Please edit documentation in R/class-workbook-wrappers.R +\name{wb_clean_sheet} \alias{wb_clean_sheet} -\alias{delete_data} -\title{clean sheet (remove all values)} +\title{Remove all values in a worksheet} \usage{ wb_clean_sheet( wb, @@ -15,11 +13,9 @@ wb_clean_sheet( styles = TRUE, merged_cells = TRUE ) - -delete_data(wb, sheet, cols, rows) } \arguments{ -\item{wb}{workbook} +\item{wb}{A Workbook object} \item{sheet}{sheet to clean} @@ -32,11 +28,10 @@ delete_data(wb, sheet, cols, rows) \item{styles}{remove all styles} \item{merged_cells}{remove all merged_cells} - -\item{cols}{numeric column vector} - -\item{rows}{numeric row vector} +} +\value{ +A Workbook object } \description{ -clean sheet (remove all values) +Remove content of a worksheet completely, or a region if specifying \code{dims}. } diff --git a/man/wb_clone_sheet_style.Rd b/man/wb_clone_sheet_style.Rd index f03472bb9..2627258e9 100644 --- a/man/wb_clone_sheet_style.Rd +++ b/man/wb_clone_sheet_style.Rd @@ -2,26 +2,18 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_clone_sheet_style} \alias{wb_clone_sheet_style} -\title{clone sheets style} +\title{Apply styling from a sheet to another within a workbook} \usage{ wb_clone_sheet_style(wb, from = current_sheet(), to) } \arguments{ -\item{wb}{workbook} +\item{wb}{A workbook} \item{from}{sheet we select the style from} -\item{to}{sheet we apply the style from} +\item{to}{sheet to apply the style to} } \description{ -clone sheets style +This function can be used to apply styling from a cell range, and apply it +to another cell range. } -\seealso{ -Other styles: -\code{\link{wb_add_border}()}, -\code{\link{wb_add_cell_style}()}, -\code{\link{wb_add_fill}()}, -\code{\link{wb_add_font}()}, -\code{\link{wb_add_numfmt}()} -} -\concept{styles} diff --git a/man/wb_clone_worksheet.Rd b/man/wb_clone_worksheet.Rd index 7a767ad73..ea37664ac 100644 --- a/man/wb_clone_worksheet.Rd +++ b/man/wb_clone_worksheet.Rd @@ -2,35 +2,36 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_clone_worksheet} \alias{wb_clone_worksheet} -\title{Clone a worksheet to a workbook} +\title{Create copies of a worksheet within a workbook} \usage{ wb_clone_worksheet(wb, old = current_sheet(), new = next_sheet()) } \arguments{ -\item{wb}{A \link{wbWorkbook} object} +\item{wb}{A \code{wbWorkbook} object} \item{old}{Name of existing worksheet to copy} -\item{new}{Name of New worksheet to create} +\item{new}{Name of the new worksheet to create} } \value{ -The \code{wb} object +The \code{wbWorkbook} object, invisibly. } \description{ -Clone a worksheet to a Workbook object -} -\details{ +Create a copy of a worksheet in the same \code{wbWorkbook} object. + Cloning is possible only to a limited extent. References to sheet names in formulas, charts, pivot tables, etc. may not be updated. Some elements like named ranges and slicers cannot be cloned yet. } \examples{ # Create a new workbook -wb <- wb_workbook("Fred") +wb <- wb_workbook() # Add worksheets wb$add_worksheet("Sheet 1") -wb$clone_worksheet("Sheet 1", "Sheet 2") +wb$clone_worksheet("Sheet 1", new = "Sheet 2") +# Take advantage of waiver functions +wb$clone_worksheet(old = "Sheet 1") } \seealso{ Other workbook wrappers: @@ -47,9 +48,9 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_col_widths.Rd b/man/wb_col_widths.Rd index 35cde1df2..797c95650 100644 --- a/man/wb_col_widths.Rd +++ b/man/wb_col_widths.Rd @@ -4,7 +4,7 @@ \alias{wb_col_widths} \alias{wb_set_col_widths} \alias{wb_remove_col_widths} -\title{Modify worksheet column widths} +\title{Modify column widths of a worksheet} \usage{ wb_set_col_widths( wb, @@ -17,33 +17,38 @@ wb_set_col_widths( wb_remove_col_widths(wb, sheet = current_sheet(), cols) } \arguments{ -\item{wb}{A \code{wbWorkbook} object} +\item{wb}{A \code{wbWorkbook} object.} -\item{sheet}{A name or index of a worksheet, a vector in the case of \code{remove}} +\item{sheet}{A name or index of a worksheet, a vector in the case of \code{remove_}} -\item{cols}{Indices of cols to set/remove width} +\item{cols}{Indices of cols to set/remove column widths.} -\item{widths}{width to set cols to specified in Excel column width units or "auto" for automatic sizing. The widths argument is -recycled to the length of cols. The default width is 8.43. Though there is no specific default width for Excel, it depends on -Excel version, operating system and DPI settings used. Setting it to specific value also is no guarantee that the output will be -of the selected width.} +\item{widths}{Width to set \code{cols} to specified column width or \code{"auto"} for +automatic sizing. \code{widths} is recycled to the length of \code{cols}. openxlsx2 +sets the default width is 8.43, as this is the standard in some spreadsheet +software. See \strong{Details} for general information on column widths.} -\item{hidden}{Logical vector. If \code{TRUE} the column is hidden.} +\item{hidden}{Logical vector recycled to the length of \code{cols}. +If \code{TRUE}, the columns are hidden.} } \description{ -Remove / set worksheet column widths to specific width or "auto". +Remove / set worksheet column widths to specified width or "auto". } \details{ The global min and max column width for "auto" columns is set by (default values show): \itemize{ -\item{options("openxlsx2.minWidth" = 3)} -\item{options("openxlsx2.maxWidth" = 250)} ## This is the maximum width allowed in Excel +\item \code{options("openxlsx2.minWidth" = 3)} +\item \code{options("openxlsx2.maxWidth" = 250)} Maximum width allowed in Excel } NOTE: The calculation of column widths can be slow for large worksheets. -NOTE: The \code{hidden} parameter may conflict with the one set in -\code{\link[=wb_group_cols]{wb_group_cols()}}; changing one will update the other. +NOTE: The \code{hidden} parameter may conflict with the one set in \code{\link[=wb_group_cols]{wb_group_cols()}}; +changing one will update the other. + +NOTE: The default column width varies by spreadsheet software, operating system, +and DPI settings used. Setting \code{widths} to specific value also is no guarantee +that the output will have consistent column widths. } \examples{ ## Create a new workbook @@ -53,7 +58,7 @@ wb <- wb_workbook() wb$add_worksheet("Sheet 1") ## set col widths -wb$set_col_widths(1, cols = c(1, 4, 6, 7, 9), widths = c(16, 15, 12, 18, 33)) +wb$set_col_widths(cols = c(1, 4, 6, 7, 9), widths = c(16, 15, 12, 18, 33)) ## auto columns wb$add_worksheet("Sheet 2") @@ -82,9 +87,9 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_copy_cells.Rd b/man/wb_copy_cells.Rd index ddbf6c987..cdf163a7a 100644 --- a/man/wb_copy_cells.Rd +++ b/man/wb_copy_cells.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_copy_cells} \alias{wb_copy_cells} -\title{copy cells around} +\title{Copy cells around within a worksheet} \usage{ wb_copy_cells( wb, @@ -15,25 +15,25 @@ wb_copy_cells( ) } \arguments{ -\item{wb}{workbook} +\item{wb}{A workbook} \item{sheet}{a worksheet} -\item{dims}{cell used as start} +\item{dims}{A cell where to place the copy} -\item{data}{a wb_data object} +\item{data}{A \code{\link[=wb_data]{wb_data}} object containing cells to copy} -\item{as_value}{should a copy of the value be written} +\item{as_value}{Should a copy of the value be written?} -\item{as_ref}{should references to the cell be written} +\item{as_ref}{Should references to the cell be written?} -\item{transpose}{should the data be written transposed} +\item{transpose}{Should the data be written transposed?} } \value{ -the wbWorkbook invisibly +the \code{wbWorkbook} invisibly } \description{ -copy cells around +Copy cells around within a worksheet } \examples{ wb <- wb_workbook()$ @@ -41,14 +41,15 @@ add_worksheet()$ add_data(x = mtcars)$ add_fill(dims = "A1:F1", color = wb_color("yellow")) -dat <- wb_data(wb, dims = "A1:D4", colNames = FALSE) - +dat <- wb_data(wb, dims = "A1:D4", col_names = FALSE) +# 1:1 copy to M2 wb$ - # 1:1 copy to M2 clone_worksheet(old = 1, new = "Clone1")$ copy_cells(data = dat, dims = "M2") } \seealso{ +\code{\link[=wb_data]{wb_data()}} + Other workbook wrappers: \code{\link{wb_add_chartsheet}()}, \code{\link{wb_add_data_table}()}, @@ -63,9 +64,9 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_creators.Rd b/man/wb_creators.Rd index 7f9258e97..9f55c9c76 100644 --- a/man/wb_creators.Rd +++ b/man/wb_creators.Rd @@ -6,7 +6,7 @@ \alias{wb_set_creators} \alias{wb_remove_creators} \alias{wb_get_creators} -\title{Workbook creators} +\title{Modify creators of a workbook} \usage{ wb_add_creators(wb, creators) @@ -23,7 +23,8 @@ wb_get_creators(wb) } \value{ \itemize{ -\item \code{wb_set_creators()}, \code{wb_add_creators()}, and \code{wb_remove_creators()} return the \code{wbWorkbook} object +\item \code{wb_set_creators()}, \code{wb_add_creators()}, and \code{wb_remove_creators()} return +the \code{wbWorkbook} object \item \code{wb_get_creators()} returns a \code{character} vector of creators } } @@ -60,9 +61,9 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_data.Rd b/man/wb_data.Rd index 0625d84d5..1b0af2802 100644 --- a/man/wb_data.Rd +++ b/man/wb_data.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/read.R \name{wb_data} \alias{wb_data} -\title{provide wb_data object as mschart input} +\title{Add the \code{wb_data} attribute to a data frame in a worksheet} \usage{ wb_data(wb, sheet = current_sheet(), dims, ...) } @@ -13,9 +13,12 @@ wb_data(wb, sheet = current_sheet(), dims, ...) \item{dims}{the dimensions} -\item{...}{additional arguments for wb_to_df. Be aware that not every +\item{...}{additional arguments for \code{wb_to_df()}. Be aware that not every argument is valid.} } +\value{ +A data frame of class \code{wb_data}. +} \description{ provide wb_data object as mschart input } @@ -27,5 +30,5 @@ provide wb_data object as mschart input wb_data(wb, 1, dims = "B2:E6") } \seealso{ -\code{\link[=wb_to_df]{wb_to_df()}} \code{\link[=wb_add_mschart]{wb_add_mschart()}} +\code{\link[=wb_to_df]{wb_to_df()}} \code{\link[=wb_add_mschart]{wb_add_mschart()}}, \code{\link[=wb_add_pivot_table]{wb_add_pivot_table()}} } diff --git a/man/wb_filter.Rd b/man/wb_filter.Rd index eb6b0762b..96acc6a81 100644 --- a/man/wb_filter.Rd +++ b/man/wb_filter.Rd @@ -52,7 +52,7 @@ wb$add_data(1, iris) wb_add_filter(wb, 1, row = 1, cols = seq_along(iris)) ## Equivalently -wb$add_data(2, x = iris, withFilter = TRUE) +wb$add_data(2, x = iris, with_filter = TRUE) ## Similarly wb$add_data_table(3, iris) diff --git a/man/wb_freeze_pane.Rd b/man/wb_freeze_pane.Rd index b4436bd52..55c42ce12 100644 --- a/man/wb_freeze_pane.Rd +++ b/man/wb_freeze_pane.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_freeze_pane} \alias{wb_freeze_pane} -\title{Freeze a worksheet pane} +\title{Freeze pane of a worksheet} \usage{ wb_freeze_pane( wb, @@ -23,14 +23,14 @@ wb_freeze_pane( \item{first_active_col}{Furthest left column of active region} -\item{first_row}{If \code{TRUE}, freezes the first row (equivalent to firstActiveRow = 2)} +\item{first_row}{If \code{TRUE}, freezes the first row (equivalent to \code{first_active_row = 2})} -\item{first_col}{If \code{TRUE}, freezes the first column (equivalent to firstActiveCol = 2)} +\item{first_col}{If \code{TRUE}, freezes the first column (equivalent to \code{first_active_col = 2})} \item{...}{additional arguments} } \description{ -Freeze a worksheet pane +Add a Freeze pane in a worksheet. } \examples{ ## Create a new workbook @@ -43,10 +43,10 @@ wb$add_worksheet("Sheet 3") wb$add_worksheet("Sheet 4") ## Freeze Panes -wb$freeze_pane("Sheet 1", firstActiveRow = 5, firstActiveCol = 3) -wb$freeze_pane("Sheet 2", firstCol = TRUE) ## shortcut to firstActiveCol = 2 -wb$freeze_pane(3, firstRow = TRUE) ## shortcut to firstActiveRow = 2 -wb$freeze_pane(4, firstActiveRow = 1, firstActiveCol = "D") +wb$freeze_pane("Sheet 1", first_active_row = 5, first_active_col = 3) +wb$freeze_pane("Sheet 2", first_col = TRUE) ## shortcut to first_active_col = 2 +wb$freeze_pane(3, first_row = TRUE) ## shortcut to first_active_row = 2 +wb$freeze_pane(4, first_active_row = 1, first_active_col = "D") } \seealso{ Other workbook wrappers: @@ -63,9 +63,9 @@ Other workbook wrappers: \code{\link{wb_creators}}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_get_named_regions.Rd b/man/wb_get_named_regions.Rd index 44857177b..29f584cc4 100644 --- a/man/wb_get_named_regions.Rd +++ b/man/wb_get_named_regions.Rd @@ -2,15 +2,42 @@ % Please edit documentation in R/get-named-regions.R \name{wb_get_named_regions} \alias{wb_get_named_regions} -\title{Get create or remove named regions} +\title{Get named regions in a workbook or an xlsx file} \usage{ wb_get_named_regions(x, tables = FALSE) } \arguments{ -\item{x}{An xlsx file or \code{wbWorkbook} object} +\item{x}{An xlsx file or a\code{wbWorkbook} object} -\item{tables}{add tables too if \code{TRUE}} +\item{tables}{Should data tables be included in the result?} +} +\value{ +A vector of named regions in \code{x}. } \description{ -Return a vector of named regions in a xlsx file or \code{wbWorkbook} object +Get named regions in a workbook or an xlsx file +} +\examples{ +wb <- wb_workbook() +wb$add_worksheet("Sheet 1") + +## specify region +wb$add_data(x = iris, start_col = 1, start_row = 1) +wb$add_named_region( + name = "iris", + dims = wb_dims(x = iris) +)$add_data(sheet = 1, x = iris, name = "iris2", start_col = 10) + +out_file <- temp_xlsx() +wb_save(wb, out_file, overwrite = TRUE) + +## see named regions +wb_get_named_regions(wb) ## From Workbook object +wb_get_named_regions(out_file) ## From xlsx file + +df <- read_xlsx(out_file, named_region = "iris2") +head(df) +} +\seealso{ +\code{\link[=wb_add_named_region]{wb_add_named_region()}}, \code{\link[=wb_get_tables]{wb_get_tables()}} } diff --git a/man/wb_get_tables.Rd b/man/wb_get_tables.Rd index 723189f8d..6116fefb5 100644 --- a/man/wb_get_tables.Rd +++ b/man/wb_get_tables.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_get_tables} \alias{wb_get_tables} -\title{List Excel tables in a workbook} +\title{List Excel tables in a worksheet} \usage{ wb_get_tables(wb, sheet = current_sheet()) } @@ -12,17 +12,17 @@ wb_get_tables(wb, sheet = current_sheet()) \item{sheet}{A name or index of a worksheet} } \value{ -character vector of table names on the specified sheet +A character vector of table names on the specified sheet } \description{ -List Excel tables in a workbook +List Excel tables in a worksheet } \examples{ wb <- wb_workbook() wb$add_worksheet(sheet = "Sheet 1") -wb$add_data_table(sheet = "Sheet 1", x = iris) -wb$add_data_table(sheet = 1, x = mtcars, tableName = "mtcars", startCol = 10) +wb$add_data_table(x = iris) +wb$add_data_table(x = mtcars, table_name = "mtcars", start_col = 10) wb$get_tables(sheet = "Sheet 1") } diff --git a/man/wb_grouping.Rd b/man/wb_grouping.Rd index 2f9d82889..45b611b73 100644 --- a/man/wb_grouping.Rd +++ b/man/wb_grouping.Rd @@ -6,7 +6,7 @@ \alias{wb_ungroup_cols} \alias{wb_group_rows} \alias{wb_ungroup_rows} -\title{Group Rows and Columns} +\title{Group rows and columns in a worksheet} \usage{ wb_group_cols( wb, @@ -29,7 +29,7 @@ wb_group_rows( wb_ungroup_rows(wb, sheet = current_sheet(), rows) } \arguments{ -\item{wb}{A \link{wbWorkbook} object} +\item{wb}{A \code{wbWorkbook} object} \item{sheet}{A name or index of a worksheet} @@ -43,7 +43,7 @@ wb_ungroup_rows(wb, sheet = current_sheet(), rows) Group a selection of rows or cols } \details{ -If row was previously hidden, it will now be shown +If row was previously hidden, it will now be shown. } \examples{ # create matrix @@ -105,9 +105,9 @@ Other workbook wrappers: \code{\link{wb_creators}}, \code{\link{wb_freeze_pane}()}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_load.Rd b/man/wb_load.Rd index 682d9e0f0..970c70849 100644 --- a/man/wb_load.Rd +++ b/man/wb_load.Rd @@ -13,7 +13,7 @@ wb_load(file, sheet, data_only = FALSE, calc_chain = FALSE, ...) sheet will be loaded.} \item{data_only}{mode to import if only a data frame should be returned. This -strips the wbWorkbook to a bare minimum.} +strips the \code{wbWorkbook} to a bare minimum.} \item{calc_chain}{optionally you can keep the calculation chain intact. This is used by spreadsheet software to identify the order in which formulas are @@ -25,19 +25,19 @@ software.} \item{...}{additional arguments} } \value{ -Workbook object. +A Workbook object. } \description{ -wb_load returns a workbook object conserving styles and -formatting of the original .xlsx file. +\code{wb_load()} returns a \link{wbWorkbook} object conserving styles and +formatting of the original input file. } \details{ -A warning is displayed if an xml namespace for main is found in the -xlsx file. Certain xlsx files created by third-party applications contain a -namespace (usually \code{x}). This namespace is not required for the file to work -in spreadsheet software and is not expected by \code{openxlsx2}. Therefore it is -removed when the file is loaded into a workbook. Removal is generally -expected to be safe, but the feature is still experimental. +A warning is displayed if an xml namespace for main is found in the xlsx file. +Certain xlsx files created by third-party applications contain a namespace +(usually \code{x}). This namespace is not required for the file to work in spreadsheet +software and is not expected by \code{openxlsx2}. Therefore it is removed when the +file is loaded into a workbook. Removal is generally expected to be safe, +but the feature is still experimental. } \examples{ ## load existing workbook from package folder diff --git a/man/wb_merge_cells.Rd b/man/wb_merge_cells.Rd index 29794c06d..8eb977158 100644 --- a/man/wb_merge_cells.Rd +++ b/man/wb_merge_cells.Rd @@ -3,14 +3,14 @@ \name{wb_merge_cells} \alias{wb_merge_cells} \alias{wb_unmerge_cells} -\title{Worksheet cell merging} +\title{Merge cells within a worksheet} \usage{ wb_merge_cells(wb, sheet = current_sheet(), dims = NULL, solve = FALSE, ...) wb_unmerge_cells(wb, sheet = current_sheet(), dims = NULL, ...) } \arguments{ -\item{wb}{A workbook object} +\item{wb}{A Workbook object} \item{sheet}{A name or index of a worksheet} @@ -21,11 +21,11 @@ wb_unmerge_cells(wb, sheet = current_sheet(), dims = NULL, ...) \item{...}{additional arguments} } \description{ -Merge cells within a worksheet +Worksheet cell merging } \details{ -As merged region must be rectangular, only min and max of cols and -rows are used. +If using the deprecated arguments \code{rows} and \code{cols} with a merged region must be rectangular, +only min and max of \code{cols} and \code{rows} are used. } \examples{ # Create a new workbook @@ -69,9 +69,9 @@ Other workbook wrappers: \code{\link{wb_creators}}, \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_named_region.Rd b/man/wb_named_region.Rd new file mode 100644 index 000000000..ac4fd3bdc --- /dev/null +++ b/man/wb_named_region.Rd @@ -0,0 +1,90 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class-workbook-wrappers.R +\name{wb_named_region} +\alias{wb_named_region} +\alias{wb_add_named_region} +\alias{wb_remove_named_region} +\title{Modify named regions in a worksheet} +\usage{ +wb_add_named_region( + wb, + sheet = current_sheet(), + dims = "A1", + name, + local_sheet = FALSE, + overwrite = FALSE, + comment = NULL, + hidden = NULL, + custom_menu = NULL, + description = NULL, + is_function = NULL, + function_group_id = NULL, + help = NULL, + local_name = NULL, + publish_to_server = NULL, + status_bar = NULL, + vb_procedure = NULL, + workbook_parameter = NULL, + xml = NULL, + ... +) + +wb_remove_named_region(wb, sheet = current_sheet(), name = NULL) +} +\arguments{ +\item{wb}{A Workbook object} + +\item{sheet}{A name or index of a worksheet} + +\item{dims}{Worksheet cell range of the region ("A1:D4").} + +\item{name}{Name for region. A character vector of length 1. Note that region +names musts be case-insensitive unique.} + +\item{local_sheet}{If \code{TRUE} the named region will be local for this sheet} + +\item{overwrite}{Boolean. Overwrite if exists? Default to \code{FALSE}.} + +\item{comment}{description text for named region} + +\item{hidden}{Should the named region be hidden?} + +\item{custom_menu, description, is_function, function_group_id, help, local_name, publish_to_server, status_bar, vb_procedure, workbook_parameter, xml}{Unknown XML feature} + +\item{...}{additional arguments} +} +\description{ +Create / delete a named region. You can also specify a named region by using +the \code{name} argument in \code{wb_add_data(x = iris, name = "my-region")}. +It is important to note that named regions are not case-sensitive and must be unique. +} +\details{ +You can use the \code{\link[=wb_dims]{wb_dims()}} helper to specify the cell range of the named region +} +\examples{ +## create named regions +wb <- wb_workbook() +wb$add_worksheet("Sheet 1") + +## specify region +wb$add_data(x = iris, start_col = 1, start_row = 1) +wb$add_named_region( + name = "iris", + dims = wb_dims(x = iris) +) + +## using add_data 'name' argument +wb$add_data(sheet = 1, x = iris, name = "iris2", start_col = 10) + +## delete one +wb$remove_named_region(name = "iris2") +wb_get_named_regions(wb) + +## read named regions +df <- wb_to_df(wb, named_region = "iris") +head(df) + +} +\seealso{ +\code{\link[=wb_get_named_regions]{wb_get_named_regions()}} +} diff --git a/man/wb_open.Rd b/man/wb_open.Rd index 46022eea3..63f0f5bdf 100644 --- a/man/wb_open.Rd +++ b/man/wb_open.Rd @@ -2,13 +2,14 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_open} \alias{wb_open} -\title{little worksheet opener} +\title{Preview a workbook in a spreadsheet software} \usage{ wb_open(wb) } \arguments{ -\item{wb}{a workbook} +\item{wb}{a \link{wbWorkbook} object} } \description{ -little worksheet opener +You can also use the shorter \code{wb$open()} as a replacement. +To open xlsx files, see \code{\link[=xl_open]{xl_open()}}. } diff --git a/man/wb_order.Rd b/man/wb_order.Rd index 6b0069e8a..3c50a4a01 100644 --- a/man/wb_order.Rd +++ b/man/wb_order.Rd @@ -4,7 +4,7 @@ \alias{wb_order} \alias{wb_get_order} \alias{wb_set_order} -\title{Order of worksheets in xlsx file} +\title{Order worksheets in a workbook} \usage{ wb_get_order(wb) diff --git a/man/wb_page_setup.Rd b/man/wb_page_setup.Rd index 778999cb1..623d400ac 100644 --- a/man/wb_page_setup.Rd +++ b/man/wb_page_setup.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_page_setup} \alias{wb_page_setup} -\title{Set page margins, orientation and print scaling} +\title{Set page margins, orientation and print scaling of a worksheet} \usage{ wb_page_setup( wb, @@ -34,27 +34,15 @@ wb_page_setup( \item{scale}{Print scaling. Numeric value between 10 and 400} -\item{left}{left page margin in inches} +\item{left, right, top, bottom}{Page margin in inches} -\item{right}{right page margin in inches} +\item{header, footer}{Margin in inches} -\item{top}{top page margin in inches} - -\item{bottom}{bottom page margin in inches} - -\item{header}{header margin in inches} - -\item{footer}{footer margin in inches} - -\item{fit_to_width}{If \code{TRUE}, worksheet is scaled to fit to page width on printing.} - -\item{fit_to_height}{If \code{TRUE}, worksheet is scaled to fit to page height on printing.} +\item{fit_to_width, fit_to_height}{If \code{TRUE}, worksheet is scaled to fit to page width /height on printing.} \item{paper_size}{See details. Default value is 9 (A4 paper).} -\item{print_title_rows}{Rows to repeat at top of page when printing. Integer vector.} - -\item{print_title_cols}{Columns to repeat at left when printing. Integer vector.} +\item{print_title_rows, print_title_cols}{Rows / columns to repeat at top of page when printing. Integer vector.} \item{summary_row}{Location of summary rows in groupings. One of "Above" or "Below".} @@ -63,10 +51,10 @@ wb_page_setup( \item{...}{additional arguments} } \description{ -Set page margins, orientation and print scaling +Set page margins, orientation and print scaling. } \details{ -paperSize is an integer corresponding to: +\code{paper_size} is an integer corresponding to: \itemize{ \item{\strong{1}}{ Letter paper (8.5 in. by 11 in.)} \item{\strong{2}}{ Letter small paper (8.5 in. by 11 in.)} diff --git a/man/wb_protect.Rd b/man/wb_protect.Rd index 53ff7f55e..5951f43dc 100644 --- a/man/wb_protect.Rd +++ b/man/wb_protect.Rd @@ -18,9 +18,9 @@ wb_protect( ) } \arguments{ -\item{wb}{A workbook object} +\item{wb}{A Workbook object} -\item{protect}{Whether to protect or unprotect the sheet (default=TRUE)} +\item{protect}{Whether to protect or unprotect the sheet (default \code{TRUE})} \item{password}{(optional) password required to unprotect the workbook} @@ -34,10 +34,10 @@ locked} \item{file_sharing}{Whether to enable a popup requesting the unlock password is prompted} -\item{username}{The username for the \code{fileSharing} popup} +\item{username}{The username for the \code{file_sharing} popup} \item{read_only_recommended}{Whether or not a post unlock message appears -stating that the workbook is recommended to be opened in readonly mode.} +stating that the workbook is recommended to be opened in read-only mode.} \item{...}{additional arguments} } @@ -58,7 +58,7 @@ Lock types: \examples{ wb <- wb_workbook() wb$add_worksheet("S1") -wb_protect(wb, protect = TRUE, password = "Password", lockStructure = TRUE) +wb_protect(wb, protect = TRUE, password = "Password", lock_structure = TRUE) # Remove the protection wb_protect(wb, protect = FALSE) @@ -67,11 +67,11 @@ wb <- wb_protect( wb, protect = TRUE, password = "Password", - lockStructure = TRUE, + lock_structure = TRUE, type = 2L, - fileSharing = TRUE, + file_sharing = TRUE, username = "Test", - readOnlyRecommended = TRUE + read_only_recommended = TRUE ) } diff --git a/man/wb_remove_row_heights.Rd b/man/wb_remove_row_heights.Rd deleted file mode 100644 index 38ee71926..000000000 --- a/man/wb_remove_row_heights.Rd +++ /dev/null @@ -1,28 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/class-workbook-wrappers.R -\name{wb_remove_row_heights} -\alias{wb_remove_row_heights} -\title{Remove custom row heights from a worksheet} -\usage{ -wb_remove_row_heights(wb, sheet = current_sheet(), rows) -} -\arguments{ -\item{wb}{A workbook object} - -\item{sheet}{A name or index of a worksheet} - -\item{rows}{Indices of rows to remove custom height (if any) from.} -} -\description{ -Remove row heights from a worksheet -} -\examples{ -## Create a new workbook -wb <- wb_load(file = system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2")) - -## remove any custom row heights in rows 1 to 10 -wb$remove_row_heights(1, rows = 1:10) -} -\seealso{ -\code{\link[=wb_set_row_heights]{wb_set_row_heights()}} -} diff --git a/man/wb_remove_tables.Rd b/man/wb_remove_tables.Rd index 74016af62..30d356bba 100644 --- a/man/wb_remove_tables.Rd +++ b/man/wb_remove_tables.Rd @@ -2,45 +2,45 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_remove_tables} \alias{wb_remove_tables} -\title{Remove an Excel table in a workbook} +\title{Remove a data table from a worksheet} \usage{ wb_remove_tables(wb, sheet = current_sheet(), table, remove_data = TRUE) } \arguments{ -\item{wb}{A workbook object} +\item{wb}{A Workbook object} \item{sheet}{A name or index of a worksheet} -\item{table}{Name of table to remove. See \code{\link[=wb_get_tables]{wb_get_tables()}}} +\item{table}{Name of table to remove. Use \code{\link[=wb_get_tables]{wb_get_tables()}} to view the +tables present in the worksheet.} -\item{remove_data}{Removes the data as well} +\item{remove_data}{Default \code{TRUE}. If \code{FALSE}, will only remove the data table attributes +but will keep the data in the worksheet.} } \value{ -character vector of table names on the specified sheet +The \code{wbWorkbook}, invisibly } \description{ -List Excel tables in a workbook +Remove Excel tables in a workbook using its name. } \examples{ - wb <- wb_workbook() wb$add_worksheet(sheet = "Sheet 1") wb$add_worksheet(sheet = "Sheet 2") -wb$add_data_table(sheet = "Sheet 1", x = iris, tableName = "iris") -wb$add_data_table(sheet = 1, x = mtcars, tableName = "mtcars", startCol = 10) - +wb$add_data_table(sheet = "Sheet 1", x = iris, table_name = "iris") +wb$add_data_table(sheet = 1, x = mtcars, table_name = "mtcars", start_col = 10) -wb <- wb_remove_worksheet(wb, sheet = 1) ## delete worksheet removes table objects +## delete worksheet removes table objects +wb <- wb_remove_worksheet(wb, sheet = 1) -wb$add_data_table(sheet = 1, x = iris, tableName = "iris") -wb$add_data_table(sheet = 1, x = mtcars, tableName = "mtcars", startCol = 10) +wb$add_data_table(sheet = 1, x = iris, table_name = "iris") +wb$add_data_table(sheet = 1, x = mtcars, table_name = "mtcars", start_col = 10) ## wb_remove_tables() deletes table object and all data wb_get_tables(wb, sheet = 1) wb$remove_tables(sheet = 1, table = "iris") -wb$add_data_table(sheet = 1, x = iris, tableName = "iris", startCol = 1) +wb$add_data_table(sheet = 1, x = iris, table_name = "iris") wb_get_tables(wb, sheet = 1) wb$remove_tables(sheet = 1, table = "iris") -wb$add_data_table(sheet = 1, x = iris, tableName = "iris", startCol = 1) } diff --git a/man/wb_remove_worksheet.Rd b/man/wb_remove_worksheet.Rd index 4903cf3cb..3b4b3ec65 100644 --- a/man/wb_remove_worksheet.Rd +++ b/man/wb_remove_worksheet.Rd @@ -7,13 +7,14 @@ wb_remove_worksheet(wb, sheet = current_sheet()) } \arguments{ -\item{wb}{A workbook object} +\item{wb}{A wbWorkbook object} -\item{sheet}{A name or index of a worksheet} +\item{sheet}{The sheet name or index to remove} +} +\value{ +The \code{wbWorkbook} object, invisibly. } \description{ -Remove a worksheet from a Workbook object - Remove a worksheet from a workbook } \examples{ diff --git a/man/wb_set_row_heights.Rd b/man/wb_row_heights.Rd similarity index 65% rename from man/wb_set_row_heights.Rd rename to man/wb_row_heights.Rd index a8be201be..00ae75a7b 100644 --- a/man/wb_set_row_heights.Rd +++ b/man/wb_row_heights.Rd @@ -1,8 +1,10 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/class-workbook-wrappers.R -\name{wb_set_row_heights} +\name{wb_row_heights} +\alias{wb_row_heights} \alias{wb_set_row_heights} -\title{Set worksheet row heights} +\alias{wb_remove_row_heights} +\title{Modify row heights of a worksheet} \usage{ wb_set_row_heights( wb, @@ -11,20 +13,22 @@ wb_set_row_heights( heights = NULL, hidden = FALSE ) + +wb_remove_row_heights(wb, sheet = current_sheet(), rows) } \arguments{ \item{wb}{A \link{wbWorkbook} object} -\item{sheet}{A name or index of a worksheet} +\item{sheet}{A name or index of a worksheet. (A vector is accepted for \code{remove_row_heights()})} -\item{rows}{Indices of rows to set height} +\item{rows}{Indices of rows to set / remove (if any) custom height.} -\item{heights}{Heights to set rows to specified in Excel column height units.} +\item{heights}{Heights to set \code{rows} to specified in a spreadsheet column height units.} -\item{hidden}{Option to hide rows.} +\item{hidden}{Option to hide rows. A logical vector of length 1 or lengt of \code{rows}} } \description{ -Set worksheet row heights +Set / remove custom worksheet row heights } \examples{ ## Create a new workbook @@ -42,10 +46,10 @@ wb <- wb_set_row_heights( ## overwrite row 1 height wb <- wb_set_row_heights(wb, 1, rows = 1, heights = 40) +## remove any custom row heights in row 1 +wb$remove_row_heights(sheet = 1, rows = 1) } \seealso{ -\code{\link[=wb_remove_row_heights]{wb_remove_row_heights()}} - Other workbook wrappers: \code{\link{wb_add_chartsheet}()}, \code{\link{wb_add_data_table}()}, diff --git a/man/wb_save.Rd b/man/wb_save.Rd index 5a5e0d125..de99f48db 100644 --- a/man/wb_save.Rd +++ b/man/wb_save.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_save} \alias{wb_save} -\title{Save Workbook to file} +\title{Save a workbook to file} \usage{ wb_save(wb, file = NULL, overwrite = TRUE, path = NULL) } @@ -11,15 +11,15 @@ wb_save(wb, file = NULL, overwrite = TRUE, path = NULL) \item{file}{A path to save the workbook to} -\item{overwrite}{If \code{FALSE}, will not overwrite when \code{path} exists} +\item{overwrite}{If \code{FALSE}, will not overwrite when \code{file} already exists.} -\item{path}{Deprecated argument previously used for file. Please use file in new code.} +\item{path}{Deprecated argument. Please use \code{file} in new code.} } \value{ the \code{wbWorkbook} object, invisibly } \description{ -Save Workbook to file +Save a workbook to file } \examples{ ## Create a new workbook and add a worksheet @@ -47,8 +47,8 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_set_bookview.Rd b/man/wb_set_bookview.Rd index 93566acce..eeda87dcf 100644 --- a/man/wb_set_bookview.Rd +++ b/man/wb_set_bookview.Rd @@ -29,7 +29,7 @@ wb_set_bookview( \item{auto_filter_date_grouping}{autoFilterDateGrouping} -\item{first_sheet}{firstSheet} +\item{first_sheet}{The first sheet to be displayed} \item{minimized}{minimized} @@ -54,8 +54,8 @@ wb_set_bookview( \item{...}{additional arguments} } \value{ -The \code{wbWorkbook} object +The Workbook object } \description{ -Get the base font used in the workbook. +Set the workbook position, size and filter } diff --git a/man/wb_set_grid_lines.Rd b/man/wb_set_grid_lines.Rd index 6d3d810e5..c4b2795d0 100644 --- a/man/wb_set_grid_lines.Rd +++ b/man/wb_set_grid_lines.Rd @@ -3,7 +3,7 @@ \name{wb_set_grid_lines} \alias{wb_set_grid_lines} \alias{wb_grid_lines} -\title{Set worksheet gridlines to show or hide.} +\title{Modify grid lines visibility in a worksheet} \usage{ wb_set_grid_lines(wb, sheet = current_sheet(), show = FALSE, print = show) @@ -19,7 +19,9 @@ wb_grid_lines(wb, sheet = current_sheet(), show = FALSE, print = show) \item{print}{A logical. If \code{FALSE}, grid lines are not printed.} } \description{ -Set worksheet gridlines to show or hide. +Set worksheet grid lines to show or hide. +You can also add / remove grid lines when creating a worksheeet with +\code{\link[=wb_add_worksheet]{wb_add_worksheet(grid_lines = FALSE)}} } \examples{ wb <- wb_workbook()$add_worksheet()$add_worksheet() diff --git a/man/wb_set_header_footer.Rd b/man/wb_set_header_footer.Rd index ac5105565..1a77e0d3b 100644 --- a/man/wb_set_header_footer.Rd +++ b/man/wb_set_header_footer.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_set_header_footer} \alias{wb_set_header_footer} -\title{Set document headers and footers} +\title{Set headers and footers of a worksheet} \usage{ wb_set_header_footer( wb, @@ -17,68 +17,59 @@ wb_set_header_footer( ) } \arguments{ -\item{wb}{A workbook object} +\item{wb}{A Workbook object} \item{sheet}{A name or index of a worksheet} -\item{header}{document header. Character vector of length 3 corresponding to positions left, center, right. Use NA to skip a position.} - -\item{footer}{document footer. Character vector of length 3 corresponding to positions left, center, right. Use NA to skip a position.} - -\item{even_header}{document header for even pages.} - -\item{even_footer}{document footer for even pages.} - -\item{first_header}{document header for first page only.} - -\item{first_footer}{document footer for first page only.} +\item{header, even_header, first_header, footer, even_footer, first_footer}{Character vector of length 3 corresponding to positions left, center, +right. \code{header} and \code{footer} are used to default additional arguments. +Setting \code{even}, \code{odd}, or \code{first}, overrides \code{header}/\code{footer}. Use \code{NA} to +skip a position.} \item{...}{additional arguments} } \description{ -Set document headers and footers +Set document headers and footers. You can also do this when adding a worksheet +with \code{\link[=wb_add_worksheet]{wb_add_worksheet()}} with the \code{header}, \code{footer} arguments and friends. +These will show up when printing an xlsx file. } \details{ Headers and footers can contain special tags \itemize{ -\item{\strong{&[Page]}}{ Page number} -\item{\strong{&[Pages]}}{ Number of pages} -\item{\strong{&[Date]}}{ Current date} -\item{\strong{&[Time]}}{ Current time} -\item{\strong{&[Path]}}{ File path} -\item{\strong{&[File]}}{ File name} -\item{\strong{&[Tab]}}{ Worksheet name} +\item \strong{&[Page]} Page number +\item \strong{&[Pages]} Number of pages +\item \strong{&[Date]} Current date +\item \strong{&[Time]} Current time +\item \strong{&[Path]} File path +\item \strong{&[File]} File name +\item \strong{&[Tab]} Worksheet name } } \examples{ wb <- wb_workbook() -wb$add_worksheet("S1") -wb$add_worksheet("S2") -wb$add_worksheet("S3") -wb$add_worksheet("S4") - -wb$add_data(1, 1:400) -wb$add_data(2, 1:400) -wb$add_data(3, 3:400) -wb$add_data(4, 3:400) +# Add example data +wb$add_worksheet("S1")$add_data(x = 1:400) +wb$add_worksheet("S2")$add_data(x = 1:400) +wb$add_worksheet("S3")$add_data(x = 3:400) +wb$add_worksheet("S4")$add_data(x = 3:400) wb$set_header_footer( sheet = "S1", header = c("ODD HEAD LEFT", "ODD HEAD CENTER", "ODD HEAD RIGHT"), footer = c("ODD FOOT RIGHT", "ODD FOOT CENTER", "ODD FOOT RIGHT"), - evenHeader = c("EVEN HEAD LEFT", "EVEN HEAD CENTER", "EVEN HEAD RIGHT"), - evenFooter = c("EVEN FOOT RIGHT", "EVEN FOOT CENTER", "EVEN FOOT RIGHT"), - firstHeader = c("TOP", "OF FIRST", "PAGE"), - firstFooter = c("BOTTOM", "OF FIRST", "PAGE") + even_header = c("EVEN HEAD LEFT", "EVEN HEAD CENTER", "EVEN HEAD RIGHT"), + even_footer = c("EVEN FOOT RIGHT", "EVEN FOOT CENTER", "EVEN FOOT RIGHT"), + first_header = c("TOP", "OF FIRST", "PAGE"), + first_footer = c("BOTTOM", "OF FIRST", "PAGE") ) wb$set_header_footer( sheet = 2, header = c("&[Date]", "ALL HEAD CENTER 2", "&[Page] / &[Pages]"), footer = c("&[Path]&[File]", NA, "&[Tab]"), - firstHeader = c(NA, "Center Header of First Page", NA), - firstFooter = c(NA, "Center Footer of First Page", NA) + first_header = c(NA, "Center Header of First Page", NA), + first_footer = c(NA, "Center Footer of First Page", NA) ) wb$set_header_footer( @@ -89,10 +80,7 @@ wb$set_header_footer( wb$set_header_footer( sheet = 4, - firstHeader = c("FIRST ONLY L", NA, "FIRST ONLY R"), - firstFooter = c("FIRST ONLY L", NA, "FIRST ONLY R") + first_header = c("FIRST ONLY L", NA, "FIRST ONLY R"), + first_footer = c("FIRST ONLY L", NA, "FIRST ONLY R") ) } -\seealso{ -\code{\link[=wb_add_worksheet]{wb_add_worksheet()}} to set headers and footers when adding a worksheet -} diff --git a/man/wb_set_last_modified_by.Rd b/man/wb_set_last_modified_by.Rd index d02ee2dd0..1886310ab 100644 --- a/man/wb_set_last_modified_by.Rd +++ b/man/wb_set_last_modified_by.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_set_last_modified_by} \alias{wb_set_last_modified_by} -\title{Add another author to the meta data of the file.} +\title{Modify author in the metadata of a workbook} \usage{ wb_set_last_modified_by(wb, name, ...) } @@ -14,7 +14,7 @@ wb_set_last_modified_by(wb, name, ...) \item{...}{additional arguments} } \description{ -Just a wrapper of wb$set_last_modified_by() +Just a wrapper of \code{wb$set_last_modified_by()} } \examples{ wb <- wb_workbook() @@ -36,8 +36,8 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, -\code{\link{wb_set_row_heights}()}, \code{\link{wb_workbook}()} } \concept{workbook wrappers} diff --git a/man/wb_set_sheetview.Rd b/man/wb_set_sheetview.Rd index 2dde752bb..4251ab9df 100644 --- a/man/wb_set_sheetview.Rd +++ b/man/wb_set_sheetview.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_set_sheetview} \alias{wb_set_sheetview} -\title{add sheetview} +\title{Modify the default view of a worksheet} \usage{ wb_set_sheetview( wb, @@ -30,27 +30,27 @@ wb_set_sheetview( ) } \arguments{ -\item{wb}{workbook} +\item{wb}{A Workbook object} \item{sheet}{sheet} \item{color_id, default_grid_color}{Integer: A color, default is 64} -\item{right_to_left}{Logical: if TRUE column ordering is right to left} +\item{right_to_left}{Logical: if \code{TRUE} column ordering is right to left} -\item{show_formulas}{Logical: if TRUE cell formulas are shown} +\item{show_formulas}{Logical: if \code{TRUE} cell formulas are shown} -\item{show_grid_lines}{Logical: if TRUE the worksheet grid is shown} +\item{show_grid_lines}{Logical: if \code{TRUE} the worksheet grid is shown} -\item{show_outline_symbols}{Logical: if TRUE outline symbols are shown} +\item{show_outline_symbols}{Logical: if \code{TRUE} outline symbols are shown} -\item{show_row_col_headers}{Logical: if TRUE row and column headers are shown} +\item{show_row_col_headers}{Logical: if \code{TRUE} row and column headers are shown} -\item{show_ruler}{Logical: if TRUE a ruler is shown in page layout view} +\item{show_ruler}{Logical: if \code{TRUE} a ruler is shown in page layout view} -\item{show_white_space}{Logical: if TRUE margins are shown in page layout view} +\item{show_white_space}{Logical: if \code{TRUE} margins are shown in page layout view} -\item{show_zeros}{Logical: if FALSE cells containing zero are shown blank if !showFormulas} +\item{show_zeros}{Logical: if \code{FALSE} cells containing zero are shown blank if \code{show_formulas = FALSE}} \item{tab_selected}{Integer: zero vector indicating the selected tab} @@ -58,7 +58,7 @@ wb_set_sheetview( \item{view}{View: "normal", "pageBreakPreview" or "pageLayout"} -\item{window_protection}{Logical: if TRUE the panes are protected} +\item{window_protection}{Logical: if \code{TRUE} the panes are protected} \item{workbook_view_id}{integer: Pointing to some other view inside the workbook} @@ -67,26 +67,26 @@ wb_set_sheetview( \item{...}{additional arguments} } \value{ -The \code{wbWorksheetObject}, invisibly +The \code{wbWorkbook} object, invisibly } \description{ -add sheetview +This helps set a worksheet's appearance, such as the zoom, whether to show grid lines } \examples{ wb <- wb_workbook()$add_worksheet() wb$set_sheetview( - zoomScale = 75, - rightToLeft = FALSE, - showFormulas = TRUE, - showGridLines = TRUE, - showOutlineSymbols = FALSE, - showRowColHeaders = TRUE, - showRuler = TRUE, - showWhiteSpace = FALSE, - tabSelected = 1, - topLeftCell = "B1", + zoom_scale = 75, + right_to_left = FALSE, + show_formulas = TRUE, + show_grid_lines = TRUE, + show_outline_symbols = FALSE, + show_row_col_headers = TRUE, + show_ruler = TRUE, + show_white_space = FALSE, + tab_selected = 1, + top_left_cell = "B1", view = "normal", - windowProtection = TRUE + window_protection = TRUE ) } diff --git a/man/wb_sheet_names.Rd b/man/wb_sheet_names.Rd index 86ebd9eac..91bd1e52e 100644 --- a/man/wb_sheet_names.Rd +++ b/man/wb_sheet_names.Rd @@ -11,18 +11,18 @@ wb_set_sheet_names(wb, old = NULL, new) wb_get_sheet_names(wb, escape = FALSE) } \arguments{ -\item{wb}{A \code{wbWorkbook} object} +\item{wb}{A \link{wbWorkbook} object} \item{old}{The name (or index) of the old sheet name. If \code{NULL} will assume all worksheets are to be renamed.} \item{new}{The name of the new sheet} -\item{escape}{Logical if the xml special characters are escaped} +\item{escape}{Should the xml special characters be escaped?} } \value{ \itemize{ -\item \code{set_}: The \link{wbWorkbook} object. +\item \code{set_}: The \code{wbWorkbook} object. \item \code{get_}: A named character vector of sheet names in order. The names represent the original value of the worksheet prior to any character substitutions. @@ -33,6 +33,6 @@ Gets / Sets the worksheet names for a \link{wbWorkbook} object. } \details{ This only changes the sheet name as shown in spreadsheet software -and will not alter it anywhere else. Not in formulas, chart references, +and will not alter it elsewhere. Not in formulas, chart references, named regions, pivot tables or anywhere else. } diff --git a/man/sheet_visibility.Rd b/man/wb_sheet_visibility.Rd similarity index 58% rename from man/sheet_visibility.Rd rename to man/wb_sheet_visibility.Rd index d89144ff4..17f75aa6e 100644 --- a/man/sheet_visibility.Rd +++ b/man/wb_sheet_visibility.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/class-workbook-wrappers.R -\name{sheet_visibility} -\alias{sheet_visibility} +\name{wb_sheet_visibility} +\alias{wb_sheet_visibility} \alias{wb_get_sheet_visibility} \alias{wb_set_sheet_visibility} -\title{Get/set worksheet visible state} +\title{Get/set worksheet visible state in a workbook} \usage{ wb_get_sheet_visibility(wb) @@ -15,15 +15,19 @@ wb_set_sheet_visibility(wb, sheet = current_sheet(), value) \item{sheet}{Worksheet identifier} -\item{value}{a logical/character vector the same length as sheet} +\item{value}{a logical/character vector the same length as sheet, +if provding a character vector, you can provide any of "hidden", "visible", or "veryHidden"} } \value{ -Character vector of worksheet names. - -Vector of "hidden", "visible", "veryHidden" +\itemize{ +\item \code{wb_set_sheet_visibility}: The Worbook object, invisibly. +\item \code{wb_get_sheet_visibility()}: A character vector of the worksheet visibility value +} } \description{ -Get and set worksheet visible state +Get and set worksheet visible state. This allows to hide worksheets from the workbook. +The visibility of a worksheet can either be "visible", "hidden", or "veryHidden". +You can set this when creating a worksheet with \code{wb_add_worksheet(visible = FALSE)} } \examples{ diff --git a/man/wb_to_df.Rd b/man/wb_to_df.Rd index e47903ee6..e52bc1e18 100644 --- a/man/wb_to_df.Rd +++ b/man/wb_to_df.Rd @@ -4,7 +4,7 @@ \alias{wb_to_df} \alias{read_xlsx} \alias{wb_read} -\title{Create Dataframe from Workbook} +\title{Create a data frame from a Workbook} \usage{ wb_to_df( file, @@ -70,7 +70,7 @@ wb_read( ) } \arguments{ -\item{file}{An xlsx file, Workbook object or URL to xlsx file.} +\item{file}{An xlsx file, \link{wbWorkbook} object or URL to xlsx file.} \item{sheet}{Either sheet name or index. When missing the first sheet in the workbook is selected.} @@ -90,10 +90,10 @@ wb_read( \item{skip_hidden_cols}{If \code{TRUE}, hidden columns are skipped.} -\item{rows}{A numeric vector specifying which rows in the Excel file to read. +\item{rows}{A numeric vector specifying which rows in the xlsx file to read. If \code{NULL}, all rows are read.} -\item{cols}{A numeric vector specifying which columns in the Excel file to read. +\item{cols}{A numeric vector specifying which columns in the xlsx file to read. If \code{NULL}, all columns are read.} \item{detect_dates}{If \code{TRUE}, attempt to recognize dates and perform conversion.} @@ -116,7 +116,7 @@ Blank cells will be returned as \code{NA}.} Names must match the returned data. See \strong{Details} for more.} \item{named_region}{Character string with a \code{named_region} (defined name or table). -If no sheet is selected, the first appearance will be selected.} +If no sheet is selected, the first appearance will be selected. See \code{\link[=wb_get_named_regions]{wb_get_named_regions()}}} \item{keep_attributes}{If \code{TRUE} additional attributes are returned. (These are used internally to define a cell type.)} @@ -125,8 +125,8 @@ If no sheet is selected, the first appearance will be selected.} } \description{ Simple function to create a \code{data.frame} from a workbook. Simple as in simply -written down. \code{\link[=read_xlsx]{read_xlsx()}} and \code{\link[=wb_read]{wb_read()}} are just internal wrappers for -\code{\link[=wb_to_df]{wb_to_df()}} intended for people coming from other packages. +written down. \code{read_xlsx()} and \code{wb_read()} are just internal wrappers of +\code{wb_to_df()} intended for people coming from other packages. } \details{ Depending if the R package \code{hms} is loaded, \code{wb_to_df()} returns @@ -137,13 +137,14 @@ The \code{types} argument must be a named numeric. \item 0: character \item 1: numeric \item 2: date -\item 3: posixt +\item 3: posixt (datetime) \item 4: logical } -Formulae written using write_formula to a Workbook object will not get picked up by \code{read_xlsx()}. -This is because only the formula is written and left to be evaluated when the file is opened in Excel. -Opening, saving and closing the file with Excel will resolve this. +\code{read_xlsx()} will not pick up formulas added to a Workbook object +via \code{\link[=wb_add_formula]{wb_add_formula()}}. This is because only the formula is written and left +to be evaluated when the file is opened in a spreadsheet software. +Opening, saving and closing the file in a spreadsheet software will resolve this. } \examples{ ########################################################################### @@ -194,7 +195,7 @@ wb_to_df(wb1, start_row = 5, col_names = FALSE) wb_to_df(wb1, na.strings = "a") ########################################################################### -# named_region // namedRegion +# Named regions file_named_region <- system.file("extdata", "namedRegions3.xlsx", package = "openxlsx2") wb2 <- wb_load(file_named_region) diff --git a/man/wb_update_table.Rd b/man/wb_update_table.Rd index 9c8835d32..49351a26d 100644 --- a/man/wb_update_table.Rd +++ b/man/wb_update_table.Rd @@ -2,24 +2,25 @@ % Please edit documentation in R/class-workbook-wrappers.R \name{wb_update_table} \alias{wb_update_table} -\title{update a data_table} +\title{Update a data table position in a worksheet} \usage{ wb_update_table(wb, sheet = current_sheet(), dims = "A1", tabname) } \arguments{ -\item{wb}{workbook} +\item{wb}{A workbook} -\item{sheet}{a worksheet} +\item{sheet}{A worksheet} -\item{dims}{cell used as start} +\item{dims}{Cell range used for new data table.} -\item{tabname}{a tablename} +\item{tabname}{A table name} } \description{ -update a data_table +Update the position of a data table, possibly written using \code{\link[=wb_add_data_table]{wb_add_data_table()}} } \details{ -Be aware that this function does not alter any filter. Excluding or adding rows does not make rows appear nor will it hide them. +Be aware that this function does not alter any filter. +Excluding or adding rows does not make rows appear nor will it hide them. } \examples{ wb <- wb_workbook()$add_worksheet()$add_data_table(x = mtcars) diff --git a/man/wb_workbook.Rd b/man/wb_workbook.Rd index 899d0b6c6..17d93e92b 100644 --- a/man/wb_workbook.Rd +++ b/man/wb_workbook.Rd @@ -27,10 +27,10 @@ See \strong{Details} for options.} \item{...}{additional arguments} } \value{ -A \link{wbWorkbook} object +A \code{wbWorkbook} object } \description{ -Create a new Workbook object +Initialize a \link{wbWorkbook} object. You can set workbook properties as well. } \details{ \code{theme} can be one of @@ -68,8 +68,8 @@ Other workbook wrappers: \code{\link{wb_freeze_pane}()}, \code{\link{wb_grouping}}, \code{\link{wb_merge_cells}()}, +\code{\link{wb_row_heights}}, \code{\link{wb_save}()}, -\code{\link{wb_set_last_modified_by}()}, -\code{\link{wb_set_row_heights}()} +\code{\link{wb_set_last_modified_by}()} } \concept{workbook wrappers} diff --git a/man/write_data.Rd b/man/write_data.Rd index 1286fb0a2..e984f9862 100644 --- a/man/write_data.Rd +++ b/man/write_data.Rd @@ -31,30 +31,32 @@ write_data( \item{x}{Object to be written. For classes supported look at the examples.} -\item{dims}{Spreadsheet dimensions that will determine startCol and startRow: "A1", "A1:B2", "A:B"} +\item{dims}{Spreadsheet cell range that will determine \code{start_col} and \code{start_row}: "A1", "A1:B2", "A:B"} -\item{start_col}{A vector specifying the starting column to write to.} +\item{start_col}{A vector specifying the starting column to write \code{x} to.} -\item{start_row}{A vector specifying the starting row to write to.} +\item{start_row}{A vector specifying the starting row to write \code{x} to.} \item{array}{A bool if the function written is of type array} -\item{col_names}{If \code{TRUE}, column names of x are written.} +\item{col_names}{If \code{TRUE}, column names of \code{x} are written.} -\item{row_names}{If \code{TRUE}, data.frame row names of x are written.} +\item{row_names}{If \code{TRUE}, the row names of \code{x} are written.} -\item{with_filter}{If \code{TRUE}, add filters to the column name row. NOTE can only have one filter per worksheet.} +\item{with_filter}{If \code{TRUE}, add filters to the column name row. +NOTE: can only have one filter per worksheet.} -\item{sep}{Only applies to list columns. The separator used to collapse list columns to a character vector e.g. sapply(x$list_column, paste, collapse = sep).} +\item{sep}{Only applies to list columns. The separator used to collapse list +columns to a character vector e.g. \code{sapply(x$list_column, paste, collapse = sep)}.} -\item{name}{If not NULL, a named region is defined.} +\item{name}{The name of a named region if specified.} -\item{apply_cell_style}{apply styles when writing on the sheet} +\item{apply_cell_style}{Should we write cell styles to the workbook} -\item{remove_cell_style}{if writing into existing cells, should the cell style be removed?} +\item{remove_cell_style}{keep the cell style?} \item{na.strings}{Value used for replacing \code{NA} values from \code{x}. Default -\code{na_strings()} uses the special \verb{#N/A} value within the workbook.} +\code{\link[=na_strings]{na_strings()}} uses the special \verb{#N/A} value within the workbook.} \item{inline_strings}{write characters as inline strings} @@ -64,66 +66,24 @@ write_data( invisible(0) } \description{ -Write an object to worksheet with optional styling. Use \code{\link[=wb_add_data]{wb_add_data()}} in new code. +Write an object to worksheet with optional styling. Use \code{\link[=wb_add_data]{wb_add_data()}} or \code{\link[=write_xlsx]{write_xlsx()}} in new code. } \details{ -Formulae written using write_formula to a Workbook object will not get picked up by read_xlsx(). +Formulae written using \code{\link[=wb_add_formula]{wb_add_formula()}} to a Workbook object will not get picked up by \code{read_xlsx()}. This is because only the formula is written and left to Excel to evaluate the formula when the file is opened in Excel. The string \code{"_openxlsx_NA"} is reserved for \code{openxlsx2}. If the data frame contains this string, the output will be broken. } \examples{ -## See formatting vignette for further examples. - -## Options for default styling (These are the defaults) -options("openxlsx2.dateFormat" = "mm/dd/yyyy") -options("openxlsx2.datetimeFormat" = "yyyy-mm-dd hh:mm:ss") -options("openxlsx2.numFmt" = NULL) - -############################################################################# -## Create Workbook object and add worksheets -wb <- wb_workbook() - -## Add worksheets -wb$add_worksheet("Cars") -wb$add_worksheet("Formula") - -x <- mtcars[1:6, ] -wb$add_data("Cars", x, startCol = 2, startRow = 3, rowNames = TRUE) - -############################################################################# -## Hyperlinks -## - vectors/columns with class 'hyperlink' are written as hyperlinks' - -v <- rep("https://CRAN.R-project.org/", 4) -names(v) <- paste0("Hyperlink", 1:4) # Optional: names will be used as display text -class(v) <- "hyperlink" -wb$add_data("Cars", x = v, dims = c("B32")) - -############################################################################# -## Formulas -## - vectors/columns with class 'formula' are written as formulas' - -df <- data.frame( - x = 1:3, y = 1:3, - z = paste(paste0("A", 1:3 + 1L), paste0("B", 1:3 + 1L), sep = "+"), - stringsAsFactors = FALSE -) - -class(df$z) <- c(class(df$z), "formula") - -wb$add_data(sheet = "Formula", x = df) - -############################################################################# # update cell range and add mtcars xlsxFile <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2") wb2 <- wb_load(xlsxFile) # read dataset with inlinestr wb_to_df(wb2) -write_data(wb2, 1, mtcars, startCol = 4, startRow = 4) +write_data(wb2, 1, mtcars, start_col = 4, start_row = 4) wb_to_df(wb2) } \seealso{ -\code{\link[=wb_add_data]{wb_add_data()}}, \code{\link[=wb_add_data_table]{wb_add_data_table()}} +\code{\link[=wb_add_data]{wb_add_data()}}, \code{\link[=write_xlsx]{write_xlsx()}} } \keyword{internal} diff --git a/man/write_datatable.Rd b/man/write_datatable.Rd index 45c24e1e4..d6594f3fa 100644 --- a/man/write_datatable.Rd +++ b/man/write_datatable.Rd @@ -33,45 +33,47 @@ write_datatable( \item{sheet}{The worksheet to write to. Can be the worksheet index or name.} -\item{x}{A data frame.} +\item{x}{A data frame} -\item{dims}{Spreadsheet dimensions that will determine startCol and startRow: "A1", "A1:B2", "A:B"} +\item{dims}{Spreadsheet cell range that will determine \code{start_col} and \code{start_row}: "A1", "A1:B2", "A:B"} -\item{start_col}{A vector specifying the starting column to write df} +\item{start_col}{A vector specifying the starting column to write \code{x} to.} -\item{start_row}{A vector specifying the starting row to write df} +\item{start_row}{A vector specifying the starting row to write \code{x} to.} -\item{col_names}{If \code{TRUE}, column names of x are written.} +\item{col_names}{If \code{TRUE}, column names of \code{x} are written.} -\item{row_names}{If \code{TRUE}, row names of x are written.} +\item{row_names}{If \code{TRUE}, the row names of \code{x} are written.} -\item{table_style}{Any excel table style name or "none" (see "formatting" vignette).} +\item{table_style}{Any table style name or "none" (see \code{vignette("openxlsx2_style_manual")})} -\item{table_name}{name of table in workbook. The table name must be unique.} +\item{table_name}{Name of table in workbook. The table name must be unique.} \item{with_filter}{If \code{TRUE}, columns with have filters in the first row.} -\item{sep}{Only applies to list columns. The separator used to collapse list columns to a character vector e.g. sapply(x$list_column, paste, collapse = sep). +\item{sep}{Only applies to list columns. The separator used to collapse list +columns to a character vector e.g. +\code{sapply(x$list_column, paste, collapse = sep)}. \cr\cr \cr\strong{The below options correspond to Excel table options:} \cr \if{html}{\figure{tableoptions.png}{options: width="40\%" alt="Figure: table_options.png"}} \if{latex}{\figure{tableoptions.pdf}{options: width=7cm}}} -\item{first_column}{logical. If TRUE, the first column is bold} +\item{first_column}{logical. If \code{TRUE}, the first column is bold.} -\item{last_column}{logical. If TRUE, the last column is bold} +\item{last_column}{logical. If \code{TRUE}, the last column is bold.} -\item{banded_rows}{logical. If TRUE, rows are color banded} +\item{banded_rows}{logical. If \code{TRUE}, rows are color banded.} -\item{banded_cols}{logical. If TRUE, the columns are color banded} +\item{banded_cols}{logical. If \code{TRUE}, the columns are color banded.} -\item{apply_cell_style}{apply styles when writing on the sheet} +\item{apply_cell_style}{Should we write cell styles to the workbook} -\item{remove_cell_style}{if writing into existing cells, should the cell style be removed?} +\item{remove_cell_style}{keep the cell style?} \item{na.strings}{Value used for replacing \code{NA} values from \code{x}. Default -\code{na_strings()} uses the special \verb{#N/A} value within the workbook.} +\code{\link[=na_strings]{na_strings()}} uses the special \verb{#N/A} value within the workbook.} \item{inline_strings}{write characters as inline strings} @@ -81,11 +83,12 @@ write_datatable( Write to a worksheet and format as an Excel table. Use \code{\link[=wb_add_data_table]{wb_add_data_table()}} in new code. } \details{ -columns of x with class Date/POSIXt, currency, accounting, -hyperlink, percentage are automatically styled as dates, currency, accounting, -hyperlinks, percentages respectively. -The string \code{"_openxlsx_NA"} is reserved for \code{openxlsx2}. If the data frame -contains this string, the output will be broken. +The columns of \code{x} with class Date/POSIXt, currency, accounting, hyperlink, +percentage are automatically styled as dates, currency, accounting, hyperlinks, +percentages respectively. + +The string \code{"_openxlsx_NA"} is reserved for \code{openxlsx2}. If \code{x} contains this +string, the output will be broken. } \examples{ ## see package vignettes for further examples. @@ -104,8 +107,8 @@ wb$add_worksheet("S3") wb$add_data_table("S1", x = iris) wb$add_data_table("S2", - x = mtcars, dims = c("B3"), rowNames = TRUE, - tableStyle = "TableStyleLight9" + x = mtcars, dims = c("B3"), row_names = TRUE, + table_style = "TableStyleLight9" ) df <- data.frame( @@ -125,7 +128,7 @@ class(df$hLink) <- "hyperlink" class(df$Percentage) <- c(class(df$Percentage), "percentage") class(df$TinyNumbers) <- c(class(df$TinyNumbers), "scientific") -wb$add_data_table("S3", x = df, startRow = 4, rowNames = TRUE, tableStyle = "TableStyleMedium9") +wb$add_data_table("S3", x = df, start_row = 4, row_names = TRUE, table_style = "TableStyleMedium9") ##################################################################################### ## Additional Header Styling and remove column filters @@ -133,12 +136,12 @@ wb$add_data_table("S3", x = df, startRow = 4, rowNames = TRUE, tableStyle = "Tab write_datatable(wb, sheet = 1, x = iris, - startCol = 7, - withFilter = FALSE, - firstColumn = TRUE, - lastColumn = TRUE, - bandedRows = TRUE, - bandedCols = TRUE + start_col = 7, + with_filter = FALSE, + first_column = TRUE, + last_column = TRUE, + banded_rows = TRUE, + banded_cols = TRUE ) ##################################################################################### @@ -150,7 +153,7 @@ for (i in 1:21) { style <- paste0("TableStyleLight", i) write_datatable(wb, x = data.frame(style), sheet = 1, - tableStyle = style, startRow = 1, startCol = i * 3 - 2 + table_style = style, start_row = 1, start_col = i * 3 - 2 ) } @@ -158,7 +161,7 @@ for (i in 1:28) { style <- paste0("TableStyleMedium", i) write_datatable(wb, x = data.frame(style), sheet = 1, - tableStyle = style, startRow = 4, startCol = i * 3 - 2 + table_style = style, start_row = 4, start_col = i * 3 - 2 ) } @@ -166,7 +169,7 @@ for (i in 1:11) { style <- paste0("TableStyleDark", i) write_datatable(wb, x = data.frame(style), sheet = 1, - tableStyle = style, startRow = 7, startCol = i * 3 - 2 + table_style = style, start_row = 7, start_col = i * 3 - 2 ) } } diff --git a/man/xl_open.Rd b/man/xl_open.Rd index 17849107f..d5b2d3559 100644 --- a/man/xl_open.Rd +++ b/man/xl_open.Rd @@ -4,7 +4,7 @@ \alias{xl_open} \alias{xl_open.wbWorkbook} \alias{xl_open.default} -\title{Open a Microsoft Excel file (xls/xlsx) or an openxlsx2 wbWorkbook} +\title{Open an xlsx file or a \code{wbWorkbook} object} \usage{ xl_open(x, interactive = NA) @@ -13,7 +13,7 @@ xl_open(x, interactive = NA) \method{xl_open}{default}(x, interactive = NA) } \arguments{ -\item{x}{A path to the Excel (xls/xlsx) file or Workbook object.} +\item{x}{A path to the Excel (xls/xlsx) file or wbWorkbook object.} \item{interactive}{If \code{FALSE} will throw a warning and not open the path. This can be manually set to \code{TRUE}, otherwise when \code{NA} (default) uses the @@ -21,14 +21,14 @@ value returned from \code{\link[base:interactive]{base::interactive()}}} } \description{ This function tries to open a Microsoft Excel (xls/xlsx) file or, -an openxlsx2 wbWorkbook with the proper application, in a portable manner. +an \link{wbWorkbook} with the proper application, in a portable manner. On Windows it uses \code{base::shell.exec()} (Windows only function) to determine the appropriate program. -In Mac (c) it uses system default handlers, given the file type. +On Mac, (c) it uses system default handlers, given the file type. -In Linux it searches (via \code{which}) for available xls/xlsx reader +On Linux, it searches (via \code{which}) for available xls/xlsx reader applications (unless \code{options('openxlsx2.excelApp')} is set to the app bin path), and if it finds anything, sets \code{options('openxlsx2.excelApp')} to the program chosen by the user via a menu (if many are present, otherwise it @@ -39,14 +39,14 @@ Sheets (\code{calligrasheets}). \examples{ \donttest{ if (interactive()) { - xlsxFile <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2") - xl_open(xlsxFile) + xlsx_file <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2") + xl_open(xlsx_file) # (not yet saved) Workbook example wb <- wb_workbook() x <- mtcars[1:6, ] wb$add_worksheet("Cars") - wb$add_data("Cars", x, startCol = 2, startRow = 3, rowNames = TRUE) + wb$add_data("Cars", x, start_col = 2, start_row = 3, row_names = TRUE) xl_open(wb) } }