morph::qt_quick::Components Class Reference

The QML components a client renders beside the built-in kinds (spec 5 §10). More...

#include <components.hpp>

Public Member Functions
	Components (std::function< void(ComponentFailure const &)> report={})
	An empty set.
	~Components ()
	Releases the compiled components and the contained engine.
	Components (Components const &)=delete
Components &	operator= (Components const &)=delete
	Components (Components &&)=delete
Components &	operator= (Components &&)=delete
void	addHost (std::string name, int version, QUrl const &source)
	Registers a host component, replacing one of the same name.
void	addBundle (std::string name, std::string qml, std::string digest)
	Registers a bundle component, replacing one of the same name.
std::expected< void, ComponentFailure >	restyle (QQmlEngine &engine, std::string const &kind, std::string const &component)
	Maps a built-in kind to a registered component, checking that the component declares every property and function of the kind's MorphUi component.
std::unique_ptr< QQmlComponent >	restyled (QQmlEngine &engine, std::string const &type)
	The compiled component a restyle maps a MorphUi type to, for a backend to instantiate.
std::expected< QQmlComponent *, ComponentFailure >	load (QQmlEngine &engine, std::string const &name, int minVersion=0)
	Compiles a registered component, or says why it cannot be used.
void	report (ComponentFailure const &failure)
	Reports a failure, once per name and reason.
std::vector< ComponentFailure > const &	failures () const noexcept
	Every failure reported so far, oldest first.

Detailed Description

The QML components a client renders beside the built-in kinds (spec 5 §10).

• A host component is QML the client carries, registered by name and version. It loads into the backend's own engine, so it may import the application's other modules.
• A bundle component is QML text delivered in the application's bundle and named by its SHA-256 digest. It loads only when the text matches the digest, and compiles in a dedicated engine whose root context holds nothing, so it sees nothing but what is set on it.
• The restyle map names a component for a built-in kind, or for a part a built-in component draws (tableRow, a table row's background; tableHeader, a table's header background; scrollBar, a scroll area's bar; splitterHandle, a splitter's handle). The component must declare every property and function of its MorphUi base; one that does not is refused when it is mapped.

Each component reports its events through host.fire(event, payload), host being a var property it declares and the renderer sets. A component that fails to load is reported once, through the callback, and the caller renders its fallback. Neither copyable nor movable; it outlives every backend that uses it.

Definition at line 48 of file components.hpp.

Constructor & Destructor Documentation

Components()

morph::qt_quick::Components::Components ( std::function< void(ComponentFailure const &)> report = {} )

explicit

An empty set.

Parameters

report

Called once for each component that fails to load, or restyle that is refused; may be empty.

Member Function Documentation

addHost()

void morph::qt_quick::Components::addHost	(	std::string	name,
		int	version,
		QUrl const &	source )

Registers a host component, replacing one of the same name.

Parameters

name	The name a document uses.
version	The version the client carries; a document asking for a later one gets the fallback.
source	The QML file, such as a qrc: URL.

addBundle()

void morph::qt_quick::Components::addBundle	(	std::string	name,
		std::string	qml,
		std::string	digest )

Registers a bundle component, replacing one of the same name.

Parameters

name	The name a document uses.
qml	The QML text, as the bundle delivered it.
digest	Its SHA-256, as the bundle names it: sha256: followed by 64 hexadecimal digits.

restyle()

std::expected< void, ComponentFailure > morph::qt_quick::Components::restyle ( QQmlEngine & engine, std::string const & kind, std::string const & component )

nodiscard

Maps a built-in kind to a registered component, checking that the component declares every property and function of the kind's MorphUi component.

Parameters

engine	The engine the backend renders with. Borrowed for the call.
kind	The kind as a document names it (button, textInput, checkbox, select, …), the multi-line input (textArea), or a part kind (tableRow).
component	The registered component's name.

Returns

Nothing, or why the mapping is refused; a refusal is also reported, and the kind keeps its MorphUi component.

restyled()

std::unique_ptr< QQmlComponent > morph::qt_quick::Components::restyled ( QQmlEngine & engine, std::string const & type )

nodiscard

The compiled component a restyle maps a MorphUi type to, for a backend to instantiate.

Parameters

engine	The backend's engine. Borrowed for the call.
type	The MorphUi type, such as MorphButton.

Returns

The component, or null when the type is not restyled.

load()

std::expected< QQmlComponent *, ComponentFailure > morph::qt_quick::Components::load ( QQmlEngine & engine, std::string const & name, int minVersion = 0 )

nodiscard

Compiles a registered component, or says why it cannot be used.

Parameters

engine	The backend's engine, which host components load into. Borrowed for the call.
name	The component's name.
minVersion	The lowest host component version that will do.

Returns

The compiled component, owned by this set, or the failure, which is also reported once.

report()

void morph::qt_quick::Components::report

(

ComponentFailure const &

failure

)

Reports a failure, once per name and reason.

Parameters

failure

The failure.

failures()

std::vector< ComponentFailure > const & morph::qt_quick::Components::failures ( ) const

nodiscardnoexcept

Every failure reported so far, oldest first.

Returns

They.

---

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

• morph/qt_quick/components.hpp