#include <contextproperty.h>
Signals | |
void | valueChanged () |
Emitted whenever the value of the property changes and the property is subscribed. | |
Public Member Functions | |
ContextProperty (const QString &key, QObject *parent=0) | |
Constructs a new ContextProperty for key and subscribes to it. | |
virtual | ~ContextProperty () |
Unsubscribes from the ContextProperty and destroys it. | |
QString | key () const |
Returns the key. | |
QVariant | value (const QVariant &def) const |
Returns the current value, or the value def if the current value is null . | |
QVariant | value () const |
Returns the current value. | |
const ContextPropertyInfo * | info () const |
Returns the metadata about this property, please refer to Introspection for details. | |
void | subscribe () const |
Starts subscribtion to the context property, if it isn't subscribed already. | |
void | unsubscribe () const |
Unsubscribes from the context property, if it is currently subscribed. | |
void | waitForSubscription () const |
Suspends the execution of the current thread until subcription is complete for this context property. | |
void | waitForSubscription (bool block) const |
Suspends the execution of the current thread until subcription is complete for this context property. | |
Static Public Member Functions | |
static void | ignoreCommander () |
Sets all of the ContextProperty instances immune to 'external commanding'. | |
static void | setTypeCheck (bool typeCheck) |
Enables or disables all of the ContextProperty instances' type-check feature. | |
Private Slots | |
void | onValueChanged () |
Private Attributes | |
ContextPropertyPrivate * | priv |
The value is available with the value() member function and change notifications are delivered via the valueChanged() signal.
You can explicity subscribe and unsubscribe using the subscribe() and unsubscribe() member functions. A ContextProperty is initially subscribed.
When a ContextProperty is in the unsubscribed state, it usually keeps its last value. This is not guaranteed however: more than one ContextProperty might exist in your process for the same key, and as long as one of them is subscribed, all of them might receive new values. Also the valueChanged() signal is emitted in this case.
A ContextProperty is generally asynchronous and relies on a running event loop. Subscriptions and unsubcriptions are only handled and new values are only received when your program enters the event loop.
ContextProperty objects can be created only after the Q(Core)Application is constructed.
When a ContextProperty is first created or goes from the unsubcribed to the subscribed state later on, it is temporarily in an intermediate 'subscribing' state. This state lasts until the negotiations with the provider of the key are over (or an error occurs) and the key's current value is known to the ContextProperty.
Thus, there is a time after creating a ContextProperty (or subscribing it again) where value() might be out of sync with the provider of the key. If you need to wait for this time to be over, you can not rely on the valueChanged() signal being emitted. This signal is only emitted when the value actually changes, which might not happen when subscription is over.
Instead, you can use the waitForSubscription() member function. This function runs a recursive event loop, if necessary, until the ContextProperty is fully subscribed.
Thus, the recommended way is to first create all ContextProperty instances that your program needs and QObject::connect their valueChanged() signals, then to call waitForSubscription() on those values that are needed to create the initial user interface.
It is important to create all needed ContextProperty instances before calling waitForSubscription() on any of them. Subscriptions are usually bundled together behind the scenes so that they can all be done with a single round trip to the provider. Interleaving creation of ContextProperties with calls to waitForSubscription() would prevent this optimization.
ContextProperty
class follows the usual QObject rules for non-GUI classes in multi-threaded programs. In Qt terminology, the ContextProperty class is reentrant but not thread-safe. This means that you can create ContextProperty instances in any thread and then freely use these instance in their threads, but you can not use a single instance concurrently from multiple threads.Please pay special attention to how signals and slots work in a multi-threaded program: by default, a slot is emitted in the thread that called QObject::connect(). For this to happen reliably, the thread needs to run a event loop.
See the Qt documentation for QThread
and related classes for more details.
ContextProperty::ContextProperty | ( | const QString & | key, | |
QObject * | parent = 0 | |||
) | [explicit] |
Constructs a new ContextProperty for key and subscribes to it.
ContextProperty::~ContextProperty | ( | ) | [virtual] |
Unsubscribes from the ContextProperty and destroys it.
QString ContextProperty::key | ( | ) | const |
Returns the key.
QVariant ContextProperty::value | ( | const QVariant & | def | ) | const |
Returns the current value, or the value def if the current value is null
.
QVariant ContextProperty::value | ( | ) | const |
Returns the current value.
const ContextPropertyInfo * ContextProperty::info | ( | ) | const |
Returns the metadata about this property, please refer to Introspection for details.
void ContextProperty::subscribe | ( | ) | const |
Starts subscribtion to the context property, if it isn't subscribed already.
If you need to wait for it to be complete, use waitForSubscription().
void ContextProperty::unsubscribe | ( | ) | const |
Unsubscribes from the context property, if it is currently subscribed.
Unsubscribing informs the rest of the system that no effort needs to be spent to keep the value up-to-date. However, the value might still change when it can happen 'for free'. In this case the valueChanged() signal will be emitted, too.
void ContextProperty::waitForSubscription | ( | ) | const |
Suspends the execution of the current thread until subcription is complete for this context property.
This might cause the main event loop of your program to run and consequently signals might get emitted (including the valueChanged() signal of this property). Calling this function while the subscription is not in progress (because it has completed already or because the property is currently unsubscribed) does nothing. Calling this function from a thread which is not the main thread results in busy looping.
void ContextProperty::waitForSubscription | ( | bool | block | ) | const |
Suspends the execution of the current thread until subcription is complete for this context property.
Spins the event loop if block is false, and blocks (e.g., select / poll with a socket) if block is true. Calling this function while the subscription is not in progress (because it has completed already or because the property is currently unsubscribed) does nothing. Calling this function with block = true is only allowed for ContextProperty objects associated with the main thread, and calling this function is only allowed in the main thread.
void ContextProperty::ignoreCommander | ( | ) | [static] |
Sets all of the ContextProperty instances immune to 'external commanding'.
This is only intended to be used by the Context Commander itself, so that it can use ContextProperties without tripping over itself. Don't use this.
void ContextProperty::setTypeCheck | ( | bool | newTypeCheck | ) | [static] |
Enables or disables all of the ContextProperty instances' type-check feature.
If it is enabled and the received value from the provider doesn't match the expected type, you will get an error message on the stderr and the value won't be updated. If you use this method, you have to use it before starting any threads.
void ContextProperty::valueChanged | ( | ) | [signal] |
Emitted whenever the value of the property changes and the property is subscribed.
void ContextProperty::onValueChanged | ( | ) | [private, slot] |
ContextPropertyPrivate* ContextProperty::priv [private] |