QVPropertyContainer Class Reference
[QVision core classes.]

Base class for dynamic property container objects. More...

#include <qvcore/qvpropertycontainer.h>

Inherited by QVCamera, QVImageCanvas, and QVWorker.

List of all members.

Public Types

enum  LinkType { AsynchronousLink, SynchronousLink }
 Semantics for a link between QVPropertyContainers. More...
enum  PropertyInputOutputFlag { noInputOutputFlag = 0x0, inputFlag = 0x1, outputFlag = 0x2 }
 Flags for each property. More...

Public Member Functions

 QVPropertyContainer (const QString name=QString())
virtual ~QVPropertyContainer ()
 Virtual destructor.
void setName (const QString name)
 Sets a new string identifier for a QVPropertyContainer.
const QString getName () const
 Retrieves identifier QString of the object.
QList< QString > getPropertyList () const
 Gets list of properties of the QVPropertyContainer.
template<class Type>
QList< QString > getPropertyListByType () const
 Gets the names of the properties of a given type.
template<class Type>
bool isType (QString name, bool *ok=NULL) const
 Checks if a property is of a given type.
bool containsProperty (const QString name) const
 Check whether the property holder has a given property.
QVariant::Type getPropertyType (const QString name, bool *ok=NULL) const
 Given a property identifying QString (see getPropertyList() function above), returns the type of the property.
template<class Type>
bool addProperty (const QString name, const PropertyInputOutputFlags flags=inputFlag, const Type &value=Type(), const QString info=QString("(Info not available)"))
 Registers a new property in the property holder.
template<class Type>
bool addProperty (const QString name, const PropertyInputOutputFlags flags, const Type &value, const QString info, const Type &minValue, const Type &maxValue)
 Registers a new property in the property holder.
bool addPropertyFromQVariant (const QString &name, const PropertyInputOutputFlags flags, QVariant variant, const QString info)
 Registers a new property in the property holder.
bool removeProperty (const QString name)
 De-registers a property in the property holder.
bool setPropertyRange (const QString name, const double &minimum, const double &maximum)
bool setPropertyRange (QString name, int &minimum, int &maximum)
bool hasRange (const QString name) const
 Tells if a range has been set for the property.
PropertyInputOutputFlags getPropertyFlags (const QString name)
 Returns flags for a property.
bool isInput (const QString name) const
 Tells if a property is of the input type.
bool isOutput (const QString name) const
 Tells if a property is of the output type.
bool isLinkedInput (const QString name) const
 Tells if a property is of the input type and is linked.
bool isLinkedOutput (const QString name) const
 Tells if a property is of the output type and is linked.
template<class Type>
bool setPropertyValue (const QString name, const Type &value)
 Sets value for property.
template<class Type>
Type getPropertyValue (const QString name, bool *ok=NULL) const
 Method to get the actual value of a property.
QVariant getPropertyQVariantValue (const QString name, bool *ok=NULL) const
 Method to get the value of a property as a QVariant.
template<class Type>
Type getPropertyMaximum (const QString name, bool *ok=NULL) const
 Method to get the maximum value for a property.
template<class Type>
Type getPropertyMinimum (const QString name, bool *ok=NULL) const
 Method to get the minimum value for a property.
QString getPropertyInfo (const QString name, bool *ok=NULL) const
 Method to get the info QString for int typed property.
QString getLastError () const
 Gets the (possible) last error string.
const QString infoInputProperties () const
 Formatted description of properties (useful to show help).
bool linkProperty (QString sourcePropertyName, QVPropertyContainer *destinyContainer, QString destinyPropertyName, LinkType linkType)
 Links properties among QVPropertyContainer's.
void unlink ()
 Completely unlinks a property holder.

Protected Member Functions

template<class Type>
bool setPropertyRange2 (const QString name, const Type &minimum, const Type &maximum)
void readInputProperties ()
 Read linked input properties from other QVPropertyContainer's.
void writeOutputProperties ()
 Write linked output properties to other QVPropertyContainer's.
template<class Type>
bool parseArgument (const QString parameter, const QString value)
 Parses a property value from a string.
void setLastError (QString str) const
 Sets an error string message.


Detailed Description

Base class for dynamic property container objects.

Parent class for objects to which we want to add execution-time accessible properties. Holds methods to register new properties, read and set their values, and to get human readable information about them (useful to show a related help text). It also supports minimum and maximum checking for integer and double values, parsing from the command line for QString, bool, integer and double types.

