CmdAccess: rename the front-end to CmdContext to clarify the purpose

src/gui/interact/cmd-context.cpp

@@ -1,5 +1,5 @@
 /*
-  CmdAccessor  -  interface to access command invocation services within the UI
+  CmdContext  -  interface to access command context binding services within the UI
 
   Copyright (C)         Lumiera.org
     2017,               Hermann Vosseler <Ichthyostega@web.de>
@@ -21,8 +21,8 @@
 * *****************************************************/
 
 
-/** @file cmd-access.cpp
- ** Implementation details of command invocation services for the UI.
+/** @file cmd-context.cpp
+ ** Implementation details of support for context-bound commands.
  ** 
  ** @see TODO___cmd-access-test.cpp
  ** 
@@ -32,7 +32,7 @@
 //#include "lib/util.hpp"
 //#include "lib/symbol.hpp"
 //#include "include/logging.h"
-#include "gui/interact/cmd-access.hpp"
+#include "gui/interact/cmd-context.hpp"
 
 //#include <boost/noncopyable.hpp>
 //#include <string>
@@ -53,7 +53,7 @@ namespace interact {
   
   
   
-  CmdAccess::~CmdAccess() { }  // Emit dtors of embedded objects here...
+  CmdContext::~CmdContext() { }  // Emit dtors of embedded objects here...
   
   
   

src/gui/interact/cmd-context.hpp

@@ -1,5 +1,5 @@
 /*
-  CMD-ACCESSOR.hpp  -  interface to access command invocation services within the UI
+  CMD-CONTEXT.hpp  -  interface to access command context binding services within the UI
 
   Copyright (C)         Lumiera.org
     2017,               Hermann Vosseler <Ichthyostega@web.de>
@@ -21,13 +21,19 @@
 */
 
 
-/** @file cmd-access.hpp
- ** Abstraction: access to command invocation for UI-Elements.
- ** The interact::CmdAccess front-end is used by any UI element about to invoke and dispatch
- ** commands into the session via ProcDispatcher. To invoke a command, typically it is necessary
- ** to prepare a _command instance_ and to pick up and bind _command arguments._ This can be achieved
+/** @file cmd-context.hpp
+ ** Abstraction: support for binding command invocation into an UI context.
+ ** The interact::CmdContext front-end is used when commands need to be bound to a whole context
+ ** of UI elements rather than to a specific widget -- especially for picking up command arguments
+ ** from interaction state found within that context. To invoke a command, typically it is necessary
+ ** to prepare a _command instance_ and to pick up and bind _command arguments._ In most cases, this
+ ** can be done directly, using a fixed command-ID and locally known argument values. But in the
+ ** aforementioned special situation, we have to deal with ongoing user interactions, which might
+ ** span several widgets, where some interaction events just happen to make invocation of a specific
+ ** command viable. The prototypical example is when some element is dragged around, and, depending
+ ** on the vicinity, might cause quite different actions when dropped. Such behaviour can be achieved
  ** with the help of an intermediary, known as ["interaction state manager"](\ref InteractionState).
- ** Thus, the command accessor allows to discover a specific InteractionState instance, which
+ ** The command context accessor allows to discover a specific InteractionState instance, which
  ** - is responsible for the specific command to be invoked
  ** - can handle context information related to a specific _control system_ (e.g mouse, keyboard,
  **   hardware controller, pen)
@@ -37,14 +43,14 @@
  ** 
  ** @todo as of 3/2017 this is a early design draft and WIP-WIP-WIP
  ** 
- ** @see TODO___cmd-access-test.cpp
+ ** @see CmdContext_test
  ** @see ////TODO_test usage example
  ** 
  */
 
 
-#ifndef GUI_INTERACT_CMD_ACCESS_H
-#define GUI_INTERACT_CMD_ACCESS_H
+#ifndef GUI_INTERACT_CMD_CONTEXT_H
+#define GUI_INTERACT_CMD_CONTEXT_H
 
 
 #include "lib/error.hpp"
