#include <qvcore/qvpropertyholder.h>
Public Types | |
enum | LinkType { AsynchronousLink, SynchronousLink } |
Semantics for a link between QVPropertyHolders. More... | |
enum | PropertyInputOutputFlag { noInputOutputFlag = 0x0, inputFlag = 0x1, outputFlag = 0x2 } |
Flags for each property. More... | |
Public Member Functions | |
QVPropertyHolder (const QString name=QString()) | |
virtual | ~QVPropertyHolder () |
Virtual destructor. | |
void | setName (const QString name) |
Sets a new string identifier for a QVPropertyHolder. | |
const QString | getName () const |
Retrieves identifier QString of the object. | |
QList< QString > | getPropertyList () const |
Gets list of properties of the QVPropertyHolder. | |
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 | removeProperty (const QString name) |
De-registers a property in the property holder. | |
bool | setPropertyRange (const QString name, const double &minimum, const double &maximum) |
Sets minimum and maximum value for an int or double property. | |
bool | setPropertyRange (const char *name, int &minimum, int &maximum) |
bool | setPropertyRange (QString name, int &minimum, int &maximum) |
DEPRECATED: set minimum and maximum value directly into constructor. | |
bool | hasRange (const QString name) |
bool | isInput (const QString name) |
Tells if a property is of the input type. | |
bool | isOutput (const QString name) |
Tells if a property is of the output type. | |
bool | isLinkedInput (const QString name) |
Tells if a property is of the input type and is linked. | |
bool | isLinkedOutput (const QString name) |
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 prop_orig, QVPropertyHolder *qvp_dest, QString prop_dest, LinkType link_type) |
Links properties among QVPropertyHolder'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 QVPropertyHolder's. | |
void | writeOutputProperties () |
Write linked output properties to other QVPropertyHolder'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. |
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.
Definition at line 71 of file qvpropertyholder.h.
Semantics for a link between QVPropertyHolders.
If a link between a source property of a QVPropertyHolder 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 QVPropertyHolder::linkProperty() method.
Definition at line 106 of file qvpropertyholder.h.
Flags for each property.
Currently, if a property is of the "input type" and/or "output type" are the only supported flags.
Definition at line 112 of file qvpropertyholder.h.
QVPropertyHolder::QVPropertyHolder | ( | const QString | name = QString() |
) |
Constructs a QVPropertyHolder with a given string identifier.
name | Identifier for the object to be created. |
Definition at line 27 of file qvpropertyholder.cpp.
References qvApp.
QVPropertyHolder::~QVPropertyHolder | ( | ) | [virtual] |
Virtual destructor.
Frees the QVPropertyHolder, and all its associated links. Besides, this destructor can (and in many cases should!) also be reimplemented in subclasses.
Definition at line 44 of file qvpropertyholder.cpp.
References qvApp.
void QVPropertyHolder::setName | ( | const QString | name | ) |
Sets a new string identifier for a QVPropertyHolder.
name | New string identifier for the object. |
Definition at line 51 of file qvpropertyholder.cpp.
const QString QVPropertyHolder::getName | ( | ) | const |
Retrieves identifier QString of the object.
Definition at line 54 of file qvpropertyholder.cpp.
Referenced by QVApplication::exec(), infoInputProperties(), linkProperty(), parseArgument(), setPropertyRange(), and setPropertyRange2().
QList< QString > QVPropertyHolder::getPropertyList | ( | ) | const |
Gets list of properties of the QVPropertyHolder.
Retrieves the names of the properties registered in the property holder, in a QStringList.
Definition at line 57 of file qvpropertyholder.cpp.
QList<QString> QVPropertyHolder::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.
Definition at line 153 of file qvpropertyholder.h.
bool QVPropertyHolder::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.
name | QString identifying the property. | |
ok | Pointer to bool value which is set to true if property exists, and to false otherwise. |
Definition at line 173 of file qvpropertyholder.h.
bool QVPropertyHolder::containsProperty | ( | const QString | name | ) | const |
Check whether the property holder has a given property.
name | QString identifying the property. |
Definition at line 60 of file qvpropertyholder.cpp.
QVariant::Type QVPropertyHolder::getPropertyType | ( | const QString | name, | |
bool * | ok = NULL | |||
) | const |
Given a property identifying QString (see getPropertyList() function above), returns the type of the property.
name | QString identifying the property. | |
ok | Pointer to bool value which is set to true if property exists, and to false otherwise. |
Definition at line 63 of file qvpropertyholder.cpp.
Referenced by infoInputProperties(), and linkProperty().
bool QVPropertyHolder::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.
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. |
Definition at line 212 of file qvpropertyholder.h.
bool QVPropertyHolder::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.
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. |
Definition at line 239 of file qvpropertyholder.h.
bool QVPropertyHolder::removeProperty | ( | const QString | name | ) |
De-registers a property in the property holder.
name | Name of the property to delete. |
Definition at line 75 of file qvpropertyholder.cpp.
bool QVPropertyHolder::setPropertyRange | ( | const QString | name, | |
const double & | minimum, | |||
const double & | maximum | |||
) |
Sets minimum and maximum value for an int or double property.
If the current value is not in the specified range, fails to set the range and returns false. Otherwise it returns true. (Note.- Can also be used to set integer min and max values, using a simple (automatic) int to double cast.) DEPRECATED: set minimum and maximum value directly into constructor.
name | Name of the new property. | |
minimum | Minimum value for the property. | |
maximum | Maximum value for the property. |
Definition at line 90 of file qvpropertyholder.cpp.
References getName(), qvApp, and setLastError().
Referenced by setPropertyRange().
bool QVPropertyHolder::setPropertyRange | ( | const char * | name, | |
int & | minimum, | |||
int & | maximum | |||
) |
DEPRECATED: set minimum and maximum value directly into constructor.
Definition at line 114 of file qvpropertyholder.cpp.
References setPropertyRange().
bool QVPropertyHolder::hasRange | ( | const QString | name | ) |
Tells if a range has been set for the property.
name | Name of the property. |
Definition at line 120 of file qvpropertyholder.cpp.
bool QVPropertyHolder::isInput | ( | const QString | name | ) |
Tells if a property is of the input type.
name | Name of the property. |
Definition at line 123 of file qvpropertyholder.cpp.
References inputFlag.
bool QVPropertyHolder::isOutput | ( | const QString | name | ) |
Tells if a property is of the output type.
name | Name of the property. |
Definition at line 126 of file qvpropertyholder.cpp.
References outputFlag.
bool QVPropertyHolder::isLinkedInput | ( | const QString | name | ) |
Tells if a property is of the input type and is linked.
name | Name of the property. |
Definition at line 129 of file qvpropertyholder.cpp.
bool QVPropertyHolder::isLinkedOutput | ( | const QString | name | ) |
Tells if a property is of the output type and is linked.
name | Name of the property. |
Definition at line 132 of file qvpropertyholder.cpp.
bool QVPropertyHolder::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.
name | Identifying QString for the property. | |
value | Value to set the property with. |
Definition at line 316 of file qvpropertyholder.h.
Type QVPropertyHolder::getPropertyValue | ( | const QString | name, | |
bool * | ok = NULL | |||
) | const [inline] |
Method to get the actual value of a property.
name | Identifying QString for the property. | |
ok | Pointer to bool value which is set to true if property exists, and to false otherwise. |
Definition at line 334 of file qvpropertyholder.h.
QVariant QVPropertyHolder::getPropertyQVariantValue | ( | const QString | name, | |
bool * | ok = NULL | |||
) | const |
Method to get the value of a property as a QVariant.
name | Identifying QString for the property. | |
ok | Pointer to bool value which is set to true if property exists, and to false otherwise. |
Definition at line 135 of file qvpropertyholder.cpp.
Type QVPropertyHolder::getPropertyMaximum | ( | const QString | name, | |
bool * | ok = NULL | |||
) | const [inline] |
Method to get the maximum value for a property.
name | Identifying QString for the property. | |
ok | Pointer to bool value which is set to true if property exists, and to false otherwise. |
Definition at line 357 of file qvpropertyholder.h.
Type QVPropertyHolder::getPropertyMinimum | ( | const QString | name, | |
bool * | ok = NULL | |||
) | const [inline] |
Method to get the minimum value for a property.
name | Identifying QString for the property. | |
ok | Pointer to bool value which is set to true if property exists, and to false otherwise. |
Definition at line 384 of file qvpropertyholder.h.
QString QVPropertyHolder::getPropertyInfo | ( | const QString | name, | |
bool * | ok = NULL | |||
) | const |
Method to get the info QString for int typed property.
name | Identifying QString for the property. | |
ok | Pointer to bool value which is set to true if property exists, and to false otherwise. |
Definition at line 144 of file qvpropertyholder.cpp.
Referenced by infoInputProperties().
QString QVPropertyHolder::getLastError | ( | ) | const |
Gets the (possible) last error string.
Definition at line 153 of file qvpropertyholder.cpp.
Referenced by QVApplication::exec().
const QString QVPropertyHolder::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).
Definition at line 158 of file qvpropertyholder.cpp.
References getName(), getPropertyInfo(), getPropertyType(), inputFlag, READ_PROPERTY, READ_PROPERTY_MAX, and READ_PROPERTY_MIN.
bool QVPropertyHolder::linkProperty | ( | QString | prop_orig, | |
QVPropertyHolder * | qvp_dest, | |||
QString | prop_dest, | |||
LinkType | link_type | |||
) |
Links properties among QVPropertyHolder's.
This is only used when programming multithreaded applications. (The pointer this corresponds to the source QVPropertyHolder).
prop_orig | Identifying QString for the source property. | |
qvp_dest | Pointer to the destination QVPropertyHolder. | |
prop_dest | Identifying QString for the destination property. | |
link_type | Synchronous or asynchronous. |
Definition at line 298 of file qvpropertyholder.cpp.
References getName(), getPropertyType(), inputFlag, inputLinks, io_flags, link_flags, outputFlag, outputLinks, qvApp, and setLastError().
Referenced by QVMPlayerCamera::link().
void QVPropertyHolder::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 367 of file qvpropertyholder.cpp.
void QVPropertyHolder::readInputProperties | ( | ) | [protected] |
Read linked input properties from other QVPropertyHolder's.
This is a protected function that should be called from the subclasses of QVPropertyHolder just before start an iteration (for example, just before the worker() function in a QVWorker, or just before the viewer() function in a QVCanvas).
In principle, it is useful only in multithreaded applications.
Definition at line 393 of file qvpropertyholder.cpp.
References SynchronousLink.
void QVPropertyHolder::writeOutputProperties | ( | ) | [protected] |
Write linked output properties to other QVPropertyHolder's.
This is a protected function that should be called from the subclasses of QVPropertyHolder just after ending an iteration (for example, just after the worker() function in a QVWorker, or just after the viewer() function in a QVCanvas). The net effect is that a coherent state of the linked output properties is saved, so other QVPropertyHolder's can safely read from it, while we can be writing new values corresponding to a new iteration.
In principle, it is useful only in multithreaded applications.
Definition at line 427 of file qvpropertyholder.cpp.
References SynchronousLink.
Referenced by QVMPlayerCamera::grab().
bool QVPropertyHolder::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). QVPropertyHolder 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 MyDerivedQVPropertyHolder::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 = "MyDerivedQVPropertyHolder::parseArgument(): holder " + getName() + ": value " + value + " is not a valid MyType value for parameter " + parameter + ".\n"; setLastError(errorString); return FALSE; } }
--
[holder:]<name>=<value> parameter | The name of the property to be set. | |
value | QString from which to obtain the value. |
Definition at line 653 of file qvpropertyholder.h.
References getName().
void QVPropertyHolder::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 QVPropertyHolder (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 481 of file qvpropertyholder.cpp.
Referenced by linkProperty(), setPropertyRange(), and setPropertyRange2().