termr
Modern Reactive Terminal Applications with Data Workflows

Package index
Search the termr package
Vignettes
Functions
602
Source code
177
Man pages
131
Home
/
CRAN
/
termr
/
Widget-class: Widget base class

Widget-class: Widget base class
In termr: Modern Reactive Terminal Applications with Data Workflows

WidgetR Documentation

Widget base class

Description

Every element of a termr interface is a Widget. Widgets form a tree: each widget has one parent and an ordered list of children. Most users create widgets with constructor functions such as label() or vertical(), and define new widget types with widget(). Subclassing Widget with R6::R6Class() is also supported for advanced use.

A subclass usually overrides some of:

  • default_style(): the built-in style() of the widget type;

  • render(): returns the content as a string, a character vector of lines or span()s;

  • on_key(event): handle a key press (return TRUE when handled);

  • paint(buffer, area, st): full control over drawing.

State

Widget state lives in reactive fields: assigning a new value invalidates the widget and schedules a repaint. Several assignments in one event loop tick produce a single repaint.

Public fields

id

Unique identifier used by ⁠#id⁠ selectors, or NULL.

classes

Character vector of classes used by .class selectors.

help

Optional help text (Markdown) shown on the help screen (F1) while this widget or a descendant has focus.

paint_states

Names of state fields whose changes only need a repaint (see invalidate_paint()); used by set_state().

focusable

Can the widget receive keyboard focus?

region

Border box assigned by the layout engine (region()).

Active bindings

parent

The parent widget (read-only).

children

List of child widgets (read-only).

app

The App this widget belongs to, or NULL.

type

Widget type name used by type selectors.

visible

Is the widget shown? Hidden widgets take no space.

disabled

Disabled widgets cannot be focused or used.

style

The widget's own style() (layered over its defaults).

border_title

Text shown in the top border (reactive), or NULL.

hovered

Is the mouse pointer over this widget (or a descendant)?

focused

Does the widget currently have keyboard focus?

Methods

Public methods

Widget$new()

Create a widget.

Usage
Widget$new(
  ...,
  id = NULL,
  classes = NULL,
  style = NULL,
  disabled = FALSE,
  visible = TRUE
)
Arguments
...

Child widgets.

id

Optional identifier.

classes

Character vector (or space separated string) of classes.

style

A style().

disabled

Is the widget disabled?

visible

Is the widget visible?

Widget$default_style()

The built-in style of this widget type.

Usage
Widget$default_style()

Widget$render()

Content of the widget (string, lines or spans). Containers return NULL.

Usage
Widget$render()

Widget$mount()

Add child widgets, at the end or at a position. A widget that already has a parent is moved. Ids must be unique within a screen.

Usage
Widget$mount(..., before = NULL, after = NULL)
Arguments
...

Widgets or lists of widgets.

before, after

A child widget (or its index) to insert before / after.

Widget$replace()

Remove all children and mount new ones.

Usage
Widget$replace(...)
Arguments
...

Widgets.

Widget$clear()

Remove all children (containers). Some widgets redefine clear() for their content (e.g. input(), log_view()).

Usage
Widget$clear()

Widget$remove()

Detach this widget (and its children) from its parent.

Usage
Widget$remove()

Widget$remove_children()

Remove all children.

Usage
Widget$remove_children()

Widget$walk()

This widget followed by all descendants (depth first).

Usage
Widget$walk()

Widget$ancestors()

Parent, grandparent, ... up to the root.

Usage
Widget$ancestors()

Widget$query()

Find descendants matching a CSS-like selector.

Usage
Widget$query(selector)
Arguments
selector

E.g. "Button", "#name", ".danger", "Vertical > Button.primary", or several separated by commas.

Returns

A list of widgets.

Widget$query_one()

The first descendant matching selector.

Usage
Widget$query_one(selector)
Arguments
selector

A selector, see query().

Widget$matches()

Does this widget match selector?

Usage
Widget$matches(selector)
Arguments
selector

A selector, see query().

Widget$on()

Handle events of a type that reach this widget (its own events and events bubbling up from descendants).

Usage
Widget$on(type, handler, selector = NULL)
Arguments
type

Event type, or "*" for all.

handler

⁠function(event, app)⁠.

selector

Optional selector matched against the event sender. The order of on() / app$on(), widget$on(type, selector, handler), is accepted too.

Widget$bind()

Add a key binding to this widget, see bind().

Usage
Widget$bind(key, action = NULL, description = NULL)
Arguments
key

Key name or a bind() binding.

action

Action name or function.

description

Optional description.

Widget$default_bindings()

Built-in bindings of this widget type.

Usage
Widget$default_bindings()

Widget$bindings()

All bindings of this widget (type bindings first, so instance bindings win).

Usage
Widget$bindings()

Widget$bind_reactive()

Keep a field in sync with a reactive function: fn runs now and again whenever the signal()s it reads change, and its result is assigned to field (e.g. "text" for a label). The binding ends when the widget is removed.

Usage
Widget$bind_reactive(field, fn)
Arguments
field

Name of a widget field (an active binding such as text).

fn

A function of no arguments.

Widget$capture_mouse()

