BusTerm Class Reference

#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
	BusTerm (BusTerm &&)=default
	may be moved, but not copied, due to the embedded identity
virtual	~BusTerm ()
	this is an interface More...
virtual void	act (GenNode const &command)
	prepare or trigger invocation of a command. More...
BusTerm	attach (ID, Tangible &newNode)
	Builder function: establish and wire a new BusTerm. More...
virtual bool	change (ID subject, MutationMessage &&diff)
	alter and reshape the designated subject by applying the given diff message. More...
ID	getID () const
virtual bool	mark (ID subject, GenNode const &mark)
	route a state update or notification to the given subject. More...
virtual size_t	markAll (GenNode const &mark)
	broadcast a notification message to all currently connected bus terminals. More...
virtual void	note (ID subject, GenNode const &mark)
	capture and record a "state mark" for later replay for restoring UI state. More...
void	note (GenNode const &mark)
	record state mark from this subject
virtual	operator string () const

Protected Types
using	EntryID = lib::idi::BareEntryID
using	Tangible = stage::model::Tangible

Protected Member Functions
	BusTerm (ID identity, BusTerm &attached_to)
bool	isShortCircuit (ID) const noexcept
virtual BusTerm &	routeAdd (ID, Tangible &)
virtual void	routeDetach (ID) noexcept

Protected Attributes
EntryID	endpointID_
BusTerm &	theBus_

Additional Inherited Members
Private Member Functions inherited from MoveOnly
	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 83 of file ui-bus.cpp.

Referenced by Nexus::zombificate().

Here is the caller graph for this function:

BusTerm()

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 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 ZombieNexus, CoreService, and TestNexus.

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

References BusTerm::act().

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

Here is the call graph for this function:

Here is the caller graph for this function:

note()

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 ZombieNexus, CoreService, and TestNexus.

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

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

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 ZombieNexus, TestNexus, and Nexus.

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

Referenced by BusTerm_test::attachNewBusTerm(), NotificationService::dispatchMsg(), StateRecorder::replayAllState(), and StateRecorder::replayPropertiesOf().

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 ZombieNexus, TestNexus, and Nexus.

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

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 ZombieNexus, TestNexus, and Nexus.

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

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 103 of file ui-bus.cpp.

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 ZombieNexus, TestNexus, and Nexus.

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

routeDetach()

void routeDetach ( ID  node )

protectedvirtualnoexcept

disable down-link connection

Remarks

corresponding node is about to go away.

Reimplemented in ZombieNexus, TestNexus, and Nexus.

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

isShortCircuit()

bool isShortCircuit ( ID  otherID ) const

inlineprotectednoexcept

circuit breaker, relevant for Nexus shutdown

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

Inheritance diagram for BusTerm:

Collaboration diagram for BusTerm:

---

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

• bus-term.hpp
• ui-bus.cpp