copy-n-paste-programming to define SessionCommand interface / service

...the sheer amount of mechanical replacements scattered all over these
files might be a vivid indication, that the design of the interface system
is subobptimal ;-)

src/common/interfaceproxy.cpp

@@ -121,6 +121,11 @@ namespace facade {
 
 
 
+    /* ==================== SessionCommand ================================= */
+    
+#include "proc/control/session-command-interface-proxy.hpp"
+
+
     /* ==================== GuiNotification ================================ */
     
 #include "gui/notification-interface-proxy.hpp"

src/gui/display-interface-proxy.hpp

@@ -69,7 +69,7 @@ namespace facade {
       //----Proxy-Implementation-of-lumiera::Display--------
       
       Display::Sink
-      getHandle (LumieraDisplaySlot display)
+      getHandle (LumieraDisplaySlot display)  override
         {
           _i_.allocate (display);
           Sink sinkHandle;

src/gui/notification-service.hpp

@@ -31,7 +31,7 @@
  ** to \em provide this service, not to access it.
  **
  ** @see gui::GuiFacade
- ** @see guifacade.cpp starting this service 
+ ** @see core-sevice.hpp starting this service
  */
 
 
@@ -67,8 +67,8 @@ namespace gui {
       
       /* === Implementation of the Facade Interface === */
       
-      void displayInfo (string const& text);
+      void displayInfo (string const& text)         override;
-      void triggerGuiShutdown (string const& cause);
+      void triggerGuiShutdown (string const& cause) override;
       
       
       /* === Interface Lifecycle === */

src/include/gui-notification-facade.h

@@ -21,10 +21,14 @@
 */
 
 /** @file gui-notification-facade.h
- ** Major public Interface of the Lumiera GUI. While generally speaking, the GUI
+ ** Major public Interface of the Lumiera GUI. While from a user's point of view,
- ** controls the application and thus acts on its own, it exposes some services
+ ** the GUI controls the application and thus acts on its own, in fact the UI sends
- ** usable by scripts or the two lower layers. The main purpose of these services
+ ** command messages to the Session subsystem in Proc-Layer. These commands cause
- ** is to push status updates and similar information up into the GUI.
+ ** changes in the session, which result in notification and structure change messages
+ ** being pushed up asynchronously back into the UI. The GuiNotification interface
+ ** abstracts this ability of the UI to receive such update messages. It is implemented
+ ** by the NotificationService within the GUI Layer, which causes actual tangible changes
+ ** to happen in the UI in response to the reception of these messages.
  **
  ** @see notification-service.hpp implementation
  ** @see gui::GuiFacade

src/include/session-command-facade.h

@@ -1,8 +1,8 @@
 /*
-  SESSION-COMMAND-FACADE.h  -  access point for pushing information into the GUI
+  SESSION-COMMAND-FACADE.h  -  access point for invoking commands on the session
 
   Copyright (C)         Lumiera.org
-    2008,               Hermann Vosseler <Ichthyostega@web.de>
+    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
@@ -20,11 +20,13 @@
 
 */
 
-/** @file gui-notification-facade.h
+/** @file session-command-facade.h
- ** Major public Interface of the Lumiera GUI. While generally speaking, the GUI
+ ** Major public Interface to the Session subsystem of Lumiera GUI.
- ** controls the application and thus acts on its own, it exposes some services
+ ** This interface describes the ability of the Session to trigger the execution
- ** usable by scripts or the two lower layers. The main purpose of these services
+ ** of pre-defined commands, outfitted with suitably arguments and parameters.
- ** is to push status updates and similar information up into the GUI.
+ ** Triggering of these commands typically happens in response of some messages
+ ** being sent over the UI-Bus. Likewise, external entities (e.g. plug-ins) may
+ ** invoke commands over this interface to alter the session.
  **
  ** @see notification-service.hpp implementation
  ** @see gui::GuiFacade
@@ -44,7 +46,8 @@
 #include <string>
 
 
-namespace gui {
+namespace proc {
+namespace control {
   
   using std::string;
   
@@ -59,10 +62,10 @@ namespace gui {
    * calls through the lumieraorg_GuiNotification interface
    * @throws lumiera::error::State when interface is not opened
    */
-  class GuiNotification
+  class SessionCommand
     {
     public:
-      static lumiera::facade::Accessor<GuiNotification> facade;
+      static lumiera::facade::Accessor<SessionCommand> facade;
       
       /** push a user visible notification text */
       virtual void displayInfo (string const& text)          =0;
@@ -74,12 +77,12 @@ namespace gui {
       
       
     protected:
-      virtual ~GuiNotification() {}
+      virtual ~SessionCommand() {}
     };
     
   
   
-} // namespace gui
+}} // namespace proc::control
 
 
 extern "C" {
@@ -88,7 +91,7 @@ extern "C" {
   
 #include "common/interface.h"
 
-LUMIERA_INTERFACE_DECLARE (lumieraorg_GuiNotification, 0,
+LUMIERA_INTERFACE_DECLARE (lumieraorg_SessionCommand, 0,
                            LUMIERA_INTERFACE_SLOT (void, displayInfo,        (const char*)),
                            LUMIERA_INTERFACE_SLOT (void, triggerGuiShutdown, (const char*)),
 );

src/lib/diff/tree-mutator-collection-binding.hpp

@@ -36,7 +36,7 @@
  ** of "child objects" managed within a typical STL container.
  ** 
  ** As a _special case_, binding to a STL map is supported, while this usage is rather
- ** discurraged, since it contradicts the diff semantics due to intrinsic ordering.
+ ** discouraged, since it contradicts the diff semantics due to intrinsic ordering.
  ** 
  ** @note the header tree-mutator-collection-binding.hpp was split off for sake of readability
  **       and is included automatically from bottom of tree-mutator.hpp

src/proc/control/session-command-interface-proxy.hpp

@@ -1,8 +1,8 @@
 /*
-  SessionCommand(Proxy)  -  public service to push information into the GUI
+  SessionCommand(Proxy)  -  public service to invoke commands on the session
 
   Copyright (C)         Lumiera.org
-    2008,               Hermann Vosseler <Ichthyostega@web.de>
+    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
@@ -25,44 +25,45 @@
 /** @file session-command-interface-proxy.hpp
  ** This is an implementation fragment, intended to be included into common/interfaceproxy.cpp
  ** 
- ** The purpose is to define a proxy implementation of gui::GuiNotification, in order to
+ ** The purpose is to define a proxy implementation of proc::control::SessionCommand, in order to
- ** redirect any calls through the associated C Language Interface "lumieraorg_GuiNotification"
+ ** redirect any calls through the associated C Language Interface "lumieraorg_SessionCommand"
  ** 
- ** @see gui-notification-facade.hpp
+ ** @see session-command-facade.hpp
- ** @see notification-service.hpp actual implementation within the GUI
+ ** @see session-command-service.hpp actual implementation within the GUI
  */
 
 
 
 
 
-/* ==================== GuiNotification =================================== */
+/* ==================== SessionCommand =================================== */
 
-#include "include/gui-notification-facade.h"
+#include "include/session-command-facade.h"
 
-namespace gui {
+namespace proc {
+namespace control {
   
   /** storage for the facade proxy factory
    *  used by client code to invoke through the interface */
-  lumiera::facade::Accessor<GuiNotification> GuiNotification::facade;
+  lumiera::facade::Accessor<SessionCommand> SessionCommand::facade;
 
-} // namespace gui
+}} // namespace proc::control
 
 
 
 namespace lumiera {
 namespace facade {
   
-  typedef InstanceHandle< LUMIERA_INTERFACE_INAME(lumieraorg_GuiNotification, 0)
+  typedef InstanceHandle< LUMIERA_INTERFACE_INAME(lumieraorg_SessionCommand, 0)
-                        , gui::GuiNotification
+                        , proc::control::SessionCommand
-                        > IHandle_GuiNotification;
+                        > IHandle_SessionCommand;
   
   
   template<>
-  class Proxy<IHandle_GuiNotification>
+  class Proxy<IHandle_SessionCommand>
-    : public Holder<IHandle_GuiNotification>
+    : public Holder<IHandle_SessionCommand>
     {
-      //----Proxy-Implementation-of-GuiNotification--------
+      //----Proxy-Implementation-of-SessionCommand--------
       
       void displayInfo (string const& text)         override  { _i_.displayInfo (cStr(text)); }
       void triggerGuiShutdown (string const& cause) override  { _i_.triggerGuiShutdown (cStr(cause)); }
@@ -73,8 +74,8 @@ namespace facade {
     };
   
   
-  template  void openProxy<IHandle_GuiNotification>  (IHandle_GuiNotification const&);
+  template  void openProxy<IHandle_SessionCommand>  (IHandle_SessionCommand const&);
-  template  void closeProxy<IHandle_GuiNotification> (void);
+  template  void closeProxy<IHandle_SessionCommand> (void);
   
   
 }} // namespace lumiera::facade

src/proc/control/session-command-service.cpp

@@ -1,8 +1,8 @@
 /*
-  SessionCommandService  -  public service allowing to push information into the GUI
+  SessionCommandService  -  public service to invoke commands on the session
 
   Copyright (C)         Lumiera.org
-    2008,               Hermann Vosseler <Ichthyostega@web.de>
+    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
@@ -20,9 +20,9 @@
 
 * *****************************************************/
 
-/** @file notification-service.cpp
+/** @file session-command-service.cpp
- ** Implementation of notifications and updates within the GUI.
+ ** Implementation of command invocation on the Session interface.
- ** This is the actual service implementation and runs within the GUI plugin.
+ ** This is the actual service implementation and runs within Session subsystem.
  ** 
  */
 
@@ -40,25 +40,26 @@ extern "C" {
 
 
 
-namespace gui {
+namespace proc {
+namespace control {
   
   using std::string;
   using util::cStr;
 
   
   void 
-  NotificationService::displayInfo (string const& text)
+  SessionCommandService::displayInfo (string const& text)
   {
-    INFO (gui, "@GUI: display '%s' as notification message.", cStr(text));
+    INFO (gui, "@Session: display '%s' as notification message.", cStr(text));
-    ////////////////////////TODO actually push the information to the GUI
+    UNIMPLEMENTED ("do bla");  ////////////////////////TODO actually do something
   }
   
   
   void
-  NotificationService::triggerGuiShutdown (string const& cause)
+  SessionCommandService::triggerGuiShutdown (string const& cause)
   {
-    NOTICE (gui, "@GUI: shutdown triggered with explanation '%s'....", cStr(cause));
+    NOTICE (gui, "@Session: shutdown triggered with explanation '%s'....", cStr(cause));
-    TODO ("actually request a shutdown from the GUI");
+    UNIMPLEMENTED ("do blubb");  ////////////////////////TODO actually do something
   }
   
   
@@ -68,15 +69,15 @@ namespace gui {
     /* ================== define an lumieraorg_GuiNotification instance ======================= */
     
     LUMIERA_INTERFACE_INSTANCE (lumieraorg_interfacedescriptor, 0
-                               ,lumieraorg_GuiNotificationFacade_descriptor
+                               ,lumieraorg_SessionCommandFacade_descriptor
                                , NULL, NULL, NULL
                                , LUMIERA_INTERFACE_INLINE (name,
                                                            const char*, (LumieraInterface ifa),
-                                                             { (void)ifa;  return "GuiNotification"; }
+                                                             { (void)ifa;  return "SessionCommand"; }
                                                           )
                                , LUMIERA_INTERFACE_INLINE (brief,
                                                            const char*, (LumieraInterface ifa),
-                                                             { (void)ifa;  return "GUI Interface: push state update and notification of events into the GUI"; }
+                                                             { (void)ifa;  return "Session Interface: invoke pre-defined commands to operate on the session"; }
                                                           )
                                , LUMIERA_INTERFACE_INLINE (homepage,
                                                            const char*, (LumieraInterface ifa),
@@ -84,7 +85,7 @@ namespace gui {
                                                           )
                                , LUMIERA_INTERFACE_INLINE (version,
                                                            const char*, (LumieraInterface ifa),
-                                                             { (void)ifa;  return "0.1~pre"; }
+                                                             { (void)ifa;  return "0.3~pre"; }
                                                           )
                                , LUMIERA_INTERFACE_INLINE (author,
                                                            const char*, (LumieraInterface ifa),
@@ -100,7 +101,7 @@ namespace gui {
                                                                (void)ifa;
                                                                return
                                                                  "Copyright (C)        Lumiera.org\n"
-                                                                 "  2008               Hermann Vosseler <Ichthyostega@web.de>";
+                                                                 "  2016               Hermann Vosseler <Ichthyostega@web.de>";
                                                              }
                                                           )
                                , LUMIERA_INTERFACE_INLINE (license,
@@ -138,15 +139,15 @@ namespace gui {
     
     
     using lumiera::facade::LUMIERA_ERROR_FACADE_LIFECYCLE;
-    typedef lib::SingletonRef<GuiNotification>::Accessor InstanceRef;
+    typedef lib::SingletonRef<SessionCommand>::Accessor InstanceRef;
     
-    InstanceRef _instance; ///< a backdoor for the C Language impl to access the actual GuiNotification implementation...
+    InstanceRef _instance; ///< a backdoor for the C Language impl to access the actual SessionCommand implementation...
     
     
     
-    LUMIERA_INTERFACE_INSTANCE (lumieraorg_GuiNotification, 0
+    LUMIERA_INTERFACE_INSTANCE (lumieraorg_SessionCommand, 0
-                               ,lumieraorg_GuiNotificationService
+                               ,lumieraorg_SessionCommandService
-                               , LUMIERA_INTERFACE_REF(lumieraorg_interfacedescriptor, 0, lumieraorg_GuiNotificationFacade_descriptor)
+                               , LUMIERA_INTERFACE_REF(lumieraorg_interfacedescriptor, 0, lumieraorg_SessionCommandFacade_descriptor)
                                , NULL /* on  open  */
                                , NULL /* on  close */
                                , LUMIERA_INTERFACE_INLINE (displayInfo,
@@ -174,14 +175,14 @@ namespace gui {
   
   
   
-  NotificationService::NotificationService () 
+  SessionCommandService::SessionCommandService ()
     : implInstance_(this,_instance),
-      serviceInstance_( LUMIERA_INTERFACE_REF (lumieraorg_GuiNotification, 0,lumieraorg_GuiNotificationService))
+      serviceInstance_( LUMIERA_INTERFACE_REF (lumieraorg_SessionCommand, 0, lumieraorg_SessionCommandService))
   {
-    INFO (gui, "GuiNotification Facade opened.");
+    INFO (gui, "SessionCommand Facade opened.");
   }
   
   
   
   
-} // namespace gui
+}} // namespace proc::control

src/proc/control/session-command-service.hpp

@@ -1,8 +1,8 @@
 /*
-  SESSION-COMMAND-SERVICE.hpp  -  public service allowing to push information into the GUI
+  SESSION-COMMAND-SERVICE.hpp  -  public service to invoke commands on the session
 
   Copyright (C)         Lumiera.org
-    2008,               Hermann Vosseler <Ichthyostega@web.de>
+    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
@@ -20,17 +20,19 @@
 
 */
 
-/** @file notification-service.hpp
+/** @file session-command-service.hpp
- ** A public service provided by the GUI, implementing the gui::GuiNotification facade interface.
+ ** A public service offered by the Session, implementing the SessionCommand facade interface.
- ** The purpose of this service is to push state update and notification of events from the lower
+ ** This is the primary way to invoke commands and cause edit operations within the Session.
- ** layers into the Lumiera GUI. Typically, this happens asynchronously and triggered either by
+ ** Through this service, the user interface or other external entities may invoke pre defined
- ** events within the lower layers, or as result of invoking commands on the session.
+ ** commands and pass the appropriate arguments. Commands are small functions operating directly
+ ** on the Session interface; each command is complemented with a state capturing function and
+ ** an UNDO function.
  ** 
  ** This service is the implementation of a layer separation facade interface. Clients should use
- ** gui::GuiNotification#facade to access this service. This header defines the interface used
+ ** proc::control::GuiNotification#facade to access this service. This header defines the interface
- ** to \em provide this service, not to access it.
+ ** used to _provide_ this service, not to access it.
  **
- ** @see gui::GuiFacade
+ ** @see facade.hpp subsystems for the Proc-Layer
  ** @see guifacade.cpp starting this service 
  */
 
@@ -39,30 +41,30 @@
 #define PROC_CONTROL_SESSION_COMMAND_SERVICE_H
 
 
-#include "include/gui-notification-facade.h"
+#include "include/session-command-facade.h"
 #include "common/instancehandle.hpp"
 #include "lib/singleton-ref.hpp"
 
 
 
-namespace gui {
+namespace proc {
+namespace control {
   
   
   
-  /**************************************************//**
+  /***********************************************************//**
-   * Actual implementation of the GuiNotification service
+   * Actual implementation of the SessionCommand service
-   * within the Lumiera GTK GUI. Creating an instance of
+   * within the Lumiera Session subsystem. Creating an instance
-   * this class automatically registers the interface
+   * of this class automatically registers corresponding interface
-   * with the Lumiera Interface/Plugin system and creates
+   * with the Lumiera Interface/Plugin system and creates a forwarding
-   * a forwarding proxy within the application core to
+   * proxy within the application core to route calls through this interface.
-   * route calls through this interface.
    * 
    * @todo the ctor of this class should take references
    *       to any internal service providers within the
-   *       GUI which are needed to implement the service. 
+   *       Session which are needed to implement the service.
    */
-  class NotificationService
+  class SessionCommandService
-    : public GuiNotification
+    : public SessionCommand
     {
       
       /* === Implementation of the Facade Interface === */
@@ -73,19 +75,19 @@ namespace gui {
       
       /* === Interface Lifecycle === */
       
-      typedef lumiera::InstanceHandle< LUMIERA_INTERFACE_INAME(lumieraorg_GuiNotification, 0)
+      typedef lumiera::InstanceHandle< LUMIERA_INTERFACE_INAME(lumieraorg_SessionCommand, 0)
-                                     , GuiNotification
+                                     , SessionCommand
                                      > ServiceInstanceHandle;
       
-      lib::SingletonRef<GuiNotification> implInstance_;
+      lib::SingletonRef<SessionCommand> implInstance_;
       ServiceInstanceHandle serviceInstance_;
       
     public:
-      NotificationService();
+      SessionCommandService();
       
     };
     
   
   
-} // namespace gui
+}} // namespace proc::control
 #endif /*PROC_CONTROL_SESSION_COMMAND_SERVICE_H*/

src/proc/play/dummy-player-interface-proxy.hpp

@@ -92,7 +92,7 @@ namespace lumiera {
          *  since it complicated the definition of the facade proxy
          *  and created quite involved library dependency problems.
          */
-        Process start(LumieraDisplaySlot viewerHandle)
+        Process start(LumieraDisplaySlot viewerHandle)  override
           {
             ProcessImplementationLink* pP = static_cast<ProcessImplementationLink*> (_i_.startPlay (viewerHandle));