Struct Tree 

pub struct Tree<M> { /* private fields */ }

A hierarchy: rows at a depth, opened and shut by a disclosure triangle.

What List is to a column of choices, this is to a settings hierarchy, a menu of menus, or a file list on a panel.

enum Message { Pick(usize), Open(usize), Fold(usize) }
Tree::new(
    [
        TreeItem::new("Nettverk"),
        TreeItem::new("Wi-Fi").at_depth(1),
        TreeItem::new("Ethernet").at_depth(1),
        TreeItem::new("Skjerm"),
    ],
    Message::Pick,
)
.on_activate(Message::Open)
.on_toggle(Message::Fold);

Flat rows with a depth, not a nest

The rows are a slice and each carries how deep it is. A row’s parent is the nearest row above it with a smaller depth, and its children are the run of deeper rows immediately below it. That is the whole data structure.

A nested type would be the obvious other choice and is worse here in three ways. It needs an allocation per branch in a crate that runs on a panel with no allocator to spare; it makes “which row is at this y” a walk instead of a count; and it cannot be handed to a widget from a form file without the file growing real nesting, which .dform deliberately does not have for content.

Nothing says has_children — it is derived, because in this representation it is not an independent fact: a row has children exactly when the row after it is deeper. A field for it could disagree with the depths, and then one of the two would be a lie.

Scrolling belongs to the tree of nodes, and this widget cooperates with it

The same arrangement List documents at length: this draws the rows that fit and stops, and the scrolling version is this inside a node marked Ui::set_scrollable, sized with preferred_height. A keyboard selection below the fold reveals itself and the viewport follows.

preferred_height counts the rows that are shown, so opening a branch makes the widget want to be taller — which is the caller’s cue to resize it and let the viewport scroll further.

Keyboard

One node, so one tab stop. List’s keyboard, plus the two the hierarchy adds:

Up, Down	The previous and next shown row. Does not wrap.
Right	Opens a shut row; on an open one, moves to its first child.
Left	Shuts an open row; on a shut one or a leaf, moves to its parent.
Home, End	The first and last shown row.
Enter	Activates.

Right and Left are the convention every tree control has used since the Windows 95 explorer, and the reason they do two things each is that the obvious one-thing version leaves a person on a shut row pressing Left with nothing happening.

Three messages, because there are three things a person does

Selecting a row, acting on it, and opening it are different, so they are separate: new takes the selection, on_activate takes Enter and the double-click, and on_toggle takes the triangle. Each reports the row’s index into the rows as given — not its position among the shown ones, which changes whenever a branch above it folds, and not a path, which a fn(usize) -> M could not carry.

Implementations

impl<M> Tree<M>

pub fn new( items: impl IntoIterator<Item = impl Into<TreeItem>>, message: fn(usize) -> M, ) -> Self

A tree with nothing selected, reporting selection through message.

pub fn inert(items: impl IntoIterator<Item = impl Into<TreeItem>>) -> Self

A tree that emits nothing, for a hierarchy the application reads rather than reacts to.

pub fn on_activate(self, message: fn(usize) -> M) -> Self

Sets the message sent when a row is activated by Enter or a double-click.

pub fn on_toggle(self, message: fn(usize) -> M) -> Self

Sets the message sent when a row is opened or shut.

The row’s own open has already changed by the time this is emitted: the widget owns what it draws, and an application that wants to veto a fold wants a different widget.

pub fn activate_on_click(self) -> Self

Makes a single click or tap activate as well as select.

The touch-panel answer; see List::activate_on_click.

pub fn with_selected(self, index: Option<usize>) -> Self

Sets the initially selected row, by its index into the rows as given.

pub fn with_row_height(self, height: i32) -> Self

Sets the height of every row, overriding the theme’s field height.

pub fn with_indent(self, indent: i32) -> Self

Sets how far one level is indented from the one above.

pub fn with_role(self, role: Role) -> Self

Sets the colour role of the selected row.

pub fn with_style(self, style: TextStyle) -> Self

Sets the rows’ font and size.

pub const fn selected(&self) -> Option<usize>

The selected row, by its index into the rows as given.

pub fn selected_item(&self) -> Option<&TreeItem>

The selected row’s item, if any.

