Detailed Description
The QValueSpaceItem class allows access to Value Space items.
The Value Space is an inter-application hierarchy of readable, writable and subscribable data. The QValueSpaceItem class allows applications to read and subscribe to this data.
Conceptually, the Value Space is a hierarchical tree of which each item can optionally contain a QVariant value and sub-items. A serialized version of a simple example might look like this.
/Device/Buttons = 3
/Device/Buttons/1/Name = Context
/Device/Buttons/1/Usable = true
/Device/Buttons/2/Name = Select
/Device/Buttons/2/Usable = false
/Device/Buttons/3/Name = Back
/Device/Buttons/3/Usable = true
Any application in Qt Extended can read values from the Value Space, or be notified asynchronously when they change using the QValueSpaceItem class.
Items in the Value Space can be thought of as representing "objects" adhering to a well known schema. This is a conceptual differentiation, not a physical one, as internally the Value Space is treated as one large tree. In the sample above, the /Device/Buttons schema can be defined as containing a value representing the number of mappable buttons on a device, and a sub-item for each. Likewise, the sub-item object schema contains two attributes - Name and Usable.
Applications may use the QValueSpaceObject class to create a schema object within the Value Space. Objects remain in the Value Space as long as the QValueSpaceObject instance exists - that is, they are not persistant. If the object is destroyed, or the application containing it exits (or crashes) the items are removed.
Change notification is modelled in a similar way. Applications subscribe to notifications at a particular object (ie. item) in the tree. If anything in that object (ie. under that item) changes, the application is notified. This allows, for example, subscription to just the /Device/Buttons item to receive notification when anything "button" related changes.
For example,
QValueSpaceItem *buttons = new QValueSpaceItem("/Device/Buttons");
qWarning() << "There are" << buttons->value().toUInt() << "buttons";
QObject::connect(buttons, SIGNAL(contentsChanged()),
this, SLOT(buttonInfoChanged()));
will invoke the buttonInfoChanged() slot whenever any item under /Device/Buttons changes. This includes the value of /Device/Buttons itself, a change of a sub-object such as /Device/Buttons/2/Name or the creation (or removal) of a new sub-object, such as /Device/Buttons/4.
Note: The QValueSpaceItem class is not thread safe and may only be used from an application's main thread.
Member Function Documentation
QValueSpaceItem::QValueSpaceItem ( const QValueSpaceItem & base, const QByteArray & path, QObject * parent = 0 )
Construct a new QValueSpaceItem with the specified parent that refers to the sub-path of base.
QValueSpaceItem::QValueSpaceItem ( const QValueSpaceItem & other, QObject * parent = 0 )
Construct a new QValueSpaceItem with the specified parent that refers to the same path as other.
QValueSpaceItem::QValueSpaceItem ( const QByteArray & path, QObject * parent = 0 )
Construct a new QValueSpaceItem with the specified parent that refers to path.
QValueSpaceItem::QValueSpaceItem ( QObject * parent = 0 )
Construct a new QValueSpaceItem with the specified parent that refers to the root path .
QValueSpaceItem::QValueSpaceItem ( const QValueSpaceItem & base, const QString & path, QObject * parent = 0 )
Construct a new QValueSpaceItem with the specified parent that refers to the sub-path of base. This constructor is equivalent to QValueSpaceItem(base, path.toUtf8()).
QValueSpaceItem::QValueSpaceItem ( const QValueSpaceItem & base, const char * path, QObject * parent = 0 )
Construct a new QValueSpaceItem with the specified parent that refers to the sub-path of base. This constructor is equivalent to QValueSpaceItem(base, QByteArray(path)).
QValueSpaceItem::QValueSpaceItem ( const QString & path, QObject * parent = 0 )
Construct a new QValueSpaceItem with the specified parent that refers to path. This constructor is equivalent to QValueSpaceItem(path.toUtf8()).
QValueSpaceItem::QValueSpaceItem ( const char * path, QObject * parent = 0 )
Construct a new QValueSpaceItem with the specified parent that refers to path. This constructor is equivalent to QValueSpaceItem(QByteArray(path)).
QValueSpaceItem::~QValueSpaceItem () [virtual]
Destroys the QValueSpaceItem
void QValueSpaceItem::contentsChanged () [signal]
Emitted whenever the value of this item, or any sub-items changes.
QString QValueSpaceItem::itemName () const
Returns the item name of this QValueSpaceItem.
void QValueSpaceItem::remove ()
Request that the item be removed. The provider of the item determines whether the request is honored or ignored.
Note: This call asynchronously asks the current provider of the object to change the value. To explicitly make a change use QValueSpaceObject.
See also QValueSpaceObject::itemRemove().
void QValueSpaceItem::remove ( const QByteArray & subPath )
This is an overloaded member function, provided for convenience.
Request that the subPath of item be removed. The provider of the sub path determines whether the request is honored or ignored.
Note: This call asynchronously asks the current provider of the object to change the value. To explicitly make a change use QValueSpaceObject.
See also QValueSpaceObject::itemRemove().
void QValueSpaceItem::remove ( const char * subPath )
This is an overloaded member function, provided for convenience.
Request that the subPath of item be removed. The provider of the sub path determines whether the request is honored or ignored.
Note: This call asynchronously asks the current provider of the object to change the value. To explicitly make a change use QValueSpaceObject.
See also QValueSpaceObject::itemRemove().
void QValueSpaceItem::remove ( const QString & subPath )
This is an overloaded member function, provided for convenience.
Request that the subPath of item be removed. The provider of the sub path determines whether the request is honored or ignored.
Note: This call asynchronously asks the current provider of the object to change the value. To explicitly make a change use QValueSpaceObject.
See also QValueSpaceObject::itemRemove().
void QValueSpaceItem::setValue ( const QVariant & value )
Request that the value of this item be changed to value. The provider of the item determines whether the request is honored or ignored.
Note: This call asynchronously asks the current provider of the object to change the value. To explicitly make a change use QValueSpaceObject.
See also value() and QValueSpaceObject::itemSetValue().
void QValueSpaceItem::setValue ( const QByteArray & subPath, const QVariant & value )
This is an overloaded member function, provided for convenience.
Request that the value of the subPath of this item be changed to value. The provider of the sub path determines whether the request is honored or ignored.
Note: This call asynchronously asks the current provider of the object to change the value. To explicitly make a change use QValueSpaceObject.
See also QValueSpaceObject::itemSetValue().
void QValueSpaceItem::setValue ( const char * subPath, const QVariant & value )
This is an overloaded member function, provided for convenience.
Request that the value of the subPath of this item be changed to value. The provider of the sub path determines whether the request is honored or ignored.
Note: This call asynchronously asks the current provider of the object to change the value. To explicitly make a change use QValueSpaceObject.
See also QValueSpaceObject::itemSetValue().
void QValueSpaceItem::setValue ( const QString & subPath, const QVariant & value )
This is an overloaded member function, provided for convenience.
Request that the value of the subPath of this item be changed to value. The provider of the sub path determines whether the request is honored or ignored.
Note: This call asynchronously asks the current provider of the object to change the value. To explicitly make a change use QValueSpaceObject.
See also QValueSpaceObject::itemSetValue().
QList<QString> QValueSpaceItem::subPaths () const
Returns a list of sub-paths for this item. For example, given a Value Space tree containing:
/Settings/Trolltech/IniValueSpace
/Settings/Trolltech/Other
/Settings/Qtopia
/Device/Buttons
QValueSpaceItem("/Settings").subPaths() will return a list containing { Trolltech, Qtopia } in no particular order.
bool QValueSpaceItem::sync ()
Commit all changes made by calls to setValue() or remove(). The return value is reserved for future use.
QVariant QValueSpaceItem::value ( const QByteArray & subPath = QByteArray(), const QVariant & def = QVariant() ) const
Returns the value of sub-item subPath of this item, or the value of this item if subPath is empty. The following code shows how the item and subPath relate.
QValueSpaceItem base("/Settings");
QValueSpaceItem equiv("/Settings/Trolltech/IniValueSpace/General/Mappings);
equiv.value() == base.value("Trolltech/IniValueSpace/General/Mapping");
If the item does not exist, def is returned.
See also setValue().
QVariant QValueSpaceItem::value ( const QString & subPath, const QVariant & def = QVariant() ) const
This is an overloaded member function, provided for convenience.
This is a convenience overload and is equivalent to value(subPath.toUtf8(), def).
QVariant QValueSpaceItem::value ( const char * subPath, const QVariant & def = QVariant() ) const
This is an overloaded member function, provided for convenience.
This is a convenience overload and is equivalent to value(QByteArray(subPath), def).
QValueSpaceItem & QValueSpaceItem::operator= ( const QValueSpaceItem & other )
Assign other to this.
