1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** GNU Free Documentation License
10 ** Alternatively, this file may be used under the terms of the GNU Free
11 ** Documentation License version 1.3 as published by the Free Software
12 ** Foundation and appearing in the file included in the packaging of
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \page qml-advtutorial.html
30 \inqmlmodule QtQuick 2
31 \title QML Advanced Tutorial
32 \brief A more advanced tutorial, showing how to use QML to create a game.
33 \nextpage QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks
35 This tutorial walks step-by-step through the creation of a full application using QML.
36 It assumes that you already know the basics of QML (for example, from reading the
37 \l{QML Tutorial}{simple tutorial}).
39 In this tutorial we write a game, \i {Same Game}, based on the Same Game application
40 included in the declarative \c examples directory, which looks like this:
42 \image declarative-samegame.png
44 We will cover concepts for producing a fully functioning application, including
45 JavaScript integration, using QML \l{State}{States} and \l{Behavior}{Behaviors} to
46 manage components and enhance your interface, and storing persistent application data.
48 An understanding of JavaScript is helpful to understand parts of this tutorial, but if you don't
49 know JavaScript you can still get a feel for how you can integrate backend logic to create and
56 \o \l {declarative/tutorials/samegame/samegame1}{Creating the Game Canvas and Blocks}
57 \o \l {declarative/tutorials/samegame/samegame2}{Populating the Game Canvas}
58 \o \l {declarative/tutorials/samegame/samegame3}{Implementing the Game Logic}
59 \o \l {declarative/tutorials/samegame/samegame4}{Finishing Touches}
62 All the code in this tutorial can be found in Qt's \c examples/declarative/tutorials/samegame
67 \page qml-advtutorial1.html
68 \inqmlmodule QtQuick 2
69 \title QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks
70 \contentspage QML Advanced Tutorial
71 \previouspage QML Advanced Tutorial
72 \nextpage QML Advanced Tutorial 2 - Populating the Game Canvas
74 \example declarative/tutorials/samegame/samegame1
76 \section2 Creating the application screen
78 The first step is to create the basic QML items in your application.
80 To begin with, we create our Same Game application with a main screen like this:
82 \image declarative-adv-tutorial1.png
84 This is defined by the main application file, \c samegame.qml, which looks like this:
86 \snippet declarative/tutorials/samegame/samegame1/samegame.qml 0
88 This gives you a basic game window that includes the main canvas for the
89 blocks, a "New Game" button and a score display.
91 One item you may not recognize here
92 is the \l SystemPalette item. This provides access to the Qt system palette
93 and is used to give the button a more native look-and-feel.
95 Notice the anchors for the \c Item, \c Button and \c Text elements are set using
96 \l {qdeclarativeintroduction.html#dot-properties}{group notation} for readability.
98 \section2 Adding \c Button and \c Block components
100 The \c Button item in the code above is defined in a separate component file named \c Button.qml.
101 To create a functional button, we use the QML elements \l Text and \l MouseArea inside a \l Rectangle.
102 Here is the \c Button.qml code:
104 \snippet declarative/tutorials/samegame/samegame1/Button.qml 0
106 This essentially defines a rectangle that contains text and can be clicked. The \l MouseArea
107 has an \c onClicked() handler that is implemented to emit the \c clicked() signal of the
108 \c container when the area is clicked.
110 In Same Game, the screen is filled with small blocks when the game begins.
111 Each block is just an item that contains an image. The block
112 code is defined in a separate \c Block.qml file:
114 \snippet declarative/tutorials/samegame/samegame1/Block.qml 0
116 At the moment, the block doesn't do anything; it is just an image. As the
117 tutorial progresses we will animate and give behaviors to the blocks.
118 We have not added any code yet to create the blocks; we will do this
121 We have set the image to be the size of its parent Item using \c {anchors.fill: parent}.
122 This means that when we dynamically create and resize the block items
123 later on in the tutorial, the image will be scaled automatically to the
126 Notice the relative path for the Image element's \c source property.
127 This path is relative to the location of the file that contains the \l Image element.
128 Alternatively, you could set the Image source to an absolute file path or a URL
129 that contains an image.
131 You should be familiar with the code so far. We have just created some basic
132 elements to get started. Next, we will populate the game canvas with some blocks.
137 \page qml-advtutorial2.html
138 \inqmlmodule QtQuick 2
139 \title QML Advanced Tutorial 2 - Populating the Game Canvas
140 \contentspage QML Advanced Tutorial
141 \previouspage QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks
142 \nextpage QML Advanced Tutorial 3 - Implementing the Game Logic
144 \example declarative/tutorials/samegame/samegame2
146 \section2 Generating the blocks in JavaScript
148 Now that we've written some basic elements, let's start writing the game.
150 The first task is to generate the game blocks. Each time the New Game button
151 is clicked, the game canvas is populated with a new, random set of
152 blocks. Since we need to dynamically generate new blocks for each new game,
153 we cannot use \l Repeater to define the blocks. Instead, we will
154 create the blocks in JavaScript.
156 Here is the JavaScript code for generating the blocks, contained in a new
157 file, \c samegame.js. The code is explained below.
159 \snippet declarative/tutorials/samegame/samegame2/samegame.js 0
161 The \c startNewGame() function deletes the blocks created in the previous game and
162 calculates the number of rows and columns of blocks required to fill the game window for the new game.
163 Then, it creates an array to store all the game
164 blocks, and calls \c createBlock() to create enough blocks to fill the game window.
166 The \c createBlock() function creates a block from the \c Block.qml file
167 and moves the new block to its position on the game canvas. This involves several steps:
171 \o \l {QML:Qt::createComponent()}{Qt.createComponent()} is called to
172 generate an element from \c Block.qml. If the component is ready,
173 we can call \c createObject() to create an instance of the \c Block
176 \o If \c createObject() returned null (i.e. if there was an error
177 while loading the object), print the error information.
179 \o Place the block in its position on the board and set its width and
180 height. Also, store it in the blocks array for future reference.
182 \o Finally, print error information to the console if the component
183 could not be loaded for some reason (for example, if the file is
189 \section2 Connecting JavaScript components to QML
191 Now we need to call the JavaScript code in \c samegame.js from our QML files.
192 To do this, we add this line to \c samegame.qml which imports
193 the JavaScript file as a \l{Modules#QML Modules}{module}:
195 \snippet declarative/tutorials/samegame/samegame2/samegame.qml 2
197 This allows us to refer to any functions within \c samegame.js using "SameGame"
198 as a prefix: for example, \c SameGame.startNewGame() or \c SameGame.createBlock().
199 This means we can now connect the New Game button's \c onClicked handler to the \c startNewGame()
202 \snippet declarative/tutorials/samegame/samegame2/samegame.qml 1
204 So, when you click the New Game button, \c startNewGame() is called and generates a field of blocks, like this:
206 \image declarative-adv-tutorial2.png
208 Now, we have a screen of blocks, and we can begin to add the game mechanics.
213 \page qml-advtutorial3.html
214 \inqmlmodule QtQuick 2
215 \title QML Advanced Tutorial 3 - Implementing the Game Logic
216 \contentspage QML Advanced Tutorial
217 \previouspage QML Advanced Tutorial 2 - Populating the Game Canvas
218 \nextpage QML Advanced Tutorial 4 - Finishing Touches
220 \example declarative/tutorials/samegame/samegame3
222 \section2 Making a playable game
224 Now that we have all the game components, we can add the game logic that
225 dictates how a player interacts with the blocks and plays the game
226 until it is won or lost.
228 To do this, we have added the following functions to \c samegame.js:
231 \o \c{handleClick(x,y)}
232 \o \c{floodFill(xIdx,yIdx,type)}
234 \o \c{victoryCheck()}
235 \o \c{floodMoveCheck(xIdx, yIdx, type)}
238 As this is a tutorial about QML, not game design, we will only discuss \c handleClick() and \c victoryCheck() below since they interface directly with the QML elements. Note that although the game logic here is written in JavaScript, it could have been written in C++ and then exposed to QML.
240 \section3 Enabling mouse click interaction
242 To make it easier for the JavaScript code to interface with the QML elements, we have added an Item called \c gameCanvas to \c samegame.qml. It replaces the background as the item which contains the blocks. It also accepts mouse input from the user. Here is the item code:
244 \snippet declarative/tutorials/samegame/samegame3/samegame.qml 1
246 The \c gameCanvas item is the exact size of the board, and has a \c score property and a \l MouseArea to handle mouse clicks.
247 The blocks are now created as its children, and its dimensions are used to determine the board size so that
248 the application scales to the available screen size.
249 Since its size is bound to a multiple of \c blockSize, \c blockSize was moved out of \c samegame.js and into \c samegame.qml as a QML property.
250 Note that it can still be accessed from the script.
252 When clicked, the \l MouseArea calls \c{handleClick()} in \c samegame.js, which determines whether the player's click should cause any blocks to be removed, and updates \c gameCanvas.score with the current score if necessary. Here is the \c handleClick() function:
254 \snippet declarative/tutorials/samegame/samegame3/samegame.js 1
256 Note that if \c score was a global variable in the \c{samegame.js} file you would not be able to bind to it. You can only bind to QML properties.
258 \section3 Updating the score
260 When the player clicks a block and triggers \c handleClick(), \c handleClick() also calls \c victoryCheck() to update the score and to check whether the player has completed the game. Here is the \c victoryCheck() code:
262 \snippet declarative/tutorials/samegame/samegame3/samegame.js 2
264 This updates the \c gameCanvas.score value and displays a "Game Over" dialog if the game is finished.
266 The Game Over dialog is created using a \c Dialog element that is defined in \c Dialog.qml. Here is the \c Dialog.qml code. Notice how it is designed to be usable imperatively from the script file, via the functions and signals:
268 \snippet declarative/tutorials/samegame/samegame3/Dialog.qml 0
270 And this is how it is used in the main \c samegame.qml file:
272 \snippet declarative/tutorials/samegame/samegame3/samegame.qml 2
274 We give the dialog a \l {Item::z}{z} value of 100 to ensure it is displayed on top of our other components. The default \c z value for an item is 0.
277 \section3 A dash of color
279 It's not much fun to play Same Game if all the blocks are the same color, so we've modified the \c createBlock() function in \c samegame.js to randomly create a different type of block (for either red, green or blue) each time it is called. \c Block.qml has also changed so that each block contains a different image depending on its type:
281 \snippet declarative/tutorials/samegame/samegame3/Block.qml 0
284 \section2 A working game
286 Now we now have a working game! The blocks can be clicked, the player can score, and the game can end (and then you can start a new one).
287 Here is a screenshot of what has been accomplished so far:
289 \image declarative-adv-tutorial3.png
291 This is what \c samegame.qml looks like now:
293 \snippet declarative/tutorials/samegame/samegame3/samegame.qml 0
295 The game works, but it's a little boring right now. Where are the smooth animated transitions? Where are the high scores?
296 If you were a QML expert you could have written these in the first iteration, but in this tutorial they've been saved
297 until the next chapter - where your application becomes alive!
302 \page qml-advtutorial4.html
303 \inqmlmodule QtQuick 2
304 \title QML Advanced Tutorial 4 - Finishing Touches
305 \contentspage QML Advanced Tutorial
306 \previouspage QML Advanced Tutorial 3 - Implementing the Game Logic
308 \example declarative/tutorials/samegame/samegame4
310 \section2 Adding some flair
312 Now we're going to do two things to liven up the game: animate the blocks and add a High Score system.
314 We've also cleaned up the directory structure for our application files. We now have a lot of files, so all the
315 JavaScript and QML files outside of \c samegame.qml have been moved into a new sub-directory named "content".
317 In anticipation of the new block animations, \c Block.qml file is now renamed to \c BoomBlock.qml.
319 \section3 Animating block movement
321 First we will animate the blocks so that they move in a fluid manner. QML has a number of methods for adding fluid
322 movement, and in this case we're going to use the \l Behavior element to add a \l SpringAnimation.
323 In \c BoomBlock.qml, we apply a \l SpringAnimation behavior to the \c x and \c y properties so that the
324 block will follow and animate its movement in a spring-like fashion towards the specified position (whose
325 values will be set by \c samegame.js).Here is the code added to \c BoomBlock.qml:
327 \snippet declarative/tutorials/samegame/samegame4/content/BoomBlock.qml 1
329 The \c spring and \c damping values can be changed to modify the spring-like effect of the animation.
331 The \c {enabled: spawned} setting refers to the \c spawned value that is set from \c createBlock() in \c samegame.js.
332 This ensures the \l SpringAnimation on the \c x is only enabled after \c createBlock() has set the block to
333 the correct position. Otherwise, the blocks will slide out of the corner (0,0) when a game begins, instead of falling
334 from the top in rows. (Try commenting out \c {enabled: spawned} and see for yourself.)
336 \section3 Animating block opacity changes
338 Next, we will add a smooth exit animation. For this, we'll use a \l Behavior element, which allows us to specify
339 a default animation when a property change occurs. In this case, when the \c opacity of a Block changes, we will
340 animate the opacity value so that it gradually fades in and out, instead of abruptly changing between fully
341 visible and invisible. To do this, we'll apply a \l Behavior on the \c opacity property of the \c Image
342 element in \c BoomBlock.qml:
344 \snippet declarative/tutorials/samegame/samegame4/content/BoomBlock.qml 2
346 Note the \c{opacity: 0} which means the block is transparent when it is first created. We could set the opacity
347 in \c samegame.js when we create and destroy the blocks,
348 but instead we'll use \l{QML States}{states}, since this is useful for the next animation we're going to add.
349 Initially, we add these States to the root element of \c{BoomBlock.qml}:
351 property bool dying: false
353 State{ name: "AliveState"; when: spawned == true && dying == false
354 PropertyChanges { target: img; opacity: 1 }
356 State{ name: "DeathState"; when: dying == true
357 PropertyChanges { target: img; opacity: 0 }
362 Now blocks will automatically fade in, as we already set \c spawned to true when we implemented the block animations.
363 To fade out, we set \c dying to true instead of setting opacity to 0 when a block is destroyed (in the \c floodFill() function).
365 \section3 Adding particle effects
367 Finally, we'll add a cool-looking particle effect to the blocks when they are destroyed. To do this, we first add a \l Particles element in
368 \c BoomBlock.qml, like so:
370 \snippet declarative/tutorials/samegame/samegame4/content/BoomBlock.qml 3
372 To fully understand this you should read the \l Particles documentation, but it's important to note that \c emissionRate is set
373 to zero so that particles are not emitted normally.
374 Also, we extend the \c dying State, which creates a burst of particles by calling the \c burst() method on the particles element. The code for the states now look
377 \snippet declarative/tutorials/samegame/samegame4/content/BoomBlock.qml 4
379 Now the game is beautifully animated, with subtle (or not-so-subtle) animations added for all of the
380 player's actions. The end result is shown below, with a different set of images to demonstrate basic theming:
382 \image declarative-adv-tutorial4.gif
384 The theme change here is produced simply by replacing the block images. This can be done at runtime by changing the \l Image \c source property, so for a further challenge, you could add a button that toggles between themes with different images.
386 \section2 Keeping a High Scores table
388 Another feature we might want to add to the game is a method of storing and retrieving high scores.
390 To do this, we will show a dialog when the game is over to request the player's name and add it to a High Scores table.
391 This requires a few changes to \c Dialog.qml. In addition to a \c Text element, it now has a
392 \c TextInput child item for receiving keyboard text input:
394 \snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 0
396 \snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 2
398 \snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 3
400 We'll also add a \c showWithInput() function. The text input will only be visible if this function
401 is called instead of \c show(). When the dialog is closed, it emits a \c closed() signal, and
402 other elements can retrieve the text entered by the user through an \c inputText property:
404 \snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 0
405 \snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 1
407 \snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 3
409 Now the dialog can be used in \c samegame.qml:
411 \snippet declarative/tutorials/samegame/samegame4/samegame.qml 0
413 When the dialog emits the \c closed signal, we call the new \c saveHighScore() function in \c samegame.js, which stores the high score locally in an SQL database and also send the score to an online database if possible.
415 The \c nameInputDialog is activated in the \c victoryCheck() function in \c samegame.js:
417 \snippet declarative/tutorials/samegame/samegame4/content/samegame.js 3
419 \snippet declarative/tutorials/samegame/samegame4/content/samegame.js 4
421 \section3 Storing high scores offline
423 Now we need to implement the functionality to actually save the High Scores table.
425 Here is the \c saveHighScore() function in \c samegame.js:
427 \snippet declarative/tutorials/samegame/samegame4/content/samegame.js 2
429 First we call \c sendHighScore() (explained in the section below) if it is possible to send the high scores to an online database.
431 Then, we use the \l{Offline Storage API} to maintain a persistent SQL database unique to this application. We create an offline storage database for the high scores using \c openDatabaseSync() and prepare the data and SQL query that we want to use to save it. The offline storage API uses SQL queries for data manipulation and retrieval, and in the \c db.transaction() call we use three SQL queries to initialize the database (if necessary), and then add to and retrieve high scores. To use the returned data, we turn it into a string with one line per row returned, and show a dialog containing that string.
433 This is one way of storing and displaying high scores locally, but certainly not the only way. A more complex alternative would be to create a high score dialog component, and pass it the results for processing and display (instead of reusing the \c Dialog). This would allow a more themeable dialog that could better present the high scores. If your QML is the UI for a C++ application, you could also have passed the score to a C++ function to store it locally in a variety of ways, including a simple format without SQL or in another SQL database.
435 \section3 Storing high scores online
437 You've seen how you can store high scores locally, but it is also easy to integrate a web-enabled high score storage into your QML application. The implementation we've done her is very
438 simple: the high score data is posted to a php script running on a server somewhere, and that server then stores it and
439 displays it to visitors. You could also request an XML or QML file from that same server, which contains and displays the scores,
440 but that's beyond the scope of this tutorial. The php script we use here is available in the \c examples directory.
442 If the player entered their name we can send the data to the web service us
444 If the player enters a name, we send the data to the service using this code in \c samegame.js:
446 \snippet declarative/tutorials/samegame/samegame4/content/samegame.js 1
448 The \l XMLHttpRequest in this code is the same as the \c XMLHttpRequest() as you'll find in standard browser JavaScript, and can be used in the same way to dynamically get XML
449 or QML from the web service to display the high scores. We don't worry about the response in this case - we just post the high
450 score data to the web server. If it had returned a QML file (or a URL to a QML file) you could instantiate it in much the same
451 way as you did with the blocks.
453 An alternate way to access and submit web-based data would be to use QML elements designed for this purpose. XmlListModel
454 makes it very easy to fetch and display XML based data such as RSS in a QML application (see the Flickr demo for an example).
459 By following this tutorial you've seen how you can write a fully functional application in QML:
462 \o Build your application with \l {{QML Elements}}{QML elements}
463 \o Add application logic \l{Integrating JavaScript}{with JavaScript code}
464 \o Add animations with \l {Behavior}{Behaviors} and \l{QML States}{states}
465 \o Store persistent application data using, for example, the \l{Offline Storage API} or \l XMLHttpRequest
468 There is so much more to learn about QML that we haven't been able to cover in this tutorial. Check out all the
469 examples and the \l {Qt Quick}{documentation} to see all the things you can do with QML!