#include "stage/ctrl/bus-term.hpp"

Description

connection point at the UI-Bus.

The UI-Bus is a star shaped network of terminal points, where each tangible UI element holds a BusTerm serving access point. The BusTerm interface exposes the basic "verbs" available for communication within the UI

to act on an element means to issue a command
to note some state or information for later replay
to mark as erroneous, send an information message, replay remembered presentation state or effect structural change There are indirect variants of the message verbs, which are intended for routing, broadcasting or forwarding. Effectively, routing is determined from the context and meaning of a message, where the act and note messages have an implicit receiver (either the Steam-Layer or the UI state manager), while the mark messages are always directed downstream towards some element.

Definition at line 96 of file bus-term.hpp.

Public Types
using	ID = EntryID const &

Public Member Functions
virtual	~BusTerm ()
	this is an interface

virtual void	act (GenNode const &command)
	prepare or trigger invocation of a command.

virtual void	note (ID subject, GenNode const &mark)
	capture and record a "state mark" for later replay for restoring UI state.

virtual bool	mark (ID subject, GenNode const &mark)
	route a state update or notification to the given subject.

virtual size_t	markAll (GenNode const &mark)
	broadcast a notification message to all currently connected bus terminals.

virtual bool	change (ID subject, MutationMessage &&diff)
	alter and reshape the designated subject by applying the given diff message.

virtual	operator string () const

void	note (GenNode const &mark)
	record state mark from this subject

ID	getID () const

BusTerm	attach (ID, Tangible &newNode)
	Builder function: establish and wire a new BusTerm.

	BusTerm (BusTerm &&)=default
	may be moved, but not copied, due to the embedded identity

Protected Types
using	EntryID = lib::idi::BareEntryID

using	Tangible = stage::model::Tangible

Protected Member Functions
	BusTerm (ID identity, BusTerm &attached_to)

virtual BusTerm &	routeAdd (ID, Tangible &)

virtual void	routeDetach (ID) noexcept

bool	isShortCircuit (ID) const noexcept

Protected Attributes
EntryID	endpointID_

BusTerm &	theBus_

Additional Inherited Members
Private Member Functions inherited from MoveOnly
	~MoveOnly ()=default

	MoveOnly ()=default

	MoveOnly (MoveOnly &&)=default

	MoveOnly (MoveOnly const &)=delete

MoveOnly &	operator= (MoveOnly &&)=delete

MoveOnly &	operator= (MoveOnly const &)=delete

Constructor & Destructor Documentation

◆ ~BusTerm()

~BusTerm ( )

virtual

this is an interface

Note: detaches the corresponding node automatically

Definition at line 66 of file ui-bus.cpp.

References BusTerm::endpointID_, BusTerm::routeDetach(), and BusTerm::theBus_.

Referenced by Nexus::zombificate().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ BusTerm() [1/2]

BusTerm ( BusTerm && )

default

may be moved, but not copied, due to the embedded identity

◆ BusTerm() [2/2]

BusTerm	(	ID	identity,
		BusTerm &	attached_to
	)

inlineprotected

Parameters

identity	used for routing towards this BusTerm
attached_to	the "upstream" connection to the Bus

Warning: it is essential that this ctor just initialises the references, but never invokes any operation on the upstream connection. Because this allows to build mutually interdependent connections.

Definition at line 140 of file bus-term.hpp.

Member Typedef Documentation

◆ EntryID

using EntryID = lib::idi::BareEntryID

protected

Definition at line 100 of file bus-term.hpp.

◆ Tangible

using Tangible = stage::model::Tangible

protected

Definition at line 101 of file bus-term.hpp.

◆ ID

using ID = EntryID const&

Definition at line 107 of file bus-term.hpp.

Member Function Documentation

◆ act()

void act ( GenNode const & command )

virtual

prepare or trigger invocation of a command.

Parameters

command a GenNode either holding command parameters

Remarks: some commands can simply be invoked right away, but in the general case, a command needs to be prepared with suitable arguments prior to being invoked, which can be a multi-step process. The stage::interact::InteractionState is used to conduct this argument binding process from within the UI. Here, at the UI-Bus interface, we're just interested in the fact that some command is to be bound and invoked. This information is forwarded to the command receiver service, which in turn talks to the steam dispatcher.

