Module `Mosaic_ui.Table`

Data table with columns, rows, keyboard navigation, and selection.

Focusable data table with column headers and row selection.

A table widget that displays rows of cell values in typed columns. The widget is keyboard- and mouse-navigable and automatically scrolls to keep the selected row visible.

Keyboard bindings:

Up/Down arrows move the selection by one row. Shift+Up/Down skips by Props.t's fast_scroll_step rows.
j/k move the selection by one row.
Enter or KP_enter activates the current row, firing the set_on_activate callback.

Mouse bindings:

Left click selects a row.
Scroll wheel navigates rows.

Column sizing

Each column carries a width strategy:

`Auto sizes the column to the widest cell content, including the header.
`Fixed n sets an exact width of n terminal columns.
`Flex f claims a proportional share of remaining space by factor f.

Remaining space, after `Fixed and `Auto columns are resolved, is distributed among `Flex columns in proportion to their factors.

Text overflow

Each column carries an overflow strategy:

`Ellipsis truncates with a "..." suffix (default).
`Crop hard-truncates at the column width.

type t

The type for table widgets.

Column specification

type alignment = [

| `Left
| `Center
| `Right

]

The type for horizontal text alignment within a column.

type width = [

| `Fixed of int
| `Auto
| `Flex of float

]

The type for column width strategies. See column sizing.

type overflow = [

| `Ellipsis
| `Crop

]

The type for cell content overflow strategies. See text overflow.

type column = {

header : string;
width : width;
alignment : alignment;
overflow : overflow;
min_width : int option;
max_width : int option;

}

The type for column definitions.

header is the column header text displayed in the header row. width, alignment, and overflow govern sizing and rendering. min_width and max_width constrain width values of `Auto and `Flex; they are ignored for `Fixed columns.

val column : 
  ?width:width ->
  ?alignment:alignment ->
  ?overflow:overflow ->
  ?min_width:int ->
  ?max_width:int ->
  string ->
  column

column header is a column specification with header as the header text and with:

width the column width strategy. Defaults to `Auto.
alignment the horizontal text alignment. Defaults to `Left.
overflow the overflow handling strategy. Defaults to `Ellipsis.
min_width the minimum column width in terminal columns, applied to `Auto and `Flex columns. Defaults to None.
max_width the maximum column width in terminal columns, applied to `Auto and `Flex columns. Defaults to None.

Cell content

type cell

The type for table cells. A cell holds either plain text or rich styled fragments (see cell and rich).

val cell : ?style:Ansi.Style.t -> string -> cell

cell s is a plain-text cell containing s with:

style an optional style that overrides the row's default style when provided. Defaults to None.

val rich : Text.fragment list -> cell

rich fragments is a styled cell built from fragments.

val cell_equal : cell -> cell -> bool

cell_equal a b is true iff a and b have identical content and style.

Constructors

val create : 
  parent:Renderable.t ->
  ?index:int ->
  ?id:string ->
  ?style:Toffee.Style.t ->
  ?visible:bool ->
  ?z_index:int ->
  ?opacity:float ->
  ?columns:column list ->
  ?rows:cell array list ->
  ?selected_row:int ->
  ?border:bool ->
  ?border_style:Grid.Border.t ->
  ?show_header:bool ->
  ?show_column_separator:bool ->
  ?show_row_separator:bool ->
  ?cell_padding:int ->
  ?header_color:Ansi.Color.t ->
  ?header_background:Ansi.Color.t ->
  ?text_color:Ansi.Color.t ->
  ?background:Ansi.Color.t ->
  ?selected_text_color:Ansi.Color.t ->
  ?selected_background:Ansi.Color.t ->
  ?focused_selected_text_color:Ansi.Color.t ->
  ?focused_selected_background:Ansi.Color.t ->
  ?row_styles:Ansi.Style.t list ->
  ?wrap_selection:bool ->
  ?fast_scroll_step:int ->
  unit ->
  t

create ~parent () is a table node attached to parent.

The node is focusable and uses buffered rendering. All optional arguments correspond to fields of Props.t; their defaults match those of Props.make. See Props.make for a full description of each parameter.

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 columns : t -> column list

columns t is the current column list of t.

val set_columns : t -> column list -> unit

set_columns t cols replaces the column specifications of t with cols and triggers a re-render.

val rows : t -> cell array list

rows t is the current data rows of t.

val set_rows : t -> cell array list -> unit

set_rows t data replaces the data rows of t with data, clamping the selection index to the new valid range. Does not fire the set_on_change callback. Triggers a re-render.

Selection

val selected_row : t -> int

selected_row t is the 0-based index of the currently selected row of t.

val set_selected_row : t -> int -> unit

set_selected_row t i selects row i in t, clamping i to the valid range [0; row_count t - 1]. Fires the set_on_change callback when the index actually changes.

val row_count : t -> int

row_count t is the number of data rows in t.

Display

val set_border : t -> bool -> unit

set_border t v enables (true) or disables (false) the outer border and header separator of t.

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

set_border_style t style sets the border character set of t to style.

val set_show_header : t -> bool -> unit

set_show_header t v shows (true) or hides (false) the header row of t.

val set_show_column_separator : t -> bool -> unit

set_show_column_separator t v shows (true) or hides (false) vertical separator lines between columns of t.

val set_show_row_separator : t -> bool -> unit

set_show_row_separator t v shows (true) or hides (false) horizontal separator lines between rows of t.

val set_cell_padding : t -> int -> unit

set_cell_padding t n sets the horizontal padding per side of each cell in t to n terminal columns.

val set_row_styles : t -> Ansi.Style.t list -> unit

set_row_styles t styles sets the alternating row styles of t to styles, applied by modulo index. Pass [] to disable alternation.

Colors

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

set_header_color t c sets the header text color of t to c.

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

set_header_background t c sets the header background color of t to c.

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

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

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

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

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

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

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

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

Behavior

val set_wrap_selection : t -> bool -> unit

set_wrap_selection t v enables (true) or disables (false) selection wrapping at row boundaries for t. When enabled, moving past the last row wraps to the first, and vice versa.

val set_fast_scroll_step : t -> int -> unit

set_fast_scroll_step t n sets the number of rows to skip on Shift+Up/Down in t to n. Values below 1 are clamped to 1.

Callbacks

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

set_on_change t cb registers cb as the callback to invoke when the selected row of t changes. cb receives the new 0-based row index. Pass None to remove the callback.

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

set_on_activate t cb registers cb as the callback to invoke when the current row is activated via Enter or KP_enter. cb receives the activated 0-based row index. Pass None to remove the callback.

Layout

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

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

Formatting and inspecting

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/Table/index.html

Module `Mosaic_ui.Table`

Keyboard and mouse navigation

Column sizing

Text overflow

Column specification

Cell content

Constructors

Props

Data

Selection

Display

Colors

Behavior

Callbacks

Layout

Formatting and inspecting

package mosaic

Install

dune-project Dependency

Authors

Maintainers

Sources

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

Module Mosaic_ui.Table

Keyboard and mouse navigation

Column sizing

Text overflow

Column specification

Cell content

Constructors

Props

Data

Selection

Display

Colors

Behavior

Callbacks

Layout

Formatting and inspecting

dune-project
Dependency

Module `Mosaic_ui.Table`