qtquick-app-development.qdoc 39.7 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.nokia.com)
**
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at info@qt.nokia.com.
**
****************************************************************************/

// **********************************************************************
// 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-design-mode.html
    \page creator-visual-editor.html
    \nextpage quick-projects.html

    \title Developing Qt Quick Applications

    You can either create Qt Quick projects from scratch or import existing
    projects to \QC.

    You can use the code editor (\l{Using the Editor}{Edit mode}) or the visual
    editor (\l{Using Qt Quick Designer}{Design mode}) to develop Qt Quick
    applications.

    \image qtcreator-qt-quick-editors.png "Edit mode and Design mode"

    The following sections describe typical tasks you can do with \QC.

    \list

        \o \l {Creating Qt Quick Projects}
        \o \l {Using Qt Quick Designer}
        \o \l {Creating Components}
        \o \l {Creating Buttons}
        \o \l {Creating Scalable Buttons and Borders}
        \o \l {Creating Screens}
        \o \l {Animating Screens}
        \o \l {Adding User Interaction Methods}
        \o \l {Exporting Designs from Graphics Software}
        \o \l {Implementing Application Logic}
        \o \l {Using QML Modules with Plugins}

    \endlist

*/


/*!

    \contentspage index.html
    \previouspage creator-visual-editor.html
    \page quick-projects.html
    \nextpage creator-using-qt-quick-designer.html

    \title Creating Qt Quick Projects

    \image qmldesigner-new-project.png "New File or Project dialog"

    When you create a new Qt Quick project from scratch, you have the following
    options:

    \list

        \o  \gui {Qt Quick Application} creates a Qt Quick application project
            that can contain both QML and C++ code. The project includes a
            QDeclarativeView. You can build the application and deploy it on
            desktop and mobile target platforms. For example, you
            can create signed Symbian Installation System (SIS) packages for
            this type of projects.

        \o  \gui {Qt Quick UI} creates a Qt Quick UI project with a single QML
            file that contains the main view. You can review Qt Quick UI
            projects in the QML Viewer and you need not build them. You do not
            need to have the development environment installed on your
            computer to create and run this type of projects.

        \o  \gui {Custom QML Extension Plugin} creates a C++ plugin that makes
            it possible to offer extensions that can be loaded dynamically into
            applications by using the QDeclarativeEngine class.

    \endlist

    If you have existing QML applications that you want to run in \QC or deploy
    to mobile devices, use the \gui {Qt Quick Application} wizard to convert
    them to Qt Quick applications.

    \section1 Creating Qt Quick UI Projects

    \list 1

        \o  Select \gui {File > New File or Project > Qt Quick Project >
            Qt Quick UI > Choose}.

            The \gui{Introduction and Project Location} dialog opens.

            \image qmldesigner-new-ui-project-location.png "Introduction and Project Location dialog"

        \o  In the \gui Name field, give a name to the project.

            Do not use spaces and special characters in the project name and
            path.

        \o  In the \gui {Create in} field, enter the path for the project files.
            For example, \c {C:\Qt\examples}. To select the path from a
            directory tree, click \gui Browse.

        \o  Click \gui{Next}.

            \image qmldesigner-new-ui-project-summary.png "Project Management dialog"

        \o  Review the project settings, and click \gui{Finish} to create the project.

    \endlist

    \QC creates the following files:

    \list

        \o  .qmlproject project file defines that all QML, JavaScript, and image
            files in the project folder belong to the project. Therefore, you do
            not need to individually list all the files in the project.

        \o  .qml file defines an element, such as a component, screen, or the
            whole application UI.

    \endlist

    The \c import statement in the beginning of the .qml file specifies the
    \l {http://doc.qt.nokia.com/4.7/qdeclarativemodules.html} {Qt modules}
    to import. Each Qt module contains a set of default elements.
    Specify a version to get the features you want.

    To use JavaScript and image files in the application, copy them to the
    project folder.

    \section1 Creating Qt Quick Applications

    \list 1

        \o  Select \gui {File > New File or Project > Qt Quick Project >
            Qt Quick Application > Choose}.

            The \gui{Introduction and Project Location} dialog opens.

            \image qmldesigner-new-project-location.png "Introduction and Project Location dialog"

        \o  In the \gui Name field, give a name to the project.

            Do not use spaces and special characters in the project name and path.

        \o  In the \gui {Create in} field, enter the path for the project files.
            For example, \c {C:\Qt\examples}. To select the path from a
            directory tree, click \gui Browse.

        \o  Click \gui{Next}.

            The \gui {Application Type} dialog opens.

            \image qmldesigner-new-project-qml-sources.png "Application Type dialog"

        \o  Select the Qt Quick Component Set to use in your application. The
            built-in elements allow you to write cross-platform applications
            with custom look and feel. The components for a mobile platform
            allow you to create applications with a native look and feel for
            that platform.

186
187
188
            \note We recommend that you use \gui {Qt Quick Components for
            MeeGo Harmattan} when you develop for MeeGo Harmattan devices.

189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
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
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
            You can also import an existing QML file in this dialog.

        \o  Click \gui{Next}.

            The \gui {Target Setup} dialog opens.

            \image qmldesigner-new-project-qt-versions.png "Target Setup dialog"

        \o  Select the Qt versions to use as build targets for your project,
            and then click \gui{Next}.

            \note Qt Quick is supported since Qt 4.7, and therefore, only Qt 4.7
            and later versions are displayed. Further, if you have only one
            supported Qt version installed, this dialog is skipped.

            The \gui {Mobile Options} dialog opens.

            \image qmldesigner-new-app-project-mobile-options.png "Mobile Options dialog"

        \o  In the \gui {Orientation behavior} field, determine how the application
            behaves when the orientation of the device display rotates between portrait
            and landscape, and then click \gui Next.

            \note This dialog opens only if you select \gui Maemo5 or
            \gui {Symbian Device} target in the \gui {Target Setup} dialog. On
            Harmattan, the Qt Quick Components for MeeGo provide native-looking
            rotation.

            The \gui {Symbian Specific} dialog opens.

            \image qmldesigner-new-project-symbian-options.png "Symbian Specific dialog"

        \o In the \gui {Application icon (.svg)} field, select an application
        icon for the \gui {Symbian Device} target, or use the default icon.

        \o In the \gui {Target UID3} field, specify the \l{Application UID}, or
        use the default UID.

        \note \QC generates a UID for testing the application on a device.
        You need to change the UID when you deliver the application for public
        use.

        \o Click \gui Next.

        The \gui {Maemo Specific} dialog opens.

        \image qmldesigner-new-project-maemo-options.png "Maemo Specific dialog"

        \o In the \gui {Application icon} field, select the application
         icon to use on Maemo or Harmattan targets, or use the default icon.

        The \gui {Project Management} dialog opens.

        \image qmldesigner-new-project-summary.png "Project Management" dialog

        \o In the \gui {Add to project} field, you can add this project to another
        project as a subproject.

        \o In the \gui {Add to version control} field, you can add the project to
        a version control system.

        \o Click \gui Finish to create the project.

    \endlist

    \QC creates the necessary boilerplate files. Some of the files are
    specific to the Symbian, Maemo, or MeeGo Harmattan platform.

    \section1 Importing QML Applications

    If you have existing QML applications that you want to run in \QC or deploy
    to mobile devices, use the \gui {Qt Quick Application} wizard and select the main
    .qml file in your project. All the other files in the project are automatically added
    to the application project.

    To import QML applications:

    \list 1

        \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick Application
        > Choose}.

        \o Name the project and set its path, and then click \gui Next.

        \o In the \gui {Application Type} dialog, select the \gui {Use an
        existing .qml file}
        option and specify the main .qml file of the project you want to import.

        \image qmldesigner-import-project.png "Application Type dialog"

        \o Click \gui Next.

        \o Select the Qt versions to use as build targets for your project, and click
        \gui{Next}.

        \o Specify options for deploying the application to mobile device targets, and
        click \gui{Next}.

        \o Review the project settings, and click \gui{Finish} to create the project.

    \endlist

    \QC adds references to the QML files to a project and creates the additional files
    necessary for deploying applications to mobile devices.

*/


