Recent changes to ComponentsConfig

ComponentsConfig modified by Tomassino Ferrauto

Tomassino Ferrauto — Fri, 20 Nov 2015 10:21:42 -0000

ComponentsConfig modified by Tomassino Ferrauto

Tomassino Ferrauto — Tue, 17 Nov 2015 13:59:15 -0000

ComponentsConfig modified by Tomassino Ferrauto

Tomassino Ferrauto — Sat, 14 Nov 2015 08:52:33 -0000

ComponentsConfig modified by Tomassino Ferrauto

Tomassino Ferrauto — Fri, 13 Nov 2015 10:31:31 -0000

--- v39
+++ v40
@@ -9,16 +9,16 @@
 Configuring components
 =======

-This page shows how to write components that can be created and configured from configuration files. This, together with the information on [how to create plugins]([PluginsAndRegistration]), is the base knowledge needed to extend FARSA and create experiments. The reference guide contains detailed description of all methods and classes used here.
-
-**NOTE**: when implementing components in a plugin, remember to follow the guidelines in [this page]([PluginsAndRegistration]). In particular, code snippets in this page lack both the FARSA\_PLUGIN\_\* and the FARSA_REGISTER_CLASS macros (because they are mostly taken from FARSA source code).
+This page shows how to write components that can be created and configured from configuration files. This, together with the information on [how to create plugins]([PluginsAndRegistration]), is the basic knowledge needed to extend FARSA and create experiments. The reference guide contains detailed description of all methods and classes used here.
+
+**NOTE**: when implementing components in a plugin, remember to follow the guidelines in [this page]([PluginsAndRegistration]). In particular, code snippets in this page lack both the FARSA\_PLUGIN\_\* and the FARSA_REGISTER_CLASS macros (because they are mostly taken from FARSA core source code).

 Introduction
 -------

 The main use of plugins in FARSA is to add new components. Almost everything in FARSA is a component: robots, sensors, motors, experiments, controllers, ... These different types of objects share one common characteristic: they can be referred in configuration files together with their parameters and they can then be created at runtime loading the configuration file.

-The objects that are created at runtime have in general the same hierarchical structure of the configuration file. An object correspond to a group of parameters in the configuration file and objects corresponding to subgroups are owned by the object corresponding to the parent group. In the remaining part of this page we will refer to the following configuration file (a reduced and simplified version of the configuration file of the KheperaDiscriminationExperiment):
+The objects that are created at runtime have in general the same hierarchical structure of the configuration file. An object corresponds to a group of parameters in the configuration file and objects corresponding to subgroups are owned by the object corresponding to the parent group. In the remaining part of this page we will refer to the following configuration file (a reduced and simplified version of the configuration file of the *KheperaDiscriminationExperiment* plugin):

 ~~~~~~~
 :::INI
@@ -78,7 +78,7 @@
 The *describe()* method
 -------

-The first method that all components need to implement is the *describe()* function. The aim of this function is to provide a description of all the parameters and subgroups that are needed by the component. For each parameter it is possible to specify its name, which is its type, a description, whether it is mandatory or not and so on. Also subgroups must be defined here. All the information is then used mainly by *total99* to allow to graphically modify the configuration file. The following code snippet is a simplified version of the describe function of the Evoga class (corresponding to the \[Component/GA\] group in the configuration file above):
+The first method that all components need to implement is the *describe()* function. The aim of this function is to provide a description of all the parameters and subgroups that are needed by the component. For each parameter it is possible to specify its name, which is its type, a description, whether it is mandatory or not and so on. Also subgroups must be defined here. This information is then used by *total99* to allow to graphically modify the configuration file. The following code snippet is a simplified version of the describe function of the *Evoga* class (corresponding to the \[Component/GA\] group in the configuration file above):

 ~~~~~~~
 :::C++
@@ -119,24 +119,24 @@
 }
 ~~~~~~~

