Export wb_comment()

NAMESPACE

@@ -76,6 +76,7 @@ export(wb_clone_sheet_style)
 export(wb_clone_worksheet)
 export(wb_color)
 export(wb_colour)
+export(wb_comment)
 export(wb_copy_cells)
 export(wb_data)
 export(wb_dims)

NEWS.md

@@ -11,11 +11,19 @@
 
 * provide solve argument for `wb_merge_cells()`. This allows to solve cell intersecting regions. [733](https://github.com/JanMarvin/openxlsx2/pull/733)
 
+* `wb_add_comment(comment = "x")` no longer errors when a comment as a character vector no longer fails [758, @olivroy](https://github.com/JanMarvin/openxlsx2/pull/758)
+
 ## Breaking changes
 
 * no longer exporting `wb_get_sheet_name()`
 * deprecating `delete_data()` and minor improvements to `wb_clean_sheet()`
 * removing `wb_get_worksheet()`, `wb_ws()`. These never worked as expected.
+* `create_comment()` has been renamed `wb_comment()`.  [758, @olivroy](https://github.com/JanMarvin/openxlsx2/pull/758) The default arguments however are changed:
+
+  * `author` looks at `options("openxlsx2.creator")` in `wb_comment()` compared to only `sys.getenv("user")` in `create_comment()`
+  * `visible` defaults to `FALSE` in `wb_comment()` to account for modern spreadsheet software behaviour.
+  In `create_comment()`, it is `TRUE`.
+  * `width` and `height` must now be of length 1. (In `create_comment()`, the first element is taken, other are ignored.)
 
 ## Internal changes
 

R/class-comment.R

@@ -35,8 +35,7 @@ wbComment <- R6::R6Class(
     #' @param width Width of the comment in ... units
     #' @param height Height of comment in ... units
     #' @return a `wbComment` object
-    initialize = function(text, author, style, visible = TRUE, width = 2, height = 4) {
-      # TODO this needs the validations that the comment wrappers have
+    initialize = function(text, author, style, visible, width, height) {
       self$text <- text
       self$author <- author
       self$style <- style
@@ -76,63 +75,41 @@ wbComment <- R6::R6Class(
     }
   )
 )
+# Comment creation ------------------------------------------------------
 
-
-# wrappers ----------------------------------------------------------------
-
-# TODO create_comment() should leverage wbComment$new() more
-# TODO write_comment() should leverage wbWorkbook$addComment() more
-# TODO remove_comment() should leverage wbWorkbook$remove_comment() more
-
-#' Create a comment
+#' Create a comment object
 #'
 #' 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.
+#' @param author Author of comment. A string. By default, will look at `options("openxlsx2.creator")`.
+#'   Otherwise, will check the system username.
 #' @param style A Style object or list of style objects the same length as comment vector.
-#' @param visible `TRUE` or `FALSE`. Is comment visible?
+#' @param visible Is comment visible? Default: `FALSE`.
 #' @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
-#' @examples
-#' wb <- wb_workbook()
-#' wb$add_worksheet("Sheet 1")
-#'
-#' # write comment without author
-#' c1 <- create_comment(text = "this is a comment", author = "")
-#' wb$add_comment(dims = "B10", comment = c1)
 #'
-#' # 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)
-#'
-#' # write a styled comment with system author
-#' s1 <- create_font(b = "true", color = wb_color(hex = "FFFF0000"), sz = "12")
-#' 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)
-create_comment <- function(text,
-  author = Sys.info()[["user"]],
-  style = NULL,
-  visible = TRUE,
-  width = 2,
-  height = 4) {
-
-  # TODO move this to wbComment$new(); this could then be replaced with
-  # wb_comment()
-
+#' @return A `wbComment` object
+#' @export
+wb_comment <- function(text = NULL,
+                       style = NULL,
+                       visible = FALSE,
+                       author = getOption("openxlsx2.creator"),
+                       width = 2,
+                       height = 4) {
+  # Code copied from the wbWorkbook
+  author <- author %||% Sys.getenv("USERNAME")
+  text <- text %||% ""
   assert_class(author, "character")
   assert_class(text, "character")
-  assert_class(width, "numeric")
-  assert_class(height, "numeric")
+  assert_class(width, c("numeric", "integer"))
+  assert_class(height, c("numeric", "integer"))
   assert_class(visible, "logical")
 
   if (length(visible) > 1) stop("visible must be a single logical")
   if (length(author) > 1) stop("author) must be a single character")
+  if (length(width) > 1) stop("width must be a single integer")
+  if (length(height) > 1) stop("height must be a single integer")
 
   width <- round(width)
   height <- round(height)
@@ -163,7 +140,52 @@ create_comment <- function(text,
     )
   }
 
-  invisible(wbComment$new(text = text, author = author, style = style, visible = visible, width = width[1], height = height[1]))
+  invisible(wbComment$new(text = text, author = author, style = style, width = width, height = height, visible = visible))
+}
+
+# wrappers ----------------------------------------------------------------
+
+# TODO create_comment() should leverage wbComment$new() more
+# TODO write_comment() should leverage wbWorkbook$addComment() more
+# TODO remove_comment() should leverage wbWorkbook$remove_comment() more
+
+#' Create a comment
+#'
+#' Use [wb_comment()] in new code.
+#'
+#' @inheritParams wb_comment
+#' @param author A string, by default, will use "user"
+#' @param visible Default: `TRUE`. Is the comment visible by default?
+#' @keywords internal
+#' @returns a `wbComment` object
+#' @seealso [wb_add_comment()]
+#' @export
+#' @examples
+#' wb <- wb_workbook()
+#' wb$add_worksheet("Sheet 1")
+#'
+#' # write comment without author
+#' c1 <- create_comment(text = "this is a comment", author = "")
+#' wb$add_comment(dims = "B10", comment = c1)
+#'
+#' # 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)
+#'
+#' # write a styled comment with system author
+#' s1 <- create_font(b = "true", color = wb_color(hex = "FFFF0000"), sz = "12")
+#' 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)
+create_comment <- function(text,
+  author = Sys.info()[["user"]],
+  style = NULL,
+  visible = TRUE,
+  width = 2,
+  height = 4) {
+  # .Deprecated("wb_comment()")
+  wb_comment(text = text, author = author, style = style, visible = visible, width = width[1], height = height[1])
 }
 
 #' Internal comment functions
@@ -383,9 +405,7 @@ remove_comment <- function(
 
 }
 
-wb_comment <- function(text = character(), author = character(), style = character()) {
-  wbComment$new(text = text, author = author, style = style)
-}
+
 
 as_fmt_txt <- function(x) {
   vapply(x, function(y) {

R/class-workbook-wrappers.R

@@ -10,7 +10,7 @@
 #' "Old Office Theme", "Organic", "Parallax", "Parcel", "Retrospect",
 #' "Savon", "Slice", "Vapor Trail", "View", "Wisp", "Wood Type"
 #'
-#' @param creator Creator of the workbook (your name). Defaults to login username
+#' @param creator Creator of the workbook (your name). Defaults to login username or `options("openxlsx2.creator")` if set.
 #' @param title,subject,category Workbook property, a string.
 #' @param datetime_created The time of the workbook is created
 #' @param theme Optional theme identified by string or number.
@@ -2965,21 +2965,15 @@ wb_add_dxfs_style <- function(
 
 }
 
-#' Add / remove comment in a worksheet
+#' Add comment to 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.
+#' @details
+#' If applying a `comment` with a string, it will use [wb_comment()] default values.
 #'
-#' @param wb A Workbook object
+#' @param wb A workbook object
 #' @param sheet A worksheet of the workbook
-#' @param dims Row and column as spreadsheet dimension, e.g. "A1"
-#' @param comment A comment to apply to the worksheet
-# TODO To fit, maybe comment, can be `x`
+#' @param dims Optional row and column as spreadsheet dimension, e.g. "A1"
+#' @param comment A comment to apply to `dims` created by [wb_comment()] or a string.
 #' @param ... additional arguments
 #' @returns The Workbook object, invisibly.
 #' @seealso [create_comment()], [wb_add_thread()]
@@ -3008,6 +3002,11 @@ wb_add_comment <- function(
   ) {
 
   assert_workbook(wb)
+
+  if (is.character(comment)) {
+    comment <- wb_comment(text = comment, author = getOption("openxlsx2.creator"))
+  }
+
   assert_comment(comment)
 
   wb$clone()$add_comment(

R/class-workbook.R

@@ -3747,6 +3747,10 @@ wbWorkbook <- R6::R6Class(
         dims <- rowcol_to_dim(row, col)
       }
 
+      if (is.character(comment)) {
+        comment <- wb_comment(text = comment, author = getOption("openxlsx2.creator"))
+      }
+
       write_comment(
         wb      = self,
         sheet   = sheet,

R/openxlsx2-package.R

@@ -73,6 +73,8 @@
 #' * `options("openxlsx2.orientation" = "portrait")` ## page orientation
 #' * `options("openxlsx2.sheet.default_name" = "Sheet")`
 #' * `options("openxlsx2.rightToLeft" = NULL)`
+#' * `options("openxlsx2.soon_deprecated" = FALSE)` ## warn if using camelCase
+#' * `options("openxlsx2.creator")` ## Default is Windows Username
 #'
 #' @name openxlsx2_options
 NULL
@@ -103,6 +105,7 @@ openxlsx2_celltype <- c(
 #' * [convertToExcelDate()] -> [convert_to_excel_date()]
 #' * [wb_grid_lines()] -> [wb_set_grid_lines()]
 #' * [delete_data()] -> [wb_clean_sheet()]
+#' * [create_comment()] -> [wb_comment()]
 #' @seealso [.Deprecated]
 #' @name openxlsx2-deprecated
 NULL

_pkgdown.yml

@@ -92,6 +92,7 @@ reference:
   contents:
   - wb_dims
   - wb_color
+  - wb_comment
   - wb_hyperlink
   - starts_with("create_")