| Overview | All Modules | Tutorial | User's Guide | Programming Guide |
| Previous | COVISE Online Documentation | Next |
The base class for all module programming is coModule. An application is created by deriving a class of coModule. The constructor of the derived class creates the module layout with input ports, output ports and parameters. Virtual functions are overloaded to implement the module's reactions on events. Every COVISE module based on coModule looks like:
Header file:
class myMod: public coModule
{
private:
... // parameter and data object ports
public:
myMod(int argc, char *argv[]); // Constructor: module set-up
virtual void compute(const char *); // Called for every execute
virtual void param(const char *, bool inMapLoading);
// Called for param changes
virtual void sockData(int sockNo); // Called for receiving data
}
Source code:
myMod::myMod(int argc, char *argv[])
: coModule(argc, argv, "My example module")
{...} // build ports and parameters
myMod::compute(const char *) {...} // module is executed
myMod::param(const char *, bool inMapLoading)
{...} // parameters changed
myMod::postInst(const char *) {...} // between c'tor and main loop
myMod::quit(const char *) {...} // after the end of main loop
myMod::sockData(int socNo) {...} // data arrived on a socket
MODULE_MAIN(SomeCategory, myMod)
To allow future use of threads and multi-linked modules, modules should use neither global nor non-constant static variables.
The constructor of a module is used to set up its external connectivity. First, it calls the constructor of the base class coModule:
void coModule::coModule(int argc, char *argv[], const char *description=NULL, bool propagate=false)
The constructor of coModule establishes some basic data structures and pre-sets them with defaults values.
The execution of a module constructor is time-critical. If the constructor is not finished within the timeout period given in the config file, the CRB will not accept the module and the user interface will issue an error message telling that the module did not start.
In general, the constructor should never do anything else than defining the ports and parameters of the module.
For any additional functionality required before entering the main loop the routine
virtual void coModule::postInst()
should be overloaded by the module. It is called once before entering the main event loop. This avoids timeouts, which could occur as described in the constructor paragraph.
Since COVISE 6.1, a module is notified immediately unconditionally when a parameter was changed by the user (i. e. all parameters are “immediate” now). For any changed parameters, the callback
virtual void coModule::param(const char *paramName, bool inMapLoading)
is called with the name of the port as the parameter.
The compute callback is called whenever new input data for a module is available or when the user executes a module manually.
virtual int coModule::compute(const char *)
Before calling the user supplied routine, the input objects are retrieved from the data manager and the object pointer is stored to be retrieved from the port. The return value of the compute callback must be either CONTINUE_PIPELINE or STOP_PIPELINE depending on whether modules below should be executed or not.
Most modules only need a compute function and do not use the other functions. All functions are pre-initialized with empty functions in case the user does not overload them. A warning is submitted if compute(const char *) is executed without being overloaded.
If a module needs to use any other external communication means than the COVISE internal networking, e. g. connect to a simulation or use the X Window system, the programmer has to make sure that COVISE messages are still received and handled. Therefore, a file descriptor, e. g. a socket, can be registered with the module via
void addSocket(int fd)
Once this has been done, COVISE adds the socket to its own sockets and calls the virtual function
virtual void coModule::sockData(int fd)
with the file descriptor as the argument. The user can then handle the input and return control to COVISE by leaving the callback. After use, the socket is removed using
void removeSocket(int fd)
quit
A module terminates either when COVISE terminates, the user deletes a module or a new map is loaded. To allow cleaning up resources, the routine
virtual void coModule::quit()
is automatically called before the module quits.
idle
The idle function is called whenever the module waits for COVISE messages.
virtual float coModule::idle()
You should not block in this function, otherwise the module will never get the chance to process incomming messages. If you overwrite this method, you have to return a float value. This value specifies the maximum number of seconds to wait until the idle function is called again. If zero is returned, the idle function is called again immediately after checking for COVISE messages. If a negative value is returned, the idle function will not be called until any message arrived. If a positive Value is returned, the idle function will be called after the appropriate time, or earlier if any message arrived.
Remember: You can't create COVISE distributed objects in this callback!
Other coModule functions
virtual void feedback(int len, const char *data);
This function is called when a COVER plugin sends a feedback message.
virtual void feedbacksetInfo(int len, const char *datatext);
Allows to set an info string in the control panel of the module.
COVISE can handle hierarchical structures of data created by Set containers, e.g. timestep series or data sets consisting of multiple distinct parts. A module handling these data types has to be written recursively to be able to handle arbtrary levels of hierarchy. In most cases, modules work with `corresponding' data, e.g. a set of geometry objects required an identical set of colors and normals, or a set of timesteps of a moving grid simulation corresponds to a similar set of data values.
For easier module development, the class coSimpleModule has been derived from coModule. It automatically un-packs all level of Set containers until reaching the lowes level, and then calls compute(const char *) for each low-level object. The module developer simply creates the module and writes a compute(const char *) function as if the data was non-hierarchical, which is then called for every corresponding set of low-level object.
The functions
void setComputeTimesteps(const int off); // 0 by default
void setComputeMultiblock(const int off); // 0 by default
can be called if the user wants to handle timesteps or multiblock data himself, e.g. for particle tracing.
The simple module also automatically copies all attributes from the input objects to the output objects at the port directly underneath the input port. If this is not desired, it can be switched of by calling
void setCopyAttributes(const int on); // 1 by default
Ports establish the connection of a module to the rest of the COVISE system. Three different kinds of connections can be defined:
All ports and parameters are created by calling a member function of coModule that returns a pointer to a port class object, which can later be used to set or retrieve port data. These pointers will usually be stored as module class private data being usable in the whole module.
The creation of ports and parameters only possible in the Constructor state, a later creation of ports is not supported. Ports can be hidden or de-activated if not currently needed.
Never create Modules with variable numbers of Ports or Parameters: These modules will crash COVISE when being read from a map file!
All ports and parameters must have a unique name and description, which can be any text explaining the function of the port. Names must not contain blank characters or any special ASCII characters like TAB, CR, LF, DEL, BS. The description may contain blanks, but no special characters like CR, LF or BS characters and need not be unique.
Never construct a port or parameter by its own constructor, COVISE must register it with the module. Instead, the functions add<type>Port and add<type>Param have to be used.
All input and parameter ports derive from the same base class coUifElem, which implements some base functionality for all kinds of ports. The following subroutines can therefore be called for all parameter and port class objects:
| const char *coUifElem::getName() const | |
| Description: | Get port's name |
| COVISE states: | all |
| Return value: | Port name |
| const char *coUifElem::getDesc() const | |
| Description: | Get port's description |
| COVISE states: | all |
| Return value: | Port description |
| virtual void coUifElem::print(ostream &str) const | ||
| Description: | Print port information into a stream | |
| COVISE states: | all | |
| IN: | str | stream to print into |
When replacing modules, data port connections can only be maintained if the ports adhere to a common naming scheme. A port name should start with a prefix from the following table. If the port is able to accept data types from several lines in this table, then choose “Data”, except for when it is Geometry and grid types, then choose “Grid”. As appropriate, append “In” or “Out” to the prefix. Finally you should append the number of the port: start with “0” for the first port with a certain prefix and direction, and increase the number for each other port with the same prefix and direction. Also append the final “0” if there is only one port of this type.
| Name prefix | Data object types |
| Data | Int, Float, Vec2, Vec3, RGBA, Mat, Tensor |
| Grid | Points, Spheres, Lines, Polygons, TriangleStrips,
UniformGrid, RectilinearGrid, StructuredGrid, UnstructuredGrid |
| Geometry | Geometry |
| Texture | Texture |
Data ports are created by:
| coInputPort *coModule::addInputPort(const char *name,const char *typeList, const char *desc) | ||
| Description: | Create an Input data port | |
| COVISE states: | Constructor | |
| IN: | name: | Port name |
| IN: | typeList: | Map editor data types |
| IN: | desc: | Parameter description |
| Return Value: | pointer to newly created port | |
| coOutputPort *coModule::addOutputPort(const char *name, const char *typeList, const char *desc) | ||
| Description: | Create an Output data port | |
| COVISE states: | Constructor | |
| IN: | name: | Port name |
| IN: | typeList: | Map editor data types |
| IN: | desc: | Parameter description |
| Return Value: | pointer to newly created port | |
The parameter types string lists all type names of objects allowed to connect with this port divided by a `|' character, e.g.:
"Float|Vec3"
The type string must not contain any blanks, otherwise it is not possible to connect the ports in the map editor. This type information is only given to the map editor, which then prohibits connections between ports without common types. The port information does not imply any checking of data types assigned to the port by the module, so type-checking must still be implemented in the module. The reason for not checking the data types according to the map editor types is to allow different usage of the same data type by different map editor types enforcing correct connections.
By default, a module only executes (i.e. calls its compute callback) if all input ports of a module are connected. By declaring a port 'not required', the pipeline will also be executed without a connection to this port. The module will then receive a NULL pointer when trying to retrieve the port's data.
| void coInputPort::setRequired(int isRequired) | ||
| Description: | declare a port (not) required | |
| COVISE states: | Compute | |
| IN: | isRequired | =0:not required, else required |
Whenever the compute(const char *) callback is called by the main loop, the data objects at the input ports are opened and can be read by calling the input port's getCurrentObject() method. If the port is not connected, or if an error occurs, a NULL pointer is returned.
A non-required input port can be declared as a `dependency' of an output port, meaning it becomes required if this output port is connected.
| void coOutputPort::setDependency(coInputPort *port) | ||
| Description: | declare an output port dependending on a certain input | |
| COVISE states: | Constructor | |
| IN: | port | port depended upon |
If no data is available on a connected port, the compute callback is not called and the start message is silently ignored. This allows a direct flow control by not creating some of the defined output objects which leads to branches of the data flow network that are not executed.
| coDistributedObject *coInputPort::getCurrentObject() | |
| Description: | Retrieve input data |
| COVISE states: | Compute |
| Return value: | Object received at the port |
The resulting object pointer is a pointer to a derived class of coDistributedObject, which can be casted up to the real class. To find the correct type, the base class member function getType() can be used.
| const char *coOutputPort:: getObjName() | |
| Description: | get object name for output objects |
| COVISE states: | Compute |
| Return value: | pointer to name for new data object |
This call delivers the appropriate name to create data objects for an output port. The return value must be given to the constructor of the object, which is then assigned to the port for sending it to all connected modules by
| void coOutputPort::setCurrentObject(coDistributedObject *obj) | |
| Description: | Assign output data object to port |
| COVISE states: | Compute |
The output object will be sent to all connected modules after the compute(const char *) callback has finished and is then automatically deleted. Examples for object creation and receiving can be found in the example modules under covise/src/examples.
The tool-tip text, which appears when right-clicking on a port, can be set by:
| void coPort::setInfo(const char *text) | ||
| Description: | set tooltip text | |
| COVISE states: | After initialisation (postInst, compute, ...) | |
| IN: | text | tooltip text |
All parameter classes are derived from coUifPara, which offers common functions for all kinds of parameter ports:
To allow direct interaction with the module, all parameter changes are immediately sent to the module and the module's param() callback is fired. If the callback does not react on the parameter, the value is still updated, but no further action is taken.
A parameter can be mapped into the Control Panel by clicking the checkbox in the Module Set-up window. Nevertheless, the module programmer can control the mapping by calls to the functions:
| void coUifPara::show() | |
| Description: | Show/Hide a parameter in the control panel |
| COVISE states: | PostInst, all Main-Loop callbacks |
| void coUifPara::hide() | |
| Description: | Show/Hide a parameter in the control panel |
| COVISE states: | PostInst, all Main-Loop callbacks |
Parameters can also be disabled by the module. If a parameter is disabled, it is displayed in gray both in the Module set-up panel and in the control panel and no parameter changes are possible. Parameter disabling is typically used for parameters that are only required under certain circumstances, e.g. in simulation couplings, which can have different sets of parameters depending on the simulation case.
| void coUifPara::enable() | |
| Description: | Enable or disable parameter |
| COVISE states: | PostInst, all Main-Loop callbacks |
| void coUifPara::disable() | |
| Description: | Enable or disable parameter |
| COVISE states: | PostInst, all Main-Loop callbacks |
A Boolean parameter can only have the values TRUE (NONZERO) or FALSE (=0).
The default value of a Boolean parameter is FALSE.
A Boolean parameter is created by:
| coBooleanParam *coModule::addBooleanParam (const char *name, const char *desc) | ||
| Description: | Create a Boolean parameter | |
| COVISE states: | Constructor | |
| IN: | name: | Parameter name |
| IN: | desc: | Parameter description |
| Return value: | pointer to new created port | |
This function creates a new port and registers it at the module for receiving port messages. The value of a Boolean Parameter can be requested and set by the program using:
| int coBooleanParam::getValue() | |
| Description: | get Value of a Boolean parameter |
| COVISE states: | all |
| Return value: | Value of the parameter |
| int coBooleanParam::setValue(int value) | ||
| Description: | set Value of a Boolean parameter | |
| COVISE states: | all | |
| IN: | value | value to be set |
| Return value: | =0 on error, =1 on success | |
A typical code fragment is:
myModule.h
class myModule
{
private:
coBooleanParam *p_shadeFlag;
...
}
myModule.cpp
myModule::myModule() // ... build ports and parameters
{
// create the boolean port: declared as member variable
p_shadeFlag = addBooleanParameter("shade","apply shading");
// set a default value
p_shadeFlag->setValue(1);
}
myModule::compute(const char *) // ... e.g. in the compute callback
{
int shading = p_shadeFlag->getValue();
...
}
It is a good habit to mark all ports and parameters with a common prefix. In our examples we have chosen names that start with 'p_'.
There are integer and float scalar parameters. Both represent a single value of the corresponding type. The integer scalar parameter is exactly identical to the float one except for replacing "...Float..." by "...Int..." in the names of functions and changing the data types.
Both float and integer scalar parameters default to 0.
A float scalar parameter is created by:
| coFloatParam *coModule::addFloatParam (const char *name, const char *desc) |
||
| Description: | Create a float scalar parameter | |
| COVISE states: | Constructor | |
| IN: | name: | Parameter name |
| IN: | desc: | Parameter description |
| Return value: | pointer to newly created port | |
The value of a scalar parameter can be requested/set by the program using:
| float coFloatParam::getValue() | |
| Description: | get Value of a float scalar parameter |
| COVISE states: | all |
| Return value: | Value of the parameter |
| int coFloatParam::setValue(float value) | ||
| Description: | set Value of a float scalar parameter | |
| COVISE states: | all | |
| IN: | value | value to be set |
| Return value: | =0 on error, =1 on success | |
The corresponding commands for the integer scalar parameter are:
coInt32Param *coModule::addInt32Param(const char *name,
const char *desc)
long coInt32Param::getValue()
int coInt32Param::setValue(long value)
A typical code fragment is:
myModule.h
class myModule
{
private:
coFloatParam *p_timestep;
coInt32Param *p_numsteps;
...
}
myModule.cpp
myModule::myModule() // ... build ports and parameters
{
p_timestep=addFloatParam ("timestep","length of a timestep");
p_numsteps=addFloatParam ("numsteps","number of steps");
// set a default values
p_timestep->setValue(0.001);
p_numsteps->setValue(100);
}
myModule::compute(const char *) // compute callback
{
float timestep = p_timestep->getValue();
int numsteps = p_numsteps->getValue(); // we can access it here!
...
}
myModule::param(const char *portname) // param callback
{
if ( strcmp(portname,numsteps->getName()) )
.... do something when the user changes number of steps
}
Sliders can also be either of type float or integer: Both of them have a minimum, maximum and a `current' value, which can be set or requested by the module.
Float sliders default to 0...0.5...1.0, int sliders to 0...127...255.
A Slider parameter is created by:
| coFloatSliderParam *coModule::addFloatSliderParam (const char *name, const char *desc) | ||
| Description: | Create a float slider parameter | |
| COVISE states: | Constructor | |
| IN: | name: | Parameter name |
| IN: | desc: | Parameter description |
| Return value: | pointer to newly created port | |
The value of a slider parameter can be requested/set by the program using:
| void coFloatSliderParam::getValue (float &min, float &max, float &value) | ||
| Description: | get Value of a float slider parameter | |
| COVISE states: | Constructor | |
| IN: | min/max | lower/upper bound of slider |
| IN: | value | current value of slider |
| Return value: | none | |
| void coFloatSliderParam::setValue (float min, float max, float value) | ||
| Description: | set Value of a float slider parameter | |
| COVISE states: | all | |
| IN: | min/max/value | value to be setlike getValue() |
| Return value: | =0 on error, =1 on success | |
Single values can also be requested or set:
float coFloatSliderParam::getMin() float coFloatSliderParam::getMax() float coFloatSliderParam::getValue() void coFloatSliderParam::getMin(float min) void coFloatSliderParam::getMax(float max) void coFloatSliderParam::getValue(float value)
As for the scalar parameter, there are corresponding integer functions, exactly like theirs float counterparts but with "Int" in the name and integer return/param type.
A typical code fragment is:
myModule.h
class myModule
{
private:
coFloatSliderParam *p_relax;
...
}
myModule.cpp
myModule::myModule() // ... build ports and parameters
{
p_relax=addFloatSliderParam ("p_relax","relaxation factor");
p_relax->setValue(0.0,1.0,0.95);
}
myModule::compute(const char *) // compute callback
{
float relax = p_relax->getValue();
...
// if the relaxation is too high, we push it down...
relax = relax * 0.9;
p_relax->setValue(relax);
}
Vectors are parameters with an arbitrary number of scalar values. The number of fields is not limited by the system, but since there is no numbering in the control panel, it should be limited to a small number for clarity reasons.
Both integer and float vector parameters default to 3D null vectors.
A vector parameter is created with a default size of 3 elements by:
| coFloatVectorParam *coModule::addFloatVectorParam (const char *name, const char *desc) | ||
| Description: | Create a float vector parameter | |
| COVISE states: | Constructor | |
| IN: | name: | Parameter name |
| IN: | desc: | Parameter description |
| Return value: | pointer to newly created port | |
This is the only way for a user to specify vector parameters with another size than three elements.
The value of any vector parameter can be requested by the program using:
| float coFloatVectorParam::getValue (int pos) | ||
| Description: | get value of one element in a float vector parameter | |
| COVISE states: | all | |
| IN: | pos | select which element to get |
| Return value: | requested value | |
If the position parameter is out of bounds, a warning is issued and 0 is returned.
A single value of a scalar parameter can also be set by the module:
| int coFloatVectorParam::setValue(int pos, float value) | ||
| Description: | set value of one element in a vector parameter | |
| COVISE states: | all | |
| IN: | pos | select which element to get |
| IN: | value | value to be set |
| Return value: | =0 on error, =1 on success | |
To change the number of values in the field, an array can be used to initialize the parameter:
| int coFloatVectorParam::setValue(int numElem, float *field) | ||
| Description: | set number of elements and set all values | |
| COVISE states: | all | |
| IN: | numElem | select which element to get |
| IN: | field | value to be set |
| Return value: | =0 on error, =1 on success | |
Since 3-dimensional vectors are used very often, commodity functions for dealing with 3D vectors are defined:
| int coFloatVectorParam::setValue (float data0, float data1, float data2) | ||
| Description: | set 3-element vector parameter values | |
| COVISE states: | all | |
| IN: | data1...3 | values to be set |
| Return value: | =0 on error, =1 on success | |
All these functions are also defined for integer vectors:
coIntVectorParam*coModule::addIntSliderParam(const char *name, const char *desc); int coIntVectorParam::getValue(int pos, long &value); int coIntVectorParam::setValue(int pos, long value); int coIntVectorParam::setValue(int numElem, long *field); int coIntVectorParam::setValue(Int data0, long data1, Int data2);
A string is a 0-terminated sequence of characters.
The default value is the string "no default val".
A string parameter is created by:
| CoStringParam *coModule::addStringParam (const char *name, const char *desc) | ||
| Description: | Create a string parameter | |
| COVISE states: | Constructor | |
| IN: | name: | Parameter name |
| IN: | desc: | Parameter description |
| Return value: | pointer to newly created port | |
The value of a string parameter can be requested by the program using:
| const char *coStringParam::getValue() | |
| Description: | get value of a string parameter |
| COVISE states: | all |
| Return value: | Value of the parameter |
The value of a string parameter can also be set by the module:
| int coStringParam::setValue(const char *val) | ||
| Description: | set value of a string parameter | |
| COVISE states: | all | |
| IN: | val | new value for the parameter |
| Return value: | =0 on error, =1 on success | |
A File Browser parameter allows the selection of a file on the host the module is running on.
The File Browser parameter cannot be updated by the module. setValue calls outside the constructors are ignored.
A Browser parameter is created by:
| coFileBrowserParam *coModule::addFileBrowserParam (const char *name, const char *desc) | ||
| Description: | Create a browser parameter | |
| COVISE states: | Constructor | |
| IN: | name: | Parameter name |
| IN: | desc: | Parameter description |
| Return value: | pointer to newly created port | |
The value of a browser parameter can be requested by the program using:
| const char *coFileBrowserParam::getValue() | |
| Description: | get filename selected in a browser parameter |
| COVISE states: | all |
| Return value: | value of the parameter |
The start value of a browser parameter must be set by the module in the constructor
| int void coFileBrowserParam::setValue (const char *defaultFile, const char *mask) | ||
| Description: | set the initial value of a file browser | |
| COVISE states: | all | |
| IN: | defaultFile | default file name with path |
| IN: | mask | file selection mask, e.g. "*.dat" |
| Return value: | =0 on error, =1 on success | |
A choice parameter allows to select one entry from a list of given choice strings.
A choice parameter is created by:
| coChoiceParam *coModule::addChoiceParam (const char *name, const char *desc) | ||
| Description: | Show a parameter in control panel | |
| COVISE states: | Constructor | |
| IN: | name: | Parameter name |
| IN: | desc: | Parameter description |
| Return value: | pointer to newly created port | |
The active choice list entry can be retrieved by:
| int coChoiceParam::getValue() | |
| Description: | get value of a choice parameter |
| COVISE states: | all |
| Return value: | active choice, count starts with 1 |
The choice list can be set by:
| int coChoiceParam::setValue(const char *val) | ||
| Description: | set value of a choice parameter | |
| COVISE states: | all | |
| IN: | val | new value for the parameter |
| Return value: | =0 on error, =1 on success | |
| int coChoiceParam::setValue
(int num, const char * const *label, int active) |
||
| Description: | set value of a choice parameter | |
| COVISE states: | all | |
| IN: | num | number of entries |
| IN: | label | array of strings:
define as `char *arr[num]' |
| IN: | active | pre-set value: count starts with 1 |
| Return value: | =0 on error, =1 on success | |
If you want to use the same contents of a choice parameter, even if it appears at a different position (number) use the update function:
| int coChoiceParam::updateValue
(int num, const char * const *label, int active) |
||
| Description: | set value of a choice parameter | |
| COVISE states: | all | |
| IN: | num | number of entries |
| IN: | label | array of strings:
define as `char *arr[num]' |
| IN: | active | pre-set value: count starts with 1, use current label if possible. If this is possible, ignore active |
| Return value: | =0 on error, =1 on success | |
The current value can be set by:
| int coFloatVectorParam::setValue(int pos, float value) | ||
| Description: | set value of one element in a vector parameter | |
| COVISE states: | all | |
| IN: | pos | select which element to get |
| IN: | value | value to be set |
| Return value: | =0 on error, =1 on success | |
See the example code $COVISEDIR/src/examples/UpdateChoice for an example using all features of the Choice parameter.
Parameters can be grouped in the control panel. The syntax for grouping parameters is:
paraSwitch("top_switch","Now switch Parameters"); // switch with
name and label
paraCase("First possibility label"); // first possibility
// ... all parameters we want to change in this group
paraEndCase();
paraCase("other possibility"); // Next switch possibility
// ... all parameters we want to change in this group
// second level of switching
paraSwitch("subSwitch","Sub-Cases"); // nested switch
paraCase("one case");
// ...parameters // one case
paraEndCase();
paraCase("other case");
// ...parameters
paraEndCase();
// second level of switching ends here
paraEndSwitch();
// The `Scalar' case ends here
paraEndCase();
paraEndSwitch();
Each paraSwitch call creates a `master' choice parameter, which automatically shows and hides the parameters of its paraCase groups. The name of the choice is the first parameter of the paraSwitch command, while the labels of the paraSwitch and all following paraCase commands are automatically added to the choice list. As the first choice, the `master' displays its own label and shows none of its cases.
The user can access the switch choices as usual choice parameters using the setValue command, e.g. to change the choice labels, but the assignment between choice result number and paraCase can not be influenced, so choice number 1 always is `no parameters', number 2 the first case, number 3 the second and so on. This feature will typically be used to de-activate complete cases from the control panel.
Notice: the module set-up panel will always show ALL parameters of the module.
The example program TestUIF shows the implementation of a 2-level hierarchy of switched parameter groups.
| coChoiceParam *coModule::paraSwitch(const char *choiceName, const char *label) | ||
| Description: | Start parameter switching group,
define name and top label of choice |
|
| COVISE states: | Constructor | |
| IN: | choiceName | Unique parameter port name |
| IN: | label | Label for the choice |
| Return value: | Pointer to the `master' choice port | |
| void coModule::paraEndSwitch() | |
| Description: | End parameter switching group |
| COVISE states: | Constructor |
| int coModule::paraCase(const char *label) | ||
| Description: | Start a case within a switched group and give corresponding choice label | |
| COVISE states: | Constructor | |
| IN: | label | Label for the choice |
| Return value: | -1 on error, 0 on success | |
| void coModule::paraEndCase() | |
| Description: | End a group within a switched parameter area |
| COVISE states: | Constructor |
COVISE has a central configuration database, which resides in XML files in the $COVISEDIR/config directory or in the .covise subdirectory of the user's home directory.
The configuration database is accessed by calling static methods of the coCoviseConfig singleton.
Several functions are provided to access entries in the configuration database. Most of these access functions require a single 'entry' parameter Scope.Var. This 'entry' parameter describes the path along which to descend in the tree of nested XML elements. Elements are separated by a dot ("."). However, the first two path elements are defined implictly (e. g. "COCONFIG.GLOBAL") and must not be specified. For all data types, there are two kinds of query functions. Those taking only an 'entry', return the value of the "value" attribute of the corresponding XML element. For querying another attribute, you have to use the method with 'variable' and 'entry' arguments.
Consider the following configuration file:
<?xml version="1.0"?>
<COCONFIG version="1">
<GLOBAL>
<Module>
<MyModule>
<BufferSize value="1024" />
</MyModule>
<Module>
</GLOBAL>
</COCONFIG>
The "value" attribute of "BufferSize" could be queried with
coCoviseConfig::getInt("value", "Module.MyModule.BufferSize") or
coCoviseConfig::getInt("Module.MyModule.BufferSize").
| const char *getEntry(const char *entry) | ||
| const char *getEntry(const char *variable, const char *entry) | ||
| Description: | get a single string entry | |
| IN: | entry | path to XML tag |
| IN: | variable | attribute, the value of which should be returned |
| Returns | value of configuration | |
| int getInt(const char *entry) | ||
| int getInt(const char *variable, const char *entry) | ||
| Description: | get a single string entry | |
| IN: | entry | path to XML tag |
| IN: | variable | attribute, the value of which should be returned |
| Returns | value of configuration | |
| long getLong(const char *entry) | ||
| long getLong(const char *variable, const char *entry) | ||
| Description: | get a single string entry | |
| IN: | entry | path to XML tag |
| IN: | variable | attribute, the value of which should be returned |
| Returns | value of configuration | |
| float getFloat(const char *entry) | ||
| float getFloat(const char *variable, const char *entry) | ||
| Description: | get a single string entry | |
| IN: | entry | path to XML tag |
| IN: | variable | attribute, the value of which should be returned |
| Returns | value of configuration | |
| bool isOn(const char *entry) | ||
| bool isOn(const char *variable, const char *entry) | ||
| Description: | get a single string entry | |
| IN: | entry | path to XML tag |
| IN: | variable | attribute, the value of which should be returned |
| Returns | value of configuration | |
| const char **getScopeEntries(const char *scope)) | ||
| Description: | get all entries of one scope | |
| IN: | scope | name of scope |
| Returns | NULL-terminated array, alternating
name0,value0,name1,value1,...valuen,NULL |
|
| const char *getScopeEntry (const char *scope, const char *name) | ||
| Description: | get a single entry | |
| IN: | scope | Scope to be looked in |
| IN: | name | Name of variable |
| Returns | value of scope.name | |
| Previous | Next |
| Authors: Martin Aumüller, Ruth Lang, Daniela Rainer, Jürgen Schulze-Döbold, Andreas Werner, Peter Wolf, Uwe Wössner |
| Copyright © 1993-2022 HLRS, 2004-2014 RRZK, 2005-2014 Visenso |
COVISE Version 2021.12
|