An App owns the widget tree (through its Screen), the event queue,
timers, key bindings, focus and the terminal driver. Create one with
app() and start it with run().
Event loop
Each tick of the loop waits for input (or the next timer), turns input into events, fires due timers, dispatches every queued event and then, if any widget was invalidated, repaints the screen once: the new frame is diffed against the previous one and only changed cells are written.
Event dispatch
An event goes to its target widget (key events: the focused widget) and
bubbles up through the ancestors to the app. At each widget the
on_<type> method runs, then handlers added with widget$on(), then -
for key events - the widget's key bindings. At the app, handlers added
with app$on() / on() run, then app bindings. event$stop() stops
propagation.
Public fields
titleOptional application title.
reduce_motionNULL(follow the option / environment variable),TRUEorFALSE: reduce decorative animation? Seemotion_reduced().clipboardText copied by widgets (Ctrl+C / Ctrl+X in inputs). This is the app's own clipboard, not the operating system's.
Active bindings
screenThe current Screen.
screensThe screen stack, bottom first.
focusedThe focused widget, or
NULL.themeThe
termr_theme()(assign a theme or a theme name).stylesheetsThe stylesheets of the app.
hoveredThe widget under the mouse pointer, or
NULL.sizeTerminal size:
c(width =, height =).runningIs the app running?
last_paintInstrumentation of the last repaint: screen cells, repainted cells, dirty rectangles, whether it was a full repaint and the ANSI bytes written. For benchmarks and debugging.
profile_last_frameOptional timings and structural counters; enable with
options(termr.profile = TRUE). Times are milliseconds.frame_statsNumber of full and incremental repaints and of layout passes so far.
frameThe last rendered ScreenBuffer.
Methods
App$new()
Create an app. See app().
Arguments
...bindingsA list of
bind()bindings.actionsA named list of functions
function(app).titleOptional title.
mouseEnable mouse input?
stylesheetA
stylesheet(), stylesheet text or a file path (or a list of them).themeA
termr_theme()or the name of a built-in theme.debugBind F12 to the debug overlay?
reduce_motionTRUEto turn decorative animation off,NULLto followoptions(termr.reduce_motion)/ theTERMR_REDUCE_MOTIONenvironment variable.
App$on()
Add an event handler, see on().
App$bind()
Add an app-level key binding, see bind().
Arguments
keyKey name or a binding created by
bind().actionAction name or function.
descriptionOptional description.
App$log_events()
Record dispatched events (for debugging). Off by default, so normal apps pay nothing.
App$add_command()
Add a command to the command palette (Ctrl+P) and the
help screen (F1). See command().
App$show_help()
Show the help screen (F1): key bindings of the focused widget, its ancestors and the app, and the app's commands.
App$post_message()
Send a custom message from the app (bubbles from the screen).
Usage
App$post_message(type, data = list())App$clipboard_write()
Copy text to the clipboard. The app clipboard
(app$clipboard) is always set; when system = TRUE and the terminal
supports OSC 52 the text is also sent to the system clipboard
(write-only: termr never reads the system clipboard). Long text is
truncated to 100 kB for the terminal.
App$capture_mouse()
Send all mouse events to widget (even outside its
region) until release_mouse() or the next button release. Used for
drags that start elsewhere, e.g. splitters.
App$request_repaint()
Schedule a repaint at the end of the current tick.
Usage
App$request_repaint(widget = NULL, full = is.null(widget), layout = TRUE)Arguments
widgetThe widget that changed, if known. Without it the next repaint redraws everything; with it only the rows of changed widgets are repainted when the layout did not change.
fullForce a full repaint?
layoutDoes the change possibly affect sizes or positions? When
FALSEand nothing else changed the layout pass is skipped.
App$add_stylesheet()
Add a stylesheet; its rules apply to all screens.
Arguments
sheetA
stylesheet(), stylesheet text or a file path.
App$push_screen()
Show a screen on top of the current one. A widget is
wrapped in a new Screen. Use modal() for dialogs.
Arguments
screenA Screen (or ModalScreen) or a widget.
callbackOptional
function(result, app)called when the screen is dismissed / popped with a result.
App$pop_screen()
Remove the top screen (or a given screen) and return to the one below, restoring its focus.
App$run_worker()
Run a function in a background R process. See
run_worker() for the arguments.
Arguments
fn, args, on_complete, on_error, on_progress, name, owner, packages, inlineSee
run_worker().on_stdout, on_stderr, timeoutSee
run_worker().
App$run_process()
Run an external program in the background, without a
shell. See run_process().
Usage
App$run_process(
command,
args = character(),
on_complete = NULL,
on_error = NULL,
on_stdout = NULL,
on_stderr = NULL,
on_exit = NULL,
timeout = NULL,
wd = NULL,
env = NULL,
name = NULL,
owner = NULL
)Arguments
command, args, on_complete, on_error, on_stdout, on_stderr, on_exit, timeout, wd, env, name, ownerSee
run_process().
App$notify()
Show a notification (toast) in the bottom-right corner.
App$scroll_into_view()
Scroll every scroll view containing widget so that it
becomes visible (done at the next repaint).