@@ -70,18 +76,18 @@ namespace interact {
    * Abstract foundation of UI state tracking components.
    * @todo write type comment...
    */
-  class CmdAccess
+  class CmdContext
     : boost::noncopyable
     {
       
     public:
-     ~CmdAccess();  ///< @todo do we need a VTable / virtual dtor?
+     ~CmdContext();  ///< @todo do we need a VTable / virtual dtor?
       
       /* === access front-end === */
       static Symbol to (Symbol cmdID, string ctxID);
       
-      friend CmdAccess&
-      cmdAccess (Symbol instanceID)
+      friend CmdContext&
+      cmdContext (Symbol instanceID)
       {
         UNIMPLEMENTED ("cmd access front-end");
       }
@@ -92,4 +98,4 @@ namespace interact {
   
   
 }} // namespace gui::interact
-#endif /*GUI_INTERACT_CMD_ACCESS_H*/
+#endif /*GUI_INTERACT_CMD_CONTEXT_H*/

src/proc/cmd.hpp

@@ -29,7 +29,6 @@
  ** 
  ** @see command.hpp
  ** @see command-def.hpp
- ** @see cmd-access.hpp
  ** @see TODO_CommandGuiUsage_test
  **
  */

src/proc/cmd/session-cmd.cpp

@@ -28,8 +28,8 @@
  ** @see cmd.hpp
  ** @see command.hpp
  ** @see command-def.hpp
- ** @see cmd-access.hpp
- ** @see TODO_CommandGuiUsage_test
+ ** @see cmd-context.hpp
+ ** @see SessionCommandFunction_test
  **
  */
 

src/proc/control/command-instance-manager.hpp

@@ -47,7 +47,7 @@
  ** @see command.hpp
  ** @see command-def.hpp
  ** @see command-setup.hpp
- ** @see cmd-access.hpp
+ ** @see session-command-service.hpp
  ** @see CommandInstanceManager_test
  **
  */

src/proc/control/command-setup.hpp

@@ -41,8 +41,9 @@
  ** 
  ** @see command-def.hpp
  ** @see command.hpp
- ** @see cmd-access.hpp
  ** @see CommandSetup_test
+ ** @see cmd.hpp
+ ** @see cmd-context.hpp
  **
  */
 

tests/gui/interact/cmd-context-test.cpp

@@ -1,5 +1,5 @@
 /*
-  CmdAccess(Test)  -  verify access to command invocation state
+  CmdContext(Test)  -  verify access to command invocation state
 
   Copyright (C)         Lumiera.org
     2017,               Hermann Vosseler <Ichthyostega@web.de>
@@ -20,14 +20,14 @@
 
 * *****************************************************/
 
-/** @file cmd-access-test.cpp
- ** unit test \ref CmdAccess_test
+/** @file cmd-context-test.cpp
+ ** unit test \ref CmdContext_test
  */
 
 
 #include "lib/test/run.hpp"
 //#include "lib/test/test-helper.hpp"
-#include "gui/interact/cmd-access.hpp"
+#include "gui/interact/cmd-context.hpp"
 //#include "lib/idi/entry-id.hpp"
 //#include "lib/diff/gen-node.hpp"
 //#include "lib/util.hpp"
@@ -49,26 +49,27 @@ namespace test {
 //  using lumiera::error::LUMIERA_ERROR_WRONG_TYPE;
   
   
-  /**************************************************************************//**
-   * @test verify the front-end to access commands, command argument binding
+  /******************************************************************************//**
+   * @test verify the front-end for context bound commands, command argument binding
    *       and invocation state from within the UI structures.
    * 
    * @see CmdAccess
    * @see CommandSetup_test
    * @see SessionCommandFunction_test
    */
-  class CmdAccess_test : public Test
+  class CmdContext_test : public Test
     {
       
       virtual void
       run (Arg)
         {
+          UNIMPLEMENTED ("context bound commands");
         }
     };
   
   
   /** Register this test class... */
-  LAUNCHER (CmdAccess_test, "unit gui");
+  LAUNCHER (CmdContext_test, "unit gui");
   
   
 }}} // namespace gui::interact::test

wiki/renderengine.html

@@ -2569,7 +2569,7 @@ In a typical editing application, the user can expect to get some visual clue re
 To start with, mostly this means to avoid a naive approach, like having code in the UI to pull in some graphics from media files. We certainly won't just render every media channel blindly. Rather, we acknowledge that we'll have a //strategy,// depending on the media content and some further parameters of the clip. This might well just be a single ''pivot image'' chosen explicitly by the editor to represent a given take. And the actual implementation of content preview rendering will largely be postponed until we get our rendering engine into a roughly working state.
 </pre>
 </div>
-<div title="GuiCommandAccess" creator="Ichthyostega" modifier="Ichthyostega" created="201704131649" modified="201704152147" tags="spec draft GuiPattern GuiIntegration" changecount="16">
+<div title="GuiCommandAccess" creator="Ichthyostega" modifier="Ichthyostega" created="201704131649" modified="201704171623" tags="spec draft GuiPattern GuiIntegration" changecount="18">
 <pre>//how to access proc layer commands from the UI and to talk to the command framework//
 
 !Command access DSL
