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


/*!
    \page qt-tools-for-android-studio.html
    \title \QtTAS
    \brief Provides an overview and getting started guide for the plugin.

    \section1 Overview

    What you need to know about the plugin:

    \section2 Features

    The plugin allows you to import new or existing Qt QML projects to a new or
    existing Android Studio project.

    \section2 Supported configurations

    You can find what is supported here.

    \section3 Host environments

    The \l{Supported Platforms}{host environment limitations} for building
    Qt applications also exist for the plugin. The plugin has been tested on
    the following operating systems:
    \list
        \li Linux (Ubuntu 22.04)
        \li Windows (10, 11)
        \li macOS ARM (Xcode version 15.2)
    \endlist

    \section3 Android Studio

    Android Studio Giraffe (2022.3.1) to Iguana (2023.2.1) is supported.

    \section3 Qt for Android

    \l{Qt for Android} version 6.7 or later is required.

    \section3 Android SDK

    \include supported-platforms.qdocinc android

    \section3 Tools

    The \l{Getting started with CMake}{CMake} and Ninja versions that are
    supported are packaged with the version of Qt you are installing.

    \section2 Licensing

    This plugin is covered by the \l{Qt Licensing Overview}{Qt Community Edition}
    license.

    \section1 Getting started

    The following video covers installing the plugin, installing all the minimum
    required Qt dependencies for using the plugin, runs through importing an example
    Qt for Android project, and building and running the project on a target device.

    \youtube _AkKSLp5FnM

    The following sections will cover this information, as well as further
    details on the plugin's features and UI.

    \section2 Installing dependencies

    \list
        \li Qt for Android installation (6.7 or later)
        \li Google's Android Studio IDE
        \li The \l{Android Development Prerequisites}{Android SDK}
    \endlist

    \section3 Install Qt for Android

    There are two ways to get Qt for Android, but for most users, we recommended
    the following way:

    \section4 With the \QOI

    To download and install Qt for Android, follow the instructions on the
    \l{Get and Install Qt} page, and do a custom install that includes at
    least the minimum requirements:

    \list
        \li Qt for Android
        \li CMake
        \li Ninja
    \endlist

    The following instructions assume you don't want to install \l{\QDS} and
    \l{Qt Creator}. These would normally be installed by default but the instructions
    here explicitly deselect these and anything not required.

    \list 1
        \li Select custom install. If you change the location make sure to note
        this as you will need it later.
        \li Deselect \uicontrol{\QDS}.
        \li Expand \uicontrol{Qt 6.7} or later and select \uicontrol{Qt for Android}.
        \li Deselect \uicontrol{Developer and Designer Tools}.
        \li Select \uicontrol{CMake} and \uicontrol{Ninja}.
        \li Select any optional Qt modules you might need.
        \li Proceed to install.
    \endlist

    \section4 Clone, build and install Qt yourself

    This method should only be used by developers who are working with unreleased
    or modified Qt builds. It won't be covered here.

    See \l{Qt for Android - Building from Source}.

    \section3 Install Android Studio and the plugin

    This plugin is installed like any other IntelliJ plugin.

    \list 1
        \li\l{https://developer.android.com/studio}{Download} and install Android
        Studio version Giraffe | 2023.1.1 Canary 1 or later.
        \li Head to the plugin's Intellij marketplace page to
        \l{https://plugins.jetbrains.com/plugin/24060-qt-tools-for-android-studio}{download}
            the plugin's jar file.
        \li Start Android Studio.
        \li On top-right corner select \uicontrol{Settings(gear-icon)->Install Plugins From Disk}
        \image android-studio-plugin/select_gear_install_plugin.png
        \li Select file and select \uicontrol{OK}.
        \image android-studio-plugin/selectpluginjar.png
        \li Check that the plugin is installed.
        \image android-studio-plugin/CheckPluginInstall.png
    \endlist

    \section3 Configure the plugin

    The plugin needs to know where certain parts of the Qt toolchain are.

    \list 1
        \li On top-left corner select \uicontrol{File -> Settings}.
        \image android-studio-plugin/Android_Studio_Settings.png
        \li Expand \uicontrol{Build,Execution,Deployment} and Select \uicontrol{Qt}.
        \image android-studio-plugin/Settings_Qt.png
        \li On this page, you need to set the path to the \b{qt-cmake} script,
        located in\c{[Qt Folder Path]/<qt version>/android_<architecture>/bin}.
        Make sure to select the right architecture for the platform you are
        targeting.
        \image android-studio-plugin/SettingsSet.png
        \list
            \li For a windows host select \c{qt-qmake.bat}.
            \li For other operating systems select \c{qt-cmake}.
        \endlist
    \endlist

    \note The \uicontrol {Additional CMake flags} field allows you to modify
    your projects CMake call.

    \section3 Install the Android SDK

    Use Android Studio's SDK manager to install the correct API, platform, and
    tools for this version of Qt. See \l{Android SDK}.

    \section2 Running the example

    Test your development setup by running the examples shipped with
    the Qt installation. You'll need to know your Qt folder path first.
    When using the \QOI, the default install locations for the Qt folder are:
    \list
         \li Windows: C:/Qt
         \li macOS: ~/Qt
         \li Linux: ~/Qt
    \endlist

    The example projects are located under your Qt installation directory
    in \c{Qt/Examples/<qt version>/qtdeclarative/examples/platforms/android/}.
    To test the examples:
    \list 1
      \li From Android Studio's welcome screen, select \uicontrol{Open}.
      \image android-studio-plugin/open_existing_project.png
      \li Select the Qt project example you want.
      \image android-studio-plugin/select_example_project.png
   \endlist

    \section2 Compiling and deploying to a target device or emulator

    To compile and deploy, select \uicontrol Run.

    \image android-studio-plugin/android_studio_select_run.png

    This will build the Qt project and the Android Studio project and run it.

    \note Selecting \uicontrol{Make Project} will not build the Qt project.

    \section2 Debugging

    Debugging QML or C++ is not possible with the plugin. For that,
    see \l{Qt Creator}.

    \section1 Writing your first application from scratch

    \list 1
    \li From Android Studio top-left select \uicontrol{File -> New -> New Qt Project}.
    \image android-studio-plugin/create_new_Qt_project_1.png
    \li Set the \uicontrol{name} for the project, select the projects folder,
    select the \c{Qt version} and select \uicontrol OK.
    \image android-studio-plugin/create_new_Qt_project_2.png
    \li Start writing your first Qt QML application!
    \endlist

    If you are a returning user or just getting started with QML, the
    \l{The QML Reference}{QML Reference} has what you need.

    \section1 Integrating QML in an Android application

    The \l{embedded_qml_target}{API documentation} for embedding QML in Android
    applications has specific implementation details and insights into this.

*/
