/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the test suite 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 Technology Preview License Agreement accompanying
** this package.
**
** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page advtutorial3.html
\title Advanced Tutorial 3 - Implementing the Game Logic

First we add to the \c initBoard function clearing of the board before filling it up again, so that clicking new game won't leave the previous game
lying around in the background. To the \c createComponent function we have added setting the type of the block to a number between
one and three - it's fundamental to the game logic that the blocks be different types if you want a fun game.

The main change was adding the following game logic functions:
\list
\o function \c{handleClick(x,y)}
\o function \c{floodFill(xIdx,yIdx,type)}
\o function \c{shuffleDown()}
\o function \c{victoryCheck()}
\o function \c{floodMoveCheck(xIdx, yIdx, type)}
\endlist

As this is a tutorial about QML, not game design, these functions will not be discussed in detail. The game logic here
was written in script, but it could have been written in C++ and had these functions exposed in the same way (except probably faster).
The interfacing of these functions and QML is what we will focus on. Of these functions, only \c handleClick and \c victoryCheck
interface closely with the QML. Those functions are shown below (the rest are still in the code for this tutorial located at
\c{$QTDIR/examples/declarative/tutorials/samegame}).

\snippet declarative/tutorials/samegame/samegame3/samegame.js 1
\snippet declarative/tutorials/samegame/samegame3/samegame.js 2

You'll notice them referring to the \c gameCanvas item. This is an item that has been added to the QML for easier interfacing with the game logic.
It is placed next to the background image and replaces the background as the item to create the blocks in.
Its code is shown below:

\snippet declarative/tutorials/samegame/samegame3/samegame.qml 1

This item is the exact size of the board, contains a score property, and a mouse region for input.
The blocks are now created as its children, and its size is used to determining the board size, so as to scale to the available screen size.
Since it needs to bind its size to a multiple of \c tileSize, \c tileSize needs to be moved into a QML property and out of the script file.
Note that it can still be accessed from the script.

The mouse region simply calls \c{handleClick()}, which deals with the input events.
Should those events cause the player to score, \c{gameCanvas.score} is updated.
The score display text item has also been changed to bind its text property to \c{gamecanvas.score}.
Note that if score was a global variable in the \c{samegame.js} file you could not bind to it. You can only bind to QML properties.

\c victoryCheck() primarily updates the score variable. But it also pops up a dialog saying \e {Game Over} when the game is over.
In this example we wanted a pure-QML, animated dialog, and since QML doesn't contain one, we wrote our own.
Below is the code for the \c Dialog element, note how it's designed so as to be usable imperatively from within the script file (via the functions and signals):

\snippet declarative/tutorials/samegame/samegame3/Dialog.qml 0

And this is how it's used in the main QML file:

\snippet declarative/tutorials/samegame/samegame3/samegame.qml 2

Combined with the line of code in \c victoryCheck, this causes a dialog to appear when the game is over, informing the user of that fact.

We now have a working game! The blocks can be clicked, the player can score, and the game can end (and then you start a new one).
Below is a screenshot of what has been accomplished so far:

\image declarative-adv-tutorial3.png

Here is the QML code as it is now for the main file:

\snippet declarative/tutorials/samegame/samegame3/samegame.qml 0

And the code for the block:

\snippet declarative/tutorials/samegame/samegame3/Block.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 for the first iteration, but in this tutorial they've been saved
until the next chapter - where your application becomes alive!

[Previous: \l {Advanced Tutorial 2 - Populating the Game Canvas}] [\l {advtutorial.html}{Advanced Tutorial}] [Next: \l {Advanced Tutorial 4 - Finishing Touches}]

*/