Skip to main content

tvision_rs/
lib.rs

1//! # tvision-rs — a text-user-interface framework for Rust
2//!
3//! tvision-rs is an idiomatic Rust port of [magiblot/tvision](https://github.com/magiblot/tvision),
4//! a modern revival of Turbo Vision. It gives you the classic Turbo Vision
5//! experience — overlapping windows, modal dialogs, menus, a status line,
6//! validated input fields, scrollers and list boxes — built on a retained view
7//! tree and a single event loop, rendered to the terminal through a pluggable
8//! [`Backend`].
9//!
10//! ## House style: the `tv::` namespace
11//!
12//! Add the crate to `Cargo.toml` aliased as `tv`, and reach everything through
13//! the `tv::` path — the path *is* the namespace, so types drop the `T` prefix
14//! the original used in their names:
15//!
16//! ```toml
17//! # Cargo.toml
18//! tv = { package = "tvision-rs", version = "0.1" }
19//! ```
20//!
21//! ```
22//! # use tvision_rs as tv;
23//! let _r = tv::Rect::new(0, 0, 80, 25);
24//! ```
25//!
26//! Public types are therefore re-exported at the crate root below, even though
27//! they live in topical modules internally.
28//!
29//! ## Documentation
30//!
31//! - **Guide** (narrative, with live terminal screenshots): the [developer
32//!   guide](https://oetiker.github.io/tvision-rs/) walks through getting
33//!   started, building apps, the internals, and a widget gallery.
34//! - **Markdown sources & design notes**: the [`docs/` folder in the
35//!   repository](https://github.com/oetiker/tvision-rs/tree/main/docs) holds the
36//!   guide's Markdown sources, the C++→Rust porting reference, and the
37//!   cross-cutting design notes — raw `.md`, which is convenient to read directly
38//!   (and friendlier than rendered HTML for tools and LLMs ingesting the docs).
39//!
40//! ## Tour of the modules
41//!
42//! - [`view`] — the [`View`] trait and [`ViewState`] that every widget is built
43//!   on, plus geometry ([`Point`], [`Rect`]) and the [`Group`] container.
44//! - [`app`] — [`Program`], the application root that owns the event loop, and
45//!   [`Application`], which adds window tiling/cascading and shell suspend.
46//! - [`window`], [`dialog`], [`desktop`] — top-level frames: resizable windows,
47//!   modal dialogs, and the backdrop they sit on.
48//! - [`widgets`] — buttons, input lines, check boxes, list boxes, scrollers,
49//!   editors, the outline viewer, and more.
50//! - [`menu`], [`status`] — the menu bar / pull-down menus and the status line.
51//! - [`event`], [`command`] — the [`Event`] enum and key/mouse types, and the
52//!   command identifiers that drive them.
53//! - [`color`], [`theme`] — colors and styles, and the [`Theme`] that maps a
54//!   widget [`Role`] to glyphs and attributes.
55//! - [`screen`], [`backend`] — the cell buffer and diffing renderer, and the
56//!   [`Backend`] trait with its crossterm and headless implementations.
57//! - [`validate`], [`text`], [`timer`], [`capture`], [`data`], [`help`] — input
58//!   validators, text measurement, the timer queue, the event-capture stack,
59//!   the typed value protocol, and help contexts.
60//!
61//! # Turbo Vision heritage
62//!
63//! tvision-rs ports Borland's Turbo Vision as modernized by magiblot/tvision (a C++
64//! codebase). The pervasive translation choices — inheritance becomes the
65//! [`View`] trait plus [`ViewState`] composition, raw pointers become [`ViewId`]
66//! handles, flag words become structs of bools, and the palette becomes a
67//! [`Theme`] keyed by [`Role`] — are summarized in the project's guide.
68
69// Lets proc-macro-generated `::tvision_rs::Type` paths resolve inside this crate.
70extern crate self as tvision_rs;
71
72pub mod app;
73pub mod backend;
74pub mod capture;
75pub mod color;
76pub mod command;
77pub mod data;
78pub mod desktop;
79pub mod dialog;
80pub mod event;
81pub mod frame;
82pub mod help;
83pub mod junction;
84pub mod keymap;
85pub mod menu;
86pub mod screen;
87pub mod status;
88pub mod text;
89pub mod theme;
90pub mod timer;
91pub mod validate;
92pub mod view;
93pub mod widgets;
94pub mod window;
95
96// --- House-style root re-exports (so `tv::Point` etc. resolve without `use`) ---
97
98pub use app::{Application, ModalFrame, Program};
99pub use backend::{Backend, CrosstermBackend, HeadlessBackend, HeadlessHandle, Renderer};
100pub use capture::{CaptureFlow, CaptureHandler, CaptureStack, TrackMask};
101pub use color::{Color, Modifiers, Style};
102pub use command::{Command, CommandSet};
103pub use data::FieldValue;
104pub use desktop::{Background, Desktop};
105pub use dialog::{
106    BUTTON_GAP, BUTTON_ROW_FROM_BOTTOM, ButtonLayout, ButtonRowAlign, CD_HELP_BUTTON,
107    CD_NO_LOAD_DIR, CD_NORMAL, ChDirDialog, ColorPicker, Dialog, DirCollection, DirEntry,
108    DirListBox, FA_DIREC, FD_CLEAR_BUTTON, FD_HELP_BUTTON, FD_NO_LOAD_DIR, FD_OK_BUTTON,
109    FD_OPEN_BUTTON, FD_REPLACE_BUTTON, FileCollection, FileDialog, FileInfoPane, FileInputLine,
110    FileList, MARGIN_LEFT, MARGIN_RIGHT, MARGIN_TOP, MessageBoxButtons, MessageBoxKind, STD_BUTTON,
111    SearchRec, Tab, search_rec_compare,
112};
113pub use event::{
114    Event, EventMask, Key, KeyEvent, KeyModifiers, MouseButtons, MouseEvent, MouseEventFlags,
115    MouseWheel, ctrl_to_arrow, hot_key, is_alt_hotkey, is_plain_hotkey,
116};
117pub use frame::Frame;
118pub use help::HelpCtx;
119pub use junction::{Edge, JunctionMark, Weight};
120pub use keymap::{KeyStroke, Keymap, Resolve};
121pub use menu::{
122    Menu, MenuBar, MenuBox, MenuBuilder, MenuItem, MenuView, MenuViewState, alt, popup_menu,
123};
124pub use screen::{Buffer, Cell, DrawBuffer};
125pub use status::{HelpCtxRange, StatusColors, StatusDef, StatusItem, StatusLine};
126pub use theme::{Role, SurfaceRoles, Theme};
127pub use timer::{Clock, ManualClock, SystemClock, TimerId, TimerQueue};
128/// Embed-and-delegate: forward the un-written `View` methods to an inner view.
129///
130/// The delegate field owns the view's one `ViewState`, so the macro forwards
131/// `state`/`state_mut` too. This compiles and forwards everything:
132///
133/// ```
134/// use tvision_rs::{Group, Rect, View, delegate};
135///
136/// struct Panel {
137///     group: Group,
138/// }
139///
140/// #[delegate(to = group)]
141/// impl View for Panel {}
142///
143/// let p = Panel { group: Group::new(Rect::new(0, 0, 10, 5)) };
144/// assert_eq!(p.state().get_bounds(), Rect::new(0, 0, 10, 5));
145/// ```
146///
147/// A hand-written `state`/`state_mut` is accepted only when its body is the
148/// forwarder the macro would generate anyway. It is redundant; leave it out:
149///
150/// ```
151/// use tvision_rs::{Group, View, ViewState, delegate};
152///
153/// struct Panel {
154///     group: Group,
155/// }
156///
157/// #[delegate(to = group)]
158/// impl View for Panel {
159///     fn state(&self) -> &ViewState {
160///         self.group.state()
161///     }
162///     fn state_mut(&mut self) -> &mut ViewState {
163///         self.group.state_mut()
164///     }
165/// }
166/// ```
167///
168/// Parentheses around the receiver are accepted too:
169///
170/// ```
171/// use tvision_rs::{Group, View, ViewState, delegate};
172///
173/// struct Panel {
174///     group: Group,
175/// }
176///
177/// #[delegate(to = group)]
178/// impl View for Panel {
179///     fn state(&self) -> &ViewState {
180///         (self.group).state()
181///     }
182/// }
183/// ```
184///
185/// Any other `state`/`state_mut` body is a compile error: it would be a second
186/// `ViewState` that every forwarded method ignores.
187///
188/// ```compile_fail
189/// use tvision_rs::{Group, View, ViewState, delegate};
190///
191/// struct Panel {
192///     group: Group,
193///     st: ViewState,
194/// }
195///
196/// #[delegate(to = group)]
197/// impl View for Panel {
198///     fn state(&self) -> &ViewState {
199///         &self.st
200///     }
201///     fn state_mut(&mut self) -> &mut ViewState {
202///         &mut self.st
203///     }
204/// }
205/// ```
206///
207/// `skip(state)` / `skip(state_mut)` is rejected for the same reason. This
208/// example documents the rule; rustc would reject it anyway (E0046, missing
209/// required trait item), so the macro's check only gives a clearer message:
210///
211/// ```compile_fail
212/// use tvision_rs::{Group, View, delegate};
213///
214/// struct Panel {
215///     group: Group,
216/// }
217///
218/// #[delegate(to = group, skip(state))]
219/// impl View for Panel {}
220/// ```
221pub use tvision_rs_macros::delegate;
222pub use validate::{
223    FilterValidator, LookupValidator, PXPictureValidator, RangeValidator, RegexError,
224    RegexValidator, StringLookupValidator, Validator,
225};
226pub use view::{
227    Context, Deferred, DragMode, DrawCtx, Group, GrowMode, Options, Phase, Point, Rect, SelectMode,
228    State, StateFlag, View, ViewId, ViewState,
229};
230pub use widgets::Indicator;
231pub use widgets::PageStack;
232pub use widgets::TabBar;
233pub use widgets::{Button, ButtonFlags};
234pub use widgets::{CheckBoxes, Cluster, ClusterKind, MultiCheckBoxes, RadioButtons};
235pub use widgets::{ColumnSpec, ColumnState, RowKey, Table, TableModel, ValidatorFactory, VecModel};
236pub use widgets::{Constraints, DividerStyle, Orientation, Splitter};
237pub use widgets::{
238    EditWindow, Editor, FindMode, InputLine, LimitMode, ListBox, ListRoles, ListViewer,
239    ListViewerState, MaskedInput, RevealEye, RevealEyeConfig, SM_DOUBLE, SM_EXTEND, SM_TRIPLE,
240    ScrollBar, Scroller, SortedListBox, ValuePosition,
241};
242pub use widgets::{Encoding, FileEditor, LineEnding, Memo};
243pub use widgets::{
244    HistoryViewer, HistoryWindow, THistory, clear_history, history_add, history_count, history_str,
245};
246pub use widgets::{Label, ParamText, StaticText};
247pub use widgets::{Node, Outline, OutlineViewer, OutlineViewerState, ov_update};
248pub use widgets::{Terminal, TextDevice};
249pub use window::{Fullscreen, ScrollBarOptions, Window, WindowFlags, WindowPalette};