diff options
Diffstat (limited to 'doc/src/declarative')
40 files changed, 292 insertions, 218 deletions
diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc index 04d7f07..6cd1f22 100644 --- a/doc/src/declarative/advtutorial.qdoc +++ b/doc/src/declarative/advtutorial.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc index e9f79d1..e567ae1 100644 --- a/doc/src/declarative/anchor-layout.qdoc +++ b/doc/src/declarative/anchor-layout.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index 208a1c4..59bf8f6 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 034b7d1..463e4a3 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** @@ -95,6 +95,26 @@ */ /*! + \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 @@ -412,7 +432,8 @@ list only modify a \e copy of the list and not the actual list. (These current limitations are due to restrictions on \l {Property Binding} where lists are involved.) - To create a modifiable list, create an array object from within a \c .js JavaScript file, + You can, however, modify a copy of the list and then reassign the property to the modified + value. Other options are to create an array object from within a \c .js JavaScript file, or implement a custom list element in C++. Here is a QML element that modifies the list in a JavaScript file: @@ -452,6 +473,78 @@ \sa {QML Basic Types} */ + +/*! + \qmlbasictype variant + \ingroup qmlbasictypes + + \brief A variant type is a generic property type. + + A variant is a generic property type. A variant type property can hold any of the + \l {QML Basic Types}{basic type} values: + + \qml + Item { + property variant aNumber : 100 + property variant aString : "Hello world!" + property variant aList : [ 1, 2, "buckle my shoe" ] + } + \endqml + + The \c variant type can also hold a \e copy of a JavaScript object. For example, the + \c animal property below defines a JavaScript object defined with JSON notation. The + object's properties and values can be examined using the standard JavaScript syntax, + as shown in the \c Component.onCompleted handler. + + \qml + Item { + property variant animal : { 'type': 'bird', 'species': 'galah', 'age': 7 } + + Component.onCompleted: { + for (var attribute in animal) + console.log(attribute, "=", animal[attribute]) + } + } + \endqml + + It must be noted that the \c animal property holds a \e copy of the defined object, and + not the object itself. (This is true even if the property refers to an object defined in + some JavaScript file; the property will hold a copy of the object, and not the actual + object.) The property essentially holds a copy of the contents within the object. This + has several implications: + + \list + \o Changes to any of the property's values (for example, the \c animal.type value + above) only modify the \e copy of the object, not the object itself. You can, however, + modify a copy of the object and then reassign the property to the modified value. + \o Because the property only holds a copy of the object, \l{Property Binding}{bindings} to + any of the property's individual values are not updated until the whole property is + reassigned to a new value. For example: + + \qml + Item { + property variant animal : { 'type': 'bird', 'species': 'galah', 'age': 7 } + + Text { text: "Animal species: " + animal.species } + + Component.onCompleted: { + animal.species = 'kookaburra' // this has no effect on the displayed text + + var newObj = animal + newObj.species = 'kookaburra' + animal = newObj // this will update the displayed text + } + } + \endqml + \o Since the object values are copied, it does not hold any reference to the original + object, and extra data such as the object's JavaScript prototype chain is lost in the + process. + \endlist + + \sa {QML Basic Types} +*/ + + /*! \qmlbasictype vector3d \ingroup qmlbasictypes diff --git a/doc/src/declarative/codingconventions.qdoc b/doc/src/declarative/codingconventions.qdoc index 3f92d46..52f8089 100644 --- a/doc/src/declarative/codingconventions.qdoc +++ b/doc/src/declarative/codingconventions.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index e10c5c8..aa9ed18 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index fcc9fd4..073e0c4 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index eaa6a82..40d67e7 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc index a62f670..2b82b2f 100644 --- a/doc/src/declarative/example-slideswitch.qdoc +++ b/doc/src/declarative/example-slideswitch.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc index 224d346..e03557b 100644 --- a/doc/src/declarative/examples.qdoc +++ b/doc/src/declarative/examples.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/declarative/extending-tutorial.qdoc index c998c5c..4caa631 100644 --- a/doc/src/declarative/extending-tutorial.qdoc +++ b/doc/src/declarative/extending-tutorial.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index c34dc13..a1f006b 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** @@ -753,15 +753,15 @@ with their default values and the corresponding C++ type: \table \header \o QML Type Name \o Default value \o C++ Type Name -\row \o int \o 0 \o int -\row \o bool \o \c false \o bool -\row \o double \o 0.0 \o double -\row \o real \o 0.0 \o double -\row \o string \o "" (empty string) \o QString -\row \o url \o "" (empty url) \o QUrl -\row \o color \o #000000 (black) \o QColor -\row \o date \o \c undefined \o QDateTime -\row \o variant \o \c undefined \o QVariant +\row \o \l int \o 0 \o int +\row \o \l bool \o \c false \o bool +\row \o \l double \o 0.0 \o double +\row \o \l real \o 0.0 \o double +\row \o \l string \o "" (empty string) \o QString +\row \o \l url \o "" (empty url) \o QUrl +\row \o \l color \o #000000 (black) \o QColor +\row \o \l date \o \c undefined \o QDateTime +\row \o \l variant \o \c undefined \o QVariant \endtable QML object types can also be used as property types. This includes @@ -776,6 +776,10 @@ property MyCustomType customProperty Such object-type properties default to an \c undefined value. +It is also possible to store a copy of a JavaScript object using the \c variant +property type. This creates some restrictions on how the property should be used; +see the \l {variant}{variant type documentation} for details. + \l{list}{List properties} are created with the \c list<Type> syntax, and default to an empty list: @@ -786,8 +790,6 @@ property list<Item> listOfItems Note that list properties cannot be modified like ordinary JavaScript arrays. See the \l {list}{list type documentation} for details. -For details about accessing and manipulating QML properties from C++, see \l {Using QML with C++}. - \section2 Property change signals diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc index ae72c3c..599d63c 100644 --- a/doc/src/declarative/focus.qdoc +++ b/doc/src/declarative/focus.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc index ffc84f9..8671b48 100644 --- a/doc/src/declarative/globalobject.qdoc +++ b/doc/src/declarative/globalobject.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/integrating.qdoc b/doc/src/declarative/integrating.qdoc index 7028585..f0d3a37 100644 --- a/doc/src/declarative/integrating.qdoc +++ b/doc/src/declarative/integrating.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index 68cb392..d221205 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc index 8d23170..1dca28c 100644 --- a/doc/src/declarative/modules.qdoc +++ b/doc/src/declarative/modules.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc index a19ca6b..675a0aa 100644 --- a/doc/src/declarative/network.qdoc +++ b/doc/src/declarative/network.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/pics/flipable.gif b/doc/src/declarative/pics/flipable.gif Binary files differindex da37b2b..6af46c3 100644 --- a/doc/src/declarative/pics/flipable.gif +++ b/doc/src/declarative/pics/flipable.gif diff --git a/doc/src/declarative/positioners.qdoc b/doc/src/declarative/positioners.qdoc index d97acbd..5493d4a 100644 --- a/doc/src/declarative/positioners.qdoc +++ b/doc/src/declarative/positioners.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc index 3bf85de..2fa95d4 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qdeclarativedebugging.qdoc b/doc/src/declarative/qdeclarativedebugging.qdoc index 9e0a969..6902c30 100644 --- a/doc/src/declarative/qdeclarativedebugging.qdoc +++ b/doc/src/declarative/qdeclarativedebugging.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc index 8af24a6..b94e32e 100644 --- a/doc/src/declarative/qdeclarativedocument.qdoc +++ b/doc/src/declarative/qdeclarativedocument.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc index 0d5fbcc..9ca8938 100644 --- a/doc/src/declarative/qdeclarativei18n.qdoc +++ b/doc/src/declarative/qdeclarativei18n.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qdeclarativeintro.qdoc b/doc/src/declarative/qdeclarativeintro.qdoc index 299ec73..4b7dce5 100644 --- a/doc/src/declarative/qdeclarativeintro.qdoc +++ b/doc/src/declarative/qdeclarativeintro.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** @@ -37,7 +37,7 @@ interface is specified as a tree of objects with properties. This introduction is meant for those with little or no programming experience. JavaScript is used as a scripting language in QML, so you may want -to learn a bit more about it (\l{Javascript Guide}) before diving +to learn a bit more about it (see the \l{Javascript Guide}) before diving deeper into QML. It's also helpful to have a basic understanding of other web technologies like HTML and CSS, but it's not required. @@ -60,13 +60,13 @@ Rectangle { } \endqml -Objects are specified by their type, followed by a pair of braces. Object -types always begin with a capital letter. In the above example, there are -two objects, a \l Rectangle, and an \l Image. Between the braces, we can specify -information about the object, such as its properties. +Here we create two objects, a \l Rectangle object and its child +\l Image object. Objects are specified by their type, followed by a pair of +braces in between which additional data can be defined for the object, such as +its property values and any child objects. -Properties are specified as \c {property: value}. In the above example, we -can see the Image has a property named \c source, which has been assigned the +Properties are specified with a \c {property: value} syntax. In the above example, we +can see the \l Image object has a property named \c source, which has been assigned the value \c "pics/logo.png". The property and its value are separated by a colon. Properties can be specified one-per-line: @@ -87,45 +87,12 @@ Rectangle { width: 100; height: 100 } When multiple property/value pairs are specified on a single line, they must be separated by a semicolon. -The \c import statement imports the \c Qt \l{QML Modules}{module}, which contains all of the +The \c import statement imports the \c QtQuick \l{QML Modules}{module}, which contains all of the standard \l {QML Elements}. Without this import statement, the \l Rectangle and \l Image elements would not be available. -\section1 Expressions - -In addition to assigning values to properties, you can also assign -expressions written in JavaScript. - -\qml -Rotation { - angle: 360 * 3 -} -\endqml - -These expressions can include references to other objects and properties, in which case -a \e binding is established: when the value of the expression changes, the property the -expression has been assigned to is automatically updated to that value. - -\qml -Item { - Text { - id: text1 - text: "Hello World" - } - Text { - id: text2 - text: text1.text - } -} -\endqml - -In the example above, the \c text2 object will display the same text as \c text1. If \c text1 is changed, -\c text2 is automatically changed to the same value. -Note that to refer to other objects, we use their \e id values. (See below for more -information on the \e id property.) - -\section1 QML Comments +\section1 Comments Commenting in QML is similar to JavaScript. \list @@ -149,27 +116,95 @@ Text { } \endqml -In the above example, the Text object will have normal opacity, since the +In the above example, the \l Text object will have normal opacity, since the line opacity: 0.5 has been turned into a comment. -\section1 Properties -\target intro-properties -\section2 Property naming -Properties begin with a lowercase letter (with the exception of \l{Attached Properties}). +\section1 Object identifiers + +Each object can be given a special \e id value that allows the object to be identified +and referred to by other objects. + +For example, below we have two \l Text objects. The first \l Text object +has an \c id value of "text1". The second \l Text object can now set its own +\c text property value to be the same as that of the first object, by referring to +\c text1.text: + +\qml +import QtQuick 1.0 + +Row { + Text { + id: text1 + text: "Hello World" + } + + Text { text: text1.text } +} +\endqml + +An object can be referred to by its \c id from anywhere within the \l {QML Documents}{component} +in which it is declared. Therefore, an \c id value must always be unique within a single component. + +The \c id value is a special value for a QML object and should not be thought of as an +ordinary object property; for example, it is not possible to access \c text1.id in the +above example. Once an object is created, its \c id cannot be changed. + +Note that an \c id must begin with a lower-case letter or an underscore, and cannot contain +characters other than letters, numbers and underscores. + + + +\section1 Expressions + +JavaScript expressions can be used to assign property values. For example: + +\code +Item { + width: 100 * 3 + height: 50 + 22 +} +\endcode + +These expressions can include references to other objects and properties, in which case +a \l{Property Binding}{binding} is established: when the value of the expression changes, +the property to which the expression is assigned is automatically updated to the +new value. For example: + +\code +Item { + width: 300 + height: 300 + + Rectangle { + width: parent.width - 50 + height: 100 + color: "yellow" + } +} +\endcode + +Here, the \l Rectangle object's \c width property is set relative to the width +of its parent. Whenever the parent's width changes, the width of the \l Rectangle is +automatically updated. -\section2 Property types -QML supports properties of many types (see \l{QML Basic Types}). The basic types include int, -real, bool, string, color, and lists. + +\section1 Properties +\target intro-properties + +\section2 Basic property types + +QML supports properties of many types (see \l{QML Basic Types}). The basic types include \c int, +\c real, \c bool, \c string and \c color. \qml Item { x: 10.5 // a 'real' property - // ... state: "details" // a 'string' property focus: true // a 'bool' property + // ... } \endqml @@ -183,31 +218,30 @@ Item { } \endcode -\section3 The \c id property +Note that with the exception of \l {Attached Properties}, properties always begin with a lowercase +letter. + + +\section2 Property change notifications -Each object can be given a special unique property called an \e id. No other object within the -same QML component (see \l{QML Documents}) can have the same \c id value. Assigning an id enables the object -to be referred to by other objects and scripts. +When a property changes value, it can send a signal to notify others of this change. -The first Rectangle element below has an \e id, "myRect". The second Rectangle element defines its -own width by referring to \tt myRect.width, which means it will have the same \tt width -value as the first Rectangle element. +To receive these signals, simply create a \e {signal handler} named with an \c on<Property>Changed +syntax. For example, the \l Rectangle element has \l {Item::}{width} and \l {Rectangle::}{color} +properties. Below, we have a \l Rectangle object that has defined two signal handlers, +\c onWidthChanged and \c onColorChanged, which will automaticallly be called whenever these +properties are modified: \qml -Item { - Rectangle { - id: myRect - width: 100 - height: 100 - } - Rectangle { - width: myRect.width - height: 200 - } +Rectangle { + width: 100; height: 100 + + onWidthChanged: console.log("Width has changed to:", width) + onColorChanged: console.log("Color has changed to:", color) } \endqml -Note that an \e id must begin with a lower-case letter or an underscore, and cannot contain characters other than letters, numbers and underscores. +Signal handlers are explained further \l {Signal Handlers}{below}. \section2 List properties @@ -293,11 +327,21 @@ Some objects attach properties to another object. Attached Properties are of the form \e {Type.property} where \e Type is the type of the element that attaches \e property. -For example: -\snippet doc/src/snippets/declarative/introduction-qml/attachedproperties1.qml component and list view +For example, the \l ListView element attaches the \e ListView.isCurrentItem property +to each delegate it creates: -The \l ListView element attaches the \e ListView.isCurrentItem property -to each delegate it creates. +\code +Component { + id: myDelegate + Text { + text: "Hello" + color: ListView.isCurrentItem ? "red" : "blue" + } +} +ListView { + delegate: myDelegate +} +\endcode Another example of attached properties is the \l Keys element which attaches properties for handling key presses to @@ -310,27 +354,40 @@ Item { } \endqml -\section2 Signal Handlers +\section1 Signal Handlers -Signal handlers allow actions to be taken in response to an event. For instance, -the \l MouseArea element has signal handlers to handle mouse press, release -and click: +Signal handlers allow JavaScript code to be executed in response to an event. For +example, the \l MouseArea element has an \l {MouseArea::}{onClicked} handler that can +be used to respond to a mouse click. Below, we use this handler to print a +message whenever the mouse is clicked: \qml -MouseArea { - onPressed: console.log("mouse button pressed") +Item { + width: 100; height: 100 + + MouseArea { + anchors.fill: parent + onClicked: { + console.log("mouse button clicked") + } + } } \endqml All signal handlers begin with \e "on". -Some signal handlers include an optional parameter, for example -the MouseArea onPressed signal handler has a \e mouse parameter: +Some signal handlers include an optional parameter. For example +the MouseArea \l{MouseArea::}{onPressed} signal handler has a \c mouse parameter +that contains information about the mouse press. This parameter can be referred to in +the JavaScript code, as below: \qml MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton - onPressed: if (mouse.button == Qt.RightButton) console.log("Right mouse button pressed") + onPressed: { + if (mouse.button == Qt.RightButton) + console.log("Right mouse button pressed") + } } \endqml diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc index 495b3bd..45246e9 100644 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qdeclarativeperformance.qdoc b/doc/src/declarative/qdeclarativeperformance.qdoc index ab8759e..36b4878 100644 --- a/doc/src/declarative/qdeclarativeperformance.qdoc +++ b/doc/src/declarative/qdeclarativeperformance.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qdeclarativereference.qdoc b/doc/src/declarative/qdeclarativereference.qdoc deleted file mode 100644 index 76fcc40..0000000 --- a/doc/src/declarative/qdeclarativereference.qdoc +++ /dev/null @@ -1,81 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the Technology Preview License Agreement accompanying -** this package. -** -** GNU 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. -** -** If you have questions regarding the use of this file, please contact -** Nokia at qt-info@nokia.com. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qdeclarativereference.html - \title QML Reference - - \target qtdeclarativemainpage - - QML is a language for building the animation rich, - highly fluid user interfaces that are becoming common in portable consumer - electronics devices such as mobile phones, media players, set-top boxes and - netbooks. It is also appropriate for highly custom desktop - user interfaces, or special elements in more traditional desktop user interfaces. - - Building fluid applications is done declaratively, rather than procedurally. - That is, you specify \e what the UI should look like and how it should behave - rather than specifying step-by-step \e how to build it. Specifying a UI declaratively - does not just include the layout of the interface items, but also the way each - individual item looks and behaves and the overall flow of the application. - - The QML elements provide a sophisticated set of graphical and behavioral building - blocks. These different elements are combined together in \l {QML Documents}{QML documents} to build components - ranging in complexity from simple buttons and sliders, to complete - internet-enabled applications like a \l {http://www.flickr.com}{Flickr} photo browser. - - Getting Started: - \list - \o \l {Introduction to the QML language} - \o \l {QML Tutorial}{Tutorial: 'Hello World'} - \o \l {QML Advanced Tutorial}{Advanced Tutorial: 'Same Game'} - \o \l {QML Examples and Demos} - \endlist - - \section1 Core QML Features: - \list - \o \l {QML Documents} - \o \l {Property Binding} - \o \l {Integrating JavaScript} - \o \l {QML Scope} - \o \l {Network Transparency} - \o \l {qmlmodels}{Data Models} - \o \l {anchor-layout}{Anchor-Based Layout} - \o \l {qmlstates}{States} - \o \l {qdeclarativeanimation.html}{Animation} - \o \l {qdeclarativemodules.html}{Modules} - \o \l {qmlfocus}{Keyboard Focus} - \o \l {Extending types from QML} - \endlist - - QML Reference: - \list - \o \l {elements}{QML Elements} - \o \l {QML Global Object} - \o \l {QML Internationalization} - \endlist -*/ diff --git a/doc/src/declarative/qdeclarativesecurity.qdoc b/doc/src/declarative/qdeclarativesecurity.qdoc index 01d6c56..8aa031d 100644 --- a/doc/src/declarative/qdeclarativesecurity.qdoc +++ b/doc/src/declarative/qdeclarativesecurity.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc index b663d43..c6160c5 100644 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qml-intro.qdoc b/doc/src/declarative/qml-intro.qdoc index e02ce8f..563dc3b 100644 --- a/doc/src/declarative/qml-intro.qdoc +++ b/doc/src/declarative/qml-intro.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qmlinuse.qdoc b/doc/src/declarative/qmlinuse.qdoc index a1be46c..7380ef5 100644 --- a/doc/src/declarative/qmlinuse.qdoc +++ b/doc/src/declarative/qmlinuse.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/declarative/qmlruntime.qdoc index dfc0ad9..f6604fb 100644 --- a/doc/src/declarative/qmlruntime.qdoc +++ b/doc/src/declarative/qmlruntime.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qmlviewer.qdoc b/doc/src/declarative/qmlviewer.qdoc index 82f1fec..cfb762c 100644 --- a/doc/src/declarative/qmlviewer.qdoc +++ b/doc/src/declarative/qmlviewer.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc index 04b8ca6..4213f66 100644 --- a/doc/src/declarative/qtbinding.qdoc +++ b/doc/src/declarative/qtbinding.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** @@ -96,7 +96,7 @@ There are a number of ways to extend your QML application through C++. For examp \list \o Load a QML component and manipulate it (or its children) from C++ \o Embed a C++ object and its properties directly into a QML component (for example, to make a -particular C++ object callable from QML, or to replace a dummy list model data with a real data set) +particular C++ object callable from QML, or to replace a dummy list model with a real data set) \o Define new QML elements (through QObject-based C++ classes) and create them directly from your QML code \endlist @@ -297,17 +297,20 @@ methods on the \c myObject object, which has been set using QDeclarativeContext: \snippet doc/src/snippets/declarative/qtbinding/functions-cpp/main.cpp 0 \endtable -Note that QML does not support overloaded functions. If a C++ has more than one function with the -same name, there is no guarantee which overloaded function will be called from QML. +QML supports the calling of overloaded C++ functions. If there are multiple C++ functions with the +same name but different arguments, the correct function will be called according to the number and +the types of arguments that are provided. \section2 Receiving signals All QML signals are automatically available to C++, and can be connected to using QObject::connect() -like any ordinary Qt C++ signal. +like any ordinary Qt C++ signal. In return, any C++ signal can be received by a QML object using +\l {Signal Handlers}{signal handlers}. Here is a QML component with a signal named \c qmlSignal. This signal is connected to a C++ object's -slot using QObject::connect(): +slot using QObject::connect(), so that the \c cppSlot() method is called whenever the \c qmlSignal +is emitted: \table \row diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc index b0c6e06..05dac52 100644 --- a/doc/src/declarative/qtdeclarative.qdoc +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc index 0c14093..7895c9f 100644 --- a/doc/src/declarative/qtprogrammers.qdoc +++ b/doc/src/declarative/qtprogrammers.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc index 7e75380..3317037 100644 --- a/doc/src/declarative/scope.qdoc +++ b/doc/src/declarative/scope.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc index a24fa85..1ee5e61 100644 --- a/doc/src/declarative/tutorial.qdoc +++ b/doc/src/declarative/tutorial.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** diff --git a/doc/src/declarative/whatsnew.qdoc b/doc/src/declarative/whatsnew.qdoc index df0e999..a3ba522 100644 --- a/doc/src/declarative/whatsnew.qdoc +++ b/doc/src/declarative/whatsnew.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** |
