diff --git a/src/gui/ctrl/bus-term.hpp b/src/gui/ctrl/bus-term.hpp index 644a63acf..3310ff7b7 100644 --- a/src/gui/ctrl/bus-term.hpp +++ b/src/gui/ctrl/bus-term.hpp @@ -22,12 +22,23 @@ /** @file bus-term.hpp - ** Attachment point to the UI-Bos. + ** Attachment point to the UI-Bus. ** Every gui::model::Tangible holds a BusTerm, which is linked ** to the Tangible's identity, and serves to relay interface actions - ** towards the Proc-Layer. Moreover, the BusTerm is the service point + ** towards the Proc-Layer, to remember state changes and to broadcast + ** notifications. Moreover, the BusTerm is the service point ** to receive structural change messages. ** + ** \par Lifecycle and identity + ** An BusTerm is always created starting from another BusTerm, to + ** which it will be wired. Moreover, each BusTerm bears a distinct + ** [identity][::endpointID_], which is used as _implicit subject_ + ** for emanating messages, or as explicit destination for routing. + ** The whole [UI-Bus][BusController] is built to perform within the + ** UI event thread and thus is _not threadsafe_. For that reason, + ** the automatic detachment built into each BusTerm's dtor is + ** sufficient to ensure sane connectivity. + ** ** @todo as of 11/2015 this is complete WIP-WIP-WIP ** ** @see ////TODO_test usage example @@ -42,6 +53,8 @@ #include "lib/error.hpp" //#include "lib/symbol.hpp" //#include "lib/util.hpp" +#include "lib/idi/entry-id.hpp" +#include "lib/diff/gen-node.hpp" #include #include @@ -52,23 +65,54 @@ namespace ctrl{ // using lib::HashVal; // using util::isnil; + using lib::idi::EntryID; + using lib::diff::GenNode; using std::string; /** - * @todo write type comment... + * connection point at the UI-Bus. + * The UI-Bus is a star shaped network of terminal points, + * where each \link Tangible tangible UI element \endlink + * 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 \em 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. */ class BusTerm : boost::noncopyable { - string nothing_; + EntryID endpointID_; + BusTerm& theBus_; public: - BusTerm(); - ~BusTerm(); + virtual ~BusTerm(); ///< this is an interface + + virtual void act (GenNode command) =0; + virtual void note (GenNode mark) =0; + virtual void mark (GenNode mark) =0; + + virtual void act (EntryID subject, GenNode command) =0; + virtual void note (EntryID subject, GenNode mark) =0; + virtual void mark (EntryID subject, GenNode mark) =0; + + BusTerm attach (EntryID newAddress); protected: - string mayday () const; + BusTerm(EntryID identity, BusTerm& attached_to =*this) + : endpointID_(identity) + , theBus_(attached_to) + { } }; diff --git a/wiki/renderengine.html b/wiki/renderengine.html index 5bb0a22c2..027adeda4 100644 --- a/wiki/renderengine.html +++ b/wiki/renderengine.html @@ -2448,7 +2448,7 @@ The workspace starts out with a single element, corresponding to the »model roo Speaking of implementation, this state and update mechanics relies on two crucial provisions: Lumiera's framework for [[tree diff representation|TreeDiffModel]] and the ExternalTreeDescription, which is an abstracted, ~DOM-like rendering of the relevant parts of the session; this model tree is comprised of [[generic node elements|GenNode]] acting as proxy for [[calls into|SessionInterface]] the [[session model|HighLevelModel]] proper. -
+
Considerations regarding the [[structure of custom timeline widgets|GuiTimelineWidgetStructure]] highlight again the necessity of a clean separation of concerns and an "open closed design". For the purpose of updating the timeline(s) to reflect the HighLevelModel in Proc-Layer, several requirements can be identified
 * we need incremental updates: we must not start redrawing each and everything on each tiny change
 * we need recursive programming, since this is the only sane way to deal with tree like nested structures.
@@ -2475,7 +2475,7 @@ Hereby we introduce a new in-layer abstraction: The UI-Bus.
 
 
 !initiating model updates
-Model updates are always pushed up from Proc-Layer, coordinated by the ProcDispatcher. A model update can be requested by the GUI -- but the actual update will arrive asynchronously. The update information originate from within the [[build process|BuildFixture]]. {{red{TODO 10/2014 clarify the specifics}}}. When updates arrive, a ''diff is generated'' against the current GuiModel contents. The GuiModel is updated to reflect the differences and the Receivers or Listeners are signalled. It is their responsibility in turn to schedule an update operation into the GUI event thread. When performing this update, the Listener thus actively retrieves and pulls the diffed information from within the GUI event thread. The GuiModel's object monitor is sufficient to coordinate this handover.
+Model updates are always pushed up from Proc-Layer, coordinated by the ProcDispatcher. A model update can be requested by the GUI -- but the actual update will arrive asynchronously. The update information originate from within the [[build process|BuildFixture]]. {{red{TODO 10/2014 clarify the specifics}}}. When updates arrive, a ''diff is generated'' against the current GuiModel contents. The GuiModel is updated to reflect the differences and then notifications for any Receivers or Listeners are scheduled into the GUI event thread. On reception, it is their responsibility in turn to pull the targeted diff. When performing this update, the Listener thus actively retrieves and pulls the diffed information from within the GUI event thread. The GuiModel's object monitor is sufficient to coordinate this handover.
 &rarr; representation of changes as a [[tree of diffs|TreeDiffModel]]
 &rarr; properties and behaviour of [[generic interface elements|UI-Element]]
 
@@ -8314,7 +8314,7 @@ The UI-Bus is a ''Mediator'' -- impersonating the role of the //Model// and the
 
 The ~MVC-Pattern as such is fine, and probably the best we know for construction of user interfaces. But it doesn't scale well towards the integration into a larger and more structured system. There is a tension between the Controller in the UI and other parts of an application, which as well need to be //in control.// And, even more important, there is a tension between the demands of UI elements for support by a model, and the demands to be placed on a core domain model of a large scale application. This tension is resolved by enacting these roles while transforming the requests and demands into //Messages.//
-
+
While our UI widgets are implemented the standard way as proposed by GTKmm, some key elements -- which are especially relevant for the anatomy and mechanics of the interface -- are made to conform to a common interface and behaviour protocol. {{red{WIP 11/15 work out what this protocol is all about}}}. #975
 As a starting point, we know
 * there is a backbone structure known as the UI-Bus
@@ -8346,10 +8346,10 @@ And finally, there are the //essential updates// -- any changes in the model //f
 :connect to an existing term, supply the {{{EntryID}}} of the new element
 ;act
 :send a GenNode representing the action
-;mark
-:send a GenNode representing the //state mark//
 ;note
-:receive a GenNode representing the //feedback//
+:send a GenNode representing the //state mark//
+;mark
+:receive a GenNode representing the //feedback// or replayed //state mark//
 ;signals
 :the individual element exposes some generic signal slots
 :* sigMut prompts the element to draw a diff to alter its configuration
@@ -8360,7 +8360,7 @@ And finally, there are the //essential updates// -- any changes in the model //f
 :* either is an incremental status update
 :* or is a from-scratch reconfiguration
 
-We should note that these conventions of interchange lead to a ''self similar design'' of the UI-Bus: Each {{{BusTerm}}} is a personalised connection to yet another {{{BusTerm}}}. Even the ''bus master'' appears as just another {{{BusTerm}}} to all the communication partners. The overall topology of the bus might be reshaped without the participating elements being aware of such a change.
+We should note that these conventions of interchange lead to a recursive or ''self similar design'' of the UI-Bus: Each {{{BusTerm}}} is a personalised connection to yet another {{{BusTerm}}}. Even the ''bus master'' appears as just another {{{BusTerm}}} to all the communication partners. The overall topology of the bus might be reshaped without the participating elements being aware of such a change.
diff --git a/wiki/thinkPad.ichthyo.mm b/wiki/thinkPad.ichthyo.mm index 56bc7c20a..c7e054322 100644 --- a/wiki/thinkPad.ichthyo.mm +++ b/wiki/thinkPad.ichthyo.mm @@ -142,32 +142,35 @@ - +

- mark: Nachricht upstream bzw broadcast + act, note: Nachricht upstream

- +

- note: Nachricht downstream + mark: Nachricht downstream

+ + + @@ -208,7 +211,22 @@ - + + + + + + + + + + + + + + + +