creator-mobile-app-tutorial.qdoc 9.82 KB
Newer Older
1 2
/****************************************************************************
**
3
** Copyright (c) 2014 Digia Plc and/or its subsidiary(-ies).
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
** 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.
// **********************************************************************

/*!
26
    \contentspage {Qt Creator Manual}
27
    \previouspage creator-writing-program.html
28
    \page creator-mobile-app-tutorial.html
29 30
    \nextpage creator-project-managing.html

31
    \title Creating a Mobile Application
32

33 34 35
    This tutorial describes developing Qt Quick applications for Android and iOS
    devices using Qt Quick Controls.
    We use \QC to implement a Qt Quick application
36 37 38 39 40
    that accelerates an SVG (Scalable Vector Graphics) image based on the
    changing accelerometer values.

    \image creator_android_tutorial_ex_app.png

41 42
    \section1 Setting up the Development Environment

43 44 45 46 47
    To be able to build and run the application on a mobile device, you must
    set up the development environment for the device platform and configure a
    connection between \QC and the mobile device.

    To develop for Android  devices, you must download and install
48
    the latest Android NDK and SDK, and update the SDK to get the API and tools
49
    needed for development. In addition, you must install the
50 51 52 53 54
    Java SE Development Kit (JDK) and Apache Ant. After you have installed all
    these tools, you must specify the paths to them in \QC.
    For detailed instructions, see \l{Qt for Android} and
    \l{Connecting Android Devices}.

55 56 57 58 59
    To develop for iOS devices, you must install Xcode and use it to configure
    a device. For this, you need an Apple developer account and iOS Developer
    Program certificate that you receive from Apple. For more information, see
    \l{Connecting iOS Devices}.

60 61 62 63
    \section1 Creating the Project

    \list 1

64
        \li Select \gui File > \gui {New File or Project} > \gui Application >
65
            \gui {Qt Quick Application} > \gui Choose.
66 67 68 69

        \li In the \gui{Name} field, type \b{accelbubble}.

        \li In the \gui {Create in} field, enter the path for the project files.
70
            For example, \c {C:\Qt\examples}, and then click \gui{Next} (or
71
            \gui Continue on OS X).
72

73
        \li In the \gui {Qt Quick component set} field, select
74
            \gui {Qt Quick Controls 1.1}.
75

76 77
        \li Select \l{glossary-buildandrun-kit}{kits} for Android ARM and iPhone
            OS, and click \gui{Next}.
78 79 80 81 82 83 84

            \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.

85
        \li Review the project settings, and click \gui{Finish} (or \gui Done on
86
            OS X).
87

88 89
    \endlist

90 91
    \QC generates a default QML file that you can modify to create the main view
    of the application.
92 93 94 95 96 97

    \section1 Creating the Main View

    The main view of the application displays an SVG bubble image at the center
    of the main window.

98 99 100 101 102
    To use the Bluebubble.svg used by the Qt Sensors example, Accel Bubble, in
    your project, you must copy it to the project directory (same subdirectory
    as the QML file) from the examples directory in the Qt installation
    directory. For example:
    \c {C:\Qt\Qt5.2.0\5.2.0\msvc2010\examples\sensors\accelbubble\content}.
103
    The image appears in \gui Resources. You can also use any other
104
    image or a QML type, instead.
105 106 107

    \list 1

108 109
        \li In the \gui Projects view, double-click the main.qml file
            to open it in the code editor.
110

111 112 113
        \li Modify the properties of the ApplicationWindow type to specify the
            application name, give the ApplicationWindow an id, and to set it
            visible, as illustrated by the following code snippet:
114

115
            \quotefromfile accelbubble/main.qml
116
            \skipto ApplicationWindow
117
            \printuntil visible
118 119 120
            \skipto /^\}/
            \printuntil }

121
        \li Click \gui Design to open the file in \QMLD.
122

123
        \li In the \gui Navigator, select \gui Label and press \key Delete
124
            to delete it.
125

126
        \li In \gui Library > \gui Resources, select Bluebubble.svg
127
            and drag and drop it to the canvas.
128

129 130
        \li In the \gui Properties pane, \gui Id field, enter \e bubble to be
            able to reference the image from other places.
131

132 133 134
        \li In the code editor, add the following new properties to the image to
            position the image at the center of ApplicationWindow when the
            application starts:
135

136
            \quotefromfile accelbubble/main.qml
137
            \skipto Image
138
            \printuntil bubble.width
139

140 141
         \li Set the x and y position of the image based on the new
            properties:
142 143

            \dots
144 145
            \printuntil centerY
            \skipto /^\}/
146 147 148
            \printuntil }
    \endlist

149
    Here is how the accelbubble.qml file looks after you made the changes:
150

151
    \quotefromfile accelbubble/main.qml
152
    \skipto import QtQuick
153
    \printuntil 1.1
154 155 156 157
    \codeline
    \skipto ApplicationWindow
    \printuntil true
    \skipto Image
158 159 160
    \printuntil y:
    \skipto /^\}/
    \printuntil }
161 162 163 164 165 166 167

    \section1 Moving the Bubble

    Now that the visual elements are in place, let us move the bubble based on
    Accelerometer sensor values.

    \list 1
168
        \li Add the following import statement to main.qml:
169

170 171 172
            \code
            import QtSensors 5.0
            \endcode
173

174
        \li Add the \l{Accelerometer} type with the necessary properties:
175

176
            \quotefromfile accelbubble/main.qml
177 178 179 180 181 182 183 184 185
            \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:

186 187 188 189
            \quotefromfile accelbubble/main.qml
            \skipto function
            \printuntil Math.atan(x
            \printuntil }
190 191 192 193 194

        \li Add the following JavaScript code for \a onReadingChanged signal of
            Accelerometer type to make the bubble move when the Accelerometer
            values change:

195 196 197
            \quotefromfile accelbubble/main.qml
            \skipto onReadingChanged
            \printuntil }
198

199 200 201
            We want to ensure that the position of the bubble is always within
            the bounds of the screen. If the Accelerometer returns not a number
            (NaN), the value is ignored and the bubble position is not updated.
202 203 204
        \li Add SmoothedAnimation behavior on the \a x and \a y properties of
            the bubble to make its movement look smoother.

205 206 207 208 209
            \quotefromfile accelbubble/main.qml
            \skipto Behavior
            \printuntil x
            \printuntil }
            \printuntil }
210 211
     \endlist

212 213 214 215 216 217 218 219 220 221 222 223 224
     \section1 Locking Device Orientation

     The device display is rotated by default when the device orientation
     changes between portrait and landscape. For this example, it would be
     better for the screen orientation to be fixed.

    To lock the orientation to portrait or landscape on Android, specify it in
    an AndroidManifest.xml that you can generate in \QC. For more information,
    see \l{Editing Manifest Files}.

    On iOS, you can lock the device orientation in a Info.plist file that you
    specify in the .pro file as the value of the QMAKE_INFO_PLIST variable.

225
    \section1 Adding Dependencies
226

227 228
    Update the accelbubble.pro file with the following library dependency
    information:
229

230 231 232
    \code
    QT += quick sensors svg xml
    \endcode
233

234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262
    On iOS, you must link to the above libraries statically, by adding the
    plugin names explicitly as values of the QTPLUGIN variable. Specify a
    qmake scope for iOS builds (which can also contain the QMAKE_INFO_PLIST
    variable):

    \code
    ios {
    QTPLUGIN += qsvg qsvgicon qtsensors_ios
    QMAKE_INFO_PLIST = Info.plist
    }
    \endcode

    After adding the dependencies, select \gui Build > \gui {Run qmake} to apply
    the changes to the Makefile of the project.

    \section1 Adding Resources

    You need to add the Bluebubble.svg image file to the application resources
    for deployment to mobile devices:

    \list 1

        \li In the \gui Projects view, double-click the qml.qrc file to open it
            in the resource editor.

        \li Select \gui Add to add Bluebubble.svg.

    \endlist

263
    \section1 Running the Application
264

265
    The application is complete and ready to be deployed to a device:
266

267
    \list 1
268

269 270
        \li Enable \e{USB Debugging} on the Android device or \e{developer mode}
            on the iOS device.
271

272
        \li Connect the device to the development PC.
273 274 275 276 277 278

    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.

279
        \li To run the application on the device, press \key {Ctrl+R}.
280

281
    \endlist
282

283
    \section1 Example Code
284

285
    When you have completed the steps, the main.qml file should look as follows:
286

287 288 289
    \quotefromfile accelbubble/main.qml
    \skipto import
    \printuntil /^\}/
290 291

*/