1 #ifndef MODULES_HEADER_
2 #define MODULES_HEADER_
6 // Forwards for all classes visible outside this header
9 template <class Iface
> class Interface
;
12 /// \defgroup modules Module implementations
13 /** A common base class for all modules */
15 friend class ModuleFactory
; ///< Permission for the ModuleFactory to manipulate Modules
18 /** Two types of cloning, used in ::clone */
19 enum CloneMethod
{ ShallowCopy
, DeepCopy
};
20 /** Types of a setting */
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
29 /** Represents one setting - one number, real or integer */
31 int i
; ///< Setting value for integer/module types (see Module::ChoiceType)
32 float f
; ///< Setting value for real-number type (see Module::ChoiceType)
34 /** Represents the type of one module's setting - without label and description */
36 ChoiceType type
; ///< The type of the item
37 SettingValue defaults
; ///< The default setting
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
49 /** Represents the type of one setting - including label, description, etc.\ */
50 struct SettingTypeItem
{
51 static const SettingTypeItem stopper
; ///< Predefined list terminator
53 const char *label
/// The text label of the setting
54 , *desc
; ///< Description text
55 SettingType type
; ///< The type of this setting
58 /** Represents one setting value in a module */
60 Module
*m
; ///< Pointer to the connected module (if type is Module::ModuleCombo)
61 SettingValue val
; ///< The setting value
63 /** Just nulls the module pointer */
64 SettingItem(): m(0) { DEBUG_ONLY( val
.f
= std::numeric_limits
<float>::quiet_NaN(); ) }
66 /** Creates a default settings-item for a settings-item-type */
67 SettingItem(const SettingTypeItem
&typeItem
): m(0), val(typeItem
.type
.defaults
) {}
69 /** Just deletes the module pointer */
70 ~SettingItem() { delete m
; }
73 /** Information about one module-type */
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
84 SettingItem
*settings
; ///< The current setting values of this Module
86 /** \name Construction, destruction and related methods
87 * @{ - all private, only to be used by ModuleFactory on module prototypes */
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();
98 /** Denial of assigment */
99 Module
& operator=(const Module
&);
100 /** Denial of copying */
101 Module(const Module
&);
104 /** Initializes an empty module */
105 Module(): settings(0) {}
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;
114 /** Deletes the settings, destroying child modules as well */
116 { delete[] settings
; }
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;
122 DECLARE_debugModule_empty
124 /** \name Settings visualization and related methods
125 * @{ - common code for all modules, implemented in gui.cpp */
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
);
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
);
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
; }
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
);
163 result
.defaults
.i
= defaults
;
164 result
.data
.i
[0]= min
;
165 result
.data
.i
[1]= max
;
168 /** Creates a bounded real-number setting */
169 static SettingType
settingFloat(float min
,float defaults
,float max
) {
172 result
.defaults
.f
= defaults
;
173 result
.data
.f
[0]= min
;
174 result
.data
.f
[1]= max
;
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
) );
182 result
.defaults
.i
= defaults
;
183 result
.data
.text
= text
;
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() );
194 result
.type
= ModuleCombo
;
195 result
.defaults
.i
= index
;
196 result
.data
.compatIDs
= &compMods
;
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() );
207 //// Macros for easier Module-writing
209 #define DECLARE_TypeInfo_helper(CNAME_,NAME_,DESC_,SETTYPE_...) \
211 friend class Module; /* Needed for concreteClone */ \
212 /*friend class ModuleFactory;*/ \
213 friend struct ModuleFactory::Creator<CNAME_>; /* Needed for GCC-3 and ICC */ \
215 CNAME_* abstractClone(CloneMethod method=DeepCopy) const \
216 { return concreteClone<CNAME_>(method); } \
218 const TypeInfo& info() const { \
219 static SettingTypeItem setType_[]= {SETTYPE_}; \
220 static TypeInfo info_= { \
221 id: ModuleFactory::getModuleID<CNAME_>(), \
224 setLength: sizeof(setType_)/sizeof(*setType_)-1, \
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)
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)
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
;
251 /** Private constructor to avoid uncontrolled instantiation */
253 /** Deletes the prototypes */
255 for_each( prototypes
.begin(), prototypes
.end(), std::mem_fun(&Module::nullModuleLinks
) );
256 for_each( prototypes
.begin(), prototypes
.end(), SingleDeleter() );
258 /** The real constructing routine */
262 /** Returns the ID of a module-type */
263 template<class M
> static int getModuleID();
265 /** Method to instantiate the singleton */
267 { ASSERT(!instance
); (instance
=new ModuleFactory
)->initialize(); }
268 /** Method to delete the singleton */
269 static void destroy()
270 { delete instance
; instance
=0; }
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
];
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
); }
281 /** Sets appropriate prototype settings according to given module's settings */
282 static void changeDefaultSettings(const Module
&module
);
288 template<class T
> struct Creator
{
289 T
* operator()() const { return new T
; }
292 template<class T
> struct Instantiator
{
293 int operator()() const;
295 /** Never called, only exists for certain templates to be instantiated in modules.cpp */
296 static void instantiateModules();
297 }; // ModuleFactory class
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
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
] ));
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(); }
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
) ); }
320 #endif // MODULES_HEADER_