host.hpp File Reference

The host contract (spec 6 §4): how a host mounts UI documents and closes them, whether it owns its own shell or is the framework's workspace shell, and DocumentScreenHost, the framework's host over documents. More...

#include <algorithm>
#include <cstdint>
#include <expected>
#include <functional>
#include <map>
#include <memory>
#include <optional>
#include <ranges>
#include <span>
#include <stdexcept>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include "../core/executor.hpp"
#include "../reactive/runtime.hpp"
#include "../reactive/signal.hpp"
#include "document.hpp"
#include "expression.hpp"
#include "inspector.hpp"
#include "interpreter.hpp"
#include "route.hpp"
#include "value.hpp"

Go to the source code of this file.

Classes
struct	morph::ui::MountError
	Why a screen could not be mounted. More...
class	morph::ui::ScreenHead
	A screen's head beside its title: the subtitle, the status badges and the actions a shell shows above the screen (the document's subtitle, status and actions). More...
class	morph::ui::ScreenHandle
	One mounted screen, as its host sees it. More...
class	morph::ui::ScreenHost
	What mounts screens for a host that owns its own shell; the workspace shell is one. More...
class	morph::ui::ScreenHostRegistry
	The host screens an application registers by name: what a catalog entry's host names instead of a document. More...
struct	morph::ui::DocumentScreenHostOptions
	How a DocumentScreenHost finds documents and mounts them. More...
class	morph::ui::detail::host::ParamsEnv
	The environment identityOf evaluates in: the params, and nothing else. Reading anything else marks it unknown. More...
class	morph::ui::DocumentScreenHost
	The framework's ScreenHost over UI documents: it mounts them through an Interpreter, closes them by the protocol of spec 6 §3, and hands a document's navigate to onNavigate, which the deriving host implements. More...
struct	morph::ui::DocumentScreenHost::Handle::State::Watch
	A wait for the screen to have nothing pending; the id tells a posted task whether it is still current. More...

Typedefs
using	morph::ui::ParamMap = ValueRecord
	A screen's params, by name.
using	morph::ui::HostScreenFactory
	Makes a host screen (spec 6 §15): the application's native screen, mounted into a shell's page with params. It returns the screen's handle, whose title, dirty, identity and close protocol the shell reads as it does a document screen's, or why it could not be mounted.
using	morph::ui::CloseGuard = std::function<void(ScreenHandle& screen, std::function<void(CloseChoice choice)> choose)>
	What decides a close the document does not decide itself: a dirty screen that declares no onClose.

Enumerations
enum class	morph::ui::CloseChoice : std::uint8_t { Save , Discard , Cancel }
	What the user chose for a dirty screen that is being closed (spec 6 §15). More...

Functions
std::string	morph::ui::detail::host::titleText (Value const &value)
	The text a title value shows.
std::optional< std::string >	morph::ui::identityKey (Value const &identity)
	The canonical text of a screen's identity: what DocumentScreenHost::identityOf answers, so identityOf(id, params) == identityKey(handle.identity().peek()) says whether a mounted screen is the one those params would open.
bool	morph::ui::sameIdentity (Value const &lhs, Value const &rhs)
	Whether two identities name the same screen instance: their keys are equal, and neither is null.

Detailed Description

The host contract (spec 6 §4): how a host mounts UI documents and closes them, whether it owns its own shell or is the framework's workspace shell, and DocumentScreenHost, the framework's host over documents.

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

Definition in file host.hpp.

Typedef Documentation

ParamMap

using morph::ui::ParamMap = ValueRecord

A screen's params, by name.

Definition at line 38 of file host.hpp.

HostScreenFactory

using morph::ui::HostScreenFactory

Initial value:

std::function<std::expected<std::unique_ptr<ScreenHandle>, MountError>(
   ParamMap const& params, ContainerWidget& page)>

Makes a host screen (spec 6 §15): the application's native screen, mounted into a shell's page with params. It returns the screen's handle, whose title, dirty, identity and close protocol the shell reads as it does a document screen's, or why it could not be mounted.

Definition at line 175 of file host.hpp.

CloseGuard

using morph::ui::CloseGuard = std::function<void(ScreenHandle& screen, std::function<void(CloseChoice choice)> choose)>

What decides a close the document does not decide itself: a dirty screen that declares no onClose.

It asks the user, typically with a dialog, and calls choose once. It offers save and close only when screen.canSave(); Save on a screen that cannot save keeps it open. The handle carries the choice out, so choose may be called after the handle is gone, and then does nothing.

Definition at line 213 of file host.hpp.

Enumeration Type Documentation

CloseChoice

enum class morph::ui::CloseChoice : std::uint8_t

strong

What the user chose for a dirty screen that is being closed (spec 6 §15).

Enumerator
Save	Run the screen's save, and close it only if it is then clean.
Discard	Close it without saving.
Cancel	Keep it open.

Definition at line 202 of file host.hpp.

Function Documentation

titleText()

std::string morph::ui::detail::host::titleText ( Value const & value )

inlinenodiscard

The text a title value shows.

Parameters

value

The title's value.

Returns

A string as is, null as empty, anything else as its canonical JSON.

Definition at line 308 of file host.hpp.

identityKey()

std::optional< std::string > morph::ui::identityKey ( Value const & identity )

inlinenodiscard

The canonical text of a screen's identity: what DocumentScreenHost::identityOf answers, so identityOf(id, params) == identityKey(handle.identity().peek()) says whether a mounted screen is the one those params would open.

Parameters

identity

The identity value.

Returns

Its JSON with record fields in name order, or std::nullopt for null (a screen without an identity).

Definition at line 322 of file host.hpp.

sameIdentity()

bool morph::ui::sameIdentity ( Value const & lhs, Value const & rhs )

inlinenodiscard

Whether two identities name the same screen instance: their keys are equal, and neither is null.

Parameters

lhs	One identity.
rhs	The other.

Returns

True when both have a key and the keys are equal; null equals nothing, itself included.

Definition at line 333 of file host.hpp.