summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorBea Lam <bea.lam@nokia.com>2011-01-06 01:16:49 (GMT)
committerBea Lam <bea.lam@nokia.com>2011-01-06 02:08:58 (GMT)
commit57a3d4250ea438b2607d7f62ef26b8b83eb0f66c (patch)
treebcdfc151298d13cc6c65672547267d53895e645c /doc
parent572598884de78c5026694843473122487269a244 (diff)
downloadQt-57a3d4250ea438b2607d7f62ef26b8b83eb0f66c.zip
Qt-57a3d4250ea438b2607d7f62ef26b8b83eb0f66c.tar.gz
Qt-57a3d4250ea438b2607d7f62ef26b8b83eb0f66c.tar.bz2
Doc fixes for introduction page and Item docs
Moved 'Identity' and 'Property Change Signals' sections from Item docs to the intro page, which previously had a section on ids but this has been moved out of the 'Properties' section since an id isn't an ordinary property.
Diffstat (limited to 'doc')
-rw-r--r--doc/src/declarative/qdeclarativeintro.qdoc213
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