cleanup of BuilderTool includes

src/proc/mobject/builder/applicable-builder-target-types.hpp

@@ -20,29 +20,54 @@
  
 */
 
+/** @file applicable-builder-target-types.hpp
+ ** Declaration of all kinds of MObjects to be treated by some "Builder tool".
+ ** This is part of Lumiera's visitation mechanism: Individual MObject subclasses
+ ** may declare by the \c DEFINE_PROCESSABLE_BY macro to be specifically processable
+ ** by a builder tool (visitor). On the other hand, any concrete builder tool (visitor)
+ ** is free to define a \c treat(Type) function for each of these specific subclasses.
+ ** If the tool doesn't define such a specific \c treat(..) function, the next suitable
+ ** function for a supertype will be used.
+ ** 
+ ** Now there needs to be \em one location where all the specific kinds of treat-able
+ ** MObjects are declared together (in a typelist). Moreover, we need the full declaration
+ ** of these classes. This is the catch of using the visitor pattern. Thus, any class
+ ** to be treated \em specifically (as opposed to be just treated through a supertype
+ ** or super interface) has two liabilities:
+ ** - DEFINE_PROCESSABLE_BY
+ ** - declare the type here in this file, including the header.
+ ** 
+ ** @note actually the ApplicableBuilderTargetTypes template, when used (as a baseclass
+ **       of any concrete builder tool, causes the generation of the necessary
+ **       dispatcher tables used by our visitor implementation.
+ **       
+ ** @see buildertool.hpp
+ ** @see buildertooltest.hpp
+ ** @see nodecreatertool.hpp
+ */
+
+
 
 #ifndef MOBJECT_BUILDER_APPLICABLEBUILDERTARGETTYPES_H
 #define MOBJECT_BUILDER_APPLICABLEBUILDERTARGETTYPES_H
 
 #include "proc/mobject/builder/buildertool.hpp"
 
+// NOTE:  need to include *all* classes using DEFINE_PROCESSABLE_BY(BuilderTool)
+#include "proc/mobject/session/root.hpp"
+#include "proc/mobject/session/clip.hpp"
+#include "proc/mobject/session/effect.hpp"
+#include "proc/mobject/session/auto.hpp"
+
+                                        /////////////////////////////////TICKET #414
+
 
 
 namespace mobject {
-  namespace session {
+namespace builder {
   
-    class Clip;
+    typedef Types< session::Root, 
-    class Effect;
+                   session::Clip, 
-    class AbstractMO;
-    template<class VAL> class Auto;
-    // Forward declarations sufficient here...
-    // actual definitions necessary only in the
-    // implementation file (*cpp) of the builder tool.
-  }
-  
-  namespace builder {
-  
-    typedef Types< session::Clip, 
                    session::Effect,
                    session::AbstractMO
                  > ::List
@@ -65,7 +90,5 @@ namespace mobject {
     
     
     
-  } // namespace mobject::builder
+}} // namespace mobject::builder
-
-} // namespace mobject
 #endif

src/proc/mobject/builder/buildertool.hpp

@@ -28,22 +28,22 @@
  ** 
  ** As the objects to be treated are normally handled by smart-ptrs, BuilderTool provides
  ** a special facility for dealing with these wrapped objects. There are some liabilities.
- ** <ul><li>each concrete Buildable subtype to be treated specifically needs to
+ ** - each concrete Buildable subtype to be treated specifically needs to
- **         declare \c DEFINE_PROCESSABLE_BY(BuilderTool) </li>
+ **   declare \c DEFINE_PROCESSABLE_BY(BuilderTool)
- **     <li>at the same time, the concrete BuilderTool subclass has to declare
+ ** - at the same time, the concrete BuilderTool subclass has to declare
- **         being Applicable to this concrete Buildable subtype. The recommended way
+ **   being Applicable to this concrete Buildable subtype. The recommended way
- **         of ensuring this, is to add an entry to applicablebuildertargettypes.hpp
+ **   of ensuring this, is to add an entry to applicable-builder-target-types.hpp
- **         and then derive the concrete BuilderTool subclass from 
+ **   and then derive the concrete BuilderTool subclass from 
- **         ApplicableBuilderTargetTypes</li>
+ **   ApplicableBuilderTargetTypes
- **     <li>when accessing the wrapper from within a \c treat() function, a suitable
+ ** - when accessing the wrapper from within a \c treat() function, a suitable
- **         concrete wrapper type has to be specified. If the wrapper type used for
+ **   concrete wrapper type has to be specified. If the wrapper type used for
- **         invoking the BuilderTool (function \c apply(BuilderTool&l, WrappedObject&) )
+ **   invoking the BuilderTool (function \c apply(BuilderTool&l, WrappedObject&) )
- **         can not be converted to this type requested from within the call, an 
+ **   can not be converted to this type requested from within the call, an 
- **         assertion failure (or segmentation fault in a release build) will result.</li>
+ **   assertion failure (or segmentation fault in a release build) will result.
  ** </ul>   
  ** 
  ** @see visitor.hpp