/*!

    \contentspage index.html
    \previouspage creator-using-qt-quick-designer.html
    \page quick-components.html
    \nextpage quick-buttons.html

    \title Creating Components

306
307
    A \l{glossary-component}{component} provides a way of defining a new type
    that you can re-use in other QML
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
    files. A component is like a black box; it interacts with the outside world
    through properties, signals, and slots, and is generally defined in its own QML file.
    You can import components to screens and applications.

    You can use the following QML elements to create components:

    \list

        \o \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
        uses an image as a border or background.
        \o \l{http://doc.qt.nokia.com/4.7/qml-image.html}{Image}
        adds a bitmap to the scene. You can stretch and tile images.
        \o \l{http://doc.qt.nokia.com/4.7/qml-item.html}{Item}
        is the most basic of all visual items in QML. Even though it has no visual appearance,
        it defines all the properties that are common across visual items, such as the x and
        y position, width and height, anchoring, and key handling.
        \o \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
        adds a rectangle that is painted with a solid fill color and an optional border.
        You can also use the radius property to create rounded rectangles.
        \o \l{http://doc.qt.nokia.com/4.7/qml-text.html}{Text}
        adds formatted read-only text.
        \o \l{http://doc.qt.nokia.com/4.7/qml-textedit.html}{Text Edit}
        adds a single line of editable formatted text that can be validated.
        \o \l{http://doc.qt.nokia.com/4.7/qml-textinput.html}{Text Input}
        adds a single line of editable plain text that can be validated.
        \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-webview.html}{Web View}
        adds web content to a canvas.

    \endlist

    QML elements allow you to write cross-platform applications with custom look
    and feel. You can also use ready-made Qt Quick Components for Symbian and
    MeeGo Harmattan that allow you to create applications with a native look and
    feel for the selected mobile platform. You can install the components as
    part of \QSDK.

    When you use the \QC project wizard to create Qt Quick applications,
    you can select which component set to use in your application.

    Even if you use the Qt Quick Components, you can still write cross-platform
    applications, by using different sets of QML files for each platform.

    You can dowload a set of commonly used UI-components for generic use in
    Qt Quick projects from
    \l{https://projects.forum.nokia.com/QMLTemplates}{QML Templates}. You can
    open and edit the templates in \QD.

    \section1 Creating Components in Qt Quick Designer

    \list 1

        \o Select \gui {File > New File or Project > Files and Classes > QML
        > Choose} to create a new .qml file.

        \note Components are listed in the \gui {QML Components} section of the
        \gui Library pane only if the filename begins with a capital letter.

        \o Click \gui Design to open the .qml file in \QMLD.

        \o Drag and drop an item from the \gui Library pane to the editor.

        \o Edit item properties in the \gui Properties pane.

        The available properties depend on the item.

    \endlist

    The following sections contain examples of how to create some common components:

    \list

        \o \l{Creating Buttons}

        \o \l{Creating Scalable Buttons and Borders}

    \endlist

385
386
387
388
389
390
391
392
393
394
    \section1 Moving Within Components

    Components can consist of several other components. To view the component
    hierarchy as a bread crumb path when you edit a component on the canvas,
    select \gui {Go into Component} or press \key F2. Click the component
    names in the path to navigate to them. You can easily navigate back to the
    top level when you are done editing the component.

    \image qmldesigner-breadcrumbs.png "Go into Component command"

395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
*/


