/****************************************************************************
**
** 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 advtutorial3.html
\target advtutorial3
\title Advanced Tutorial 3 - Implementing the Game Logic

To the \c initBoard function we added clearing the board beforehand, 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 just as well (in fact, probably faster).
The interfacing between these funcions and QML is of interest though. 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 easy interfacing.
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.
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.
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() mostly just updates score. 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 quite usable imperatively from within the script file:

\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's the smooth animated transitions? Where's 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 {advtutorial2}{Advanced Tutorial 2}] [\l {advtutorial.html}{Advanced Tutorial}] [Next: \l {advtutorial4}{Advanced Tutorial 4}]

*/