UI-Bus/mutation: draft idea for mutation message on UI-Bus

src/gui/ctrl/bus-controller.cpp

@@ -73,6 +73,9 @@ namespace ctrl {
   }
   
   
+  MutationMessage::~MutationMessage() { }
+  
+  
   
   
   /** Builder function: establish and wire a new BusTerm.
@@ -171,6 +174,24 @@ namespace ctrl {
   }
   
   
+  /** alter and reshape the designated subject by applying the given diff message.
+   * @param diff encapsulated representation of a concrete diff sequence for the target.
+   * @return if the target was known and the diff was applied without accident
+   * @throws lumiera::error::State when diff application fails due to the target's shape
+   *         or state being different than implicitly assumed by the given diff.
+   * @remark 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.
+   */
+  void
+  BusTerm::change (ID subject, MutationMessage& diff)
+  {
+    theBus_.change(subject, diff);
+  }
+  
+  
   /**
    * @internal establish new down-link connection form UI-Bus
    * @param node reference to the [Tangible] to be connected.

src/gui/ctrl/bus-term.hpp

@@ -55,6 +55,7 @@
 //#include "lib/util.hpp"
 #include "lib/idi/entry-id.hpp"
 #include "lib/diff/gen-node.hpp"
+#include "gui/ctrl/mutation-message.hpp"
 
 #include <boost/noncopyable.hpp>
 #include <utility>
@@ -111,6 +112,7 @@ namespace ctrl{
       virtual bool mark (ID subject, GenNode const& mark);
       
       virtual size_t markAll (GenNode const& mark);
+      virtual void change (ID subject, MutationMessage& diff);
       
       virtual operator string()  const;
       

src/gui/ctrl/mutation-message.hpp

@@ -0,0 +1,104 @@
+/*
+  MUTATION-MESSAGE.hpp  -  message on UI-Bus to cause changes to tangible UI elements
+
+  Copyright (C)         Lumiera.org
+    2016,               Hermann Vosseler <Ichthyostega@web.de>
+
+  This program is free software; you can redistribute it and/or
+  modify it under the terms of the GNU General Public License as
+  published by the Free Software Foundation; either version 2 of
+  the License, or (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, write to the Free Software
+  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+*/
+
+
+/** @file mutation-message.hpp
+ ** Message on the UI-Bus to cause changes on the targeted [UI-Element](\ref Tangible).
+ ** The UI-Bus offers a dedicated API to direct MutationMessages towards Tangible elements,
+ ** as designated by the given ID. Actually, such messages serve as capsule to transport a
+ ** diff-sequence -- since a diff sequence as such is always concrete and tied to a specific context,
+ ** we can not represent it directly as an abstract type on interface level. The receiver of a diff
+ ** sequence must offer the ability to be reshaped through diff messages, which is expressed through
+ ** the interface DiffMutable. In the case at question here, gui::model::Tangible offers this interface
+ ** and thus the ability to construct a concrete lib::diff::TreeMutator, which in turn is bound to the
+ ** internals of the actual UI-Element. Together this allows for a generic implementation of MutationMessage
+ ** handling, where the designated UI-Element is reshaped by applying an embedded concrete diff message
+ ** with the help of a `DiffApplicator<DiffMutable>`, based on the TreeMutator exposed.
+ ** 
+ ** ## Creating mutation messages
+ ** The UI-Bus invocation actually takes a reference to MutationMessage, and thus on usage a
+ ** concrete instance needs to be created. This concrete Message embeds an actual diff sequence,
+ ** which is an iterable sequence of lib::diff::DiffStep records.
+ ** 
+ ** @todo as of 10/2016 this is WIP-WIP-WIP
+ ** 
+ ** @see [AbstractTangible_test]
+ ** 
+ */
+
+
+#ifndef GUI_CTRL_MUTATION_MESSAGE_H
+#define GUI_CTRL_MUTATION_MESSAGE_H
+
+
+#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 <boost/noncopyable.hpp>
+//#include <utility>
+#include <string>
+
+
+namespace gui {
+namespace model {
+  class Tangible;
+}
+namespace ctrl{
+  
+//  using lib::HashVal;
+//  using util::isnil;
+//  using lib::idi::EntryID;
+//  using lib::diff::GenNode;
+  using std::string;
+  
+  
+  /**
+   * Message on the UI-Bus holding an embedded diff sequence.
+   * The Nexus (hub of the UI-Bus) will prompt the designated Tangible
+   * to expose a TreeMutator, and then apply the embedded diff.
+   */
+  class MutationMessage
+    {
+    protected:
+      
+    public:
+      virtual ~MutationMessage();  ///< this is an interface
+      
+      operator string()  const
+        {
+          UNIMPLEMENTED("string representation of diff/mutation messages");
+        }
+      
+    protected:
+    };
+  
+  
+    
+  
+  /**  */
+  
+  
+}} // namespace gui::ctrl
+#endif /*GUI_CTRL_MUTATION_MESSAGE_H*/