Receive all mouse events (also outside this widget's region) until release_mouse() or the button is released.

Usage
Widget$capture_mouse()

Widget$release_mouse()

Stop capturing the mouse.

Usage
Widget$release_mouse()

Widget$run_action()

Run an action, looked up on this widget, its ancestors, then the app.

Usage
Widget$run_action(action)
Arguments
action

Action name or function.

Widget$post_message()

Send a message that bubbles up from this widget to the app. Handlers receive a MessageEvent whose sender is this widget.

Usage
Widget$post_message(type, data = list(), bubbles = TRUE)
Arguments
type

Message name, e.g. "counter.changed".

data

A list of values.

bubbles

Should the message bubble to ancestors?

Returns

The event (invisibly), or NULL when not attached to an app.

Widget$set_timeout()

Call callback(self, app) once after delay seconds. The timer is cancelled automatically when the widget is removed.

Usage
Widget$set_timeout(delay, callback)
Arguments
delay

Seconds.

callback

Function.

Returns

A Timer.

Widget$set_interval()

Call callback(self, app) every interval seconds while the widget is mounted.

Usage
Widget$set_interval(interval, callback)
Arguments
interval

Seconds.

callback

Function.

Returns

A Timer.

Widget$animate()

Animate a numeric field of this widget. See animate().

Usage
Widget$animate(property, to, ...)
Arguments
property

Field name.

to

Target value.

...

Other arguments of animate().

Widget$run_worker()

Run a background worker owned by this widget (cancelled when the widget is removed). See run_worker().

Usage
Widget$run_worker(fn, ...)
Arguments
fn

Function to run.

...

Other arguments of run_worker().

Widget$run_process()

Run an external program owned by this widget. See run_process().

Usage
Widget$run_process(command, ...)
Arguments
command

Program to run.

...

Other arguments of run_process().

Widget$focus()

Give keyboard focus to this widget.

Usage
Widget$focus()

Widget$blur()

Remove keyboard focus from this widget.

Usage
Widget$blur()

Widget$add_class()

Add classes.

Usage
Widget$add_class(...)
Arguments
...

Class names.

Widget$remove_class()

Remove classes.

Usage
Widget$remove_class(...)
Arguments
...

Class names.

Widget$toggle_class()

Add a class if absent, remove it if present.

Usage
Widget$toggle_class(name)
Arguments
name

Class name.

Widget$has_class()

Does the widget have this class?

Usage
Widget$has_class(name)
Arguments
name

Class name.

Widget$set()

Assign one or more fields, e.g. app$query_one("#name")$set(value = ""). R does not allow app$query_one("#name")$value <- "", so use this method when the widget comes from a function call.

Usage
Widget$set(...)
Arguments
...

Named values.

Returns

The widget, invisibly (so calls can be chained).

Widget$get_state()

Read a state field.

Usage
Widget$get_state(name)
Arguments
name

Field name.

Widget$set_state()

Write a state field; invalidates the widget when the value changes.

Usage
Widget$set_state(name, value)
Arguments
name

Field name.

value

New value.

Widget$layout_differs()

Would the widget's size-related style differ if it were in the pseudo states with rather than without? Used to decide whether a focus / hover change needs a layout pass.

Usage
Widget$layout_differs(with, without)
Arguments
with, without

Character vectors of states.

Widget$invalidate()

Mark the widget as needing a re-render and schedule a repaint, including a new layout pass (its size may have changed). Repaints are batched per event-loop tick.

Usage
Widget$invalidate()

Widget$invalidate_paint()

Like invalidate() for changes that cannot affect the size or position of anything (a cursor moved, a colour changed): the widget is repainted but the layout is not recomputed.

Usage
Widget$invalidate_paint()

Widget$refresh()

Force the widget to re-render on the next repaint.

Usage
Widget$refresh()

Widget$render_lines()

Rendered content as lines of styled segments (cached until the widget is invalidated).

Usage
Widget$render_lines(width = NA_integer_)
Arguments
width

Available content width (may be NA while measuring).

Widget$content_width()

Natural width of the content area.

Usage
Widget$content_width()

Widget$content_height()

Natural height of the content area for a given width.

Usage
Widget$content_height(width)
Arguments
width

Content width.

Widget$arrange_children()

Place the visible children inside the content box. Containers with special behaviour (scrolling, ...) override this.

Usage
Widget$arrange_children(children, inner, st)
Arguments
children

Visible child widgets.

inner

Content rectangle of this widget.

st

Computed style of this widget.

Returns

A list with one rectangle per child.

Widget$child_clip()

The rectangle children are clipped to when painting.

Usage
Widget$child_clip(st)
Arguments
st

Computed style of this widget.

Widget$pseudo_states()

Names of active states used to select state styles.

Usage
Widget$pseudo_states()

Widget$computed_style()

The fully resolved style of the widget.

Usage
Widget$computed_style(inherited = NULL)
Arguments
inherited

The parent's computed style (computed if NULL).

Widget$layout_descend()

Which children need their own layout? Containers that clip their children (scroll views) skip the ones that are entirely out of view; they get their region but not their descendants.

Usage
Widget$layout_descend(rects)
Arguments
rects

The rectangles arrange_children() returned.

Widget$paint()

Paint the widget (not its children) into a buffer.

Usage
Widget$paint(buffer, area, st)
Arguments
buffer

A ScreenBuffer.

area

The visible part of self$region.

st

The computed style.

Widget$is_enabled()

Is the widget and every ancestor enabled?

Usage
Widget$is_enabled()

Widget$is_displayed()

Is the widget and every ancestor visible?

Usage
Widget$is_displayed()

Widget$format()

A one-line description used by print().

Usage
Widget$format(...)
Arguments
...

Ignored.

Widget$print()

Print the widget tree.

Usage
Widget$print(...)
Arguments
...

Ignored.

Widget$clone()

The objects of this class are cloneable with this method.

Usage
Widget$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.


termr documentation built on Oct. 21, 2026, 5:13 p.m.

Related to Widget-class in termr...

termr index
Package overview README.md

R Package Documentation

rdrr.io home R language documentation Run R code online

Browse R Packages

CRAN packages Bioconductor packages R-Forge packages GitHub packages

We want your feedback!

Note that we can't provide technical support on individual packages. You should contact the package authors for that.
GitHub issue tracker
ian@mutexlabs.com
Personal blog

 
Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.

Close