/*!
    \contentspage index.html
    \previouspage quick-components.html
    \page quick-buttons.html
    \nextpage quick-scalable-image.html

    \title Creating Buttons

    To create a button component:

    \list 1

        \o Select \gui {File > New File or Project > QML > QML File > Choose} to
         create a QML file called Button.qml (for example).

        \note Components are listed in the \gui Library pane only if the filename
        begins with a capital letter.

        \o Click \gui {Design} to edit the file in the visual editor.

        \o In the \gui Navigator pane, click \gui Rectangle to set properties
        for it.

        \o In the \gui Properties pane, modify the appearance of the button.

        \list a

            \o In the \gui Size field, set the width (\gui W) and height (\gui H)
            of the button.

            \o In the \gui Color field, select the button color.

            \o In the \gui Radius field, use the slider to set the radius of the
            rectangle and produce rounded corners for the button.

        \endlist

        \o Drag and drop a \gui {Text} item on top of the \gui Rectangle. This
        creates a nested element where \gui Rectangle is the parent element of
        \gui Text. Elements are positioned relative to their parents.

        \o In the \gui Properties pane, edit the properties of the \gui Text item.

        \list a

            \o In the \gui Text field, type \bold Button.

            You can select the text color, font, size, and style in the \gui Font
            section.

            \o In the \gui Alignment field, select the center buttons to align
            the text to the center of the button.

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the text to the whole button area.

        \endlist

        \o Press \key {Ctrl+S} to save the button.

        \image qmldesigner-button.png "Button component"

    \endlist

    \note To view the button, you must add it to a Qt Quick Application or Qt Quick UI
    project.

    To create a graphical button that scales beautifully without using vector graphics,
    use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
    element. For more information, see \l{Creating Scalable Buttons and Borders}.

    */


