diff options
Diffstat (limited to 'src/quick/doc/src/advtutorial.qdoc')
| -rw-r--r-- | src/quick/doc/src/advtutorial.qdoc | 63 |
1 files changed, 29 insertions, 34 deletions
diff --git a/src/quick/doc/src/advtutorial.qdoc b/src/quick/doc/src/advtutorial.qdoc index 966233c371..80a0173f32 100644 --- a/src/quick/doc/src/advtutorial.qdoc +++ b/src/quick/doc/src/advtutorial.qdoc @@ -27,7 +27,6 @@ /*! \page qml-advtutorial.html tutorial -\inqmlmodule QtQuick 2 \title QML Advanced Tutorial \brief A more advanced tutorial, showing how to use QML to create a game. \nextpage QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks @@ -65,7 +64,6 @@ directory. /*! \page qml-advtutorial1.html -\inqmlmodule QtQuick 2 \title QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks \contentspage QML Advanced Tutorial \previouspage QML Advanced Tutorial @@ -83,7 +81,7 @@ To begin with, we create our Same Game application with a main screen like this: This is defined by the main application file, \c samegame.qml, which looks like this: -\snippet quick/tutorials/samegame/samegame1/samegame.qml 0 +\snippet tutorials/samegame/samegame1/samegame.qml 0 This gives you a basic game window that includes the main canvas for the blocks, a "New Game" button and a score display. @@ -101,7 +99,7 @@ The \c Button item in the code above is defined in a separate component file nam To create a functional button, we use the QML types \l Text and \l MouseArea inside a \l Rectangle. Here is the \c Button.qml code: -\snippet quick/tutorials/samegame/samegame1/Button.qml 0 +\snippet tutorials/samegame/samegame1/Button.qml 0 This essentially defines a rectangle that contains text and can be clicked. The \l MouseArea has an \c onClicked() handler that is implemented to emit the \c clicked() signal of the @@ -111,7 +109,7 @@ In Same Game, the screen is filled with small blocks when the game begins. Each block is just an item that contains an image. The block code is defined in a separate \c Block.qml file: -\snippet quick/tutorials/samegame/samegame1/Block.qml 0 +\snippet tutorials/samegame/samegame1/Block.qml 0 At the moment, the block doesn't do anything; it is just an image. As the tutorial progresses we will animate and give behaviors to the blocks. @@ -135,7 +133,6 @@ types to get started. Next, we will populate the game canvas with some blocks. /*! \page qml-advtutorial2.html -\inqmlmodule QtQuick 2 \title QML Advanced Tutorial 2 - Populating the Game Canvas \contentspage QML Advanced Tutorial \previouspage QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks @@ -156,7 +153,7 @@ create the blocks in JavaScript. Here is the JavaScript code for generating the blocks, contained in a new file, \c samegame.js. The code is explained below. -\snippet quick/tutorials/samegame/samegame2/samegame.js 0 +\snippet tutorials/samegame/samegame2/samegame.js 0 The \c startNewGame() function deletes the blocks created in the previous game and calculates the number of rows and columns of blocks required to fill the game window for the new game. @@ -168,7 +165,7 @@ and moves the new block to its position on the game canvas. This involves severa \list -\li \l {QML:Qt::createComponent()}{Qt.createComponent()} is called to +\li \l {QtQml2::Qt::createComponent()}{Qt.createComponent()} is called to generate a type from \c Block.qml. If the component is ready, we can call \c createObject() to create an instance of the \c Block item. @@ -192,14 +189,14 @@ Now we need to call the JavaScript code in \c samegame.js from our QML files. To do this, we add this line to \c samegame.qml which imports the JavaScript file as a \l{QML Modules}{module}: -\snippet quick/tutorials/samegame/samegame2/samegame.qml 2 +\snippet tutorials/samegame/samegame2/samegame.qml 2 This allows us to refer to any functions within \c samegame.js using "SameGame" as a prefix: for example, \c SameGame.startNewGame() or \c SameGame.createBlock(). This means we can now connect the New Game button's \c onClicked handler to the \c startNewGame() function, like this: -\snippet quick/tutorials/samegame/samegame2/samegame.qml 1 +\snippet tutorials/samegame/samegame2/samegame.qml 1 So, when you click the New Game button, \c startNewGame() is called and generates a field of blocks, like this: @@ -211,7 +208,6 @@ Now, we have a screen of blocks, and we can begin to add the game mechanics. /*! \page qml-advtutorial3.html -\inqmlmodule QtQuick 2 \title QML Advanced Tutorial 3 - Implementing the Game Logic \contentspage QML Advanced Tutorial \previouspage QML Advanced Tutorial 2 - Populating the Game Canvas @@ -241,7 +237,7 @@ As this is a tutorial about QML, not game design, we will only discuss \c handle To make it easier for the JavaScript code to interface with the QML types, 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: -\snippet quick/tutorials/samegame/samegame3/samegame.qml 1 +\snippet tutorials/samegame/samegame3/samegame.qml 1 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. The blocks are now created as its children, and its dimensions are used to determine the board size so that @@ -251,7 +247,7 @@ Note that it can still be accessed from the script. 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: -\snippet quick/tutorials/samegame/samegame3/samegame.js 1 +\snippet tutorials/samegame/samegame3/samegame.js 1 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. @@ -259,17 +255,17 @@ Note that if \c score was a global variable in the \c{samegame.js} file you woul 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: -\snippet quick/tutorials/samegame/samegame3/samegame.js 2 +\snippet tutorials/samegame/samegame3/samegame.js 2 This updates the \c gameCanvas.score value and displays a "Game Over" dialog if the game is finished. The Game Over dialog is created using a \c Dialog type 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: -\snippet quick/tutorials/samegame/samegame3/Dialog.qml 0 +\snippet tutorials/samegame/samegame3/Dialog.qml 0 And this is how it is used in the main \c samegame.qml file: -\snippet quick/tutorials/samegame/samegame3/samegame.qml 2 +\snippet tutorials/samegame/samegame3/samegame.qml 2 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. @@ -278,7 +274,7 @@ We give the dialog a \l {Item::z}{z} value of 100 to ensure it is displayed on t 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: -\snippet quick/tutorials/samegame/samegame3/Block.qml 0 +\snippet tutorials/samegame/samegame3/Block.qml 0 \section2 A working game @@ -290,7 +286,7 @@ Here is a screenshot of what has been accomplished so far: This is what \c samegame.qml looks like now: -\snippet quick/tutorials/samegame/samegame3/samegame.qml 0 +\snippet tutorials/samegame/samegame3/samegame.qml 0 The game works, but it's a little boring right now. Where are the smooth animated transitions? Where are the high scores? If you were a QML expert you could have written these in the first iteration, but in this tutorial they've been saved @@ -300,7 +296,6 @@ until the next chapter - where your application becomes alive! /*! \page qml-advtutorial4.html -\inqmlmodule QtQuick 2 \title QML Advanced Tutorial 4 - Finishing Touches \contentspage QML Advanced Tutorial \previouspage QML Advanced Tutorial 3 - Implementing the Game Logic @@ -324,7 +319,7 @@ In \c BoomBlock.qml, we apply a \l SpringAnimation behavior to the \c x and \c y block will follow and animate its movement in a spring-like fashion towards the specified position (whose values will be set by \c samegame.js).Here is the code added to \c BoomBlock.qml: -\snippet quick/tutorials/samegame/samegame4/content/BoomBlock.qml 1 +\snippet tutorials/samegame/samegame4/content/BoomBlock.qml 1 The \c spring and \c damping values can be changed to modify the spring-like effect of the animation. @@ -341,7 +336,7 @@ animate the opacity value so that it gradually fades in and out, instead of abru visible and invisible. To do this, we'll apply a \l Behavior on the \c opacity property of the \c Image type in \c BoomBlock.qml: -\snippet quick/tutorials/samegame/samegame4/content/BoomBlock.qml 2 +\snippet tutorials/samegame/samegame4/content/BoomBlock.qml 2 Note the \c{opacity: 0} which means the block is transparent when it is first created. We could set the opacity in \c samegame.js when we create and destroy the blocks, @@ -367,14 +362,14 @@ To fade out, we set \c dying to true instead of setting opacity to 0 when a bloc Finally, we'll add a cool-looking particle effect to the blocks when they are destroyed. To do this, we first add a \l ParticleSystem in \c BoomBlock.qml, like so: -\snippet quick/tutorials/samegame/samegame4/content/BoomBlock.qml 3 +\snippet tutorials/samegame/samegame4/content/BoomBlock.qml 3 To fully understand this you should read the \l Particles documentation, but it's important to note that \c emitRate is set to zero so that particles are not emitted normally. Also, we extend the \c dying State, which creates a burst of particles by calling the \c burst() method on the particles type. The code for the states now look like this: -\snippet quick/tutorials/samegame/samegame4/content/BoomBlock.qml 4 +\snippet tutorials/samegame/samegame4/content/BoomBlock.qml 4 Now the game is beautifully animated, with subtle (or not-so-subtle) animations added for all of the player's actions. The end result is shown below, with a different set of images to demonstrate basic theming: @@ -391,32 +386,32 @@ To do this, we will show a dialog when the game is over to request the player's This requires a few changes to \c Dialog.qml. In addition to a \c Text type, it now has a \c TextInput child item for receiving keyboard text input: -\snippet quick/tutorials/samegame/samegame4/content/Dialog.qml 0 +\snippet tutorials/samegame/samegame4/content/Dialog.qml 0 \dots 4 -\snippet quick/tutorials/samegame/samegame4/content/Dialog.qml 2 +\snippet tutorials/samegame/samegame4/content/Dialog.qml 2 \dots 4 -\snippet quick/tutorials/samegame/samegame4/content/Dialog.qml 3 +\snippet tutorials/samegame/samegame4/content/Dialog.qml 3 We'll also add a \c showWithInput() function. The text input will only be visible if this function is called instead of \c show(). When the dialog is closed, it emits a \c closed() signal, and other types can retrieve the text entered by the user through an \c inputText property: -\snippet quick/tutorials/samegame/samegame4/content/Dialog.qml 0 -\snippet quick/tutorials/samegame/samegame4/content/Dialog.qml 1 +\snippet tutorials/samegame/samegame4/content/Dialog.qml 0 +\snippet tutorials/samegame/samegame4/content/Dialog.qml 1 \dots 4 -\snippet quick/tutorials/samegame/samegame4/content/Dialog.qml 3 +\snippet tutorials/samegame/samegame4/content/Dialog.qml 3 Now the dialog can be used in \c samegame.qml: -\snippet quick/tutorials/samegame/samegame4/samegame.qml 0 +\snippet tutorials/samegame/samegame4/samegame.qml 0 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. The \c nameInputDialog is activated in the \c victoryCheck() function in \c samegame.js: -\snippet quick/tutorials/samegame/samegame4/content/samegame.js 3 +\snippet tutorials/samegame/samegame4/content/samegame.js 3 \dots 4 -\snippet quick/tutorials/samegame/samegame4/content/samegame.js 4 +\snippet tutorials/samegame/samegame4/content/samegame.js 4 \section3 Storing high scores offline @@ -424,7 +419,7 @@ Now we need to implement the functionality to actually save the High Scores tabl Here is the \c saveHighScore() function in \c samegame.js: -\snippet quick/tutorials/samegame/samegame4/content/samegame.js 2 +\snippet tutorials/samegame/samegame4/content/samegame.js 2 First we call \c sendHighScore() (explained in the section below) if it is possible to send the high scores to an online database. @@ -443,7 +438,7 @@ If the player entered their name we can send the data to the web service us If the player enters a name, we send the data to the service using this code in \c samegame.js: -\snippet quick/tutorials/samegame/samegame4/content/samegame.js 1 +\snippet tutorials/samegame/samegame4/content/samegame.js 1 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 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 |