LUMIERA.clone/src/proc/mobject/session/defsmanager.hpp

/*
  DEFSMANAGER.hpp  -  access to preconfigured default objects and definitions

  Copyright (C)         Lumiera.org
    2008,               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.

*/


#ifndef MOBJECT_SESSION_DEFSMANAGER_H
#define MOBJECT_SESSION_DEFSMANAGER_H


#include "lib/p.hpp"
#include "lib/query.hpp"

#include <boost/scoped_ptr.hpp>
#include <boost/noncopyable.hpp>



namespace mobject {
  namespace session {
    
    
    using lumiera::P;
    using boost::scoped_ptr;
    
    namespace impl { class DefsRegistry; }


    /**
     * Organise a collection of preconfigured default objects.
     * For various kinds of objects we can tweak the default parametrisation
     * as part of the general session configuration. A ref to an instance of
     * this class is accessible through the current session and can be used
     * to fill in parts of the configuration of new objects, if the user 
     * code didn't give more specific parameters. Necessary sub-objects 
     * will be created on demand, and any default configuration, once
     * found, will be remembered and stored with the current session.
     * 
     * @note while the logic of defaults handling can be considered
     *       roughly final, as of 12/09 most of the actual object
     *       handling is placeholder code.
     */
    class DefsManager : private boost::noncopyable
      {
        scoped_ptr<impl::DefsRegistry> defsRegistry;
        
      public:
        
        DefsManager ()  throw();
       ~DefsManager ();
       
        /** common access point: retrieve the default object fulfilling
         *  some given conditions. May silently trigger object creation.
         *  @throw error::Config in case no solution is possible, which
         *         is considered \e misconfiguration. 
         */
        template<class TAR>
        P<TAR> operator() (lumiera::Query<TAR> const&);
        
        
        /** search through the registered defaults, never create anything.
         *  @return object fulfilling the query, \c empty ptr if not found. 
         */
        template<class TAR>
        P<TAR> search  (lumiera::Query<TAR> const&);
        
        /** retrieve an object fulfilling the query and register it as default.
         *  The resolution is delegated to the ConfigQuery system (which may cause
         *  creation of new object instances) 
         *  @return object fulfilling the query, \c empty ptr if no solution.
         */ 
        template<class TAR>
        P<TAR> create  (lumiera::Query<TAR> const&);
        
        /** register the given object as default, after ensuring it fulfils the
         *  query. The latter may cause some properties of the object to be set,
         *  trigger creation of additional objects, and may fail altogether.
         *  @return true if query was successful and object is registered as default
         *  @note only a weak ref to the object is stored
         */ 
        template<class TAR>
        bool define  (P<TAR> const&, lumiera::Query<TAR> const&  =lumiera::Query<TAR>());
        
        /** remove the defaults registration of the given object, if there was such
         *  @return false if nothing has been changed because the object wasn't registered
         */
        template<class TAR>
        bool forget  (P<TAR> const&);
        
        
// Q: can we have something along the line of...?
//
//        template
//          < class TAR,                   ///< the target to query for 
//            template <class> class SMP  ///<  smart pointer class to wrap the result
//          >
//        SMP<TAR> operator() (const lumiera::Query<TAR>&);

// 12/09: according to my current knowledge of template metaprogramming, the answer is "no",
//        but we could use a traits template to set up a fixed association of smart pointers
//        and kinds of target object. This would allow to define a templated operator() returning
//        the result wrapped into the right holder. But currently I don't see how to build a sensible
//        implementation infrastructure backing such an interface.
//////////TICKET #452
        
      };

      

  } // namespace mobject::session

} // namespace mobject
#endif