diff options
Diffstat (limited to 'doc')
172 files changed, 7569 insertions, 2 deletions
diff --git a/doc/doc.pri b/doc/doc.pri index d4fdcd8..a5e4a82 100644 --- a/doc/doc.pri +++ b/doc/doc.pri @@ -21,13 +21,14 @@ $$unixstyle { } ADP_DOCS_QDOCCONF_FILE = qt-build-docs.qdocconf QT_DOCUMENTATION = ($$QDOC qt-api-only.qdocconf assistant.qdocconf designer.qdocconf \ - linguist.qdocconf qmake.qdocconf) && \ + linguist.qdocconf qmake.qdocconf qml.qdocconf) && \ (cd $$QT_BUILD_TREE && \ $$GENERATOR doc-build/html-qt/qt.qhp -o doc/qch/qt.qch && \ $$GENERATOR doc-build/html-assistant/assistant.qhp -o doc/qch/assistant.qch && \ $$GENERATOR doc-build/html-designer/designer.qhp -o doc/qch/designer.qch && \ $$GENERATOR doc-build/html-linguist/linguist.qhp -o doc/qch/linguist.qch && \ - $$GENERATOR doc-build/html-qmake/qmake.qhp -o doc/qch/qmake.qch \ + $$GENERATOR doc-build/html-qmake/qmake.qhp -o doc/qch/qmake.qch && \ + $$GENERATOR doc-build/html-qml/qml.qhp -o doc/qch/qml.qch \ ) win32-g++:isEmpty(QMAKE_SH) { diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc new file mode 100644 index 0000000..c796633 --- /dev/null +++ b/doc/src/declarative/advtutorial.qdoc @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** 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 advtutorial.html +\title Advanced Tutorial + +This tutorial goes step-by-step through creating a full application using just QML. +It is assumed that you already know basic QML (such as from doing the simple tutorial) and the focus is on showing +how to turn that knowledge into a complete and functioning application. + +In this tutorial we recreate, step by step, the Same Game demo in $QTDIR/demos/declarative/samegame.qml. +The results of the individual steps are in the $QTDIR/examples/declarative/tutorials/samegame directory. + +Tutorial chapters: + +\list +\o \l {Advanced Tutorial 1 - Creating the Game Canvas and Blocks} +\o \l {Advanced Tutorial 2 - Populating the Game Canvas} +\o \l {Advanced Tutorial 3 - Implementing the Game Logic} +\o \l {Advanced Tutorial 4 - Finishing Touches} +\endlist + +*/ diff --git a/doc/src/declarative/advtutorial1.qdoc b/doc/src/declarative/advtutorial1.qdoc new file mode 100644 index 0000000..66fa607 --- /dev/null +++ b/doc/src/declarative/advtutorial1.qdoc @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** 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 advtutorial1.html +\example declarative/tutorials/samegame/samegame1 +\title Advanced Tutorial 1 - Creating the Game Canvas and Blocks + +The first step is to create the items in your application. In Same Game we have a main game screen and the blocks that populate it. + +\image declarative-adv-tutorial1.png + +Here is the QML code for the basic elements. The game window: + +\snippet declarative/tutorials/samegame/samegame1/samegame.qml 0 + +This gives you a basic game window, with room for the game canvas. A new game +button and room to display the score. The one thing you may not recognize here +is the \l SystemPalette item. This item provides access to the Qt system palette +and is used to make the button look more like a system button (for exact native +feel you would use a \l QPushButton). Since we want a fully QML button, and QML does +not include a button, we had to write our own. Below is the code which we wrote to do this: + +\snippet declarative/tutorials/samegame/samegame1/Button.qml 0 + +Note that this Button component was written to be fairly generic, in case we +want to use a similarly styled button later. + +And here is a simple block: + +\snippet declarative/tutorials/samegame/samegame1/Block.qml 0 + +Since it doesn't do anything yet it's very simple, just an image. As the +tutorial progresses and the block starts doing things the file will become +more than just an image. Note that we've set the image to be the size of the itm. +This will be used later, when we dynamically create and size the block items the image will be scaled automatically +to the correct size. + +You should be familiar with all that goes on in these files so far. This is a +very basic start and doesn't move at all - next we will populate the game canvas +with some blocks. + +[\l {advtutorial.html}{Advanced Tutorial}] [Next: \l {Advanced Tutorial 2 - Populating the Game Canvas}] +*/ + 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}] + +*/ diff --git a/doc/src/declarative/advtutorial3.qdoc b/doc/src/declarative/advtutorial3.qdoc new file mode 100644 index 0000000..0d236e4 --- /dev/null +++ b/doc/src/declarative/advtutorial3.qdoc @@ -0,0 +1,117 @@ +/**************************************************************************** +** +** 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 +\example declarative/tutorials/samegame/samegame3 +\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 {Advanced Tutorial 2 - Populating the Game Canvas}] [\l {advtutorial.html}{Advanced Tutorial}] [Next: \l {Advanced Tutorial 4 - Finishing Touches}] + +*/ + diff --git a/doc/src/declarative/advtutorial4.qdoc b/doc/src/declarative/advtutorial4.qdoc new file mode 100644 index 0000000..f4724d8 --- /dev/null +++ b/doc/src/declarative/advtutorial4.qdoc @@ -0,0 +1,158 @@ +/**************************************************************************** +** +** 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 +\example declarative/tutorials/samegame/samegame4 +\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 \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 \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 + + x: SpringFollow { source: targetX; spring: 2; damping: 0.2 } + y: SpringFollow { source: targetY; spring: 2; damping: 0.2 } +\endcode + +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: + +\snippet declarative/tutorials/samegame/samegame4/content/BoomBlock.qml 1 + +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: + +\snippet declarative/tutorials/samegame/samegame4/content/BoomBlock.qml 2 + +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: [ + State{ name: "AliveState"; when: spawned == true && dying == false + PropertyChanges { target: img; opacity: 1 } + }, State{ name: "DeathState"; when: dying == true + PropertyChanges { target: img; opacity: 0 } + } + ] +\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 \c floodFill function). + +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 emissionRate is set +to zero, so that no particles are emitted normally. +We next 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: + +\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 Offline High Scores +Another extension we might want for the game is some way of storing and retrieving high scores. This tutorial contains both online and offline high score storage. + +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 we store the name and high score, using the code below. + +\snippet declarative/tutorials/samegame/samegame4/content/samegame.js 2 + +For offline storage, we use the HTML 5 offline storage javascript API to maintain a persistant SQL database unique to this application. This first line in this function calls the function for the web-based high scores, described later, if it has been setup. Next 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. For a more detailed explanation of the offline storage API in QML, consult the global object documentation. + +This is one way of storing and displaying high scores locally, but not the only way. A more complex alternative would have been to create a high score dialog component, and pass the results to it for processing and display (instead of resusing the Dialog). This would allow a more themable dialog that could present the high scores better. If your QML is the UI for a C++ application, you could also have passed the score to a C++ function to store it locally in a variety of ways, including a simple format without SQL. + +\section2 Web-based High Scores + +You've seen how to store high scores locally, but it is also easy to integrate a web enabled high score storage into your QML application. This tutorial also shows you how to communicate the high scores to a web server. 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. The php script we've used is available in the examples directory. + +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 \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). + +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 {Advanced Tutorial 3 - Implementing the Game Logic}] [\l {advtutorial.html}{Advanced Tutorial}] +*/ diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc new file mode 100644 index 0000000..503b881 --- /dev/null +++ b/doc/src/declarative/anchor-layout.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** 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 anchor-layout.html +\target anchor-layout +\title Anchor-based Layout in QML + +In addition to the more traditional \l Grid, \l Row, and \l Column, QML also provides a way to layout items using the concept of anchors. Each item can be thought of as having a set of 6 invisible "anchor lines": \e left, \e horizontalCenter, \e right, \e top, \e verticalCenter, and \e bottom. + +\image edges_qml.png + +The QML anchoring system allows you to define relationships between the anchor lines of different items. For example, you can write: + +\code +Rectangle { id: rect1; ... } +Rectangle { id: rect2; anchors.left: rect1.right; ... } +\endcode + +In this case, the left edge of \e rect2 is bound to the right edge of \e rect1, producing the following: + +\image edge1.png + +The anchoring system also allows you to specify margins and offsets. Margins specify the amount of empty space to leave to the outside of an item, while offsets allow you to manipulate positioning using the center anchor lines. Note that margins specified using the anchor layout system only have meaning for anchors; they won't have any effect when using other layouts or absolute positioning. + +\image margins_qml.png + +The following example specifies a left margin: + +\code +Rectangle { id: rect1; ... } +Rectangle { id: rect2; anchors.left: rect1.right; anchors.leftMargin: 5; ... } +\endcode + +In this case, a margin of 5 pixels is reserved to the left of \e rect2, producing the following: + +\image edge2.png + +You can specify multiple anchors. For example: + +\code +Rectangle { id: rect1; ... } +Rectangle { id: rect2; anchors.left: rect1.right; anchors.top: rect1.bottom; ... } +\endcode + +\image edge3.png + +By specifying multiple horizontal or vertical anchors you can control the size of an item. For example: + +\code +Rectangle { id: rect1; x: 0; ... } +Rectangle { id: rect2; anchors.left: rect1.right; anchors.right: Rect3.left; ... } +Rectangle { id: Rect3; x: 150; ... } +\endcode + +\image edge4.png + +\section1 Limitations + +For performance reasons, you can only anchor an item to its siblings and direct parent. For example, the following anchor would be considered invalid and would produce a warning: + +\badcode +Item { + id: Group1 + Rectangle { id: rect1; ... } +} +Item { + id: Group2 + Rectangle { id: rect2; anchors.left: rect1.right; ... } // invalid anchor! +} +\endcode + +*/ diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc new file mode 100644 index 0000000..1314493 --- /dev/null +++ b/doc/src/declarative/animation.qdoc @@ -0,0 +1,266 @@ +/**************************************************************************** +** +** 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 qmlanimation.html +\title QML Animation + +Animation in QML is done by animating properties of objects. Properties of type +real, int, color, rect, point, and size can all be animated. + +QML supports three different forms of animation - basic property animation, +transitions, and property behaviors. + +\section1 Basic Property Animation + +The simplest form of animation is directly using \l PropertyAnimation, which can animate all of the property +types listed above. If the property you are animating is a number or color, you can alternatively use +NumberAnimation or ColorAnimation. These elements don't add any additional functionality, +but will help enforce type correctness and are slightly more efficient. + +A property animation can be specified as a value source. This is especially useful for repeating animations. + +The following example creates a bouncing effect: +\qml +Rectangle { + id: rect + width: 120; height: 200; + Image { + id: img + source: "qt-logo.png" + x: 60-img.width/2 + y: 0 + y: SequentialAnimation { + running: true + repeat: true + NumberAnimation { to: 200-img.height; easing: "easeOutBounce"; duration: 2000 } + PauseAnimation { duration: 1000 } + NumberAnimation { to: 0; easing: "easeOutQuad"; duration: 1000 } + } + } +} +\endqml + +\image propanim.gif + +When you assign an animation as a value source, you do not need to specify \c property +or \c target; they are automatically selected for you. You do, however, need to specify \c to, and explicitly +start the animation (usually via the \c running property). + +\qml +Rectangle { + id: rect + width: 200; height: 200; + Rectangle { + color: "red" + width: 50; height: 50 + x: NumberAnimation { to: 50; running: true } + } +} +\endqml + +A property animation can also be specified as a resource that is manipulated from script. + +\qml +PropertyAnimation { + id: animation + target: image + property: "scale" + from: 1; to: .5 +} +Image { + id: image + source: "image.png" + MouseRegion { + anchors.fill: parent + onPressed: animation.start() + } +} +\endqml + +As can be seen, when an animation is used like this (as opposed to as a value source) you will need +to explicitly set the \c target and \c property to animate. + +Animations can be joined into a group using SequentialAnimation and ParallelAnimation. + +\target state-transitions +\section1 Transitions + +QML transitions describe animations to perform when \l{qmlstates}{state} changes occur. A transition +can only be triggered by a state change. + +For example, a transition could describe how an item moves from its initial position to its new position: + +\code +transitions: [ + Transition { + NumberAnimation { + matchProperties: "x,y" + easing: "easeOutBounce" + duration: 200 + } + } +] +\endcode + +As you can see from the above example, transitions make use of the same basic animation classes introduced +above. However, you generally use a different set of properties when working with transitions. In the example, +no \c target or \c property has been specified. Instead, we have specified \c matchProperties, +which (along with \c matchTargets) acts as a selector to determine which property changes to animate; +in this case, we will animate any x,y properties that have changed on any objects. + +QML transitions also have selectors to determine which state changes a transition should apply to: + +\code +Transition { + from: "*" + to: "details" + ... +} +\endcode + +Transitions can happen in parallel, in sequence, or in any combination of the two. By default, the top-level +animations in a transition will happen in parallel. The following example shows a rather complex transition +making use of both sequential and parallel animations: + +\code +Transition { + from: "*" + to: "MyState" + reversible: true + SequentialAnimation { + ColorAnimation { duration: 1000 } + PauseAnimation { duration: 1000 } + ParallelAnimation { + NumberAnimation { + duration: 1000 + easing: "easeOutBounce" + matchTargets: box1 + matchProperties: "x,y" + } + NumberAnimation { + duration: 1000 + matchTargets: box2 + matchProperties: "x,y" + } + } + } +} +\endcode + +To insert an explicit animation into your transition, you can use \target and \property as normal. + +\code +Transition { + from: "*" + to: "MyState" + reversible: true + SequentialAnimation { + NumberAnimation { + duration: 1000 + easing: "easeOutBounce" + // animate myItem's x and y if they have changed in the state + matchTargets: myItem + matchProperties: "x,y" + } + NumberAnimation { + duration: 1000 + // animate myItem2's y to 200, regardless of what happens in the state + target: myItem2 + property: "y" + to: 200 + } + } +} +\endcode + +\section1 Property Behaviors + +A property behavior specifies a default animation to run whenever the property's value changes, regardless +of what caused the change. Unlike Transition, Behavior doesn't provide a way to indicate that a Behavior +should only apply under certain circumstances. + +In the following snippet, we specify that we want the x position of redRect to be animated +whenever it changes. The animation will last 300 milliseconds and use an InOutQuad easing curve. + +\qml +Rectangle { + id: redRect + color: "red" + width: 100; height: 100 + x: Behavior { NumberAnimation { duration: 300; easing: "InOutQuad" } } +} +\endqml + +Like using an animation as a value source, when used in a Behavior and animation does not need to specify +a \c target or \c property. + +To trigger this behavior, we could: +\list +\o Enter a state that changes x + +\qml +State { + name: "myState" + PropertyChanges { + target: redRect + x: 200 + ... + } +} +\endqml + +\o Update x from a script + +\qml +MouseRegion { + .... + onClicked: redRect.x = 24; +} +\endqml +\endlist + +If x were bound to another property, triggering the binding would also trigger the behavior. + +If a state change has a transition animation matching a property with a Behavior, the transition animation +will override the Behavior for that state change. + +*/ diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc new file mode 100644 index 0000000..0551443 --- /dev/null +++ b/doc/src/declarative/basictypes.qdoc @@ -0,0 +1,257 @@ +/**************************************************************************** +** +** 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 basicqmltypes.html + \title Common QML Types + + QML uses a range of property types, which you will see + referenced throughout the element documentation. Almost all of them are + exactly what you would expect. + + \target basicqmlint + \section1 int + + An integer or \c int is a whole numbers like 0, 10 or -20. The possible \c int + values range from around -2000000000 to around 2000000000, although most + elements will only accept a reduced range (which they mention in their + documentation). + + Example: + \qml + Item { width: 100; height: 200 } + \endqml + + \target basicqmlbool + \section1 bool + + A boolean or \c bool is a binary true/false value. + + Example: + \qml + Item { focus: true; clip: false } + \endqml + + \target basicqmlreal + \section1 real + + A \c real is a number - either a whole number like an \c int, or a fractional number + like 1.2 or -29.8. + + Example: + \qml + Item { width: 100.45; height: 150.82 } + \endqml + + \note In QML all reals are stored in single precision, \l {http://en.wikipedia.org/wiki/IEEE_754}{IEEE floating point} format. + + \target basicqmlstring + \section1 string + + A string is a free form text, like "Hello world!". + + Example: + \qml + Text { text: "Hello world!" } + \endqml + + \target basicqmlurl + \section1 url + + A URL is a resource locator, like a file name. It can be either absolute, like "http://qtsoftware.com", + or relative, like "pics/logo.png". A relative URL is resolved relative to the URL of the component where + the URL is converted from a JavaScript string expression to a url property value. + + Example: + \qml + Image { source: "pics/logo.png" } + \endqml + + \raw HTML + \endraw + + \target basicqmlcolor + \section1 color + + A \c color is most commonly specified as an \l {http://www.w3.org/TR/SVG/types.html#ColorKeywords}{SVG color name}. These names include colors like + "red", "green" and "lightsteelblue". + + If the color you want isn't part of this list, colors can also be specified + in hexidecimal triplets or quads that take the form \c "#RRGGBB" and + \c "#AARRGGBB" respectively. For example, the color red corresponds to a + triplet of \c "#FF0000" and a slightly transparent blue to a quad of + \c "#800000FF". + + Example: + \qml + Rectangle { color: "steelblue" } + Rectangle { color: "#FF0000" } + Rectangle { color: "#800000FF" } + \endqml + + \target basicqmlpoint + \section1 point + + A \c point is specified in \c "x,y" format. + + Example: + \qml + Widget { pos: "0,20" } + \endqml + + \target basicqmlsize + \section1 size + + A \c size is specified in \c "widthxheight" format. + + Example: + \qml + Widget { size: "150x50" } + \endqml + + \target basicqmlrectangle + \section1 rect + + A \c rect is specified in \c "x,y,widthxheight" format. + + Example: + \qml + Widget { geometry: "50,50,100x100" } + \endqml + + \target basicqmldate + \section1 date + + A \c date is specified in \c "YYYY-MM-DD" format. + + Example: + \qml + DatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" } + \endqml + + \target basicqmltime + \section1 time + + A \c time is specified in \c "hh:mm:ss" format. + + Example: + \qml + TimePicker { time: "14:22:15" } + \endqml + + \target basicqmlfont + \section1 font + + The \c font type has the following properties of a QFont: + \list + \o \c string font.family + \o \c bool font.bold + \o \c bool font.italic + \o \c bool font.underline + \o \c real font.pointSize + \o \c int font.pixelSize + \endlist + + Example: + \qml + Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true } + \endqml + + \target basicqmlaction + \section1 action + + The action type has all the properties of QAction, in particular: + \list + \o \c slot action.trigger - invoke the action + \o \c bool action.enabled - true if the action is enabled + \o \c string action.text - the text associated with the action + \endlist + + Actions are used like this: + + \qml + MouseRegion { onClicked: MyItem.myaction.trigger() } + State { name: "enabled"; when: MyItem.myaction.enabled == true } + Text { text: MyItem.someaction.text } + \endqml + + \target basicqmllist + \section1 list + + While not technically a basic type, QML also supports lists of object + types. When used from QML, the engine automatically appends each value to the + list. + + For example, the \l Item class has a children list property + that can be used like this: + \qml + Item { + children: [ + Item { id: child1 }, + Rectangle { id: child2 }, + Text { id: child3 } + ] + } + \endqml + \c Child1, \c Child2 and \c Child3 will all be added to the children list + in the order in which they appear. + + \target basicqmlvector3d + \section1 vector3d + + A \c vector3d is specified in \c "x,y,z" format: + + \qml + Rotation { angle: 60; axis: "0,1,0" } + \endqml + + or with the \c{Qt.vector3d()} helper function: + + \qml + Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) } + \endqml + + or as separate \c x, \c y, and \c z components: + + \qml + Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 } + \endqml +*/ diff --git a/doc/src/declarative/ecmascriptblocks.qdoc b/doc/src/declarative/ecmascriptblocks.qdoc new file mode 100644 index 0000000..815c68c --- /dev/null +++ b/doc/src/declarative/ecmascriptblocks.qdoc @@ -0,0 +1,213 @@ +/**************************************************************************** +** +** 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 qmlecmascript.html +\title ECMAScript Blocks + +QML encourages building UIs declaratively, using \l {Property Binding} and the +composition of existing \l {QML Elements}. If imperative code is required to implement +more advanced behavior, the \l Script element can be used to add ECMAScript code directly +to a QML file, or to include an external ECMAScript file. + +The \l Script element is a QML language \e intrinsic. It can be used anywhere in a +QML file, \e except as the root element of a file or sub-component, but cannot be +assigned to an object property or given an id. The included ECMAScript is evaluated +in a scope chain. The \l {QML Scope} documentation covers the specifics of scoping +in QML. + +\section1 Inline Script + +Small blocks of ECMAScript can be included directly inside a \l {QML Document} as +the body of the \l Script element. + +\code +Rectangle { + Script { + function factorial(var a) { + a = Integer(a); + if (a <= 0) + return 1; + else + return a * factorial(a - 1); + } + } +} +\endcode + +Good programming practice dictates that only small script snippets should be written +inline. QML prohibits the declaration of anything other than functions in an inline +script block. For example, the following script is illegal as an inline script block +as it declares the non-function variable \c lastResult. + +\code +// Illegal inline code block +var lastResult = 0 +function factorial(var a) { + a = Integer(a); + if (a <= 0) + lastResult = 1; + else + lastResult = a * factorial(a - 1); + return lastResult; +} +\endcode + +\section1 Including an External File + +To avoid cluttering the QML file, large script blocks should be in a separate file. +The \l Script element's \c source property is used to load script from an external +file. + +If the previous factorial code that was illegal as an inline script block was saved +into a "factorial.js" file, it could be included like this. + +\code +Rectangle { + Script { + source: "factorial.js" + } +} +\endcode + +The \c source property may reference a relative file, or an absolute path. In the +case of a relative file, the location is resolved relative to the location of the +\l {QML Document} that contains the \l Script element. If the script file is not +accessible, an error will occur. If the source is on a network resource, the +enclosing QML document will remain in the \l {QmlComponent::status()}{waiting state} +until the script has been retrieved. + +\section1 Running Script at Startup + +It is occasionally necessary to run a block of ECMAScript code at application (or +component instance) "startup". While it is tempting to just include the startup +script as \e {global code} in an external script file, this can have sever limitations +as the QML environment may not have been fully established. For example, some objects +might not have been created or some \l {Property Binding}s may not have been run. +\l {QML Script Restrictions} covers the exact limitations of global script code. + +The QML \l Component element provides an \e attached \c onCompleted property that +can be used to trigger the execution of script code at startup after the +QML environment has been completely established. + +The following QML code shows how to use the \c Component::onCompleted property. + +\code +Rectangle { + Script { + function startupFunction() { + // ... startup code + } + } + + Component.onCompleted: startupFunction(); +} +\endcode + +Any element in a QML file - including nested elements and nested QML component +instances - can use this attached property. If there is more than one script to +execute at startup, they are run sequentially in an undefined order. + +\section1 QML Script Restrictions + +QML \l Script blocks contain standard ECMAScript code. QML introduces the following +restrictions. + +\list +\o Script code cannot modify the global object. + +In QML, the global object is constant - existing properties cannot be modified or +deleted, and no new properties may be created. + +Most ECMAScript programs do not explicitly modify the global object. However, +ECMAScript's automatic creation of undeclared variables is an implicit modification +of the global object, and is prohibited in QML. + +Assuming that the \c a variable does not exist in the scope chain, the following code +is illegal in QML. + +\code +// Illegal modification of undeclared variable +a = 1; +for (var ii = 1; ii < 10; ++ii) a = a * ii; +print("Result: " + a); +\endcode + +It can be trivially modified to this legal code. + +\code +var a = 1; +for (var ii = 1; ii < 10; ++ii) a = a * ii; +print("Result: " + a); +\endcode + +Any attempt to modify the global object - either implicitly or explicitly - will +cause an exception. If uncaught, this will result in an warning being printed, +that includes the file and line number of the offending code. + +\o Global code is run in a reduced scope + +During startup, if a \l Script block includes an external file with "global" +code, it is executed in a scope that contains only the external file itself and +the global object. That is, it will not have access to the QML objects and +properties it \l {QML Scope}{normally would}. + +Global code that only accesses script local variable is permitted. This is an +example of valid global code. + +\code +var colors = [ "red", "blue", "green", "orange", "purple" ]; +\endcode + +Global code that accesses QML objects will not run correctly. + +\code +// Invalid global code - the "rootObject" variable is undefined +var initialPosition = { rootObject.x, rootObject.y } +\endcode + +This restriction exists as the QML environment is not yet fully established. +To run code after the environment setup has completed, refer to +\l {Running Script at Startup}. + +\endlist + +*/ diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc new file mode 100644 index 0000000..81a6c96 --- /dev/null +++ b/doc/src/declarative/elements.qdoc @@ -0,0 +1,201 @@ +/**************************************************************************** +** +** 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 qmlelements.html +\target elements +\title QML Elements + +The following table lists the QML elements provided by the Qt Declarative module. + +\bold {Standard Qt Declarative Elements} + +\table 80% +\header +\o \bold {States} +\o \bold {Animation and Transitions} +\o \bold {Working with Data} +\o \bold {Utility} +\row + +\o +\list +\o \l State +\o \l PropertyChanges +\o \l StateGroup +\o \l ParentChange (Item-specific) +\o \l StateChangeScript (Item-specific) +\o \l AnchorChanges (Item-specific) +\endlist + +\o +\list +\o \l PropertyAnimation +\o \l NumberAnimation +\o \l ColorAnimation +\o \l SequentialAnimation +\o \l ParallelAnimation +\o \l PauseAnimation +\o \l PropertyAction +\o \l ParentAction +\o \l ScriptAction +\o \l Transition +\o \l SpringFollow +\o \l EaseFollow +\o \l Behavior +\endlist + +\o +\list +\o \l Binding +\o \l ListModel, \l ListElement +\o \l VisualItemModel +\o \l XmlListModel and XmlRole +\o \l DateTimeFormatter +\o \l NumberFormatter +\endlist + +\o +\list +\o \l Script +\o \l Connection +\o \l Component +\o \l Timer +\endlist +\endtable + +\bold {QML Items} + +\table 80% +\header +\o \bold {Basic Visual Items} +\o \bold {Basic Interaction Items} +\o \bold {Widgets} +\o \bold {Utility} + +\row +\o +\list +\o \l Item +\o \l Rectangle +\o \l Image +\o \l BorderImage +\o \l Text +\o \l TextInput +\o \l TextEdit +\endlist + +\o +\list +\o \l MouseRegion +\o \l FocusScope +\endlist + +\o +\list +\o \l Flickable +\o \l Flipable +\o \l WebView +\endlist + +\o +\list +\o \l Loader +\o \l Repeater +\o \l SystemPalette +\o \l GraphicsObjectContainer +\endlist + +\header +\o \bold {Views} +\o \bold {Positioners} +\o \bold {Transforms} +\o \bold {Effects} + +\row +\o + +\target xmlViews +\list +\o \l ListView +\o \l GridView +\o \l PathView + \list + \o \l Path + \list + \o \l PathLine + \o \l PathQuad + \o \l PathCubic + \o \l PathAttribute + \o \l PathPercent + \endlist + \endlist +\endlist + +\o +\list +\o \l Column +\o \l Row +\o \l Grid +\endlist + +\o +\list +\o \l Scale +\o \l Rotation +\endlist + +\o +\list +\o \l Blur +\o \l Colorize +\o \l DropShadow +\o \l Opacity +\o \l Particles + \list + \o \l ParticleMotionLinear + \o \l ParticleMotionGravity + \o \l ParticleMotionWander + \endlist +\endlist +\endtable + +*/ diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc new file mode 100644 index 0000000..9d66089 --- /dev/null +++ b/doc/src/declarative/examples.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** 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 qmlexamples.html +\title QML Examples and Walkthroughs + +\section1 Running Examples + +A \l {qmlviewer}{viewer} application is included that allows you to quickly explore many of the +examples. It has some useful options, revealed by: + +\code + bin/qmlviewer -help +\endcode + +There are several illustrative QML examples available. From your build +directory, + +\code + bin/qmlviewer $QT_SOURCE_DIR/demos/declarative/flickr/flickr-desktop.qml +\endcode +or +\code + bin/qmlviewer $QT_SOURCE_DIR/demos/declarative/samegame/samegame.qml +\endcode + +Many other simple examples can be found under the \c examples/declarative sub +directory. Some can be run directly using the viewer like those above, and +others require you to build and run an executable. More sophisticated demos of +large applications can be found under the \c demos/declarative sub directory. +These are intended to show more integrated functionality rather than to be +instructive on specific elements. + +\section1 Examples + +These will be documented, and demonstrate how to achieve various things in QML. + +\raw HTML +<center> +<table cellspacing="10"> +<tr> +<td> +\endraw +\image dial-example.gif +\raw HTML +</td> +<td> +\endraw +\image switch-example.gif +\raw HTML +</td> +<td> +\endraw +\image declarative-adv-tutorial4.gif +\raw HTML +</td> +</tr> +<tr> +<td> +<center>Elastic Dial</center> +</td> +<td> +<center>Touch Toggle Switch</center> +</td> +<td> +<center>Samegame</center> +</td> +</table> +</center> +\endraw + +*/ diff --git a/doc/src/declarative/extending-examples.qdoc b/doc/src/declarative/extending-examples.qdoc new file mode 100644 index 0000000..17bef4e --- /dev/null +++ b/doc/src/declarative/extending-examples.qdoc @@ -0,0 +1,309 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\example declarative/extending/adding +\title Extending QML - Adding Types Example + +The Adding Types Example shows how to add a new element type, \c Person, to QML. +The \c Person type can be used from QML like this: + +\snippet examples/declarative/extending/adding/example.qml 0 + +\section1 Declare the Person class + +All QML elements map to C++ types. Here we declare a basic C++ Person class +with the two properties we want accessible on the QML type - name and shoeSize. +Although in this example we use the same name for the C++ class as the QML +element, the C++ class can be named differently, or appear in a namespace. + +\snippet examples/declarative/extending/adding/person.h 0 + +Following the class declaration, we include the QML_DECLARE_TYPE() macro. This +is necessary to declare the type to QML. It also includes the logic necessary +to expose the class to Qt's meta system - that is, it includes the +Q_DECLARE_METATYPE() functionality. + +\section1 Define the Person class + +\snippet examples/declarative/extending/adding/person.cpp 0 + +The Person class implementation is quite basic. The property accessors simply +return members of the object instance. + +The implementation must also include the QML_DEFINE_TYPE() macro. This macro +registers the Person class with QML as a type in the People library version 1.0, +and defines the mapping between the C++ and QML class names. + +\section1 Running the example + +The main.cpp file in the example includes a simple shell application that +loads and runs the QML snippet shown at the beginning of this page. +*/ + +/*! +\example declarative/extending/properties +\title Extending QML - Object and List Property Types Example + +This example builds on: +\list +\o \l {Extending QML - Adding Types Example} +\endlist + +The Object and List Property Types example shows how to add object and list +properties in QML. This example adds a BirthdayParty element that specifies +a birthday party, consisting of a celebrant and a list of guests. People are +specified using the People QML type built in the previous example. + +\snippet examples/declarative/extending/properties/example.qml 0 + +\section1 Declare the BirthdayParty + +The BirthdayParty class is declared like this: + +\snippet examples/declarative/extending/properties/birthdayparty.h 0 +\snippet examples/declarative/extending/properties/birthdayparty.h 1 +\snippet examples/declarative/extending/properties/birthdayparty.h 2 +\snippet examples/declarative/extending/properties/birthdayparty.h 3 + +The class contains a member to store the celebrant object, and also a +QmlConcreteList<Person *> member. + +In QML, the type of a list properties - and the guests property is a list of +people - are all of type QmlList<T *>*. QmlList is an abstract list interface +that allows a developer to react to QML accessing and modifying the contents of +the list. This is useful for implementing "virtual lists" or other advanced +scenarios, but can't be used directly for the common case of just wanting a +regular list of things. For this a concrete implementation, QmlConcreteList, is +provided and that is used here. + +\section2 Define the BirthdayParty + +The implementation of BirthdayParty property accessors is straight forward. + +\snippet examples/declarative/extending/properties/birthdayparty.cpp 0 + +\section1 Running the example + +The main.cpp file in the example includes a simple shell application that +loads and runs the QML snippet shown at the beginning of this page. +*/ + +/*! +\example declarative/extending/coercion +\title Extending QML - Inheritance and Coercion Example + +This example builds on: +\list +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +The Inheritance and Coercion Example shows how to use base classes to assign +elements of more than one type to a property. It specializes the Person element +developed in the previous examples into two elements - a \c Boy and a \c Girl. + +\snippet examples/declarative/extending/coercion/example.qml 0 + +\section1 Declare Boy and Girl + +\snippet examples/declarative/extending/coercion/person.h 0 + +The Person class remains unaltered in this example and the Boy and Girl C++ +classes are trivial extensions of it. As an example, the inheritance used here +is a little contrived, but in real applications it is likely that the two +extensions would add additional properties or modify the Person classes +behavior. + +\section2 Define People as a base class + +The implementation of the People class itself has not changed since the the +previous example. However, as we have repurposed the People class as a common +base for Boy and Girl, we want to prevent it from being instantiated from QML +directly - an explicit Boy or Girl should be instantiated instead. + +\snippet examples/declarative/extending/coercion/person.cpp 0 + +While we want to disallow instantiating Person from within QML, it still needs +to be registered with the QML engine, so that it can be used as a property type +and other types can be coerced to it. To register a type, without defining a +named mapping into QML, we use the QML_DEFINE_NOCREATE_TYPE() macro instead of +the QML_DEFINE_TYPE() macro used previously. + +\section2 Define Boy and Girl + +The implementation of Boy and Girl are trivial. + +\snippet examples/declarative/extending/coercion/person.cpp 1 + +All that is necessary is to implement the constructor, and to register the types +and their QML name with the QML engine. + +\section1 Running the example + +The BirthdayParty element has not changed since the previous example. The +celebrant and guests property still use the People type. + +\snippet examples/declarative/extending/coercion/birthdayparty.h 0 + +However, as all three types, Person, Boy and Girl, have been registered with the +QML system, on assignment QML automatically (and type-safely) converts the Boy +and Girl objects into a Person. + +The main.cpp file in the example includes a simple shell application that +loads and runs the QML snippet shown at the beginning of this page. +*/ + +/*! +\example declarative/extending/default +\title Extending QML - Default Property Example + +This example builds on: +\list +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +The Default Property Example is a minor modification of the +\l {Extending QML - Inheritance and Coercion Example} that simplifies the +specification of a BirthdayParty through the use of a default property. + +\snippet examples/declarative/extending/default/example.qml 0 + +\section1 Declaring the BirthdayParty class + +The only difference between this example and the last, is the addition of the +\c DefaultProperty class info annotation. + +\snippet examples/declarative/extending/default/birthdayparty.h 0 + +The default property specifies the property to assign to whenever an explicit +property is not specified, in the case of the BirthdayParty element the guest +property. It is purely a syntactic simplification, the behavior is identical +to specifying the property by name, but it can add a more natural feel in many +situations. The default property must be either an object or list property. + +\section1 Running the example + +The main.cpp file in the example includes a simple shell application that +loads and runs the QML snippet shown at the beginning of this page. +*/ + +/*! +\example declarative/extending/grouped +\title Extending QML - Grouped Properties Example + +This example builds on: +\list +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/extending/grouped +\title Extending QML - Attached Properties Example + +This example builds on: +\list +\o \l {Extending QML - Grouped Properties Example} +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/extending/signal +\title Extending QML - Signal Support Example + +This example builds on: +\list +\o \l {Extending QML - Attached Properties Example} +\o \l {Extending QML - Grouped Properties Example} +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/extending/valuesource +\title Extending QML - Property Value Source Example + +This example builds on: +\list +\o \l {Extending QML - Signal Support Example} +\o \l {Extending QML - Attached Properties Example} +\o \l {Extending QML - Grouped Properties Example} +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/extending/binding +\title Extending QML - Binding Example + +This example builds on: +\list +\o \l {Extending QML - Property Value Source Example} +\o \l {Extending QML - Signal Support Example} +\o \l {Extending QML - Attached Properties Example} +\o \l {Extending QML - Grouped Properties Example} +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc new file mode 100644 index 0000000..7a9de60 --- /dev/null +++ b/doc/src/declarative/extending.qdoc @@ -0,0 +1,950 @@ +/**************************************************************************** +** +** 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 qml-extending.html +\title Extending QML + +The QML syntax declaratively describes how to construct an in memory object +tree. In Qt, QML is mainly used to describe a visual scene graph, but it is +not conceptually limited to this: the QML format is an abstract description of +any object tree. All the QML element types included in Qt are implemented using +the C++ extension mechanisms describe on this page. Programmers can use these +APIs to add new types that interact with the existing Qt types, or to repurpose +QML for their own independent use. + +\tableofcontents + +\section1 Adding Types + +\snippet examples/declarative/extending/adding/example.qml 0 + +The QML snippet shown above instantiates one \c Person instance and sets +the name and shoeSize properties on it. Everything in QML ultimately comes down +to either instantiating an object instance, or assigning a property a value. +QML relies heavily on Qt's meta object system and can only instantiate classes +that derive from QObject. + +The QML engine has no intrinsic knowledge of any class types. Instead the +programmer must define the C++ types, and their corresponding QML name. + +Custom C++ types are made available to QML using these two macros: + +\quotation +\code +#define QML_DECLARE_TYPE(T) +#define QML_DEFINE_TYPE(URI,VMAJ,VFROM,VTO,QmlName,T) +\endcode + +Register the C++ type \a T with the QML system, and make it available in QML +under the name \a QmlName in library URI version VMAJ.VFROM to VMAJ.VTO. +\a T and \a QmlName may be the same. + +Generally the QML_DECLARE_TYPE() macro should be included immediately following +the type declaration (usually in its header file), and the QML_DEFINE_TYPE() +macro in the implementation file. QML_DEFINE_TYPE() must not be present in +a header file. + +Type \a T must be a concrete type that inherits QObject and has a default +constructor. +\endquotation + +Once registered, all of the \l {Qt's Property System}{properties} of a supported +type are available for use within QML. QML has intrinsic support for properties +of these types: + +\list +\o bool +\o unsigned int, int +\o float, double, qreal +\o QString +\o QUrl +\o QColor +\o QDate, QTime, QDateTime +\o QPoint, QPointF +\o QSize, QSizeF +\o QRect, QRectF +\o QVariant +\endlist + +QML is typesafe. Attempting to assign an invalid value to a property will +generate an error. For example, assuming the name property of the \c Person +element had a type of QString, this would cause an error: + +\code +Person { + // Will NOT work + name: 12 +} +\endcode + +\l {Extending QML - Adding Types Example} shows the complete code used to create +the \c Person type. + +\section1 Object and List Property Types + +\snippet examples/declarative/extending/properties/example.qml 0 + +The QML snippet shown above assigns a \c Person object to the \c BirthdayParty's +celebrant property, and assigns three \c Person objects to the guests property. + +QML can set properties of types that are more complex than basic intrinsics like +integers and strings. Properties can also be object pointers, Qt interface +pointers, lists of object points, and lists of Qt interface pointers. As QML +is typesafe it ensures that only valid types are assigned to these properties, +just like it does for primitive types. + +Properties that are pointers to objects or Qt interfaces are declared with the +Q_PROPERTY() macro, just like other properties. The celebrant property +declaration looks like this: + +\snippet examples/declarative/extending/properties/birthdayparty.h 1 + +As long as the property type, in this case Person, is registered with QML the +property can be assigned. + +QML also supports assigning Qt interfaces. To assign to a property whose type +is a Qt interface pointer, the interface must also be registered with QML. As +they cannot be instantiated directly, registering a Qt interface is different +from registering a new QML type. The following macros are used instead: + +\quotation +\code + #define QML_DECLARE_INTERFACE(T) + #define QML_DEFINE_INTERFACE(T) +\endcode + +Register the C++ interface \a T with the QML system. + +Generally the QML_DECLARE_INTERFACE() macro should be included immediately +following the interface declaration (usually in its header file), and the +QML_DEFINE_INTERFACE() macro in an implementation file. QML_DEFINE_INTERFACE() +must not be present in a header file. + +Following registration, QML can coerce objects that implement this interface +for assignment to appropriately typed properties. +\endquotation + +The guests property is a list of \c Person objects. Properties that are lists +of objects or Qt interfaces are also declared with the Q_PROPERTY() macro, just +like other properties. List properties must have the type \c {QmlList<T *>*}. +As with object properties, the type \a T must be registered with QML. + +The guest property declaration looks like this: + +\snippet examples/declarative/extending/properties/birthdayparty.h 2 + +\l {Extending QML - Object and List Property Types Example} shows the complete +code used to create the \c BirthdayParty type. + +\section1 Inheritance and Coercion + +\snippet examples/declarative/extending/coercion/example.qml 0 + +The QML snippet shown above assigns a \c Boy object to the \c BirthdayParty's +celebrant property, and assigns three other objects to the guests property. + +QML supports C++ inheritance heirarchies and can freely coerce between known, +valid object types. This enables the creation of common base classes that allow +the assignment of specialized classes to object or list properties. In the +snippet shown, both the celebrant and the guests properties retain the Person +type used in the previous section, but the assignment is valid as both the Boy +and Girl objects inherit from Person. + +To assign to a property, the property's type must have been registered with QML. +Both the QML_DEFINE_TYPE() and QML_DEFINE_INTERFACE() macros already shown can +be used to register a type with QML. Additionally, if a type that acts purely +as a base class that cannot be instantiated from QML needs to be +registered these macros can be used: + +\quotation +\code + #define QML_DECLARE_TYPE(T) + #define QML_DEFINE_NOCREATE_TYPE(T) +\endcode + +Register the C++ type \a T with the QML system. QML_DEFINE_NOCREATE_TYPE() +differs from QML_DEFINE_TYPE() in that it does not define a mapping between the +C++ class and a QML element name, so the type is not instantiable from QML, but +it is available for type coercion. + +Generally the QML_DECLARE_TYPE() macro should be included immediately following +the type declaration (usually in its header file), and the +QML_DEFINE_NOCREATE_TYPE() macro in the implementation file. +QML_DEFINE_NOCREATE_TYPE() must not be present in a header file. + +Type \a T must inherit QObject, but there are no restrictions on whether it is +concrete or the signature of its constructor. +\endquotation + +QML will automatically coerce C++ types when assigning to either an object +property, or to a list property. Only if coercion fails does an assignment +error occur. + +\l {Extending QML - Inheritance and Coercion Example} shows the complete +code used to create the \c Boy and \c Girl types. + +\section1 Default Property + +\snippet examples/declarative/extending/default/example.qml 0 + +The QML snippet shown above assigns a collection of objects to the +\c BirthdayParty's default property. + +The default property is a syntactic convenience that allows a type designer to +specify a single property as the type's default. The default property is +assigned to whenever no explicit property is specified. As a convenience, it is +behaviorally identical to assigning the default property explicitly by name. + +From C++, type designers mark the default property using a Q_CLASSINFO() +annotation: + +\quotation +\code +Q_CLASSINFO("DefaultProperty", "property") +\endcode + +Mark \a property as the class's default property. \a property must be either +an object property, or a list property. + +A default property is optional. A derived class inherits its base class's +default property, but may override it in its own declaration. \a property can +refer to a property declared in the class itself, or a property inherited from a +base class. +\endquotation + +\l {Extending QML - Default Property Example} shows the complete code used to +specify a default property. + +\section1 Grouped Properties + +\snippet examples/declarative/extending/grouped/example.qml 1 + +The QML snippet shown above assigns a number properties to the \c Boy object, +including four properties using the grouped property syntax. + +Grouped properties collect similar properties together into a single named +block. Grouped properties can be used to present a nicer API to developers, and +may also simplify the implementation of common property collections across +different types through implementation reuse. + +A grouped property block is implemented as a read-only object property. The +shoe property shown is declared like this: + +\snippet examples/declarative/extending/grouped/person.h 1 + +The ShoeDescription type declares the properties available to the grouped +property block - in this case the size, color, brand and price properties. + +Grouped property blocks may declared and accessed be recusively. + +\l {Extending QML - Grouped Properties Example} shows the complete code used to +implement the \c shoe property grouping. + +\section1 Attached Properties + +\snippet examples/declarative/extending/attached/example.qml 1 + +The QML snippet shown above assigns the rsvp property using the attached +property syntax. + +Attached properties allow unrelated types to annotate other types with some +additional properties, generally for their own use. Attached properties are +identified through the use of the attacher type name, in the case shown +\c BirthdayParty, as a suffix to the property name. + +In the example shown, \c BirthdayParty is called the attaching type, and the +Box instance the attachee object instance. + +For the attaching type, an attached property block is implemented as a new +QObject derived type, called the attachment object. The properties on the +attachment object are those that become available for use as the attached +property block. + +Any QML type can become an attaching type by declaring the +\c qmlAttachedProperties() public function and declaring that the class has +QML_HAS_ATTACHED_PROPERTIES: + +\quotation +\code +class MyType : public QObject { + Q_OBJECT +public: + + ... + + static AttachedPropertiesType *qmlAttachedProperties(QObject *object); +}; + +QML_DECLARE_TYPEINFO(MyType, QML_HAS_ATTACHED_PROPERTIES) +QML_DECLARE_TYPE(MyType) +\endcode +Return an attachment object, of type \a AttachedPropertiesType, for the +attachee \a object instance. It is customary, though not strictly required, for +the attachment object to be parented to \a object to prevent memory leaks. + +\a AttachedPropertiesType must be a QObject derived type. The properties on +this type will be accessible through the attached properties syntax. + +This method will be called at most once for each attachee object instance. The +QML engine will cache the returned instance pointer for subsequent attached +property accesses. Consequently the attachment object may not be deleted until +\a object is destroyed. +\endquotation + +Conceptually, attached properties are a \e type exporting a set of additional +properties that can be set on \e any other object instance. Attached properties +cannot be limited to only attaching to a sub-set of object instances, although +their effect may be so limited. + +For example, a common usage scenario is for a type to enhance the properties +available to its children in order to gather instance specific data. Here we +add a rsvp field to all the guests coming to a birthday party: +\code +BirthdayParty { + Boy { BirthdayParty.rsvp: "2009-06-01" } +} +\endcode +However, as a type cannot limit the instances to which the attachment object +must attach, the following is also allowed, even though adding a birthday party +rsvp in this context will have no effect. +\code +GraduationParty { + Boy { BirthdayParty.rsvp: "2009-06-01" } +} +\endcode + +From C++, including the attaching type implementation, the attachment object for +an instance can be accessed using the following method: + +\quotation +\code +template<typename T> +QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true); +\endcode +Returns the attachment object attached to \a attachee by the attaching type +\a T. If type \a T is not a valid attaching type, this method always returns 0. + +If \a create is true, a valid attachment object will always be returned, +creating it if it does not already exist. If \a create is false, the attachment +object will only be returned if it has previously been created. +\endquotation + +\l {Extending QML - Attached Properties Example} shows the complete code used to +implement the rsvp attached property. + +\section1 Signal Support + +\snippet examples/declarative/extending/signal/example.qml 0 +\snippet examples/declarative/extending/signal/example.qml 1 + +The QML snippet shown above associates the evaluation of a ECMAScript expression +with the emission of a Qt signal. + +All Qt signals on a registered class become available as special "signal +properties" within QML to which the user can assign a single ECMAScript +expression. The signal property's name is a transformed version of the Qt +signal name: "on" is prepended, and the first letter of the signal name upper +cased. For example, the signal used in the example above has the following +C++ signature: + +\snippet examples/declarative/extending/signal/birthdayparty.h 0 + +In classes with multiple signals with the same name, only the final signal +is accessible as a signal property. Although QML provides an element, +\l Connection, for accessing the other signals it is less elegant. For the best +QML API, class developers should avoid overloading signal names. + +Signal parameters become accessible by name to the assigned script. An +unnamed parameter cannot be accessed, so care should be taken to name all the +signal parameters in the C++ class declaration. The intrinsic types +listed in \l {Adding Types}, as well registered object types are permitted as +signal parameter types. Using other types is not an error, but the parameter +value will not be accessible from script. + +\l {Extending QML - Signal Support Example} shows the complete code used to +implement the onPartyStarted signal property. + +\section1 Property Value Sources + +\snippet examples/declarative/extending/valuesource/example.qml 0 +\snippet examples/declarative/extending/valuesource/example.qml 1 + +The QML snippet shown above assigns a property value to the speaker property. +A property value source generates a value for a property that changes over time. + +Property value sources are most commonly used to do animation. Rather than +constructing an animation object and manually setting the animation's "target" +property, a property value source can be assigned directly to a property of any +type and automatically set up this association. + +The example shown here is rather contrived: the speaker property of the +BirthdayParty object is a string that is printed every time it is assigned and +the HappyBirthday value source generates the lyrics of the song +"Happy Birthday". + +\snippet examples/declarative/extending/valuesource/birthdayparty.h 0 + +Normally, assigning an object to a string property would not be allowed. In +the case of a property value source, rather than assigning the object instance +itself, the QML engine sets up an association between the value source and +the property. + +Property value sources are special types that derive from the +QmlPropertyValueSource base class. This base class contains a single method, +QmlPropertyValueSource::setTarget(), that the QML engine invokes when +associating the property value source with a property. The relevant part of +the HappyBirthday type declaration looks like this: + +\snippet examples/declarative/extending/valuesource/happybirthday.h 0 +\snippet examples/declarative/extending/valuesource/happybirthday.h 1 +\snippet examples/declarative/extending/valuesource/happybirthday.h 2 + +In all other respects, property value sources are regular QML types. They must +be registered with the QML engine using the same macros as other types, and can +contain properties, signals and methods just like other types. + +When a property value source object is assigned to a property, QML first tries +to assign it normally, as though it were a regular QML type. Only if this +assignment fails does the engine call the setTarget() method. This allows +the type to also be used in contexts other than just as a value source. + +\l {Extending QML - Property Value Source Example} shows the complete code used +implement the HappyBirthday property value source. + +\section1 Property Binding + +\snippet examples/declarative/extending/binding/example.qml 0 +\snippet examples/declarative/extending/binding/example.qml 1 + +The QML snippet shown above uses a property binding to ensure the +HappyBirthday's name property remains up to date with the celebrant. + +Property binding is a core feature of QML. In addition to assigning literal +values, property bindings allow the developer to assign an arbitrarily complex +ECMAScript expression that may include dependencies on other property values. +Whenever the expression's result changes - through a change in one of its +constituent values - the expression is automatically reevaluated and +the new result assigned to the property. + +All properties on custom types automatically support property binding. However, +for binding to work correctly, QML must be able to reliably determine when a +property has changed so that it knows to reevaluate any bindings that depend on +the property's value. QML relies on the presence of a +\c {Qt's Property System}{NOTIFY signal} for this determination. + +Here is the celebrant property declaration: + +\snippet examples/declarative/extending/binding/birthdayparty.h 0 + +The NOTIFY attribute is followed by a signal name. It is the responsibility of +the class implementer to ensure that whenever the property's value changes, the +NOTIFY signal is emitted. The signature of the NOTIFY signal is not important to QML. + +To prevent loops or excessive evaluation, developers should ensure that the +signal is only emitted whenever the property's value is actually changed. If +a property, or group of properties, is infrequently used it is permitted to use +the same NOTIFY signal for several properties. This should be done with care to +ensure that performance doesn't suffer. + +To keep QML reliable, if a property does not have a NOTIFY signal, it cannot be +used in a binding expression. However, the property can still be assigned +a binding as QML does not need to monitor the property for change in that +scenario. + +Consider a custom type, \c TestElement, that has two properties, "a" and "b". +Property "a" does not have a NOTIFY signal, and property "b" does have a NOTIFY +signal. + +\code +TestElement { + // This is OK + a: b +} +TestElement { + // Will NOT work + b: a +} +\endcode + +The presence of a NOTIFY signal does incur a small overhead. There are cases +where a property's value is set at object construction time, and does not +subsequently change. The most common case of this is when a type uses +\l {Grouped Properties}, and the grouped property object is allocated once, and +only freed when the object is deleted. In these cases, the CONSTANT attribute +may be added to the property declaration instead of a NOTIFY signal. + +\snippet examples/declarative/extending/binding/person.h 0 + +Extreme care must be taken here or applications using your type may misbehave. +The CONSTANT attribute should only be used for properties whose value is set, +and finalized, only in the class constructor. All other properties that want +to be used in bindings should have a NOTIFY signal instead. + +\l {Extending QML - Binding Example} shows the BirthdayParty example updated to +include NOTIFY signals for use in binding. + +\section1 Binding and Script Properties + +While generally no changes are needed to a C++ class to use property +binding, sometimes more advanced interaction between the binding engine and +an object is desirable. To facilitate this, there is a special exception +in the bind engine for allowing an object to access the binding directly. + +If a binding is assigned to a property with a type of QmlBinding +pointer (ie. \c {QmlBinding *}), each time the binding value changes, +a QmlBinding instance is assigned to that property. The QmlBinding instance +allows the object to read the binding and to evaluate the binding's current value. + +\section1 Extension Objects + +\snippet examples/declarative/extending/extended/example.qml 0 + +The QML snippet shown above adds a new property to an existing C++ type without +modifying its source code. + +When integrating existing classes and technology into QML, their APIs will often +need to be tweaked to fit better into the declarative environment. Although +the best results are usually obtained by modifying the original classes +directly, if this is either not possible or is complicated by some other +concerns, extension objects allow limited extension possibilities without +direct modifications. + +Extension objects are used to add additional properties to an existing type. +Extension objects can only add properties, not signals or methods. An extended +type definition allows the programmer to supply an additional type - known as the +extension type - when registering the target class whose properties are +transparently merged with the original target class when used from within QML. + +An extension class is a regular QObject, with a constructor that takes a QObject +pointer. When needed (extension classes are delay created until the first extended +property is accessed) the extension class is created and the target object is +passed in as the parent. When an extended property on the original is accessed, +the appropriate property on the extension object is used instead. + +When an extended type is installed, one of the +\code + #define QML_DEFINE_EXTENDED_TYPE(URI, VMAJ, VFROM, VTO, QmlName,T, ExtendedT) + #define QML_DEFINE_EXTENDED_NOCREATE_TYPE(T, ExtendedT) +\endcode +macros should be used instead of the regular \c QML_DEFINE_TYPE or +\c QML_DEFINE_NOCREATE_TYPE. The arguments are identical to the corresponding +non-extension object macro, except for the ExtendedT parameter which is the type +of the extension object. + +\section1 Optimization + +Often to develop high performance elements it is helpful to know more about the +status of the QML engine. For example, it might be beneficial to delay +initializing some costly data structures until after all the properties have been +set. + +The QML engine defines an interface class called QmlParserStatus, which contains a +number of virtual methods that are invoked at various stages during component +instantiation. To receive these notifications, an element implementation inherits +QmlParserStatus and notifies the Qt meta system using the Q_INTERFACES() macro. + +For example, + +\code +class Example : public QObject, public QmlParserStatus +{ + Q_OBJECT + Q_INTERFACES(QmlParserStatus) +public: + virtual void componentComplete() + { + qDebug() << "Woohoo! Now to do my costly initialization"; + } +}; +\endcode + +*/ + +/*! +\page qml-extending-types.html +\title Extending types from QML + +Many of the elements available for use in QML are implemented in +\l {Extending QML}{C++}. These types are know as "core types". QML +allows programmers to build new, fully functional elements without using C++. +Existing core types can be extended, and new types defined entirely in the QML +language. + +\tableofcontents + +\section1 Adding new properties + +New properties can be added to an existing type. These new properties are +available for use within QML, and also appear as regular Qt properties on the +C++ object, accessible through the regular property access mechanisms. + +Like all properties in QML, custom properties are typed. The type is used to +define the property's behavior, and also determines the C++ type of the created +Qt property. The following table shows the list of types available when +declaring a new property, and the corresponding C++ type. + +\table +\header \o QML Type Name \o C++ Type Name +\row \o int \o int +\row \o bool \o bool +\row \o double \o double +\row \o real \o double +\row \o string \o QString +\row \o url \o QUrl +\row \o color \o QColor +\row \o date \o QDate +\row \o var \o QVariant +\row \o variant \o QVariant +\endtable + +QML supports two methods for adding a new property to a type - a new property +definition, and a property alias. + +\section2 Property definitions + +Property definitions add a new property to an existing type. The storage of the +property is managed by QML. The defined property may be read, written and bound +to and from. + +The syntax for defining a new property is: +\code + [default] property <type> <name>[: defaultValue] +\endcode + +This declaration may appear anywhere within a type body, but it is customary to +include it at the top. Attempting to declare two properties with the same name +in the same type block is an error. However, a new property may reuse the name +of an existing property on the type. This should be done with caution, as the +existing property will be hidden, and become inaccessible. + +The <type> must be one of the QML type names shown in the above table. +Additionally, an optional default value of the property can be provided. The +default value is a convenient shortcut, but is behaviorally identical to doing +it in two steps, like this: + +\code + // Use default value + property int myProperty: 10 + + // Longer, but behaviorally identical + property int myProperty + myProperty: 10 +\endcode + +If specified, the optional "default" attribute marks the new property as the +types default property, overriding any existing default property. Using the +default attribute twice in the same type block is an error. + +The following example shows how to declare a new "innerColor" property that +controls the color of the inner rectangle. + +\code + Rectangle { + property color innerColor: "black" + + color: "red"; width: 100; height: 100 + Rectangle { + anchors.centerIn: parent + width: parent.width - 10 + height: parent.height - 10 + color: innerColor + } + } +\endcode + +\section2 Property aliases + +Property aliases are a more advanced form of property declaration. Unlike a +property definition, that allocates a new, unique storage space for the +property, a property alias connects the newly declared property (called the +aliasing property) to an existing property (the aliased property). Read +operations on the aliasing property act as read operations on the aliased +property, and write operations on the aliasing property as write operations on +the aliased property. + +A property alias declaration looks a lot like a property definition: +\code + [default] property alias <name>: <alias reference> +\endcode + +As the aliasing property has the same type as the aliased property, an explicit +type is omitted, and the special "alias" keyword is used. Instead of a default +value, a property alias includes a compulsary alias reference. The alias +reference is used to locate the aliased property. While similar to a property +binding, the alias reference syntax is highly restricted. + +An alias reference takes one of the following forms +\code + <Id>.<property> + <Id> +\endcode +where <Id> must refer to an object id within the same component as the type +declaring the alias, and, optionally, <property> refers to a property on that object. + +Here is the property definition example rewritten to use property aliases. +\code +Rectangle { + property alias innerColor: innerRect.color + + color: "red"; width: 100; height: 100 + Rectangle { + id: innerRect + anchors.centerIn: parent + width: parent.width - 10 + height: parent.height - 10 + color: "black" + } +} +\endcode + +Aliases are most useful when \l {Defining new Components}. Consequently +they have several apparent limitations that only make sense in this context. + +Aliases are only activated once the component specifying them is completed. The +most obvious consequence of this is that the component itself cannot generally +use the aliased property directly. For example, this will not work: + +\code + // Does NOT work + property alias innerColor: innerRect.color + innerColor: "black" +\endcode + +This behavior is required to allow type developers to redefine the behavior +of existing property names while continuing to use the existing behavior within +the type they are building, something that is not possible with property +definitions. In the example used so far, this could allows the developer to fix +the external rectangle's color as "red" and redefine the "color" property to +refer to the inner rectangle, like this: + +\code +Rectangle { + property alias color: innerRect.color + + color: "red"; width: 100; height: 100 + Rectangle { + id: innerRect + anchors.centerIn: parent + width: parent.width - 10 + height: parent.height - 10 + color: "black" + } +} +\endcode + +Users of this type would not be able to affect the color of the red rectangle, +but would find using the "color" property, rather than the strange new +"innerColor" property, much more familiar. + +A second, much less significant, consequence of the delayed activation of +aliases is that an alias reference cannot refer to another aliasing property +declared within the same component. This will not work: + +\code + // Does NOT work + id: root + property alias innerColor: innerRect.color + property alias innerColor2: root.innerColor +\endcode + +From outside the component, aliasing properties appear as regular Qt properties +and consequently can be used in alias references. + +\section1 Adding new signals + +New signals can be added to an existing type. These new signals are available +for use within QML, and also appear as regular Qt signals on the C++ object that +can be used in Qt signal/slot connections. + +The syntax for defining a new signal is: +\code +signal <name>[([<type> <parameter name>[, ...]])] +\endcode + +This declaration may appear anywhere within a type body, but it is customary to +include it at the top. Attempting to declare two signals or methods with the +same name in the same type block is an error. However, a new signal may reuse +the name of an existing signal on the type. This should be done with caution, +as the existing signal may be hidden and become inaccessible. + +The options for parameter types are the same as for property types (see +\l {Adding new properties}. If this signal has no parameters, the parameter +list may be omitted entirely. + +Here are three examples of signal declarations: +\code + Item { + signal clicked + signal hovered() + signal performAction(string action, var actionArgument) + } +\endcode + +\section1 Adding new methods + +New methods can be added to an existing type. These new methods are available +for use within QML, and also appear as regular Qt slots on the C++ object that +can be used in Qt signal/slot connections. + +\code +function <name>([<parameter name>[, ...]]) { <body> } +\endcode + +This declaration may appear anywhere within a type body, but it is customary to +include it at the top. Attempting to declare two methods or signals with the +same name in the same type block is an error. However, a new method may reuse +the name of an existing method on the type. This should be done with caution, +as the existing method may be hidden and become inaccessible. + +Methods parameters are not typed. In C++ these parameters are of type QVariant. +The body of the method is written in JavaScript and may access the parameters by +name. + +This example adds a new method that behaves like a child: +\code +Item { + function say(text) { + print("You said " + text); + } +} +\endcode + +\section1 Defining new Components +\target components + +A component is a reusable type with a well-defined interface built entirely in +QML. Components appear as regular QML elements, and can be used interchangably +with core types. Components allow developers to create new types to be reused +in other projects without the use of C++. Components can also help to reduce +duplication inside one project by limiting the need for large numbers of +copy-and-pasted blocks. + +Any snippet of QML code can become a component, just by placing it in the file +"<Name>.qml" where <Name> is the new element name, and begins with an uppercase +letter. These QML files automatically become available as new QML element types +to other QML components and applications in the same directory. + +For example, here we show how a component named "Box" is defined and used +multiple times by an application. + +\table +\row +\o application.qml +\code +Rectangle { + width: 100; height: 400; + Box { x: 0; y: 0 } + Box { x: 0; y: 150 } + Box { x: 0; y: 300 } +} +\endcode +\o Box.qml +\code +Rectangle { + width: 100; height: 100; + color: "blue" +} +\endcode +\endtable + +Components may be collected into \l {Modules} that gives the +developer more freedom than just putting files in the same directory. + +\section2 Building reusable components + +A component type built to be reused by others must have a well defined +interface. In QML, an interface consists of a defined collection of +properties, signals and methods. Users of a component have access to all the +properties, signals and methods defined on the root element of the component. + +In the component example above, the root element of the "Box" component is a +Rect. As the Rect type has a "color" property, this property is accessible to +users of the Box component. For example, the application.qml can be modified +to show three different colored boxes like this: +\code +Rectangle { + width: 100; height: 400; + Box { x: 0; y: 0; color: "red"; } + Box { x: 0; y: 150; color: "yellow"; } + Box { x: 0; y: 300; color: "green"; } +} +\endcode + +As expected, adding additional properties to the root element of Box, makes them +available externally. Here we add a "text" property: + +\table +\row +\o application.qml +\code +Rectangle { + width: 100; height: 400; + Box { x: 0; y: 0; color: "red"; text: "stop" } + Box { x: 0; y: 150; color: "yellow"; text: "slow" } + Box { x: 0; y: 300; color: "green"; text: "go" } +} +\endcode +\o Box.qml +\code +Rectangle { + property alias text: myText.text + width: 100; height: 100; + color: "blue" + Text { + id: myText + anchors.centerIn: parent + } +} +\endcode +\endtable + +Methods and signals may be added in the same way. + +As all external methods, signals and properties are accessible to external +users, developers should ensure that setting these properties does not have +any undesirable side-effects. For most resiliance, root level properties should +only be used for literal default values. When a root level property must be +used inside the component - such as the children property - property aliases +can be used to redirect this property to a "safe" location for external users. +Try to think of the root level properties as being "owned" by the components +user, rather than the component itself. +*/ diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc new file mode 100644 index 0000000..8061a7c --- /dev/null +++ b/doc/src/declarative/focus.qdoc @@ -0,0 +1,338 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\target qmlfocus +\page qmlfocus.html +\title Keyboard Focus in QML + +When a key is pressed or released, a key event is generated and delivered to the +focused QML \l Item. To facilitate the construction of reusable components +and to address some of the cases unique to fluid user interfaces, the QML items add a +\e scope based extension to Qt's traditional keyboard focus model. + +\section1 Key Handling Overview + +When the user presses or releases a key, the following occurs: +\list 1 +\o Qt receives the key action and generates a key event. +\o If the Qt widget containing the \l QmlView has focus, the key event is delivered to it. Otherwise, regular Qt key handling continues. +\o The key event is delivered by the scene to the QML \l Item with \e {active focus}. If no \l Item has \e {active focus}, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues. +\o If the QML \l Item with \e {active focus} accepts the key event, propagation stops. Otherwise the event is "bubbled up", by recursively passing it to each \l Item's parent until either the event is accepted, or the root \l Item is reached. + +If the \c {Rectangle} element in the following example has active focus and the \e A key is pressed, +it will bubble up to its parent. However, pressing the \e B key will bubble up to the root +item and thus subsequently be \l {QEvent::ignore()}{ignored}. + +\code +Item { + Item { + Keys.onPressed: if (event.key == Qt.Key_A) { print('Key A was pressed'); event.accepted = true } + Rectangle {} + } +} +\endcode + +\o If the root \l Item is reached, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues. + +\endlist + +See also the \l {Keys}{Keys attached property} and \l {KeyNavigation}{KeyNavigation attached property}. + +\section1 Querying the Active Focus Item + +Whether or not an \l Item has \e {active focus} can be queried through the +property \c {Item::focus}. For example, here we have a \l Text +element whose text is determined by whether or not it has \e {active focus}. + +\code +Text { + text: focus ? "I have active focus!" : "I do not have active focus" +} +\endcode + +\section1 Acquiring Focus and Focus Scopes + +An \l Item requests focus by setting the \c {Item::focus} property to true. + +For very simple cases simply setting the \c {Item::focus} property is sometimes +sufficient. If we run the following example in the \c qmlviewer, we see that +the \c {keyHandler} element has \e {active focus} and pressing the 'A', 'B' +or 'C' keys modifies the text appropriately. + +\table +\row +\o \code + Rectangle { + color: "lightsteelblue"; width: 240; height: 25 + Text { id: myText } + Item { + id: keyHandler + focus: true + Keys.onPressed: { + if (event.key == Qt.Key_A) + myText.text = 'Key A was pressed' + else if (event.key == Qt.Key_B) + myText.text = 'Key B was pressed' + else if (event.key == Qt.Key_C) + myText.text = 'Key C was pressed' + } + } + } +\endcode +\o \image declarative-qmlfocus1.png +\endtable + +However, were the above example to be used as a self-contained component, this +simple use of the \c {Item::focus} property is no longer sufficient. The left +hand side of the following table shows what we would like to be able to write. +Here we create two instances of our previously defined component, and set the +second one to have focus. The intention is that when the \e A, \e B, or \e C +keys are pressed, the second of the two components receives the event and +reponds accordingly. + +\table +\row +\o \code +Rectangle { + color: "red"; width: 240; height: 55 + MyWidget {} + MyWidget { y: 30; focus: true } +} +\endcode +\o \code +Rectangle { + color: "red"; width: 240; height: 55 + Rectangle { + color: "lightsteelblue"; width: 240; height: 25 + Text { id: myText } + Item { + id: keyHandler + focus: true + Keys.onPressed: { + if (event.key == Qt.Key_A) + myText.text = 'Key A was pressed' + else if (event.key == Qt.Key_B) + myText.text = 'Key B was pressed' + else if (event.key == Qt.Key_C) + myText.text = 'Key C was pressed' + } + } + } + Rectangle { + y: 30; focus: true + color: "lightsteelblue"; width: 240; height: 25 + Text { id: myText } + Item { + id: keyHandler + focus: true + Keys.onPressed: { + if (event.key == Qt.Key_A) + myText.text = 'Key A was pressed' + else if (event.key == Qt.Key_B) + myText.text = 'Key B was pressed' + else if (event.key == Qt.Key_C) + myText.text = 'Key C was pressed' + } + } + } +} +\endcode +\endtable + +The right hand side of the example shows the expanded code - the equivalent QML +without the use of the component \c {MyWidget}. From this, the problem is +evident - there are no less than three elements that have the \c {Item::focus} +property set to true. Ultimately only one element can have focus, and the +system has to decide which on. In this case the first appearance of the +\c {Item::focus} property being set to true on line 4 is selected, and the value +of \c {Item::focus} in the other two instances is reverted back to false. This +is exactly the opposite of what was wanted! + +This problem is fundamentally one of visibility. The \c {MyWidget} +components each set their \c {keyHandler} Items as focused as that is all they can +do - they don't know how they are going to be used, but they do know that when +they're in use their \c {keyHandler} element is what needs focus. Likewise +the code that uses the two \c {MyWidgets} sets the second \c {MyWidget} as +focused. While it doesn't know exactly how the \c {MyWidget} is +implemented, it knows that it wants the second one to be focused. This allows us +to achieve encapsulation, allowing each widget to focus on it's appropriate behaviour +itself. + +To solve this problem - allowing components to care about what they know about +and ignore everything else - the QML items introduce a concept known as a +\e {focus scope}. For existing Qt users, a \e {focus scope} is like an +automatic focus proxy. A \e {focus scope} is created using the \l FocusScope +element. + +In the next example, a \l FocusScope is added to the component, and the visual +result shown. + +\table +\row +\o \code +FocusScope { + width: 240; height: 25 + Rectangle { + color: "lightsteelblue"; width: 240; height: 25 + Text { id: myText } + Item { + id: keyHandler + focus: true + Keys.onPressed: { + if (event.key == Qt.Key_A) + myText.text = 'Key A was pressed' + else if (event.key == Qt.Key_B) + myText.text = 'Key B was pressed' + else if (event.key == Qt.Key_C) + myText.text = 'Key C was pressed' + } + } + } +} +\endcode +\o \image declarative-qmlfocus2.png +\endtable + +Conceptually \e {focus scopes} are quite simple. +\list +\o Within each \e {focus scope} one element may have \c {Item::focus} set to true. +If more than one \l Item has the \c {Item::focus} property set, the first is selected +and the others are unset, just like when there are no \e {focus scopes}. +\o When a \e {focus scope} receives \e {active focus}, the contained element with +\c {Item::focus} set (if any) also gets \e {active focus}. If this element is +also a \l FocusScope, the proxying behaviour continues. Both the +\e {focus scope} and the sub-focused item will have \c {Item::focus} set. +\endlist + +So far the example has the second component statically selected. It is trivial +now to extend this component to make it clickable, and add it to the original +application. We still set a one of the widgets as focused by default, but from +then on clicking the either one gives it focus. + +\table +\row +\o \code +Rectangle { + color: "red"; width: 240; height: 55 + MyClickableWidget {} + MyClickableWidget { y: 30; focus: true } +} +\endcode +\o \code +FocusScope { + id: page; width: 240; height: 25 + MyWidget { focus: true } + MouseRegion { anchors.fill: parent; onClicked: { page.focus = true } } +} +\endcode +\endtable + +\image declarative-qmlfocus3.png + +When a QML item explicitly relinquishes focus (by setting its +\c {Item::focus} property to false while it has \e {active focus}), the system +does not automatically select another element to receive focus. That is, it +is possible for there to be no currently \e {active focus}. + +\section1 Advanced uses of Focus Scopes + +Focus scopes allow focus to allocation to be easily partitioned. Several +QML items use it to this effect. + +\l ListView, for example, is itself a focus scope. Generally this isn't +noticable as \l ListView doesn't usually have manually added visual children. +By being a focus scope, \l ListView can focus the current list item without +worrying about how that will effect the rest of the application. This allows +the current item delegate to react to key presses. + +This contrived example shows how this works. Pressing the \c Return key will +print the name of the current list item. + +\table +\row +\o \code +Rectangle { + color: "lightsteelblue"; width: 240; height: 320 + + ListView { + id: myView; anchors.fill: parent; focus: true + model: ListModel { + ListElement { name: "Bob" } + ListElement { name: "John" } + ListElement { name: "Michael" } + } + delegate: FocusScope { + width: contents.width; height: contents.height + Text { + focus: true + text: name + Keys.onReturnPressed: print(name) + } + } + } +} +\endcode +\o \image declarative-qmlfocus4.png +\endtable + +While the example is simple, there's a lot going on behind the scenes. Whenever +the current item changes, the \l ListView sets the delegate's \c {Item::focus} +property. As the \l ListView is a \e {focus scope}, this doesn't effect the +rest of the application. However, if the \l ListView itself has +\e {active focus} this causes the delegate itself to receive \e {active focus}. +In this example, the root element of the delegate is also a \e {focus scope}, +which in turn gives \e {active focus} to the \c {Text} element that +actually performs the work of handling the \e {Return} key. + +All of the QML view classes, such as \l PathView and \l GridView, behave +in a similar mannor to allow key handling in their respective delegates. + +\section1 Focus Panels + +Traditional UIs are composed of many top-level windows. Windows actually +perform two tasks - they act as the visual bounds for a widget, and they segment +focus. Each window has a separate focused widget, that becomes (to mix +terminologies) the \e {active focus} widget when the window is the active +window. + +### Focus panels do basically the same thing. +*/ diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc new file mode 100644 index 0000000..e983ad0 --- /dev/null +++ b/doc/src/declarative/globalobject.qdoc @@ -0,0 +1,243 @@ +/**************************************************************************** +** +** 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 qmlglobalobject.html +\title QML Global Object +Contains all the properties of the ECMAScript global object, plus: + +\list +\o Qt +\o createQmlObject +\o createComponent +\o XMLHttpRequest +\o openDatabase +\endlist + +Contents: +\tableofcontents + +\section1 Qt Object + +The Qt object provides useful enums and functions from Qt, for use in all QML +files. + +\section2 Enums +The Qt object contains all enums in the Qt namespace. For example, you can +access the AlignLeft member of the Qt::AlignmentFlag enum with \c Qt.AlignLeft. + +For a full list of enums, see the Qt Namespace documentation. + +\section2 Types +The Qt object also contains helper functions for creating objects of specific +data types. This is primarily useful when setting the properties of an item +when the property has one of the following types: + +\list +\o Color +\o Rect +\o Point +\o Size +\o Vector3D +\endlist + +There are also string based constructors for these types, see \l{basicqmltypes.html}{Qml Types}. + +\section3 Qt.rgba(int red, int green, int blue, int alpha) +This function returns a Color with the specified \c red, \c green, \c blue and \c alpha components. All components should be in the range 0-1 inclusive. + +\section3 Qt.hsla(int hue, int saturation, int lightness, int alpha) +This function returns a Color with the specified \c hue, \c saturation, \c lightness and \c alpha components. All components should be in the range 0-1 inclusive. + +\section3 Qt.rect(int x, int y, int width, int height) +This function returns a Rect with the top-left corner at \c x,\c y and the specified \c width and \c height. +\section3 Qt.point(int x, int y) +This function returns a Point with the specified \c x and \c y coordinates. +\section3 Qt.size(int width, int height) +This function returns as Size with the specified width and height. +\section3 Qt.vector3d(real x, real y, real z) +This function returns a Vector3D with the specified x, y and z. +\section2 Functions +The Qt object also contains the following miscellaneous functions which expose Qt functionality for use in QML. + +\section3 Qt.lighter(color baseColor) +This function returns a color 50% lighter than \c baseColor. See QColor::lighter() for further details. +\section3 Qt.darker(color baseColor) +This function returns a color 50% darker than \c baseColor. See QColor::lighter() for further details. +\section3 Qt.tint(color baseColor, color tintColor) + This function allows tinting one color with another. + + The tint color should usually be mostly transparent, or you will not be able to see the underlying color. The below example provides a slight red tint by having the tint color be pure red which is only 1/16th opaque. + + \qml + Rectangle { x: 0; width: 80; height: 80; color: "lightsteelblue" } + Rectangle { x: 100; width: 80; height: 80; color: Qt.tint("lightsteelblue", "#10FF0000") } + \endqml + \image declarative-rect_tint.png + + Tint is most useful when a subtle change is intended to be conveyed due to some event; you can then use tinting to more effectively tune the visible color. +\section3 Qt.closestAngle(number fromAngle, number toAngle) +This function returns an equivalent angle to toAngle, such that the difference between fromAngle and toAngle is never more than 180 degrees. This is useful when animating angles using a NumberAnimation, which does not know about equivalent angles, when you always want to take the shortest path. + +\section3 Qt.playSound(url soundLocation) +This function plays the audio file located at \c soundLocation. Only .wav files are supported. + +\section3 Qt.openUrlExternally(url target) +This function attempts to open the specified \c target url in an external application, based on the user's desktop preferences. It will return true if it succeeds, and false otherwise. + +\section3 Qt.md5(data) +This function returns a hex string of the md5 hash of \c data. + +\section1 Dynamic Object Creation +The following functions on the global object allow you to dynamically create QML +items from files or strings. + +You can also dynamically create objects in a declarative manner, using items +such as ListView, \l Repeater and \l Loader. + +\section2 createComponent(url file) + This function takes the URL of a QML file as its only argument. It returns + a component object which can be used to create and load that QML file. + + Example QML script is below. Remember that QML files that might be loaded + over the network cannot be expected to be ready immediately. + \code + var component; + var sprite; + function finishCreation(){ + if(component.isReady()){ + sprite = component.createObject(); + if(sprite == 0){ + // Error Handling + }else{ + sprite.parent = page; + sprite.x = 200; + //... + } + }else if(component.isError()){ + // Error Handling + } + } + + component = createComponent("Sprite.qml"); + if(component.isReady()){ + finishCreation(); + }else{ + component.statusChanged.connect(finishCreation); + } + \endcode + + If you are certain the files will be local, you could simplify to + + \code + component = createComponent("Sprite.qml"); + sprite = component.createObject(); + if(sprite == 0){ + // Error Handling + print(component.errorsString()); + }else{ + sprite.parent = page; + sprite.x = 200; + //... + } + \endcode + + If you want to just create an arbitrary string of QML, instead of + loading a QML file, consider the createQmlObject() function. + +\section2 createQmlObject(string qml, object parent, string filepath) + Creates a new object from the specified string of QML. It requires a + second argument, which is the id of an existing QML object to use as + the new object's parent. If a third argument is provided, this is used + for error reporting as the filepath that the QML came from. + + Example (where targetItem is the id of an existing QML item): + \code + newObject = createQmlObject('import Qt 4.6; Rectangle {color: "red"; width: 20; height: 20}', + targetItem, "dynamicSnippet1"); + \endcode + + This function is intended for use inside QML only. It is intended to behave + similarly to eval, but for creating QML elements. + + Returns the created object, or null if there is an error. In the case of an + error, details of the error are output using qWarning(). + + Note that this function returns immediately, and therefore may not work if + the QML loads new components. If you are trying to load a new component, + for example from a QML file, consider the createComponent() function + instead. 'New components' refers to external QML files that have not yet + been loaded, and so it is safe to use createQmlObject to load built-in + components. + +\section1 Asynchronous JavaScript and XML +QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain data from over a network. +\section2 XMLHttpRequest() +In QML you can construct an XMLHttpRequest object just like in a web browser! TODO: Real documentation for this object. +\section1 Offline Storage API + +The \c openDatabase() and related functions +provide the ability to access local offline storage in an SQL database. + +These databases are user-specific and QML-specific. They are stored in the \c Databases subdirectory +of QmlEngine::offlineStoragePath(), currently as SQLite databases. + +The API conforms to the Synchronous API of the HTML5 Web Database API, +\link http://www.w3.org/TR/2009/WD-webdatabase-20091029/ W3C Working Draft 29 October 2009\endlink. + +The API can be used from JavaScript functions in your QML: + +\quotefile declarative/sql/hello.qml + +When a database is first created, an INI file is also created specifying its characteristics: + +\table +\header \o \bold {Key} \o \bold {Value} +\row \o Name \o The name of the database passed to \c openDatabase() +\row \o Version \o The version of the database passed to \c openDatabase() +\row \o Description \o The description of the database passed to \c openDatabase() +\row \o EstimatedSize \o The estimated size of the database passed to \c openDatabase() +\row \o Driver \o Currently "QSQLITE" +\endtable + +This data can be used by application tools. + +*/ diff --git a/doc/src/declarative/measuring-performance.qdoc b/doc/src/declarative/measuring-performance.qdoc new file mode 100644 index 0000000..bd1b0eb --- /dev/null +++ b/doc/src/declarative/measuring-performance.qdoc @@ -0,0 +1,122 @@ +/**************************************************************************** +** +** 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 optimizing-performance.html +\target optimizing-performance +\title Optimizing Performance in QML + +The Qt Declarative module includes several tools to help measure performance. + +\section1 Performance Logging + +The declarative module uses the functionality provided by QPerformanceLog to log performance information. To see this information you can add the following to src.pro: + +\code +DEFINES += Q_ENABLE_PERFORMANCE_LOG +\endcode + +The performance information will be printed to screen on a QML application startup, or when running the viewer can be forced at anytime by pressing 'F3' on the keyboard. + +Additional logging can be enabled by adding the relevant categories to qfxperf.h and qfxperf.cpp. + +For example, to measure the cost of calculating the size of a text item, you would first define a TextSize category by adding the following: + +\code +//in qfxperf.h +Q_DECLARE_PERFORMANCE_METRIC(TextSize); + +//in qfxperf.cpp +Q_DEFINE_PERFORMANCE_METRIC(TextSize, "Text Size Calculation"); +\endcode + +You could then use this category in the code: + +\code +void QmlGraphicsText::updateSize() +{ + QmlPerfTimer<QmlPerf::TextSize> perf; + ... +} +\endcode + +Because there is no cost for a QmlPerfTimer when Q_ENABLE_PERFORMANCE_LOG is not defined, this line can persist in the code and be used to help detect performance bottlenecks and regressions. See the QPerformanceLog documentation for more information on this performance framework. + +\section1 FPS Measurements + +When running the viewer, pressing 'F2' on the keyboard while a QML program is running will cause information on cost-per-frame and frames-per-second (FPS) to be printed to the console. + +The information printed includes: +\list +\o \e repaint(): the total time spent painting. +\o \e paint(): the time spent by Qt painting. +\o \e timeBetweenFrames: the total time spent per frame. This number minus repaint() gives a good idea of how much time is spent on things besides painting. A high number here with a low number for repaint() indicates expensive calculations happening each frame. +\endlist + +\section1 Improving Performance + +The following tips can help decrease startup time for QML-based appications. + +\section2 Images + +\list +\o Use jpg instead of png for photo-like images. On the N810, this can save 150ms for a large (320x480) image. + +\o If you are configuring Qt, configure out any image plugins you don't plan to support (mng and svg are the most expensive). On the N810, this can save 75-100ms startup time. For example: + +\code +configure -no-libmng -no-svg -no-libtiff +\endcode + +\o In some cases running pngcrush, optipng, gifsicle or other similar tools can give some improvement. + +We are also investigating support for the loading of uncompressed images. This will provide opportunites to decrease startup time at the cost of increased storage space. +\endlist + +\section2 Fonts + +\list +\o Use qpf instead of ttf. When using multiple font sizes and weights on the N810, this can save 125ms startup time compared to a ttf 'clean' run, and 40-50ms on subsequent runs (ttfs are shared by open applications). +\endlist + +*/ + +*/ diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc new file mode 100644 index 0000000..1491fea --- /dev/null +++ b/doc/src/declarative/modules.qdoc @@ -0,0 +1,147 @@ +/**************************************************************************** +** +** 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 qmlmodules.html +\title Modules + +A \bold module is a collection of QML types. + +To use types from a module it must be imported using the \c import statement. Successive +import statements override earlier import statements. + +\section1 Importing Built-in Types + +To use built-in types, you must import the module defining them. +For example, to use types from Qt, import it: + +\code +import Qt 4.6 +\endcode + +This makes available all types in Qt that were available in Qt 4.6, regardless of the +actual version of Qt executing the QML. + +Modules can be compiled-in (such as the Qt module), or they can be +defined in QML files. + +\section1 Importing QML Files + +To import types defined in QML files in directories relative to the file importing them, +a quoted import directory is used: + +\code +import "path" +\endcode + +This allows all components defined in the directory \c path to be used in +the component where this statement appears. + +To import types defined in QML files that are installed somewhere on the system, +an unquoted URI is used: + +\code +import com.nokia.CoolStuff 1.0 +\endcode + +This will access file in the directory \c com/nokia/CoolStuff/, found in some +location determined outside QML. See QmlEngine::addImportPath() and the \c -L option +to the \l {qmlviewer}{viewer} application. + +The directory of installed files must include a file \c qmldir which specifies the +mapping from all type names to versioned QML files. It is a list of lines of the form: + +\code +# <Comment> +<TypeName> <InitialVersion> <File> +\endcode + +<TypeName> is the type being made available; <InitialVersion> is a version +number like \c 4.0; <File> is the (relative) +file name of the QML file defining the type. + +The same type can be provided by different files in different versions, in which +case later earlier versions (eg. 1.2) must precede earlier versions (eg. 1.0), +since the \e first name-version match is used. + +Installed files do not need to import the module of which they are a part, as they can refer +to the other QML files in the module as relative (local) files. + +Installed files \e must be referred to by version information described above, +local files \e may have it. + +The versioning system ensures that a given QML file will work regardless of the version +of installed software, since a versioned import \e only imports types for that version, +leaving other identifiers available, even if the actual installed version might otherwise +use those identifiers. + +\section1 Namespaces - Named Imports + +When importing content it by default imports types into the global namespace. +You may choose to import the module into another namespace, either to allow identically-named +types to be referenced, or purely for readability. + +To import a module into a namespace: + +\code +import Qt 4.6 as TheQtLibrary +\endcode + +Types from Qt 4.6 may then be used, but only by qualifying them with the namespace: + +\code +TheQtLibrary.Rectangle { ... } +\endcode + +Multiple modules can be imported into the same namespace in the same way that multiple +modules can be imported into the global namespace: + +\code +import Qt 4.6 as Nokia +import Ovi 1.0 as Nokia +\endcode +*/ + +/* + +See original requirement QT-558. + +*/ diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc new file mode 100644 index 0000000..ed20e66e --- /dev/null +++ b/doc/src/declarative/network.qdoc @@ -0,0 +1,167 @@ +/**************************************************************************** +** +** 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 qmlnetwork.html +\title Network Transparency + +QML supports network transparency by using URLs (rather than file names) for all +references from a QML document to other content: + +\qml +Image { + source: "http://www.example.com/images/logo.png" +} +\endqml + +Since a \e relative URL is the same +as a relative file, development of QML on regular file systems remains simple: + +\qml +Image { + source: "images/logo.png" +} +\endqml + +Network transparency is supported throughout QML, for example: + +\list +\o Scripts - the \c source property of \l Script is a URL +\o Fonts - the \c source property of FontLoader is a URL +\o WebViews - the \c url property of WebView (obviously!) +\endlist + +Even QML types themselves can be on the network - if \l qmlviewer is used to load +\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", this +will load from \tt http://example.com/mystuff/World.qml just as it would for a local file. +Any other resources that \tt Hello.qml referred to, usually by a relative URL, would +similarly be loaded from the network. + + +\section1 Relative vs. Absolute URLs + +Whenever an object has a property of type URL (QUrl), assigning a string to that +property will actually assign an absolute URL - by resolving the string against +the URL of the document where the string is used. + +For example, consider this content in \tt{http://example.com/mystuff/test.qml}: + +\qml +Image { + source: "images/logo.png" +} +\endqml + +The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png}, +but while the QML is being developed, in say \tt C:\\User\\Fred\\Documents\\MyStuff\\test.qml, it will be assigned +\tt C:\\User\\Fred\\Documents\\MyStuff\\images\\logo.png. + +If the string assigned to a URL is already an absolute URL, then "resolving" does +not change it and the URL is assigned directly. + + +\section1 Progressive Loading + +Because of the declarative nature of QML and the asynchronous nature of network resources, +objects which reference network resource generally change state as the network resource loads. +For example, an Image with a network source will initially have +a \c width and \c height of 0, a \c status of \c Loading, and a \c progress of 0.0. +While the content loads, the \c progress will increase until +the content is fully loaded from the network, +at which point the \c width and \c height become the content size, the \c status becomes \c Ready, and the \c progress reaches 1.0. +Applications can bind to these changing states to provide visual progress indicators where appropriate, or simply +bind to the \c width and \c height as if the content was a local file, adapting as those bound values change. + +Note that when objects reference local files they immediately have the \c Ready status, but applications wishing +to remain network transparent should not rely on this. Future versions of QML may also use asynchronous local file I/O +to improve performance. + + +\section1 Accessing Network Services + +QML types such as XmlListModel, and JavaScript classes like XMLHttpRequest are intended +entirely for accessing network services, which usually respond with references to +content by URLs that can then be used directly in QML. For example, using these facilities +to access an on-line photography service would provide the QML application with URLs to +photographs, which can be directly set on an \l Image \c source property. + +See the \tt demos/declarative/flickr for a real demonstration of this. + + +\section1 Configuring the Network Access Manager + +All network access from QML is managed by a QNetworkAccessManager set on the QmlEngine which executes the QML. +By default, this is an unmodified Qt QNetworkAccessManager. You may set a different manager using +QmlEngine::setNetworkAccessManager() as appropriate for the policies of your application. +For example, the \l qmlviewer tool sets a new QNetworkAccessManager which +trusts HTTP Expiry headers to avoid network cache checks, allows HTTP Pipelining, adds a persistent HTTP CookieJar, +a simple disk cache, and supports proxy settings. + + +\section1 QRC Resources + +One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into +the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content +that is compiled into the executable: + +\code + QmlView *canvas = new QmlView; + canvas->setUrl(QUrl("qrc:/dial.qml")); +\endcode + +The content itself can then use relative URLs, and so be transparently unaware that the content is +compiled into the executable. + + +\section1 Limitations + +The \c import statement is only network transparent if it has an "as" clause. + +More specifically: +\list +\o \c{import "dir"} only works on local file systems +\o \c{import libraryUri} only works on local file systems +\o \c{import "dir" as D} works network transparently +\o \c{import libraryUrl as U} works network transparently +\endlist + + +*/ diff --git a/doc/src/declarative/pics/3d-axis.png b/doc/src/declarative/pics/3d-axis.png Binary files differnew file mode 100644 index 0000000..1a587ff --- /dev/null +++ b/doc/src/declarative/pics/3d-axis.png diff --git a/doc/src/declarative/pics/3d-rotation-axis.png b/doc/src/declarative/pics/3d-rotation-axis.png Binary files differnew file mode 100644 index 0000000..b940215 --- /dev/null +++ b/doc/src/declarative/pics/3d-rotation-axis.png diff --git a/doc/src/declarative/pics/BorderImage.png b/doc/src/declarative/pics/BorderImage.png Binary files differnew file mode 100644 index 0000000..651dd8a --- /dev/null +++ b/doc/src/declarative/pics/BorderImage.png diff --git a/doc/src/declarative/pics/ListViewHighlight.png b/doc/src/declarative/pics/ListViewHighlight.png Binary files differnew file mode 100644 index 0000000..02bf51d --- /dev/null +++ b/doc/src/declarative/pics/ListViewHighlight.png diff --git a/doc/src/declarative/pics/ListViewHorizontal.png b/doc/src/declarative/pics/ListViewHorizontal.png Binary files differnew file mode 100644 index 0000000..4633a0e --- /dev/null +++ b/doc/src/declarative/pics/ListViewHorizontal.png diff --git a/doc/src/declarative/pics/ListViewSections.png b/doc/src/declarative/pics/ListViewSections.png Binary files differnew file mode 100644 index 0000000..9270126 --- /dev/null +++ b/doc/src/declarative/pics/ListViewSections.png diff --git a/doc/src/declarative/pics/ListViewVertical.png b/doc/src/declarative/pics/ListViewVertical.png Binary files differnew file mode 100644 index 0000000..e0b23d9 --- /dev/null +++ b/doc/src/declarative/pics/ListViewVertical.png diff --git a/doc/src/declarative/pics/anatomy-component.png b/doc/src/declarative/pics/anatomy-component.png Binary files differnew file mode 100644 index 0000000..70ed983 --- /dev/null +++ b/doc/src/declarative/pics/anatomy-component.png diff --git a/doc/src/declarative/pics/anchors.svg b/doc/src/declarative/pics/anchors.svg new file mode 100644 index 0000000..08b00ed --- /dev/null +++ b/doc/src/declarative/pics/anchors.svg @@ -0,0 +1,92 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="744.09448819" + height="1052.3622047" + id="svg1910" + sodipodi:version="0.32" + inkscape:version="0.44.1" + inkscape:export-filename="/home/mbrasser/work/Kinetic/ngui/doc/src/pics/anchors_example2.png" + inkscape:export-xdpi="189.65207" + inkscape:export-ydpi="189.65207" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="anchors.svg"> + <defs + id="defs1912" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.979899" + inkscape:cx="431.57095" + inkscape:cy="413.38853" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="1386" + inkscape:window-height="971" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata1915"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:black;stroke-width:0.52033526;stroke-miterlimit:4;stroke-dasharray:1.04067054, 0.52033527;stroke-dashoffset:0;stroke-opacity:1" + id="rect2807" + width="36.245155" + height="32.204544" + x="390.23157" + y="574.62024" /> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:black;stroke-width:0.44547796;stroke-miterlimit:4;stroke-dasharray:0.89095592, 0.44547796;stroke-dashoffset:0;stroke-opacity:1" + id="rect2809" + width="59.048447" + height="14.601732" + x="430.82993" + y="574.9483" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="399.40982" + y="594.76312" + id="text3696"><tspan + sodipodi:role="line" + id="tspan3698" + x="399.40982" + y="594.76312">pic</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="445.84048" + y="586.5423" + id="text3700"><tspan + sodipodi:role="line" + id="tspan3702" + x="445.84048" + y="586.5423">label</tspan></text> + </g> +</svg> diff --git a/doc/src/declarative/pics/animatedimageitem.gif b/doc/src/declarative/pics/animatedimageitem.gif Binary files differnew file mode 100644 index 0000000..85c3cb5 --- /dev/null +++ b/doc/src/declarative/pics/animatedimageitem.gif diff --git a/doc/src/declarative/pics/axisrotation.png b/doc/src/declarative/pics/axisrotation.png Binary files differnew file mode 100644 index 0000000..4cddcdf --- /dev/null +++ b/doc/src/declarative/pics/axisrotation.png diff --git a/doc/src/declarative/pics/blur_example.png b/doc/src/declarative/pics/blur_example.png Binary files differnew file mode 100644 index 0000000..763b112 --- /dev/null +++ b/doc/src/declarative/pics/blur_example.png diff --git a/doc/src/declarative/pics/content.png b/doc/src/declarative/pics/content.png Binary files differnew file mode 100644 index 0000000..47a98ac --- /dev/null +++ b/doc/src/declarative/pics/content.png diff --git a/doc/src/declarative/pics/declarative-adv-tutorial1.png b/doc/src/declarative/pics/declarative-adv-tutorial1.png Binary files differnew file mode 100644 index 0000000..990a329 --- /dev/null +++ b/doc/src/declarative/pics/declarative-adv-tutorial1.png diff --git a/doc/src/declarative/pics/declarative-adv-tutorial2.png b/doc/src/declarative/pics/declarative-adv-tutorial2.png Binary files differnew file mode 100644 index 0000000..b410d50 --- /dev/null +++ b/doc/src/declarative/pics/declarative-adv-tutorial2.png diff --git a/doc/src/declarative/pics/declarative-adv-tutorial3.png b/doc/src/declarative/pics/declarative-adv-tutorial3.png Binary files differnew file mode 100644 index 0000000..e192772 --- /dev/null +++ b/doc/src/declarative/pics/declarative-adv-tutorial3.png diff --git a/doc/src/declarative/pics/declarative-adv-tutorial4.gif b/doc/src/declarative/pics/declarative-adv-tutorial4.gif Binary files differnew file mode 100644 index 0000000..827458d --- /dev/null +++ b/doc/src/declarative/pics/declarative-adv-tutorial4.gif diff --git a/doc/src/declarative/pics/declarative-qmlfocus1.png b/doc/src/declarative/pics/declarative-qmlfocus1.png Binary files differnew file mode 100644 index 0000000..fd05146 --- /dev/null +++ b/doc/src/declarative/pics/declarative-qmlfocus1.png diff --git a/doc/src/declarative/pics/declarative-qmlfocus2.png b/doc/src/declarative/pics/declarative-qmlfocus2.png Binary files differnew file mode 100644 index 0000000..a946e2c --- /dev/null +++ b/doc/src/declarative/pics/declarative-qmlfocus2.png diff --git a/doc/src/declarative/pics/declarative-qmlfocus3.png b/doc/src/declarative/pics/declarative-qmlfocus3.png Binary files differnew file mode 100644 index 0000000..ba55f76 --- /dev/null +++ b/doc/src/declarative/pics/declarative-qmlfocus3.png diff --git a/doc/src/declarative/pics/declarative-qmlfocus4.png b/doc/src/declarative/pics/declarative-qmlfocus4.png Binary files differnew file mode 100644 index 0000000..e21f2a6 --- /dev/null +++ b/doc/src/declarative/pics/declarative-qmlfocus4.png diff --git a/doc/src/declarative/pics/dial-example.gif b/doc/src/declarative/pics/dial-example.gif Binary files differnew file mode 100644 index 0000000..4e90ba9 --- /dev/null +++ b/doc/src/declarative/pics/dial-example.gif diff --git a/doc/src/declarative/pics/edge1.png b/doc/src/declarative/pics/edge1.png Binary files differnew file mode 100644 index 0000000..f4bc16d --- /dev/null +++ b/doc/src/declarative/pics/edge1.png diff --git a/doc/src/declarative/pics/edge2.png b/doc/src/declarative/pics/edge2.png Binary files differnew file mode 100644 index 0000000..71bda8e --- /dev/null +++ b/doc/src/declarative/pics/edge2.png diff --git a/doc/src/declarative/pics/edge3.png b/doc/src/declarative/pics/edge3.png Binary files differnew file mode 100644 index 0000000..51bb894 --- /dev/null +++ b/doc/src/declarative/pics/edge3.png diff --git a/doc/src/declarative/pics/edge4.png b/doc/src/declarative/pics/edge4.png Binary files differnew file mode 100644 index 0000000..aee3bd1 --- /dev/null +++ b/doc/src/declarative/pics/edge4.png diff --git a/doc/src/declarative/pics/edges.png b/doc/src/declarative/pics/edges.png Binary files differnew file mode 100644 index 0000000..211b101 --- /dev/null +++ b/doc/src/declarative/pics/edges.png diff --git a/doc/src/declarative/pics/edges.svg b/doc/src/declarative/pics/edges.svg new file mode 100644 index 0000000..25698ca --- /dev/null +++ b/doc/src/declarative/pics/edges.svg @@ -0,0 +1,185 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="744.09448819" + height="1052.3622047" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.44.1" + sodipodi:docbase="/home/mbrasser" + sodipodi:docname="edges.svg"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Mstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mstart" + style="overflow:visible"> + <path + id="path3850" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.4) translate(10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3856" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.8) translate(12.5,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.8583315" + inkscape:cx="372.04724" + inkscape:cy="596.15198" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="1279" + inkscape:window-height="969" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:black;stroke-width:0.04639034;stroke-miterlimit:4;stroke-dasharray:0.09278069, 0.04639034;stroke-dashoffset:0;stroke-opacity:1" + id="rect1872" + width="33.656742" + height="39.808346" + x="208.86543" + y="390.22763" + rx="5" + ry="5" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 225.51888,380.99149 C 225.51888,439.06733 225.86873,439.06733 225.86873,439.06733" + id="path2760" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 242.97392,380.99149 C 242.97392,439.06733 243.32377,439.06733 243.32377,439.06733" + id="path3647" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 208.33832,380.99149 C 208.33832,439.06733 208.68817,439.06733 208.68817,439.06733" + id="path3649" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,409.67956 C 256.44329,409.67956 256.09344,409.67956 256.09344,409.67956" + id="path3651" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,429.97112 C 256.44329,429.97112 256.09344,429.97112 256.09344,429.97112" + id="path3653" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,390.78742 C 256.44329,390.78742 256.09344,390.78742 256.09344,390.78742" + id="path3655" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="258.54242" + y="393.58627" + id="text3657"><tspan + sodipodi:role="line" + id="tspan3659" + x="258.54242" + y="393.58627" + style="font-size:10px">Top</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="258.78955" + y="412.28455" + id="text3661"><tspan + sodipodi:role="line" + id="tspan3663" + x="258.78955" + y="412.28455" + style="font-size:10px">VerticalCenter</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="260.18896" + y="433.27582" + id="text3665"><tspan + sodipodi:role="line" + id="tspan3667" + x="260.18896" + y="433.27582" + style="font-size:10px">Bottom</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="198.96443" + y="376.24954" + id="text3669"><tspan + sodipodi:role="line" + id="tspan3671" + x="198.96443" + y="376.24954" + style="font-size:10px">Left</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="230.55408" + y="375.39383" + id="text3673"><tspan + sodipodi:role="line" + id="tspan3675" + x="230.55408" + y="375.39383" + style="font-size:10px">Right</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="186.71951" + y="355.25827" + id="text3677"><tspan + sodipodi:role="line" + id="tspan3679" + x="186.71951" + y="355.25827" + style="font-size:10px">HorizontalCenter</tspan></text> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Mstart)" + d="M 224.2567,375.39382 C 227.40539,356.85154 227.75525,357.20139 227.75525,357.20139" + id="path3681" /> + </g> +</svg> diff --git a/doc/src/declarative/pics/edges_examples.svg b/doc/src/declarative/pics/edges_examples.svg new file mode 100644 index 0000000..31e9901 --- /dev/null +++ b/doc/src/declarative/pics/edges_examples.svg @@ -0,0 +1,109 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="744.09448819" + height="1052.3622047" + id="svg3885" + sodipodi:version="0.32" + inkscape:version="0.44.1" + inkscape:export-filename="/home/mbrasser/edge4.png" + inkscape:export-xdpi="189.65207" + inkscape:export-ydpi="189.65207" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="edges_examples.svg"> + <defs + id="defs3887" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2" + inkscape:cx="162.62912" + inkscape:cy="591.92069" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="928" + inkscape:window-height="624" + inkscape:window-x="0" + inkscape:window-y="495" /> + <metadata + id="metadata3890"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3893" + width="50" + height="50" + x="100" + y="414.36218" /> + <rect + style="opacity:1;fill:#fa0c2a;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3895" + width="104" + height="50" + x="150" + y="414.36218" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="109" + y="443.65125" + id="text3897"><tspan + sodipodi:role="line" + id="tspan3899" + x="109" + y="443.65125">rect1</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="186.54297" + y="443.65125" + id="text3901"><tspan + sodipodi:role="line" + id="tspan3903" + x="186.54297" + y="443.65125">rect2</tspan></text> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3905" + width="50" + height="50" + x="254" + y="414.36218" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="263" + y="443.65125" + id="text3907"><tspan + sodipodi:role="line" + id="tspan3909" + x="263" + y="443.65125">rect3</tspan></text> + </g> +</svg> diff --git a/doc/src/declarative/pics/edges_qml.png b/doc/src/declarative/pics/edges_qml.png Binary files differnew file mode 100644 index 0000000..73f22f9 --- /dev/null +++ b/doc/src/declarative/pics/edges_qml.png diff --git a/doc/src/declarative/pics/edges_qml.svg b/doc/src/declarative/pics/edges_qml.svg new file mode 100644 index 0000000..1814ec6 --- /dev/null +++ b/doc/src/declarative/pics/edges_qml.svg @@ -0,0 +1,188 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="744.09448819" + height="1052.3622047" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.44.1" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="edges_qml.svg" + inkscape:export-filename="/home/mbrasser/edges_qml.png" + inkscape:export-xdpi="284.45999" + inkscape:export-ydpi="284.45999"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Mstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mstart" + style="overflow:visible"> + <path + id="path3850" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.4) translate(10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3856" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.8) translate(12.5,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.8583315" + inkscape:cx="372.04724" + inkscape:cy="596.15198" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="1279" + inkscape:window-height="969" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:black;stroke-width:0.04639034;stroke-miterlimit:4;stroke-dasharray:0.09278069, 0.04639034;stroke-dashoffset:0;stroke-opacity:1" + id="rect1872" + width="33.656742" + height="39.808346" + x="208.86543" + y="390.22763" + rx="5" + ry="5" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 225.51888,380.99149 C 225.51888,439.06733 225.86873,439.06733 225.86873,439.06733" + id="path2760" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 242.97392,380.99149 C 242.97392,439.06733 243.32377,439.06733 243.32377,439.06733" + id="path3647" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 208.33832,380.99149 C 208.33832,439.06733 208.68817,439.06733 208.68817,439.06733" + id="path3649" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,409.67956 C 256.44329,409.67956 256.09344,409.67956 256.09344,409.67956" + id="path3651" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,429.97112 C 256.44329,429.97112 256.09344,429.97112 256.09344,429.97112" + id="path3653" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,390.78742 C 256.44329,390.78742 256.09344,390.78742 256.09344,390.78742" + id="path3655" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="258.54242" + y="393.58627" + id="text3657"><tspan + sodipodi:role="line" + id="tspan3659" + x="258.54242" + y="393.58627" + style="font-size:10px">top</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="258.78955" + y="412.28455" + id="text3661"><tspan + sodipodi:role="line" + id="tspan3663" + x="258.78955" + y="412.28455" + style="font-size:10px">verticalCenter</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="260.18896" + y="433.27582" + id="text3665"><tspan + sodipodi:role="line" + id="tspan3667" + x="260.18896" + y="433.27582" + style="font-size:10px">bottom</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="200.96443" + y="376.24954" + id="text3669"><tspan + sodipodi:role="line" + id="tspan3671" + x="200.96443" + y="376.24954" + style="font-size:10px">left</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="232.55408" + y="375.39383" + id="text3673"><tspan + sodipodi:role="line" + id="tspan3675" + x="232.55408" + y="375.39383" + style="font-size:10px">right</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="190.71951" + y="355.25827" + id="text3677"><tspan + sodipodi:role="line" + id="tspan3679" + x="190.71951" + y="355.25827" + style="font-size:10px">horizontalCenter</tspan></text> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Mstart);stroke-opacity:1" + d="M 226.2567,375.39382 C 229.40539,356.85154 229.75525,357.20139 229.75525,357.20139" + id="path3681" /> + </g> +</svg> diff --git a/doc/src/declarative/pics/flickable.gif b/doc/src/declarative/pics/flickable.gif Binary files differnew file mode 100644 index 0000000..f7a3319 --- /dev/null +++ b/doc/src/declarative/pics/flickable.gif diff --git a/doc/src/declarative/pics/flipable.gif b/doc/src/declarative/pics/flipable.gif Binary files differnew file mode 100644 index 0000000..6386f06 --- /dev/null +++ b/doc/src/declarative/pics/flipable.gif diff --git a/doc/src/declarative/pics/gradient.png b/doc/src/declarative/pics/gradient.png Binary files differnew file mode 100644 index 0000000..5eefdd2 --- /dev/null +++ b/doc/src/declarative/pics/gradient.png diff --git a/doc/src/declarative/pics/gridLayout_example.png b/doc/src/declarative/pics/gridLayout_example.png Binary files differnew file mode 100644 index 0000000..6b120e9 --- /dev/null +++ b/doc/src/declarative/pics/gridLayout_example.png diff --git a/doc/src/declarative/pics/gridview.png b/doc/src/declarative/pics/gridview.png Binary files differnew file mode 100644 index 0000000..3726893 --- /dev/null +++ b/doc/src/declarative/pics/gridview.png diff --git a/doc/src/declarative/pics/highlight.gif b/doc/src/declarative/pics/highlight.gif Binary files differnew file mode 100644 index 0000000..fbef256 --- /dev/null +++ b/doc/src/declarative/pics/highlight.gif diff --git a/doc/src/declarative/pics/horizontalpositioner_example.png b/doc/src/declarative/pics/horizontalpositioner_example.png Binary files differnew file mode 100644 index 0000000..42f90ec --- /dev/null +++ b/doc/src/declarative/pics/horizontalpositioner_example.png diff --git a/doc/src/declarative/pics/margins_qml.png b/doc/src/declarative/pics/margins_qml.png Binary files differnew file mode 100644 index 0000000..d7d73a3 --- /dev/null +++ b/doc/src/declarative/pics/margins_qml.png diff --git a/doc/src/declarative/pics/margins_qml.svg b/doc/src/declarative/pics/margins_qml.svg new file mode 100644 index 0000000..1f0ff02 --- /dev/null +++ b/doc/src/declarative/pics/margins_qml.svg @@ -0,0 +1,196 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="744.09448819" + height="1052.3622047" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.44.1" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="margins_qml.svg" + inkscape:export-filename="/home/mbrasser/edges_qml.png" + inkscape:export-xdpi="284.45999" + inkscape:export-ydpi="284.45999"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Send" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Send" + style="overflow:visible;"> + <path + id="path2976" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;" + transform="scale(0.2) rotate(180) translate(6,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Sstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Sstart" + style="overflow:visible"> + <path + id="path2979" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.2) translate(6,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Mstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mstart" + style="overflow:visible"> + <path + id="path3850" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.4) translate(10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3856" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.8) translate(12.5,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.8583315" + inkscape:cx="372.04724" + inkscape:cy="596.15198" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="1279" + inkscape:window-height="969" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:black;stroke-width:0.04639034;stroke-miterlimit:4;stroke-dasharray:0.09278069, 0.04639034;stroke-dashoffset:0;stroke-opacity:1" + id="rect1872" + width="33.656742" + height="39.808346" + x="208.86543" + y="390.22763" + rx="5" + ry="5" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02602077;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02602088, 1.02602088;stroke-dashoffset:0;stroke-opacity:1" + d="M 252.98692,377.00435 C 252.98692,443.05433 253.31077,443.05433 253.31077,443.05433" + id="path3647" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02601969;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02602007, 1.02602007;stroke-dashoffset:0;stroke-opacity:1" + d="M 198.35134,377.00433 C 198.35134,443.05431 198.67515,443.05431 198.67515,443.05431" + id="path3649" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02421367;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02421381, 1.02421381;stroke-dashoffset:0;stroke-opacity:1" + d="M 193.94282,437.97112 C 257.43421,437.97112 257.06721,437.97112 257.06721,437.97112" + id="path3653" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02421367;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02421381, 1.02421381;stroke-dashoffset:0;stroke-opacity:1" + d="M 193.94282,380.78742 C 257.43421,380.78742 257.06721,380.78742 257.06721,380.78742" + id="path3655" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="260.29169" + y="388.78741" + id="text1911"><tspan + sodipodi:role="line" + id="tspan1913" + x="260.29169" + y="388.78741" + style="font-size:10px">topMargin</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="259.65204" + y="437.27798" + id="text1915"><tspan + sodipodi:role="line" + id="tspan1917" + x="259.65204" + y="437.27798" + style="font-size:10px">bottomMargin</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="170.07939" + y="454.4209" + id="text1919"><tspan + sodipodi:role="line" + id="tspan1921" + x="170.07939" + y="454.4209" + style="font-size:10px">leftMargin</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="228.47504" + y="454.4209" + id="text1923"><tspan + sodipodi:role="line" + id="tspan1925" + x="228.47504" + y="454.4209" + style="font-size:10px">rightMargin</tspan></text> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.92020172px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-end:url(#Arrow1Send);stroke-opacity:1" + d="M 225.6938,382.51213 C 225.6938,388.91693 225.6938,388.91693 225.6938,388.91693" + id="path1929" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.92007709px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-end:url(#Arrow1Send);stroke-opacity:1" + d="M 225.6938,430.56703 C 225.6938,436.97192 225.6938,436.97192 225.6938,436.97192" + id="path3000" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-mid:none;marker-end:url(#Arrow1Send);stroke-opacity:1" + d="M 201.16631,410.1318 C 207.81355,410.1318 207.81355,410.1318 207.81355,410.1318" + id="path3002" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-mid:none;marker-end:url(#Arrow1Send);stroke-opacity:1" + d="M 244.02348,410.1318 C 250.67072,410.1318 250.67072,410.1318 250.67072,410.1318" + id="path3889" /> + </g> +</svg> diff --git a/doc/src/declarative/pics/particles.gif b/doc/src/declarative/pics/particles.gif Binary files differnew file mode 100644 index 0000000..763a8a8 --- /dev/null +++ b/doc/src/declarative/pics/particles.gif diff --git a/doc/src/declarative/pics/pathview.gif b/doc/src/declarative/pics/pathview.gif Binary files differnew file mode 100644 index 0000000..4052eb2 --- /dev/null +++ b/doc/src/declarative/pics/pathview.gif diff --git a/doc/src/declarative/pics/positioner-add.gif b/doc/src/declarative/pics/positioner-add.gif Binary files differnew file mode 100644 index 0000000..86e9247 --- /dev/null +++ b/doc/src/declarative/pics/positioner-add.gif diff --git a/doc/src/declarative/pics/positioner-move.gif b/doc/src/declarative/pics/positioner-move.gif Binary files differnew file mode 100644 index 0000000..1825c22 --- /dev/null +++ b/doc/src/declarative/pics/positioner-move.gif diff --git a/doc/src/declarative/pics/positioner-remove.gif b/doc/src/declarative/pics/positioner-remove.gif Binary files differnew file mode 100644 index 0000000..7086511 --- /dev/null +++ b/doc/src/declarative/pics/positioner-remove.gif diff --git a/doc/src/declarative/pics/propanim.gif b/doc/src/declarative/pics/propanim.gif Binary files differnew file mode 100644 index 0000000..f86406e --- /dev/null +++ b/doc/src/declarative/pics/propanim.gif diff --git a/doc/src/declarative/pics/qml-context-object.png b/doc/src/declarative/pics/qml-context-object.png Binary files differnew file mode 100644 index 0000000..1b91aff --- /dev/null +++ b/doc/src/declarative/pics/qml-context-object.png diff --git a/doc/src/declarative/pics/qml-context-tree.png b/doc/src/declarative/pics/qml-context-tree.png Binary files differnew file mode 100644 index 0000000..6bba5f4 --- /dev/null +++ b/doc/src/declarative/pics/qml-context-tree.png diff --git a/doc/src/declarative/pics/qml-context.png b/doc/src/declarative/pics/qml-context.png Binary files differnew file mode 100644 index 0000000..bdf2ecd --- /dev/null +++ b/doc/src/declarative/pics/qml-context.png diff --git a/doc/src/declarative/pics/qml-scope.png b/doc/src/declarative/pics/qml-scope.png Binary files differnew file mode 100644 index 0000000..be025c8 --- /dev/null +++ b/doc/src/declarative/pics/qml-scope.png diff --git a/doc/src/declarative/pics/qtlogo.png b/doc/src/declarative/pics/qtlogo.png Binary files differnew file mode 100644 index 0000000..399bd0b --- /dev/null +++ b/doc/src/declarative/pics/qtlogo.png diff --git a/doc/src/declarative/pics/rect-smooth.png b/doc/src/declarative/pics/rect-smooth.png Binary files differnew file mode 100644 index 0000000..abbb0a9 --- /dev/null +++ b/doc/src/declarative/pics/rect-smooth.png diff --git a/doc/src/declarative/pics/reflection_example.png b/doc/src/declarative/pics/reflection_example.png Binary files differnew file mode 100644 index 0000000..fd9bb48 --- /dev/null +++ b/doc/src/declarative/pics/reflection_example.png diff --git a/doc/src/declarative/pics/repeater-index.png b/doc/src/declarative/pics/repeater-index.png Binary files differnew file mode 100644 index 0000000..3dbe6d0 --- /dev/null +++ b/doc/src/declarative/pics/repeater-index.png diff --git a/doc/src/declarative/pics/repeater.png b/doc/src/declarative/pics/repeater.png Binary files differnew file mode 100644 index 0000000..973df27 --- /dev/null +++ b/doc/src/declarative/pics/repeater.png diff --git a/doc/src/declarative/pics/scalegrid.svg b/doc/src/declarative/pics/scalegrid.svg new file mode 100644 index 0000000..e386f3d --- /dev/null +++ b/doc/src/declarative/pics/scalegrid.svg @@ -0,0 +1,183 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="744.09448819" + height="1052.3622047" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.44.1" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="scalegrid.svg" + inkscape:export-filename="/home/mbrasser/work/Kinetic/ngui/doc/src/pics/scalegrid.png" + inkscape:export-xdpi="189.65207" + inkscape:export-ydpi="189.65207"> + <defs + id="defs4" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="50" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="3.2163554" + inkscape:cx="173.89302" + inkscape:cy="703.69531" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="true" + inkscape:grid-bbox="false" + inkscape:guide-bbox="false" + inkscape:window-width="1409" + inkscape:window-height="1016" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:red;fill-opacity:1;stroke:none;stroke-width:3;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + id="rect1876" + width="45.104" + height="45.137001" + x="119.16868" + y="301.00308" + rx="5" + ry="5" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.3965202;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304035, 0.39652018;stroke-dashoffset:0;stroke-opacity:1" + d="M 157.02483,295.52571 C 157.02483,352.04784 157.02483,352.04784 157.02483,352.04784" + id="path2766" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.39652267;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304534, 0.39652268;stroke-dashoffset:0;stroke-opacity:1" + d="M 126.2,295.64284 C 126.2,352.16567 126.2,352.16567 126.2,352.16567" + id="path2768" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.39652267;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304534, 0.39652268;stroke-dashoffset:0;stroke-opacity:1" + d="M 169.05321,308.25967 C 112.53038,308.25967 112.53038,308.25967 112.53038,308.25967" + id="path2770" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.39652267;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304534, 0.39652268;stroke-dashoffset:0;stroke-opacity:1" + d="M 169.08024,339.77238 C 112.55741,339.77238 112.55741,339.77238 112.55741,339.77238" + id="path2772" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Arial Black" + x="115.2857" + y="303.60583" + id="text2774"><tspan + sodipodi:role="line" + id="tspan2776" + x="115.2857" + y="303.60583">1</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="137.19142" + y="303.60583" + id="text2782"><tspan + sodipodi:role="line" + id="tspan2784" + x="137.19142" + y="303.60583" + style="font-family:Arial Black">2</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Arial Black" + x="161.56842" + y="303.45935" + id="text2786"><tspan + sodipodi:role="line" + id="tspan2788" + x="161.56842" + y="303.45935">3</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="114.72613" + y="327.00702" + id="text2790"><tspan + sodipodi:role="line" + id="tspan2792" + x="114.72613" + y="327.00702" + style="font-family:Arial Black">4</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="137.12404" + y="326.86053" + id="text2794"><tspan + sodipodi:role="line" + id="tspan2796" + x="137.12404" + y="326.86053" + style="font-family:Arial Black">5</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="161.49518" + y="326.86053" + id="text2798"><tspan + sodipodi:role="line" + id="tspan2800" + x="161.49518" + y="326.86053" + style="font-family:Arial Black">6</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="114.70855" + y="351.25809" + id="text2802"><tspan + sodipodi:role="line" + id="tspan2804" + x="114.70855" + y="351.25809" + style="font-family:Arial Black">7</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="137.08595" + y="351.1116" + id="text2806"><tspan + sodipodi:role="line" + id="tspan2808" + x="137.08595" + y="351.1116" + style="font-family:Arial Black">8</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="161.58307" + y="351.1116" + id="text2810"><tspan + sodipodi:role="line" + id="tspan2812" + x="161.58307" + y="351.1116" + style="font-family:Arial Black">9</tspan></text> + </g> +</svg> diff --git a/doc/src/declarative/pics/shadow_example.png b/doc/src/declarative/pics/shadow_example.png Binary files differnew file mode 100644 index 0000000..6214620 --- /dev/null +++ b/doc/src/declarative/pics/shadow_example.png diff --git a/doc/src/declarative/pics/spacing_a.png b/doc/src/declarative/pics/spacing_a.png Binary files differnew file mode 100644 index 0000000..c0fe895 --- /dev/null +++ b/doc/src/declarative/pics/spacing_a.png diff --git a/doc/src/declarative/pics/spacing_b.png b/doc/src/declarative/pics/spacing_b.png Binary files differnew file mode 100644 index 0000000..24cf640 --- /dev/null +++ b/doc/src/declarative/pics/spacing_b.png diff --git a/doc/src/declarative/pics/squish-transform.png b/doc/src/declarative/pics/squish-transform.png Binary files differnew file mode 100644 index 0000000..0eb848e --- /dev/null +++ b/doc/src/declarative/pics/squish-transform.png diff --git a/doc/src/declarative/pics/squish.png b/doc/src/declarative/pics/squish.png Binary files differnew file mode 100644 index 0000000..73bf292 --- /dev/null +++ b/doc/src/declarative/pics/squish.png diff --git a/doc/src/declarative/pics/switch-example.gif b/doc/src/declarative/pics/switch-example.gif Binary files differnew file mode 100644 index 0000000..3d6582f --- /dev/null +++ b/doc/src/declarative/pics/switch-example.gif diff --git a/doc/src/declarative/pics/trivialListView.png b/doc/src/declarative/pics/trivialListView.png Binary files differnew file mode 100644 index 0000000..3782570 --- /dev/null +++ b/doc/src/declarative/pics/trivialListView.png diff --git a/doc/src/declarative/pics/verticalpositioner_example.png b/doc/src/declarative/pics/verticalpositioner_example.png Binary files differnew file mode 100644 index 0000000..458dc7f --- /dev/null +++ b/doc/src/declarative/pics/verticalpositioner_example.png diff --git a/doc/src/declarative/pics/verticalpositioner_transition.gif b/doc/src/declarative/pics/verticalpositioner_transition.gif Binary files differnew file mode 100644 index 0000000..ed61adb --- /dev/null +++ b/doc/src/declarative/pics/verticalpositioner_transition.gif diff --git a/doc/src/declarative/pics/webview.png b/doc/src/declarative/pics/webview.png Binary files differnew file mode 100644 index 0000000..0d24586 --- /dev/null +++ b/doc/src/declarative/pics/webview.png diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc new file mode 100644 index 0000000..8d0ffa9 --- /dev/null +++ b/doc/src/declarative/propertybinding.qdoc @@ -0,0 +1,110 @@ +/**************************************************************************** +** +** 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 propertybinding.html +\title Property Binding + +Property binding is a declarative way of specifying the value of a property. Binding allows +a property's value to be expressed as an ECMAScript expression that defines the value relative +to other property values or data accessible in the application. The property value is +automatically kept up to date if the other properties or data values change. + +Property bindings are created implicitly in QML whenever a property is assigned an ECMAScript +expression. The following QML uses two property bindings to connect the size of the rectangle +to that of \c otherItem. + +\code +Rectangle { + width: otherItem.width + height: otherItem.height +} +\endcode + +QML extends a standards compliant ECMAScript engine, so any valid ECMAScript expression can be +used as a property binding. Bindings can access object properties, make function calls and even +use builtin ECMAScript objects like \e {Date} and \e {Math}. Assigning a constant value to a +property can even be thought of as a binding - afterall, a constant is a valid ECMAScript +expression! Here are some examples of more complex bindings: + +\code +Rectangle { + Script { + function calculateMyHeight() { + return Math.max(otherItem.height, thirdItem.height); + } + } + + anchors.centerIn: parent + width: Math.min(otherItem.width, 10) + height: calculateMyHeight() + color: { if (width > 10) "blue"; else "red" } +} +\endcode + +Being ECMAScript expressions, bindings are evaluated in a scope chain. The \l {QML Scope} +documentation covers the specifics of scoping in QML. + +\list +\o When does a binding not get updated? +\o Scope +\o Assigning a constant/other binding clears existing binding +\o Loops +\o Using model data +\endlist + +\section1 Binding Element + +The implicit binding syntax shown previously is easy to use and works perfectly for most uses +of bindings. In some advanced cases, it is necessary to create bindings explicitly using the +\l Binding element. + +For example, to bind a property exposed from C++ (\c system.brightness) to a value +coming from QML (\c slider.value), you could use the Binding element as follows: +\qml +Binding { + target: system + property: "brightness" + value: slider.value +} +\endqml +*/ + diff --git a/doc/src/declarative/qmldocument.qdoc b/doc/src/declarative/qmldocument.qdoc new file mode 100644 index 0000000..2775ea6 --- /dev/null +++ b/doc/src/declarative/qmldocument.qdoc @@ -0,0 +1,190 @@ +/**************************************************************************** +** +** 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 qmldocuments.html +\title QML Documents + +A QML document is a block of QML source code. QML documents generally correspond to files +stored on a disk or network resource, but can be constructed directly from text data. + +A simple QML document looks like this: + +\code +import Qt 4.6 + +Rectangle { + width: 240; height: 320; + + resources: [ + Component { + id: contactDelegate + Text { + text: modelData.firstName + " " + modelData.lastName + } + } + ] + + ListView { + anchors.fill: parent + model: contactModel + delegate: contactDelegate + } +} +\endcode + +QML documents are always encoded in UTF-8 format. + +A QML document always begins with one or more import statements. To prevent elements +introduced in later versions from affecting existing QML programs, the element types +available within a document are controlled by the imported QML \l {Modules}. That is, +QML is a \e versioned language. + +Syntactically a QML document is self contained; QML does \e not have a preprocessor that +modifies the document prior to presentation to the QML runtime. \c import statements +do not "include" code in the document, but instead instruct the QML runtime on how to +resolve type references found in the document. Any type reference present in a QML +document - such as \c Rectangle and \c ListView - including those made within an +\l {ECMAScript Block} or \l {Property Binding}s, are \e resolved based exclusively on the +import statements. QML does not import any modules by default, so at least one \c import +statement must be present or no elements will be available! + +A QML document defines a single, top-level \l {QmlComponent}{QML component}. A QML component +is a template that is interpreted by the QML runtime to create an object with some predefined +behaviour. As it is a template, a single QML component can be "run" multiple times to +produce several objects, each of which are said to be \e instances of the component. + +Once created, instances are not dependent on the component that created them, so they can +operate on independent data. Here is an example of a simple "button" component that is +instantiated four times, each with a different value for its \c text property. + +\table +\row +\o +\raw HTML +<table><tr><td> +\endraw +\code +import Qt 4.6 + +BorderImage { + property alias text: textElement.text + width: 100; height: 30; source: "images/toolbutton.sci" + + Text { + id: textElement + anchors.centerIn: parent + font.pointSize: 20 + style: Text.Raised + color: "white" + } +} +\endcode +\raw HTML +</td> <td> +\endraw +\image anatomy-component.png +\raw HTML +</td> </tr> </table> +\endraw +\endtable + +In addition to the top-level component that all QML documents define, documents may also +include additional \e inline components. Inline components are declared using the +\l Component element, as can be seen in the first example above. Inline components share +all the characteristics of regular top-level components and use the same \c import list as their +containing QML document. Components are one of the most basic building blocks in QML, and are +frequently used as "factories" by other elements. For example, the \l ListView element uses the +\c delegate component as the template for instantiating list items - each list item is just a +new instance of the component with the item specific data set appropriately. + +Like other \l {QML Elements}, the \l Component element is an object and must be assigned to a +property. \l Component objects may also have an object id. In the first example on this page, +the inline component is added to the \l Rectangle's \c resources list, and then +\l {Property Binding} is used to assign the \l Component to the \l ListView's \c delegate +property. While using property binding allows the \l Component object to be shared (for example, +if the QML document contained multiple \l ListView's with the same delegate), in this case the +\l Component could have been assigned directly to the \l ListView's \c delegate. The QML +language even contains a syntactic optimization when assigning directly to a component property +for this case where it will automatically insert the \l Component tag. + +These final two examples are behaviorally identical to the original document. + +\table +\row +\o +\code +import Qt 4.6 + +Rectangle { + width: 240; height: 320; + + ListView { + anchors.fill: parent + model: contactModel + delegate: Component { + Text { + text: modelData.firstName + " " + modelData.lastName + } + } + } +} +\endcode +\o +\code +import Qt 4.6 + +Rectangle { + width: 240; height: 320; + + ListView { + anchors.fill: parent + model: contactModel + delegate: Text { + text: modelData.firstName + " " + modelData.lastName + } + } +} +\endcode +\endtable + +\sa QmlComponent +*/ diff --git a/doc/src/declarative/qmlintro.qdoc b/doc/src/declarative/qmlintro.qdoc new file mode 100644 index 0000000..f84d614 --- /dev/null +++ b/doc/src/declarative/qmlintro.qdoc @@ -0,0 +1,330 @@ +/**************************************************************************** +** +** 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 qmlintroduction.html +\title Introduction to the QML language + +\tableofcontents + +\section1 What is QML? + +QML is a declarative language designed to describe the user interface of a +program: both what it looks like and how it behaves. In QML, a user +interface is specified as a tree of objects with properties. + +\section1 What should I know before starting? + +This introduction is meant for those with little or no programming +experience. JavaScript is used as a scripting language in QML, so you may want +to learn a bit more about it (\l{JavaScript: The Definitive Guide}) before diving +too deep into QML. It's also helpful to have a basic understanding of other web +technologies like HTML and CSS, but not required. + +\section1 Basic QML Syntax + +QML looks like this: + +\code +Rectangle { + width: 200 + height: 200 + color: "white" + Image { + source: "pics/logo.png" + anchors.centerIn: parent + } +} +\endcode + +Objects are specified by their type, followed by a pair of braces. Object +types always begin with a capital letter. In the above example, there are +two objects, a \l Rectangle, and an \l Image. Between the braces, we can specify +information about the object, such as its properties. + +Properties are specified as \c {property: value} (much like CSS). In the above +example, we can see the Image has a property named \c source, which has been +assigned the value \c "pics/logo.png". The property and its value are +separated by a colon. + +Properties can be specified one-per-line: + +\code +Rectangle { + width: 100 + height: 100 +} +\endcode + +or you can put multiple properties on a single line: + +\code +Rectangle { width: 100; height: 100 } +\endcode + +When multiple property/value pairs are specified on a single line, they +must be separated by a semicolon. + +\section1 Expressions + +In addition to assigning values to properties, you can also assign +expressions written in JavaScript. + +\code +Rotation { + angle: 360 * 3 +} +\endcode + +These expressions can include references to other objects and properties, in which case +a \e binding is established: when the value of the expression changes, the property the +expression has been assigned to is automatically updated to that value. + +\code +Item { + Text { + id: text1 + text: "Hello World" + } + Text { + id: text2 + text: Text1.text + } +} +\endcode + +In the example above, the Text2 object will display the same text as Text1. If Text1 is updated, +Text2 will be updated as well. + +Note that to refer to other objects, we use their \e id (more information on the id property can be +found in a following section). + +\section1 QML Comments + +Commenting in QML is similar to JavaScript. +\list +\o Single line comments begin with // and end at the end of the line. +\o Multiline comments begin with /* and end with *\/ +\endlist + +\quotefile doc/src/snippets/declarative/comments.qml + +Comments are ignored by the engine. The are useful for explaining what you +are doing: for referring back to at a later date, or for others reading +your QML files. + +Comments can also be used to prevent the execution of code, which is +sometimes useful for tracking down problems. + +\code +Text { + text: "Hello world!" + //opacity: 0.5 +} +\endcode + +In the above example, the Text object will have normal opacity, since the +line opacity: 0.5 has been turned into a comment. + +\section1 Properties +\target intro-properties + +\section2 Property naming + +Properties begin with a lowercase letter (with the exception of \l{Attached Properties}). + +\section2 Property types + +QML supports properties of many types (\l{Common QML Types}). The basic types include int, +real, bool, string, color, and lists. + +\code +Item { + x: 10.5 // a 'real' property + ... + state: "details" // a 'string' property + focus: true // a 'bool' property +} +\endcode + +QML properties are what is known as \e typesafe. That is, they only allow you to assign a value that +matches the property type. For example, the scale property of item is a real, and if you try to assign +a string to it you will get an error. + +\badcode +Item { + scale: "hello" //illegal! +} +\endcode + +\section3 The \c id property + +The \c id property is a special property of type \e id. Assigning an id to an object allows you +to refer to it elsewhere. + +\code +Item { + Text { + id: myName + text: "..." + } + Text { + text: myName.text + } +} +\endcode + +\c Ids must begin with a lowercase letter. + +\section2 List properties + +List properties look like this: + +\code +Item { + children: [ + Image {}, + Text {} + ] +} +\endcode + +The list is enclosed in square brackets, with a comma separating the +list elements. In cases where you are only assigning a single item to a +list, you can omit the square brackets: + +\code +Image { + children: Rectangle {} +} +\endcode + +\section2 Default properties + +Each object type can specify one of its list properties as its default property. +If a list property has been declared as the default property, the property tag can be omitted. + +For example this code: +\code +State { + changes: [ + PropertyChanges {}, + PropertyChanges {} + ] +} +\endcode + +can be simplified to: + +\code +State { + PropertyChanges {} + PropertyChanges {} +} +\endcode + +because \c changes is the default property of the \c State type. + +\section2 Dot Properties + + + +\section2 Attached Properties +\target attached-properties + +Some objects attach properties to another object. Attached Properties +are of the form \e {Type.property} where \e Type is the type of the +element that attaches \e property. + +For example: +\code +Component { + id: myDelegate + Text { + text: "Hello" + color: ListView.isCurrentItem ? "red" : "blue" + } +} +ListView { + delegate: myDelegate +} +\endcode + +The \l ListView element attaches the \e ListView.isCurrentItem property +to each delegate it creates. + +Another example of attached properties is the \l Keys element which +attaches properties for handling key presses to +any visual Item, for example: + +\code +Item { + focus: true + Keys.onSelectPressed: print("Selected") +} +\endcode + +\section2 Signal Handlers + +Signal handlers allow actions to be taken in reponse to an event. For instance, +the \l MouseRegion element has signal handlers to handle mouse press, release +and click: + +\code +MouseRegion { + onPressed: print("mouse button pressed") +} +\endcode + +All signal handlers begin with \e "on". + +Some signal handlers include an optional parameter, for example +the MouseRegion onPressed signal handler has a \e mouse parameter: + +\code +MouseRegion { + acceptedButtons: Qt.LeftButton | Qt.RightButton + onPressed: if (mouse.button == Qt.RightButton) print("Right mouse button pressed") +} +\endcode + + +*/ diff --git a/doc/src/declarative/qmlmodels.qdoc b/doc/src/declarative/qmlmodels.qdoc new file mode 100644 index 0000000..a14345b --- /dev/null +++ b/doc/src/declarative/qmlmodels.qdoc @@ -0,0 +1,225 @@ +/**************************************************************************** +** +** 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 qmlmodels.html +\target qmlmodels +\title Data Models + +Some QML Items use Data Models to provide the data to be displayed. +These items typically require a \e delegate component that +creates an instance for each item in the model. Models may be static, or +have items modified, inserted, removed or moved dynamically. + +Data is provided to the delegate via named data roles which the +delegate may bind to. The roles are exposed as properties of the +\e model property, though this property is set as a default property +of the delegate so, unless there is a naming clash with a +property in the delegate, the roles are usually accessed unqualified. + +A special \e index role containing the index of the item in the model +is also available. + +Models that do not have named roles will have the data provided via +the \e modelData role. The \e modelData role is also provided for +Models that have only one role. In this case the \e modelData role +contains the same data as the named role. + +There are a number of QML elements that operate using data models: + +\list +\o ListView +\o GridView +\o PathView +\o \l Repeater +\endlist + +QML supports several types of data model, which may be provided by QML +or C++ (via QmlContext::setContextProperty(), for example). + +\section1 QML Data Models + +\section2 ListModel + +ListModel is a simple hierarchy of elements specified in QML. The +available roles are specified by the \l ListElement properties. + +\code +ListModel { + id: fruitModel + ListElement { + name: "Apple" + cost: 2.45 + } + ListElement { + name: "Orange" + cost: 3.25 + } + ListElement { + name: "Banana" + cost: 1.95 + } +} +\endcode + +The above model has two roles, \e name and \e cost. These can be bound +bound to by a ListView delegate, for example: + +\code +Component { + id: fruitDelegate + Row { + Text { text: "Fruit: " + name } + Text { text: "Cost: $" + cost } + } +} +ListView { + model: fruitModel + delegate: fruitDelegate +} +\endcode + + +\section2 XmlListModel + +XmlListModel allows construction of a model from an XML data source. The roles +are specified via the \l XmlRole element. + +The following model has three roles, \e title, \e link and \e description: +\code +XmlListModel { + id: feedModel + source: "http://rss.news.yahoo.com/rss/oceania" + query: "/rss/channel/item" + XmlRole { name: "title"; query: "title/string()" } + XmlRole { name: "link"; query: "link/string()" } + XmlRole { name: "description"; query: "description/string()" } +} +\endcode + + +\section2 VisualItemModel + +VisualItemModel allows QML items to be provided as a model. This model contains +both the data and delegate (its child items). This model does not provide any roles. + +\code + VisualItemModel { + id: itemModel + Rectangle { height: 30; width: 80; color: "red" } + Rectangle { height: 30; width: 80; color: "green" } + Rectangle { height: 30; width: 80; color: "blue" } + } + + ListView { + anchors.fill: parent + model: itemModel + } +\endcode + +Note that in the above example there is no delegate required. +The items of the model itself provide the visual elements that +will be positioned by the view. + + +\section1 C++ Data Models + +\list +\o QAbstractItemModel provides the roles set via the QAbstractItemModel::setRoleNames() method. +\o QStringList provides the contents of the list via the \e modelData role. +\o QList<QObject*> provides the properties of the objects in the list as roles. +\endlist + + +\section1 Other Data Models + + +\section2 An Integer + +An Integer specifies a model containing the integer number of elements. +There are no data roles. + +The following example creates a ListView with five elements: +\code +Component { + id: itemDelegate + Text { text: "I am item number: " + index } +} +ListView { + model: 5 + delegate: itemDelegate +} +\endcode + + +\section2 An Object Instance + +An Object Instance specifies a model with a single Object element. The +properties of the object are provided as roles. + +The example below creates a list with one item, showing the color of the +\e myText text. Note the use of the \e model property to specify the model +data rather than the \e color property of the Text element in the delegate. + +\code +Rectangle { + Text { + id: myText + text: "Hello" + color: "#dd44ee" + } + + Component { + id: myDelegate + Text { + text: model.color + } + } + ListView { + anchors.fill: parent + anchors.topMargin: 30 + model: myText + delegate: myDelegate + } +} +\endcode + +*/ diff --git a/doc/src/declarative/qmlreference.qdoc b/doc/src/declarative/qmlreference.qdoc new file mode 100644 index 0000000..f17e9d7 --- /dev/null +++ b/doc/src/declarative/qmlreference.qdoc @@ -0,0 +1,86 @@ +/**************************************************************************** +** +** 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 qmlreference.html + \title QML Reference + + \target qtdeclarativemainpage + + QML is a language for building highly dynamic and fluid applications. It is targetted at the sorts of user + interface (and the sorts of hardware) in embedded devices such as phones, media + players, and set-top boxes. It is also appropriate for highly custom desktop + user interfaces, or special elements in more traditional desktop user interfaces. + + Building fluid applications is done declaratively, rather than procedurally. + That is, you specify \e what the UI should look like and how it should behave + rather than specifying step-by-step \e how to build it. Specifying a UI declaratively + does not just include the layout of the interface items, but also the way each + individual item looks and behaves and the overall flow of the application. + + Getting Started: + \list + \o \l {Introduction to the QML language} + \o \l {tutorial}{Tutorial: 'Hello World'} + \o \l {advtutorial.html}{Advanced Tutorial: 'Same Game'} + \o \l {QML Examples and Walkthroughs} + \endlist + + \section1 Core QML Features: + \list + \o \l {QML Documents} + \o \l {Property Binding} + \o \l {ECMAScript Blocks} + \o \l {Network Transparency} + \o \l {qmlmodels}{Data Models} + \o \l {anchor-layout}{Anchor-based Layout} + \o \l {qmlstates}{States} + \o \l {qmlanimation.html}{Animation} + \o \l {qmlmodules.html}{Modules} + \o \l {qmlfocus}{Keyboard Focus} + \o \l {Extending types from QML} + \endlist + + QML Reference: + \list + \o \l {elements}{QML Elements} + \endlist +*/ diff --git a/doc/src/declarative/qmlstates.qdoc b/doc/src/declarative/qmlstates.qdoc new file mode 100644 index 0000000..261e3f5 --- /dev/null +++ b/doc/src/declarative/qmlstates.qdoc @@ -0,0 +1,60 @@ +/*! +\page qmlstates.html +\target qmlstates +\title QML States + +QML states describe user interface configurations, including: +\list +\o What UI elements are present +\o The properties of those elements (including how they behave) +\o What actions are available +\endlist + +A state can also be thought of as a set of batched changes from a default configuration. + +Examples of states in modern UI: +\list +\o A Contacts application has a 'View Contact' state and an 'Edit Contact' State. In the first state the information presented is static (using labels), and in the second it is editable (using editors). +\o A button has a pressed and unpressed state. When pressed the text moves down and to the right, and the button has a slightly darker appearance. +\endlist + +In QML: +\list +\o Any object can use states. +\o There is a default state. The default state can be explicitly set. +\o A state can affect the properties of other objects, not just the object owning the state (and not just that object's children). +\endlist + +The following example shows a simple use of states. In the default state \c myrect is positioned at 0,0. In the 'moved' state it is positioned at 50,50. + +\code +Item { + Rectangle { + id: myrect + width: 100 + height: 100 + } + states: [ + State { + name: "moved" + PropertyChanges { + target: myrect + x: 50 + y: 50 + } + } + ] +} +\endcode + +To animate state changes, you can use \l{state-transitions}{transitions}. + +Other things you can do in a state change: +\list +\o override signal handlers with PropertyChanges +\o change an item's parent with ParentChange +\o change an item's anchors with AnchorChanges +\o run some script with StateChangeScript +\endlist + +*/ diff --git a/doc/src/declarative/qmlviewer.qdoc b/doc/src/declarative/qmlviewer.qdoc new file mode 100644 index 0000000..f153df2 --- /dev/null +++ b/doc/src/declarative/qmlviewer.qdoc @@ -0,0 +1,78 @@ +/**************************************************************************** +** +** 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 qmlviewer.html + \title Qt Declarative UI Viewer (qmlviewer) + \ingroup qttools + \keyword qmlviewer + + This page documents the \e{Declarative UI Viewer} for the Qt GUI + toolkit. The \c qmlviewer reads a declarative user interface definition + (\c .qml) file and displays the user interface it describes. + + qmlviewer is a development tool. It is not intended to be + installed in a production environment. + + \section1 Options + + When run with the \c -help option, qmlviewer shows available options. + + \section1 Dummy Data + + One use of qmlviewer is to allow QML files to be viewed stand-alone, + rather than being loaded from within a Qt program. Qt applications will + usually bind objects and properties into the execution context before + running the QML. To stand-in for such bindings, you can provide dummy + data: create a directory called "dummydata" in the same directory as + the target QML file and create files there with the "qml" extension. + All such files will be loaded as QML objects and bound to the root + context as a property with the name of the file (without ".qml"). + + For example, if the Qt application has a "clock.time" property + that is a qreal from 0 to 86400 representing the number of seconds since + midnight, dummy data for this could be provided by \c dummydata/clock.qml: + \code + Object { property real time: 12345 } + \endcode + Any QML can be used in the dummy data files. You could even animate the + fictional data! +*/ diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc new file mode 100644 index 0000000..61520f7 --- /dev/null +++ b/doc/src/declarative/qtbinding.qdoc @@ -0,0 +1,262 @@ +/**************************************************************************** +** +** 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 qtbinding.html +\target qtbinding +\title Using QML in C++ Applications + +\tableofcontents + +The QML API is split into three main classes - QmlEngine, QmlComponent and QmlContext. +QmlEngine provides the environment in which QML is run, QmlComponent encapsulates +\l {QML Documents}, and QmlContext allows applications to expose data to QML component instances. + +QML also includes a convenience API, QmlView, for applications that simply want to embed QML +components into a new QGraphicsView. QmlView covers up many of the details discussed below. +While QmlView is mainly intended for rapid prototyping it can have uses in production applications. + +\section1 Basic Usage + +Every application requires at least one QmlEngine. A QmlEngine allows the configuration of +global settings that apply to all the QML component instances - such as the QNetworkAccessManager +that is used for network communications, and the path used for persistent storage. +Multiple QmlEngine's are only needed if the application requires these settings to differ +between QML component instances. + +\l {QML Documents} are loaded using the QmlComponent class. Each QmlComponent instance +represents a single QML document. A QmlComponent can be passed a document URL, or raw text +representing the content of the document. The document URL can be a local filesystem URL, or +any network URL supported by QNetworkAccessManager. + +QML component instances can then be created by calling the QmlComponent::create() method. Here's +an example of loading a QML document, and creating an object from it. + +\code +QmlEngine *engine = new QmlEngine(parent); +QmlComponent component(engine, QUrl("main.qml")); +QObject *myObject = component.create(); +\endcode + +\section1 Exposing Data + +QML components are instantiated in a QmlContext. A context allows the application to expose data +to the QML component instance. A single QmlContext can be used to instantiate all the objects +used by an application, or several QmlContext can be created for more fine grained control over +the data exposed to each instance. If a context is not passed to the QmlComponent::create() +method, the QmlEngine's \l {QmlEngine::rootContext()}{root context} is used. Data exposed through +the root context is available to all object instances. + +\section1 Simple Data + +To expose data to a QML component instance, applications set \l {QmlContext::setContextProperty()} +{context properties} which are then accessible by name from QML \l {Property Binding}s and +\l {ECMAScript Blocks}. The following example shows how to expose a background color to a QML +file. + +\table +\row +\o +\code +// main.cpp +QmlContext *windowContext = new QmlContext(engine->rootContext()); +windowContext->setContextProperty("backgroundColor", + QColor(Qt::lightsteelblue)); + +QmlComponent component(&engine, "main.qml"); +QObject *window = component.create(windowContext); +\endcode +\o +\code +// main.qml +import Qt 4.6 + +Rectangle { + color: backgroundColor + + Text { + anchors.centerIn: parent + text: "Hello Light Steel Blue World!" + } +} +\endcode +\endtable + +Context properties work just like normal properties in QML bindings - if the \c backgroundColor +context property in the previous example was changed to red, the component object instances would +all be automatically updated. + +QmlContexts form a tree - each QmlContext except for the root context has a parent. Child +QmlContexts effectively inherit the context properties present in their parents. This gives +applications more freedom in partitioning the data exposed to different QML object instances. +If a QmlContext sets a context property that is also set in one of its parents, the new context +property shadows that in the parent. In The following example, the \c background context property +in \c {Context 1} shadows the \c background context property in the root context. + +\image qml-context-tree.png + +\section2 Structured Data + +Context properties can also be used to expose structured and writable data to QML objects. In +addition to all the types already supported by QVariant, QObject derived types can be assigned to +context properties. QObject context properties allow the data exposed to be more structured, and +allow QML to set values. + +The following example creates a \c CustomPalette object, and sets it as the \c palette context +property. + +\code +class CustomPalette : public QObject +{ +Q_OBJECT +Q_PROPERTY(QColor background READ background WRITE setBackground NOTIFY backgroundChanged) +Q_PROPERTY(QColor text READ text WRITE setText NOTIFY text) +public: + CustomPalette() : m_background(Qt::white), m_text(Qt::black) {} + + QColor background() const { return m_background; } + void setBackground(const QColor &c) { + if (c != m_background) { + m_background = c; + emit backgroundChanged(); + } + } + + QColor text() const { return m_text; } + void setText(const QColor &c) { + if (c != m_text) { + m_text = c; + emit textChanged(); + } + } +private: + QColor m_background; + QColor m_text; +}; + +int main(int argc, char **argv) +{ + // ... + + QmlContext *windowContext = new QmlContext(engine->rootContext()); + windowContext->setContextProperty("palette", new CustomPalette); + + QmlComponent component(&engine, "main.qml"); + QObject *window = component.create(windowContext); +} +\endcode + +The QML that follows references the palette object, and its properties, to set the appropriate +background and text colors. When the window is clicked, the palette's text color is changed, and +the window text will update accordingly. + +\code +// main.qml +import Qt 4.6 + +Rectangle { + width: 240 + height: 320 + color: palette.background + + Text { + anchors.centerIn: parent + color: palette.text + text: "Hello Colorful World!" + } + + MouseRegion { + anchors.fill: parent + onClicked: { + palette.text = "blue"; + } + } +} +\endcode + +To detect when a C++ property value - in this case the \c CustomPalette's \c text property - +changes, the property must have a corresponding NOTIFY signal. The NOTIFY signal specifies a signal +that is emitted whenever the property changes value. Implementers should take care to only emit the +signal if the value \e changes to prevent loops from occuring. Accessing a property from a +binding that does not have a NOTIFY signal will cause QML to issue a warning at runtime. + +\section2 Dynamic Structured Data + +If an application is too dynamic to structure data as compile-time QObject types, dynamically +structured data can be constructed at runtime using the QmlPropertyMap class. + +\section1 Network Components + +If the URL passed to QmlComponent is a network resource, or if the QML document references a +network resource, the QmlComponent has to fetch the network data before it is able to create +objects. In this case, the QmlComponent will have a \l {QmlComponent::Loading}{Loading} +\l {QmlComponent::status()}{status}. An application will have to wait until the component +is \l {QmlComponent::Ready}{Ready} before calling \l {QmlComponent::create()}. + +The following example shows how to load a QML file from a network resource. After creating +the QmlComponent, it tests whether the component is loading. If it is, it connects to the +QmlComponent::statusChanged() signal and otherwise calls the \c {continueLoading()} method +directly. This test is necessary, even for URLs that are known to be remote, just in case +the component has been cached and is ready immediately. + +\code +MyApplication::MyApplication() +{ + // ... + component = new QmlComponent(engine, QUrl("http://www.example.com/main.qml")); + if (component->isLoading()) + QObject::connect(component, SIGNAL(statusChanged(QmlComponent::Status)), + this, SLOT(continueLoading())); + else + continueLoading(); +} + +void MyApplication::continueLoading() +{ + if (component->isError()) { + qWarning() << component->errors(); + } else { + QObject *myObject = component->create(); + } +} +\endcode +*/ + diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc new file mode 100644 index 0000000..ea8e198 --- /dev/null +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -0,0 +1,104 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\module QtDeclarative +\title QtDeclarative Module +\ingroup modules + +\brief The Qt Declarative module provides a declarative framework for building +highly dynamic, custom UIs + +Qt Declarative aids programmers and designers in building the animation rich, +highly fluid user interfaces that are becoming common in portable consumer +electronics devices, such as mobile phones, media players, set-top boxes and +netbooks. The Qt Declarative module provides an engine for interpreting the +declarative QML language, and a rich set of \l {QML Elements} that can be used +from QML. + +QML is an extension to \l {http://www.ecma-international.org/publications/standards/Ecma-262.htm} +{ECMAScript}, that provides a mechanism to declaratively build an object tree +of \l {QML Elements}. QML improves the integration between ECMAScript and Qt's +existing QObject based type system, adds support for automatic +\l {Property Binding}s and provides \l {Network Transparency} at the language +level. + +The \l {QML Elements} are a sophisticated set of graphical and behavioral building +blocks. \l {QML Elements} are combined together in \l {QML Documents} to build components +ranging in complexity from simple pushbuttons and sliders, to complete +internet-enabled applications like a \l {http://www.flickr.com}{flickr} photo browser. + +Qt Declarative builds on \l {QML for Qt programmers}{Qt's existing strengths}. +QML can be be used to incrementally extend an existing application or to build +completely new applications. QML is fully \l {Extending QML}{extensible from C++}. + +\section1 Getting Started: +\list +\o \l {Introduction to the QML language} +\o \l {Tutorial}{Tutorial: 'Hello World'} +\o \l {advtutorial.html}{Tutorial: 'Same Game'} +\o \l {QML Examples and Walkthroughs} +\o \l {Using QML in C++ Applications} +\endlist + +\section1 Core QML Features: +\list +\o \l {QML Documents} +\o \l {Property Binding} +\o \l {ECMAScript Blocks} +\o \l {QML Scope} +\o \l {Network Transparency} +\o \l {qmlmodels}{Data Models} +\o \l {anchor-layout}{Anchor-based Layout} +\o \l {qmlstates}{States} +\o \l {qmlanimation.html}{Animation} +\o \l {qmlmodules.html}{Modules} +\o \l {qmlfocus}{Keyboard Focus} +\o \l {Extending types from QML} +\endlist + +\section1 Reference: +\list +\o \l {QML Elements} +\o \l {QML Global Object} +\o \l {Extending QML} +\endlist +*/ diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc new file mode 100644 index 0000000..7b1ab44 --- /dev/null +++ b/doc/src/declarative/qtprogrammers.qdoc @@ -0,0 +1,162 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + + INCOMPLETE + +\page qtprogrammers.html +\target qtprogrammers +\title QML for Qt programmers + +\section1 Overview + +While QML does not require Qt knowledge to use, if you \e are already familar with Qt, +much of your knowledge is directly relevant to learning and using QML. Of course, +an application with a UI defined in QML also uses Qt for all the non-UI logic. + +\section1 Familiar Concepts + +QML provides direct access to the following concepts from Qt: + +\list + \o QAction - the \l {basicqmlaction}{action} type + \o QObject signals and slots - available as functions to call in JavaScript + \o QObject properties - available as variables in JavaScript + \o QWidget - QmlView is a QML-displaying widget + \o Qt models - used directly in data binding (QAbstractItemModel and next generation QListModelInterface) +\endlist + +Qt knowledge is \e required for \l {Extending QML}. + +\section1 QML Items compared with QWidgets + +QML Items are very similar to QWidgets: they define the look and feel of the user interface. (Note that while QWidgets +haven't traditionally been used to define the look and feel of view delegates, QML Items can be used for this as well.) + +There are three structurally different types of QWidget: + +\list + \o Simple widgets that are not used as parents (QLabel, QCheckBox, QToolButton, etc.) + \o Parent widgets that are normally used as parents to other widgets (QGroupBox, QStackedWidget, QTabWidget, etc.) + \o Compound widgets that are internally composed of child widgets (QComboBox, QSpinBox, QFileDialog, QTabWidget, etc.) +\endlist + +QML Items also serve these purposes. Each is considered separately below. + +\section2 Simple Widgets + +The most important rule to remember while implementing a new QmlGraphicsItem in C++ +is that it should not contain any look and feel policies - leave that to the +QML usage of the item. + +As an example, imagine you wanted a reusable Button item. If you therefore +decided to write a QmlGraphicsItem subclass to implement a button, +just as QToolButton subclasses QWidget for this purpose, following the rule above, your +\c QmlGraphicsButton would not have any appearance - just the notions of enabled, triggering, etc. + +But there is already an object in Qt that does this: QAction. + +QAction is the UI-agnostic essence of QPushButton, QCheckBox, QMenu items, QToolButton, +and other visual widgets that are commonly bound to a QAction. + +So, the job of implementing a checkbox abstraction for QML is already done - it's QAction. +The look and feel of an action - the appearance of the button, the transition between states, +and exactly how it respond to mouse, key, or touch input, should all be left for definition +in QML. + +It is illustrative to note that QmlGraphicsTextEdit is built upon QTextControl, +QmlGraphicsWebView is built upon QWebPage, and ListView uses QListModelInterface, +just as QTextEdit, QWebView, and QListView are built upon +those same UI-agnostic components. + +The encapsulation of the look and feel that QWidgets gives is important, and for this +the QML concept of \l {qmldocuments.html}{components} serves the same purpose. If you are building a complete +suite of applications which should have a consistent look and feel, you should build +a set of reusable components with the look and feel you desire. + +So, to implement your reusable button, you would simply build a QML component. + + +\section2 Parent Widgets + +Parent widgets each provide a generic way to interface to one or more arbitrary other widgets. +A QTabWidget provides an interface to multiple "pages", one of which is visible at any time, +and a mechnism for selecting among them (the QTabBar). A QScollArea provides scrollbars around +a widget that is otherwise too large to fit in available space. + +Nearly all such components can be created directly in QML. Only a few cases +which require very particular event handling, such as Flickable, require C++ implementations. + +As an example, imagine you decided to make a generic tab widget item to be used +through your application suite wherever information is in such quantity that it +needs to be divided up into pages. + +A significant difference in the parenting concept with QML compare to QWidgets +is that while child items are positioned relative to their parents, +there is no requirement that they be wholy contained ("clipped") to +the parent (although the clipped property of the child Item does allow +this where it is needed). +This difference has rather far-reaching consequences, for example: + +\list + \o A shadow or highlight around a widget could be a child of that widget. + \o Particle effects can flow outside the object where they originate. + \o Transitioning animations can "hide" items by visibly moving them beyond the screen bounds. +\endlist + + +\section2 Compound Widgets + +Some widgets provide functionality by composing other widgets as an "implementation detail", +providing a higher level API to the composition. QSpinBox for example is a line edit and some +buttons to increase/decrease the edited value. QFileDialog uses a whole host of widgets to +give the user a way of finding and selecting a file name. + +When developing reusable QML Items, you may choose to do the same: build an item composed +of other items you have already defined. + +The only caveat when doing this is to consider the possible animations and transitions that +users of the compound item might wish to employ. For example, a spinbox might need to smoothly +transition from an arbitrary Text item, or characters within a Text item, so your spinbox +item would need to be sufficiently flexible to allow such animation. + +*/ diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc new file mode 100644 index 0000000..fc678d1 --- /dev/null +++ b/doc/src/declarative/scope.qdoc @@ -0,0 +1,378 @@ +/**************************************************************************** +** +** 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 qmlscope.html +\title QML Scope + +\l {Property Binding}s and \l {ECMAScript Blocks} are executed in a scope chain automatically +established by QML when constructing a component instance. QML is a \e {dynamically scoped} +language. Different object instances instantiated from the same component can exist in +different scope chains. + +\image qml-scope.png + +\section1 ECMAScript Variable object + +Each binding and script block has its own distinct ECMAScript variable object where local +variables are stored. That is, local variables from different bindings and script blocks never +conflict. + +\section1 Element Type Names + +Bindings or script blocks use element type names when accessing \l {Attached Properties} or +enumeration values. The set of available element names is defined by the import list of the +\l {QML Documents}{QML Document} in which the the binding or script block is defined. + +These two examples show how to access attached properties and enumeration values with different +types of import statements. +\table +\row +\o +\code +import Qt 4.6 + +Text { + id: root + scale: root.PathView.scale + horizontalAlignment: Text.AlignLeft +} +\endcode +\o +\code +import Qt 4.6 as MyQt + +Text { + id: root + scale: root.MyQt.PathView.scale + horizontalAlignment: MyQt.Text.AlignLeft +} +\endcode +\endtable + +\section1 QML Local Scope + +Most variables references are resolved in the local scope. The local scope is controlled by the +QML component in which the binding or script block was declarated. The following example shows +three different bindings, and the component that dictates their local scope. + +\table +\row +\o +\code +// main.qml +import Qt 4.6 + +Rectangle { // Local scope component for binding 1 + id: root + property string text + + Button { + text: root.text // binding 1 + } + + ListView { + delegate: Component { // Local scope component for binding 2 + Rectangle { + width: ListView.view.width // binding 2 + } + } + } + +} +\endcode +\o +\code +// Button.qml +import Qt 4.6 + +Rectangle { // Local scope component for binding 3 + id: root + property string text + + Text { + text: root.text // binding 3 + } +} +\endcode +\endtable + +Inside the local scope, four "sub-scopes" exist. Each "sub-scope" is searched in order when +resolving a name - names in a higher "sub-scopes" shadow those in lower sub-scopes. + +\section2 IDs + +IDs present in the component take precendence over other names. The QML engine enforces +uniqueness of IDs within a component, so their names cannot conflict with one another. + +This is an example of using IDs within bindings. + +\code +Item { + id: root + width: nested.width + Item { + id: nested + height: root.height + } +} +\endcode + +\section2 Script Methods + +Methods declared in script blocks are searched immediately after IDs. In the case of multiple +script blocks in the one component, the blocks are searched in the order in which they were +declared - the nesting of script blocks within a component is not significant for name +resolution. + +In the following example, \c {Method 1} shadows \c {Method 2} for the bindings, but not for +\c {Method 3}. + +\code +Item { + Script { + function getValue() { return 10; } // Method 1 + } + + Rectangle { + Script { + function getValue() { return 11; } // Method 2 + function getValue2() { return getValue(); } // Method 3 + } + + x: getValue() // Resolves to Method 1, set to 10 + y: getValue2() // Resolves to Method 3, set to 11 + } +} +\endcode + +\section2 Scope Object + +A scope object is associated with each binding and script block. Properties and methods of the +scope object appear in the scope chain, immediately after \l {Script Methods}. + +In bindings and script blocks established explicitly in \l {QML Documents}, the scope object is +always the element containing the binding or script block. The following example shows two +bindings, one using grouped properties, and the corresponding scope object. These two bindings +use the scope object to resolve variable references - \c height is a property on \l Rectangle, +and \c parent is a property on \l Text. + +\code +Item { // Scope object for Script block 1 + Script { // Script block 1 + function calculateValue() { ... } + } + + Rectangle { // Scope object for Binding 1 and Script block 2 + Script { // Script block 2 + function calculateColor() { ... } + } + width: height * 2 // Binding 1 + } + + Text { // Scope object for Binding 2 + font.pixelSize: parent.height * 0.7 // binding 2 + } +} +\endcode + +One notable characteristic of the scope object is its interaction with \l {Attached Properties}. +As attached properties exist on all objects, an attached property reference that is not +explicitly prefixed by an id will \e always resolve to the attached property on the scope +object. + +In the following example, \c {Binding 1} will resolve to the attached properties of the +\l Rectangle element, as intended. However, due to the property search of the scope object, +\c {Binding 2} will resolve to the attached properties of the \l Text element, which +is probably not what was intended. This code can be corrected, by replacing \c {Binding 2} +with this explicit element reference \c {root.ListView.view.width}. + +\code +import Qt 4.6 + +ListView { + delegate: Rectangle { + id: root + width: ListView.view.width // Binding 1 + Text { + text: contactName + width: ListView.view.width // Binding 2 + } + } +} +\endcode + +\e TODO + +\list +\o scope object for PropertyChanges +\endlist + +\section2 Root Object + +Properties and methods on the local scope component's root object appear in the scope chain +immediately after the \l {Scope Object}. If the scope object and root object are the same, +this step has no effect. + +This example uses the root object to easily propagate data throughout the component. + +\code +Item { + property string description + property int fontSize + + Text { + text: description + font.pixelSize: fontSize + } +} +\endcode + +\section1 QML Component chain + +When a QML component is instantiated it is given a parent component instance. The parent +component instance is immutable - it is not effected, for example, by changes in the instance's +visual parent (in the case of visual elements). Should name resolution fail within the +\l {QML Local Scope}, this parent chain is searched. + +For each component instance in the chain, the following are examined: + +\list 1 +\o IDs +\o Script Methods +\o Root Object +\endlist + +This list is a sub-set of that in the \l {QML Local Scope}. + +Sub-components used within a component have their parent component instance set to the component +instance that created them. In the following example, the two \c Button instances have the +\c main.qml instance as their parent component instance. If the \c Button type was used from +within another QML file, it may have a difference parent component instance, and consequently +the \c buttonClicked() method may resolve differently. + +\table +\row +\o +\code +// main.qml +Item { + function buttonClicked(var data) { + print(data + " clicked"); + } + + Button { text: "Button1" } + Button { text: "Button2" } +} +\endcode +\o +\code +// Button.qml +Rectangle { + id: root + property string text + width: 80 + height: 30 + Text { + anchors.centerIn: parent + text: root.text + } + MouseRegion { + anchors.fill: parent + onClicked: buttonClicked(text) + } +} +\endcode +\endtable + +The code above discourages the re-use of the \c Button component, as it has a hard dependency +on the environment in which it is used. Tightly coupling two types together like this should +only be used when the components are within the same module, and the author controls the +implementations of both. + +In the following example, the \l ListView sets the parent component instance of each of its +delegates to its own component instance. In this way, the main component can easily pass data +into the \l ListView delegates. + +\code +Item { + property color delegateColor: "red" + + ListView { + delegate: Component { + Rectangle { + color: delegateColor + } + } + } +} +\endcode + +\section1 QmlContext chain + +The \l QmlContext chain allows C++ applications to pass data into QML applications. +\l QmlComponent object instances created from C++ are passed a \l QmlContext in which they +are created. Variables defined in this context appear in the scope chain. Each QmlContext +also defines a parent context. Variables in child QmlContext's shadow those in its parent. + +Consider the following QmlContext tree. + +\image qml-context-tree.png + +The value of \c background in \c {Context 1} would be used if it was instantiated in +\c {Context 1}, where as the value of the \c background in the root context would be used if +the component instance was instantiated in \c {Context 2}. + +\code +import Qt 4.6 + +Rectangle { + id: myRect + width: 100; height: 100 + color: background +} +\endcode + +\section1 QML Global Object + +The \l {QML Global Object} contains all the properties of the ECMAScript global object, plus some +QML specific extensions. +*/ diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc new file mode 100644 index 0000000..19921c0 --- /dev/null +++ b/doc/src/declarative/tutorial.qdoc @@ -0,0 +1,23 @@ +/*! +\page tutorial.html +\title Tutorial + +This tutorial gives an introduction to QML. It doesn't cover everything; the emphasis is on teaching the key principles, +and features are introduced as needed. + +Through the different steps of this tutorial we will learn about QML basic types, we will create our own QML component +with properties and signals, and we will create a simple animation with the help of states and transitions. + +Chapter one starts with a minimal "Hello world" program and the following chapters introduce new concepts. + +The tutorial's source code is located in the $QTDIR/examples/declarative/tutorials/helloworld directory. + +Tutorial chapters: + +\list +\o \l {Tutorial 1 - Basic Types} +\o \l {Tutorial 2 - QML Component} +\o \l {Tutorial 3 - States and Transitions} +\endlist + +*/ diff --git a/doc/src/declarative/tutorial1.qdoc b/doc/src/declarative/tutorial1.qdoc new file mode 100644 index 0000000..f7e44b0 --- /dev/null +++ b/doc/src/declarative/tutorial1.qdoc @@ -0,0 +1,56 @@ +/*! +\page tutorial1.html +\title Tutorial 1 - Basic Types + +This first program is a very simple "Hello world" example that introduces some basic QML concepts. +The picture below is a screenshot of this program. + +\image declarative-tutorial1.png + +Here is the QML code for the application: + +\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 0 + +\section1 Walkthrough + +\section2 Import + +First, we need to import the types that we need for this example. Most QML files will import the built-in QML +types (like \l{Rectangle}, \l{Image}, ...) that come with Qt with: + +\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 3 + +\section2 Rectangle element + +\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 1 + +We declare a root element of type \l{Rectangle}. It is one of the basic building blocks you can use to create an application in QML. +We give it an \c{id} to be able to refer to it later. In this case, we call it \e page. +We also set the \c width, \c height and \c color properties. +The \l{Rectangle} element contains many other properties (such as \c x and \c y), but these are left at their default values. + +\section2 Text element + +\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 2 + +We add a \l Text element as a child of our root element that will display the text 'Hello world!'. + +The \c y property is used to position the text vertically at 30 pixels from the top of its parent. + +The \c font.pointSize and \c font.bold properties are related to fonts and use the \l{Dot Properties}{dot notation}. + +The \c anchors.horizontalCenter property refers to the horizontal center of an element. +In this case, we specify that our text element should be horizontally centered in the \e page element (see \l{anchor-layout}{Anchor-based Layout}). + +\section2 Viewing the example + +To view what you have created, run the qmlviewer (located in the \c bin directory) with your filename as the first argument. +For example, to run the provided completed Tutorial 1 example from the install location, you would type: + +\code +bin/qmlviewer $QTDIR/examples/declarative/tutorials/helloworld/tutorial1.qml +\endcode + +[\l {Tutorial}] [Next: \l {Tutorial 2 - QML Component}] + +*/ diff --git a/doc/src/declarative/tutorial2.qdoc b/doc/src/declarative/tutorial2.qdoc new file mode 100644 index 0000000..dd0d428 --- /dev/null +++ b/doc/src/declarative/tutorial2.qdoc @@ -0,0 +1,71 @@ +/*! +\page tutorial2.html +\title Tutorial 2 - QML Component + +This chapter adds a color picker to change the color of the text. + +\image declarative-tutorial2.png + +Our color picker is made of six cells with different colors. +To avoid writing the same code multiple times, we first create a new \c Cell component. +A component provides a way of defining a new type that we can re-use in other QML files. +A QML component is like a black-box and interacts with the outside world through properties, signals and slots and is generally +defined in its own QML file (for more details, see \l {Defining new Components}). +The component's filename must always start with a capital letter. + +Here is the QML code for \c Cell.qml: + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 0 + +\section1 Walkthrough + +\section2 The Cell Component + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 1 + +The root element of our component is an \l Item with the \c id \e container. +An \l Item is the most basic visual element in QML and is often used as a container for other elements. + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 4 + +We declare a \c color property. This property is accessible from \e outside our component, this allows us +to instantiate the cells with different colors. +This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{intro-properties}{Properties}). + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 5 + +We want our component to also have a signal that we call \e clicked with a \e color parameter. +We will use this signal to change the color of the text in the main QML file later. + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 2 + +Our cell component is basically a colored rectangle with the \c id \e rectangle. + +The \c anchors.fill property is a convenient way to set the size of an element. +In this case the rectangle will have the same size as its parent (see \l{anchor-layout}{Anchor-based Layout}). + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 3 + +In order to change the color of the text when clicking on a cell, we create a \l MouseRegion element with +the same size as its parent. + +A \l MouseRegion defines a signal called \e clicked. +When this signal is triggered we want to emit our own \e clicked signal with the color as parameter. + +\section2 The main QML file + +In our main QML file, we use our \c Cell component to create the color picker: + +\snippet examples/declarative/tutorials/helloworld/tutorial2.qml 0 + +We create the color picker by putting 6 cells with different colors in a grid. + +\snippet examples/declarative/tutorials/helloworld/tutorial2.qml 1 + +When the \e clicked signal of our cell is triggered, we want to set the color of the text to the color passed as a parameter. +We can react to any signal of our component through a property of the name \e 'onSignalName' (see \l{Signal Handlers}). + +[Previous: \l {Tutorial 1 - Basic Types}] [Next: \l {Tutorial 3 - States and Transitions}] + +*/ + diff --git a/doc/src/declarative/tutorial3.qdoc b/doc/src/declarative/tutorial3.qdoc new file mode 100644 index 0000000..290b535 --- /dev/null +++ b/doc/src/declarative/tutorial3.qdoc @@ -0,0 +1,45 @@ +/*! +\page tutorial3.html +\title Tutorial 3 - States and Transitions + +In this chapter, we make this example a little bit more dynamic by introducing states and transitions. + +We want our text to move to the bottom of the screen, rotate and become red when clicked. + +\image declarative-tutorial3_animation.gif + +Here is the QML code: + +\snippet examples/declarative/tutorials/helloworld/tutorial3.qml 0 + +\section1 Walkthrough + +\snippet examples/declarative/tutorials/helloworld/tutorial3.qml 2 + +First, we create a new \e down state for our text element. +This state will be activated when the \l MouseRegion is pressed, and deactivated when it is released. + +The \e down state includes a set of property changes from our implicit \e {default state} +(the items as they were initially defined in the QML). +Specifically, we set the \c y property of the text to \c 160, the rotation to \c 180 and the \c color to red. + +\snippet examples/declarative/tutorials/helloworld/tutorial3.qml 3 + +Because we don't want the text to appear at the bottom instantly but rather move smoothly, +we add a transition between our two states. + +\c from and \c to define the states between which the transition will run. +In this case, we want a transition from the default state to our \e down state. + +Because we want the same transition to be run in reverse when changing back from the \e down state to the default state, +we set \c reversible to \c true. +This is equivalent to writing the two transitions separately. + +The \l ParallelAnimation element makes sure that the two types of animations (number and color) start at the same time. +We could also run them one after the other by using \l SequentialAnimation instead. + +For more details on states and transitions, see \l {QML States}. + +[Previous: \l {Tutorial 2 - QML Component}] [\l {Tutorial}] + +*/ diff --git a/doc/src/images/declarative-anchors_example.png b/doc/src/images/declarative-anchors_example.png Binary files differnew file mode 100644 index 0000000..293cd4b --- /dev/null +++ b/doc/src/images/declarative-anchors_example.png diff --git a/doc/src/images/declarative-anchors_example2.png b/doc/src/images/declarative-anchors_example2.png Binary files differnew file mode 100644 index 0000000..6d3be7d --- /dev/null +++ b/doc/src/images/declarative-anchors_example2.png diff --git a/doc/src/images/declarative-image_fillMode.gif b/doc/src/images/declarative-image_fillMode.gif Binary files differnew file mode 100644 index 0000000..eb0a9af --- /dev/null +++ b/doc/src/images/declarative-image_fillMode.gif diff --git a/doc/src/images/declarative-image_tile.png b/doc/src/images/declarative-image_tile.png Binary files differnew file mode 100644 index 0000000..b946a6d --- /dev/null +++ b/doc/src/images/declarative-image_tile.png diff --git a/doc/src/images/declarative-item_opacity1.png b/doc/src/images/declarative-item_opacity1.png Binary files differnew file mode 100644 index 0000000..cde973b --- /dev/null +++ b/doc/src/images/declarative-item_opacity1.png diff --git a/doc/src/images/declarative-item_opacity2.png b/doc/src/images/declarative-item_opacity2.png Binary files differnew file mode 100644 index 0000000..8627360 --- /dev/null +++ b/doc/src/images/declarative-item_opacity2.png diff --git a/doc/src/images/declarative-item_stacking1.png b/doc/src/images/declarative-item_stacking1.png Binary files differnew file mode 100644 index 0000000..18f4148 --- /dev/null +++ b/doc/src/images/declarative-item_stacking1.png diff --git a/doc/src/images/declarative-item_stacking2.png b/doc/src/images/declarative-item_stacking2.png Binary files differnew file mode 100644 index 0000000..7a71bcd --- /dev/null +++ b/doc/src/images/declarative-item_stacking2.png diff --git a/doc/src/images/declarative-item_stacking3.png b/doc/src/images/declarative-item_stacking3.png Binary files differnew file mode 100644 index 0000000..cde973b --- /dev/null +++ b/doc/src/images/declarative-item_stacking3.png diff --git a/doc/src/images/declarative-item_stacking4.png b/doc/src/images/declarative-item_stacking4.png Binary files differnew file mode 100644 index 0000000..3fdf627 --- /dev/null +++ b/doc/src/images/declarative-item_stacking4.png diff --git a/doc/src/images/declarative-nopercent.png b/doc/src/images/declarative-nopercent.png Binary files differnew file mode 100644 index 0000000..28b00a9 --- /dev/null +++ b/doc/src/images/declarative-nopercent.png diff --git a/doc/src/images/declarative-pathattribute.png b/doc/src/images/declarative-pathattribute.png Binary files differnew file mode 100644 index 0000000..57cd049 --- /dev/null +++ b/doc/src/images/declarative-pathattribute.png diff --git a/doc/src/images/declarative-pathcubic.png b/doc/src/images/declarative-pathcubic.png Binary files differnew file mode 100644 index 0000000..ffbca5d --- /dev/null +++ b/doc/src/images/declarative-pathcubic.png diff --git a/doc/src/images/declarative-pathquad.png b/doc/src/images/declarative-pathquad.png Binary files differnew file mode 100644 index 0000000..65f1999 --- /dev/null +++ b/doc/src/images/declarative-pathquad.png diff --git a/doc/src/images/declarative-percent.png b/doc/src/images/declarative-percent.png Binary files differnew file mode 100644 index 0000000..c277055 --- /dev/null +++ b/doc/src/images/declarative-percent.png diff --git a/doc/src/images/declarative-qtlogo1.png b/doc/src/images/declarative-qtlogo1.png Binary files differnew file mode 100644 index 0000000..940d159 --- /dev/null +++ b/doc/src/images/declarative-qtlogo1.png diff --git a/doc/src/images/declarative-qtlogo2.png b/doc/src/images/declarative-qtlogo2.png Binary files differnew file mode 100644 index 0000000..b1d128a --- /dev/null +++ b/doc/src/images/declarative-qtlogo2.png diff --git a/doc/src/images/declarative-qtlogo3.png b/doc/src/images/declarative-qtlogo3.png Binary files differnew file mode 100644 index 0000000..d516524 --- /dev/null +++ b/doc/src/images/declarative-qtlogo3.png diff --git a/doc/src/images/declarative-qtlogo4.png b/doc/src/images/declarative-qtlogo4.png Binary files differnew file mode 100644 index 0000000..7c8aa64 --- /dev/null +++ b/doc/src/images/declarative-qtlogo4.png diff --git a/doc/src/images/declarative-qtlogo5.png b/doc/src/images/declarative-qtlogo5.png Binary files differnew file mode 100644 index 0000000..b7b3513 --- /dev/null +++ b/doc/src/images/declarative-qtlogo5.png diff --git a/doc/src/images/declarative-qtlogo6.png b/doc/src/images/declarative-qtlogo6.png Binary files differnew file mode 100644 index 0000000..07a078f --- /dev/null +++ b/doc/src/images/declarative-qtlogo6.png diff --git a/doc/src/images/declarative-rect.png b/doc/src/images/declarative-rect.png Binary files differnew file mode 100644 index 0000000..173759a --- /dev/null +++ b/doc/src/images/declarative-rect.png diff --git a/doc/src/images/declarative-rect_gradient.png b/doc/src/images/declarative-rect_gradient.png Binary files differnew file mode 100644 index 0000000..f79d579 --- /dev/null +++ b/doc/src/images/declarative-rect_gradient.png diff --git a/doc/src/images/declarative-rect_tint.png b/doc/src/images/declarative-rect_tint.png Binary files differnew file mode 100644 index 0000000..3a44013 --- /dev/null +++ b/doc/src/images/declarative-rect_tint.png diff --git a/doc/src/images/declarative-removebutton-close.png b/doc/src/images/declarative-removebutton-close.png Binary files differnew file mode 100644 index 0000000..d73f8e1 --- /dev/null +++ b/doc/src/images/declarative-removebutton-close.png diff --git a/doc/src/images/declarative-removebutton-open.png b/doc/src/images/declarative-removebutton-open.png Binary files differnew file mode 100644 index 0000000..b54d797 --- /dev/null +++ b/doc/src/images/declarative-removebutton-open.png diff --git a/doc/src/images/declarative-removebutton.gif b/doc/src/images/declarative-removebutton.gif Binary files differnew file mode 100644 index 0000000..ca4d7e6 --- /dev/null +++ b/doc/src/images/declarative-removebutton.gif diff --git a/doc/src/images/declarative-removebutton.png b/doc/src/images/declarative-removebutton.png Binary files differnew file mode 100644 index 0000000..f783e6a --- /dev/null +++ b/doc/src/images/declarative-removebutton.png diff --git a/doc/src/images/declarative-reuse-1.png b/doc/src/images/declarative-reuse-1.png Binary files differnew file mode 100644 index 0000000..c704457 --- /dev/null +++ b/doc/src/images/declarative-reuse-1.png diff --git a/doc/src/images/declarative-reuse-2.png b/doc/src/images/declarative-reuse-2.png Binary files differnew file mode 100644 index 0000000..0b6006b --- /dev/null +++ b/doc/src/images/declarative-reuse-2.png diff --git a/doc/src/images/declarative-reuse-3.png b/doc/src/images/declarative-reuse-3.png Binary files differnew file mode 100644 index 0000000..695a725 --- /dev/null +++ b/doc/src/images/declarative-reuse-3.png diff --git a/doc/src/images/declarative-reuse-bluerect.png b/doc/src/images/declarative-reuse-bluerect.png Binary files differnew file mode 100644 index 0000000..97dbb5f --- /dev/null +++ b/doc/src/images/declarative-reuse-bluerect.png diff --git a/doc/src/images/declarative-reuse-focus.png b/doc/src/images/declarative-reuse-focus.png Binary files differnew file mode 100644 index 0000000..f91d374 --- /dev/null +++ b/doc/src/images/declarative-reuse-focus.png diff --git a/doc/src/images/declarative-rotation.png b/doc/src/images/declarative-rotation.png Binary files differnew file mode 100644 index 0000000..994011b --- /dev/null +++ b/doc/src/images/declarative-rotation.png diff --git a/doc/src/images/declarative-roundrect.png b/doc/src/images/declarative-roundrect.png Binary files differnew file mode 100644 index 0000000..607da81 --- /dev/null +++ b/doc/src/images/declarative-roundrect.png diff --git a/doc/src/images/declarative-scale.png b/doc/src/images/declarative-scale.png Binary files differnew file mode 100644 index 0000000..bab729e --- /dev/null +++ b/doc/src/images/declarative-scale.png diff --git a/doc/src/images/declarative-scalegrid.png b/doc/src/images/declarative-scalegrid.png Binary files differnew file mode 100644 index 0000000..32d87125 --- /dev/null +++ b/doc/src/images/declarative-scalegrid.png diff --git a/doc/src/images/declarative-text.png b/doc/src/images/declarative-text.png Binary files differnew file mode 100644 index 0000000..c1a4112 --- /dev/null +++ b/doc/src/images/declarative-text.png diff --git a/doc/src/images/declarative-textedit.gif b/doc/src/images/declarative-textedit.gif Binary files differnew file mode 100644 index 0000000..7186eb9 --- /dev/null +++ b/doc/src/images/declarative-textedit.gif diff --git a/doc/src/images/declarative-textformat.png b/doc/src/images/declarative-textformat.png Binary files differnew file mode 100644 index 0000000..ade1b45 --- /dev/null +++ b/doc/src/images/declarative-textformat.png diff --git a/doc/src/images/declarative-textstyle.png b/doc/src/images/declarative-textstyle.png Binary files differnew file mode 100644 index 0000000..858c1bc --- /dev/null +++ b/doc/src/images/declarative-textstyle.png diff --git a/doc/src/images/declarative-transformorigin.png b/doc/src/images/declarative-transformorigin.png Binary files differnew file mode 100644 index 0000000..4af320f --- /dev/null +++ b/doc/src/images/declarative-transformorigin.png diff --git a/doc/src/images/declarative-tutorial-list-closed.png b/doc/src/images/declarative-tutorial-list-closed.png Binary files differnew file mode 100644 index 0000000..4a0fee9 --- /dev/null +++ b/doc/src/images/declarative-tutorial-list-closed.png diff --git a/doc/src/images/declarative-tutorial-list-open.png b/doc/src/images/declarative-tutorial-list-open.png Binary files differnew file mode 100644 index 0000000..16a9c94 --- /dev/null +++ b/doc/src/images/declarative-tutorial-list-open.png diff --git a/doc/src/images/declarative-tutorial-list.png b/doc/src/images/declarative-tutorial-list.png Binary files differnew file mode 100644 index 0000000..723fe2f --- /dev/null +++ b/doc/src/images/declarative-tutorial-list.png diff --git a/doc/src/images/declarative-tutorial1.png b/doc/src/images/declarative-tutorial1.png Binary files differnew file mode 100644 index 0000000..c9d3844 --- /dev/null +++ b/doc/src/images/declarative-tutorial1.png diff --git a/doc/src/images/declarative-tutorial2.png b/doc/src/images/declarative-tutorial2.png Binary files differnew file mode 100644 index 0000000..835484a --- /dev/null +++ b/doc/src/images/declarative-tutorial2.png diff --git a/doc/src/images/declarative-tutorial3.gif b/doc/src/images/declarative-tutorial3.gif Binary files differnew file mode 100644 index 0000000..e2eae81 --- /dev/null +++ b/doc/src/images/declarative-tutorial3.gif diff --git a/doc/src/images/declarative-tutorial3_animation.gif b/doc/src/images/declarative-tutorial3_animation.gif Binary files differnew file mode 100644 index 0000000..80b78de --- /dev/null +++ b/doc/src/images/declarative-tutorial3_animation.gif diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index f376af2..6b81936 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -103,6 +103,7 @@ <li><a href="paintsystem.html">Painting and Printing</a></li> <li><a href="graphicsview.html">Canvas UI with Graphics View</a></li> <li><a href="webintegration.html">Integrating Web Content</a></li> + <li><a href="qtdeclarative.html">Declarative UI</a></li> </ul> </td> <td valign="top"> diff --git a/doc/src/modules.qdoc b/doc/src/modules.qdoc index ef29990..bc79ed3 100644 --- a/doc/src/modules.qdoc +++ b/doc/src/modules.qdoc @@ -65,6 +65,7 @@ \row \o \l{QtWebKit} \o Classes for displaying and editing Web content \row \o \l{QtXml} \o Classes for handling XML \row \o \l{QtXmlPatterns} \o An XQuery & XPath engine for XML and custom data models + \row \o \l{QtDeclarative} \o An engine for declaratively building fluid user interfaces. \row \o \l{Phonon Module}{Phonon} \o Multimedia framework classes \row \o \l{Qt3Support} \o Qt 3 compatibility classes \header \o {2,1} \bold{Modules for working with Qt's tools} diff --git a/doc/src/snippets/declarative/GroupBox.qml b/doc/src/snippets/declarative/GroupBox.qml new file mode 100644 index 0000000..6c5431e --- /dev/null +++ b/doc/src/snippets/declarative/GroupBox.qml @@ -0,0 +1,15 @@ +import Qt 4.6 + +ContentWrapper { + id: container; width: parent.width; height: contents.height + children: [ + Rectangle { + width: parent.width; height: contents.height + color: "white"; pen.width: 2; pen.color: "#adaeb0"; radius: 10 + Column { + id: layout; width: parent.width; margin: 5; spacing: 2 + Content { } + } + } + ] +} diff --git a/doc/src/snippets/declarative/border-image.qml b/doc/src/snippets/declarative/border-image.qml new file mode 100644 index 0000000..c4215cd --- /dev/null +++ b/doc/src/snippets/declarative/border-image.qml @@ -0,0 +1,31 @@ +import Qt 4.6 + +Rectangle { + id: page + color: "white" + width: 520; height: 280 + + Row { + anchors.centerIn: parent + spacing: 50 +//! [0] + BorderImage { + width: 180; height: 180 + border.left: 30; border.top: 30 + border.right: 30; border.bottom: 30 + horizontalTileMode: BorderImage.Stretch + verticalTileMode: BorderImage.Stretch + source: "content/colors.png" + } + + BorderImage { + width: 180; height: 180 + border.left: 30; border.top: 30 + border.right: 30; border.bottom: 30 + horizontalTileMode: BorderImage.Round + verticalTileMode: BorderImage.Round + source: "content/colors.png" + } +//! [0] + } +} diff --git a/doc/src/snippets/declarative/comments.qml b/doc/src/snippets/declarative/comments.qml new file mode 100644 index 0000000..806be29 --- /dev/null +++ b/doc/src/snippets/declarative/comments.qml @@ -0,0 +1,11 @@ +import Qt 4.6 + +Text { + text: "Hello world!" //a basic greeting + /* + We want this text to stand out from the rest so + we give it a large size and different font. + */ + font.family: "Helvetica" + font.pointSize: 24 +} diff --git a/doc/src/snippets/declarative/content.qml b/doc/src/snippets/declarative/content.qml new file mode 100644 index 0000000..fb03ced --- /dev/null +++ b/doc/src/snippets/declarative/content.qml @@ -0,0 +1,9 @@ +import Qt 4.6 + +Rectangle { + width: 200; height: 100; color: "lightgray" + GroupBox { + Text { text: "First Item" } + Text { text: "Second Item" } + } +} diff --git a/doc/src/snippets/declarative/drag.qml b/doc/src/snippets/declarative/drag.qml new file mode 100644 index 0000000..8735d0c --- /dev/null +++ b/doc/src/snippets/declarative/drag.qml @@ -0,0 +1,18 @@ +import Qt 4.6 + +//! [0] +Rectangle { + id: blurtest; width: 600; height: 200; color: "white" + Image { + id: pic; source: "qtlogo-64.png"; anchors.verticalCenter: parent.verticalCenter + opacity: (600.0-pic.x) / 600; + MouseRegion { + anchors.fill: parent + drag.target: pic + drag.axis: "XAxis" + drag.minimumX: 0 + drag.maximumX: blurtest.width-pic.width + } + } +} +//! [0] diff --git a/doc/src/snippets/declarative/gradient.qml b/doc/src/snippets/declarative/gradient.qml new file mode 100644 index 0000000..281360e --- /dev/null +++ b/doc/src/snippets/declarative/gradient.qml @@ -0,0 +1,10 @@ +import Qt 4.6 + +Rectangle { + width: 100; height: 100 + gradient: Gradient { + GradientStop { position: 0.0; color: "red" } + GradientStop { position: 0.33; color: "yellow" } + GradientStop { position: 1.0; color: "green" } + } +} diff --git a/doc/src/snippets/declarative/gridview/dummydata/ContactModel.qml b/doc/src/snippets/declarative/gridview/dummydata/ContactModel.qml new file mode 100644 index 0000000..3cf9ba7 --- /dev/null +++ b/doc/src/snippets/declarative/gridview/dummydata/ContactModel.qml @@ -0,0 +1,25 @@ +import Qt 4.6 + +ListModel { + id: contactModel + ListElement { + name: "Bill Smith" + number: "555 3264" + portrait: "pics/portrait.png" + } + ListElement { + name: "Jim Williams" + number: "555 5673" + portrait: "pics/portrait.png" + } + ListElement { + name: "John Brown" + number: "555 8426" + portrait: "pics/portrait.png" + } + ListElement { + name: "Sam Wise" + number: "555 0473" + portrait: "pics/portrait.png" + } +} diff --git a/doc/src/snippets/declarative/gridview/gridview.qml b/doc/src/snippets/declarative/gridview/gridview.qml new file mode 100644 index 0000000..1a2021c --- /dev/null +++ b/doc/src/snippets/declarative/gridview/gridview.qml @@ -0,0 +1,47 @@ +import Qt 4.6 + +//! [3] +Rectangle { + width: 240; height: 180; color: "white" + // ContactModel model is defined in dummydata/ContactModel.qml + // The viewer automatically loads files in dummydata/* to assist + // development without a real data source. + + // Define a delegate component. A component will be + // instantiated for each visible item in the list. +//! [0] + Component { + id: delegate + Item { + id: wrapper + width: 80; height: 78 + Column { + Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter } + Text { text: name; anchors.horizontalCenter: parent.horizontalCenter } + } + } + } +//! [0] + // Define a highlight component. Just one of these will be instantiated + // by each ListView and placed behind the current item. +//! [1] + Component { + id: highlight + Rectangle { + color: "lightsteelblue" + radius: 5 + } + } +//! [1] + // The actual grid +//! [2] + GridView { + width: parent.width; height: parent.height + model: ContactModel; delegate: delegate + cellWidth: 80; cellHeight: 80 + highlight: highlight + focus: true + } +//! [2] +} +//! [3] diff --git a/doc/src/snippets/declarative/gridview/pics/portrait.png b/doc/src/snippets/declarative/gridview/pics/portrait.png Binary files differnew file mode 100644 index 0000000..fb5052a --- /dev/null +++ b/doc/src/snippets/declarative/gridview/pics/portrait.png diff --git a/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml b/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml new file mode 100644 index 0000000..31e02ea --- /dev/null +++ b/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml @@ -0,0 +1,17 @@ +import Qt 4.6 + +ListModel { + id: ContactModel + ListElement { + name: "Bill Smith" + number: "555 3264" + } + ListElement { + name: "John Brown" + number: "555 8426" + } + ListElement { + name: "Sam Wise" + number: "555 0473" + } +} diff --git a/doc/src/snippets/declarative/listview/highlight.qml b/doc/src/snippets/declarative/listview/highlight.qml new file mode 100644 index 0000000..b016f9a --- /dev/null +++ b/doc/src/snippets/declarative/listview/highlight.qml @@ -0,0 +1,63 @@ +import Qt 4.6 + +Rectangle { + width: 180; height: 200; color: "white" + + // ContactModel model is defined in dummydata/ContactModel.qml + // The viewer automatically loads files in dummydata/* to assist + // development without a real data source. + + // Define a delegate component. A component will be + // instantiated for each visible item in the list. +//! [0] + Component { + id: delegate + Item { + id: wrapper + width: 180; height: 40 + Column { + x: 5; y: 5 + Text { text: '<b>Name:</b> ' + name } + Text { text: '<b>Number:</b> ' + number } + } + // Use the ListView.isCurrentItem attached property to + // indent the item if it is the current item. + states: [ + State { + name: "Current" + when: wrapper.ListView.isCurrentItem + PropertyChanges { target: wrapper; x: 10 } + } + ] + transitions: [ + Transition { NumberAnimation { matchProperties: "x"; duration: 200 } } + ] + } + } +//! [0] + // Specify a highlight with custom movement. Note that autoHighlight + // is set to false in the ListView so that we can control how the + // highlight moves to the current item. +//! [1] + Component { + id: highlight + Rectangle { + width: 180; height: 40 + color: "lightsteelblue"; radius: 5 + y: SpringFollow { + source: list.currentItem.y + spring: 3 + damping: 0.2 + } + } + } + ListView { + id: list + width: parent.height; height: parent.height + model: ContactModel; delegate: delegate + highlight: highlight + highlightFollowsCurrentItem: false + focus: true + } +//! [1] +} diff --git a/doc/src/snippets/declarative/listview/listview.qml b/doc/src/snippets/declarative/listview/listview.qml new file mode 100644 index 0000000..be0f3ad --- /dev/null +++ b/doc/src/snippets/declarative/listview/listview.qml @@ -0,0 +1,49 @@ +import Qt 4.6 + +//! [3] +Rectangle { + width: 180; height: 200; color: "white" + + // ContactModel model is defined in dummydata/ContactModel.qml + // The viewer automatically loads files in dummydata/* to assist + // development without a real data source. + + // Define a delegate component. A component will be + // instantiated for each visible item in the list. +//! [0] + Component { + id: delegate + Item { + id: wrapper + width: 180; height: 40 + Column { + x: 5; y: 5 + Text { text: '<b>Name:</b> ' + name } + Text { text: '<b>Number:</b> ' + number } + } + } + } +//! [0] + // Define a highlight component. Just one of these will be instantiated + // by each ListView and placed behind the current item. +//! [1] + Component { + id: highlight + Rectangle { + color: "lightsteelblue" + radius: 5 + } + } +//! [1] + // The actual list +//! [2] + ListView { + width: parent.width; height: parent.height + model: ContactModel + delegate: delegate + highlight: highlight + focus: true + } +//! [2] +} +//! [3] diff --git a/doc/src/snippets/declarative/mouseregion.qml b/doc/src/snippets/declarative/mouseregion.qml new file mode 100644 index 0000000..67857f5 --- /dev/null +++ b/doc/src/snippets/declarative/mouseregion.qml @@ -0,0 +1,26 @@ +import Qt 4.6 + +Rectangle { width: 200; height: 100 +HorizontalLayout { +//! [0] +Rectangle { width: 100; height: 100; color: "green" + MouseRegion { anchors.fill: parent; onClicked: { parent.color = 'red' } } +} +//! [0] +//! [1] +Rectangle { + width: 100; height: 100; color: "green" + MouseRegion { + anchors.fill: parent + acceptedButtons: Qt.LeftButton | Qt.RightButton + onClicked: { + if (mouse.button == Qt.RightButton) + parent.color = 'blue'; + else + parent.color = 'red'; + } + } +} +//! [1] +} +} diff --git a/doc/src/snippets/declarative/pathview/dummydata/MenuModel.qml b/doc/src/snippets/declarative/pathview/dummydata/MenuModel.qml new file mode 100644 index 0000000..20b3b7d --- /dev/null +++ b/doc/src/snippets/declarative/pathview/dummydata/MenuModel.qml @@ -0,0 +1,17 @@ +import Qt 4.6 + +ListModel { + id: MenuModel + ListElement { + name: "Bill Jones" + icon: "pics/qtlogo-64.png" + } + ListElement { + name: "Jane Doe" + icon: "pics/qtlogo-64.png" + } + ListElement { + name: "John Smith" + icon: "pics/qtlogo-64.png" + } +} diff --git a/doc/src/snippets/declarative/pathview/pathattributes.qml b/doc/src/snippets/declarative/pathview/pathattributes.qml new file mode 100644 index 0000000..19a192c --- /dev/null +++ b/doc/src/snippets/declarative/pathview/pathattributes.qml @@ -0,0 +1,36 @@ +import Qt 4.6 + +Rectangle { + width: 240; height: 200; color: 'white' +//! [0] +//! [1] + Component { + id: delegate + Item { + id: wrapper + width: 80; height: 80 + scale: PathView.scale + opacity: PathView.opacity + Column { + Image { anchors.horizontalCenter: name.horizontalCenter; width: 64; height: 64; source: icon } + Text { id: name; text: name; font.pointSize: 16} + } + } + } +//! [1] +//! [2] + PathView { + anchors.fill: parent; model: MenuModel; delegate: delegate + path: Path { + startX: 120; startY: 100 + PathAttribute { name: "scale"; value: 1.0 } + PathAttribute { name: "opacity"; value: 1.0 } + PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 } + PathAttribute { name: "scale"; value: 0.3 } + PathAttribute { name: "opacity"; value: 0.5 } + PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 } + } + } +//! [2] +//! [0] +} diff --git a/doc/src/snippets/declarative/pathview/pathview.qml b/doc/src/snippets/declarative/pathview/pathview.qml new file mode 100644 index 0000000..5605139 --- /dev/null +++ b/doc/src/snippets/declarative/pathview/pathview.qml @@ -0,0 +1,30 @@ +import Qt 4.6 + +Rectangle { + width: 240; height: 200; color: 'white' +//! [0] +//! [1] + Component { + id: delegate + Item { + id: wrapper + width: 80; height: 80 + Column { + Image { anchors.horizontalCenter: name.horizontalCenter; width: 64; height: 64; source: icon } + Text { id: name; text: name; font.pointSize: 16} + } + } + } +//! [1] +//! [2] + PathView { + anchors.fill: parent; model: MenuModel; delegate: delegate + path: Path { + startX: 120; startY: 100 + PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 } + PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 } + } + } +//! [2] +//! [0] +} diff --git a/doc/src/snippets/declarative/pathview/pics/qtlogo-64.png b/doc/src/snippets/declarative/pathview/pics/qtlogo-64.png Binary files differnew file mode 100644 index 0000000..4f68e16 --- /dev/null +++ b/doc/src/snippets/declarative/pathview/pics/qtlogo-64.png diff --git a/doc/src/snippets/declarative/pics/qt.png b/doc/src/snippets/declarative/pics/qt.png Binary files differnew file mode 100644 index 0000000..cbed1a9 --- /dev/null +++ b/doc/src/snippets/declarative/pics/qt.png diff --git a/doc/src/snippets/declarative/repeater-index.qml b/doc/src/snippets/declarative/repeater-index.qml new file mode 100644 index 0000000..9063967 --- /dev/null +++ b/doc/src/snippets/declarative/repeater-index.qml @@ -0,0 +1,15 @@ +import Qt 4.6 + +Rectangle { + width: 50; height: childrenRect.height; color: "white" + +//! [0] + Column { + Repeater { + model: 10 + Text { text: "I'm item " + index } + } + } +//! [0] +} + diff --git a/doc/src/snippets/declarative/repeater.qml b/doc/src/snippets/declarative/repeater.qml new file mode 100644 index 0000000..f8ac856 --- /dev/null +++ b/doc/src/snippets/declarative/repeater.qml @@ -0,0 +1,16 @@ +import Qt 4.6 + +Rectangle { + width: 220; height: 20; color: "white" + +//! [0] + Row { + Rectangle { width: 10; height: 20; color: "red" } + Repeater { + model: 10 + Rectangle { width: 20; height: 20; radius: 10; color: "green" } + } + Rectangle { width: 10; height: 20; color: "blue" } + } +//! [0] +} diff --git a/doc/src/snippets/declarative/rotation.qml b/doc/src/snippets/declarative/rotation.qml new file mode 100644 index 0000000..4a67dcb --- /dev/null +++ b/doc/src/snippets/declarative/rotation.qml @@ -0,0 +1,33 @@ +import Qt 4.6 + +Rectangle { + width: 360; height: 80 + color: "white" +//! [0] + Row { + x: 10; y: 10 + spacing: 10 + Image { source: "pics/qt.png" } + Image { + source: "pics/qt.png" + transform: Rotation { origin.x: 30; origin.y: 30; axis { x: 0; y: 1; z: 0 } angle: 18 } + smooth: true + } + Image { + source: "pics/qt.png" + transform: Rotation { origin.x: 30; origin.y: 30; axis { x: 0; y: 1; z: 0 } angle: 36 } + smooth: true + } + Image { + source: "pics/qt.png" + transform: Rotation { origin.x: 30; origin.y: 30; axis { x: 0; y: 1; z: 0 } angle: 54 } + smooth: true + } + Image { + source: "pics/qt.png" + transform: Rotation { origin.x: 30; origin.y: 30; axis { x: 0; y: 1; z: 0 } angle: 72 } + smooth: true + } + } +//! [0] +} |