This introspection functionality is in a sense similar to that given by QObject, but it does not inherit from it, so we can have properties for classes which need not contain the Q_OBJECT macro, thus not needing to be forcibly in a .h file. It also allows for direct access of the QVApplication to variables created by the final programmer, in order to, for example, show associated widgets to property so that the user can directly access to them.

Also, one of the most important features that this introspection adds to the QVision framework is the ability to link properties among different property holders, in the sense that the "input properties" of one of them can be "linked" to be read in execution time from the "output properties" of another holder. The main application of this feature is to be able to program independently different threads of execution (QVThread), which can be later used and "linked" afterwards by other programmers, thus making the programmed QVThread easily reusable.

Todo:
Parámetro --help de línea de comandos no muestra propiedades de los workers.

Definition at line 73 of file qvpropertycontainer.h.


Member Enumeration Documentation

enum QVPropertyContainer::LinkType

Semantics for a link between QVPropertyContainers.

If a link between a source property of a QVPropertyContainer object A and a corresponding destination property of another one B is declared as synchronous, it means that every time that the readInputProperties() method is executed on B, the system assures that one (and just one) corresponding call to the writeOutputProperties() has been previously executed on A. In the (common) case of a link between two QVThread's, that would mean, for example, that each running of the source QVThread corresponds exactly to another (posterior) running of the destination QVThread.

That is equivalent to say that every data produced by the source is always consumed by the destination, so no data is ever "lost" in that sense. The obvious cost is that both threads will have to run at the speed of the slowest, of course.

The alternative is an asynchronous link, in which the only thing that the system assures on the properties read by the destination is that, in the case of a multiple link (several input properties of B connected to several corresponding output properties of B), all of them correspond to the same iteration of the source (more precisely, to the last execution of the writeOutputProperties() method in A, independently of the specific sequence number of that iteration). We say that the output is 'coherent' in all the properties linked this way. But, as has been already said, the iterations are not linked in the temporal sense, so, for example, for the case of QVThreads, both could run asynchronously, and at different speeds.

See also the QVPropertyContainer::linkProperty() method.

Enumerator:
AsynchronousLink 
SynchronousLink 

Definition at line 108 of file qvpropertycontainer.h.

enum QVPropertyContainer::PropertyInputOutputFlag

Flags for each property.

Currently, if a property is of the "input type" and/or "output type" are the only supported flags.

Enumerator:
noInputOutputFlag 
inputFlag 
outputFlag 

Definition at line 114 of file qvpropertycontainer.h.


Constructor & Destructor Documentation

QVPropertyContainer::QVPropertyContainer ( const QString  name = QString()  ) 

Constructs a QVPropertyContainer with a given string identifier.

Parameters:
name Identifier for the object to be created.

Definition at line 27 of file qvpropertycontainer.cpp.

References qvApp.

QVPropertyContainer::~QVPropertyContainer (  )  [virtual]

Virtual destructor.

Frees the QVPropertyContainer, and all its associated links. Besides, this destructor can (and in many cases should!) also be reimplemented in subclasses.

Definition at line 46 of file qvpropertycontainer.cpp.

References qvApp.


Member Function Documentation

void QVPropertyContainer::setName ( const QString  name  ) 

Sets a new string identifier for a QVPropertyContainer.

Parameters:
name New string identifier for the object.

Definition at line 53 of file qvpropertycontainer.cpp.

Referenced by QVImageCanvas::QVImageCanvas().

const QString QVPropertyContainer::getName (  )  const

Retrieves identifier QString of the object.

Returns:
QString identifying the property holder object.

Definition at line 56 of file qvpropertycontainer.cpp.

Referenced by QVApplication::deregisterQVPropertyContainer(), QVApplication::exec(), infoInputProperties(), QVMPlayerCamera::link(), linkProperty(), parseArgument(), QVGUI::QVGUI(), QVImageCanvas::QVImageCanvas(), QVApplication::registerQVPropertyContainer(), setPropertyRange(), and setPropertyRange2().

QList< QString > QVPropertyContainer::getPropertyList (  )  const

Gets list of properties of the QVPropertyContainer.

Retrieves the names of the properties registered in the property holder, in a QStringList.

Returns:
QStringList of names of properties in the object.

Definition at line 59 of file qvpropertycontainer.cpp.

template<class Type>
QList<QString> QVPropertyContainer::getPropertyListByType (  )  const [inline]

