Extend the addressbook example to use the new QIviSimulationEngine

Task-number: AUTOSUITE-628
Change-Id: Ia90e42d801c68d91dd71b309ea4c518f349f13f9
Reviewed-by: Robert Griebl <robert.griebl@pelagicore.com>

2 files changed, 47 insertions, 5 deletions

diff --git a/src/ivicore/doc/src/examples-qface-ivi-addressbook.qdoc b/src/ivicore/doc/src/examples-qface-ivi-addressbook.qdoc
index 5becc79..258d215 100644
--- a/src/ivicore/doc/src/examples-qface-ivi-addressbook.qdoc
+++ b/src/ivicore/doc/src/examples-qface-ivi-addressbook.qdoc
@@ -91,13 +91,54 @@ The model is retrieved from the \e addressbook object using the \e contacts prop
 the ListView. The delegate can access the actual contact using the \l {QIviPagingModel::}{ItemRole}
 of the QIviPagingModel, which is exposed to QML through \e model.item.
 
-\section1 Limitations
+\section1 Extended Simulation Behavior
 
 Because the \l backend_simulator template can only generated a stub, it doesn't know what behavior
 it should implement for the insertContact function of the qface file. The ivigenerator will simply
-generate a stub implementation printing a message that this function is not implemented. Because of
-that, the "New Contact" button in the Demo Application won't do anything useful.
+generate a stub implementation printing a message that this function is not implemented.
+
+This limitation is fixed by using the \l {config_simulator_simulationFile}{simulationFile}
+annotation to tell the autogenerator we want to provide our own simulation QML file.
+
+In the example the \e simulationFile annotation points to a QML file in a resource file. The
+resource file is added to the project file as usual like this:
+
+\snippet ../../../../examples/ivicore/qface-ivi-addressbook/backend_simulator/backend_simulator.pro 0
+
+\section2 Providing the simulation behavior in QML
+
+The autogenerated simulation backend code loads the simulation behavior from a QML file using a
+QIviSimulationEngine. This special engine makes sure the autogenerated backend interfaces are
+provided to the QML file and they can be extended from there. It also makes sure that the
+interfaces are available only to this engine instance and to no other engine running in the same
+process (e.g. in the frontend). See the QIviSimulationEngine documentation for more information
+about how the engine works.
+
+Using the ivigenerator for the simulation backend, the simulation interfaces are provided in the \e
+example.ivi.addressbook.simulation uri. The provided types are named after the backend interfaces
+implemented by the simulation backend. For our example two types are registered:
+
+\list
+    \li AddressBookBackend
+    \li ContactsModelBackend
+\endlist
+
+Our simulation QML file looks like this:
+
+\snippet ../../../../examples/ivicore/qface-ivi-addressbook/backend_simulator/simulation.qml 0
+
+It creates an AddressBookBackend instance and prints a message once the QML code is loaded by using
+the Component.onCompleted handler.
+
+To implement the behavior for the insertContact function, a JS function is added to the
+AddressBookBackend object in QML. This function takes three arguments, the first one is an
+PendingReply object used to notify the frontend once the request was successful or failed. The
+other arguments are as defined in the IDL file.
+
+To insert the provided contact to our list we use the \e contacts property which hold the
+implementation of the QIviPagingModelInterface for the contacts property. This implementation
+provides some extra convenience functions which can be used by the simulation to modify the model
+in an easy way. In our case we just call the \c insert() function and let the autogenerated
+implementation do the rest.
 
-This limitation can be fixed by providing a backend connected to a real service or by providing a
-manually written simulation backend.
 */
diff --git a/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc b/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc
index aedbd29..6df2840 100644
--- a/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc
+++ b/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc
@@ -228,6 +228,7 @@ annotations used for defining various aspects of the generation of the backend-s
         \li Purpose
     \row
         \li
+        \target config_simulator_simulationFile
         \code
         config_simulator:
              simulationFile: ":/qrc/simulation.qml"