| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** 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. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| /*! |
| \page qmlfirststeps.html |
| \title First Steps with QML |
| \brief Basic QML application development examples |
| |
| \section1 Creating a QML Document |
| |
| 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 \c{QtQuick} |
| import. |
| |
| \section2 Importing and Using the QtQuick Module |
| |
| To use the \l{Qt Quick} module, a QML document needs to |
| import it. The import syntax looks like this: |
| |
| \code |
| import QtQuick 2.3 |
| \endcode |
| |
| The types and functionality that \l{Qt Quick} 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} provides the basic building blocks |
| for all user interfaces, such as the objects for displaying images and text and |
| for handling 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 All Together |
| |
| The \l Rectangle and \l Text types used in the above example are both provided |
| by the \c{QtQuick} import. Putting the import and object declaration |
| together, we get a complete QML document: |
| |
| \qml |
| import QtQuick 2.3 |
| |
| 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 Creating and Running QML Projects |
| |
| To display the graphical scene defined by the QML document, it may be loaded |
| with \l{Qt Creator Manual}{Qt Creator}. For simple UI files such as this one, |
| select \gui{File > New File or Project > Applications > Qt Quick UI} from |
| within Qt Creator. |
| |
| Pressing the green \gui{Run} button runs the application. You should see the |
| text \gui{Hello, World!} in the center of a red rectangle. |
| |
| For more information about creating and running projects in Qt Creator, visit |
| the following pages: |
| \list |
| \li \l{Qt Creator: Creating Qt Quick Projects}{Creating Qt Quick Projects} |
| \li \l{Qt Creator: Building and Running an Example}{Building and Running an Example} |
| \endlist |
| |
| \section1 Creating QML Applications with Controls |
| |
| While Qt Quick provides basic graphical elements, \l{Qt Quick Controls} provides |
| ready-made QML types for use within an application. |
| |
| Inserting the \l[QtQuickControls2]{ApplicationWindow} type is a good starting |
| point for creating applications. An application UI has this basic layout: |
| |
| \image applicationwindow.png |
| |
| Within each area, different \e controls may be added and connected to form |
| an application. For example, the following snippet is a basic application that |
| demonstrates the use of available space: |
| |
| \qml |
| //import related modules |
| import QtQuick 2.12 |
| import QtQuick.Controls 2.12 |
| |
| //window containing the application |
| ApplicationWindow { |
| |
| //title of the application |
| title: qsTr("Hello World") |
| width: 640 |
| height: 480 |
| |
| //menu containing two menu items |
| menuBar: MenuBar { |
| Menu { |
| title: qsTr("File") |
| MenuItem { |
| text: qsTr("&Open") |
| onTriggered: console.log("Open action triggered"); |
| } |
| MenuItem { |
| text: qsTr("Exit") |
| onTriggered: Qt.quit(); |
| } |
| } |
| } |
| |
| //Content Area |
| |
| //a button in the middle of the content area |
| Button { |
| text: qsTr("Hello World") |
| anchors.horizontalCenter: parent.horizontalCenter |
| anchors.verticalCenter: parent.verticalCenter |
| } |
| } |
| \endqml |
| |
| The application has two menu items and a button in the middle. Clicking on the |
| \uicontrol Exit menu item closes the application. |
| |
| There are also different navigation methods and different controls such as |
| buttons and sliders. The following examples are available from |
| Qt Creator and demonstrate different controls and layouts. |
| |
| \list |
| \li \l{Qt Quick Layouts - Basic Example}{Basic Layouts} |
| \li \l{Qt Quick Controls - Gallery} |
| \endlist |
| |
| Feel free to copy and paste the snippets onto this simple Hellow World |
| application to see how QML works. |
| |
| \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 these signals are handled by |
| \l{qml-signals-and-handlers}{signal handlers}. |
| |
| For example, consider the following example: |
| \qml |
| import QtQuick 2.12 |
| |
| Rectangle { |
| width: 200 |
| height: 100 |
| color: "red" |
| |
| Text { |
| anchors.centerIn: parent |
| text: "Hello, World!" |
| } |
| |
| TapHandler { |
| onTapped: 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 \l TapHandler also emits the tapped 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 |
| 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 |
| 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 |
| 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: parent.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 types 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 MessageLabel type in the |
| \c MessageLabel.qml file: |
| |
| \snippet qmlapp/qml-extending-types/components/MessageLabel.qml 0 |
| |
| That type may now be re-used multiple times in the application, as follows: |
| |
| \table |
| \row |
| \li \snippet qmlapp/qml-extending-types/components/application.qml 0 |
| \li \borderedimage qmlapp/qml-extending-types.gif |
| \endtable |
| |
| |
| In this way, modular user interface types are assembled and reused within |
| an application. |
| |
| See \l {QML Object Attributes} |
| for more details on how to develop your own reusable components. |
| |
| \section1 Where to Go from Here |
| |
| Now that you have seen QML in action, you are ready to take your next step. |
| The follow page will lead you in your journey with QML. |
| |
| \list |
| \li \l{QML Applications} |
| \li \l{Qt Examples and Tutorials} |
| \endlist |
| |
| */ |