| 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.0.0.9000 |
| Built: | 2026-06-13 09:59:29 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() route, 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() 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() route, 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 in one call: the graphics device for
plots, the web viewer for HTML widgets and Shiny apps (and explicit
URLs via rustgd_browse()), and the data frame viewer behind View().
The change takes
effect immediately in the current session, and a small snippet is also
written to your user-level .Rprofile so the same setup is restored
automatically in future sessions.
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 |
Two startup modes control only 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.
The web viewer and the View() route are turned on immediately in
both modes. The .Rprofile snippet is guarded by interactive() so
non-interactive contexts (Rscript, R CMD BATCH, knitr, testthat,
package checks) are unaffected, and by requireNamespace() so
uninstalling rustgd will not break R startup.
Safe to call repeatedly. Re-running with a different mode replaces
the existing snippet in place.
unuse_rustgd() to undo this, and rustgd_enable() for a
one-session activation that does not touch .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)
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 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.