The reactive state of one field: its draft and everything derived from it. More...

#include <form_session.hpp>

Public Member Functions
	FieldState (detail::engine::SessionCore &core, FieldSpec const &spec, std::string path, std::vector< std::unique_ptr< FieldState > > const siblings, FieldState const parent)
	FieldState (FieldState const &)=delete
FieldState &	operator= (FieldState const &)=delete
	FieldState (FieldState &&)=delete
FieldState &	operator= (FieldState &&)=delete
FieldSpec const &	spec () const noexcept
	The field's spec.
std::string const &	path () const noexcept
	The instance path.
std::string const &	label () const noexcept
	The label: the explicit key's translation, else the derived key's (top level only), else the schema's title.
std::string const &	help () const noexcept
	The help text, resolved like the label.
std::string const &	placeholder () const noexcept
	The placeholder: x-placeholder resolved like the label, else defaultPlaceholder.
reactive::Signal< std::string > &	text () noexcept
	The draft: what the control holds. Setting it is a user edit.
std::string const &	draft () const
	The draft, read-only. Tracked.
reactive::Signal< std::size_t > &	unit () noexcept
	A Decimal's or Quantity's entry unit, an index into spec().units.
reactive::Signal< bool > &	engaged () noexcept
	Whether a blank-capable field was filled once (an x-blankAs: empty text, or a collection that had rows).
reactive::Computed< Encoding > const &	encoded () const noexcept
	The draft's encoding. Tracked.
reactive::Computed< std::optional< FieldError > > const &	error () const noexcept
	Why the draft does not encode, if it does not. Tracked.
reactive::Computed< bool > const &	visible () const noexcept
	Whether the field is shown: not x-hidden, and no visibleWhen naming it is False.
reactive::Computed< bool > const &	readonly () const noexcept
	Whether the field is frozen: x-readonly, a frozen parent, or a readonlyWhen naming it that is True.
reactive::Computed< bool > const &	required () const noexcept
	Whether the field must be filled: required, or a requiredWhen naming it that is True.
bool	blank () const
	Whether nothing is entered: a blank draft, an Object whose members are all blank, a collection with no rows that was never engaged. Tracked.
RuleOperand	ruleOperand () const
	What a rule sees of this field. Tracked.
std::vector< ChoiceOption > const &	options () const
	The selectable options: an Enum's from the schema, a Choice's as last fetched for its current parents. Tracked.
void	retryOptions ()
	Fetches a Choice's options again when the last fetch failed; does nothing otherwise. What opening its select runs, so options that could not be fetched when the form was built are fetched once the user asks for them.
bool	optionsPending () const
	Whether a Choice's options request is in flight. Tracked.
void	switchUnit (std::size_t index)
	Switches a Quantity's entry unit, converting the draft exactly (half away from zero to the new unit's decimals). A user action.
std::span< std::unique_ptr< FieldState > const >	members () const noexcept
	An Object's members, in x-order.
FieldState *	member (std::string_view name) const noexcept
	An Object's member by wire name.
std::vector< std::shared_ptr< RowState > > const &	rows () const
	A collection's rows, in order. Tracked.
std::uint64_t	addRow ()
	Appends a blank row to a collection and engages it. A user action.
void	removeRow (std::uint64_t key)
	Removes a collection row by key. A user action. A holder of the row's shared_ptr (a mounted view) keeps its state alive until it lets go.
std::string	snapshot () const
	What the field holds, as one string: two snapshots are equal exactly when the field holds the same entry (draft, unit and engagement, and every member's and row's). Untracked.
std::expected< void, std::string >	edit (detail::engine::Json const &value)
	Replaces the draft with a wire value as the user's own edit, in one batch: a load the session does not mark programmatic, so the field counts as changed and is validated as an edit is.
void	load (detail::engine::Json const *value)
	Replaces the draft with the decoded wire value; null or absent is blank. Does not mark the change programmatic — the caller does, in the same batch.
void	clear ()
	Blanks the draft, the unit, the engagement, the members and the rows.
void	start ()
	Starts what needs every sibling to exist: an x-blankAs field's engagement, a Choice's options query, and every member's own. Called once, after the owner built all its fields.

Detailed Description

The reactive state of one field: its draft and everything derived from it.

Definition at line 188 of file form_session.hpp.

Constructor & Destructor Documentation

◆ FieldState()

morph::forms::FieldState::FieldState	(	detail::engine::SessionCore &	core,
		FieldSpec const &	spec,
		std::string	path,
		std::vector< std::unique_ptr< FieldState > > const *	siblings,
		FieldState const *	parent )

inline

Parameters

