3 files changed, 50 insertions, 1 deletions
diff --git a/doc/src/contacts.qdoc b/doc/src/contacts.qdoc
index 000fb064c0..030d6a39a4 100644
--- a/doc/src/contacts.qdoc
+++ b/doc/src/contacts.qdoc
@@ -267,6 +267,21 @@ synchronous API only.
 
 For more detailed documentation on the synchronous API, see the \l{Contacts Synchronous API}.
 
+\section2 Actions
+
+Clients can perform \l{QContactAction}{actions} on contacts which support
+them.  Actions are things like "Send Email" or "Dial", and can be provided
+from various sources including Qt Plugins or the Qt Mobility Service
+Framework. Every action implementation is uniquely identified by a
+combination of its name, the name of the vendor which provided the
+implementation, and the version of the implementation according to the
+vendor.  These pieces of data may be encapsulated in a
+\l{QContactActionDescriptor} which can be used to retrieve an instance of the
+implementation from a \l{QContactActionFactory}.
+
+When an instance of a \l{QContactAction} is created, the caller takes
+ownership of the instance, and must delete it after use.
+
 \section1 Non-Client-Facing API
 
 The non-client-facing API allows third party developers to implement a manager
@@ -343,6 +358,12 @@ criteria:
 A client can also request that the results of such a selection be sorted,
 by passing a \l{QContactSortOrder} (or list of sort orders) to the manager.
 
+\section2 Actions
+
+Actions are described by descriptors and are instantiated by factories.
+
+\annotatedlist contacts-actions
+
 \section2 Implementing Backends
 
 A backend implementor must implement the following interfaces:
diff --git a/doc/src/contactsusage.qdoc b/doc/src/contactsusage.qdoc
index 16b7980f94..3c6764242d 100644
--- a/doc/src/contactsusage.qdoc
+++ b/doc/src/contactsusage.qdoc
@@ -268,7 +268,8 @@ a contact is involved, but carries the risk that the cache is stale.
 Clients can inform the manager that they do not require this cache of
 relationships to be populated when retrieving a contact, which can allow a
 manager to optimize contact retrieval.  Other retrieval optimizations are also
-possible to specify, for example that they are only interested in certain types of details.
+possible to specify, for example that they do not require action preferences
+to be returned, or that they are only interested in certain types of details.
 The following code shows how the client can inform the manager that they are
 only interested in relationships of the \c HasMember type (groups):
 
diff --git a/doc/src/snippets/qtcontactsdocsample/qtcontactsdocsample.cpp b/doc/src/snippets/qtcontactsdocsample/qtcontactsdocsample.cpp
index f12b16548a..b2e62bef06 100644
--- a/doc/src/snippets/qtcontactsdocsample/qtcontactsdocsample.cpp
+++ b/doc/src/snippets/qtcontactsdocsample/qtcontactsdocsample.cpp
@@ -55,6 +55,7 @@ static void queryManagerCapabilities();
 static void contactDetailManipulation();
 static void contactManipulation();
 static void addContact(QContactManager*);
+static void callContact(QContactManager*);
 static void matchCall(QContactManager*, const QString&);
 static void viewSpecificDetail(QContactManager*);
 static void viewDetails(QContactManager*);
@@ -73,6 +74,7 @@ int stopCompilerWarnings()
     // synchronous API examples
     QContactManager* cm = new QContactManager();
     addContact(cm);
+    callContact(cm);
     matchCall(cm, "111-222-333"); // unknown number.
     matchCall(cm, "12345678");    // alice's number.
     viewSpecificDetail(cm);
@@ -291,6 +293,7 @@ void addContact(QContactManager* cm)
     number.setSubTypes(QContactPhoneNumber::SubTypeMobile);
     number.setNumber("12345678");
     alice.saveDetail(&number);
+    alice.setPreferredDetail("DialAction", number);
 
     /* Add a second phone number */
     QContactPhoneNumber number2;
@@ -306,6 +309,30 @@ void addContact(QContactManager* cm)
 }
 //! [Creating a new contact]
 
+void callContact(QContactManager* cm)
+{
+    QList<QContactLocalId> contactIds = cm->contactIds();
+    QContact a = cm->contact(contactIds.first());
+
+    /* Get this contact's first phone number */
+    QContact contact;
+
+    //! [Details with action]
+    // Get the first "Call" action
+    QContactAction* action = QContactAction::action(QContactAction::actionDescriptors("Call").value(0));
+    QList<QContactDetail> details = contact.detailsWithAction(action);
+
+    if (details.count() == 0) {
+        // Can't call this contact
+    } else if (details.count() == 1) {
+        // Just call this specific detail
+        action->invokeAction(contact, details.first());
+    } else {
+        // Offer the user the choice of details to call
+        // ...
+    }
+    //! [Details with action]
+}
 
 //! [Filtering by definition and value]
 void matchCall(QContactManager* cm, const QString& incomingCallNbr)