Add PauseResume capability flag

Android lacks this capability as the native TextToSpeech class has no
API for this. Since we now have the capabilities enum, add PauseResume
and don't list that for Android, so that applications can disable the
respective UI.

Do that for our examples - hide the pause & resume buttons if the
capability flag is not set.

Document the unsupported capabilities for all engines that lacks some
features

Fixes: QTBUG-113805
Change-Id: Ia8139e235f4cd968519423515e31c81285a2d349
Reviewed-by: Axel Spoerl <axel.spoerl@qt.io>

10 files changed, 27 insertions, 5 deletions

diff --git a/src/plugins/tts/darwin/darwin_plugin.json b/src/plugins/tts/darwin/darwin_plugin.json
index 98b428a..6d82519 100644
--- a/src/plugins/tts/darwin/darwin_plugin.json
+++ b/src/plugins/tts/darwin/darwin_plugin.json
@@ -5,6 +5,7 @@
     "Priority": 100,
     "Capabilities": [
         "Speak",
+        "PauseResume",
         "WordByWordProgress",
         "Synthesize"
     ]
diff --git a/src/plugins/tts/flite/flite_plugin.json b/src/plugins/tts/flite/flite_plugin.json
index b9fd6ef..48d89dc 100644
--- a/src/plugins/tts/flite/flite_plugin.json
+++ b/src/plugins/tts/flite/flite_plugin.json
@@ -5,6 +5,7 @@
     "Priority": 50,
     "Capabilities": [
         "Speak",
+        "PauseResume",
         "WordByWordProgress",
         "Synthesize"
     ]
diff --git a/src/plugins/tts/macos/macos_plugin.json b/src/plugins/tts/macos/macos_plugin.json
index b779e4f..56c6b5a 100644
--- a/src/plugins/tts/macos/macos_plugin.json
+++ b/src/plugins/tts/macos/macos_plugin.json
@@ -5,6 +5,7 @@
     "Priority": 50,
     "Capabilities": [
         "Speak",
+        "PauseResume",
         "WordByWordProgress"
     ]
 }
diff --git a/src/plugins/tts/mock/mock_plugin.json b/src/plugins/tts/mock/mock_plugin.json
index 7785016..57a9d37 100644
--- a/src/plugins/tts/mock/mock_plugin.json
+++ b/src/plugins/tts/mock/mock_plugin.json
@@ -5,6 +5,7 @@
     "Priority": -1,
     "Capabilities": [
         "Speak",
+        "PauseResume",
         "Synthesize",
         "WordByWordProgress"
     ]
diff --git a/src/plugins/tts/sapi/sapi_plugin.json b/src/plugins/tts/sapi/sapi_plugin.json
index 95de0bf..049e152 100644
--- a/src/plugins/tts/sapi/sapi_plugin.json
+++ b/src/plugins/tts/sapi/sapi_plugin.json
@@ -5,6 +5,7 @@
     "Priority": 50,
     "Capabilities": [
         "Speak",
+        "PauseResume",
         "WordByWordProgress",
         "Synthesize"
     ]
diff --git a/src/plugins/tts/speechdispatcher/speechd_plugin.json b/src/plugins/tts/speechdispatcher/speechd_plugin.json
index ba403c6..4c0e2fa 100644
--- a/src/plugins/tts/speechdispatcher/speechd_plugin.json
+++ b/src/plugins/tts/speechdispatcher/speechd_plugin.json
@@ -4,6 +4,7 @@
     "Version": 100,
     "Priority": 80,
     "Capabilities": [
-        "Speak"
+        "Speak",
+        "PauseResume"
     ]
 }
diff --git a/src/plugins/tts/winrt/winrt_plugin.json b/src/plugins/tts/winrt/winrt_plugin.json
index f47e3f6..0911bb4 100644
--- a/src/plugins/tts/winrt/winrt_plugin.json
+++ b/src/plugins/tts/winrt/winrt_plugin.json
@@ -5,6 +5,7 @@
     "Priority": 80,
     "Capabilities": [
         "Speak",
+        "PauseResume",
         "WordByWordProgress",
         "Synthesize"
     ]
