diff options
Diffstat (limited to 'doc/src/declarative/qdeclarativeintro.qdoc')
| -rw-r--r-- | doc/src/declarative/qdeclarativeintro.qdoc | 213 |
1 files changed, 130 insertions, 83 deletions
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 |