From cd968c4c48d61bbbada3d4bb216ff3366e481cdf Mon Sep 17 00:00:00 2001
From: Leena Miettinen <riitta-leena.miettinen@digia.com>
Date: Tue, 15 Jul 2014 13:22:46 +0200
Subject: Doc: add docs for Component Error example

Document the example.
Edit text in the example files.
Add a screenshot.

Change-Id: Ib5c3e0d78006d81ec77c75c92b7636f358e83412
Reviewed-by: Tim Jenssen <tim.jenssen@digia.com>
Reviewed-by: Kai Koehne <kai.koehne@digia.com>
---
 examples/componenterror/config/config.xml          |   8 +--
 .../packages/root.component1/meta/installscript.js |   2 +-
 .../packages/root.component1/meta/package.xml      |   4 +-
 .../packages/root.component2/meta/installscript.js |   2 +-
 .../packages/root.component2/meta/package.xml      |   4 +-
 .../packages/root/meta/installscript.js            |   2 +-
 .../componenterror/packages/root/meta/package.xml  |   3 +-
 examples/doc/componenterror.qdoc                   |  57 ++++++++++++++++++++-
 .../doc/images/qtifw-examples-componenterror.png   | Bin 0 -> 40203 bytes
 9 files changed, 70 insertions(+), 12 deletions(-)
 create mode 100644 examples/doc/images/qtifw-examples-componenterror.png

(limited to 'examples')

diff --git a/examples/componenterror/config/config.xml b/examples/componenterror/config/config.xml
index e9d6a9dd5..da707f228 100644
--- a/examples/componenterror/config/config.xml
+++ b/examples/componenterror/config/config.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <Installer>
-    <Name>Component Error Installer Example</Name>
+    <Name>Component Error Example</Name>
     <Version>1.0.0</Version>
-    <Title>Component Error Installer Example</Title>
+    <Title>Component Error Example</Title>
     <Publisher>Qt-Project</Publisher>
-    <StartMenuDir>Qt Installer Framework Example</StartMenuDir>
-    <TargetDir>@HomeDir@/IFWComponentErrorInstallerExample</TargetDir>
+    <StartMenuDir>Qt IFW Examples</StartMenuDir>
+    <TargetDir>@HomeDir@/IfwExample</TargetDir>
 </Installer>
diff --git a/examples/componenterror/packages/root.component1/meta/installscript.js b/examples/componenterror/packages/root.component1/meta/installscript.js
index 6d76437b2..8fc0cb35a 100644
--- a/examples/componenterror/packages/root.component1/meta/installscript.js
+++ b/examples/componenterror/packages/root.component1/meta/installscript.js
@@ -44,7 +44,7 @@ function Component()
     var error = true;
     if (error) {
         installer.setValue("component_errors", installer.value("component_errors") + ";;;"
-            + "error from component: " + component.name);
+            + "Error in component: " + component.name);
     }
     installer.setValue("ComponentError", true);
 }
diff --git a/examples/componenterror/packages/root.component1/meta/package.xml b/examples/componenterror/packages/root.component1/meta/package.xml
index eac36530b..9b975093d 100644
--- a/examples/componenterror/packages/root.component1/meta/package.xml
+++ b/examples/componenterror/packages/root.component1/meta/package.xml
@@ -1,6 +1,8 @@
 <?xml version="1.0"?>
 <Package>
-    <DisplayName>component1</DisplayName>
+    <DisplayName>Component 1</DisplayName>
+    <Description>This component contains an error that prevents it from being
+    installed.</Description>
     <Version>1.0.1</Version>
     <ReleaseDate>2013-08-21</ReleaseDate>
     <Script>installscript.js</Script>
diff --git a/examples/componenterror/packages/root.component2/meta/installscript.js b/examples/componenterror/packages/root.component2/meta/installscript.js
index 6d76437b2..8fc0cb35a 100644
--- a/examples/componenterror/packages/root.component2/meta/installscript.js
+++ b/examples/componenterror/packages/root.component2/meta/installscript.js
@@ -44,7 +44,7 @@ function Component()
     var error = true;
     if (error) {
         installer.setValue("component_errors", installer.value("component_errors") + ";;;"
-            + "error from component: " + component.name);
+            + "Error in component: " + component.name);
     }
     installer.setValue("ComponentError", true);
 }
diff --git a/examples/componenterror/packages/root.component2/meta/package.xml b/examples/componenterror/packages/root.component2/meta/package.xml
index 4caad7ad6..8898e2e6d 100644
--- a/examples/componenterror/packages/root.component2/meta/package.xml
+++ b/examples/componenterror/packages/root.component2/meta/package.xml
@@ -1,6 +1,8 @@
 <?xml version="1.0"?>
 <Package>
