diff --git a/doc/images/creator_android_tutorial_ex_app.png b/doc/images/creator_android_tutorial_ex_app.png new file mode 100755 index 00000000000..84e876d5f95 Binary files /dev/null and b/doc/images/creator_android_tutorial_ex_app.png differ diff --git a/doc/snippets/qml/tutorial_finalmainqml.qml b/doc/snippets/qml/tutorial_finalmainqml.qml new file mode 100644 index 00000000000..1332a86c634 --- /dev/null +++ b/doc/snippets/qml/tutorial_finalmainqml.qml @@ -0,0 +1,118 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +import QtQuick 2.1 +import QtQuick.Controls 1.0 + +//! [sensorimport] +import QtSensors 5.0 +//! [sensorimport] + + +ApplicationWindow { + title: "Accelerate Bubble" + id: mainWindow + width: 320 + height: 480 + visible: true + + Accelerometer { + id: accel + dataRate: 100 + active:true + + +//! [readingchanged] + onReadingChanged: { + var newX = (bubble.x + calcRoll(accel.reading.x, accel.reading.y, accel.reading.z) * 0.1) + var newY = (bubble.y - calcPitch(accel.reading.x, accel.reading.y, accel.reading.z) * 0.1) + + if (newX < 0) + newX = 0 + + if (newX > mainWindow.width - bubble.width) + newX = mainWindow.width - bubble.width + + if (newY < 18) + newY = 18 + + if (newY > mainWindow.height - bubble.height) + newY = mainWindow.height - bubble.height + + bubble.x = newX + bubble.y = newY + } +//! [readingchanged] + } + +//! [jsfunctions] + function calcPitch(x, y, z) { + return -(Math.atan(y / Math.sqrt(x * x + z * z)) * 57.2957795); + } + function calcRoll(x, y, z) { + return -(Math.atan(x / Math.sqrt(y * y + z * z)) * 57.2957795); + } +//! [jsfunctions] + + Image { + id: bubble + source: "Bluebubble.svg" + smooth: true + property real centerX: mainWindow.width / 2 + property real centerY: mainWindow.height / 2; + property real bubbleCenter: bubble.width / 2 + x: centerX - bubbleCenter + y: centerY - bubbleCenter + +//! [smoothedanim] + Behavior on y { + SmoothedAnimation { + easing.type: Easing.Linear + duration: 100 + } + } + Behavior on x { + SmoothedAnimation { + easing.type: Easing.Linear + duration: 100 + } + } +//! [smoothedanim] + } +} diff --git a/doc/snippets/qml/tutorial_initialqml.qml b/doc/snippets/qml/tutorial_initialqml.qml new file mode 100644 index 00000000000..56f55c678bf --- /dev/null +++ b/doc/snippets/qml/tutorial_initialqml.qml @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [initialcode] +import QtQuick 2.0 + +Rectangle { + width: 100 + height: 62 +} +//! [initialcode] diff --git a/doc/snippets/qml/tutorial_updatedmainview.qml b/doc/snippets/qml/tutorial_updatedmainview.qml new file mode 100644 index 00000000000..bb4dfba0474 --- /dev/null +++ b/doc/snippets/qml/tutorial_updatedmainview.qml @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [imports] +import QtQuick 2.1 +import QtQuick.Controls 1.0 +//! [imports] + +ApplicationWindow { + title: "Accelerate Bubble" + id: mainWindow + width: 320 + height: 480 + visible: true + + Image { + id: bubble + source: "Bluebubble.svg" + smooth: true + property real centerX: mainWindow.width / 2 + property real centerY: mainWindow.height / 2 + property real bubbleCenter: bubble.width / 2 + x: centerX - bubbleCenter + y: centerY - bubbleCenter + } +} diff --git a/doc/snippets/tutorial_accelbubble.pro b/doc/snippets/tutorial_accelbubble.pro new file mode 100644 index 00000000000..430e671df39 --- /dev/null +++ b/doc/snippets/tutorial_accelbubble.pro @@ -0,0 +1,7 @@ +RESOURCES += \ + accelbubble.qrc + +SOURCES += \ + main.cpp + +QT += quick sensors svg xml diff --git a/doc/snippets/tutorial_main.cpp b/doc/snippets/tutorial_main.cpp new file mode 100644 index 00000000000..e5ba8ab34a0 --- /dev/null +++ b/doc/snippets/tutorial_main.cpp @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +#include +#include + +int main(int argc, char *argv[]) +{ + QGuiApplication app(argc, argv); + QQmlApplicationEngine engine(QUrl("qrc:///accelbubble.qml")); + + return app.exec(); +} + diff --git a/doc/src/android/creator-android-app-tutorial.qdoc b/doc/src/android/creator-android-app-tutorial.qdoc new file mode 100644 index 00000000000..ecf946ab848 --- /dev/null +++ b/doc/src/android/creator-android-app-tutorial.qdoc @@ -0,0 +1,288 @@ +/**************************************************************************** +** +** Copyright (c) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of Qt Creator +** +** +** GNU Free Documentation License +** +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** +****************************************************************************/ + +// ********************************************************************** +// NOTE: the sections are not ordered by their logical order to avoid +// reshuffling the file each time the index order changes (i.e., often). +// Run the fixnavi.pl script to adjust the links to the index order. +// ********************************************************************** + +/*! + \contentspage index.html + \previouspage creator-writing-program.html + \page creator-android-app-tutorial.html + \nextpage creator-project-managing.html + + \title Creating an Android Application + + This tutorial describes developing Qt Quick applications for Android devices + using Qt Quick Controls. + + This tutorial describes how to use \QC to implement a Qt Quick application + that accelerates an SVG (Scalable Vector Graphics) image based on the + changing accelerometer values. + + \image creator_android_tutorial_ex_app.png + + \section1 Creating the Project + + Let us start with creating an empty Qt project. + + \list 1 + + \li Select \gui{File > New File or Project > Other Project > + Empty Qt Project > Choose}. + + \li In the \gui{Name} field, type \b{accelbubble}. + + \li In the \gui {Create in} field, enter the path for the project files. + For example, \c {C:\Qt\examples}, and then click \gui{Next} (on + Mac OS X, it is \gui Continue). + + \li Select an Android \l{glossary-buildandrun-kit}{kit} for arm, + and click \gui{Next}. + + \note Kits are listed if they have been specified in \gui Tools > + \gui Options > \gui{Build & Run} > \gui Kits. + + \li Select \gui Next in the following dialogs to use the default + settings. + + \li Review the project settings, and click \gui{Finish} (on Mac OS X, + it is \gui Done). + \endlist + + \QC creates the project and displays its contents under the \gui Projects + view on the sidebar. You can only see a .pro file under the project as we + created an empty project, but the remaining bits will be added + during the course of this tutorial. + + \section1 Creating the Main View + + The main view of the application displays an SVG bubble image at the center + of the main window. + + \list 1 + + \li In the \gui Edit mode, right-click on the \b{accelbubble} project + and select \gui{Add new} to open the \gui{New File} dialog. + + \li Select \gui{Qt > QML File (Qt Quick 2)} and click \gui Choose to + give a name to the QML file. + + \li In the \gui Name field, type "accelbubble" and select \gui Next. + + \li Select \gui Finish to add accelbubble.qml to the project. + \endlist + + \QC adds a default QML file containing a Rectangle. Here is how the QML + file looks: + + \snippet qml/tutorial_initialqml.qml initialcode + + Now let us edit accelbubble.qml to add the bits required for our + application. + + \list 1 + + \li Replace the existing import statement with the following: + + \snippet qml/tutorial_updatedmainview.qml imports + + \li Replace the Rectangle type with ApplicationWindow, which + will be the top-level window for our application. + + \li Set the \a id, \a title, \a visible, and the window dimension + properties (width and height) with the values given in the + following snippet: + + \quotefromfile qml/tutorial_updatedmainview.qml + \skipto ApplicationWindow + \printuntil true + \skipto /^\}/ + \printuntil } + \endlist + + \section1 Adding an SVG Image + + SVG is an XML-based image format that enables you to combine vector + graphics, raster graphics, and text into one image. It is based on + an open standard developed and maintained by \l{http://www.w3.org/}{W3C}. + + Qt supports the \l{http://www.w3.org/TR/SVGTiny12/}{SVGT} v1.2, which is a + trimmed version of the \l{http://www.w3.org/TR/SVG12/}{SVG Full v1.2} + specification, for mobile devices. + + You can copy the Bluebubble.svg used by the Qt Sensors example, Accel + Bubble, to your project directory or find an SVG image that uses SVGT v1.2. + + \note If you choose to create a new SVG image, ensure that the \a svg root + element has the \a version attribute with the value 1.1 or 1.2, and baseProfile + with \c tiny. + + \list 1 + \li Open accelbubble.qml in \gui Edit mode and add an Image type + within the ApplicationWindow. + \li Set the image \a id, \a source, and \a smooth properties as shown + in the following code block: + + \quotefromfile qml/tutorial_updatedmainview.qml + \skipto Image + \printuntil true + + \li Add the following new properties to the image: + + \dots + \printuntil bubbleCenter: + + \note These properties are used to position the image + at the center of ApplicationWindow when the application starts. + \li Set the x and y position of the image based on the new + properties. + + \dots + \printuntil } + \endlist + + Here is how the accelbubble.qml file looks after making the changes + mentioned earlier in this section: + + \quotefromfile qml/tutorial_updatedmainview.qml + \skipto import QtQuick + \printuntil 1.0 + \codeline + \skipto ApplicationWindow + \printuntil true + + \skipto Image + \printuntil /^\}\ + + + \section1 Moving the Bubble + + Now that the visual elements are in place, let us move the bubble based on + Accelerometer sensor values. + + \list 1 + \li Add the following import statement to accelbubble.qml: + + \snippet qml/tutorial_finalmainqml.qml sensorimport + + \li Add the Accelerometer type with the necessary properties as shown + in the following code block: + + \quotefromfile qml/tutorial_finalmainqml.qml + \skipto Accelerometer + \printuntil true + \skipto } + \printuntil } + + \li Add the following JavaScript functions that calculate the + x and y position of the bubble based on the current Accelerometer + values: + + \snippet qml/tutorial_finalmainqml.qml jsfunctions + + \li Add the following JavaScript code for \a onReadingChanged signal of + Accelerometer type to make the bubble move when the Accelerometer + values change: + + \snippet qml/tutorial_finalmainqml.qml readingchanged + + \li Add SmoothedAnimation behavior on the \a x and \a y properties of + the bubble to make its movement look smoother. + + \snippet qml/tutorial_finalmainqml.qml smoothedanim + \endlist + + + \section1 Running the Application + + The main view is complete but the application is not ready yet. This + section provides instructions to add a few lines of C++ code that loads the + QML file when you try to run the application on an Android device. + + \list 1 + \li Right-click on the project in \gui Edit mode and select + \gui{Add New > Qt > Qt Resource File}. + + \li Name the resource file as \a accelbubble.qrc and click \gui Next. + + \li Select \gui Finish in the following dialog to add the resource file + to the project and open it in \gui Edit mode. + + \li Select \gui {Add > Add Prefix} and add \c / as the prefix. + + \note The prefix is used every time you refer to the .qrc file + contents from the C++ code. + + \li Select \gui {Add > Add Files} and add accelbubble.qml and Bluebubble.svg + to the resource file. + + \li Right-click on the project in \gui Edit mode and select + \gui {Add New} to open the \gui {New File} dialog. + + \li Select \gui {C++ > C++ Source File > Choose} + + \li Name the file as \a main.cpp and click \gui Next. + + \li Select \gui Finish to add main.cpp to the project and open it in + edit mode. + + \li Add the following lines of C++ code to main.cpp to load the + accelbubble.qml file from accelbubble.qrc: + + \quotefromfile tutorial_main.cpp + \skipto #include + \printuntil } + + \li Update the accelbubble.pro file with the following library + dependency information: + + \code + QT += quick sensors svg xml + \endcode + \endlist + + The application is complete and ready to be deployed to the device. + Enable "USB Debugging" on your Android device and connect it to your PC. + If you are using a device running Android v4.2.2, it should prompt you to + verify the connection to allow USB debugging from the PC it is connected + to. To avoid such prompts every time you connect the device, check + "Always allow from the computer" and select \gui OK. + + To run the application on the device, press CTRL + R keys in \QC + \gui Edit mode. + + \section1 Example Code + + When you have completed the steps mentioned in the earlier sections, the + accelbubble.qml, main.cpp, and accelbubble.pro files look as follows: + + \section2 accelbubble.qml + + \quotefile qml/tutorial_finalmainqml.qml + + \section2 main.cpp + + \quotefile tutorial_main.cpp + + \section2 accelbubble.pro + + \quotefile tutorial_accelbubble.pro +*/ diff --git a/doc/src/overview/creator-tutorials.qdoc b/doc/src/overview/creator-tutorials.qdoc index b3513c2943e..7dad18d9f98 100644 --- a/doc/src/overview/creator-tutorials.qdoc +++ b/doc/src/overview/creator-tutorials.qdoc @@ -46,6 +46,11 @@ Learn how to create a Qt widget based application for the desktop. + \li \l{Creating an Android Application} + + Learn how to create a Qt Quick application using Qt Quick Controls + for Android devices. + \endlist */ diff --git a/doc/src/projects/creator-projects-overview.qdoc b/doc/src/projects/creator-projects-overview.qdoc index 072368a03e7..a72d16a9df5 100644 --- a/doc/src/projects/creator-projects-overview.qdoc +++ b/doc/src/projects/creator-projects-overview.qdoc @@ -24,7 +24,7 @@ /*! \contentspage index.html - \previouspage creator-writing-program.html + \previouspage creator-android-app-tutorial.html \page creator-project-managing.html \nextpage creator-project-creating.html diff --git a/doc/src/qtcreator.qdoc b/doc/src/qtcreator.qdoc index f5662893675..b8d8ddc9d62 100644 --- a/doc/src/qtcreator.qdoc +++ b/doc/src/qtcreator.qdoc @@ -154,6 +154,7 @@ \list \li \l{Creating a Qt Quick Application} \li \l{Creating a Qt Widget Based Application} + \li \l{Creating an Android Application} \endlist \endlist \li \l{Managing Projects} diff --git a/doc/src/widgets/qtdesigner-app-tutorial.qdoc b/doc/src/widgets/qtdesigner-app-tutorial.qdoc index 65a58b88a43..1cdfcf35060 100644 --- a/doc/src/widgets/qtdesigner-app-tutorial.qdoc +++ b/doc/src/widgets/qtdesigner-app-tutorial.qdoc @@ -26,7 +26,7 @@ \contentspage index.html \previouspage creator-qml-application.html \page creator-writing-program.html - \nextpage creator-project-managing.html + \nextpage creator-android-app-tutorial.html \title Creating a Qt Widget Based Application