@@ -2619,7 +2619,7 @@ The above design for command access looked as a good idea -- at first sight. Yet
 
 Another point of contention is the duality between a command access framework and the UI-Bus. It turns out this is rooted in a fundamental conflict. The command system and by extension also a command access framework represents the classic »command and control« style API (to use a term coined by Martin Fowler). This kind of interface shines when used on top of a shared data or object model. Which is exactly the kind of architecture we shun, on a global level. It is fine when //confined within some subsystem,// yet creates a corroding tendency towards high coupling, when used on a global scale. For this reason, we introduced a message driven connection, and for the same reason, we should refrain from using the command and control structure as a second channel, bypassing the bus. //This is entirely an architectural decision// -- on the level of tracing actual calls, any message based connection looks overengineered, when compared to &quot;just invoke the f**cking function&quot;
 
-The ''conclusions'' drawn from this critique is to forego using the InvocationTrail, in favour of a plain command ID, and to simplify and mostly automate the command instance management (&amp;rarr; CommandCycle)
+The ''conclusions'' drawn from this critique is to forego using the InvocationTrail, in favour of a plain command ID, and to simplify and automate the command instance management (&amp;rarr; GuiCommandCycle)
 </pre>
 </div>
 <div title="GuiCommandBinding" creator="Ichthyostega" modifier="Ichthyostega" created="201704140008" modified="201704140029" tags="design GuiPattern GuiIntegration discuss" changecount="8">
@@ -2674,7 +2674,7 @@ This contrastive approach attempts to keep knowledge and definition clustered in
 &amp;rarr; CommandSetup
 </pre>
 </div>
-<div title="GuiCommandCycle" creator="Ichthyostega" modifier="Ichthyostega" created="201703031817" modified="201704160028" tags="design operational GuiPattern GuiIntegration draft discuss img" changecount="60">
+<div title="GuiCommandCycle" creator="Ichthyostega" modifier="Ichthyostega" created="201703031817" modified="201704171730" tags="design operational GuiPattern GuiIntegration draft discuss img" changecount="61">
 <pre>//the process of issuing a session command from the UI//
 Within the Lumiera UI, we distinguish between core concerns and the //local mechanics of the UI.// The latter is addressed in the usual way, based on a variation of the [[MVC-Pattern|http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller]]. The UI toolkit set, here the GTK, affords ample ways to express actions and reactions within this framework, where widgets in the presentation view are wired with the corresponding controllers vice versa (GTK terms these connections as //&quot;signals&quot;//, we rely on {{{libSigC++}}} for implementation).
 A naive approach would extend these mature mechanisms to also cover the actual functionality of the application. This compelling solution allows quickly to get &quot;something tangible&quot; up and running, yet -- on the long run -- inevitably leads to core concerns being tangled into the presentation layer, which in turn becomes hard to maintain and loaded with &quot;code behind&quot;. Since we are here &quot;for the long run&quot;, we immediately draw the distinction between UI mechanics and core concerns. The latter are, by decree and axiom, required to perform without even an UI layer running. This decision gives rise to the challenge how to form and integrate the invocation of ''core commands'' into the presentation layer.
@@ -2714,11 +2714,11 @@ from these use cases, we can derive the //crucial activities for command handlin
 *;context bound
 *:invocation of a command is formed within a context, typically through a //interaction gesture.//
 *:most, if not all arguments of the command are picked up from the context, based on the current [[Spot]]
-*:* on setup of such an invocation context, the responsible part in the UI queries the {{{CmdAccess}}} for an InteractionState
+*:* on setup of such an invocation context, the responsible part in the UI queries the {{{CmdContext}}} for an InteractionState
 *:* the latter in turn retrieves a new command instance ID from the {{{CmdInstanceManager}}} in Proc
 *:* and the latter keeps a smart-ptr corresponding to this instance in its internal registration table
 *:* within the UI, the InteractionState instance responsible for this context tracks state changes and keeps track of all command instances bound to this context
-*:* ~UI-Elements use the services of {{{CmdAccess}}} to act as observer of state changes &amp;rarr; GuiCommandAccess
+*:* ~UI-Elements use the services of {{{CmdContext}}} to act as observer of state changes &amp;rarr; GuiCommandAccess
 *:* when a command is completely parametrised, it can be invoked. The managing {{{InteractionState}}} knows about this
 *:* on invocation, the ID of the instance and the fully resolved arguments are sent via UI-Bus to the {{{CmdInstanceManager}}}
 *:* which in turn removes the instance handle from its registration table and hands it over into the ProcDispatcher