diff options
1736 files changed, 222 insertions, 167783 deletions
diff --git a/doc/config/qtquick.qdocconf b/doc/config/qtquick.qdocconf index a4c7a352e0..69e860919e 100644 --- a/doc/config/qtquick.qdocconf +++ b/doc/config/qtquick.qdocconf @@ -21,9 +21,6 @@ imagedirs += ../src/images \ sourcedirs += ../src \ ../../src -excludedirs += ../src/qtquick1 \ - ../../src/qtquick1 - #indexes = $QT5DOC/doc/html/qt.index # The following parameters are for creating a qhp file, the qhelpgenerator diff --git a/doc/src/declarative/qmltest.qdoc b/doc/src/declarative/qmltest.qdoc index e9340d8137..640275cf93 100644 --- a/doc/src/declarative/qmltest.qdoc +++ b/doc/src/declarative/qmltest.qdoc @@ -104,21 +104,4 @@ \code IMPORTPATH += $$PWD/../imports/my_module1 $$PWD/../imports/my_module2 \endcode - - \section1 Running tests with QtQuick 1 - - The \c{-qtquick1} option can be passed to a test binary to run - the tests using QDeclarativeView (QtQuick 1) rather than QQuickView (QtQuick 2): - - \code - tst_example -qtquick1 - \endcode - - To run tests with either QtQuick 1 or QtQuick 2, use - "import QtQuick 1.0" in your unit tests and then specify - compatibility mode to the QtQuick2 engine: - - \code - QMLSCENE_IMPORT_NAME=quick1 tst_example - \endcode */ diff --git a/doc/src/declarative/qtquick1.qdoc b/doc/src/declarative/qtquick1.qdoc deleted file mode 100644 index a64fc7d91d..0000000000 --- a/doc/src/declarative/qtquick1.qdoc +++ /dev/null @@ -1,40 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \qmlmodule QtQuick 1 - \title QML Module QtQuick 1 - - \brief The QML Elements - - This QML module contains all the QML elements that are - instantiated as objects of C++ classes in the QtQuick1 - module. These elements are QGraphicsObject based, and - work with the Graphics View framework. In Qt 5, they - have been replaced by \l{QtQuick 2}, based on the - Scenegraph renderer. - */ diff --git a/doc/src/declarative/whatsnew.qdoc b/doc/src/declarative/whatsnew.qdoc index 3121080c7a..4e67bac407 100644 --- a/doc/src/declarative/whatsnew.qdoc +++ b/doc/src/declarative/whatsnew.qdoc @@ -148,15 +148,12 @@ New elements have been added for contructing paths: PathArc, PathCurve, PathSvg. \section2 QtQuick 1 is now a separate library and module Writing C++ applications using QtQuick 1 specific API, i.e. QDeclarativeView or QDeclarativeItem -requires adding the "qtquick1" module to the .pro file, e.g. QT += declarative qtquick1 +requires adding the "quick1" module to the .pro file, e.g. QT += quick1 QDeclarativeView and QDeclarativeItem headers are now in the QtQuick 1 module, i.e. #include <QtQuick1/QDeclarativeView> #include <QtQuick1/QDeclarativeItem> -"import QtQuick 1.0" loads the module dynamically. To deploy QtQuick 1 applications -the library (lib/libQtQuick1*) and plugin (imports/QtQuick/) must be installed. - \sa {What's New in Qt Quick 1}{What's New in Qt Quick 1} */ diff --git a/doc/src/qtquick1/advtutorial.qdoc b/doc/src/qtquick1/advtutorial.qdoc deleted file mode 100644 index 5921488803..0000000000 --- a/doc/src/qtquick1/advtutorial.qdoc +++ /dev/null @@ -1,470 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-advtutorial.html -\inqmlmodule QtQuick 1 -\title QML Advanced Tutorial -\brief A more advanced tutorial, showing how to use QML to create a game. -\nextpage QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks - -This tutorial walks step-by-step through the creation of a full application using QML. -It assumes that you already know the basics of QML (for example, from reading the -\l{QML Tutorial}{simple tutorial}). - -In this tutorial we write a game, \e {Same Game}, based on the Same Game application -included in the declarative \c examples directory, which looks like this: - -\image declarative-samegame.png - -We will cover concepts for producing a fully functioning application, including -JavaScript integration, using QML \l{State}{States} and \l{Behavior}{Behaviors} to -manage components and enhance your interface, and storing persistent application data. - -An understanding of JavaScript is helpful to understand parts of this tutorial, but if you don't -know JavaScript you can still get a feel for how you can integrate backend logic to create and -control QML elements. - - -Tutorial chapters: - -\list 1 -\o \l {declarative/tutorials/samegame/samegame1}{Creating the Game Canvas and Blocks} -\o \l {declarative/tutorials/samegame/samegame2}{Populating the Game Canvas} -\o \l {declarative/tutorials/samegame/samegame3}{Implementing the Game Logic} -\o \l {declarative/tutorials/samegame/samegame4}{Finishing Touches} -\endlist - -All the code in this tutorial can be found in Qt's \c examples/declarative/tutorials/samegame -directory. -*/ - -/*! -\page qml-advtutorial1.html -\inqmlmodule QtQuick 1 -\title QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks -\contentspage QML Advanced Tutorial -\previouspage QML Advanced Tutorial -\nextpage QML Advanced Tutorial 2 - Populating the Game Canvas - -\example declarative/tutorials/samegame/samegame1 - -\section2 Creating the application screen - -The first step is to create the basic QML items in your application. - -To begin with, we create our Same Game application with a main screen like this: - -\image declarative-adv-tutorial1.png - -This is defined by the main application file, \c samegame.qml, which looks like this: - -\snippet declarative/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. - -One item you may not recognize here -is the \l SystemPalette item. This provides access to the Qt system palette -and is used to give the button a more native look-and-feel. - -Notice the anchors for the \c Item, \c Button and \c Text elements are set using -\l {qdeclarativeintroduction.html#dot-properties}{group notation} for readability. - -\section2 Adding \c Button and \c Block components - -The \c Button item in the code above is defined in a separate component file named \c Button.qml. -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 declarative/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 -\c container when the area is clicked. - -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 declarative/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. -We have not added any code yet to create the blocks; we will do this -in the next chapter. - -We have set the image to be the size of its parent Item using \c {anchors.fill: parent}. -This means that when we dynamically create and resize the block items -later on in the tutorial, the image will be scaled automatically to the -correct size. - -Notice the relative path for the Image element's \c source property. -This path is relative to the location of the file that contains the \l Image element. -Alternatively, you could set the Image source to an absolute file path or a URL -that contains an image. - -You should be familiar with the code so far. We have just created some basic -elements to get started. Next, we will populate the game canvas with some blocks. -*/ - - -/*! -\page qml-advtutorial2.html -\inqmlmodule QtQuick 1 -\title QML Advanced Tutorial 2 - Populating the Game Canvas -\contentspage QML Advanced Tutorial -\previouspage QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks -\nextpage QML Advanced Tutorial 3 - Implementing the Game Logic - -\example declarative/tutorials/samegame/samegame2 - -\section2 Generating the blocks in JavaScript - -Now that we've written some basic elements, let's start writing the game. - -The first task is to generate the game blocks. Each time the New Game button -is clicked, the game canvas is populated with a new, random set of -blocks. Since we need to dynamically generate new blocks for each new game, -we cannot use \l Repeater to define the blocks. Instead, we will -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 declarative/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. -Then, it creates an array to store all the game -blocks, and calls \c createBlock() to create enough blocks to fill the game window. - -The \c createBlock() function creates a block from the \c Block.qml file -and moves the new block to its position on the game canvas. This involves several steps: - -\list - -\o \l {QML:Qt::createComponent()}{Qt.createComponent()} is called to - generate an element from \c Block.qml. If the component is ready, - we can call \c createObject() to create an instance of the \c Block - item. - -\o If \c createObject() returned null (i.e. if there was an error - while loading the object), print the error information. - -\o Place the block in its position on the board and set its width and - height. Also, store it in the blocks array for future reference. - -\o Finally, print error information to the console if the component - could not be loaded for some reason (for example, if the file is - missing). - -\endlist - - -\section2 Connecting JavaScript components to QML - -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{Modules#QML Modules}{module}: - -\snippet declarative/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 declarative/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: - -\image declarative-adv-tutorial2.png - -Now, we have a screen of blocks, and we can begin to add the game mechanics. - -*/ - -/*! -\page qml-advtutorial3.html -\inqmlmodule QtQuick 1 -\title QML Advanced Tutorial 3 - Implementing the Game Logic -\contentspage QML Advanced Tutorial -\previouspage QML Advanced Tutorial 2 - Populating the Game Canvas -\nextpage QML Advanced Tutorial 4 - Finishing Touches - -\example declarative/tutorials/samegame/samegame3 - -\section2 Making a playable game - -Now that we have all the game components, we can add the game logic that -dictates how a player interacts with the blocks and plays the game -until it is won or lost. - -To do this, we have added the following functions to \c samegame.js: - -\list -\o \c{handleClick(x,y)} -\o \c{floodFill(xIdx,yIdx,type)} -\o \c{shuffleDown()} -\o \c{victoryCheck()} -\o \c{floodMoveCheck(xIdx, yIdx, type)} -\endlist - -As this is a tutorial about QML, not game design, we will only discuss \c handleClick() and \c victoryCheck() below since they interface directly with the QML elements. Note that although the game logic here is written in JavaScript, it could have been written in C++ and then exposed to QML. - -\section3 Enabling mouse click interaction - -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 declarative/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 -the application scales to the available screen size. -Since its size is bound to a multiple of \c blockSize, \c blockSize was moved out of \c samegame.js and into \c samegame.qml as a QML property. -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 declarative/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. - -\section3 Updating the score - -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 declarative/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 declarative/tutorials/samegame/samegame3/Dialog.qml 0 - -And this is how it is used in the main \c samegame.qml file: - -\snippet declarative/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. - - -\section3 A dash of color - -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 declarative/tutorials/samegame/samegame3/Block.qml 0 - - -\section2 A working game - -Now we now have a working game! The blocks can be clicked, the player can score, and the game can end (and then you can start a new one). -Here is a screenshot of what has been accomplished so far: - -\image declarative-adv-tutorial3.png - -This is what \c samegame.qml looks like now: - -\snippet declarative/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 -until the next chapter - where your application becomes alive! - -*/ - -/*! -\page qml-advtutorial4.html -\inqmlmodule QtQuick 1 -\title QML Advanced Tutorial 4 - Finishing Touches -\contentspage QML Advanced Tutorial -\previouspage QML Advanced Tutorial 3 - Implementing the Game Logic - -\example declarative/tutorials/samegame/samegame4 - -\section2 Adding some flair - -Now we're going to do two things to liven up the game: animate the blocks and add a High Score system. - -We've also cleaned up the directory structure for our application files. We now have a lot of files, so all the -JavaScript and QML files outside of \c samegame.qml have been moved into a new sub-directory named "content". - -In anticipation of the new block animations, \c Block.qml file is now renamed to \c BoomBlock.qml. - -\section3 Animating block movement - -First we will animate the blocks so that they move in a fluid manner. QML has a number of methods for adding fluid -movement, and in this case we're going to use the \l Behavior element to add a \l SpringAnimation. -In \c BoomBlock.qml, we apply a \l SpringAnimation behavior to the \c x and \c y properties so that the -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 declarative/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. - -The \c {enabled: spawned} setting refers to the \c spawned value that is set from \c createBlock() in \c samegame.js. -This ensures the \l SpringAnimation on the \c x is only enabled after \c createBlock() has set the block to -the correct position. Otherwise, the blocks will slide out of the corner (0,0) when a game begins, instead of falling -from the top in rows. (Try commenting out \c {enabled: spawned} and see for yourself.) - -\section3 Animating block opacity changes - -Next, we will add a smooth exit animation. For this, we'll use a \l Behavior element, which allows us to specify -a default animation when a property change occurs. In this case, when the \c opacity of a Block changes, we will -animate the opacity value so that it gradually fades in and out, instead of abruptly changing between fully -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 declarative/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, -but instead we'll use \l{QML States}{states}, since this is useful for the next animation we're going to add. -Initially, we add these States to the root element of \c{BoomBlock.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 blocks will automatically fade in, as we already set \c spawned to true when we implemented the block animations. -To fade out, we set \c dying to true instead of setting opacity to 0 when a block is destroyed (in the \c floodFill() function). - -\section3 Adding particle effects - -Finally, we'll add a cool-looking particle effect to the blocks when they are destroyed. To do this, we first add a \l Particles element in -\c BoomBlock.qml, like so: - -\snippet declarative/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 emissionRate 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 declarative/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: - -\image declarative-adv-tutorial4.gif - -The theme change here is produced simply by replacing the block images. This can be done at runtime by changing the \l Image \c source property, so for a further challenge, you could add a button that toggles between themes with different images. - -\section2 Keeping a High Scores table - -Another feature we might want to add to the game is a method of storing and retrieving high scores. - -To do this, we will show a dialog when the game is over to request the player's name and add it to a High Scores table. -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 declarative/tutorials/samegame/samegame4/content/Dialog.qml 0 -\dots 4 -\snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 2 -\dots 4 -\snippet declarative/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 declarative/tutorials/samegame/samegame4/content/Dialog.qml 0 -\snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 1 -\dots 4 -\snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 3 - -Now the dialog can be used in \c samegame.qml: - -\snippet declarative/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 declarative/tutorials/samegame/samegame4/content/samegame.js 3 -\dots 4 -\snippet declarative/tutorials/samegame/samegame4/content/samegame.js 4 - -\section3 Storing high scores offline - -Now we need to implement the functionality to actually save the High Scores table. - -Here is the \c saveHighScore() function in \c samegame.js: - -\snippet declarative/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. - -Then, we use the \l{Offline Storage API} to maintain a persistent SQL database unique to this application. We create an offline storage database for the high scores using \c 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 retrieval, and in the \c 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. - -This is one way of storing and displaying high scores locally, but certainly not the only way. A more complex alternative would be to create a high score dialog component, and pass it the results for processing and display (instead of reusing the \c Dialog). This would allow a more themeable dialog that could better present the high scores. 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 or in another SQL database. - -\section3 Storing high scores online - -You've seen how you can store high scores locally, but it is also easy to integrate a web-enabled high score storage into your QML application. The implementation we've done her 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 also request an XML or QML file from that same server, which contains and displays the scores, -but that's beyond the scope of this tutorial. The php script we use here is available in the \c examples directory. - -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 declarative/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 -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 with 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). - - -\section2 That's it! - -By following this tutorial you've seen how you can write a fully functional application in QML: - -\list -\o Build your application with \l {{QML Elements}}{QML elements} -\o Add application logic \l{Integrating JavaScript}{with JavaScript code} -\o Add animations with \l {Behavior}{Behaviors} and \l{QML States}{states} -\o Store persistent application data using, for example, the \l{Offline Storage API} or \l XMLHttpRequest -\endlist - -There is so much more to learn about QML that we haven't been able to cover in this tutorial. Check out all the -examples and the \l {Qt Quick}{documentation} to see all the things you can do with QML! -*/ diff --git a/doc/src/qtquick1/anchor-layout.qdoc b/doc/src/qtquick1/anchor-layout.qdoc deleted file mode 100644 index b7b1480649..0000000000 --- a/doc/src/qtquick1/anchor-layout.qdoc +++ /dev/null @@ -1,145 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-anchor-layout.html -\inqmlmodule QtQuick 1 -\target anchor-layout -\contentspage QML Features -\previouspage {Using QML Positioner and Repeater Items}{Component Layouts} -\nextpage {QML Mouse Events}{Mouse Events} -\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 \e anchors. -Each item can be thought of as having a set of 7 invisible "anchor lines": -\l {Item::anchors.left}{left}, \l {Item::anchors.horizontalCenter}{horizontalCenter}, -\l {Item::anchors.right}{right}, \l {Item::anchors.top}{top}, -\l {Item::anchors.verticalCenter}{verticalCenter}, \l {Item::anchors.baseline}{baseline}, -and \l {Item::anchors.bottom}{bottom}. - -\image edges_qml.png - -The baseline (not pictured above) corresponds to the imaginary line on which -text would sit. For items with no text it is the same as \e top. - -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 - - -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. Below, -\e rect2 is anchored to the right of \e rect1 and the left of \e rect3. If either of the blue -rectangles are moved, \e rect2 will stretch and shrink as necessary: - -\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 - -There are also some convenience anchors. anchors.fill is a convenience that is the same as setting the left,right,top and bottom anchors -to the left,right,top and bottom of the target item. anchors.centerIn is another convenience anchor, and is the same as setting the verticalCenter -and horizontalCenter anchors to the verticalCenter and horizontalCenter of the target item. - -\section1 Anchor Margins and Offsets - -The anchoring system also allows \e margins and \e offsets to be specified for an item's anchors. -Margins specify the amount of empty space to leave to the outside of an item's anchor, while -offsets allow positioning to be manipulated using the center anchor lines. An item can -specify its anchor margins individually through \l {Item::anchors.leftMargin}{leftMargin}, -\l {Item::anchors.rightMargin}{rightMargin}, \l {Item::anchors.topMargin}{topMargin} and -\l {Item::anchors.bottomMargin}{bottomMargin}, or use \l {Item::}{anchors.margins} to -specify the same margin value for all four edges. Anchor offsets are specified using -\l {Item::anchors.horizontalCenterOffset}{horizontalCenterOffset}, -\l {Item::anchors.verticalCenterOffset}{verticalCenterOffset} and -\l {Item::anchors.baselineOffset}{baselineOffset}. - -\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 - -\note Anchor margins only apply to anchors; they are \e not a generic means of applying margins to an \l Item. -If an anchor margin is specified for an edge but the item is not anchored to any item on that -edge, the margin is not applied. - - -\section1 Restrictions - -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 -Item { - id: group1 - Rectangle { id: rect1; ... } -} -Item { - id: group2 - Rectangle { id: rect2; anchors.left: rect1.right; ... } // invalid anchor! -} -\endcode - -Also, anchor-based layouts cannot be mixed with absolute positioning. If an item specifies its -\l {Item::}{x} position and also sets \l {Item::}{anchors.left}, -or anchors its left and right edges but additionally sets a \l {Item::}{width}, the -result is undefined, as it would not be clear whether the item should use anchoring or absolute -positioning. The same can be said for setting an item's \l {Item::}{y} and \l {Item::}{height} -with \l {Item::}{anchors.top} and \l {Item::}{anchors.bottom}, or setting \l {Item::}{anchors.fill} -as well as \l {Item::}{width} or \l {Item::}{height}. The same applies when using positioners -such as Row and Grid, which may set the item's \l {Item::}{x} and \l {Item::}{y} properties. -If you wish to change from using -anchor-based to absolute positioning, you can clear an anchor value by setting it to \c undefined. - -*/ diff --git a/doc/src/qtquick1/animation.qdoc b/doc/src/qtquick1/animation.qdoc deleted file mode 100644 index 97c6a720a2..0000000000 --- a/doc/src/qtquick1/animation.qdoc +++ /dev/null @@ -1,274 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativeanimation.html -\inqmlmodule QtQuick 1 -\ingroup qml-features -\contentspage QML Features -\previouspage {QML States}{States} -\nextpage {QML Data Models}{Structuring Data with Models} -\title QML Animation and Transitions - -\keyword qml-animation-elements -\section1 Animation and Transitions Elements -\list -\o \l {Transition} - Animates transitions during state changes -\o \l {SequentialAnimation} - Runs animations sequentially -\o \l {ParallelAnimation} - Runs animations in parallel -\o \l {Behavior} - Specifies a default animation for property changes -\o \l {PropertyAction} - Sets immediate property changes during animation -\o \l {PauseAnimation} - Introduces a pause in an animation -\o \l {SmoothedAnimation} - Allows a property to smoothly track a value -\o \l {SpringAnimation} - Allows a property to track a value in a spring-like motion -\o \l {ScriptAction} - Runs scripts during an animation -\endlist - -\keyword qml-property-animation-elements -Elements that animate properties based on data types -\list -\o \l {PropertyAnimation} - Animates property changes -\o \l {NumberAnimation} - Animates properties of type qreal -\o \l {Vector3dAnimation} - Animates properties of type QVector3d -\o \l {ColorAnimation} - Animates color changes -\o \l {RotationAnimation} - Animates rotations -\o \l {ParentAnimation} - Animates parent changes -\o \l {AnchorAnimation} - Animates anchor changes -\endlist - -In QML, animations are created by applying animation elements to property -values. Animation elements will interpolate property values to create smooth -transitions. As well, state transitions may assign animations to state changes. - -To create an animation, use an appropriate animation element for the type of -the property that is to be animated, and apply the animation depending on the -type of behavior that is required. - -\keyword qml-triggering-animations -\section1 Triggering Animations - -There are several ways of setting animation to an object. - -\keyword qml-direct-animation -\section2 Direct Property Animation - -To create an immediate movement or animated movement, set the property value -directly. This may be done in signal handlers or attached properties. - -\snippet doc/src/snippets/declarative/animation.qml direct property change - -However, to create more control, \e {property animations} apply smooth movements -by interpolating values between property value changes. Property animations -provide timing controls and allows different interpolations through -\l{qml-easing-animation}{easing curves}. - -\snippet doc/src/snippets/declarative/animation.qml property animation - -Specialized \l{qml-property-animation-elements}{property animation elements} -have more efficient implementations than the \l{PropertyAnimation} element. They -are for setting animations to different QML types such as \c int, \c color, and -rotations. Similarly, the \l{ParentAnimation} can animate parent changes. - -See the \l {qml-controlling-animations}{Controlling Animations} section for more -information about the different animation properties. - -\keyword qml-transition-animations -\section2 Transitions during State Changes - -\l{QML States}{States} are property configurations where a property may have different values to reflect different states. State changes introduce -abrupt property changes; animations smooth transitions to produce visually -appealing state changes. - -The \l{Transition} element can contain -\l{qml-animation-elements}{animation elements} to interpolate property changes -caused by state changes. To assign the transition to an object, bind it to the -\c transitions property. - -A button might have two states, the \c pressed state when the user clicks on the -button and a \c released state when the user releases the button. We can assign -different property configurations for each state. A transition would animate the -change from the \c pressed state to the \c released state. Likewise, there would -be an animation during the change from the \c released state to the \c pressed -state. - -\snippet doc/src/snippets/declarative/animation.qml transition animation - -Binding the \c to and \c from properties to the state's name will assign that -particular transition to the state change. For simple or symmetric transitions, -setting the to \c to property to the wild card symbol, "\c{*}", denotes -that the transition applies to any state change. - -\snippet doc/src/snippets/declarative/animation.qml wildcard animation - -\section2 Default Animation as Behaviors - -Default property animations are set using \e {behavior animations}. Animations -declared in \l {Behavior} elements apply to the property and animates any -property value changes. However, Behavior elements have an -\c enabled property to purposely enable or disable the behavior animations. - -A ball component might have a behavior animation assigned to its \c x, \c y, and -\c color properties. The behavior animation could be set up to simulate an -elastic effect. In effect, this behavior animation would apply the elastic -effect to the properties whenever the ball moves. - -\snippet doc/src/snippets/declarative/animation.qml behavior animation - -There are several methods of assigning behavior animations to properties. The -\c{Behavior on <property>} declaration is a convenient way of assigning a -behavior animation onto a property. - -See the \l {declarative/animation/behaviors}{Behaviors example} for a -demonstration of behavioral animations. - -\section1 Playing Animations in Parallel or in Sequence - -Animations can run \e {in parallel} or \e {in sequence}. Parallel animations -will play a group of animations at the same time while sequential animations -play a group of animations in order: one after the other. Grouping animations in -\l{SequentialAnimation} and \l{ParallelAnimation} will play the animations in -sequence or in parallel. - -A banner component may have several icons or slogans to display, one after the -other. The \c opacity property could transform to \c 1.0 denoting an opaque -object. Using the \l{SequentialAnimation} element, the opacity animations will -play after the preceding animation finishes. The \l{ParallelAnimation} element -will play the animations at the same time. - -\snippet doc/src/snippets/declarative/animation.qml sequential animation - -Once individual animations are placed into a SequentialAnimation or -ParallelAnimation, they can no longer be started and stopped independently. The -sequential or parallel animation must be started and stopped as a group. - -The \l SequentialAnimation element is also useful for playing -\l{qml-transition-animations}{transition animations} because animations are -played in parallel inside transitions. - -See the \l {declarative/animation/basics}{Animation basics example} for a -demonstration of creating and combining multiple animations in QML. - -\keyword qml-controlling-animations -\section1 Controlling Animations - -There are different methods to control animations. - -\section2 Animation Playback -All \l{qml-animation-elements}{animation elements} inherit from the \l Animation element. It is not -possible to create \l Animation objects; instead, this element provides the -essential properties and methods for animation elements. Animation elements have -\c{start()}, \c{stop()}, \c{resume()}, \c{pause()}, \c {restart()}, and -\c{complete()} -- all of these methods control the execution of animations. - -\keyword qml-easing-animation -\section2 Easing - -Easing curves define how the animation will interpolate between the start value -and the end value. Different easing curves might go beyond the defined range of -interpolation. The easing curves simplify the creation of animation effects such -as bounce effects, acceleration, deceleration, and cyclical animations. - -A QML object may have different easing curve for each property animation. There -are also different parameters to control the curve, some of which are exclusive -to a particular curve. For more information about the easing curves, visit the -\l {PropertyAnimation::easing.type}{easing} documentation. - -The \l{declarative/animation/easing}{easing example} visually demonstrates each -of the different easing types. - -\section2 Other Animation Elements - -In addition, QML provides several other elements useful for animation: - -\list -\o PauseAnimation: enables pauses during animations -\o ScriptAction: allows JavaScript to be executed during an animation, and can -be used together with StateChangeScript to reused existing scripts -\o PropertyAction: changes a property \e immediately during an animation, -without animating the property change -\endlist - -These are specialized animation elements that animate different property types -\list -\o SmoothedAnimation: a specialized NumberAnimation that provides smooth -changes in animation when the target value changes -\o SpringAnimation: provides a spring-like animation with specialized -attributes such as \l {SpringAnimation::}{mass}, -\l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon} -\o ParentAnimation: used for animating a parent change (see ParentChange) -\o AnchorAnimation: used for animating an anchor change (see AnchorChanges) -\endlist - -\section1 Sharing Animation Instances - -Sharing animation instances between Transitions or Behaviors is not -supported, and may lead to undefined behavior. In the following example, -changes to the Rectangle's position will most likely not be correctly animated. - -\qml -Rectangle { - // NOT SUPPORTED: this will not work correctly as both Behaviors - // try to control a single animation instance - NumberAnimation { id: anim; duration: 300; easing.type: Easing.InBack } - Behavior on x { animation: anim } - Behavior on y { animation: anim } -} -\endqml - -The easiest fix is to repeat the NumberAnimation for both Behaviors. If the repeated -animation is rather complex, you might also consider creating a custom animation -component and assigning an instance to each Behavior, for example: - -\qml -// MyNumberAnimation.qml -NumberAnimation { id: anim; duration: 300; easing.type: Easing.InBack } -\endqml - -\qml -// main.qml -Rectangle { - Behavior on x { MyNumberAnimation {} } - Behavior on y { MyNumberAnimation {} } -} -\endqml - -*/ - - - -\snippet doc/src/snippets/declarative/animation-elements.qml color -\snippet doc/src/snippets/declarative/animation-propertyvaluesource.qml 0 -\snippet doc/src/snippets/declarative/animation-signalhandler.qml 0 -\snippet doc/src/snippets/declarative/animation-standalone.qml 0 - -\snippet doc/src/snippets/declarative/animation-transitions.qml 0 -\snippet doc/src/snippets/declarative/animation-groups.qml 0 - -\snippet doc/src/snippets/declarative/animation-groups.qml 1 -\snippet doc/src/snippets/declarative/animation-groups.qml 0 -\image propanim.gif - diff --git a/doc/src/qtquick1/basicelements.qdoc b/doc/src/qtquick1/basicelements.qdoc deleted file mode 100644 index 836a102723..0000000000 --- a/doc/src/qtquick1/basicelements.qdoc +++ /dev/null @@ -1,115 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmlbasicelements.html -\inqmlmodule QtQuick 1 -\ingroup qml-features -\contentspage QML Features -\previouspage QML Features -\nextpage {QML Basic Types}{Data Types} - -\title QML Basic Elements - -QML's basic elements allow the easy inclusion of objects into the -scene. - -\section1 Basic Elements -This is a list of some of the elements readily available for users. -\list -\o \l {Item} -\o \l {Rectangle} -\o \l {Image} -\o \l {Text} -\o \l {TextInput} -\o \l {TextEdit} -\o \l {FocusScope} -\o \l {Component} -\o \l {MouseArea} -\endlist - -For a complete list of QML elements, please visit the \l {QML Elements} page. - -\section1 Properties and Qt Declarative Module - -When using QML elements, keep in mind that elements may possess properties that -other elements also possess. This is because QML and its underlying engine is -implemented in C++ using Qt. More importantly, the chain of property inheritance -is directly due to QML's use of the \l {Qt Declarative Module} and Qt's -\l {Meta-Object System}{meta-object} and \l {The Property System}{property} systems. For example, visual elements that have C++ implementation are sublcasses of -\l {QDeclarativeItem}. As a result, elements such as \l {Rectangle} and -\l {Text} elements inherit properties such as \c clip and \c smooth. - -\section1 Item Element - -Many QML elements inherit \l Item properties. \c Item possesses important properties -such as \c focus, \c children, and dimension properties such as \c width and -\c height. Although \c Item has physical properties, it is not a visual element. -Using \c Item as the top-level QML element (as the screen) will not produce a -visual result, use the \l {Rectangle} element instead. Use the \c Item to create -opacity effects, such as when creating an invisible container to hold other -components. - -\section1 Rectangle Element - -The \l Rectangle element is the basic visual element, for displaying different -types of items onto the screen. The \c Rectangle is customizable and utilizes -other elements such as \l Gradient and \l BorderImage for displaying advanced -customized graphics. - -\section1 Image Element - -To insert an image into a QML scene, merely declare an \l Image element. The -\c Image element can load images in formats supported by Qt. - -\section1 Text Elements - -The \l Text and \l TextEdit elements display formatted text onto the screen. -\c TextEdit features multi-line editing while the \l TextInput element is for -single line text input. - -\keyword qml-top-level-component -\section1 Using Elements as the Top-Level Component - -For creating components (or displaying a simple scene), there are different -elements that could be used as the top-level component. To display a simple scene, -a \l Rectangle as the top-level component may suffice. \l Rectangle, -\l FocusScope, \l Component, \l {QML:QtObject} {QtObject}, \l Item, are some of -the commonly used elements as the top-level component. - -When importing components, the top-level component is important because the -top-level component's properties are the only properties exposed to the parent. - -For example, a \c Button component may be implemented using different elements as -its top-level component. When this component is loaded into another QML scene, -the component will retain the top-level component's properties. If a non-visual -component is the top-level component, the visual properties should be aliased to -the top-level to display the component properly. - -For more information on how to build upon QML elements, see the -\l{Importing Reusable Components} document. -*/ diff --git a/doc/src/qtquick1/basictypes.qdoc b/doc/src/qtquick1/basictypes.qdoc deleted file mode 100644 index 2cc8859dc2..0000000000 --- a/doc/src/qtquick1/basictypes.qdoc +++ /dev/null @@ -1,597 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qdeclarativebasictypes.html -\inqmlmodule QtQuick 1 - \ingroup qml-features - \contentspage QML Features - \previouspage {QML Basic Elements} - \nextpage Property Binding - \title QML Basic Types - - QML has a set of primitive types, as listed below, that are used throughout - the \l {QML Elements}. - - \annotatedlist qmlbasictypes - - To create additional types, such as data types created in C++, read the - \l{Extending QML Functionalities using C++} article. -*/ - -/*! - \qmlbasictype int - \ingroup qmlbasictypes - - \brief An integer is a whole number, e.g. 0, 10, or -20. - - An integer is a whole number, e.g. 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 - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype bool - \ingroup qmlbasictypes - - \brief A boolean is a binary true/false value. - - A boolean is a binary true/false value. - - Example: - \qml - Item { focus: true; clip: false } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype real - \ingroup qmlbasictypes - - \brief A real number has a decimal point, e.g. 1.2 or -29.8. - - A real number has a decimal point, e.g. 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. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype double - \ingroup qmlbasictypes - - \brief A double number has a decimal point and is stored in double precision. - - A double number has a decimal point and is stored in double precision, \l - {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} - format. - - Example: - \qml - Item { - property double number: 32155.2355 - } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype string - \ingroup qmlbasictypes - - \brief A string is a free form text in quotes, e.g. "Hello world!". - - A string is a free form text in quotes, e.g. "Hello world!". - - Example: - \qml - Text { text: "Hello world!" } - \endqml - - Strings have a \c length attribute that holds the number of - characters in the string. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype url - \ingroup qmlbasictypes - - \brief A URL is a resource locator, like a file name. - - A URL is a resource locator, like a file name. It can be either - absolute, e.g. "http://qt.nokia.com", or relative, e.g. - "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 - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype color - \ingroup qmlbasictypes - - \brief A color is a standard color name in quotes. - - A color is a standard color name in quotes. It is normally 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: - \div{float-right} - \inlineimage declarative-colors.png - \enddiv - \snippet doc/src/snippets/declarative/colors.qml colors - - Or with the \l{QML:Qt::rgba()}{Qt.rgba()}, \l{QML:Qt::hsla()}{Qt.hsla()}, \l{QML:Qt::darker()}{Qt.darker()}, - \l{QML:Qt::lighter()}{Qt.lighter()} or \l{QML:Qt::tint()}{Qt.tint()} functions: - - \qml - Rectangle { color: Qt.rgba(0.5, 0.5, 0, 1) } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype point - \ingroup qmlbasictypes - - \brief A point type has x and y attributes. - - A \c point type has \c x and \c y attributes. - - To create a \c point value, specify it as a "x,y" string: - - \qml - CustomObject { myPointProperty: "0,20" } - \endqml - - Or use the \l{QML:Qt::point()}{Qt.point()} function: - - \qml - CustomObject { myPointProperty: Qt.point(0, 20) } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype size - \ingroup qmlbasictypes - - \brief A size type has width and height attributes - - A \c size type has \c width and \c height attributes. - - For example, to read the \l {Image::sourceSize} \c size property: - - \qml - Column { - Image { id: image; source: "logo.png" } - Text { text: image.sourceSize.width + "," + image.sourceSize.height } - } - \endqml - - To create a \c size value, specify it as a "width x height" string: - - \qml - LayoutItem { preferredSize: "150x50" } - \endqml - - Or use the \l{QML:Qt::size()}{Qt.size()} function: - - \qml - LayoutItem { preferredSize: Qt.size(150, 50) } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype rect - \ingroup qmlbasictypes - - \brief A rect type has x, y, width and height attributes. - - A \c rect type has \c x, \c y, \c width and \c height attributes. - - For example, to read the \l {Item::childrenRect.x}{Item::childrenRect} \c rect property: - \qml - Rectangle { - width: childrenRect.width - height: childrenRect.height - - Rectangle { width: 100; height: 100 } - } - \endqml - - To create a \c rect value, specify it as a "x, y, width x height" string: - - \qml - CustomObject { myRectProperty: "50,50,100x100" } - \endqml - - Or use the \l{QML:Qt::rect()}{Qt.rect()} function: - - \qml - CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype date - \ingroup qmlbasictypes - - \brief A date is specified as "YYYY-MM-DD". - - To create a \c date value, specify it as a "YYYY-MM-DD" string: - - Example: - \qml - MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" } - \endqml - - To read a date value returned from a C++ extension class, use - \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype time - \ingroup qmlbasictypes - - \brief A time is specified as "hh:mm:ss". - - A time is specified as "hh:mm:ss". - - Example: - \qml - MyTimePicker { time: "14:22:15" } - \endqml - - To read a time value returned from a C++ extension class, use - \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}. - - \sa {QML Basic Types} - */ - -/*! - \qmlbasictype font - \ingroup qmlbasictypes - - \brief A font type has the properties of a QFont. - - A font type has the properties of a QFont. The properties are: - - \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 - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype action - \ingroup qmlbasictypes - - \brief The action type has all the properties of QAction. - - The action type has all the properties of QAction. The properties - are: - - \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 - Item { - MouseArea { onClicked: myaction.trigger() } - State { name: "enabled"; when: myaction.enabled == true } - Text { text: someaction.text } - } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype list - \ingroup qmlbasictypes - - \brief A list of objects. - - A list type contains a list of objects. While not technically - a basic type, QML supports lists of object types. When used - from QML, the engine automatically appends each value to the list. - Items in the list can be accessed by index using the usual - \c listName[index] syntax. - - For example, the \l Item class contains a list property named - children that can be used like this: - - \qml - Item { - children: [ - Item { id: child1 }, - Rectangle { id: child2; width: 200 }, - Text { id: child3 } - ] - - Component.onCompleted: { - console.log("Width of child rectangle:", children[1].width) - } - } - \endqml - \c child1, \c child2 and \c child3 will be added to the children list - in the order in which they appear. - - List \l {Property Binding}{properties} can be created as a - \c variant type, or as a \c list<Type> type, where \c Type is the - type of the object in the list: - - \qml - Item { - property list<Rectangle> rects: [ - Rectangle { width: 100; height: 100}, - Rectangle { width: 200; height: 200} - ] - } - \endqml - - A list property can only contain values that match (or are derived from) the - specified \c Type. - - While the \c rects property can be reassigned to a different list value (including - an empty list), its individual values cannot be modified. See the \l variant type - documentation for details. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype variant - \ingroup qmlbasictypes - - \brief A variant type is a generic property type. - - A variant is a generic property type. A variant type property can hold - any of the \l {QML Basic Types}{basic type} values: - - \qml - Item { - property variant aNumber: 100 - property variant aString: "Hello world!" - property variant aBool: false - } - \endqml - - A \c variant type property can also hold an image or pixmap. - A \c variant which contains a QPixmap or QImage is known as a - "scarce resource" and the declarative engine will attempt to - automatically release such resources after evaluation of any JavaScript - expression which requires one to be copied has completed. - - Clients may explicitly release such a scarce resource by calling the - "destroy" method on the \c variant property from within JavaScript. They - may also explicitly preserve the scarce resource by calling the - "preserve" method on the \c variant property from within JavaScript. - For more information regarding the usage of a scarce resource, please - see \l{Scarce Resources in JavaScript}. - - Finally, the \c variant type can also hold: - - \list - \o An array of \l {QML Basic Types}{basic type} values - \o A map of key-value pairs with \l {QML Basic Types}{basic-type} values - \endlist - - For example, below is an \c items array and an \c attributes map. Their - contents can be examined using JavaScript \c for loops. Individual array - values are accessible by index, and individual map values are accessible - by key: - - \qml - Item { - property variant items: [1, 2, 3, "four", "five"] - property variant attributes: { 'color': 'red', 'width': 100 } - - Component.onCompleted: { - for (var i=0; i<items.length; i++) - console.log(items[i]) - - for (var prop in attributes) - console.log(prop, "=", attributes[prop]) - } - } - \endqml - - While this is a convenient way to store array and map-type values, you - must be aware that the \c items and \c attributes properties above are \e not - QML objects (and certainly not JavaScript object either) and the key-value - pairs in \c attributes are \e not QML properties. Rather, the \c items - property holds an array of values, and \c attributes holds a set of key-value - pairs. Since they are stored as a set of values, instead of as an object, - their contents \e cannot be modified individually: - - \qml - Item { - property variant items: [1, 2, 3, "four", "five"] - property variant attributes: { 'color': 'red', 'width': 100 } - - Component.onCompleted: { - items[0] = 10 - console.log(items[0]) // This will still be '1'! - attributes.color = 'blue' - console.log(attributes.color) // This will still be 'red'! - } - } - \endqml - - Additionally, since \c items and \c attributes are not QML objects, changing - their individual values do not trigger property change notifications. If - the above example had \c onNumberChanged or \c onAnimalChanged signal - handlers, they would not have been called. If, however, the \c items or - \c attributes properties themselves were reassigned to different values, then - such handlers would be called. - - One way to "update" the contents of an array or map is to copy the property - to a JavaScript object, modify the copy as desired, and then reassign the - property to the updated copy. Note, however, that this is not efficient. - In the example below, which reassigns the \c attributes property, the \e entire - set of key-value pairs must be serialized and deserialized every time it is - copied between a JavaScript object and a QML property: - - \qml - Item { - property variant attributes: { 'color': 'red', 'width': 100 } - - Component.onCompleted: { - // Change the value of attributes.color to 'blue': - var temp = attributes // copy all values to 'temp' - temp.color = 'blue' - attributes = temp // copy all values back to 'attributes' - } - } - \endqml - - Since this operation is inefficient, if a list or map should be modifiable, - it is better to use alternative approaches. For example, you could implement - a custom C++ list element, or write to a JavaScript object defined from - within a JavaScript file. - - JavaScript programmers should also note that when a JavaScript object is - copied to an array or map property, the \e contents of the object (that is, - its key-value properties) are copied, rather than the object itself. The - property does not hold a reference to the original JavaScript object, and - extra data such as the object's JavaScript prototype chain is also lost in - the process. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype vector3d - \ingroup qmlbasictypes - - \brief A vector3d type has x, y, and z attributes. - - A \c vector3d type has \c x, \c y, and \c z attributes. - - To create a \c vector3d value, specify it as a "x,y,z" string: - - \qml - Rotation { angle: 60; axis: "0,1,0" } - \endqm |