1 files changed, 108 insertions, 0 deletions
diff --git a/doc/src/declarative/advtutorial2.qdoc b/doc/src/declarative/advtutorial2.qdoc
new file mode 100644
index 0000000..abfdbc6
--- /dev/null
+++ b/doc/src/declarative/advtutorial2.qdoc
@@ -0,0 +1,108 @@
+/****************************************************************************
+**
+** 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 advtutorial2.html
+\example declarative/tutorials/samegame/samegame2
+\title Advanced Tutorial 2 - Populating the Game Canvas
+
+Now that we've written some basic elements, let's start writing the game. The
+first thing to do is to generate all of the blocks. Now we need to dynamically
+generate all of these blocks, because you have a new, random set of blocks
+every time. As they are dynamically generated every time the new game button is
+clicked, as opposed to on startup, we will be dynamically generating the blocks
+in the ECMAScript, as opposed to using a \l Repeater.
+
+This adds enough script to justify a new file, \c{samegame.js}, the intial version
+of which is shown below
+
+\snippet declarative/tutorials/samegame/samegame2/samegame.js 0
+
+The gist of this code is that we create the blocks dynamically, as many as will fit, and then store them in an array for future reference.
+The \c initBoard function will be hooked up to the new game button soon, and should be fairly straight forward.
+
+The \c createBlock function is a lot bigger, and I'll explain it block by block.
+First we ensure that the component has been constructed. QML elements, including composite ones like the \c Block.qml
+that we've written, are never created directly in script. While there is a function to parse and create an arbitrary QML string,
+in the case where you are repeatedly creating the sme item you will want to use the \c createComponent function. \c createComponent is
+a built-in function in the declarative ECMAScript, and returns a component object.
+A component object prepares and stores a QML element (usually a composite element) for easy and efficient use.
+When the component is ready, you can create a new instance of the loaded QML with the \c createObject method.
+If the component is loaded remotely (over HTTP for example) then you will have to wait for the component to finish loading
+before calling \c createObject. Since we don't wait here (the waiting is a syncronous, the component object has a signal to tell
+you when it's done) this code will only work if the block QML is a local file.
+
+As we aren't waiting for he component, the next block of code creates a game block with \c{component.createObject}.
+Since there could be an error in the QML file you are trying to load, success is not guaranteed.
+The first bit of error checkign code comes right after \c{createObject()}, to ensure that the object loaded correctly.
+If it did not load correctly the function returns false, but we don't have that hooked up to the main UI to indicate
+that something has gone wrong. Instead we print out error messages to the console, because an error here means an invalid
+QML file and should only happen while you are developing and testing the UI.
+
+Next we start to set up our dynamically created block.
+Because the \c{Block.qml} file is generic it needs to be placed in the main scene, and in the right place.
+This is why \c parent, \c x, \c y, \c width and \c height are set. We then store it in the board array for later use.
+
+Finally, we have some more error handling. You can only call \c{createObject} if the component has loaded.
+If it has not loaded, either it is still loading or there was an error loading (such as a missing file).
+Since we don't request remote files the problem is likely to be a missing or misplaced file.
+Again we print this to the console to aid debugging.
+
+You now have the code to create a field of blocks dynamically, like below:
+
+\image declarative-adv-tutorial2.png
+
+To hook this code up to the \e{New Game} button, you alter it as below:
+
+\snippet declarative/tutorials/samegame/samegame2/samegame.qml 1
+
+We have just replaced the \c{onClicked: print("Implement me!")} with \c{onClicked: initBoard()}.
+Note that in order to have the function available, you'll need to include the script in the main file,
+by adding a script element to it.
+
+\snippet declarative/tutorials/samegame/samegame2/samegame.qml 2
+
+With those two changes, and the script file, you are now dynamically creating a field of blocks you can play with.
+They don't do anything now though; the next chapter will add the game mechanics.
+
+[Previous: \l {Advanced Tutorial 1 - Creating the Game canvas and block}] [\l {advtutorial.html}{Advanced Tutorial}] [Next: \l {Advanced Tutorial 3 - Implementing the Game Logic}]
+
+*/