The toolkit-agnostic view tree: props, node kinds and their builders. More...

#include <algorithm>
#include <concepts>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <type_traits>
#include <utility>
#include <variant>
#include <vector>
#include "../reactive/runtime.hpp"
#include "../reactive/signal.hpp"
#include "../util/datetime.hpp"
#include "alignment.hpp"
#include "button_emphasis.hpp"
#include "button_style.hpp"

Classes
struct	morph::ui::SlotBinding< F >
	A slot's read together with its id, as ui::slot makes it; a Prop made from it is a slot with that id. More...
struct	morph::ui::detail::IsSlotBinding< T >
	Whether a type is a SlotBinding: false here, true for the specialisation below. More...
struct	morph::ui::detail::IsSlotBinding< SlotBinding< F > >
	A SlotBinding is one. More...
class	morph::ui::Prop< T >
	A node property: a constant, or a slot — a reactive read, with a stable id when it was given one. More...
struct	morph::ui::Sizing
	How much space a widget asks for along one dimension, in backend units (a character cell on the TUI). More...
struct	morph::ui::LayoutHints
	A widget's size request in both dimensions, and the bounds its extent is clamped into. More...
struct	morph::ui::Accessibility
	What assistive technology announces for a node. More...
struct	morph::ui::KeyBinding
	A keyboard chord a node handles while focus is inside it. More...
struct	morph::ui::Common
	The part every node carries: visibility, enablement, layout, drag-and-drop, accessibility, test identity, tooltip, surface, keyboard chords and autofocus. More...
struct	morph::ui::FieldState
	The state of a value a user edits or reads: whether it may be changed, must be given, is wrong, or is being recomputed. More...
struct	morph::ui::Text
	Static or bound text. More...
struct	morph::ui::Button
	A push button. More...
struct	morph::ui::TextInput
	An editable text field. The backend never reports its own setText back through onChange. More...
struct	morph::ui::Checkbox
	A labelled check box. More...
struct	morph::ui::SelectOption
	One option of a Select. More...
struct	morph::ui::Select
	A choice of one option. More...
struct	morph::ui::MenuItem
	One entry of a Menu: its label and its handler in one place, so there are no parallel lists. More...
struct	morph::ui::Menu
	A vertical list of commands. More...
struct	morph::ui::Column
	Children stacked top to bottom. More...
struct	morph::ui::Row
	Children laid out left to right. More...
struct	morph::ui::GridCell
	One cell of a Grid. More...
struct	morph::ui::Grid
	Cells laid out row-major in a fixed number of columns. More...
struct	morph::ui::Spacer
	Empty space that takes what its layout hints ask for. More...
struct	morph::ui::Panel
	A titled frame around one child; a collapsible one is an accordion section. More...
struct	morph::ui::Scroll
	A scrollable viewport around one child. More...
struct	morph::ui::SwitchCase
	One case of a Switch. More...
struct	morph::ui::Switch
	Shows the case whose key the selector yields; remounts only when that key changes. More...
struct	morph::ui::Tab
	One page of Tabs. More...
struct	morph::ui::Tabs
	A tab bar over pages. More...
struct	morph::ui::Dialog
	A modal overlay; its content is mounted only while it is open. More...
struct	morph::ui::Busy
	A progress indicator. More...
class	morph::ui::detail::RowSlot
	One mounted row of a ForEach or a Table: the row's signal, and the view built from it once. More...
class	morph::ui::detail::ForEachSession
	One mount's use of a ForEach: the latest snapshot of the rows, and a way to make row slots from it. More...
class	morph::ui::detail::ForEachModel
	A ForEach's row source, key function and row view, with the row type erased. More...
class	morph::ui::detail::TypedForEach< RowT >
	The typed model behind forEach<RowT> and table<RowT>. More...
struct	morph::ui::Virtualization
	When a keyed row list realizes a widget only for the rows in or near the visible range, instead of for every row regardless of scroll position. A row's own reactive state (its signal, rebuilt from the session on every change) is unaffected either way and is never released while its key exists; this setting only decides whether a row's mounted widget is also kept alive off-screen. More...
