Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Inheritance → trait + composition

C++ Turbo Vision is built on inheritance. TView is the base class; TGroup, TWindow, TButton and every other widget derive from it, override a few virtuals (draw, handleEvent, setState, …), and inherit the rest. Rust has no inheritance, so tvision-rs uses the idiom that replaces it: a trait for behaviour and composition for data.

The View trait + ViewState

The TView class splits into two pieces:

  • View: the trait that carries the virtual methods. draw, handle_event, set_state, calc_bounds and the rest live here. Most have a faithful default body, so a widget overrides only what differs.
  • ViewState: a plain struct holding what were TView's data members: origin, size, cursor, the state/option/grow/drag flag sets, the event mask, the help context, and the view's own id. The flag words become named-boolean structs (State (sf*), Options (of*), GrowMode (gf*), DragMode (dm*)); see Flag words → struct-of-bools.

Every widget embeds a ViewState and exposes it through the trait's two required accessors, state() and state_mut(). Those two, plus draw, which has no sensible base default, are the only methods a widget must write; everything else defaults.

// Illustrative sketch — not a standalone program.
fn state(&self) -> &ViewState { &self.state }
fn state_mut(&mut self) -> &mut ViewState { &mut self.state }

Where C++ writes class TButton : public TView, tvision-rs writes struct Button { state: ViewState, /* … */ } and impl View for Button.

Building on a concrete widget: embed-and-delegate

Subclassing a leaf TView means embedding a ViewState. Turbo Vision code also derives from concrete widgets: an "About" box is class AboutDialog : public TDialog, reusing all of TDialog's behaviour and overriding only draw. Without inheritance, a type cannot extend Dialog; it embeds one:

#![allow(unused)]
fn main() {
use tvision_rs as tv;
use tv::Dialog;
#[allow(dead_code)]
struct AboutDialog { dialog: Dialog }
}

Rust then provides none of the inherited methods. To behave like its inner Dialog, the embedder must forward every un-overridden View method to the inner field by hand: more than a dozen one-line forwarders like fn handle_event(&mut self, ev, ctx) { self.dialog.handle_event(ev, ctx) }. That boilerplate is the cost of composition.

#[delegate] removes the boilerplate

The #[delegate] attribute macro (from the tvision-rs-macros crate, re-exported as tv::delegate) generates the forwarders. The impl contains only the methods that differ; the macro injects a forwarder for the rest:

#![allow(unused)]
fn main() {
use tvision_rs as tv;
use tv::{delegate, Dialog, View, DrawCtx};
#[allow(dead_code)]
struct AboutDialog { dialog: Dialog }
#[delegate(to = dialog)]
impl View for AboutDialog {
    fn draw(&mut self, ctx: &mut DrawCtx) { /* custom paint */ }
    // handle_event, set_state, calc_bounds, … all auto-forward to self.dialog
}
}

It reads the trait name from the impl header, collects the methods written in the impl, looks up the trait's full method set from a hand-maintained table, and emits fn m(args) { self.dialog.m(args) } for each method neither written nor listed in skip(...). A skip(name) leaves that method at the trait's default body instead of forwarding. This is used when forwarding would change behaviour (for example, Window skips calc_bounds so its size floor still applies, instead of deferring to the group's). Skipping a name that isn't a trait method is a hard error, so a typo can't silently turn into a forward. Embedders such as Terminal (#[delegate(to = scroller)]) and Desktop (#[delegate(to = group)]) reuse their inner view this way.

One ViewState. The delegate field owns the view's state, so do not write state/state_mut in a #[delegate] impl. An override that returns a ViewState of the outer type would be a second state that every forwarded method (set_state, change_bounds, calc_bounds, ...) ignores: the focus flag and the geometry would land on the inner view. The macro rejects such an override, and skip(state) / skip(state_mut), with a compile error. It accepts only the plain forwarder self.<field>.state(), which is redundant. Keep the state in the delegate field, or implement View by hand without #[delegate].

When you add a View method, add its forwarder too. The macro keeps a hand-maintained mirror of trait View. A missing required method fails to compile, but a new defaulted one would silently not forward; a behavioural spy test guards every currently known method. The design note docs/design/delegation-macros.md has the full rationale.

For the inverse direction (how a view tree is assembled and walked at runtime) see The view tree.