diff options
| author | Jerome Pasion <jerome.pasion@nokia.com> | 2012-02-09 17:31:02 +0100 |
|---|---|---|
| committer | Qt by Nokia <qt-info@nokia.com> | 2012-02-14 12:53:21 +0100 |
| commit | 2d4e6ff9dd1e0e3410c4dc002c25d80fecfeafd2 (patch) | |
| tree | b12aec803acf837024b4426526f1ce69cb3080ae | |
| parent | d95178153a0f15991b2e6e91216dbcf5c0be2af3 (diff) | |
Doc: Overhaul of doc/src/declarative and QtQuick2 docs.
-Consolidated model/view documentation into one.
-Added a new navigation for all overviews (grouped the pages)
-New front page that shows the grouping
-Separated the Qt C++ from the main QML overviews
-Consolidated Qt C++ into the "declarative runtime" section
-New articles about JavaScript, the engine, and plugins
-Fixed the older examples. New snippet comments
-Renamed some of the articles
-kept the qtquick2 qmlmodule
-"Qt Quick Elements"
Moved contents of doc/src/declarative into respective
module dirs.
-Qt Quick 2, LocalStorage, Particles, and QML are now
separate.
-Removed unused or duplicate documentation.
-edited C++ examples
-removed navigation and "\inqmlmodule QtQuick 2" for
those pages that are not in Qt Quick 2
-fixed doc/src/ licenses to header.FDL from qtbase
Change-Id: Ib36f9c07565d91160fa8d04f9670c438f684b82a
Reviewed-by: Sergio Ahumada <sergio.ahumada@nokia.com>
| -rwxr-xr-x | doc/config/style/qtquick.css | 82 | ||||
| -rw-r--r-- | doc/src/declarative/declarativeui.qdoc | 160 | ||||
| -rw-r--r-- | doc/src/declarative/examples.qdoc | 253 | ||||
| -rw-r--r-- | doc/src/declarative/extending.qdoc | 786 | ||||
| -rw-r--r-- | doc/src/declarative/globalobject.qdoc | 126 | ||||
| -rw-r--r-- | doc/src/declarative/qdeclarativedocument.qdoc | 144 | ||||
| -rw-r--r-- | doc/src/declarative/qdeclarativeintro.qdoc | 405 | ||||
| -rw-r--r-- | doc/src/declarative/qdeclarativemodels.qdoc | 511 | ||||
| -rw-r--r-- | doc/src/declarative/qmlinuse.qdoc | 500 | ||||
| -rw-r--r-- | doc/src/declarative/qmlviews.qdoc | 128 | ||||
| -rw-r--r-- | doc/src/declarative/qtprogrammers.qdoc | 156 | ||||
| -rw-r--r-- | doc/src/examples/advtutorial.qdoc (renamed from doc/src/declarative/advtutorial.qdoc) | 2 | ||||
| -rw-r--r-- | doc/src/examples/dynamicview-tutorial.qdoc (renamed from doc/src/declarative/dynamicview-tutorial.qdoc) | 0 | ||||
| -rw-r--r-- | doc/src/examples/example-slideswitch.qdoc | 12 | ||||
| -rw-r--r-- | doc/src/examples/example-textballoons.qdoc | 1 | ||||
| -rw-r--r-- | doc/src/examples/examples.qdoc | 307 | ||||
| -rw-r--r-- | doc/src/examples/tutorial.qdoc (renamed from doc/src/declarative/tutorial.qdoc) | 4 | ||||
| -rw-r--r-- | doc/src/external-resources.qdoc | 32 | ||||
| -rw-r--r-- | doc/src/images/modelview-overview.png | bin | 0 -> 15042 bytes | |||
| -rw-r--r-- | doc/src/localstorage/localstorage.qdoc | 123 | ||||
| -rw-r--r-- | doc/src/particles/particles.qdoc (renamed from doc/src/declarative/particles.qdoc) | 10 | ||||
| -rw-r--r-- | doc/src/qml/basictypes.qdoc (renamed from doc/src/declarative/basictypes.qdoc) | 11 | ||||
| -rw-r--r-- | doc/src/qml/c++models.qdoc | 208 | ||||
| -rw-r--r-- | doc/src/qml/codingconventions.qdoc (renamed from doc/src/declarative/codingconventions.qdoc) | 6 | ||||
| -rw-r--r-- | doc/src/qml/debugging.qdoc (renamed from doc/src/declarative/qdeclarativedebugging.qdoc) | 25 | ||||
| -rw-r--r-- | doc/src/qml/dynamicobjects.qdoc (renamed from doc/src/declarative/dynamicobjects.qdoc) | 16 | ||||
| -rw-r--r-- | doc/src/qml/extending-tutorial.qdoc (renamed from doc/src/declarative/extending-tutorial.qdoc) | 9 | ||||
| -rw-r--r-- | doc/src/qml/globalobject.qdoc | 41 | ||||
| -rw-r--r-- | doc/src/qml/integrating.qdoc (renamed from doc/src/declarative/integrating.qdoc) | 12 | ||||
| -rw-r--r-- | doc/src/qml/javascriptblocks.qdoc (renamed from doc/src/declarative/javascriptblocks.qdoc) | 271 | ||||
| -rw-r--r-- | doc/src/qml/modules.qdoc (renamed from doc/src/declarative/modules.qdoc) | 8 | ||||
| -rw-r--r-- | doc/src/qml/network.qdoc (renamed from doc/src/declarative/network.qdoc) | 87 | ||||
| -rw-r--r-- | doc/src/qml/performance.qdoc (renamed from doc/src/declarative/qdeclarativeperformance.qdoc) | 2 | ||||
| -rw-r--r-- | doc/src/qml/propertybinding.qdoc (renamed from doc/src/declarative/propertybinding.qdoc) | 90 | ||||
| -rw-r--r-- | doc/src/qml/qmlcomponents.qdoc (renamed from doc/src/declarative/qmlreusablecomponents.qdoc) | 71 | ||||
| -rw-r--r-- | doc/src/qml/qmldate.qdoc (renamed from doc/src/declarative/qmldate.qdoc) | 0 | ||||
| -rw-r--r-- | doc/src/qml/qmldocument.qdoc | 151 | ||||
| -rw-r--r-- | doc/src/qml/qmlengine.qdoc | 477 | ||||
| -rw-r--r-- | doc/src/qml/qmlevents.qdoc (renamed from doc/src/declarative/qmlevents.qdoc) | 42 | ||||
| -rw-r--r-- | doc/src/qml/qmli18n.qdoc (renamed from doc/src/declarative/qdeclarativei18n.qdoc) | 9 | ||||
| -rw-r--r-- | doc/src/qml/qmlintro.qdoc | 1234 | ||||
| -rw-r--r-- | doc/src/qml/qmlnumber.qdoc (renamed from doc/src/declarative/qmlnumber.qdoc) | 0 | ||||
| -rw-r--r-- | doc/src/qml/qmlplugins.qdoc | 133 | ||||
| -rw-r--r-- | doc/src/qml/qmlruntime.qdoc (renamed from doc/src/declarative/qmlruntime.qdoc) | 6 | ||||
| -rw-r--r-- | doc/src/qml/qmlsyntax.qdoc (renamed from doc/src/declarative/qmlsyntax.qdoc) | 7 | ||||
| -rw-r--r-- | doc/src/qml/qmltest.qdoc (renamed from doc/src/declarative/qmltest.qdoc) | 1 | ||||
| -rw-r--r-- | doc/src/qml/qmltypes.qdoc | 783 | ||||
| -rw-r--r-- | doc/src/qml/qmlviewer.qdoc (renamed from doc/src/declarative/qmlviewer.qdoc) | 17 | ||||
| -rw-r--r-- | doc/src/qml/qtbinding.qdoc (renamed from doc/src/declarative/qtbinding.qdoc) | 13 | ||||
| -rw-r--r-- | doc/src/qml/qtdeclarative.qdoc (renamed from doc/src/declarative/qtdeclarative.qdoc) | 0 | ||||
| -rw-r--r-- | doc/src/qml/qtjavascript.qdoc (renamed from doc/src/declarative/qtjavascript.qdoc) | 2 | ||||
| -rw-r--r-- | doc/src/qml/qtprogrammers.qdoc | 197 | ||||
| -rw-r--r-- | doc/src/qml/scope.qdoc (renamed from doc/src/declarative/scope.qdoc) | 25 | ||||
| -rw-r--r-- | doc/src/qml/security.qdoc (renamed from doc/src/declarative/qdeclarativesecurity.qdoc) | 6 | ||||
| -rw-r--r-- | doc/src/qtdeclarative.qdoc | 180 | ||||
| -rw-r--r-- | doc/src/qtquick2/anchor-layout.qdoc (renamed from doc/src/declarative/anchor-layout.qdoc) | 10 | ||||
| -rw-r--r-- | doc/src/qtquick2/animation.qdoc (renamed from doc/src/declarative/animation.qdoc) | 7 | ||||
| -rw-r--r-- | doc/src/qtquick2/basicelements.qdoc (renamed from doc/src/declarative/basicelements.qdoc) | 58 | ||||
| -rw-r--r-- | doc/src/qtquick2/behaviors-and-states.qdoc (renamed from doc/src/declarative/behaviors-and-states.qdoc) | 12 | ||||
| -rw-r--r-- | doc/src/qtquick2/canvaspainting.qdoc (renamed from doc/src/declarative/qmlwebkit.qdoc) | 27 | ||||
| -rw-r--r-- | doc/src/qtquick2/elements.qdoc (renamed from doc/src/declarative/elements.qdoc) | 35 | ||||
| -rw-r--r-- | doc/src/qtquick2/focus.qdoc (renamed from doc/src/declarative/focus.qdoc) | 9 | ||||
| -rw-r--r-- | doc/src/qtquick2/modelview.qdoc | 378 | ||||
| -rw-r--r-- | doc/src/qtquick2/mouseevents.qdoc (renamed from doc/src/declarative/mouseevents.qdoc) | 9 | ||||
| -rw-r--r-- | doc/src/qtquick2/positioners.qdoc (renamed from doc/src/declarative/positioners.qdoc) | 63 | ||||
| -rw-r--r-- | doc/src/qtquick2/qmltexthandling.qdoc (renamed from doc/src/declarative/qmltexthandling.qdoc) | 10 | ||||
| -rw-r--r-- | doc/src/qtquick2/qtquick-intro.qdoc (renamed from doc/src/declarative/qtquick-intro.qdoc) | 69 | ||||
| -rw-r--r-- | doc/src/qtquick2/qtquick2.qdoc (renamed from doc/src/declarative/qtquick2.qdoc) | 0 | ||||
| -rw-r--r-- | doc/src/qtquick2/righttoleft.qdoc (renamed from doc/src/declarative/righttoleft.qdoc) | 12 | ||||
| -rw-r--r-- | doc/src/qtquick2/shaders.qdoc | 52 | ||||
| -rw-r--r-- | doc/src/qtquick2/states.qdoc (renamed from doc/src/declarative/qdeclarativestates.qdoc) | 11 | ||||
| -rw-r--r-- | doc/src/qtquick2/writingcomponents.qdoc | 498 | ||||
| -rw-r--r-- | doc/src/whatsnew.qdoc (renamed from doc/src/declarative/whatsnew.qdoc) | 4 | ||||
| -rw-r--r-- | examples/declarative/cppextensions/referenceexamples/adding/person.h | 4 | ||||
| -rw-r--r-- | examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h | 5 | ||||
| -rw-r--r-- | examples/declarative/cppextensions/referenceexamples/attached/example.qml | 31 | ||||
| -rw-r--r-- | examples/declarative/cppextensions/referenceexamples/attached/main.cpp | 7 | ||||
| -rw-r--r-- | examples/declarative/cppextensions/referenceexamples/coercion/main.cpp | 7 | ||||
| -rw-r--r-- | examples/declarative/cppextensions/referenceexamples/coercion/person.h | 3 | ||||
| -rw-r--r-- | examples/declarative/cppextensions/referenceexamples/grouped/example.qml | 30 | ||||
| -rw-r--r-- | examples/declarative/cppextensions/referenceexamples/methods/example.qml | 4 | ||||
| -rw-r--r-- | examples/declarative/cppextensions/referenceexamples/properties/main.cpp | 2 | ||||
| -rw-r--r-- | examples/declarative/cppextensions/referenceexamples/signal/example.qml | 16 |
83 files changed, 5589 insertions, 3666 deletions
diff --git a/doc/config/style/qtquick.css b/doc/config/style/qtquick.css index bdd0ea3d29..fe68f466d5 100755 --- a/doc/config/style/qtquick.css +++ b/doc/config/style/qtquick.css @@ -679,3 +679,85 @@ } } /* end of print media */ + + +/* modify the TOC layouts */ +div.toc ul { + padding-left: 20px; +} +div.toc li { + padding-left: 4px; +} +/* Remove the border around images*/ +a img +{ + border:none; +} + +/*Add styling to the front pages*/ + +.threecolumn_area +{ + padding-top: 20px; + padding-bottom: 20px; +} +.threecolumn_piece +{ + display: inline-block; + margin-left: 78px; + margin-top: 8px; + padding: 0; + vertical-align: top; + width: 25.5%; +} +div.threecolumn_piece ul { + list-style-type: none; + padding-left: 0px; + margin-top: 2px; +} +div.threecolumn_piece p { + margin-bottom: 7px; + color: #5C626E; + text-decoration: none; + font-weight: bold; +} +div.threecolumn_piece li { + padding-left: 0px; + margin-bottom: 5px; +} +div.threecolumn_piece a { + font-weight: normal; +} +/* Add style to guide page*/ +.fourcolumn_area +{ + padding-top: 20px; + padding-bottom: 20px; +} +.fourcolumn_piece +{ + display: inline-block; + margin-left: 35px; + margin-top: 8px; + padding: 0; + vertical-align: top; + width: 21.3%; +} +div.fourcolumn_piece ul { + list-style-type: none; + padding-left: 0px; + margin-top: 2px; +} +div.fourcolumn_piece p { + margin-bottom: 7px; + color: #40444D; + text-decoration: none; + font-weight: bold; +} +div.fourcolumn_piece li { + padding-left: 0px; + margin-bottom: 5px; +} +div.fourcolumn_piece a { + font-weight: normal; +} diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc deleted file mode 100644 index 5e44d86d0c..0000000000 --- a/doc/src/declarative/declarativeui.qdoc +++ /dev/null @@ -1,160 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\title Qt Quick -\page qtquick.html -\inqmlmodule QtQuick 2 -\ingroup qt-gui-concepts - -\brief Qt Quick provides a declarative framework for building highly -dynamic user interfaces. - -Qt Quick is a collection of technologies that are designed to help -developers create the kind of intuitive, modern, fluid user -interfaces that are increasingly used on mobile phones, media players, -set-top boxes and other portable devices. - -Qt Quick consists of a rich set of user interface elements, a declarative -language for describing user interfaces and a language runtime. A collection -of C++ APIs is used to integrate these high level features with classic -Qt applications. - -\section1 Getting Started - -\list -\o \l{Introduction to Qt Quick} -\o \l{QML for Qt Programmers}{QML Programming for Qt Programmers} -\o \l{Getting Started Programming with QML} - -\o \l{What's New in Qt Quick 2}{What's New in the Qt Quick Release} -\o \l{QML Examples} -\endlist - -\section1 QML Features - -\list -\o \l{QML Basic Elements}{Basic Elements} -\o \l{QML Basic Types}{Data Types} -\o \l{Property Binding} -\o \l{Using QML Positioner and Repeater Items}{Component Layouts} -\o \l{Anchor-based Layout in QML}{Layouts using Anchors} -\o \l{QML Mouse Events}{Mouse Events} -\o \l{QML Text Handling and Validators}{Text Handling and Validators} -\o \l{Keyboard Focus in QML}{Keyboard Focus} -\o \l{QML Signal and Handler Event System}{Signal and Handler Event System} -\o \l{Importing Reusable Components} -\o \l{QML States}{States} -\o \l{QML Animation and Transitions}{Animation and Transitions} -\o \l{QML Data Models}{Structuring Data with Models} -\o \l{Presenting Data with Views} -\o \l{Extending QML Functionalities using C++} -\o \l{Using QML Bindings in C++ Applications} -\o \l{Integrating QML Code with Existing Qt UI Code} -\o \l{Dynamic Object Management in QML}{Dynamic Object Management} -\o \l{Network Transparency}{Loading Resources in QML} -\o \l{QML Internationalization}{Internationalization} -\o \l{Accessible}{Accessibility} -\endlist - -\section1 QML Add-Ons - -\list -\o \l{QtWebKit QML Module} -\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-plugins.html}{Mobility QML Plugins} -\endlist - -\section1 Qt Quick Tools - -\list -\o \l{Debugging QML} -\o \l{external: Developing Qt Quick Applications with Creator}{Developing with Qt Creator} -\o \l{QML Viewer} -\endlist - -\section1 Reference - -\list -\o \l{Introduction to the QML language}{QML Syntax} -\o \l{QML Elements} -\o \l{Qt Declarative Module} -\o \l{QML Basic Types}{QML Data Types} -\o \l{QML Coding Conventions} -\o \l{external: Qt Creator Manual}{Qt Creator Manual} -\o \l{Programming with Qt} -\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/index.html}{Qt Mobility Documentation} -\endlist - -\section1 Architecture - -\list -\o \l{Qt Declarative UI Runtime} -\o \l{Integrating JavaScript} -\o \l{QML Scope} -\o \l{QML Modules} -\o \l{QML Documents} -\o \l{QML Global Object} -\o \l{QML Internationalization} -\o \l{QML Right-to-left User Interfaces} -\o \l{QML Security} -\o \l{Qt Declarative Module} -\endlist - -\section1 Examples - -\list -\o \l{QML Tutorial}{"Hello World" Tutorial} -\o \l{Getting Started Programming with QML} -\o \l{QML Advanced Tutorial}{Tutorial: "Same Game"} -\o \l{Tutorial: Writing QML extensions with C++} -\o \l{QML Examples and Demos} - -\o Forum Nokia: -\l{http://wiki.forum.nokia.com/index.php/Qt_Quick_examples_for_porting}{Qt Quick -examples for porting} -\endlist - -\section1 Best Practices - -\list -\o \l{QML Best Practices: Coding Conventions}{Coding Tips} -\o \l{QML Performance}{Performance Tips} -\endlist - -\section1 License Information -\list -\o \l{Qt Quick Licensing Information} -\endlist - -\section1 Online Examples - -\list -\o Forum Nokia: -\l{http://wiki.forum.nokia.com/index.php/Qt_Quick_examples_for_porting}{Qt Quick -examples for porting} -\endlist -*/ diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc deleted file mode 100644 index 836519a892..0000000000 --- a/doc/src/declarative/examples.qdoc +++ /dev/null @@ -1,253 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qdeclarativeexamples.html -\inqmlmodule QtQuick 2 - \title QML Examples - \brief Building UIs with QML - \ingroup all-examples - - -Qt includes a set of examples that show how to use various aspects -of QML. The examples are demonstrations of particular QML components, -some are small code snippets, while others contain more complete and -functional applications. - -To run the examples, open them in Qt Creator or use the included -\l {QML Viewer} tool. The \l {QML Viewer} can be run from the command line: - -\code - qmlviewer $QTDIR/examples/declarative/samegame/samegame.qml -\endcode - -On Mac OS X, you can run the included "QMLViewer" application from the -Finder, or use the command line: - -\code - QMLViewer.app/Contents/MacOS/QMLViewer $QTDIR/examples/declarative/samegame/samegame.qml -\endcode - - -The examples can be found in Qt's \c examples/declarative directory. - - -\section1 Functional Applications - -These QML examples integrate a variety of features to demonstrate how QML -can be used to produce sophisticated interfaces and applications: - - -\table -\row - -\o -\l{declarative/calculator}{Calculator} -\image qml-calculator-example-small.png - -\o -\l{declarative/flickr}{Flickr Mobile} -\image qml-flickr-demo-small.png - -\o -\l{declarative/minehunt}{Minehunt} -\image qml-minehunt-demo-small.png - -\row - -\o -\l{declarative/photoviewer}{Photo Viewer} -\image qml-photoviewer-demo-small.png - -\o -\l{declarative/rssnews}{RSS News Reader} -\image qml-rssnews-demo-small.png - -\o -\l{declarative/samegame}{Same Game} -\image qml-samegame-demo-small.png - -\row - -\o -\l{declarative/snake}{Snake} -\image qml-snake-demo-small.png - -\o -\l{declarative/twitter}{Twitter} -\image qml-twitter-demo-small.png - -\o -\l{declarative/webbrowser}{Web Browser} -\image qml-webbrowser-demo-small.png - -\endtable - -\section1 Code Snippets - -These QML examples are small, simple applications that show how to use a particular -QML component or feature. If you are new -to QML, you may also find the \l{QML Tutorial}{Hello World} and -\l {QML Advanced Tutorial}{Same Game} tutorials useful. - -\section2 Animation -\list -\o \l{declarative/animation/basics}{Basics} -\o \l{declarative/animation/behaviors}{Behaviors} -\o \l{declarative/animation/easing}{Easing} -\o \l{declarative/animation/states}{States} -\endlist - -\section2 Image Elements -\list -\o \l{declarative/imageelements/borderimage}{BorderImage} -\o \l{declarative/imageelements/image}{Image} -\endlist - -\section2 Text -\list -\o \l{declarative/text/fonts}{Fonts} -\o \l{declarative/text/textselection}{Text Selection} -\endlist - -\section2 Positioners -\list -\o \l{declarative/positioners}{Example} -\endlist - -\section2 Key Interaction -\list -\o \l{declarative/keyinteraction/focus}{Focus} -\endlist - -\section2 Touch Interaction -\list -\o \l{declarative/touchinteraction/mousearea}{MouseArea} -\endlist - -\section2 UI Components -\list -\o \l{declarative/ui-components/dialcontrol}{Dial control} -\o \l{declarative/ui-components/flipable}{Flipable} -\o \l{declarative/ui-components/progressbar}{Progress bar} -\o \l{declarative/ui-components/scrollbar}{Scroll bar} -\o \l{declarative/ui-components/searchbox}{Search box} -\o \l{declarative/ui-components/slideswitch}{Slide switch} -\o \l{declarative/ui-components/spinner}{Spinner} -\o \l{declarative/ui-components/tabwidget}{Tab widget} -\endlist - -\section2 Toys -\list -\o \l{declarative/toys/clocks}{Clocks} -\o \l{declarative/toys/corkboards}{Corkboards} -\o \l{declarative/toys/dynamicscene}{Dynamic Scene} -\o \l{declarative/toys/tic-tac-toe}{Tic Tac Toe} -\o \l{declarative/toys/tvtennis}{TV Tennis} -\endlist - -\section2 Models and Views -\list -\o \l{declarative/modelviews/gridview}{GridView} -\o \l{declarative/modelviews/listview}{ListView} -\o \l{declarative/modelviews/pathview}{PathView} -\o \l{declarative/modelviews/package}{Package} -\o \l{declarative/modelviews/parallax}{Parallax} -\o \l{declarative/modelviews/visualitemmodel}{VisualItemModel} - -\o \l{declarative/modelviews/stringlistmodel}{String ListModel} -\o \l{declarative/modelviews/objectlistmodel}{Object ListModel} -\o \l{declarative/modelviews/abstractitemmodel}{AbstractItemModel} - -\o \l{declarative/modelviews/webview}{WebView} -\endlist - -\section2 XML -\list -\o \l{declarative/xml/xmlhttprequest}{XmlHttpRequest} -\endlist - -\section2 Internationalization (i18n) -\list -\o \l{declarative/i18n}{Example} -\endlist - -\section2 Right-to-left User Interfaces -\list -\o \l{declarative/righttoleft/layoutmirroring}{Layout mirroring} -\o \l{declarative/righttoleft/layoutdirection}{Layout direction} -\o \l{declarative/righttoleft/textalignment}{Text alignment} -\endlist - -\section2 Threading -\list -\o \l{declarative/threading/threadedlistmodel}{Threaded ListModel} -\o \l{declarative/threading/workerscript}{WorkerScript} -\endlist - -\section2 Screen Orientation -\list -\o \l{declarative/screenorientation}{Example} -\endlist - -\section2 SQL Local Storage -\list -\o \l{declarative/sqllocalstorage}{Example} -\endlist - -\section2 C++ Extensions -\list -\o \l{declarative-cppextensions-reference.html}{Reference examples} -\o \l{declarative/cppextensions/plugins}{Plugins} -\o \l{declarative-cppextensions-qgraphicslayouts.html}{QGraphicsLayouts} -\o \l{declarative/cppextensions/qwidgets}{QWidgets} -\o \l{declarative/cppextensions/imageprovider}{Image provider} -\o \l{declarative/cppextensions/networkaccessmanagerfactory}{Network access manager factory} -\endlist - -\section2 Scenegraph -\list -\o \l{declarative/painteditem/textballoons}{Painted Item} -\endlist - -\section1 Labs - -\list -\o \l{src/imports/folderlistmodel}{Folder List Model} - a C++ model plugin -\endlist - -\section1 Tutorials - -\list -\o \l {QML Tutorial}{Hello World} -\o \l {QML Advanced Tutorial}{Same Game} -\o \l {Tutorial: Writing QML Extensions with C++}{Writing QML Extensions with C++} -\o \l {QML Dynamic View Ordering Tutorial}{Dynamic View Ordering} -\endlist - -*/ - diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc deleted file mode 100644 index 1180a029af..0000000000 --- a/doc/src/declarative/extending.qdoc +++ /dev/null @@ -1,786 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-extending.html -\inqmlmodule QtQuick 2 -\ingroup qml-features -\contentspage QML Features -\previouspage {Presenting Data with Views} -\nextpage {Using QML Bindings in C++ Applications} -\title Extending QML Functionalities using C++ - -The QML syntax declaratively describes how to construct an in-memory object -tree. In Qt, QML is mainly used to describe a visual scene graph, but it is -not conceptually limited to this: the QML format is an abstract description of -any object tree. All the QML element types included in Qt are implemented using -the C++ extension mechanisms describe on this page. Programmers can use these -APIs to add new types that interact with the existing Qt types, or to repurpose -QML for their own independent use. - -\tableofcontents - -\section1 Adding Types -\target adding-types - -\snippet examples/declarative/cppextensions/referenceexamples/adding/example.qml 0 - -The QML snippet shown above instantiates one \c Person instance and sets -the \c name and \c shoeSize properties on it. Everything in QML ultimately comes down -to either instantiating an object instance, or assigning a property a value. - -QML relies heavily on Qt's meta object system and can only instantiate classes -that derive from QObject. For visual element types, this will usually mean a subclass -of QDeclarativeItem; for models used with the view elements, a subclass of QAbstractItemModel; -and for arbitrary objects with properties, a direct subclass of QObject. - -The QML engine has no intrinsic knowledge of any class types. Instead the -programmer must register the C++ types with their corresponding QML names. - -Custom C++ types are registered using a template function: - -\quotation - -\code -template<typename T> -int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) -\endcode - -Calling qmlRegisterType() registers the C++ type \a T with the QML -system, and makes it available in QML under the name \a qmlName in -library \a uri version \a versionMajor.versionMinor. The \a qmlName -can be the same as the C++ type name. - -Type \a T must be a concrete type that inherits QObject and has a default -constructor. - -\endquotation - -#include <QtDeclarative> to use qmlRegisterType(). - -Types can be registered by libraries, application code, or by plugins -(see QDeclarativeExtensionPlugin). - -Once registered, all \l {Qt's Property System}{properties} of the -supported types are available in QML. QML has intrinsic support for -properties of the types listed in the \l{QML Basic Types} -document, which includes the following: - -\list -\o bool, unsigned int, int, float, double, qreal -\o QString, QUrl, QColor -\o QDate, QTime, QDateTime -\o QPoint, QPointF, QSize, QSizeF, QRect, QRectF -\o QVariant -\endlist - -When a property of a supported type is added to a C++ class, in a QML -element based on the C++ class, a \i{value-changed} signal handler -will be available. See \l{Signal Support} below. - -QML is typesafe. Attempting to assign an invalid value to a property -will generate an error. For example, assuming the \i{name} property -of the \c Person element had a type of QString, this would cause an -error: - -\code -Person { - // Will NOT work - name: 12 -} -\endcode - -\l {Extending QML - Adding Types Example} shows the complete code used to create -the \c Person type. - -If you wish to provide functionality to clients without requiring them to -instantiate an element, consider providing a module API instead of registering -a type; see qmlRegisterModuleApi() for more information. - -\section1 QML Type Versioning - -In C++ adding a new class, method or property cannot break old applications. -In QML, however, new elements, methods and properties can change what a name previously -resolved to to within a scope chain. - -For example, consider these two QML files - -\code -// main.qml -import QtQuick 1.0 -Item { - id: root - MyComponent {} -} -\endcode - -\code -// MyComponent.qml -import MyModule 1.0 -CppElement { - value: root.x -} -\endcode - -where CppElement maps to the C++ class QCppElement. - -If the author of QCppElement adds a "root" property to QCppElement in a new version of the module, -it will break the above program as \c root.x now resolves to a different value. -The solution is to allow the author of QCppElement to state that the new \c root property is -only available from a particular version of QCppElement onwards. This permits new properties -and features to be added to existing elements without breaking existing programs. - -QML enables this by allowing the properties, methods and signals of a class to be tagged with -a particular \i revision, so that they are only accessible if the relevant module version -is imported. In this case, the author can tag the \c root property as being added in -\i {revision 1} of the class, and register that revision in version 1.1 of the module. - -The REVISION tag is used to mark the \c root property as added in revision 1 of the class. -Methods such as Q_INVOKABLE's, signals and slots can also be tagged for a -revision using the \c Q_REVISION(x) macro: - -\code -class CppElement : public BaseObject -{ - Q_OBJECT - Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION 1) - -signals: - Q_REVISION(1) void rootChanged(); -}; -\endcode - -To register the new class revision to a particular version the following function is used: - -\code -template<typename T, int metaObjectRevision> -int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) -\endcode - -To register \c CppElement version 1 for \c {MyModule 1.1}: - -\code -qmlRegisterType<QCppElement,1>("MyModule", 1, 1, "CppElement") -\endcode - -\c root is only available when MyModule 1.1 is imported. - -For the same reason, new elements introduced in later versions should use the minor version argument of qmlRegisterType. - -This feature of the language allows for behavioural changes to be made without breaking existing applications. Consequently QML module authors should always remember to document what changed between minor versions, and QML module users should check that their application still runs correctly before deploying an updated import statement. - -You may also register the revision of a base class that your module depends upon -using the qmlRegisterRevision() function: - -\code -template<typename T, int metaObjectRevision> -int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) -\endcode - -For example, if \c BaseObject is changed and now has a revision 1, you can specify that -your module uses the new revision: - -\code -qmlRegisterRevision<BaseObject,1>("MyModule", 1, 1); -\endcode - -This is useful when deriving from base classes not declared as part of your module, e.g. -when extending classes from the QtQuick library. - - -\section1 Object and List Property Types - -\snippet examples/declarative/cppextensions/referenceexamples/properties/example.qml 0 - -The QML snippet shown above assigns a \c Person object to the \c BirthdayParty's -\c host property, and assigns three \c Person objects to the guests property. - -QML can set properties of types that are more complex than basic intrinsics like -integers and strings. Properties can also be object pointers, Qt interface -pointers, lists of object pointers, and lists of Qt interface pointers. As QML -is typesafe it ensures that only valid types are assigned to these properties, -just like it does for primitive types. - -Properties that are pointers to objects or Qt interfaces are declared with the -Q_PROPERTY() macro, just like other properties. The \c host property -declaration looks like this: - -\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1 - -As long as the property type, in this case \c Person, is registered with QML the -property can be assigned. - -QML also supports assigning Qt interfaces. To assign to a property whose type -is a Qt interface pointer, the interface must also be registered with QML. As -they cannot be instantiated directly, registering a Qt interface is different -from registering a new QML type. The following function is used instead: - -\quotation -\code -template<typename T> -int qmlRegisterInterface(const char *typeName) -\endcode - -This registers the C++ interface \a T with the QML system as \a typeName. - -Following registration, QML can coerce objects that implement this interface -for assignment to appropriately typed properties. -\endquotation - -The \c guests property is a list of \c Person objects. Properties that are lists -of objects or Qt interfaces are also declared with the Q_PROPERTY() macro, just -like other properties. List properties must have the type \c {QDeclarativeListProperty<T>}. -As with object properties, the type \a T must be registered with QML. - -The \c guest property declaration looks like this: - -\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 2 - -\l {Extending QML - Object and List Property Types Example} shows the complete -code used to create the \c BirthdayParty type. - -\section1 Sequence Types - -Certain C++ sequence types are supported transparently in QML as JavaScript Array types. -In particular, QML currently supports: -\list - \o \c {QList<int>} - \o \c {QList<qreal>} - \o \c {QList<bool>} - \o \c {QList<QString>} and \c{QStringList} - \o \c {QList<QUrl>} -\endlist - -These sequence types are implemented directly in terms of the underlying C++ sequence. -There are two ways in which such sequences can be exposed to QML: as a Q_PROPERTY of -the given sequence type; or as the return type of a Q_INVOKABLE method. There are some -differences in the way these are implemented, which are important to note. - -If the sequence is exposed as a Q_PROPERTY, accessing any value in the sequence by index -will cause the sequence data to be read from the QObject's property, then a read to occur. -Similarly, modifying any value in the sequence will cause the sequence data to be read, -and then the modification will be performed and the modified sequence will be written back -to the QObject's property. - -If the sequence is returned from a Q_INVOKABLE function, access and mutation is much cheaper, -as no QObject property read or write occurs; instead, the C++ sequence data is accessed and -modified directly. - -Other sequence types are not supported transparently, and instead an instance of any other -sequence type will be passed between QML and C++ as an opaque QVariantList. - -\bold {Important Note:} There are some minor differences between the semantics of such -sequence Array types and default JavaScript Array types which result from the use of a -C++ storage type in the implementation. In particular, deleting an element from an Array -will result in a default-constructed value replacing that element, rather than an -Undefined value. Similarly, setting the length property of the Array to a value larger -than its current value will result in the Array being padded out to the specified length -with default-constructed elements rather than Undefined elements. - -The default-constructed values for each sequence type are as follows: -\table -\row \o QList<int> \o integer value 0 -\row \o QList<qreal> \o real value 0.0 -\row \o QList<bool> \o boolean value \c {false} -\row \o QList<QString> and QStringList \o empty QString -\row \o QList<QUrl> \o empty QUrl -\endtable - -If you wish to remove elements from a sequence rather than simply replace them with default -constructed values, do not use the indexed delete operator ("delete sequence[i]") but instead -use the \c {splice} function ("sequence.splice(startIndex, deleteCount)"). - -\section1 Inheritance and Coercion - -\snippet examples/declarative/cppextensions/referenceexamples/coercion/example.qml 0 - -The QML snippet shown above assigns a \c Boy object to the \c BirthdayParty's -\c host property, and assigns three other objects to the \c guests property. - -QML supports C++ inheritance hierarchies and can freely coerce between known, -valid object types. This enables the creation of common base classes that allow -the assignment of specialized classes to object or list properties. In the -snippet shown, both the \c host and the \c guests properties retain the \c Person -type used in the previous section, but the assignment is valid as both the \c Boy -and \c Girl objects inherit from \c Person. - -To assign to a property, the property's type must have been registered with QML. -Both the qmlRegisterType() and qmlRegisterInterface() template functions already -shown can be used to register a type with QML. Additionally, if a type that acts purely -as a base class that cannot be instantiated from QML needs to be -registered, the following function can be used: - -\quotation -\code - template<typename T> - int qmlRegisterType() -\endcode - -This registers the C++ type \a T with the QML system. The parameterless call to the template -function qmlRegisterType() does not define a mapping between the -C++ class and a QML element name, so the type is not instantiable from QML, but -it is available for type coercion. - -Type \a T must inherit QObject, but there are no restrictions on whether it is -concrete or the signature of its constructor. -\endquotation - -QML will automatically coerce C++ types when assigning to either an object -property, or to a list property. Only if coercion fails does an assignment -error occur. - -\l {Extending QML - Inheritance and Coercion Example} shows the complete -code used to create the \c Boy and \c Girl types. - -\section1 Default Property - -\snippet examples/declarative/cppextensions/referenceexamples/default/example.qml 0 - -The QML snippet shown above assigns a collection of objects to the -\c BirthdayParty's default property. - -The \i {default property} is a syntactic convenience that allows a type designer to -specify a single property as the type's default. The default property is -assigned to whenever no explicit property is specified. As a convenience, it is -behaviorally identical to assigning to the default property explicitly by name. - -From C++, type designers mark the default property using a Q_CLASSINFO() -annotation: - -\quotation -\code -Q_CLASSINFO("DefaultProperty", "property") -\endcode - -This marks \a property as the class's default property. \a property must be either -an object property, or a list property. - -A default property is optional. A derived class inherits its base class's -default property, but may override it in its own declaration. \a property can -refer to a property declared in the class itself, or a property inherited from a -base class. -\endquotation - -\l {Extending QML - Default Property Example} shows the complete code used to -specify a default property. - -\section1 Grouped Properties - -\snippet examples/declarative/cppextensions/referenceexamples/grouped/example.qml 1 - -The QML snippet shown above assigns a number of properties to the \c Boy object, -including four properties using the grouped property syntax. - -Grouped properties collect similar properties together into a single named -block. Grouped properties can be used to present a nicer API to developers, and -may also simplify the implementation of common property collections across -different types through implementation reuse. - -A grouped property block is implemented as a read-only object property. The -\c shoe property shown is declared like this: - -\snippet examples/declarative/cppextensions/referenceexamples/grouped/person.h 1 - -The \c ShoeDescription type declares the properties available to the grouped -property block - in this case the \c size, \c color, \c brand and \c price properties. - -Grouped property blocks may declared and accessed be recusively. - -\l {Extending QML - Grouped Properties Example} shows the complete code used to -implement the \c shoe property grouping. - -\section1 Attached Properties - -\snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml 1 - -The QML snippet shown above assigns a date to the \c rsvp property using the attached -property syntax. - -Attached properties allow unrelated types to annotate other types with some -additional properties, generally for their own use. Attached properties are -identified through the use of the attacher type name, in the case shown -\c BirthdayParty, as a prefix to the property name. - -In the example shown, \c BirthdayParty is called the attaching type, and the -\c Boy instance the attachee object instance. - -For the attaching type, an attached property block is implemented as a new -QObject derived type, called the attachment object. The properties on the -attachment object are those that become available for use as the attached -property block. - -Any QML type can become an attaching type by declaring the -\c qmlAttachedProperties() public function and declaring that the class has -QML_HAS_ATTACHED_PROPERTIES: - -\quotation -\code -class MyType : public QObject { - Q_OBJECT -public: - - ... - - static AttachedPropertiesType *qmlAttachedProperties(QObject *object); -}; - -QML_DECLARE_TYPEINFO(MyType, QML_HAS_ATTACHED_PROPERTIES) -\endcode -This returns an attachment object, of type \a AttachedPropertiesType, for the -attachee \a object instance. It is customary, though not strictly required, for -the attachment object to be parented to \a object to prevent memory leaks. - -\a AttachedPropertiesType must be a QObject derived type. The properties on -this type will be accessible through the attached properties syntax. - -This method will be called at most once for each attachee object instance. The -QML engine will cache the returned instance pointer for subsequent attached -property accesses. Consequently the attachment object may not be deleted until -\a object is destroyed. -\endquotation - -Conceptually, attached properties are a \i type exporting a set of additional -properties that can be set on \i any other object instance. Attached properties -cannot be limited to only attaching to a sub-set of object instances, although -their effect may be so limited. - -For example, a common usage scenario is for a type to enhance the properties -available to its children in order to gather instance specific data. Here we -add a \c rsvp field to all the guests coming to a birthday party: -\code -BirthdayParty { - Boy { BirthdayParty.rsvp: "2009-06-01" } -} -\endcode -However, as a type cannot limit the instances to which the attachment object -must attach, the following is also allowed, even though adding a birthday party -rsvp in this context will have no effect. -\code -GraduationParty { - Boy { BirthdayParty.rsvp: "2009-06-01" } -} -\endcode - -From C++, including the attaching type implementation, the attachment object for -an instance can be accessed using the following method: - -\quotation -\code -template<typename T> -QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true); -\endcode -This returns the attachment object attached to \a attachee by the attaching type -\a T. If type \a T is not a valid attaching type, this method always returns 0. - -If \a create is true, a valid attachment object will always be returned, -creating it if it does not already exist. If \a create is false, the attachment -object will only be returned if it has previously been created. -\endquotation - -\l {Extending QML - Attached Properties Example} shows the complete code used to -implement the rsvp attached property. - -\section1 Memory Management and QVariant types - -It is an element's responsibility to ensure that it does not access or return -pointers to invalid objects. QML makes the following guarentees: - -\list -\o An object assigned to a QObject (or QObject-derived) pointer property will be -valid at the time of assignment. - -Following assignment, it is the responsibility of the class to subsequently guard -this pointer, either through a class specific method or the generic QPointer class. - -\o An object assigned to a QVariant will be valid at the time of assignment. - -When assigning an object to a QVariant property, QML will always use a QMetaType::QObjectStar -typed QVariant. It is the responsibility of the class to guard the pointer. A -general rule when writing a class that uses QVariant properties is to check the -type of the QVariant when it is set and if the type is not handled by your class, -reset it to an invalid variant. - -\o An object assigned to a QObject (or QObject-derived) list property will be -valid at the time of assignment. - -Following assignment, it is the responsibility of the class to subsequently guard -this pointer, either through a class specific method or the generic QPointer class. -\endlist - -Elements should assume that any QML assigned object can be deleted at any time, and -respond accordingly. If documented as such an element need not continue to work in -this situation, but it must not crash. - -\section1 Signal Support - -\snippet examples/declarative/cppextensions/referenceexamples/signal/example.qml 0 -\snippet examples/declarative/cppextensions/referenceexamples/signal/example.qml 1 - -The QML snippet shown above associates the evaluation of a JavaScript expression -with the emission of a Qt signal. - -All Qt signals on a registered class become available as special "signal -properties" within QML to which the user can assign a single JavaScript -expression. The signal property's name is a transformed version of the Qt -signal name: "on" is prepended, and the first letter of the signal name upper -cased. For example, the signal used in the example above has the following -C++ signature: - -\snippet examples/declarative/cppextensions/referenceexamples/signal/birthdayparty.h 0 - -In classes with multiple signals with the same name, only the final signal -is accessible as a signal property. Note that signals with the same name -but different parameters cannot be distinguished. - -Signal parameters become accessible by name to the assigned script. An -unnamed parameter cannot be accessed, so care should be taken to name all the -signal parameters in the C++ class declaration. The intrinsic types -listed in \l{Adding Types}, as well registered object types are permitted as -signal parameter types. Using other types is not an error, but the parameter -value will not be accessible from script. - -\l {Extending QML - Signal Support Example} shows the complete code used to -implement the onPartyStarted signal property. - -If you want to use signals from objects not created in QML, you can access their -signals with the \l {Connections} element. - -Additionally, if a property is added to a C++ class, all QML elements -based on that C++ class will have a \i{value-changed} signal handler -for that property. The name of the signal handler is -\i{on<Property-name>Changed}, with the first letter of the property -name being upper case. - -\note The QML signal handler will always be named -on<Property-name>Changed, regardless of the name used for the NOTIFY -signal in C++. We recommend using <property-name>Changed() for the -NOTIFY signal in C++. - -See also \l {Importing Reusable Components} - -\section1 Methods - -Slots and methods marked Q_INVOKABLE may be called as functions in QML. - -\snippet examples/declarative/cppextensions/referenceexamples/methods/example.qml 0 - -In this example an invitation is added via an \c {invite()} invokable method of -the BirthdayParty element. This function is available in QML by marking the \c {invite()} -method with Q_INVOKABLE in the BirthdayParty class: - -\snippet examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.h 0 - -\l {Extending QML - Methods Example} shows the complete code used to -implement the invite() method. - -The \c {invite()} method is similarly available if it is declared as a slot. - -\section1 Property Value Sources - -\snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 0 -\snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 1 - -The QML snippet shown above applies a property value source to the \c announcement property. -A property value source generates a value for a property that changes over time. - -Property value sources are most commonly used to do animation. Rather than -constructing an animation object and manually setting the animation's "target" -property, a property value source can be assigned directly to a property of any -type and automatically set up this association. - -The example shown here is rather contrived: the \c announcement property of the -\c BirthdayParty object is a string that is printed every time it is assigned and -the \c HappyBirthdaySong value source generates the lyrics of the song -"Happy Birthday". - -\snippet examples/declarative/cppextensions/referenceexamples/valuesource/birthdayparty.h 0 - -Normally, assigning an object to a string property would not be allowed. In -the case of a property value source, rather than assigning the object instance -itself, the QML engine sets up an association between the value source and -the property. - -Property value sources are special types that derive from the -QDeclarativePropertyValueSource base class. This base class contains a single method, -QDeclarativePropertyValueSource::setTarget(), that the QML engine invokes when -associating the property value source with a property. The relevant part of -the \c HappyBirthdaySong type declaration looks like this: - -\snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 0 -\snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 1 -\snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 2 - -In all other respects, property value sources are regular QML types. They must -be registered with the QML engine using the same macros as other types, and can -contain properties, signals and methods just like other types. - -When a property value source object is assigned to a property, QML first tries -to assign it normally, as though it were a regular QML type. Only if this -assignment fails does the engine call the \l {QDeclarativePropertyValueSource::}{setTarget()} method. This allows -the type to also be used in contexts other than just as a value source. - -\l {Extending QML - Property Value Source Example} shows the complete code used -to implement the \c HappyBirthdaySong property value source. - -\section1 Property Binding - -\snippet examples/declarative/cppextensions/referenceexamples/binding/example.qml 0 -\snippet examples/declarative/cppextensions/referenceexamples/binding/example.qml 1 - -The QML snippet shown above uses a property binding to ensure the -\c HappyBirthdaySong's \c name property remains up to date with the \c host. - -Property binding is a core feature of QML. In addition to assigning literal -values, property bindings allow the developer to assign an arbitrarily complex -JavaScript expression that may include dependencies on other property values. -Whenever the expression's result changes - through a change in one of its -constituent values - the expression is automatically reevaluated and -the new result assigned to the property. - -All properties on custom types automatically support property binding. However, -for binding to work correctly, QML must be able to reliably determine when a -property has changed so that it knows to reevaluate any bindings that depend on -the property's value. QML relies on the presence of a -\l {Qt's Property System}{NOTIFY signal} for this determination. - -Here is the \c host property declaration: - -\snippet examples/declarative/cppextensions/referenceexamples/binding/birthdayparty.h 0 - -The NOTIFY attribute is followed by a signal name. It is the responsibility of -the class implementer to ensure that whenever the property's value changes, the -NOTIFY signal is emitted. The signature of the NOTIFY signal is not important to QML. - -To prevent loops or excessive evaluation, developers should ensure that the -signal is only emitted whenever the property's value is actually changed. If -a property, or group of properties, is infrequently used it is permitted to use -the same NOTIFY signal for several properties. This should be done with care to -ensure that performance doesn't suffer. - -To keep QML reliable, if a property does not have a NOTIFY signal, it cannot be -used in a binding expression. However, the property can still be assigned -a binding as QML does not need to monitor the property for change in that -scenario. - -Consider a custom type, \c TestElement, that has two properties, "a" and "b". -Property "a" does not have a NOTIFY signal, and property "b" does have a NOTIFY -signal. - -\code -TestElement { - // This is OK - a: b -} -TestElement { - // Will NOT work - b: a -} -\endcode - -The presence of a NOTIFY signal does incur a small overhead. There are cases -where a property's value is set at object construction time, and does not -subsequently change. The most common case of this is when a type uses -\l {Grouped Properties}, and the grouped property object is allocated once, and -only freed when the object is deleted. In these cases, the CONSTANT attribute -may be added to the property declaration instead of a NOTIFY signal. - -\snippet examples/declarative/cppextensions/referenceexamples/binding/person.h 0 - -Extreme care must be taken here or applications using your type may misbehave. -The CONSTANT attribute should only be used for properties whose value is set, -and finalized, only in the class constructor. All other properties that want -to be used in bindings should have a NOTIFY signal instead. - -\l {Extending QML - Binding Example} shows the BirthdayParty example updated to -include NOTIFY signals for use in binding. - -\section1 Extension Objects - -\snippet examples/declarative/cppextensions/referenceexamples/extended/example.qml 0 - -The QML snippet shown above adds a new property to an existing C++ type without -modifying its source code. - -When integrating existing classes and technology into QML, their APIs will often -need to be tweaked to fit better into the declarative environment. Although -the best results are usually obtained by modifying the original classes -directly, if this is either not possible or is complicated by some other -concerns, extension objects allow limited extension possibilities without -direct modifications. - -Extension objects are used to add additional properties to an existing type. -Extension objects can only add properties, not signals or methods. An extended -type definition allows the programmer to supply an additional type - known as the -extension type - when registering the target class whose properties are -transparently merged with the original target class when used from within QML. - -An extension class is a regular QObject, with a constructor that takes a QObject -pointer. When needed (extension class creation is delayed until the first extended -property is accessed) the extension class is created and the target object is -passed in as the parent. When an extended property on the original is accessed, -the appropriate property on the extension object is used instead. - -When an extended type is installed, one of the -\code -template<typename T, typename ExtendedT> -int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) - -template<typename T, typename ExtendedT> -int qmlRegisterExtendedType() -\endcode -functions should be used instead of the regular \c qmlRegisterType() variations. -The arguments are identical to the corresponding non-extension registration functions, -except for the ExtendedT parameter which is the type -of the extension object. - -\section1 Optimization - -Often to develop high performance elements it is helpful to know more about the -status of the QML engine. For example, it might be beneficial to delay -initializing some costly data structures until after all the properties have been -set. - -The QML engine defines an interface class called QDeclarativeParserStatus, which contains a -number of virtual methods that are invoked at various stages during component -instantiation. To receive these notifications, an element implementation inherits -QDeclarativeParserStatus and notifies the Qt meta system using the Q_INTERFACES() macro. - -For example, - -\code -class Example : public QObject, public QDeclarativeParserStatus -{ - Q_OBJECT - Q_INTERFACES(QDeclarativeParserStatus) -public: - virtual void componentComplete() - { - qDebug() << "Woohoo! Now to do my costly initialization"; - } -}; -\endcode -*/ diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc deleted file mode 100644 index 47687022b1..0000000000 --- a/doc/src/declarative/globalobject.qdoc +++ /dev/null @@ -1,126 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativeglobalobject.html -\inqmlmodule QtQuick 2 -\title QML Global Object - -Contains all the properties of the JavaScript global object, plus: - -\tableofcontents - -\section1 Qt Object - -The \l{QmlGlobalQtObject}{Qt object} provides useful enums and functions from Qt, for use in all QML -files. - -\section1 XMLHttpRequest - -\target XMLHttpRequest - -QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain -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 -\o QML's XMLHttpRequest does not enforce the same origin policy. -\o QML's XMLHttpRequest does not support \i synchronous requests. -\endlist - -Additionally, the \c responseXML XML DOM tree currently supported by QML is a reduced subset -of the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web -browser. The following objects and properties are supported by the QML implementation: - -\table -\header -\o \bold {Node} -\o \bold {Document} -\o \bold {Element} -\o \bold {Attr} -\o \bold {CharacterData} -\o \bold {Text} - -\row -\o -\list -\o nodeName -\o nodeValue -\o nodeType -\o parentNode -\o childNodes -\o firstChild -\o lastChild -\o previousSibling -\o nextSibling -\o attributes -\endlist - -\o -\list -\o xmlVersion -\o xmlEncoding -\o xmlStandalone -\o documentElement -\endlist - -\o -\list -\o tagName -\endlist - -\o -\list -\o name -\o value -\o ownerElement -\endlist - -\o -\list -\o data -\o length -\endlist - -\o -\list -\o isElementContentWhitespace -\o wholeText -\endlist - -\endtable - -The \l{declarative/xml/xmlhttprequest}{XMLHttpRequest example} demonstrates how to -use the XMLHttpRequest object to make a request and read the response headers. - -\section1 Logging - -\c console.log(), \c console.debug(), \c console.time(), and \c console.timeEnd() can be used to print information -to the console. See \l{Debugging QML} for more information. - -*/ diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc deleted file mode 100644 index 992c000fc0..0000000000 --- a/doc/src/declarative/qdeclarativedocument.qdoc +++ /dev/null @@ -1,144 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativedocuments.html -\inqmlmodule QtQuick 2 -\title QML Documents -\brief A description of QML documents and the kind of content they contain. - -A QML document is a block of QML source code. QML documents generally correspond to files -stored on a disk or at a location on a network, but they can also be constructed directly -from text data. - -Here is a simple QML document: - -\snippet doc/src/snippets/declarative/qml-documents/non-trivial.qml document - -QML documents are always encoded in UTF-8 format. - -A QML document always begins with one or more import statements. To prevent elements -introduced in later versions from affecting existing QML programs, the element types -available within a document are controlled by the imported QML \l {Modules}. That is, -QML is a \i versioned language. - -Syntactically a QML document is self contained; QML does \i not have a preprocessor that -modifies the document prior to presentation to the QML runtime. \c import statements -do not "include" code in the document, but instead instruct the QML runtime on how to -resolve type references found in the document. Any type reference present in a QML -document - such as \c Rectangle and \c ListView - including those made within an -\l {Inline JavaScript}{JavaScript block} or \l {Property Binding}s, are \i resolved based exclusively on the -import statements. QML does not import any modules by default, so at least one \c import -statement must be present or no elements will be available! - -Each \c id value in a QML document must be unique within that document. They -do not need to be unique across different documents as id values are -resolved according to the document scope. - - -\section1 Documents as Component Definitions - -A QML document defines a single, top-level \l {QDeclarativeComponent}{QML component}. A QML component -is a template that is interpreted by the QML runtime to create an object with some predefined -behaviour. As it is a template, a single QML component can be "run" multiple times to -produce several objects, each of which are said to be \i instances of the component. - -Once created, instances are not dependent on the component that created them, so they can -operate on independent data. Here is an example of a simple "Button" component (defined -in a \c Button.qml file) that is instantiated four times by \c application.qml. -Each instance is created with a different value for its \c text property: - -\table -\row -\o Button.qml -\o application.qml - -\row -\o \snippet doc/src/snippets/declarative/qml-documents/qmldocuments.qml document -\o -\qml -import QtQuick 1.0 - -Column { - spacing: 10 - - Button { text: "Apple" } - Button { text: "Orange" } - Button { text: "Pear" } - Button { text: "Grape" } -} -\endqml - -\image anatomy-component.png - -\endtable - -Any snippet of QML code can become a component, just by placing it in the file "<Name>.qml" -where <Name> is the new element name, and begins with an \bold uppercase letter. Note that -the case of all characters in the <Name> are significant on some filesystems, notably -UNIX filesystems. It is recommended that the case of the filename matches the case of -the component name in QML exactly, regardless of the platform the QML will be deployed to. - -These QML component files automatically become available as new QML element types -to other QML components and applications in the same directory. - - - -\section1 Inline Components - -In addition to the top-level component that all QML documents define, and any reusable -components placed in separate files, documents may also -include \i inline components. Inline components are declared using the -\l Component element, as can be seen in the first example above. Inline components share -all the characteristics of regular top-level components and use the same \c import list as their -containing QML document. Components are one of the most basic building blocks in QML, and are -frequently used as "factories" by other elements. For example, the \l ListView element uses the -\c delegate component as the template for instantiating list items - each list item is just a -new instance of the component with the item specific data set appropriately. - -Like other \l {QML Elements}, the \l Component element is an object and must be assigned to a -property. \l Component objects may also have an object id. In the first example on this page, -the inline component is added to the \l Rectangle's \c resources list, and then -\l {Property Binding} is used to assign the \l Component to the \l ListView's \c delegate -property. While using property binding allows the \l Component object to be shared (for example, -if the QML document contained multiple \l ListView's with the same delegate), in this case the -\l Component could have been assigned directly to the \l ListView's \c delegate. The QML -language even contains a syntactic optimization when assigning directly to a component property -for this case where it will automatically insert the \l Component tag. - -These final two examples are behaviorally identical to the original document. - -\table -\row -\o -\snippet doc/src/snippets/declarative/qml-documents/inline-component.qml document -\o -\snippet doc/src/snippets/declarative/qml-documents/inline-text-component.qml document -\endtable - -\sa QDeclarativeComponent -*/ diff --git a/doc/src/declarative/qdeclarativeintro.qdoc b/doc/src/declarative/qdeclarativeintro.qdoc deleted file mode 100644 index 5de82eedfc..0000000000 --- a/doc/src/declarative/qdeclarativeintro.qdoc +++ /dev/null @@ -1,405 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativeintroduction.html -\inqmlmodule QtQuick 2 -\title Introduction to the QML Language - -\tableofcontents - -QML is a declarative language designed to describe the user interface of a -program: both what it looks like, and how it behaves. In QML, a user -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 (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. - -\section1 Basic QML Syntax - -QML looks like this: - -\qml -import QtQuick 1.0 - -Rectangle { - width: 200 - height: 200 - color: "blue" - - Image { - source: "pics/logo.png" - anchors.centerIn: parent - } -} -\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 -braces in between which additional data can be defined for the object, such as -its property values and any child objects. - -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: - -\qml -Rectangle { - width: 100 - height: 100 -} -\endqml - -or you can put multiple properties on a single line: - -\qml -Rectangle { width: 100; height: 100 } -\endqml - -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 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 Comments - -Commenting in QML is similar to JavaScript. -\list -\o Single line comments start with // and finish at the end of the line. -\o Multiline comments start with /* and finish with *\/ -\endlist - -\snippet doc/src/snippets/declarative/comments.qml 0 - -Comments are ignored by the engine. They are useful for explaining what you -are doing; for referring back to at a later date, or for others reading -your QML files. - -Comments can also be used to prevent the execution of code, which is -sometimes useful for tracking down problems. - -\qml -Text { - text: "Hello world!" - //opacity: 0.5 -} -\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 - -Each object can be given a special \i 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: - -\qml -Item { - width: 100 * 3 - height: 50 + 22 -} -\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: - -\qml -Item { - width: 300 - height: 300 - - Rectangle { - width: parent.width - 50 - height: 100 - color: "yellow" - } -} -\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 -automatically updated. - - - -\section1 Properties -\target intro-properties - -\section2 Basic Property Types - -QML supports properties of many types (see \l{QML Basic Types}). The basic types include \c int, -\c real, \c bool, \c string and \c color. - -\qml -Item { - x: 10.5 // a 'real' property - state: "details" // a 'string' property - focus: true // a 'bool' property - // ... -} -\endqml - -QML properties are what is known as \i 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 -a string to it you will get an error. - -\badcode -Item { - x: "hello" // illegal! -} -\endcode - -Note that with the exception of \l {Attached Properties}, properties always begin with a lowercase -letter. - - -\section2 Property Change Notifications - -When a property changes value, it can send a signal to notify others of this change. - -To receive these signals, simply create a \i {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) -} -\endqml - -Signal handlers are explained further \l {Signal Handlers}{below}. - - -\section2 List properties - -List properties look like this: - -\qml -Item { - children: [ - Image {}, - Text {} - ] -} -\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: - -\qml -Image { - children: Rectangle {} -} -\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 - -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: -\qml -State { - changes: [ - PropertyChanges {}, - PropertyChanges {} - ] -} -\endqml - -can be simplified to: - -\qml -State { - PropertyChanges {} - PropertyChanges {} -} -\endqml - -because \c changes is the default property of the \c State type. - -\section2 Grouped Properties -\target dot properties - -In some cases properties form a logical group and use a 'dot' or grouped notation -to show this. - -Grouped properties can be written like this: -\qml -Text { - font.pixelSize: 12 - font.bold: true -} -\endqml - -or like this: -\qml -Text { - font { pixelSize: 12; bold: true } -} -\endqml - -In the element documentation grouped properties are shown using the 'dot' notation. - -While you can bind the entire group at once, like below, note that setting any of the -grouped properties will result in setting the group and thus invalidate the binding. -\qml -Text { - font: otherText.font -} -\endqml - -\section2 Attached Properties -\target attached-properties - -Some objects attach properties to another object. Attached Properties -are of the form \i {Type.property} where \i Type is the type of the -element that attaches \i property. - -For example, the \l ListView element attaches the \i ListView.isCurrentItem property -to each delegate it creates: - -\qml -Component { - id: myDelegate - Text { - text: "Hello" - color: ListView.isCurrentItem ? "red" : "blue" - } -} -\endqml - -\qml -ListView { - delegate: myDelegate -} -\endqml - -Another example of attached properties is the \l Keys element which -attaches properties for handling key presses to -any visual Item, for example: - -\qml -Item { - focus: true - Keys.onSelectPressed: console.log("Selected") -} -\endqml - -\section1 Signal Handlers - -Signal handlers allow JavaScript code to be executed in response to an event. For -example, the \l MouseArea element has an \l {MouseArea::}{onClicked} handler that can -be used to respond to a mouse click. Below, we use this handler to print a -message whenever the mouse is clicked: - -\qml -Item { - width: 100; height: 100 - - MouseArea { - anchors.fill: parent - onClicked: { - console.log("mouse button clicked") - } - } -} -\endqml - -All signal handlers begin with \i "on". - -Some signal handlers include an optional parameter. For example -the MouseArea \l{MouseArea::}{onPressed} signal handler has a \c mouse parameter -that contains information about the mouse press. This parameter can be referred to in -the JavaScript code, as below: - -\qml -MouseArea { - acceptedButtons: Qt.LeftButton | Qt.RightButton - onPressed: { - if (mouse.button == Qt.RightButton) - console.log("Right mouse button pressed") - } -} -\endqml -*/ diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc deleted file mode 100644 index fd0ae9325a..0000000000 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ /dev/null @@ -1,511 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativemodels.html -\inqmlmodule QtQuick 2 -\ingroup qml-features -\contentspage QML Features -\previouspage {QML Animation and Transitions}{Animation and Transitions} -\nextpage {Presenting Data with Views} -\target qmlmodels -\title QML Data Models - -QML items such as ListView, GridView and \l Repeater require Data Models -that provide the data to be displayed. -These items typically require a \i delegate component that -creates an instance for each item in the model. Models may be static, or -have items modified, inserted, removed or moved dynamically. - -Data is provided to the delegate via named data roles which the -delegate may bind to. Here is a ListModel with two roles, \i type and \i age, -and a ListView with a delegate that binds to these roles to display their -values: - -\snippet doc/src/snippets/declarative/qml-data-models/listmodel-listview.qml document - -If there is a naming clash between the model's properties and the delegate's -properties, the roles can be accessed with the qualified \i model name instead. -For example, if a \l Text element had \i type or \i age properties, the text in the -above example would display those property values instead of the \i type and \i age values -from the model item. In this case, the properties could have been referenced as -\c model.type and \c model.age instead to ensure the delegate displays the -property values from the model item. - -A special \i index role containing the index of the item in the model -is also available to the delegate. Note this index is set to -1 if the item is removed from -the model. If you bind to the index role, be sure that the logic -accounts for the possibility of index being -1, i.e. that the item -is no longer valid. (Usually the item will shortly be destroyed, but -it is possible to delay delegate destruction in some views via a \c delayRemove -attached property.) - -Models that do not have named roles (such as the QStringList model shown below) -will have the data provided via the \i modelData role. The \i modelData role is also provided for -models that have only one role. In this case the \i modelData role -contains the same data as the named role. - -QML provides several types of data models among the built-in set of -QML elements. In addition, models can be created with C++ and then -made available to QML components. - -The views used to access data models are described in the -\l{Presenting Data with Views} overview. -The use of positioner items to arrange items from a model is covered in -\l{Using QML Positioner and Repeater Items}. - - -\keyword qml-data-models -\section1 QML Data Models - -\section2 ListModel - -ListModel is a simple hierarchy of elements specified in QML. The -available roles are specified by the \l ListElement properties. - -\snippet doc/src/snippets/declarative/qml-data-models/listelements.qml model - -The above model has two roles, \i name and \i cost. These can be bound -to by a ListView delegate, for example: - -\snippet doc/src/snippets/declarative/qml-data-models/listelements.qml view - -ListModel provides methods to manipulate the ListModel directly via JavaScript. -In this case, the first item inserted determines the roles available -to any views that are using the model. For example, if an empty ListModel is -created and populated via JavaScript, the roles provided by the first -insertion are the only roles that will be shown in the view: - -\snippet doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml model -\dots -\snippet doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml mouse area - -When the MouseArea is clicked, \c fruitModel will have two roles, \i cost and \i name. -Even if subsequent roles are added, only the first two will be handled by views -using the model. To reset the roles available in the model, call ListModel::clear(). - - -\section2 XmlListModel - -XmlListModel allows construction of a model from an XML data source. The roles -are specified via the \l XmlRole element. - -Note: From QtQuick 2.0, XmlListModel has been move to a seperate module \l QtQuick.XmlListModel, -to use XmlListModel item, an additional "import QtQuick.XmlListModel 2.0" is needed. - -The following model has three roles, \i title, \i link and \i description: -\qml -import QtQuick.XmlListModel 2.0 -XmlListModel { - id: feedModel - source: "http://rss.news.yahoo.com/rss/oceania" - query: "/rss/channel/item" - XmlRole { name: "title"; query: "title/string()" } - XmlRole { name: "link"; query: "link/string()" } - XmlRole { name: "description"; query: "description/string()" } -} -\endqml - -The \l{declarative/rssnews}{RSS News demo} shows how XmlListModel can -be used to display an RSS feed. - - -\section2 VisualItemModel - -VisualItemModel allows QML items to be provided as a model. - -This model contains both the data and delegate; the child items of a -VisualItemModel provide the contents of the delegate. The model -does not provide any roles. - -\snippet doc/src/snippets/declarative/models/visual-model-and-view.qml visual model and view - -Note that in the above example there is no delegate required. -The items of the model itself provide the visual elements that -will be positioned by the view. - -\keyword qml-c++-models -\section1 C++ Data Models - -Models can be defined in C++ and then made available to QML. This is useful -for exposing existing C++ data models or otherwise complex datasets to QML. - -A C++ model class can be defined as a QStringList, a QList<QObject*> or a -QAbstractItemModel. The first two are useful for exposing simpler datasets, -while QAbstractItemModel provides a more flexible solution for more complex -models. - - -\section2 QStringList-based model - -A model may be a simple QStringList, which provides the contents of the list via the \i modelData role. - -Here is a ListView with a delegate that references its model item's -value using the \c modelData role: - -\snippet examples/declarative/modelviews/stringlistmodel/view.qml 0 - -A Qt application can load this QML document and set the value of \c myModel -to a QStringList: - -\snippet examples/declarative/modelviews/stringlistmodel/main.cpp 0 - -The complete example is available in Qt's \l {declarative/modelviews/stringlistmodel}{examples/declarative/modelviews/stringlistmodel} directory. - -\note There is no way for the view to know that the contents of a QStringList -have changed. If the QStringList changes, it will be necessary to reset -the model by calling QDeclarativeContext::setContextProperty() again. - - -\section2 QObjectList-based model - -A list of QObject* values can also be used as a model. A QList<QObject*> provides -the properties of the objects in the list as roles. - -The following application creates a \c DataObject class that with -Q_PROPERTY values that will be accessible as named roles when a -QList<DataObject*> is exposed to QML: - -\snippet examples/declarative/modelviews/objectlistmodel/dataobject.h 0 -\dots 4 -\snippet examples/declarative/modelviews/objectlistmodel/dataobject.h 1 -\codeline -\snippet examples/declarative/modelviews/objectlistmodel/main.cpp 0 -\dots - -The QObject* is available as the \c modelData property. As a convenience, -the properties of the object are also made available directly in the -delegate's context. Here, \c view.qml references the \c DataModel properties in -the ListView delegate: - -\snippet examples/declarative/modelviews/objectlistmodel/view.qml 0 - -Note the use of the fully qualified access to the \c color property. -The properties of the object are not replicated in the \c model -object, since they are easily available via the \c modelData -object. - -The complete example is available in Qt's \l {declarative/modelviews/objectlistmodel}{examples/declarative/modelviews/objectlistmodel} directory. - -Note: There is no way for the view to know that the contents of a QList -have changed. If the QList changes, it will be necessary to reset -the model by calling QDeclarativeContext::setContextProperty() again. - - -\section2 QAbstractItemModel - -A model can be defined by subclassing QAbstractItemModel. This is the -best approach if you have a more complex model that cannot be supported -by the other approaches. A QAbstractItemModel can also automatically -notify a QML view when the model data has changed. - -The roles of a QAbstractItemModel subclass can be exposed to QML by calling -QAbstractItemModel::setRoleNames(). The default role names set by Qt are: - -\table -\header -\o Qt Role -\o QML Role Name -\row -\o Qt::DisplayRole -\o display -\row -\o Qt::DecorationRole -\o decoration -\endtable - -Here is an application with a QAbstractListModel subclass named \c AnimalModel -that has \i type and \i size roles. It calls QAbstractItemModel::setRoleNames() to set the -role names for accessing the properties via QML: - -\snippet examples/declarative/modelviews/abstractitemmodel/model.h 0 -\dots -\snippet examples/declarative/modelviews/abstractitemmodel/model.h 1 -\dots -\snippet examples/declarative/modelviews/abstractitemmodel/model.h 2 -\codeline -\snippet examples/declarative/modelviews/abstractitemmodel/model.cpp 0 -\codeline -\snippet examples/declarative/modelviews/abstractitemmodel/main.cpp 0 -\dots - -This model is displayed by a ListView delegate that accesses the \i type and \i size -roles: - -\snippet examples/declarative/modelviews/abstractitemmodel/view.qml 0 - -QML views are automatically updated when the model changes. Remember the model -must follow the standard rules for model changes and notify the view when -the model has changed by using QAbstractItemModel::dataChanged(), -QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for -more information. - -The complete example is available in Qt's \l {declarative/modelviews/abstractitemmodel}{examples/declarative/modelviews/abstractitemmodel} directory. - -QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML -can only display list data. -In order to display child lists of a hierarchical model -the VisualDataModel element provides several properties and functions for use -with models of type QAbstractItemModel: - -\list -\o \i hasModelChildren role property to determine whether a node has child nodes. -\o \l VisualDataModel::rootIndex allows the root node to be specifed -\o \l VisualDataModel::modelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex -\o \l VisualDataModel::parentModelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex -\endlist - - -\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 -register the C++ model class as a QML type from a QML C++ plugin using -QDeclarativeExtensionPlugin. This would allow the model classes to be -created directly as elements within QML: - -\table -\row - -\o -\code -class MyModelPlugin : public QDeclarativeExtensionPlugin -{ -public: - void registerTypes(const char *uri) - { - qmlRegisterType<MyModel>(uri, 1, 0, - "MyModel"); - } -} - -Q_EXPORT_PLUGIN2(mymodelplugin, MyModelPlugin); -\endcode - -\o -\qml -MyModel { - id: myModel - ListElement { someProperty: "some value" } -} -\endqml - -\qml -ListView { - width: 200; height: 250 - model: myModel - delegate: Text { text: someProperty } -} -\endqml - -\endtable - -See \l {Tutorial: Writing QML extensions with C++} for details on writing QML C++ -plugins. - - - -\section1 Other Data Models - - -\section2 An Integer - -An integer can be used to specify a model that contains a certain number -of elements. In this case, the model does not have any data roles. - -The following example creates a ListView with five elements: -\qml -Item { - width: 200; height: 250 - - Component { - id: itemDelegate - Text { text: "I am item number: " + index } - } - - ListView { - anchors.fill: parent - model: 5 - delegate: itemDelegate - } - -} -\endqml - - -\section2 An Object Instance - -An object instance can be used to specify a model with a single object element. The -properties of the object are provided as roles. - -The example below creates a list with one item, showing the color of the -\i myText text. Note the use of the fully qualified \i model.color property -to avoid clashing with \i color property of the Text element in the delegate. - -\qml -Rectangle { - width: 200; height: 250 - - Text { - id: myText - text: "Hello" - color: "#dd44ee" - } - - Component { - id: myDelegate - Text { text: model.color } - } - - ListView { - anchors.fill: parent - anchors.topMargin: 30 - model: myText - delegate: myDelegate - } -} -\endqml - -\section1 Accessing Views and Models from Delegates - -You can access the view for which a delegate is used, and its -properties, by using ListView.view in a delegate on a ListView, or -GridView.view in a delegate on a GridView, etc. In particular, you can -access the model and its properties by using ListView.view.model. - -This is useful when you want to use the same delegate for a number of -views, for example, but you want decorations or other features to be -different for each view, and you would like these different settings to -be properties of each of the views. Similarly, it might be of interest -to access or show some properties of the model. - -In the following example, the delegate shows the property \i{language} -of the model, and the color of one of the fields depends on the -property \i{fruit_color} of the view. - -\snippet doc/src/snippets/declarative/models/views-models-delegates.qml rectangle - -Another important case is when some action (e.g. mouse click) in the -delegate should update data in the model. In this case you can define -a function in the model, e.g.: - -\code - setData(int row, const QString & field_name, QVariant new_value), -\endcode - -...and call it from the delegate using: - -\js - ListView.view.model.setData(index, field, value) -\endjs - -...assuming that \i{field} holds the name of the field which should be -updated, and that \i{value} holds the new value. - -*/ - -/*! -\page qml-presenting-data.html -\inqmlmodule QtQuick 2 -\title Presenting Data with QML - -\section1 Introduction - -Qt Quick contains a set of standard items that can be used to present data in a -number of different ways. For simple user interfaces, -\l{Using QML Positioner and Repeater Items#Repeaters}{Repeaters} can be used -in combination with -\l{Using QML Positioner and Repeater Items#Positioners}{Positioners} -to obtain pieces of data and arrange them in a user interface. However, when -large quantities of data are involved, it is often better to use models with -the standard views since these contain many built-in display and navigation -features. - -\section1 Views - -Views are scrolling containers for collections of items. They are feature-rich, -supporting many of the use cases found in typical applications, and can be -customized to meet requirements on style and behavior. - -A set of standard views are provided in the basic set of Qt Quick -graphical elements: - -\list -\o \l{#ListView}{ListView} arranges items in a horizontal or vertical list -\o \l{#GridView}{GridView} arranges items in a grid within the available space -\o \l{#PathView}{PathView} arranges items on a path -\endlist - -Unlike these items, \l WebView is not a fully-featured view item, and needs -to be combined with a \l Flickable item to create a view that performs like -a Web browser. - -\section2 ListView - -\l ListView shows a classic list of items with horizontal or vertical placing -of items. - -\beginfloatright -\inlineimage qml-listview-snippet.png -\endfloat - -The following example shows a minimal ListView displaying a sequence of -numbers (using an \l{QML Data Models#An Integer}{integer as a model}). -A simple delegate is used to define an items for each piece of data in the -model. - -\clearfloat -\snippet doc/src/snippets/declarative/listview/listview-snippet.qml document - - - -\section2 GridView - -\l GridView displays items in a grid like an file manager's icon view. - -\section2 PathView - -\l PathView displays items on a path, where the selection remains in -the same place and the items move around it. - -\section1 Decorating Views - -\section2 Headers and Footers - -\section2 Sections - -\section2 Navigation - -In traditional user interfaces, views can be scrolled using standard -controls, such as scroll bars and arrow buttons. In some situations, it -is also possible to drag the view directly by pressing and holding a -mouse button while moving the cursor. In touch-based user interfaces, -this dragging action is often complemented with a flicking action, where -scrolling continues after the user has stopped touching the view. - -\section1 Further Reading -*/ diff --git a/doc/src/declarative/qmlinuse.qdoc b/doc/src/declarative/qmlinuse.qdoc deleted file mode 100644 index ffc8799a31..0000000000 --- a/doc/src/declarative/qmlinuse.qdoc +++ /dev/null @@ -1,500 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qmlinuse.html -\inqmlmodule QtQuick 2 -\title Using QML elements - -\raw HTML - <div class="item group"> - <div class="secondaryx"> - <div class="toc"> - <h3> - <a name="toc">QML Elements</a></h3> - <ul> - <li class="level1"><a href="#basicElements">Basic QML Elements</a></li> - <li class="level1"><a href="#visualElements">QML Visual Elements</a></li> - <li class="level1"><a href="#AnimAndTrans">QML Animation and Transition Elements</a></li> - <li class="level1"><a href="#interactElement">Basic QML Interaction Elements</a></li> - <li class="level1"><a href="#eventElements">QML Event Elements</a></li> - <li class="level1"><a href="#Position">QML Positioning Elements</a></li> - <li class="level1"><a href="#stateElement">QML State Elements</a></li> - <li class="level1"><a href="#transformElement">QML Transform Elements</a></li> - <li class="level1"><a href="#utilityElement">QML Utility Elements</a></li> - <li class="level1"><a href="#modelView">Models and View Elements</a></li> - <li class="level1"><a href="#paths">Paths</a></li> - <li class="level1"><a href="#ParticleElement">Particle Elements</a></li> - <li class="level1"><a href="#bridge">Bridge Elements</a></li> - </ul> - </div> - </div> - <div class="primary"> - <h1> - Groups Of Related QML Elements</h1> - <p> - QML Elements are grouped by their respective functionalities. Certain elements are - suited for building complex components while other elements strictly dictate appearances - and color.</p> - <div class="cols two group unclear"> - <div class="col first"> - <p> - <i>add something about elements in use in general</i></p> - </div> - <div class="col"> - <img src="images/quick_screens.png" /> - </div> - </div> - </div> - </div> - <!-- tech domains start --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="basicElements"> Basic QML Elements</a></h2> - <p> - Basic elements can be extended to form more complex elements.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-item.html">Item Element</a> - - The Item is the most basic of all visual items in QML. Many visual elements inherit - properties from the Item element.</li> - <li><a href="qml-component.html">Component Element</a> - - The Component element encapsulates a QML component definition.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="visualElements">QML Visual Elements</a></h2> - <p> - Visual elements offer various interactive and graphical functionalities. Visual - elements can directly set properties that dictate appearances.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-borderimage.html">BorderImage - Element</a> - The BorderImage element provides an image that can be used as a border.</li> - <li><a href="qml-gradient.html">Gradient Element</a> - - The Gradient item defines a gradient fill.</li> - <li><a href="qml-gradientstop.html">GradientStop - Element</a> - The GradientStop item defines the color at a position in a Gradient.</li> - <li><a href="qml-image.html">Image Element</a> - - The Image element displays an image from a source.</li> - <li><a href="qml-rectangle.html">Rectangle Element</a> - - The Rectangle item provides a filled rectangle.</li> - <li><a href="qml-text.html">Text Element</a> - - The Text item allows the addition of formatted text to a scene.</li> - <li><a href="qml-textedit.html">TextEdit Element</a> - - The TextEdit item displays multiple lines of editable formatted text.</li> - <li><a href="qml-textinput.html">TextInput Element</a> - - The TextInput item displays an editable line of text.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="AnimAndTrans">QML Animation and Transition Elements</a></h2> - <p> - Animation and transition elements control animation behaviors. Animations can run - in parallel or in series for different value types. - </p> - <b>Elements:</b> - <ul> - <li><a href="qml-anchoranimation.html">AnchorAnimation Element</a> - - The AnchorAnimation element animates changes in anchor values.</li> - <li><a href="qml-animation.html">Animation Element</a> - The Animation - element is the base of all QML animations.</li> - <li><a href="qml-behavior.html">Behavior Element</a> - The Behavior element allows you to specify a default animation for a property change.</li> - <li><a href="qml-coloranimation.html">ColorAnimation Element</a> - The ColorAnimation element animates changes in color values.</li> - <li><a href="qml-numberanimation.html">NumberAnimation Element</a> - The NumberAnimation element animates changes in qreal-type values.</li> - <li><a href="qml-parallelanimation.html">ParallelAnimation Element</a> - The ParallelAnimation element allows animations to be run in parallel.</li> - <li><a href="qml-parentanimation.html">ParentAnimation Element</a> - The ParentAnimation element animates changes in parent values.</li> - <li><a href="qml-pauseanimation.html">PauseAnimation Element</a> - The PauseAnimation element provides a pause during an animation.</li> - <li><a href="qml-propertyaction.html">PropertyAction Element</a> - The PropertyAction element allows immediate property changes during animation.</li> - <li><a href="qml-propertyanimation.html">PropertyAnimation Element</a> - The PropertyAnimation element animates changes in property values.</li> - <li><a href="qml-rotationanimation.html">RotationAnimation Element</a> - The RotationAnimation element animates changes in rotational values.</li> - <li><a href="qml-scriptaction.html">ScriptAction Element</a> - The ScriptAction element allows scripts to be run during an animation.</li> - <li><a href="qml-sequentialanimation.html">SequentialAnimation Element</a> - The SequentialAnimation element allows animations to be run sequentially.</li> - <li><a href="qml-smoothedanimation.html">SmoothedAnimation Element</a> - The SmoothedAnimation element allows a property to smoothly track a value.</li> - <li><a href="qml-springanimation.html">SpringAnimation Element</a> - The SpringAnimation element allows a property to track a value in a spring-like - motion.</li> - <li><a href="qml-transition.html">Transition Element</a> - The Transition element defines animated transitions that occur on state changes.</li> - <li><a href="qml-vector3danimation.html">Vector3dAnimation Element</a> - The Vector3dAnimation element animates changes in QVector3d values.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <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> - <ul> - <li><a href="qml-flickable.html">Flickable Element</a> - The Flickable item provides a surface that can be "flicked".</li> - <li><a href="qml-flipable.html">Flipable Element</a> - The Flipable item provides a surface that can be flipped or reflected.</li> - <li><a href="qml-focuspanel.html">FocusPanel Element</a> - The FocusPanel item explicitly creates a focus panel.</li> - <li><a href="qml-focusscope.html">FocusScope Element</a> - The FocusScope object explicitly creates a focus scope for focus management.</li> - <li><a href="qml-pincharea.html">PinchArea Element</a> - The PinchArea item enables simple pinch gesture handling.</li> - <li><a href="qml-keynavigation.html">KeyNavigation Element</a> - The KeyNavigation attached property supports key navigation by arrow keys.</li> - <li><a href="qml-keys.html">Keys Element</a> - The Keys attached property provides key handling to Items.</li> - <li><a href="qml-mousearea.html">MouseArea Element</a> - The MouseArea item enables simple mouse handling.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="eventElements">QML Event Elements</a></h2> - <p> - Key and mouse events information are provided in these event elements.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-keyevent.html">KeyEvent Element</a> - The KeyEvent - object provides information about a key event.</li> - <li><a href="qml-mouseevent.html">MouseEvent Element</a> - The MouseEvent - object provides information about a mouse event.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="Position">QML Positioning Elements</a></h2> - <p> - Using positioning elements, layouts can be defined and their children accessed through - an index.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-column.html">Column Element</a> - The Column - item arranges its children vertically.</li> - <li><a href="qml-flow.html">Flow Element</a> - The Flow item - arranges its children side by side, wrapping as necessary.</li> - <li><a href="qml-grid.html">Grid Element</a> - The Grid item - positions its children in a grid.</li> - <li><a href="qml-row.html">Row Element</a> - The Row item - arranges its children horizontally.</li> - <li><a href="qml-repeater.html">Repeater Element</a> - The Repeater element allows you to repeat an Item-based component using a model.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - - <h2><a name="stateElement">QML State Elements</a></h2> - <p> - States and groups of states are formed using state elements.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-anchorchanges.html">AnchorChanges Element</a> - The AnchorChanges element allows you to change the anchors of an item in a state.</li> - <li><a href="qml-parentchange.html">ParentChange Element</a> - The ParentChange element allows you to reparent an Item in a state change.</li> - <li><a href="qml-propertychanges.html">PropertyChanges Element</a> - The PropertyChanges element describes new property bindings or values for a state.</li> - <li><a href="qml-state.html">State Element</a> - The State - element defines configurations of objects and properties.</li> - <li><a href="qml-statechangescript.html">StateChangeScript Element</a> - The StateChangeScript element allows you to run a script in a state.</li> - <li><a href="qml-stategroup.html">StateGroup Element</a> - The StateGroup element provides state support for non-Item elements.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="transformElement">QML Transform Elements</a></h2> - <p> - Advanced handling of transformations is controlled in transform elements.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-rotation.html">Rotation Element</a> - The Rotation object provides a way to rotate an Item.</li> - <li><a href="qml-scale.html">Scale Element</a> - The Scale element provides a way to scale an Item.</li> - <li><a href="qml-transform.html">Transform Element</a> - The Transform element provide a way of building advanced transformations on Items.</li> - <li><a href="qml-translate.html">Translate Element</a> - The Translate object provides a way to move an Item without changing its x or y properties.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="utilityElement">QML Utility Elements</a></h2> - <p> - These elements handle assorted operations such as event timing, Qt enumerations, - and font loading.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-binding.html">Binding Element</a> - The Binding element allows arbitrary property bindings to be created.</li> - <li><a href="qml-connections.html">Connections Element</a> - A Connections element describes generalized connections to signals.</li> - <li><a href="qml-doublevalidator.html">DoubleValidator Element</a> - Provides a validator for non-integer numbers.</li> - <li><a href="qml-fontloader.html">FontLoader Element</a> - The FontLoader element allows fonts to be loaded by name or URL.</li> - <li><a href="qml-intvalidator.html">IntValidator Element</a> - This element provides a validator for integer values.</li> - <li><a href="qml-layoutitem.html">LayoutItem Element</a> - The LayoutItem element allows declarative UI elements to be placed inside Qt's Graphics View layouts.</li> - <li><a href="qml-loader.html">Loader Element</a> - The Loader item allows dynamically loading an Item-based subtree from a URL or Component.</li> - <li><a href="qml-package.html">Package Element</a> - Package provides a bundle for shared contexts in multiple views.</li> - <li><a href="qml-qt.html">Qt Element</a> - The QML global Qt object provides useful enums and functions from Qt.</li> - <li><a href="qml-qtobject.html">QtObject Element</a> - The QtObject element is the most basic element in QML.</li> - <li><a href="qml-regexpvalidator.html">RegExpValidator Element</a> - This element provides a validator for regular expressions.</li> - <li><a href="qml-systempalette.html">SystemPalette Element</a> - The SystemPalette element provides access to the Qt palettes.</li> - <li><a href="qml-timer.html">Timer Element</a> - The Timer item triggers a handler at a specified interval.</li> - <li><a href="qml-workerscript.html">WorkerScript Element</a> - The WorkerScript element enables the use of threads in QML.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="modelView">Models and View Elements</a></h2> - <p> - Models and views are used to organize data and control their layouts using delegates. - Models dictate the data formation and views control the layouts of data in the model.</p> - <b>View Elements:</b> - <ul> - <li><a href="qml-gridview.html">GridView Element</a> - The GridView item provides a grid view of items provided by a model.</li> - <li><a href="qml-listview.html">ListView Element</a> - The ListView item provides a list view of items provided by a model.</li> - <li><a href="qml-pathview.html">PathView Element</a> - The PathView element lays out model-provided items on a path.</li> - <li><a href="qml-webview.html">WebView Element</a> - The WebView item allows you to add Web content to a canvas.</li> - </ul> - <b>Model Elements:</b> - <ul> - <li><a href="qml-folderlistmodel.html">FolderListModel Element</a> - The FolderListModel provides a model of the contents of a file system folder.</li> - <li><a href="qml-listelement.html">ListElement Element</a> - A ListElement defines a data item in a ListModel.</li> - <li><a href="qml-listmodel.html">ListModel Element</a> - The ListModel element defines a free-form list data source.</li> - <li><a href="qml-visualdatamodel.html">VisualDataModel Element</a> - The VisualDataModel encapsulates a model and delegate.</li> - <li><a href="qml-visualitemmodel.html">VisualItemModel Element</a> - The VisualItemModel allows items to be provided to a view.</li> - <li><a href="qml-xmllistmodel.html">XmlListModel Element</a> - The XmlListModel element is used to specify a model using XPath expressions.</li> - <li><a href="qml-xmlrole.html">XmlRole Element</a> - The XmlRole element allows you to specify a role for an XmlListModel.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="paths">Paths</a></h2> - <p> - QML components can be arranged along paths. Path elements allow control over different - path types.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-path.html">Path Element</a> - A Path object defines a path for use by PathView.</li> - <li><a href="qml-pathattribute.html">PathAttribute Element</a> - The PathAttribute allows setting an attribute at a given position in a Path.</li> - <li><a href="qml-pathcubic.html">PathCubic Element</a> - The PathCubic defines a cubic Bezier curve with two control points.</li> - <li><a href="qml-pathelement.html">PathElement Element</a> - PathElement is the base path type.</li> - <li><a href="qml-pathline.html">PathLine Element</a> - The PathLine defines a straight line.</li> - <li><a href="qml-pathpercent.html">PathPercent Element</a> - The PathPercent manipulates the way a path is interpreted.</li> - <li><a href="qml-pathquad.html">PathQuad Element</a> - The PathQuad defines a quadratic Bezier curve with a control point.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="ParticleElement">Particle Elements</a></h2> - <p> - Particle effects are declared and controlled using particle elements.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-particlemotiongravity.html">ParticleMotionGravity Element</a> - The ParticleMotionGravity object moves particles towards a point.</li> - <li><a href="qml-particlemotionlinear.html">ParticleMotionLinear Element</a> - The ParticleMotionLinear object moves particles linearly.</li> - <li><a href="qml-particlemotionwander.html">ParticleMotionWander Element</a> - The ParticleMotionWander object moves particles in a somewhat random fashion.</li> - <li><a href="qml-particles.html">Particles Element</a> - The Particles object generates and moves particles.</li> - </ul> - </div> - </div> - <!-- next --> - <div class="item group"> - <hr /> - <div class="secondary"> - <div class="box"> - <!-- video box --> - <h3> - image heading</h3> - <img src="" /> - <p> - img descr.</p> - </div> - <!-- video box end --> - </div> - <div class="primary"> - <h2><a name="bridge">Bridge Elements</a></h2> - <p> - Bridge elements allow direct communication between C++ and QML entities.</p> - <b>Elements:</b> - <ul> - <li><a href="qml-layoutitem.html">LayoutItem Element</a> - The LayoutItem element allows declarative UI elements to be placed inside Qt's Graphics View layouts.</li> - </ul> - </div> - </div> - -\endraw - - - -*/ - diff --git a/doc/src/declarative/qmlviews.qdoc b/doc/src/declarative/qmlviews.qdoc deleted file mode 100644 index 22de80c8dc..0000000000 --- a/doc/src/declarative/qmlviews.qdoc +++ /dev/null @@ -1,128 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qml-views.html -\inqmlmodule QtQuick 2 -\ingroup qml-features -\contentspage QML Features -\previouspage {QML Data Models}{Structuring Data with Models} -\nextpage {Extending QML Functionalities using C++} -\title Presenting Data with Views - -Views are containers for collections of items. They are feature-rich and can be -customizable to meet style or behavior requirements. - -\keyword qml-view-elements -A set of standard views are provided in the basic set of Qt Quick -graphical elements: - -\list -\o \l{ListView} arranges items in a horizontal or vertical list -\o \l{GridView} arranges items in a grid within the available space -\o \l{PathView} arranges items on a path -\o \l{WebView}{WebView} - available from the \l {QtWebKit QML Module}. -\endlist -Unlike other views, \l WebView is not a fully-featured view item, and needs -to be combined with a \l Flickable item to create a view that performs like -a Web browser. - -These elements have properties and behaviors exclusive to each element. Visit -their respective documentation for more information. - -\section1 Models - -Views display \l{qml-data-models}{models} onto the screen. A model could be a simple list of \l{QML Data Models#An Integer}{integer} or a \l{qml-c++-models}{C++ model}. - -To assign a model to a view, bind the view's \c model property to a model. -\snippet doc/src/snippets/declarative/listview.qml model -\snippet doc/src/snippets/declarative/listview.qml model - -For more information, consult the \l {QML Data Models} article. - -\keyword qml-view-delegate -\section1 View Delegates - -Views need a \i delegate to visually represent an item in a list. A view will -visualize each item list according to the template defined by the delegate. -Items in a model are accessible through the \c index property as well as the -item's properties. -\snippet doc/src/snippets/declarative/listview.qml delegate -\image listview-setup.png - -\section1 Decorating Views - -Views allow visual customization through \i decoration properties such as the \c header, \c footer, and \c section properties. By binding an object, usually -another visual object, to these properties, the views are decoratable. A footer -may include a \l Rectangle element showcasing borders or a header that displays -a logo on top of the list. - -Suppose that a specific club wants to decorate its members list with its brand -colors. A member list is in a \c model and the \c delegate will display the -model's content. -\snippet doc/src/snippets/declarative/listview-decorations.qml model -\snippet doc/src/snippets/declarative/listview-decorations.qml delegate - -The club may decorate the members list by binding visual objects to the -\c header and \c footer properties. The visual object may be defined inline, in another file, or in a -\l {Component} element. -\snippet doc/src/snippets/declarative/listview-decorations.qml decorations -\image listview-decorations.png - -\section1 Mouse/touch Handling - -The views handle dragging and flicking of their content, however they do -not handle touch interaction with the individual delegates. In order for the -delegates to react to touch input, e.g. to set the \c currentIndex, a MouseArea -with the appropriate touch handling logic must be provided by the delegate. - -Note that if \c highlightRangeMode is set to \c StrictlyEnforceRange the -currentIndex will be affected by dragging/flicking the view, since the view -will always ensure that the \c currentIndex is within the highlight range -specified. - - -\section1 ListView Sections - -\l {ListView} contents may be grouped into \i sections, where related list items -are labeled according to their sections. Further, the sections may be decorated -with \l{qml-view-delegate}{delegates}. - -A list may contain a list indicating people's names and the team on which team -the person belongs. -\snippet doc/src/snippets/declarative/listview-sections.qml model -\snippet doc/src/snippets/declarative/listview-sections.qml delegate - -The ListView element has the \c section -\l{Property Binding#Attached Properties}{attached property} that can combine -adjacent and related elements into a section. The section's \c property -property is for selecting which list element property to use as sections. -The \c criteria can dictate how the section names are displayed and the -\c delegate is similar to the views' \l {qml-view-delegate}{delegate} property. -\snippet doc/src/snippets/declarative/listview-sections.qml section -\image listview-section.png -*/ diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc deleted file mode 100644 index 594fe8c944..0000000000 --- a/doc/src/declarative/qtprogrammers.qdoc +++ /dev/null @@ -1,156 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtprogrammers.html -\inqmlmodule QtQuick 2 -\target qtprogrammers -\title QML for Qt Programmers - -While QML does not require Qt knowledge to use, if you \i are already familiar with Qt, -much of your knowledge is directly relevant to learning and using QML. Of course, -an application with a UI defined in QML also uses Qt for all the non-UI logic. - -\section1 Familiar Concepts - -QML provides direct access to the following concepts from Qt: - -\list - \o QAction - the \l {QML Basic Types}{action} type - \o QObject signals and slots - available as functions to call in JavaScript - \o QObject properties - available as variables in JavaScript - \o QWidget - QDeclarativeView is a QML-displaying widget - \o Qt models - used directly in data binding (QAbstractItemModel) -\endlist - -Qt knowledge is \i required for \l {Extending QML Functionalities using C++}, -and also for \l{Integrating QML Code with existing Qt UI code}. - -\section1 QML Items compared with QWidgets - -QML Items are very similar to QWidgets: they define the look and feel of the user interface. (Note that while QWidgets -haven't traditionally been used to define the look and feel of view delegates, QML Items can be used for this as well.) - -There are three structurally different types of QWidget: - -\list - \o Simple widgets that are not used as parents (QLabel, QCheckBox, QToolButton, etc.) - \o Parent widgets that are normally used as parents to other widgets (QGroupBox, QStackedWidget, QTabWidget, etc.) - \o Compound widgets that are internally composed of child widgets (QComboBox, QSpinBox, QFileDialog, QTabWidget, etc.) -\endlist - -QML Items also serve these purposes. Each is considered separately below. - -\section2 Simple Widgets - -The most important rule to remember while implementing a new QDeclarativeItem in C++ -is that it should not contain any look and feel policies - leave that to the -QML usage of the item. - -As an example, imagine you wanted a reusable Button item. If you therefore -decided to write a QDeclarativeItem subclass to implement a button, -just as QToolButton subclasses QWidget for this purpose, following the rule above, your -\c QDeclarativeButton would not have any appearance - just the notions of enabled, triggering, etc. - -But there is already an object in Qt that does this: QAction. - -QAction is the UI-agnostic essence of QPushButton, QCheckBox, QMenu items, QToolButton, -and other visual widgets that are commonly bound to a QAction. - -So, the job of implementing a checkbox abstraction for QML is already done - it's QAction. -The look and feel of an action - the appearance of the button, the transition between states, -and exactly how it respond to mouse, key, or touch input, should all be left for definition -in QML. - -It is illustrative to note that QDeclarativeTextEdit is built upon QTextControl, -QDeclarativeWebView is built upon QWebPage, and ListView uses QAbstractItemModel, -just as QTextEdit, QWebView, and QListView are built upon -those same UI-agnostic components. - -The encapsulation of the look and feel that QWidgets gives is important, and for this -the QML concept of \l {qdeclarativedocuments.html}{components} serves the same purpose. If you are building a complete -suite of applications which should have a consistent look and feel, you should build -a set of reusable components with the look and feel you desire. - -So, to implement your reusable button, you would simply build a QML component. - - -\section2 Parent Widgets - -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 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 -which require very particular event handling, such as Flickable, require C++ implementations. - -As an example, imagine you decided to make a generic tab widget item to be used -through your application suite wherever information is in such quantity that it -needs to be divided up into pages. - -A significant difference in the parenting concept with QML compare to QWidgets -is that while child items are positioned relative to their parents, -there is no requirement that they be wholly contained ("clipped") to -the parent (although the clipped property of the child Item does allow -this where it is needed). -This difference has rather far-reaching consequences, for example: - -\list - \o A shadow or highlight around a widget could be a child of that widget. - \o Particle effects can flow outside the object where they originate. - \o Transitioning animations can "hide" items by visibly moving them beyond the screen bounds. -\endlist - - -\section2 Compound Widgets - -Some widgets provide functionality by composing other widgets as an "implementation detail", -providing a higher level API to the composition. QSpinBox for example is a line edit and some -buttons to increase/decrease the edited value. QFileDialog uses a whole host of widgets to -give the user a way of finding and selecting a file name. - -When developing reusable QML Items, you may choose to do the same: build an item composed -of other items you have already defined. - -The only caveat when doing this is to consider the possible animations and transitions that -users of the compound item might wish to employ. For example, a spinbox might need to smoothly -transition from an arbitrary Text item, or characters within a Text item, so your spinbox -item would need to be sufficiently flexible to allow such animation. - -\section1 QML Items Compared With QGraphicsWidgets - -The main difference between QML items and QGraphicsWidgets is how they are intended to be used. The technical implementation details are much the same, but in practice they are different because QML items are made for declarative and compositional use, and QGraphicsWidgets are made for imperative and more integrated use. Both QML items and QGraphicsWidgets inherit from QGraphicsObject, and can co-exist. The differences are in the layouting system and the interfacing with other components. Note that, as QGraphicsWidgets tend more to be all-in-one packages, the equivalent of a QGraphicsWidget may be many QML items composed across several QML files, but it can still be loaded and used as a single QGraphicsObject from C++. - -QGraphicsWidgets are usually designed to be laid out with QGraphicsLayouts. QML does not use QGraphicsLayouts, as the Qt layouts do not mix well with animated and fluid UIs, so the geometry interface is one of the main differences. When writing QML elements, you allow the designers to place their bounding rectangle using absolute geometry, bindings or anchors (all setup for you when you inherit QDeclarativeItem) and you do not use layouts or size hints. If size hints are appropriate, then place them in the QML documentation so that the designers know how to use the item best, but still have complete control over the look and feel. - -The other main difference is that QGraphicsWidgets tend to follow the widget model, in that they are a self-contained bundle of UI and logic. In contrast, QML primitives are usually a single purpose item that does not fulfill a use case on its own, but is composed into the equivalent of the widget inside the QML file. So when writing QML Items, try to avoid doing UI logic or composing visual elements inside the items. Try instead to write more general purpose primitives, so that the look and feel (which involves the UI logic) can be written in QML. - -Both differences are caused by the different method of interaction. QGraphicsWidget is a QGraphicsObject subclass which makes fluid UI development from C++ easier, and QDeclarativeItem is a QGraphicsObject subclass which makes fluid UI development from QML easier. The difference therefore is primarily one of the interface exposed, and the design of the items that come with it (the Declarative primitives for QML and the nothing for QGraphicsWidget, because you need to write your own UI logic into the subclass). - -If you wish to use both QML and C++ to write the UI, for example to ease the transition period, it is recommended to use QDeclarativeItem subclasses (although you can use QGraphicsWidgets as well). To allow for easier use from C++ make the root item of each C++ component a LayoutItem, and load individual 'widgets' of QML (possibly comprised of multiple files, and containing a self-contained bundle of UI and logic) into your scene to replace individual QGraphicsWidgets one at a time. -*/ diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/examples/advtutorial.qdoc index d78e2de17f..d682a73430 100644 --- a/doc/src/declarative/advtutorial.qdoc +++ b/doc/src/examples/advtutorial.qdoc @@ -460,7 +460,7 @@ By following this tutorial you've seen how you can write a fully functional appl \list \o Build your application with \l {{QML Elements}}{QML elements} -\o Add application logic \l{Integrating JavaScript}{with JavaScript code} +\o Add application logic \l{JavaScript Expressions in QML}{with JavaScript code} \o Add animations with \l {Behavior}{Behaviors} and \l{QML States}{states} \o Store persistent application data using, for example, the \l{Offline Storage API} or \l XMLHttpRequest \endlist diff --git a/doc/src/declarative/dynamicview-tutorial.qdoc b/doc/src/examples/dynamicview-tutorial.qdoc index 517dacc2f1..517dacc2f1 100644 --- a/doc/src/declarative/dynamicview-tutorial.qdoc +++ b/doc/src/examples/dynamicview-tutorial.qdoc diff --git a/doc/src/examples/example-slideswitch.qdoc b/doc/src/examples/example-slideswitch.qdoc index 354ed749a5..689841a78b 100644 --- a/doc/src/examples/example-slideswitch.qdoc +++ b/doc/src/examples/example-slideswitch.qdoc @@ -25,16 +25,14 @@ ** ****************************************************************************/ + /*! -\page qdeclarativeexampletoggleswitch.html -\inqmlmodule QtQuick 2 +\page qmlexampletoggleswitch.html \title QML Example - Toggle Switch -\example declarative/ui-components/slideswitch -\brief A reusable switch component in QML - +\brief A reusable switch component made in QML This example shows how to create a reusable switch component in QML. -The code for this example can be found in the \c $QTDIR/examples/declarative/ui-components/slideswitch directory. +The code for this example can be found in the \c examples/declarative/ui-components/slideswitch directory. The elements that compose the switch are: @@ -116,7 +114,7 @@ states (\i on and \i off). This second function is called when the knob is released and we want to make sure that the knob does not end up between states (neither \i on nor \i off). If it is the case call the \c toggle() function otherwise we do nothing. -For more information on scripts see \l{Integrating JavaScript}. +For more information on scripts see \l{JavaScript Expressions in QML}. \section2 Transition \snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 7 diff --git a/doc/src/examples/example-textballoons.qdoc b/doc/src/examples/example-textballoons.qdoc index 872c254fb0..be004f59ed 100644 --- a/doc/src/examples/example-textballoons.qdoc +++ b/doc/src/examples/example-textballoons.qdoc @@ -25,6 +25,7 @@ ** ****************************************************************************/ + /*! \title Scenegraph Painted Item Example \example declarative/painteditem/textballoons diff --git a/doc/src/examples/examples.qdoc b/doc/src/examples/examples.qdoc new file mode 100644 index 0000000000..f9c89d87f4 --- /dev/null +++ b/doc/src/examples/examples.qdoc @@ -0,0 +1,307 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + +\page qtquick-codesamples.html +\title Qt Quick Code Samples +\brief Building UIs with QML +\ingroup all-examples +\ingroup qtquick +\target qtquick-samples +\inqmlmodule QtQuick 2 + +These are code samples that show how to use various aspects of Qt Quick. Larger +compound interfaces are grouped as applications as they demonstrate more Qt +Quick features. + +To run the sample applications, open them in Qt Creator or use the included +\l {QML Viewer} tool. + +Some of these code samples have a corresponding \l{qtquick-tutorials}{tutorial}. +The Qt Quick features are covered in the \l {qtquick-overviews}{main page}. +This set of code samples are part of the collection of \l{Qt Examples}. + +\div {class="threecolumn_area"} + \div {class="heading"} + Qt Quick Applications + \enddiv + \div {class="threecolumn_piece"} + \l{demos/declarative/calculator}{Calculator} + \image qml-calculator-example-small.png + \enddiv + \div {class="threecolumn_piece"} + \l{demos/declarative/flickr}{Flickr Mobile} + \image qml-flickr-demo-small.png + \enddiv + \div {class="threecolumn_piece"} + \l{demos/declarative/minehunt}{Minehunt} + \image qml-minehunt-demo-small.png + \enddiv + \div {class="threecolumn_piece"} + \l{demos/declarative/photoviewer}{Photo Viewer} + \image qml-photoviewer-demo-small.png + \enddiv + \div {class="threecolumn_piece"} + \l{demos/declarative/rssnews}{RSS News Reader} + \image qml-rssnews-demo-small.png + \enddiv + \div {class="threecolumn_piece"} + \l{demos/declarative/samegame}{Same Game} + \image qml-samegame-demo-small.png + \enddiv + \div {class="threecolumn_piece"} + \l{demos/declarative/snake}{Snake} + \image qml-snake-demo-small.png + \enddiv + \div {class="threecolumn_piece"} + \l{demos/declarative/twitter}{Twitter} + \image qml-twitter-demo-small.png + \enddiv + \div {class="threecolumn_piece"} + \l{demos/declarative/webbrowser}{Web Browser} + \image qml-webbrowser-demo-small.png + \enddiv +\enddiv +\div {class="threecolumn_area"} + \div {class="heading"} + QML Examples + \enddiv + Code samples demonstrate a general use for QML features. Some showcase + how elements or properties can be used in an application. + \div {class="threecolumn_piece"} + \div {class="heading"} + QML Features + \enddiv + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Mouse and Keyboard Input + \enddiv + \list + \o \l{declarative/text/fonts}{Fonts} + \o \l{declarative/text/textselection}{Text Selection} + \o \l{declarative/keyinteraction/focus}{Keyboard Focus} + \o \l{declarative/touchinteraction/mousearea}{MouseArea} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + States and Transitions + \enddiv + \list + \o \l{declarative/animation/states}{States} + \o \l{declarative/animation/basics}{Animation Essentials} + \o \l{declarative/animation/behaviors}{Behaviors} + \o \l{declarative/animation/easing}{Easing} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + UI Components + \enddiv + \list + \o \l{declarative/ui-components/dialcontrol}{Dial Control} + \o \l{declarative/ui-components/flipable}{Flipable} + \o \l{declarative/ui-components/progressbar}{Progress Bar} + \o \l{declarative/ui-components/scrollbar}{Scroll Bar} + \o \l{declarative/ui-components/searchbox}{Search Box} + \o \l{declarative/ui-components/slideswitch}{Slide Switch} + \o \l{declarative/ui-components/spinner}{Spinner} + \o \l{declarative/ui-components/tabwidget}{Tab Widget} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Positioners and Layout + \enddiv + \list + \o \l{declarative/positioners}{Row and Column} + \o \l{declarative/righttoleft/layoutmirroring}{Layout Mirroring} + \o \l{declarative/righttoleft/layoutdirection}{Layout Direction} + \o \l{declarative/righttoleft/textalignment}{Text Alignment} + \o \l{declarative/screenorientation}{Screen Orientation} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Data with Models and Views + \enddiv + \list + \o \l{declarative/modelviews/gridview}{GridView} + \o \l{declarative/modelviews/listview}{ListView} + \o \l{declarative/modelviews/pathview}{PathView} + \o \l{declarative/modelviews/package}{Package} + \o \l{declarative/modelviews/visualitemmodel}{VisualItemModel} + \o \l{declarative/modelviews/stringlistmodel}{String ListModel} + \o \l{declarative/modelviews/objectlistmodel}{Object ListModel} + \o \l{declarative/modelviews/abstractitemmodel}{AbstractItemModel} + \o \l{declarative/modelviews/webview}{WebView} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Advance UI Components + \enddiv + \list + \o \l{declarative/modelviews/parallax}{Parallax} + \o \l{declarative/toys/clocks}{Clocks} + \o \l{declarative/toys/corkboards}{Corkboards} + \o \l{declarative/toys/dynamicscene}{Dynamic Scene} + \o \l{declarative/toys/tic-tac-toe}{Tic Tac Toe} + \o \l{declarative/toys/tvtennis}{TV Tennis} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Image Elements + \enddiv + \list + \o \l{declarative/imageelements/borderimage}{BorderImage} + \o \l{declarative/imageelements/image}{Image} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Loading Resources + \enddiv + \list + \o \l{declarative/sqllocalstorage}{SQL Local Storage} + \o \l{declarative/xml/xmlhttprequest}{XmlHttpRequest} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Localization + \enddiv + \list + \o \l{declarative/i18n}{Translation} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Threading + \enddiv + \list + \o \l{declarative/threading/threadedlistmodel}{Threaded ListModel} + \o \l{declarative/threading/workerscript}{WorkerScript Element} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Graphical Effects + \enddiv + \list + \o \l{declarative/shadereffects}{Shader Effects} + \endlist + \enddiv +\enddiv +\div {class="threecolumn_area"} + \div {class="heading"} + QDeclarative Examples + \enddiv + These examples show how a QML based UI could interact with the + QDeclarative module. + \div {class="threecolumn_piece"} + \div {class="heading"} + From Qt C++ to QML + \enddiv + \list + \o \l {declarative/cppextensions/referenceexamples/adding}{Exporting C++ Classes} + \o \l {declarative/cppextensions/referenceexamples/properties}{Exporting Qt C++ Properties} + \o \l {declarative/cppextensions/referenceexamples/coercion}{C++ Inheritance and Coercion} + \o \l {declarative/cppextensions/referenceexamples/default}{Default Property} + \o \l {declarative/cppextensions/referenceexamples/grouped}{Grouped Properties} + \o \l {declarative/cppextensions/referenceexamples/attached}{Attached Properties} + \o \l {declarative/cppextensions/referenceexamples/signal}{Signal Support} + \o \l {declarative/cppextensions/referenceexamples/methods}{Methods Support} + \o \l {declarative/cppextensions/referenceexamples/valuesource}{Property Value Source} + \o \l {declarative/cppextensions/referenceexamples/binding}{Binding} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Plugins and Resources + \enddiv + \list + \o \l{declarative/cppextensions/plugins}{Plugins} + \o \l{declarative/cppextensions/imageprovider}{Image Provider} + \o \l{declarative/cppextensions/networkaccessmanagerfactory}{Network Access Manager} + \o \l{src/imports/folderlistmodel}{Folder List Model} - a C++ model plugin + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Qt UI and QML Integration + \enddiv + \list + \o \l{declarative-cppextensions-qgraphicslayouts.html}{QGraphicsLayouts} + \o \l{declarative/cppextensions/qwidgets}{QWidgets} + \endlist + \enddiv +\enddiv + +\div {class="threecolumn_area"} + \div {class="heading"} + Learning and Resources + \enddiv + The Qt Developer Network contains additional content such as learning + videos, a wiki, and a forum for posting questions. + \div {class="threecolumn_piece"} + \div {class="heading"} + Elements and Components + \enddiv + \list + \o \l{QML Elements} + \o \l{external: Qt Mobility QML Plugins}{QML Plugins} + \o \l{external: Qt Quick Components for Symbian}{Symbian Components} + \o MeeGo Components + \o \l{QtWebKit QML Module} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Qt Developer Network + \enddiv + \list + \o \l{Qt eLearning}{Training Materials} + \o \l{Forums on Qt Developer Network}{Forums} + \o \l{Wiki on Qt Developer Network}{Wiki} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Reference + \enddiv + \list + \o \l{All Classes}{Qt API} + \o \l{external: Qt Creator Manual}{Qt Creator Manual} + \o \l{Develop with Qt} + \endlist + \enddiv +\enddiv +*/ diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/examples/tutorial.qdoc index f81180a7ec..9042b5e3d8 100644 --- a/doc/src/declarative/tutorial.qdoc +++ b/doc/src/examples/tutorial.qdoc @@ -30,6 +30,7 @@ \inqmlmodule QtQuick 2 \title QML Tutorial \brief An introduction to the basic concepts and features of QML. +\previouspage Introduction to the QML Language \nextpage QML Tutorial 1 - Basic Types This tutorial gives an introduction to QML, the mark up language for Qt Quick. It doesn't cover everything; @@ -147,7 +148,8 @@ An \l Item is the most basic visual element in QML and is often used as a contai We declare a \c cellColor property. This property is accessible from \i outside our component, this allows us to instantiate the cells with different colors. -This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{Property Binding}). +This property is just an alias to an existing property - the color of the rectangle that compose the cell +(see \l{Property Binding in QML}). \snippet examples/declarative/tutorials/helloworld/Cell.qml 5 diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc new file mode 100644 index 0000000000..b4aecbad75 --- /dev/null +++ b/doc/src/external-resources.qdoc @@ -0,0 +1,32 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \externalpage http://www.ecma-international.org/publications/standards/Ecma-262.htm + \title ECMA-262 +*/ + diff --git a/doc/src/images/modelview-overview.png b/doc/src/images/modelview-overview.png Binary files differnew file mode 100644 index 0000000000..41e3a6827f --- /dev/null +++ b/doc/src/images/modelview-overview.png diff --git a/doc/src/localstorage/localstorage.qdoc b/doc/src/localstorage/localstorage.qdoc new file mode 100644 index 0000000000..bee491f9b9 --- /dev/null +++ b/doc/src/localstorage/localstorage.qdoc @@ -0,0 +1,123 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qml-localstorage.html +\title QML Local Storage +\brief SQL storage for QML + +The local storage API provides a JavaScript interface to an SQL relational +database. The QtQuick.LocalStorage module contains the API and it may be given +a namespace. + +\code +import QtQuick.LocalStorage 2.0 as SQL +\endcode +\section2 Database API + +The \c openDatabaseSync() and related functions +provide the ability to access local storage in an SQL database. + +These databases are user-specific and QML-specific, but accessible to all QML applications. +They are stored in the \c Databases subdirectory +of QDeclarativeEngine::offlineStoragePath(), currently as SQLite databases. + +Database connections are automatically closed during Javascript garbage collection. + +The API can be used from JavaScript functions in your QML: + +\snippet declarative/sqllocalstorage/hello.qml 0 + +The API conforms to the Synchronous API of the HTML5 Web Database API, +\link http://www.w3.org/TR/2009/WD-webdatabase-20091029/ W3C Working Draft 29 October 2009\endlink. + +The \l{declarative/sqllocalstorage}{SQL Local Storage example} demonstrates the basics of +using the Local Storage API. + +\section3 db = openDatabaseSync(identifier, version, description, estimated_size, callback(db)) + +Returns the database identified by \i identifier. If the database does not already exist, it +is created, and the function \i callback is called with the database as a parameter. \i description +and \i estimated_size are written to the INI file (described below), but are otherwise currently +unused. + +May throw exception with code property SQLException.DATABASE_ERR, or SQLException.VERSION_ERR. + +When a database is first created, an INI file is also created specifying its characteristics: + +\table +\header \o \bold {Key} \o \bold {Value} +\row \o Name \o The name of the database passed to \c openDatabase() +\row \o Version \o The version of the database passed to \c openDatabase() +\row \o Description \o The description of the database passed to \c openDatabase() +\row \o EstimatedSize \o The estimated size (in bytes) of the database passed to \c openDatabase() +\row \o Driver \o Currently "QSQLITE" +\endtable + +This data can be used by application tools. + +\section3 db.changeVersion(from, to, callback(tx)) + +This method allows you to perform a \i{Scheme Upgrade}. + +If the current version of \i db is not \i from, then an exception is thrown. + +Otherwise, a database transaction is created and passed to \i callback. In this function, +you can call \i executeSql on \i tx to upgrade the database. + +May throw exception with code property SQLException.DATABASE_ERR or SQLException.UNKNOWN_ERR. + +\section3 db.transaction(callback(tx)) + +This method creates a read/write transaction and passed to \i callback. In this function, +you can call \i executeSql on \i tx to read and modify the database. + +If the callback throws exceptions, the transaction is rolled back. + +\section3 db.readTransaction(callback(tx)) + +This method creates a read-only transaction and passed to \i callback. In this function, +you can call \i executeSql on \i tx to read the database (with SELECT statements). + +\section3 results = tx.executeSql(statement, values) + +This method executes a SQL \i statement, binding the list of \i values to SQL positional parameters ("?"). + +It returns a results object, with the following properties: + +\table +\header \o \bold {Type} \o \bold {Property} \o \bold {Value} \o \bold {Applicability} +\row \o int \o rows.length \o The number of rows in the result \o SELECT +\row \o var \o rows.item(i) \o Function that returns row \i i of the result \o SELECT +\row \o int \o rowsAffected \o The number of rows affected by a modification \o UPDATE, DELETE +\row \o string \o insertId \o The id of the row inserted \o INSERT +\endtable + +May throw exception with code property SQLException.DATABASE_ERR, SQLException.SYNTAX_ERR, or SQLException.UNKNOWN_ERR. + + + +*/ diff --git a/doc/src/declarative/particles.qdoc b/doc/src/particles/particles.qdoc index e6996a53f5..d51bcdf11f 100644 --- a/doc/src/declarative/particles.qdoc +++ b/doc/src/particles/particles.qdoc @@ -41,7 +41,7 @@ /*! \page qml-particlesystem.html -\inqmlmodule QtQuick 2 +\inqmlmodule QtQuick.Particles 2 \title Using the Qt Quick Particle System \section1 The ParticleSystem @@ -126,9 +126,9 @@ \title Qt Quick Particle System Performance Guide The performance of the particle system scales with the number of particles it is maintaining. After prototyping the desired - effect, performance can be improved by lowering the particle count. Conversely, if performance is well withing acceptable - bounds you can increase the number of particles until you hit that point (should that improve the effect). - + effect, performance can be improved by lowering the particle count. Conversely, if performance is well within the acceptable + bounds, you can increase the number of particles until you hit that point (should that improve the effect). + Note that particle count is often estimated by the particle system, and in some cases explicitly providing hints as to how many particles will be needed will improve performance. You can do this by setting maximumEmitted on an Emitter, and it is generally useful for Emitters which do not continuously emit particles. @@ -137,7 +137,7 @@ The exception to this is Affectors. For systems not including Affectors, the majority of the performance cost of particles will be on the GPU. Since the GPU is better at parallelizing large numbers of operations more particles can be drawn at 60FPS when Affectors are not used. - + Affectors, particularly if modifying the particles in javascript, can be relatively slow as well as increasing the CPU cost of using particles. Avoid using them in high-volume systems where possible. Some easy cases where Affectors can be avoided are using timed ParticleGroup transitions instead of time-triggered Affectors, or setting acceleration due to gravity in the diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/qml/basictypes.qdoc index 80576f63ab..150383fdc2 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/qml/basictypes.qdoc @@ -26,13 +26,10 @@ ****************************************************************************/ /*! - \page qdeclarativebasictypes.html -\inqmlmodule QtQuick 2 + \page qml-basictypes.html \ingroup qml-features - \contentspage QML Features - \previouspage {QML Basic Elements} - \nextpage Property Binding \title QML Basic Types + \brief basic data types in QML QML has a set of primitive types, as listed below, that are used throughout the \l {QML Elements}. @@ -40,7 +37,7 @@ \annotatedlist qmlbasictypes To create additional types, such as data types created in C++, read the - \l{Extending QML Functionalities using C++} article. + \l{Creating QML Types} article. */ /*! @@ -91,7 +88,7 @@ Item { width: 100.45; height: 150.82 } \endqml - \note In QML all reals are stored in single precision, \l + \bold{Note:} In QML all reals are stored in single precision, \l {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} format. diff --git a/doc/src/qml/c++models.qdoc b/doc/src/qml/c++models.qdoc new file mode 100644 index 0000000000..e2498134fe --- /dev/null +++ b/doc/src/qml/c++models.qdoc @@ -0,0 +1,208 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qml-c++models.qdoc +\title Exposing C++ Models +\brief exposing Qt C++ models to the runtime + +Models can be defined in C++ and then made available to QML. This is useful +for exposing existing C++ data models or otherwise complex datasets to QML. + +A C++ model class can be defined as a \l QStringList, a \l QList<QObject*> or a +\l QAbstractItemModel. The first two are useful for exposing simpler datasets, +while QAbstractItemModel provides a more flexible solution for more complex +models. + + +\section1 QStringList-based Model + + A model may be a simple \l QStringList, which provides the contents of the list + via the \i modelData role. + + Here is a ListView with a delegate that references its model item's + value using the \c modelData role: + + \snippet examples/declarative/modelviews/stringlistmodel/view.qml 0 + + A Qt application can load this QML document and set the value of \c myModel + to a QStringList: + + \snippet examples/declarative/modelviews/stringlistmodel/main.cpp 0 + + The complete example is available in Qt's \l {declarative/modelviews/stringlistmodel}{examples/declarative/modelviews/stringlistmodel} directory. + + \bold{Note:} There is no way for the view to know that the contents of a QStringList + have changed. If the QStringList changes, it will be necessary to reset + the model by calling QDeclarativeContext::setContextProperty() again. + + +\section1 QObjectList-based model + + A list of QObject* values can also be used as a model. A QList<QObject*> provides + the properties of the objects in the list as roles. + + The following application creates a \c DataObject class that with + Q_PROPERTY values that will be accessible as named roles when a + QList<DataObject*> is exposed to QML: + + \snippet examples/declarative/modelviews/objectlistmodel/dataobject.h 0 + \dots 4 + \snippet examples/declarative/modelviews/objectlistmodel/dataobject.h 1 + \codeline + \snippet examples/declarative/modelviews/objectlistmodel/main.cpp 0 + \dots + + The QObject* is available as the \c modelData property. As a convenience, + the properties of the object are also made available directly in the + delegate's context. Here, \c view.qml references the \c DataModel properties in + the ListView delegate: + + \snippet examples/declarative/modelviews/objectlistmodel/view.qml 0 + + Note the use of the fully qualified access to the \c color property. + The properties of the object are not replicated in the \c model + object, since they are easily available via the \c modelData + object. + + The complete example is available in Qt's \l {declarative/modelviews/objectlistmodel}{examples/declarative/modelviews/objectlistmodel} directory. + + Note: There is no way for the view to know that the contents of a QList + have changed. If the QList changes, it will be necessary to reset + the model by calling QDeclarativeContext::setContextProperty() again. + + +\section1 QAbstractItemModel + + A model can be defined by subclassing QAbstractItemModel. This is the + best approach if you have a more complex model that cannot be supported + by the other approaches. A QAbstractItemModel can also automatically + notify a QML view when the model data has changed. + + The roles of a QAbstractItemModel subclass can be exposed to QML by calling + QAbstractItemModel::setRoleNames(). The default role names set by Qt are: + + \table + \header + \o Qt Role + \o QML Role Name + \row + \o Qt::DisplayRole + \o display + \row + \o Qt::DecorationRole + \o decoration + \endtable + + Here is an application with a QAbstractListModel subclass named \c AnimalModel + that has \i type and \i size roles. It calls QAbstractItemModel::setRoleNames() to set the + role names for accessing the properties via QML: + + \snippet examples/declarative/modelviews/abstractitemmodel/model.h 0 + \dots + \snippet examples/declarative/modelviews/abstractitemmodel/model.h 1 + \dots + \snippet examples/declarative/modelviews/abstractitemmodel/model.h 2 + \codeline + \snippet examples/declarative/modelviews/abstractitemmodel/model.cpp 0 + \codeline + \snippet examples/declarative/modelviews/abstractitemmodel/main.cpp 0 + \dots + + This model is displayed by a ListView delegate that accesses the \i type and \i size + roles: + + \snippet examples/declarative/modelviews/abstractitemmodel/view.qml 0 + + QML views are automatically updated when the model changes. Remember the model + must follow the standard rules for model changes and notify the view when + the model has changed by using QAbstractItemModel::dataChanged(), + QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for + more information. + + The complete example is available in Qt's \l {declarative/modelviews/abstractitemmodel}{examples/declarative/modelviews/abstractitemmodel} directory. + + QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML + can only display list data. + In order to display child lists of a hierarchical model + the VisualDataModel element provides several properties and functions for use + with models of type QAbstractItemModel: + + \list + \o \i hasModelChildren role property to determine whether a node has child nodes. + \o \l VisualDataModel::rootIndex allows the root node to be specified + \o \l VisualDataModel::modelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex + \o \l VisualDataModel::parentModelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex + \endlist + +\section1 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 +register the C++ model class as a QML type from a QML C++ plugin using +QDeclarativeExtensionPlugin. This would allow the model classes to be +created directly as elements within QML: + +\table +\row + +\o +\code +class MyModelPlugin : public QDeclarativeExtensionPlugin +{ +public: + void registerTypes(const char *uri) + { + qmlRegisterType<MyModel>(uri, 1, 0, + "MyModel"); + } +} + +Q_EXPORT_PLUGIN2(mymodelplugin, MyModelPlugin); +\endcode + +\o +\qml +MyModel { + id: myModel + ListElement { someProperty: "some value" } +} +\endqml + +\qml +ListView { + width: 200; height: 250 + model: myModel + delegate: Text { text: someProperty } +} +\endqml + +\endtable + +See \l {Tutorial: Writing QML extensions with C++} for details on writing QML C++ +plugins. + +*/ diff --git a/doc/src/declarative/codingconventions.qdoc b/doc/src/qml/codingconventions.qdoc index cbf10e6f03..89fdfd59f9 100644 --- a/doc/src/declarative/codingconventions.qdoc +++ b/doc/src/qml/codingconventions.qdoc @@ -27,15 +27,11 @@ /*! \page qml-coding-conventions.html -\inqmlmodule QtQuick 2 \title QML Coding Conventions +\brief code style convention This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow. -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 Through our documentation and examples, QML objects are always structured in the following order: diff --git a/doc/src/declarative/qdeclarativedebugging.qdoc b/doc/src/qml/debugging.qdoc index 6097130bd9..520e23abb5 100644 --- a/doc/src/declarative/qdeclarativedebugging.qdoc +++ b/doc/src/qml/debugging.qdoc @@ -26,9 +26,10 @@ ****************************************************************************/ /*! -\page qdeclarativedebugging.html -\inqmlmodule QtQuick 2 +\page qml-debugging.html +\ingroup qtquick-tools \title Debugging QML +\brief debugging tools in QML \section1 Console API @@ -37,11 +38,11 @@ \c console.log, console.debug, console.info, console.warn and console.error can be used to print debugging information to the console. For example: -\qml +\code function f(a, b) { console.log("a is ", a, "b is ", b); } -\endqml +\endcode The output is generated using the qDebug, qWarning, qCritical methods in C++ (see also http://doc.qt.nokia.com/latest/debug.html#warning-and-debugging-messages). @@ -67,7 +68,7 @@ function f() { \c console.time and console.timeEnd log the time (in milliseconds) that was spent between the calls. Both take a string argument that identifies the measurement. For example: -\qml +\code function f() { console.time("wholeFunction"); console.time("firstPart"); @@ -76,7 +77,7 @@ function f() { // second part console.timeEnd("wholeFunction"); } -\endqml +\endcode \section2 Trace @@ -107,7 +108,7 @@ without a previous call to console.profile will print a warning to the console. profiling client should have been attached before this call to receive and store the profiling data. For example: -\qml +\code function f() { console.profile(); //Call some function that needs to be profiled. @@ -115,7 +116,7 @@ function f() { //the profiling session. console.profileEnd(); } -\endqml +\endcode \section2 Exception @@ -133,12 +134,12 @@ click on the "Debugging" menu, then "Slow Down Animations". \section1 Debugging module imports The \c QML_IMPORT_TRACE environment variable can be set to enable debug output -from QML's import loading mechanisms. +from QML's import loading mechanisms. For example, for a simple QML file like this: \qml -import QtQuick 1.0 +import QtQuick 2.0 Rectangle { width: 100; height: 100 } \endqml @@ -147,8 +148,8 @@ If you set \c {QML_IMPORT_TRACE=1} before running the \l {QML Viewer} (or your QML C++ application), you will see output similar to this: \code -QDeclarativeImportDatabase::addImportPath "/qt-sdk/imports" -QDeclarativeImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS" +QDeclarativeImportDatabase::addImportPath "/qt-sdk/imports" +QDeclarativeImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS" QDeclarativeImportDatabase::addToImport 0x106237370 "." -1.-1 File as "" QDeclarativeImportDatabase::addToImport 0x106237370 "Qt" 4.7 Library as "" QDeclarativeImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle" diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/qml/dynamicobjects.qdoc index 466fb03d35..e3d9adb49a 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/qml/dynamicobjects.qdoc @@ -26,13 +26,10 @@ ****************************************************************************/ /*! -\page qdeclarativedynamicobjects.html -\inqmlmodule QtQuick 2 +\page qml-dynamicobjects.html \ingroup qml-features -\contentspage {QML Features} -\previouspage {Integrating QML Code with Existing Qt UI Code} -\nextpage {Network Transparency}{Loading Resources in QML} \title Dynamic Object Management in QML +\brief instantiating and managing QML objects QML provides a number of ways to dynamically create and manage QML objects. The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements @@ -63,16 +60,17 @@ at runtime. \section2 Creating a Component Dynamically To dynamically load a component defined in a QML file, call the -\l {QML:Qt::createComponent()}{Qt.createComponent()} function on the \l{QML Global Object}. +\l {QML:Qt::createComponent()}{Qt.createComponent()} function in the +\l {QmlGlobalQtObject}{Qt object}. This function takes the URL of the QML file as its only argument and creates a \l Component object from this URL. Once you have a \l Component, you can call its \l {Component::createObject()}{createObject()} method to create an instance of the component. This function can take one or two arguments: \list -\o The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is - recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass \c null to - this function. +\o The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is + recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass \c null to + this function. \o The second is optional and is a map of property-value items that define initial any property values for the item. Property values specified by this argument are applied to the object before its creation is finalized, avoiding binding errors that may occur if particular properties must be initialized to enable other property bindings. diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/qml/extending-tutorial.qdoc index cb02c790b0..00f4bb5691 100644 --- a/doc/src/declarative/extending-tutorial.qdoc +++ b/doc/src/qml/extending-tutorial.qdoc @@ -27,8 +27,8 @@ /*! \page qml-extending-tutorial-index.html -\inqmlmodule QtQuick 2 \title Tutorial: Writing QML Extensions with C++ +\brief tutorial about extending QML with Qt C++ The Qt Declarative module provides a set of APIs for extending QML through C++ extensions. You can write extensions to add your own QML types, extend existing @@ -207,7 +207,7 @@ Try out the example yourself with the updated code in Qt's \c examples/tutorials \example declarative/tutorials/extending/chapter3-bindings -Property bindings is a powerful feature of QML that allows values of different +Property binding is a powerful feature of QML that allows values of different elements to be synchronized automatically. It uses signals to notify and update other elements' values when property values are changed. @@ -455,7 +455,6 @@ be used by \c app.qml without import statements. /*! \page qml-extending-tutorial7.html -\inqmlmodule QtQuick 2 \title Chapter 7: In Summary In this tutorial, we've shown the basic steps for creating a QML extension: @@ -470,7 +469,7 @@ In this tutorial, we've shown the basic steps for creating a QML extension: \endlist -The \l {Extending QML Functionalities using C++} reference documentation shows +The \l{Extending QML with C++} reference documentation shows other useful features that can be added to QML extensions. For example, we could use \l{Default Property}{default properties} to allow slices to be added without using the \c slices property: @@ -492,7 +491,7 @@ Or randomly add and remove slices from time to time using \l{Property Value Sour \endcode -See the \l{Extending QML Functionalities using C++} reference documentation +See the \l{Extending QML with C++} reference documentation for more information. */ diff --git a/doc/src/qml/globalobject.qdoc b/doc/src/qml/globalobject.qdoc new file mode 100644 index 0000000000..26a974cf2e --- /dev/null +++ b/doc/src/qml/globalobject.qdoc @@ -0,0 +1,41 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qml-globalobject.html +\title QML Global Object +\brief the global functions included in the QML engine + +The QML engine provides several global objects. These global objects do not +need to be imported and provide basic functions to QML applications. + +\section1 QML Global Object + +Included in the \c{QtQuick 2.0} module is the \l{QmlGlobalQtObject}{Qt object}. +It contains several helpful functions that are available to elements and +components. + +*/ diff --git a/doc/src/declarative/integrating.qdoc b/doc/src/qml/integrating.qdoc index 1b51112c3d..7cd15a4fd4 100644 --- a/doc/src/declarative/integrating.qdoc +++ b/doc/src/qml/integrating.qdoc @@ -27,12 +27,9 @@ /*! \page qml-integration.html -\inqmlmodule QtQuick 2 \ingroup qml-features -\previouspage {Using QML Bindings in C++ Applications} -\nextpage {Dynamic Object Management in QML}{Dynamic Object Management} -\contentspage QML Features \title Integrating QML Code with Existing Qt UI Code +\brief applications with QML and Qt code There are a number of ways to integrate QML into QWidget-based UI applications, depending on the characteristics of your existing UI code. @@ -98,7 +95,7 @@ of QML UIs: \o QGraphicsScene::setItemIndexMethod(QGraphicsScene::NoIndex) \endlist -\section2 Loading QGraphicsWidget objects in QML +\section2 Loading QGraphicsWidget Objects in QML An alternative approach is to expose your existing QGraphicsWidget objects to QML and construct your scene in QML instead. See the \l {declarative-cppextensions-qgraphicslayouts.html}{graphics layouts example} @@ -106,7 +103,6 @@ which shows how to expose Qt's graphics layout classes to QML in order to use QGraphicsWidget with classes like QGraphicsLinearLayout and QGraphicsGridLayout. To expose your existing QGraphicsWidget classes to QML, use \l {qmlRegisterType()}. -See \l{Extending QML Functionalities using C++} for further information on -how to use C++ types in QML. - +See \l{Extending QML with C++} for further information on how to use C++ types +in QML. */ diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/qml/javascriptblocks.qdoc index eaad7bb77f..4cc98f1d7a 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/qml/javascriptblocks.qdoc @@ -26,25 +26,91 @@ ****************************************************************************/ /*! -\page qdeclarativejavascript.html -\inqmlmodule QtQuick 2 -\title Integrating JavaScript +\page qml-javascript.html +\ingroup qml-features +\title JavaScript Expressions in QML +\brief adding logic to QML applications with JavaScript -QML encourages building UIs declaratively, using \l {Property Binding} and the -composition of existing \l {QML Elements}. To allow the implementation of more -advanced behavior, QML integrates tightly with imperative JavaScript code. +\code + +This article is a work-in-progress. + +\endcode + +JavaScript adds logic to QML components. Properties can bind +to JavaScript expressions or reside inline in functions or signal handlers. The +\l{The QML Engine}{QML engine} will then interpret the expression to calculate new +property values or to execute a routine. + +The \l{JavaScript Runtime}{JavaScript runtime} can run valid standard +JavaScript constructs such as conditional operators, arrays, variable setting, +loops. In addition to the standard JavaScript properties, the \l {QML Global +Object} includes a number of helper methods that simplify building UIs and +interacting with the QML environment. -The JavaScript environment provided by QML is stricter than that in a web browser. -In QML you cannot add, or modify, members of the JavaScript global object. It -is possible to do this accidentally by using a variable without declaring it. In -QML this will throw an exception, so all local variables should be explicitly -declared. +The JavaScript environment provided by QML is stricter than that in a web +browser. In QML you cannot add, or modify, members of the JavaScript global +object. In regular JavaScript, it is possible to do this accidentally by using a +variable without declaring it. In QML this will throw an exception, so all local +variables should be explicitly declared. -In addition to the standard JavaScript properties, the \l {QML Global Object} -includes a number of helper methods that simplify building UIs and interacting -with the QML environment. -\section1 Inline JavaScript +\section1 Adding Logic + +The \l {QML Elements} provide a declarative way of creating and managing the +interface layout and scene. Binding properties or signal handlers to JavaScript +expressions adds logic to the QML application. + +Suppose that a button represented by a Rectangle element has a MouseArea and a +Text label. The MouseArea will call its \l{MouseArea::}{onPressed} handler when the user presses the defined interactive area. The QML engine will execute the +contents bound to the onPressed and onReleased handlers. Typically, a signal +handler is bound to JavaScript expressions to initiate other events or to simply +assign property values. + +\code +Rectangle { + id: button + width: 200; height: 80; color: "lightsteelblue" + + MouseArea { + id: mousearea + anchors.fill: parent + + onPressed: { + label.text = "I am Pressed!" + } + onReleased: { + label.text = "Click Me!" + } + + } + + Text { + id: label + anchors.centerIn: parent + text: "Press Me!" + } +} +\endcode + +During startup, the QML engine will set up and initialize the property +bindings. The JavaScript conditional operator is a valid property binding. + +\code +Rectangle { + id: colorbutton + width: 200; height: 80; + + color: mousearea.pressed ? "steelblue" : "lightsteelblue" + + MouseArea { + id: mousearea + anchors.fill: parent + } +} +\endcode + +\section2 Inline JavaScript Small JavaScript functions can be written inline with other QML declarations. These inline functions are added as methods to the QML element that contains @@ -67,12 +133,14 @@ Item { } \endcode +The factorial function will run whenever the MouseArea detects a clicked signal. + As methods, inline functions on the root element in a QML component can be invoked by callers outside the component. If this is not desired, the method can be added to a non-root element or, preferably, written in an external JavaScript file. -\section1 Separate JavaScript files +\section2 JavaScript files Large blocks of JavaScript should be written in separate files. These files can be imported into QML files using an \c import statement, in the same way @@ -91,61 +159,77 @@ Item { } \endcode -Both relative and absolute JavaScript URLs can be imported. In the case of a -relative URL, the location is resolved relative to the location of the -\l {QML Document} that contains the import. If the script file is not accessible, -an error will occur. If the JavaScript needs to be fetched from a network -resource, the component's \l {QDeclarativeComponent::status()}{status} is set to -"Loading" until the script has been downloaded. +For more information about loading external JavaScript files into QML, read +the section about \l{Importing JavaScript into QML}. -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. (This also means qualifiers cannot -be named the same as built-in JavaScript objects such as \c Date and \c Math). +\section1 JavaScript Expressions +The \l{JavaScript Runtime}{JavaScript runtime} run regular JavaScript +expressions as defined by the +\section2 Variables and Properties -\section2 Code-Behind Implementation Files +-variables +-basic data types +-values and assigning +-relate to property binding -Most JavaScript files imported into a QML file are stateful, logic implementations -for the QML file importing them. In these cases, for QML component instances to -behave correctly each instance requires a separate copy of the JavaScript objects -and state. +\section2 Conditional Loops +- for loops et al. +- conditional operator -The default behavior when importing JavaScript files is to provide a unique, isolated -copy for each QML component instance. The code runs in the same scope as the QML -component instance and consequently can can access and manipulate the objects and -properties declared. +\section2 Data Structures +- arrays +- object +- relate to the content below about valid JS scope, objects, etc. +- more advanced data types such as accessing QML list -\section2 Stateless JavaScript libraries +\section2 Functions +- function declaration +- function assignment (return values) +- function parameters +- connecting functions +- importing libraries, functions +- difference between JS functions and signals and QML methods +\section3 Receiving QML Signals in JavaScript -Some JavaScript files act more like libraries - they provide a set of stateless -helper functions that take input and compute output, but never manipulate QML -component instances directly. +To receive a QML signal, use the signal's \c connect() method to connect it to a JavaScript +function. -As it would be wasteful for each QML component instance to have a unique copy of -these libraries, the JavaScript programmer can indicate a particular file is a -stateless library through the use of a pragma, as shown in the following example. +For example, the following code connects the MouseArea \c clicked signal to the \c jsFunction() +in \c script.js: -\code -// factorial.js -.pragma library +\table +\row +\o \snippet doc/src/snippets/declarative/integrating-javascript/connectjs.qml 0 +\o \snippet doc/src/snippets/declarative/integrating-javascript/script.js 0 +\endtable -function factorial(a) { - a = parseInt(a); - if (a <= 0) - return 1; - else - return a * factorial(a - 1); -} -\endcode +The \c jsFunction() will now be called whenever MouseArea's \c clicked signal is emitted. -The pragma declaration must appear before any JavaScript code excluding comments. +See \l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} +{Connecting Signals to Methods and Signals} for more information. -As they are shared, stateless library files cannot access QML component instance -objects or properties directly, although QML values can be passed as function -parameters. +\section2 Advanced Usage +- using JS to access QML scene +- using JS for algorithms + - sorting, reordering lists +- how to modify other QML entities with JS + +\section1 Importing JavaScript into QML +Both relative and absolute JavaScript URLs can be imported. In the case of a +relative URL, the location is resolved relative to the location of the +\l {QML Document} that contains the import. If the script file is not accessible, +an error will occur. If the JavaScript needs to be fetched from a network +resource, the component's \l {QDeclarativeComponent::status()}{status} is set to +"Loading" until the script has been downloaded. + +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. (This also means qualifiers cannot +be named the same as built-in JavaScript objects such as \c Date and \c Math). + \section2 Importing One JavaScript File From Another If a JavaScript file needs to use functions defined inside another JavaScript file, @@ -207,6 +291,49 @@ for the purposes of backwards-compatibility. The third semantic remains unchanged from the current semantics for shared scripts, but is clarified here in respect to the newly possible case (where the script imports other scripts or modules). +\section2 Code-Behind Implementation Files + +Most JavaScript files imported into a QML file are stateful implementations +for the QML file importing them. In these cases, for QML component instances to +behave correctly each instance requires a separate copy of the JavaScript objects +and state. + +The default behavior when importing JavaScript files is to provide a unique, isolated +copy for each QML component instance. The code runs in the same scope as the QML +component instance and consequently can can access and manipulate the objects and +properties declared. + +\section2 Stateless JavaScript libraries + +Some JavaScript files act more like libraries - they provide a set of stateless +helper functions that take input and compute output, but never manipulate QML +component instances directly. + +As it would be wasteful for each QML component instance to have a unique copy of +these libraries, the JavaScript programmer can indicate a particular file is a +stateless library through the use of a pragma, as shown in the following example. + +\code +// factorial.js +.pragma library + +function factorial(a) { + a = parseInt(a); + if (a <= 0) + return 1; + else + return a * factorial(a - 1); +} +\endcode + +The pragma declaration must appear before any JavaScript code excluding comments. + +As they are shared, stateless library files cannot access QML component instance +objects or properties directly, although QML values can be passed as function +parameters. + + + \section1 Running JavaScript at Startup @@ -239,34 +366,6 @@ Likewise, the \l {Component::onDestruction} attached property is triggered on component destruction. -\section1 JavaScript and Property Binding - -Property bindings can be created in JavaScript by assigning the property with a \c function -that returns the required value. - -See \l {qml-javascript-assignment}{Property Assignment versus Property Binding} for details. - - -\section1 Receiving QML Signals in JavaScript - -To receive a QML signal, use the signal's \c connect() method to connect it to a JavaScript -function. - -For example, the following code connects the MouseArea \c clicked signal to the \c jsFunction() -in \c script.js: - -\table -\row -\o \snippet doc/src/snippets/declarative/integrating-javascript/connectjs.qml 0 -\o \snippet doc/src/snippets/declarative/integrating-javascript/script.js 0 -\endtable - -The \c jsFunction() will now be called whenever MouseArea's \c clicked signal is emitted. - -See \l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} -{Connecting Signals to Methods and Signals} for more information. - - \section1 QML JavaScript Restrictions QML executes standard JavaScript code, with the following restrictions: @@ -332,7 +431,7 @@ To run code after the environment setup has completed, refer to \o The value of \c this is currently undefined in QML in the majority of contexts -The \c this keyword is supported when binding properties from JavaScript. +The \c this keyword is supported when binding properties from JavaScript. In all other situations, the value of \c this is undefined in QML. diff --git a/doc/src/declarative/modules.qdoc b/doc/src/qml/modules.qdoc index f280bf10a2..f75c03301c 100644 --- a/doc/src/declarative/modules.qdoc +++ b/doc/src/qml/modules.qdoc @@ -26,11 +26,11 @@ ****************************************************************************/ /*! -\page qdeclarativemodules.html -\inqmlmodule QtQuick 2 -\title Modules -\section1 QML Modules +\page qml-modules.html +\title QML Modules +\brief creating and setting up QML modules +\section1 Modules 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, diff --git a/doc/src/declarative/network.qdoc b/doc/src/qml/network.qdoc index 667c81c775..15a17203c3 100644 --- a/doc/src/declarative/network.qdoc +++ b/doc/src/qml/network.qdoc @@ -26,13 +26,10 @@ ****************************************************************************/ /*! -\page qdeclarativenetwork.html -\inqmlmodule QtQuick 2 +\page qml-network.html \ingroup qml-features -\previouspage {Dynamic Object Management in QML}{Dynamic Object Management} -\nextpage {QML Internationalization}{Internationalization} -\contentspage QML Features -\title Network Transparency +\title Resource Loading and Network Transparency in QML +\brief about loading files and resources accross a network QML supports network transparency by using URLs (rather than file names) for all references from a QML document to other content. This means that anywhere a URL source is expected, @@ -157,5 +154,83 @@ More specifically: \o \c{import libraryUrl as U} works network transparently \endlist +\section1 XMLHttpRequest + +\target XMLHttpRequest + +QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain +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 policy. +\i QML's XMLHttpRequest does not support \i synchronous requests. +\endlist + +Additionally, the \c responseXML XML DOM tree currently supported by QML is a reduced subset +of the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web +browser. The following objects and properties are supported by the QML implementation: + +\table +\header +\o \bold {Node} +\o \bold {Document} +\o \bold {Element} +\o \bold {Attr} +\o \bold {CharacterData} +\o \bold {Text} + +\row +\o +\list +\o nodeName +\o nodeValue +\o nodeType +\o parentNode +\o childNodes +\o firstChild +\o lastChild +\o previousSibling +\o nextSibling +\o attributes +\endlist + +\o +\list +\o xmlVersion +\o xmlEncoding +\o xmlStandalone +\o documentElement +\endlist + +\o +\list +\o tagName +\endlist + +\o +\list +\o name +\o value +\o ownerElement +\endlist + +\o +\list +\o data +\o length +\endlist + +\o +\list +\o isElementContentWhitespace +\o wholeText +\endlist + +\endtable + +The \l{declarative/xml/xmlhttprequest}{XMLHttpRequest example} demonstrates how to +use the XMLHttpRequest object to make a request and read the response headers. */ diff --git a/doc/src/declarative/qdeclarativeperformance.qdoc b/doc/src/qml/performance.qdoc index 3caaff064c..88437a81d4 100644 --- a/doc/src/declarative/qdeclarativeperformance.qdoc +++ b/doc/src/qml/performance.qdoc @@ -27,8 +27,8 @@ /*! \page qtquick2-performance.html -\inqmlmodule QtQuick 2 \title QML Performance +\brief performance issues and suggestions \tableofcontents diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/qml/propertybinding.qdoc index b470b16253..b89b3d7a61 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/qml/propertybinding.qdoc @@ -26,18 +26,15 @@ ****************************************************************************/ /*! -\page propertybinding.html -\inqmlmodule QtQuick 2 +\page qml-properties.html \ingroup qml-features -\contentspage QML Features -\previouspage {QML Basic Types}{Data Types} -\nextpage {Using QML Positioner and Repeater Items}{Component Layouts} -\title Property Binding +\title Properties and Property Binding in QML +\brief declaring and binding properties \section1 Properties QML components have \i properties that can be read and modified by other objects. -In QML, properties serve many purposes but their main function is to bind to +In QML, properties serve many purposes but their main function is to hold to values. Values may be a \l{QML Basic Types}{basic type}, or other QML elements. The syntax for properties is: @@ -100,8 +97,63 @@ Assigning a value to a property that is already bound will remove the previous b A property can only have one value at a time (a list of property is one value), and if any code explicitly re-sets this value, the property binding is removed. -There is no way to create a property binding directly from imperative JavaScript code, -although it is possible to use the \l {Using the Binding Element}{Binding} element. +\section1 Binding to JavaScript Functions + +The \c{property : value} syntax for property binding is QML-specific and cannot +be used in JavaScript. Instead, to bind a property from JavaScript, assign a \c +function to the property that returns the required value. The following code +correctly creates +the binding in JavaScript rather than QML: + +\qml +Item { + width: 100 + + Component.onCompleted: { + height = (function() { return width * 2 }) + } +} +\endqml + +When creating a property binding from JavaScript, QML allows the use of the \c +this keyword to refer to the object to which the property binding will be +assigned. This allows one to explicitly refer to a property within an object +when there may be ambiguity about the exact property that should be used for the +binding. + +For example, the \c Component.onCompleted handler below is defined within the +scope of the \l Item, and references to \c width within this scope would refer +to the \l Item's width, rather than that of the \l Rectangle. To bind the \l +Rectangle's \c height to its own \c width, the function needs to explicitly +refer to \c this.width rather than just \c width. Otherwise, the height of the +\l Rectangle would be bound to the width of the \l Item and not the \l +Rectangle. + +\qml +Item { + width: 500 + height: 500 + + Rectangle { + id: rect + width: 100 + color: "yellow" + } + + Component.onCompleted: { + rect.height = (function() { return this.width * 2 }) + } +} +\endqml + +In this case, the function could also have referred to \c rect.width rather than +\c this.width. + +Note that the value of \c this is not defined outside of its use in property binding. +See \l {QML JavaScript Restrictions} for details. + +The \l{Binding} element provides more control for binding properties with +JavaScript code. \section1 Types of Properties @@ -122,21 +174,6 @@ Certain properties bind to more complex types such as other elements and objects Basic types such as \l int, \l real, and other Qt structures may be bound to properties. For a list of types, visit the \l {QML Basic Types} document. -\keyword qml-id-property -\section2 The \c id Property - -Each QML object may be given a special unique property called an \c id. -No other object within the same QML component (see \l{QML Documents}) can have -the same \c id value. QML objects may then access an object using the \c id -property. -\snippet doc/src/snippets/declarative/properties.qml id property -A component may readily access its parent's properties by using the \c parent -property. - -Note that an \c id must begin with a lower-case letter or an underscore. The -\c id cannot contain characters other than letters, numbers, underscores, and -\l {JavaScript Reserved Words}{JavaScript reserved words}. - \section2 Elements and Objects as Property Values Many properties bind to objects. For example, the \l Item element has a @@ -309,8 +346,9 @@ a tab effect. In some advanced cases, it may be necessary to create bindings explicitly with the\l Binding element. -For example, to bind a property exposed from C++ (\c system.brightness) to a -value written in QML (\c slider.value), you could use the \l Binding element as +For example, to bind a property exposed from the \l{The QML Engine}{declarative +runtime} or \l{QmlGlobalQtObject}{Qt object}, such as the \c system.brightness +property, to a value written in QML, you could use the \l Binding element as follows: \snippet doc/src/snippets/declarative/properties.qml binding element diff --git a/doc/src/declarative/qmlreusablecomponents.qdoc b/doc/src/qml/qmlcomponents.qdoc index a81588e137..bcc465f4b2 100644 --- a/doc/src/declarative/qmlreusablecomponents.qdoc +++ b/doc/src/qml/qmlcomponents.qdoc @@ -26,40 +26,57 @@ ****************************************************************************/ /*! -\page qmlreusablecomponents.html -\inqmlmodule QtQuick 2 +\page qml-components.html \ingroup qml-features -\previouspage {QML Signal and Handler Event System}{Signal and Handler Event System} -\nextpage {QML States}{States} -\contentspage QML Features +\contentspage QML Reference -\title Importing Reusable Components +\title QML Components +\brief creating and instantiating components -A \i component is an instantiable QML definition, typically contained in a -\c .qml file. For instance, a Button \i component may be defined in -\c Button.qml. The QML runtime may instantiate this Button component to create -Button \i objects. Alternatively, a component may be defined inside a -\l Component element. +A \i component is an instantiable QML definition, typically contained in a \c +.qml file. For instance, a Button \i component may be defined in \c Button.qml +file. The \l{The QML Engine}{QML engine} may instantiate this Button +component to create Button \i objects. Alternatively, a component may be defined +inside a \l Component element. Moreover, the Button definition may also contain other components. A Button -component could use a Text element for its label and other components to +component might have a Text element for its label and other components to implement its functions. Compounding components to form new components -(and effectively new interfaces) is the emphasis in QML. +is the emphasis in QML. \keyword qml-define-components \section1 Defining New Components Any snippet of QML code may become a component, by placing the code in a QML -file (extension is \c .qml). A complete Button component that responds to user -input may be in a Button.qml file. +file, whose file extension is \c .qml). A complete Button component that +responds to user input may be in a Button.qml file. \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml document +The component name, \c Button, matches the QML filename, \c Button.qml. +Also, the first character is in upper case. Matching the names allow +components in the same directory to be in the direct import path of the +application. The section on \l{Importing a Component} has information about +naming components with different filenames. + Alternatively, a \l Component element may encapsulate a QML object to form a component. \snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent begin \snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component \snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent end + +Components may incorporate any \l{Qt Quick}{QML feature} such as: +\list +\o \l{Property Binding in QML}{Properties} - for binding to data and functions +\o \l{JavaScript Expressions in QML}{JavaScript functions} - for performing routines and logic +\o \l{QML Signal and Handler Event System}{Signals and handlers} - t notify other +objects about events +\o \l{QML States}{States} and \l{QML Animation and Transitions}{Transitions} +\o many others +\endlist +For information about these features, visit the respective overviews or the +main Qt Quick \l{Qt Quick}{reference} page. + \keyword qml-loading-components \section1 Loading a Component @@ -80,9 +97,9 @@ components in the same directory to be in the direct import path of the application. For flexibility, a \c qmldir file is for dictating which additional components, -plugins, or directories should be imported. By using a \c qmldir file, -component names do not need to match the filenames. The \c qmldir file should, -however, be in an imported path. +plugins, or directories should be imported. By using a \c qmldir file, component +names do not need to match the filenames. The \c qmldir file should, however, be +in an imported path. \snippet doc/src/snippets/declarative/reusablecomponents/qmldir document \section2 Loading an Inline Component @@ -90,7 +107,7 @@ however, be in an imported path. A consequence of inline components is that initialization may be deferred or delayed. A component may be created during a MouseArea event or by using a \l Loader element. The component can create an object, which is addressable in a -similar way as an \l {qml-id-property}{id property}. Thus, the created object may +similar way as an \l {qml-id}{identifier}. Thus, the created object may have its bindings set and read like a normal QML object. \snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component \snippet doc/src/snippets/declarative/reusablecomponents/component.qml create inline component @@ -141,6 +158,21 @@ to be exposed. \snippet doc/src/snippets/declarative/reusablecomponents/focusbutton.qml document +\keyword qml-id +\section2 The Object Identifier + +Each QML object may be given a special unique identifier called an \c id. +No other object within the same QML component (see \l{QML Documents}) can have +the same \c id value. QML objects may then access an object using the \c id +property. +\snippet doc/src/snippets/declarative/properties.qml id property +A component may readily access its parent's properties by using the \c parent +property. + +Note that an \c id must begin with a lower-case letter or an underscore. The +\c id cannot contain characters other than letters, numbers, underscores, and +\l {JavaScript Reserved Words}{JavaScript reserved words}. + \section2 Child Components Objects or Items declared within a component can be made accessible by binding their id to a @@ -159,3 +191,4 @@ If a property of type \c Text was used instead of an alias in this instance ther guarantee that \c label would be initialized before the binding was attempted which would cause the binding to fail. */ + diff --git a/doc/src/declarative/qmldate.qdoc b/doc/src/qml/qmldate.qdoc index 7ac200db46..7ac200db46 100644 --- a/doc/src/declarative/qmldate.qdoc +++ b/doc/src/qml/qmldate.qdoc diff --git a/doc/src/qml/qmldocument.qdoc b/doc/src/qml/qmldocument.qdoc new file mode 100644 index 0000000000..fedeba35e1 --- /dev/null +++ b/doc/src/qml/qmldocument.qdoc @@ -0,0 +1,151 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-documents.html +\title QML Documents +\brief a description of QML documents and the kind of content they contain + +A QML document is a block of QML source code. QML documents generally correspond to files +stored on a disk or at a location on a network, but they can also be constructed directly +from text data. + +Here is a simple QML document: + +\snippet doc/src/snippets/declarative/qml-documents/non-trivial.qml document + +QML documents are always encoded in UTF-8 format. + +A QML document always begins with one or more import statements. To prevent elements +introduced in later versions from affecting existing QML programs, the element types +available within a document are controlled by the imported QML \l {Modules} with +a corresponding \i version. + +QML does \i not have a preprocessor that modifies the document prior to +presentation to the \l{The QML Engine}{QML engine}, unlike C or C++. +The \c import statements do not copy and prepend the code in the document, but +instead instruct the QML engine on how to resolve type references found +in the document. Any type reference present in a QML document - such as \c +Rectangle and \c ListView - including those made within an \l {Inline +JavaScript}{JavaScript block} or \l {Property Binding in QML}{property +bindings}, are \i resolved based exclusively on the import statements. At least +one \c import statement must be present such as \c{import QtQuick 2.0}. + +Each \c id value in a QML document must be unique within that document. They do +not need to be unique across different documents as id values are resolved +according to the document scope. + +\section1 Documents as Component Definitions + +A QML document defines a single, top-level \l {QML Components}{QML component}. A +QML component is a template that is interpreted by the QML engine to +create an object with some predefined behaviour. As it is a template, a single +QML component can be "run" multiple times to produce several objects, each of +which are said to be \i instances of the component. + +Once created, instances are not dependent on the component that created them, so +they can operate on independent data. Here is an example of a simple "Button" +component (defined in a \c Button.qml file) that is instantiated four times by +\c application.qml. Each instance is created with a different value for its \c +text property: + +\table +\row +\o Button.qml +\o application.qml + +\row +\o \snippet doc/src/snippets/declarative/qml-documents/qmldocuments.qml document +\o +\qml +import QtQuick 2.0 + +Column { + spacing: 10 + + Button { text: "Apple" } + Button { text: "Orange" } + Button { text: "Pear" } + Button { text: "Grape" } +} +\endqml + +\image anatomy-component.png + +\endtable + +Any snippet of QML code can become a component, just by placing it in the file +"<Name>.qml" where <Name> is the component name, and begins with an \bold +uppercase letter. Note that the case of all characters in the <Name> are +significant on some filesystems, notably UNIX filesystems. It is recommended +that the case of the filename matches the case of the component name in QML +exactly, regardless of the platform the QML will be deployed to. These QML +component files automatically become available as new QML element types to other +QML components and applications in the same directory. + +The \l{QML Components} article details the creation of components and how to +load them in other components. + +\section1 Inline Components + +In addition to the top-level component that all QML documents define, and any +reusable components placed in separate files, documents may also include \i +inline components. Inline components are declared using the \l Component +element, as can be seen in the first example above. Inline components share all +the characteristics of regular top-level components and use the same \c import +list as their containing QML document. Components are one of the most basic +building blocks in QML, and are frequently used as "factories" by other +elements. For example, the \l ListView element uses the \c delegate component as +the template for instantiating list items - each list item is just a new +instance of the component with the item specific data set appropriately. + +Like other \l {QML Elements}, the \l Component element is an object and must be +assigned to a property. \l Component objects may also have an object id. In the +first example on this page, the inline component is added to the \l Rectangle's +\c resources list, and then \l {Property Binding} is used to assign the \l +Component to the \l ListView's \c delegate property. The QML language even +contains a syntactic optimization when assigning directly to a component +property for this case where it will automatically insert the \l Component tag. +This means that by enclosing components in a \c Component element, we can +assign an id to the component and use the component elsewhere + +These final two examples perform identically to the original document. + +\table +\row +\o +\snippet doc/src/snippets/declarative/qml-documents/inline-component.qml document +\o +\snippet doc/src/snippets/declarative/qml-documents/inline-text-component.qml document +\endtable + + +For information about components, the \l{QML Components} article details the +creation of components and how to load them in other components. + +\sa QDeclarativeComponent +*/ diff --git a/doc/src/qml/qmlengine.qdoc b/doc/src/qml/qmlengine.qdoc new file mode 100644 index 0000000000..3e8ef1ae3f --- /dev/null +++ b/doc/src/qml/qmlengine.qdoc @@ -0,0 +1,477 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\target qmlengine +\page qmlengine.html +\ingroup qml-features +\title The QML Engine +\brief the engine runs QML applications + +The QML engine runs and executes QML +applications. The engine loads, instantiates, and executes the QML context as +specified in QML files, plugins, or applications. + +\section1 Core Module Classes + + The \l{QtDeclarative}{Qt Declarative} module provides a set of C++ APIs for + extending your QML applications from C++ and embedding QML into C++ + applications. There are several core classes in the Qt Declarative module + that provide the essential capabilities for doing this. These are: + + \list + \o QDeclarativeEngine: A QML engine provides the environment for executing QML code. Every + application requires at least one engine instance. + \o QDeclarativeComponent: A component encapsulates QML information. + \o QDeclarativeContext: A context allows an application to expose data to + the QML components created by an engine. + \endlist + + The Qt Declarative module consists of the engine, + context, component encapsulation, and visual items. + + \list + \o QQuickItem + \o QQuickPaintedItem + \o QQuickView + \endlist + + \section2 Declarative Engine + A QDeclarativeEngine allows the configuration of global settings that + apply to all of its QML component instances: for example, the + QNetworkAccessManager to be used for network communications, and the + file path to be used for persistent storage. + + QDeclarativeComponent is used to load QML documents. Each + QDeclarativeComponent instance represents a single document. A component + can be created from the URL or file path of a QML document, or the raw + QML code of the document. Component instances are instatiated through + the QDeclarativeComponent::create() method, like this: + + \code + QDeclarativeEngine engine; + QDeclarativeComponent component(&engine, QUrl::fromLocalFile("MyRectangle.qml")); + QObject *rectangleInstance = component.create(); + + // ... + delete rectangleInstance; + \endcode + + QML documents can also be loaded using QDeclarativeView. This class + provides a convenient QWidget-based view for embedding QML components + into QGraphicsView-based applications. (For other methods of integrating + QML into QWidget-based applications, see \l {Integrating QML Code with + existing Qt UI code}.) + +\section1 Engine and Context Initialization + + \section2 Loading QML Components from C++ + + A QML document can be loaded with QDeclarativeComponent or QDeclarativeView. + QDeclarativeComponent loads a QML component as a C++ object; + QDeclarativeView also does this, but additionally loads the QML component + directly into a QGraphicsView. It is convenient for loading a displayable + QML component into a QWidget-based application. + + For example, suppose there is a \c MyItem.qml file that looks like this: + + \snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml start + \snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml end + + This QML document can be loaded with QDeclarativeComponent or + QDeclarativeView with the following C++ code. Using a QDeclarativeComponent + requires calling QDeclarativeComponent::create() to create a new instance of + the component, while a QDeclarativeView automatically creates an instance of + the component, which is accessible via QDeclarativeView::rootObject(): + + \table + \row + \o + \snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeComponent-a + \dots 0 + \snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeComponent-b + \o + \snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeView + \endtable + + This \c object is the instance of the \c MyItem.qml component that has been + created. You can now modify the item's properties using + QObject::setProperty() or QDeclarativeProperty: + + \snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp properties + + Alternatively, you can cast the object to its actual type and call functions + with compile-time safety. In this case the base object of \c MyItem.qml is + an \l Item, which is defined by the QDeclarativeItem class: + + \snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp cast + + You can also connect to any signals or call functions defined in the + component using QMetaObject::invokeMethod() and QObject::connect(). See \l + {Exchanging data between QML and C++} below for further details. + + \section3 Locating child objects + + QML components are essentially object trees with children that have siblings + and their own children. Child objects of QML components can be located using + the QObject::objectName property with QObject::findChild(). For example, if + the root item in \c MyItem.qml had a child \l Rectangle item: + + \snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml start + \codeline + \snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml child + \snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml end + + The child could be located like this: + + \snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp findChild + + If \c objectName is used inside a delegate of a ListView, \l Repeater or + some other element that creates multiple instances of its delegates, there + will be multiple children with the same \c objectName. In this case, + QObject::findChildren() can be used to find all children with a matching \c + objectName. + + \warning While it is possible to use C++ to access and manipulate QML + objects deep into the object tree, we recommend that you do not take this + approach outside of application testing and prototyping. One strength of QML + and C++ integration is the ability to implement the QML user interface + separately from the C++ logic and dataset backend, and this strategy breaks + if the C++ side reaches deep into the QML components to manipulate them + directly. This would make it difficult to, for example, swap a QML view + component for another view, if the new component was missing a required \c + objectName. It is better for the C++ implementation to know as little as + possible about the QML user interface implementation and the composition of + the QML object tree. + + + \section2 Embedding C++ Objects into QML Components + + When loading a QML scene into a C++ application, it can be useful to + directly embed C++ data into the QML object. QDeclarativeContext enables + this by exposing data to the context of a QML component, allowing data to be + injected from C++ into QML. + + For example, here is a QML item that refers to a \c currentDateTime value + that does not exist in the current scope: + + \snippet doc/src/snippets/declarative/qtbinding/context/MyItem.qml 0 + + This \c currentDateTime value can be set directly by the C++ application + that loads the QML component, using + QDeclarativeContext::setContextProperty(): + + \snippet doc/src/snippets/declarative/qtbinding/context/main.cpp 0 + + Context properties can hold either QVariant or QObject* values. This means + custom C++ objects can also be injected using this approach, and these + objects can be modified and read directly in QML. Here, we modify the above + example to embed a QObject instance instead of a QDateTime value, and the + QML code invokes a method on the object instance: + + \table + \row + \o + \snippet doc/src/snippets/declarative/qtbinding/context-advanced/applicationdata.h 0 + \codeline + \snippet doc/src/snippets/declarative/qtbinding/context-advanced/main.cpp 0 + \o + \snippet doc/src/snippets/declarative/qtbinding/context-advanced/MyItem.qml 0 + \endtable + + (Note that date/time values returned from C++ to QML can be formatted through + \l{QML:Qt::formatDateTime}{Qt.formatDateTime()} and associated functions.) + + If the QML item needs to receive signals from the context property, it can + connect to them using the \l Connections element. For example, if \c + ApplicationData has a signal named \c dataChanged(), this signal can be + connected to using an \c onDataChanged handler within a \l Connections + object: + + \snippet doc/src/snippets/declarative/qtbinding/context-advanced/connections.qml 0 + + Context properties can be useful for using C++ based data models in a QML view. See the + \l {declarative/modelviews/stringlistmodel}{String ListModel}, + \l {declarative/modelviews/objectlistmodel}{Object ListModel} and + \l {declarative/modelviews/abstractitemmodel}{AbstractItemModel} models for + respective examples on using QStringListModel, QObjectList-based models and QAbstractItemModel + in QML views. + + Also see the QDeclarativeContext documentation for more information. + + +\section1 Invoking QML Entities through the Engine + + QML and C++ objects can communicate with one another through signals, slots + and property modifications. For a C++ object, any data that is exposed to + Qt's \l{The Meta-Object System}{Meta-Object System} that is, properties, + signals, slots and Q_INVOKABLE methods - become available to QML. On the QML + side, all QML object data is automatically made available to the meta-object + system and can be accessed from C++. + + The \l{Creating QML Types} article covers the topic of exposing Qt functions + and properties to the declarative engine. + + \section2 Calling Functions + + QML functions can be called from C++ and vice-versa. + + All QML functions are exposed to the meta-object system and can be called + using QMetaObject::invokeMethod(). Here is a C++ application that uses this + to call a QML function: + + \table + \row + \o \snippet doc/src/snippets/declarative/qtbinding/functions-qml/MyItem.qml 0 + \o \snippet doc/src/snippets/declarative/qtbinding/functions-qml/main.cpp 0 + \endtable + + Notice the Q_RETURN_ARG() and Q_ARG() arguments for + QMetaObject::invokeMethod() must be specified as QVariant types, as this is + the generic data type used for QML functions and return values. + + To call a C++ function from QML, the function must be either a Qt slot, or a + function marked with the Q_INVOKABLE macro, to be available to QML. In the + following example, the QML code invokes methods on the \c myObject object, + which has been set using QDeclarativeContext::setContextProperty(): + + \table + \row + \o + \snippet doc/src/snippets/declarative/qtbinding/functions-cpp/MyItem.qml 0 + \o + \snippet doc/src/snippets/declarative/qtbinding/functions-cpp/myclass.h 0 + \codeline + \snippet doc/src/snippets/declarative/qtbinding/functions-cpp/main.cpp 0 + \endtable + + 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. 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(), so that the \c + cppSlot() method is called whenever the \c qmlSignal is emitted: + + \table + \row + \o + \snippet doc/src/snippets/declarative/qtbinding/signals-qml/MyItem.qml 0 + \o + \snippet doc/src/snippets/declarative/qtbinding/signals-qml/myclass.h 0 + \codeline + \snippet doc/src/snippets/declarative/qtbinding/signals-qml/main.cpp 0 + \endtable + + To connect to Qt C++ signals from within QML, use a signal handler with the + \c on<SignalName> syntax. If the C++ object is directly creatable from + within QML (see \l {Defining new QML elements} above) then the signal + handler can be defined within the object declaration. In the following + example, the QML code creates a \c ImageViewer object, and the \c + imageChanged and \c loadingError signals of the C++ object are connected to + through \c onImagedChanged and \c onLoadingError signal handlers in QML: + + \table + \row + \o + + \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/imageviewer.h start + \dots 4 + \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/imageviewer.h end + + \o + \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/standalone.qml 0 + \endtable + + (Note that if a signal has been declared as the NOTIFY signal for a + property, QML allows it to be received with an \c on<Property>Changed + handler even if the signal's name does not follow the \c <Property>Changed + naming convention. In the above example, if the "imageChanged" signal was + named "imageModified" instead, the \c onImageChanged signal handler would + still be called.) + + If, however, the object with the signal is not created from within the QML + code, and the QML item only has a reference to the created object - for + example, if the object was set using + QDeclarativeContext::setContextProperty() - then the \l Connections element + can be used instead to create the signal handler: + + \table + \row + \o \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/main.cpp connections + \o \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/MyItem.qml 0 + \endtable + + C++ signals can use enum values as parameters provided that the enum is + declared in the class that is emitting the signal, and that the enum is + registered using Q_ENUMS. See \l {Using enumerations of a custom type} below + for details. + + + \section2 Modifying Properties + + Any properties declared in a QML object are automatically accessible from + C++. Given a QML item like this: + + \snippet doc/src/snippets/declarative/qtbinding/properties-qml/MyItem.qml 0 + + The value of the \c someNumber property can be set and read using + QDeclarativeProperty, or QObject::setProperty() and QObject::property(): + + \snippet doc/src/snippets/declarative/qtbinding/properties-qml/main.cpp 0 + + You should always use QObject::setProperty(), QDeclarativeProperty or + QMetaProperty::write() to change a QML property value, to ensure the QML + engine is made aware of the property change. For example, say you have a + custom element \c PushButton with a \c buttonText property that internally + reflects the value of a \c m_buttonText member variable. Modifying the + member variable directly like this is not a good idea: + + \badcode + // BAD! + QDeclarativeComponent component(engine, "MyButton.qml"); + PushButton *button = qobject_cast<PushButton*>(component.create()); + button->m_buttonText = "Click me"; + \endcode + Since the value is changed directly, this bypasses Qt's \l{The Meta-Object + System}{meta-object system} and the QML engine is not made aware of the + property change. This means property bindings to \c buttonText would not be + updated, and any \c onButtonTextChanged handlers would not be called. + + \target properties-cpp + + Any \l {The Property System}{Qt properties} - that is, those declared with + the Q_PROPERTY() macro - are accessible from QML. Here is a modified version + of the \l {Embedding C++ objects into QML components}{earlier example} on + this page; here, the \c ApplicationData class has a \c backgroundColor + property. This property can be written to and read from QML: + + \table + \row + \o \snippet doc/src/snippets/declarative/qtbinding/properties-cpp/applicationdata.h 0 + \o \snippet doc/src/snippets/declarative/qtbinding/properties-cpp/MyItem.qml 0 + \endtable + + Notice the \c backgroundColorChanged signal is declared as the NOTIFY signal + for the \c backgroundColor property. If a Qt property does not have an + associated NOTIFY signal, the property cannot be used for \l{Property + Binding in QML}, as the QML engine would not be notified when the value + changes. If you are using custom types in QML, make sure their properties + have NOTIFY signals so that they can be used in property bindings. + + The \l{Creating QML Types} article covers the topic of exposing Qt + properties to the runtime. For more information, the + \l{Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++} + tutorial demonstrates basic usage patterns. + +\section1 Loading QML Plugins + + Additional Qt code is runnable in the engine as a QML plugin. The \l{QML + Plugins} article covers the creation and usage patterns of QML plugins. The + QDeclarativeExtensionPlugin class is an abstract class for writing QML + plugins. The \l {How to Create Qt Plugins} contains more information about + Qt's plugin system. + +\target qml-engine-optimization +\section1 Optimization + + Often, to develop high performance elements it is helpful to know more about + the status of the QML engine. For example, it might be beneficial to delay + initializing some costly data structures until after all the properties have + been set. + + The QML engine defines an interface class called QDeclarativeParserStatus, + which contains a number of virtual methods that are invoked at various + stages during component instantiation. To receive these notifications, an + element implementation inherits QDeclarativeParserStatus and notifies the Qt + meta system using the Q_INTERFACES() macro. + + \code + class Example : public QObject, public QDeclarativeParserStatus + { + Q_OBJECT + Q_INTERFACES(QDeclarativeParserStatus) + public: + virtual void componentComplete() + { + qDebug() << "Woohoo! Now to do my costly initialization"; + } + }; + \endcode + +\section1 Memory Management and QVariant types + + It is a component's responsibility to ensure that it does not access or + return pointers to invalid objects. QML makes the following guarentees: + + \list + \o An object assigned to a QObject (or QObject-derived) pointer property + will be valid at the time of assignment. + + Following assignment, it is the responsibility of the class to subsequently + guard this pointer, either through a class specific method or the generic + QPointer class. + + \o An object assigned to a QVariant will be valid at the time of assignment. + + When assigning an object to a QVariant property, QML will always use a + QMetaType::QObjectStar typed QVariant. It is the responsibility of the class + to guard the pointer. A general rule when writing a class that uses QVariant + properties is to check the type of the QVariant when it is set and if the + type is not handled by your class, reset it to an invalid variant. + + \o An object assigned to a QObject (or QObject-derived) list property will + be valid at the time of assignment. + + Following assignment, it is the responsibility of the class to subsequently + guard this pointer, either through a class specific method or the generic + QPointer class. + \endlist + + Components should assume that any QML assigned object can be deleted at any + time, and respond accordingly. If documented as such an element need not + continue to work in this situation, but it must not crash. + +\section1 JavaScript Runtime + + The runtime implements the \l{ECMA-262}{ECMAScript Language Specification} standard. + The reserved words, conditionals, variables, and object behaviors follow + after the standard. + + The \l{JavaScript Code} article has information about placing JavaScript + code within QML code. + +*/ diff --git a/doc/src/declarative/qmlevents.qdoc b/doc/src/qml/qmlevents.qdoc index 1835b1ddbc..f29b2f260b 100644 --- a/doc/src/declarative/qmlevents.qdoc +++ b/doc/src/qml/qmlevents.qdoc @@ -27,17 +27,21 @@ /*! \page qmlevents.html -\inqmlmodule QtQuick 2 \ingroup qml-features -\contentspage QML Features -\previouspage {Keyboard Focus in QML}{Keyboard Focus} -\nextpage Importing Reusable Components \title QML Signal and Handler Event System +\brief the event sytem in QML -QML utilizes Qt's \l{The Meta-Object System}{meta-object} and -\l{Signals & Slots}{signals} systems. Signals and slots created using Qt in C++ -are inheritely valid in QML. +Application and user interface components communicate with each other. For +example, a button component needs to know that the user is clicking on it. +The button may change colors to indicate its state or perform some logic. As +well, application needs to know whether the user is clicking the button. The +application may need to relay this clicking event to other applications. + +QML has a signal and handler mechanism, where the \i signal is the event +and the component responds to the event through the \i handler. The signal +is emitted and the handler is invoked. Placing logic such as scripts or other +operations in the handler allows the component to respond to the event. \keyword qml-signals-and-handlers \section1 Signals and Handlers @@ -85,10 +89,9 @@ Note that the \c Component.onCompleted is an Signal objects have a \c connect() method to a connect a signal either to a method or another signal. When a signal is connected to a method, the method is -automatically invoked whenever the signal is emitted. (In Qt terminology, the -method is a \i slot that is connected to the \i signal; all methods defined in -QML are created as \l{Signals & Slots}{Qt slots}.) This enables a signal -to be received by a method instead of a \l {Signal Handlers}{signal handler}. +automatically invoked whenever the signal is emitted. This mechanism enables a +signal to be received by a method instead of a +\l {Signal Handlers}{signal handler}. \snippet doc/src/snippets/declarative/events.qml connect method The \c {connect()} method is appropriate when connecting a JavaScript method to @@ -113,16 +116,15 @@ output: Send clicked \endcode -\section1 C++ Additions - -Because QML uses Qt, a signal defined in C++ also works as a QML signal. The -signal may be emitted in QML code or called as a method. In addition, the QML -runtime automatically creates signal handlers for the C++ signals. For more -signal control, the \c connect() method and the \l Connections element may connect -a C++ signal to another signal or method. +\section1 Events from the Declarative Runtime -For complete information on how to call C++ functions in QML, read the -\l{Extending QML - Signal Support Example}. +There maybe cases where a signal comes from the \l{The QML Engine}{declarative +runtime}. For example, it is possible to receive events from \l{QML Plugins}{QML +plugins}. For more signal control, the \c connect() method and the \l +Connections element may connect a signal from the runtime to another signal or +method. +For complete information on events from the runtime or creating signals from the +runtime, read the \l{The QML Engine} and the \l{Creating QML Types} articles. */ diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/qml/qmli18n.qdoc index b4faa011aa..4e546c7ed4 100644 --- a/doc/src/declarative/qdeclarativei18n.qdoc +++ b/doc/src/qml/qmli18n.qdoc @@ -26,13 +26,10 @@ ****************************************************************************/ /*! -\page qdeclarativei18n.html -\inqmlmodule QtQuick 2 +\page qml-i18n.html \ingroup qml-features -\contentspage QML Features -\previouspage {Network Transparency}{Loading Resources in QML} -\nextpage {QML Features} \title QML Internationalization +\brief translating texts in QML \section1 Translation @@ -92,7 +89,7 @@ Localization is the process of adapting to local conventions, for example presenting dates and times using the locally preferred formats. Qt Quick supports localization via the \l {QtQuick2::Locale}{Locale} object and extensions to the -ECMAScript \l {QtQuick2::Date}{Date} and \l {QtQuick2::Number}{Number} types. +\l{ECMA-262}{ECMAScript} \l {QtQuick2::Date}{Date} and \l {QtQuick2::Number}{Number} types. */ diff --git a/doc/src/qml/qmlintro.qdoc b/doc/src/qml/qmlintro.qdoc new file mode 100644 index 0000000000..03ee94d6d1 --- /dev/null +++ b/doc/src/qml/qmlintro.qdoc @@ -0,0 +1,1234 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-intro.html +\title Introduction to the QML Language +\brief Introduction to the concepts and features behind QML. + +QML is a declarative language designed to describe the user interface of a +program: both what it looks like, and how it behaves. In QML, a user +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 (see the online \l{Javascript Guide}) before +diving deeper into QML. It is also helpful to have a basic understanding of +other Web technologies like HTML and JSON, but it is not required. + +The examples shown in this guide are located in the +\c{examples/declarative/tutorials/qmlintro} directory within the Qt source +package. You can run then with the \l{QML Viewer} tool. + +\section1 \l{QML Concepts and Syntax} +\tableofcontents{1 QML Concepts and Syntax}{section4} + +\section1 \l{Composing User Interfaces with QML} +\tableofcontents{1 Composing User Interfaces with QML}{section4} + +\section1 \l{User Interaction with QML} +\tableofcontents{1 User Interaction with QML}{section4} +*/ + +/*! +\page qml-basic-syntax.html +\brief The basic syntax and concepts of the QML language. +\contentspage Introduction to the QML Language +\previouspage Introduction to the QML Language +\nextpage Composing User Interfaces with QML +\title QML Concepts and Syntax + +\tableofcontents + +This chapter covers the basic syntax of the QML language through the +use of examples, introducing the concepts behind the language and +the terminology used in the reference documentation. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-basic-syntax.png +\enddiv +The following example shows the basic syntax of QML. When opened in +the \l{QML Viewer}{\QQV tool}, the output displayed should match the +image shown on the right: a light blue rectangle. + +\snippet examples/declarative/tutorials/qmlintro/basic-syntax.qml document + +In this example, we import the features defined by Qt Quick 1.0, and +we declare and create a single rectangle with width, height and color. +Let's take a look at the main points of the language introduced by +this simple example. + +\section1 Importing Modules + +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 other elements would not be available. + +A specific version of a module is imported. This guarantees that the +elements imported when the application is run by the user match those +used by the developer when the application was written, ensuring that +they have the expected behavior. + +\section1 Elements + +The rectangle in the above example is specified by the \l Rectangle +element. When we declare objects like this, we write the element's 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. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-elements1.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/elements1.qml document + +Here, we create two elements: a rectangle with an image inside it. We say that +the rectangle is the parent element and the image is its child. Since the +rectangle does not have a parent element, it is a top level element. + +The position of each element in the user interface is defined relative +to the position of its parent, except for the top level element whose +position is always the top-left corner of the screen. + +QML files can contain multiple elements, but \e{only one} can be a top level +element. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-elements2.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/elements2.qml document + +In this example, we can define as many elements inside the rectangle +as we like, but we cannot define other top level elements. All the +additional elements are defined inside the light blue rectangle. + +\note In the QML documentation, we refer to \e elements, \e items and +\e components, often interchangeably. + +\list +\o When we talk about an \e element, we usually mean the syntactic structure, + including the name, the opening and closing braces, and its contents. +\o An \e item is an element that has a visual appearance. All items are + elements that inherit \l Item either directly or indirectly. For example, + a \l Rectangle is an item, but a \l State is an element because it does + not have an intrinsic appearance. +\o A \e component is an element that is defined to be reused. In many cases, + components are often items, too. +\endlist + +For now, we will refer to elements and items. Components are discussed in +detail later in this guide. + +A list of the most common elements is described on the \l{QML Basic Elements} +page. A full list can be found on the \l{QML Elements} page. + +\clearfloat +\section1 Properties + +A QML element usually has various \e properties that help define the element. +For example, all items have the \l{Item::}{x} and \l{Item::}{y} properties +that define the position of the item relative to its parent item (or the +screen's origin) and \l{Item::}{width} and \l{Item::}{height} properties +that define its dimensions. All simple properties have names that begin +with a lower case letter. + +\section2 Setting Properties + +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: + +\qml +Rectangle { + width: 100 + height: 100 +} +\endqml + +or you can put multiple properties on a single line: + +\qml +Rectangle { width: 100; height: 100 } +\endqml + +When multiple property-value pairs are specified on a single line, they +must be separated by a semicolon. + +\section2 Basic Property Types + +QML supports properties of many types (see \l{QML Basic Types}). The basic types +include \c int, \c real, \c bool, \c string and \c color. + +\qml +Item { + x: 10.5 // a 'real' property + state: "details" // a 'string' property + focus: true // a 'bool' property + // ... +} +\endqml + +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 a string to it you will get an error. + +\badcode +Item { + x: "hello" // illegal! +} +\endcode + +Property values are dynamic, responding to changes in the user interface. +See the \l{#Property Change Notifications}{Property Change Notifications} +section for information on the different ways to define properties, bind +them together and react to changes. + +\section2 Grouped Properties +\target dot properties + +Some elements contain a set of related properties that form a logical group; +these use a "dot" or grouped notation to show this. The \l Text item is one +such item that uses groups of properties to describe the font used to +display text. + +Grouped properties can be written like this: + +\snippet examples/declarative/tutorials/qmlintro/grouped-properties1.qml text with grouped properties + +or like this: + +\snippet examples/declarative/tutorials/qmlintro/grouped-properties2.qml text with grouped properties + +In the element documentation, grouped properties are shown using the "dot" notation. + +\section2 List Properties + +Some properties contain lists of elements, such as \l State, \l Item or +\l Transition. For example, the \l{Item::}{states} property is used like +this: + +\qml +Item { + states: [ + State { name: "stop" }, + State { name: "go" } + ] +} +\endqml + +The list is enclosed in square brackets, with a comma separating the list +elements. In cases where you are only assigning a single element to a list, +you can omit the square brackets: + +\qml +Item { + states: State { name: "stop" } +} +\endqml + +Elements 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. + +\section1 Expressions + +JavaScript expressions can be used to assign property values. For example: + +\qml +Item { + width: 100 * 3 + height: 50 + 22 +} +\endqml + +These expressions can include references to other objects and properties, in +which case a \l{Property Binding in QML}{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: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-property-binding1.png +\br +\inlineimage declarative-qmlintro-property-binding2.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/property-binding.qml elements + +Here, the child \l Rectangle item'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. This uses the special \c parent +property to refer to a parent item, which we explore in the +\l{Object Identifiers}{next section}. + +This is useful for relating the size of one element to another, so that +changes to the sizes of elements in the design, or at run-time, will be +taken into account. + +Property binding works with all types of properties, not just those related +to the size of an element. + +\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. An \c id must begin with +a lower-case letter or an underscore, and cannot contain characters other +than letters, numbers and underscores. + +For example, below we define a \l Text element and a \l Rectangle element +as children of a \l Column element. The \l Text object has an \c id value +of \c{textElement}. The Rectangle object defines its \c width property +to be the same as that of the Text object by referring to +\c{textElement.width}: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-object-identifiers.png +\enddiv + +\snippet examples/declarative/tutorials/qmlintro/object-identifiers.qml document + +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. +This means that a single QML file should only contain one place where +a particular \c id value is defined. + +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{textElement.id} in the above example. Once an object is +created, its \c id cannot be changed. + +\note The \c parent value is a special identity that each element can use +to refer to its parent item. For most simple user interfaces containing +a few display items, the parent of an item will be the enclosing element +in the QML file that contains it. However, when we look at more complex +ways to arrange and display items, we will find that this is not always +the case. + +\section1 Comments + +Commenting in QML is similar to JavaScript. +\list +\o Single line comments start with // and finish at the end of the line. +\o Multi-line comments start with /* and finish with *\/ +\endlist + +Comments are ignored by the QML engine. They are useful for explaining what +you are doing; for referring back to at a later date, or for others reading +your QML files. + +\snippet examples/declarative/tutorials/qmlintro/comments.qml commenting + +Comments can also be used to prevent the execution of code, which is +sometimes useful for tracking down problems. In the above example, the +\l Text element will have normal opacity, since the line containing the +opacity property has been turned into a comment. + +\section1 Responding to Changes + +User interfaces created using QML contain items such as \l Rectangle, +\l Image and \l Text to display content, but they can also contain items +that accept user input, such as \l TextInput and \l MouseArea. When the +user interacts with these items, they emit signals to inform other +components of any change. These signals can be received by the items +themselves; this is the main way to create items that respond to the user. + +\section2 Signal Handlers + +Signal handlers allow JavaScript code to be executed in response to a signal. +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: + +\snippet examples/declarative/tutorials/qmlintro/signal-handlers.qml document + +All signal handlers begin with \e "on". + +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: + +\snippet examples/declarative/tutorials/qmlintro/signal-handlers-parameters.qml mouse area + +\section2 Property Change Notifications + +When a property changes value, it can send a signal to notify others of this change. + +To receive these signals, simply create a \i{signal handler} named with an +\e on<Property>Changed syntax. For example, the \l TextInput element has a +\l{TextInput::}{text} property. When this property changes, the \c textChanged +signal is emitted. We can monitor this property for changes with the +\c onTextChanged handler. + +\table +\header \o Property \o Signal \o Signal Handler +\row \o \l{TextInput::}{text} \o \c textChanged \o \c onTextChanged +\endtable + +The following code shows this in practice: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-property-change1.png +\br +\inlineimage declarative-qmlintro-property-change2.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/property-change.qml property change + +When the user modifies the text, the expression assigned to the \c textChanged +handler will be evaluated. In this example, the text changes color when this +happens. + +Similarly, the \l Rectangle element has \l{Item::}{width} and +\l{Rectangle::}{color} properties. Below, we have a \l Rectangle element +that has defined two signal handlers, \c onWidthChanged and \c onColorChanged, +which will automatically 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) +} +\endqml + +These cause the new values of these properties to be written to the console, +which can be useful for debugging purposes. + +\section2 Attached Properties +\target attached-properties + +Some elements attach properties to other elements. This is used in cases +where one element needs to access features of another, but does not +inherit properties to access those features. + +Attached Properties are of the form \e {<Type>.<property>} where \e <Type> +is the type of the element that attaches \e <property>. + +An example of attached properties in use involves the \l Keys element which +attaches properties for handling key presses to any item. For example: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-attached-properties.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/attached-properties.qml attached properties + +The \l Keys properties are not defined by the \l Item element. They are +defined separately and attached to the item. + +Attached properties are also used by delegates to reference information about +the view they are used in. For example, the \l ListView element attaches +the \e ListView.isCurrentItem property to each delegate it creates: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-attached-properties-view.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/attached-properties-view.qml delegate with attached property + +In effect, by attaching this property, \l ListView provides an interface +that lets the delegate access information about the current item in the +view it appears in. + +The use of attached properties will be covered in more depth later in this +guide. + +\omit +\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: +\qml +State { + changes: [ + PropertyChanges {}, + PropertyChanges {} + ] +} +\endqml + +can be simplified to: + +\qml +State { + PropertyChanges {} + PropertyChanges {} +} +\endqml + +because \c changes is the default property of the \c State type. +\endomit +*/ + +/*! +\page qml-composing-uis.html +\contentspage Introduction to the QML Language +\previouspage QML Concepts and Syntax +\nextpage User Interaction with QML +\title Composing User Interfaces with QML +\brief How to arrange items with anchors. + +\tableofcontents + +In the \l{Introduction to the QML Language}{previous chapter}, we looked at +the syntax of QML and the basic building blocks that are used to create +user interfaces. For example, at a low level, we have seen that an item's +\c x and \c y properties are used to position it within its parent item. +However, when defining more complex user interfaces, especially those with +items that will move or change size, we need a way to arrange items in a +more systematic way. + +\section1 Anchors and Anchor Lines + +In the previous examples, all the items have been given either absolute +positions in the user interface or positions relative to their parents. +For more flexibility, both at design-time and in the case where the user +interface changes at run-time, we prefer to use anchors to arrange items. + +Anchors connect items together visually, creating relationships between +their geometries. As a result, mixing absolute positioning and anchors +is only recommended in cases where the constraints imposed by each +approach do not conflict. Anchors can only be used to relate items +with their parents, children or siblings. + +\section2 Anchoring within Items + +Anchors can be used to generally describe how items are positioned +within the space occupied by their parents. Two of the anchors are used +to place items in this way. + +The following example uses anchors to position a \l Text item in the +center of a \l Rectangle. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-anchors-centerin.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/anchors.qml centered text + +In this case, the center of the text item is anchored to the center of +its parent item by using the \c{anchors.centerIn} grouped property. +This defines a high level description of the relationship between the two +items. Similarly, the \c{anchors.fill} grouped property is used to describe +the case where an item needs to fill the space provided by its parent. + +\note When using \c{anchors.centerIn} and \c{anchors.fill}, the value of +the anchor property is an item. + +\section2 Anchor Lines + +At a lower level, anchors can be used to line up the edges of two items. +In the following example, the \l Text item is centered within its parent, +the \l Item that defines the user interface. The \l Rectangle uses anchors +to define its position relative to the text item. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-anchors-edges.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/anchors2.qml anchored items + +By giving the text item the \c textItem identifier, we can refer to it when +defining the anchors for the rectangle. We line up the right edge of the +rectangle with the left edge of the text item, and line up their top edges. + +This example shows the use of anchor lines. Grouped properties are defined +for key parts of each item, including its top, left, right and bottom edges, +plus the lines running through the horizontal center and vertical center of +the item. A baseline anchor line is also used for items that display text. + +\note We connect anchor lines to other anchor lines, not to items. + +\section2 Anchors and Property Bindings + +Since the anchor definitions are property bindings, any changes to the +position of an anchor will cause any connected anchors to move as well. +This is illustrated by the following example, which places a red rectangle +beneath a \l TextInput item and uses anchors to ensure that it is always +the same width. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-anchors-expanding1.png +\br +\inlineimage declarative-qmlintro-anchors-expanding2.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/anchors-expanding.qml anchored items + +The anchor lines on the left and right edges of the rectangle are connected +to those of the text input item. Since the text can be modified by the user, +the width of the item can change. The use of anchors causes the width of the +rectangle to change as well. + +The \l{Anchor-Based Layout in QML} document covers the use of anchors in +more detail. + +\clearfloat +\section2 Margins + +Although anchors are useful for lining up items, it is often useful to leave +small gaps between the edges of adjacent items. The following example lines +up an \l Image item with a \l Text item, but uses a margin to leave a gap +between them. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-anchors-margins.png +\br +\inlineimage declarative-qmlintro-anchors-baseline-margins.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/anchors-margins.qml anchored items + +Note that the image also uses a margin to leave a gap between its left edge +and the left edge of the user interface. + +Adding \l Rectangle items to the scene description, we can see the effects of +the anchors and margins, with the image displaced from the left edge of its +parent item and the text label displaced from the right edge of the image. + +\clearfloat +\section2 Limitations and Strategies + +Anchors allow the relationships between items to be described using simple +declarations, maintaining a user interface layout when items move or change +size. They are useful in most situations, but have limitations which need +to be considered, and therefore it is a good idea to adopt strategies for +using them. + +\section3 Limitations of Anchors + +Since anchors can only be used to relate an item with its parent, children or +siblings, care must be taken when referencing items in complex or deeply-nested +user interfaces. Where there are lots of items to be arranged, it can be more +productive to use \l{#Positioners}{positioners} and +\l{Generating Items with Repeaters}{repeaters}, or +\l{QML Models and Views}{models and views}. + +Connections between anchors cannot be deleted and will override explicit +declarations of positions and sizes using the \l{Item::}{x}, \l{Item::}{y}, +\l{Item::}{width} and \l{Item::}{height} properties of items. + +Since anchors rely on property binding to ensure that items are dynamically +updated if one of them changes, each anchor definition creates a new dependency +on another item. Use of anchors therefore causes a dependency graph defining an +order in which items will be updated. Problems can occur if circular dependencies +are created between items. The following example shows this occurring with a +parent item and its child. + +\snippet examples/declarative/tutorials/qmlintro/circular.qml circular + +\section3 Strategies for Use + +In order to reference an item with an anchor, it needs a way to be identified. +Children of the item can refer to it as \c parent, but otherwise it needs to +define an \l{Introduction to the QML Language#Object Identifiers}{identifier}. +It is good practice to define identifiers for all the items that need to be +positioned or referenced in some way unless those items can be referenced +using the \c parent identifier. + +It is usually helpful to identify the fixed or dominant parts of the user +interface and give those items identifiers so that dependent items can refer +to them. This avoids potential issues with circular dependencies. +In the example shown, the \c launchBox and \c cancelBox items are anchored +within the top level item that contains the user interface. Each of these +items contain an image and a text item that are anchored to their parent. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-anchors-strategy-annotated.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/anchors-strategy.qml anchor strategy + +The above example shows how each item is anchored to its parent. This ensures +that the dependencies introduced by the anchors all consistently point to each +item's parent or a sibling. It is not always possible to ensure such simple +dependencies between items. As a result, it is often necessary to consider +other factors that determine how the use of anchors will affect the geometries +of items. + +When positioning items using the \c horizontalCenter anchor, do not use the +\c left or \c right anchors; define the width of the item instead, either as +a fixed value or as a proportion of the parent item. Similarly, avoid using +the \c top or \c bottom anchors with the \c verticalCenter anchor; set the +height of the item instead. + +Items that define their own width and height based on their contents, like +\l Image or \l TextInput, can be used with all kinds of anchors. Care must +be taken to avoid imposing conflicting constraints on their dimensions. +For example, using \c left and \c right anchors to position a text input +item may be problematic because the item determines its own width and it +may change. + +When defining an item that you want to stretch to fill the available space +between other items, make sure that you anchor the stretchable item to items +with well-defined or implicitly-defined sizes and not the other way round. +The following example shows this with a \l Text item with an implicit size +and a \l Rectangle that stretches to fill the remaining space in its parent +item. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-anchors-stretch.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/anchors-stretch.qml items + +The rectangle uses anchors to define its top, left and right edges in terms +of its parent item, and the bottom edge is aligned with the top of the text +item. If, instead, the text item is anchored to the rectangle, which has no +implicit size, the layout of the user interface will be broken because the +rectangle will be assigned a zero height. + +\section1 Positioners + +Positioner items are container items that manage the positions and sizes of +items in a declarative user interface. Positioners behave in a similar way to +the \l{Widgets and Layouts}{layout managers} used with standard Qt widgets, +except that they are also containers in their own right. + +Positioners make it easier to work with many items when they need to be +arranged in a regular layout. As we will see when we encounter +\l{Generating Items with Repeaters}{Repeaters}, it is easier to describe +how items should be arranged when there are many of them than it is to +try and individually position them. + +\section2 Standard Positioners + +A set of standard positioners are provided in the basic set of Qt Quick items. +Since these are all based on the \l Item element, they contain properties that +define their positions and sizes, but they do not have any visual appearance +of their own; they simply arrange their child items in the space allocated to +them. Any background color, if desired, must be added to a parent Rectangle. + +\list +\o \l{#Row}{Row} arranges its children in a row. +\o \l{#Column}{Column} arranges its children in a column. +\o \l{#Grid}{Grid} arranges its children in a grid. +\o \l{#Flow}{Flow} arranges its children like words on a page. +\endlist + +Each of these items provides many of the same properties as the others, +making it easy to exchange one with another at a later point in the design +of an application or component. The common properties are \c spacing, +\c add and \c move. As expected, the \l{Row::spacing}, \l{Column::spacing} +and \l{Grid::spacing} properties have slightly different meanings because +they describe how space is added to different kinds of layout. + +The \c add and \c move properties describe what should happen when items +are added to a positioner item or moved within it. These actions are +described with \l{QML Animation and Transitions}{transitions}, and will +be covered later. + +\section3 Row + +\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 +by an outer colored Rectangle. The \l{Row::spacing}{spacing} property is set to +include a small amount of space between the rectangles. + +\div {class="float-right"} +\inlineimage qml-row.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/row.qml document + +We ensure that the parent \l Rectangle is large enough so that there is some space +left around the edges of the horizontally centered Row item. The equally-sized +rectangles in this example automatically line up because they each have the +same height. Items with different heights will not be positioned vertically +by the \l Row; these need to be lined up using anchors. + +Since the \l Row item is responsible for positioning its child items +horizontally, those child items cannot use anchors to position themselves +within the row. However, they can use anchors to align themselves vertically +relative to one another or to the row itself. The following example uses +\c verticalCenter anchors to vertically align three rectangles with +different sizes. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-row-anchors.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/row-anchors.qml row + +Note that the \l Row item itself uses \c horizontalCenter and \c verticalCenter +anchors to place itself in the center of its parent. It is free to do this +because it is not being positioned by its parent, a \l Rectangle. However, +when we place positioners inside other positioner, such as a \l Row inside +a \l Column, we will need to be aware of what constraints are being imposed +by the positioner's parent item. This is +\l{#Nesting Positioner Items}{discussed later} in this chapter. + +The height of the row is dependent on the heights of the individual child +items and, unless specified using the \c height property or with anchors, +it will only be as high as the tallest child item. + +\clearfloat +\section3 Column + +\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 +by an outer \l Item. The \l{Column::spacing}{spacing} property is set to +include a small amount of space between the rectangles. + +\div {class="float-right"} +\inlineimage qml-column.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/column.qml document + +In the above example, each of the rounded rectangles are positioned by the +\l Column item. The column only changes the vertical positions of its +child items and does not restrict their horizontal positions. However, +the restrictions on the use of anchors do not apply to the children of +these child items, so each \l Text item uses its \c centerIn anchor to +horizontally and vertically align itself within its parent rectangle. + +The width of the column is dependent on the widths of the individual child +items and, unless specified using the \c width property or with anchors, +it will only be as wide as the widest child item. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-column-anchors.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/column-anchors.qml document + +The example above stretches the column horizontally to fill the entire +user interface, and stretches each rectangle inside to fill the column. +The text items behave as they did in the previous example. + +\clearfloat +\section3 Grid + +\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 +in a 2-by-2 grid. As with the other positioners, the spacing between items +can be specified using the \l{Grid::spacing}{spacing} property. + +\div {class="float-right"} +\inlineimage qml-grid-spacing.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/grid-spacing.qml document + +There is no difference between horizontal and vertical spacing inserted +between items, so any additional space must be added within the items +themselves. Any empty cells in the grid must be created by defining +placeholder items at the appropriate places in the grid definition. + +As with the \l Row and \l Column items, \l Grid items restrict the anchors +used by their child items. Since they position items both horizontally +and vertically, it is not possible to use any of the anchors to align +items within the grid. However, we can use placeholder items as the grid's +child items and put visible items inside those, using anchors to align +them. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-grid-positioning.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/grid-positioning.qml document start +\snippet examples/declarative/tutorials/qmlintro/grid-positioning.qml document end + +We only show the first item, but the principle is the same for the others. + +\clearfloat +\section3 Flow + +\l Flow items are used to place items like words on a page, with rows or +columns of non-overlapping items. + +Flow items arrange items in a similar way to \l Grid items, with items +arranged in lines along one axis (the minor axis), and lines of items +placed next to each other along another axis (the major axis). The +direction of flow, as well as the spacing between items, are controlled +by the \l{Flow::}{flow} and \l{Flow::}{spacing} properties. + +The following example shows a Flow item containing a number of \l Text +child items. These are arranged in a similar way to those shown in the +screenshots. + +\div {class="float-right"} +\inlineimage qml-flow-text1.png +\br +\inlineimage qml-flow-text2.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/flow.qml document + +The main differences between the \l Grid and \l Flow positioners are that +items inside a \l Flow will wrap when they run out of space on the minor +axis, and items on one line may not be aligned with items on another line +if the items do not have uniform sizes. As with grid items, there is no +independent control of spacing between items and between lines of items. + +\clearfloat +\section2 Nesting Positioner Items + +Since each positioner is based on \l Item, we can nest them like other +items, placing one positioner inside another. The following example shows a +\l Column that contains two \l Row positioners. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-nested-positioners.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/nested-positioners.qml column + +The example works around the restrictions on the use of anchors mentioned +earlier by using appropriate anchors for each item. The innermost items, +\l Text and \l Rectangle, use anchors for vertical positioning within +\l Row items, which each perform horizontal positioning of their child +items. + +The rows use anchors to position themselves within the \l Column item, which +arranges them vertically. The column is centered horizontally and vertically +within its parent, a non-positioning item. + +\clearfloat +\section2 Strategies for Use + +Positioners are intended to be used in situations where it would be +tedious to apply anchors to a number of items. For this reason, they are +also used to position dynamically created items, such as those generated +by \l Repeater items. + +The items used with positioners must have a well-defined size, otherwise +positioners will not be able to determine where they should be placed, +leaving their positions undefined. When using a \l Column, it is sufficient +to give each child item a fixed height; the width can be defined using +anchors. Similarly, with a \l Row, the width of each item should be +fixed, but the height can be defined using anchors. Items used with \l Grid +and \l Flow positioners should have fixed widths and heights. +*/ + +/*! +\page qml-user-interaction.html +\contentspage Introduction to the QML Language +\previouspage Composing User Interfaces with QML +\nextpage Generating Items with Repeaters +\title User Interaction with QML +\brief Making items respond to user input. + +\tableofcontents + +So far, we have shown how to declare items and arrange them to create a user +interface. If we play a QML file using the \l{QML Viewer}, we can resize the +display window and see the items adapt to the change, but the items +themselves do not respond to user input from the keyboard or mouse. + +Unlike standard Qt widgets, items do not include intrinsic support for user +interaction. The features required for interactivity are added or applied to +items. + +QML provides the \l MouseArea item to handle mouse input and \l Keys and +\l KeyNavigation attached properties to handle keyboard input. These are +used with other items to make them responsive to user input. + +\section1 Mouse Areas + +To make items responsive to mouse clicks, we add \l MouseArea items to the +user interface, typically as children of the items we want to make +interactive. Since \l MouseArea is based on \l Item, it has a geometry, but +no visual appearance. The following example defines a mouse area with an +explicit position and size; the image shown indicates where the mouse area +is in the user interface, but it will not be visible in the running example. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mousearea-annotated.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/mousearea.qml mouse area + +The \l{MouseArea::}{onPressed} and \l{MouseArea::}{onReleased} definitions +are \l{QML Concepts and Syntax#Signal Handlers}{signal handlers} that +contain JavaScript code that will be executed in response to a signal. In +this case, when the mouse button is pressed or released, the code will +change the color of the background. Other signal handlers can be defined +to handle other user input, such as \l{MouseArea::}{onClicked} and +\l{MouseArea::}{onDoubleClicked}. Some require additional configuration +of the item before they will work as expected, as we shall see later. + +\note It is more common to define mouse areas within items and position them +with anchors, as shown by the rest of the examples in this chapter. + +\clearfloat +\section2 Handling Mouse Buttons + +The following example uses an anchor to fill a \l Text item with a mouse +area, and defines two signal handlers to response to mouse button input. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-pressed1.png +\br +\inlineimage declarative-qmlintro-mouse-pressed2.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/mouse-pressed-signals.qml text item + +The \l{MouseArea::}{onPressed} and \l{MouseArea::}{onReleased} +signal handlers are defined for the mouse area. As a result, when the user +presses a mouse button when the cursor is over the text, the color changes +to green; when the button is released, the color changes to black. + +Note that the mouse area only responds to the left mouse button by default. +This is because the default value of the \l{MouseArea::}{acceptedButtons} +is \l{Qt::LeftButton}{Qt.LeftButton}. To test for other buttons, set this +property to be the combination of the buttons required (using the OR +operator), as in the following example. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-pressed-buttons.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/mouse-pressed-buttons.qml items + +The mouse area covers the entire area of the user interface and accepts +input from both left and right buttons. Each of the rectangles defines its +color as an expression that depends on the mouse area's +\l{MouseArea::}{pressedButtons} property, testing whether the relevant +button is found in the value of this property. When a button is released, +the value is \c{Qt.NoButton}. + +\note The \l{MouseArea::}{pressed} property provides information about +whether or not a button was pressed in the mouse area, but does not +provide any more than a boolean value. This can be sufficient in many +situations. + +\clearfloat +\section2 Finding the Cursor Position + +The \l MouseArea item contains a number of properties and signal handlers +that provide information about the mouse cursor. For example, the +\l{MouseArea::}{mouseX} and \l{MouseArea::}{mouseY} properties contain the +position of the cursor, as shown in the following example. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-pressed-position.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/mouse-pressed-position.qml text item + +When the user presses the mouse button over the text item, the text changes +to show the coordinates within the mouse area where the press occurred. If +we need to find the mouse position outside the text item, we should make +the mouse area a child of the text item's parent and use anchors to fill +that item instead. + +\clearfloat +\section2 Mouse Hover + +In the previous examples, the text item and rectangles were updated only +when the mouse button was pressed. Consider a situation where we would like +to continuously update the text item with the mouse's position. In such a +case, we could try the following: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-pressed-position2.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/mouse-pressed-position2.qml text item + +When we run this example, the text item shows the initial, default value of +the mouse area's \c mouseX and \c mouseY properties. Moving the cursor over +the text has no effect. It is only when the text item is clicked that the +text is updated. + +The reason for this is that, by default, the mouse area only updates various +properties when a button is pressed. To receive continuous updates about the +mouse cursor, we need to enable \e{mouse hover} by setting its +\l{MouseArea::}{hoverEnabled} property, as shown in the following example: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-hover-enabled.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/mouse-hover-enabled.qml text item + +With mouse hover enabled, other properties of the \l MouseArea can be +monitored. For example, the \l{MouseArea::}{containsMouse} property can be +used to determine whether the mouse cursor is over the mouse area. +Previously, we only knew when this was the case because the user had to +press a mouse button over the area. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-hover-containsmouse1.png +\br +\inlineimage declarative-qmlintro-mouse-hover-containsmouse2.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/mouse-hover-containsmouse.qml items + +The above example uses \l{QML Concepts and Syntax#Expressions}{an expression} +to show the coordinates of the mouse cursor when it is in the mouse area, +\c area. When \c{area.containsMouse} evaluates to \c false, the \c{-} +character is shown instead. + +Certain signal handlers only become useful when mouse hover is enabled. +For example, the \l{MouseArea::}{onEntered}, \l{MouseArea::}{onExited} +and \l{MouseArea::}{onPositionChanged} signal handlers will be called +when the cursor enters, exits or changes position in the area. + +\section2 Dragging Items + +As well as handling the low level interaction details, the \l MouseArea item +also handles drag operations if the relevant properties are set. The +following example shows how dragging is enabled for an item. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-drag.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/mouse-drag.qml draggable item + +The item to be dragged is the \l Rectangle containing a \l MouseArea and +\l Text items. All that is required is to set the value of the +\l{MouseArea::}{drag.target} grouped property to the item we wish to enable +dragging for; in this case, the \c parent of the mouse area. When run, the +rectangle containing the text can be dragged around its parent's area. + +The other \c drag grouped properties allow the dragging behavior of the +item to be restricted and fine-tuned. \l{MouseArea::}{drag.axis} can be +set to only allow dragging to occur along the x or y axes, and the range +of positions to which the target item can be dragged can be limited to +a range specified by the \l{MouseArea::}{drag.minimumX}, +\l{MouseArea::}{drag.minimumY}, \l{MouseArea::}{drag.maximumX} and +\l{MouseArea::}{drag.maximumY} properties. + +\clearfloat +\section2 Strategies for Use + +Mouse areas are applied to a user interface by using anchors to fill the +items that need to respond to user input. This makes them responsive to +button presses by default, and to mouse movement when the +\l{MouseArea::}{hoverEnabled} property is set to \c true. When a mouse +area is not needed to provide input, its \l{MouseArea::}{enabled} +property can be set to \c false, so that it ignores user input. + +When mouse buttons are pressed and released, the +\l{MouseArea::}{pressedButtons} property is updated as expected. However, +when multiple buttons are used, as in the +\l{#Handling Mouse Buttons}{example above}, the most up-to-date values +reported by this property are not necessarily propagated to the items +that use it. For this reason, it can be better to consider using signal +handlers to respond to mouse button presses and releases. + + +\section1 Key Handling + +Another important method of user input is via the keyboard. In addition to +the \l TextInput and \l TextEdit items, which accept keyboard input for +display purposes, QML provides facilities to allow items to capture key +presses, as well as higher level features for navigation using keys. + +Unlike mouse input, which uses the \l MouseArea item, key input uses two +attached properties to handle keyboard input: \l Keys and \l KeyNavigation. +These look like ordinary elements, but can be applied to any item in order +to enable keyboard input support. + +\section2 Key Navigation + +In desktop user interfaces, it is usually helpful to provide a way for the +user to navigate between input fields or other interactive items by pressing +navigation keys, typically the cursor keys or the \key Tab key. The +\l KeyNavigation attached property is used to define the relationships +between items to allow this kind of navigation. + +The following example shows two \l Rectangle items placed in a \l Row +positioner. These are defined with identifiers, \c{leftRect} and +\c{rightRect}. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-key-navigation1.png +\br +\inlineimage declarative-qmlintro-key-navigation2.png +\enddiv +\snippet examples/declarative/tutorials/qmlintro/key-navigation.qml items + +The \c{leftRect} rectangle attaches the +\l{KeyNavigation::right}{KeyNavigation.right} property, setting it to refer +to the \c{rightRect} rectangle. The \c{rightRect} rectangle attaches the +\l{KeyNavigation::left}{KeyNavigation.left} property, referring to the +\c{leftRect} rectangle. + +Initially, the \c{leftRect} rectangle has the keyboard focus, since its +\l{Item::}{focus} property is set to \c true. When the user presses the +right cursor key, the focus is passed to the \c{rightRect} rectangle instead, +as defined by the \l KeyNavigation attached property for that item. Pressing +the left cursor key causes the focus to be passed back to \c{leftRect} +because as defined by the \l KeyNavigation attached property for +\c{rightRect}. + +\clearfloat +*/ + +/*! +\page qml-positioning-items.html +\contentspage Introduction to the QML Language +\previouspage Composing User Interfaces with QML +\nextpage QML Tutorial +\title Generating Items with Repeaters +\brief How to generate and position items dynamically. + +\tableofcontents + +\section1 Repeaters + +\div {class="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 +lots of items. A \l Repeater item is placed inside a positioner, and generates +items that the enclosing positioner arranges. + +Each Repeater creates a number of items by combining each element of data +from a model, specified using the \l{Repeater::model}{model} property, with +the template item, defined as a child item within the Repeater. +The total number of items is determined by the amount of data in the model. + +The following example shows a repeater used with a \l{#Grid}{Grid} item to +arrange a set of Rectangle items. The Repeater item creates a series of 24 +rectangles for the Grid item to position in a 5 by 5 arrangement. + +\clearfloat +\snippet doc/src/snippets/declarative/repeaters/repeater-grid-index.qml document + +The number of items created by a Repeater is held by its \l{Repeater::}{count} +property. It is not possible to set this property to determine the number of +items to be created. Instead, as in the above example, we use an integer as +the model. This is explained in the \l{QML Data Models#An Integer}{QML Data Models} +document. + +It is also possible to use a delegate as the template for the items created +by a Repeater. This is specified using the \l{Repeater::}{delegate} property. + +\section1 Using Transitions + +Transitions can be used to animate items that are added to, moved within, +or removed from a positioner. + +Transitions for adding items apply to items that are created as part of a +positioner, as well as those that are reparented to become children of a +positioner. +Transitions for removing items apply to items within a positioner that are +deleted, as well as those that are removed from a positioner and given new +parents in a document. + +Additionally, changing the opacity of items to zero will cause them to +disappear using the remove transition, and making the opacity non-zero will +cause them to appear using the add transition. + +\section1 Other Ways to Position Items + +There are several other ways to position items in a user interface. In addition +to the basic technique of specifying their coordinates directly, they can be +positioned relative to other items with \l{anchor-layout}{anchors}, or used +with \l{QML Data Models} such as +\l{QML Data Models#VisualItemModel}{VisualItemModel}. +*/ diff --git a/doc/src/declarative/qmlnumber.qdoc b/doc/src/qml/qmlnumber.qdoc index 099a619c0e..099a619c0e 100644 --- a/doc/src/declarative/qmlnumber.qdoc +++ b/doc/src/qml/qmlnumber.qdoc diff --git a/doc/src/qml/qmlplugins.qdoc b/doc/src/qml/qmlplugins.qdoc new file mode 100644 index 0000000000..9b6fe29c1e --- /dev/null +++ b/doc/src/qml/qmlplugins.qdoc @@ -0,0 +1,133 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qml-plugins.html +\title QML Plugins +\target qml-plugins +\brief importing Qt C++ functions as plugins + + + The \l{The QML Engine}{QML engine} can run Qt C++ applications + by \l{register-c++-type}{registering} types into the runtime and by loading + C++ code as plugins. Plugins are imported and labeled as modules and + its content are available as components. + + QDeclarativeExtensionPlugin is a plugin interface that makes it possible to + create QML extensions that can be loaded dynamically into QML applications. + These extensions allow custom QML types to be made available to the + QML engine. + + To write a QML extension plugin: + \list 1 + \o Subclass QDeclarativeExtensionPlugin + \o Implement QDeclarativeExtensionPlugin's + \l{QDeclarativeExtensionPlugin::}{registerTypes()} method + \o Register types with qmlRegisterType() + \o Export the class using the Q_EXPORT_PLUGIN2() macro + \o Write a project file for the plugin + \o Create a \l{Writing a qmldir file}{qmldir file} to describe the plugin + \endlist + + QML extension plugins are for either application-specific or library-like + plugins. Library plugins should limit themselves to registering types, as + any manipulation of the engine's root context may cause conflicts or other + issues in the library user's code. + +\section1 Plugin Example + + Suppose there is a new \c TimeModel C++ class that should be made available + as a new QML element. It provides the current time through \c hour and \c minute + properties. + + \snippet examples/declarative/cppextensions/plugins/plugin.cpp 0 + \dots + + A plugin class, \c QExampleQMLPlugin, is a subclass of + \l QDeclarativeExtensionPlugin and it implements the + \l{QDeclarativeExtensionPlugin::}{registerTypes()} method. + + In the registerTypes() method, the plugin class can + \l{register-c++-type}{register} the \c TimeModel class to the declarative + runtime with the qmlRegisterType() function. The Q_EXPORT_PLUGIN2() macro has + two parameters, the generated plugin name and the class name. + + \snippet examples/declarative/cppextensions/plugins/plugin.cpp plugin + \codeline + \snippet examples/declarative/cppextensions/plugins/plugin.cpp export + + The \c TimeModel class receives a \c{1.0} version of this plugin library, as + a QML type called \c Time. The Q_ASSERT() macro can ensure the module is + imported correctly by any QML components that use this plugin. The + \l{Creating QML Types} article has more information about registering C++ + types into the runtime. + + For this example, the TimeExample source directory is in + \c{com/nokia/TimeExample}. The plugin's module import statement will follow + this structure. + + The project file, in a \c .pro file, defines the project as a plugin library + and specifies it should be built into the \c com/nokia/TimeExample + directory: + + \code + TEMPLATE = lib + CONFIG += qt plugin + QT += declarative + + DESTDIR = com/nokia/TimeExample + TARGET = qmlqtimeexampleplugin + ... + \endcode + + Finally, a \l{Writing a qmldir file}{qmldir file} is required in the \c + com/nokia/TimeExample directory to specify the plugin. This directory + includes a \c Clock.qml file that should be bundled with the plugin, so it + needs to be specified in the \c qmldir file: + + \quotefile examples/declarative/cppextensions/plugins/com/nokia/TimeExample/qmldir + + Once the project is built and installed, the new \c Time component is + accessible by any QML component that imports the \c com.nokia.TimeExample + module + + \snippet examples/declarative/cppextensions/plugins/plugins.qml 0 + + The full source code is available in the \l {declarative/cppextensions/plugins}{plugins example}. + + +\section1 Reference + + \list + \o \l {Tutorial: Writing QML extensions with C++} - contains a chapter + on creating QML plugins. + \o \l{Creating QML Types} - information about registering C++ types into + the runtime. + \o \l{How to Create Qt Plugins} - information about Qt plugins + \endlist + + +*/ diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/qml/qmlruntime.qdoc index 1bd1140795..5853c14844 100644 --- a/doc/src/declarative/qmlruntime.qdoc +++ b/doc/src/qml/qmlruntime.qdoc @@ -27,8 +27,8 @@ /*! \page qmlruntime.html -\inqmlmodule QtQuick 2 \title Qt Declarative UI Runtime +\brief launching QML based applications through Qt QML documents are loaded and executed by the QML runtime. This includes the Declarative UI engine along with the built-in QML elements and plugin modules, @@ -61,7 +61,7 @@ QDeclarativeView is a QWidget-based class that is able to load QML files. For example, if there is a QML file, \c application.qml, like this: \qml - import QtQuick 1.0 + import QtQuick 2.0 Rectangle { width: 100; height: 100; color: "red" } \endqml @@ -132,7 +132,7 @@ as details on including QML files through \l{The Qt Resource System}{Qt's Resour -\section1 Developing and prototyping with QML Viewer +\section1 Developing and Prototyping with QML Viewer The Declarative UI package includes a QML runtime tool, the \QQV, which loads and displays QML documents. This is useful during the application development diff --git a/doc/src/declarative/qmlsyntax.qdoc b/doc/src/qml/qmlsyntax.qdoc index f5c17a05ab..b2b7fc89bd 100644 --- a/doc/src/declarative/qmlsyntax.qdoc +++ b/doc/src/qml/qmlsyntax.qdoc @@ -26,11 +26,10 @@ ****************************************************************************/ /*! -\page qmlsyntax.html -\inqmlmodule QtQuick 2 +\page qml-syntax.html \title QML Syntax \ingroup QML Reference -\contentspage QML Reference +\brief listing of valid QML syntax \tableofcontents @@ -47,7 +46,7 @@ deeper into QML. QML looks like this: \code -import QtQuick 1.0 +import QtQuick 2.0 Rectangle { width: 200 diff --git a/doc/src/declarative/qmltest.qdoc b/doc/src/qml/qmltest.qdoc index 640275cf93..a8524999e7 100644 --- a/doc/src/declarative/qmltest.qdoc +++ b/doc/src/qml/qmltest.qdoc @@ -30,6 +30,7 @@ \inqmlmodule QtQuick 2 \title QtQuickTest Reference Documentation \keyword QtQuickTest Reference Documentation + \brief unit testing framework for QML \section1 Introduction diff --git a/doc/src/qml/qmltypes.qdoc b/doc/src/qml/qmltypes.qdoc new file mode 100644 index 0000000000..71985c2e1c --- /dev/null +++ b/doc/src/qml/qmltypes.qdoc @@ -0,0 +1,783 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qml-c++types.html +\title Creating QML Types +\brief exposing Qt C++ types into the QML engine + +The \l{The QML Engine}{QML engine} can instantiate any Qt C++ construct +such as \l{The Property System}{properties}, functions, and data models into +the QML context allowing the constructs to be accessible from within QML. + +\target register-c++-type +\section1 Register a Type + + In an application or a \l{QML Plugins}{plugin}, the \c qmlRegisterType + template will register a class to the QML engine. + +\code +template<typename T> +int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) +\endcode + + \l qmlRegisterType() registers the C++ type \a T with the QML system, and + makes it available to the QML context under the name \c qmlName in library + \c uri version \c versionMajor.versionMinor. The \c qmlName can be the same + as the C++ type name. + + Suppose that a \c Person class defined in a C++ is to be exposed into the + QML context. The class must be a subclass of \l{QObject} and have a default + constructor. The \l{The Property System}{properties} created with the + Q_PROPERTY macro are visible in the QML context as well. + \snippet declarative/cppextensions/referenceexamples/adding/person.h 0 + + The application registers the class to the runtime with the + \l{qmlRegisterType()}. + + \snippet declarative/cppextensions/referenceexamples/adding/main.cpp 0 + + The Person type is then imported with the \c "People 1.0" module and its + properties are accessible in a QML file. +\snippet declarative/cppextensions/referenceexamples/adding/example.qml 0 + + The \l {Extending QML - Adding Types Example}{Adding Types} example + demonstrates as usage of the \l qmlRegisterType(). + + Alternatively, these functions provide a way for other types of C++ types + to be visible in the QML context. + \list + \o \l qmlRegisterUncreatableType() is suited for attached + properties and enum types. + \o \l qmlRegisterTypeNotAvailable() is for + reserving a namespace and suited for generating useful errors. + \o \l qmlRegisterInterface() - for registering base or abstract classes for + \l{qml-c++-coercion}{coercion and inheritance}. This is useful for general + Qt objects or \l{Qt Objects and Interfaces}{pointers} to objects. + \o \l qmlRegisterExtendedType() - for \l{qml-c++-extension}{extended types} + \endlist + + \section2 Qt Objects and Interfaces + QML can bind to complex objects such as pointers to objects or lists. As QML + is typesafe, the \l{The QML Engine}{QML engine} ensures that only + valid types are assigned to these properties. + + The QML engine treats pointers to objects or Qt interfaces the same + way as regular properties. Thus, the lists or pointers are created as + properties using the Q_PROPERTY() macro. + + \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1 + + The \c host is an \l{qml-expose-properties}{exposed property} that can bind + to objects or lists of objects. The property type, in this case \c Person, + must be \l{register-c++-type}{registered} into the runtime. + + QML also supports assigning Qt interfaces. To assign to a property whose + type is a Qt interface pointer, the interface must also be registered with + QML. As they cannot be instantiated directly, registering a Qt interface is + different from registering a new QML type. The following function is used + instead: + + \code + template<typename T> + int qmlRegisterInterface(const char *typeName) + \endcode + + This function registers the C++ interface \a T with the QML system as \a + typeName. + + Following registration, QML can \l{qml-c++-coercion}{coerce} objects that + implement this interface for assignment to appropriately typed properties. + +\target qml-expose-properties +\section1 Exposing Qt C++ Properties + + The \l{The QML Engine}{QML engine} utilizes Qt's + \l{The Property System}{Property System} and in effect, QML + \l{Property Binding in QML}{property bindings} also use Qt properties. + + Essentially, a Qt C++ property has a \i write function, \i read function, + and has a signal function. QML properties are inheritely public, both + readable and writable, albeit type-safe. QML properties may also have + signals which are emitted when the property value or binding changes. + + The QML property equivalent of a Qt C++ property is created as a property + with the \l Q_PROPERTY() macro. There needs to be C++ functions assigned as + the property's read, write, and signal handler function. + + The \l {register-c++-type}{Register a Type} section mentions that the + \c Person class has properties that are exposed to the QML context. The QML + properties are created with the \c Q_PROPERTY macro. The macro associates + the properties to the read, write, and singal functions in its argument. + +\code +Q_PROPERTY(int size READ size WRITE setSize NOTIFY shoeChanged) +\endcode + + A \c Shoe class might have an integer property called \c size. We set the \c + size() function as the \c READ function and the \c setSize() function to be + the \c WRITE function. In a QML application, when a property is read, the \c + size() is called and when the property's binding changes, the \c setSize() + is called. The READ function, by definition, must return the same type as + the property. + + We may also connect a \l{signals and slots}{signal} to a property. The \c + size property may have a \c shoeChanged signal indicated after the \c NOTIFY + parameter of the macro. The \c shoeChanged becomes a \l{QML Signal and + Handler Event System}{QML signal} and the runtime will create QML handler + called \c onShoeChanged. Whenever the size property's binding changes, the + \c shoeChanged signal is emitted and the \c onShoeChanged handler is + invoked. In the handler, commands such as \l{JavaScript Expressions in + QML}{JavaScript expressions} can perform clean-up operations or call other + functions. + + \bold{Note:} The QML signal handler will always be named + on<Property-name>Changed, regardless of the name used for the NOTIFY + signal in C++. We recommend using <property-name>Changed() for the + NOTIFY signal in C++. + + We may also make the property a \c read-only property by placing + \c CONSTANT in the parameter. Changing the binding will generate an error. +\code +//A read-only property +Q_PROPERTY(int size READ size CONSTANT) +\endcode + +\section2 Default Property + + When imported, QML components will bind their children to their designated + \l{default-property}{default property}. This is helpful, for example, + to redirect any declared child components to a property of another + component. + + The runtime can set a property to be the default property by tagging the + property with \c DefaultProperty in The Q_CLASSINFO() macro. + + \code + Q_CLASSINFO("DefaultProperty", "pipe") + \endcode + + The property tagged as default property, \c pipe, can only be an object + property, or a list property. + + A default property is optional. A derived class inherits its base class's + default property, but may override it in its own declaration. The \c pipe + property can refer to a property declared in the class itself, or a property + inherited from a base class. + + The \l{Extending QML - Default Property Example}{Default Property} example + uses \l{default-property}{default properties} to assign the children of + a component to a specific property. + + \section2 Grouped Properties + + A property group may be functionally defined as a set of related properties. + For example, the \l{Layouts with Anchors}{anchors} are a group of + related properties. In practice, property groups resemble a parent object + where the individual properties are accessed as children. + + A grouped property's member properties are accessed using the + <group>.<property> notation. For example, shoe.color is the way to access + the \c color property in the \c shoe property group . + + \snippet examples/declarative/cppextensions/referenceexamples/grouped/example.qml ungrouped + + Alternatively, the group can be accessed as a set. + \snippet examples/declarative/cppextensions/referenceexamples/grouped/example.qml grouped + + A grouped property block is implemented as a read-only object property. The + \c shoe property shown is declared like this: + + \snippet examples/declarative/cppextensions/referenceexamples/grouped/person.h 1 + + The \c ShoeDescription type declares the properties available to the grouped + property block - in this case the \c size, \c color, \c brand and \c price properties. + + Grouped property blocks may declared and accessed be recusively. + + \l {Extending QML - Grouped Properties Example} shows the complete code used to + implement the \c shoe property grouping. + + \section2 Attached Properties + + Attached properties annotate or add properties to another type or component. + For example, the \l Keys \i{attaching type} contains \i{attached properties} + that other elements may use to respond to key input. Conceptually, attached + properties are a \i type exporting a set of additional properties that can + be set on any other object instance. + + The attaching type is a QObject derived type. The properties on the + attaching type are those that become available for use as attached + properties. + + \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml 1 + + The \c BirthdayParty is called the attaching type and the + \c Boy instance the attachee object instance. The property \c rsvp is the + attached property. + + Any Qt C++ type can become an attaching type by declaring the \c + qmlAttachedProperties() a public member function and declaring that the + class has QML_HAS_ATTACHED_PROPERTIES. + + \code + static AttachedPropertiesType *qmlAttachedProperties(QObject *object); + \endcode + + This static pointer returns an attachment object, of type \a + AttachedPropertiesType, for the attachee \a object instance. It is + customary, though not strictly required, for the attachment object to be + parented to \a object to prevent memory leaks. + The \l {Extending QML - Attached Properties Example}{Birthday} + class has \c BirthdayPartyAttached attached properties. + + \snippet examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h static attached + + The QML_DECLARE_TYPEINFO() macro can notify the runtime that the type has + attached properties with the QML_HAS_ATTACHED_PROPERTIES argument. + + \snippet examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h declare attached + + The qmlAttachedProperties method will be called at most once for each + attachee object instance. The QML engine will cache the returned instance + pointer for subsequent attached property accesses. Consequently the + attachment object may not be deleted until \a object is destroyed. + + A common usage scenario is for a type to enhance the properties + available to its children in order to gather instance specific data. + + \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml begin + \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml rsvp + \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml end + + However, as a QML type cannot limit the instances to which the attachment + object must attach, the following is also allowed, even though adding a + birthday party rsvp in this context will have no effect. Instead, \c + BirthdayParty could be a separate component with a property \c rsvp. + \code + GraduationParty { + Boy { BirthdayParty.rsvp: "2009-06-01" } + } + \endcode + + From C++, including the attaching type implementation, the attachment object + for an instance can be accessed using the following method: + + \code + template<typename T> + QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true); + \endcode + + This returns the attachment object attached to \a attachee by the attaching + type \a T. If type \a T is not a valid attaching type, this method always + returns 0. If \a create is true, a valid attachment object will always be + returned, creating it if it does not already exist. If \a create is false, + the attachment object will only be returned if it has previously been + created. + + The \c rsvp properties of each guest in the \c Birthday party is accessible + through the \c qmlAttachedPropertiesObject function. + + \snippet examples/declarative/cppextensions/referenceexamples/attached/main.cpp query rsvp + + The + \l {Extending QML - Attached Properties Example}{Attached Properties Example} + demonstrates the creation of attached properties with a birthday party + scenario. + +\section2 Object and List Properties + + QML can set properties of types that are more complex than basic intrinsics like + integers and strings. Properties can also be object pointers, Qt interface + pointers, lists of object pointers, and lists of Qt interface pointers. As QML + is typesafe it ensures that only valid types are assigned to these properties, + just like it does for primitive types. + + Properties that are pointers to objects or Qt interfaces are declared with the + Q_PROPERTY() macro, just like other properties. The \c host property + declaration looks like this: + + \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1 + + As long as the property type, in this case \c Person, is registered with QML the + property can be assigned. + + QML also supports assigning Qt interfaces. To assign to a property whose type + is a Qt interface pointer, the interface must also be registered with QML. As + they cannot be instantiated directly, registering a Qt interface is different + from registering a new QML type. The following function is used instead: + + \code + template<typename T> + int qmlRegisterInterface(const char *typeName) + \endcode + + \c qmlRegisterInterface registers the C++ interface \a T with the QML system + as \a typeName. + + Following registration, QML can coerce objects that implement this interface + for assignment to appropriately typed properties. + + + \snippet examples/declarative/cppextensions/referenceexamples/properties/example.qml 0 + + The \c guests property is a \i{list property} of \c Person objects. A list + of \c Person objects are bound to the \c BirthdayParty's \c host property, + and assigns three \c Person objects to the guests property. + + Properties that are lists of objects or Qt interfaces are also declared with + the Q_PROPERTY() macro. However, list properties must have the type + \l{QDeclarativeListProperty}{QDeclarativeListProperty<T>}. + + \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 2 + + As with the other property types, the type of list content, \a T, must be + \l{register-c++-type}{registered} into the runtime. + + \snippet examples/declarative/cppextensions/referenceexamples/properties/main.cpp register list + + \l {Extending QML - Object and List Property Types Example} shows the + complete code used to create the \c BirthdayParty type. For more + information, visit \l{QDeclarativeListProperty}{QDeclarativeListProperty<T>} + for creating list properties. + +\section2 Sequence Types + + Certain C++ sequence types are supported transparently in QML as JavaScript + Array types. + In particular, QML currently supports: + \list + \o \c {QList<int>} + \o \c {QList<qreal>} + \o \c {QList<bool>} + \o \c {QList<QString>} and \c{QStringList} + \o \c {QList<QUrl>} + \endlist + + These sequence types are implemented directly in terms of the underlying C++ + sequence. There are two ways in which such sequences can be exposed to QML: + as a Q_PROPERTY of the given sequence type; or as the return type of a + Q_INVOKABLE method. There are some differences in the way these are + implemented, which are important to note. + + If the sequence is exposed as a Q_PROPERTY, accessing any value in the + sequence by index will cause the sequence data to be read from the QObject's + property, then a read to occur. Similarly, modifying any value in the + sequence will cause the sequence data to be read, and then the modification + will be performed and the modified sequence will be written back to the + QObject's property. + + If the sequence is returned from a Q_INVOKABLE function, access and mutation + is much cheaper, as no QObject property read or write occurs; instead, the + C++ sequence data is accessed and modified directly. + + Other sequence types are not supported transparently, and instead an + instance of any other sequence type will be passed between QML and C++ as an + opaque QVariantList. + + \bold {Important Note:} There are some minor differences between the + semantics of such sequence Array types and default JavaScript Array types + which result from the use of a C++ storage type in the implementation. In + particular, deleting an element from an Array will result in a + default-constructed value replacing that element, rather than an Undefined + value. Similarly, setting the length property of the Array to a value larger + than its current value will result in the Array being padded out to the + specified length with default-constructed elements rather than Undefined + elements. + + The default-constructed values for each sequence type are as follows: + \table + \row \o QList<int> \o integer value 0 + \row \o QList<qreal> \o real value 0.0 + \row \o QList<bool> \o boolean value \c {false} + \row \o QList<QString> and QStringList \o empty QString + \row \o QList<QUrl> \o empty QUrl + \endtable + + If you wish to remove elements from a sequence rather than simply replace + them with default constructed values, do not use the indexed delete operator + ("delete sequence[i]") but instead use the \c {splice} function + ("sequence.splice(startIndex, deleteCount)"). + + +\section2 Property Signals + + All properties on custom types automatically support property binding. + However, for binding to work correctly, QML must be able to reliably + determine when a property has changed so that it knows to reevaluate any + bindings that depend on the property's value. QML relies on the presence of + a \l {Qt's Property System}{NOTIFY signal} for this determination. + + Here is the \c host property declaration: + + \snippet examples/declarative/cppextensions/referenceexamples/binding/birthdayparty.h 0 + + The NOTIFY attribute is followed by a signal name. It is the responsibility + of the class implementer to ensure that whenever the property's value + changes, the NOTIFY signal is emitted. The signature of the NOTIFY signal is + not important to QML. + + To prevent loops or excessive evaluation, developers should ensure that the + signal is only emitted whenever the property's value is actually changed. If + a property, or group of properties, is infrequently used it is permitted to + use the same NOTIFY signal for several properties. This should be done with + care to ensure that performance doesn't suffer. + + To keep QML reliable, if a property does not have a NOTIFY signal, it cannot + be used in a binding expression. However, the property can still be assigned + a binding as QML does not need to monitor the property for change in that + scenario. + + Consider a custom type, \c TestElement, that has two properties, \c a and + \c b. Property \c a does \i not have a NOTIFY signal, and property \c b does + have a NOTIFY signal. + + \code + TestElement { + // This is OK + a: b + } + TestElement { + // Will NOT work + b: a + } + \endcode + + The presence of a NOTIFY signal does incur a small overhead. There are cases + where a property's value is set at object construction time, and does not + subsequently change. The most common case of this is when a type uses \l + {Grouped Properties}, and the grouped property object is allocated once, and + only freed when the object is deleted. In these cases, the CONSTANT + attribute may be added to the property declaration instead of a NOTIFY + signal. + + \snippet examples/declarative/cppextensions/referenceexamples/binding/person.h 0 + + Extreme care must be taken here or applications using your type may misbehave. + The CONSTANT attribute should only be used for properties whose value is set, + and finalized, only in the class constructor. All other properties that want + to be used in bindings should have a NOTIFY signal instead. + + \l {Extending QML - Binding Example} shows the BirthdayParty example updated to + include NOTIFY signals for use in binding. + +\section1 Signals Support + + A \l{signals and slots}{signal} in Qt C++ is readily available as a + \l{QML Signal and Handler Event System}{QML signal}. A signal will have + a corresponding signal \i{handler}, created automatically. The handler + name will have \c on prepended at the beginning of the name. The first + character of the signal is uppercased for the signal handler. The + signal parameter is also availabe to the QML signal. + + \snippet examples/declarative/cppextensions/referenceexamples/signal/birthdayparty.h 0 + The QML engine will create a handler for the \c partyStarted signal + called \c onPartyStarted. + \snippet examples/declarative/cppextensions/referenceexamples/signal/example.qml 0 + + Classes may have multiple signals with the same name, but only the final + signal is accessible as a QML signal. Note that signals with the same name + but different parameters cannot be distinguished from one another. + + Signal parameters are exposed and can be any one of the QML + \l{QML Basic Types}{basic types} as well registered object types. Accessing + unregistered types will not generate an error, but the parameter value will + not be accessible from the handler. + + To use signals from items not created in QML, access their signals with the + \l {Connections} element. + + Additionally, if a property is added to a C++ class, all QML elements + based on that C++ class will have a \i{value-changed} signal handler + for that property. The name of the signal handler is + \i{on<Property-name>Changed}, with the first letter of the property + name being upper case. + + The \l {Extending QML - Signal Support Example}{Signal Support Example} + shows an example application exposing signals to a QML component. + +\section1 Exposing Methods + + The Q_INVOKABLE macro exposes any Qt C++ method as a QML method. + + \snippet examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.h 0 + + In a QML file, we can invoke the method as we would a + \l{JavaScript Expressions in QML}{JavaScript expression}. + \snippet examples/declarative/cppextensions/referenceexamples/methods/example.qml 0 + + \l {Extending QML - Methods Example}{Methods example} uses the Q_INVOKABLE + method to expose methods and demonstrates some usages of the method in + an application. + + An alternative to the Q_INVOKABLE macro is to declare the C++ method as a + \l{signals and slot}{slot}. + + \code + slots: + void invite(const QString &name); + \endcode + +\section1 Type Revisions and Versions + + Type revisions and versions allow new properties or methods to exist in the + new version while remaining compatible with previous versions. + + Consider these two QML files: + \code + // main.qml + import QtQuick 1.0 + Item { + id: root + MyComponent {} + } + \endcode + + \code + // MyComponent.qml + import MyModule 1.0 + CppItem { + value: root.x + } + \endcode + where \c CppItem maps to the C++ class \c QCppItem. + + If the author of QCppItem adds a \c root property to QCppItem in a new + version of the module, \c root.x now resolves to a different value because + \c root is also the \c id of the top level component. The author could + specify that the new \c root property is available from a specific minor + version. This permits new properties and features to be added to existing + elements without breaking existing programs. + + The REVISION tag is used to mark the \c root property as added in revision 1 + of the class. Methods such as Q_INVOKABLE's, signals and slots can also be + tagged for a revision using the \c Q_REVISION(x) macro: + + \code + class CppElement : public BaseObject + { + Q_OBJECT + Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION 1) + + signals: + Q_REVISION(1) void rootChanged(); + }; + \endcode + + To register the new class revision to a particular version the following function is used: + + \code + template<typename T, int metaObjectRevision> + int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) + \endcode + + To register \c CppElement version 1 for \c {MyModule 1.1}: + + \code + qmlRegisterType<QCppElement,1>("MyModule", 1, 1, "CppElement") + \endcode + + \c root is only available when MyModule 1.1 is imported. + + For the same reason, new elements introduced in later versions should use + the minor version argument of qmlRegisterType. + + This feature of the language allows for behavioural changes to be made + without breaking existing applications. Consequently QML module authors + should always remember to document what changed between minor versions, and + QML module users should check that their application still runs correctly + before deploying an updated import statement. + + You may also register the revision of a base class that your module depends upon + using the qmlRegisterRevision() function: + + \code + template<typename T, int metaObjectRevision> + int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) + \endcode + + For example, if \c BaseObject is changed and now has a revision 1, you can specify that + your module uses the new revision: + + \code + qmlRegisterRevision<BaseObject,1>("MyModule", 1, 1); + \endcode + + This is useful when deriving from base classes not declared as part of your + module, e.g. when extending classes from the QtQuick library. + + The revision feature of QML allows for behavioral changes without breaking + existing applications. Consequently, QML module authors should always + remember to document what changed between minor versions, and QML module + users should check that their application still runs correctly before + deploying an updated import statement. + +\target qml-c++-coercion +\section1 Inheritance and Coercion + + QML supports C++ inheritance hierarchies and can freely coerce between + known, valid object types. This enables the creation of common base classes + that allow the assignment of specialized classes to object or list + properties. + + \snippet examples/declarative/cppextensions/referenceexamples/coercion/example.qml 0 + + The QML snippet shown above assigns a \c Boy object to the \c + BirthdayParty's \c host property, and assigns three other objects to the \c + guests property. Both the \c host and the \c guests properties binds to the + \c Person type, but the assignment is valid as both the \c Boy and \c Girl + objects inherit from \c Person. + + To assign to a property, the property's type must have been + \l{register-c++-type}{registered} to the \l{The QML Engine}{declarative + runtime}. If a type that acts purely as a base class that cannot be + instantiated from QML needs to be registered as well. The + \l qmlRegisterType() is useful for this occasion. + + \code + template<typename T> + int qmlRegisterType() + \endcode + + This function registers the C++ type \a T with the QML system. The + parameterless call to the template function qmlRegisterType() does not + define a mapping between the C++ class and a QML element name, so the type + is not instantiable from QML, but it is available for type coercion. + + \snippet examples/declarative/cppextensions/referenceexamples/coercion/main.cpp 0 + \snippet examples/declarative/cppextensions/referenceexamples/coercion/main.cpp register boy girl + The \c Person class is registered withouth the parameters. Both the + \c Boy and \c Girl class derive from the \c Person class. + + Type \a T must inherit QObject, but there are no restrictions on whether it + is concrete or the signature of its constructor. + + QML will automatically coerce C++ types when assigning to either an object + property, or to a list property. Only if coercion fails does an assignment + error occur. + + The \l{Extending QML - Inheritance and Coercion Example}{Inheritance and Coercion Example} + shows the complete code used to create the \c Boy and \c Girl types. + +\target qml-c++-extension +\section1 Extension Objects + + \snippet examples/declarative/cppextensions/referenceexamples/extended/example.qml 0 + + The \c leftMargin property is a new property to an existing C++ type, + \l QLineEdit, without modifying its source code. + + When integrating existing classes and technology into QML, APIs will + often need tweaking to fit better into the declarative environment. + Although the best results are usually obtained by modifying the original + classes directly, if this is either not possible or is complicated by some + other concerns, extension objects allow limited extension possibilities + without direct modifications. + + \i{Extension objects} add additional properties to an existing type. + Extension objects can only add properties, not signals or methods. An + extended type definition allows the programmer to supply an additional type, + known as the \i{extension type}, when registering the class. The + properties are transparently merged with the original target class when used + from within QML. + + The \l qmlRegisterExtendedType() is for registering extended types. Note + that it has two forms. + \code + template<typename T, typename ExtendedT> + int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) + + template<typename T, typename ExtendedT> + int qmlRegisterExtendedType() + \endcode + functions should be used instead of the regular \c qmlRegisterType() variations. + The arguments are identical to the corresponding non-extension registration functions, + except for the ExtendedT parameter which is the type + of the extension object. + + An extension class is a regular QObject, with a constructor that takes a + QObject pointer. However, the extension class creation is delayed until the + first extended property is accessed. The extension class is created and the + target object is passed in as the parent. When the property on the original + is accessed, the corresponding property on the extension object is used + instead. + + The \l{Extending QML - Extension Objects}{Extension Objects} example + demonstrates a usage of extension objects. + +\section1 Property Value Sources + +\snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 0 +\snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 1 + +The QML snippet shown above applies a property value source to the \c announcement property. +A property value source generates a value for a property that changes over time. + +Property value sources are most commonly used to do animation. Rather than +constructing an animation object and manually setting the animation's "target" +property, a property value source can be assigned directly to a property of any +type and automatically set up this association. + +The example shown here is rather contrived: the \c announcement property of the +\c BirthdayParty object is a string that is printed every time it is assigned and +the \c HappyBirthdaySong value source generates the lyrics of the song +"Happy Birthday". + +\snippet examples/declarative/cppextensions/referenceexamples/valuesource/birthdayparty.h 0 + +Normally, assigning an object to a string property would not be allowed. In +the case of a property value source, rather than assigning the object instance +itself, the QML engine sets up an association between the value source and +the property. + +Property value sources are special types that derive from the +QDeclarativePropertyValueSource base class. This base class contains a single method, +QDeclarativePropertyValueSource::setTarget(), that the QML engine invokes when +associating the property value source with a property. The relevant part of +the \c HappyBirthdaySong type declaration looks like this: + +\snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 0 +\snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 1 +\snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 2 + +In all other respects, property value sources are regular QML types. They must +be registered with the QML engine using the same macros as other types, and can +contain properties, signals and methods just like other types. + +When a property value source object is assigned to a property, QML first tries +to assign it normally, as though it were a regular QML type. Only if this +assignment fails does the engine call the \l {QDeclarativePropertyValueSource::}{setTarget()} method. This allows +the type to also be used in contexts other than just as a value source. + +\l {Extending QML - Property Value Source Example} shows the complete code used +to implement the \c HappyBirthdaySong property value source. + +\section1 Optimization and Other Considerations + +The \l{qml-engine-optimization}{ QML Engine} article suggests possible +optimization considerations as memory management and QVariant type usages. + +*/ diff --git a/doc/src/declarative/qmlviewer.qdoc b/doc/src/qml/qmlviewer.qdoc index df60c066e4..6439e95f4e 100644 --- a/doc/src/declarative/qmlviewer.qdoc +++ b/doc/src/qml/qmlviewer.qdoc @@ -26,13 +26,13 @@ ****************************************************************************/ /*! - \page qmlviewer.html -\inqmlmodule QtQuick 2 +\ingroup qtquick-tools \title QML Viewer \ingroup qttools +\brief a tool for testing and loading QML files -The Declarative UI package includes \QQV, a tool for loading QML documents that +The Declarative UI package includes QML Viewer, a tool for loading QML documents that makes it easy to quickly develop and debug QML applications. It invokes the QML runtime to load QML documents and also includes additional features useful for the development of QML-based applications. @@ -119,7 +119,7 @@ For example, this QML document refers to a \c lottoNumbers property which does not actually exist within the document: \qml -import QtQuick 1.0 +import QtQuick 2.0 ListView { width: 200; height: 300 @@ -132,7 +132,7 @@ If within the document's directory, there is a "dummydata" directory which contains a \c lottoNumbers.qml file like this: \qml -import QtQuick 1.0 +import QtQuick 2.0 ListModel { ListElement { number: 23 } @@ -147,7 +147,7 @@ Child properties are included when loaded from dummy data. The following documen refers to a \c clock.time property: \qml -import QtQuick 1.0 +import QtQuick 2.0 Text { text: clock.time } \endqml @@ -155,7 +155,7 @@ The text value could be filled by a \c dummydata/clock.qml file with a \c time property in the root context: \qml -import QtQuick 1.0 +import QtQuick 2.0 QtObject { property int time: 54321 } \endqml @@ -193,7 +193,7 @@ Rectangle { } \endqml -\note Since Qt Quick 1.1 this information is accessible outside of the QML Viewer, +\bold{Note:} Since Qt Quick 1.1 this information is accessible outside of the QML Viewer, through the \c active property of the \l {QML:Qt::application}{Qt.application} object. \row @@ -231,6 +231,5 @@ Rectangle { \endqml \endtable - */ diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/qml/qtbinding.qdoc index 4ec47a40f5..10581857dc 100644 --- a/doc/src/declarative/qtbinding.qdoc +++ b/doc/src/qml/qtbinding.qdoc @@ -27,12 +27,9 @@ /*! \page qtbinding.html -\inqmlmodule QtQuick 2 \ingroup qml-features -\previouspage {Extending QML Functionalities using C++} -\nextpage {Integrating QML Code with Existing Qt UI Code} -\contentspage QML Features \title Using QML Bindings in C++ Applications +\brief incorporating QML bindings in Qt C++ applications QML is designed to be easily extensible to and from C++. The classes in the Qt Declarative module allow QML components to be loaded and manipulated from C++, and through @@ -267,7 +264,7 @@ a displayable item. If the item is not displayable, it can simply inherit from Q For more information on defining new QML elements, see the \l {Tutorial: Writing QML extensions with C++} {Writing QML extensions with C++} tutorial and the -\l {Extending QML Functionalities using C++} reference documentation. +\l{Extending QML with C++} reference documentation. @@ -419,7 +416,7 @@ property. This property can be written to and read from QML: Notice the \c backgroundColorChanged signal is declared as the NOTIFY signal for the \c backgroundColor property. If a Qt property does not have an associated NOTIFY signal, -the property cannot be used for \l {Property Binding} in QML, as the QML engine would not be +the property cannot be used for \l{Property Binding in QML}, as the QML engine would not be notified when the value changes. If you are using custom types in QML, make sure their properties have NOTIFY signals so that they can be used in property bindings. @@ -508,7 +505,7 @@ can be registered using qmlRegisterUncreatableType(). To be accessible from QML must begin with a capital letter. See the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++} tutorial and -the \l {Extending QML Functionalities using C++} reference documentation for +the \l{Extending QML with C++} reference documentation for more information. @@ -518,7 +515,7 @@ C++ signals may pass enumeration values as signal parameters to QML, providing t and the signal are declared within the same class, or that the enumeration value is one of those declared in the \l {Qt}{Qt Namespace}. -Likewise, invokable C++ method parameters may be enumeration values providing +Likewise, invokable C++ method parameters may be enumeration values providing that the enumeration and the method are declared within the same class, or that the enumeration value is one of those declared in the \l {Qt}{Qt Namespace}. diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/qml/qtdeclarative.qdoc index c4b59fb07b..c4b59fb07b 100644 --- a/doc/src/declarative/qtdeclarative.qdoc +++ b/doc/src/qml/qtdeclarative.qdoc diff --git a/doc/src/declarative/qtjavascript.qdoc b/doc/src/qml/qtjavascript.qdoc index 1628503ec2..394435f77b 100644 --- a/doc/src/declarative/qtjavascript.qdoc +++ b/doc/src/qml/qtjavascript.qdoc @@ -34,9 +34,9 @@ /*! \page qtjavascript.html -\inqmlmodule QtQuick 2 \title Making Applications Scriptable \ingroup frameworks-technologies + \brief incorporating JavaScript in Qt applications. Qt provides support for application scripting with JavaScript. The following guides and references cover aspects of programming with diff --git a/doc/src/qml/qtprogrammers.qdoc b/doc/src/qml/qtprogrammers.qdoc new file mode 100644 index 0000000000..215f71859c --- /dev/null +++ b/doc/src/qml/qtprogrammers.qdoc @@ -0,0 +1,197 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qtprogrammers.html +\target qtprogrammers +\title QML for Qt Programmers +\brief learning QML for programmers with Qt knowledge + +While QML does not require Qt knowledge to use, if you \i are already familiar with Qt, +much of your knowledge is directly relevant to learning and using QML. Of course, +an application with a user interface defined in QML also uses Qt for all the non-UI +logic. + +\section1 Familiar Concepts + +QML provides direct access to the following concepts from Qt: + +\list + \o QAction - the \l {QML Basic Types}{action} type + \o QObject signals and slots - available as functions to call in JavaScript + \o QObject properties - available as variables in JavaScript + \o QWidget - QDeclarativeView is a QML-displaying widget + \o Qt models - used directly in data binding (QAbstractItemModel) +\endlist + +Qt knowledge is \i required for \l{Extending QML with C++}, +and also for \l{Integrating QML Code with existing Qt UI code}. + +\section1 QML Items Compared with Widgets + +QML Items are very similar to widgets: they define the look and feel of the user +interface. Note that, while widgets haven't traditionally been used to define the +look and feel of view delegates, QML Items can be used for this as well. + +There are three structurally different types of widget: + +\list + \o Simple widgets that are not used as parents (QLabel, QCheckBox, QToolButton, etc.) + \o Parent widgets that are normally used as parents to other widgets (QGroupBox, + QStackedWidget, QTabWidget, etc.) + \o Compound widgets that are internally composed of child widgets (QComboBox, + QSpinBox, QFileDialog, QTabWidget, etc.) +\endlist + +QML Items also serve these purposes. Each is considered separately below. + +\section2 Simple Widgets + +The most important rule to remember while implementing a new QDeclarativeItem in C++ +is that it should not contain any look and feel policies; leave that to the QML +usage of the item. + +As an example, imagine you wanted a reusable Button item. If you therefore decided +to write a QDeclarativeItem subclass to implement a button, just as QToolButton +subclasses QWidget for this purpose, following the rule above, your +\c QDeclarativeButton would not have any appearance; just the notions of enabled, +triggering, etc. + +However, there is already an object in Qt that does this: QAction. + +QAction is the UI-agnostic essence of QPushButton, QCheckBox, QMenu items, +QToolButton, and other visual widgets that are commonly bound to a QAction. + +So, the job of implementing a checkbox abstraction for QML is already done by QAction. +The look and feel of an action, the appearance of the button, the transition +between states, and exactly how it responds to mouse, key, or touch input, should +all be left for definition in QML. + +It is illustrative to note that QDeclarativeTextEdit is built upon QTextControl, +QDeclarativeWebView is built upon QWebPage, and ListView uses QAbstractItemModel, +just as QTextEdit, QWebView, and QListView are built upon those same UI-agnostic +components. + +The encapsulation of the look and feel that widgets provide is important, and for +this the QML concept of \l{QML Documents}{components} serves the same purpose. +If you are building a complete suite of applications which should have a +consistent look and feel, you should build a set of reusable components with the +look and feel you desire. + +So, to implement your reusable button, you would simply build a QML component. + + +\section2 Parent Widgets + +Parent widgets each provide a generic way to provide an interface to one or more +arbitrary 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 QScrollArea provides scrollbars around a widget that is otherwise too large to +fit in the available space. + +Nearly all such components can be created directly in QML. Only a few cases +which require very particular event handling, such as \l Flickable, require C++ +implementations. + +As an example, imagine you decided to make a generic tab widget item to be used +through your application suite wherever information is in such quantity that it +needs to be divided up into pages. + +A significant difference in the parenting concept with QML compare to QWidgets +is that while child items are positioned relative to their parents, there is no +requirement that they be wholly contained ("clipped") to the parent (although the +\l{Item::}{clipped} property of the child item does allow this where it is needed). +This difference has rather far-reaching consequences, for example: + +\list +\o A shadow or highlight around a widget could be a child of that widget. +\o Particle effects can flow outside the object where they originate. +\o Transitioning animations can "hide" items by visibly moving them beyond + the screen bounds. +\endlist + +\section2 Compound Widgets + +Some widgets provide functionality by composing other widgets as an "implementation +detail", providing a higher level API to the composition. QSpinBox for example is a +line edit and some buttons to increase/decrease the edited value. QFileDialog uses +a whole host of widgets to give the user a way of finding and selecting a file +name. + +When developing reusable QML Items, you may choose to do the same: build an item +composed of other items you have already defined. + +The only caveat when doing this is to consider the possible animations and +transitions that users of the compound item might wish to employ. For example, a +spinbox might need to smoothly transition from an arbitrary \l Text item, or +characters within a \l Text item, so your spinbox item would need to be sufficiently +flexible to allow such animation. + +\section1 QML Items Compared with Graphics Widgets + +The main difference between QML items and QGraphicsWidgets is how they are intended +to be used. The technical implementation details are much the same, but in practice +they are different because QML items are made for declarative and compositional use, +and QGraphicsWidgets are made for imperative and more integrated use. Both QML items +and QGraphicsWidgets inherit from QGraphicsObject, and can co-exist. The differences +are in the layout system and the interfacing with other components. Note that, as +QGraphicsWidgets tend more to be all-in-one packages, the equivalent of a +QGraphicsWidget may be many QML items composed across several QML files, but it can +still be loaded and used as a single QGraphicsObject from C++. + +QGraphicsWidgets are usually designed to be laid out with QGraphicsLayouts. QML does +not use QGraphicsLayouts, as the Qt layouts do not mix well with animated and fluid +UIs, so the geometry interface is one of the main differences. When writing QML +elements, you allow the designers to place their bounding rectangle using absolute +geometry, bindings or anchors (all set up for you when you inherit QDeclarativeItem) +and you do not use layouts or size hints. If size hints are appropriate, then place +them in the QML documentation so that the designers know how to use the item best, +but still have complete control over the look and feel. + +The other main difference is that QGraphicsWidgets tend to follow the widget model, +in that they are a self-contained bundle of UI and logic. In contrast, QML +primitives are usually a single purpose item that does not fulfill a use case on +its own, but is composed into the equivalent of the widget inside the QML file. So +when writing QML Items, try to avoid doing UI logic or composing visual elements +inside the items. Try instead to write more general purpose primitives, so that the +look and feel (which involves the UI logic) can be written in QML. + +Both differences are caused by the different method of interaction. QGraphicsWidget +is a QGraphicsObject subclass which makes fluid UI development from C++ easier, and +QDeclarativeItem is a QGraphicsObject subclass which makes fluid UI development +from QML easier. The difference, therefore, is primarily one of the interface +exposed, and the design of the items that come with it; the declarative primitives +for QML and nothing for QGraphicsWidget, because you need to write your own UI +logic into the subclass. + +If you wish to use both QML and C++ to write the UI, for example to ease the +transition period, it is recommended to use QDeclarativeItem subclasses, although +you can use QGraphicsWidgets as well. To allow for easier use from C++, make the +root item of each C++ component a \l LayoutItem, and load individual "widgets" of +QML (possibly comprised of multiple files, and containing a self-contained bundle +of UI and logic) into your scene to replace individual QGraphicsWidgets one at a time. +*/ diff --git a/doc/src/declarative/scope.qdoc b/doc/src/qml/scope.qdoc index 3156ff6fa9..649653f9e3 100644 --- a/doc/src/declarative/scope.qdoc +++ b/doc/src/qml/scope.qdoc @@ -25,13 +25,14 @@ ** ****************************************************************************/ /*! -\page qdeclarativescope.html -\inqmlmodule QtQuick 2 +\page qml-scope.html +\contentspage QML Reference +\ingroup qml-features \title QML Scope - +\brief access hierarchy in QML \tableofcontents -QML property bindings, inline functions and imported JavaScript files all +QML property bindings, inline functions, and imported JavaScript files all run in a JavaScript scope. Scope controls which variables an expression can access, and which variable takes precedence when two or more names conflict. @@ -89,7 +90,7 @@ following example shows a simple QML file that accesses some enumeration values and calls an imported JavaScript function. \code -import QtQuick 1.0 +import QtQuick 2.0 import "code.js" as Code ListView { @@ -230,7 +231,7 @@ is used, the \c title property may resolve differently. \code // TitlePage.qml -import QtQuick 1.0 +import QtQuick 2.0 Item { property string title @@ -246,7 +247,7 @@ Item { } // TitleText.qml -import QtQuick 1.0 +import QtQuick 2.0 Text { property int size text: "<b>" + title + "</b>" @@ -262,7 +263,7 @@ to use property interfaces, like this: \code // TitlePage.qml -import QtQuick 1.0 +import QtQuick 2.0 Item { id: root property string title @@ -281,7 +282,7 @@ Item { } // TitleText.qml -import QtQuick 1.0 +import QtQuick 2.0 Text { property string title property int size @@ -295,8 +296,10 @@ Text { In addition to all the properties that a developer would normally expect on the JavaScript global object, QML adds some custom extensions to make UI or -QML specific tasks a little easier. These extensions are described in the -\l {QML Global Object} documentation. +QML specific tasks a little easier. The +\l{JavaScript Runtime}{JavaScript runtime} and the \l{QML Scope} articles +contain more information about the scoping +capabilities QML disallows element, id and property names that conflict with the properties on the global object to prevent any confusion. Programmers can be confident diff --git a/doc/src/declarative/qdeclarativesecurity.qdoc b/doc/src/qml/security.qdoc index 915f260290..262e560d33 100644 --- a/doc/src/declarative/qdeclarativesecurity.qdoc +++ b/doc/src/qml/security.qdoc @@ -26,10 +26,10 @@ ****************************************************************************/ /*! -\page qdeclarativesecurity.html -\inqmlmodule QtQuick 2 +\page qml-security.html \title QML Security \section1 QML Security +\brief the security model in QML The QML security model is that QML content is a chain of trusted content: the user installs QML content that they trust in the same way as they install native Qt applications, @@ -42,7 +42,7 @@ arbitrary downloaded JavaScript, nor instantiate arbitrary downloaded QML elemen For example, this QML content: \qml -import QtQuick 1.0 +import QtQuick 2.0 import "http://evil.com/evil.js" as Evil Component { diff --git a/doc/src/qtdeclarative.qdoc b/doc/src/qtdeclarative.qdoc new file mode 100644 index 0000000000..9669b6517a --- /dev/null +++ b/doc/src/qtdeclarative.qdoc @@ -0,0 +1,180 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\title Qt Quick +\page qtquick-reference.html +\inqmlmodule QtQuick 2 +\ingroup qt-gui-concepts +\ingroup overviews + +\brief Qt Quick provides a declarative framework for building highly +dynamic applications. + +For App Developers and Designers, who want to deliver apps with amazing user +experience, Qt provides the QML language, the Qt Quick Elements, and tools in Qt +Creator that make it faster than ever to transform your brilliant idea into a +winning App across mobile, embedded, and desktop platforms. + +\target qtquick-overviews +\div {class="threecolumn_area"} + \div {class="heading"} + QML Topics + \enddiv + QML is a declarative language for creating flexible and reusable + components. The QML runtime powers QML based applications. The runtime + includes a QML engine, JavaScript engine, and mechanism to bind to the Qt + Framework. + + \div {class=" threecolumn_piece"} + \div {class="heading"} + QML Essentials + \enddiv + \list + \o \l{QML Components}{Components} + \o \l{Properties and Property Binding in QML}{Properties and Property Binding} + \o \l{JavaScript Expressions in QML}{JavaScript Code} + \o \l{QML Signal and Handler Event System}{Signal and Handler Event System} + \o \l{QML Modules}{Modules} + \endlist + \list + \o \l{What's New in Qt Quick 2}{What's New in Qt Quick} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + QML Engine + \enddiv + \list + \o \l{The QML Engine} + \o \l{QML Global Object} + \o \l{Dynamic Object Management in QML}{Dynamic Object Management} + \o \l{QML Performance}{Performance} + \endlist + \enddiv + \div {class=" threecolumn_piece"} + \div {class="heading"} + Reference + \enddiv + \list + \o \l{QML Syntax} + \o \l{QML Basic Types}{Data Types} + \o \l{QML Coding Conventions}{Coding Conventions} + \o \l{QML Security}{Security Model} + \o \l{QML Scope}{Scope Model} + \o \l{QML Documents}{Documents} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + QML Bindings with Qt C++ + \enddiv + \list + \o \l{Creating QML Types} + \o \l{QML Plugins} + \o \l{Exposing C++ Models} + \o \l{Integrating QML Code with Existing Qt UI Code}{Qt Gui Porting Information} + \endlist + \enddiv + \div {class=" threecolumn_piece"} + \div {class="heading"} + Tools + \enddiv + \list + \o \l{QML Internationalization}{Internationalization} + \o \l{QtQuickTest Reference Documentation} + \o \l{Debugging QML} + \endlist + \enddiv +\enddiv +\div {class="threecolumn_area"} + \div {class="heading"} + Qt Quick Elements + \enddiv + Qt Quick Elements features graphical elements, user input system, + animation system, and data visualization through models and delegates. + \div {class="threecolumn_piece"} + \div {class="heading"} + Graphics and Special Effects + \enddiv + \list + \o \l{Qt Quick Basic Elements}{Basic Elements} + \o \l{Painting with Canvas API} + \o \l{Using the Qt Quick Particle System}{Particle Effects} + \o \l{Shader Effects in QML}{Shader Effects} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Anchoring and Layouts + \enddiv + \list + \o \l{Component Layouts} + \o \l{Layouts with Anchors} + \o \l{QML Right-to-left User Interfaces}{Right-to-left User Interfaces} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Mouse and Keyboard Input + \enddiv + \list + \o \l{QML Mouse Events}{Mouse Events} + \o \l{QML Text Handling and Validators}{Text Handling and Validators} + \o \l{Keyboard Focus in QML}{Keyboard Focus} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + States and Transitions + \enddiv + \list + \o \l{QML States}{States} + \o \l{QML Animation and Transitions}{Animation and Transitions} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Data with Models and Views + \enddiv + \list + \o \l{QML Models and Views}{Models and Views} + \endlist + \enddiv + \div {class="threecolumn_piece"} + \div {class="heading"} + Data Storage and Resources + \enddiv + \list + \o \l{QML Local Storage}{SQL Local Storage} + \o \l{Resource Loading and Network Transparency in QML}{Resources and Network Transparency} + \endlist + \enddiv +\enddiv + +*/ + diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/qtquick2/anchor-layout.qdoc index 6bd69caa9a..6e56768f8a 100644 --- a/doc/src/declarative/anchor-layout.qdoc +++ b/doc/src/qtquick2/anchor-layout.qdoc @@ -26,14 +26,12 @@ ****************************************************************************/ /*! -\page qml-anchor-layout.html -\inqmlmodule QtQuick 2 -\target anchor-layout +\page qtquick-anchorlayout.html \contentspage QML Features -\previouspage {Using QML Positioner and Repeater Items}{Component Layouts} -\nextpage {QML Mouse Events}{Mouse Events} -\title Anchor-based Layout in QML +\title Layouts with Anchors +\brief placing items with anchor properties +\target anchor-layout In addition to the more traditional \l Grid, \l Row, and \l Column, QML also provides a way to layout items using the concept of \i anchors. Each item can be thought of as having a set of 7 invisible "anchor lines": diff --git a/doc/src/declarative/animation.qdoc b/doc/src/qtquick2/animation.qdoc index e8c5b7b83b..626571f50e 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/qtquick2/animation.qdoc @@ -26,13 +26,10 @@ ****************************************************************************/ /*! -\page qdeclarativeanimation.html -\inqmlmodule QtQuick 2 +\page qtquick-animation.html \ingroup qml-features -\contentspage QML Features -\previouspage {QML States}{States} -\nextpage {QML Data Models}{Structuring Data with Models} \title QML Animation and Transitions +\brief the animation system in Qt Quick \keyword qml-animation-elements \section1 Animation and Transitions Elements diff --git a/doc/src/declarative/basicelements.qdoc b/doc/src/qtquick2/basicelements.qdoc index 20462f853f..ae212f1964 100644 --- a/doc/src/declarative/basicelements.qdoc +++ b/doc/src/qtquick2/basicelements.qdoc @@ -26,18 +26,17 @@ ****************************************************************************/ /*! -\page qmlbasicelements.html -\inqmlmodule QtQuick 2 +\page qtquick-basicelements.html \ingroup qml-features -\contentspage QML Features -\previouspage QML Features -\nextpage {QML Basic Types}{Data Types} +\title Qt Quick Basic Elements +\brief introduction to the Qt Quick Elements -\title QML Basic Elements - -QML's basic elements allow the easy inclusion of objects into the -scene. +Qt Quick includes \i elements for placing components. These can be combined +to form other components. +\code +import QtQuick 2.0 +\endcode \section1 Basic Elements This is a list of some of the elements readily available for users. \list @@ -54,16 +53,6 @@ This is a list of some of the elements readily available for users. For a complete list of QML elements, please visit the \l {QML Elements} page. -\section1 Properties and Qt Declarative Module - -When using QML elements, keep in mind that elements may possess properties that -other elements also possess. This is because QML and its underlying engine is -implemented in C++ using Qt. More importantly, the chain of property inheritance -is directly due to QML's use of the \l {Qt Declarative Module} and Qt's -\l {Meta-Object System}{meta-object} and \l {The Property System}{property} systems. For example, visual elements that have C++ implementation are sublcasses of -\l {QDeclarativeItem}. As a result, elements such as \l {Rectangle} and -\l {Text} elements inherit properties such as \c clip and \c smooth. - \section1 Item Element Many QML elements inherit \l Item properties. \c Item possesses important properties @@ -95,7 +84,7 @@ single line text input. \keyword qml-top-level-component \section1 Using Elements as the Top-Level Component -For creating components (or displaying a simple scene), there are different +For creating components, there are different elements that could be used as the top-level component. To display a simple scene, a \l Rectangle as the top-level component may suffice. \l Rectangle, \l FocusScope, \l Component, \l {QML:QtObject} {QtObject}, \l Item, are some of @@ -111,5 +100,32 @@ component is the top-level component, the visual properties should be aliased to the top-level to display the component properly. For more information on how to build upon QML elements, see the -\l{Importing Reusable Components} document. +\l{QML Components} document. + +\section1 Additional Elements + +The \l{QML Local Storage}{SQL Local Storage API} provides a JavaScript interface to an SQL relational +database. The import statement needs a namespace + +\code +import QtQuick.LocalStorage 2.0 as SQL +\endcode + +The \l{QML Module QtQuick.Particles 2}{QtQuick.Particles} module provides a +particle system for additional graphics. The +\l{qml-particlesystem.html}{Using the Qt Quick Particle System} article outlines +the system features. +\code +import QtQuick.Particles 2.0 +\endcode + +\section1 Extending and Importing Elements + +Components may use the basic elements to create new components or to add +functionality to existing components. In addition, external component sets +may exist to perform logic or provide plugins. + +To extend existing elements or to create a custom component, the articles +\l{Creating QML Types} and \l{The QML Engine} contain information about +registering new types into the QML engine. */ diff --git a/doc/src/declarative/behaviors-and-states.qdoc b/doc/src/qtquick2/behaviors-and-states.qdoc index f37976dc20..626b6e61e3 100644 --- a/doc/src/declarative/behaviors-and-states.qdoc +++ b/doc/src/qtquick2/behaviors-and-states.qdoc @@ -26,9 +26,9 @@ ****************************************************************************/ /*! -\page qml-behaviors-and-states.html -\inqmlmodule QtQuick 2 +\page qtquick-behaviors-states.html \title Using QML Behaviors with States +\brief animating property changes with behaviors \section1 Using Behaviors with States @@ -37,7 +37,7 @@ In some cases you may choose to use a Behavior to animate a property change caus Here's an example that shows the problem: \qml -import QtQuick 1.0 +import QtQuick 2.0 Rectangle { width: 400 @@ -90,7 +90,7 @@ While future versions of QML should be able to handle this situation more gracef 1. Use a transition to animate the change, rather than a Behavior. \qml -import QtQuick 1.0 +import QtQuick 2.0 Rectangle { width: 400 @@ -130,7 +130,7 @@ Rectangle { 2. Use a conditional binding to change the property value, rather than a state \qml -import QtQuick 1.0 +import QtQuick 2.0 Rectangle { width: 400 @@ -159,7 +159,7 @@ Rectangle { 3. Use only explicitly defined states, rather than an implicit base state \qml -import QtQuick 1.0 +import QtQuick 2.0 Rectangle { width: 400 diff --git a/doc/src/declarative/qmlwebkit.qdoc b/doc/src/qtquick2/canvaspainting.qdoc index fffc77b92c..8590c74913 100644 --- a/doc/src/declarative/qmlwebkit.qdoc +++ b/doc/src/qtquick2/canvaspainting.qdoc @@ -26,28 +26,19 @@ ****************************************************************************/ /*! -\page qmlwebkit.html -\inqmlmodule QtQuick 2 +\page qtquick-canvaspainting.html +\ingroup qml-features +\title Painting with Canvas API +\brief custom graphics with the Canvas API -\title QtWebKit QML Module +\section1 Canvas Element -Qt WebKit QML - -\section1 WebKit QML Elements \list -\o \l WebView + \o \l{Canvas} + \o \l{Context2D} \endlist -\section1 QtWebKit Module -The QtWebKit Module has a QML element, \l{WebView} for displaying web content -from a \c URL. - -Import the QtWebKit module before declaring a \c WebView element: -\snippet doc/src/snippets/declarative/webview/webview.qml import - -\section1 Simple Usage -\snippet doc/src/snippets/declarative/webview/webview.qml document -\image webview.png +The Canvas and Context2D elements implement the \l{HTML Canvas API 2D Context} +and allows applications to have custom painting routines. -\sa {Models and Views: WebView Example}{WebView Example}, {QML Web Browser} */ diff --git a/doc/src/declarative/elements.qdoc b/doc/src/qtquick2/elements.qdoc index 7146edba2f..4dde7216e5 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/qtquick2/elements.qdoc @@ -26,14 +26,15 @@ ****************************************************************************/ /*! - \page qdeclarativeelements.html -\inqmlmodule QtQuick 2 - \target elements - \title QML Elements - \brief A listing of standard QML elements. +\page qtquick-elements.html +\title QML Elements +\brief a listing of standard QML elements + + +\target elements These are the functionally grouped lists of QML elements as part of -\l{Qt Quick}. You can also browse the module pages for \l{QtQuick 1}, \l{QtQuick 2} and \l{QtQuick.Particles 2} +\l{Qt Quick}. You can also browse the module pages for \l{QtQuick 2} and \l{QtQuick.Particles 2} 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 @@ -334,3 +335,25 @@ Elements that provide lower-level animation control \generatelist{related} */ + +/*! + \group qml-shader-elements + \title QML Shader Elements + \ingroup qml-groups + + \brief Elements for using OpenGL shading language code together with the QML code. + + \generatelist{related} + +*/ + +/*! + \group qml-shader-elements + \title QML Shader Elements + \ingroup qml-groups + + \brief Elements for using OpenGL shading language code together with the QML code. + + \generatelist{related} + +*/ diff --git a/doc/src/declarative/focus.qdoc b/doc/src/qtquick2/focus.qdoc index 66579fd18a..05d797e7be 100644 --- a/doc/src/declarative/focus.qdoc +++ b/doc/src/qtquick2/focus.qdoc @@ -26,15 +26,10 @@ ****************************************************************************/ /*! -\target qmlfocus -\page qdeclarativefocus.html -\inqmlmodule QtQuick 2 +\page qtquick-keyboardfocus.html \ingroup qml-features -\contentspage QML Features -\previouspage {QML Text Handling and Validators}{Text Handling and Validators} -\nextpage {QML Signal and Handler Event System}{Signal and Handler Event System} - \title Keyboard Focus in QML +\brief handling keyboard focus 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 diff --git a/doc/src/qtquick2/modelview.qdoc b/doc/src/qtquick2/modelview.qdoc new file mode 100644 index 0000000000..56c726eab8 --- /dev/null +++ b/doc/src/qtquick2/modelview.qdoc @@ -0,0 +1,378 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qtquick-modelview.html +\title QML Models and Views +\brief how to display and form data in QML + +Simply put, applications need to form data and display the data. QML has the +notion of \i models, \i views, and \i delegates to display data. They modularize +the visualization of data in order to give the developer or designer control +over the different aspects of the data. A developer can swap a list view with a +grid view with little changes to the data. Similarly, encapsulating an instance +of the data in a delegate allows the developer to dictate how to present or +handle the data. + +\image modelview-overview.png +\list +\o \bold Model - contains the data and its structure. There are several QML +elements for creating models. +\o \bold View - a container that displays the data. The view might +display the data in a list or a grid. +\o \bold Delegate - dictates how the data should appear in the view. +The delegate takes each data in the model and encapsulates it. The data is +accessible through the delegate. +\endlist + +To visualize data, bind the view's \c model property to a model and the +\c delegate property to a component or an element. + +\section1 Displaying Data with Views + + Views are containers for collections of items. They are feature-rich and can be + customizable to meet style or behavior requirements. + + \keyword qml-view-elements + A set of standard views are provided in the basic set of Qt Quick + graphical elements: + + \list + \o \l{ListView} - arranges items in a horizontal or vertical list + \o \l{GridView} - arranges items in a grid within the available space + \o \l{PathView} - arranges items on a path + \endlist + + These elements have properties and behaviors exclusive to each element. + Visit their respective documentation for more information. + + \section2 Decorating Views + + Views allow visual customization through \i decoration properties such as + the \c header, \c footer, and \c section properties. By binding an object, + usually another visual object, to these properties, the views are + decoratable. A footer may include a \l Rectangle element showcasing borders + or a header that displays a logo on top of the list. + + Suppose that a specific club wants to decorate its members list with its brand + colors. A member list is in a \c model and the \c delegate will display the + model's content. + \snippet doc/src/snippets/declarative/listview-decorations.qml model + \snippet doc/src/snippets/declarative/listview-decorations.qml delegate + + The club may decorate the members list by binding visual objects to the \c + header and \c footer properties. The visual object may be defined inline, in + another file, or in a \l {Component} element. + \snippet doc/src/snippets/declarative/listview-decorations.qml decorations + \image listview-decorations.png + + \section2 Mouse and Touch Handling + + The views handle dragging and flicking of their content, however they do + not handle touch interaction with the individual delegates. In order for the + delegates to react to touch input, e.g. to set the \c currentIndex, a MouseArea + with the appropriate touch handling logic must be provided by the delegate. + + Note that if \c highlightRangeMode is set to \c StrictlyEnforceRange the + currentIndex will be affected by dragging/flicking the view, since the view + will always ensure that the \c currentIndex is within the highlight range + specified. + + + \section2 ListView Sections + + \l {ListView} contents may be grouped into \i sections, where related list + items are labeled according to their sections. Further, the sections may be + decorated with \l{qml-view-delegate}{delegates}. + + A list may contain a list indicating people's names and the team on which + team the person belongs. + \snippet doc/src/snippets/declarative/listview-sections.qml model + \snippet doc/src/snippets/declarative/listview-sections.qml delegate + + The ListView element has the \c section \l{Property Binding in QML#Attached + Properties}{attached property} that can combine adjacent and related + elements into a section. The section's \c property property is for selecting + which list element property to use as sections. The \c criteria can dictate + how the section names are displayed and the \c delegate is similar to the + views' \l {qml-view-delegate}{delegate} property. + \snippet doc/src/snippets/declarative/listview-sections.qml section + \image listview-section.png + +\keyword qml-view-delegate +\section1 View Delegates + + Views need a \i delegate to visually represent an item in a list. A view will + visualize each item list according to the template defined by the delegate. + Items in a model are accessible through the \c index property as well as the + item's properties. + \snippet doc/src/snippets/declarative/listview.qml delegate + \image listview-setup.png + + \section2 Accessing Views and Models from Delegates + + The list view to which the delegate is bound is accessible from the delegate + through the \c{ListView.view} property. Likewise, the GridView + \c{GridView.view} is available to delegates. The corresponding model and its + properties, therefore, are available through \c{ListView.view.model}. In + addition, any defined signals or methods in the model are also accessible. + + This mechanism is useful when you want to use the same delegate for a number + of views, for example, but you want decorations or other features to be + different for each view, and you would like these different settings to be + properties of each of the views. Similarly, it might be of interest to + access or show some properties of the model. + + In the following example, the delegate shows the property \i{language} of + the model, and the color of one of the fields depends on the property + \i{fruit_color} of the view. + + \snippet doc/src/snippets/declarative/models/views-models-delegates.qml rectangle + +\keyword qml-data-models +\section1 Models + + Data is provided to the delegate via named data roles which the delegate may + bind to. Here is a ListModel with two roles, \i type and \i age, and a + ListView with a delegate that binds to these roles to display their values: + + \snippet doc/src/snippets/declarative/qml-data-models/listmodel-listview.qml document + + If there is a naming clash between the model's properties and the delegate's + properties, the roles can be accessed with the qualified \i model name + instead. For example, if a \l Text element had \i type or \i age properties, + the text in the above example would display those property values instead of + the \i type and \i age values from the model item. In this case, the + properties could have been referenced as \c model.type and \c model.age + instead to ensure the delegate displays the property values from the model + item. + + A special \i index role containing the index of the item in the model is + also available to the delegate. Note this index is set to -1 if the item is + removed from the model. If you bind to the index role, be sure that the + logic accounts for the possibility of index being -1, i.e. that the item is + no longer valid. (Usually the item will shortly be destroyed, but it is + possible to delay delegate destruction in some views via a \c delayRemove + attached property.) + + Models that do not have named roles (such as the ListModel shown + below) will have the data provided via the \i modelData role. The \i + modelData role is also provided for models that have only one role. In this + case the \i modelData role contains the same data as the named role. + + QML provides several types of data models among the built-in set of QML + elements. In addition, models can be created with Qt C++ and then made + available to the \l{The QML Engine}{QML engine} for use by + QML components. For information about creating these models, visit the + \l{Exposing C++ Models} and \l{Creating QML Types} articles. + + The use of positioner items to arrange items from a model is covered in + \l{Generating Items with Repeaters}. + + \section2 ListModel + + ListModel is a simple hierarchy of elements specified in QML. The + available roles are specified by the \l ListElement properties. + + \snippet doc/src/snippets/declarative/qml-data-models/listelements.qml model + + The above model has two roles, \i name and \i cost. These can be bound + to by a ListView delegate, for example: + + \snippet doc/src/snippets/declarative/qml-data-models/listelements.qml view + + ListModel provides methods to manipulate the ListModel directly via JavaScript. + In this case, the first item inserted determines the roles available + to any views that are using the model. For example, if an empty ListModel is + created and populated via JavaScript, the roles provided by the first + insertion are the only roles that will be shown in the view: + + \snippet doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml model + \dots + \snippet doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml mouse area + + When the MouseArea is clicked, \c fruitModel will have two roles, \i cost and \i name. + Even if subsequent roles are added, only the first two will be handled by views + using the model. To reset the roles available in the model, call ListModel::clear(). + + + \section2 XmlListModel + + XmlListModel allows construction of a model from an XML data source. The roles + are specified via the \l XmlRole element. The element needs to be imported. + + \code + import QtQuick.XmlListModel 2.0 + \endcode + + + The following model has three roles, \i title, \i link and \i description: + \qml + XmlListModel { + id: feedModel + source: "http://rss.news.yahoo.com/rss/oceania" + query: "/rss/channel/item" + XmlRole { name: "title"; query: "title/string()" } + XmlRole { name: "link"; query: "link/string()" } + XmlRole { name: "description"; query: "description/string()" } + } + \endqml + + The \l{declarative/rssnews}{RSS News demo} shows how XmlListModel can + be used to display an RSS feed. + + + \section2 VisualItemModel + + VisualItemModel allows QML items to be provided as a model. + + This model contains both the data and delegate; the child items of a + VisualItemModel provide the contents of the delegate. The model + does not provide any roles. + + \snippet doc/src/snippets/declarative/models/visual-model-and-view.qml visual model and view + + Note that in the above example there is no delegate required. + The items of the model itself provide the visual elements that + will be positioned by the view. + + \section2 Integers as Models + + An integer can be used as a model that contains a certain number + of elements. In this case, the model does not have any data roles. + + The following example creates a ListView with five elements: + \qml + Item { + width: 200; height: 250 + + Component { + id: itemDelegate + Text { text: "I am item number: " + index } + } + + ListView { + anchors.fill: parent + model: 5 + delegate: itemDelegate + } + + } + \endqml + + + \section2 Object Instances as Models + + An object instance can be used to specify a model with a single object + element. The properties of the object are provided as roles. + + The example below creates a list with one item, showing the color of the \i + myText text. Note the use of the fully qualified \i model.color property to + avoid clashing with \i color property of the Text element in the delegate. + + \qml + Rectangle { + width: 200; height: 250 + + Text { + id: myText + text: "Hello" + color: "#dd44ee" + } + + Component { + id: myDelegate + Text { text: model.color } + } + + ListView { + anchors.fill: parent + anchors.topMargin: 30 + model: myText + delegate: myDelegate + } + } + \endqml + + \keyword qml-c++-models + \section2 C++ Data Models + + Models can be defined in C++ and then made available to QML. This mechanism + is useful for exposing existing C++ data models or otherwise complex + datasets to QML. + + For information, visit the \l{Exposing C++ Models} article. + + +\section1 Repeaters + +\div {class="float-right"} +\inlineimage repeater-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 +lots of items. A \l Repeater item is placed inside a positioner, and generates +items that the enclosing positioner arranges. + +Each Repeater creates a number of items by combining each element of data +from a model, specified using the \l{Repeater::model}{model} property, with +the template item, defined as a child item within the Repeater. +The total number of items is determined by the amount of data in the model. + +The following example shows a repeater used with a \l{#Grid}{Grid} item to +arrange a set of Rectangle items. The Repeater item creates a series of 24 +rectangles for the Grid item to position in a 5 by 5 arrangement. + +\snippet doc/src/snippets/declarative/repeaters/repeater-grid-index.qml document + +The number of items created by a Repeater is held by its \l{Repeater::}{count} +property. It is not possible to set this property to determine the number of +items to be created. Instead, as in the above example, we use an integer as +the model. This is explained in the \l{QML Data Models#An Integer}{QML Data Models} +document. + +It is also possible to use a delegate as the template for the items created +by a Repeater. This is specified using the \l{Repeater::}{delegate} property. + +\section1 Using Transitions + +Transitions can be used to animate items that are added to, moved within, +or removed from a positioner. + +Transitions for adding items apply to items that are created as part of a +positioner, as well as those that are reparented to become children of a +positioner. +Transitions for removing items apply to items within a positioner that are +deleted, as well as those that are removed from a positioner and given new +parents in a document. + +Additionally, changing the opacity of items to zero will cause them to +disappear using the remove transition, and making the opacity non-zero will +cause them to appear using the add transition. + + +*/ diff --git a/doc/src/declarative/mouseevents.qdoc b/doc/src/qtquick2/mouseevents.qdoc index 911dbc2c49..d981c7c1dd 100644 --- a/doc/src/declarative/mouseevents.qdoc +++ b/doc/src/qtquick2/mouseevents.qdoc @@ -26,13 +26,10 @@ ****************************************************************************/ /*! -\page mouseevents.html -\inqmlmodule QtQuick 2 -\title QML Mouse Events +\page qtquick-mouseevents.html \ingroup QML Features -\previouspage {Anchor-based Layout in QML}{Layouts using Anchors} -\nextpage {QML Text Handling and Validators}{Text Handling and Validators} -\contentspage QML Features +\title QML Mouse Events +\brief handling mouse events in QML \tableofcontents diff --git a/doc/src/declarative/positioners.qdoc b/doc/src/qtquick2/positioners.qdoc index 1171039a10..c7110f7cf9 100644 --- a/doc/src/declarative/positioners.qdoc +++ b/doc/src/qtquick2/positioners.qdoc @@ -26,21 +26,16 @@ ****************************************************************************/ /*! -\page qml-positioners.html -\inqmlmodule QtQuick 2 +\page qtquick-positioners.html \ingroup qml-features -\previouspage Property Binding -\nextpage Anchor-based Layout in QML -\contentspage QML Features -\title Using QML Positioner and Repeater Items - +\title Item Layouts Positioner items are container items that manage the positions and sizes of items in a declarative user interface. Positioners behave in a similar way to the \l{Widgets and Layouts}{layout managers} used with standard Qt widgets, except that they are also containers in their own right. -Positioners and repeaters make it easier to work with many items when they need +Positioners make it easier to work with many items when they need to be arranged in a regular layout. \section1 Positioners @@ -66,7 +61,6 @@ uses a Column item to arrange three \l Rectangle items in an area defined by an outer \l Item. The \l{Column::spacing}{spacing} property is set to include a small amount of space between the rectangles. -\clearfloat \snippet doc/src/snippets/declarative/column/column.qml document Note that, since Column inherits directly from Item, any background color @@ -86,7 +80,6 @@ include a small amount of space between the rectangles. We ensure that the parent Rectangle is large enough so that there is some space left around the edges of the horizontally centered Row item. -\clearfloat \snippet doc/src/snippets/declarative/row.qml document \section2 Grid @@ -100,7 +93,6 @@ The following example uses a Grid item to place four \l Rectangle items in a 2-by-2 grid. As with the other positioners, the spacing between items can be specified using the \l{Grid::spacing}{spacing} property. -\clearfloat \snippet doc/src/snippets/declarative/grid-spacing.qml document There is no difference between horizontal and vertical spacing inserted @@ -130,7 +122,6 @@ The following example shows a Flow item containing a number of \l Text child items. These are arranged in a similar way to those shown in the screenshots. -\clearfloat \snippet doc/src/snippets/declarative/flow.qml document The main differences between the Grid and Flow positioners are that items @@ -139,54 +130,6 @@ items on one line may not be aligned with items on another line if the items do not have uniform sizes. As with Grid items, there is no independent control of spacing between items and between lines of items. -\section1 Repeaters - -\div {class="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 -lots of items. A \l Repeater item is placed inside a positioner, and generates -items that the enclosing positioner arranges. - -Each Repeater creates a number of items by combining each element of data -from a model, specified using the \l{Repeater::model}{model} property, with -the template item, defined as a child item within the Repeater. -The total number of items is determined by the amount of data in the model. - -The following example shows a repeater used with a \l{#Grid}{Grid} item to -arrange a set of Rectangle items. The Repeater item creates a series of 24 -rectangles for the Grid item to position in a 5 by 5 arrangement. - -\clearfloat -\snippet doc/src/snippets/declarative/repeaters/repeater-grid-index.qml document - -The number of items created by a Repeater is held by its \l{Repeater::}{count} -property. It is not possible to set this property to determine the number of -items to be created. Instead, as in the above example, we use an integer as -the model. This is explained in the \l{QML Data Models#An Integer}{QML Data Models} -document. - -It is also possible to use a delegate as the template for the items created -by a Repeater. This is specified using the \l{Repeater::}{delegate} property. - -\section1 Using Transitions - -Transitions can be used to animate items that are added to, moved within, -or removed from a positioner. - -Transitions for adding items apply to items that are created as part of a -positioner, as well as those that are reparented to become children of a -positioner. -Transitions for removing items apply to items within a positioner that are -deleted, as well as those that are removed from a positioner and given new -parents in a document. - -Additionally, changing the opacity of items to zero will cause them to -disappear using the remove transition, and making the opacity non-zero will -cause them to appear using the add transition. - \section1 Other Ways to Position Items There are several other ways to position items in a user interface. In addition diff --git a/doc/src/declarative/qmltexthandling.qdoc b/doc/src/qtquick2/qmltexthandling.qdoc index 22adf70fc0..876ab3c42f 100644 --- a/doc/src/declarative/qmltexthandling.qdoc +++ b/doc/src/qtquick2/qmltexthandling.qdoc @@ -26,13 +26,11 @@ ****************************************************************************/ /*! -\page texthandling.html -\inqmlmodule QtQuick 2 -\title QML Text Handling and Validators +\page qtquick-texthandling.html \ingroup QML Features -\previouspage {QML Mouse Events}{Mouse Events} -\nextpage {Keyboard Focus in QML}{Keyboard Focus} -\contentspage QML Features + +\title QML Text Handling and Validators +\brief elements that accept and handle text input \tableofcontents diff --git a/doc/src/declarative/qtquick-intro.qdoc b/doc/src/qtquick2/qtquick-intro.qdoc index f456111732..8aeab7e199 100644 --- a/doc/src/declarative/qtquick-intro.qdoc +++ b/doc/src/qtquick2/qtquick-intro.qdoc @@ -26,8 +26,7 @@ ****************************************************************************/ /*! -\page qml-intro.html -\inqmlmodule QtQuick 2 +\page qtquick-intro.html \title Introduction to Qt Quick Qt Quick is a collection of technologies that are designed to help developers @@ -44,35 +43,51 @@ environment (IDE) introduces tools for developing Qt Quick applications. \section1 The QML Language -QML is a high level, scripted language. Its commands, more correctly -\i elements, leverage the power and efficiency of the Qt libraries to make easy -to use commands that perform intuitive functions. Drawing a rectangle, -displaying an image, and application events -- all are possible with declarative -programming. +QML is a high level language that uses a declarative syntax to define how the +user interface should appear and behave. QML is used to build interfaces using +a collection of standard elements for fundamental user interface features. +These elements expose properties that can be changed at run-time, allowing +visual elements to be animated and used in transitions between states of the +user interfaces. -The language also allows more flexibility of these commands by using -\l{About JavaScript}{JavaScript} to implement the high level user interface -logic. +\div{class="float-left"} +\inlineimage qml-dialcontrol-example.png +\enddiv +A Dial element might define a \e value property that can be used to control +the position of the needle on the dial. The element could be declared to +use a slider that adjusts the value of this property. -A QML element usually has various \i properties that help define the element. -For example, if we created an element called Circle then the radius of the -circle would be a property. Building user interfaces by importing these elements -is one of the great feature of QML and Qt Quick. -\image qml-texteditor5_newfile.png +\snippet examples/declarative/ui-components/dialcontrol/qml/dialcontrol.qml the dial in use + +Building user interfaces by importing these elements and linking their properties +together is one of the fundamental features of QML and Qt Quick. + +\clearfloat +Behind the scenes, QML leverages the power and efficiency of the Qt libraries +to provide rendering facilities, perform processor-intensive operations, and +to access components written in C++. + +The QML language also gives the developer more flexibility to create parts +of their user interface by allowing \l{About JavaScript}{JavaScript} to be +used to implement high level user interface logic. + +\l{How to Learn QML} introduces the reader to the language and declarative +concepts. \section1 QtDeclarative Module -To make Qt Quick possible, Qt introduces the \l {QtDeclarative} module. The +To make Qt Quick possible, Qt introduces the \l{QtDeclarative} module. The module creates a JavaScript runtime that QML runs under with a Qt based backend. Because QtDeclarative and QML are built upon Qt, they inherit many of Qt's technology, namely the \l{Signals and Slots}{signals and slots} mechanism and the \l{The Meta-Object System}{meta-object} system. Data created using C++ are -directly accessible from QML and QML objects are also accessible from C++ code. +directly accessible from QML, and QML objects are also accessible from C++ code. -In conjunction with the QML language, the QtDeclarative module separates the -interface logic in QML from the application logic in C++. +The QtDeclarative module separates the interface logic in QML from the +application logic in C++. It also allows the range of standard QML elements +to be \l{Extending QML with C++}{extended with new ones written in C++}. -\section1 Creator Tools +\section1 Qt Creator Tools Qt Creator is a complete integrated development environment (IDE) for creating applications with Qt Quick and the Qt application framework. @@ -109,16 +124,20 @@ system. \section1 Where to Go from Here -The \l {Qt Quick} page has links to various Qt Quick topics such as QML +\l{external: Developing Qt Quick Applications with Creator} +{Developing Qt Quick Applications with Creator} provides an overview +of user interface development using the visual \e{Qt Quick Designer} tool. + +\l{How to Learn QML} introduces the reader to the language and declarative +concepts. + +The \l{QML Reference} page has links to various Qt Quick topics such as QML features, addons, and tools. -The \l {QML Examples and Demos} page has a gallery of QML applications. +The \l {Qt Quick Code Samples} page has a gallery of QML applications. \section1 License Information \list \o \l{Qt Quick Licensing Information} \endlist */ - - - diff --git a/doc/src/declarative/qtquick2.qdoc b/doc/src/qtquick2/qtquick2.qdoc index 6a1b7999c9..6a1b7999c9 100644 --- a/doc/src/declarative/qtquick2.qdoc +++ b/doc/src/qtquick2/qtquick2.qdoc diff --git a/doc/src/declarative/righttoleft.qdoc b/doc/src/qtquick2/righttoleft.qdoc index 43a7457d49..b2cff57ee0 100644 --- a/doc/src/declarative/righttoleft.qdoc +++ b/doc/src/qtquick2/righttoleft.qdoc @@ -26,10 +26,10 @@ ****************************************************************************/ /*! -\page qml-righttoleft.html -\inqmlmodule QtQuick 2 +\page qtquick-righttoleft.html +\ingroup qml-features \title QML Right-to-left User Interfaces - +\brief switching text flow and layout \section1 Overview This chapter discusses different approaches and options available for implementing right-to-left @@ -61,7 +61,7 @@ aligned to the right side of the text area. The alignment of a text element with its alignment cue from \l QInputMethod::inputDirection(), which is based on the active system locale. -This default locale-based alignment can be overriden by setting the \c horizontalAlignment +This default locale-based alignment can be overridden by setting the \c horizontalAlignment property for the text element, or by enabling layout mirroring using the \l LayoutMirroring attached property, which causes any explicit left and right horizontal alignments to be mirrored. Note that when \l LayoutMirroring is set, the \c horizontalAlignment property value remains unchanged; @@ -90,8 +90,8 @@ views that takes the mirroring into account can be read from the \c effectiveLay The attached property \l LayoutMirroring is provided as a convenience for easily implementing right-to-left support for existing left-to-right Qt Quick applications. It mirrors the behavior of \l {anchor-layout} -{Item anchors}, the layout direction of \l{Using QML Positioner and Repeater Items}{positioners} and -model views, and the explicit text alignment of QML text elements. +{Item anchors}, the layout direction of \l{Composing User Interfaces with QML#Positioners}{positioners} and +\l{QML Models and Views}{model views}, and the explicit text alignment of QML text elements. You can enable layout mirroring for a particular \l Item: diff --git a/doc/src/qtquick2/shaders.qdoc b/doc/src/qtquick2/shaders.qdoc new file mode 100644 index 0000000000..825eb29ac1 --- /dev/null +++ b/doc/src/qtquick2/shaders.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qtquick-shaders.html +\title Shader Effects in QML +\brief applying OpenGL vertex and fragment shaders to QML Rectangles + +\code +NOTE: This article is a work in progress. +\endcode + +\section1 Shaders +Describe Shaders and where it could be used in UIs or applications +Mention OpenGL shader language (GLSL) + +\section1 ShaderEffect Element +Introduce the \l{QtQuick2::ShaderEffect} Element. +Say what is possible and how to load shaders + +\section1 Shader Overview +Go over shaders in more detail and what shaders actually do. + +\section2 Vertex Shader +Go over vertex shaders + +\section2 Fragment Shader +Go over fragment shaders +*/ diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/qtquick2/states.qdoc index 16ed71a82a..559b4facac 100644 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ b/doc/src/qtquick2/states.qdoc @@ -26,15 +26,12 @@ ****************************************************************************/ /*! -\page qdeclarativestates.html -\inqmlmodule QtQuick 2 +\page qtquick-states.html \ingroup qml-features -\contentspage QML Features -\previouspage {Importing Reusable Components} -\nextpage {QML Animation and Transitions}{Animation and Transitions} -\target qmlstates \title QML States +\brief creating and setting states in QML +\target qmlstates \section1 States Elements \list \o \l State @@ -85,7 +82,7 @@ model the states using the \c State element and the color and flag configurations with the \c PropertyChanges element. \snippet doc/src/snippets/declarative/states.qml signal states The \l PropertyChanges element will change the values of object properties. -Objects are referenced through their \l {qml-id-property}{id}. Objects outside +Objects are referenced through their \l {qml-id}{id}. Objects outside the component are also referenced using the \c id property, exemplified by the property change to the external \c flag object. diff --git a/doc/src/qtquick2/writingcomponents.qdoc b/doc/src/qtquick2/writingcomponents.qdoc new file mode 100644 index 0000000000..64d28eff0b --- /dev/null +++ b/doc/src/qtquick2/writingcomponents.qdoc @@ -0,0 +1,498 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qtquick-writecomponents.html +\title Writing QML Components +\brief creating and initializing QML components + +\code +NOTE: This article is a work in progress. +\endcode + +One of the key concepts in QML is the ability to define your own QML components that suit +the purposes of your application. The standard \l {QML Elements} provide the essential components +for creating a QML application; beyond these, you can write your own custom components that can +be created and reused, without the use of C++. + +Components are the building blocks of a QML project. When writing a QML application, whether +large or small, it is best to separate QML code into smaller components that perform specific +sets of operations, instead of creating mammoth QML files with large, combined functionality +that is more difficult to manage and may contain duplicated code. + + +\section1 Defining New Components + +A component is a reusable type with a well-defined interface, built entirely in QML. +Any snippet of QML code can become a component, by placing the code in a file "<Name>.qml" where +<Name> is the new component name, beginning with an uppercase letter. These QML files automatically +become available as new QML element types to other QML components and applications in the same directory. + +For example, one of the simplest and most common components you can build in QML is a +button-type component. Below, we implement this component as a \l Rectangle with a clickable +\l MouseArea, in a file named \c Button.qml: + +\snippet doc/src/snippets/declarative/qml-extending-types/components/Button.qml 0 + +Now this component can be reused by another file within the same directory. Since the file is +named \c Button.qml, the component is referred to as \c Button: + +\table +\row +\o \snippet doc/src/snippets/declarative/qml-extending-types/components/application.qml 0 +\o \image qml-extending-types.png +\endtable + +The root object in \c Button.qml defines the attributes that are available to users of the +\c Button component. In this case, the root object is a \l Rectangle, so any properties, methods +and signals of \l Rectangle are made available, allowing \c application.qml to +customize the \c width, \c height, \c radius and \c color properties of \c Button objects. + + +If \c Button.qml was not in the same directory, \c application.qml would need to load it as a +\l {Modules}{module} from a specific filesystem path or \l{QDeclarativeExtensionPlugin}{plugin}. +Also, note the letter case of the component file name is significant on some (notably UNIX) +filesystems. It is recommended the file name case matches the case of the QML component name +exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the +QML component will be deployed. + +To write a useful component, it is generally necessary to provide it with custom attributes that store and +communicate specific data. This is achieved by adding the following attributes to your components: + +\list +\o \bold Properties that can be accessed externally to modify an object (for example, \l Item has + \l {Item::}{width} and \l {Item::}{height} properties) and used in \l {Property Binding} +\o \bold Methods of JavaScript code can be invoked internally or externally (for example, + \l Animation has a \l {Animation::}{start()} method) +\o \bold Signals to notify other objects when an event has occurred (for example, MouseArea has a + \c clicked signal) +\endlist + +The following sections show how these attributes can be added to QML components. + + +\section1 Adding Properties + +A property is a value of a QML component that can be read and modified by other objects. For +example, a \l Rectangle component has \l {Item::}{width}, \l {Item::}{height} and \l +{Rectangle::}{color} properties. Significantly, properties be used with \l {Property Binding}, where +a property value is automatically updated using the value of another property. + +The syntax for defining a new property is: + +\code +[default] property <type> <name>[: defaultValue] +\endcode + +A \c property declaration can appear anywhere within a QML component definition, but it is customary +to place it at the top. A component cannot declare more than one property with the same name. (It is +possible to have a property name that is the same as an existing property in a type, but this is not +recommended as the existing property becomes hidden and inaccessible.) + +Below is an example. The \c ImageViewer component has defined a \c string type property named +\c currentImage, and its initial value is "default-image.png". This property is used to set the image +displayed in the child \l Image object. Another file, \c application.qml, can create +an \c ImageViewer object and read or modify the \c currentImage value: + +\table +\row +\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/ImageViewer.qml 0 +\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/application.qml 0 +\endtable + +It is optional for a property to have a default value. The default value is a convenient shortcut, and is +behaviorally identical to doing it in two steps, like this: + +\qml +// Use default value +property int myProperty: 10 + +// Longer, but behaviorally identical +property int myProperty +myProperty: 10 +\endqml + + +\section2 Supported property types + +All QML properties are typed. The examples above show properties with \c int and \c string types; +notice that the type of the property must be declared. The type is used to determine the property +behavior, and how the property is defined in C++. + +A number of property types are supported by default. These are listed in the table below, +with their default values and the corresponding C++ type: + +\table +\header \o QML Type Name \o Default value \o C++ Type Name +\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 +\l {Defining new QML elements}{custom QML types} implemented in C++. Such properties are +defined like this: + +\qml +property Item itemProperty +property QtObject objectProperty +property MyCustomType customProperty +\endqml + +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: + +\qml +property list<Item> listOfItems +\endqml + +Note that list properties cannot be modified like ordinary JavaScript +arrays. See the \l {list}{list type documentation} for details. + + +\section2 Property change signals + +Adding a \c property to an item automatically adds a \e {value changed} +signal handler to the item. To connect to this signal, use a \l {Signal Handlers}{signal handler} +named with the \c on<Property>Changed syntax, using upper case for the first letter of the +property name. + +For example, the following \c onMyNumberChanged signal handler is automatically called whenever the +\c myNumber property changes: + +\snippet doc/src/snippets/declarative/qml-extending-types/properties/property-signals.qml 0 + + +\section2 Default properties + +The optional \c default attribute for a property marks it as the \e {default property} +for a type. This allows other items to specify the default property's value +as child elements. For example, the \l Item element's default property is its +\l{Item::children}{children} property. This allows the children of an \l Item +to be set like this: + +\qml +Item { + Rectangle {} + Rectangle {} +} +\endqml + +If the \l{Item::children}{children} property was not the default property for +\l Item, its value would have to be set like this instead: + +\qml +Item { + children: [ + Rectangle {} + Rectangle {} + ] +} +\endqml + +See the \l{declarative/ui-components/tabwidget}{TabWidget} example for a +demonstration of using default properties. + +Specifying a default property overrides any existing default property (for +example, any default property inherited from a parent item). Using the +\c default attribute twice in the same type block is an error. + + +\section2 Property aliases + +Property aliases are a more advanced form of property declaration. Unlike a +property definition, which allocates a new, unique storage space for the +property, a property alias connects the newly declared property (called the +aliasing property) as a direct reference to an existing property (the aliased property). Read +operations on the aliasing property act as read operations on the aliased +property, and write operations on the aliasing property as write operations on +the aliased property. + +A property alias declaration looks a lot like an ordinary property definition: +\code + [default] property alias <name>: <alias reference> +\endcode + +As the aliasing property has the same type as the aliased property, an explicit +type is omitted, and the special "alias" keyword is used. Instead of a default +value, a property alias includes a compulsory alias reference. The alias +reference is used to locate the aliased property. While similar to a property +binding, the alias reference syntax is highly restricted. + +An alias reference takes one of the following forms: +\code + <id>.<property> + <id> +\endcode + +where <id> must refer to an object id within the same component as the type +declaring the alias, and, optionally, <property> refers to a property on that object. + +For example, below is a \c Button.qml component with a \c buttonText aliased property which is +connected to the child Text object's \c text property: + +\snippet doc/src/snippets/declarative/qml-extending-types/properties/alias.qml 0 + +The following code would create a \c Button with a defined text string for the +child \l Text object: + +\qml +Button { buttonText: "This is a button" } +\endqml + +Here, modifying \c buttonText directly modifies the \c textItem.text value; it does not +change some other value that then updates \c textItem.text. + +In this case, the use of aliased properties is essential. If \c buttonText was not an alias, +changing its value would not actually change the displayed text at all, as +\l {Property Binding}{property bindings} are not bi-directional: the \c buttonText value would +change when \c textItem.text changes, but not the other way around. + +Aliased properties are also useful for allowing external objects to directly modify and +access child objects in a component. For example, here is a modified version of the \c ImageViewer +component shown \l {Adding Properties}{earlier} on this page. The \c currentImage property has +been changed to an alias to the child \l Image object: + +\table +\row +\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/alias/ImageViewer.qml 0 +\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/alias/application.qml 0 +\endtable + +Instead of being limited to setting the \l Image source, \c application.qml can now directly +access and modify the child \l Image object and its properties. + +Obviously, exposing child objects in this manner should be done with care, as it allows external +objects to modify them freely. However, this use of aliased properties can be quite useful in +particular situations, such as for the \l {declarative/ui-components/tabwidget}{TabWidget} +example, where new tab items are actually parented to a child object that displays the current tab. + + +\section3 Considerations for property aliases + +Aliases are only activated once the component specifying them is completed. The +most obvious consequence of this is that the component itself cannot generally +use the aliased property directly during creation. For example, this will not work: + +\code + // Does NOT work + property alias buttonText: textItem.text + buttonText: "Some text" // buttonText is not yet defined when this value is set +\endcode + +A second, much less significant, consequence of the delayed activation of +aliases is that an alias reference cannot refer to another aliasing property +declared within the same component. This will not work: + +\code + // Does NOT work + id: root + property alias buttonText: textItem.text + property alias buttonText2: root.buttonText +\endcode + +At the time the component is created, the \c buttonText value has not yet been assigned, +so \c root.buttonText would refer to an undefined value. (From outside the component, +however, aliasing properties appear as regular Qt properties and consequently can be +used in alias references.) + +It is possible for an aliased property to have the same name as an existing property. For example, +the following component has a \c color alias property, named the same as the built-in +\l {Rectangle::color} property: + +\snippet doc/src/snippets/declarative/qml-extending-types/properties/alias-override.qml 0 + +Any objects that use this component and refer to its \c color property will be +referring to the alias rather than the ordinary \l {Rectangle::color} property. Internally, +however, the rectangle can correctly set this property to "red" and refer to the actual defined +property rather than the alias. + + +\section1 Adding Methods + +A QML component can define methods of JavaScript code. These methods can be invoked +either internally or by other objects. + +The syntax for defining a method is: + +\code +function <name>([<parameter name>[, ...]]) { <body> } +\endcode + +This declaration may appear anywhere within a type body, but it is customary to +include it at the top. Attempting to declare two methods or signals with the +same name in the same type block is an error. However, a new method may reuse +the name of an existing method on the type. (This should be done with caution, +as the existing method may be hidden and become inaccessible.) + +Unlike \l{Adding Signals}{signals}, method parameter types do not have to be declared as they +default to the \c variant type. The body of the method is written in JavaScript and may access +the parameters by name. + +Here is an example of a component with a \c say() method that accepts a single \c text argument: + +\snippet doc/src/snippets/declarative/qml-extending-types/methods/app.qml 0 + +A method can be connected to a signal so that it is automatically invoked whenever the signal +is emitted. See \l {Connecting signals to methods and other signals} below. + +Also see \l {Integrating JavaScript} for more information on using JavaScript with QML. + + +\section1 Adding Signals + +Signals provide a way to notify other objects when an event has occurred. For example, the MouseArea +\c clicked signal notifies other objects that the mouse has been clicked within the area. + +The syntax for defining a new signal is: + +\code +signal <name>[([<type> <parameter name>[, ...]])] +\endcode + +This declaration may appear anywhere within a type body, but it is customary to +include it at the top. Attempting to declare two signals or methods with the +same name in the same type block is an error. However, a new signal may reuse +the name of an existing signal on the type. (This should be done with caution, +as the existing signal may be hidden and become inaccessible.) + +Here are three examples of signal declarations: + +\code +Item { + signal clicked + signal hovered() + signal performAction(string action, variant actionArgument) +} +\endcode + +If the signal has no parameters, the "()" brackets are optional. If parameters are used, the +parameter types must be declared, as for the \c string and \c variant arguments for the \c +performAction signal above; the allowed parameter types are the same as those listed in the \l +{Adding Properties} section on this page. + +Adding a signal to an item automatically adds a \l {Signal Handlers}{signal handler} as well. +The signal hander is named \c on<SignalName>, with the first letter of the signal being upper +cased. The above example item would now have the following signal handlers: + +\list +\o onClicked +\o onHovered +\o onPerformAction +\endlist + +To emit a signal, simply invoke it in the same way as a method. Below left, when the \l MouseArea is +clicked, it emits the parent \c buttonClicked signal by invoking \c rect.buttonClicked(). The +signal is received by \c application.qml through an \c onButtonClicked signal handler: + +\table +\row +\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/basic.qml 0 +\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/no-parameters.qml 0 +\endtable + +If the signal has parameters, they are accessible by parameter name in the signal handler. +In the example below, \c buttonClicked is emitted with \c xPos and \c yPos parameters instead: + +\table +\row +\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/Button.qml 0 +\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/parameters.qml 0 +\endtable + + +\section2 Connecting signals to methods and other signals + +Signal objects have a \c connect() method that can be used to a connect a signal to a method or +another signal. When a signal is connected to a method, the method is automatically invoked +whenever the signal is emitted. (In Qt terminology, the method is a \e slot that is connected +to the \e signal; all methods defined in QML are created as Qt slots.) This enables a signal +to be received by a method instead of a \l {Signal Handlers}{signal handler}. + +For example, the \c application.qml above could be rewritten as: + +\snippet doc/src/snippets/declarative/qml-extending-types/signals/connectslots.qml 0 + +The \c myMethod() method will be called whenever the \c buttonClicked signal is received. + +In many cases it is sufficient to receive signals through signal handlers rather than using +the \c connect() function; the above example does not provide any improvements over using a +simple \c onButtonClicked handler. However, if you are \l{Dynamic Object Management in QML}{creating objects dynamically}, +or \l {Integrating JavaScript}{integrating JavaScript code}, then you will find the +\c connect() method useful. For example, the component below creates three \c Button +objects dynamically, and connects the \c buttonClicked signal of each object to the +\c myMethod() function: + +\snippet doc/src/snippets/declarative/qml-extending-types/signals/connectdynamic.qml 0 + +In the same way, you could connect a signal to methods defined in a dynamically +created object, or \l {Receiving QML Signals in JavaScript}{connect a signal to a JavaScript method}. + +There is also a corresponding \c disconnect() method for removing connected signals. The following +code removes the connection created in \c application.qml above: + +\qml +// application.qml +Item { + ... + + function removeSignal() { + button.clicked.disconnect(item.myMethod) + } +} +\endqml + + +\section3 Forwarding signals + +The \c connect() method can also connect a signal to other signals. This has the effect +of "forwarding" a signal: it is automatically emitted whenever the relevant signal is emitted. For +example, the MouseArea \c onClicked handler in \c Button.qml above could have been replaced with +a call to \c connect(): + +\qml +MouseArea { + anchors.fill: parent + Component.onCompleted: clicked.connect(item.buttonClicked) +} +\endqml + +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/whatsnew.qdoc b/doc/src/whatsnew.qdoc index 05de859265..c7baa26047 100644 --- a/doc/src/declarative/whatsnew.qdoc +++ b/doc/src/whatsnew.qdoc @@ -94,8 +94,8 @@ The \l{QtQuick.Particles 2}{QtQuick.Particles} module contains elements that can New \l SpriteImage element renders animated sprites and can transition between animations. It uses the \l Sprite element to represent each animation. -MouseArea can now propagate clicked, doubleClicked and pressAndHold differently to pressed. -These can now be propagated to the highest-stacking-order enabled MouseArea which has a handler for them. +MouseArea now propagates clicked, doubleClicked and pressAndHold differently to pressed. +These will now be propagated to the highest-stacking-order enabled MouseArea which has a handler for them. You can still ignore these events in the handler to let them pass through. This behavior is triggered with the new property propagateComposedEvents. diff --git a/examples/declarative/cppextensions/referenceexamples/adding/person.h b/examples/declarative/cppextensions/referenceexamples/adding/person.h index 896bf4bd52..45fb2f3297 100644 --- a/examples/declarative/cppextensions/referenceexamples/adding/person.h +++ b/examples/declarative/cppextensions/referenceexamples/adding/person.h @@ -41,7 +41,7 @@ #define PERSON_H #include <QObject> -// ![0] +//![0] class Person : public QObject { Q_OBJECT @@ -60,6 +60,6 @@ private: QString m_name; int m_shoeSize; }; -// ![0] +//![0] #endif // PERSON_H diff --git a/examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h b/examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h index 02e9593b8b..c789c0bd51 100644 --- a/examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h +++ b/examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h @@ -75,12 +75,15 @@ public: int guestCount() const; Person *guest(int) const; + //! [static attached] static BirthdayPartyAttached *qmlAttachedProperties(QObject *); + //! [static attached] private: Person *m_host; QList<Person *> m_guests; }; +//! [declare attached] QML_DECLARE_TYPEINFO(BirthdayParty, QML_HAS_ATTACHED_PROPERTIES) - +//! [declare attached] #endif // BIRTHDAYPARTY_H diff --git a/examples/declarative/cppextensions/referenceexamples/attached/example.qml b/examples/declarative/cppextensions/referenceexamples/attached/example.qml index c21813ebf9..6a83af2804 100644 --- a/examples/declarative/cppextensions/referenceexamples/attached/example.qml +++ b/examples/declarative/cppextensions/referenceexamples/attached/example.qml @@ -40,32 +40,29 @@ import People 1.0 +//! [begin] BirthdayParty { - host: Boy { - name: "Bob Jones" - shoe { size: 12; color: "white"; brand: "Nike"; price: 90.0 } - } +//! [begin] +//! [rsvp] + Boy { + name: "Robert Campbell" + BirthdayParty.rsvp: "2009-07-01" + } +//! [rsvp] // ![1] - Boy { - name: "Leo Hodges" + Boy { + name: "Leo Hodges" shoe { size: 10; color: "black"; brand: "Reebok"; price: 59.95 } BirthdayParty.rsvp: "2009-07-06" } // ![1] - Boy { - name: "Jack Smith" + Boy { + name: "Jack Smith" shoe { size: 8; color: "blue"; brand: "Puma"; price: 19.95 } } - Girl { - name: "Anne Brown" - shoe.size: 7 - shoe.color: "red" - shoe.brand: "Marc Jacobs" - shoe.price: 699.99 - - BirthdayParty.rsvp: "2009-07-01" - } +//! [end] } +//! [end] diff --git a/examples/declarative/cppextensions/referenceexamples/attached/main.cpp b/examples/declarative/cppextensions/referenceexamples/attached/main.cpp index 21f076c3b7..4c2c3003fe 100644 --- a/examples/declarative/cppextensions/referenceexamples/attached/main.cpp +++ b/examples/declarative/cppextensions/referenceexamples/attached/main.cpp @@ -70,12 +70,13 @@ int main(int argc, char ** argv) for (int ii = 0; ii < party->guestCount(); ++ii) { Person *guest = party->guest(ii); + //! [query rsvp] QDate rsvpDate; - QObject *attached = - qmlAttachedPropertiesObject<BirthdayParty>(guest, false); + QObject *attached = qmlAttachedPropertiesObject<BirthdayParty>(guest, false); + if (attached) rsvpDate = attached->property("rsvp").toDate(); - + //! [query rsvp] if (rsvpDate.isNull()) qWarning() << " " << guest->name() << "RSVP date: Hasn't RSVP'd"; else diff --git a/examples/declarative/cppextensions/referenceexamples/coercion/main.cpp b/examples/declarative/cppextensions/referenceexamples/coercion/main.cpp index e0eabae4b4..95b309de4c 100644 --- a/examples/declarative/cppextensions/referenceexamples/coercion/main.cpp +++ b/examples/declarative/cppextensions/referenceexamples/coercion/main.cpp @@ -49,11 +49,14 @@ int main(int argc, char ** argv) QCoreApplication app(argc, argv); qmlRegisterType<BirthdayParty>("People", 1,0, "BirthdayParty"); -// ![0] + //![0] qmlRegisterType<Person>(); -// ![0] + //![0] + + //![register boy girl] qmlRegisterType<Boy>("People", 1,0, "Boy"); qmlRegisterType<Girl>("People", 1,0, "Girl"); + //![register boy girl] QDeclarativeEngine engine; QDeclarativeComponent component(&engine, QUrl("qrc:example.qml")); diff --git a/examples/declarative/cppextensions/referenceexamples/coercion/person.h b/examples/declarative/cppextensions/referenceexamples/coercion/person.h index 65faaf1521..dc4ae43dd6 100644 --- a/examples/declarative/cppextensions/referenceexamples/coercion/person.h +++ b/examples/declarative/cppextensions/referenceexamples/coercion/person.h @@ -69,13 +69,14 @@ public: Boy(QObject * parent = 0); }; - +//! [girl class] class Girl : public Person { Q_OBJECT public: Girl(QObject * parent = 0); }; +//! [girl class] // ![0] diff --git a/examples/declarative/cppextensions/referenceexamples/grouped/example.qml b/examples/declarative/cppextensions/referenceexamples/grouped/example.qml index 21e368abc4..9ae80f222e 100644 --- a/examples/declarative/cppextensions/referenceexamples/grouped/example.qml +++ b/examples/declarative/cppextensions/referenceexamples/grouped/example.qml @@ -44,30 +44,34 @@ import People 1.0 BirthdayParty { host: Boy { name: "Bob Jones" - shoe { size: 12; color: "white"; brand: "Nike"; price: 90.0 } + shoe { size: 12; color: "white"; brand: "Bikey"; price: 90.0 } } - Boy { - name: "Leo Hodges" - shoe { size: 10; color: "black"; brand: "Reebok"; price: 59.95 } + Boy { + name: "Leo Hodges" +//![grouped] + shoe { size: 10; color: "black"; brand: "Thebok"; price: 59.95 } +//![grouped] } // ![1] - Boy { - name: "Jack Smith" - shoe { + Boy { + name: "Jack Smith" + shoe { size: 8 color: "blue" - brand: "Puma" - price: 19.95 + brand: "Luma" + price: 19.95 } } // ![1] - Girl { - name: "Anne Brown" + Girl { + name: "Anne Brown" +//![ungrouped] shoe.size: 7 shoe.color: "red" - shoe.brand: "Marc Jacobs" - shoe.price: 699.99 + shoe.brand: "Job Macobs" + shoe.price: 699.99 +//![ungrouped] } } // ![0] diff --git a/examples/declarative/cppextensions/referenceexamples/methods/example.qml b/examples/declarative/cppextensions/referenceexamples/methods/example.qml index adc8cf7590..9119835e04 100644 --- a/examples/declarative/cppextensions/referenceexamples/methods/example.qml +++ b/examples/declarative/cppextensions/referenceexamples/methods/example.qml @@ -41,7 +41,6 @@ import QtQuick 2.0 import People 1.0 -// ![0] BirthdayParty { host: Person { name: "Bob Jones" @@ -53,6 +52,7 @@ BirthdayParty { Person { name: "Anne Brown" } ] +// ![0] Component.onCompleted: invite("William Green") -} // ![0] +} diff --git a/examples/declarative/cppextensions/referenceexamples/properties/main.cpp b/examples/declarative/cppextensions/referenceexamples/properties/main.cpp index d037d88f20..421ce9fbaa 100644 --- a/examples/declarative/cppextensions/referenceexamples/properties/main.cpp +++ b/examples/declarative/cppextensions/referenceexamples/properties/main.cpp @@ -48,8 +48,10 @@ int main(int argc, char ** argv) { QCoreApplication app(argc, argv); +//![register list] qmlRegisterType<BirthdayParty>("People", 1,0, "BirthdayParty"); qmlRegisterType<Person>("People", 1,0, "Person"); +//![register list] QDeclarativeEngine engine; QDeclarativeComponent component(&engine, QUrl("qrc:example.qml")); diff --git a/examples/declarative/cppextensions/referenceexamples/signal/example.qml b/examples/declarative/cppextensions/referenceexamples/signal/example.qml index ba792a8617..796c2f32a1 100644 --- a/examples/declarative/cppextensions/referenceexamples/signal/example.qml +++ b/examples/declarative/cppextensions/referenceexamples/signal/example.qml @@ -40,8 +40,8 @@ import People 1.0 -// ![0] BirthdayParty { +// ![0] onPartyStarted: console.log("This party started rockin' at " + time); // ![0] @@ -50,22 +50,22 @@ BirthdayParty { shoe { size: 12; color: "white"; brand: "Nike"; price: 90.0 } } - Boy { - name: "Leo Hodges" + Boy { + name: "Leo Hodges" BirthdayParty.rsvp: "2009-07-06" shoe { size: 10; color: "black"; brand: "Reebok"; price: 59.95 } } - Boy { - name: "Jack Smith" + Boy { + name: "Jack Smith" shoe { size: 8; color: "blue"; brand: "Puma"; price: 19.95 } } - Girl { - name: "Anne Brown" + Girl { + name: "Anne Brown" BirthdayParty.rsvp: "2009-07-01" shoe.size: 7 shoe.color: "red" shoe.brand: "Marc Jacobs" - shoe.price: 699.99 + shoe.price: 699.99 } // ![1] } |