-The small excerpt from the Evoga class declaration shows that the *describe()* function is a static method. This method is called when the component is registered, before any instance of the class is created. The *type* parameter of the function contains the name with which the component is registered (which is the same as the class name). This is also the name you must use as the value of *type* parameter in the configuration file.
+The small excerpt from the *Evoga* class declaration shows that the *describe()* function is a static method. This method is called when the component is registered, before any instance of the class is created. The *type* parameter of the function contains the name with which the component is registered (which is the same as the class name). This is also the name you must use as the value of *type* parameter in the configuration file.

 The first line of the function is a call to the describe function of the parent class. This is important so that all parameters of the parent class are also associated with the present component.

 The second instruction creates a *Descriptor* object. This object is then used to declare all the parameters and subgroups. The object is created using the *addTypeDescription* function of the *ParameterSettable* class which takes two arguments: the first one is the name of the type being described (that is the type parameter of the *describe()* function) and the second one is a short description of the class. A third optional parameter is a longer description of the component.

-The remaining part of the function makes use of the *Descriptor* object to declare the parameters and subgroups. *Descriptor* has a set of functions named *describe\<type\>()* to declare different type of parameters. In the example above the *describeEnum()*, *describeInt()* and *describeReal()* functions are used. These functions take one parameter (the name of the configuration parameter) and return an object that can be used to further specify the parameter properties (default value, range, help text, ...). Refer to the [API documentation]([APIDoc]) for the full list of *describe\<type\>()* functions and the methods of the associated objects.
-
-Similarly to configuration parameters, subgroups are declared using the *describeSubgroup()* function, which takes the name of the subgroup as the only parameter. In the source code above, the subgroup is called "Experiment". The example configuration file contains a group named *\[Component/GA/Experiment\]*, that is a subgroup of *\[Component/GA\]* from which the Evoga object is created. A fundamental property of the subgroup is the type, which dictates which is the type of components that can be created from the subgroup. In the example, the type of the "Experiment" subgroup is "EvoRobotExperiment". This means that the *EvoRobotExperiment* component or any subclass can be used. In the configuration file the type "KheperaDiscriminationExperiment" is specified and that is actually a subclass of *EvoRobotExperiment* (you can check that this is actually the case by looking at the header file in the KheperaDiscriminationExperiment plugin).
+The remaining part of the function makes use of the *Descriptor* object to declare the parameters and subgroups. *Descriptor* has a set of functions named *describe<type>()* to declare different types of parameters. In the example above the *describeEnum()*, *describeInt()* and *describeReal()* functions are used. These functions take one parameter (the name of the configuration parameter) and return an object that can be used to further specify the parameter properties (default value, range, help text, ...). Refer to the [API documentation]([APIDoc]) for the full list of *describe<type>()* functions and the methods of the associated objects.
+
+Similarly to configuration parameters, subgroups are declared using the *describeSubgroup()* function, which takes the name of the subgroup as the only parameter. In the source code above, the subgroup is called "Experiment". The example configuration file contains a group named *\[Component/GA/Experiment\]*, that is a subgroup of *\[Component/GA\]* from which the *Evoga* object is created. A fundamental property of the subgroup is the type, which dictates which is the type of components that can be created from the subgroup. In the example, the type of the "Experiment" subgroup is "EvoRobotExperiment". This means that the *EvoRobotExperiment* component or any subclass can be used. In the configuration file the type "KheperaDiscriminationExperiment" is specified and that is actually a subclass of *EvoRobotExperiment* (you can check that this is actually the case by looking at the header file in the *KheperaDiscriminationExperiment* plugin).

 The constructor and the *configure()* method
 -------

