Module `Mosaic_ui.Tree`

Hierarchical tree with expandable nodes, guide lines, and selection.

Hierarchical tree with expand/collapse navigation.

A focusable, keyboard-navigable tree widget that displays items in a hierarchy with optional guide lines. Each node can be expanded or collapsed to show or hide its children. The widget automatically scrolls to keep the selected node visible.

Keyboard bindings:

Up/Down arrows move the selection. Shift moves by fast_scroll_step items.
j/k move the selection by one item.
Right expands the focused node or moves to its first child.
Left collapses the focused node or moves to its parent.
Space toggles expand/collapse of the focused node.
Enter/KP_enter activates the focused node (fires on_activate).

Mouse bindings:

Left click on the icon area toggles expand/collapse.
Left click on the label area selects the node.
Scroll wheel navigates through the list.

Guide lines

When show_guides is true, Unicode box-drawing characters render the tree structure. The character set is controlled by guide_style, which accepts any Grid.Border.t preset (single, rounded, heavy, etc.). When show_guides is false (the default), only indentation is used.

type t

The type for tree widgets.

Item

type item = {

label : string;
children : item list;

}

The type for tree nodes. label is the display string; children is the (possibly empty) list of child nodes.

val item : ?children:item list -> string -> item

item label is a tree node with label and no children.

children defaults to [].

Construction

val create : 
  parent:Renderable.t ->
  ?index:int ->
  ?id:string ->
  ?style:Toffee.Style.t ->
  ?visible:bool ->
  ?z_index:int ->
  ?opacity:float ->
  ?items:item list ->
  ?selected_index:int ->
  ?expand_depth:int ->
  ?indent_size:int ->
  ?show_guides:bool ->
  ?guide_style:Grid.Border.t ->
  ?expand_icon:string ->
  ?collapse_icon:string ->
  ?leaf_icon:string ->
  ?background:Ansi.Color.t ->
  ?text_color:Ansi.Color.t ->
  ?selected_background:Ansi.Color.t ->
  ?selected_text_color:Ansi.Color.t ->
  ?focused_selected_background:Ansi.Color.t ->
  ?focused_selected_text_color:Ansi.Color.t ->
  ?guide_color:Ansi.Color.t ->
  ?icon_color:Ansi.Color.t ->
  ?wrap_selection:bool ->
  ?fast_scroll_step:int ->
  unit ->
  t

create ~parent () is a tree widget attached to parent.

The widget is focusable and uses buffered rendering. Tree-specific parameters are forwarded to Props.make; refer to Props.make for their defaults.

val node : t -> Renderable.t

node t is the underlying Renderable.t for t.

Props

module Props : sig ... end

val apply_props : t -> Props.t -> unit

apply_props t props applies props to t, triggering the minimum necessary layout and render updates.

Data

val items : t -> item list

items t is the current item list of t.

val set_items : t -> item list -> unit

set_items t items replaces the item tree with items. Resets the expansion state according to expand_depth, clamps the selection to a valid index, and triggers a re-render.

Selection

val selected_index : t -> int

selected_index t is the 0-based index of the selected entry in the visible (flattened) list of t.

val set_selected_index : t -> int -> unit

set_selected_index t i selects the visible entry at index i. The index is clamped to the valid range. Fires on_change if the index actually changes.

val selected_item : t -> item option

selected_item t is the currently selected item of t, or None if the tree is empty.

val visible_count : t -> int

visible_count t is the number of currently visible entries in t.

val depth_of : t -> int -> int

depth_of t i is the nesting depth of visible entry i in t. depth_of t i is 0 for out-of-bounds indices.

Expansion

val expand : t -> int -> unit

expand t i expands the visible entry at index i. No-op if the entry is already expanded or is a leaf.

val collapse : t -> int -> unit

collapse t i collapses the visible entry at index i. No-op if the entry is already collapsed or is a leaf.

val toggle_expand : t -> int -> unit

toggle_expand t i toggles the expansion state of visible entry i in t.

val expand_all : t -> unit

expand_all t expands every expandable node in t.

val collapse_all : t -> unit

collapse_all t collapses every expandable node in t.

val is_expanded : t -> int -> bool

is_expanded t i is true iff visible entry i is expanded.

Display

val set_indent_size : t -> int -> unit

set_indent_size t n sets the number of columns per depth level to n.

val set_show_guides : t -> bool -> unit

set_show_guides t v shows guide lines when v is true and hides them when v is false.

val set_guide_style : t -> Grid.Border.t -> unit

set_guide_style t style sets the guide line character set to style.

val set_expand_icon : t -> string -> unit

set_expand_icon t s sets the icon for collapsed expandable nodes to s.

val set_collapse_icon : t -> string -> unit

set_collapse_icon t s sets the icon for expanded nodes to s.

val set_leaf_icon : t -> string -> unit

set_leaf_icon t s sets the icon for leaf nodes to s.

Colors

val set_background : t -> Ansi.Color.t -> unit

set_background t c sets the background color of t to c.

val set_text_color : t -> Ansi.Color.t -> unit

set_text_color t c sets the text color of t to c.

val set_selected_background : t -> Ansi.Color.t -> unit

set_selected_background t c sets the background color of the selected node to c.

val set_selected_text_color : t -> Ansi.Color.t -> unit

set_selected_text_color t c sets the text color of the selected node to c.

val set_guide_color : t -> Ansi.Color.t -> unit

set_guide_color t c sets the guide line color of t to c.

val set_icon_color : t -> Ansi.Color.t -> unit

set_icon_color t c sets the expand/collapse icon color of t to c.

Behavior

val set_wrap_selection : t -> bool -> unit

set_wrap_selection t v enables selection wrapping at list boundaries when v is true and disables it when v is false.

val set_fast_scroll_step : t -> int -> unit

set_fast_scroll_step t n sets the number of rows to skip with Shift+Up/Down to n. n is clamped to a minimum of 1.

Callbacks

val set_on_change : t -> (int -> unit) option -> unit

set_on_change t cb registers cb to be called when the selected index changes. cb receives the new selected index.

val set_on_activate : t -> (int -> unit) option -> unit

set_on_activate t cb registers cb to be called when the focused node is activated via Enter. cb receives the activated visible index.

val set_on_expand : t -> (int -> bool -> unit) option -> unit

set_on_expand t cb registers cb to be called when a node is expanded or collapsed. cb receives the visible index and the new expanded state (true for expanded, false for collapsed).

Layout

val set_style : t -> Toffee.Style.t -> unit

set_style t style sets the layout style of t to style.

Formatting

val pp : Format.formatter -> t -> unit

pp ppf t formats t on ppf for debugging.

Install

dune-project
Dependency

Authors

Maintainers

Sources

doc/mosaic.ui/Mosaic_ui/Tree/index.html

Module `Mosaic_ui.Tree`

Navigation

Guide lines

Item

Construction

Props

Data

Selection

Expansion

Display

Colors

Behavior

Callbacks

Layout

Formatting

package mosaic

Install

dune-project Dependency

Authors

Maintainers

Sources

doc/mosaic.ui/Mosaic_ui/Tree/index.html

Module Mosaic_ui.Tree

Navigation

Guide lines

Item

Construction

Props

Data

Selection

Expansion

Display

Colors

Behavior

Callbacks

Layout

Formatting

dune-project
Dependency

Module `Mosaic_ui.Tree`