Extend the addressbook example to use the new QIviSimulationEngine

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

7 files changed, 133 insertions, 6 deletions

diff --git a/examples/ivicore/qface-ivi-addressbook/backend_simulator/backend_simulator.pro b/examples/ivicore/qface-ivi-addressbook/backend_simulator/backend_simulator.pro
index 76974e5..38e65e7 100644
--- a/examples/ivicore/qface-ivi-addressbook/backend_simulator/backend_simulator.pro
+++ b/examples/ivicore/qface-ivi-addressbook/backend_simulator/backend_simulator.pro
@@ -20,3 +20,7 @@ PLUGIN_CLASS_NAME = AddressBookPlugin
 CONFIG += install_ok  # Do not cargo-cult this!
 target.path = $$[QT_INSTALL_EXAMPLES]/ivicore/qface-ivi-addressbook/qtivi/
 INSTALLS += target
+
+#! [0]
+RESOURCES += plugin_resource.qrc
+#! [0]
diff --git a/examples/ivicore/qface-ivi-addressbook/backend_simulator/plugin_resource.qrc b/examples/ivicore/qface-ivi-addressbook/backend_simulator/plugin_resource.qrc
new file mode 100644
index 0000000..7b89deb
--- /dev/null
+++ b/examples/ivicore/qface-ivi-addressbook/backend_simulator/plugin_resource.qrc
@@ -0,0 +1,5 @@
+<RCC>
+    <qresource prefix="/plugin_resource">
+        <file>simulation.qml</file>
+    </qresource>
+</RCC>
diff --git a/examples/ivicore/qface-ivi-addressbook/backend_simulator/simulation.qml b/examples/ivicore/qface-ivi-addressbook/backend_simulator/simulation.qml
new file mode 100644
index 0000000..7810632
--- /dev/null
+++ b/examples/ivicore/qface-ivi-addressbook/backend_simulator/simulation.qml
@@ -0,0 +1,71 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 Pelagicore AG
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtIvi module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD-QTAS$
+** Commercial License Usage
+** Licensees holding valid commercial Qt Automotive Suite licenses may use
+** this file in accordance with the commercial license agreement provided
+** with the Software or, alternatively, in accordance with the terms
+** contained in a written agreement between you and The Qt Company.  For
+** licensing terms and conditions see https://www.qt.io/terms-conditions.
+** For further information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+** SPDX-License-Identifier: BSD-3-Clause
+**
+****************************************************************************/
+
+//! [0]
+import QtQuick 2.0
+import example.ivi.addressbook.simulation 1.0
+
+Item {
+    AddressBookBackend {
+
+        function insertContact(reply, index, contact) {
+            print("BACKEND SIMULATION INSERT CONTACT")
+            contacts.insert(index, contact);
+            reply.setSuccess(true);
+        }
+
+        Component.onCompleted: {
+            console.log("BACKEND SIMULATION CREATED")
+        }
+    }
+}
+//! [0]
diff --git a/examples/ivicore/qface-ivi-addressbook/demo/main.qml b/examples/ivicore/qface-ivi-addressbook/demo/main.qml
index 30a6824..1f93250 100644
--- a/examples/ivicore/qface-ivi-addressbook/demo/main.qml
+++ b/examples/ivicore/qface-ivi-addressbook/demo/main.qml
@@ -78,6 +78,7 @@ Window {
                 Layout.fillWidth: true
                 Layout.fillHeight: true
                 model: addressBook.contacts
+                clip: true
 
                 delegate: ItemDelegate {
                     width: parent.width
@@ -89,7 +90,7 @@ Window {
             Button {
                 Layout.fillWidth: true
                 text: "New Contact"
-                onClicked: addressBook.insertContact(0, AddressBookModule.contact())
+                onClicked: addressBook.insertContact(0, AddressBookModule.contact("Foo", "Bar", "12234"))
             }
         }
     }
diff --git a/examples/ivicore/qface-ivi-addressbook/example-ivi-addressbook.yaml b/examples/ivicore/qface-ivi-addressbook/example-ivi-addressbook.yaml
index 4762f2a..20304e3 100644
--- a/examples/ivicore/qface-ivi-addressbook/example-ivi-addressbook.yaml
+++ b/examples/ivicore/qface-ivi-addressbook/example-ivi-addressbook.yaml
@@ -1,3 +1,7 @@
+Example.IVI.AddressBook:
+    config_simulator:
+        simulationFile: ":/plugin_resource/simulation.qml"
+
 Example.IVI.AddressBook.AddressBook#contacts:
     config_simulator:
         default: [[ "John", "Doe", "12345" ], [ "Jane", "Doe", "67890" ]]
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"