-The *describe()* method allows to declare all the parameters and subgroups that a component expects to find. When the component is created, it has to read the value of those parameters and create the "sub-components", i.e. the components associated with its subgroups. Depending on whether the components inherits from the *ParameterSettableInConstructor* class or from the *ParameterSettableWithConfigureFunction* class, the function in which configuration parameters are read is different. How parameters are read and sub-components are created, however, is the same in both cases. We will first show how to implement components inheriting from *ParameterSettableWithConfigureFunction*, then we will discuss in what components inheriting from *ParameterSettableInConstructor* differ.
+The *describe()* method allows to declare all the parameters and subgroups that a component expects to find. When the component is created, it has to read the value of those parameters and create the sub-components, i.e. the components associated with its subgroups. Depending on whether the components inherits from the *ParameterSettableInConstructor* class or from the *ParameterSettableWithConfigureFunction* class, the function in which configuration parameters are read is different. How parameters are read and sub-components are created, however, is the same in both cases. We will first show how to implement components inheriting from *ParameterSettableWithConfigureFunction*, then we will discuss in what components inheriting from *ParameterSettableInConstructor* differ.

 **ParameterSettableWithConfigureFunction**

-The following is an example of a component inheriting from *ParameterSettableWithConfigureFunction*. As we did above, we will use a simplified version of the configure function of the Evoga class (corresponding to the \[Component/GA\] group in the configuration file above):
+The following is an example of a component inheriting from *ParameterSettableWithConfigureFunction*. As we did above, we will use a simplified version of the configure function of the *Evoga* class (corresponding to the \[Component/GA\] group in the configuration file above):

 ~~~~~~~
 :::C++
@@ -153,17 +153,17 @@
     // Call parent class configure() function if not pure virtual!
     //ParameterSettableWithConfigureFunction::configure(params, prefix);

-   evolutionType = ConfigurationHelper::getString(params, prefix + "evolutionType", "steadyState");
-   if ( evolutionType != "steadyState" && evolutionType != "generational" && evolutionType != "xnes" && evolutionType != "specializerSteadyState") {
-       Logger::error( "Evoga - evolutionType has been wrongly setted. It can assume only 'steadyState', 'generational', 'xnes' or 'specializerSteadyState' values" );
-       evolutionType = "steadyState";
-   }
+    evolutionType = ConfigurationHelper::getString(params, prefix + "evolutionType", "steadyState");
+    if ( evolutionType != "steadyState" && evolutionType != "generational" && evolutionType != "xnes" && evolutionType != "specializerSteadyState") {
+        Logger::error( "Evoga - evolutionType has been wrongly setted. It can assume only 'steadyState', 'generational', 'xnes' or 'specializerSteadyState' values" );
+        evolutionType = "steadyState";
+    }

     nogenerations = ConfigurationHelper::getInt(params, prefix + "ngenerations", 100);
-   
-   mutation = ConfigurationHelper::getDouble(params, prefix + "mutation_rate", 0.02);
-   
-   exp = params.getObjectFromGroup<EvoRobotExperiment>(prefix + "Experiment");
+
+    mutation = ConfigurationHelper::getDouble(params, prefix + "mutation_rate", 0.02);
+
+    exp = params.getObjectFromGroup<EvoRobotExperiment>(prefix + "Experiment");
 }
 ~~~~~~~

@@ -171,7 +171,7 @@

 The first instruction of the function should be a call to the parent class *configure()* function. This is needed so that configuration parameters of the parent are correctly set. The only exception to this rule is when a class inherits directly from *ParameterSettableWithConfigureFunction*, as in the example above: in this case the parent function cannot be called because it is declared as pure virtual.

