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:
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
idUnique identifier used by
#idselectors, orNULL.classesCharacter vector of classes used by
.classselectors.helpOptional help text (Markdown) shown on the help screen (F1) while this widget or a descendant has focus.
paint_statesNames of state fields whose changes only need a repaint (see
invalidate_paint()); used byset_state().focusableCan the widget receive keyboard focus?
regionBorder box assigned by the layout engine (
region()).
Active bindings
parentThe parent widget (read-only).
childrenList of child widgets (read-only).
appThe App this widget belongs to, or
NULL.typeWidget type name used by type selectors.
visibleIs the widget shown? Hidden widgets take no space.
disabledDisabled widgets cannot be focused or used.
styleThe widget's own
style()(layered over its defaults).border_titleText shown in the top border (reactive), or
NULL.hoveredIs the mouse pointer over this widget (or a descendant)?
focusedDoes the widget currently have keyboard focus?
Methods
Widget$new()
Create a widget.
Usage
Widget$new(
...,
id = NULL,
classes = NULL,
style = NULL,
disabled = FALSE,
visible = TRUE
)Arguments
...Child widgets.
idOptional identifier.
classesCharacter vector (or space separated string) of classes.
styleA
style().disabledIs the widget disabled?
visibleIs the widget visible?
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.
Widget$clear()
Remove all children (containers). Some widgets redefine
clear() for their content (e.g. input(), log_view()).
Widget$query()
Find descendants matching a CSS-like selector.
Widget$on()
Handle events of a type that reach this widget (its own events and events bubbling up from descendants).
Arguments
typeEvent type, or
"*"for all.handlerfunction(event, app).selectorOptional 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().
Arguments
keyKey name or a
bind()binding.actionAction name or function.
descriptionOptional description.
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.
Widget$capture_mouse()
Receive all mouse events (also outside this widget's
region) until release_mouse() or the button is released.
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)Widget$set_timeout()
Call callback(self, app) once after delay seconds.
The timer is cancelled automatically when the widget is removed.
Returns
A Timer.
Widget$set_interval()
Call callback(self, app) every interval seconds
while the widget is mounted.
Returns
A Timer.
Widget$animate()
Animate a numeric field of this widget. See animate().
Arguments
propertyField name.
toTarget 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().
Arguments
fnFunction to run.
...Other arguments of
run_worker().
Widget$run_process()
Run an external program owned by this widget. See
run_process().
Arguments
commandProgram to run.
...Other arguments of
run_process().
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.
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.
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.
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.
Widget$render_lines()
Rendered content as lines of styled segments (cached until the widget is invalidated).
Widget$arrange_children()
Place the visible children inside the content box. Containers with special behaviour (scrolling, ...) override this.
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.
Widget$paint()
Paint the widget (not its children) into a buffer.
Arguments
bufferA ScreenBuffer.
areaThe visible part of
self$region.stThe computed style.
Widget$format()
A one-line description used by print().