/*!

    \contentspage index.html
    \previouspage quick-buttons.html
    \page quick-scalable-image.html
    \nextpage quick-screens.html

    \title Creating Scalable Buttons and Borders

    You can use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
    element to display an image, such as a PNG file, as a border and a background.

    Use two Border Image elements and suitable graphics to make it look like the button
    is pushed down when it is clicked. One of the Border Image elements is visible by default.
    You can specify that it is hidden and the other one becomes visible when the mouse
    is clicked.

    Add a MouseArea that covers the whole area and emits the clicked signal (\c {parent.clicked()})
    when it detects a mouse click.

    You can add text to the button and set it up as a property. The text can then be initialized
    from the outside, making the button a reusable UI component. The font size is also available
    in case the default size is too big. You can scale down the button text and use smooth text
    rendering for some extra quality.

    \image qmldesigner-borderimage.png "Graphical button"

    To create a graphical button:

    \list 1

        \o Select \gui {File > New File or Project > QML > QML File > Choose} to create
        a QML file called Button.qml (for example).

        \o Double-click the file to open it in the code editor.

        \o Replace the \gui Rectangle with an \gui Item, as illustrated by the
        following code snippet:

        \qml
        Item {

        }
        \endqml

        \o Specify properties and set expressions for the \gui Item, as
        illustrated by the following code snippet:

        \snippet snippets/qml/quick-scalable-image.qml properties and signal definitions

        You will point to the properties and expression later.

        \o Click \gui {Design} to edit the file in the visual editor.

        \o Drag and drop two \gui BorderImage items from the \gui Library pane to
        the scene.

        \o Drag and drop a \gui Text item to the scene.

        \o Drag and drop a \gui MouseArea to the screen.

        \o In the \gui Navigator pane, select \gui border_image1 to specify
        settings for it in the \gui Properties pane:

        \list a

            \o Select \gui {Set Expression} in the menu next to the \gui Visibility
            check box.

            \o Enter the following expression to specify that the image is visible
            when the mouse is not pressed down: \c {!mouse_area1.pressed}.

            \o In the \gui Source field, select the image file for the
            button, for example button_up.png.

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the border image to the \gui Item.

        \endlist

        \o Select \gui border_image2 to specify similar settings for it:

        \list a

            \o Set the following epression for \gui Visibility, to specify that
            the image is visible when the mouse is pressed down:
            \c {mouse_area1.pressed}.

            \o In the \gui Source field, select the image file for the
            button when it is clicked, for example button_down.png.

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the border image to the \gui Item.

        \endlist

        \o Select \gui text1 to specify font size and color, and text
        scaling and rendering:

        \list a

            \o In the \gui Color field, use the color picker to select
            the font color, or enter a value in the field.

            \o In the \gui Text field, select \gui {Set Expression} and
            enter a pointer to the \c {text} property that you specified
            earlier: \c {parent.txt}.

            \o Select the \gui Aliasing check box to enable smooth text
            rendering.

            \o In the \gui Size field, select \gui {Pixels} to specify
            the font size in pixels. By default, the size is specified in
            points.

            \o In the \gui Size field, select \gui {Set Expression} and
            enter a pointer to the \c {fontSize} property that you specified
            earlier.

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-center-in.png "Anchor buttons"
            buttons to inherit the vertical and horizontal centering from
            the parent.

            \o Click \gui Advanced to specify scaling for the text in the
            \gui Scale field.

            \o Select \gui {Set Expression} and enter the following expression:
            \c {if (!mousearea1.pressed) { 1 } else { 0.95 }}.

            \note You can enter long and complicated expressions also in the
            code editor.

        \endlist

        \o In the code editor, add to the \c MouseArea item
        a pointer to the \c clicked expression that you added earlier:
        \c {onClicked: parent.clicked()}.

    \endlist

    \note To view the button, you must add it to a Qt Quick Application or Qt
    Quick UI project.

*/


