creator-mobile-app-tutorial.qdoc 10.7 KB
Newer Older
1 2
/****************************************************************************
**
3 4
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
5
**
6
** This file is part of the Qt Creator documentation.
7
**
8 9 10 11 12 13 14
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
15
**
16
** GNU Free Documentation License Usage
17 18
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
19 20 21 22
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
23 24 25 26 27 28 29 30 31 32
**
****************************************************************************/

// **********************************************************************
// 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.
// **********************************************************************

/*!
33
    \contentspage {Qt Creator Manual}
34
    \previouspage creator-writing-program.html
35
    \example accelbubble
Leena Miettinen's avatar
Leena Miettinen committed
36
    \nextpage {Using Qt Quick UI Forms}
37

38
    \title Creating a Mobile Application
39

40 41 42
    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
43 44 45 46 47
    that accelerates an SVG (Scalable Vector Graphics) image based on the
    changing accelerometer values.

    \image creator_android_tutorial_ex_app.png

48 49
    \section1 Setting up the Development Environment

50
    To be able to build the application for and run it on a mobile device, you must
51 52 53 54
    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
55
    the latest Android NDK and SDK, and update the SDK to get the API and tools
56
    needed for development. In addition, you must install the
57 58 59 60 61
    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}.

62 63 64 65 66
    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}.

67
    \include creator-tutorial-create-qq-project.qdocinc qt quick application
68

69
    \section1 Creating the Accelbubble Main View
70

71 72
    The main view of the application displays an SVG bubble image that moves
    around the screen when you tilt the device.
73

74 75 76 77
    To use \l{accelbubble/Bluebubble.svg}{Bluebubble.svg} in your project,
    copy it to the project directory (same subdirectory as the QML file).
    The image appears in \uicontrol Resources. You can also use any other
    image or a QML type, instead.
78

79
    To create the UI in the \uicontrol Design mode:
80

81
    \list 1
82

83 84
        \li In the \uicontrol Projects view, double-click the MainForm.ui.qml
            file to open it in \QMLD.
85

86 87
        \li In the \uicontrol Navigator, select \uicontrol RowLayout and press
            \key Delete to delete it.
88

89 90 91
        \li In \uicontrol Library > \uicontrol {QML Types}, select
            \uicontrol Rectangle and drag and drop it to the \uicontrol Item in
            the navigator.
92

93
        \li Select the rectangle in the navigator to edit its properties:
94

95
            \list a
96

97 98
                \li In the \uicontrol Id field enter \e mainWindow, to be able
                    to reference the rectangle from other places.
99

100
                \li Select the \uicontrol Layout tab, and then click
101
                    the \inlineimage anchor_fill.png
102 103
                    (\uicontrol {Fill to Parent}) button to anchor the rectangle
                    to the item.
104

105
            \endlist
106

107 108
        \li In \uicontrol Library > \uicontrol Resources, select Bluebubble.svg
            and drag and drop it to \e mainWindow in the navigator.
109

110 111 112
        \li In the \uicontrol Properties pane, \uicontrol Id field, enter
            \e bubble to be able to reference the image from other places.

113
        \li Select the \inlineimage export_unchecked.png
114 115 116 117 118 119 120
            (\uicontrol Export) button in the navigator to export the
            \e mainWindow and \e bubble as properties.

    \endlist

    We want to modify the properties of the bubble in ways that are not
    supported by \QMLD, and therefore we create a custom QML type for it:
121 122 123

    \list 1

124
        \li Select \uicontrol Edit to open MainForm.ui.qml in the code editor.
125

126 127
        \li Right-click \uicontrol Image and select \uicontrol Refactoring >
            \uicontrol {Move Component into Separate File}.
128

129 130
        \li In the \uicontrol {Component name} field, enter \e Bubble and
            select \uicontrol OK to create \e Bubble.qml.
131

132
    \endlist
133

134
    \QC creates a reference to Bubble.qml in MainForm.ui.qml.
135

136 137 138
    To check your code, you can compare MainForm.ui.qml with the
    \l{accelbubble/MainForm.ui.qml}{MainForm.ui.qml} example file and Bubble.qml
    with the \l{accelbubble/Bubble.qml}{Bubble.qml} example file.
139

140 141 142
    The UI is now ready and you can switch to editing the main.qml and
    Bubble.qml files in the \uicontrol Edit mode, as described in the
    following section.
143

144
    \section1 Moving the Bubble
145

146 147 148 149 150
    The new project wizard adds boilerplate code to the main.qml file to create
    menu items and push buttons. Modify the boilerplate code by removing
    obsolete code and by adding new code. You removed the push buttons from the
    UI Form, so you also need to remove the corresponding code from main.qml (or
    the application cannot be built).
151

152 153
    In the code editor, edit Bubble.qml to add properties that we will use to
    position the image:
154

155 156 157
    \quotefromfile accelbubble/Bubble.qml
    \skipto Image
    \printuntil }
158

159 160
    In the code editor, edit the main.qml to specify the application title, as
    illustrated by the following code snippet:
161

162 163 164
    \quotefromfile accelbubble/main.qml
    \skipto ApplicationWindow
    \printuntil title
165

166
    Use the bubble properties to position the image:
167

168
    \printuntil bubbleCenter
169

170
    Then set the x and y position of the image based on the new properties:
171

172 173 174
    \printuntil centerY
    \skipto /^\}/
    \printuntil }
175

176
    Then add code to move the bubble based on Accelerometer sensor values:
177 178

    \list 1
179
        \li Add the following import statement to main.qml:
180

181
            \code
182
            import QtSensors 5.5
183
            \endcode
184

185
        \li Add the \l{Accelerometer} type with the necessary properties:
186

187
            \quotefromfile accelbubble/main.qml
188 189 190 191 192 193 194 195 196
            \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:

197 198 199 200
            \quotefromfile accelbubble/main.qml
            \skipto function
            \printuntil Math.atan(x
            \printuntil }
201

202
        \li Add the following JavaScript code for \c onReadingChanged signal of
203 204 205
            Accelerometer type to make the bubble move when the Accelerometer
            values change:

206 207 208
            \quotefromfile accelbubble/main.qml
            \skipto onReadingChanged
            \printuntil }
209

210 211 212
            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.
213
        \li Add SmoothedAnimation behavior on the \c x and \c y properties of
214 215
            the bubble to make its movement look smoother.

216 217 218 219 220
            \quotefromfile accelbubble/main.qml
            \skipto Behavior
            \printuntil x
            \printuntil }
            \printuntil }
221 222
     \endlist

223 224 225 226 227 228 229 230 231 232 233 234 235
     \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.

236
    \section1 Adding Dependencies
237

238 239
    Update the accelbubble.pro file with the following library dependency
    information:
240

241 242 243
    \code
    QT += quick sensors svg xml
    \endcode
244

245 246 247 248 249 250 251 252 253 254 255 256
    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

257
    After adding the dependencies, select \uicontrol Build > \uicontrol {Run qmake} to apply
258 259 260 261 262 263 264 265 266
    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

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

270
        \li Select \uicontrol Add to add Bluebubble.svg.
271 272 273

    \endlist

274
    \section1 Running the Application
275

276
    The application is complete and ready to be deployed to a device:
277

278
    \list 1
279

280 281
        \li Enable \e{USB Debugging} on the Android device or \e{developer mode}
            on the iOS device.
282

283
        \li Connect the device to the development PC.
284 285 286

    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
287 288 289
    to. To avoid such prompts every time you connect the device, select the
    \uicontrol {Always allow from the computer} check box, and then select
    \uicontrol OK.
290

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

293
    \endlist
294
*/