[qml] Document the new property and how it updates

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 ##
 

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
 

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");
     }
 
 }

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