Lumiera  0.pre.03
»edityourfreedom«
BusTerm Class Reference

#include "gui/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 Proc-Layer or the UI state manager), while the mark messages are always directed downstream towards some element.

Definition at line 105 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 More...
 
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 More...
 
virtual operator string () const
 

Protected Types

using EntryID = lib::idi::BareEntryID
 
using Tangible = gui::model::Tangible
 

Protected Member Functions

 BusTerm (ID identity, BusTerm &attached_to)
 
bool isShortCircuit (ID) const noexcept
 
virtual BusTermrouteAdd (ID, Tangible &)
 
virtual void routeDetach (ID) noexcept
 

Protected Attributes

EntryID endpointID_
 
BusTermtheBus_
 

Additional Inherited Members

- Private Member Functions inherited from MoveOnly
 MoveOnly ()=default
 
 MoveOnly (MoveOnly &&)=default
 
 MoveOnly (MoveOnly const &)=delete
 
 ~MoveOnly ()=default
 
MoveOnlyoperator= (MoveOnly &&)=delete
 
MoveOnlyoperator= (MoveOnly const &)=delete
 

Member Typedef Documentation

◆ EntryID

using EntryID = lib::idi::BareEntryID
protected

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

◆ Tangible

using Tangible = gui::model::Tangible
protected

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

◆ ID

using ID = EntryID const&

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

Constructor & Destructor Documentation

◆ ~BusTerm()

~BusTerm ( )
virtual

this is an interface

Note
detaches the corresponding node automatically

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

Referenced by Nexus::zombificate().

+ 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
identityused for routing towards this BusTerm
attached_tothe "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 149 of file bus-term.hpp.

Member Function Documentation

◆ act()

void act ( GenNode const &  command)
virtual

prepare or trigger invocation of a command.

Parameters
commanda 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 gui::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 proc 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
gui::model::Tangible::issueCommand()
proc::control::SessionCommand

Reimplemented in CoreService.

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

References BusTerm::act().

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

+ 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
subjectthe endpoint-ID of the emitting element
markthe 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 CoreService.

Definition at line 158 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
subjectthe endpoint-ID of the element to address
markthe actual state update or notification message to be delivered
Remarks
each addressed "subject" is a gui::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.

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

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

+ 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
markthe 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.

Definition at line 192 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
diffencapsulated 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::Statewhen 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.

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

Referenced by NotificationService::mutate().

+ Here is the caller graph for this function:

◆ operator string()

operator string ( ) const
virtual

Reimplemented in Nexus.

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

◆ note() [2/2]

void note ( GenNode const &  mark)
inline

record state mark from this subject

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

◆ getID()

ID getID ( ) const
inline

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

Referenced by MockElm::getID(), Tangible::operator ID(), 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
newNodethe 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 112 of file ui-bus.cpp.

Referenced by Tangible::Tangible().

+ Here is the caller graph for this function:

◆ routeAdd()

BusTerm & routeAdd ( ID  identity,
Tangible node 
)
protectedvirtual

establish new down-link connection form UI-Bus

Parameters
nodereference to the [Tangible] to be connected.
Returns
corresponding up-link for the initiating node to use

Reimplemented in Nexus.

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

References BusTerm::routeAdd().

Referenced by 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.

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

References BusTerm::routeDetach().

Referenced by 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 172 of file bus-term.hpp.

Member Data Documentation

◆ endpointID_

EntryID endpointID_
protected

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

◆ theBus_

BusTerm& theBus_
protected

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

+ Inheritance diagram for BusTerm:
+ Collaboration diagram for BusTerm:

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