Export wb_comment() (#758)

* working example.

* Change default to `visible = FALSE` in `wb_comment()` to account for new spreadsheet software behaviour.

* lint

* Different behaviour on multiple width and height in `wb_comment()` vs `create_comment()`

* tweaks to make the overall diff more pleasant to look at.

* Tweaks and show fmt_txt

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,63 @@ wbComment <- R6::R6Class(
  }
  )
 )
-
-
-# wrappers ----------------------------------------------------------------
+# 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 text Comment text. Character vector. or a [fmt_txt()] 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()]
+#'
+#' @return A `wbComment` object
 #' @export
 #' @examples
 #' wb <- wb_workbook()
 #' wb$add_worksheet("Sheet 1")
 #'
 #' # write comment without author
-#' c1 <- create_comment(text = "this is a comment", author = "")
+#' c1 <- wb_comment(text = "this is a comment", author = "", visible = TRUE)
 #' wb$add_comment(dims = "B10", comment = c1)
 #'
 #' # Write another comment with author information
-#' c2 <- create_comment(text = "this is another comment", author = "Marco Polo")
+#' c2 <- wb_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))
+#' c3 <- wb_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()
-
+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 +162,30 @@ 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))
+}
+
+#' 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
+#' @export
+create_comment <- function(text,
+ author = Sys.info()[["user"]],
+ style = NULL,
+ visible = TRUE,
+ width = 2,
+ height = 4) {
+ #
+ if (getOption("openxlsx2.soon_deprecated", default = FALSE)) {
+ .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,37 +2965,34 @@ 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()], a string or a [fmt_txt()] object
 #' @param ... additional arguments
 #' @returns The Workbook object, invisibly.
-#' @seealso [create_comment()], [wb_add_thread()]
+#' @seealso [wb_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 = "")
+#' c1 <- wb_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")
+#' c2 <- wb_comment(text = "this is another comment", author = "Marco Polo", visible = TRUE)
 #' wb$add_comment(sheet = 1, dims = "C10", comment = c2)
+#' # Works with formatted text also.
+#' formatted_text <- fmt_txt("bar", underline = TRUE)
+#' wb$add_comment(dims = "B5", comment = formatted_text)
 NULL
 #' @rdname wb_add_comment
 #' @export
@@ -3008,6 +3005,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_")