diff options
Diffstat (limited to 'doc/src/declarative/advtutorial4.qdoc')
| -rw-r--r-- | doc/src/declarative/advtutorial4.qdoc | 183 |
1 files changed, 106 insertions, 77 deletions
diff --git a/doc/src/declarative/advtutorial4.qdoc b/doc/src/declarative/advtutorial4.qdoc index 5ad1ec3..e30fe84 100644 --- a/doc/src/declarative/advtutorial4.qdoc +++ b/doc/src/declarative/advtutorial4.qdoc @@ -1,15 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + /*! \page advtutorial4.html -\title Advanced Tutorial 4 - Finishing Touches \target advtutorial4 +\title Advanced Tutorial 4 - Finishing Touches Now we're going to do two things to liven the game up. Animate the blocks and add a web-based high score system. -If you compare the samegame3 directory with samegame4, you'll noticed that we've cleaned the directory structure up. We now have a lot of files, and so they've been split up into folders - the most notable one being a content folder which we've placed all the QML but the main file. +If you compare the \c samegame3 directory with \c samegame4, you'll noticed that we've cleaned the directory structure up. +We now have a lot of files, and so they've been split up into folders - the most notable one being a content folder +which we've placed all the QML but the main file. \section2 Animated Blocks -The most vital animations are that the blocks move fluidly around the board. QML has many tools for fluid behavior, and in this case we're going to use the Follow element. By having the script set targetX and targetY, instead of x and y directly, we can set the x and y of the block to a follow. SpringFollow is a property value source, which means that you can set a property to be one of these elements and it will automatically bind the property to the element's value. The SpringFollow's value follows another value over time, when the value it is tracking changes the SpringFollow's value will also change, but it will move smoothly there over time with a spring-like movement (based on the spring parameters specified). This is shown in the below snippet of code from Block.qml: +The most vital animations are that the blocks move fluidly around the board. QML has many tools for fluid behavior, +and in this case we're going to use the \l SpringFollow element. By having the script set \c targetX and \c targetY, instead of \c x +and \c y directly, we can set the \c x and \c y of the block to a follow. \l SpringFollow is a property value source, which means +that you can set a property to be one of these elements and it will automatically bind the property to the element's value. +The SpringFollow's value follows another value over time, when the value it is tracking changes the SpringFollow's +value will also change, but it will move smoothly there over time with a spring-like movement (based on the spring +parameters specified). This is shown in the below snippet of code from \c Block.qml: + \code property int targetX: 0 property int targetY: 0 @@ -18,36 +68,25 @@ The most vital animations are that the blocks move fluidly around the board. QML y: SpringFollow { source: targetY; spring: 2; damping: 0.2 } \endcode -We also have to change the samegame.js code, so that wherever it was setting the x or y it now sets targetX and targetY (including when creating the block). This simple change is all you need to get spring moving blocks that no longer teleport around the board. If you try doing just this though, you'll notice that they now never jump from one point to another, even in the initialization! This gives an odd effect of having them all jump out of the corner (0,0) on start up. We'd rather that they fall down from the top in rows. To do this, we disable the x Follow (but not the y follow) and only enable it after we've set the x in the createBlock function. The above snippet now becomes: +We also have to change the \c{samegame.js} code, so that wherever it was setting the \c x or \c y it now sets \c targetX and \c targetY +(including when creating the block). This simple change is all you need to get spring moving blocks that no longer teleport +around the board. If you try doing just this though, you'll notice that they now never jump from one point to another, even in +the initialization! This gives an odd effect of having them all jump out of the corner (0,0) on start up. We'd rather that they +fall down from the top in rows. To do this, we disable the \c x follow (but not the \c y follow) and only enable it after we've set +the \c x in the \c createBlock function. The above snippet now becomes: -\code - property bool spawned: false - property int targetX: 0 - property int targetY: 0 +\snippet declarative/tutorials/samegame/samegame4/content/BoomBlock.qml 1 - x: SpringFollow { enabled: spawned; source: targetX; spring: 2; damping: 0.2 } - y: SpringFollow { source: targetY; spring: 2; damping: 0.2 } -\endcode +The next-most vital animation is a smooth exit. For this animation, we'll use a \l Behavior element. A Behavior is also a property +value source, and it is much like SpringFollow except that it doesn't model the behavior of a spring. You specify how a Behavior +transitions using the standard animations. As we want the blocks to smoothly fade in and out we'll set a Behavior on the block +image's opacity, like so: -The next-most vital animation is a smooth exit. For this animation, we'll use a Behavior element. A Behavior is also a property value source, and it is much like SpringFollow except that it doesn't model the behavior of a spring. You specify how a Behavior transitions using the standard animations. As we want the blocks to smoothly fade in and out we'll set a Behavior on the block image's opacity, like so: -\code - Image { id: img - source: { - if(type == 0){ - "pics/redStone.png"; - } else if(type == 1) { - "pics/blueStone.png"; - } else { - "pics/greenStone.png"; - } - } - opacity: 0 - opacity: Behavior { NumberAnimation { properties:"opacity"; duration: 200 } } - anchors.fill: parent - } -\endcode +\snippet declarative/tutorials/samegame/samegame4/content/BoomBlock.qml 2 -Note that the 'opacity: 0' makes it start out transparent. We could set the opacity in the script file when we create the blocks, but instead we use states (as this is useful for the next animation we'll implement). The below snippet is set on the root element of Block.qml: +Note that the \c{opacity: 0} makes it start out transparent. We could set the opacity in the script file when we create the blocks, +but instead we use states (as this is useful for the next animation we'll implement). The below snippet is set on the root +element of \c{Block.qml}: \code property bool dying: false states: [ @@ -59,62 +98,52 @@ Note that the 'opacity: 0' makes it start out transparent. We could set the opac ] \endcode -Now it will automatically fade in, as we set spawned to true already when implementing the block movement animations. To fade out, we set 'dying' to true instead of setting opacity to 0 when a block is destroyed (in the floodFill function). +Now it will automatically fade in, as we set spawned to true already when implementing the block movement animations. +To fade out, we set 'dying' to true instead of setting opacity to 0 when a block is destroyed (in the \c floodFill function). -The least vital animations are a cool-looking particle effect when they get destroyed. First we create a Particles Element in the block, like so: -\code - Particles { id: particles - width:1; height:1; anchors.centerIn: parent; opacity: 0 - lifeSpan: 700; lifeSpanDeviation: 600; count:0; streamIn: false - angle: 0; angleDeviation: 360; velocity: 100; velocityDeviation:30 - source: { - if(type == 0){ - "pics/redStar.png"; - } else if (type == 1) { - "pics/blueStar.png"; - } else { - "pics/greenStar.png"; - } - } - } -\endcode -To fully understand this you'll want to look at the Particles element documentation, but it's important to note that count is set to zero. -We next extend the 'dying' state, which triggers the particles by setting the count to non-zero. The code for that state looks like this: -\code - State{ name: "DeathState"; when: dying == true - PropertyChanges { target: particles; count: 50 } - PropertyChanges { target: particles; opacity: 1 } - PropertyChanges { target: particles; emitting: false } // i.e. emit only once - PropertyChanges { target: img; opacity: 0 } - } -\endcode -And now the game should be beautifully animated and smooth, with a subtle (or not-so-subtle) animation added for all of the player's actions. +The least vital animations are a cool-looking particle effect when they get destroyed. First we create a \l Particles element in +the block, like so: + +\snippet declarative/tutorials/samegame/samegame4/content/BoomBlock.qml 3 + +To fully understand this you'll want to look at the Particles element documentation, but it's important to note that count is set +to zero. +We next extend the 'dying' state, which triggers the particles by setting the count to non-zero. The code for the states now look +like this: + +\snippet declarative/tutorials/samegame/samegame4/content/BoomBlock.qml 4 + +And now the game should be beautifully animated and smooth, with a subtle (or not-so-subtle) animation added for all of the +player's actions. The end result is shown below: + +\image declarative-adv-tutorial4.gif \section2 Web-based High Scores -Another extension we might want for the game is some way of storing and retriveing high scores. In this tutorial we'll show you how to integrate a web enabled high score storage into your QML application. The implementation we've done is very simple - the high score data is posted to a php script running on a server somewhere, and that server then stores it and displays it to visitors. You could request an XML or QML file from that same server, which contained and displayed the scores, but that's beyond the scope of this tutorial. +Another extension we might want for the game is some way of storing and retrieving high scores. In this tutorial we'll show you +how to integrate a web enabled high score storage into your QML application. The implementation we've done is very +simple - the high score data is posted to a php script running on a server somewhere, and that server then stores it and +displays it to visitors. You could request an XML or QML file from that same server, which contained and displayed the scores, +but that's beyond the scope of this tutorial. -For better high score data, we want the name and time of the player. The time is obtained in the script fairly simply, but we have to ask the player for their name. We thus re-use the dialog QML file to pop up a dialog asking for the player's name (and if they exit this dialog without entering it they have a way to opt out of posting their high score). When the dialog is closed, if the player entered their name we can send the data to the web service in the followign snippet out of the script file: -\code -function sendHighScore(name) { - var postman = new XMLHttpRequest() - var postData = "name="+name+"&score="+gameCanvas.score - +"&gridSize="+maxX+"x"+maxY +"&time="+Math.floor(timer/1000); - postman.open("POST", scoresURL, true); - postman.onreadystatechange = function() { - if (postman.readyState == postman.DONE) { - dialog.show("Your score has been uploaded."); - } - } - postman.send(postData); -} -\endcode +For better high score data, we want the name and time of the player. The time is obtained in the script fairly simply, but we +have to ask the player for their name. We thus re-use the dialog QML file to pop up a dialog asking for the player's name (and +if they exit this dialog without entering it they have a way to opt out of posting their high score). When the dialog is closed, +if the player entered their name we can send the data to the web service in the following snippet out of the script file: + +\snippet declarative/tutorials/samegame/samegame4/content/samegame.js 1 -This is the same XMLHttpRequest() as you'll find in 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 here though, we just post the high 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 way as you did the blocks. +This is the same \c XMLHttpRequest() as you'll find in 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 here though, we just post the high +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 +way as you did the blocks. -An alternate way to access and submit web-based data would be to use QML elements designed for this purpose - XmlListModel 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). +An alternate way to access and submit web-based data would be to use QML elements designed for this purpose - XmlListModel +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). -By following this tutorial you've now ben shown how to write a fully functional application in QML, with the application logic written in a script file and with both many fluid animations and being web-enabled. Congratulations, you should now be skilled enough to write your own QML applications. +By following this tutorial you've now ben shown how to write a fully functional application in QML, with the application logic +written in a script file and with both many fluid animations and being web-enabled. Congratulations, you should now be skilled +enough to write your own QML applications. [Previous: \l {advtutorial3}{Advanced Tutorial 3}] [\l {advtutorial.html}{Advanced Tutorial}] */ |