/*!

    \contentspage index.html
    \previouspage quick-scalable-image.html
    \page quick-screens.html
    \nextpage quick-animations.html

    \title Creating Screens

    You can use predefined QML elements and your own components to create screens.
    Typically, the main qml file in a Qt Quick project specifies the main window of an
    application.

    The QML files in the project folder are displayed in \gui {QML Components} in the
    \gui Library pane.

    You can also use ready-made Qt Quick Components for Symbian and
    MeeGo Harmattan that allow you to create screens with a native look and
    feel for the selected mobile platform. You can install the components as
    part of \QSDK.

    You can dowload QML templates that specify different types of screens from
    \l{https://projects.developer.nokia.com/QMLTemplates}{QML Templates} for use in
    your Qt Quick projects. You can open and edit the templates in \QD.

    \section1 Adding Components to Screens

    \list 1

        \o Drag and drop components from the \gui Library pane to the editor.

        \o Select components in the \gui Navigator pane to edit their properties
        in the \gui Properties pane.

        For example, you can anchor components to a position on the screen.

    \endlist

    \section1 Using Data Models

    You can create the following types of views to organize items provided by
    \l{http://doc.qt.nokia.com/4.7/qdeclarativemodels.html}{data models}:

    \list

        \o \l{http://doc.qt.nokia.com/4.7/qml-gridview.html}{Grid View}
        provides a grid vizualization of a model.

        \o \l{http://doc.qt.nokia.com/4.7/qml-listview.html}{List View}
        provides a list vizualization of a model.

        \o \l{http://doc.qt.nokia.com/4.7/qml-pathview.html}{Path View}
        visualizes the contents of a model along a path.

    \endlist

    When you add a Grid View, List View, or Path View element, the
    \l{http://doc.qt.nokia.com/4.7/qml-listmodel.html}{ListModel} and the
    delegate component that creates an instance for each item in the model are
    added automatically. You can edit element properties in the \gui Properties
    pane or in the code editor. You can also replace the default model and
    delegate with other, more complex models and delegates in the code editor.

    \section1 Positioning Items on Screens

    You can use the following items to arrange items on screens:

    \list

        \o  \l{http://doc.qt.nokia.com/4.7-snapshot/qml-column.html}{Column}
            arranges its child items vertically.

        \o  \l{http://doc.qt.nokia.com/4.7-snapshot/qml-row.html}{Row}
            arranges its child items horizontally.

        \o  \l{http://doc.qt.nokia.com/4.7-snapshot/qml-grid.html}{Grid}
            arranges its child items so that they are aligned in a grid and
            are not overlapping.

        \o  \l{http://doc.qt.nokia.com/4.7-snapshot/qml-flow.html}{Flow}
            arranges its child items side by side, wrapping as necessary.

    \endlist

706
707
708
709
    To lay out several items in a Column, Row, Grid, or Flow element, select
    the elements on the canvas, and then select \gui Layout in the context
    menu.

710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
    \section1 Using States

    Use states and transitions
    to navigate between screens.

    QML states typically describe user interface configurations, such as the UI elements,
    their properties and behavior and the available actions. For example, you can use
    states to create two screens.

    To add states, click the empty slot in the \gui States pane. Then modify the new state
    in the visual editor.

    \image qmldesigner-states.png "States pane"

    The properties that you change in a state are highlighted with blue color.
    In the code editor, you can see the changes recorded as changes to the base state.

    To keep the QML code clean, you should create a base state that contains all the
    elements you will need in the application. You can then create states, in
    which you hide and show a set of items and modify their properties.
    This allows you to:

    \list

        \o Align items on different screens with each other.

        \o Avoid excessive property changes. If an item is invisible in the base
        state, you must define all changes to its child elements as property changes,
        which leads to complicated QML code.

        \o Minimize the differences between the base state and the other states
        to keep the QML code short and readable and to improve performance.

        \o Avoid problems when using transitions and animation when changing
        states.

    \endlist

    To create screens for an application by using states:

    \list 1

        \o In the base state, add all elements you will need in the application.
        While you work on one screen, you can click the
        \inlineimage qmldesigner-show-hide-icon.png
        icon to hide elements on the canvas that are not part of a screen.

        \o In the \gui States pane, click the empty slot to create a new state
        and give it a name. For example, \c Normal.

        \o In the \gui Properties pane, deselect the \gui Visibility check box
        or set \gui Opacity to 0 for each element that is not needed in this view.
        If you specify the setting for the parent element, all child elements
        inherit it and are also hidden.

        \image qmldesigner-screen-design.png "Designing screens"

        \o Create additional states for each screen and set the visibility or
        opacity of the elements in the screen.

        \o To determine which view opens when the application starts, use the code
        editor to set the state of the root item of the .qml file, as specified by the
        following code snippet:

        \qml
        Item {
            state: "Normal"
        }
        \endqml

    \endlist


*/