struct	morph::ui::ForEach
	One widget per row of a keyed collection, updated in place when a row with the same key changes. More...
struct	morph::ui::TableColumn
	One column of a Table. More...
struct	morph::ui::Table
	Keyed rows of cells under column headers. Each row's view is a Row whose children are the cells, one per column. More...
struct	morph::ui::DateTimeInput
	A date, or a date and time, edited in a display zone and reported as an instant. More...
struct	morph::ui::Slider
	An integer chosen on a range. More...
struct	morph::ui::FilePicker
	A file path, typed or chosen in the platform's file dialog. More...
struct	morph::ui::ActionButton
	A button inside another kind, such as a banner's action: its caption beside its handler. More...
struct	morph::ui::Banner
	A message across the top of a region, with an optional action and an optional dismissal. More...
struct	morph::ui::Badge
	A short label marking a state, such as a count or a status. More...
struct	morph::ui::Progress
	A progress bar. More...
struct	morph::ui::Step
	One step of a Steps indicator. More...
struct	morph::ui::Steps
	The steps of a process in order, each with its state. More...
struct	morph::ui::KeyValueItem
	One row of a KeyValue list. More...
struct	morph::ui::KeyValue
	Captions beside their values, one pair per row. More...
struct	morph::ui::EmptyState
	What a region shows when it has nothing to show: a title, an explanation and an optional action. More...
struct	morph::ui::Drawer
	A panel that slides in from one edge over the content: a Dialog with a side, and the same rules. More...
struct	morph::ui::ActionBar
	A row of buttons in the footer of the dialog or drawer whose content holds it: what a document's overlay actions lower to. The mount refuses one anywhere else. More...
struct	morph::ui::Splitter
	Panes side by side, or stacked, with handles the user drags to share the space between them. More...
struct	morph::ui::Collapsible
	A titled section the user opens and closes. Its header stays usable while it is closed. More...
struct	morph::ui::DropZone
	A region that takes files dropped from the operating system. More...
struct	morph::ui::CustomProp
	One prop a loaded custom component is given. More...
struct	morph::ui::Custom
	A component the backend may load (spec 5 §10), with the built-in nodes shown when it does not. More...
struct	morph::ui::NodeData
	What a Node points at: exactly one node kind. More...
struct	morph::ui::TableOptions
	Everything about a table beyond its columns and rows. More...
struct	morph::ui::TableRowView
	What a table's row view builds for one row: its cells, one per column, and its tone. More...

Concepts
concept	morph::ui::detail::ConstantConvertible
	Whether From may become a constant Prop<To>: an implicit conversion that does not silently change the kind of value.

Typedefs
using	morph::ui::Action = std::function<void()>
	A widget event handler taking no arguments.
using	morph::ui::Key = std::variant<std::int64_t, std::string>
	The identity of a Switch case, a Select option, a ForEach or Table row and a drag payload.
using	morph::ui::SlotId = std::uint32_t
	The stable identity of a slot: a bound property a renderer can refer to by number.
using	morph::ui::Node = std::shared_ptr<NodeData const>
	A view-tree node: immutable, shared data.

Enumerations
enum class	morph::ui::TextRole : std::uint8_t { Normal , Muted , Heading , Error , Success , Section }
	How a Text is styled; each backend maps a role to its theme. More...
enum class	morph::ui::TextInputMode : std::uint8_t { SingleLine , Multiline , Password }
	How a TextInput edits. More...
enum class	morph::ui::SelectStyle : std::uint8_t { Dropdown , Radio }
	How a Select presents its options. More...
enum class	morph::ui::Axis : std::uint8_t { Vertical , Horizontal }
	The direction a stack arranges, or a scroll area scrolls, its content. More...
enum class	morph::ui::DateMode : std::uint8_t { Date , DateTime }
	What a DateTimeInput edits. More...