core	The session core. Borrowed: it must outlive the field.
spec	The field's spec. Borrowed from the core's model (or a parent's children).
path	The instance path (name, parent.member, rows#key.member).
siblings	The fields x-optionsDependsOn names are looked up among. Borrowed.
parent	The containing Object or ObjectArray field, or null at the top level.

Definition at line 196 of file form_session.hpp.

Member Function Documentation

◆ spec()

FieldSpec const & morph::forms::FieldState::spec ( ) const

inlinenodiscardnoexcept

The field's spec.

Returns: The spec.

Definition at line 257 of file form_session.hpp.

◆ path()

std::string const & morph::forms::FieldState::path ( ) const

inlinenodiscardnoexcept

The instance path.

Returns: name, parent.member, or rows#key.member inside a collection row.

Definition at line 261 of file form_session.hpp.

◆ label()

std::string const & morph::forms::FieldState::label ( ) const

inlinenodiscardnoexcept

The label: the explicit key's translation, else the derived key's (top level only), else the schema's title.

Returns: The label.

Definition at line 266 of file form_session.hpp.

◆ help()

std::string const & morph::forms::FieldState::help ( ) const

inlinenodiscardnoexcept

The help text, resolved like the label.

Returns: The help text; empty when the schema states none.

Definition at line 270 of file form_session.hpp.

◆ placeholder()

std::string const & morph::forms::FieldState::placeholder ( ) const

inlinenodiscardnoexcept

The placeholder: x-placeholder resolved like the label, else defaultPlaceholder.

Returns: The placeholder.

Definition at line 274 of file form_session.hpp.

◆ text()

reactive::Signal< std::string > & morph::forms::FieldState::text ( )

inlinenodiscardnoexcept

The draft: what the control holds. Setting it is a user edit.

Returns: The draft signal.

Definition at line 278 of file form_session.hpp.

◆ draft()

std::string const & morph::forms::FieldState::draft ( ) const

inlinenodiscard

The draft, read-only. Tracked.

Returns: What the control holds.

Definition at line 282 of file form_session.hpp.

◆ unit()

reactive::Signal< std::size_t > & morph::forms::FieldState::unit ( )

inlinenodiscardnoexcept

A Decimal's or Quantity's entry unit, an index into spec().units.

Returns: The unit signal.

Definition at line 286 of file form_session.hpp.

◆ engaged()

reactive::Signal< bool > & morph::forms::FieldState::engaged ( )

inlinenodiscardnoexcept

Whether a blank-capable field was filled once (an x-blankAs: empty text, or a collection that had rows).

Returns: The engagement signal.

Definition at line 291 of file form_session.hpp.

◆ encoded()

reactive::Computed< Encoding > const & morph::forms::FieldState::encoded ( ) const

inlinenodiscardnoexcept

The draft's encoding. Tracked.

Returns: The encoding computed.

Definition at line 295 of file form_session.hpp.

◆ error()

reactive::Computed< std::optional< FieldError > > const & morph::forms::FieldState::error ( ) const

inlinenodiscardnoexcept

Why the draft does not encode, if it does not. Tracked.

Returns: The error computed.

Definition at line 299 of file form_session.hpp.

◆ visible()

reactive::Computed< bool > const & morph::forms::FieldState::visible ( ) const

inlinenodiscardnoexcept

Whether the field is shown: not x-hidden, and no visibleWhen naming it is False.

Returns: The visibility computed.

Definition at line 303 of file form_session.hpp.

◆ readonly()

reactive::Computed< bool > const & morph::forms::FieldState::readonly ( ) const

inlinenodiscardnoexcept

Whether the field is frozen: x-readonly, a frozen parent, or a readonlyWhen naming it that is True.

Returns: The read-only computed.

Definition at line 308 of file form_session.hpp.

◆ required()

reactive::Computed< bool > const & morph::forms::FieldState::required ( ) const

inlinenodiscardnoexcept

Whether the field must be filled: required, or a requiredWhen naming it that is True.

Returns: The required computed.

Definition at line 312 of file form_session.hpp.

◆ blank()

bool morph::forms::FieldState::blank ( ) const

inlinenodiscard

Whether nothing is entered: a blank draft, an Object whose members are all blank, a collection with no rows that was never engaged. Tracked.

Returns: true when blank.

Definition at line 318 of file form_session.hpp.

◆ ruleOperand()

RuleOperand morph::forms::FieldState::ruleOperand ( ) const

inlinenodiscard

What a rule sees of this field. Tracked.

Returns: Blank, Invalid, or Valid with the exact value.

Definition at line 337 of file form_session.hpp.

◆ options()

std::vector< ChoiceOption > const & morph::forms::FieldState::options ( ) const

inlinenodiscard

The selectable options: an Enum's from the schema, a Choice's as last fetched for its current parents. Tracked.

Returns: The options; empty for every other kind, and for a Choice with nothing fetched.

Definition at line 351 of file form_session.hpp.

◆ retryOptions()

void morph::forms::FieldState::retryOptions ( )

inline

Fetches a Choice's options again when the last fetch failed; does nothing otherwise. What opening its select runs, so options that could not be fetched when the form was built are fetched once the user asks for them.

Definition at line 361 of file form_session.hpp.

◆ optionsPending()

bool morph::forms::FieldState::optionsPending ( ) const

inlinenodiscard

Whether a Choice's options request is in flight. Tracked.

Returns: true while fetching.

Definition at line 369 of file form_session.hpp.

◆ switchUnit()

void morph::forms::FieldState::switchUnit ( std::size_t index )

inline

Switches a Quantity's entry unit, converting the draft exactly (half away from zero to the new unit's decimals). A user action.

Parameters

index The new unit, an index into spec().units.

Definition at line 374 of file form_session.hpp.

◆ members()

std::span< std::unique_ptr< FieldState > const > morph::forms::FieldState::members ( ) const

inlinenodiscardnoexcept

An Object's members, in x-order.

Returns: The members; empty for every other kind.

Definition at line 391 of file form_session.hpp.

◆ member()

FieldState * morph::forms::FieldState::member ( std::string_view name ) const

inlinenodiscardnoexcept

An Object's member by wire name.

Parameters

name	The wire name.

Returns: The member, or null.

Definition at line 396 of file form_session.hpp.

◆ rows()

std::vector< std::shared_ptr< RowState > > const & morph::forms::FieldState::rows ( ) const

inlinenodiscard

A collection's rows, in order. Tracked.

Returns: The rows; empty for every other kind.

Definition at line 404 of file form_session.hpp.

◆ addRow()

std::uint64_t morph::forms::FieldState::addRow ( )

inline

Appends a blank row to a collection and engages it. A user action.

Returns: The new row's key; 0 when the field is not a collection, or a truncated one.

Definition at line 408 of file form_session.hpp.

◆ removeRow()

void morph::forms::FieldState::removeRow ( std::uint64_t key )

inline

Removes a collection row by key. A user action. A holder of the row's shared_ptr (a mounted view) keeps its state alive until it lets go.

Parameters

key	The row's key.

Definition at line 425 of file form_session.hpp.

◆ snapshot()

std::string morph::forms::FieldState::snapshot ( ) const

inlinenodiscard

What the field holds, as one string: two snapshots are equal exactly when the field holds the same entry (draft, unit and engagement, and every member's and row's). Untracked.

Returns: The snapshot.

Definition at line 432 of file form_session.hpp.

◆ edit()

std::expected< void, std::string > morph::forms::FieldState::edit ( detail::engine::Json const & value )

inline

Replaces the draft with a wire value as the user's own edit, in one batch: a load the session does not mark programmatic, so the field counts as changed and is validated as an edit is.

Parameters

value The wire value; null is blank.

Returns: Nothing, or why the value does not fit the field: an Object takes a JSON object, a collection a JSON array. Then nothing changes.

Definition at line 443 of file form_session.hpp.

◆ load()

void morph::forms::FieldState::load ( detail::engine::Json const * value )

inline

Replaces the draft with the decoded wire value; null or absent is blank. Does not mark the change programmatic — the caller does, in the same batch.

Parameters

value The wire value, or null.

Definition at line 461 of file form_session.hpp.

◆ clear()

void morph::forms::FieldState::clear ( )

inline

Blanks the draft, the unit, the engagement, the members and the rows.

Definition at line 505 of file form_session.hpp.

◆ start()

void morph::forms::FieldState::start ( )

inline

Starts what needs every sibling to exist: an x-blankAs field's engagement, a Choice's options query, and every member's own. Called once, after the owner built all its fields.

Definition at line 519 of file form_session.hpp.

The documentation for this class was generated from the following file:

morph/forms/engine/form_session.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ FieldState()

Member Function Documentation

◆ spec()

◆ path()

◆ label()

◆ help()

◆ placeholder()

◆ text()

◆ draft()

◆ unit()

◆ engaged()

◆ encoded()

◆ error()

◆ visible()

◆ readonly()

◆ required()

◆ blank()

◆ ruleOperand()

◆ options()

◆ retryOptions()

◆ optionsPending()

◆ switchUnit()

◆ members()

◆ member()

◆ rows()

◆ addRow()

◆ removeRow()

◆ snapshot()

◆ edit()

◆ load()

◆ clear()

◆ start()