diff --git a/src/tts/doc/src/qttexttospeech-engines.qdoc b/src/tts/doc/src/qttexttospeech-engines.qdoc
index 0fc2745..3546c0b 100644
--- a/src/tts/doc/src/qttexttospeech-engines.qdoc
+++ b/src/tts/doc/src/qttexttospeech-engines.qdoc
@@ -68,12 +68,18 @@
 
     The macOS engine does not support any engine specific parameters.
 
+    \note The "macos" engine does not have the \l{QTextToSpeech::Capabilities}{Synthesize}
+    capability.
+
     \section1 Android
 
     The "android" engine is the only engine available on the Android platform. It uses the
     \l{https://developer.android.com/reference/android/speech/tts/TextToSpeech}{TextToSpeech}
     package, which in turn supports multiple engine backends.
 
+    \note The "android" engine does not have the \l{QTextToSpeech::Capabilities}
+    {PauseResume} capability.
+
     \table
         \header
             \li Name
@@ -118,5 +124,8 @@
     \l{https://htmlpreview.github.io/?https://github.com/brailcom/speechd/blob/master/doc/speech-dispatcher.html#Top}
     {speech-dispatcher} daemon, and requires at least libspeechd 0.9.
 
+    \note The speech-dispatcher engine does not have the \l {QTextToSpeech::Capabilities}
+    {WordByWordProgress} or \l {QTextToSpeech::Capabilities}{Synthesize} capabilities.
+
     The speech-dispatcher engine does not support any engine specific parameters.
 */
diff --git a/src/tts/qtexttospeech.cpp b/src/tts/qtexttospeech.cpp
index 9121a8b..47cad9c 100644
--- a/src/tts/qtexttospeech.cpp
+++ b/src/tts/qtexttospeech.cpp
@@ -518,6 +518,7 @@ QString QTextToSpeech::engine() const
 
     \value None                 The engine implements none of the capabilities.
     \value Speak                The engine can play audio output from text.
+    \value PauseResume          The engine can pause and then resume the audo output.
     \value WordByWordProgress   The engine emits the sayingWord() signal for
                                 each word that gets spoken.
     \value Synthesize           The engine can \l{synthesize()}{synthesize} PCM
@@ -994,7 +995,8 @@ void QTextToSpeech::stop(BoundaryHint boundaryHint)
 
     Whether the \a boundaryHint is respected depends on the  \l engine.
 
-    \sa resume(), QTextToSpeech::BoundaryHint
+    \sa resume(), QTextToSpeech::BoundaryHint,
+        {QTextToSpeech::Capabilities}{PauseResume}
 */
 
 /*!
@@ -1002,7 +1004,7 @@ void QTextToSpeech::stop(BoundaryHint boundaryHint)
 
     Whether the \a boundaryHint is respected depends on the  \l engine.
 
-    \sa resume()
+    \sa resume(), {QTextToSpeech::Capabilities}{PauseResume}
 */
 void QTextToSpeech::pause(BoundaryHint boundaryHint)
 {
@@ -1033,6 +1035,9 @@ void QTextToSpeech::pause(BoundaryHint boundaryHint)
 /*!
     Resume speaking after \l pause() has been called.
 
+    \note On Android, resuming paused speech will restart from the beginning.
+    This is a limitation of the underlying text-to-speech engine.
+
     \sa pause()
 */
 void QTextToSpeech::resume()
diff --git a/src/tts/qtexttospeech.h b/src/tts/qtexttospeech.h
index fb586b5..2b3951b 100644
--- a/src/tts/qtexttospeech.h
+++ b/src/tts/qtexttospeech.h
@@ -63,8 +63,9 @@ public:
     enum class Capability {
         None                = 0,
         Speak               = 1 << 0,
-        WordByWordProgress  = 1 << 1,
-        Synthesize          = 1 << 2,
+        PauseResume         = 1 << 1,
+        WordByWordProgress  = 1 << 2,
+        Synthesize          = 1 << 3,
     };
     Q_DECLARE_FLAGS(Capabilities, Capability)
     Q_FLAG(Capabilities)