Gets the names of the properties of a given type.

Retrieves the names of those properties, registered in the property holder, which hold values of the type given by the template parameter, in a QStringList.

Returns:
QList of identifying QStrings.

Definition at line 155 of file qvpropertycontainer.h.

template<class Type>
bool QVPropertyContainer::isType ( QString  name,
bool *  ok = NULL 
) const [inline]

Checks if a property is of a given type.

Returns true if type passed as template parameter equals type of value contained in a property.

Parameters:
name QString identifying the property.
ok Pointer to bool value which is set to true if property exists, and to false otherwise.
Returns:
True if property has same type as parameter template.

Definition at line 175 of file qvpropertycontainer.h.

Referenced by QVMPlayerCamera::link().

bool QVPropertyContainer::containsProperty ( const QString  name  )  const

Check whether the property holder has a given property.

Parameters:
name QString identifying the property.
Returns:
True if the QVPropertyContainer contains a property with the given name, otherwise returns false.

Definition at line 62 of file qvpropertycontainer.cpp.

QVariant::Type QVPropertyContainer::getPropertyType ( const QString  name,
bool *  ok = NULL 
) const

Given a property identifying QString (see getPropertyList() function above), returns the type of the property.

Parameters:
name QString identifying the property.
ok Pointer to bool value which is set to true if property exists, and to false otherwise.
Returns:
a QVariant::Type value. Note that user defined properties will return QVariant::UserType value.

Definition at line 65 of file qvpropertycontainer.cpp.

Referenced by infoInputProperties(), and linkProperty().

template<class Type>
bool QVPropertyContainer::addProperty ( const QString  name,
const PropertyInputOutputFlags  flags = inputFlag,
const Type &  value = Type(),
const QString  info = QString("(Info not available)") 
) [inline]

Registers a new property in the property holder.

Parameters:
name Name of the new property.
value Initial value for the property.
info Info string for the property.
flags Whether the property is input, output, or both.
Returns:
True if property was correctly added, false otherwise.

Definition at line 214 of file qvpropertycontainer.h.

template<class Type>
bool QVPropertyContainer::addProperty ( const QString  name,
const PropertyInputOutputFlags  flags,
const Type &  value,
const QString  info,
const Type &  minValue,
const Type &  maxValue 
) [inline]

Registers a new property in the property holder.

Parameters:
name Name of the new property.
value Initial value for the property.
info Info string for the property.
flags Whether the property is input, output, or both.
minValue Minimum value for the property.
maxValue Maximum value for the property.
Returns:
True if property was correctly added, false otherwise.

Definition at line 235 of file qvpropertycontainer.h.

bool QVPropertyContainer::addPropertyFromQVariant ( const QString &  name,
const PropertyInputOutputFlags  flags,
QVariant  variant,
const QString  info 
) [inline]

Registers a new property in the property holder.

Parameters:
name Name of the new property.
flags Whether the property is input, output, or both.
variant Initial QVariant value for the property
info Info string for the property.
Returns:
True if property was correctly added, false otherwise.

Definition at line 252 of file qvpropertycontainer.h.

Referenced by QVImageCanvas::linkProperty().

bool QVPropertyContainer::removeProperty ( const QString  name  ) 

De-registers a property in the property holder.

Parameters:
name Name of the property to delete.
Returns:
True if property was correctly removed, false otherwise.

Definition at line 77 of file qvpropertycontainer.cpp.

bool QVPropertyContainer::setPropertyRange ( const QString  name,
const double &  minimum,
const double &  maximum 
)

Deprecated:
Should set range in the constructor.

Definition at line 92 of file qvpropertycontainer.cpp.

References getName(), qvApp, and setLastError().

Referenced by setPropertyRange().

bool QVPropertyContainer::setPropertyRange ( QString  name,
int &  minimum,
int &  maximum 
)

Deprecated:
Should set range in the constructor.

Definition at line 117 of file qvpropertycontainer.cpp.

References setPropertyRange().

bool QVPropertyContainer::hasRange ( const QString  name  )  const

Tells if a range has been set for the property.

Parameters:
name Name of the property.
Returns:
True if there exist a range for the property.

Definition at line 120 of file qvpropertycontainer.cpp.

PropertyInputOutputFlags QVPropertyContainer::getPropertyFlags ( const QString  name  )  [inline]

Returns flags for a property.

Parameters:
name Name of the property.
Returns:
Flags for the property.