enum class	morph::ui::FilePickerMode : std::uint8_t { Open , Save }
	Whether a FilePicker chooses an existing file or a file to write. More...
enum class	morph::ui::Tone : std::uint8_t { Neutral , Info , Ok , Warn , Err }
	What a message or a mark conveys, mapped to the theme's colours. More...
enum class	morph::ui::Side : std::uint8_t { Start , End }
	The edge a Drawer slides in from, in reading direction. More...
enum class	morph::ui::StepState : std::uint8_t { Pending , Active , Done , Failed }
	Where one step of a Steps indicator stands. More...
enum class	morph::ui::SelectionMode : std::uint8_t { None , Single , Multiple }
	How many rows of a Table the user can select. More...

Functions
template<typename F>
SlotBinding< std::decay_t< F > >	morph::ui::slot (SlotId slotId, F &&read)
	A slot with an id.
constexpr int	morph::ui::spacingStep (int value) noexcept
	A gap or padding as the spacing step a backend receives.
template<typename Kind>
Node	morph::ui::detail::makeNode (Kind spec)
	Wraps one node aggregate into a shared node.
Node	morph::ui::text (Text spec)
	Static or bound text.
Node	morph::ui::button (Button spec)
	A push button.
Node	morph::ui::textInput (TextInput spec)
	An editable text field.
Node	morph::ui::checkbox (Checkbox spec)
	A labelled check box.
Node	morph::ui::select (Select spec)
	A choice of one option.
Node	morph::ui::menu (Menu spec)
	A list of commands.
Node	morph::ui::column (Column spec)
	Children stacked top to bottom.
Node	morph::ui::row (Row spec)
	Children laid out left to right.
Node	morph::ui::grid (Grid spec)
	Cells in a fixed number of columns.
Node	morph::ui::spacer (Spacer spec={})
	Empty space.
Node	morph::ui::panel (Panel spec)
	A titled frame, optionally collapsible.
Node	morph::ui::scroll (Scroll spec)
	A scrollable viewport.
Node	morph::ui::switchOf (Switch spec)
	Shows the case the selector picks. Spelled switchOf because switch is a keyword.
Node	morph::ui::tabs (Tabs spec)
	A tab bar over pages.
Node	morph::ui::dialog (Dialog spec)
	A modal overlay.
Node	morph::ui::busy (Busy spec)
	A progress indicator.
Node	morph::ui::dateTimeInput (DateTimeInput spec)
	A date or date-and-time field.
Node	morph::ui::slider (Slider spec)
	An integer on a range.
Node	morph::ui::filePicker (FilePicker spec)
	A file path field.
Node	morph::ui::banner (Banner spec)
	A message across the top of a region.
Node	morph::ui::badge (Badge spec)
	A short label marking a state.
Node	morph::ui::progress (Progress spec)
	A progress bar.
Node	morph::ui::steps (Steps spec)
	The steps of a process.
Node	morph::ui::keyValue (KeyValue spec)
	Captions beside their values.
Node	morph::ui::emptyState (EmptyState spec)
	What a region shows when it has nothing to show.
Node	morph::ui::drawer (Drawer spec)
	A panel that slides in from one edge.
Node	morph::ui::actionBar (ActionBar spec)
	An action bar node.
Node	morph::ui::splitter (Splitter spec)
	Panes with handles the user drags.
Node	morph::ui::collapsible (Collapsible spec)
	A titled section the user opens and closes.
Node	morph::ui::dropZone (DropZone spec)
	A region that takes dropped files.
Node	morph::ui::custom (Custom spec)
	A component loaded by name, mounted by Mounted as its fallback.
template<typename E> requires std::is_enum_v<E>
Node	morph::ui::switchOn (std::function< E()> selector, std::vector< std::pair< E, Node > > cases, Node fallback={})
	A Switch over an enumeration: each enumerator becomes the int64 key of its case.
