ContextProperty Class Reference

The ContextProperty class allows access to keys and their values. More...

#include <contextproperty.h>

List of all members.

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 ContextPropertyInfoinfo () 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

ContextPropertyPrivatepriv


Detailed Description

The ContextProperty class allows access to keys and their values.

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.

Note:
The 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.


Constructor & Destructor Documentation

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.


Member Function Documentation

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]


Member Data Documentation


The documentation for this class was generated from the following files:

Generated on Sun Apr 21 16:11:51 2013 for libcontextsubscriber by  doxygen 1.5.6