src/gui/ctrl/nexus.hpp

@@ -114,6 +114,15 @@ namespace ctrl{
           return routingTable_.size();
         }
       
+      
+      /** */
+      virtual void
+      change (ID subject, MutationMessage& diff)  override
+        {
+          UNIMPLEMENTED("actually apply a diff to the target Tangible");
+        }
+      
+      
       /** add a new down-link connection to the routing table
        * @param identity the [endpoint-ID](\ref BusTerm::endpointID_) used
        *         to address the new element to be connected to the bus.

tests/gui/test/test-nexus.cpp

@@ -75,6 +75,7 @@ using lib::diff::DataValues;
 using lib::idi::instanceTypeID;
 using lib::test::EventLog;
 using gui::ctrl::BusTerm;
+using gui::ctrl::MutationMessage;
 using gui::interact::PresentationStateManager;
 using gui::interact::StateRecorder;
 using proc::control::Command;
@@ -211,6 +212,14 @@ namespace test{
             return cnt;
           }
         
+        virtual void
+        change (ID subject, MutationMessage& diff)  override
+          {
+            log_.call (this, "change", subject, diff);
+            BusHub::change (subject, diff);
+            log_.event ("TestNexus", _Fmt("applied diff to %s |%s") % subject % diff);
+          }
+        
         virtual BusTerm&
         routeAdd (ID identity, Tangible& newNode)  override
           {
@@ -345,6 +354,14 @@ namespace test{
             return 0;
           }
         
+        virtual void
+        change (ID subject, MutationMessage& diff)  override
+          {
+            log().call(this, "change", subject, diff);
+            log().error ("request to apply a diff message via ZombieNexus");
+            cerr << "change diff -> ZombieNexus" <<endl;
+          }
+        
         virtual BusTerm&
         routeAdd (ID identity, Tangible& newNode)  override
           {

wiki/thinkPad.ichthyo.mm

@@ -5543,6 +5543,33 @@
 <icon BUILTIN="help"/>
 </node>
 </node>
+<node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1475342135193" HGAP="31" ID="ID_336806935" MODIFIED="1475342156412" TEXT="Problem: Diff-Nachricht" VSHIFT="7">
+<icon BUILTIN="messagebox_warning"/>
+<node CREATED="1475342157302" ID="ID_1383404259" MODIFIED="1475342166025" TEXT="&quot;Diff&quot; ist kein Typ"/>
+<node CREATED="1475342185707" ID="ID_787925049" MODIFIED="1475342190662" TEXT="Lumiera-Iteratoren sind generisch"/>
+<node CREATED="1475342218598" ID="ID_686706998" MODIFIED="1475342224385" TEXT="Alternativen">
+<icon BUILTIN="idea"/>
+<node CREATED="1475342242123" ID="ID_996905586" MODIFIED="1475342351972" TEXT="implizite Diff-Facade">
+<icon BUILTIN="button_cancel"/>
+<node CREATED="1475342267168" ID="ID_1015562836" MODIFIED="1475342372677" TEXT="nur ID eines Diff senden..."/>
+<node CREATED="1475342283158" ID="ID_859890341" MODIFIED="1475342287497" TEXT="Diff ist dann hinterlegt"/>
+<node CREATED="1475342309914" ID="ID_1398047498" MODIFIED="1475342360640" TEXT="Wo? im GuiModel??">
+<icon BUILTIN="idea"/>
+</node>
+<node CREATED="1475342301331" ID="ID_496549205" MODIFIED="1475342346474" TEXT="zwar implizit, aber starr">
+<icon BUILTIN="button_cancel"/>
+</node>
+</node>
+<node CREATED="1475342230013" ID="ID_129545687" MODIFIED="1475353925913" TEXT="UI-Bus-Interface erweitern">
+<icon BUILTIN="button_ok"/>
+<node CREATED="1475342469085" ID="ID_218240539" MODIFIED="1475342487060" TEXT="Ausgangspunkt: DiffMutable">
+<icon BUILTIN="idea"/>
+</node>
+<node CREATED="1475342391631" ID="ID_1330153391" MODIFIED="1475342446252" TEXT="Platzhalter-Typ: DiffMessage"/>
+<node CREATED="1475342401278" ID="ID_1020722080" MODIFIED="1475342430750" TEXT="macht Diff zug&#xe4;nglich"/>
+</node>
+</node>
+</node>
 </node>
 <node CREATED="1473352470896" ID="ID_864450713" MODIFIED="1473352474499" TEXT="Unit-Tests">
 <node CREATED="1473352475375" ID="ID_731425414" MODIFIED="1473352482010" TEXT="AbstractTangible_test"/>