modules.h

   1 #ifndef MODULES_HEADER_
   2 #define MODULES_HEADER_
   3
   4 #include "util.h"
   5
   6 //      Forwards for all classes visible outside this header
   7 class Module;
   8 class ModuleFactory;
   9 template <class Iface> class Interface;
  10
  11
  12 /// \defgroup modules Module implementations
  13 /** A common base class for all modules */
  14 class Module {
  15         friend class ModuleFactory; ///< Permission for the ModuleFactory to manipulate Modules
  16 //      Type definitions
  17 public:
  18         /** Two types of cloning, used in ::clone */
  19         enum CloneMethod { ShallowCopy, DeepCopy };
  20         /** Types of a setting */
  21         enum ChoiceType {
  22                 Stop,           ///< a list-terminator
  23                 Int,            ///< integer from an interval
  24                 IntLog2,        ///< integer from an interval prefixed with 2^
  25                 Float,          ///< real number from an interval
  26                 ModuleCombo,///< a connection to another module (shown as a combo-box)
  27                 Combo           ///  choice from a list of strings
  28         };
  29         /** Represents one setting - one number, real or integer */
  30         union SettingValue {
  31                 int i;          ///< Setting value for integer/module types (see Module::ChoiceType)
  32                 float f;        ///< Setting value for real-number type (see Module::ChoiceType)
  33         };
  34         /** Represents the type of one module's setting - without label and description */
  35         struct SettingType {
  36                 ChoiceType type;                ///< The type of the item
  37                 SettingValue defaults;  ///< The default setting
  38
  39                 union {
  40                         int i[2];                       ///< Lower and upper bound (#type==Int,IntLog2)
  41                         float f[2];                     ///< Lower and upper bound (#type==Float)
  42                         const char *text;       ///< Lines of the combo-box (#type==Combo)
  43                         /** Pointer to the vector of IDs of compatible modules (#type==ModuleCombo),
  44                          *      meant to be one of Interface::getCompMods() */
  45                         const std::vector<int> *compatIDs;
  46                 } data;                         ///< Additional data, differs for different #type
  47         };
  48
  49         /** Represents the type of one setting - including label, description, etc.\ */
  50         struct SettingTypeItem {
  51                 static const SettingTypeItem stopper; ///< Predefined list terminator
  52
  53                 const char *label       ///  The text label of the setting
  54                 , *desc;                        ///< Description text
  55                 SettingType type;       ///< The type of this setting
  56         };
  57
  58         /** Represents one setting value in a module */
  59         struct SettingItem {
  60                 Module *m;      ///< Pointer to the connected module (if type is Module::ModuleCombo)
  61                 SettingValue val;       ///< The setting value
  62
  63                 /** Just nulls the module pointer */
  64                 SettingItem(): m(0) { DEBUG_ONLY( val.f= std::numeric_limits<float>::quiet_NaN(); ) }
  65
  66                 /** Creates a default settings-item for a settings-item-type */
  67                 SettingItem(const SettingTypeItem &typeItem): m(0), val(typeItem.type.defaults) {}
  68
  69                 /** Just deletes the module pointer */
  70                 ~SettingItem() { delete m; }
  71         };
  72
  73         /** Information about one module-type */
  74         struct TypeInfo {
  75                 int id;                                                 ///< The module-type's ID
  76                 const char *name                                ///  The module-type's name
  77                 , *desc;                                                ///< The module-type's description
  78                 int setLength;                                  ///< The number of setting items
  79                 const SettingTypeItem *setType; ///< The types of module's settings
  80         };
  81
  82 //      Data definitions
  83 protected:
  84         SettingItem *settings; ///< The current setting values of this Module
  85
  86 /** \name Construction, destruction and related methods
  87  *      @{      - all private, only to be used by ModuleFactory on module prototypes */
  88 private:
  89         /**     Creates a copy of module's settings (includes the whole module subtree) */
  90         SettingItem* copySettings(CloneMethod method) const;
  91         /** Called for prototypes to initialize the default links to other modules */
  92         void initDefaultModuleLinks();
  93         /** Called for prototypes to null links to other modules */
  94         void nullModuleLinks();
  95         /** Called for prototypes to create the settings and inicialize them with defaults */
  96         void createDefaultSettings();
  97
  98         /** Denial of assigment */
  99         Module& operator=(const Module&);
 100         /** Denial of copying */
 101         Module(const Module&);
 102 ///     @}
 103 protected:
 104         /**     Initializes an empty module */
 105         Module(): settings(0) {}
 106
 107         /** Cloning method, implemented in all modules via macros \return a new module
 108          *      \param method determines creation of a deep or a shallow copy (zeroed children) */
 109         virtual Module* abstractClone(CloneMethod method) const =0;
 110         /** Concrete cloning method - templated by the actual type of the module */
 111         template<class M> M* concreteClone(CloneMethod method) const;
 112
 113 public:
 114         /** Deletes the settings, destroying child modules as well */
 115         virtual ~Module()
 116                 { delete[] settings; }
 117
 118         /** Returns reference to module-type's information,
 119          *      like count and types of settings, etc.\ Implemented in all modules via macros */
 120         virtual const TypeInfo& info() const =0;
 121
 122         DECLARE_debugModule_empty
 123
 124 /**     \name Settings visualization and related methods
 125  *      @{      - common code for all modules, implemented in gui.cpp */
 126 public:
 127         /** Creates or updates settings-box and/or settings-tree.\
 128          *      if overridden in derived modules, it is recommended to call this one at first */
 129         virtual void adjustSettings( int which, QTreeWidgetItem *myTree, QGroupBox *setBox );
 130 protected:
 131         /** Reads a setting value from a widget */
 132         void widget2settings( const QWidget *widget, int which );
 133         /** Writes a setting value into a widget */
 134         void settings2widget( QWidget *widget, int which );
 135         /** Initializes a widget according to a setting-item type */
 136         void settingsType2widget( QWidget *widget, const SettingTypeItem &typeItem );
 137 ///     @}
 138
 139 //      Other methods
 140 protected:
 141         /** Saves all the settings, icluding child modules */
 142         void file_saveAllSettings(std::ostream &stream);
 143         /** Loads all the settings, icluding child modules (and their settings) */
 144         void file_loadAllSettings(std::istream &stream);
 145         /** Puts a module-identifier in a stream (\p which is the index in settings) */
 146         void file_saveModuleType( std::ostream &os, int which );
 147         /** Gets an module-identifier from the stream, initializes the pointer in settings
 148          *      with a new empty instance and does some checking (bounds,Iface) */
 149         void file_loadModuleType( std::istream &is, int which );
 150         /** A shortcut method for working with integer settings */
 151         int& settingsInt(int index)
 152                 { return settings[index].val.i; }
 153         int settingsInt(int index) const
 154                 { return settings[index].val.i; }
 155
 156 /**     \name SettingType construction methods
 157  *      @{      - to be used within DECLARE_TypeInfo macros when declaring modules */
 158         /** Creates a bounded integer setting, optionally shown as a power of two */
 159         static SettingType settingInt(int min,int defaults,int max,ChoiceType type=Int) {
 160                 ASSERT( type==Int || type==IntLog2 );
 161                 SettingType result;
 162                 result.type= type;
 163                 result.defaults.i= defaults;
 164                 result.data.i[0]= min;
 165                 result.data.i[1]= max;
 166                 return result;
 167         }
 168         /** Creates a bounded real-number setting */
 169         static SettingType settingFloat(float min,float defaults,float max) {
 170                 SettingType result;
 171                 result.type= Float;
 172                 result.defaults.f= defaults;
 173                 result.data.f[0]= min;
 174                 result.data.f[1]= max;
 175                 return result;
 176         }
 177         /** Creates a choose-one-of setting shown as a combo-box */
 178         static SettingType settingCombo(const char *text,int defaults) {
 179                 ASSERT( defaults>=0 && defaults<1+countEOLs(text) );
 180                 SettingType result;
 181                 result.type= Combo;
 182                 result.defaults.i= defaults;
 183                 result.data.text= text;
 184                 return result;
 185         }
 186         /** Creates a connection to another module (type specified as a template parameter).
 187          *      It will be shown as a combo-box and automatically filled by compatible modules.
 188          *      The default possibility can be specified */
 189         template<class Iface> static SettingType settingModule(int defaultID) {
 190                 const std::vector<int> &compMods= Iface::getCompMods();
 191                 int index=  find( compMods.begin(), compMods.end(), defaultID ) - compMods.begin();
 192                 ASSERT( index < (int)compMods.size() );
 193                 SettingType result;
 194                 result.type= ModuleCombo;
 195                 result.defaults.i= index;
 196                 result.data.compatIDs= &compMods;
 197                 return result;
 198         }
 199         /** A shortcut to set the first compatible module as the default one */
 200         template<class Iface> static SettingType settingModule() {
 201                 return settingModule<Iface>( Iface::getCompMods().front() );
 202         }
 203 ///     @}
 204 }; // Module class
 205
 206
 207 ////    Macros for easier Module-writing
 208
 209 #define DECLARE_TypeInfo_helper(CNAME_,NAME_,DESC_,SETTYPE_...) \
 210 /** \cond */ \
 211         friend class Module; /* Needed for concreteClone */ \
 212         /*friend class ModuleFactory;*/ \
 213         friend struct ModuleFactory::Creator<CNAME_>; /* Needed for GCC-3 and ICC */ \
 214 public: \
 215         CNAME_* abstractClone(CloneMethod method=DeepCopy) const \
 216                 { return concreteClone<CNAME_>(method); } \
 217  \
 218         const TypeInfo& info() const { \
 219                 static SettingTypeItem setType_[]= {SETTYPE_}; \
 220                 static TypeInfo info_= { \
 221                         id: ModuleFactory::getModuleID<CNAME_>(), \
 222                         name: NAME_, \
 223                         desc: DESC_, \
 224                         setLength: sizeof(setType_)/sizeof(*setType_)-1, \
 225                         setType: setType_ \
 226                 }; \
 227                 return info_; \
 228         } \
 229 /** \endcond */ \
 230
 231 /** Declares technical stuff within a Module descendant that contains no settings
 232  *      - parameters: the name of the class (Token),
 233  *      the name of the module ("Name"), some description ("Desc...") */
 234 #define DECLARE_TypeInfo_noSettings(CNAME_,NAME_,DESC_) \
 235         DECLARE_TypeInfo_helper(CNAME_,NAME_,DESC_,SettingTypeItem::stopper)
 236
 237 /** Like DECLARE_TypeInfo_noSettings, but for a module containing settings
 238  *      - additional parameter: an array of SettingTypeItem */
 239 #define DECLARE_TypeInfo(CNAME_,NAME_,DESC_,SETTYPE_...) \
 240         DECLARE_TypeInfo_helper(CNAME_,NAME_,DESC_,SETTYPE_,SettingTypeItem::stopper)
 241
 242
 243
 244 /** A singleton factory class for creating modules */
 245 class ModuleFactory {
 246         /** Static pointer to the only instance of the ModuleFactory */
 247         static ModuleFactory *instance;
 248         /** Pointers to the prototypes for every module type (indexed by their ID's) */
 249         std::vector<Module*> prototypes;
 250
 251         /** Private constructor to avoid uncontrolled instantiation */
 252         ModuleFactory() {}
 253         /** Deletes the prototypes */
 254         ~ModuleFactory() {
 255                 for_each( prototypes.begin(), prototypes.end(), std::mem_fun(&Module::nullModuleLinks) );
 256                 for_each( prototypes.begin(), prototypes.end(), SingleDeleter() );
 257         }
 258         /** The real constructing routine */
 259         void initialize();
 260
 261 public:
 262         /** Returns the ID of a module-type */
 263         template<class M> static int getModuleID();
 264
 265         /** Method to instantiate the singleton */
 266         static void init()
 267                 { ASSERT(!instance); (instance=new ModuleFactory)->initialize(); }
 268         /** Method to delete the singleton */
 269         static void destroy()
 270                 { delete instance; instance=0; }
 271
 272         /** Returns a reference to the module prototype with given id */
 273         static const Module& prototype(int id) {
 274                 ASSERT( instance && instance->prototypes.at(id) );
 275                 return *instance->prototypes[id];
 276         }
 277         /** Returns a new instance of the module-type with given id */
 278         static Module* newModule( int id, Module::CloneMethod method=Module::DeepCopy )
 279                 { return prototype(id).abstractClone(method); }
 280
 281         /** Sets appropriate prototype settings according to given module's settings */
 282         static void changeDefaultSettings(const Module &module);
 283
 284 #ifndef __ICC
 285 private:
 286 #endif
 287 //      some helper stuff
 288         template<class T> struct Creator {
 289                 T* operator()() const { return new T; }
 290         };
 291 private:
 292         template<class T> struct Instantiator {
 293                 int operator()() const;
 294         };
 295         /** Never called, only exists for certain templates to be instantiated in modules.cpp */
 296         static void instantiateModules();
 297 }; // ModuleFactory class
 298
 299
 300 /**     A base class for all interfaces, parametrized by the interface's type */
 301 template<class Iface> class Interface: public Module {
 302         static std::vector<int> compMods_; ///< IDs of modules derived from this interface
 303 public:
 304         /** Returns a reference to #compMods_ (initializes it if empty) */
 305         static const std::vector<int>& getCompMods();
 306         /** Returns a reference to the index-th prototype implementing this interface */
 307         static const Iface& compatiblePrototype(int index=0) {
 308                 ASSERT( index>=0 && index<(int)getCompMods().size() );
 309                 return *debugCast<const Iface*>(&ModuleFactory::prototype( getCompMods()[index] ));
 310         }
 311         /** Creates a new instance of the index-th compatible module (deep copy of the prototype) */
 312         static Iface* newCompatibleModule(int index=0)
 313                 { return compatiblePrototype(index).clone(); }
 314
 315         /** Works like abstractClone(), but is public and returns the correct type */
 316         Iface* clone(CloneMethod method=DeepCopy) const
 317                 { return debugCast<Iface*>( abstractClone(method) ); }
 318 };
 319
 320 #endif // MODULES_HEADER_