template<typename RowT>
Node	morph::ui::forEach (std::function< std::vector< RowT >()> rows, std::function< Key(RowT const &)> keyOf, std::function< Node(reactive::Signal< RowT > const &)> rowView, Axis axis=Axis::Vertical, int gap=0)
	One widget per row of a keyed collection read through a binding (a Query's value() included).
template<typename RowT>
Node	morph::ui::forEach (reactive::Signal< std::vector< RowT > > const &rows, std::function< Key(RowT const &)> keyOf, std::function< Node(reactive::Signal< RowT > const &)> rowView, Axis axis=Axis::Vertical, int gap=0)
	One widget per row of a keyed collection held in a signal.
template<typename RowT>
Node	morph::ui::table (std::vector< TableColumn > columns, std::function< std::vector< RowT >()> rows, std::function< Key(RowT const &)> keyOf, std::function< std::vector< Node >(reactive::Signal< RowT > const &)> cells, TableOptions options={})
	A table of keyed rows: one Row of cells per row, under the column headers.
template<typename RowT>
Node	morph::ui::table (std::vector< TableColumn > columns, std::function< std::vector< RowT >()> rows, std::function< Key(RowT const &)> keyOf, std::function< TableRowView(reactive::Signal< RowT > const &)> rowView, TableOptions options={})
	A table of keyed rows whose row view gives each row its tone as well as its cells.

Variables
constexpr int	morph::ui::kMaxSpacingStep = 5
	The largest spacing step: a gap or padding names a step from 0 (none) to this, which each backend maps to its own distance (the theme's space.<step> on Qt Quick, cells on the terminal).

Detailed Description

The toolkit-agnostic view tree: props, node kinds and their builders.

Specified in docs/spec/ui/view_tree.md.

Definition in file view.hpp.

Typedef Documentation

◆ Action

using morph::ui::Action = std::function<void()>

A widget event handler taking no arguments.

Definition at line 33 of file view.hpp.

◆ Key

using morph::ui::Key = std::variant<std::int64_t, std::string>

The identity of a Switch case, a Select option, a ForEach or Table row and a drag payload.

Never a floating-point number: morph ids can exceed 2^53.

Definition at line 38 of file view.hpp.

◆ SlotId

using morph::ui::SlotId = std::uint32_t

The stable identity of a slot: a bound property a renderer can refer to by number.

Whoever builds the tree assigns slot ids; the interpreter numbers every bound property of a document, and a code-generating renderer names the value it reads after it (v.s17). Mounted does not use them. A slot made from a bare callable has no id.

Definition at line 45 of file view.hpp.

◆ Node

using morph::ui::Node = std::shared_ptr<NodeData const>

A view-tree node: immutable, shared data.

Definition at line 403 of file view.hpp.

Enumeration Type Documentation

◆ TextRole

enum class morph::ui::TextRole : std::uint8_t

strong

How a Text is styled; each backend maps a role to its theme.

Enumerator
Normal	Body text.
Muted	Secondary text.
Heading	A section heading.
Error	An error message.
Success	A confirmation.
Section	The heading of a group within a list: body size, bold and muted, below a Heading.

Definition at line 199 of file view.hpp.

◆ TextInputMode

enum class morph::ui::TextInputMode : std::uint8_t

strong

How a TextInput edits.

Enumerator
SingleLine	One line; Enter submits.
Multiline	Several lines.
Password	One line, masked.

Definition at line 209 of file view.hpp.

◆ SelectStyle

enum class morph::ui::SelectStyle : std::uint8_t

strong

How a Select presents its options.

Enumerator
Dropdown	A closed field that opens a list.
Radio	Every option visible, one marked.

Definition at line 216 of file view.hpp.

◆ Axis

enum class morph::ui::Axis : std::uint8_t

strong

The direction a stack arranges, or a scroll area scrolls, its content.

Enumerator
Vertical	Top to bottom.
Horizontal	Left to right.

Definition at line 222 of file view.hpp.

◆ DateMode

enum class morph::ui::DateMode : std::uint8_t

strong

What a DateTimeInput edits.

Enumerator
Date	A calendar date; the time of day is midnight in the display zone.
DateTime	A date and a time of day.

Definition at line 228 of file view.hpp.

◆ FilePickerMode

enum class morph::ui::FilePickerMode : std::uint8_t

strong

Whether a FilePicker chooses an existing file or a file to write.

Enumerator
Open	An existing file.
Save	A file to create or overwrite.

Definition at line 234 of file view.hpp.

◆ Tone

enum class morph::ui::Tone : std::uint8_t

strong

What a message or a mark conveys, mapped to the theme's colours.

Enumerator
Neutral	Nothing in particular.
Info	Information.
Ok	Success.
Warn	Something to check.
Err	A failure.

Definition at line 240 of file view.hpp.

◆ Side

enum class morph::ui::Side : std::uint8_t

strong

The edge a Drawer slides in from, in reading direction.

Enumerator
Start	The left edge in a left-to-right layout.
End	The right edge in a left-to-right layout.

Definition at line 249 of file view.hpp.

◆ StepState

enum class morph::ui::StepState : std::uint8_t

strong

Where one step of a Steps indicator stands.

Enumerator
Pending	Not started.
Active	In progress.
Done	Completed.
Failed	Stopped by a failure.

Definition at line 255 of file view.hpp.

◆ SelectionMode

enum class morph::ui::SelectionMode : std::uint8_t

strong

How many rows of a Table the user can select.

Enumerator
None	Rows can be activated, not selected.
Single	At most one row.
Multiple	Any number of rows.

Definition at line 263 of file view.hpp.

Function Documentation

◆ slot()

template<typename F>

SlotBinding< std::decay_t< F > > morph::ui::slot	(	SlotId	slotId,
		F &&	read )

nodiscard

A slot with an id.

Template Parameters

F	A callable taking no arguments.

Parameters

slotId	The slot's id.
read	Reads the value; every signal it reads is a dependency.

Returns: What a Prop takes as a slot with slotId.

Definition at line 63 of file view.hpp.

◆ spacingStep()

int morph::ui::spacingStep ( int value )

nodiscardconstexprnoexcept

A gap or padding as the spacing step a backend receives.

Parameters

value The value as written.

Returns: value clamped to [0, kMaxSpacingStep].

Definition at line 561 of file view.hpp.

◆ makeNode()

template<typename Kind>

Node morph::ui::detail::makeNode ( Kind spec )

nodiscard

Wraps one node aggregate into a shared node.

Template Parameters

Kind	The node aggregate type.

Parameters

spec The node.

Returns: The shared node.

Definition at line 1185 of file view.hpp.

◆ text()

Node morph::ui::text ( Text spec )

inlinenodiscard

Static or bound text.

Parameters

spec The node.

Returns: The node.

Definition at line 1194 of file view.hpp.

◆ button()

Node morph::ui::button ( Button spec )

inlinenodiscard

A push button.

Parameters

spec The node.

Returns: The node.

Definition at line 1199 of file view.hpp.

◆ textInput()

Node morph::ui::textInput ( TextInput spec )

inlinenodiscard

An editable text field.

Parameters

spec The node.

Returns: The node.

Definition at line 1204 of file view.hpp.

◆ checkbox()

Node morph::ui::checkbox ( Checkbox spec )

inlinenodiscard

A labelled check box.

Parameters

spec The node.

Returns: The node.

Definition at line 1209 of file view.hpp.

◆ select()

Node morph::ui::select ( Select spec )

inlinenodiscard

A choice of one option.

Parameters

spec The node.

Returns: The node.

Definition at line 1214 of file view.hpp.

◆ menu()

Node morph::ui::menu ( Menu spec )

inlinenodiscard

A list of commands.

Parameters

spec The node.

Returns: The node.

Definition at line 1219 of file view.hpp.

◆ column()

Node morph::ui::column ( Column spec )

inlinenodiscard

Children stacked top to bottom.

Parameters

spec The node.

Returns: The node.

Definition at line 1224 of file view.hpp.

◆ row()

Node morph::ui::row ( Row spec )

inlinenodiscard

Children laid out left to right.

Parameters

spec The node.

Returns: The node.

Definition at line 1229 of file view.hpp.

◆ grid()

Node morph::ui::grid ( Grid spec )

inlinenodiscard

Cells in a fixed number of columns.

Parameters

spec The node.

Returns: The node.

Definition at line 1234 of file view.hpp.

◆ spacer()

Node morph::ui::spacer ( Spacer spec = {} )

inlinenodiscard

Empty space.

Parameters

spec The node.

Returns: The node.

Definition at line 1239 of file view.hpp.

◆ panel()

Node morph::ui::panel ( Panel spec )

inlinenodiscard

A titled frame, optionally collapsible.

Parameters

spec The node.

Returns: The node.

Definition at line 1244 of file view.hpp.

◆ scroll()

Node morph::ui::scroll ( Scroll spec )

inlinenodiscard

A scrollable viewport.

Parameters

spec The node.

Returns: The node.

Definition at line 1249 of file view.hpp.

◆ switchOf()

Node morph::ui::switchOf ( Switch spec )

inlinenodiscard

Shows the case the selector picks. Spelled switchOf because switch is a keyword.

Parameters

spec The node.

Returns: The node.

Definition at line 1254 of file view.hpp.

◆ tabs()

Node morph::ui::tabs ( Tabs spec )

inlinenodiscard

A tab bar over pages.

Parameters

spec The node.

Returns: The node.

Definition at line 1259 of file view.hpp.

◆ dialog()

Node morph::ui::dialog ( Dialog spec )

inlinenodiscard

A modal overlay.

Parameters

spec The node.

Returns: The node.

Definition at line 1264 of file view.hpp.

◆ busy()

Node morph::ui::busy ( Busy spec )

inlinenodiscard

A progress indicator.

Parameters

spec The node.

Returns: The node.

Definition at line 1269 of file view.hpp.

◆ dateTimeInput()

Node morph::ui::dateTimeInput ( DateTimeInput spec )

inlinenodiscard

A date or date-and-time field.

Parameters

spec The node.

Returns: The node.

Definition at line 1274 of file view.hpp.

◆ slider()

Node morph::ui::slider ( Slider spec )

inlinenodiscard

An integer on a range.

Parameters

spec The node.

Returns: The node.

Definition at line 1279 of file view.hpp.

◆ filePicker()

Node morph::ui::filePicker ( FilePicker spec )

inlinenodiscard

A file path field.

Parameters

spec The node.

Returns: The node.

Definition at line 1284 of file view.hpp.

◆ banner()

Node morph::ui::banner ( Banner spec )

inlinenodiscard

A message across the top of a region.

Parameters

spec The node.

Returns: The node.

Definition at line 1289 of file view.hpp.

◆ badge()

Node morph::ui::badge ( Badge spec )

inlinenodiscard

A short label marking a state.

Parameters

spec The node.

Returns: The node.

Definition at line 1294 of file view.hpp.

◆ progress()

Node morph::ui::progress ( Progress spec )

inlinenodiscard

A progress bar.

Parameters

spec The node.

Returns: The node.

Definition at line 1299 of file view.hpp.

◆ steps()

Node morph::ui::steps ( Steps spec )

inlinenodiscard

The steps of a process.

Parameters

spec The node.

Returns: The node.

Definition at line 1304 of file view.hpp.

◆ keyValue()

Node morph::ui::keyValue ( KeyValue spec )

inlinenodiscard

Captions beside their values.

Parameters

spec The node.

Returns: The node.

Definition at line 1309 of file view.hpp.

◆ emptyState()

Node morph::ui::emptyState ( EmptyState spec )

inlinenodiscard

What a region shows when it has nothing to show.

Parameters

spec The node.

Returns: The node.

Definition at line 1314 of file view.hpp.

◆ drawer()

Node morph::ui::drawer ( Drawer spec )

inlinenodiscard

A panel that slides in from one edge.

Parameters

spec The node.

Returns: The node.

Definition at line 1319 of file view.hpp.

◆ actionBar()

Node morph::ui::actionBar ( ActionBar spec )

inlinenodiscard

An action bar node.

Parameters

spec The bar.

Returns: The node.

Definition at line 1324 of file view.hpp.

◆ splitter()

Node morph::ui::splitter ( Splitter spec )

inlinenodiscard

Panes with handles the user drags.

Parameters

spec The node.

Returns: The node.

Definition at line 1329 of file view.hpp.

◆ collapsible()

Node morph::ui::collapsible ( Collapsible spec )

inlinenodiscard

A titled section the user opens and closes.

Parameters

spec The node.

Returns: The node.

Definition at line 1334 of file view.hpp.

◆ dropZone()

Node morph::ui::dropZone ( DropZone spec )

inlinenodiscard

A region that takes dropped files.

Parameters

spec The node.

Returns: The node.

Definition at line 1339 of file view.hpp.

◆ custom()

Node morph::ui::custom ( Custom spec )

inlinenodiscard

A component loaded by name, mounted by Mounted as its fallback.

Parameters

spec The node.

Returns: The node.

Exceptions

std::invalid_argument when the fallback is null: a renderer that cannot load the component has nothing else to show.

Definition at line 1346 of file view.hpp.

◆ switchOn()

template<typename E>
requires std::is_enum_v<E>

Node morph::ui::switchOn	(	std::function< E()>	selector,
		std::vector< std::pair< E, Node > >	cases,
		Node	fallback = {} )

nodiscard

A Switch over an enumeration: each enumerator becomes the int64 key of its case.

Enumerators are compared as int64: an unsigned value above INT64_MAX wraps to a negative key, and distinct enumerators still give distinct keys.

Template Parameters

E	The enumeration.

Parameters

selector	Which enumerator to show; every signal it reads is a dependency.
cases	One node per enumerator shown.
fallback	Shown when no case matches; may be null.

Returns: The node.

Exceptions

std::invalid_argument when selector is empty, as a Prop refuses an empty binding.

Definition at line 1365 of file view.hpp.

◆ forEach() [1/2]

template<typename RowT>

Node morph::ui::forEach	(	std::function< std::vector< RowT >()>	rows,
		std::function< Key(RowT const &)>	keyOf,
		std::function< Node(reactive::Signal< RowT > const &)>	rowView,
		Axis	axis = Axis::Vertical,
		int	gap = 0 )

nodiscard

One widget per row of a keyed collection read through a binding (a Query's value() included).

A kept key keeps its widget, which a changed row updates in place; a new key is mounted, a gone key unmounted, and the rows are brought into the snapshot's order by moving as few widgets as possible.

Template Parameters

RowT	The row type; copyable.

Parameters

rows	Reads the rows; every signal it reads is a dependency.
keyOf	A row's identity; a later duplicate of a key is reported and refused, and the first one is kept.
rowView	Builds a row's view once, from a signal the mount keeps equal to the row. Read the signal inside bindings: what the view reads directly while it is built is read once and never again.
axis	The stacking direction.
gap	Space between rows.

Returns: The node.

Exceptions

std::invalid_argument when rows, keyOf or rowView is empty.

Definition at line 1396 of file view.hpp.

◆ forEach() [2/2]

template<typename RowT>

Node morph::ui::forEach	(	reactive::Signal< std::vector< RowT > > const &	rows,
		std::function< Key(RowT const &)>	keyOf,
		std::function< Node(reactive::Signal< RowT > const &)>	rowView,
		Axis	axis = Axis::Vertical,
		int	gap = 0 )

nodiscard

One widget per row of a keyed collection held in a signal.

Template Parameters

RowT	The row type; copyable.

Parameters

rows	The signal; it must outlive every mount of the node.
keyOf	A row's identity; a later duplicate of a key is reported and refused, and the first one is kept.
rowView	Builds a row's view once, from a signal the mount keeps equal to the row.
axis	The stacking direction.
gap	Space between rows.

Returns: The node.

Exceptions

std::invalid_argument when keyOf or rowView is empty.

Definition at line 1417 of file view.hpp.

◆ table() [1/2]

template<typename RowT>

Node morph::ui::table	(	std::vector< TableColumn >	columns,
		std::function< std::vector< RowT >()>	rows,
		std::function< Key(RowT const &)>	keyOf,
		std::function< std::vector< Node >(reactive::Signal< RowT > const &)>	cells,
		TableOptions	options = {} )

nodiscard

A table of keyed rows: one Row of cells per row, under the column headers.

Rows are mounted, updated, unmounted and reordered as forEach does. A row whose cells are not exactly one non-null node per column would shift the columns after it, so it is refused as a row that fails to mount is: reported, left out, and tried again on the next change of the rows.

Template Parameters

RowT	The row type; copyable.

Parameters

columns	The columns, in order.
rows	Reads the rows; every signal it reads is a dependency.
keyOf	A row's identity; a later duplicate of a key is reported and refused, and the first one is kept.
cells	Builds a row's cells once, one per column, from a signal the mount keeps equal to the row. Read the signal inside bindings: what the cells read directly while they are built is read once and never again.
options	Selection, activation and Common.

Returns: The node.

Exceptions

std::invalid_argument when rows, keyOf or cells is empty.

Definition at line 1464 of file view.hpp.

◆ table() [2/2]

template<typename RowT>

Node morph::ui::table	(	std::vector< TableColumn >	columns,
		std::function< std::vector< RowT >()>	rows,
		std::function< Key(RowT const &)>	keyOf,
		std::function< TableRowView(reactive::Signal< RowT > const &)>	rowView,
		TableOptions	options = {} )

nodiscard

A table of keyed rows whose row view gives each row its tone as well as its cells.

As the other table, with rowView answering a TableRowView: the tone binds in the row's own scope, and the table is told it after the row's key and on every change.

Template Parameters

RowT	The row type; copyable.

Parameters

columns	The columns, in order.
rows	Reads the rows; every signal it reads is a dependency.
keyOf	A row's identity; a later duplicate of a key is reported and refused, and the first one is kept.
rowView	Builds a row's cells, one per column, and its tone, once, from a signal the mount keeps equal to the row.
options	Selection, activation and Common.

Returns: The node.

Exceptions

std::invalid_argument when rows, keyOf or rowView is empty.

Definition at line 1492 of file view.hpp.

Variable Documentation

◆ kMaxSpacingStep

int morph::ui::kMaxSpacingStep = 5

inlineconstexpr

The largest spacing step: a gap or padding names a step from 0 (none) to this, which each backend maps to its own distance (the theme's space.<step> on Qt Quick, cells on the terminal).

Definition at line 556 of file view.hpp.

Classes

Concepts

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ Action

◆ Key

◆ SlotId

◆ Node

Enumeration Type Documentation

◆ TextRole

◆ TextInputMode

◆ SelectStyle

◆ Axis

◆ DateMode

◆ FilePickerMode

◆ Tone

◆ Side

◆ StepState

◆ SelectionMode

Function Documentation

◆ slot()

◆ spacingStep()

◆ makeNode()

◆ text()

◆ button()

◆ textInput()

◆ checkbox()

◆ select()

◆ menu()

◆ column()

◆ row()

◆ grid()

◆ spacer()

◆ panel()

◆ scroll()

◆ switchOf()

◆ tabs()

◆ dialog()

◆ busy()

◆ dateTimeInput()

◆ slider()

◆ filePicker()

◆ banner()

◆ badge()

◆ progress()

◆ steps()

◆ keyValue()

◆ emptyState()

◆ drawer()

◆ actionBar()

◆ splitter()

◆ collapsible()

◆ dropZone()

◆ custom()

◆ switchOn()

◆ forEach() [1/2]

◆ forEach() [2/2]

◆ table() [1/2]

◆ table() [2/2]

Variable Documentation

◆ kMaxSpacingStep