-The rest of the function contains code to read the value of parameters and create subcomponents. All parameters are stored as strings in *ConfigurationParameters*, so they must in general be converted to the correct type. The class *ConfigurationHelper* contains a set of static functions that can be used to convert a value to the correct type and to assign a default value in case the parameter is missing or the conversion fails. All the functions are called *ConfigurationHelper::get\<type\>()* and take three parameters: the first one is the *ConfigurationParameters* object containing the parameters and their values, the second one is the name and path of the parameter to read and the third one is the default value. The functions take the full path to a parameter. This means that you must provide the name of the group followed by the name of the parameter. The name of the group is in *prefix* and you can simply append to it the name of the parameter using the + operator (as in the example above). As always, refer to the [API documentation]([APIDoc]) for more information.
+The rest of the function contains code to read the value of parameters and create subcomponents. All parameters are stored as strings in *ConfigurationParameters*, so they must in general be converted to the correct type. The class *ConfigurationHelper* contains a set of static functions that can be used to convert a value to the correct type and to assign a default value in case the parameter is missing or the conversion fails. All the functions are called *ConfigurationHelper::get<type>()* and take three parameters: the first one is the *ConfigurationParameters* object containing the parameters and their values, the second one is the name and path of the parameter to read and the third one is the default value. The functions take the full path to a parameter. This means that you must provide the name of the group followed by the name of the parameter. The name of the group is in *prefix* and you can simply append to it the name of the parameter using the + operator (as in the example above). As always, refer to the [API documentation]([APIDoc]) for more information.

 A note on the default value. It is important to use the same default value for a parameter in both the *describe()* and *configure()* functions. At the moment the default value when reading the parameters cannot be inferred automatically from the default value declared in *describe()* (this will be changed in a future version of FARSA).

@@ -194,12 +194,12 @@
 };

 KheperaSampledProximityIRSensor::KheperaSampledProximityIRSensor(ConfigurationParameters& params, QString prefix) :