Definition at line 289 of file qvpropertycontainer.h.

bool QVPropertyContainer::isInput ( const QString  name  )  const

Tells if a property is of the input type.

Parameters:
name Name of the property.
Returns:
True if the property is of the input type.

Definition at line 123 of file qvpropertycontainer.cpp.

References inputFlag.

Referenced by infoInputProperties().

bool QVPropertyContainer::isOutput ( const QString  name  )  const

Tells if a property is of the output type.

Parameters:
name Name of the property.
Returns:
True if the property is of the output type.

Definition at line 126 of file qvpropertycontainer.cpp.

References outputFlag.

bool QVPropertyContainer::isLinkedInput ( const QString  name  )  const

Tells if a property is of the input type and is linked.

Parameters:
name Name of the property.
Returns:
True if the property is of the input type and is linked.

Definition at line 129 of file qvpropertycontainer.cpp.

bool QVPropertyContainer::isLinkedOutput ( const QString  name  )  const

Tells if a property is of the output type and is linked.

Parameters:
name Name of the property.
Returns:
True if the property is of the output type and is linked.

Definition at line 132 of file qvpropertycontainer.cpp.

template<class Type>
bool QVPropertyContainer::setPropertyValue ( const QString  name,
const Type &  value 
) [inline]

Sets value for property.

If the property is not writable, this function will return false, and won't change property value. Besides, if there is a [minimum,maximum] range and the value is not in it, also fails to set the value. In both cases the function issues a warning through stderr, and returns false.

Parameters:
name Identifying QString for the property.
value Value to set the property with.
Returns:
True if the value was set successfully.

Definition at line 325 of file qvpropertycontainer.h.

template<class Type>
Type QVPropertyContainer::getPropertyValue ( const QString  name,
bool *  ok = NULL 
) const [inline]

Method to get the actual value of a property.

Parameters:
name Identifying QString for the property.
ok Pointer to bool value which is set to true if property exists, and to false otherwise.
Returns:
Actual value for the property.

Definition at line 343 of file qvpropertycontainer.h.

QVariant QVPropertyContainer::getPropertyQVariantValue ( const QString  name,
bool *  ok = NULL 
) const

Method to get the value of a property as a QVariant.

Parameters:
name Identifying QString for the property.
ok Pointer to bool value which is set to true if property exists, and to false otherwise.
Returns:
Actual value for the property.

Definition at line 135 of file qvpropertycontainer.cpp.

Referenced by QVImageCanvas::linkProperty().

template<class Type>
Type QVPropertyContainer::getPropertyMaximum ( const QString  name,
bool *  ok = NULL 
) const [inline]

Method to get the maximum value for a property.

Parameters:
name Identifying QString for the property.
ok Pointer to bool value which is set to true if property exists, and to false otherwise.
Returns:
Maximum value for the property.

Definition at line 366 of file qvpropertycontainer.h.

template<class Type>
Type QVPropertyContainer::getPropertyMinimum ( const QString  name,
bool *  ok = NULL 
) const [inline]

Method to get the minimum value for a property.

Parameters:
name Identifying QString for the property.
ok Pointer to bool value which is set to true if property exists, and to false otherwise.
Returns:
Minimum value for the property.

Definition at line 393 of file qvpropertycontainer.h.

QString QVPropertyContainer::getPropertyInfo ( const QString  name,
bool *  ok = NULL 
) const

Method to get the info QString for int typed property.

Parameters:
name Identifying QString for the property.
ok Pointer to bool value which is set to true if property exists, and to false otherwise.
Returns:
The info QString about the property, if defined. Empty QString otherwise.

Definition at line 144 of file qvpropertycontainer.cpp.

Referenced by infoInputProperties(), and QVImageCanvas::linkProperty().

QString QVPropertyContainer::getLastError (  )  const

Gets the (possible) last error string.

Returns:
A QString indicating the last error that occurred in an operation on the the property, if defined. Empty QString otherwise.

Definition at line 153 of file qvpropertycontainer.cpp.

Referenced by QVApplication::exec().

const QString QVPropertyContainer::infoInputProperties (  )  const

Formatted description of properties (useful to show help).

Obtains a human readable description QString of all the object's properties that have some associated info (otherwise they are ignored).

Returns:
QString containing human readable list of properties, and info about them.

Definition at line 158 of file qvpropertycontainer.cpp.

References getName(), getPropertyInfo(), getPropertyType(), and isInput().