Note: no information regarding the origin of this command invocation is captured. If a command needs a subject, this has to be bound as an command argument beforehand.

See also: stage::model::Tangible::issueCommand(); steam::control::SessionCommand

Reimplemented in TestNexus, ZombieNexus, and CoreService.

Definition at line 113 of file ui-bus.cpp.

References BusTerm::act(), and BusTerm::theBus_.

Referenced by TestControl::Page1::Page1(), TestControl::Page2::Page2(), BusTerm::act(), Tangible::invoke(), and Tangible::invoke().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ note() [1/2]

void note	(	ID	subject,
		GenNode const &	mark
	)

virtual

capture and record a "state mark" for later replay for restoring UI state.

Parameters

subject	the endpoint-ID of the emitting element
mark	the actual state update or notification message to be remembered

Remarks: relevant changes to presentation state, which are to be recalled and restored later, are emitted from the place they occur, packaged as "state mark" messages. This assumes the presence of some dedicated presentation state manager, attached and listening somewhere at a core service location. Such a core presentation state service has additional shared understanding of the state mark's meaning; it is assumed to track cumulated state, which will be replayed later when it comes to restoring some presentation state.

Reimplemented in TestNexus, ZombieNexus, and CoreService.

Definition at line 132 of file ui-bus.cpp.

References BusTerm::mark(), BusTerm::note(), and BusTerm::theBus_.

Referenced by Tangible::clearErr(), Tangible::clearMsg(), Tangible::doMark(), Tangible::markErr(), Tangible::markMsg(), BusTerm::note(), BusTerm::note(), Tangible::reset(), Tangible::slotCollapse(), and Tangible::slotExpand().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mark()

bool mark	(	ID	subject,
		GenNode const &	mark
	)

virtual

route a state update or notification to the given subject.

Parameters

subject	the endpoint-ID of the element to address
mark	the actual state update or notification message to be delivered

Remarks: each addressed "subject" is a stage::model::Tangible, and as such holds a BusTerm of its own, which in turn ensures a registration and connection from the central routing hub down to the element. Thus, the default implementation is just to pass the given state mark "up", assuming that it will reach the hub eventually, which in turn knows how to reach the element, and invoke the Tangible::mark() operation.

Returns: true if the target was known and the mark operation dispatched.

Note: messages to unreachable elements will be dropped.

Reimplemented in Nexus, TestNexus, and ZombieNexus.

Definition at line 151 of file ui-bus.cpp.

References BusTerm::mark(), and BusTerm::theBus_.

Referenced by BusTerm_test::attachNewBusTerm(), NotificationService::dispatchMsg(), BusTerm::mark(), BusTerm::markAll(), BusTerm::note(), StateRecorder::replayAllState(), StateRecorder::replayPropertiesOf(), and StateRecorder::replayState().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ markAll()

size_t markAll ( GenNode const & mark )

virtual

broadcast a notification message to all currently connected bus terminals.

Parameters

mark	the actual state update or notification message to be delivered

Returns: number of notified terminals.

Remarks: this call assumes that "somewhere" within the UI-Bus a distribution node or hub is installed, with the ability to find all currently connected terminals. In the standard configuration this is implemented by the ctrl::Nexus

Reimplemented in Nexus, TestNexus, and ZombieNexus.

Definition at line 166 of file ui-bus.cpp.

References BusTerm::mark(), BusTerm::markAll(), and BusTerm::theBus_.

Referenced by BusTerm::markAll().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ change()

bool change	(	ID	subject,
		MutationMessage &&	diff
	)

virtual

alter and reshape the designated subject by applying the given diff message.

Parameters

diff	encapsulated representation of a concrete diff sequence for the target.

Returns: true if the target was known and the diff was applied without accident, false if no diff was applied because the desired target is unconnected.

Exceptions

lumiera::error::State when diff application fails due to the target's shape or state being different than implicitly assumed by the given diff.