-   KheperaSensor(params, prefix),
-   m_activeSensors(ConfigurationHelper::getBoolVector(params, prefix + "activeSensors", "11111111"))
-{
-   if (m_activeSensors.size() != 8) {
-       ConfigurationHelper::throwUserConfigError(prefix + "activeSensors", params.getValue(prefix + "activeSensors"), "The parameter must be a list of exactly 8 elements either equal to 1 or to 0 (do not use any space to separate elements, just put them directly one after the other)");
-   }
+    KheperaSensor(params, prefix),
+    m_activeSensors(ConfigurationHelper::getBoolVector(params, prefix + "activeSensors", "11111111"))
+{
+    if (m_activeSensors.size() != 8) {
+        ConfigurationHelper::throwUserConfigError(prefix + "activeSensors", params.getValue(prefix + "activeSensors"), "The parameter must be a list of exactly 8 elements either equal to 1 or to 0 (do not use any space to separate elements, just put them directly one after the other)");
+    }
 }
 ~~~~~~~

@@ -295,17 +295,17 @@

 ~~~~~~~

-The *getUIManager()* function must return a new instance of a subclass of *ParameterSettableUI* (it is a *factory* method). The returned object is then managed by total99. The default implementation of the function returns NULL, to indicate that the component has no GUI.
-
-The *EvonetUI* class inherits from *ParameterSettableUI* and implements a number of methods. *getViewers()* is the one that creates and returns the GUIs associated to the component. The function parameters (*parent* and *flags*) are meant to be passed to constructors of the GUIs, which generally are QT widgets. The function returns a list of the GUIs that have been created together with their names (refer to the [API documentation]([APIDoc]) for more information). The returned objects are managed by total99.
-
-In the example above the *fillActionsMenu()* and *addAdditionalMenus()* methods are empty. They can be implemented to respectively add actions that will be shown in the total99 *Actions* menu and to insert new menus in the menu bar of total99. Information on how to create new menu items and menus can be found in the QT library documentation.
+The *getUIManager()* function must return a new instance of a subclass of *ParameterSettableUI* (it is a *factory* method). The returned object is then managed by *total99*. The default implementation of the function returns NULL, to indicate that the component has no GUI.
+
+The *EvonetUI* class inherits from *ParameterSettableUI* and implements a number of methods. *getViewers()* is the one that creates and returns the GUIs associated to the component. The function parameters (*parent* and *flags*) are meant to be passed to constructors of the GUIs, which generally are QT widgets. The function returns a list of the GUIs that have been created together with their names (refer to the [API documentation]([APIDoc]) for more information). The returned objects are managed by *total99*.
+
+In the example above the *fillActionsMenu()* and *addAdditionalMenus()* methods are empty. They can be implemented to respectively add actions that will be shown in the *total99* *Actions* menu and to insert new menus in the menu bar of *total99*. Information on how to create new menu items and menus can be found in the QT library documentation.

 **Threading issues**

-One important aspect to keep in mind when dealing with GUIs and menus in FARSA is that when total99 is running there are two different threads: one managing the grafical user interface and one running the experiment/simulation. GUI objects (*ParameterSettableUI* subclasses and all the objects it creates) live in the former, components are created in the former but then run in the latter. This means that when exchanging data to and from the GUI or when actions are triggered from total99 menus, special care should be taken. FARSA does not impose the use of a specific synchronization and locking mechanism, so you are free to use whatever you like. There are, however, some helper classes that can be useful, like those implemented in the *dataexchange.h* header file (e.g. *DataUploader*, *DataDownloader*, ...) . Refer to the [API documentation]([APIDoc]) for a detailed description of those classes and examples of their use.
+One important aspect to keep in mind when dealing with GUIs and menus in FARSA is that when *total99* is running there are two different threads: one managing the grafical user interface and one running the experiment/simulation. GUI objects (*ParameterSettableUI* subclasses and all the objects it creates) live in the former, components are created in the former but then run in the latter. This means that when exchanging data to and from the GUI or when actions are triggered from *total99* menus, special care should be taken. FARSA does not impose the use of a specific synchronization and locking mechanism, so you are free to use whatever you like. There are, however, some helper classes that can be useful, like those implemented in the *dataexchange.h* header file (e.g. *DataUploader*, *DataDownloader*, ...) . Refer to the [API documentation]([APIDoc]) for a detailed description of those classes and examples of their use.

 The *Component* class
 -------

-Despite the name, this is a special kind of component, specifically the first one that is loaded by total99. Its use is described in [this page]([ComponentBaseExperiment]).
+Despite the name, this is a special kind of component, specifically the first one that is loaded by *total99*. Its use is described in [this page]([ComponentBaseExperiment]).

ComponentsConfig modified by Tomassino Ferrauto

Tomassino Ferrauto — Thu, 12 Nov 2015 10:36:26 -0000

ComponentsConfig modified by Tomassino Ferrauto

Tomassino Ferrauto — Thu, 12 Nov 2015 10:21:20 -0000

--- v37
+++ v38
@@ -1,3 +1,11 @@
+[Prev: Creating a plugin and registering components]([PluginsAndRegistration]) | [Up: Plugins, components and resources]([ComponentsPluginAndResources]) | [Next: Declaring and accessing resources]([Resources])
+ -------|--------|----------
+        |        |
+
+**Table of contents**
+
+[TOC]
+
 Configuring components
 =======

ComponentsConfig modified by Tomassino Ferrauto

Tomassino Ferrauto — Wed, 21 Oct 2015 14:11:30 -0000

--- v36
+++ v37
@@ -5,7 +5,7 @@

 **NOTE**: when implementing components in a plugin, remember to follow the guidelines in [this page]([PluginsAndRegistration]). In particular, code snippets in this page lack both the FARSA\_PLUGIN\_\* and the FARSA_REGISTER_CLASS macros (because they are mostly taken from FARSA source code).

-Overview
+Introduction
 -------

 The main use of plugins in FARSA is to add new components. Almost everything in FARSA is a component: robots, sensors, motors, experiments, controllers, ... These different types of objects share one common characteristic: they can be referred in configuration files together with their parameters and they can then be created at runtime loading the configuration file.

ComponentsConfig modified by Tomassino Ferrauto

Tomassino Ferrauto — Wed, 21 Oct 2015 11:41:04 -0000

--- v35
+++ v36
@@ -117,7 +117,7 @@

 The second instruction creates a *Descriptor* object. This object is then used to declare all the parameters and subgroups. The object is created using the *addTypeDescription* function of the *ParameterSettable* class which takes two arguments: the first one is the name of the type being described (that is the type parameter of the *describe()* function) and the second one is a short description of the class. A third optional parameter is a longer description of the component.

-The remaining part of the function makes use of the *Descriptor* object to declare the parameters and subgroups. *Descriptor* has a set of functions named *describe\<type\>()* to declare different type of parameters. In the example above the *describeEnum()*, *describeInt()* and *describeReal()* functions are used. These functions take one parameter (the name of the configuration parameter) and return an object that can be used to further specify the parameter properties (default value, range, help text, ...). Refer to the API documentation for the full list of *describe\<type\>()* functions and the methods of the associated objects.
+The remaining part of the function makes use of the *Descriptor* object to declare the parameters and subgroups. *Descriptor* has a set of functions named *describe\<type\>()* to declare different type of parameters. In the example above the *describeEnum()*, *describeInt()* and *describeReal()* functions are used. These functions take one parameter (the name of the configuration parameter) and return an object that can be used to further specify the parameter properties (default value, range, help text, ...). Refer to the [API documentation]([APIDoc]) for the full list of *describe\<type\>()* functions and the methods of the associated objects.

 Similarly to configuration parameters, subgroups are declared using the *describeSubgroup()* function, which takes the name of the subgroup as the only parameter. In the source code above, the subgroup is called "Experiment". The example configuration file contains a group named *\[Component/GA/Experiment\]*, that is a subgroup of *\[Component/GA\]* from which the Evoga object is created. A fundamental property of the subgroup is the type, which dictates which is the type of components that can be created from the subgroup. In the example, the type of the "Experiment" subgroup is "EvoRobotExperiment". This means that the *EvoRobotExperiment* component or any subclass can be used. In the configuration file the type "KheperaDiscriminationExperiment" is specified and that is actually a subclass of *EvoRobotExperiment* (you can check that this is actually the case by looking at the header file in the KheperaDiscriminationExperiment plugin).

@@ -163,13 +163,13 @@

 The first instruction of the function should be a call to the parent class *configure()* function. This is needed so that configuration parameters of the parent are correctly set. The only exception to this rule is when a class inherits directly from *ParameterSettableWithConfigureFunction*, as in the example above: in this case the parent function cannot be called because it is declared as pure virtual.

-The rest of the function contains code to read the value of parameters and create subcomponents. All parameters are stored as strings in *ConfigurationParameters*, so they must in general be converted to the correct type. The class *ConfigurationHelper* contains a set of static functions that can be used to convert a value to the correct type and to assign a default value in case the parameter is missing or the conversion fails. All the functions are called *ConfigurationHelper::get\<type\>()* and take three parameters: the first one is the *ConfigurationParameters* object containing the parameters and their values, the second one is the name and path of the parameter to read and the third one is the default value. The functions take the full path to a parameter. This means that you must provide the name of the group followed by the name of the parameter. The name of the group is in *prefix* and you can simply append to it the name of the parameter using the + operator (as in the example above). As always, refer to the API documentation for more information.
+The rest of the function contains code to read the value of parameters and create subcomponents. All parameters are stored as strings in *ConfigurationParameters*, so they must in general be converted to the correct type. The class *ConfigurationHelper* contains a set of static functions that can be used to convert a value to the correct type and to assign a default value in case the parameter is missing or the conversion fails. All the functions are called *ConfigurationHelper::get\<type\>()* and take three parameters: the first one is the *ConfigurationParameters* object containing the parameters and their values, the second one is the name and path of the parameter to read and the third one is the default value. The functions take the full path to a parameter. This means that you must provide the name of the group followed by the name of the parameter. The name of the group is in *prefix* and you can simply append to it the name of the parameter using the + operator (as in the example above). As always, refer to the [API documentation]([APIDoc]) for more information.

 A note on the default value. It is important to use the same default value for a parameter in both the *describe()* and *configure()* functions. At the moment the default value when reading the parameters cannot be inferred automatically from the default value declared in *describe()* (this will be changed in a future version of FARSA).

 The example also shows that you should check errors when reading parameters. If a parameter ends up having and invalid value, you should either set it to the default and warn the used (as in the example above) or you can abort the configuration of all components throwing an exception of type *UserDefinedCheckFailureException* (in this case the *ConfigurationHelper::throwUserConfigError()* function is a convenient helper function).

-The last instruction of the function shows how subcomponents can be created using the *ConfigurationParameters::getObjectFromGroup()* function. The function returns a pointer to a new object that is created using configuration parameters of the subgroup. More in detail, *getObjectFromGroup()* is a template function whose template parameter is the type of the object to return. The function creates the object and then checks whether its type is compatible with the requested one, throwing an exception if it is not. The only parameter of the function is the group from which the object is to be created: the full path is needed and, as for parameters, it can be obtained by concatenating *prefix* with the subgroup name. The *getObjectFromGroup()* function has also other parameters to customize its behaviour, refer to the API documentation for more information.
+The last instruction of the function shows how subcomponents can be created using the *ConfigurationParameters::getObjectFromGroup()* function. The function returns a pointer to a new object that is created using configuration parameters of the subgroup. More in detail, *getObjectFromGroup()* is a template function whose template parameter is the type of the object to return. The function creates the object and then checks whether its type is compatible with the requested one, throwing an exception if it is not. The only parameter of the function is the group from which the object is to be created: the full path is needed and, as for parameters, it can be obtained by concatenating *prefix* with the subgroup name. The *getObjectFromGroup()* function has also other parameters to customize its behaviour, refer to the [API documentation]([APIDoc]) for more information.

 **ParameterSettableInConstructor**

@@ -289,13 +289,13 @@

 The *getUIManager()* function must return a new instance of a subclass of *ParameterSettableUI* (it is a *factory* method). The returned object is then managed by total99. The default implementation of the function returns NULL, to indicate that the component has no GUI.

-The *EvonetUI* class inherits from *ParameterSettableUI* and implements a number of methods. *getViewers()* is the one that creates and returns the GUIs associated to the component. The function parameters (*parent* and *flags*) are meant to be passed to constructors of the GUIs, which generally are QT widgets. The function returns a list of the GUIs that have been created together with their names (refer to the API reference for more information). The returned objects are managed by total99.
+The *EvonetUI* class inherits from *ParameterSettableUI* and implements a number of methods. *getViewers()* is the one that creates and returns the GUIs associated to the component. The function parameters (*parent* and *flags*) are meant to be passed to constructors of the GUIs, which generally are QT widgets. The function returns a list of the GUIs that have been created together with their names (refer to the [API documentation]([APIDoc]) for more information). The returned objects are managed by total99.

 In the example above the *fillActionsMenu()* and *addAdditionalMenus()* methods are empty. They can be implemented to respectively add actions that will be shown in the total99 *Actions* menu and to insert new menus in the menu bar of total99. Information on how to create new menu items and menus can be found in the QT library documentation.

 **Threading issues**

-One important aspect to keep in mind when dealing with GUIs and menus in FARSA is that when total99 is running there are two different threads: one managing the grafical user interface and one running the experiment/simulation. GUI objects (*ParameterSettableUI* subclasses and all the objects it creates) live in the former, components are created in the former but then run in the latter. This means that when exchanging data to and from the GUI or when actions are triggered from total99 menus, special care should be taken. FARSA does not impose the use of a specific synchronization and locking mechanism, so you are free to use whatever you like. There are, however, some helper classes that can be useful, like those implemented in the *dataexchange.h* header file (e.g. *DataUploader*, *DataDownloader*, ...) . Refer to the API documentation for a detailed description of those classes and examples of their use.
+One important aspect to keep in mind when dealing with GUIs and menus in FARSA is that when total99 is running there are two different threads: one managing the grafical user interface and one running the experiment/simulation. GUI objects (*ParameterSettableUI* subclasses and all the objects it creates) live in the former, components are created in the former but then run in the latter. This means that when exchanging data to and from the GUI or when actions are triggered from total99 menus, special care should be taken. FARSA does not impose the use of a specific synchronization and locking mechanism, so you are free to use whatever you like. There are, however, some helper classes that can be useful, like those implemented in the *dataexchange.h* header file (e.g. *DataUploader*, *DataDownloader*, ...) . Refer to the [API documentation]([APIDoc]) for a detailed description of those classes and examples of their use.

 The *Component* class
 -------

ComponentsConfig modified by Tomassino Ferrauto

Tomassino Ferrauto — Wed, 14 Oct 2015 07:59:22 -0000

--- v34
+++ v35
@@ -159,7 +159,7 @@
 }
 ~~~~~~~

