From 03ac0d2cf0f9701e0edbd2cdf2a0ba7544b865cb Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Tue, 27 Aug 2019 15:54:06 +0200
Subject: [PATCH] [qml] Document the new property and how it updates

---
 CHANGES                                      |  3 +++
 src/branding/README.md                       | 10 ++++++++++
 src/branding/default/show.qml                | 14 +++++++++-----
 src/qml/calamares/slideshow/Presentation.qml |  8 +++++++-
 4 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/CHANGES b/CHANGES
index 66323ff9f..02a7fc4f5 100644
--- a/CHANGES
+++ b/CHANGES
@@ -20,6 +20,9 @@ This release contains contributions from (alphabetically by first name):
   (maintained!) upstream version instead. It also gives us KMacroExpander
   everywhere, which will simplify code for handling substitutions
   in configuration files.
+- *Slideshows* now have a new property *activatedInCalamares* which
+  controls the keyboard shortcuts (and can control timers and other
+  properties of the slideshow, too).
 
 ## Modules ##
 
diff --git a/src/branding/README.md b/src/branding/README.md
index 1b9eb57fd..099163836 100644
--- a/src/branding/README.md
+++ b/src/branding/README.md
@@ -66,6 +66,16 @@ The setting *slideshowAPI* in `branding.desc` indicates which one to use
 for a given branding slideshow. Which API to use is really a function of
 the QML. Expect the version 1 API to be deprecated in the course of Calamares 3.3.
 
+In Calamares 3.2.13 support for activation notification to the QML 
+parts is improved:
+ - If the root object has a property *activatedInCalamares* (the examples do),
+   then that property is set to *true* when the slideshow becomes visible
+   (activated) and is set to *false* when the slideshow is hidden (e.g.
+   when the installation phase is done).
+ - The *actvatedInCalamares* property can be used to set up timers also in V1.
+ - The keyboard shortcuts in the example slideshow are enabled only while
+   the slideshow is visible.
+
 
 ## Translations
 
diff --git a/src/branding/default/show.qml b/src/branding/default/show.qml
index 1a174f0b6..dcb0f9257 100644
--- a/src/branding/default/show.qml
+++ b/src/branding/default/show.qml
@@ -32,7 +32,7 @@ Presentation
     Timer {
         id: advanceTimer
         interval: 1000
-        running: false
+        running: presentation.activatedInCalamares
         repeat: true
         onTriggered: nextSlide()
     }
@@ -68,15 +68,19 @@ Presentation
         centeredText: qsTr("This is a third Slide element.")
     }
 
+    // When this slideshow is loaded as a V1 slideshow, only
+    // activatedInCalamares is set, which starts the timer (see above).
+    //
+    // In V2, also the onActivate() and onLeave() methods are called.
+    // These example functions log a message (and re-start the slides
+    // from the first).
     function onActivate() {
-        presentation.currentSlide = 0;
-        presentation.activatedInCalamares = true;
-        advanceTimer.running = true;
         console.log("QML Component (default slideshow) activated");
+        presentation.currentSlide = 0;
     }
     
     function onLeave() {
-        presentation.activatedInCalamares = true;
+        console.log("QML Component (default slideshow) deactivated");
     }
 
 }
diff --git a/src/qml/calamares/slideshow/Presentation.qml b/src/qml/calamares/slideshow/Presentation.qml
index a4138d588..1d2fd9c85 100644
--- a/src/qml/calamares/slideshow/Presentation.qml
+++ b/src/qml/calamares/slideshow/Presentation.qml
@@ -80,7 +80,13 @@ Item {
     property string fontFamily: "Helvetica"
     property string codeFontFamily: "Courier New"
 
-    property bool activatedInCalamares: false;
+    // This is set by the C++ part of Calamares when the slideshow
+    // becomes visible. You can connect it to a timer, or whatever
+    // else needs to start only when the slideshow becomes visible.
+    //
+    // It is used in this example also to keep the keyboard shortcuts
+    // enabled only while the slideshow is active.
+    property bool activatedInCalamares: false
     
     // Private API
     property int _lastShownSlide: 0