pub fn set_selected(&mut self, index: Option<usize>)

Selects a row. Out of range, disabled, or hidden under a shut branch selects nothing.

Hidden is refused rather than silently opening the branch: a selection nobody can see is one the keyboard would then move from a place the person is not looking at.

pub fn items(&self) -> &[TreeItem]

The rows, as given.

pub fn set_items( &mut self, items: impl IntoIterator<Item = impl Into<TreeItem>>, )

Replaces the rows.

pub fn set_open(&mut self, index: usize, open: bool)

Opens or shuts one row, without reporting it.

For an application driving the tree rather than answering it — restoring what was open when a screen was last shown, say.

pub fn set_all_open(&mut self, open: bool)

Opens or shuts every row that has children.

pub fn set_row_enabled(&mut self, index: usize, enabled: bool)

Enables or disables one row.

pub fn set_role(&mut self, role: Role)

Replaces the colour role of the selected row.

pub fn set_style(&mut self, style: TextStyle)

Replaces the rows’ font and size.

pub fn has_children(&self, index: usize) -> bool

Whether the row at index has any children.

Derived from the depths rather than stored; see the note on the type.

pub fn is_shown(&self, index: usize) -> bool

Whether the row at index is drawn — every branch above it being open.

pub fn shown_rows(&self) -> usize

How many rows are drawn.

pub fn row_height(&self, theme: &Theme) -> i32

Height every row is drawn at.

pub fn visible_rows(&self, theme: &Theme, height: i32) -> usize

How many rows fit in height.

pub fn preferred_height(&self, theme: &Theme) -> i32

Height this tree needs to show every row that is currently shown.

Changes as branches open and shut, which is the point: a caller sizing a tree inside a scrolling viewport asks again after a toggle.

pub fn preferred_width(&self, engine: &mut TextEngine) -> i32

Width the widest shown row needs, indentation and columns included.

Trait Implementations

impl<M: Clone> Clone for Tree<M>

fn clone(&self) -> Tree<M>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<M: Debug> Debug for Tree<M>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<M> Describe for Tree<M>

const KIND: &'static str = "tree"

The name a form file uses for this widget. Kebab-case.

const DOC: &'static str = "A hierarchy of rows that open and shut, indented by depth."

One line saying what this widget is, for somebody choosing one.

const GROUP: Group = Group::Data

Which shelf of the catalogue this belongs on.

const ICON: &'static Icon

The widget’s glyph: a small portrait of the thing, for a palette to draw beside — or instead of — its name.

const PROPERTIES: &'static [Property]

Every property, in the order an inspector should show them.

fn get(&self, name: &str) -> Option<Value>

The current value.

fn apply(&mut self, name: &str, value: Value) -> Result<(), Mismatch>

Applies a value, reporting only what went wrong.

fn set(&mut self, name: &str, value: Value) -> Result<(), PropertyError>

Applies a value, reporting what went wrong and where.

impl<M: 'static> Widget<M> for Tree<M>

fn focusable(&self) -> bool

A tree with no row anybody can choose is not a tab stop.

fn describe(&self) -> Option<&dyn DynDescribe>

This widget’s property description, if it has one.

fn describe_mut(&mut self) -> Option<&mut dyn DynDescribe>

The mutable half of describe.

fn measure(&self, ctx: &mut MeasureCtx<'_>, _offered: Offer) -> Measured

How big this widget would like to be, given what the caller can promise.

fn paint(&self, ctx: &mut PaintCtx<'_>, canvas: &mut Pen<'_>)

Draws into canvas, which is already clipped to this widget’s bounds intersected with the damage region being repainted.

fn on_event(&mut self, event: &Event<'_>, ctx: &mut EventCtx<'_, M>) -> Handled

Reacts to an event routed to this widget.

fn accepts_pointer(&self) -> bool

Returns true if the pointer can hit this widget.

fn preserves_focus(&self) -> bool

Returns true if a press on this widget should leave focus exactly where it is.

fn animate(&mut self, now_ms: u64) -> Animation

Advances time-based state. Called only while this widget has asked to animate — see EventCtx::request_animation — and stops being called the moment it answers Wake::Never.

fn snap(&mut self, now_ms: u64) -> Animation

Lands whatever is in flight at its end state, without animating it.