-The small excerpt from the Evoga class declaration shows that the *configure()* function is a virtual method. It takes two parameters: a reference to a *ConfigurationParameters* object and a string. The *ConfigurationParameters* class is the one responsible of reading the configuration file. All parameters and subgroups are read through *params*, directly or using helper methods. This object contains all parameters in the file, even those relative to objects different from the one being configured. The *prefix* string contains the name of the group associated with the object being configured , and is then needed to access the object own parameters (as explained in detail below).
+The small excerpt from the Evoga class declaration shows that the *configure()* function is a virtual method. It takes two parameters: a reference to a *ConfigurationParameters* object and a string. The *ConfigurationParameters* class is the one responsible of reading the configuration file. All parameters and subgroups are read through *params*, directly or using helper methods. This object contains all parameters in the file, even those relative to objects different from the one being configured. The *prefix* string contains the name of the group associated with the object being configured, and is then needed to access the object own parameters (as explained in detail below).

 The first instruction of the function should be a call to the parent class *configure()* function. This is needed so that configuration parameters of the parent are correctly set. The only exception to this rule is when a class inherits directly from *ParameterSettableWithConfigureFunction*, as in the example above: in this case the parent function cannot be called because it is declared as pure virtual.

ComponentsConfig modified by Tomassino Ferrauto

