diff options
Diffstat (limited to 'doc/src')
42 files changed, 461 insertions, 155 deletions
diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc index 598f47b..4807fd2 100644 --- a/doc/src/declarative/advtutorial.qdoc +++ b/doc/src/declarative/advtutorial.qdoc @@ -160,25 +160,25 @@ 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: +file, \c samegame.js. The code is explained below. \snippet declarative/tutorials/samegame/samegame2/samegame.js 0 -The main function here is \c initBoard(). It creates an array to store all the game -blocks, then calls \c createBlock() to create enough blocks to fill the game canvas. +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 using the \c Block.qml file +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)} is called to generate an element from \c Block.qml. +\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. - (If a component is loaded remotely - over HTTP for example - then we would have to wait for the - component to finish loading before calling \c createObject()). \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 in the blocks array for future reference. + 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 @@ -193,13 +193,13 @@ 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.initBoard() or \c SameGame.createBlock(). -This means we can now connect the New Game button's \c onClicked handler to the \c initBoard() +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 initBoard() is called and generates a field of blocks, like this: +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 @@ -240,17 +240,17 @@ As this is a tutorial about QML, not game design, we will only discuss \c handle \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, and accepts mouse input from the user. Here is the item code: +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 for input. +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 tileSize, \c tileSize needs to be moved out of \c samegame.js and into \c samegame.qml as a QML property. +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. -The \l MouseArea simply 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: +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 @@ -258,7 +258,7 @@ Note that if \c score was a global variable in the \c{samegame.js} file you woul \section3 Updating the score -When the player clicks a block and triggers \c handleClick(), \c handleClick() also calls victoryCheck() to update the score and to check whether the player has completed the game. Here is the \c victoryCheck() code: +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 @@ -287,7 +287,7 @@ Here is a screenshot of what has been accomplished so far: \image declarative-adv-tutorial3.png -Here is the QML code as it is now in \c samegame.qml: +This is what \c samegame.qml looks like now: \snippet declarative/tutorials/samegame/samegame3/samegame.qml 0 @@ -439,7 +439,7 @@ By following this tutorial you've seen how you can write a fully functional appl \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 through online and offline methods +\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 diff --git a/doc/src/declarative/codingconventions.qdoc b/doc/src/declarative/codingconventions.qdoc new file mode 100644 index 0000000..e1e7871 --- /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 + +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 index f310484..a4f4bc7 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -47,10 +47,10 @@ 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 +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. @@ -106,5 +106,6 @@ completely new applications. QML is fully \l {Extending QML in C++}{extensible \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 index b2e3f90..4cb5198 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -62,15 +62,11 @@ 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 createComponent function on the \l{QML Global Object}. +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. -You can also create a component by placing your QML inside a Component element. -Referencing that component element by id will be the same as referencing the variable -which you save the result of createComponent into. - -Once you have a component you can use its createObject method to create an instance of +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 @@ -116,13 +112,13 @@ the component. Example QML script is below. Remember that QML files that might b 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 createComponent is executed. +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 createQmlObject function, as in the following example: +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.6; Rectangle { color: "red"; width: 20; height: 20 }', + 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 @@ -139,9 +135,9 @@ 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 createComponent +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 createQmlObject, was specified. If the creation +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. diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index 1bb739d..ce3a6e3 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -88,11 +88,17 @@ The following table lists the QML elements provided by the Qt Declarative module \o \list \o \l Binding -\o \l ListModel, \l ListElement +\o \l ListModel +\list +\o \l ListElement +\endlist \o \l VisualItemModel \o \l VisualDataModel \o \l Package -\o \l XmlListModel and XmlRole +\o \l XmlListModel +\list +\o \l XmlRole +\endlist \endlist \o @@ -140,7 +146,6 @@ The following table lists the QML elements provided by the Qt Declarative module \o \l Loader \o \l Repeater \o \l SystemPalette -\o \l GraphicsObjectContainer \o \l LayoutItem \endlist diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index b6aa9da..e1c6469 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -655,7 +655,7 @@ declaring a new property, and the corresponding C++ type. \row \o url \o QUrl \row \o color \o QColor \row \o date \o QDateTime -\row \o var \o QVariant +\row \o variant \o QVariant \endtable QML supports two methods for adding a new property to a type: a new property @@ -852,7 +852,7 @@ Here are three examples of signal declarations: Item { signal clicked signal hovered() - signal performAction(string action, var actionArgument) + signal performAction(string action, variant actionArgument) } \endcode diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc index 231e75a..97f5d91 100644 --- a/doc/src/declarative/globalobject.qdoc +++ b/doc/src/declarative/globalobject.qdoc @@ -203,6 +203,9 @@ This function causes the QML engine to emit the quit signal, which in 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 @@ -266,7 +269,7 @@ of their use. Example (where targetItem is the id of an existing QML item): \code - newObject = createQmlObject('import Qt 4.6; Rectangle {color: "red"; width: 20; height: 20}', + newObject = createQmlObject('import Qt 4.7; Rectangle {color: "red"; width: 20; height: 20}', targetItem, "dynamicSnippet1"); \endcode diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index c198295..8ffe58c 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -41,25 +41,25 @@ /*! \page qdeclarativejavascript.html -\title Integrating JavaScript +\title Integrating JavaScript -QML encourages building UIs declaratively, using \l {Property Binding} and the +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 +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} +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. +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. @@ -73,30 +73,31 @@ Item { return a * factorial(a - 1); } - MouseRegion { + MouseArea { anchors.fill: parent onClicked: print(factorial(10)) } } \endcode -As methods, inline functions on the root element in a QML component can be +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. Like element -types, external JavaScript files are \c {import}'ed into QML 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. -The \c {factorial()} method used in the \l {Inline JavaScript} section could -be refactored into an external file, and accessed like this. +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 { - MouseRegion { + MouseArea { anchors.fill: parent onClicked: print(MathFunctions.factorial(10)) } @@ -107,24 +108,24 @@ 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 will remain in the -\l {QDeclarativeComponent::status()}{waiting state} until the script has been +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 +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 +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 +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 @@ -133,8 +134,8 @@ 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 +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 @@ -161,15 +162,13 @@ parameters. 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 +as the QML environment may not have been fully established. For example, some objects might not have been created or some \l {Property Binding}s may not have been run. -\l {QML Script Restrictions} covers the exact limitations of global script code. +\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. - -The following QML code shows how to use the \c Component::onCompleted property. +QML environment has been completely established. For example: \code Rectangle { @@ -182,24 +181,24 @@ Rectangle { \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 onCompleted +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 +\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 +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, +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 +Assuming that the \c a variable does not exist in the scope chain, the following code is illegal in QML. \code @@ -217,18 +216,18 @@ 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, +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 +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 +Global code that only accesses script local variable is permitted. This is an example of valid global code. \code @@ -242,8 +241,8 @@ Global code that accesses QML objects will not run correctly. 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 +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/modules.qdoc b/doc/src/declarative/modules.qdoc index d476d6f..0c69930 100644 --- a/doc/src/declarative/modules.qdoc +++ b/doc/src/declarative/modules.qdoc @@ -86,7 +86,7 @@ The second exception is explained in more detail in the section below on Namespa \section2 The Import Path Installed modules are searched for on the import path. -The \c -L option to the \l {Qt Declarative UI Runtime}{qml} runtime adds paths to 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(). @@ -114,19 +114,7 @@ Installed files do not need to import the module of which they are a part, as th 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: - -\code -internal <TypeName> <File> -\endcode - -\c plugin <Name> [<Path>] lines are used to add \l{QDeclarativeExtensionPlugin}{QML C++ plugins} -to the module. <Name> is the -name of the library. <Path> is an optional argument specifying the full path to the directory -containing the plugin file; if it is omitted then the directory is assumed to be the same as -the directory of the \c qmldir file. Note that <Name> is not usually 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. +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), @@ -141,6 +129,23 @@ of installed software, since a versioned import \e only imports types for that v 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. @@ -150,10 +155,10 @@ types to be referenced, or purely for readability. To import a module into a namespace: \code -import Qt 4.6 as TheQtLibrary +import Qt 4.7 as TheQtLibrary \endcode -Types from Qt 4.6 may then be used, but only by qualifying them with the namespace: +Types from the Qt 4.7 module may then be used, but only by qualifying them with the namespace: \code TheQtLibrary.Rectangle { ... } @@ -163,7 +168,7 @@ Multiple modules can be imported into the same namespace in the same way that mu modules can be imported into the global namespace: \code -import Qt 4.6 as Nokia +import Qt 4.7 as Nokia import Ovi 1.0 as Nokia \endcode diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc index f1d4db1..0a26c68 100644 --- a/doc/src/declarative/network.qdoc +++ b/doc/src/declarative/network.qdoc @@ -64,7 +64,6 @@ Image { Network transparency is supported throughout QML, for example: \list -\o Scripts - the \c source property of \l Script is a URL \o Fonts - the \c source property of FontLoader is a URL \o WebViews - the \c url property of WebView (obviously!) \endlist diff --git a/doc/src/declarative/pics/rect-smooth.png b/doc/src/declarative/pics/rect-smooth.png Binary files differindex abbb0a9..7ffd8ab 100644 --- a/doc/src/declarative/pics/rect-smooth.png +++ b/doc/src/declarative/pics/rect-smooth.png diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc index a210c98..cf3aae2 100644 --- a/doc/src/declarative/qdeclarativedocument.qdoc +++ b/doc/src/declarative/qdeclarativedocument.qdoc @@ -49,7 +49,7 @@ stored on a disk or network resource, but can also be constructed directly from Here is a simple QML document: \code -import Qt 4.6 +import Qt 4.7 Rectangle { width: 240; height: 320; @@ -83,7 +83,7 @@ modifies the document prior to presentation to the QML runtime. \c import statem 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 {JavaScript Block} or \l {Property Binding}s, are \e resolved based exclusively on the +\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! @@ -103,7 +103,7 @@ instantiated four times, each with a different value for its \c text property. <table><tr><td> \endraw \code -import Qt 4.6 +import Qt 4.7 BorderImage { property alias text: textElement.text @@ -152,7 +152,7 @@ These final two examples are behaviorally identical to the original document. \row \o \code -import Qt 4.6 +import Qt 4.7 Rectangle { width: 240; height: 320; @@ -170,7 +170,7 @@ Rectangle { \endcode \o \code -import Qt 4.6 +import Qt 4.7 Rectangle { width: 240; height: 320; diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc index 598c567..0a48dd9 100644 --- a/doc/src/declarative/qdeclarativei18n.qdoc +++ b/doc/src/declarative/qdeclarativei18n.qdoc @@ -72,7 +72,7 @@ that needs to be translated is enclosed in a call to \c qsTr(). hello.qml: \qml -import Qt 4.6 +import Qt 4.7 Rectangle { width: 200; height: 200 diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc index e80824d..d8b2a5d 100644 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -54,7 +54,7 @@ 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 he \e color role of the model and +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. @@ -309,13 +309,21 @@ There are no data roles. The following example creates a ListView with five elements: \code -Component { - id: itemDelegate - Text { text: "I am item number: " + index } -} -ListView { - model: 5 - delegate: itemDelegate +Item { + width: 200 + height: 250 + + Component { + id: itemDelegate + Text { text: "I am item number: " + index } + } + + ListView { + anchors.fill: parent + model: 5 + delegate: itemDelegate + } + } \endcode diff --git a/doc/src/declarative/qdeclarativesecurity.qdoc b/doc/src/declarative/qdeclarativesecurity.qdoc index 56216dd..ab75a57 100644 --- a/doc/src/declarative/qdeclarativesecurity.qdoc +++ b/doc/src/declarative/qdeclarativesecurity.qdoc @@ -72,7 +72,7 @@ A non-exhaustive list of the ways you could shoot yourself in the foot is: \list \i Using \c import to import QML or JavaScropt you do not control. BAD \i Using \l Loader to import QML you do not control. BAD - \i Using XMLHttpRequest to load data you do not control and executing it. 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. @@ -81,7 +81,7 @@ 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 XMLHttpRequest to interact with online services. 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}, diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc index 577e69a..181c504 100644 --- a/doc/src/declarative/qtbinding.qdoc +++ b/doc/src/declarative/qtbinding.qdoc @@ -108,7 +108,7 @@ QObject *window = component.create(windowContext); \o \code // main.qml -import Qt 4.6 +import Qt 4.7 Rectangle { color: backgroundColor @@ -198,7 +198,7 @@ the window text will update accordingly. \code // main.qml -import Qt 4.6 +import Qt 4.7 Rectangle { width: 240 @@ -287,7 +287,7 @@ int main(int argc, char **argv) \o \code // main.qml -import Qt 4.6 +import Qt 4.7 Rectangle { MouseArea { @@ -311,7 +311,7 @@ is to have a "running" property. This leads to much nicer QML code: \o \code // main.qml -import Qt 4.6 +import Qt 4.7 Rectangle { MouseArea { @@ -390,7 +390,7 @@ MyApplication::MyApplication() \endcode \code // main.qml -import Qt 4.6 +import Qt 4.7 Image { source: "images/background.png" diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc index 964f7d5..65553cf 100644 --- a/doc/src/declarative/scope.qdoc +++ b/doc/src/declarative/scope.qdoc @@ -126,7 +126,7 @@ following example shows a simple QML file that accesses some enumeration values and calls an imported JavaScript function. \code -import Qt 4.6 +import Qt 4.7 import "code.js" as Code ListView { @@ -267,7 +267,7 @@ is used, the \c title property may resolve differently. \code // TitlePage.qml -import Qt 4.6 +import Qt 4.7 Item { property string title @@ -283,7 +283,7 @@ Item { } // TitleText.qml -import Qt 4.6 +import Qt 4.7 Text { property int size text: "<b>" + title + "</b>" @@ -299,7 +299,7 @@ to use property interfaces, like this: \code // TitlePage.qml -import Qt 4.6 +import Qt 4.7 Item { id: root property string title @@ -318,7 +318,7 @@ Item { } // TitleText.qml -import Qt 4.6 +import Qt 4.7 Text { property string title property int size 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/snippets/declarative/border-image.qml b/doc/src/snippets/declarative/border-image.qml index c4215cd..9c4247e 100644 --- a/doc/src/snippets/declarative/border-image.qml +++ b/doc/src/snippets/declarative/border-image.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 Rectangle { id: page @@ -9,23 +9,21 @@ Rectangle { anchors.centerIn: parent spacing: 50 //! [0] - BorderImage { - width: 180; height: 180 - border.left: 30; border.top: 30 - border.right: 30; border.bottom: 30 - horizontalTileMode: BorderImage.Stretch - verticalTileMode: BorderImage.Stretch - source: "content/colors.png" - } +BorderImage { + width: 180; height: 180 + border { left: 30; top: 30; right: 30; bottom: 30 } + horizontalTileMode: BorderImage.Stretch + verticalTileMode: BorderImage.Stretch + source: "content/colors.png" +} - BorderImage { - width: 180; height: 180 - border.left: 30; border.top: 30 - border.right: 30; border.bottom: 30 - horizontalTileMode: BorderImage.Round - verticalTileMode: BorderImage.Round - source: "content/colors.png" - } +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 index 806be29..ab1bbc9 100644 --- a/doc/src/snippets/declarative/comments.qml +++ b/doc/src/snippets/declarative/comments.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 Text { text: "Hello world!" //a basic greeting diff --git a/doc/src/snippets/declarative/drag.qml b/doc/src/snippets/declarative/drag.qml index 8e5b599..9465efb 100644 --- a/doc/src/snippets/declarative/drag.qml +++ b/doc/src/snippets/declarative/drag.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 //! [0] Rectangle { diff --git a/doc/src/snippets/declarative/flipable.qml b/doc/src/snippets/declarative/flipable.qml index c837ebc..ae74345 100644 --- a/doc/src/snippets/declarative/flipable.qml +++ b/doc/src/snippets/declarative/flipable.qml @@ -1,5 +1,5 @@ //! [0] -import Qt 4.6 +import Qt 4.7 Flipable { id: flipable diff --git a/doc/src/snippets/declarative/gradient.qml b/doc/src/snippets/declarative/gradient.qml index 281360e..168398d 100644 --- a/doc/src/snippets/declarative/gradient.qml +++ b/doc/src/snippets/declarative/gradient.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 Rectangle { width: 100; height: 100 diff --git a/doc/src/snippets/declarative/gridview/dummydata/ContactModel.qml b/doc/src/snippets/declarative/gridview/dummydata/ContactModel.qml index 3cf9ba7..90f139d 100644 --- a/doc/src/snippets/declarative/gridview/dummydata/ContactModel.qml +++ b/doc/src/snippets/declarative/gridview/dummydata/ContactModel.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 ListModel { id: contactModel diff --git a/doc/src/snippets/declarative/gridview/gridview.qml b/doc/src/snippets/declarative/gridview/gridview.qml index 1a2021c..1d3df97 100644 --- a/doc/src/snippets/declarative/gridview/gridview.qml +++ b/doc/src/snippets/declarative/gridview/gridview.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 //! [3] Rectangle { diff --git a/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml b/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml index 6832308..20687cf 100644 --- a/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml +++ b/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 ListModel { id: contactModel diff --git a/doc/src/snippets/declarative/listview/highlight.qml b/doc/src/snippets/declarative/listview/highlight.qml index 6a9d215..794b3f2 100644 --- a/doc/src/snippets/declarative/listview/highlight.qml +++ b/doc/src/snippets/declarative/listview/highlight.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 Rectangle { width: 180; height: 200; color: "white" @@ -45,7 +45,7 @@ Rectangle { width: 180; height: 40 color: "lightsteelblue"; radius: 5 SpringFollow on y { - source: list.currentItem.y + to: list.currentItem.y spring: 3 damping: 0.2 } diff --git a/doc/src/snippets/declarative/listview/listview.qml b/doc/src/snippets/declarative/listview/listview.qml index be0f3ad..61bf126 100644 --- a/doc/src/snippets/declarative/listview/listview.qml +++ b/doc/src/snippets/declarative/listview/listview.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 //! [3] Rectangle { diff --git a/doc/src/snippets/declarative/mouseregion.qml b/doc/src/snippets/declarative/mouseregion.qml index fc6c8f0..a464069 100644 --- a/doc/src/snippets/declarative/mouseregion.qml +++ b/doc/src/snippets/declarative/mouseregion.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 Rectangle { width: 200; height: 100 Row { diff --git a/doc/src/snippets/declarative/pathview/dummydata/MenuModel.qml b/doc/src/snippets/declarative/pathview/dummydata/MenuModel.qml index 1334cf4..4004076 100644 --- a/doc/src/snippets/declarative/pathview/dummydata/MenuModel.qml +++ b/doc/src/snippets/declarative/pathview/dummydata/MenuModel.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 ListModel { id: menuModel diff --git a/doc/src/snippets/declarative/pathview/pathattributes.qml b/doc/src/snippets/declarative/pathview/pathattributes.qml index 99d0de2..ba860c2 100644 --- a/doc/src/snippets/declarative/pathview/pathattributes.qml +++ b/doc/src/snippets/declarative/pathview/pathattributes.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 Rectangle { width: 240; height: 200; color: 'white' diff --git a/doc/src/snippets/declarative/pathview/pathview.qml b/doc/src/snippets/declarative/pathview/pathview.qml index e316578..3686398 100644 --- a/doc/src/snippets/declarative/pathview/pathview.qml +++ b/doc/src/snippets/declarative/pathview/pathview.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 Rectangle { width: 240; height: 200; color: 'white' diff --git a/doc/src/snippets/declarative/repeater-index.qml b/doc/src/snippets/declarative/repeater-index.qml index 9063967..709eaf2 100644 --- a/doc/src/snippets/declarative/repeater-index.qml +++ b/doc/src/snippets/declarative/repeater-index.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 Rectangle { width: 50; height: childrenRect.height; color: "white" diff --git a/doc/src/snippets/declarative/repeater.qml b/doc/src/snippets/declarative/repeater.qml index f8ac856..02a8208 100644 --- a/doc/src/snippets/declarative/repeater.qml +++ b/doc/src/snippets/declarative/repeater.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 Rectangle { width: 220; height: 20; color: "white" diff --git a/doc/src/snippets/declarative/rotation.qml b/doc/src/snippets/declarative/rotation.qml index 4a67dcb..f2fd78c 100644 --- a/doc/src/snippets/declarative/rotation.qml +++ b/doc/src/snippets/declarative/rotation.qml @@ -1,4 +1,4 @@ -import Qt 4.6 +import Qt 4.7 Rectangle { width: 360; height: 80 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] |