- ** @see applicablebuildertargettypes.hpp
+ ** @see applicable-builder-target-types.hpp
  ** @see buildertooltest.hpp
  ** @see nodecreatertool.hpp
  */

src/proc/mobject/builder/nodecreatortool.cpp

@@ -22,9 +22,7 @@
 
 
 #include "proc/mobject/builder/nodecreatortool.hpp"
-#include "proc/mobject/session/clip.hpp"
+
-#include "proc/mobject/session/effect.hpp"
-#include "proc/mobject/session/auto.hpp"
 
 using mobject::Buildable;
 using mobject::session::Clip;
@@ -34,6 +32,10 @@ using mobject::session::Auto;
 namespace mobject {
   namespace builder {
 
+                                        /////////////////////////////////TICKET #414
+    
+    
+    ////TODO: do we ever get to treat a model root element??
     
     
     void
@@ -63,7 +65,7 @@ namespace mobject {
     void
     NodeCreatorTool::onUnknown (Buildable& target)
     {
-      UNIMPLEMENTED ("catch-all when partitioning timeline");  ////////TODO: verify why this gets enfoced here...
+      UNIMPLEMENTED ("catch-all when partitioning timeline");  ////////TODO: verify why this gets enforced here...
     }
 
 

src/proc/mobject/builder/nodecreatortool.hpp

@@ -25,7 +25,7 @@
 #define MOBJECT_BUILDER_NODECREATORTOOL_H
 
 
-#include "proc/mobject/builder/applicablebuildertargettypes.hpp"
+#include "proc/mobject/builder/applicable-builder-target-types.hpp"
 
 #include "proc/engine/rendergraph.hpp"
 
@@ -66,7 +66,7 @@ namespace builder {
       virtual void treat (mobject::session::Auto<double>& automation) ;  //TODO: the automation-type-problem
       virtual void treat (mobject::Buildable& something) ;
       
-      void onUnknown (Buildable& target) ;             /////////TODO why doesn't the treat(Buildable) function shaddow this??
+      void onUnknown (Buildable& target) ;             /////////TODO why doesn't the treat(Buildable) function shadow this??
     };
   
   

src/proc/mobject/builder/segmentationtool.cpp

@@ -22,9 +22,7 @@
 
 
 #include "proc/mobject/builder/segmentationtool.hpp"
-#include "proc/mobject/session/clip.hpp"
+
-#include "proc/mobject/session/effect.hpp"
-#include "proc/mobject/session/segment.hpp"
 
 using mobject::Buildable;
 using mobject::session::Clip;
@@ -34,6 +32,7 @@ using mobject::session::Effect;
 namespace mobject {
   namespace builder {
 
+                                        /////////////////////////////////TICKET #414
 
   
     SegmentationTool::SegmentationTool(mobject::session::Fixture&)

src/proc/mobject/builder/segmentationtool.hpp

@@ -25,7 +25,7 @@
 #define MOBJECT_BUILDER_SEGMENTATIONTOOL_H
 
 
-#include "proc/mobject/builder/applicablebuildertargettypes.hpp"
+#include "proc/mobject/builder/applicable-builder-target-types.hpp"
 
 #include "proc/mobject/session/segmentation.hpp"
 #include "proc/mobject/session/fixture.hpp"   //////TODO really on the header??
@@ -59,7 +59,7 @@ namespace mobject {
 
         void treat (mobject::Buildable& something) ;
         
-        void onUnknown (Buildable& target) ;             /////////TODO why doesn't the treat(Buildable) function shaddow this??
+        void onUnknown (Buildable& target) ;             /////////TODO why doesn't the treat(Buildable) function shadow this??
         
         bool empty()  const;