/*!

    \contentspage index.html
    \previouspage quick-screens.html
    \page quick-animations.html
    \nextpage quick-user-interaction.html

    \title Animating Screens

    To make movement between states smooth, you can specify transitions.
    You can use different types of animated transitions. For example, you can animate changes
    to property values and colors. You can use rotation animation to control the direction of
    rotation. For more information, see
    \l{http://doc.qt.nokia.com/4.7/qdeclarativeanimation.html}{QML Animation}.

    You can use the \c ParallelAnimation element to start several animations at the same time.
    Or use the \c SequentialAnimation element to run them one after another.

    You can use the code editor to specify transitions. For more information, see
    \l{http://doc.qt.nokia.com/4.7/qml-transition.html}{QML Transition Element}.

*/


/*!

    \contentspage index.html
    \previouspage quick-animations.html
    \page quick-user-interaction.html
    \nextpage quick-export-to-qml.html

    \title Adding User Interaction Methods

    You can add the following basic interaction methods to scenes:

    \list

        \o \l{http://doc.qt.nokia.com/4.7/qml-flickable.html}{Flickable}
        items can be flicked horizontally or vertically.
        \o \l{http://doc.qt.nokia.com/4.7/qml-flipable.html}{Flipable}
        items can be flipped between their front and back sides by using rotation,
        state, and transition.
        \o \l{http://doc.qt.nokia.com/4.7/qml-focusscope.html}{Focus Scope}
        assists in keyboard focus handling when building reusable QML components.
        \o \l{http://doc.qt.nokia.com/4.7/qml-mousearea.html}{Mouse Area}
        enables simple mouse handling.

    \endlist

*/


