/*
XXX
-These sections have been temporarily removed from the
-"QML Application Developer Resources" page as we do not have any content
-for them yet.
+The "Features And Use-Case Solutions" section has been temporarily removed
+from the "QML Application Developer Resources" page as we do not have any
+content for them yet.
Once we have written content for these sections, they can be re-integrated.
-See QTBUG-26427 and QTBUG-26428
-
-
-\section1 Quick Start
-
-\list
-\li \l{qtquick-quickstart-basics.html}{QML Basics}
- \list
- \li \l{qtquick-quickstart-basics.html#creating-a-qml-document}{Creating A QML Document}
- \li \l{qtquick-quickstart-basics.html#importing-and-using-the-qtquick-module}{Importing And Using The QtQuick Module}
- \li \l{qtquick-quickstart-basics.html#loading-and-displaying-the-qml-document}{Loading And Displaying The QML Document}
- \endlist
-\li \l{qtquick-quickstart-essentials.html}{QML Essentials}
- \list
- \li \l{qtquick-quickstart-essentials.html#bindings-and-signals}{Bindings And Signals}
- \li \l{qtquick-quickstart-essentials.html#handling-user-input}{Handling User Input}
- \li \l{qtquick-quickstart-essentials.html#defining-custom-qml-types-for-re-use}{Defining Custom QML Types For Re-use}
- \endlist
-\endlist
+See QTBUG-26428
\section1 Features And Use-Case Solutions
information about the various QML types and other functionality provided by
Qt Quick.}
+\section1 Quick Start
+
+\list
+\li \l{qtquick-quickstart-basics.html}{QML Basics}
+ \list
+ \li \l{qtquick-quickstart-basics.html#creating-a-qml-document}{Creating A QML Document}
+ \li \l{qtquick-quickstart-basics.html#loading-and-displaying-the-qml-document}{Loading And Displaying The QML Document}
+ \endlist
+\li \l{qtquick-quickstart-essentials.html}{QML Essentials}
+ \list
+ \li \l{qtquick-quickstart-essentials.html#handling-user-input}{Handling User Input}
+ \li \l{qtquick-quickstart-essentials.html#property-bindings-and-animations}{Property Bindings And Animations}
+ \li \l{qtquick-quickstart-essentials.html#defining-custom-qml-types-for-re-use}{Defining Custom QML Types For Re-use}
+ \endlist
+\endlist
+
\section1 Important Application Development Topics
\list
\section1 Creating A QML Document
-\section1 Importing And Using The QtQuick Module
+A QML document defines a hierarchy of objects with a highly-readable,
+structured layout. Every QML document consists of two parts: an imports
+section and an object declaration section. The types and functionality most
+common to user interfaces are provided in the \l{Qt Quick Module}{QtQuick}
+import.
+
+\section2 Importing And Using The QtQuick Module
+
+To use the \l{Qt Quick Module}{QtQuick} module, a QML document needs to
+import it. The import syntax looks like this:
+
+\qml
+import QtQuick 2.0
+\endqml
+
+The types and functionality that \l{Qt Quick Module}{QtQuick} provides can now
+be used in the QML document!
+
+\section2 Defining An Object Hierarchy
+
+The object declaration in a QML document defines what will be displayed in the
+visual scene. \l{Qt Quick Module}{QtQuick} provides the basic building blocks
+for all user interfaces, including objects to display images and text, and to
+handle user input.
+
+A simple object declaration might be a colored rectangle with some text centered
+in it:
+
+\qml
+Rectangle {
+ width: 200
+ height: 100
+ color: "red"
+
+ Text {
+ anchors.centerIn: parent
+ text: "Hello, World!"
+ }
+}
+\endqml
+
+This defines an object hierarchy with a root \l Rectangle object
+which has a child \l Text object. The \c parent of the \l Text object is
+automatically set to the \l Rectangle, and similarly, the \l Text object is
+added to the \c children property of the \l Rectangle object, by QML.
+
+\section2 Putting It Together
+
+The \l Rectangle and \l Text types used in the above example are both provided
+by the \l{Qt Quick Module}{QtQuick} import. To use them, we need to import
+\l{Qt Quick Module}{QtQuick}. Putting the import and object declaration
+together, we get a complete QML document:
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+ width: 200
+ height: 100
+ color: "red"
+
+ Text {
+ anchors.centerIn: parent
+ text: "Hello, World!"
+ }
+}
+\endqml
+
+If we save that document as "HelloWorld.qml" we can load and display it.
\section1 Loading And Displaying The QML Document
+To display the graphical scene defined by the QML document, it may be loaded
+with the \l{Protoyping with qmlscene}{qmlscene} tool. The
+\l{Protoyping with qmlscene}{qmlscene} tool should be installed into the
+Qt installation directory. Assuming that the Qt binaries are installed into
+or are available in the system executable path, you can display the QML
+document with the following command:
+
+\code
+qmlscene HelloWorld.qml
+\endcode
+
+You should see the text "Hello, World!" in the center of a red rectangle.
+
*/
\title Quick Start Guide - QML Essentials
\brief Essential QML application development examples
-\section1 Bindings And Signals
-
\section1 Handling User Input
+One of the great advantages of using QML to define a user interface is that it
+allows the user interface designer to define how the application should react
+to events with simple JavaScript expressions. In QML, we refer to those events
+as \l{Signal and Handler Event System}{signals} and such signals can be handled
+with \l{qml-signals-and-handlers}{signal handlers}.
+
+For example, consider the following example:
+\qml
+import QtQuick 2.0
+
+Rectangle {
+ width: 200
+ height: 100
+ color: "red"
+
+ Text {
+ anchors.centerIn: parent
+ text: "Hello, World!"
+ }
+
+ MouseArea {
+ anchors.fill: parent
+ onClicked: parent.color = "blue"
+ }
+}
+\endqml
+
+This example can be saved as "ClickableHelloWorld.qml" and run with qmlscene.
+Whenever the user clicks anywhere in the window, the rectangle will change
+from red to blue. Note that the \l MouseArea type also emits the clicked
+signal for touch events, so this code will also work on a mobile device.
+
+Keyboard user input can be similarly handled with a simple expression:
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+ width: 200
+ height: 100
+ color: "red"
+
+ Text {
+ anchors.centerIn: parent
+ text: "Hello, World!"
+ }
+
+ focus: true
+ Keys.onPressed: {
+ if (event.key == Qt.Key_Return) {
+ color = "blue";
+ event.accepted = true;
+ }
+ }
+}
+\endqml
+
+By accepting focus, the color can be changed to blue whenever the return key
+is pressed.
+
+\section1 Property Bindings
+
+Objects and their properties form the basis of a graphical interface defined
+in a QML document. The QML language allows properties to be bound to each
+other in various ways, enabling highly dynamic user interfaces.
+
+In the following example, the geometry of each child \l Rectangle is bound to
+that of the parent \l Rectangle. If the geometry of the parent \l Rectangle
+were to change, the geometry of each child \l Rectangle would automatically
+update due to the property bindings.
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+ width: 400
+ height: 200
+
+ Rectangle {
+ width: parent.width / 2
+ height: parent.height
+ }
+
+ Rectangle {
+ width: parent.width / 2
+ height: parent.height
+ x: parent.width / 2
+ }
+}
+\endqml
+
+\section1 Animations
+
+Properties can also be dynamically updated via animations. The \c QtQuick
+import provides various animation types which can be used to animate changes
+to a property's value. In the following example, a property is animated which
+then gets displayed in a \l Text area:
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+ color: "lightgray"
+ width: 200
+ height: 200
+
+ property int animatedValue: 0
+ SequentialAnimation on animatedValue {
+ loops: Animation.Infinite
+ PropertyAnimation { to: 150; duration: 1000 }
+ PropertyAnimation { to: 0; duration: 1000 }
+ }
+
+ Text {
+ anchors.centerIn: parent
+ text: animatedValue
+ }
+}
+\endqml
+
+The value being displayed will vary from 0 to 150 periodically.
+
\section1 Defining Custom QML Types For Re-use
+One of the most important concepts in QML is that of type re-use. An
+application will probably have multiple visual elements which are all similar
+(for example, multiple push buttons), and QML allows these sort of things to
+be defined as re-usable, custom types, to minimize code duplication and
+maximize readability.
+
+For example, imagine that the developer defines a new \c Button type in the
+\c Button.qml file:
+
+\snippet qml/qml-extending-types/components/Button.qml 0
+
+That type may now be re-used multiple times in the application, as follows:
+
+\table
+\row
+\li \snippet qml/qml-extending-types/components/application.qml 0
+\li \image qml-extending-types.png
+\endtable
+
+
+In this way, modular user interface elements can be built up and re-used within
+an application.
+
+The Qt Quick Desktop Components project provides the most commonly used
+user interface elements (such as buttons, lists, scrollers, tabbed screens, and
+so forth) for both commercial and open-source use. Please see the
+Qt Quick Desktop Components home page on the Qt Project website for more
+information on how to use these components in applications.
+
See \l{qtquick-appdevguide-components.html}{Defining Resuable Components}
-for more details.
+for more details on how to develop your own reusable components.
*/
projects / platform / upstream / qtdeclarative.git / commitdiff