Tomassino Ferrauto — Wed, 14 Oct 2015 07:58:22 -0000

--- v33
+++ v34
@@ -295,7 +295,7 @@

 **Threading issues**

-One important aspect to keep in mind when dealing with GUIs and menus is that in FARSA is that when total99 is running there are two different threads: one managing the grafical user interface and one running the experiment/simulation. GUI objects (*ParameterSettableUI* subclasses and all the objects it creates) live in the former, components are created in the former but then run in the latter. This means that when exchanging data to and from the GUI or when actions are triggered from total99 menus, special care should be taken. FARSA does not impose the use of a specific synchronization and locking mechanism, so you are free to use whatever you like. There are, however, some helper classes that can be useful, like those implemented in the *dataexchange.h* header file (e.g. *DataUploader*, *DataDownloader*, ...) . Refer to the API documentation for a detailed description of those classes and examples of their use.
+One important aspect to keep in mind when dealing with GUIs and menus in FARSA is that when total99 is running there are two different threads: one managing the grafical user interface and one running the experiment/simulation. GUI objects (*ParameterSettableUI* subclasses and all the objects it creates) live in the former, components are created in the former but then run in the latter. This means that when exchanging data to and from the GUI or when actions are triggered from total99 menus, special care should be taken. FARSA does not impose the use of a specific synchronization and locking mechanism, so you are free to use whatever you like. There are, however, some helper classes that can be useful, like those implemented in the *dataexchange.h* header file (e.g. *DataUploader*, *DataDownloader*, ...) . Refer to the API documentation for a detailed description of those classes and examples of their use.

 The *Component* class
 -------