diff options
Diffstat (limited to 'doc/src/declarative')
| -rw-r--r-- | doc/src/declarative/basictypes.qdoc | 95 | ||||
| -rw-r--r-- | doc/src/declarative/codingconventions.qdoc | 18 | ||||
| -rw-r--r-- | doc/src/declarative/declarativeui.qdoc | 2 | ||||
| -rw-r--r-- | doc/src/declarative/extending.qdoc | 24 | ||||
| -rw-r--r-- | doc/src/declarative/focus.qdoc | 339 | ||||
| -rw-r--r-- | doc/src/declarative/javascriptblocks.qdoc | 4 | ||||
| -rw-r--r-- | doc/src/declarative/modules.qdoc | 66 | ||||
| -rw-r--r-- | doc/src/declarative/qdeclarativeintro.qdoc | 213 | ||||
| -rw-r--r-- | doc/src/declarative/qdeclarativereference.qdoc | 81 | ||||
| -rw-r--r-- | doc/src/declarative/qtbinding.qdoc | 13 |
10 files changed, 419 insertions, 436 deletions
diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 034b7d1..e9d3a44 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -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 ba789e0..3f92d46 100644 --- a/doc/src/declarative/codingconventions.qdoc +++ b/doc/src/declarative/codingconventions.qdoc @@ -35,7 +35,7 @@ This page assumes that you are already familiar with the QML language. If you need an introduction to the language, please read \l {Introduction to the QML language}{the QML introduction} first. -\section1 QML objects +\section1 QML Objects Through our documentation and examples, QML objects are always structured in the following order: @@ -58,7 +58,7 @@ For example, a hypothetical \e photo QML object would look like this: \snippet doc/src/snippets/declarative/codingconventions/photo.qml 0 -\section1 Grouped properties +\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. @@ -72,6 +72,18 @@ can be written like this: \snippet doc/src/snippets/declarative/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 doc/src/snippets/declarative/codingconventions/private.qml 0 + + \section1 Lists If a list contains only one element, we generally omit the square brackets. @@ -87,7 +99,7 @@ we will write this: \snippet doc/src/snippets/declarative/codingconventions/lists.qml 1 -\section1 JavaScript code +\section1 JavaScript Code If the script is a single expression, we recommend writing it inline: diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index 5d9eaaf..41b9952 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -108,6 +108,7 @@ Module. \section1 Handling Data \list +\o \l{QML Basic Types}{QML Basic Data Types} \o \l{Using QML Positioner and Repeater Items} \o \l{QML Data Models} \o \l{Presenting Data with QML} @@ -136,6 +137,7 @@ Module. \list \o \l{QML Elements} +\o \l{QML Basic Types} \o \l{QML Global Object} \o \l{QML Internationalization} \o \l{QML Security} diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 748ec6c..ff519f6 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -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 2e74fe0..ae72c3c 100644 --- a/doc/src/declarative/focus.qdoc +++ b/doc/src/declarative/focus.qdoc @@ -31,7 +31,7 @@ \title Keyboard Focus in QML When a key is pressed or released, a key event is generated and delivered to the -focused QML \l Item. To facilitate the construction of reusable components +focused QML \l Item. To facilitate the construction of reusable components and to address some of the cases unique to fluid user interfaces, the QML items add a \e scope based extension to Qt's traditional keyboard focus model. @@ -42,27 +42,21 @@ and to address some of the cases unique to fluid user interfaces, the QML items When the user presses or releases a key, the following occurs: \list 1 \o Qt receives the key action and generates a key event. -\o If the Qt widget containing the \l QDeclarativeView has focus, the key event is delivered to it. Otherwise, regular Qt key handling continues. -\o The key event is delivered by the scene to the QML \l Item with \e {active focus}. If no \l Item has \e {active focus}, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues. -\o If the QML \l Item with \e {active focus} accepts the key event, propagation stops. Otherwise the event is "bubbled up", by recursively passing it to each \l Item's parent until either the event is accepted, or the root \l Item is reached. - -If the \c {Rectangle} element in the following example has active focus and the \e A key is pressed, -it will bubble up to its parent. However, pressing the \e B key will bubble up to the root -item and thus subsequently be \l {QEvent::ignore()}{ignored}. - -\code -Item { - Item { - Keys.onPressed: { - if (event.key == Qt.Key_A) { - console.log('Key A was pressed'); - event.accepted = true; - } - } - Rectangle {} - } -} -\endcode +\o If the Qt widget containing the \l QDeclarativeView has focus, the key event +is delivered to it. Otherwise, regular Qt key handling continues. +\o The key event is delivered by the scene to the QML \l Item with +\e {active focus}. If no Item has active focus, the key event is +\l {QEvent::ignore()}{ignored} and regular Qt key handling continues. +\o If the QML Item with active focus accepts the key event, propagation +stops. Otherwise the event is "bubbled up", by recursively passing it to each +Item's parent until either the event is accepted, or the root Item is reached. + +If the \c {Rectangle} element in the following example has active focus and the \c A key is pressed, +it will bubble up to its parent. However, pressing the \c B key will bubble up to the root +item and thus subsequently be ignored. + +\snippet doc/src/snippets/declarative/focus/rectangle.qml simple key event +\snippet doc/src/snippets/declarative/focus/rectangle.qml simple key event end \o If the root \l Item is reached, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues. @@ -72,232 +66,139 @@ See also the \l {Keys}{Keys attached property} and \l {KeyNavigation}{KeyNavigat \section1 Querying the Active Focus Item -Whether or not an \l Item has \e {active focus} can be queried through the -property \c {Item::activeFocus}. For example, here we have a \l Text -element whose text is determined by whether or not it has \e {active focus}. +Whether or not an \l Item has active focus can be queried through the +property \c {Item::activeFocus} property. For example, here we have a \l Text +element whose text is determined by whether or not it has active focus. -\code -Text { - text: activeFocus ? "I have active focus!" : "I do not have active focus" -} -\endcode +\snippet doc/src/snippets/declarative/focus/rectangle.qml active focus \section1 Acquiring Focus and Focus Scopes -An \l Item requests focus by setting the \c {Item::focus} property to true. - -For very simple cases simply setting the \c {Item::focus} property is sometimes -sufficient. If we run the following example with the \l {QML Viewer}, we see that -the \c {keyHandler} element has \e {active focus} and pressing the 'A', 'B' -or 'C' keys modifies the text appropriately. - -\table -\row -\o \code - Rectangle { - color: "lightsteelblue"; width: 240; height: 25 - Text { id: myText } - Item { - id: keyHandler - focus: true - Keys.onPressed: { - if (event.key == Qt.Key_A) - myText.text = 'Key A was pressed' - else if (event.key == Qt.Key_B) - myText.text = 'Key B was pressed' - else if (event.key == Qt.Key_C) - myText.text = 'Key C was pressed' - } - } - } -\endcode -\o \image declarative-qmlfocus1.png -\endtable - -However, were the above example to be used as a self-contained component, this -simple use of the \c {Item::focus} property is no longer sufficient. The left -hand side of the following table shows what we would like to be able to write. -Here we create two instances of our previously defined component, and set the -second one to have focus. The intention is that when the \e A, \e B, or \e C -keys are pressed, the second of the two components receives the event and +An \l Item requests focus by setting the \c focus property to \c true. + +For very simple cases simply setting the \c focus property is sometimes +sufficient. If we run the following example with the \l {QML Viewer}, we see that +the \c {keyHandler} element has active focus and pressing the \c A, \c B, +or \c C keys modifies the text appropriately. + +\snippet doc/src/snippets/declarative/focus/basicwidget.qml focus true + +\image declarative-qmlfocus1.png + +However, were the above example to be used as a reusable or imported component, +this simple use of the \c focus property is no longer sufficient. + +To demonstrate, we create two instances of our previously defined component and +set the first one to have focus. The intention is that when the \c A, \c B, or +\c C keys are pressed, the first of the two components receives the event and responds accordingly. -\table -\row -\o \code -Rectangle { - color: "red"; width: 240; height: 55 - MyWidget {} - MyWidget { y: 30; focus: true } -} -\endcode -\o \code -Rectangle { - color: "red"; width: 240; height: 55 - Rectangle { - color: "lightsteelblue"; width: 240; height: 25 - Text { id: myText } - Item { - id: keyHandler - focus: true - Keys.onPressed: { - if (event.key == Qt.Key_A) - myText.text = 'Key A was pressed' - else if (event.key == Qt.Key_B) - myText.text = 'Key B was pressed' - else if (event.key == Qt.Key_C) - myText.text = 'Key C was pressed' - } - } - } - Rectangle { - y: 30; focus: true - color: "lightsteelblue"; width: 240; height: 25 - Text { id: myText } - Item { - id: keyHandler - focus: true - Keys.onPressed: { - if (event.key == Qt.Key_A) - myText.text = 'Key A was pressed' - else if (event.key == Qt.Key_B) - myText.text = 'Key B was pressed' - else if (event.key == Qt.Key_C) - myText.text = 'Key C was pressed' - } - } - } -} -\endcode -\endtable - -The right hand side of the example shows the expanded code - the equivalent QML -without the use of the component \c {MyWidget}. From this, the problem is -evident - there are no less than three elements that have the \c {Item::focus} -property set to true. Ultimately only one element can have keyboard focus, and the -system has to decide which on. In this case the first appearance of the -\c {Item::focus} property being set to true on line 4 is selected, and the value -of \c {Item::focus} in the other two instances is reverted back to false. This -is exactly the opposite of what was wanted! - -This problem is fundamentally one of visibility. The \c {MyWidget} -components each set their \c {keyHandler} Items as focused as that is all they can -do - they don't know how they are going to be used, but they do know that when -they're in use their \c {keyHandler} element is what needs focus. Likewise -the code that uses the two \c {MyWidgets} sets the second \c {MyWidget} as -focused. While it doesn't know exactly how the \c {MyWidget} is -implemented, it knows that it wants the second one to be focused. This allows us -to achieve encapsulation, allowing each widget to focus on it's appropriate behaviour -itself. - -To solve this problem - allowing components to care about what they know about -and ignore everything else - the QML items introduce a concept known as a -\e {focus scope}. For existing Qt users, a \e {focus scope} is like an -automatic focus proxy. A \e {focus scope} is created using the \l FocusScope -element. - -In the next example, a \l FocusScope is added to the component, and the visual -result shown. - -\table -\row -\o \code -FocusScope { - width: 240; height: 25 - Rectangle { - color: "lightsteelblue"; width: 240; height: 25 - Text { id: myText } - Item { - id: keyHandler - focus: true - Keys.onPressed: { - if (event.key == Qt.Key_A) - myText.text = 'Key A was pressed' - else if (event.key == Qt.Key_B) - myText.text = 'Key B was pressed' - else if (event.key == Qt.Key_C) - myText.text = 'Key C was pressed' - } - } - } -} -\endcode -\o \image declarative-qmlfocus2.png -\endtable +The code that imports and creates two MyWidget instances: +\snippet doc/src/snippets/declarative/focus/widget.qml window + +The MyWidget code: +\snippet doc/src/snippets/declarative/focus/mywidget.qml mywidget + +We would like to have the first MyWidget object to have the focus by setting its +\c focus property to \c true. However, by running the code, we can confirm that +the second widget receives the focus. + +\image declarative-qmlfocus2.png + +Looking at both \c MyWidget and \c window code, the problem is evident - there +are three elements that set the \c focus property set to \c true. The two +MyWidget sets the \c focus to \c true and the \c window component also sets the +focus. Ultimately, only one element can have keyboard focus, and the system has +to decide which element receives the focus. When the second MyWidget is created, +it receives the focus because it is the last element to set its \c focus +property to \c true. + +This problem is due to visibility. The \c MyWidget component would like to have +the focus, but it cannot control the focus when it is imported or reused. +Likewise, the \c window component does not have the ability to know if its +imported components are requesting the focus. + +To solve this problem, the QML introduces a concept known as a \e {focus scope}. +For existing Qt users, a focus scope is like an automatic focus proxy. +A focus scope is created by declaring the \l FocusScope element. + +In the next example, a \l FocusScope element is added to the component, and the +visual result shown. + +\snippet doc/src/snippets/declarative/focus/myfocusscopewidget.qml widget in focusscope + +\image declarative-qmlfocus3.png + Conceptually \e {focus scopes} are quite simple. \list -\o Within each \e {focus scope} one element may have \c {Item::focus} set to true. -If more than one \l Item has the \c {Item::focus} property set, the first is selected -and the others are unset, just like when there are no \e {focus scopes}. -\o When a \e {focus scope} receives \e {active focus}, the contained element with -\c {Item::focus} set (if any) also gets \e {active focus}. If this element is -also a \l FocusScope, the proxying behaviour continues. Both the -\e {focus scope} and the sub-focused item will have \c {Item::activeFocus} set. +\o Within each focus scope one element may have \c {Item::focus} set to +\c true. If more than one \l Item has the \c focus property set, the +last element to set the \c focus will have the focus and the others are unset, +similar to when there are no focus scopes. +\o When a focus scope receives active focus, the contained element with +\c focus set (if any) also gets the active focus. If this element is +also a \l FocusScope, the proxying behavior continues. Both the +focus scope and the sub-focused item will have \c activeFocus property set. \endlist -So far the example has the second component statically selected. It is trivial +Note that, since the FocusScope element is not a visual element, the properties +of its children need to be exposed to the parent item of the FocusScope. Layouts +and positioning elements will use these visual and styling properties to create +the layout. In our example, the \c Column element cannot display the two widgets +properly because the FocusScope lacks visual properties of its own. The MyWidget +component directly binds to the \c rectangle properties to allow the \c Column +element to create the layout containing the children of the FocusScope. + +So far, the example has the second component statically selected. It is trivial now to extend this component to make it clickable, and add it to the original -application. We still set a one of the widgets as focused by default, but from -then on clicking the either one gives it focus. - -\table -\row -\o \code -Rectangle { - color: "red"; width: 240; height: 55 - MyClickableWidget {} - MyClickableWidget { y: 30; focus: true } -} -\endcode -\o \code -FocusScope { - id: page; width: 240; height: 25 - MyWidget { focus: true } - MouseArea { anchors.fill: parent; onClicked: { page.focus = true } } -} -\endcode -\endtable +application. We still set one of the widgets as focused by default. +Now, clicking either MyClickableWidget gives it focus and the other widget +loses the focus. -\image declarative-qmlfocus3.png +The code that imports and creates two MyClickableWidget instances: +\snippet doc/src/snippets/declarative/focus/clickablewidget.qml clickable window + +The MyClickableWidget code: +\snippet doc/src/snippets/declarative/focus/myclickablewidget.qml clickable in focusscope -When a QML item explicitly relinquishes focus (by setting its -\c {Item::focus} property to false while it has \e {active focus}), the system -does not automatically select another element to receive focus. That is, it -is possible for there to be no currently \e {active focus}. +\image declarative-qmlfocus4.png -See the \l{declarative/keyinteraction/focus}{Keyboard Focus example} for a +When a QML \l Item explicitly relinquishes focus (by setting its +\c focus property to \c false while it has active focus), the +system does not automatically select another element to receive focus. That is, +it is possible for there to be no currently active focus. + +See the \l{declarative/keyinteraction/focus}{Keyboard Focus example} for a demonstration of moving keyboard focus between multiple areas using FocusScope elements. \section1 Advanced uses of Focus Scopes -Focus scopes allow focus to allocation to be easily partitioned. Several +Focus scopes allow focus to allocation to be easily partitioned. Several QML items use it to this effect. -\l ListView, for example, is itself a focus scope. Generally this isn't +\l ListView, for example, is itself a focus scope. Generally this isn't noticeable as \l ListView doesn't usually have manually added visual children. By being a focus scope, \l ListView can focus the current list item without -worrying about how that will effect the rest of the application. This allows -the current item delegate to react to key presses. +worrying about how that will effect the rest of the application. This allows the +current item delegate to react to key presses. -This contrived example shows how this works. Pressing the \c Return key will +This contrived example shows how this works. Pressing the \c Return key will print the name of the current list item. -\table -\row -\o \snippet doc/src/snippets/declarative/focusscopes.qml 0 -\o \image declarative-qmlfocus4.png -\endtable +\snippet doc/src/snippets/declarative/focus/advancedFocus.qml FocusScope delegate + +\image declarative-qmlfocus5.png -While the example is simple, there's a lot going on behind the scenes. Whenever +While the example is simple, there are a lot going on behind the scenes. Whenever the current item changes, the \l ListView sets the delegate's \c {Item::focus} -property. As the \l ListView is a \e {focus scope}, this doesn't effect the -rest of the application. However, if the \l ListView itself has -\e {active focus} this causes the delegate itself to receive \e {active focus}. -In this example, the root element of the delegate is also a \e {focus scope}, -which in turn gives \e {active focus} to the \c {Text} element that -actually performs the work of handling the \e {Return} key. +property. As the \l ListView is a focus scope, this doesn't affect the +rest of the application. However, if the \l ListView itself has +active focus this causes the delegate itself to receive active focus. +In this example, the root element of the delegate is also a focus scope, +which in turn gives active focus to the \c {Text} element that actually performs +the work of handling the \c {Return} key. All of the QML view classes, such as \l PathView and \l GridView, behave in a similar manner to allow key handling in their respective delegates. diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index 155bd6e..68cb392 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -99,7 +99,9 @@ resource, the component's \l {QDeclarativeComponent::status()}{status} is set to 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. +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 Code-Behind Implementation Files diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc index 011eb63..8d23170 100644 --- a/doc/src/declarative/modules.qdoc +++ b/doc/src/declarative/modules.qdoc @@ -31,14 +31,14 @@ \section1 QML Modules -A module is a set of QML content files that can be imported as a unit into a QML +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 +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 +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 @@ -54,13 +54,13 @@ This can be seen in the snippet commonly found at the top of QML files: \qml import QtQuick 1.0 \endqml - -This imports version 4.7 of the "Qt" module into the global namespace. (The QML + +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{The QML import path}{import path}. There are two types of QML modules: +The \c Qt module is an \e installed module; it is found in the +\l{The QML import path}{import path}. There are two types of QML modules: location modules (defined by a URL) and installed modules (defined by a URI). @@ -87,8 +87,8 @@ directory using a relative or absolute path, like this: MyQMLProject |- MyComponents |- Slider.qml - |- CheckBox.qml - |- Main + |- CheckBox.qml + |- Main |- application.qml \endcode @@ -112,7 +112,7 @@ be imported like this: Remote location modules must have a \l{Writing a qmldir file}{qmldir file} in the same directory to specify which QML files should be made available. See the -\l {#qmldirexample}{example} below. The qmldir file is optional for modules on +\l {#qmldirexample}{example} below. The qmldir file is optional for modules on the local filesystem. @@ -121,8 +121,8 @@ the local filesystem. Installed modules are modules that are installed on the -local filesystem within the QML import path, or modules defined in C++ -application code. When importing an installed module, an un-quoted URI is +local filesystem within the QML import path, or modules defined in C++ +application code. When importing an installed module, an un-quoted URI is used, with a mandatory version number: \code @@ -131,7 +131,7 @@ used, with a mandatory version number: \endcode Installed modules that are installed into the import path or created -as a \l{QDeclarativeExtensionPlugin}{QML C++ plugin} must define a +as a \l{QDeclarativeExtensionPlugin}{QML C++ plugin} must define a \l{Writing a qmldir file}{qmldir file}. @@ -142,7 +142,7 @@ The default import path includes: \list \o The directory of the current file -\o The location specified by QLibraryInfo::ImportsPath +\o The location specified by QLibraryInfo::ImportsPath \o Paths specified by the \c QML_IMPORT_PATH environment variable \endlist @@ -153,10 +153,10 @@ When running the \l {QML Viewer}, use the \c -I option to add paths to the impor \section2 Creating installed modules in C++ -C++ applications can dynamically define installed modules using -qmlRegisterType(). +C++ applications can dynamically define installed modules using +qmlRegisterType(). -For \l{QDeclarativeExtensionPlugin}{QML C++ plugins}, the +For \l{QDeclarativeExtensionPlugin}{QML C++ plugins}, the module URI is automatically passed to QDeclarativeExtensionPlugin::registerTypes(). The QDeclarativeExtensionPlugin documentation shows how to use this URI to call qmlRegisterType() to enable the plugin library to be built as @@ -167,7 +167,7 @@ in QML, like this: import com.nokia.TimeExample 1.0 \endcode -A \l{QDeclarativeExtensionPlugin}{QML C++ plugin} also requires a +A \l{QDeclarativeExtensionPlugin}{QML C++ plugin} also requires a \l{Writing a qmldir file}{qmldir file} to make it available to the QML engine. @@ -190,9 +190,9 @@ Types from these modules can then only be used when qualified by the namespace: \qml QtLibrary.Rectangle { ... } - + MyComponents.Slider { ... } - + MyModule.SomeComponent { ... } \endqml @@ -209,19 +209,21 @@ 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. \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 +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 location 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: @@ -237,7 +239,7 @@ plugin <Name> [<Path>] \bold {<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. +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 @@ -264,10 +266,10 @@ provide those identifiers. \bold {plugin <Name> [<Path>]} lines are used to add \l{QDeclarativeExtensionPlugin}{QML C++ plugins} to the module. <Name> is the name of the library. It is usually not the same as the file name of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes would produce -\c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows. +\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 +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 QDeclarativeEngine::pluginPathList() and modified using QDeclarativeEngine::addPluginPath(). When running the \l {QML Viewer}, use the \c -P option to add paths to the plugin search path. @@ -275,7 +277,7 @@ file. The plugin search path can be queried with QDeclarativeEngine::pluginPathL \target qmldirexample \section2 Example -If the components in the \c MyComponents directory from the +If the components in the \c MyComponents directory from the \l{Location Modules}{earlier example} were to be made available as a network resource, the directory would need to contain a \c qmldir file similar to this: @@ -284,7 +286,7 @@ ComponentA 1.0 ComponentA.qml ComponentB 1.0 ComponentB.qml \endcode -The \c MyComponents directory could then be imported as a module using: +The \c MyComponents directory could then be imported as a module using: \code import "http://the-server-name.com/MyComponents" @@ -298,15 +300,15 @@ a later version is used, as the \c qmldir file specifies that these elements are only available in the 1.0 version. -For examples of \c qmldir files for plugins, see the -\l {declarative/cppextensions/plugins}{Plugins} example and +For examples of \c qmldir files for plugins, see the +\l {declarative/cppextensions/plugins}{Plugins} example and \l {Tutorial: Writing QML extensions with C++}. \section1 Debugging The \c QML_IMPORT_TRACE environment variable can be useful for debugging -when there are problems with finding and loading modules. See +when there are problems with finding and loading modules. See \l{Debugging module imports} for more information. diff --git a/doc/src/declarative/qdeclarativeintro.qdoc b/doc/src/declarative/qdeclarativeintro.qdoc index 4e41fda..20db248 100644 --- a/doc/src/declarative/qdeclarativeintro.qdoc +++ b/doc/src/declarative/qdeclarativeintro.qdoc @@ -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 { } \endcode -Objects are specified by their type, followed by a pair of braces. Object -types always begin with a capital letter. In the above example, there are -two objects, a \l Rectangle, and an \l Image. Between the braces, we can specify -information about the object, such as its properties. +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,13 @@ 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. - -\code -Rotation { - angle: 360 * 3 -} -\endcode - -These expressions can include references to other objects and properties, in which case -a \e binding is established: when the value of the expression changes, the property the -expression has been assigned to is automatically updated to that value. - -\code -Item { - Text { - id: text1 - text: "Hello World" - } - Text { - id: text2 - text: text1.text - } -} -\endcode - -In the example above, the \c text2 object will display the same text as \c text1. If \c text1 is changed, -\c text2 is automatically changed to the same value. -Note that to refer to other objects, we use their \e id values. (See below for more -information on the \e id property.) -\section1 QML Comments +\section1 Comments Commenting in QML is similar to JavaScript. \list @@ -149,27 +117,95 @@ Text { } \endcode -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. \code Item { x: 10.5 // a 'real' property - ... state: "details" // a 'string' property focus: true // a 'bool' property + ... } \endcode @@ -183,31 +219,30 @@ Item { } \endcode -\section3 The \c id property +Note that with the exception of \l {Attached Properties}, properties always begin with a lowercase +letter. -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. -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. +\section2 Property change notifications -\code -Item { - Rectangle { - id: myRect - width: 100 - height: 100 - } - Rectangle { - width: myRect.width - height: 200 - } +When a property changes value, it can send a signal to notify others of this change. + +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 +Rectangle { + width: 100; height: 100 + + onWidthChanged: console.log("Width has changed to:", width) + onColorChanged: console.log("Color has changed to:", color) } -\endcode +\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,7 +328,9 @@ 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: +For example, the \l ListView element attaches the \e ListView.isCurrentItem property +to each delegate it creates: + \code Component { id: myDelegate @@ -307,9 +344,6 @@ ListView { } \endcode -The \l ListView element attaches the \e ListView.isCurrentItem property -to each delegate it creates. - Another example of attached properties is the \l Keys element which attaches properties for handling key presses to any visual Item, for example: @@ -321,27 +355,40 @@ Item { } \endcode -\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: \code -MouseArea { - onPressed: console.log("mouse button pressed") +Item { + width: 100; height: 100 + + MouseArea { + anchors.fill: parent + onClicked: { + console.log("mouse button clicked") + } + } } \endcode All signal handlers begin with \e "on". -Some signal handlers include an optional parameter, for example -the MouseArea onPressed signal handler has a \e mouse parameter: +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: \code 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") + } } \endcode diff --git a/doc/src/declarative/qdeclarativereference.qdoc b/doc/src/declarative/qdeclarativereference.qdoc deleted file mode 100644 index c2c5e91..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/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc index 04b8ca6..8ee7247 100644 --- a/doc/src/declarative/qtbinding.qdoc +++ b/doc/src/declarative/qtbinding.qdoc @@ -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 |