diff --git a/R/class-workbook-wrappers.R b/R/class-workbook-wrappers.R index cb12da40e..1075e1722 100644 --- a/R/class-workbook-wrappers.R +++ b/R/class-workbook-wrappers.R @@ -846,17 +846,15 @@ wb_remove_row_heights <- function(wb, sheet = current_sheet(), rows) { #' #' @param wb A workbook object #' @param sheet A name or index of a worksheet -#' @param startRow Row coordinate of upper left corner of figure. -#' @param startCol Column coordinate of upper left corner of figure. -#' @param rowOffset offset within cell (row) -#' @param colOffset offset within cell (column) +#' @param dims Worksheet dimension, single cell ("A1") or cell range ("A1:D4") +#' @param row_offset,col_offset offset for column and row #' @param width Width of figure. Defaults to `6`in. #' @param height Height of figure . Defaults to `4`in. -#' @param fileType File type of image +#' @param file_type File type of image #' @param units Units of width and height. Can be `"in"`, `"cm"` or `"px"` #' @param dpi Image resolution -#' @param dims Worksheet dimension, single cell ("A1") or cell range ("A1:D4") -#' @seealso [wb_add_image()] +#' @param ... additional arguments +#' @seealso [wb_add_chart_xml()] [wb_add_drawing()] [wb_add_image()] [wb_add_mschart()] #' @export #' @examples #' if (requireNamespace("ggplot2") && interactive()) { @@ -885,40 +883,39 @@ wb_remove_row_heights <- function(wb, sheet = current_sheet(), rows) { #' } wb_add_plot <- function( wb, - sheet = current_sheet(), - width = 6, - height = 4, - startRow = 1, - startCol = 1, - rowOffset = 0, - colOffset = 0, - fileType = "png", - units = "in", - dpi = 300, - dims = rowcol_to_dim(startRow, startCol) + sheet = current_sheet(), + dims = "A1", + width = 6, + height = 4, + row_offset = 0, + col_offset = 0, + file_type = "png", + units = "in", + dpi = 300, + ... ) { assert_workbook(wb) wb$clone()$add_plot( - sheet = sheet, - width = width, - height = height, - startRow = startRow, - startCol = startCol, - rowOffset = rowOffset, - colOffset = colOffset, - fileType = fileType, - units = units, - dpi = dpi, - dims = dims + sheet = sheet, + dims = dims, + width = width, + height = height, + row_offset = row_offset, + col_offset = col_offset, + file_type = file_type, + units = units, + dpi = dpi, + ... = ... ) } #' add drawings to workbook #' @param wb a wbWorkbook #' @param sheet a sheet in the workbook -#' @param xml the drawing xml as character or file #' @param dims the dimension where the drawing is added. Can be NULL -#' @param colOffset,rowOffset offsets for column and row +#' @param xml the drawing xml as character or file +#' @param col_offset,row_offset offsets for column and row +#' @param ... additional arguments #' @examples #' if (requireNamespace("rvg") && interactive()) { #' @@ -934,22 +931,86 @@ wb_add_plot <- function( #' add_drawing(xml = tmp)$ #' add_drawing(xml = tmp, dims = NULL) #' } +#' @seealso [wb_add_chart_xml()] [wb_add_image()] [wb_add_mschart()] [wb_add_plot()] #‘ @export wb_add_drawing <- function( wb, - sheet = current_sheet(), + sheet = current_sheet(), + dims = "A1", xml, - dims = NULL, - colOffset = 0, - rowOffset = 0 + col_offset = 0, + row_offset = 0, + ... ) { assert_workbook(wb) wb$clone()$add_drawing( - sheet = sheet, - xml = xml, - dims = dims, - colOffset = colOffset, - rowOffset = rowOffset + sheet = sheet, + dims = dims, + xml = xml, + col_offset = col_offset, + row_offset = row_offset, + ... = ... + ) +} + +#' Add mschart object to an existing workbook +#' @param wb a workbook +#' @param sheet the sheet on which the graph will appear +#' @param dims the dimensions where the sheet will appear +#' @param graph mschart object +#' @param col_offset,row_offset offsets for column and row +#' @param ... additional arguments +#' @examples +#' if (requireNamespace("mschart")) { +#' require(mschart) +#' +#' ## Add mschart to worksheet (adds data and chart) +#' scatter <- ms_scatterchart(data = iris, x = "Sepal.Length", y = "Sepal.Width", group = "Species") +#' scatter <- chart_settings(scatter, scatterstyle = "marker") +#' +#' wb <- wb_workbook() %>% +#' wb_add_worksheet() %>% +#' wb_add_mschart(dims = "F4:L20", graph = scatter) +#' +#' ## Add mschart to worksheet and use available data +#' wb <- wb_workbook() %>% +#' wb_add_worksheet() %>% +#' wb_add_data(x = mtcars, dims = "B2") +#' +#' # create wb_data object +#' dat <- wb_data(wb, 1, dims = "B2:E6") +#' +#' # call ms_scatterplot +#' data_plot <- ms_scatterchart( +#' data = dat, +#' x = "mpg", +#' y = c("disp", "hp"), +#' labels = c("disp", "hp") +#' ) +#' +#' # add the scatterplot to the data +#' wb <- wb %>% +#' wb_add_mschart(dims = "F4:L20", graph = data_plot) +#' } +#' @seealso [wb_data()] [wb_add_chart_xml()] [wb_add_image] [wb_add_mschart()] [wb_add_plot] +#' @export +wb_add_mschart <- function( + wb, + sheet = current_sheet(), + dims = NULL, + graph, + col_offset = 0, + row_offset = 0, + ... +) { + assert_workbook(wb) + wb$clone()$add_mschart( + sheet = sheet, + dims = dims, + graph = graph, + col_offset = col_offset, + row_offset = row_offset, + ... = ... ) } @@ -2171,59 +2232,52 @@ wb_set_last_modified_by <- function(wb, LastModifiedBy) { #' #' @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 file An image file. Valid file types are:` "jpeg"`, `"png"`, `"bmp"` #' @param width Width of figure. #' @param height Height of figure. -#' @param startRow Row coordinate of upper left corner of the image -#' @param startCol Column coordinate of upper left corner of the image -#' @param rowOffset offset vector for one or two cell anchor within cell (row) -#' @param colOffset offset vector for one or two cell anchor within cell (column) +#' @param row_offset offset vector for one or two cell anchor within cell (row) +#' @param col_offset offset vector for one or two cell anchor within cell (column) #' @param units Units of width and height. Can be `"in"`, `"cm"` or `"px"` #' @param dpi Image resolution used for conversion between units. -#' @param dims Dimensions where to plot. Default absolute anchor, single cell (eg. "A1") oneCellAnchor, cell range (eg. "A1:D4") twoCellAnchor -#' @seealso [wb_add_plot()] +#' @param ... additional arguments +#' @seealso [wb_add_chart_xml()] [wb_add_drawing()] [wb_add_mschart()] [wb_add_plot()] #' @export #' @examples -#' ## Create a new workbook -#' wb <- wb_workbook("Ayanami") -#' -#' ## Add some worksheets -#' wb$add_worksheet("Sheet 1") -#' wb$add_worksheet("Sheet 2") -#' wb$add_worksheet("Sheet 3") -#' -#' ## Insert images #' img <- system.file("extdata", "einstein.jpg", package = "openxlsx2") -#' wb$add_image("Sheet 1", img, startRow = 5, startCol = 3, width = 6, height = 5) -#' wb$add_image(2, img, startRow = 2, startCol = 2) -#' wb$add_image(3, img, width = 15, height = 12, startRow = 3, startCol = "G", units = "cm") +#' +#' wb <- wb_workbook()$ +#' add_worksheet()$ +#' add_image("Sheet 1", dims = "C5", file = img, width = 6, height = 5)$ +#' add_worksheet()$ +#' add_image(dims = "B2", file = img)$ +#' add_worksheet()$ +#' add_image(dims = "G3", file = img, width = 15, height = 12, units = "cm") wb_add_image <- function( wb, - sheet = current_sheet(), + sheet = current_sheet(), + dims = "A1", file, - width = 6, - height = 3, - startRow = 1, - startCol = 1, - rowOffset = 0, - colOffset = 0, - units = "in", - dpi = 300, - dims = rowcol_to_dim(startRow, startCol) + width = 6, + height = 3, + row_offset = 0, + col_offset = 0, + units = "in", + dpi = 300, + ... ) { assert_workbook(wb) wb$clone()$add_image( - sheet = sheet, - file = file, - startRow = startRow, - startCol = startCol, - width = width, - height = height, - rowOffset = rowOffset, - colOffset = colOffset, - units = units, - dpi = dpi, - dims = dims + sheet = sheet, + dims = dims, + file = file, + width = width, + height = height, + row_offset = row_offset, + col_offset = col_offset, + units = units, + dpi = dpi, + ... ) } @@ -2231,20 +2285,30 @@ wb_add_image <- function( #' add a chart xml to a workbook #' @param wb a workbook #' @param sheet the sheet on which the graph will appear -#' @param xml chart xml #' @param dims the dimensions where the sheet will appear -#' @param colOffset,rowOffset startCol and startRow +#' @param xml chart xml +#' @param col_offset,row_offset positioning +#' @param ... additional arguments +#' @seealso [wb_add_drawing()] [wb_add_image()] [wb_add_mschart()] [wb_add_plot()] #' @export wb_add_chart_xml <- function( wb, - sheet = current_sheet(), + sheet = current_sheet(), + dims = NULL, xml, - dims = NULL, - colOffset = 0, - rowOffset = 0 + col_offset = 0, + row_offset = 0, + ... ) { assert_workbook(wb) - wb$clone()$add_chart_xml(sheet, xml, dims, colOffset, rowOffset) + wb$clone()$add_chart_xml( + sheet = sheet, + xml = xml, + dims = dims, + col_offset = col_offset, + row_offset = row_offset, + ... = ... + ) } diff --git a/R/class-workbook.R b/R/class-workbook.R index 62313babe..821d8821c 100644 --- a/R/class-workbook.R +++ b/R/class-workbook.R @@ -1466,26 +1466,29 @@ wbWorkbook <- R6::R6Class( ### load workbook ---- #' @description load workbook #' @param file file - #' @param xlsxFile xlsxFile + #' @param xlsx_file xlsx_file #' @param sheet sheet #' @param data_only data_only #' @param calc_chain calc_chain + #' @param ... additional arguments #' @return The `wbWorkbook` object invisibly load = function( file, - xlsxFile = NULL, + xlsx_file = NULL, sheet, data_only = FALSE, - calc_chain = FALSE + calc_chain = FALSE, + ... ) { if (missing(file)) file <- substitute() if (missing(sheet)) sheet <- substitute() self <- wb_load( file = file, - xlsxFile = xlsxFile, + xlsx_file = xlsx_file, sheet = sheet, data_only = data_only, - calc_chain = calc_chain + calc_chain = calc_chain, + ... = ... ) invisible(self) }, @@ -4009,36 +4012,39 @@ wbWorkbook <- R6::R6Class( #' @description #' Insert an image into a sheet #' @param sheet sheet + #' @param dims dims #' @param file file - #' @param startRow startRow - #' @param startCol startCol #' @param width width #' @param height height - #' @param rowOffset rowOffset - #' @param colOffset colOffset + #' @param row_offset,col_offset offsets #' @param units units #' @param dpi dpi - #' @param dims dims + #' @param ... additional arguments #' @return The `wbWorkbook` object, invisibly add_image = function( sheet = current_sheet(), + dims = "A1", file, width = 6, height = 3, - startRow = 1, - startCol = 1, - rowOffset = 0, - colOffset = 0, + row_offset = 0, + col_offset = 0, units = "in", dpi = 300, - dims = rowcol_to_dim(startRow, startCol) + ... ) { - if (!file.exists(file)) { - stop("File ", file, " does not exist.") + + standardize_case_names(...) + + if (exists("start_row") && !is.null(start_row) && + exists("start_col") && !is.null(start_col)) { + .Deprecated(old = "start_col/start_row", new = "dims", package = "openxlsx2") + start_col <- col2int(start_col) + start_row <- as.integer(start_row) } - if (is.null(dims) && (startRow > 1 || startCol > 1)) { - warning("dims is NULL, startRow/startCol will have no impact") + if (!file.exists(file)) { + stop("File ", file, " does not exist.") } # TODO require user to pass a valid path @@ -4053,9 +4059,6 @@ wbWorkbook <- R6::R6Class( stop("Invalid units.\nunits must be one of: cm, in, px") } - startCol <- col2int(startCol) - startRow <- as.integer(startRow) - ## convert to inches if (units == "px") { width <- width / dpi @@ -4076,8 +4079,6 @@ wbWorkbook <- R6::R6Class( imageType <- gsub("^\\.", "", imageType) mediaNo <- length(self$media) + 1L - startCol <- col2int(startCol) - ## update Content_Types if (!any(grepl(stri_join("image/", imageType), self$Content_Types))) { self$Content_Types <- @@ -4129,8 +4130,13 @@ wbWorkbook <- R6::R6Class( xml_attributes = xml_attr ) - self$add_drawing(sheet, drawing, dims, colOffset, rowOffset) - + self$add_drawing( + sheet = sheet, + dims = dims, + xml = drawing, + col_offset = col_offset, + row_offset = row_offset + ) # add image to drawings_rels old_drawings_rels <- unlist(self$drawings_rels[[sheet_drawing]]) @@ -4153,36 +4159,40 @@ wbWorkbook <- R6::R6Class( #' @description Add plot. A wrapper for add_image() #' @param sheet sheet + #' @param dims dims #' @param width width #' @param height height - #' @param startRow startRow - #' @param startCol startCol - #' @param rowOffset rowOffset - #' @param colOffset colOffset - #' @param fileType fileType + #' @param row_offset,col_offset offsets + #' @param file_type fileType #' @param units units #' @param dpi dpi - #' @param dims dims + #' @param ... additional arguments #' @returns The `wbWorkbook` object add_plot = function( - sheet = current_sheet(), - width = 6, - height = 4, - startRow = 1, - startCol = 1, - rowOffset = 0, - colOffset = 0, - fileType = "png", - units = "in", - dpi = 300, - dims = rowcol_to_dim(startRow, startCol) + sheet = current_sheet(), + dims = "A1", + width = 6, + height = 4, + row_offset = 0, + col_offset = 0, + file_type = "png", + units = "in", + dpi = 300, + ... ) { + + args <- list(...) + if (!is.null(args$start_row) && !is.null(args$start_col)) { + .Deprecated(old = "start_row/start_col", new = "dims", package = "openxlsx2") + dims <- rowcol_to_dims(args$start_row, args$start_col) + } + if (is.null(dev.list()[[1]])) { warning("No plot to insert.") return(invisible(self)) } - fileType <- tolower(fileType) + fileType <- tolower(file_type) units <- tolower(units) # TODO just don't allow jpg @@ -4199,7 +4209,7 @@ wbWorkbook <- R6::R6Class( stop("Invalid units.\nunits must be one of: cm, in, px") } - fileName <- tempfile(pattern = "figureImage", fileext = paste0(".", fileType)) + fileName <- tempfile(pattern = "figureImage", fileext = paste0(".", file_type)) # Workaround for wrapper test. Otherwise tempfile names differ if (requireNamespace("testthat")) { @@ -4222,17 +4232,15 @@ wbWorkbook <- R6::R6Class( stopifnot(file.exists(fileName)) self$add_image( - sheet = sheet, - file = fileName, - width = width, - height = height, - startRow = startRow, - startCol = startCol, - rowOffset = rowOffset, - colOffset = colOffset, - units = units, - dpi = dpi, - dims = dims + sheet = sheet, + dims = dims, + file = fileName, + width = width, + height = height, + row_offset = row_offset, + col_offset = col_offset, + units = units, + dpi = dpi ) }, @@ -4240,15 +4248,20 @@ wbWorkbook <- R6::R6Class( #' @param sheet sheet #' @param dims dims #' @param xml xml - #' @param colOffset,rowOffset offsets for column and row + #' @param col_offset,row_offset offsets for column and row + #' @param ... additional arguments #' @returns The `wbWorkbook` object add_drawing = function( - sheet = current_sheet(), + sheet = current_sheet(), + dims = "A1", xml, - dims = NULL, - colOffset = 0, - rowOffset = 0 + col_offset = 0, + row_offset = 0, + ... ) { + + standardize_case_names(...) + sheet <- private$get_sheet_index(sheet) is_chartsheet <- self$is_chartsheet[sheet] @@ -4299,8 +4312,8 @@ wbWorkbook <- R6::R6Class( dims_list <- strsplit(dims, ":")[[1]] cols <- col2int(dims_list) rows <- as.numeric(gsub("\\D+", "", dims_list)) - if (length(colOffset) != 2) colOffset <- rep(colOffset, 2) - if (length(rowOffset) != 2) rowOffset <- rep(rowOffset, 2) + if (length(col_offset) != 2) col_offset <- rep(col_offset, 2) + if (length(row_offset) != 2) row_offset <- rep(row_offset, 2) anchor <- paste0( "", @@ -4314,10 +4327,10 @@ wbWorkbook <- R6::R6Class( ) anchor <- sprintf( anchor, - cols[1] - 1L, colOffset[1], - rows[1] - 1L, rowOffset[1], - cols[2], colOffset[2], - rows[2], rowOffset[2] + cols[1] - 1L, col_offset[1], + rows[1] - 1L, row_offset[1], + cols[2], col_offset[2], + rows[2], row_offset[2] ) } else { @@ -4335,8 +4348,8 @@ wbWorkbook <- R6::R6Class( ) anchor <- sprintf( anchor, - cols[1] - 1L, colOffset[1], - rows[1] - 1L, rowOffset[1] + cols[1] - 1L, col_offset[1], + rows[1] - 1L, row_offset[1] ) } @@ -4405,16 +4418,28 @@ wbWorkbook <- R6::R6Class( #' @param sheet sheet #' @param dims dims #' @param xml xml - #' @param colOffset,rowOffset startCol and startRow + #' @param col_offset,row_offset positioning parameters + #' @param ... additional arguments #' @returns The `wbWorkbook` object add_chart_xml = function( - sheet = current_sheet(), + sheet = current_sheet(), + dims = NULL, xml, - dims = NULL, - colOffset = 0, - rowOffset = 0 + col_offset = 0, + row_offset = 0, + ... ) { + args <- list(...) + + standardize_case_names(...) + + if (exists("start_row") && !is.null(start_row) && + exists("start_col") && !is.null(start_col)) { + .Deprecated(old = "start_col/start_row", new = "dims", package = "openxlsx2") + dims <- rowcol_to_dims(args$start_row, args$start_col) + } + sheet <- private$get_sheet_index(sheet) if (length(self$worksheets[[sheet]]$relships$drawing)) { # if one is found: we have to select this drawing @@ -4427,12 +4452,12 @@ wbWorkbook <- R6::R6Class( next_chart <- NROW(self$charts) + 1 chart <- data.frame( - chart = xml, - colors = colors1_xml, - style = styleplot_xml, - rels = chart1_rels_xml(next_chart), + chart = xml, + colors = colors1_xml, + style = styleplot_xml, + rels = chart1_rels_xml(next_chart), chartEx = "", - relsEx = "" + relsEx = "" ) self$charts <- rbind(self$charts, chart) @@ -4441,11 +4466,11 @@ wbWorkbook <- R6::R6Class( # create drawing. add it to self$drawings, the worksheet and rels self$add_drawing( - sheet = sheet, - xml = next_chart, - dims = dims, - colOffset = colOffset, - rowOffset = rowOffset + sheet = sheet, + dims = dims, + xml = next_chart, + col_offset = col_offset, + row_offset = row_offset ) sheet_drawing <- self$worksheets[[sheet]]$relships$drawing @@ -4462,16 +4487,20 @@ wbWorkbook <- R6::R6Class( #' @param sheet the sheet on which the graph will appear #' @param dims the dimensions where the sheet will appear #' @param graph mschart graph - #' @param colOffset,rowOffset startCol and startRow + #' @param col_offset,row_offset offsets for column and row + #' @param ... additional arguments #' @returns The `wbWorkbook` object add_mschart = function( - sheet = current_sheet(), - dims = NULL, + sheet = current_sheet(), + dims = NULL, graph, - colOffset = 0, - rowOffset = 0 + col_offset = 0, + row_offset = 0, + ... ) { + standardize_case_names(...) + requireNamespace("mschart") assert_class(graph, "ms_chart") @@ -4492,11 +4521,23 @@ wbWorkbook <- R6::R6Class( # write the chart data to the workbook if (inherits(graph$data_series, "wb_data")) { self$ - add_chart_xml(sheet = sheet, xml = out_xml, dims = dims, colOffset = colOffset, rowOffset = rowOffset) + add_chart_xml( + sheet = sheet, + dims = dims, + xml = out_xml, + col_offset = col_offset, + row_offset = row_offset + ) } else { self$ add_data(sheet = sheet, x = graph$data_series)$ - add_chart_xml(sheet = sheet, xml = out_xml, dims = dims, colOffset = colOffset, rowOffset = rowOffset) + add_chart_xml( + sheet = sheet, + dims = dims, + xml = out_xml, + col_offset = col_offset, + row_offset = row_offset + ) } }, diff --git a/R/wb_functions.R b/R/wb_functions.R index 697de5971..ffe7e2cf4 100644 --- a/R/wb_functions.R +++ b/R/wb_functions.R @@ -939,58 +939,6 @@ wb_set_selected <- function(wb, sheet) { wb } -#' Add mschart object to an existing workbook -#' @param wb a workbook -#' @param sheet the sheet on which the graph will appear -#' @param dims the dimensions where the sheet will appear -#' @param graph mschart object -#' @param colOffset,rowOffset startCol and startRow -#' @examples -#' if (requireNamespace("mschart")) { -#' require(mschart) -#' -#' ## Add mschart to worksheet (adds data and chart) -#' scatter <- ms_scatterchart(data = iris, x = "Sepal.Length", y = "Sepal.Width", group = "Species") -#' scatter <- chart_settings(scatter, scatterstyle = "marker") -#' -#' wb <- wb_workbook() %>% -#' wb_add_worksheet() %>% -#' wb_add_mschart(dims = "F4:L20", graph = scatter) -#' -#' ## Add mschart to worksheet and use available data -#' wb <- wb_workbook() %>% -#' wb_add_worksheet() %>% -#' wb_add_data(x = mtcars, dims = "B2") -#' -#' # create wb_data object -#' dat <- wb_data(wb, 1, dims = "B2:E6") -#' -#' # call ms_scatterplot -#' data_plot <- ms_scatterchart( -#' data = dat, -#' x = "mpg", -#' y = c("disp", "hp"), -#' labels = c("disp", "hp") -#' ) -#' -#' # add the scatterplot to the data -#' wb <- wb %>% -#' wb_add_mschart(dims = "F4:L20", graph = data_plot) -#' } -#' @seealso [wb_data()] -#' @export -wb_add_mschart <- function( - wb, - sheet = current_sheet(), - dims = NULL, - graph, - colOffset = 0, - rowOffset = 0 -) { - assert_workbook(wb) - wb$clone()$add_mschart(sheet = sheet, dims = dims, graph = graph, colOffset = colOffset, rowOffset = rowOffset) -} - #' provide wb_data object as mschart input #' @param wb a workbook #' @param sheet a sheet in the workbook either name or index diff --git a/R/wb_load.R b/R/wb_load.R index a81289e0c..3ac4019a0 100644 --- a/R/wb_load.R +++ b/R/wb_load.R @@ -1,7 +1,7 @@ #' @name wb_load #' @title Load an existing .xlsx file #' @param file A path to an existing .xlsx or .xlsm file -#' @param xlsxFile alias for file +#' @param xlsx_file alias for file #' @param sheet optional sheet parameter. if this is applied, only the selected #' sheet will be loaded. #' @param data_only mode to import if only a data frame should be returned. This @@ -12,6 +12,7 @@ #' 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 @@ -32,13 +33,16 @@ #' wb$add_worksheet("A new worksheet") wb_load <- function( file, - xlsxFile = NULL, + xlsx_file = NULL, sheet, data_only = FALSE, - calc_chain = FALSE + calc_chain = FALSE, + ... ) { - file <- xlsxFile %||% file + standardize_case_names(...) + + file <- xlsx_file %||% file file <- getFile(file) if (!file.exists(file)) { diff --git a/man/wbWorkbook.Rd b/man/wbWorkbook.Rd index 6d886cb7f..cf80d0e6d 100644 --- a/man/wbWorkbook.Rd +++ b/man/wbWorkbook.Rd @@ -895,10 +895,11 @@ load workbook \subsection{Usage}{ \if{html}{\out{
}}\preformatted{wbWorkbook$load( file, - xlsxFile = NULL, + xlsx_file = NULL, sheet, data_only = FALSE, - calc_chain = FALSE + calc_chain = FALSE, + ... )}\if{html}{\out{
}} } @@ -907,13 +908,15 @@ load workbook \describe{ \item{\code{file}}{file} -\item{\code{xlsxFile}}{xlsxFile} +\item{\code{xlsx_file}}{xlsx_file} \item{\code{sheet}}{sheet} \item{\code{data_only}}{data_only} \item{\code{calc_chain}}{calc_chain} + +\item{\code{...}}{additional arguments} } \if{html}{\out{}} } @@ -1719,16 +1722,15 @@ Insert an image into a sheet \subsection{Usage}{ \if{html}{\out{
}}\preformatted{wbWorkbook$add_image( sheet = current_sheet(), + dims = "A1", file, width = 6, height = 3, - startRow = 1, - startCol = 1, - rowOffset = 0, - colOffset = 0, + row_offset = 0, + col_offset = 0, units = "in", dpi = 300, - dims = rowcol_to_dim(startRow, startCol) + ... )}\if{html}{\out{
}} } @@ -1737,25 +1739,21 @@ Insert an image into a sheet \describe{ \item{\code{sheet}}{sheet} +\item{\code{dims}}{dims} + \item{\code{file}}{file} \item{\code{width}}{width} \item{\code{height}}{height} -\item{\code{startRow}}{startRow} - -\item{\code{startCol}}{startCol} - -\item{\code{rowOffset}}{rowOffset} - -\item{\code{colOffset}}{colOffset} +\item{\code{row_offset, col_offset}}{offsets} \item{\code{units}}{units} \item{\code{dpi}}{dpi} -\item{\code{dims}}{dims} +\item{\code{...}}{additional arguments} } \if{html}{\out{}} } @@ -1771,16 +1769,15 @@ Add plot. A wrapper for add_image() \subsection{Usage}{ \if{html}{\out{
}}\preformatted{wbWorkbook$add_plot( sheet = current_sheet(), + dims = "A1", width = 6, height = 4, - startRow = 1, - startCol = 1, - rowOffset = 0, - colOffset = 0, - fileType = "png", + row_offset = 0, + col_offset = 0, + file_type = "png", units = "in", dpi = 300, - dims = rowcol_to_dim(startRow, startCol) + ... )}\if{html}{\out{
}} } @@ -1789,25 +1786,21 @@ Add plot. A wrapper for add_image() \describe{ \item{\code{sheet}}{sheet} +\item{\code{dims}}{dims} + \item{\code{width}}{width} \item{\code{height}}{height} -\item{\code{startRow}}{startRow} - -\item{\code{startCol}}{startCol} - -\item{\code{rowOffset}}{rowOffset} +\item{\code{row_offset, col_offset}}{offsets} -\item{\code{colOffset}}{colOffset} - -\item{\code{fileType}}{fileType} +\item{\code{file_type}}{fileType} \item{\code{units}}{units} \item{\code{dpi}}{dpi} -\item{\code{dims}}{dims} +\item{\code{...}}{additional arguments} } \if{html}{\out{}} } @@ -1820,10 +1813,11 @@ Add xml drawing \subsection{Usage}{ \if{html}{\out{
}}\preformatted{wbWorkbook$add_drawing( sheet = current_sheet(), + dims = "A1", xml, - dims = NULL, - colOffset = 0, - rowOffset = 0 + col_offset = 0, + row_offset = 0, + ... )}\if{html}{\out{
}} } @@ -1832,11 +1826,13 @@ Add xml drawing \describe{ \item{\code{sheet}}{sheet} +\item{\code{dims}}{dims} + \item{\code{xml}}{xml} -\item{\code{dims}}{dims} +\item{\code{col_offset, row_offset}}{offsets for column and row} -\item{\code{colOffset, rowOffset}}{offsets for column and row} +\item{\code{...}}{additional arguments} } \if{html}{\out{}} } @@ -1852,10 +1848,11 @@ Add xml chart \subsection{Usage}{ \if{html}{\out{
}}\preformatted{wbWorkbook$add_chart_xml( sheet = current_sheet(), - xml, dims = NULL, - colOffset = 0, - rowOffset = 0 + xml, + col_offset = 0, + row_offset = 0, + ... )}\if{html}{\out{
}} } @@ -1864,11 +1861,13 @@ Add xml chart \describe{ \item{\code{sheet}}{sheet} +\item{\code{dims}}{dims} + \item{\code{xml}}{xml} -\item{\code{dims}}{dims} +\item{\code{col_offset, row_offset}}{positioning parameters} -\item{\code{colOffset, rowOffset}}{startCol and startRow} +\item{\code{...}}{additional arguments} } \if{html}{\out{}} } @@ -1883,8 +1882,9 @@ Add mschart chart to the workbook sheet = current_sheet(), dims = NULL, graph, - colOffset = 0, - rowOffset = 0 + col_offset = 0, + row_offset = 0, + ... )}\if{html}{\out{}} } @@ -1897,7 +1897,9 @@ Add mschart chart to the workbook \item{\code{graph}}{mschart graph} -\item{\code{colOffset, rowOffset}}{startCol and startRow} +\item{\code{col_offset, row_offset}}{offsets for column and row} + +\item{\code{...}}{additional arguments} } \if{html}{\out{}} } diff --git a/man/wb_add_chart_xml.Rd b/man/wb_add_chart_xml.Rd index 15785c522..51e66432c 100644 --- a/man/wb_add_chart_xml.Rd +++ b/man/wb_add_chart_xml.Rd @@ -7,10 +7,11 @@ wb_add_chart_xml( wb, sheet = current_sheet(), - xml, dims = NULL, - colOffset = 0, - rowOffset = 0 + xml, + col_offset = 0, + row_offset = 0, + ... ) } \arguments{ @@ -18,12 +19,17 @@ wb_add_chart_xml( \item{sheet}{the sheet on which the graph will appear} +\item{dims}{the dimensions where the sheet will appear} + \item{xml}{chart xml} -\item{dims}{the dimensions where the sheet will appear} +\item{col_offset, row_offset}{positioning} -\item{colOffset, rowOffset}{startCol and startRow} +\item{...}{additional arguments} } \description{ add a chart xml to a workbook } +\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_drawing.Rd b/man/wb_add_drawing.Rd index 3b6ba002a..9807de6b1 100644 --- a/man/wb_add_drawing.Rd +++ b/man/wb_add_drawing.Rd @@ -7,10 +7,11 @@ wb_add_drawing( wb, sheet = current_sheet(), + dims = "A1", xml, - dims = NULL, - colOffset = 0, - rowOffset = 0 + col_offset = 0, + row_offset = 0, + ... ) } \arguments{ @@ -18,11 +19,13 @@ wb_add_drawing( \item{sheet}{a sheet in the workbook} +\item{dims}{the dimension where the drawing is added. Can be NULL} + \item{xml}{the drawing xml as character or file} -\item{dims}{the dimension where the drawing is added. Can be NULL} +\item{col_offset, row_offset}{offsets for column and row} -\item{colOffset, rowOffset}{offsets for column and row} +\item{...}{additional arguments} } \description{ add drawings to workbook @@ -43,3 +46,6 @@ wb <- wb_workbook()$ add_drawing(xml = tmp, dims = NULL) } } +\seealso{ +\code{\link[=wb_add_chart_xml]{wb_add_chart_xml()}} \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_image.Rd b/man/wb_add_image.Rd index 0f42c496a..adc2ea304 100644 --- a/man/wb_add_image.Rd +++ b/man/wb_add_image.Rd @@ -7,16 +7,15 @@ wb_add_image( wb, sheet = current_sheet(), + dims = "A1", file, width = 6, height = 3, - startRow = 1, - startCol = 1, - rowOffset = 0, - colOffset = 0, + row_offset = 0, + col_offset = 0, units = "in", dpi = 300, - dims = rowcol_to_dim(startRow, startCol) + ... ) } \arguments{ @@ -24,44 +23,38 @@ 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{file}{An image file. Valid file types are:\code{ "jpeg"}, \code{"png"}, \code{"bmp"}} \item{width}{Width of figure.} \item{height}{Height of figure.} -\item{startRow}{Row coordinate of upper left corner of the image} - -\item{startCol}{Column coordinate of upper left corner of the image} - -\item{rowOffset}{offset vector for one or two cell anchor within cell (row)} +\item{row_offset}{offset vector for one or two cell anchor within cell (row)} -\item{colOffset}{offset vector for one or two cell anchor within cell (column)} +\item{col_offset}{offset vector for one or two cell anchor within cell (column)} \item{units}{Units of width and height. Can be \code{"in"}, \code{"cm"} or \code{"px"}} \item{dpi}{Image resolution used for conversion between units.} -\item{dims}{Dimensions where to plot. Default absolute anchor, single cell (eg. "A1") oneCellAnchor, cell range (eg. "A1:D4") twoCellAnchor} +\item{...}{additional arguments} } \description{ Insert an image into a worksheet } \examples{ -## Create a new workbook -wb <- wb_workbook("Ayanami") - -## Add some worksheets -wb$add_worksheet("Sheet 1") -wb$add_worksheet("Sheet 2") -wb$add_worksheet("Sheet 3") - -## Insert images img <- system.file("extdata", "einstein.jpg", package = "openxlsx2") -wb$add_image("Sheet 1", img, startRow = 5, startCol = 3, width = 6, height = 5) -wb$add_image(2, img, startRow = 2, startCol = 2) -wb$add_image(3, img, width = 15, height = 12, startRow = 3, startCol = "G", units = "cm") + +wb <- wb_workbook()$ + add_worksheet()$ + add_image("Sheet 1", dims = "C5", file = img, width = 6, height = 5)$ + add_worksheet()$ + add_image(dims = "B2", file = img)$ + add_worksheet()$ + add_image(dims = "G3", file = img, width = 15, height = 12, units = "cm") } \seealso{ -\code{\link[=wb_add_plot]{wb_add_plot()}} +\code{\link[=wb_add_chart_xml]{wb_add_chart_xml()}} \code{\link[=wb_add_drawing]{wb_add_drawing()}} \code{\link[=wb_add_mschart]{wb_add_mschart()}} \code{\link[=wb_add_plot]{wb_add_plot()}} } diff --git a/man/wb_add_mschart.Rd b/man/wb_add_mschart.Rd index b86247a9d..8396c8668 100644 --- a/man/wb_add_mschart.Rd +++ b/man/wb_add_mschart.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/wb_functions.R +% Please edit documentation in R/class-workbook-wrappers.R \name{wb_add_mschart} \alias{wb_add_mschart} \title{Add mschart object to an existing workbook} @@ -9,8 +9,9 @@ wb_add_mschart( sheet = current_sheet(), dims = NULL, graph, - colOffset = 0, - rowOffset = 0 + col_offset = 0, + row_offset = 0, + ... ) } \arguments{ @@ -22,7 +23,9 @@ wb_add_mschart( \item{graph}{mschart object} -\item{colOffset, rowOffset}{startCol and startRow} +\item{col_offset, row_offset}{offsets for column and row} + +\item{...}{additional arguments} } \description{ Add mschart object to an existing workbook @@ -61,5 +64,5 @@ wb <- wb \%>\% } } \seealso{ -\code{\link[=wb_data]{wb_data()}} +\code{\link[=wb_data]{wb_data()}} \code{\link[=wb_add_chart_xml]{wb_add_chart_xml()}} \link{wb_add_image} \code{\link[=wb_add_mschart]{wb_add_mschart()}} \link{wb_add_plot} } diff --git a/man/wb_add_plot.Rd b/man/wb_add_plot.Rd index fb60e9eb6..0c07d419b 100644 --- a/man/wb_add_plot.Rd +++ b/man/wb_add_plot.Rd @@ -7,16 +7,15 @@ wb_add_plot( wb, sheet = current_sheet(), + dims = "A1", width = 6, height = 4, - startRow = 1, - startCol = 1, - rowOffset = 0, - colOffset = 0, - fileType = "png", + row_offset = 0, + col_offset = 0, + file_type = "png", units = "in", dpi = 300, - dims = rowcol_to_dim(startRow, startCol) + ... ) } \arguments{ @@ -24,25 +23,21 @@ wb_add_plot( \item{sheet}{A name or index of a worksheet} +\item{dims}{Worksheet dimension, single cell ("A1") or cell range ("A1:D4")} + \item{width}{Width of figure. Defaults to \code{6}in.} \item{height}{Height of figure . Defaults to \code{4}in.} -\item{startRow}{Row coordinate of upper left corner of figure.} - -\item{startCol}{Column coordinate of upper left corner of figure.} +\item{row_offset, col_offset}{offset for column and row} -\item{rowOffset}{offset within cell (row)} - -\item{colOffset}{offset within cell (column)} - -\item{fileType}{File type of image} +\item{file_type}{File type of image} \item{units}{Units of width and height. Can be \code{"in"}, \code{"cm"} or \code{"px"}} \item{dpi}{Image resolution} -\item{dims}{Worksheet dimension, single cell ("A1") or cell range ("A1:D4")} +\item{...}{additional arguments} } \description{ The current plot is saved to a temporary image file using @@ -76,5 +71,5 @@ wb$add_plot(1, dims = "J2", width = 16, height = 10, fileType = "png", units = " } } \seealso{ -\code{\link[=wb_add_image]{wb_add_image()}} +\code{\link[=wb_add_chart_xml]{wb_add_chart_xml()}} \code{\link[=wb_add_drawing]{wb_add_drawing()}} \code{\link[=wb_add_image]{wb_add_image()}} \code{\link[=wb_add_mschart]{wb_add_mschart()}} } diff --git a/man/wb_load.Rd b/man/wb_load.Rd index 3777825f8..4badaebd0 100644 --- a/man/wb_load.Rd +++ b/man/wb_load.Rd @@ -4,12 +4,19 @@ \alias{wb_load} \title{Load an existing .xlsx file} \usage{ -wb_load(file, xlsxFile = NULL, sheet, data_only = FALSE, calc_chain = FALSE) +wb_load( + file, + xlsx_file = NULL, + sheet, + data_only = FALSE, + calc_chain = FALSE, + ... +) } \arguments{ \item{file}{A path to an existing .xlsx or .xlsm file} -\item{xlsxFile}{alias for file} +\item{xlsx_file}{alias for file} \item{sheet}{optional sheet parameter. if this is applied, only the selected sheet will be loaded.} @@ -23,6 +30,8 @@ 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.} + +\item{...}{additional arguments} } \value{ Workbook object. diff --git a/tests/testthat/test-class-workbook.R b/tests/testthat/test-class-workbook.R index 251a148bb..e6e9b76f4 100644 --- a/tests/testthat/test-class-workbook.R +++ b/tests/testthat/test-class-workbook.R @@ -693,7 +693,7 @@ test_that("various image functions work as expected", { expect_warning( wb$add_worksheet()$add_image(file = img, width = 6, height = 5, dims = NULL, startRow = 2, startCol = 2), - "dims is NULL, startRow/startCol will have no impact" + "'start_col/start_row' is deprecated." ) }) diff --git a/tests/testthat/test-read_sources.R b/tests/testthat/test-read_sources.R index ad1f51cb9..05dd8db42 100644 --- a/tests/testthat/test-read_sources.R +++ b/tests/testthat/test-read_sources.R @@ -148,7 +148,11 @@ test_that("reading charts", { img <- system.file("extdata", "einstein.jpg", package = "openxlsx2") which(wb$get_sheet_names() == "Uebersicht_Quoten") - wb$add_image(19, img, startRow = 5, startCol = 3, width = 6, height = 5) + expect_warning( + wb$add_image(19, file = img, startRow = 5, startCol = 3, width = 6, height = 5), + "'start_col/start_row' is deprecated." + ) + wb$save(temp) # check that we wrote a chartshape