Interfacing with RStudio in Visual Mode

library(rstudioapi)

RStudio v1.4 includes a new visual editing mode, which provides a WYSIWYM-style editing interface for R Markdown documents. This vignette describes how rstudioapi can be used to interface with the RStudio visual mode editor.

Most of the pre-existing rstudioapi functions used for interacting with a document (e.g. rstudioapi::getSourceEditorContext()) consume and / or produce objects which describe the position of the current selection in terms of row + column offsets into the document. Unfortunately, this abstraction does not neatly map into visual editing mode, as there is no notion of a “global” cursor position – rather, a cursor might be placed into a particular cell, and could have an offset somewhere into that cell.

If you are an RStudio Addin author, then you may want to ensure your addins are visual-mode-aware, so that they can function regardless of whether the user has enabled visual mode. To that end, we’ve introduced a small set of functions, which are more narrow in scope but can function in both source and visual mode:

• rstudioapi::documentId(): Retrieve the ID associated with the document currently open and being edited in the RStudio IDE.
• rstudioapi::documentPath(): Retrieve the path on disk for a file currently open in the RStudio IDE.
• rstudioapi::selectionGet(): Get the contents of the user’s selection.
• rstudioapi::selectionSet(): Set the contents of the user’s selection.

In addition, the rstudioapi::insertText() function will function in both source and visual mode, as long as only the text argument is supplied.

Using this, you can build addins that modify the user’s selected text. For example, a function that uses rstudioapi to reformat the user’s current selection might look like this:

reformat <- function() {
  id <- rstudioapi::documentId(allowConsole = TRUE)
  selection <- rstudioapi::selectionGet(id = id)
  formatted <- styler::style_text(text = selection$value)
  rstudioapi::selectionSet(value = formatted, id = id)
}