diff options
Diffstat (limited to 'src/quick/doc/src')
53 files changed, 427 insertions, 220 deletions
diff --git a/src/quick/doc/src/advtutorial.qdoc b/src/quick/doc/src/advtutorial.qdoc index dbd13fff07..5e7affc5ed 100644 --- a/src/quick/doc/src/advtutorial.qdoc +++ b/src/quick/doc/src/advtutorial.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -53,10 +53,10 @@ control QML elements. Tutorial chapters: \list 1 -\li \l {tutorials/samegame/samegame1}{Creating the Game Canvas and Blocks} -\li \l {tutorials/samegame/samegame2}{Populating the Game Canvas} -\li \l {tutorials/samegame/samegame3}{Implementing the Game Logic} -\li \l {tutorials/samegame/samegame4}{Finishing Touches} +\li \l {quick/tutorials/samegame/samegame1}{Creating the Game Canvas and Blocks} +\li \l {quick/tutorials/samegame/samegame2}{Populating the Game Canvas} +\li \l {quick/tutorials/samegame/samegame3}{Implementing the Game Logic} +\li \l {quick/tutorials/samegame/samegame4}{Finishing Touches} \endlist All the code in this tutorial can be found in Qt's \c examples/quick/tutorials/samegame @@ -71,7 +71,7 @@ directory. \previouspage QML Advanced Tutorial \nextpage QML Advanced Tutorial 2 - Populating the Game Canvas -\example tutorials/samegame/samegame1 +\example quick/tutorials/samegame/samegame1 \section2 Creating the application screen @@ -83,7 +83,7 @@ To begin with, we create our Same Game application with a main screen like this: This is defined by the main application file, \c samegame.qml, which looks like this: -\snippet tutorials/samegame/samegame1/samegame.qml 0 +\snippet quick/tutorials/samegame/samegame1/samegame.qml 0 This gives you a basic game window that includes the main canvas for the blocks, a "New Game" button and a score display. @@ -101,7 +101,7 @@ The \c Button item in the code above is defined in a separate component file nam To create a functional button, we use the QML elements \l Text and \l MouseArea inside a \l Rectangle. Here is the \c Button.qml code: -\snippet tutorials/samegame/samegame1/Button.qml 0 +\snippet quick/tutorials/samegame/samegame1/Button.qml 0 This essentially defines a rectangle that contains text and can be clicked. The \l MouseArea has an \c onClicked() handler that is implemented to emit the \c clicked() signal of the @@ -111,7 +111,7 @@ In Same Game, the screen is filled with small blocks when the game begins. Each block is just an item that contains an image. The block code is defined in a separate \c Block.qml file: -\snippet tutorials/samegame/samegame1/Block.qml 0 +\snippet quick/tutorials/samegame/samegame1/Block.qml 0 At the moment, the block doesn't do anything; it is just an image. As the tutorial progresses we will animate and give behaviors to the blocks. @@ -141,7 +141,7 @@ elements to get started. Next, we will populate the game canvas with some blocks \previouspage QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks \nextpage QML Advanced Tutorial 3 - Implementing the Game Logic -\example tutorials/samegame/samegame2 +\example quick/tutorials/samegame/samegame2 \section2 Generating the blocks in JavaScript @@ -156,7 +156,7 @@ create the blocks in JavaScript. Here is the JavaScript code for generating the blocks, contained in a new file, \c samegame.js. The code is explained below. -\snippet tutorials/samegame/samegame2/samegame.js 0 +\snippet quick/tutorials/samegame/samegame2/samegame.js 0 The \c startNewGame() function deletes the blocks created in the previous game and calculates the number of rows and columns of blocks required to fill the game window for the new game. @@ -192,14 +192,14 @@ Now we need to call the JavaScript code in \c samegame.js from our QML files. To do this, we add this line to \c samegame.qml which imports the JavaScript file as a \l{QML Modules}{module}: -\snippet tutorials/samegame/samegame2/samegame.qml 2 +\snippet quick/tutorials/samegame/samegame2/samegame.qml 2 This allows us to refer to any functions within \c samegame.js using "SameGame" as a prefix: for example, \c SameGame.startNewGame() or \c SameGame.createBlock(). This means we can now connect the New Game button's \c onClicked handler to the \c startNewGame() function, like this: -\snippet tutorials/samegame/samegame2/samegame.qml 1 +\snippet quick/tutorials/samegame/samegame2/samegame.qml 1 So, when you click the New Game button, \c startNewGame() is called and generates a field of blocks, like this: @@ -217,7 +217,7 @@ Now, we have a screen of blocks, and we can begin to add the game mechanics. \previouspage QML Advanced Tutorial 2 - Populating the Game Canvas \nextpage QML Advanced Tutorial 4 - Finishing Touches -\example tutorials/samegame/samegame3 +\example quick/tutorials/samegame/samegame3 \section2 Making a playable game @@ -241,7 +241,7 @@ As this is a tutorial about QML, not game design, we will only discuss \c handle To make it easier for the JavaScript code to interface with the QML elements, we have added an Item called \c gameCanvas to \c samegame.qml. It replaces the background as the item which contains the blocks. It also accepts mouse input from the user. Here is the item code: -\snippet tutorials/samegame/samegame3/samegame.qml 1 +\snippet quick/tutorials/samegame/samegame3/samegame.qml 1 The \c gameCanvas item is the exact size of the board, and has a \c score property and a \l MouseArea to handle mouse clicks. The blocks are now created as its children, and its dimensions are used to determine the board size so that @@ -251,7 +251,7 @@ Note that it can still be accessed from the script. When clicked, the \l MouseArea calls \c{handleClick()} in \c samegame.js, which determines whether the player's click should cause any blocks to be removed, and updates \c gameCanvas.score with the current score if necessary. Here is the \c handleClick() function: -\snippet tutorials/samegame/samegame3/samegame.js 1 +\snippet quick/tutorials/samegame/samegame3/samegame.js 1 Note that if \c score was a global variable in the \c{samegame.js} file you would not be able to bind to it. You can only bind to QML properties. @@ -259,17 +259,17 @@ Note that if \c score was a global variable in the \c{samegame.js} file you woul When the player clicks a block and triggers \c handleClick(), \c handleClick() also calls \c victoryCheck() to update the score and to check whether the player has completed the game. Here is the \c victoryCheck() code: -\snippet tutorials/samegame/samegame3/samegame.js 2 +\snippet quick/tutorials/samegame/samegame3/samegame.js 2 This updates the \c gameCanvas.score value and displays a "Game Over" dialog if the game is finished. The Game Over dialog is created using a \c Dialog element that is defined in \c Dialog.qml. Here is the \c Dialog.qml code. Notice how it is designed to be usable imperatively from the script file, via the functions and signals: -\snippet tutorials/samegame/samegame3/Dialog.qml 0 +\snippet quick/tutorials/samegame/samegame3/Dialog.qml 0 And this is how it is used in the main \c samegame.qml file: -\snippet tutorials/samegame/samegame3/samegame.qml 2 +\snippet quick/tutorials/samegame/samegame3/samegame.qml 2 We give the dialog a \l {Item::z}{z} value of 100 to ensure it is displayed on top of our other components. The default \c z value for an item is 0. @@ -278,7 +278,7 @@ We give the dialog a \l {Item::z}{z} value of 100 to ensure it is displayed on t It's not much fun to play Same Game if all the blocks are the same color, so we've modified the \c createBlock() function in \c samegame.js to randomly create a different type of block (for either red, green or blue) each time it is called. \c Block.qml has also changed so that each block contains a different image depending on its type: -\snippet tutorials/samegame/samegame3/Block.qml 0 +\snippet quick/tutorials/samegame/samegame3/Block.qml 0 \section2 A working game @@ -290,7 +290,7 @@ Here is a screenshot of what has been accomplished so far: This is what \c samegame.qml looks like now: -\snippet tutorials/samegame/samegame3/samegame.qml 0 +\snippet quick/tutorials/samegame/samegame3/samegame.qml 0 The game works, but it's a little boring right now. Where are the smooth animated transitions? Where are the high scores? If you were a QML expert you could have written these in the first iteration, but in this tutorial they've been saved @@ -305,7 +305,7 @@ until the next chapter - where your application becomes alive! \contentspage QML Advanced Tutorial \previouspage QML Advanced Tutorial 3 - Implementing the Game Logic -\example tutorials/samegame/samegame4 +\example quick/tutorials/samegame/samegame4 \section2 Adding some flair @@ -324,7 +324,7 @@ In \c BoomBlock.qml, we apply a \l SpringAnimation behavior to the \c x and \c y block will follow and animate its movement in a spring-like fashion towards the specified position (whose values will be set by \c samegame.js).Here is the code added to \c BoomBlock.qml: -\snippet tutorials/samegame/samegame4/content/BoomBlock.qml 1 +\snippet quick/tutorials/samegame/samegame4/content/BoomBlock.qml 1 The \c spring and \c damping values can be changed to modify the spring-like effect of the animation. @@ -341,7 +341,7 @@ animate the opacity value so that it gradually fades in and out, instead of abru visible and invisible. To do this, we'll apply a \l Behavior on the \c opacity property of the \c Image element in \c BoomBlock.qml: -\snippet tutorials/samegame/samegame4/content/BoomBlock.qml 2 +\snippet quick/tutorials/samegame/samegame4/content/BoomBlock.qml 2 Note the \c{opacity: 0} which means the block is transparent when it is first created. We could set the opacity in \c samegame.js when we create and destroy the blocks, @@ -367,14 +367,14 @@ To fade out, we set \c dying to true instead of setting opacity to 0 when a bloc Finally, we'll add a cool-looking particle effect to the blocks when they are destroyed. To do this, we first add a \l ParticleSystem in \c BoomBlock.qml, like so: -\snippet tutorials/samegame/samegame4/content/BoomBlock.qml 3 +\snippet quick/tutorials/samegame/samegame4/content/BoomBlock.qml 3 To fully understand this you should read the \l Particles documentation, but it's important to note that \c emitRate is set to zero so that particles are not emitted normally. Also, we extend the \c dying State, which creates a burst of particles by calling the \c burst() method on the particles element. The code for the states now look like this: -\snippet tutorials/samegame/samegame4/content/BoomBlock.qml 4 +\snippet quick/tutorials/samegame/samegame4/content/BoomBlock.qml 4 Now the game is beautifully animated, with subtle (or not-so-subtle) animations added for all of the player's actions. The end result is shown below, with a different set of images to demonstrate basic theming: @@ -391,32 +391,32 @@ To do this, we will show a dialog when the game is over to request the player's This requires a few changes to \c Dialog.qml. In addition to a \c Text element, it now has a \c TextInput child item for receiving keyboard text input: -\snippet tutorials/samegame/samegame4/content/Dialog.qml 0 +\snippet quick/tutorials/samegame/samegame4/content/Dialog.qml 0 \dots 4 -\snippet tutorials/samegame/samegame4/content/Dialog.qml 2 +\snippet quick/tutorials/samegame/samegame4/content/Dialog.qml 2 \dots 4 -\snippet tutorials/samegame/samegame4/content/Dialog.qml 3 +\snippet quick/tutorials/samegame/samegame4/content/Dialog.qml 3 We'll also add a \c showWithInput() function. The text input will only be visible if this function is called instead of \c show(). When the dialog is closed, it emits a \c closed() signal, and other elements can retrieve the text entered by the user through an \c inputText property: -\snippet tutorials/samegame/samegame4/content/Dialog.qml 0 -\snippet tutorials/samegame/samegame4/content/Dialog.qml 1 +\snippet quick/tutorials/samegame/samegame4/content/Dialog.qml 0 +\snippet quick/tutorials/samegame/samegame4/content/Dialog.qml 1 \dots 4 -\snippet tutorials/samegame/samegame4/content/Dialog.qml 3 +\snippet quick/tutorials/samegame/samegame4/content/Dialog.qml 3 Now the dialog can be used in \c samegame.qml: -\snippet tutorials/samegame/samegame4/samegame.qml 0 +\snippet quick/tutorials/samegame/samegame4/samegame.qml 0 When the dialog emits the \c closed signal, we call the new \c saveHighScore() function in \c samegame.js, which stores the high score locally in an SQL database and also send the score to an online database if possible. The \c nameInputDialog is activated in the \c victoryCheck() function in \c samegame.js: -\snippet tutorials/samegame/samegame4/content/samegame.js 3 +\snippet quick/tutorials/samegame/samegame4/content/samegame.js 3 \dots 4 -\snippet tutorials/samegame/samegame4/content/samegame.js 4 +\snippet quick/tutorials/samegame/samegame4/content/samegame.js 4 \section3 Storing high scores offline @@ -424,7 +424,7 @@ Now we need to implement the functionality to actually save the High Scores tabl Here is the \c saveHighScore() function in \c samegame.js: -\snippet tutorials/samegame/samegame4/content/samegame.js 2 +\snippet quick/tutorials/samegame/samegame4/content/samegame.js 2 First we call \c sendHighScore() (explained in the section below) if it is possible to send the high scores to an online database. @@ -443,7 +443,7 @@ If the player entered their name we can send the data to the web service us If the player enters a name, we send the data to the service using this code in \c samegame.js: -\snippet tutorials/samegame/samegame4/content/samegame.js 1 +\snippet quick/tutorials/samegame/samegame4/content/samegame.js 1 The \l XMLHttpRequest in this code is the same as the \c XMLHttpRequest() as you'll find in standard browser JavaScript, and can be used in the same way to dynamically get XML or QML from the web service to display the high scores. We don't worry about the response in this case - we just post the high diff --git a/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc index ab96a6ccdf..a1d84735b7 100644 --- a/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc +++ b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/codingconventions.qdoc b/src/quick/doc/src/appdevguide/codingconventions.qdoc index 05d09cbdad..b48c5e8a7a 100644 --- a/src/quick/doc/src/appdevguide/codingconventions.qdoc +++ b/src/quick/doc/src/appdevguide/codingconventions.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/debugging.qdoc b/src/quick/doc/src/appdevguide/debugging.qdoc index b20ca6554f..94ce13459c 100644 --- a/src/quick/doc/src/appdevguide/debugging.qdoc +++ b/src/quick/doc/src/appdevguide/debugging.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -123,14 +123,6 @@ function f() { \c console.exception prints an error message together with the stack trace of JavaScript execution at the point where it is called. -\section1 Debugging Transitions - -When a transition doesn't look quite right, it can be helpful to view it in slow -motion to see what is happening more clearly. This functionality is supported -in the \l{qtquick-qmlscene.html}{QML Scene} tool: to enable this, -click on the "Debugging" menu, then "Slow Down Animations". - - \section1 Debugging module imports The \c QML_IMPORT_TRACE environment variable can be set to enable debug output diff --git a/src/quick/doc/src/appdevguide/deployment.qdoc b/src/quick/doc/src/appdevguide/deployment.qdoc index 12296ecb53..bf98902c17 100644 --- a/src/quick/doc/src/appdevguide/deployment.qdoc +++ b/src/quick/doc/src/appdevguide/deployment.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -189,23 +189,23 @@ project The \c main.qml and \c background.png files will be packaged as resource files. This is done in the \c example.qrc resource collection file: -\quotefile qml/qtbinding/resources/example.qrc +\quotefile ../src/qml/doc/snippets/qml/qtbinding/resources/example.qrc Since \c background.png is a resource file, \c main.qml can refer to it using the relative path specified in \c example.qrc: -\snippet qml/qtbinding/resources/main.qml 0 +\snippet ../src/qml/doc/snippets/qml/qtbinding/resources/main.qml 0 To allow QML to locate resource files correctly, the \c main.cpp loads the main QML file, \c main.qml, as a resource file using the \c qrc scheme: -\snippet qml/qtbinding/resources/main.cpp 0 +\snippet ../src/qml/doc/snippets/qml/qtbinding/resources/main.cpp 0 Finally \c project.pro uses the RESOURCES variable to indicate that \c example.qrc should be used to build the application resources: -\quotefile qml/qtbinding/resources/resources.pro +\quotefile ../src/qml/doc/snippets/qml/qtbinding/resources/resources.pro See \l {The Qt Resource System} for more information. - +*/ diff --git a/src/quick/doc/src/appdevguide/glossary.qdoc b/src/quick/doc/src/appdevguide/glossary.qdoc index 3f26e0aa70..5ebdca96cc 100644 --- a/src/quick/doc/src/appdevguide/glossary.qdoc +++ b/src/quick/doc/src/appdevguide/glossary.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/internationalization.qdoc b/src/quick/doc/src/appdevguide/internationalization.qdoc index dce5a895b8..bf6b667a01 100644 --- a/src/quick/doc/src/appdevguide/internationalization.qdoc +++ b/src/quick/doc/src/appdevguide/internationalization.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -262,7 +262,7 @@ SOURCES = main.qml \ \endcode -You can also specify the .qml source files without with a wildcard match. The +You can also specify the .qml source files with a wildcard match. The search is not recursive so you need to specify each directory where there are user interface strings in the source code: diff --git a/src/quick/doc/src/appdevguide/performance.qdoc b/src/quick/doc/src/appdevguide/performance.qdoc index 277444b99b..4f0590d554 100644 --- a/src/quick/doc/src/appdevguide/performance.qdoc +++ b/src/quick/doc/src/appdevguide/performance.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/porting.qdoc b/src/quick/doc/src/appdevguide/porting.qdoc index 305524c9e6..dcc864179b 100644 --- a/src/quick/doc/src/appdevguide/porting.qdoc +++ b/src/quick/doc/src/appdevguide/porting.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/qmlscene.qdoc b/src/quick/doc/src/appdevguide/qmlscene.qdoc index 264adffee3..a749b48c04 100644 --- a/src/quick/doc/src/appdevguide/qmlscene.qdoc +++ b/src/quick/doc/src/appdevguide/qmlscene.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/qtquicktest.qdoc b/src/quick/doc/src/appdevguide/qtquicktest.qdoc index c577a90be1..f6085764be 100644 --- a/src/quick/doc/src/appdevguide/qtquicktest.qdoc +++ b/src/quick/doc/src/appdevguide/qtquicktest.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -95,11 +95,39 @@ tst_example -input /mnt/SDCard/qmltests \endcode + It is also possible to run a single file using the \c{-input} option. + For example: + + \code + tst_example -input data/test.qml + \endcode + + \code + tst_example -input <full_path>/test.qml + \endcode + + \note Specifying the full path to the qml test file is for example + needed for shadow builds. + If your test case needs QML imports, then you can add them as - \c{-import} options to the the test program command-line by adding + \c{-import} options to the test program command-line by adding the following line to your .pro file: \code IMPORTPATH += $$PWD/../imports/my_module1 $$PWD/../imports/my_module2 \endcode + + The \c{-functions} command-line option will return a list of the current + tests functions. It is possible to run a single test function using the name + of the test function as an argument. For example: + + \code + tst_example Test_Name::function1 + \endcode + + The \c{-help} command-line option will return all the options available. + + \code + tst_example -help + \endcode */ diff --git a/src/quick/doc/src/appdevguide/quickstart/basics.qdoc b/src/quick/doc/src/appdevguide/quickstart/basics.qdoc index 5748507f0a..ef30f1682d 100644 --- a/src/quick/doc/src/appdevguide/quickstart/basics.qdoc +++ b/src/quick/doc/src/appdevguide/quickstart/basics.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc b/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc index 4256e40c6f..d061d795a5 100644 --- a/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc +++ b/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/usecases/animations.qdoc b/src/quick/doc/src/appdevguide/usecases/animations.qdoc index cc391017b1..3e87bae81d 100644 --- a/src/quick/doc/src/appdevguide/usecases/animations.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/animations.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/usecases/integratingjs.qdoc b/src/quick/doc/src/appdevguide/usecases/integratingjs.qdoc index 78c257ba8d..4bad4a4033 100644 --- a/src/quick/doc/src/appdevguide/usecases/integratingjs.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/integratingjs.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/usecases/layouts.qdoc b/src/quick/doc/src/appdevguide/usecases/layouts.qdoc index 3519dd5656..2c6f4d0dd8 100644 --- a/src/quick/doc/src/appdevguide/usecases/layouts.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/layouts.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/usecases/styling.qdoc b/src/quick/doc/src/appdevguide/usecases/styling.qdoc index 79d326bbc1..7da230b1a0 100644 --- a/src/quick/doc/src/appdevguide/usecases/styling.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/styling.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/usecases/text.qdoc b/src/quick/doc/src/appdevguide/usecases/text.qdoc index 405f551686..d0b8901170 100644 --- a/src/quick/doc/src/appdevguide/usecases/text.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/text.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/usecases/userinput.qdoc b/src/quick/doc/src/appdevguide/usecases/userinput.qdoc index 8425ad54ec..b31fcc4d5f 100644 --- a/src/quick/doc/src/appdevguide/usecases/userinput.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/userinput.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/appdevguide/usecases/visual.qdoc b/src/quick/doc/src/appdevguide/usecases/visual.qdoc index cb72cb9cd6..a022b185fe 100644 --- a/src/quick/doc/src/appdevguide/usecases/visual.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/visual.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/convenience/topic.qdoc b/src/quick/doc/src/concepts/convenience/topic.qdoc index a4b1dad0d3..113b4952a6 100644 --- a/src/quick/doc/src/concepts/convenience/topic.qdoc +++ b/src/quick/doc/src/concepts/convenience/topic.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/effects/particles.qdoc b/src/quick/doc/src/concepts/effects/particles.qdoc index 0263996a8a..08a76511b6 100644 --- a/src/quick/doc/src/concepts/effects/particles.qdoc +++ b/src/quick/doc/src/concepts/effects/particles.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/effects/sprites.qdoc b/src/quick/doc/src/concepts/effects/sprites.qdoc index 9f32724bfb..ac3234b24c 100644 --- a/src/quick/doc/src/concepts/effects/sprites.qdoc +++ b/src/quick/doc/src/concepts/effects/sprites.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/effects/topic.qdoc b/src/quick/doc/src/concepts/effects/topic.qdoc index 03450d8a05..42b0291e44 100644 --- a/src/quick/doc/src/concepts/effects/topic.qdoc +++ b/src/quick/doc/src/concepts/effects/topic.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/effects/transformations.qdoc b/src/quick/doc/src/concepts/effects/transformations.qdoc index 7c632c4360..606260cdd4 100644 --- a/src/quick/doc/src/concepts/effects/transformations.qdoc +++ b/src/quick/doc/src/concepts/effects/transformations.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/input/focus.qdoc b/src/quick/doc/src/concepts/input/focus.qdoc index eb23e65653..7af1a26ee3 100644 --- a/src/quick/doc/src/concepts/input/focus.qdoc +++ b/src/quick/doc/src/concepts/input/focus.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/input/mouse.qdoc b/src/quick/doc/src/concepts/input/mouse.qdoc index 5617f6c64a..a1fbb6ce0e 100644 --- a/src/quick/doc/src/concepts/input/mouse.qdoc +++ b/src/quick/doc/src/concepts/input/mouse.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/input/textinput.qdoc b/src/quick/doc/src/concepts/input/textinput.qdoc index 1809d5050b..3c65b7e842 100644 --- a/src/quick/doc/src/concepts/input/textinput.qdoc +++ b/src/quick/doc/src/concepts/input/textinput.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -50,10 +50,10 @@ The \e validator types enforce the type and format of \annotatedlist qtquick-text-validator -\snippet doc/snippets/qml/texthandling.qml int validator +\snippet qml/texthandling.qml int validator The validator types bind to \c {TextInput}'s \c validator property. -\snippet doc/snippets/qml/texthandling.qml regexp validator +\snippet qml/texthandling.qml regexp validator The regular expression in the snippet will only allow the inputted text to be \c {fruit basket}. diff --git a/src/quick/doc/src/concepts/input/topic.qdoc b/src/quick/doc/src/concepts/input/topic.qdoc index 51b6496c1d..e3349f350c 100644 --- a/src/quick/doc/src/concepts/input/topic.qdoc +++ b/src/quick/doc/src/concepts/input/topic.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/modelviewsdata/cppmodels.qdoc b/src/quick/doc/src/concepts/modelviewsdata/cppmodels.qdoc index 8fd24b00ec..8571879f78 100644 --- a/src/quick/doc/src/concepts/modelviewsdata/cppmodels.qdoc +++ b/src/quick/doc/src/concepts/modelviewsdata/cppmodels.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -49,14 +49,16 @@ via the \e modelData role. Here is a ListView with a delegate that references its model item's value using the \c modelData role: -\snippet examples/quick/modelviews/stringlistmodel/view.qml 0 +\snippet quick/models/stringlistmodel/view.qml 0 A Qt application can load this QML document and set the value of \c myModel to a QStringList: -\snippet examples/quick/modelviews/stringlistmodel/main.cpp 0 +\snippet quick/models/stringlistmodel/main.cpp 0 -The complete example is available in Qt's \l {quick/modelviews/stringlistmodel}{examples/quick/modelviews/stringlistmodel} directory. +The complete source code for this example is available in +\l {quick/modelviews/stringlistmodel}{examples/quick/modelviews/stringlistmodel} +within the Qt install directory. \b{Note:} There is no way for the view to know that the contents of a QStringList have changed. If the QStringList changes, it will be necessary to reset @@ -68,15 +70,15 @@ the model by calling QQmlContext::setContextProperty() again. A list of QObject* values can also be used as a model. A QList<QObject*> provides the properties of the objects in the list as roles. -The following application creates a \c DataObject class that with +The following application creates a \c DataObject class with Q_PROPERTY values that will be accessible as named roles when a QList<DataObject*> is exposed to QML: -\snippet examples/quick/modelviews/objectlistmodel/dataobject.h 0 +\snippet quick/models/objectlistmodel/dataobject.h 0 \dots 4 -\snippet examples/quick/modelviews/objectlistmodel/dataobject.h 1 +\snippet quick/models/objectlistmodel/dataobject.h 1 \codeline -\snippet examples/quick/modelviews/objectlistmodel/main.cpp 0 +\snippet quick/models/objectlistmodel/main.cpp 0 \dots The QObject* is available as the \c modelData property. As a convenience, @@ -84,17 +86,19 @@ the properties of the object are also made available directly in the delegate's context. Here, \c view.qml references the \c DataModel properties in the ListView delegate: -\snippet examples/quick/modelviews/objectlistmodel/view.qml 0 +\snippet quick/models/objectlistmodel/view.qml 0 -Note the use of the fully qualified access to the \c color property. +Note the use of \c color property with qualifier. The properties of the object are not replicated in the \c model -object, since they are easily available via the \c modelData +object, as they are easily available via the \c modelData object. -The complete example is available in Qt's \l {quick/modelviews/objectlistmodel}{examples/quick/modelviews/objectlistmodel} directory. +The complete source code for this example is available in +\l {quick/modelviews/objectlistmodel}{examples/quick/modelviews/objectlistmodel} +within the Qt install directory. Note: There is no way for the view to know that the contents of a QList -have changed. If the QList changes, it will be necessary to reset +has changed. If the QList changes, it is necessary to reset the model by calling QQmlContext::setContextProperty() again. @@ -103,10 +107,11 @@ the model by calling QQmlContext::setContextProperty() again. A model can be defined by subclassing QAbstractItemModel. This is the best approach if you have a more complex model that cannot be supported by the other approaches. A QAbstractItemModel can also automatically -notify a QML view when the model data has changed. +notify a QML view when the model data changes. -The roles of a QAbstractItemModel subclass can be exposed to QML by calling -QAbstractItemModel::setRoleNames(). The default role names set by Qt are: +The roles of a QAbstractItemModel subclass can be exposed to QML by +reimplementing QAbstractItemModel::roleNames(). The default role names +set by Qt are: \table \header @@ -120,39 +125,42 @@ QAbstractItemModel::setRoleNames(). The default role names set by Qt are: \li decoration \endtable -Here is an application with a QAbstractListModel subclass named \c AnimalModel -that has \e type and \e size roles. It reimplements QAbstractItemModel::roleNames() to set the -role names for accessing the properties via QML: +Here is an application with a QAbstractListModel subclass named \c AnimalModel, +which exposes the \e type and \e sizes roles. It reimplements +QAbstractItemModel::roleNames() to expose the role names, so that they can be +accessed via QML: -\snippet examples/quick/modelviews/abstractitemmodel/model.h 0 +\snippet quick/models/abstractitemmodel/model.h 0 \dots -\snippet examples/quick/modelviews/abstractitemmodel/model.h 1 +\snippet quick/models/abstractitemmodel/model.h 1 \dots -\snippet examples/quick/modelviews/abstractitemmodel/model.h 2 +\snippet quick/models/abstractitemmodel/model.h 2 \codeline -\snippet examples/quick/modelviews/abstractitemmodel/model.cpp 0 +\snippet quick/models/abstractitemmodel/model.cpp 0 \codeline -\snippet examples/quick/modelviews/abstractitemmodel/main.cpp 0 +\snippet quick/models/abstractitemmodel/main.cpp 0 \dots This model is displayed by a ListView delegate that accesses the \e type and \e size roles: -\snippet examples/quick/modelviews/abstractitemmodel/view.qml 0 +\snippet quick/models/abstractitemmodel/view.qml 0 QML views are automatically updated when the model changes. Remember the model must follow the standard rules for model changes and notify the view when the model has changed by using QAbstractItemModel::dataChanged(), -QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for +QAbstractItemModel::beginInsertRows(), and so on. See the \l {Model subclassing reference} for more information. -The complete example is available in Qt's \l {quick/modelviews/abstractitemmodel}{examples/quick/modelviews/abstractitemmodel} directory. +The complete source code for this example is available in +\l {quick/modelviews/abstractitemmodel}{examples/quick/modelviews/abstractitemmodel} +within the Qt install directory. QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML can only display list data. -In order to display child lists of a hierarchical model -the VisualDataModel element provides several properties and functions for use -with models of type QAbstractItemModel: +In order to display the child lists of a hierarchical model, +use the VisualDataModel type, which provides the following properties and functions to be used +with list models of QAbstractItemModel type: \list \li \e hasModelChildren role property to determine whether a node has child nodes. diff --git a/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc b/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc index dc4de0a4ca..7c424dd286 100644 --- a/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc +++ b/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/modelviewsdata/topic.qdoc b/src/quick/doc/src/concepts/modelviewsdata/topic.qdoc index 5acc7c996d..6939c3131f 100644 --- a/src/quick/doc/src/concepts/modelviewsdata/topic.qdoc +++ b/src/quick/doc/src/concepts/modelviewsdata/topic.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/positioning/anchors.qdoc b/src/quick/doc/src/concepts/positioning/anchors.qdoc index bec0949fb3..d0a14f7392 100644 --- a/src/quick/doc/src/concepts/positioning/anchors.qdoc +++ b/src/quick/doc/src/concepts/positioning/anchors.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -140,7 +140,8 @@ carefully ordered, or they may produce unexpected outcomes. The following exampl \table \row \li - \badcode + \code + //bad code Rectangle { width: 50 anchors.left: parent.left @@ -185,7 +186,8 @@ conditional bindings, as this can lead to the ordering issue described above. In the Rectangle will eventually grow to the full width of its parent, because both left and right anchors will be simultaneously set during binding update. -\badcode +\code +//bad code Rectangle { width: 50; height: 50 anchors.left: state == "right" ? undefined : parent.left; @@ -201,7 +203,8 @@ ordering issues internally. For performance reasons, you can only anchor an item to its siblings and direct parent. For example, the following anchor is invalid and would produce a warning: -\badcode +\code +//bad code Item { id: group1 Rectangle { id: rect1; ... } diff --git a/src/quick/doc/src/concepts/positioning/layouts.qdoc b/src/quick/doc/src/concepts/positioning/layouts.qdoc index 9d52d4b2e6..0981bddb3d 100644 --- a/src/quick/doc/src/concepts/positioning/layouts.qdoc +++ b/src/quick/doc/src/concepts/positioning/layouts.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/positioning/righttoleft.qdoc b/src/quick/doc/src/concepts/positioning/righttoleft.qdoc index b9fba98ec6..44bb03f394 100644 --- a/src/quick/doc/src/concepts/positioning/righttoleft.qdoc +++ b/src/quick/doc/src/concepts/positioning/righttoleft.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/positioning/topic.qdoc b/src/quick/doc/src/concepts/positioning/topic.qdoc index 8b40407395..799f578d6e 100644 --- a/src/quick/doc/src/concepts/positioning/topic.qdoc +++ b/src/quick/doc/src/concepts/positioning/topic.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/statesanimations/animations.qdoc b/src/quick/doc/src/concepts/statesanimations/animations.qdoc index 3eb9d61fc1..438804ce41 100644 --- a/src/quick/doc/src/concepts/statesanimations/animations.qdoc +++ b/src/quick/doc/src/concepts/statesanimations/animations.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/statesanimations/behaviors.qdoc b/src/quick/doc/src/concepts/statesanimations/behaviors.qdoc index c6953b6d75..9c213fdf9f 100644 --- a/src/quick/doc/src/concepts/statesanimations/behaviors.qdoc +++ b/src/quick/doc/src/concepts/statesanimations/behaviors.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/statesanimations/states.qdoc b/src/quick/doc/src/concepts/statesanimations/states.qdoc index 28fc535033..7ef05ac2ac 100644 --- a/src/quick/doc/src/concepts/statesanimations/states.qdoc +++ b/src/quick/doc/src/concepts/statesanimations/states.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/statesanimations/topic.qdoc b/src/quick/doc/src/concepts/statesanimations/topic.qdoc index 050a770d71..bbcee5a7d2 100644 --- a/src/quick/doc/src/concepts/statesanimations/topic.qdoc +++ b/src/quick/doc/src/concepts/statesanimations/topic.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/visualcanvas/coordinates.qdoc b/src/quick/doc/src/concepts/visualcanvas/coordinates.qdoc index 3f49de540f..fead7d7777 100644 --- a/src/quick/doc/src/concepts/visualcanvas/coordinates.qdoc +++ b/src/quick/doc/src/concepts/visualcanvas/coordinates.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc index 6e9d963d8d..099c7eb443 100644 --- a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc +++ b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -51,7 +51,7 @@ reduction like this can greatly improve performance on some hardware. The scene graph is closely tied to Qt Quick 2.0 and can not be used stand-alone. The scene graph is managed and rendered by the -QQuickWindow class and custom Item elements can add their graphical +QQuickWindow class and custom Item types can add their graphical primitives into the scene graph through a call to QQuickItem::updatePaintNode(). @@ -63,54 +63,212 @@ graph will even be rendered on a dedicated render thread while the GUI thread is preparing the next frame's state. +\section1 Qt Quick Scene Graph Structure -\section1 Scene Graph Nodes +The scene graph is composed of a number of predefined node types, each +serving a dedicated purpose. Although we refer to it as a scene graph, +a more precise definition is node tree. The tree is built from +QQuickItem types in the QML scene and internally the scene is then +processed by a renderer which draws the scene. The nodes themselves do +\b not contain any active drawing code nor virtual \c paint() +function. -The scene graph can only contain a predefined set of node types, each -serving a dedicated purpose. +Even though the node tree is mostly built internally by the existing +Qt Quick QML types, it is possible for users to also add complete +subtrees with their own content, including subtrees that represent 3D +models. -\list -\li QSGGeometryNode - for all rendered content in the scene -graph. In most cases, it will be enough for a custom QQuickItem object to -simply return a single QSGGeometryNode object from the -QQuickItem::updatePaintNode() call. +\section2 Nodes -\li QSGTransformNode - implements transformations in the scene -graph. Nested transforms are multiplied together. +The most important node for users is the \l QSGGeometryNode. It is +used to define custom graphics by defining its geometry and +material. The geometry is defined using \l QSGGeometry and describes +the shape or mesh of the graphical primitive. It can be a line, a +rectangle, a polygon, many disconnected rectangles, or complex 3D +mesh. The material defines how the pixels in this shape are filled. -\li QSGOpacityNode - for node opacity changes. Nested opacity nodes have -cumulative effect. +A node can have any number of children and geometry nodes will be +rendered so they appear in child-order with parents behind their +children. \note This does not say anything about the actual rendering +order in the renderer. Only the visual output is guaranteed. -\li QSGClipNode - implements clipping in the scene graph. Nested clips -are intersected. +The available nodes are: +\annotatedlist{qtquick-scenegraph-nodes} -\li QSGNode - base class for all nodes in the scene graph. Its primary purpose -is provide the ability to insert nodes into the scene graph that do not affect -the rendering, such as the shared root for a subtree of geometry nodes. +Custom nodes are added to the scene graph by subclassing +QQuickItem::updatePaintNode() and setting the +\l {QQuickItem::ItemHasContents} flag. -\endlist +\warning It is crucial that OpenGL operations and interaction with the +scene graph happens exclusively on the render thread, primarily +during the updatePaintNode() call. The rule of thumb is to only +use classes with the "QSG" prefix inside the +QQuickItem::updatePaintNode() function. + +For more details, see the \l {Custom Geometry Example}. + +\section3 Preprocessing + +Nodes have a virtual QSGNode::preprocess() function, which will be +called before the scene graph is rendered. Node subclasses can set the +flag \l QSGNode::UsePreprocess and override the QSGNode::preprocess() +function to do final preparation of their node. For example, dividing a +bezier curve into the correct level of detail for the current scale +factor or updating a section of a texture. + +\section3 Node Ownership Ownership of the nodes is either done explicitly by the creator or by -the scene graph by setting the flag \l QSGNode::OwnedByParent on -it. Assigning ownership to the scene graph is often preferable as it +the scene graph by setting the flag \l QSGNode::OwnedByParent. +Assigning ownership to the scene graph is often preferable as it simplifies cleanup when the scene graph lives outside the GUI thread. +\section2 Materials + +The material describes how the interior of a geometry in a \l +QSGGeometryNode is filled. It encapsulates an OpenGL shader program +and provides ample flexibility in what can be achieved, though most of +the Qt Quick items themselves only use very basic materials, such as +solid color and texture fills. + +For users who just want to apply custom shading to a QML Item type, +it is possible to do this directly in QML using the \l ShaderEffect +type. -\section1 Rendering +Below is a complete list of material classes: +\annotatedlist{qtquick-scenegraph-materials} + +For more details, see the \l {Simple Material Example} + + +\section2 Convenience Nodes + +The scene graph API is very low-level and focuses on performance +rather than convenience. Writing custom geometries and materials from +scratch, even the most basic ones, requires a non-trivial amount of +code. For this reason, the API includes a few convenience classes to +make the most common custom nodes readily available. + +\list +\li \l QSGSimpleRectNode - a QSGGeometryNode subclass which defines a +rectangular geometry with a solid color material. + +\li \l QSGSimpleTextureNode - a QSGGeometryNode subclass which defines +a rectangular geometry with a texture material. +\endlist + + + +\section1 Scene Graph and Rendering The rendering of the scene graph happens internally in the -QQuickWindow class and is described under the \l{Scene Graph and -Rendering} section. +QQuickWindow class, and there is no public API to access it. There are +however, a few places in the rendering pipeline where the user can +attach application code. This can be to add custom scene graph +content or render raw OpenGL content. The integration points are +defined by the render loop. + + +\section2 Threaded Render Loop + +On many configurations, the scene graph rendering will happen on a +dedicated render thread. This is done to increase parallelism of +multi-core processors and make better use of stall times such as +waiting for a blocking swap buffer call. This offers significant +performance improvements, but imposes certain restrictions on where +and when interaction with the scene graph can happen. -How to integrate QPainter based graphics is explained in \l{Custom -Items using QPainter}. +The following is a simple outline of how a frame gets +composed with the threaded render loop. -\section1 Mixing Scene Graph and OpenGL +\image sg-renderloop-threaded.jpg + +\list 1 + +\li A change occurs in the QML scene, causing \c QQuickItem::update() +to be called. This can be the result of for instance an animation or +user input. An event is posted to the render thread to initiate a new +frame. + +\li The render thread prepares to draw a new frame and makes the +OpenGL context current and initiates a blocks on the GUI thread. + +\li While the render thread is preparing the new frame, the GUI thread +calls QQuickItem::updatePolish() to do final touch-up of items before +they are rendered. + +\li GUI thread is blocked. + +\li The QQuickWindow::beforeSynchronizing() signal is emitted. +Applications can make direct connections (using Qt::DirectConnection) +to this signal to do any preparation required before calls to +QQuickItem::updatePaintNode(). -The scene graph offers two methods for integrating OpenGL -content. +\li Synchronization of the QML state into the scene graph. This is +done by calling the QQuickItem::updatePaintNode() function on all +items that have changed since the previous frame. This is the only +time the QML items and the nodes in the scene graph interact. + +\li GUI thread block is released. + +\li The scene graph is rendered: + \list 1 + + \li The QQuickWindow::beforeRendering() signal is + emitted. Applications can make direct connections + (using Qt::DirectConnection) to this signal to use custom OpenGL calls + which will then stack visually beneath the QML scene. + + \li Items that have specified QSGNode::UsePreprocess, will have their + QSGNode::preprocess() function invoked. + + \li The renderer processes the nodes and calls OpenGL functions. + + \li The QQuickWindow::afterRendering() signal is + emitted. Applications can make direct connections + (using Qt::DirectConnection) to this signal to use custom OpenGL calls + which will then stack visually over the QML scene. + + \li The rendered frame is swapped and QQuickWindow::frameSwapped() + is emitted. + + \endlist + +\li While the render thread is rendering, the GUI is free to advance +animations, process events, etc. + +\endlist + +The threaded renderer is currently used by default on Linux, Mac OS X +and EGLFS based QPA platforms, but this is subject to change. It is +possible to force use of the threaded renderer by setting \c +{QML_FORCE_THREADED_RENDERER=1} in the environment. + + +\section2 Non-threaded Render Loop + +The non-threaded render loop is currently used by default on Windows +and non-EGLFS based embedded platforms. This is mostly a precautionary +measure, as not all combinations of OpenGL drivers and windowing +systems have been tested. + +Even when using the non-threaded render loop, you should write your +code as if you are using the threaded renderer, as failing to do so +will make the code non-portable. + +The following is a simplified illustration of the frame rendering +sequence in the non-threaded renderer. + +\image sg-renderloop-singlethreaded.jpg + + +\section2 Mixing Scene Graph and OpenGL + +The scene graph offers two methods for integrating OpenGL content: +by calling OpenGL commands directly and by creating a textured node +in the scene graph. By connecting to the \l QQuickWindow::beforeRendering() and \l QQuickWindow::afterRendering() signals, applications can make OpenGL @@ -122,6 +280,10 @@ needed to perform the rendering. The downside is that Qt Quick decides when to call the signals and this is the only time the OpenGL application is allowed to draw. +The \l {OpenGL Under QML} example gives an example on how to use use +these signals. + + The other alternative is to create a FramebufferObject, render into it and use the result as a textured node in the scene graph, for instance using a QSGSimpleTextureNode. A simple way of doing the same is to use @@ -131,7 +293,8 @@ the OpenGL rendering and QPainter::endNativePainting() after. When OpenGL content is integrated with a texture and FramebufferObject, the application has more control over when the content is rendered. For instance, the application can create a second QOpenGLContext on the -GUI thread which shares memory with the scene graph's OpenGL context and drive the rendering manually. +GUI thread which shares memory with the scene graph's OpenGL context +and drive the rendering manually. \warning When mixing OpenGL content with scene graph rendering, it is important the application does not leave the OpenGL context in a state @@ -143,6 +306,19 @@ behavior. rendering might be happening outside the GUI thread. +\section2 Custom Items using QPainter + +The QQuickItem provides a subclass, QQuickPaintedItem, which allows +the users to render content using QPainter. + +\warning Using QQuickPaintedItem uses an indirect 2D surface to render +its content, either using software rasterization or using an OpenGL +framebuffer object (FBO), so the rendering is a two-step +operation. First rasterize the surface, then draw the surface. Using +scene graph API directly is always significantly faster. + + + \section1 Scene Graph Backend In addition to the public API, the scene graph has an adaptation layer @@ -155,7 +331,7 @@ It includes: \li Custom textures; specifically the implementation of QQuickWindow::createTextureFromImage and the internal representation -of the texture used by \l Image and \l BorderImage elements. +of the texture used by \l Image and \l BorderImage types. \li Custom renderer; the adaptation layer lets the plugin decide how the scene graph is traversed and rendered, making it possible to @@ -163,7 +339,7 @@ optimize the rendering algorithm for a specific hardware or to make use of extensions which improve performance. \li Custom scene graph implementation of many of the default QML -elements, including its text and font rendering. +types, including its text and font rendering. \li Custom animation driver; allows the animation system to hook into the low-level display vertical refresh to get smooth rendering. diff --git a/src/quick/doc/src/concepts/visualcanvas/topic.qdoc b/src/quick/doc/src/concepts/visualcanvas/topic.qdoc index 5ef6ef090c..c70c86ff3f 100644 --- a/src/quick/doc/src/concepts/visualcanvas/topic.qdoc +++ b/src/quick/doc/src/concepts/visualcanvas/topic.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc b/src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc index 4c9dbdc2dc..37b0b6084f 100644 --- a/src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc +++ b/src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/concepts/visualtypes/topic.qdoc b/src/quick/doc/src/concepts/visualtypes/topic.qdoc index 4f5c419eea..af8e673640 100644 --- a/src/quick/doc/src/concepts/visualtypes/topic.qdoc +++ b/src/quick/doc/src/concepts/visualtypes/topic.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/cppextensionpoints.qdoc b/src/quick/doc/src/cppextensionpoints.qdoc index f1a0e835bb..4700b1c3b9 100644 --- a/src/quick/doc/src/cppextensionpoints.qdoc +++ b/src/quick/doc/src/cppextensionpoints.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/dynamicview-tutorial.qdoc b/src/quick/doc/src/dynamicview-tutorial.qdoc index 3edfdc65c0..26f418516a 100644 --- a/src/quick/doc/src/dynamicview-tutorial.qdoc +++ b/src/quick/doc/src/dynamicview-tutorial.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -39,10 +39,10 @@ data to dynamically sort all items in a view. Tutorial chapters: \list 1 -\li \l {tutorials/dynamicview/dynamicview1}{A Simple ListView and Delegate} -\li \l {tutorials/dynamicview/dynamicview2}{Dragging View Items} -\li \l {tutorials/dynamicview/dynamicview3}{Moving Dragged Items} -\li \l {tutorials/dynamicview/dynamicview4}{Sorting Items} +\li \l {quick/tutorials/dynamicview/dynamicview1}{A Simple ListView and Delegate} +\li \l {quick/tutorials/dynamicview/dynamicview2}{Dragging View Items} +\li \l {quick/tutorials/dynamicview/dynamicview3}{Moving Dragged Items} +\li \l {quick/tutorials/dynamicview/dynamicview4}{Sorting Items} \endlist All the code in this tutorial can be found in Qt's \c examples/quick/tutorials/dynamicview @@ -57,19 +57,19 @@ directory. \previouspage QML Dynamic View Ordering Tutorial \nextpage QML Dynamic View Ordering Tutorial 2 - Dragging View Items -\example tutorials/dynamicview/dynamicview1 +\example quick/tutorials/dynamicview/dynamicview1 We begin our application by defining a ListView, a model which will provide data to the view, and a delegate which provides a template for constructing items in the view. The code for the ListView and delegate looks like this: -\snippet tutorials/dynamicview/dynamicview1/dynamicview.qml 0 +\snippet quick/tutorials/dynamicview/dynamicview1/dynamicview.qml 0 The model is defined in a separate QML file which looks like this: -\snippet tutorials/dynamicview/dynamicview1/PetsModel.qml 0 -\snippet tutorials/dynamicview/dynamicview1/PetsModel.qml 1 +\snippet quick/tutorials/dynamicview/dynamicview1/PetsModel.qml 0 +\snippet quick/tutorials/dynamicview/dynamicview1/PetsModel.qml 1 \section2 Walkthrough @@ -79,11 +79,11 @@ is the template from which each item in the ListView is constructed. The \c name, \c age, \c type, and \c size variables referenced in the delegate are sourced from the model data. The names correspond to roles defined in the model. -\snippet tutorials/dynamicview/dynamicview1/dynamicview.qml 1 +\snippet quick/tutorials/dynamicview/dynamicview1/dynamicview.qml 1 The second part of the application is the ListView itself to which we bind the model and delegate. -\snippet tutorials/dynamicview/dynamicview1/dynamicview.qml 2 +\snippet quick/tutorials/dynamicview/dynamicview1/dynamicview.qml 2 */ /*! @@ -94,13 +94,13 @@ The second part of the application is the ListView itself to which we bind the m \previouspage QML Dynamic View Ordering Tutorial 1 - A Simple ListView and Delegate \nextpage QML Dynamic View Ordering Tutorial 3 - Moving Dragged Items -\example tutorials/dynamicview/dynamicview2 +\example quick/tutorials/dynamicview/dynamicview2 Now that we have a visible list of items we want to be able to interact with them. We'll start by extending the delegate so the visible content can be dragged up and down the screen. The updated delegate looks like this: -\snippet tutorials/dynamicview/dynamicview2/dynamicview.qml 0 +\snippet quick/tutorials/dynamicview/dynamicview2/dynamicview.qml 0 \section2 Walkthrough @@ -109,8 +109,8 @@ for mouse events and will allow us to drag the delegate's content item. It also a container for the content item which is important as a delegate's root item is positioned by the view and cannot be moved by other means. -\snippet tutorials/dynamicview/dynamicview2/dynamicview.qml 1 -\snippet tutorials/dynamicview/dynamicview2/dynamicview.qml 2 +\snippet quick/tutorials/dynamicview/dynamicview2/dynamicview.qml 1 +\snippet quick/tutorials/dynamicview/dynamicview2/dynamicview.qml 2 Dragging the content item is enabled by binding it to the MouseArea's \l {QtQuick2::MouseArea::drag.target}{drag.target} property. Because we still want the view to be @@ -120,14 +120,14 @@ timeout has expired it is interpreted as moving the list and if it moves after i dragging an item. To make it more obvious to the user when an item can be dragged we'll change the background color of the content item when the timeout has expired. -\snippet tutorials/dynamicview/dynamicview2/dynamicview.qml 3 +\snippet quick/tutorials/dynamicview/dynamicview2/dynamicview.qml 3 The other thing we'll need to do before an item can be dragged is to unset any anchors on the content item so it can be freely moved around. We do this in a state change that is triggered when the delegate item is held, at the same time we can reparent the content item to the root item so that is above other items in the stacking order and isn't obscured as it is dragged around. -\snippet tutorials/dynamicview/dynamicview2/dynamicview.qml 4 +\snippet quick/tutorials/dynamicview/dynamicview2/dynamicview.qml 4 */ @@ -139,16 +139,16 @@ so that is above other items in the stacking order and isn't obscured as it is d \previouspage QML Dynamic View Ordering Tutorial 2 - Dragging View Items \nextpage QML Dynamic View Ordering Tutorial 4 - Sorting Items -\example examples/quick/tutorials/dynamicview/dynamicview3 +\example quick/tutorials/dynamicview/dynamicview3 The next step in our application to move items within the list as they're dragged so that we can re-order the list. To achieve this we introduce three new elements to our application; VisualDataModel, \l Drag and DropArea. -\snippet tutorials/dynamicview/dynamicview3/dynamicview.qml 0 -\snippet tutorials/dynamicview/dynamicview3/dynamicview.qml 1 -\snippet tutorials/dynamicview/dynamicview3/dynamicview.qml 2 -\snippet tutorials/dynamicview/dynamicview3/dynamicview.qml 5 +\snippet quick/tutorials/dynamicview/dynamicview3/dynamicview.qml 0 +\snippet quick/tutorials/dynamicview/dynamicview3/dynamicview.qml 1 +\snippet quick/tutorials/dynamicview/dynamicview3/dynamicview.qml 2 +\snippet quick/tutorials/dynamicview/dynamicview3/dynamicview.qml 5 \section2 Walkthrough @@ -156,7 +156,7 @@ In order to re-order the view we need to determine when one item has been dragge the Drag attached property we can generate events that are sent to the scene graph whenever the item it is attached to moves. -\snippet tutorials/dynamicview/dynamicview3/dynamicview.qml 1 +\snippet quick/tutorials/dynamicview/dynamicview3/dynamicview.qml 1 Drag events are only sent while the active property is true, so in this example the first event would be sent when the delegate was held with additional event sents when dragging. The @@ -167,7 +167,7 @@ Then we use a DropArea in each view item to determine when the hot spot of the d intersects another item, when a drag enters one of these DropAreas we can move the dragged item to the index of the item it was dragged over. -\snippet tutorials/dynamicview/dynamicview3/dynamicview.qml 3 +\snippet quick/tutorials/dynamicview/dynamicview3/dynamicview.qml 3 To move the items within the view we use a VisualDataModel. The VisualDataModel element is used by the view elements to instantiate delegate items from model data and when constructed explicitly can @@ -181,7 +181,7 @@ To utilize a VisualDataModel with a ListView we bind it to the \l {QtQuick2::Lis property of the view and bind the \l {QtQuick2::VisualDataModel::model}{model} and \l {QtQuick2::VisualDataModel::delegate}{delegate} to the VisualDataModel. -\snippet tutorials/dynamicview/dynamicview3/dynamicview.qml 4 +\snippet quick/tutorials/dynamicview/dynamicview3/dynamicview.qml 4 */ @@ -192,13 +192,13 @@ property of the view and bind the \l {QtQuick2::VisualDataModel::model}{model} a \contentspage QML Dynamic View Ordering Tutorial \previouspage QML Dynamic View Ordering Tutorial 3 - Moving Dragged Items -\example tutorials/dynamicview/dynamicview4 +\example quick/tutorials/dynamicview/dynamicview4 Drag and drop isn't the only way items in a view can be re-ordered, using a VisualDataModel it is also possible to sort items based on model data. To do that we extend our VisualDataModel instance like this: -\snippet tutorials/dynamicview/dynamicview4/dynamicview.qml 0 +\snippet quick/tutorials/dynamicview/dynamicview4/dynamicview.qml 0 \section2 Walkthrough @@ -209,8 +209,8 @@ we want items to first be added to an unsorted group from where we can transfer position in the items group. To do that we clear includeByDefault on the items group and set it on a new group name 'unsorted'. -\snippet tutorials/dynamicview/dynamicview4/dynamicview.qml 1 -\snippet tutorials/dynamicview/dynamicview4/dynamicview.qml 2 +\snippet quick/tutorials/dynamicview/dynamicview4/dynamicview.qml 1 +\snippet quick/tutorials/dynamicview/dynamicview4/dynamicview.qml 2 We sort the items by first finding the position in the items group to insert the first unsorted item and then transfer the item to the items group before moving it to the pre-determined index and @@ -221,19 +221,19 @@ with the \l {QtQuick2::VisualDataModel::get} {get} function. Through the model handle we can access the same model data that is available in a delegate instance of that item and compare against other items to determine relative position. -\snippet tutorials/dynamicview/dynamicview4/dynamicview.qml 3 +\snippet quick/tutorials/dynamicview/dynamicview4/dynamicview.qml 3 The lessThan argument to the sort function is a comparsion function which will determine the order of the list. In this example it can be one of the following: -\snippet tutorials/dynamicview/dynamicview4/dynamicview.qml 4 +\snippet quick/tutorials/dynamicview/dynamicview4/dynamicview.qml 4 A sort is triggered whenever new items are added to the unsorted VisualDataGroup which we are notified of by the \l {QtQuick2::VisualDataGroup::onChanged}{onChanged} handler. If no sort function is currently selected we simply transfer all items from the unsorted group to the items group, otherwise we call sort with the selected sort function. -\snippet tutorials/dynamicview/dynamicview4/dynamicview.qml 5 +\snippet quick/tutorials/dynamicview/dynamicview4/dynamicview.qml 5 Finally when the selected sort order changes we can trigger a full re-sort of the list by moving all items from the items group to the unsorted group, which will trigger the @@ -241,6 +241,6 @@ all items from the items group to the unsorted group, which will trigger the items group in correct order. Note that the \l {QtQuick2::VisualDataGroup::onChanged}{onChanged} handler will not be invoked recursively so there's no issue with it being invoked during a sort. -\snippet tutorials/dynamicview/dynamicview4/dynamicview.qml 6 +\snippet quick/tutorials/dynamicview/dynamicview4/dynamicview.qml 6 */ diff --git a/src/quick/doc/src/examples.qdoc b/src/quick/doc/src/examples.qdoc index c64664da11..a67876b91e 100644 --- a/src/quick/doc/src/examples.qdoc +++ b/src/quick/doc/src/examples.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/qmltypereference.qdoc b/src/quick/doc/src/qmltypereference.qdoc index e64ee25dbb..9604b927a8 100644 --- a/src/quick/doc/src/qmltypereference.qdoc +++ b/src/quick/doc/src/qmltypereference.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/qtquick-cpp.qdoc b/src/quick/doc/src/qtquick-cpp.qdoc index 54a37f62b6..f8df3eb4a3 100644 --- a/src/quick/doc/src/qtquick-cpp.qdoc +++ b/src/quick/doc/src/qtquick-cpp.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/qtquick.qdoc b/src/quick/doc/src/qtquick.qdoc index 77f89f9868..4326799cab 100644 --- a/src/quick/doc/src/qtquick.qdoc +++ b/src/quick/doc/src/qtquick.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. diff --git a/src/quick/doc/src/tutorial.qdoc b/src/quick/doc/src/tutorial.qdoc index 619f754696..7dbb211cb8 100644 --- a/src/quick/doc/src/tutorial.qdoc +++ b/src/quick/doc/src/tutorial.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -59,7 +59,7 @@ Tutorial chapters: \title QML Tutorial 1 - Basic Types \contentspage QML Tutorial \previouspage QML Tutorial -\nextpage QML Tutorial 2 - QML Component +\nextpage QML Tutorial 2 - QML Components 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. @@ -68,7 +68,7 @@ The picture below is a screenshot of this program. Here is the QML code for the application: -\snippet tutorials/helloworld/tutorial1.qml 0 +\snippet quick/tutorials/helloworld/tutorial1.qml 0 \section1 Walkthrough @@ -77,11 +77,11 @@ Here is the QML code for the application: 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, using: -\snippet tutorials/helloworld/tutorial1.qml 3 +\snippet quick/tutorials/helloworld/tutorial1.qml 3 \section2 Rectangle element -\snippet tutorials/helloworld/tutorial1.qml 1 +\snippet quick/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 "page". @@ -90,7 +90,7 @@ The \l{Rectangle} element contains many other properties (such as \c x and \c y) \section2 Text element -\snippet tutorials/helloworld/tutorial1.qml 2 +\snippet quick/tutorials/helloworld/tutorial1.qml 2 We add a \l Text element as a child of the root Rectangle element that displays the text 'Hello world!'. @@ -133,37 +133,37 @@ The component's filename must always start with a capital letter. Here is the QML code for \c Cell.qml: -\snippet tutorials/helloworld/Cell.qml 0 +\snippet quick/tutorials/helloworld/Cell.qml 0 \section1 Walkthrough \section2 The Cell Component -\snippet tutorials/helloworld/Cell.qml 1 +\snippet quick/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 tutorials/helloworld/Cell.qml 4 +\snippet quick/tutorials/helloworld/Cell.qml 4 We declare a \c cellColor 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{Property Binding in QML}). -\snippet tutorials/helloworld/Cell.qml 5 +\snippet quick/tutorials/helloworld/Cell.qml 5 We want our component to also have a signal that we call \e clicked with a \e cellColor parameter of type \e color. We will use this signal to change the color of the text in the main QML file later. -\snippet tutorials/helloworld/Cell.qml 2 +\snippet quick/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 tutorials/helloworld/Cell.qml 3 +\snippet quick/tutorials/helloworld/Cell.qml 3 In order to change the color of the text when clicking on a cell, we create a \l MouseArea element with the same size as its parent. @@ -175,11 +175,11 @@ When this signal is triggered we want to emit our own \e clicked signal with the In our main QML file, we use our \c Cell component to create the color picker: -\snippet tutorials/helloworld/tutorial2.qml 0 +\snippet quick/tutorials/helloworld/tutorial2.qml 0 We create the color picker by putting 6 cells with different colors in a grid. -\snippet tutorials/helloworld/tutorial2.qml 1 +\snippet quick/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 \e cellColor passed as a parameter. We can react to any signal of our component through a property of the name \e 'onSignalName' (see \l{Signal Attributes}). @@ -190,7 +190,7 @@ We can react to any signal of our component through a property of the name \e 'o \inqmlmodule QtQuick 2 \title QML Tutorial 3 - States and Transitions \contentspage QML Tutorial -\previouspage QML Tutorial 2 - QML Component +\previouspage QML Tutorial 2 - QML Components In this chapter, we make this example a little bit more dynamic by introducing states and transitions. @@ -200,11 +200,11 @@ We want our text to move to the bottom of the screen, rotate and become red when Here is the QML code: -\snippet tutorials/helloworld/tutorial3.qml 0 +\snippet quick/tutorials/helloworld/tutorial3.qml 0 \section1 Walkthrough -\snippet tutorials/helloworld/tutorial3.qml 2 +\snippet quick/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 MouseArea is pressed, and deactivated when it is released. @@ -213,13 +213,13 @@ The \e down state includes a set of property changes from our implicit \e {defau (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 tutorials/helloworld/tutorial3.qml 3 +\snippet quick/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 \li down state. +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. diff --git a/src/quick/doc/src/whatsnew.qdoc b/src/quick/doc/src/whatsnew.qdoc index 0c382ec742..3959a1b5eb 100644 --- a/src/quick/doc/src/whatsnew.qdoc +++ b/src/quick/doc/src/whatsnew.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. |