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

The view tree

Everything you see on screen is a node in one tree. The desktop is a node; each window on it is a node; the frame, scrollbars, buttons and input lines inside a window are nodes. tvision-rs calls the core abstraction the View trait and the container type Group, keeping the Turbo Vision tree model in idiomatic Rust.

A trait and a state struct

Every widget in tvision-rs is defined by two things working together:

  • View: the behaviour. It is a trait whose methods cover everything the framework calls: draw paints the view, handle_event reacts to input, and a handful of others (set_state, valid, value / set_value) cover focus, validation and data transfer. handle_event and these four have default bodies.
  • ViewState: the data. A struct that every widget embeds (conventionally a field named state), holding origin, size, cursor, the state / option / grow / drag flags, the event mask and the help context.

Every widget embeds a ViewState and implements View. Only three methods are required: state, state_mut, and draw; the rest have defaults. That is the composition recipe, and the Writing your own View chapter walks it end to end.

Turbo Vision heritage: the C++ library built every widget by inheriting from TView. The View trait covers TView's virtual methods; ViewState covers its data members.

Flags became fields

The boolean properties of a view (visibility, focus, whether it responds to keyboard input) are organized into four structs of named booleans, one per logical family. You read self.state.state.visible directly; no bitmask arithmetic is needed.

Coming from C++ Turbo Vision, the flag word families map like this:

C++ flag wordtvision-rs struct
sfXxx (state)State
ofXxx (options)Options
gfXxx (grow mode)GrowMode
dmXxx (drag mode)DragMode

The propagating subset of state flags a parent flips on a child during focus and activation is the StateFlag enum (Active, Selected, Focused, Dragging).

Geometry

A view's rectangle is two corners: Rect holds a top-left a (inclusive) and bottom-right b (exclusive), each a Point. Coordinates are i32: signed, because origins go negative when a view scrolls offscreen, and faithful to magiblot's widening of the historical short to int. Rect carries the familiar chained mutators (grow, intersect, plus r#move and r#union, raw-named to dodge the Rust keywords).

A view's origin is relative to its owner. The tree resolves the absolute position as it descends; there is no up-pointer to walk.

Groups are the branch nodes

A Group is a View that owns child views. It is the port of TGroup and the node type of the tree. The desktop, every window and every dialog are groups. A group:

  • owns its children in a Vec in back-to-front paint order: children[0] is the bottom (drawn first), children.last() is the frontmost (drawn last);
  • draws its children back-to-front (painter's algorithm, with no damage tracking: the whole tree redraws and a diff finds the changes);
  • routes events to them and tracks which child is current (focused).

Turbo Vision heritage: TGroup stored children in a circular next/prev ring with a per-child owner back-pointer. tvision-rs replaces this with a plain Vec and handle-based addressing; children have no up-pointer.

Because a child has no pointer back to its parent, cross-references use a ViewId handle instead of a raw pointer. Each view's id is minted when it is inserted into a group and stamped into its own ViewState; the framework resolves a handle back to a view by walking down from the group. This is also how a window addresses one of its controls, and how a leaf view reaches a sibling; see Cross-view brokering & ViewId.

Where to go next