<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- android.qdoc -->
<title>Android | QtDoc 5.1</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader"></div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#getting-started">Getting Started</a></li>
<li class="level1"><a href="#porting-an-existing-qt-application">Porting an Existing Qt Application</a></li>
<li class="level1"><a href="#related-information">Related Information</a></li>
</ul>
</div>
<h1 class="title">Android</h1>
<span class="subtitle"></span>
<!-- $$$android_support.html-description -->
<div class="descr"> <a name="details"></a>
<p>Qt for Android enables you to run Qt 5 applications on devices with Android v2.3.3 (API level 10) or later. Here is a list of supported items:</p>
<ul>
<li>Qt Widgets and <a href="qtquick-applicationdevelopers.html">QML</a> applications</li>
<li>QML media player functionality in Qt Multimedia</li>
<li>A set of commonly used sensors with Qt Sensors</li>
<li>Deploying your application to a device from <a href="http://qt-project.org/doc/qtcreator/index.html">Qt Creator</a></li>
</ul>
<a name="getting-started"></a>
<h2>Getting Started</h2>
<p>In order to use Qt for Android, you will need the following external tools:</p>
<ul>
<li><a href="http://developer.android.com/sdk/index.html">The Android SDK Tools</a></li>
<li><a href="http://developer.android.com/tools/sdk/ndk/index.html">The Android NDK</a></li>
<li><a href="http://ant.apache.org/bindownload.cgi">Apache Ant</a> v1.8 or later</li>
<li><a href="http://openjdk.java.net">OpenJDK</a> v6 or later</li>
<li>Android Debug Bridge (ADB) driver on the Windows platform to enable USB debugging. The default USB driver on Windows does not allow debugging. You can download the ADB driver from the device manufacturer's support website. For example, the ADB driver for Google Nexus 7 can be downloaded from <a href="http://support.asus.com">http://support.asus.com</a>.<p>After installing the driver, try running a few basic <a href="http://developer.android.com/tools/help/adb.html">adb</a> commands and check whether your device responds to it.</p>
</li>
</ul>
<p><b>Note: </b>You must set the <tt>JAVA_HOME</tt> environment variable to the JDK install directory path so that Qt Creator finds the binaries required to build your application.</p><p>After installing these tools, update the Android SDK to get the API and tools packages required for development. You can update the SDK using the <a href="http://developer.android.com/tools/help/android.html">android</a> tool that comes with the SDK Tools package. For example, on Ubuntu the following command starts the <a href="http://developer.android.com/sdk/installing/adding-packages.html">Android SDK Manager</a>, which enables you to select the packages you want to install:</p>
<pre class="cpp"><span class="operator">.</span><span class="operator">/</span>android update sdk</pre>
<p>After the SDK is updated, install the Qt 5.1 binaries using the <a href="qtinstaller.html">Qt installation program</a> and configure Qt Creator to develop for Android. For more information, see <a href="http://qt-project.org/doc/qtcreator/creator-developing-android.html">Qt Creator: Connecting Android Devices</a>.</p>
<p><b>Note: </b>You must select at least one of the two Qt libraries for Android (x86 and ARMv7) from the <b>Qt 5.1.0</b> component tree in the <b>Select Components</b> page of <a href="qtinstaller.html">Qt installation program</a>. By default, Qt libraries for ARMv7 are selected.</p><p>Test your setup by running one of the desktop examples. You can list all the examples tested for Android using the <tt>android</tt> keyword in the search field under the <b>Examples</b> tab in Qt Creator <b>Welcome</b> mode.</p>
<a name="porting-an-existing-qt-application"></a>
<h2>Porting an Existing Qt Application</h2>
<p>Most Qt applications should be portable to Android with ease, unless they depend on a specific hardware or software feature not supported by Android. If your application is not using any such feature, deployment is probably the only step that demands some changes to your application.</p>
<p>Like most UI applications, Qt applications also depend on resources such as images, icons, translation files, and so on. These resources must be made available on the device as they are required for the application to function effectively.</p>
<p>The most convenient option is to bundle the resources into a qrc file, which gets built into the application binary. This approach reduces the porting effort considerably and provides faster access to the resources. It is also a cross-platform approach, which makes porting to other platforms easier.</p>
<p>By default, all Qt applications can access the contents of a qrc file using the ":/" prefix or the URL scheme prefix, "qrc:". To know more about qrc files and how they are handled, see the Qt Resource System.</p>
<p>The other approach is to deploy the resources into the package's <tt>assets</tt> directory. It is the best option if you want to achieve better interoperability with the Android APIs. You can access all resources in the directory using the "assets:" prefix. Unlike qrc, this approach is not a cross-platform solution.</p>
<p>The following step-by-step instructions guide you to port an existing Qt Quick application to Android using the qrc approach:</p>
<ol class="1">
<li>Open the existing project in Qt Creator v2.7.1 or later, and configure it with "Android for ARM" kit. For more information, see <a href="http://qt-project.org/doc/qtcreator/creator-configuring-projects.html">Qt Creator: Configuring Projects</a></li>
<li>Update all local directory imports in the <tt>qml</tt> files to use a local namespace. For example, to import the QML documents in the "contents" directory relative to <tt>main.qml</tt>, use the following import statement:<pre class="cpp"> import <span class="string">"contents"</span> as Contents</pre>
</li>
<li>Identify all the resources used by your application and add them to one or more qrc files. Qt Creator updates your qmake project file with the "RESOURCES" variable listing the qrc files you added.</li>
<li>To load or refer to the resources in the qrc file from a C++ file, use the "qrc:" prefix with the URL. For example, to load the <tt>main.qml</tt> file from <tt>resources.qrc</tt>, you can use the following code in your <tt>main</tt> function:<pre class="cpp"> <span class="type">QQuickView</span> viewer;
viewer<span class="operator">.</span>setSource(<span class="type">QUrl</span>(<span class="string">"qrc:qml/main.qml"</span>));
viewer<span class="operator">.</span>show();</pre>
<p><b>Note: </b>QML documents can refer to the contents in qrc files using the relative path to the document. Such references do not require the "<tt>qrc:</tt>" or "<tt>:/</tt>" prefix.</p></li>
<li>Update the "Run" settings for your project as described in the <a href="http://qt-project.org/doc/qtcreator/creator-run-settings.html">Qt Creator: Specifying Run Settings</a><p><b>Note: </b>You can change the default settings for application icons and identifier.</p></li>
<li>If your application uses imports or plugins which depend on special Qt modules, these Qt modules should be added to the .pro file. For example, if your app uses the Qt Multimedia import in QML, you should add the following to your .pro file:<pre class="cpp"> QT <span class="operator">+</span><span class="operator">=</span> multimedia</pre>
</li>
<li>Save the changes to your project and run the application.</li>
</ol>
<p>Qt Creator deploys your application on the Android device, if the device is detected by the PC. Otherwise, it tries to run the application on an AVD (Android Virtual Device). You will be prompted to create one if there are no AVDs found.</p>
<a name="related-information"></a>
<h2>Related Information</h2>
<ul>
<li><a href="platform-notes-android.html">Platform Notes</a></li>
<li><a href="http://qt-project.org/doc/qtcreator/creator-deploying-android.html">Qt Creator: Deploying Applications to Android Devices</a></li>
<li><a href="android-runtime-licensing-notes.html">Android GNU C++ run-time licensing</a></li>
</ul>
</div>
<!-- @@@android_support.html -->
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Digia, Qt and their respective logos are trademarks of Digia Plc
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
</body>
</html>