/*!

    \contentspage index.html
    \previouspage quick-user-interaction.html
    \page quick-export-to-qml.html
    \nextpage quick-application-logic.html

    \title Exporting Designs from Graphics Software

    You can export designs from graphics software, such as Adobe Photoshop and GIMP,
    to QML files. Each scene is converted into a single QML file with an Image or a
    Text element for each layer and saved on the development PC. Top-level layer
    groups are converted into merged QML Image elements.

    Note: GIMP does not support grouping, and therefore, each layer is exported as
    an item in GIMP.

    You can open the QML file in \QC for editing. If you edit the file in Adobe
    Photoshop and export it to the same directory again, any changes you made in
    \QC are overwritten. However, you can re-export graphical assets without
    recreating the QML code.

    If you create vector graphics with other tools that have an Adobe Photoshop export
    option, such as Adobe Illustrator, you can export them first to Photoshop
    and then
    to QML.

    \section1 Conversion Rules

    The following rules apply to the conversions:

    \list

        \o Layer names are used as element names. Spaces and hash marks (#) are
         replaced with underscore characters to create valid ids for the elements.

        \o Layer styles, such as drop shadows, are converted to images.

        \o Offset, size, ordering and opacity are preserved.

        \o Text layers are converted to Text elements, unless you specify that they
        be converted to Image elements.

        \o Hidden layers can be exported, and their visibility is set to hidden.

        \o PNG images are copied to the images subirectory.

    \endlist

    \section1 Preparing Files for Conversion

    To create QML files that are easy to use, prepare the Adobe Photoshop or
    GIMP designs for exporting, as follows:

    \list

        \o  To minimize the number of elements, minimize the number of layers or
            use top-level layer groups, because each layer or layer group is
            exported as a Text or Image element.

        \o  To make sure that all related elements are exported to the same
            element, use top-level layer groups.

        \o  To determine that some layers are not exported, hide them, and
            deselect the \gui {Export hidden} check box during exporting.

        \o  To make it easier to find the layers and layer groups after
            exporting them, use descriptive names for them.

        \o  To make sure that image dimensions are preserved during export,
            create at least one fully filled layer (which can be hidden), such
            as a background layer. If the export script does not find a fully
            filled layer, it resizes all images to the size of the canvas.

        \o  To prevent errors during export, make sure that the layers are not
            locked. Locked layers cannot be exported.

        \o  To avoid unexpected results, do not use Blending Mode effects. They
            are not exported.

    \endlist

    \section1 Exporting from Adobe Photoshop to QML

    \image qml-export-photoshop.png

    The script has been tested to work on Adobe Photoshop CS 4 and 5, but it might also
    work on other versions.

    \list 1

        \o Download the export script, \e{Export QML.jx}, from
        \l{http://qt.gitorious.org/qt-labs/photoshop-qmlexporter/trees/master}{Gitorious}.

        \note Read the README.txt file in the repository for latest information about
        the script.

        \o Double-click the export script to add the export command to the \gui Scripts
        menu. You can also copy the script file to the Adobe Photoshop scripts directory
        (typically, \c{\Presets\Scripts} in the Photoshop installation directory).

        \o In Adobe Photoshop, choose \gui {File > Scripts > Export to QML} to export the
        scene to a QML file.

        \o In the \gui {Export Document to QML} dialog, enter a name and location for the
        QML file.

        \o Select the \gui {Rasterize text} check box to export text layers as images,
        not as Text elements.

        \o Select the \gui {Group layers} check box to export each top-level group as a
        merged QML Image element.

        \o Select the \gui {Export hidden} check box to export hidden layers and to set
        their visibility property to hidden.

        \o Deselect the \gui {Export QML} check box if you have modified the QML document
        in \QC, but still want to re-export graphical assets.

        \o Click \gui Export.

    \endlist

    The QML file is saved to the location that you specified.
    In \QC, choose \gui {File > Open File or Project} to open the QML file.

    \note Existing files are replaced without warning.

    \section1 Exporting from GIMP to QML

    \image qml-export-gimp.png

    The script has been tested to work on GIMP 2. You can download GIMP 2 from
    \l{http://www.gimp.org/downloads/}{GIMP Downloads}.

    To use the export script on Microsoft Windows, you also need to install the
    GIMP Python extension (Python, PyCairo, PyGobject, PyGTK). However, GIMP is
    not officially supported on Windows, so we cannot guarantee that this will
    work.

    \list 1

        \o On Microsoft Windows, you must first add Python support to your GIMP
        installation, as instructed in
        \l {http://www.gimpusers.com/tutorials/install-python-for-gimp-2-6-windows}{Tutorial: Installing Python for GIMP 2.6 (Windows)}.

        \o Download the export script, \e qmlexporter.py, from
        \l{http://qt.gitorious.org/qt-labs/gimp-qmlexporter/trees/master}{Gitorious}.

        \note Read the INSTALL.txt in the repository for latest information about the
        script.

        \o Copy the export script to the plug-ins directory in the GIMP installation
        directory.

        \o Check the properties of the file to make sure that it is executable.

        On Linux, run the following command: \c {chmod u+rx}

        \o Restart GIMP to have the export command added to the \gui File menu.

        \o Choose \gui {File > Export to QML} to export the design to a QML file.

        \o In the \gui {Export Layers to a QML Document} dialog, enter a name and
        location for the QML file, and click \gui Export.

    \endlist

    The QML file is saved to the location that you specified.
    In \QC, choose \gui {File > Open File or Project} to open the QML file.

    \note Existing files are replaced without warning.

*/


