Context Properties

The Context Framework allows you to access system- and session-wide named values. Examples are context properties like the current geographical location. You can receive notifications about changes to these values, and you can also easily subscribe and unsubscribe from change notifications to help with managing power consumption.

Overview

The Context Properties are key/value pairs. The keys are strings and the values are QVariants.

Key are arranged in a hierarchical namespace like in this example of two contextual properties

    Screen.TopEdge = "left"
    Screen.IsCovered = false

Although the key names can be considered to form a tree (with "Screen" at the root) there is no semantic relationship between parent and child nodes in the tree: the key "Screen" is unrelated to "Screen.TopEdge". In particular, change notifications do not travel up the tree.

The Introspection section describes in detail how to get a list of existing keys and examine their capabilities.

Programmers access the key/value pairs through instances of the ContextProperty class. These instances allow applications to access the values and receive change notifications.

Example:

    ContextProperty *topEdge = new ContextProperty("Screen.TopEdge");
    QObject::connect(topEdge, SIGNAL(valueChanged()),
                     this, SLOT(topEdgeChanged()));

In your edgeUpChanged method you are able to retrieve the value of the property:

    qWarning() << "The edge " << topEdge->value() << " is up";

Creating a ContextProperty instance for a key causes the program to 'subscribe' to this key. The values for some keys might be expensive to determine, so you should only subscribe to those keys that you are currently interested in. You can temporarily unsubscribe from a key without destroying the ContextProperty instance by using the unsubscribe() member function. Later, you can resume the subscription by calling the subscribe() member function.

    void onScreenBlank ()
    {
        topEdge->unsubscribe();
    }

    void onScreenUnblank ()
    {
        topEdge->subscribe();
    }

All the context properties can be used anytime, not depending on whether the provider of the property is installed or running. If the system/provider cannot provide you with a value, the value of the context property will be null. If for some reason you are interested in property metadata (such as a key's current provider, availability, etc.) you should consult the Introspection API.


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