The class containing configuration parameters. More...

Public Member Functions

 ConfigurationParameters (bool caseSensitive=false)
 Constructor. More...
 
 ConfigurationParameters (const ConfigurationParameters &other)
 Copy constructor. More...
 
 ~ConfigurationParameters ()
 Destructor. More...
 
void addObserver (FactoryObserver *observer)
 Add a new observer. More...
 
void clearAll ()
 Delete all parameters in all groups and subgroups. More...
 
bool copyGroupTree (QString sourceGroup, QString destGroup)
 Copy a group tree to another location. More...
 
void createGroup (QString groupPath)
 Create a group in the path specified. More...
 
void createParameter (QString groupPath, QString parameter)
 Create a parameter in the group path specified. More...
 
void createParameter (QString groupPath, QString parameter, QString value)
 Create a parameter in the group path specified and set its value. More...
 
void createParameter (QString groupPath, QString parameter, ParameterSettable *object)
 Create a parameter in the group path specified and set its value to point to an object. More...
 
QString createSubGroup (QString parentPath, QString groupName)
 Create a sub-group of parent group specified. More...
 
bool deleteGroup (QString groupPath)
 Delete the last group in the path specified. More...
 
void deleteParameter (QString groupPath, QString parameter)
 Delete a parameter in the group path specified. More...
 
QStringList getFilteredGroupsList (QString group, QRegExp filter) const
 Returns the list of sub-groups in the given group whose name matches the given regular expression. More...
 
QStringList getFilteredParametersList (QString group, QRegExp filter) const
 Returns the list of parameters in the given group whose name matches the given regular expression. More...
 
QStringList getGroupsList (QString group) const
 Returns the list of sub-groups in the given group. More...
 
QStringList getGroupsWithPrefixList (QString group, QString prefix) const
 Returns the list of sub-groups in the given group whose name starts with the provided string. More...
 
template<class TypeToCreate >
TypeToCreate * getObjectFromGroup (QString group, bool configure=true, bool forceObjectCreation=false)
 Returns the object for the given group, creating it if it doesn't exist. More...
 
template<class TypeToCreate >
TypeToCreate * getObjectFromParameter (QString param, bool alsoMatchParents=false, bool configure=true, bool forceObjectCreation=false)
 Returns the object for the given parameter, creating it if it doesn't exist. More...
 
QStringList getParametersList (QString group) const
 Returns the list of parameters in the given group. More...
 
QStringList getParametersWithPrefixList (QString group, QString prefix) const
 Returns the list of parameters in the given group whose name starts with the provided string. More...
 
SimpleResourcesUsergetResourcesUserForResource (QString resourceName)
 Returns the resouce user holding the resource with the given name. More...
 
QString getValue (QString path, bool alsoMatchParents=false) const
 Returns a parameter value. More...
 
bool isCaseSensitive () const
 Returns true if we are case sensistive, false otherwise. More...
 
bool loadParameters (QString filename, bool keepOld=false, QString format="")
 Loads a configuration file. More...
 
ConfigurationParametersoperator= (const ConfigurationParameters &other)
 Assignment operator. More...
 
bool renameGroup (QString oldGroupPath, QString newGroupName)
 Rename the last group in the path specified with the new name. More...
 
void resetGroupObjectAssociations ()
 Resets all associations between groups and objects. More...
 
bool saveParameters (QString filename, QString format="", bool append=false)
 Saves a configuration file. More...
 
void setResourcesUser (ResourcesUser *resourcesUser)
 Registers a new resource user. More...
 
bool setValue (QString path, QString value)
 Sets the value of the parameter with the given path. More...
 
bool setValue (QString path, ParameterSettable *object)
 Sets the value of the parameter with the given path to point to an object. More...
 
void shareObserversWith (ConfigurationParameters &params)
 share the FactoryObservers with an another ConfigurationParameters More...
 
bool startObjectParameters (QString groupPath, QString typeName, ParameterSettable *object)
 Initializes a group so that it corresponds to the given object. More...
 
void startRememberingGroupObjectAssociations ()
 Starts remembering associations between groups and objects. More...
 
void stopRememberingGroupObjectAssociations ()
 Stops remembering associations between groups and objects. More...
 
void updateObjectReferences ()
 Updates all object references to point to actual groups. More...
 

Static Public Member Functions

static QString GroupSeparator ()
 The character used to split path in groups. More...
 
