| Title: | Rust-Backed Graphics Device and Viewer Windows for Terminal R Sessions |
|---|---|
| Description: | Provides a Rust-backed graphics device and companion viewer windows for plots, HTML widgets and live URLs, and data frames, so that terminal and editor R sessions without an IDE viewer pane (such as radian, Zed, or Neovim) can display graphics, htmlwidgets, Shiny apps, and data frames in native windows. |
| Authors: | Jose J. Alcocer [aut, cre] |
| Maintainer: | Jose J. Alcocer <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.2 |
| Built: | 2026-10-08 22:23:19 UTC |
| Source: | https://github.com/alcocer-jj/rustgd |
Internal: absolute path to the staged rustgd-frames binary.
.rustgd_frames_bin().rustgd_frames_bin()
Internal: per-process frames directory, a sibling of the plots and widgets directories. Uses the session temp directory so it works on every platform (Windows has no /tmp); the binary receives this path as an argument.
.rustgd_frames_dir().rustgd_frames_dir()
Internal: remove the frames directory when R exits.
.rustgd_frames_register_cleanup().rustgd_frames_register_cleanup()
Internal: snapshot the current device's graphics display list, provided rustgd is the active device. Returns NULL silently in any situation where recordPlot is not safe or not meaningful (e.g. the user switched devices mid-expression, or there's nothing to record). Recording is cheap compared to the actual drawing that just happened, so calling it on every drew/new_page flag fire (not just new_page) is fine.
.rustgd_record_current().rustgd_record_current()
Internal: register a one-time finalizer that removes the widget directory when R exits, so nothing is left in the temp folder. The webview binary, if still open, sees its directory vanish on its next poll and exits.
.rustgd_register_cleanup().rustgd_register_cleanup()
Internal: per-process widget directory. Separate from the device's
rustgd-
.rustgd_widgets_dir().rustgd_widgets_dir()
Launches a native viewer window. When the viewer is resized, all plots in the session history reflow automatically during R's idle time, with no need to press Enter or run any command. Each plot's recorded graphics display list (captured via grDevices::recordPlot immediately after the plot was drawn) is replayed onto the resized device via grDevices::replayPlot, which lets the underlying plotting package (ggplot2, tmap, base R, lattice, etc.) lay itself out fresh at the new dimensions without re-executing any of the user's R code. If recording or replay fails for any reason, the captured top-level expression is re-evaluated as a fallback.
rustgd()rustgd()
Closing the viewer window propagates back to R: the next idle-time poll detects the close, calls dev.off() on the rustgd device, and the Rust-side close() callback removes the session directory. After closing, calling rustgd() again opens a fresh window with no stray state.
Points the rustgd webview window at a running address: a Shiny app, a local dashboard, a development server, or any reachable http(s) page. Unlike an htmlwidget, nothing is copied; the window loads the URL directly, so the entry is only meaningful while that server is up.
rustgd_browse(url, title = NULL)rustgd_browse(url, title = NULL)
url |
A single http:// or https:// address. |
title |
Optional label stored with the entry. |
Because a stopped server leaves a dead address behind, pushing any URL first clears any previous URL entry from the window, so there is at most one live URL at a time. Your htmlwidget entries are left untouched. The last URL stays until you close it with the window's "Clear widget" button.
The URL, invisibly.
Inverse of rustgd_enable(). Restores the previous graphics device,
web viewer, and Shiny launcher, and removes the View() and view()
routes, without touching .Rprofile. Open rustgd windows are left alone.
rustgd_disable()rustgd_disable()
Routes plots to the rustgd graphics device, HTML widgets and Shiny
apps to the rustgd web viewer, and View() and lowercase view() to
the rustgd data frame window, for this session only. Does not modify
.Rprofile.
Used internally by use_rustgd() and by the .Rprofile snippet it
writes; also usable directly for a one-off session.
rustgd_enable(mode = c("lazy", "eager"))rustgd_enable(mode = c("lazy", "eager"))
mode |
Either "lazy" or "eager"; affects the plot device only. "eager" opens a plot window immediately. |
rustgd_disable(), use_rustgd().
Internal: process a clear-all signal from the viewer. Empties the plot history, deletes every plot-NNNN.svg in the session dir, and resets the page counter so the next user-issued plot() starts fresh at plot-0001.svg.
rustgd_handle_clear_all()rustgd_handle_clear_all()
Internal: process a clear-active-plot signal from the viewer. The marker file contains the 1-based index of the plot to remove. The entry is dropped from plot_history, the corresponding SVG file is deleted, and any higher-numbered files are renamed down by one so the on-disk numbering stays contiguous and matches the new history indices.
rustgd_handle_clear_plot()rustgd_handle_clear_plot()
Internal: process a pending resize if one exists. Reads resize.txt, updates the device dimensions, and re-evaluates every plot in the session history at the new size. Each plot is directed to its own plot-NNNN.svg file via rustgd_set_current_page().
rustgd_input_handler()rustgd_input_handler()
Internal: scheduled poll for resize signals and viewer-close events. Reschedules itself while the device is active.
rustgd_poll_resize()rustgd_poll_resize()
Internal: absolute path to the staged rustgd-webview binary.
rustgd_webview_bin()rustgd_webview_bin()
Inverse of use_rustgd(). Restores the previous graphics device, web
viewer, and Shiny launcher in the current session, removes the rustgd
View() and view() routes, and strips the auto-activation snippet from
.Rprofile. Any rustgd windows already open are left alone. Safe to
call when nothing is active.
unuse_rustgd(rprofile_path = path.expand("~/.Rprofile"))unuse_rustgd(rprofile_path = path.expand("~/.Rprofile"))
rprofile_path |
Path to the |
Inverse of use_rustgd_webview(). Restores whatever options("viewer")
and options("shiny.launch.browser") were set before, so an IDE viewer
pane (RStudio, Positron) and the default Shiny launcher take over again.
Any open rustgd webview window is left alone.
unuse_rustgd_webview()unuse_rustgd_webview()
Activates the full rustgd suite for the current session: the graphics
device for plots, the web viewer for HTML widgets and Shiny apps (and
explicit URLs via rustgd_browse()). The data-frame viewer behind
View() and lowercase view() is always available once the package is
attached with library(rustgd), so it does not require this call.
use_rustgd( mode = c("lazy", "eager"), rprofile_path = path.expand("~/.Rprofile") )use_rustgd( mode = c("lazy", "eager"), rprofile_path = path.expand("~/.Rprofile") )
mode |
Either "lazy" or "eager"; see description. Affects the plot device only. |
rprofile_path |
Path to the |
To make the plot and web viewer activation persist across sessions,
this function can add a small snippet to your user-level .Rprofile.
Because that edits a file in your home directory, it is only done in an
interactive session and only after you explicitly confirm at a prompt.
If you decline, or if the session is non-interactive (Rscript, R CMD
BATCH, knitr, testthat, package checks), nothing is written and the
snippet is printed for you to add yourself.
Two startup modes control the plot device:
"lazy" (the default) registers rustgd as the default device via
options(device = ...). The viewer window opens when you draw your
first plot and not before, matching base R's quartz and X11.
"eager" additionally opens a plot window straight away, so it is ready before you plot anything.
Invisibly, the .Rprofile path if it was written, otherwise
FALSE.
unuse_rustgd() to undo this, and rustgd_enable() for a
one-session activation that never touches .Rprofile.
Registers the rustgd webview window as R's HTML viewer by setting
options(viewer = ...), and also routes Shiny apps to the same window by
setting options(shiny.launch.browser = ...). After this, printing an
htmlwidget (plotly, leaflet, a tmap in view mode, and so on) at the
console, or running a Shiny app with shiny::runApp(), opens in a rustgd
webview window instead of a browser tab. This is meant for terminal and
editor R sessions (radian, Zed, Neovim) that otherwise have no viewer pane.
use_rustgd_webview()use_rustgd_webview()
The window launches lazily: it opens the first time you display something, not when this function is called. Later content reuses the same window. Closing the window is fine; the next item reopens one.
Widgets are copied into a per-session directory under the system temp
folder, so what the window shows does not depend on R's own temp files.
Shiny apps and other live URLs are shown in place by pointing the window at
the running address; see rustgd_browse(). For a Shiny app, stopping it
(Ctrl+C, which is also what returns your terminal) removes its entry from
the window automatically, so no separate clear step is needed. Closing the
window deletes the copies, and quitting R removes the whole directory, so
nothing is left behind.
The previous values of options("viewer") and
options("shiny.launch.browser") are remembered and restored by
unuse_rustgd_webview().
Writes the data frame to the frames channel as Arrow IPC and opens, or reuses, the rustgd frames window to display it. Non-blocking: it returns at once and the window appears on its own, the same way the plot and web viewers behave. Each call adds a frame; later stages page through them as a gallery.
view(df, title = NULL) View(df, title = NULL)view(df, title = NULL) View(df, title = NULL)
df |
A data frame, or an object coercible to one. |
title |
Optional label shown in the window; defaults to the expression
passed in, for example |
The capitalized View() is an identical alias. Both are ordinary exports,
so they take effect as soon as the package is attached with
library(rustgd), needing no separate activation call. Once attached,
View() shadows utils::View() for the session (utils is a base package,
so an attached rustgd sits above it on the search path). Lowercase view()
can be overtaken if a package that also exports view() (such as tibble) is
attached after rustgd; re-run library(rustgd) or call rustgd::view().
The frame is written uncompressed so the viewer needs no compression codec.
Requires the arrow package for write_feather().
The path to the written Arrow file, invisibly.