/*!

    \contentspage index.html
    \previouspage quick-export-to-qml.html
    \page quick-application-logic.html
    \nextpage creator-qml-modules-with-plugins.html

    \title Implementing Application Logic

    A user interface is only a part of an application, and not really useful by itself.
    You can use Qt or JavaScript to implement the application logic. For more information on
    using JavaScript, see
    \l {http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html} {Integrating JavaScript}.

    For an example of how to use JavaScript to develop a game, see the
    \l {http://doc.qt.nokia.com/4.7/qml-advtutorial.html} {QML Advanced Tutorial}.

 */


/*!
    \contentspage index.html
    \previouspage quick-application-logic.html
    \page creator-qml-modules-with-plugins.html
    \nextpage creator-using-qt-designer.html

    \title Using QML Modules with Plugins

    QML modules may use plugins to expose components defined in C++ to
    QML applications. Since \QC cannot load the plugins to determine
    the details of the contained components, these modules need to provide
    extra type information for code completion and the semantic checks to work
    correctly.

Leena Miettinen's avatar
Leena Miettinen committed
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
    When you write a QML module or use QML from a C++ application you typically
    register new types with
    \l{http://doc.qt.nokia.com/4.8/qdeclarativeengine.html#qmlRegisterType}
    {qmlRegisterType} or expose some class instances with
    \l{http://doc.qt.nokia.com/4.8/qdeclarativecontext.html#setContextProperty}
    {setContextProperty}. The \QC C++ code model now scans for these calls and
    tells the QML code model about them. This means that properties are
    displayed during code completion and the JavaScript code checker does not
    complain about unknown types. However, this works only when the source code
    is available, and therefore, you must explicitly generate type information
    for QML modules with plugins before distributing them.

1060
1061
1062
1063
1064
1065
1066
1067
    Ideally, QML modules have a \c{plugins.qmltypes} file in the same directory
    as the \c qmldir file. The \c qmltypes file contains a description of the
    components exported by the module's plugins and is loaded by \QC
    when the module is imported.

    For Qt 4.8 and later, one or more \c qmltypes files can be listed in the
    \c qmldir file under the \c typeinfo header. These files will be read in addition
    to \c{plugins.qmltypes}. For more information, see
Leena Miettinen's avatar
Leena Miettinen committed
1068
    \l{http://doc.qt.nokia.com/4.8/qdeclarativemodules.html#writing-a-qmldir-file}{Writing a qmldir File}.
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097

    \section1 Generating qmltypes Files

    You can create and edit \c qmltypes files manually, but you are recommended
    to use the \c qmlplugindump tool shipped with Qt 4.8 and later to generate
    them automatically. For earlier versions of Qt, you can compile a version
    of the tool called \c qmldump from the sources in
    \c{<QtCreator>/share/qtcreator/qml/qmldump} if the Qt version contains private headers.

    Once you have obtained qmlplugindump for the Qt version the QML module's
    plugins were compiled with, run the following command to load My.Module
    version 1.0 from \c{/import/path/my/module} including all its plugins and
    output a description of the plugins' types to
    \c{/import/path/my/module/plugins.qmltypes}:

    \code
    qmlplugindump My.Module 1.0 /import/path > /import/path/my/module/plugins.qmltypes
    \endcode

    You can safely ignore the debug output.

    \section1 Dumping Plugins Automatically

    If a module with plugins lacks the \c qmltypes file, \QC tries to
    generate a temporary file itself by running the \c qmldump program in the
    background. However, this automatic dumping is a fallback mechanism with
    many points of failure and cannot be relied upon.

*/