pub struct Program { /* private fields */ }Expand description
The live event loop and application root.
Program is the application root: it owns the single event loop, the
desktop / status-line / menu-bar subviews, the TimerQueue, and the
CaptureStack. Program::run is the only loop (Program::pump_once
is one iteration), and modality is a ModalFrame on the CaptureStack:
a handler that consumes every otherwise-unhandled event is the modal loop.
§How it works
-
One loop, no nested modal loops.
Program::runis the single event loop andpump_onceis one iteration; modal dialogs are realized as aModalFramecapture handler rather than a nested blocking loop. -
Broadcasts carry a subject.
Event::Broadcastcarries asource: ViewIdidentifying the subject view;Event::Commandcarries only theCommand. Integer payloads are not served bysource(they are notViewIds): a fired timer’s id is carried byEvent::Timer, and a window number is resolved by a direct desktop walk. -
Whole-tree redraw + diff every pass. No damage tracking; a terminal resize is picked up by the size check at the top of
pump_once(the backend reports terminal size live). -
Injected
Clock+Backend. Headless never blocks, so tests drivepump_oncesynchronously with aManualClock. -
String commands, enabled-by-default. The command set is stored as its complement — the disabled set, seeded with the five startup-disabled window commands (see
initial_disabled_commands). Every command not in it, including any app-mintedCommand::custom, is enabled. Seedocs/design/command-enablement.md.
Modal dialogs (exec_view / messageBox / inputBox)
run on top of the ModalFrame mechanism; Alt-1..9 window selection walks the
desktop directly for the child whose number matches; the
status line and menu bar are real subviews that the pump pre-routes keyDown and
over-the-line mouseDown events to before normal dispatch.
§Turbo Vision heritage
Ports TProgram (tprogram.cpp/tprogram.h), the application root and its
blocking event loop. The single non-recursive loop plus a capture stack
replaces the original’s nested modal loops (deviation D9); broadcasts carry a
ViewId subject instead of a raw pointer (deviation D4). The original
derived an application class from this root by inheritance; here
Application embeds a Program and forwards to
it (deviation D2).
Implementations§
Source§impl Program
impl Program
Sourcepub fn new(
backend: Box<dyn Backend>,
clock: Box<dyn Clock>,
theme: Theme,
create_desktop: impl FnOnce(Rect) -> Option<Box<dyn View>>,
create_status_line: impl FnOnce(Rect) -> Option<Box<dyn View>>,
create_menu_bar: impl FnOnce(Rect) -> Option<Box<dyn View>>,
) -> Self
pub fn new( backend: Box<dyn Backend>, clock: Box<dyn Clock>, theme: Theme, create_desktop: impl FnOnce(Rect) -> Option<Box<dyn View>>, create_status_line: impl FnOnce(Rect) -> Option<Box<dyn View>>, create_menu_bar: impl FnOnce(Rect) -> Option<Box<dyn View>>, ) -> Self
Construct the program. The three subviews are built from injected factory
closures over the full program extent; each factory owns its own shrinking
(the status-line / menu-bar factories may return None to omit them).
Construction behavior:
- Bounds =
(0, 0, w, h)frombackend.size(). - The root group’s state gets
active/selected/focused/modalset directly (it is the always-visible, always-focused root). - Insert desktop, status-line, menu-bar in that order.
- The desktop is made
currentso focused events route into it (theinsertdeliberately does not auto-select).
§Turbo Vision heritage
Ports TProgram::TProgram (tprogram.cpp); the factory closures stand in
for the original’s virtual initDeskTop / initStatusLine / initMenuBar
factory-mixin hooks.
Sourcepub fn desktop(&self) -> Option<ViewId>
pub fn desktop(&self) -> Option<ViewId>
The desktop child’s ViewId, or None if the create_desktop factory
returned None at construction.
The id is stable for the application lifetime. Use it when you need to
reach the desktop view directly (e.g. to call a method on a custom desktop
subtype via as_any_mut). To open new windows in the desktop at runtime,
prefer Program::desktop_insert — it handles the Context and focus
bookkeeping for you.
§Turbo Vision heritage
Ports the C++ TProgram::deskTop global static pointer
(include/tvision/app.h), reshaped into an owned ViewId handle (global
raw pointer → handle, resolved via find_mut).
The menu-bar child’s ViewId, or None if the create_menu_bar factory
returned None at construction.
The handle is stable for the application lifetime. Use it to resolve the
menu bar view when you need to update its items at runtime (e.g. to rebuild
the menu on locale change). For command-enablement, prefer
Program::enable_command / Program::disable_command — the menu bar
observes the cmCommandSetChanged broadcast automatically.
§Turbo Vision heritage
Ports the C++ TProgram::menuBar global static pointer
(include/tvision/app.h), reshaped into an owned ViewId handle.
Sourcepub fn status_line(&self) -> Option<ViewId>
pub fn status_line(&self) -> Option<ViewId>
The status-line child’s ViewId, or None if the create_status_line
factory returned None at construction.
The pump pre-routes KeyDown events to the status line first (so status-bar
hot keys fire regardless of focus), and over-the-line MouseDown events are
also pre-routed to it. Use the id when you need to reach the status-line view
directly (e.g. to call a custom method after downcasting via as_any_mut).
§Turbo Vision heritage
Ports the C++ TProgram::statusLine global static pointer
(include/tvision/app.h), reshaped into an owned ViewId handle. The
pre-routing behavior mirrors TProgram::getEvent (tprogram.cpp:153).
Sourcepub fn set_shell_msg_hook(&mut self, hook: Box<dyn Fn() -> String>)
pub fn set_shell_msg_hook(&mut self, hook: Box<dyn Fn() -> String>)
Register a closure that produces the shell-suspend message printed to the
terminal before the application yields to the shell (Command::DOS_SHELL,
typically wired to a “Shell” menu item or Ctrl-Z).
Call this once during setup when the default platform message is not appropriate — for example, to include your app name or instructions specific to your shell environment:
program.set_shell_msg_hook(Box::new(|| {
"MyApp is suspended. Type `fg` to return.".to_string()
}));When not set, the built-in platform default is used (Windows: “Type EXIT to
return…”; Unix: the fg return instruction).
§Turbo Vision heritage
Replaces the virtual TApplication::writeShellMsg override point
(tapplica.cpp). The C++ default printed "Type EXIT to return..." on
Windows/DOS and the fg-instruction on unix; that same branching logic
lives in the crate-private default_shell_msg helper.
Sourcepub fn set_on_idle(&mut self, f: impl FnMut(&mut Program) + 'static)
pub fn set_on_idle(&mut self, f: impl FnMut(&mut Program) + 'static)
Register a callback run once on every idle pass of the event loop — each iteration where no input event was waiting.
Use it for background work that should advance whenever the app is not
busy: a clock, an animation frame, a periodic refresh. The callback gets
&mut Program, so it can insert/close windows, post commands, or read
state. Keep it cheap — it runs on the loop’s idle cadence (the 20 ms frame
tick), not a real-time scheduler. For exact timing, prefer a timer
(Event::Timer).
Only one idle callback is held; a second call replaces the first.
The hook fires on the idle passes of any loop level, including while a
modal dialog, message box, or other exec_view is open — so a clock keeps
ticking during a dialog rather than freezing. It does not re-enter
itself: while the hook runs, it is taken out, so a modal it opens will not
fire the hook recursively.
§Driving the UI from external / async data sources
set_on_idle is the program-level hook for draining external data into
the view tree. The pattern:
- Hold shared application state in an
Rc<RefCell<AppState>>cloned into each view factory closure and into the idle callback. - In the callback, drain the external source (e.g.
try_recvon astd::sync::mpsc::Receiver) into the shared state. - Broadcast a refresh command with
broadcastso interested views repaint from the updated state. Use a stableCommand::custom("myapp.refresh")constant. Any other event can be queued withput_event. Both are queued, not dispatched inside the hook: the event reaches the views on the next pump pass.
let shared = Rc::new(RefCell::new(AppState::default()));
let shared_idle = Rc::clone(&shared);
program.set_on_idle(move |prog| {
let mut state = shared_idle.borrow_mut();
if let Ok(msg) = receiver.try_recv() {
state.update(msg);
drop(state); // release borrow before broadcast
prog.broadcast(REFRESH, None);
}
});For view-owned drains (where the drain logic lives inside a view with
access to Context rather than &mut Program), prefer a periodic timer
set via Context::set_timer combined with Context::broadcast. A
zero-area child view can hold the timer and be invisible on screen while
still receiving every Event::Timer tick — see Context::set_timer for
the cross-reference.
§Turbo Vision heritage
The successor to overriding TProgram::idle, which Turbo Vision called
once per event-less loop pass (the guide’s clock / heap-display pattern),
including during modal execute() loops.
Sourcepub fn double_delay_ms(&self) -> u64
pub fn double_delay_ms(&self) -> u64
The double-click interval, in ms: a mouse press with the same buttons
on the same cell at most this long after the previous press is flagged
double_click (then
triple_click).
Default 440 ms.
§Turbo Vision heritage
Reads TEventQueue::doubleDelay (tevent.cpp), kept in 55 ms ticks
there.
Sourcepub fn set_double_delay_ms(&mut self, ms: u64)
pub fn set_double_delay_ms(&mut self, ms: u64)
Set the double-click interval, in ms (see
double_delay_ms). A mouse-settings dialog
calls this.
§Turbo Vision heritage
Writes TEventQueue::doubleDelay, the public static tvdemo’s mouse
dialog tunes (mousedlg.cpp).
Sourcepub fn end_modal(&mut self, cmd: Command)
pub fn end_modal(&mut self, cmd: Command)
Signal that the event loop should stop, returning cmd as the result
of run once the tree validates it.
Owner-side, immediate. Call this when you already hold
&mut Program — for example from an application main, a test
harness, or a startup sequence. For the far more common case where a
view closes a dialog from inside handle_event, use
Context::end_modal instead (which
pushes a deferred effect that the pump applies after dispatch unwinds).
Rule of thumb: view → ctx.end_modal; owner / top-level →
Program::end_modal.
See also: ending a modal in the tvision-rs guide.
§Turbo Vision heritage
Ports TGroup::endModal (tgroup.cpp).
Sourcepub fn end_state(&self) -> Option<Command>
pub fn end_state(&self) -> Option<Command>
The current modal end state, if set (test/inspection hook).
Sourcepub fn put_event(&mut self, ev: Event)
pub fn put_event(&mut self, ev: Event)
Queue ev for the loop. The next pump pass takes it before it polls the
backend, and routes it like any input event (through the capture stack
when a modal or menu is open). This is how code that holds &mut Program — an idle hook (set_on_idle), or the
application between pump_once calls — injects an
event. Views use Context::put_event instead.
The idle hook also runs while a modal is open. Then a queued command or
key reaches only the modal and is dropped if the modal does not handle
it, as in C++ TGroup::execute. While a drag holds the input, a queued
command or key is discarded, as the C++ hold loops discard it. To tell
views to refresh, use
broadcast: broadcasts and timer expiries reach the
whole tree also under a modal (D9).
§Turbo Vision heritage
Ports TProgram::putEvent (tprogram.cpp). C++ holds one pending
event and a second putEvent overwrites the first; here the events
queue up in order, so none is lost.
Sourcepub fn broadcast(&mut self, command: Command, source: Option<ViewId>)
pub fn broadcast(&mut self, command: Command, source: Option<ViewId>)
Queue a broadcast of command for the loop. source names the view the
broadcast is about, or None. The broadcast is delivered on a later pump
pass, to every view in the tree, also while a modal is open (D9). A
window drag or an open menu discards a broadcast that arrives while it
holds the input.
§Turbo Vision heritage
The successor to message(app, evBroadcast, command, infoPtr) from an
overridden TProgram::idle. C++ message dispatches at once; here the
broadcast is queued, because the idle hook runs between pump passes.
Sourcepub fn enable_command(&mut self, cmd: Command)
pub fn enable_command(&mut self, cmd: Command)
Enable cmd program-wide. On a real change (the command was previously
disabled) this sets the command-set-changed flag so the next idle pass
broadcasts the new command set, letting menus and the status line regray.
§Turbo Vision heritage
Ports TView::enableCommand (tview.cpp), program-side.
Sourcepub fn disable_command(&mut self, cmd: Command)
pub fn disable_command(&mut self, cmd: Command)
Disable cmd program-wide. On a real change (the command was previously
enabled) this sets the command-set-changed flag (see
enable_command).
§Turbo Vision heritage
Ports TView::disableCommand (tview.cpp), program-side.
Sourcepub fn command_enabled(&self, cmd: Command) -> bool
pub fn command_enabled(&self, cmd: Command) -> bool
Whether cmd is currently enabled: enabled iff not in the disabled set.
The command space is open strings — all enabled by default and all
maskable.
§Turbo Vision heritage
Ports TView::commandEnabled (tview.cpp).
Sourcepub fn get_tile_rect(&mut self) -> Option<Rect>
pub fn get_tile_rect(&mut self) -> Option<Rect>
The rectangle that the desktop’s tile and cascade layout operations lay
windows into: the desktop child’s local-origin extent (0, 0, w, h).
Returns None if no desktop was created. The TILE and CASCADE command
handlers read this rect so window layout stays within the desktop area even
when the desktop is inset below a menu bar or above a status line. If you
want to restrict tiling to a sub-region, size the desktop accordingly rather
than overriding this method.
Requires &mut self because Group::find_mut requires &mut.
§Turbo Vision heritage
Ports TApplication::getTileRect (tapplica.cpp).
Sourcepub fn run(&mut self) -> Command
pub fn run(&mut self) -> Command
Drive the event loop until the application posts a quit command that passes validation, then return it.
This is the outer loop of a tvision-rs application. Call it once from
main after building the Program and inserting startup views:
loop {
end_state = None;
while end_state.is_none() { pump_once(); }
let es = end_state.unwrap();
if valid_end(es) { return es; }
}Each iteration of pump_once picks one event,
routes it through the view tree, applies deferred effects, then
redraws and diffs. The outer loop re-runs the entire validate/pump
cycle if a view refuses the end state (e.g. an unsaved-file guard
that cancels the quit).
For app-level command handling use
run_app instead; for a single pump step (tests,
headless drivers) use pump_once.
With a production SystemClock + a real backend, polling for an event
blocks, so this does not spin. Do not call on a headless backend
without a QUIT path — headless never blocks, so it would busy-loop;
tests step pump_once instead.
See also: the single modal loop in the tvision-rs guide.
§Turbo Vision heritage
Ports TProgram::run → TGroup::execute (tprogram.cpp / tgroup.cpp).
The per-group nested loop of the original is replaced by a single top-level
loop plus a ModalFrame capture handler for modality.
Sourcepub fn run_app<F>(&mut self, on_command: F) -> Command
pub fn run_app<F>(&mut self, on_command: F) -> Command
Run the application, calling on_command for each Command that reaches
the program level but is not consumed by any view or the built-in program
handlers (QUIT, TILE, CASCADE, Alt-N window select). This is the hook for
application-level commands such as “File → Color Picker” → color_dialog.
The handler receives &mut Program so it can call methods like
color_dialog, message_box,
and input_box in response to menu-driven commands.
§Example
use tvision_rs::{Color, Command};
const CMD_PICK: Command = Command::custom("my_app.pick_color");
// program.run_app(|prog, cmd| {
// if cmd == CMD_PICK { prog.color_dialog(Color::Default); }
// });Sourcepub fn exec_view(&mut self, view: Box<dyn View>) -> Command
pub fn exec_view(&mut self, view: Box<dyn View>) -> Command
Run view as a modal dialog: insert it into the root group, pump the event
loop until the view (or the user) posts an end command, then remove it and
return that command.
Call this from an app main or test harness when you need a blocking
modal — e.g. an open-file dialog at startup, a settings panel, or a
confirm-quit box triggered by app-level code. For the common built-in dialogs
prefer the typed wrappers: message_box,
input_box, open_file_dialog.
Top-level only — the type system enforces it: a View holds only
&mut Context, never &mut Program, so a view cannot call this from
inside handle_event (which is what keeps the nested
pump_once loop sound). Call from an app main,
startup, or a test driving pre-queued events. A view-/menu-triggered modal
instead requests one through the deferred channel
(Deferred::OpenModal + a posted completion command).
Only the modal view handles focused events during the modal pump.
While the ModalFrame is on the capture stack, keys, commands and
pastes go to the modal view alone, as TGroup::execute hands them to
p->handleEvent. A command it does not consume is dropped
(eventError): the menu bar, the Alt-N window selection, the quit
catch, cmTile/cmCascade/cmDosShell and the application command handler
of run_app do not see it. So a Command::QUIT — for
example from the status line’s Alt-X — leaves the modal open. The
status line still sees keys and clicks first, as in
TProgram::getEvent.
HEADLESS HANG WARNING: pump_once does not block on a
headless backend, so the inner while end_state.is_none() loop spins until
something sets end_state. The caller MUST ensure the modal reaches
Context::end_modal (e.g. a pre-queued OK/Cancel, or an Esc that a
Dialog turns into a posted cancel). A modal with
no path to end_modal hangs.
Control flow:
- Save the current focus + a clone of the command set.
- Insert the view into the root group. Insert FIRST so
set_currentcan resolve the id. - Clear the selectable option on the view (so it is not part of normal focus rotation while modal).
- Set the modal state bit directly (it does not propagate to children).
- Make the view current — selects + focuses it (fires its command enables, deferred; unwound by the command-set restore in step 9).
- Push the
ModalFramedirectly (we hold&mut self, not inside a dispatch). - The loop:
loop { end_state = None; while none { pump_once }; if the MODAL view's own valid(es) break es }— validate against the modal view’s ownvalid, NOT the root group’s. - Pop the frame, remove the view, restore the saved focus.
- Restore the command set.
See also: the modal chapter in the tvision-rs guide.
§Turbo Vision heritage
Ports TGroup::execView + TGroup::execute (tgroup.cpp), run on the
owner program group. The blocking nested loop becomes a single pump plus a
ModalFrame capture handler (deviation D9).
Sourcepub fn exec_view_focused(
&mut self,
view: Box<dyn View>,
initial_focus: ViewId,
) -> Command
pub fn exec_view_focused( &mut self, view: Box<dyn View>, initial_focus: ViewId, ) -> Command
Like exec_view, but focuses initial_focus (a child of
view) when the modal opens, overriding the default open-time currency.
Without an explicit focus, a freshly-opened modal selects the last
inserted selectable child (the first_match_visible_selectable order — bottom
child, then top-down). For an OK/Cancel Dialog
whose buttons are inserted OK-then-Cancel, that lands focus on Cancel;
since a focused button acts as the dialog’s default (Enter target), pressing
Enter would then fire Cancel. Pass the OK/default button’s
ViewId here so it opens focused and Enter triggers it.
This is the same initial_focus override the built-in
message_box uses internally (it focuses its first
button); this method exposes it for hand-built dialogs run through the public
API. initial_focus is resolved within view’s group via
View::focus_descendant; an id that names no child is a silent no-op (the
default currency stands).
§Turbo Vision heritage
A convenience over execView, which takes no focus argument. It bundles
execView with the focus seed a C++ caller applies by hand before it, for
example msgbox.cpp’s selectNext(False) to land the first
button — here generalized to focus any descendant by ViewId
via View::focus_descendant, closer to setCurrent(p, …) than to
selectNext.
Sourcepub fn message_box_rect(
&mut self,
r: Rect,
msg: &str,
kind: MessageBoxKind,
buttons: MessageBoxButtons,
) -> Command
pub fn message_box_rect( &mut self, r: Rect, msg: &str, kind: MessageBoxKind, buttons: MessageBoxButtons, ) -> Command
Build and run a message-box dialog at an explicit Rect. Construction and
execution are split: build_message_box builds the dialog (pure, testable),
and exec_view runs it.
kind picks the title (Warning / Error / Information / Confirm).
buttons selects which of [Yes, No, OK, Cancel] to show.
Returns the Command the user chose (Command::OK, Command::CANCEL,
Command::YES, Command::NO).
§Turbo Vision heritage
Ports messageBoxRect (msgbox.cpp).
Sourcepub fn message_box(
&mut self,
msg: &str,
kind: MessageBoxKind,
buttons: MessageBoxButtons,
) -> Command
pub fn message_box( &mut self, msg: &str, kind: MessageBoxKind, buttons: MessageBoxButtons, ) -> Command
Build and run a message-box dialog auto-centered on the desktop.
Sizing logic:
- Base rect
(0, 0, 40, 9). - If
msg.chars().count() > (40-7) * (9-6), expand the height:h = char_count / (40-7) + 6 + 1. - Center within the desktop’s size (or the root group’s size if no desktop was created).
Coordinate note: exec_view root-inserts the modal, so the rect is
in absolute/root coords, while centering uses the desktop’s SIZE. When the
desktop is inset by a menu/status bar, the centered box can therefore sit
off by the menu-bar offset.
§Turbo Vision heritage
Ports messageBox + its makeRect helper (msgbox.cpp).
Sourcepub fn input_box_rect(
&mut self,
bounds: Rect,
title: &str,
label: &str,
initial: &str,
limit: i32,
) -> (Command, String)
pub fn input_box_rect( &mut self, bounds: Rect, title: &str, label: &str, initial: &str, limit: i32, ) -> (Command, String)
Build and run a single-line input dialog at an explicit Rect. The modal
insertion / teardown lives here in Program and the typed value currency
carries the scatter (seed) / gather (read-back). Construction is split out
into the pure build_input_box builder.
label is the prompt drawn left of the field; initial is the starting
text, seeded into the input line with select-all; limit caps the field’s
byte length (max length = limit - 1).
Returns (cmd, text) where cmd is the end Command (Command::OK /
Command::CANCEL). On a non-cancel result, text is the field’s final
contents; on cancel, text is the unchanged initial.
Single-field shortcut (not the general group-walk). The input box has
exactly one transferable field (the lone
InputLine), so scatter = set_value on it
and gather = value() on it. The general Dialog gather/scatter group-walk
is supplied by its multi-field consumers.
§Turbo Vision heritage
Ports inputBoxRect (msgbox.cpp); the value currency replaces the
original’s setData/getData transfer (deviation D10).
Sourcepub fn input_box(
&mut self,
title: &str,
label: &str,
initial: &str,
limit: i32,
) -> (Command, String)
pub fn input_box( &mut self, title: &str, label: &str, initial: &str, limit: i32, ) -> (Command, String)
Build and exec a single-line input dialog auto-centered on the desktop.
Convenience wrapper around input_box_rect that
computes the position automatically (base rect 60 × 8, centered within
the desktop). Use this when you don’t need precise placement; use
input_box_rect when you need an explicit position.
title is the dialog frame label. label is the prompt drawn left of the
field. initial seeds the input line (the entire text is pre-selected so
the user can immediately type a replacement). limit caps the field byte
length (max length = limit - 1).
Returns (cmd, text). If the user presses OK, cmd = Command::OK and
text holds what they typed. If the user presses Cancel or Esc,
cmd = Command::CANCEL and text is the unchanged initial.
Coordinate note: centering uses the desktop’s SIZE; when the desktop is inset by a menu/status bar, the box can sit off by the menu-bar offset.
§Turbo Vision heritage
Ports inputBox (msgbox.cpp); the size offset is deskTop->size.x/y.
Sourcepub fn color_dialog(&mut self, initial: Color) -> Option<Color>
pub fn color_dialog(&mut self, initial: Color) -> Option<Color>
Open the truecolor color-picker modal seeded with initial; return the
chosen Color on OK, or None on Cancel/Esc.
The picker presents four surface tabs (Presets, RGB, Plane, Xterm-256), an Info column showing old and new swatches, and OK/Cancel buttons. Call this from your application’s event handler when the user selects a “Pick Color” menu item or similar:
let new_color = program.color_dialog(current_color);
if let Some(c) = new_color {
// apply c
}The chosen color is read out of the modal’s own
ColorPicker and returned by value via
exec_view_with-style capture. Color is
deliberately not a FieldValue (a 4-variant enum, not a packable scalar;
spec non-goal).
§Turbo Vision heritage
tvision-rs extension: no Turbo Vision counterpart. Supersedes TColorDialog
(guide pp. 406–409), which edited the application’s TPalette, each
entry a foreground/background attribute built from the BIOS colors.
tvision-rs replaces it with a
truecolor picker that returns an Option<Color> directly instead of
mutating an in-memory TPalette blob.
Sourcepub fn set_theme(&mut self, theme: Theme)
pub fn set_theme(&mut self, theme: Theme)
Install a new theme and force a full repaint (theme editor).
Sourcepub fn theme_editor(&mut self)
pub fn theme_editor(&mut self)
Sourcepub fn desktop_rect(&mut self) -> Rect
pub fn desktop_rect(&mut self) -> Rect
The desktop’s local extent (0,0,w,h). Use it to compute bounds for
windows opened at runtime (e.g. CMD_NEW). Returns a zero rect when no
desktop was created.
Sourcepub fn desktop_insert(&mut self, view: Box<dyn View>) -> Option<ViewId>
pub fn desktop_insert(&mut self, view: Box<dyn View>) -> Option<ViewId>
Insert view into the desktop and make it the current (focused) window.
This is the standard way to open a new window at runtime: call it from your
run_app command handler (e.g. on CMD_NEW) with a freshly constructed
Window or Dialog.
Returns the new view’s ViewId on success, or None if no desktop was
created or the desktop downcast fails.
§Turbo Vision heritage
C++ TProgram::insertWindow (tprogram.cpp) disposes a window being
inserted when the active window cannot release focus (validView /
canMoveFocus). tvision-rs does not gate a programmatic insert: the
focus-release check (valid(RELEASED_FOCUS)) is applied where it matters
interactively — Alt-N window selection and modal close — not on insert. An
app that inserts a window expects it to appear; refusing the insert
(DOS-era behavior) would surprise more than it protects.
Sourcepub fn open_file_dialog(
&mut self,
title: &str,
wild_card: &str,
) -> Option<PathBuf>
pub fn open_file_dialog( &mut self, title: &str, wild_card: &str, ) -> Option<PathBuf>
Show a file-open dialog and return the chosen PathBuf, or None on
cancel. Runs a FileDialog modally and reads
back the resolved filename.
wild_card is the initial filename pattern (e.g. "*.*"), title is the
dialog caption (e.g. "Open a File").
Sourcepub fn exec_view_with<R>(
&mut self,
view: Box<dyn View>,
extract: impl FnOnce(&mut dyn View, Command) -> R,
) -> R
pub fn exec_view_with<R>( &mut self, view: Box<dyn View>, extract: impl FnOnce(&mut dyn View, Command) -> R, ) -> R
Execute view as a modal and return a caller-typed result extracted from
the finished modal by value — no shared Rc cell and no dyn Any in
the framework. extract runs once, at modal close, receiving the modal’s
own &mut dyn View and the end Command while the view is still in the
tree; whatever it returns is handed straight back to the caller.
R is named by the caller and never by the framework. A consumer that
needs a single field can read it through View::value; a consumer that
needs a richer native value (a Color, a whole
Theme) returns it directly from extract.
§Turbo Vision heritage
The value-returning twin of TGroup::execView (tgroup.cpp:188), which
returns a ushort end command to its method caller. Where C++ then reads
results out of the still-live dialog with getData, extract reads them
by value here.
Sourcepub fn pump_once(&mut self) -> bool
pub fn pump_once(&mut self) -> bool
One iteration of the event loop.
Borrow discipline: self is destructured into field
bindings at the top, so the disjoint fields backing Context
(out_events / timers / deferred) can be borrowed alongside
group / captures. The dispatch is a free function with explicit field
borrows; there are no &mut self helpers with overlapping field sets.
Returns true when this pass was idle — the None => arm ran because
no input event (real, queued, or synthesized mouse-auto) was waiting. The
run loop uses this to fire the user idle hook (set_on_idle)
outside this destructured borrow.
Auto Trait Implementations§
impl !RefUnwindSafe for Program
impl !Send for Program
impl !Sync for Program
impl !UnwindSafe for Program
impl Freeze for Program
impl Unpin for Program
impl UnsafeUnpin for Program
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can
then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be
further downcast into Rc<ConcreteType> where ConcreteType implements Trait.§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &Any’s vtable from &Trait’s.§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &mut Any’s vtable from &mut Trait’s.