// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \example quickspeech
    \title Quick Speech Example
    \examplecategory {Data Processing & I/O}
    \ingroup qttexttospeech_examples
    \brief The Quick Speech example reads out user-provided text.
    \meta tags {quick Android}

    \image quickspeech-example.png {Screenshot showing a tool for text to speech
           with options to change engine, locale, voice, volume, pitch, and
           rate}

    The \e{Quick Speech} example demonstrates how the \l[QML]{TextToSpeech} type
    can be used in a \l{Qt Quick} application to read out text and to control
    the speech.

    The example uses \l{Qt Quick Controls} to provide controls for the speech's
    pitch, volume, and rate. It also lets the user select an engine, a
    language, and a voice.

    \section1 Initializing a TextToSpeech
    First, we initialize the text to speech object \c{tts}:

    \snippet quickspeech/Main.qml initialize

    \section1 Getting the status

    \image status.gif {Gif showing a status example of the tool}

    Switch cases are used to update the Label \c statusLabel in the footer.

    \snippet quickspeech/Main.qml stateChanged

    \section1 Highlighting words as they are spoken

    The TextArea \c input is used to get the text to input and the
    \l{TextToSpeech::sayingWord}{onSayingWord} signal as the trigger and also
    to know the position to highlight words as they are spoken.

    \snippet quickspeech/Main.qml sayingWord

     The TextArea \c input is declared here:

    \quotefromfile quickspeech/Main.qml
    \skipto ColumnLayout {
    \printuntil }

    \section1 Controlling speech

    \l Button types are arranged with a \l RowLayout and configured to control
    the TextToSpeech \c tts.

    \section2 The speak button

    A \l Button is created labeled "Speak". It is enabled if \c tts's state
    property is either \l{QTextToSpeech::}{Paused} or \l{QTextToSpeech::}{Ready}.
    When the button is clicked, the available voices on the target devices are
    retrieved, and \c tts.voice is set to the currently selected voice of
    \c voicesComboBox. Then TextToSpeech::say() is called and is passed the
    text in the \c inputbox.

    \snippet quickspeech/Main.qml say0

    \section1 The pause, resume, and stop buttons

    These buttons are similar in implementation to the \c Speak button:

    \snippet quickspeech/Main.qml pause
    \snippet quickspeech/Main.qml resume
    \snippet quickspeech/Main.qml stop

    \section1 Selecting text to speech options

    A \l GridLayout is used to arrange the controls and labels for the selection
    of engine, locale, voice, volume, pitch, and rate options for text to
    speech synthesis.

    \section2 Selecting engine, locale, and voice

    A group of \l{ComboBox} components are used for selecting these parameters.

    For the engine selection ComboBox, \c tts.availableEngines() is used as the
    model.

    The \l{ComboBox::activated}{onActivated} triggers assigning tts.engine the
    current text at the ComboBoxes current index.

    \skipto Label {
    \printuntil updateVoices()
    \printto Label {

    The last two lines in the above code snippet show that the available locales
    and voices are updated at this point as well, as they are dependent on the
    selected engine. Those functions are covered in a
    \l{Updating available options}{following section}.

    The \c localesComboBox is implemented the same way as \c engineComboBox, but
    without updating the available engines.


    \printuntil id: voicesComboBox
    \printto Label

    \section2 Selecting volume, pitch, and rate

    These controls are implemented with \l{Slider}{Sliders} as follows:

    \printto footer: Label {

    \section1 Updating available options

    By using the \c Component.onCompleted signal, the following is done
    once the root ApplicationWindow has been instantiated.

    \list
        \li The \c enginesComboBox index is set to the currently set engine of
            \c{tts}.
        \li The available locales and voices are updated.
        \li The current state of \c tts is signaled.
    \endlist

    \skipto Component.onCompleted: {
    \printto }

    Used throughout the application, the \c updateLocales() and \c updateVoice()
    functions are implemented as follows:

    \printuntil voicesComboBox.currentIndex = indexOfVoice

    \include examples-run.qdocinc

*/