Remarks: each tangible offers to build a custom TreeMutator, which is appropriately wired to receive diff messages targeted towards this specific element. The standard implementation within the Nexus uses this ability to create a DiffApplicator<DiffMutable>, finally to feed the given diff to the target, which consequently will reshape and remould itself accordingly.

Reimplemented in Nexus, TestNexus, and ZombieNexus.

Definition at line 185 of file ui-bus.cpp.

References BusTerm::change(), and BusTerm::theBus_.

Referenced by BusTerm::change(), and NotificationService::mutate().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator string()

operator string ( ) const

virtual

Reimplemented in Nexus, TestNexus, and ZombieNexus.

Definition at line 215 of file ui-bus.cpp.

◆ note() [2/2]

void note ( GenNode const & mark )

inline

record state mark from this subject

Definition at line 156 of file bus-term.hpp.

References BusTerm::endpointID_, BusTerm::note(), and BusTerm::theBus_.

Here is the call graph for this function:

◆ getID()

ID getID ( ) const

inline

Definition at line 122 of file bus-term.hpp.

References BusTerm::endpointID_.

Referenced by Tangible::getID(), MockElm::getID(), Tangible::operator LuidH(), and Nexus::zombificate().

Here is the caller graph for this function:

◆ attach()

BusTerm attach	(	ID	identity,
		Tangible &	newNode
	)

Builder function: establish and wire a new BusTerm.

Parameters

newNode the UI-Element corresponding to and using the new BusTerm

Remarks: automatically establishes a down-link connection to the given [Tangible]; the UI-Bus will use this node as target to dispatch mark messages addressed to the new node's ID. It is expected that the Tangible in turn will use the returned BusTerm for any up-link communication. Thus, on destruction, the new BusTerm will detach this UI-Bus connection altogether.

Definition at line 86 of file ui-bus.cpp.

References BusTerm::routeAdd(), and BusTerm::theBus_.

Here is the call graph for this function:

◆ routeAdd()

BusTerm & routeAdd	(	ID	identity,
		Tangible &	node
	)

protectedvirtual

establish new down-link connection form UI-Bus

Parameters

node	reference to the [Tangible] to be connected.

Returns: corresponding up-link for the initiating node to use

Reimplemented in Nexus, TestNexus, and ZombieNexus.

Definition at line 197 of file ui-bus.cpp.

References BusTerm::routeAdd(), and BusTerm::theBus_.

Referenced by BusTerm::attach(), and BusTerm::routeAdd().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ routeDetach()

void routeDetach ( ID node )

protectedvirtualnoexcept

disable down-link connection

Remarks: corresponding node is about to go away.

Reimplemented in Nexus, TestNexus, and ZombieNexus.

Definition at line 208 of file ui-bus.cpp.

References BusTerm::routeDetach().

Referenced by BusTerm::~BusTerm(), and BusTerm::routeDetach().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isShortCircuit()

bool isShortCircuit ( ID otherID ) const

inlineprotectednoexcept

circuit breaker, relevant for Nexus shutdown

Definition at line 163 of file bus-term.hpp.

Member Data Documentation

◆ endpointID_

EntryID endpointID_

protected

Definition at line 103 of file bus-term.hpp.

Referenced by BusTerm::~BusTerm(), BusTerm::getID(), and BusTerm::note().

◆ theBus_

BusTerm& theBus_

protected

Definition at line 104 of file bus-term.hpp.

Referenced by BusTerm::~BusTerm(), BusTerm::act(), BusTerm::attach(), BusTerm::change(), BusTerm::mark(), BusTerm::markAll(), BusTerm::note(), BusTerm::note(), and BusTerm::routeAdd().

Inheritance diagram for BusTerm:

Collaboration diagram for BusTerm:

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

Description

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ ~BusTerm()

◆ BusTerm() [1/2]

◆ BusTerm() [2/2]

Member Typedef Documentation

◆ EntryID

◆ Tangible

◆ ID

Member Function Documentation

◆ act()

◆ note() [1/2]

◆ mark()

◆ markAll()

◆ change()

◆ operator string()

◆ note() [2/2]

◆ getID()

◆ attach()

◆ routeAdd()

◆ routeDetach()

◆ isShortCircuit()

Member Data Documentation

◆ endpointID_

◆ theBus_