diff options
| author | Venugopal Shivashankar <Venugopal.Shivashankar@qt.io> | 2018-03-14 14:20:44 +0100 |
|---|---|---|
| committer | Venugopal Shivashankar <Venugopal.Shivashankar@qt.io> | 2018-05-02 09:05:09 +0000 |
| commit | 103aeab4c13f9969fbbd4f3d64e650373c35a141 (patch) | |
| tree | 8c34545ec9527245e1c951a4edcf7b608ad015a5 /sources/pyside2/doc | |
| parent | 5f83ff14270cbe63492c08b5aa279d30a6c2677b (diff) | |
Doc: Update the QML advanced tutorial
- Switch the languague to 2nd person
- Update the Qt Quick import statements
- Replace instances of "elements" that referred to
QML types or items.
Change-Id: Iabac624270dbd8685bf1f4d2dec198984e7a3c68
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
Diffstat (limited to 'sources/pyside2/doc')
19 files changed, 217 insertions, 141 deletions
diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/index.rst b/sources/pyside2/doc/tutorials/qmladvancedtutorial/index.rst index 5b5a367d0..d40af59d7 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/index.rst +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/index.rst @@ -3,23 +3,24 @@ QML Advanced Tutorial ********************* -This tutorial walks step-by-step through the creation of a full application using QML. +This tutorial walks you through the steps of creating an application using QML. It assumes that you already know the basics of QML (for example, from reading the :ref:`qmltutorial`. -In this tutorial we write a game, *Same Game*, based on the Same Game application -included in the declarative demos directory, which looks like this: +In this tutorial, you will develop the game, *Same Game*. It is based on the +Same Game application included in the declarative demos directory, and looks +like this: .. figure:: declarative-samegame.png :align: center -We will cover concepts for producing a fully functioning application, including -JavaScript integration, using QML States and Behaviors to -manage components and enhance your interface, and storing persistent application data. +The tutorial covers concepts related to producing a fully functional application, +including JavaScript integration, using QML states and behaviors to manage +components and enhance your interface, and storing persistent application data. -An understanding of JavaScript is helpful to understand parts of this tutorial, but if you don't -know JavaScript you can still get a feel for how you can integrate backend logic to create and -control QML elements. +Prior knowledge of JavaScript is useful to understand parts of this +tutorial, but if you don't know it, you can still get a feel of +integrating the backend logic that creates and controls QML items. Tutorial chapters: diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame1/Block.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame1/Block.qml index 27520cef4..fb78c473c 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame1/Block.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame1/Block.qml @@ -49,7 +49,7 @@ ****************************************************************************/ //![0] -import QtQuick 1.0 +import QtQuick 2.0 Item { id: block diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame1/Button.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame1/Button.qml index 64d86d527..c612655f0 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame1/Button.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame1/Button.qml @@ -49,7 +49,7 @@ ****************************************************************************/ //![0] -import QtQuick 1.0 +import QtQuick 2.0 Rectangle { id: container diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame1/samegame.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame1/samegame.qml index 18f256a05..aa40b2bff 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame1/samegame.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame1/samegame.qml @@ -49,7 +49,7 @@ ****************************************************************************/ //![0] -import QtQuick 1.0 +import QtQuick 2.0 Rectangle { id: screen diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame2/Block.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame2/Block.qml index ac1ae7616..4306d9ecb 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame2/Block.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame2/Block.qml @@ -48,7 +48,7 @@ ** ****************************************************************************/ -import QtQuick 1.0 +import QtQuick 2.0 Item { id: block diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame2/Button.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame2/Button.qml index 0e0aef7e2..abfba0725 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame2/Button.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame2/Button.qml @@ -48,7 +48,7 @@ ** ****************************************************************************/ -import QtQuick 1.0 +import QtQuick 2.0 Rectangle { id: container diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame2/samegame.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame2/samegame.qml index 7e8257b25..179835e96 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame2/samegame.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame2/samegame.qml @@ -48,7 +48,7 @@ ** ****************************************************************************/ -import QtQuick 1.0 +import QtQuick 2.0 //![2] import "samegame.js" as SameGame //![2] diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/Block.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/Block.qml index 4d4f9f3c5..6e35ad0e2 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/Block.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/Block.qml @@ -49,7 +49,7 @@ ****************************************************************************/ //![0] -import QtQuick 1.0 +import QtQuick 2.0 Item { id: block diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/Button.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/Button.qml index 0e0aef7e2..abfba0725 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/Button.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/Button.qml @@ -48,7 +48,7 @@ ** ****************************************************************************/ -import QtQuick 1.0 +import QtQuick 2.0 Rectangle { id: container diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/Dialog.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/Dialog.qml index 637e8ade7..dd626977e 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/Dialog.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/Dialog.qml @@ -49,7 +49,7 @@ ****************************************************************************/ //![0] -import QtQuick 1.0 +import QtQuick 2.0 Rectangle { id: container diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/samegame.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/samegame.qml index 7ad4bd0bb..c1e21f218 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/samegame.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame3/samegame.qml @@ -49,7 +49,7 @@ ****************************************************************************/ //![0] -import QtQuick 1.0 +import QtQuick 2.0 import "samegame.js" as SameGame Rectangle { diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/content/BoomBlock.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/content/BoomBlock.qml index 7392e3e37..cf767f2d5 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/content/BoomBlock.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/content/BoomBlock.qml @@ -48,7 +48,7 @@ ** ****************************************************************************/ -import QtQuick 1.0 +import QtQuick 2.0 import Qt.labs.particles 1.0 Item { diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/content/Button.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/content/Button.qml index 0e0aef7e2..abfba0725 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/content/Button.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/content/Button.qml @@ -48,7 +48,7 @@ ** ****************************************************************************/ -import QtQuick 1.0 +import QtQuick 2.0 Rectangle { id: container diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/content/Dialog.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/content/Dialog.qml index a46ee74bb..979904f28 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/content/Dialog.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/content/Dialog.qml @@ -48,7 +48,7 @@ ** ****************************************************************************/ -import QtQuick 1.0 +import QtQuick 2.0 //![0] Rectangle { diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/samegame.qml b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/samegame.qml index 6053136c3..bb8a5f9dd 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/samegame.qml +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame/samegame4/samegame.qml @@ -48,7 +48,7 @@ ** ****************************************************************************/ -import QtQuick 1.0 +import QtQuick 2.0 import "content" import "content/samegame.js" as SameGame diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame1.rst b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame1.rst index c8638ce06..f48c0672b 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame1.rst +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame1.rst @@ -8,7 +8,7 @@ Creating the application screen The first step is to create the basic QML items in your application. -To begin with, we create our Same Game application with a main screen like this: +To begin with, create a main screen like this: .. figure:: declarative-adv-tutorial1.png :align: center @@ -18,21 +18,21 @@ This is defined by the main application file, ``samegame.qml``, which looks like .. pysideinclude:: samegame/samegame1/samegame.qml :snippet: 0 -This gives you a basic game window that includes the main canvas for the -blocks, a "New Game" button and a score display. +It gives a basic game window that includes the main canvas for the +blocks, a "New Game" button, and a score display. -One item you may not recognize here -is the SystemPalette item. This provides access to the Qt system palette -and is used to give the button a more native look-and-feel. +One item you may not recognize here is the SystemPalette item. This provides +access to the Qt system palette and is used to give the button a more native +look-and-feel. -Notice the anchors for the ``Item``, ``Button`` and ``Text`` elements are set using +Notice the anchors for the ``Item``, ``Button``, and ``Text`` items are set using group notation for readability. -Adding Button and Block components +Adding button and block components ================================== The ``Button`` item in the code above is defined in a separate component file named ``Button.qml``. -To create a functional button, we use the QML elements Text and MouseArea inside a Rectangle. +To create a functional button, use the Text and MouseArea QML types inside a Rectangle. Here is the ``Button.qml`` code: .. pysideinclude:: samegame/samegame1/Button.qml @@ -43,28 +43,29 @@ has an ``onClicked()`` handler that is implemented to emit the ``clicked()`` sig ``container`` when the area is clicked. 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 ``Block.qml`` file: +Each block is an item that contains an image. The block +is defined in the ``Block.qml`` file: .. pysideinclude:: samegame/samegame1/Block.qml :snippet: 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. -We have not added any code yet to create the blocks; we will do this -in the next chapter. +tutorial progresses, you will animate and give behaviors to the blocks. +You have not added any code yet to create the blocks; this +will be done in the next chapter. -We have set the image to be the size of its parent Item using ``anchors.fill: parent``. -This means that when we dynamically create and resize the block items +You have set the image to be the size of its parent Item using ``anchors.fill: parent``. +This means that when you dynamically create and resize the block items later on in the tutorial, the image will be scaled automatically to the correct size. -Notice the relative path for the Image element's ``source`` property. -This path is relative to the location of the file that contains the Image element. +Notice the relative path for the Image item's ``source`` property. +It is relative to the location of the file that contains the Image item. Alternatively, you could set the Image source to an absolute file path or a URL that contains an image. -You should be familiar with the code so far. We have just created some basic -elements to get started. Next, we will populate the game canvas with some blocks. +You should be familiar with the code so far, as you have created some basic +items to get started. In the next chapter, you will populate the game canvas +with some blocks. -[Previous :ref:`qmladvancedtutorial`] [Next :ref:`samegame2`]
\ No newline at end of file +[Previous :ref:`qmladvancedtutorial`] [Next :ref:`samegame2`] diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame2.rst b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame2.rst index 6cc12d5ca..7f3ee8845 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame2.rst +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame2.rst @@ -6,13 +6,12 @@ QML Advanced Tutorial 2 - Populating the Game Canvas Generating the blocks in JavaScript =================================== -Now that we've written some basic elements, let's start writing the game. +Now that the basic elements are in place, start writing the game. The first task is to generate the game blocks. Each time the New Game button is clicked, the game canvas is populated with a new, random set of -blocks. Since we need to dynamically generate new blocks for each new game, -we cannot use Repeater to define the blocks. Instead, we will -create the blocks in JavaScript. +blocks that are generated dynamically. You can achieve this by creating +the blocks using JavaScript intead of a Repeater. Here is the JavaScript code for generating the blocks, contained in a new file, ``samegame.js``. The code is explained below. @@ -29,11 +28,11 @@ The ``createBlock()`` function creates a block from the ``Block.qml`` file and moves the new block to its position on the game canvas. This involves several steps: * ``Qt.createComponent()`` is called to - generate an element from ``Block.qml``. If the component is ready, + generate an instance of ``Block.qml``. If the component is ready, we can call ``createObject()`` to create an instance of the ``Block`` item. -* If ``createObject()`` returned null (i.e. if there was an error +* If ``createObject()`` returned null (that is, if there was an error while loading the object), print the error information. * Place the block in its position on the board and set its width and @@ -46,26 +45,26 @@ and moves the new block to its position on the game canvas. This involves severa Connecting JavaScript components to QML ======================================= -Now we need to call the JavaScript code in ``samegame.js`` from our QML files. -To do this, we add this line to ``samegame.qml`` which imports +Now, call the JavaScript code in ``samegame.js`` from your QML files. +To do this, add the following line to ``samegame.qml`` to import the JavaScript file as a module: .. pysideinclude:: samegame/samegame2/samegame.qml :snippet: 2 -This allows us to refer to any functions within ``samegame.js`` using "SameGame" +This lets you to refer to any functions within ``samegame.js`` using "SameGame" as a prefix: for example, ``SameGame.startNewGame()`` or ``SameGame.createBlock()``. -This means we can now connect the New Game button's ``onClicked`` handler to the ``startNewGame()`` +This means you can now connect the New Game button's ``onClicked`` handler to the ``startNewGame()`` function, like this: .. pysideinclude:: samegame/samegame2/samegame.qml :snippet: 1 -So, when you click the New Game button, ``startNewGame()`` is called and generates a field of blocks, like this: +So, when you click the New Game button, ``startNewGame()`` is called to generate a field of blocks, like this: .. figure:: declarative-adv-tutorial2.png :align: center -Now, we have a screen of blocks, and we can begin to add the game mechanics. +Now that the screen of blocks is ready, you can start adding the game mechanics. -[Previous :ref:`samegame1`] [Next :ref:`samegame3`]
\ No newline at end of file +[Previous :ref:`samegame1`] [Next :ref:`samegame3`] diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame3.rst b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame3.rst index a1fe44edd..b3c794ec2 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame3.rst +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame3.rst @@ -6,11 +6,11 @@ QML Advanced Tutorial 3 - Implementing the Game Logic Making a playable game ====================== -Now that we have all the game components, we can add the game logic that -dictates how a player interacts with the blocks and plays the game +Now that all the UI components are ready, add the game logic that +dictates how a player interacts with the blocks and plays the game, until it is won or lost. -To do this, we have added the following functions to ``samegame.js``: +To achieve this, add the following functions to ``samegame.js``: * ``handleClick(x,y)`` @@ -19,56 +19,82 @@ To do this, we have added the following functions to ``samegame.js``: * ``victoryCheck()`` * ``floodMoveCheck(xIdx, yIdx, type)`` -As this is a tutorial about QML, not game design, we will only discuss ``handleClick()`` and ``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 Python and then exposed to QML. +As this is a tutorial about QML, not game design, only the ``handleClick()`` +and ``victoryCheck()`` functions that interface directly with the QML items +are discussed. + +.. Note:: Although the game logic here is written in JavaScript, + it could have been written in Python and then exposed to QML. Enabling mouse click interaction ================================ -To make it easier for the JavaScript code to interface with the QML elements, we have added an Item called ``gameCanvas`` to ``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: +To make it easier for the JavaScript code to interface with the QML items, +an Item called ``gameCanvas`` is added to ``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: .. pysideinclude:: samegame/samegame3/samegame.qml :snippet: 1 -The ``gameCanvas`` item is the exact size of the board, and has a ``score`` property and a 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 -the application scales to the available screen size. -Since its size is bound to a multiple of ``blockSize``, ``blockSize`` was moved out of ``samegame.js`` and into ``samegame.qml`` as a QML property. -Note that it can still be accessed from the script. +The ``gameCanvas`` item is of the same size as the board, and has a ``score`` +property and a 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 the application scales to the available screen size. As the item's size +is bound to a multiple of ``blockSize``, ``blockSize`` is moved into ``samegame.qml`` +from ``samegame.js``, as a QML property. + +.. Note:: The ``blockSize`` can still be accessed from the script. -When clicked, the MouseArea calls ``handleClick()`` in ``samegame.js``, which determines whether the player's click should cause any blocks to be removed, and updates ``gameCanvas.score`` with the current score if necessary. Here is the ``handleClick()`` function: +When clicked, the MouseArea calls ``handleClick()`` in ``samegame.js``, which +determines whether the player's click should cause any blocks to be removed, +and updates ``gameCanvas.score`` with the current score if necessary. Here is +the ``handleClick()`` function: .. pysideinclude:: samegame/samegame3/samegame.js :snippet: 1 -Note that if ``score`` was a global variable in the ``samegame.js`` file you would not be able to bind to it. You can only bind to QML properties. +.. Note:: If ``score`` was a global variable in the ``samegame.js`` file, + you would not be able to bind to it. You can only bind to QML properties. Updating the score ================== -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: +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: .. pysideinclude:: samegame/samegame3/samegame.js :snippet: 2 -This updates the ``gameCanvas.score`` value and displays a "Game Over" dialog if the game is finished. +This updates the ``gameCanvas.score`` value and displays a "Game Over" dialog +if the game is finished. -The Game Over dialog is created using a ``Dialog`` element that is defined in ``Dialog.qml``. Here is the ``Dialog.qml`` code. Notice how it is designed to be usable imperatively from the script file, via the functions and signals: +The Game Over dialog is created using a ``Dialog`` item that is defined in +``Dialog.qml``. Here is the ``Dialog.qml`` code: .. pysideinclude:: samegame/samegame3/Dialog.qml :snippet: 0 -And this is how it is used in the main ``samegame.qml`` file: +Notice how it is designed to be usable imperatively from the script file, via +the functions and signals. And this is how it is used in the main +``samegame.qml`` file: .. pysideinclude:: samegame/samegame3/samegame.qml :snippet: 2 -We give the dialog a ``z`` value of 100 to ensure it is displayed on top of our other components. The default ``z`` value for an item is 0. +Give the dialog a ``z`` value of 100 to ensure it is displayed on top of our +other components. The default ``z`` value for an item is 0. A dash of color --------------- -It's not much fun to play Same Game if all the blocks are the same color, so we've modified the ``createBlock()`` function in ``samegame.js`` to randomly create a different type of block (for either red, green or blue) each time it is called. ``Block.qml`` has also changed so that each block contains a different image depending on its type: +It's not much fun to play Same Game if all the blocks are of the same color, so +the ``createBlock()`` function in ``samegame.js`` randomly changes the color +to create a different type of block (for either red, green or blue) each time +it is called. ``Block.qml`` has also changed so that each block contains a +different image depending on its type: .. pysideinclude:: samegame/samegame3/Block.qml :snippet: 0 @@ -77,7 +103,8 @@ It's not much fun to play Same Game if all the blocks are the same color, so we' A working game ============== -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). +You 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). Here is a screenshot of what has been accomplished so far: .. figure:: declarative-adv-tutorial3.png @@ -88,8 +115,10 @@ This is what ``samegame.qml`` looks like now: .. pysideinclude:: samegame/samegame3/samegame.qml :snippet: 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 -until the next chapter - where your application becomes alive! +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 until the next chapter +- where your application becomes alive! [Previous :ref:`samegame2`] [Next :ref:`samegame4`] diff --git a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame4.rst b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame4.rst index 50aaff16a..5ea38a5ad 100644 --- a/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame4.rst +++ b/sources/pyside2/doc/tutorials/qmladvancedtutorial/samegame4.rst @@ -6,48 +6,59 @@ QML Advanced Tutorial 4 - Finishing Touches Adding some flair ================= -Now we're going to do two things to liven up the game: animate the blocks and add a High Score system. +In this chapter, you are going to do two things to enhance the game +experience: animate the blocks and add a High Score system. -We've also cleaned up the directory structure for our application files. We now have a lot of files, so all the -JavaScript and QML files outside of ``samegame.qml`` have been moved into a new sub-directory named "content". +You should clean up the directory structure, now that there are a +lot of files. Move all the JavaScript and QML files outside of ``samegame.qml`` +into a new sub-directory named "content". -In anticipation of the new block animations, ``Block.qml`` file is now renamed to ``BoomBlock.qml``. +In anticipation of the new block animations, ``Block.qml`` file is now renamed +to ``BoomBlock.qml``. Animating block movement ------------------------ -First we will animate the blocks so that they move in a fluid manner. QML has a number of methods for adding fluid -movement, and in this case we're going to use the Behavior element to add a SpringAnimation. -In ``BoomBlock.qml``, we apply a SpringAnimation behavior to the ``x`` and ``y`` properties so that the -block will follow and animate its movement in a spring-like fashion towards the specified position (whose -values will be set by ``samegame.js``).Here is the code added to ``BoomBlock.qml``: +First, you will animate the blocks so that they move in a fluid manner. QML has +a number of methods for adding fluid movement, and in this case you are going to +use the Behavior type to add a SpringAnimation. In ``BoomBlock.qml``, apply a +SpringAnimation behavior to the ``x`` and ``y`` properties so that the +block follows and animate its movement in a spring-like fashion towards the +specified position (whose values are set by ``samegame.js``). Here is the code +added to ``BoomBlock.qml``: .. pysideinclude:: samegame/samegame4/content/BoomBlock.qml :snippet: 1 -The ``spring`` and ``damping`` values can be changed to modify the spring-like effect of the animation. +The ``spring`` and ``damping`` values can be changed to modify the spring-like +effect of the animation. -The ``enabled: spawned`` setting refers to the ``spawned`` value that is set from ``createBlock()`` in ``samegame.js``. -This ensures the SpringAnimation on the ``x`` is only enabled after ``createBlock()`` has set the block to -the correct position. Otherwise, the blocks will slide out of the corner (0,0) when a game begins, instead of falling -from the top in rows. (Try commenting out ``enabled: spawned`` and see for yourself.) +The ``enabled: spawned`` setting refers to the ``spawned`` value that comes from +the ``createBlock()`` function in ``samegame.js``. This ensures that the +SpringAnimation on ``x`` is only enabled after ``createBlock()`` has set the +block to the correct position. Otherwise, the blocks will slide out of the +corner (0,0) when a game begins, instead of falling from the top in rows. +Try commenting out the line, ``enabled: spawned``, and see the effect for +yourself. Animating block opacity changes ------------------------------- -Next, we will add a smooth exit animation. For this, we'll use a Behavior element, which allows us to specify -a default animation when a property change occurs. In this case, when the ``opacity`` of a Block changes, we will -animate the opacity value so that it gradually fades in and out, instead of abruptly changing between fully -visible and invisible. To do this, we'll apply a Behavior on the ``opacity`` property of the ``Image`` -element in ``BoomBlock.qml``: +Next, add a smooth exit animation. For this, use a Behavior type, which +allows us to specify a default animation when a property change occurs. In this +case, when the ``opacity`` of a Block changes, animate the opacity value so that +it gradually fades in and out, instead of abruptly changing between fully +visible and invisible. To do this, apply a Behavior on the ``opacity`` property +of the ``Image`` item in ``BoomBlock.qml``: .. pysideinclude:: samegame/samegame4/content/BoomBlock.qml :snippet: 2 -Note the ``opacity: 0`` which means the block is transparent when it is first created. We could set the opacity -in ``samegame.js`` when we create and destroy the blocks, -but instead we'll use states, since this is useful for the next animation we're going to add. -Initially, we add these States to the root element of ``BoomBlock.qml``: +Note the ``opacity: 0``, which means the block is transparent when it is first +created. You could set the opacity in ``samegame.js`` when we create and +destroy the blocks, but use states instead, as this is useful for the next +animation you are going to add. Initially, add these States to the root +item of ``BoomBlock.qml``: :: @@ -61,42 +72,53 @@ Initially, we add these States to the root element of ``BoomBlock.qml``: } ] -Now blocks will automatically fade in, as we already set ``spawned`` to true when we implemented the block 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 blocks will automatically fade in, as ``spawned`` is set to true when +you implemented the block animations. To fade out, set ``dying`` to true +instead of setting opacity to 0 when a block is destroyed (in the +``floodFill()`` function). Adding particle effects ----------------------- -Finally, we'll add a cool-looking particle effect to the blocks when they are destroyed. To do this, we first add a Particles element in -``BoomBlock.qml``, like so: +Finally, add a cool-looking particle effect to the blocks when they are +destroyed. To do this, first add a Particles item in +``BoomBlock.qml``, like this: .. pysideinclude:: samegame/samegame4/content/BoomBlock.qml :snippet: 3 -To fully understand this you should read the Particles documentation, but it's important to note that ``emissionRate`` is set -to zero so that particles are not emitted normally. -Also, we extend the ``dying`` State, which creates a burst of particles by calling the ``burst()`` method on the particles element. The code for the states now look -like this: +To fully understand this you should read the Particles documentation, +but it's important to note that ``emissionRate`` is set to zero so that +particles are not emitted normally. Also, extend the ``dying`` State, +which creates a burst of particles by calling the ``burst()`` method on the +particles item. The code for the states now look like this: .. pysideinclude:: samegame/samegame4/content/BoomBlock.qml :snippet: 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: +Now the gaming experience is pleasing with these animations. With a few +more simple animations for all of the player's actions, it will look even better. +The end result is shown below, with a different set of images to demonstrate +the basic theme: .. figure:: declarative-adv-tutorial4.gif :align: center -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. +The theme change here is produced simply by replacing the block images. This +can be done at runtime by changing the ``source`` property of the Image. You +could go a step further and add a button that toggles between themes with +different images. -Keeping a High Scores table +Keeping a high scores table =========================== -Another feature we might want to add to the game is a method of storing and retrieving high scores. +Another feature you might want to add to the game is a method of storing and +retrieving high scores. -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. -This requires a few changes to ``Dialog.qml``. In addition to a ``Text`` element, it now has a -``TextInput`` child item for receiving keyboard text input: +To do this, show a dialog when the game is over to request the player's name +and add it to a High Scores table. This requires a few changes to +``Dialog.qml``. In addition to a ``Text`` item, it now has a ``TextInput`` +child item for receiving keyboard text input: .. pysideinclude:: samegame/samegame4/content/Dialog.qml :snippet: 2 @@ -106,9 +128,10 @@ This requires a few changes to ``Dialog.qml``. In addition to a ``Text`` element } -We'll also add a ``showWithInput()`` function. The text input will only be visible if this function -is called instead of ``show()``. When the dialog is closed, it emits a ``closed()`` signal, and -other elements can retrieve the text entered by the user through an ``inputText`` property: +Also, add a ``showWithInput()`` function. The text input will only be visible if +this function is called instead of ``show()``. When the dialog is closed, it +emits a ``closed()`` signal, and other items can retrieve the text entered by +the user through the ``inputText`` property: .. pysideinclude:: samegame/samegame4/content/Dialog.qml :snippet: 1 @@ -122,9 +145,12 @@ Now the dialog can be used in ``samegame.qml``: .. pysideinclude:: samegame/samegame4/samegame.qml :snippet: 0 -When the dialog emits the ``closed`` signal, we call the new ``saveHighScore()`` function in ``samegame.js``, which stores the high score locally in an SQL database and also send the score to an online database if possible. +When the dialog emits the ``closed`` signal, we call the new ``saveHighScore()`` +function in ``samegame.js``, to store the high score locally in an SQL database +and also send the score to an online database if possible. -The ``nameInputDialog`` is activated in the ``victoryCheck()`` function in ``samegame.js``: +The ``nameInputDialog`` is activated in the ``victoryCheck()`` function in +``samegame.js``: .. pysideinclude:: samegame/samegame4/content/samegame.js :snippet: 4 @@ -134,40 +160,60 @@ The ``nameInputDialog`` is activated in the ``victoryCheck()`` function in ``sam Storing high scores offline --------------------------- -Now we need to implement the functionality to actually save the High Scores table. +Now, you need to implement the functionality to actually save the High Scores table. Here is the ``saveHighScore()`` function in ``samegame.js``: .. pysideinclude:: samegame/samegame4/content/samegame.js :snippet: 2 -First we call ``sendHighScore()`` (explained in the section below) if it is possible to send the high scores to an online database. - -Then, we use the Offline Storage API to maintain a persistant SQL database unique to this application. We create an offline storage database for the high scores using ``openDatabase()`` 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 retrival, and in the ``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. - -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 ``Dialog``). This would allow a more themeable dialog that could beter present the high scores. If your QML is the UI for a Python application, you could also have passed the score to a Python function to store it locally in a variety of ways, including a simple format without SQL or in another SQL database. +First, call ``sendHighScore()`` to send the high scores to an online database. + +Then, use the Offline Storage API to maintain a persistent SQL database, unique +to this application. Create an offline storage database for the high scores +using ``openDatabase()``, then 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. The ``db.transaction()`` uses three SQL queries: + * To initialize the database, if necessary. + * To add high scores to the database. + * To retrieve the high score records. + +To use the returned records, turn it into a string with one line per row, and show +a dialog containing that string. + +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 ``Dialog``). This allows for a more themeable dialog that could +present the high scores in a better way. If you are using QML-based UI for a +Python application, you can also pass the score to a function that stores it +locally in a variety of ways. This can be a simple format without SQL, or in +another SQL database. Storing high scores online -------------------------- -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 here 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 also request an XML or QML file from that same server, which contains and displays the scores, -but that's beyond the scope of this tutorial. The php script we use here is available in the ``examples`` directory. - -If the player entered their name we can send the data to the web service us +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 application. The +implementation we've done here 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 also request an XML or QML file, which +contains and displays the scores, but that's beyond the scope of this tutorial. +The php script used here is available in the ``examples`` directory. -If the player enters a name, we send the data to the service using this code in ``samegame.js``: +If the player entered their name, you can send the data to an online database +service. The following code snippet from ``samegame.js`` demonstrates this well: .. pysideinclude:: samegame/samegame4/content/samegame.js :snippet: 1 -The XMLHttpRequest in this code is the same as the ``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 +The XMLHttpRequest in this code is the same as the ``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 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 with the blocks. -An alternate way to access and submit web-based data would be to use QML elements designed for this purpose. XmlListModel +An alternate way to access and submit web-based data would be to use QML items 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). @@ -176,7 +222,7 @@ That's it! By following this tutorial you've seen how you can write a fully functional application in QML: -* Build your application with QML elements. +* Build your application with QML items. * Add application logic with JavaScript code. * Add animations with Behaviors and states. * Store persistent application data using, for example, the Offline Storage API or XMLHttpRequest. @@ -184,4 +230,4 @@ By following this tutorial you've seen how you can write a fully functional appl There is so much more to learn about QML that we haven't been able to cover in this tutorial. Check out all the demos and examples and the documentation to see all the things you can do with QML! -[Previous :ref:`samegame3`]
\ No newline at end of file +[Previous :ref:`samegame3`] |