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

/*!
  \example demos/android/splashscreen/quick
  \title Implementing a splash screen with Qt Quick on Android
  \brief Showcase how to setup a splash screen with Qt Quick View on Android.
  \meta {tag}{android}
  \ingroup android-platform-extra-topics
  \image splash-screen-launch.webp

  This simple example demonstrates using a QML view as a Qt splash screen. No
  additional transitions are used. In this example, the default splash screen,
  that was introduced in Android 12, is hidden. When the application starts, the
  splash screen is shown for two seconds, after which the main view is shown
  without transition.

  This example is one of series of two similar examples demonstrating splash
  screen. This one uses QML view,
  \l{Implementing a splash screen with Qt Quick on Android}{the other}
  uses AndroidManifest flags.

  \section1 Using the Qt Quick splash screen on Android

  To use a QML \l View as a splash screen, you define a View and add a few items specific to
  splash screen functionality.

  \snippet demos/android/splashscreen/quick/Splash.qml Splash view header

  \list
    \li \c{modality: Qt.ApplicationModal} sets the view modal.
    \li \c{flags: Qt.SplashScreen} hides the titlebar.
    \li \c{property int timeoutInterval: 2000} sets the visibility time for the
    view.
  \endlist

  \section2 Loading the main view

  \snippet demos/android/splashscreen/quick/Splash.qml Loader

  The timer calls the exit function on timeout to switch from the splash screen
  to the main view. Any possible out-animations would be initiated here.

  \snippet demos/android/splashscreen/quick/Splash.qml Exit function for timer

  The timer allows appropriate time for the splash screen to appear. This can be
  used in conjunction with \l{Loader::onLoaded()} signal or possibly with another
  signal originating from the app implementation when the app is ready to be
  shown.

  \snippet demos/android/splashscreen/quick/Splash.qml The timer

  On launch, the default splash screen is shown before the first view of the
  application is shown. See \l{Android Splash screens} for the instructions on
  modifying it.
  \br By default, Android uses the applications icon for the splash screen. On
  a Qt for Android application, this can be modified to be used as the app
  splash screen or it can be combined with the Qt splash screen.

  \section2 Hiding the native Android splash screen

  To keep the launch user experience consistent between platforms, it may be
  needed to hide the Android splash screen. To do this, define a translucent
  theme that effectively hides the Android splash screen.

  \quotefile demos/android/splashscreen/quick/android/res/values/splashstarttheme.xml

  There is a problem though. Orientation changes stop working if we have
  translucent theme. This is caused by the fact that the Android view gets
  its orientation from the underlying view, usually this is an Application
  Drawer which does not change its orientation. And because the theme cannot be
  changed after the Activity view is set, we end up with an application stuck
  in one orientation.
  \br As a workaround we can create throwaway Activity with translucent theme
  for the Android splash screen. As soon as possible we launch another Activity,
  which has all the bells and whistles our application requires.

  \snippet demos/android/splashscreen/quick/android/AndroidManifest.xml Startup activity

  Now the native Android splash screen is \e not shown, and we launch the
  QtActivity, which shows the splash screen defined in QML. To launch the QML
  splash screen, we must override the Android Activity's \c onCreate method and
  use an Intent to launch the QtActivity.

  \quotefile demos/android/splashscreen/quick/android/java/io/qt/qmlsplashscreeninandroid/SplashActivity.java

  Finally, the QML splash screen opens the main view, which in this example
  contains just a single View with a close button.
*/