-    <DisplayName>component2</DisplayName>
+    <DisplayName>Component 2</DisplayName>
+    <Description>This component contains an error that prevents it from being
+                 installed.</Description>
     <Version>1.0.1</Version>
     <ReleaseDate>2013-08-21</ReleaseDate>
     <Script>installscript.js</Script>
diff --git a/examples/componenterror/packages/root/meta/installscript.js b/examples/componenterror/packages/root/meta/installscript.js
index 7ddf7dab5..4f28d4758 100644
--- a/examples/componenterror/packages/root/meta/installscript.js
+++ b/examples/componenterror/packages/root/meta/installscript.js
@@ -49,7 +49,7 @@ function abortInstaller()
     installer.setDefaultPageVisible(QInstaller.PerformInstallation, false);
     installer.setDefaultPageVisible(QInstaller.LicenseCheck, false);
 
-    var abortText = "<font color='red' size=6>" + qsTr("The installation has failed.") + "</font>";
+    var abortText = "<font color='red' size=3>" + qsTr("Installation failed:") + "</font>";
 
     var error_list = installer.value("component_errors").split(";;;");
     abortText += "<ul>";
diff --git a/examples/componenterror/packages/root/meta/package.xml b/examples/componenterror/packages/root/meta/package.xml
index ce9b55537..a5ee2e52e 100644
--- a/examples/componenterror/packages/root/meta/package.xml
+++ b/examples/componenterror/packages/root/meta/package.xml
@@ -1,6 +1,7 @@
 <?xml version="1.0"?>
 <Package>
-    <DisplayName>ROOT</DisplayName>
+    <DisplayName>Root Component</DisplayName>
+    <Description>This component handles the errors in the other components.</Description>
     <Version>1.0.1</Version>
     <ReleaseDate>2013-08-21</ReleaseDate>
     <Script>installscript.js</Script>
diff --git a/examples/doc/componenterror.qdoc b/examples/doc/componenterror.qdoc
index b0530701e..d4e6ef17a 100644
--- a/examples/doc/componenterror.qdoc
+++ b/examples/doc/componenterror.qdoc
@@ -28,13 +28,66 @@
 /*!
     \example componenterror
     \ingroup qtifwexamples
-    \title Component Error Installer Example
+    \title Component Error Example
 
-    \brief Reacting to errors in components.
+    \brief Stopping the installation if the components cannot be installed.
+
+    \image qtifw-examples-componenterror.png
+
+    \e{Component Error} demonstrates how to stop the installation and display
+    error messages if one or several components cannot be installed.
 
     \include installerfw-examples-configuring.qdocinc
 
     \quotefile componenterror/config/config.xml
 
+    \include installerfw-examples-packaging.qdocinc
+
+    \list
+        \li The \c <Script> section specifies the file name of the JavaScript
+            file that is loaded to perform operations.
+    \endlist
+
+    \quotefile componenterror/packages/root/meta/package.xml
+
+    This example attempts to install three components, so we create a
+    package.xml file in each component directory: \c root, \c root.component1,
+    and \c root.component2 and specify the component name and description in
+    each of them.
+
+    \section1 Stopping the Installation on Errors
+
+    In installscript.js in the \c root directory, we call the
+    \c abortInstaller() function to hide all the default installer pages and to
+    display an error message if the components contain errors:
+
+    \quotefromfile componenterror/packages/root/meta/installscript.js
+    \skipto abortInstaller()
+    \printuntil FinishedText
+    \printuntil }
+
+    We use the \c reactOnAbortInstallerChange() signal to stop the installation
+    if \c ComponentError is \c true:
+
+    \printuntil }
+
+    We use the \c Component() function to connect to the
+    \c reactOnAbortInstallerChange() signal when the list of new root
+    components has been updated:
+
+    \printuntil }
+
+    To open the page that displays the error message, we create fake errors by
+    setting \c ComponentError to \c true in installscript.js in the
+    \c root.component1 and \c root.component2 directories:
+
+    \quotefromfile componenterror/packages/root.component1/meta/installscript.js
+    \skipto Component()
+    \printuntil /^\}/
+
+    Each component adds a message to the \c component_errors variable. In your
+    app, the \c error variable should return the results of a real check for an
+    existing file or system feature.
+
     \include installerfw-examples-generating.qdocinc
 */
diff --git a/examples/doc/images/qtifw-examples-componenterror.png b/examples/doc/images/qtifw-examples-componenterror.png
new file mode 100644
index 000000000..e659aaf67
Binary files /dev/null and b/examples/doc/images/qtifw-examples-componenterror.png differ
-- 
cgit v1.2.3