Revision control
++ // Copyright (C) 2026 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \page android-getting-started.html
++ \title Getting Started with Qt for Android
++ \brief A beginner's guide to install Qt and the Android toolchain and create
++ your first Qt for Android app with Qt Creator IDE.
++
++ This tutorial describes how to use \QC to develop a Qt Quick application for
++ Android devices.
++
++ You develop a Qt Quick application that accelerates an SVG (Scalable Vector
++ Graphics) image based on changing accelerometer values.
++
++ \image {android/android-gettingstarted-project-result.webp}
++ {Accelerate Bubble example}
++
++ \section1 Set up the development environment
++
++ To get started with Qt for Android:
++
++ \list 1
++ \li Download and install Qt. To do this, follow the instructions on the
++ \l{Get and Install Qt} page.
++ \li Install all the necessary tools and configure the development
++ environment as explained in \l {Qt for Android Prerequisites}.
++ \endlist
++
++ \section1 Create the project
++
++ \list 1
++
++ \li Open \QC. Go to \uicontrol File > \uicontrol {New Project} >
++ \uicontrol {Application (Qt)} > \uicontrol {Qt Quick Application}.
++
++ \image {android/android-gettingstarted-create-quick-project.webp}
++ {New Project dialog}
++
++ \li Select \uicontrol {Choose...} to open the \uicontrol {Project Location}
++ dialog.
++
++ \li In \uicontrol Name, enter a name for the application.
++
++ \image {android/android-gettingstarted-project-name-location.webp}
++ {Project Location dialog}
++
++ \li In \uicontrol {Create in}, enter the path for the project files. You can
++ move project folders later without problems.
++
++ \li Select \uicontrol Next (or \uicontrol Continue on \macos) to open the
++ \uicontrol {Define Project Details} dialog.
++
++ \image {android/android-gettingstarted-project-details.webp}
++ {Define Project Details dialog}
++
++ \li Select \uicontrol Next (or \uicontrol Continue on \macos) to open the
++ \uicontrol {Kit Selection} dialog.
++
++ \li Select \l{\QC: Kits}{kits} for the platforms that you want to build
++ the application for.
++
++ \image {android/android-gettingstarted-project-kit-selection.webp}
++ {Selecting kits for the project}
++
++ \note The list shows kits that you specify in \uicontrol {Preferences} >
++ \uicontrol Kits.
++ For more information, see \l {\QC: Add kits}{Add kits} and
++ \l {\QC: Kits}{Managing kits}.
++
++ \li Select \uicontrol Next (or \uicontrol Continue on \macos) to open the
++ \uicontrol {Project Management} dialog.
++
++ \li Review the project settings, and select \uicontrol{Finish}
++ (or \uicontrol Done on \macos) to create the project.
++
++ \image {android/android-gettingstarted-project-management.webp}
++ {Project Management dialog}
++ \endlist
++
++ \section1 Add images as resources
++
++ The main view of the application displays an SVG bubble image that moves around
++ the screen when you tilt the device.
++
++ For the image to appear when you run the application, you must specify it as a
++ resource in the \c RESOURCES argument of the \c qt_add_qml_module() method in
++ the \c CMakeLists.txt file that the wizard created for you:
++
++ \snippet tutorials/android-app/CMakeLists.txt qml-module
++
++ \section1 Create the Accelbubble main view
++
++ \list 1
++
++ \li In the \uicontrol Projects view, select \c Main.qml. In the \c Main.qml
++ file, replace the content with the following code:
++
++ \snippet tutorials/android-app/Main.qml create-image-0
++ \snippet tutorials/android-app/Main.qml create-image-1
++ \snippet tutorials/android-app/Main.qml create-image-2
++ \snippet tutorials/android-app/Main.qml create-image-4
++ \snippet tutorials/android-app/Main.qml create-image-5
++
++ This code changes the default \l Window properties and adds the recently
++ added image to the view. You can use any other image or component instead.
++
++ \li Add custom properties to position the image in respect to the width and
++ height of the main window:
++
++ \snippet tutorials/android-app/Main.qml create-image-0
++ \snippet tutorials/android-app/Main.qml create-image-1
++ \snippet tutorials/android-app/Main.qml create-image-2
++ \snippet tutorials/android-app/Main.qml create-image-3
++ \snippet tutorials/android-app/Main.qml create-image-4
++ \snippet tutorials/android-app/Main.qml create-image-5
++
++ \li Add the following import statement:
++
++ \snippet tutorials/android-app/Main.qml import-sensors
++
++ It is required because we want to move the bubble based on
++ Accelerometer sensor values.
++
++ \li Add the \l{Accelerometer} component with the necessary properties:
++
++ \snippet tutorials/android-app/Main.qml create-image-0
++ \snippet tutorials/android-app/Main.qml import-sensors
++ \snippet tutorials/android-app/Main.qml accelerometer-1
++ \dots
++ \snippet tutorials/android-app/Main.qml accelerometer-2
++ \snippet tutorials/android-app/Main.qml accelerometer-4
++ \dots
++
++ \li Add the following JavaScript functions that calculate the x and y position
++ of the bubble based on the current Accelerometer values:
++
++ \snippet tutorials/android-app/Main.qml create-image-0
++ \snippet tutorials/android-app/Main.qml import-sensors
++ \snippet tutorials/android-app/Main.qml accelerometer-1
++ \dots
++ \snippet tutorials/android-app/Main.qml accelerometer-3
++ \dots
++ \snippet tutorials/android-app/Main.qml accelerometer-4
++ \snippet tutorials/android-app/Main.qml calc-functions
++ \dots
++
++
++ \li Add the following JavaScript code for \c onReadingChanged signal of
++ Accelerometer component to make the bubble move when the Accelerometer
++ values change:
++
++ \snippet tutorials/android-app/Main.qml accelerometer-2
++ \snippet tutorials/android-app/Main.qml on-reading-changed
++ \snippet tutorials/android-app/Main.qml accelerometer-4
++
++ You need to ensure that the position of the bubble is always within the
++ bounds of the screen. If the Accelerometer returns \e {not a number} (NaN),
++ the value is ignored and the bubble position is not updated.
++
++ \li Add \l SmoothedAnimation behavior on the \c x and \c y properties of the
++ bubble to make its movement look smoother.
++
++ \snippet tutorials/android-app/Main.qml create-image-2
++ \dots
++ \snippet tutorials/android-app/Main.qml smoothed-animation
++ \dots
++ \endlist
++
++ \section1 Lock device orientation
++
++ By default, the display rotates when the device orientation changes between
++ portrait and landscape. This application looks better if you lock the screen
++ orientation to portrait mode.
++
++ On Android, you set the screen orientation in the \c AndroidManifest.xml file,
++ which you generate in \QC. To lock the orientation to portrait:
++
++ \list 1
++ \li Go to \uicontrol {Tools} > \uicontrol {Android} >
++ \uicontrol {Manifest XML Source}. \QC creates the file in an \e android
++ directory inside your project directory and opens it in the manifest
++ editor.
++
++ \li In the manifest editor, select \uicontrol {XML Source} and set the
++ \c android:screenOrientation attribute of the \c activity element to
++ \c portrait.
++
++ \code{xml}
++ <?xml version='1.0'?>
++ <manifest ...>
++ <supports-screens.../>
++ <!--%%INSERT_PERMISSIONS-->
++ <!--%%INSERT_FEATURES-->
++ <application ...>
++ <activity ... android:screenOrientation="portrait">
++ ...
++ \endcode
++
++ For more information, see
++ \l{\QC: Edit Android manifest files}{Edit Android manifest files}.
++ \endlist
++
++ \section1 Add dependencies
++
++ The application uses the Qt Sensors and Qt SVG modules, so you should add them
++ as dependencies in the \c CMakeLists.txt file. To add the dependencies:
++
++ \list 1
++ \li Add the \c Sensors and \c Svg components to the \c find_package
++ function. This tells CMake to look up the Qt installation and import the
++ modules:
++
++ \snippet tutorials/android-app/CMakeLists.txt find-package
++
++ \li Add the imported targets to the \c target_link_libraries function:
++
++ \snippet tutorials/android-app/CMakeLists.txt link-libraries
++
++ This tells CMake that the \c accelbubble executable uses the modules.
++ CMake then passes the necessary arguments to the linker, and the
++ appropriate include directories and compiler definitions to the C++
++ compiler.
++
++ \li To apply the configuration changes, go to \uicontrol Build and select
++ \uicontrol {Run CMake}.
++ \endlist
++
++ For more information about the \c CMakeLists.txt file, see
++ \l{Getting started with CMake}.
++
++ \note If you have not installed all the Qt modules listed in \c find_package(),
++ \QC asks whether you want to install them with \QOI.
++
++ \section1 Run the application
++
++ You can now deploy the application to a real or virtual Android device.
++
++ If you use a real device:
++
++ \list 1
++ \li Enable \e{USB Debugging} on the Android device.
++ \li Connect the device to the development PC.
++ \endlist
++
++ If you have several devices connected, \QC allows you to select the device to
++ run the application on.
++
++ \image {android/android-gettingstarted-select-device.webp}
++ {Chose the device to run the application on}
++
++ To run the application on the device, select \key {Ctrl+R} (\key {Cmd+R}).
++
++ Once the application started on the device, you can tilt the device to see the
++ bubble move around the screen. The bubble moves in the direction of the tilt,
++ and the speed of the movement depends on the tilt angle. The bubble moves
++ faster when you tilt the device more.
++
++ \image {android/android-getting-started-result-in-action.gif}
++ {Running the application on an Android device}
++
++ \sa {Qt Academy - Getting Started with Qt for Android}{Qt Academy: Getting Started with Qt for Android},
++ {Design Qt Quick UIs}{How to: Design Qt Quick UIs}, {Qt Quick UI design},
++ {Designing Qt Quick UIs}
++
++ */