static QString ParentGroup ()
 The sequence used to indicate the parent group. More...
 
static bool registerFileFormat (QString format, ParametersFileLoaderSaver *fileLoaderSaver, QString defaultExtension)
 The function to register file formats to use when loading or saving parameters from/to file. More...
 

Friends

template<class T , bool ConfigureInConstructor>
class ParameterSettableCreatorT
 ParameterSettableCreatorT is friend to be able to call the setObjectFromGroupStatusTo* functions. More...
 
class RealFactory
 RealFactory is friend to be able to call the to access some member data and functions. More...
 

Detailed Description

The class containing configuration parameters.

Parameters have a tree-like organization. They are divided into groups which can have sub-groups. The main group (the one containing all the others) can be referenced using "" (i.e. the empty string). Moreover values are always string (classes using configuration parameters are responsible of converting to the actual type - one exception is object reference, see below). You can specify in the constructor whether you want property names and group names to be case sensitive or case insensitive.

The special character '/' is used to divide groups and subgroups names into path specifications. For example, "group1/subgroupA/paramName" specify a paramName contained into subgroupA of group1. Methods like getValue, setValue, createGroup require a full path. You are not allowed to use '/' into a name of parameter or group because it can generate confusion and unexpected results in parsing groups and parameters path. Another special sequence is "..". When used as the name of a group means "the parent group" (just like in filesystems ".." denotes the parent directory). For example, "group1/subgroupA/../paramName" indicates that paramName is inside group1: more explicitly it says that paramName is inside the parent group of subgroupA, that is group1. The parent group of the main group is the main group itself, so, for example, "group1/../../../../paramName" indicates that paramName is in the main group.