bool QVPropertyContainer::linkProperty ( QString  sourcePropertyName,
QVPropertyContainer destinyContainer,
QString  destinyPropertyName,
LinkType  linkType 
)

Links properties among QVPropertyContainer's.

This method safely links properties among property holders in a thread safe manner. It is mainly used when programming multithreaded applications -with multiple QVWorkers-, but also, for example, when linking workers (running in an independent thread) with GUI widgets (running in the main thread).

The pointer this corresponds to the source QVPropertyContainer.

See also QVPropertyContainer::LinkType.

Parameters:
sourcePropertyName Identifying QString for the source property.
destinyContainer Pointer to the destination QVPropertyContainer.
destinyPropertyName Identifying QString for the destination property.
linkType Synchronous or asynchronous.
Returns:
TRUE if the connection went OK, FALSE otherwise (for example, due to type mismatch, some of the properties does not exists, or whatever).

Definition at line 286 of file qvpropertycontainer.cpp.

References getName(), getPropertyType(), inputFlag, inputLinks, io_flags, link_flags, outputFlag, outputLinks, qvApp, and setLastError().

Referenced by QVMPlayerCamera::link(), and QVImageCanvas::linkProperty().

void QVPropertyContainer::unlink (  ) 

Completely unlinks a property holder.

Deletes all the input and output links associated to the holder. Of course, all the corresponding necessary unlinks in other property holders are also performed.

Definition at line 355 of file qvpropertycontainer.cpp.

Referenced by QVWorker::run().

void QVPropertyContainer::readInputProperties (  )  [protected]

Read linked input properties from other QVPropertyContainer's.

This is a protected function that should be called from the subclasses of QVPropertyContainer just before starting to use any input property linked to another property holder (for example, just before the worker() function in a QVWorker, or just before the viewer() function in a QVCanvas).

Definition at line 381 of file qvpropertycontainer.cpp.

References SynchronousLink.

Referenced by QVWorker::run().

void QVPropertyContainer::writeOutputProperties (  )  [protected]

Write linked output properties to other QVPropertyContainer's.

This is a protected function that should be called from the subclasses of QVPropertyContainer just after having a new set of output properties ready to be read by another property holder (for example, just after the worker() function in a QVWorker, or just after the viewer() function in a QVCanvas). The effect is that a coherent state of the linked output properties is saved, so other QVPropertyContainer's can safely read from it -while we can be writing new values corresponding to a new iteration-.

Definition at line 415 of file qvpropertycontainer.cpp.

References SynchronousLink.

Referenced by QVMPlayerCamera::grab(), and QVWorker::run().

bool QVPropertyContainer::parseArgument< QString > ( const QString  parameter,
const QString  value 
) [inline, protected]

Parses a property value from a string.

Parses a QString containing the value for a property (mainly useful when initializing it from the command line). QVPropertyContainer implements a series of default parsers (namely for bool, int, double and QString properties). But the method is templatized to allow customization of the parsed QString, if we wish to add new parameter types in the subclasses. In that case, users should specialize the corresponding template this way:

 template <> bool MyDerivedQVPropertyContainer::parseArgument<MyType>(const QString parameter, const QString value)
 {
     bool ok;
     MyType myVar1 = myParserForMyType1(value,&ok);
     if(ok) { // parsing OK 
          setPropertyValue<MyType>(parameter,myVar1);
          return TRUE;
     } else { // parsing failed
          QString errorString = "MyDerivedQVPropertyContainer::parseArgument(): holder "
          + getName() + ": value " + value
          + " is not a valid MyType value for parameter " + parameter + ".\n";
          setLastError(errorString);
          return FALSE;
     }
 }
The format of the input params in the command line should be the following:
--[holder:]<name>=<value>
where

Definition at line 663 of file qvpropertycontainer.h.

References getName().

void QVPropertyContainer::setLastError ( QString  str  )  const [protected]

Sets an error string message.

Sets an error string message corresponding to the last error that occurred in an operation on the QVPropertyContainer (if such an error occurred). If no error occurred since the creation of the object, the string will be empty. The method is const because it only modifies the error message (which is mutable), not the object itself.

Definition at line 469 of file qvpropertycontainer.cpp.

Referenced by linkProperty(), setPropertyRange(), and setPropertyRange2().


The documentation for this class was generated from the following files:
Generated on Fri Feb 22 18:26:57 2008 for QVision by  doxygen 1.5.3