This class has also support for object creation and references between objects. Suppose you have two objects A and B which are subclasses of ParameterSettable and can then be created and configured using the factory (note that the Factory class is only used to register types and meta-type information, the class doing the actual object creation is RealFactory that is only used inside ConfigurationParameters). Suppose also that A needs a reference to object B and both are created using the factory from configuration parameters. It is possible for A to request a ConfigurationParameters object to return a reference to the B object (creating it if it hasn't been already). In this case both object A and B would correspond to groups in the ConfigurationParameters tree: referring to one object simply means indicating the path to the corresponding group. To get a reference to one object use the getObjectFromParameter() function. So, for example, suppose you have the following configuration file:

[somePrefix/A]
type = typeA
param1 = value1
param2 = value2
anObjectINeed = someOtherPrefix/B
[someOtherPrefix/B]
type = typeB
param1 = value1

The configure() function of object A could look like this:

void configure(const ConfigurationParameters& params, QString prefix)
{
// ... Read other parameters ...
m_otherObj = params.getObjectFromParameter<typeB>(prefix + "anObjectINeed", false, true);
// ... Do other stuffs ...
}

In this situation during the call to getObjectFromParameter() the somePrefix/A/anObjectINeed parameter is read and its value is used to get to the someOtherPrefix/B group; if an object has already been created using this group, its instance is returned, otherwise a new object is created and returned. To be able to do this we need to keep an association between a group in the configuration tree and the last object created from that group. Each time an object is created using the factory (functions of this class like getObjectFromParameter() and getObjectFromGroup() use the factory), an association is created between the new object and the group from which it is configured. If afterwards an object for the same group is requested using functions of this class, the previously created instance is returned instead of creating a new one. If however the factory is used directly to create an object, the association with the previous object is ignored and a new one is created.

When saving parameters, if you want a parameter to refer to another object, use the setValue() function taking as a second parameter a pointer to a ParameterSettable object. The other object is then expected to call the startObjectParameters() function in its save() function so that an association between the object and a group can be created (this function also sets the "type" parameter for the object). The actual path of the object is substituted to the pointer before saving the ConfigurationParameters object to file.

The getObjectFromParameter() function has a boolean parameter to specify whether a fully configured object is required or not. If the parameter is true, the returned object is guaranteed to be configured, otherwise it could be returned before the configuration step has been performed (depending on the type of object). When a non-configured object is returned, it is actually configured after the one who requested it has ended configuring itself. The possibility to request non-configured objects is useful in case of cyclic dependencies among objects. If ObjectA needs a pointer to ObjectB and vice-versa, it is not possible for both of them to have a pointer to a fully configured object during their configuration phase (because this would lead to an infinite loop). In this case one (or both) of them has to content with a pointer to a non-configured object (in this case there is no loop). If a loop is generated when configuring one object, an exception is thrown and object creation is aborted.

The ParameterSettable class also has a postConfigureInitialization() virtual function. This function is called after all objects deriving from the creation of one object have been created and configured. In the example above (an object A requesting the creation of another object B), the postConfigureInitialization() would be called after both A and B have been created and configured. To be more precise, that function is called just before returning from the most external call to RealFactory::create() function or ConfigurationParameters::getObjectFromGroup() function (whichever is the outermost, we can have ConfigurationParameters::getObjectFromGroup() calling RealFactory::create() or vice-versa) on all objects created by that call or by nested calls. The order in which the objects are called is not specified. Also note that the function is only called on configured objects: if you ask the factory to create on object but not to configure it, the postConfigureInitialization() is not called on that object (it is called on objects created by nested calls to factory functions, though). For more information on this issue see the RealFactory::create() function documentation.

The getObjectFromGroup() function is similar to getObjectFromParameter() but insted of taking a path to a parameter from which a group is read, takes a path to a group directly. It also allows creating non-configured objects.

A ConfigurationParameters object can also have one or more associated SimpleResourcesUser objects. To obtain a pointer to the SimpleResourcesUser which contains a certain resource use the function getResourcesUserForResource(). This function returns a pointer to a SimpleResourcesUser object that contains the requested resource or NULL if the resource is not present in any resource user. The search for the resource among all installed SimpleResourcesUser objects is performed from the SimpleResourcesUser object registered last to the first one. SimpleResourcesUser objects are removed when exiting from the call that registered them. To register a resource user use the setResourcesUser() function. This function takes a pointer to a ResourcesUser instance and creates internally a SimpleResourcesUser object that shares resources with the ResourcesUser object. An example should clarify the whole process. Suppose you have the following dependencies among objects (an arrow means creation, so, for example, A -> B means "A creates B"):

A ---> B ---> C ---> D
|
+----> E

Here we suppose that each object creates other objects using the getObjectFromGroup() function or similar ones (as described above). Also suppose for the moment that there is no circular dependency, so objects are always created and configured at the same time (the case of circular dependencies is discussed below). Now suppose you have the following sequence of actions:

  • A gets created and configured
    • during configuration, A sets a resource user RA
    • then A creates and configures B
      • during configuration, B creates and configures C
        • during configuration, C sets a resource user RC
        • then C creates and configures D
          • the configuration function of D is executed
        • C finishes its configuration phase
      • now B creates and configures E
        • the configuration function of E is executed
      • B finishes its configuration phase
    • A finishes its configuration phase

In this situation two SimpleResourcesUser objects are registered: one during the configuration phase of A (named RA), the other during the configuration phase of C (named RC). Here is the list of objects and which resource user they can access with the getResourcesUserForResource() function:

  • A can only access RA (after it has registered it)
  • B can only access RA
  • C can access both RA and RC (after it has registered RC)
  • D can access both RA and RC
  • E can only access RA

As you can see E can only access the SimpleResourcesUser object registered by A even though it is created and configured after C (which registers another SimpleResourcesUser object). This happends because the SimpleResourcesUser object RC is removed after C has finished its configuration phase. When the D object calls the getResourcesUserForResource() function the resource is first searched in RC (which has been registered last), then, if not found, in RA. Note that each object can only register one SimpleResourcesUser object. A subsequent call to setResourcesUser() replaces the previously registered SimpleResourcesUser object.

If two objects have a circular dependency, so that each one requests the other non-configured (as described above), things get more complicated. Suppose you have two objects A and B which have a mutual dependency. Also suppose that A, during its configuration phase, first registers a SimpleResourcesUser object RA and then requests the creation of B. In turn, B, during configuration, first registers a SimpleResourcesUser RB and then requestes the creation of A. Which SimpleResourcesUser object is visible to which class is a matter of who gets created first, making things ambigous. You should try to avoid situations like these because they can lead to subtle bugs.

Warning
This class it NOT thread-safe. We also use SimpleResourcesUser which is not thread safe.
Try to be consistent with regard to case: if you load parameters in a case insensitive ConfigurationParameters object and then save them, case for groups and properties names could be changed
If you have classes that are derived from ParameterSettable, use ALWAYS functions of this class to create and configure them. In particular NEVER call configure() or postConfigureInitialization() explicitly, otherwise you could experience strange problems
Todo:
For the moment when associating an object to a parameter we need a non-const pointer. Perhaps we should allow using const pointers in this case...

Definition at line 259 of file configurationparameters.h.

Constructor & Destructor Documentation

ConfigurationParameters ( bool  caseSensitive = false)

Constructor.

Parameters
caseSensitiveif true parameters and groups names are considered as being case sensitive, otherwise case insensitive

Definition at line 70 of file configurationparameters.cpp.

Copy constructor.

This copies all parameters and groups from other, but no object association (so this can be safely called inside configure functions). This also doesn't copy any resource manager association

Parameters
otherthe ConfigurationParameters object to copy

Definition at line 80 of file configurationparameters.cpp.

Destructor.

Definition at line 114 of file configurationparameters.cpp.

Member Function Documentation

void addObserver ( FactoryObserver observer)

Add a new observer.

Parameters
observeris the object acting as FactoryObserver on this object internal factory

Definition at line 424 of file configurationparameters.cpp.

void clearAll ( )

Delete all parameters in all groups and subgroups.

Definition at line 124 of file configurationparameters.cpp.

Referenced by ParametersFileLoaderSaver::load().

bool copyGroupTree ( QString  sourceGroup,
QString  destGroup 
)

Copy a group tree to another location.

Suppose you have the following configuration file (in INI format):

[GROUP_A]
param1 = value1
[GROUP_A/GROUP_B]
param2 = value2

When this methos is called in the following way:

params.copyGroupTree( "GROUP_A", "GROUP_C" );

The results are (in INI format):

[GROUP_A]
param1 = value1
[GROUP_A/GROUP_B]
param2 = value2
[GROUP_C]
param1 = value1
[GROUP_C/GROUP_B]
param2 = value2

The GROUP_B has been renamed to B_GROUP and all others remain untouched.

Parameters
sourceGroupthe full group path to copy
destGroupthe full group path where to copy

Definition at line 177 of file configurationparameters.cpp.

References ConfigurationParameters::createGroup(), and ConfigurationNode::isNull().

void createParameter ( QString  groupPath,
QString  parameter 
)

Create a parameter in the group path specified.

Parameters
groupPathis the full group path where to add the new parameter
parameterthe name of the parameter
Warning
It doesn't automatically create groups

Definition at line 192 of file configurationparameters.cpp.

References ConfigurationNode::addParameter(), and ConfigurationNode::isNull().

Referenced by ParameterSettable::BoolDescriptor::BoolDescriptor(), ParameterSettable::StringDescriptor::def(), ParameterSettable::IntDescriptor::def(), ParameterSettable::RealDescriptor::def(), ParameterSettable::BoolDescriptor::def(), ParameterSettable::EnumDescriptor::def(), ParameterSettable::Descriptor::Descriptor(), ParameterSettable::EnumDescriptor::EnumDescriptor(), ParameterSettable::StringDescriptor::help(), ParameterSettable::IntDescriptor::help(), ParameterSettable::RealDescriptor::help(), ParameterSettable::BoolDescriptor::help(), ParameterSettable::EnumDescriptor::help(), ParameterSettable::ObjectDescriptor::help(), ParameterSettable::SubgroupDescriptor::help(), ParameterSettable::IntDescriptor::IntDescriptor(), ParameterSettable::IntDescriptor::limits(), ParameterSettable::RealDescriptor::limits(), ParameterSettable::ObjectDescriptor::ObjectDescriptor(), ParameterSettable::RealDescriptor::RealDescriptor(), ConfigurationParameters::startObjectParameters(), ParameterSettable::StringDescriptor::StringDescriptor(), ParameterSettable::ObjectDescriptor::type(), ParameterSettable::SubgroupDescriptor::type(), and ParameterSettable::EnumDescriptor::values().

void createParameter ( QString  groupPath,
QString  parameter,
QString  value 
)
inline

Create a parameter in the group path specified and set its value.

Parameters
groupPathis the full group path where to add the new parameter
parameterthe name of the parameter
valuethe value of parameter
Warning
It doesn't automatically create groups

Definition at line 647 of file configurationparameters.h.

void createParameter ( QString  groupPath,
QString  parameter,
ParameterSettable object 
)
inline

Create a parameter in the group path specified and set its value to point to an object.

Parameters
groupPathis the full group path where to add the new parameter
parameterthe name of the parameter
objectthe object to which the parameter refer
Warning
It doesn't automatically create groups

Definition at line 663 of file configurationparameters.h.

QString createSubGroup ( QString  parentPath,
QString  groupName 
)
inline

Create a sub-group of parent group specified.

Parameters
parentPaththe full path of the parent group on which the sub-group will be added
groupNamethe name of the sub-group
Returns
the full path of the sub-group created
Note
If the group already exists it will do nothing

Definition at line 621 of file configurationparameters.h.

bool deleteGroup ( QString  groupPath)

Delete the last group in the path specified.

Suppose you have the following configuration file (in INI format):

[GROUP_A]
param1 = value1
[GROUP_A/GROUP_B]
param2 = value2
[GROUP_A/GROUP_B/GROUP_C]
param3 = value3

When this methos is called in the following way:

params.deleteGroup( "GROUP_A/GROUP_B" );

The results are (in INI format):

[GROUP_A]
param1 = value1

The GROUP_B and all its parameters and subgroups has been removed from the ConfigurationParameters, while the GROUP_A remains untouched

Parameters
groupPaththe full group path to delete from ConfigurationParameters
Note
deleteGroup( "" ), deleteGroup( "/" ) or deleteGroup( ".." ) have no effects; If you want to remove all groups see clearAll()

Definition at line 159 of file configurationparameters.cpp.

References ConfigurationParameters::GroupSeparator().

void deleteParameter ( QString  groupPath,
QString  parameter 
)

Delete a parameter in the group path specified.

Parameters
groupPathis the full group path where to remove the parameter
parameterthe name of the parameter to delete

Definition at line 200 of file configurationparameters.cpp.

References ConfigurationNode::deleteParameter(), and ConfigurationNode::isNull().

QStringList getFilteredGroupsList ( QString  group,
QRegExp  filter 
) const

Returns the list of sub-groups in the given group whose name matches the given regular expression.

Parameters
groupthe group for which the list of sub-groups is requested. "" means the main group.
filterthe regular expression that must be matched by group names
Returns
the filtered list of names of groups in the given group

Definition at line 142 of file configurationparameters.cpp.

Referenced by ConfigurationParameters::getGroupsWithPrefixList().

QStringList getFilteredParametersList ( QString  group,
QRegExp  filter 
) const

Returns the list of parameters in the given group whose name matches the given regular expression.

Parameters
groupthe group for which the list of parameters is requested. "" means the main group.
filterthe regular expression that must be matched by parameters names
Returns
the filtered list of names of parameters in the given group

Definition at line 247 of file configurationparameters.cpp.

Referenced by ConfigurationParameters::getParametersWithPrefixList().

QStringList getGroupsList ( QString  group) const

Returns the list of sub-groups in the given group.

Parameters
groupthe group for which the list of sub-groups is requested. "" means the main group.
Returns
the list of names of groups in the given group

Definition at line 129 of file configurationparameters.cpp.

Referenced by ConfigurationHelper::getDescribedParameterNames(), ConfigurationHelper::getDescribedSubgroupNames(), and ConfigurationHelper::hasGroup().

QStringList getGroupsWithPrefixList ( QString  group,
QString  prefix 
) const

Returns the list of sub-groups in the given group whose name starts with the provided string.

Parameters
groupthe group for which the list of sub-groups is requested. "" means the main group.
prefixthe string that must be at the beginning of the names of the returned groups
Returns
the filtered list of names of groups in the given group

Definition at line 134 of file configurationparameters.cpp.

References ConfigurationParameters::getFilteredGroupsList(), and ConfigurationParameters::isCaseSensitive().

Referenced by RealFactory::createListFromParameter(), and RealFactory::createVectorFromParameter().

TypeToCreate * getObjectFromGroup ( QString  group,
bool  configure = true,
bool  forceObjectCreation = false 
)

Returns the object for the given group, creating it if it doesn't exist.

At the beginning of the most external call to this function all associations between groups and objects are forgotten calling resetGroupObjectAssociations() on the root node (unless we are requested not to forget associations, see startRememberingGroupObjectAssociations() and stopRememberingGroupObjectAssociations()). This is one reason why this is not a const function. The other problem is that we need to modify nodes when creating objects to (temporarily) store the association. When the object for the group has already been created, the behaviour of the function dependes on the value of the forceObjectCreation parameter. If it is false (the default) the already created object is returned. If it is true, a new object is created and the association with the old one is lost. If however an object has been created but hasn't been configured yet, an exception is thrown

Parameters
groupthe group corresponding to the wanted object
configureif true the object is returned configured, if false it could be returned non configured
forceObjectCreationif true a new object is created even if we already have an object associated with the group.
Returns
the object
Note
This uses the factory to create the object, so a factory exception could be thrown (e.g. if group is not found)
Warning
Setting forceObjectCreation to true is experimental and not well tested

Definition at line 1195 of file configurationparameters.h.

References ParameterSettableWithConfigureFunction::configure(), ConfigurationNode::getObjectForNode(), ConfigurationParameters::GroupSeparator(), ConfigurationParameters::operator=(), ConfigurationParameters::resetGroupObjectAssociations(), and ConfigurationNode::setObjectForNode().

TypeToCreate* getObjectFromParameter ( QString  param,
bool  alsoMatchParents = false,
bool  configure = true,
bool  forceObjectCreation = false 
)
inline

Returns the object for the given parameter, creating it if it doesn't exist.

This calls getObjectFromGroup(), so everything said with regard to that function also applies here

Parameters
paramthe parameter whose value is the group corresponding to the wanted object
alsoMatchParentsif true, the parameter is first searched in the given path then, if it is not found, it is searched back in parent groups until found or the main group is reached. If false the parameter is only searched in the given path
configureif true the object is returned configured, if false it could be returned non configured
forceObjectCreationif true a new object is created even if we already have an object associated with the group (see getObjectFromGroup() for a detailed description)
Returns
the object
Warning
Setting forceObjectCreation to true is experimental and not well tested
Note
if alsoMatchParents is true and the path contains "..", the parameter is searched in any of the traversed groups (also in subgroups). So, for example, if you have the following structure:
[GROUP_A]
param1 = obj1
[GROUP_A/GROUP_B]
param2 = obj2

and call getObjectFromParameter("GROUP_A/GROUP_B/../param2", true), you will get the value of param2 inside GROUP_A/GROUP_B

Definition at line 912 of file configurationparameters.h.

QStringList getParametersList ( QString  group) const

Returns the list of parameters in the given group.

Parameters
groupthe group for which the list of parameters is requested
Returns
the list of names of parameters in the given group

Definition at line 234 of file configurationparameters.cpp.

QStringList getParametersWithPrefixList ( QString  group,
QString  prefix 
) const

Returns the list of parameters in the given group whose name starts with the provided string.

Parameters
groupthe group for which the list of parameters is requested. "" means the main group.
prefixthe string that must be at the beginning of the names of the returned parameters
Returns
the filtered list of names of parameters in the given group

Definition at line 239 of file configurationparameters.cpp.

References ConfigurationParameters::getFilteredParametersList(), and ConfigurationParameters::isCaseSensitive().

SimpleResourcesUser * getResourcesUserForResource ( QString  resourceName)

Returns the resouce user holding the resource with the given name.

See class description for more information

Parameters
resourceNamethe name of the resource to search
Returns
the resource user holding the requested resource or NULL if no resource user has it

Definition at line 407 of file configurationparameters.cpp.

QString getValue ( QString  path,
bool  alsoMatchParents = false 
) const

Returns a parameter value.

Parameters
paththe path of the parameter
alsoMatchParentsif true, the parameter is first searched in the given path then, if it is not found, it is searched back in parent groups until found or the main group is reached. If false the parameter is only searched in the given path
Returns
the parameter value or a empty string if no such parameter exists
Note
if alsoMatchParents is true and the path contains "..", the parameter is searched in any of the traversed groups (also in subgroups). So, for example, if you have the following structure:
[GROUP_A]
param1 = value1
[GROUP_A/GROUP_B]
param2 = value2

and call getValue("GROUP_A/GROUP_B/../param2", true), you will get the value of param2 inside GROUP_A/GROUP_B

Definition at line 219 of file configurationparameters.cpp.

Referenced by RealFactory::createFromParameter(), ConfigurationHelper::getBool(), ConfigurationHelper::getBoolVector(), ConfigurationHelper::getDouble(), Factory::getEditorForType(), ConfigurationHelper::getInt(), ConfigurationHelper::getIntegerVector(), ConfigurationHelper::getString(), ConfigurationHelper::getStringList(), ConfigurationHelper::getUnsignedInt(), ConfigurationHelper::getUnsignedIntegerVector(), ConfigurationHelper::getVector(), and ConfigurationHelper::hasParameter().

bool isCaseSensitive ( ) const

Returns true if we are case sensistive, false otherwise.

Returns
true if we are case sensistive, false otherwise

Definition at line 119 of file configurationparameters.cpp.

Referenced by ConfigurationParameters::getGroupsWithPrefixList(), ConfigurationParameters::getParametersWithPrefixList(), and ConfigurationHelper::hasGroup().

bool loadParameters ( QString  filename,
bool  keepOld = false,
QString  format = "" 
)

Loads a configuration file.

Parameters
filenamethe name of the file from which parameters should be loaded
keepOldif false old parameters are deleted before loading the new ones, otherwisethey are kept
formatthe format of the file to load. If "" format is guessed from filename extension. If guessing fails, loading fails
Returns
false if loading fails, true otherwise

Definition at line 360 of file configurationparameters.cpp.

ConfigurationParameters & operator= ( const ConfigurationParameters other)

Assignment operator.

This copies all parameters and groups from other and remove all old parameters. Also the case-sensitiveness is changed to match the one of other. No object association is copied, but this cannot be called if this object (i.e. the object which is overridden by the copy) is inside calls to configure. This also doesn't copy any resource manager association

Parameters
otherthe ConfigurationParameters object to copy

Definition at line 92 of file configurationparameters.cpp.

Referenced by ConfigurationParameters::getObjectFromGroup().

static QString ParentGroup ( )
inlinestatic

The sequence used to indicate the parent group.

Note
DON'T change to a character that changes between upper and lower case

Definition at line 276 of file configurationparameters.h.

Referenced by ConfigurationNode::addNode(), ConfigurationNode::addParameter(), ConfigurationNode::getNode(), ConfigurationNode::getObject(), ConfigurationNode::getValue(), ConfigurationNode::renameNode(), and ConfigurationNode::setValue().

bool registerFileFormat ( QString  format,
ParametersFileLoaderSaver fileLoaderSaver,
QString  defaultExtension 
)
static

The function to register file formats to use when loading or saving parameters from/to file.

Parameters
formatthe name of the format. This will be the string with which the format will be referred
fileLoaderSaverthe object to use to load/save files with the current format
defaultExtensionthe default extension for the current file format. If this is the empty string, the extension will be the same as the format name
Returns
true if registration was successful, false otherwise

Definition at line 47 of file configurationparameters.cpp.

bool renameGroup ( QString  oldGroupPath,
QString  newGroupName 
)

Rename the last group in the path specified with the new name.

Suppose you have the following configuration file (in INI format):

[GROUP_A]
param1 = value1
[GROUP_A/GROUP_B]
param2 = value2
[GROUP_A/GROUP_B/GROUP_C]
param3 = value3

When this methos is called in the following way:

params.renameGroup( "GROUP_A/GROUP_B", "B_GROUP" );

The results are (in INI format):

[GROUP_A]
param1 = value1
[GROUP_A/B_GROUP]
param2 = value2
[GROUP_A/B_GROUP/GROUP_C]
param3 = value3

The GROUP_B has been renamed to B_GROUP and all others remain untouched.

Parameters
oldGroupPaththe full group path to rename from ConfigurationParameters
newGroupNameonly the new name of the last group of the oldGroupPath

Definition at line 168 of file configurationparameters.cpp.

References ConfigurationParameters::GroupSeparator().

void resetGroupObjectAssociations ( )

Resets all associations between groups and objects.

Calling this function resets all associations between groups in the configuration tree and objects

Note
This function is quite computationally expensive

Definition at line 262 of file configurationparameters.cpp.

References ConfigurationNode::getChildrenNodesList(), and ConfigurationNode::resetObject().

Referenced by ConfigurationParameters::getObjectFromGroup().

bool saveParameters ( QString  filename,
QString  format = "",
bool  append = false 
)

Saves a configuration file.

This calls updateObjectReferences before saving. This is he reason why this function is not const

Parameters
filenamethe name of the file to which parameters should be saved
formatthe format of the file to save. If "" format is guessed from filename extension. If guessing fails, loading fails
appendif true it appends the parameters to the file specified lefting any previous data present on the file untouched; if false, it delete any previous data on file
Returns
false if saving fails, true otherwise

Definition at line 382 of file configurationparameters.cpp.

References ConfigurationParameters::updateObjectReferences().

void setResourcesUser ( ResourcesUser resourcesUser)

Registers a new resource user.

See class description for more information

Parameters
resourcesUserthe ResourcesUser object to register

Definition at line 419 of file configurationparameters.cpp.

bool setValue ( QString  path,
QString  value 
)

Sets the value of the parameter with the given path.

Parameters
paththe path of the parameter
valuethe new value for the parameter
Returns
false if the parameter doesn't exists, true otherwise
Note
it the value is an empty string, setValue will remove the parameter

Definition at line 224 of file configurationparameters.cpp.

bool setValue ( QString  path,
ParameterSettable object 
)

Sets the value of the parameter with the given path to point to an object.

Parameters
paththe path of the parameter
objectthe object to which the parameter refer
Returns
false if the parameter doesn't exists, true otherwise

Definition at line 229 of file configurationparameters.cpp.

void shareObserversWith ( ConfigurationParameters params)

share the FactoryObservers with an another ConfigurationParameters

Definition at line 429 of file configurationparameters.cpp.

bool startObjectParameters ( QString  groupPath,
QString  typeName,
ParameterSettable object 
)

Initializes a group so that it corresponds to the given object.

This sets the "type" parameter to typeName and make groupPath correspond to object. Note that previous association of the group to other objects is lost when calling this function.

Note
If you have a hierachy of classes deriving from ParameterSettable, each with its own save function, call startObjectParameters after having called the parent save function, like in the following example:
class Parent : public ParameterSettableWithConfigureFunction {
...
void save(ConfigurationParameters& params, QString prefix)
{
params.startObjectParameters(prefix, "Parent", this);
...
}
...
};
class Child : public Parent {
...
void save(ConfigurationParameters& params, QString prefix)
{
Parent::save(params, prefix);
params.startObjectParameters(prefix, "Child", this);
...
}
};

This way the type parameter is correctly set to the type of the child class when Child::save is called (the type parameter is overwritten each time startObjectParameters is called, so it is important that the actual type name is the one in the last call)

Parameters
groupPathis the full group path corresponding to the object
typeNamethe name of the type for the object
objectthe object corresponding to the group
Returns
false in case of error (e.g. groupPath is not a group)

Definition at line 207 of file configurationparameters.cpp.

References ConfigurationParameters::createGroup(), and ConfigurationParameters::createParameter().

void startRememberingGroupObjectAssociations ( )

Starts remembering associations between groups and objects.

When calling getObjectFromGroup() (or getObjectFromParameter()) associations between groups and objects are remembered until the most external call to getObjectFromGroup() terminates (see getObjectFromGroup()). Calling this prevents associations from being forgotten, so that even non-nested calls to getObjectFromGroup() refer to the same objects for the same groups. Call stopRememberingGroupObjectAssociations() to restore the original behaviour. Note that neither this nor startRememberingGroupObjectAssociations() call resetGroupObjectAssociations() (associations are reset only when resetGroupObjectAssociations() is explicitly called or the most external call to getObjectFromGroup() terminates in the standard situation)

Definition at line 252 of file configurationparameters.cpp.

void stopRememberingGroupObjectAssociations ( )

Stops remembering associations between groups and objects.

See startRememberingGroupObjectAssociations()

Definition at line 257 of file configurationparameters.cpp.

void updateObjectReferences ( )

Updates all object references to point to actual groups.

When a property is set to point to an object, it could know not which is the group for the object (because the object hasn't been added yet to the configuration tree). This function updates all properties pointing to objects so that they point to the correct group.

Note
This function is quite computationally expensive

Definition at line 285 of file configurationparameters.cpp.

References ConfigurationNode::getChildrenNodesList(), ConfigurationNode::getFullName(), ConfigurationNode::getObject(), ConfigurationNode::getObjectForNode(), ConfigurationNode::getObjectParametersList(), ConfigurationParameters::GroupSeparator(), ConfigurationNode::ObjectAndStatus::object, and ConfigurationNode::setValue().

Referenced by ConfigurationParameters::saveParameters().

Friends And Related Function Documentation

friend class ParameterSettableCreatorT
friend

ParameterSettableCreatorT is friend to be able to call the setObjectFromGroupStatusTo* functions.

Definition at line 1171 of file configurationparameters.h.

friend class RealFactory
friend

RealFactory is friend to be able to call the to access some member data and functions.

This is perhaps not very nice, but it is the easiest way of implementing calls to postConfigureInitialization() after all related objects have been created and configured

Definition at line 1181 of file configurationparameters.h.


The documentation for this class was generated from the following files: