diff --git a/doc/config/qtdoc.qdocconf b/doc/config/qtdoc.qdocconf index e9b4a7d3e..184b82592 100644 --- a/doc/config/qtdoc.qdocconf +++ b/doc/config/qtdoc.qdocconf @@ -115,7 +115,8 @@ include(../edu/config/qtforeducation.qdocconf) # doc/src/overviews.qdoc: # (qdoc) warning: '\generatelist explanations-webtechnologies' no such group # (qdoc) warning: '\generatelist explanations-positioning' no such group -warninglimit = 2 +# (qdoc) warning: '\generatelist explanations-programminglanguages' no such group +warninglimit = 3 # Autogenerate navigation linking based on "All Topics": navigation.toctitles = "All Topics" diff --git a/doc/images/qmlapp/qml-extending-types.gif b/doc/images/qmlapp/qml-extending-types.gif deleted file mode 100644 index 86ccb4787..000000000 Binary files a/doc/images/qmlapp/qml-extending-types.gif and /dev/null differ diff --git a/doc/images/qmlapp/qml-uses-animation.png b/doc/images/qmlapp/qml-uses-animation.png deleted file mode 100644 index b54361260..000000000 Binary files a/doc/images/qmlapp/qml-uses-animation.png and /dev/null differ diff --git a/doc/images/qmlapp/qml-uses-integratingjs.png b/doc/images/qmlapp/qml-uses-integratingjs.png deleted file mode 100644 index 3bb0d8aad..000000000 Binary files a/doc/images/qmlapp/qml-uses-integratingjs.png and /dev/null differ diff --git a/doc/images/qmlapp/qml-uses-layouts-anchors.png b/doc/images/qmlapp/qml-uses-layouts-anchors.png deleted file mode 100644 index 769597cf5..000000000 Binary files a/doc/images/qmlapp/qml-uses-layouts-anchors.png and /dev/null differ diff --git a/doc/images/qmlapp/qml-uses-layouts-direct.png b/doc/images/qmlapp/qml-uses-layouts-direct.png deleted file mode 100644 index 0682da36f..000000000 Binary files a/doc/images/qmlapp/qml-uses-layouts-direct.png and /dev/null differ diff --git a/doc/images/qmlapp/qml-uses-layouts-positioners.png b/doc/images/qmlapp/qml-uses-layouts-positioners.png deleted file mode 100644 index ebdd9c58d..000000000 Binary files a/doc/images/qmlapp/qml-uses-layouts-positioners.png and /dev/null differ diff --git a/doc/images/qmlapp/qml-uses-text.png b/doc/images/qmlapp/qml-uses-text.png deleted file mode 100644 index 6b3d88cb3..000000000 Binary files a/doc/images/qmlapp/qml-uses-text.png and /dev/null differ diff --git a/doc/images/qmlapp/qml-uses-visual-opacity.png b/doc/images/qmlapp/qml-uses-visual-opacity.png deleted file mode 100644 index ab238deb5..000000000 Binary files a/doc/images/qmlapp/qml-uses-visual-opacity.png and /dev/null differ diff --git a/doc/images/qmlapp/qml-uses-visual-rectangles.png b/doc/images/qmlapp/qml-uses-visual-rectangles.png deleted file mode 100644 index acf7cb160..000000000 Binary files a/doc/images/qmlapp/qml-uses-visual-rectangles.png and /dev/null differ diff --git a/doc/images/qmlapp/qml-uses-visual-transforms.png b/doc/images/qmlapp/qml-uses-visual-transforms.png deleted file mode 100644 index d89fc7525..000000000 Binary files a/doc/images/qmlapp/qml-uses-visual-transforms.png and /dev/null differ diff --git a/doc/snippets/qmlapp/codingconventions/dotproperties.qml b/doc/snippets/qmlapp/codingconventions/dotproperties.qml deleted file mode 100644 index c661c02c6..000000000 --- a/doc/snippets/qmlapp/codingconventions/dotproperties.qml +++ /dev/null @@ -1,31 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -import QtQuick - -Item { - -//! [0] -Rectangle { - anchors.left: parent.left; anchors.top: parent.top; anchors.right: parent.right; anchors.leftMargin: 20 -} - -Text { - text: "hello" - font.bold: true; font.italic: true; font.pixelSize: 20; font.capitalization: Font.AllUppercase -} - -//! [0] - -//! [1] -Rectangle { - anchors { left: parent.left; top: parent.top; right: parent.right; leftMargin: 20 } -} - -Text { - text: "hello" - font { bold: true; italic: true; pixelSize: 20; capitalization: Font.AllUppercase } -} -//! [1] - -} diff --git a/doc/snippets/qmlapp/codingconventions/javascript-imports.qml b/doc/snippets/qmlapp/codingconventions/javascript-imports.qml deleted file mode 100644 index 593e91884..000000000 --- a/doc/snippets/qmlapp/codingconventions/javascript-imports.qml +++ /dev/null @@ -1,10 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -import QtQuick - -//![0] -import "myscript.js" as Script - -Rectangle { color: "blue"; width: Script.calculateWidth(parent) } -//![0] diff --git a/doc/snippets/qmlapp/codingconventions/javascript-semicolons.qml b/doc/snippets/qmlapp/codingconventions/javascript-semicolons.qml deleted file mode 100644 index 230339614..000000000 --- a/doc/snippets/qmlapp/codingconventions/javascript-semicolons.qml +++ /dev/null @@ -1,14 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -import QtQuick - -//![0] -MouseArea { - anchors.fill: parent - onClicked: event => { - var scenePos = mapToItem(null, event.x, event.y); - console.log("MouseArea was clicked at scene pos " + scenePos); - } -} -//![0] diff --git a/doc/snippets/qmlapp/codingconventions/javascript.qml b/doc/snippets/qmlapp/codingconventions/javascript.qml deleted file mode 100644 index 88218abc9..000000000 --- a/doc/snippets/qmlapp/codingconventions/javascript.qml +++ /dev/null @@ -1,42 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -import QtQuick - -Rectangle { - -//![0] -Rectangle { - color: "blue" - width: parent.width / 3 -} -//![0] - -//![1] -Rectangle { - color: "blue" - width: { - var w = parent.width / 3; - console.debug(w); - return w; - } -} -//![1] - -//![2] -function calculateWidth(object : Item) : double -{ - var w = object.width / 3; - // ... - // more javascript code - // ... - console.debug(w); - return w; -} - -Rectangle { - color: "blue" - width: calculateWidth(parent) -} -//![2] -} diff --git a/doc/snippets/qmlapp/codingconventions/myscript.js b/doc/snippets/qmlapp/codingconventions/myscript.js deleted file mode 100644 index 60542369a..000000000 --- a/doc/snippets/qmlapp/codingconventions/myscript.js +++ /dev/null @@ -1,9 +0,0 @@ -function calculateWidth(parent) -{ - var w = parent.width / 3; - // ... - // more javascript code - // ... - console.debug(w); - return w; -} diff --git a/doc/snippets/qmlapp/codingconventions/photo.qml b/doc/snippets/qmlapp/codingconventions/photo.qml deleted file mode 100644 index 3863cf41c..000000000 --- a/doc/snippets/qmlapp/codingconventions/photo.qml +++ /dev/null @@ -1,58 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -import QtQuick - -//! [0] -Rectangle { - id: photo // id on the first line makes it easy to find an object - - property bool thumbnail: false // property declarations - property alias image: photoImage.source - - signal clicked // signal declarations - - function doSomething(x) // javascript functions - { - return x + photoImage.width; - } - - color: "gray" // object properties - x: 20 // try to group related properties together - y: 20 - height: 150 - width: { // large bindings - if (photoImage.width > 200) { - photoImage.width; - } else { - 200; - } - } - - states: [ - State { - name: "selected" - PropertyChanges { target: border; color: "red" } - } - ] - - transitions: [ - Transition { - from: "" - to: "selected" - ColorAnimation { target: border; duration: 200 } - } - ] - - Rectangle { // child objects - id: border - anchors.centerIn: parent - color: "white" - - Image { - id: photoImage - anchors.centerIn: parent - } - } -} -//! [0] diff --git a/doc/snippets/qmlapp/codingconventions/qualifiedaccess.qml b/doc/snippets/qmlapp/codingconventions/qualifiedaccess.qml deleted file mode 100644 index e0cca796f..000000000 --- a/doc/snippets/qmlapp/codingconventions/qualifiedaccess.qml +++ /dev/null @@ -1,16 +0,0 @@ -// Copyright (C) 2021 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -import QtQuick - -//![0] -Item { - id: root - - property int rectangleWidth: 50 - - Rectangle { - width: root.rectangleWidth - } -} -//![0] diff --git a/doc/snippets/qmlapp/codingconventions/signalhandler.qml b/doc/snippets/qmlapp/codingconventions/signalhandler.qml deleted file mode 100644 index 06f9c6061..000000000 --- a/doc/snippets/qmlapp/codingconventions/signalhandler.qml +++ /dev/null @@ -1,10 +0,0 @@ -// Copyright (C) 2021 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -import QtQuick - -//![0] -MouseArea { - onClicked: event => { console.log(`${event.x},${event.y}`); } -} -//![0] diff --git a/doc/snippets/qmlapp/qml-extending-types/components/MessageLabel.qml b/doc/snippets/qmlapp/qml-extending-types/components/MessageLabel.qml deleted file mode 100644 index 6701229e7..000000000 --- a/doc/snippets/qmlapp/qml-extending-types/components/MessageLabel.qml +++ /dev/null @@ -1,38 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause -//![0] -// MessageLabel.qml -import QtQuick - -Rectangle { - height: 50 - property string message: "debug message" - property var msgType: ["debug", "warning" , "critical"] - color: "black" - - Column { - anchors.fill: parent - padding: 5.0 - spacing: 2 - Text { - text: msgType.toString().toUpperCase() + ":" - font.bold: msgType == "critical" - font.family: "Terminal Regular" - color: msgType === "warning" || msgType === "critical" ? "red" : "yellow" - ColorAnimation on color { - running: msgType == "critical" - from: "red" - to: "black" - duration: 1000 - loops: msgType == "critical" ? Animation.Infinite : 1 - } - } - Text { - text: message - color: msgType === "warning" || msgType === "critical" ? "red" : "yellow" - font.family: "Terminal Regular" - } - } - -} -//![0] diff --git a/doc/snippets/qmlapp/qml-extending-types/components/application.qml b/doc/snippets/qmlapp/qml-extending-types/components/application.qml deleted file mode 100644 index 6def828a5..000000000 --- a/doc/snippets/qmlapp/qml-extending-types/components/application.qml +++ /dev/null @@ -1,33 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause -//![0] -// application.qml -import QtQuick -Window { - id: root - width: 180 - height: 180 - visible: true - Column { - anchors.fill: parent - padding: 1.5 - topPadding: 10.0 - bottomPadding: 10.0 - spacing: 5 - MessageLabel{ - width: root.width - 2 - msgType: "debug" - } - MessageLabel { - width: root.width - 2 - message: "This is a warning!" - msgType: "warning" - } - MessageLabel { - width: root.width - 2 - message: "A critical warning!" - msgType: "critical" - } - } -} -//![0] diff --git a/doc/snippets/qmlapp/qml_overview.qml b/doc/snippets/qmlapp/qml_overview.qml deleted file mode 100644 index 3368d7fef..000000000 --- a/doc/snippets/qmlapp/qml_overview.qml +++ /dev/null @@ -1,26 +0,0 @@ -// Copyright (C) 2020 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//! [file] -import QtQuick -import QtQuick.Controls - -ApplicationWindow { - width: 400 - height: 400 - visible: true - - Button { - id: button - text: "A Special Button" - background: Rectangle { - implicitWidth: 100 - implicitHeight: 40 - color: button.down ? "#d6d6d6" : "#f6f6f6" - border.color: "#26282a" - border.width: 1 - radius: 4 - } - } -} -//! [file] diff --git a/doc/snippets/qmlapp/qtbinding/resources/example.qrc b/doc/snippets/qmlapp/qtbinding/resources/example.qrc deleted file mode 100644 index 5e4941512..000000000 --- a/doc/snippets/qmlapp/qtbinding/resources/example.qrc +++ /dev/null @@ -1,10 +0,0 @@ - - - - - main.qml - images/background.png - - - - diff --git a/doc/snippets/qmlapp/qtbinding/resources/main.cpp b/doc/snippets/qmlapp/qtbinding/resources/main.cpp deleted file mode 100644 index e8ccde2fd..000000000 --- a/doc/snippets/qmlapp/qtbinding/resources/main.cpp +++ /dev/null @@ -1,20 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -#include -#include -#include - -//![0] -int main(int argc, char *argv[]) -{ - QApplication app(argc, argv); - - QQuickView view; - view.setSource(QUrl("qrc:/main.qml")); - view.show(); - - return app.exec(); -} -//![0] - diff --git a/doc/snippets/qmlapp/qtbinding/resources/main.qml b/doc/snippets/qmlapp/qtbinding/resources/main.qml deleted file mode 100644 index 0df237b7f..000000000 --- a/doc/snippets/qmlapp/qtbinding/resources/main.qml +++ /dev/null @@ -1,9 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -// main.qml -import QtQuick - -Image { source: "images/background.png" } -//![0] diff --git a/doc/snippets/qmlapp/qtbinding/resources/resources.pro b/doc/snippets/qmlapp/qtbinding/resources/resources.pro deleted file mode 100644 index 5aee288a6..000000000 --- a/doc/snippets/qmlapp/qtbinding/resources/resources.pro +++ /dev/null @@ -1,4 +0,0 @@ -QT += qml - -SOURCES += main.cpp -RESOURCES += example.qrc diff --git a/doc/snippets/qmlapp/usecases/animations.qml b/doc/snippets/qmlapp/usecases/animations.qml deleted file mode 100644 index 52a29d41b..000000000 --- a/doc/snippets/qmlapp/usecases/animations.qml +++ /dev/null @@ -1,146 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -import QtQuick - -Item { - - width: 320 - height: 480 - - Rectangle { - color: "#272822" - width: 320 - height: 480 - } - - Column { - //![states] - - Item { - id: container - width: 320 - height: 120 - - Rectangle { - id: rect - color: "red" - width: 120 - height: 120 - - TapHandler { - onTapped: container.state === '' ? container.state = 'other' : container.state = '' - } - } - states: [ - // This adds a second state to the container where the rectangle is farther to the right - - State { name: "other" - - PropertyChanges { - target: rect - x: 200 - } - } - ] - transitions: [ - // This adds a transition that defaults to applying to all state changes - - Transition { - - // This applies a default NumberAnimation to any changes a state change makes to x or y properties - NumberAnimation { properties: "x,y" } - } - ] - } - //![states] - //![behave] - Item { - width: 320 - height: 120 - - Rectangle { - color: "green" - width: 120 - height: 120 - - // This is the behavior, and it applies a NumberAnimation to any attempt to set the x property - Behavior on x { - - NumberAnimation { - //This specifies how long the animation takes - duration: 600 - //This selects an easing curve to interpolate with, the default is Easing.Linear - easing.type: Easing.OutBounce - } - } - - TapHandler { - onTapped: parent.x == 0 ? parent.x = 200 : parent.x = 0 - } - } - } - //![behave] - //![constant] - Item { - width: 320 - height: 120 - - Rectangle { - color: "blue" - width: 120 - height: 120 - - // By setting this SequentialAnimation on x, it and animations within it will automatically animate - // the x property of this element - SequentialAnimation on x { - id: xAnim - // Animations on properties start running by default - running: false - loops: Animation.Infinite // The animation is set to loop indefinitely - NumberAnimation { from: 0; to: 200; duration: 500; easing.type: Easing.InOutQuad } - NumberAnimation { from: 200; to: 0; duration: 500; easing.type: Easing.InOutQuad } - PauseAnimation { duration: 250 } // This puts a bit of time between the loop - } - - TapHandler { - // The animation starts running when you click within the rectangle - onTapped: xAnim.running = true - } - } - } - //![constant] - - //![scripted] - Item { - width: 320 - height: 120 - - Rectangle { - id: rectangle - color: "yellow" - width: 120 - height: 120 - - TapHandler { - // The animation starts running when you click within the rectangle - onTapped: anim.running = true; - } - } - - // This animation specifically targets the Rectangle's properties to animate - SequentialAnimation { - id: anim - // Animations on their own are not running by default - // The default number of loops is one, restart the animation to see it again - - NumberAnimation { target: rectangle; property: "x"; from: 0; to: 200; duration: 500 } - - NumberAnimation { target: rectangle; property: "x"; from: 200; to: 0; duration: 500 } - } - } - //![scripted] - } -} -//![0] diff --git a/doc/snippets/qmlapp/usecases/integratingjs-inline.qml b/doc/snippets/qmlapp/usecases/integratingjs-inline.qml deleted file mode 100644 index faccb5b2f..000000000 --- a/doc/snippets/qmlapp/usecases/integratingjs-inline.qml +++ /dev/null @@ -1,41 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -import QtQuick - -Item { - id: container - width: 320 - height: 480 - - function randomNumber() { - return Math.random() * 360; - } - - function getNumber() { - return container.randomNumber(); - } - - TapHandler { - // This line uses the JS function from the item - onTapped: rectangle.rotation = container.getNumber(); - } - - Rectangle { - color: "#272822" - width: 320 - height: 480 - } - - Rectangle { - id: rectangle - anchors.centerIn: parent - width: 160 - height: 160 - color: "green" - Behavior on rotation { RotationAnimation { direction: RotationAnimation.Clockwise } } - } - -} -//![0] diff --git a/doc/snippets/qmlapp/usecases/integratingjs.qml b/doc/snippets/qmlapp/usecases/integratingjs.qml deleted file mode 100644 index 0e36c1c2e..000000000 --- a/doc/snippets/qmlapp/usecases/integratingjs.qml +++ /dev/null @@ -1,33 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -import QtQuick -import "myscript.js" as Logic - -Item { - width: 320 - height: 480 - - Rectangle { - color: "#272822" - width: 320 - height: 480 - } - - TapHandler { - // This line uses the JS function from the separate JS file - onTapped: rectangle.rotation = Logic.getRandom(rectangle.rotation); - } - - Rectangle { - id: rectangle - anchors.centerIn: parent - width: 160 - height: 160 - color: "green" - Behavior on rotation { RotationAnimation { direction: RotationAnimation.Clockwise } } - } - -} -//![0] diff --git a/doc/snippets/qmlapp/usecases/layouts.qml b/doc/snippets/qmlapp/usecases/layouts.qml deleted file mode 100644 index d736775b1..000000000 --- a/doc/snippets/qmlapp/usecases/layouts.qml +++ /dev/null @@ -1,105 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![import] -import QtQuick - -//![import] - -Column { - -//![direct] -Item { - width: 100; height: 100 - - Rectangle { - // Manually positioned at 20,20 - x: 20 - y: 20 - width: 80 - height: 80 - color: "red" - } -} -//![direct] - -//![anchors] -Item { - width: 200; height: 200 - - Rectangle { - // Anchored to 20px off the top right corner of the parent - anchors.right: parent.right - anchors.top: parent.top - anchors.margins: 20 // Sets all margins at once - - width: 80 - height: 80 - color: "orange" - } - - Rectangle { - // Anchored to 20px off the top center corner of the parent. - // Notice the different group property syntax for 'anchors' compared to - // the previous Rectangle. Both are valid. - anchors { horizontalCenter: parent.horizontalCenter; top: parent.top; topMargin: 20 } - - width: 80 - height: 80 - color: "green" - } -} -//![anchors] - -//![positioners] -Item { - width: 300; height: 100 - - Row { // The "Row" type lays out its child items in a horizontal line - spacing: 20 // Places 20px of space between items - - Rectangle { width: 80; height: 80; color: "red" } - Rectangle { width: 80; height: 80; color: "green" } - Rectangle { width: 80; height: 80; color: "blue" } - } -} -//![positioners] - -Item { - width: 300; height: 400 - - Rectangle { - id: middleRect - //This Rectangle has its y animated, for the others to follow - x: 120 - y: 220 - SequentialAnimation on y { - loops: -1 - NumberAnimation { from: 220; to: 380; easing.type: Easing.InOutQuad; duration: 1200 } - NumberAnimation { from: 380; to: 220; easing.type: Easing.InOutQuad; duration: 1200 } - } - width: 80 - height: 80 - color: "green" - } - Rectangle { - // x,y bound to the position of middleRect - x: middleRect.x - 100 - y: middleRect.y - width: 80 - height: 80 - color: "red" - } - - Rectangle { - // Anchored to the position of middleRect - anchors.left: middleRect.right - anchors.leftMargin: 20 - anchors.verticalCenter: middleRect.verticalCenter - width: 80 - height: 80 - color: "blue" - } -} - -} diff --git a/doc/snippets/qmlapp/usecases/myscript.js b/doc/snippets/qmlapp/usecases/myscript.js deleted file mode 100644 index ff629d983..000000000 --- a/doc/snippets/qmlapp/usecases/myscript.js +++ /dev/null @@ -1,9 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -// myscript.js -function getRandom(previousValue) { - return Math.floor(previousValue + Math.random() * 90) % 360; -} -//![0] diff --git a/doc/snippets/qmlapp/usecases/styling.qml b/doc/snippets/qmlapp/usecases/styling.qml deleted file mode 100644 index 92c184144..000000000 --- a/doc/snippets/qmlapp/usecases/styling.qml +++ /dev/null @@ -1,29 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -import QtQuick -import QtQuick.Controls -import QtQuick.Window -import QtQuick.Controls.Styles - -ApplicationWindow { - - //![0] - Button { - text: qsTr("Hello World") - style: ButtonStyle { - background: Rectangle { - implicitWidth: 100 - implicitHeight: 25 - border.width: control.activeFocus ? 2 : 1 - border.color: "#FFF" - radius: 4 - gradient: Gradient { - GradientStop { position: 0 ; color: control.pressed ? "#ccc" : "#fff" } - GradientStop { position: 1 ; color: control.pressed ? "#000" : "#fff" } - } - } - } - //![0] - } -} diff --git a/doc/snippets/qmlapp/usecases/text.qml b/doc/snippets/qmlapp/usecases/text.qml deleted file mode 100644 index 2ae891053..000000000 --- a/doc/snippets/qmlapp/usecases/text.qml +++ /dev/null @@ -1,71 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -import QtQuick - -Item { - id: root - width: 480 - height: 320 - - Rectangle { - color: "#272822" - width: 480 - height: 320 - } - - Column { - spacing: 20 - - Text { - text: 'I am the very model of a modern major general!' - - // color can be set on the entire element with this property - color: "yellow" - - } - - Text { - // For text to wrap, a width has to be explicitly provided - width: root.width - - // This setting makes the text wrap at word boundaries when it goes - // past the width of the Text object - wrapMode: Text.WordWrap - - // You can use \ to escape quotation marks, or to add new lines (\n). - // Use \\ to get a \ in the string - text: 'I am the very model of a modern major general. I\'ve information \ - vegetable, animal and mineral. I know the kings of england and I \ - quote the fights historical; from Marathon to Waterloo in order categorical.' - - // color can be set on the entire element with this property - color: "white" - - } - - Text { - text: 'I am the very model of a modern major general!' - - // color can be set on the entire element with this property - color: "yellow" - - // font properties can be set effciently on the whole string at once - font { family: 'Courier'; pixelSize: 20; italic: true; capitalization: Font.SmallCaps } - - } - - Text { - // HTML like markup can also be used - text: 'I am the very model of a modern major general!' - - // This could also be written font { pointSize: 14 }. Both syntaxes are valid. - font.pointSize: 14 - - // StyledText format supports fewer tags, but is more efficient than RichText - textFormat: Text.StyledText - } - } -} -//![0] diff --git a/doc/snippets/qmlapp/usecases/userinput-keys.qml b/doc/snippets/qmlapp/usecases/userinput-keys.qml deleted file mode 100644 index f8f627345..000000000 --- a/doc/snippets/qmlapp/usecases/userinput-keys.qml +++ /dev/null @@ -1,34 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -import QtQuick - -Item { - id: root - - width: 320 - height: 480 - - Rectangle { - color: "#272822" - width: 320 - height: 480 - } - - Rectangle { - id: rectangle - x: 40 - y: 20 - width: 120 - height: 120 - color: "red" - - focus: true - Keys.onUpPressed: rectangle.y -= 10 - Keys.onDownPressed: rectangle.y += 10 - Keys.onLeftPressed: rectangle.x += 10 - Keys.onRightPressed: rectangle.x -= 10 - } -} -//![0] diff --git a/doc/snippets/qmlapp/usecases/userinput-text.qml b/doc/snippets/qmlapp/usecases/userinput-text.qml deleted file mode 100644 index 8df2634f9..000000000 --- a/doc/snippets/qmlapp/usecases/userinput-text.qml +++ /dev/null @@ -1,45 +0,0 @@ -// Copyright (C) 2018 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -import QtQuick -import QtQuick.Controls -import QtQuick.Layouts - -ApplicationWindow { - width: 300 - height: 200 - visible: true - - ColumnLayout { - anchors.fill: parent - TextField { - id: singleline - text: "Initial Text" - Layout.alignment: Qt.AlignHCenter | Qt.AlignTop - Layout.margins: 5 - background: Rectangle { - implicitWidth: 200 - implicitHeight: 40 - border.color: singleline.focus ? "#21be2b" : "lightgray" - color: singleline.focus ? "lightgray" : "transparent" - } - } - - TextArea { - id: multiline - placeholderText: "Initial text\n...\n...\n" - Layout.alignment: Qt.AlignLeft - Layout.fillWidth: true - Layout.fillHeight: true - Layout.margins: 5 - background: Rectangle { - implicitWidth: 200 - implicitHeight: 100 - border.color: multiline.focus ? "#21be2b" : "lightgray" - color: multiline.focus ? "lightgray" : "transparent" - } - } - } -} -//![0] diff --git a/doc/snippets/qmlapp/usecases/userinput.qml b/doc/snippets/qmlapp/usecases/userinput.qml deleted file mode 100644 index 74d24b66f..000000000 --- a/doc/snippets/qmlapp/usecases/userinput.qml +++ /dev/null @@ -1,32 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -import QtQuick - -Item { - id: root - - width: 320 - height: 480 - - Rectangle { - color: "#272822" - width: 320 - height: 480 - } - - Rectangle { - id: rectangle - x: 40 - y: 20 - width: 120 - height: 120 - color: "red" - - TapHandler { - onTapped: rectangle.width += 10 - } - } -} -//![0] diff --git a/doc/snippets/qmlapp/usecases/visual-opacity.qml b/doc/snippets/qmlapp/usecases/visual-opacity.qml deleted file mode 100644 index 4787c3891..000000000 --- a/doc/snippets/qmlapp/usecases/visual-opacity.qml +++ /dev/null @@ -1,46 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -import QtQuick - -Item { - - width: 320 - height: 480 - - Rectangle { - color: "#272822" - width: 320 - height: 480 - } - - Item { - x: 20 - y: 270 - width: 200 - height: 200 - MouseArea { - anchors.fill: parent - onClicked: topRect.visible = !topRect.visible - } - Rectangle { - x: 20 - y: 20 - width: 100 - height: 100 - color: "red" - } - Rectangle { - id: topRect - opacity: 0.5 - - x: 100 - y: 100 - width: 100 - height: 100 - color: "blue" - } - } -} -//![0] diff --git a/doc/snippets/qmlapp/usecases/visual-rects.qml b/doc/snippets/qmlapp/usecases/visual-rects.qml deleted file mode 100644 index e1b9256b0..000000000 --- a/doc/snippets/qmlapp/usecases/visual-rects.qml +++ /dev/null @@ -1,41 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -import QtQuick - -Item { - - width: 320 - height: 480 - - Rectangle { - color: "#272822" - width: 320 - height: 480 - } - - // This element displays a rectangle with a gradient and a border - Rectangle { - x: 160 - y: 20 - width: 100 - height: 100 - radius: 8 // This gives rounded corners to the Rectangle - gradient: Gradient { // This sets a vertical gradient fill - GradientStop { position: 0.0; color: "aqua" } - GradientStop { position: 1.0; color: "teal" } - } - border { width: 3; color: "white" } // This sets a 3px wide black border to be drawn - } - - // This rectangle is a plain color with no border - Rectangle { - x: 40 - y: 20 - width: 100 - height: 100 - color: "red" - } -} -//![0] diff --git a/doc/snippets/qmlapp/usecases/visual-transforms.qml b/doc/snippets/qmlapp/usecases/visual-transforms.qml deleted file mode 100644 index 30f9d38bf..000000000 --- a/doc/snippets/qmlapp/usecases/visual-transforms.qml +++ /dev/null @@ -1,35 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -import QtQuick - -Item { - - width: 320 - height: 480 - - Rectangle { - color: "#272822" - width: 320 - height: 480 - } - - Rectangle { - rotation: 45 // This rotates the Rectangle by 45 degrees - x: 20 - y: 160 - width: 100 - height: 100 - color: "blue" - } - Rectangle { - scale: 0.8 // This scales the Rectangle down to 80% size - x: 160 - y: 160 - width: 100 - height: 100 - color: "green" - } -} -//![0] diff --git a/doc/snippets/qmlapp/usecases/visual.qml b/doc/snippets/qmlapp/usecases/visual.qml deleted file mode 100644 index 36f21b378..000000000 --- a/doc/snippets/qmlapp/usecases/visual.qml +++ /dev/null @@ -1,29 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause - -//![0] -import QtQuick - -Item { - - width: 320 - height: 480 - - Rectangle { - color: "#272822" - width: 320 - height: 480 - } - - //![image] - // This element displays an image. Because the source is online, it may take some time to fetch - Image { - x: 40 - y: 20 - width: 61 - height: 73 - source: "http://codereview.qt-project.org/static/logo_qt.png" - } - //![image] -} -//![0] diff --git a/doc/src/images/applicationwindow.png b/doc/src/images/applicationwindow.png deleted file mode 100644 index 478cdda50..000000000 Binary files a/doc/src/images/applicationwindow.png and /dev/null differ diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index 93a075ecc..e27d8ff44 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -90,7 +90,6 @@ \li \l{Integrating Web Content}{Web Content} \endomit //! Not part of Qt 6 \li \l{Mobile Development} - \li \l{QML Applications} \li \l{Platform Integration} \endlist \list diff --git a/doc/src/qmlapp/applicationdevelopers.qdoc b/doc/src/qmlapp/applicationdevelopers.qdoc deleted file mode 100644 index 12ab375fe..000000000 --- a/doc/src/qmlapp/applicationdevelopers.qdoc +++ /dev/null @@ -1,127 +0,0 @@ -// Copyright (C) 2021 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -\page qmlapplications.html -\title QML Applications -\brief Essential documentation for QML application developers -\ingroup explanations-programminglanguages - -QML is a declarative language that allows user interfaces to be described in -terms of their visual components and how they interact and relate with one -another. It is a highly readable language that was designed to enable -components to be interconnected in a dynamic manner, and it allows components to -be easily reused and customized within a user interface. Using the \c QtQuick -module, designers and developers can easily build fluid animated user interfaces -in QML, and have the option of connecting these user interfaces to any back-end -C++ libraries. - - -\section1 What is QML? - -QML is a user interface specification and programming language. -It allows developers and designers alike to create highly performant, fluidly -animated and visually appealing applications. QML offers a highly readable, -declarative, JSON-like syntax with support for imperative JavaScript -expressions combined with dynamic property bindings. - -\snippet qmlapp/qml_overview.qml file - -The QML language and engine infrastructure is provided by the \l {Qt Qml} module. -For in-depth information about the QML language, please see the -\l{Qt Qml} module documentation. - -The following pages contain more information about QML: -\list -\li \l{First Steps with QML} - begin using QML with these examples -\li \l{\QC: Create Qt Quick Applications} -\li \l{The QML Reference} - reference about the QML constructs and features -\li \l{qml-codingconventions.html}{QML Coding Conventions} -\li \l{Glossary of QML Terms} -\li \l{All QML APIs by Module} -\endlist - -\section1 What is Qt Quick? - -Qt Quick is the standard library of QML types and functionality for QML. It -includes visual types, interactive types, animations, models and views, -particle effects and shader effects. A QML application developer can get -access to all of that functionality with a single import statement. - -The \c QtQuick QML library is provided by the \l{Qt Quick} module. -For in-depth information about the various QML types and other functionality -provided by Qt Quick, please see the \l{Qt Quick} module documentation. -Qt Quick adds visual types, animation types, and other QML types in addition to -the standard QML types from Qt Qml. - -\list -\li \l{qtquick-usecase-visual.html}{Visual types in QML} -\li \l{qtquick-usecase-userinput.html}{Responding to User Input in QML} -\li \l{qtquick-usecase-animations.html}{Animations in QML} -\li \l{qtquick-usecase-text.html}{Displaying Text in QML} -\li \l{qtquick-usecase-layouts.html}{Layouts in QML} -\li \l{qtquick-usecase-styling.html}{Style and Theme Support} -\li \l{qtquick-usecase-integratingjs.html}{Integrating JavaScript in QML} -\endlist - -\section2 Buttons, Menus, and other Controls - -For a set of UI controls, the \l{Qt Quick Controls} module implements several -controls such as buttons, menus, and views. These controls come with -several built-in styles that can be used, and also support the creation -of custom styles. - -\section1 Qt Quick Application Development - -\l{\QC Documentation}{\QC} has built-in support for creating Qt Quick -applications. \l{Qt VS Tools} and \l {Qt Extension for VS Code} -also allow you to create Qt Quick applications with Visual Studio and Visual -Studio Code. The \QMLLS can be used from any IDE supporting the language server -protocol. - -For a design centric workflow, use \QDS. - -For more information about creating Qt Quick applications, visit the following -pages: -\list -\li \l{\QC: Create Qt Quick Applications} -\li \l{\QDS: Getting Started} -\endlist - -\section1 Code Samples and Demos - -To learn more about uses of QML code, there are several code samples which show -how QML types are used. In addition, there are several demos which show how -QML code is used in applications. - -\list -\li \l{Getting Started Programming with Qt Quick} - a tutorial showing the creation of a simple QML text editor. -\li \l{Qt Quick Examples and Tutorials} -\endlist - -\section1 Advanced Application Development Topics - -\list -\li \l{Overview - QML and C++ Integration} -\li \l{qtquick-deployment.html}{Deploying QML Applications} -\li \l{Qt Quick Compiler} -\li \l{qtquick-bestpractices.html}{Best Practices for QML and Qt Quick} -\li \l{qtquick-performance.html}{QML Performance Considerations and Suggestions} -\li \l{Internationalization with Qt}{Internationalization and Localization} -\li Testing and Debugging - \list - \li \l{qml_runtime_tool}{Prototyping with the QML Runtime Tool} - \li \l{qtquick-debugging.html}{Debugging QML Applications} - \li \l{Qt Quick Test}{Qt Quick Test: QML Unit Testing Framework} - \endlist -\endlist - -\section1 Related Topics - -\list -\li \l{All QML Types} -\li \l{All QML APIs by Module} -\li \l{Obsolete QML Types} -\endlist - -*/ diff --git a/doc/src/qmlapp/codingconventions.qdoc b/doc/src/qmlapp/codingconventions.qdoc deleted file mode 100644 index 20dc4f1b9..000000000 --- a/doc/src/qmlapp/codingconventions.qdoc +++ /dev/null @@ -1,101 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -\page qml-codingconventions.html -\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. - -\section1 QML Object Declarations - -Throughout our documentation and examples, \l{QML Object Attributes}{QML object attributes} are always structured in the following order: - -\list -\li id -\li property declarations -\li signal declarations -\li JavaScript functions -\li object properties -\li child objects -\endlist - -For better readability, we separate these different parts with an empty line. - - -For example, a hypothetical \e photo QML object would look like this: - -\snippet qmlapp/codingconventions/photo.qml 0 - - -\section1 Grouped Properties - -If using multiple properties from a group of properties, -consider using \e {group notation} instead of \e {dot notation} if it -improves readability. - -For example, this: - -\snippet qmlapp/codingconventions/dotproperties.qml 0 - -could be written like this: - -\snippet qmlapp/codingconventions/dotproperties.qml 1 - -\section1 Unqualified access - -In order to improve readability and performance always reference properties of parent components by their id explicitly: - -\snippet qmlapp/codingconventions/qualifiedaccess.qml 0 - -\section1 Required properties - -When requiring data defined outside the component, make this explicit by using \l{Required Properties}. -Required properties must be set or else the creation of the component will fail. -These are preferable to unqualified lookups because they are more performant and allow for both -users and tooling to reason about an external property's type. -Additionally they remove assumptions that a component otherwise has to make about the environment -in which it is created. - -\section1 Signal handlers - -When handling parameters in signal handlers use functions which name them explicitly: - -\snippet qmlapp/codingconventions/signalhandler.qml 0 - -\section1 JavaScript Code - -For better readability and maintainability, we generally declare each property on a separate line, -even for simple expressions. - -\snippet qmlapp/codingconventions/javascript.qml 0 - -For script expressions spanning multiple lines, we use a block format: - -\snippet qmlapp/codingconventions/javascript.qml 1 - -If the script is more than a couple of lines long or can be used by different objects, we recommend creating a function and calling it like this: - -\snippet qmlapp/codingconventions/javascript.qml 2 - -Also note that is recommended to add type annotations to your function in order -to more easily reason about and refactor your application since both parameter -and return types are immediately visible from the function signature. - -For long scripts, we will put the functions in their own JavaScript file and import it like this: - -\snippet qmlapp/codingconventions/javascript-imports.qml 0 - -If the code is longer than one line and hence within a block, -we use semicolons to indicate the end of each statement: - -\snippet qmlapp/codingconventions/javascript-semicolons.qml 0 - -\section1 Related Information - -\list - \li \l {Best Practices for QML and Qt Quick} -\endlist - -*/ diff --git a/doc/src/qmlapp/debugging.qdoc b/doc/src/qmlapp/debugging.qdoc deleted file mode 100644 index 050cbaec6..000000000 --- a/doc/src/qmlapp/debugging.qdoc +++ /dev/null @@ -1,228 +0,0 @@ -// Copyright (C) 2022 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -\page qtquick-debugging.html -\ingroup qtquick-tools -\title Debugging QML Applications -\brief Provides information on how to use QML's debugging tools. - -When you develop an application with QML, there are many ways to debug possible issues that you -may face. The sections below describe the debugging tools available and how to use them. - -\section1 Console API - -\table - \header - \li Feature - \li Description - \row - \keyword console log - \li Log - \li Use \c{console.log}, \c{console.debug}, \c{console.info}, \c{console.warn}, or - \c{console.error} to print debugging information to the console. - - For example: - - \code - function f(a, b) { - console.log("a is ", a, "b is ", b); - } - \endcode - - The output is generated using the qCDebug, qCWarning, or qCCritical methods in C++, - with a category of \c qml or \c js, depending on the type of file doing the logging. - See also \l {Debugging Techniques}. - \row - \keyword console assert - \li Assert - \li \c console.assert tests that an expression is true. If not, it writes an optional - message to the console and prints the stack trace. - - For example: - - \code - function f() { - var x = 12 - console.assert(x == 12, "This will pass"); - console.assert(x > 12, "This will fail"); - } - \endcode - \row - \keyword console time - \keyword console timeEnd - \li Timer - \li \c{console.time} and \c{console.timeEnd} log the time (in milliseconds) that was spent - between the calls. Both take a string argument that identifies the measurement. - - For example: - - \code - function f() { - console.time("wholeFunction"); - console.time("firstPart"); - // first part - console.timeEnd("firstPart"); - // second part - console.timeEnd("wholeFunction"); - } - \endcode - \row - \keyword console trace - \li Trace - \li \c console.trace prints the stack trace of the JavaScript execution at the point where - it was called. This stack trace information contains the function name, file name, - line number, and column number. The stack trace is limited to last 10 stack frames. - \row - \keyword console count - \li Count - \li \c console.count prints the current number of times a particular piece of code has run, - along with a message. - - For example: - - \code - function f() { - console.count("f called"); - } - \endcode - - The code sample above prints \c{f called: 1}, \c{f called: 2} ... whenever \c{f()} is - run. - \row - \keyword console profile - \li Profile - \li \c console.profile turns on the QML and JavaScript profilers. Nested calls are not - supported and prints a warning to the console. - \row - \keyword console profileEnd - \li ProfileEnd - \li \c console.profileEnd turns off the QML and JavaScript profilers. Calling this function - without a previous call to \c console.profile prints a warning to the console. A - profiling client needs to be attached before this call to receive and store the - profiling data. - - For example: - - \code - function f() { - console.profile(); - //Call some function that needs to be profiled. - //Ensure that a client is attached before ending - //the profiling session. - console.profileEnd(); - } - \endcode - - \row - \keyword console exception - \li Exception - \li \c console.exception prints an error message together with the stack trace of - JavaScript execution at the point where it is called. -\endtable - -Alternatively, a \l {QLoggingCategory}{logging category} can be passed as the -first argument to any of these \c {console} functions. See \l [QML] LoggingCategory for more details. - -\section1 Debugging Module Imports - -Set the \c QML_IMPORT_TRACE environment variable to enable debug output from QML's import loading -mechanisms. - -For example, for a simple QML file like this: - -\qml -import QtQuick - -Rectangle { width: 100; height: 100 } -\endqml - -If you set \c {QML_IMPORT_TRACE=1} before running the \l{qml_runtime_tool}{QML Runtime Tool} or your -QML C++ application, you will see output similar to: - -\code -QQmlImportDatabase::addImportPath "/qt-sdk/imports" -QQmlImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS" -QQmlImportDatabase::addToImport 0x106237370 "." -1.-1 File as "" -QQmlImportDatabase::addToImport 0x106237370 "Qt" 4.7 Library as "" -QQmlImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle" -\endcode - -\section1 QML Debugging Infrastructure -\keyword declarative_debug -\keyword qml debug - -The \l{Qt Qml} module provides services for debugging, inspecting, and profiling applications via a -TCP port or a local socket. - -\note The \c qmltooling plugins that are required for debugging and profiling -QML applications on devices are automatically installed during Qt installation. -They must be deployed to the devices for debugging and profiling to work. - -\section2 Enabling the Infrastructure - -When you compile your application, you must explicitly enable the debugging infrastructure. If you -use qmake, you can add the configuration parameters to the project \c{.pro} file: - -\list - \li Qt Quick 1: \c {CONFIG+=declarative_debug} - \li Qt Quick 2: \c {CONFIG+=qml_debug} -\endlist - -If you use another build system, you can pass the following defines to the compiler: - -\list - \li Qt Quick 1: \c {QT_DECLARATIVE_DEBUG} - \li Qt Quick 2: \c {QT_QML_DEBUG} -\endlist - -\note Enabling the debugging infrastructure may compromise the integrity of your application and -system, and therefore, you should only enable it in a controlled environment. When the -infrastructure is enabled, the application displays the following warning: - -\c {QML debugging is enabled. Only use this in a safe environment.} - -\section2 Starting Applications - -To enable debugging -- from the start or to attach a debugger later on -- start the application -with the following arguments: - -\c {-qmljsdebugger=port:[,port_to][,host:][,block][,file:][,services:]} - -Where: -\list - \li the mandatory \c {port_from} specifies either the debugging port or the start port of a - range of ports when \c {port_to} is specified - \li the optional \c {ip address} specifies the IP address of the host where the application is - running - \li the optional \c block prevents the application from running until the debug client connects - to the server - \li the optional \c {file} specifies the local socket. - \li the optional \c {services} specifies the services to enable; the default is all that are - found. Note that the \c{v4 debug} service disables the JIT. -\endlist - -After the application has successfully started, it displays the following message: - -\c {QML Debugger: Waiting for connection on port } -or -\c {QML Debugger: Connecting to socket at "} - -\section2 Connecting to Applications - -When the application is running, an IDE or a tool that implements the binary protocol can connect -to the open port. - -Qt provides a \c qmlprofiler command line tool to capture profiling data in a file. To run this -tool, enter the following command: - -\c {qmlprofiler -p -attach } - -\section1 Debugging with \QC - -\QC uses the debugging infrastructure to debug, inspect, and profile Qt Quick applications -on the desktop as well as on remote devices. \QC provides integrated clients for debugging -JavaScript, inspecting the object tree, and profiling the activities of a QML engine. For more -information, see \l{\QC: Debugging Qt Quick Projects}. - -*/ diff --git a/doc/src/qmlapp/deployment.qdoc b/doc/src/qmlapp/deployment.qdoc deleted file mode 100644 index cc88a0d29..000000000 --- a/doc/src/qmlapp/deployment.qdoc +++ /dev/null @@ -1,229 +0,0 @@ -// Copyright (C) 2017 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -\page qtquick-deployment.html -\title Deploying QML Applications -\brief Provides information on how to use deploy QML applications. - -QML documents are loaded and run by the QML runtime. This includes the Declarative UI engine -along with the built-in QML types and plugin modules. The QML runtime also provides access -to third-party QML types and modules. - -Applications that use QML must invoke the QML runtime to run QML documents. You can do this by -creating a QQuickView or a QQmlEngine, as described below. In addition, the Declarative UI -package includes the \c qml tool, which loads \c .qml files. This tool is useful for developing -and testing QML code without having to write a C++ application to load the QML runtime. - -\section1 Deploying Applications with \QC - -\l{\QC Documentation}{\QC} deploys and packages QML applications to various platforms. -For mobile devices, \QC can directly bundle applications to the respective platform -package formats, such as APK. - -When you run your applications on the target platform, your application needs to access -the location of the QML libraries. If you use \l{qmake Manual}{qmake}, the -\c QT_INSTALL_QML environment variable points to the location of the libraries. The -\l{Downloads}{Qt Installers} install the QML libraries in: -\c{}\c{/}\e{}\c{/qml} directory. - -\section1 QML Caching - -The QML runtime loads QML documents by parsing them and generating byte code. Most of the time, -the document hasn't changed since the last time it was loaded. To speed up this loading process, -the QML runtime maintains a cache file for each QML document. This cache file contains the -compiled byte code and a binary representation of the QML document structure. In addition, when -multiple applications use the same QML document, the memory needed for the code is shared between -application processes. The cache files are loaded via the \c mmap() system call on POSIX-compliant -operating systems or \c CreateFileMapping() on Windows, resulting in significant memory savings. - -Each time you load a changed QML document, the cache is automatically re-created. Cache files are -located in a sub-directory of QStandardPaths::CacheLocation with the name "qmlcache". The file -extension is \c .qmlc for QML documents and \c .jsc for imported JavaScript modules. - -\target Compiling Ahead of Time -\section1 Ahead-of-Time Compilation - -The automatic caching of compiled QML documents into cache files results in significantly faster -application load time. However, the initial creation of cache files can still take time, especially -when the application starts for the very first time. To avoid that initial step and provide faster -startup times from the very beginning, Qt's build system allows you to perform the compilation step -for QML files ahead of time, when compiling the C++ parts of your application. - -One benefit of compiling ahead of time is that, in the event of syntax errors in your QML -documents, you are notified at application compile-time instead of at run-time, when the file is -loaded. - -This will happen automatically if you use the \l{qt_add_qml_module}{CMake QML Module API}, -for qmake see the section below. - -\section2 qmake - -When using qmake, in order to deploy your application with QML files compiled ahead of time, you must organize the files and -the build system in a specific way: - -\list - \li All QML documents (including JavaScript files) must be included as resources via - \l{The Qt Resource System}{Qt's Resource system}. - \li Your application must load the QML documents via the \c qrc:/// URL scheme. - \li You can enable Ahead-of-Time compilation using the \c CONFIG+=qtquickcompiler directive. -\endlist - -\section1 Prototyping with QML Scene - -The Declarative UI package includes a QML Runtime Tool, \l{qml_runtime_tool}{qml}, -which loads and displays QML documents. This is useful during the application development phase -for prototyping QML-based applications without writing your own C++ applications to invoke -the QML runtime. - -\section1 Initializing the QML Runtime in Applications - -To run an application that uses QML, your application must invoke the QML runtime. This is done -by writing a Qt C++ application that loads the QQmlEngine by either: - -\list - \li Loading the QML file through a QQuickView instance. - \li Creating a QQmlEngine instance and loading QML files with QQmlComponent. -\endlist - - -\section2 Initializing with QQuickView - -QQuickView is a QWindow-based class that can load QML files. For example, if there is a QML file, -\c application.qml, it will look like this: - -\qml - import QtQuick - - Rectangle { width: 100; height: 100; color: "red" } -\endqml - -It can be loaded in a Qt application's \c main.cpp file like this: - -\code - #include - #include - - int main(int argc, char *argv[]) - { - QGuiApplication app(argc, argv); - - QQuickView view; - view.setSource(QUrl::fromLocalFile("application.qml")); - view.show(); - - return app.exec(); - } -\endcode - -This creates a QWindow-based view that displays the contents of \c application.qml. - -\section3 Build Files - -\if defined(onlinedocs) - \tab {build-qt-app}{tab-cmake}{CMake}{checked} - \tab {build-qt-app}{tab-qmake}{qmake}{} - \tabcontent {tab-cmake} -\else - \section1 Using CMake -\endif - \include {module-use.qdocinc} {building with cmake} {Quick} -\if defined(onlinedocs) - \endtabcontent - \tabcontent {tab-qmake} -\else - \section1 Using qmake -\endif - \include {module-use.qdocinc} {building_with_qmake} {quick} - For more information, see \l{Creating Project Files}. -\if defined(onlinedocs) - \endtabcontent -\endif - -\section2 Creating a QQmlEngine Directly - -If \c application.qml doesn't have any graphical components, or if it's preferred to -avoid QQuickView for other reasons, the QQmlEngine can be constructed directly instead. -In this case, \c application.qml is loaded as a QQmlComponent instance rather than placed into -a view: - -\code - #include - #include - #include - #include - - int main(int argc, char *argv[]) - { - QGuiApplication app(argc, argv); - - QQmlEngine engine; - QQmlContext *objectContext = new QQmlContext(engine.rootContext()); - - QQmlComponent component(&engine, "application.qml"); - QObject *object = component.create(objectContext); - - // ... delete object and objectContext when necessary - - return app.exec(); - } -\endcode - -If you're not using any graphical items from Qt Quick, you can replace QGuiApplication with a -QCoreApplication in the code above. This way, you can use QML as a language without any -dependencies to the \l{Qt GUI} module. - -\section1 Using the Qt Resource System with QML - -The \l {The Qt Resource System}{Qt resource system} allows resource files to be stored as binary -files in an application executable. The Qt Resource System is used for QML application -as it enables QML files and other resources -- such as images and sound files -- to be referred -to through the resource system URI scheme rather than relative or absolute paths to filesystem -resources. - -\note Usage of the resource system means that the application executable usually must be -re-compiled whenever a QML source file is changed, to update the resources in the package. - -The \l{qt_add_qml_module}{CMake QML Module API} automatically places your QML files in the resource -system. To access them, load your main QML file as a resource or as a URL with the \c{qrc} scheme. -The path in the resource system where your QML files are placed can be found by concatenating: - -\list -\li the \c RESOURCE_PREFIX you have passed to \l{qt_add_qml_module}. -\li \c{/qt/qml}, if you have \e{not} passed \c RESOURCE_PREFIX to - \l{qt_add_qml_module} and \l{QTP0001} policy is set to \c NEW. -\li \c{/}, if you have \e{not} passed \c RESOURCE_PREFIX to \l{qt_add_qml_module} - and \l{QTP0001} policy is \c{not} set to \c NEW. -\li If you have \e{not} passed \c NO_RESOURCE_TARGET_PATH to \l{qt_add_qml_module}: - the \c URI you have passed to \l{qt_add_qml_module} with dots replaced by slashes. -\endlist - -For example, a module called \c{My.Own.Module} is placed at: -\list -\li \c{:/qt/qml/My/Own/Module/} if you have specified \c{/qt/qml} as \c RESOURCE_PREFIX, or - you have \e{not} passed \c RESOURCE_PREFIX and \l{QTP0001} policy is set to \c NEW. -\li \c{:/My/Own/Module/} if you have specified \c{/} as \c RESOURCE_PREFIX, or - you have \e{not} passed \c RESOURCE_PREFIX and \l{QTP0001} policy is \e{not} set to \c NEW. -} -\li \c{:/Some/Prefix/My/Own/Module/} if you have specified \c{Some/Prefix/} as \c RESOURCE_PREFIX -\li \c{:/} if you have specified \c NO_RESOURCE_TARGET_PATH -\endlist - -Once this is done, all files specified by relative paths in QML are loaded from the resource system. -Use of the resource system is completely transparent to the QML layer; this means all QML code -should refer to resource files using relative paths and should \e{not} use the \c{qrc} scheme. This -scheme should only be used from C++ code to refer to resource files. - -\note When using qmake, you need to manually place your files in the resource system. See the -\l{qmake Manual} and the \l{The Qt Resource System}{general documentation} on the resouce system for -how to do this. It's advisable to still follow the path naming convention outlined above. - -\section1 Related Information -\list - \li \l{Deploying Qt Applications} - \li \l{\QC: Run on many platforms} - \li \l{qtqml-cppintegration-data.html}{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Types to QML} - \li \l{The Qt Resource System} -\endlist - -*/ diff --git a/doc/src/qmlapp/firststepsqml.qdoc b/doc/src/qmlapp/firststepsqml.qdoc deleted file mode 100644 index 621def571..000000000 --- a/doc/src/qmlapp/firststepsqml.qdoc +++ /dev/null @@ -1,359 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only -/*! -\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: - -\qml -import QtQuick -\endqml - -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 window with some text centered -in it: - -\qml -Window { - width: 640 - height: 480 - visible: true - color: "red" - - Text { - anchors.centerIn: parent - text: "Hello, World!" - } -} -\endqml - -This defines an object hierarchy with a root \l Window object -which has a child \l Text object. The \c parent of the \l Text object is -automatically set to the \l Window, and similarly, the \l Text object is -added to the \c children property of the \l Window object, by QML. - -\section2 Putting it All Together - -The \l Window 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 - -Window { - width: 640 - height: 480 - visible: true - 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{\QC Documentation}{\QC}. To create a new QML project in \QC: -\list 1 -\li Select \uicontrol{File} > \uicontrol{New Project} > \uicontrol{Qt Quick Application} -from within \QC. -\li Enter a name for your project and select a location to save it. -\li Select the appropriate Qt version and optionally configure version -control settings for the project. -\li Review the summary of your project settings and continue to complete the project build. -\endlist - -When finished, \QC will generate the necessary files and open the project for development. -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 \QC, visit -the following pages: -\list -\li \l{\QC: Create Qt Quick Applications} -\li \l{\QC: Tutorial: Build and run} -\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 -import QtQuick.Controls - -//window containing the application -ApplicationWindow { - width: 640 - height: 480 - visible: true - //title of the application - title: qsTr("Hello World") - - //menu containing two menu items - header: MenuBar { - Menu { - title: qsTr("&File") - Action { - text: qsTr("&Open...") - onTriggered: console.log("Open action triggered") - } - MenuSeparator { } - Action { - 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 -\QC 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 Hello 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 - -Window { - id: root - width: 200 - height: 100 - color: isRed ? "red" : "blue" - visible: true - - property bool isRed: true // Track the color state - - Text { - anchors.centerIn: parent - text: "Hello, World!" - } - - TapHandler { - onTapped: root.isRed = !root.isRed // Toggle state - } -} -\endqml - -This example can be saved as "ClickableHelloWorld.qml" and run with \c qml, the -\l{qml_runtime_tool}{QML Runtime Tool}. -Whenever the user clicks anywhere in the window, the rectangle will change -from red to blue. Tapping again will change it back to red. - -\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 -import QtQuick - -Window { - id: root - width: 200 - height: 100 - color: "red" - visible: true - - Text { - id: myText - anchors.centerIn: parent - text: toggle ? "Hello, World!" : "Goodbye, World!" - focus: true - property bool toggle: true - Keys.onReturnPressed: (event)=>{ - myText.toggle = !myText.toggle; - event.accepted = true; - } - } -} -\endqml - -Now, each time you press the Enter key, the text will alternate between -"Hello, World" and "Goodbye, World". - -\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 Window. If the geometry of the parent \l Window object -were to change, the geometry of each child \l Rectangle would automatically -update due to the property bindings. - -\qml -import QtQuick - -Window { - id: root - width: 200 - height: 100 - color: "red" - visible: true - - - Rectangle { - width: root.width / 2 - height: root.height - color: "blue" - } - - Rectangle { - width: root.width / 2 - height: root.height - x: root.width / 2 - color: "green" - } -} -\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 - -Window { - id: root - width: 200 - height: 100 - color: "red" - visible: true - - property int animatedValue - - SequentialAnimation on animatedValue { - loops: Animation.Infinite - PropertyAnimation { - to: 150 - duration: 1000 - } - PropertyAnimation { - to: 0 - duration: 1000 - } - } - - Text { - anchors.centerIn: parent - text: root.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 - -*/ diff --git a/doc/src/qmlapp/glossary.qdoc b/doc/src/qmlapp/glossary.qdoc deleted file mode 100644 index b0edefeb0..000000000 --- a/doc/src/qmlapp/glossary.qdoc +++ /dev/null @@ -1,164 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -\page qml-glossary.html -\title Glossary Of QML Terms -\brief Glossary of terms used in the documentation for QML and Qt Quick - -\section1 Common Terms - -\table - \header - \li Term - \li Definition - - \row - \li QML - \li The language in which QML applications are written. The language - architecture and engine are implemented by the Qt Qml module. - - \row - \li Qt Quick - \li The standard library of types and functionality for the - QML language, which is provided by the Qt Quick module, - and may be accessed with "import QtQuick". - - \row - \li Type - \li In QML, a \e type may refer to either a - \l{qtqml-typesystem-topic.html}{Value Type} or a - \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Type}. - - The QML language provides a number of built-in - \l{qtqml-typesystem-valuetypes.html}{value types}, and the - Qt Quick module provides various \l {Qt Quick QML Types}{Qt Quick types} - for building QML applications. Types can also be provided by - third-party developers through (\l{qtqml-modules-topic.html}{modules}) or by the application - developer in the application itself through \l{qtqml-documents-definetypes.html}{QML Documents}. - - See \l{qtqml-typesystem-topic.html}{The QML Type System} - for more details. - - \row - \li Value Type - \li A \l{qtqml-typesystem-topic.html}{value type} is a simple type - such as \c int, \c string and \c bool. Unlike - \l{qtqml-typesystem-topic.html#qml-object-types}{object types}, - an object cannot be instantiated from a value type; for example, - it is not possible to create an \c int object with properties, - methods, signals and so on. - - Value types as well as object types usually belong to a - \l{qtqml-modules-topic.html}{QML module}. You have to import the - module to use them. Some types are built into the language, for - example int, bool, double, string, but also QtObject and Component. - - See \l{qtqml-typesystem-topic.html}{The QML Type System} - for more details. - - \row - \li Object Type - \li A \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Type} - is a type that can be instantiated by the QML engine. - - A QML type can be defined either by a document in a .qml file - beginning with a capital letter, or by a QObject-based C++ class. - - See \l{qtqml-typesystem-topic.html}{The QML Type System} - for more details. - - \row - \li Object - \li A QML object is an instance of a - \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Type}. - - Such objects are created by the engine when it processes - \l{qtqml-syntax-basics.html#object-declarations}{object declarations}, - which specify the objects to be created and the attributes that are to - be defined for each object. - - Additionally, objects can be dynamically created at runtime through - Component.createObject() and Qt.createQmlObject(). - - See also \l{#lazy-instantiation}{Lazy Instantiation}. - - \row - \li Component - \li A component is a template from which a QML object or object - tree is created. It is produced when a document is loaded by - the QML engine. Once it has been loaded, it can be used to - instantiate the object or object tree that it represents. - - Additionally, the \l Component type is a special type that can - can be used to declare a component inline within a document. - Component objects can also be dynamically created through - Qt.createComponent() to dynamically create QML objects. - - \row - \li Document - \li A \l{qtqml-documents-topic.html}{QML Document} is a self - contained piece of QML source code that begins with one or more - import statements and contains a single top-level object - declaration. A document may reside in a .qml file or a text string. - - If it is placed in a .qml file whose name begins with a capital - letter, the file is recognized by the engine as a definition of - a QML type. The top-level object declaration encapsulates the - object tree that will be instantiated by the type. - - \row - \li Property - \li A property is an attribute of an object type that has a name and - an associated value; this value can be read (and in most cases, also - written to) externally. - - An object can have one or more properties. Some properties - are associated with the canvas (e.g., x, y, width, height, - and opacity) while others may be data specific to that type - (e.g., the "text" property of the \l Text type). - - See \l{qtqml-syntax-objectattributes.html}{QML Object Attributes} - for more details. - - \row - \li Binding - \li A binding is a JavaScript expression which is "bound" to a - property. The value of the property at any point in time - will be the value returned by evaluating that expression. - - See \l{qtqml-syntax-propertybinding.html}{Property Binding} - for more details. - - \row - \li Signal - \li A signal is a notification from a QML object. When an object emits - a signal, other objects can receive and process this signal through - a \l{Signal Attributes}{signal handler}. - - Most properties of QML objects - have a change signal, and also an associated change signal handler - which may be defined by clients to implement functionality. For - example, the "onClicked()" handler of an instance of the MouseArea - type might be defined in an application to cause a sound to be - played. - - See \l{qtqml-syntax-signals.html}{Signal and Handler Event System} - for more details. - - \row - \li Signal Handler - \li A signal handler is the expression (or function) which is triggered - by a signal. It is also known as a "slot" in C++. - - See \l{qtqml-syntax-signals.html}{Signal and Handler Event System} - for more details. - - \row - \li Lazy Instantiation \target lazy-instantiation - \li Object instances can be instantiated "lazily" at run-time, - to avoid performing unnecessary work until needed. Qt Quick - provides the \l Loader type to make lazy instantiation more - convenient. -\endtable -*/ diff --git a/doc/src/qmlapp/performance.qdoc b/doc/src/qmlapp/performance.qdoc deleted file mode 100644 index b71bcfd01..000000000 --- a/doc/src/qmlapp/performance.qdoc +++ /dev/null @@ -1,1071 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -\page qtquick-performance.html -\title QML Performance Considerations And Suggestions -\brief Discussion of performance-related trade-offs and best-practices - -\section1 Timing Considerations - -As an application developer, you must strive to allow the rendering engine -to achieve a consistent 60 frames-per-second refresh rate. 60 FPS means -that there is approximately 16 milliseconds between each frame in which -processing can be done, which includes the processing required to upload -the draw primitives to the graphics hardware. - -In practice, this means that the application developer should: -\list - \li use asynchronous, event-driven programming wherever possible - \li use worker threads to do significant processing - \li never manually spin the event loop - \li never spend more than a couple of milliseconds per frame within blocking functions -\endlist - -Failure to do so will result in skipped frames, which has a drastic effect on the -user experience. - -\note A pattern which is tempting, but should \e never be used, is creating your -own QEventLoop or calling QCoreApplication::processEvents() in order to avoid -blocking within a C++ code block invoked from QML. This is dangerous, because -when an event loop is entered in a signal handler or binding, the QML engine -continues to run other bindings, animations, transitions, etc. Those bindings -can then cause side effects which, for example, destroy the hierarchy containing -your event loop. - -\section1 Profiling - -The most important tip is: use the QML Profiler included in \QC. Knowing -where time is spent in an application will allow you to focus on problem areas which -actually exist, rather than problem areas which potentially exist. See -\l{\QC: Profiling QML Applications} for more information. - -Determining which bindings are being run the most often, or which functions your -application is spending the most time in, will allow you to decide whether you need -to optimize the problem areas, or redesign some implementation details of your -application so that the performance is improved. Attempting to optimize code without -profiling is likely to result in very minor rather than significant performance -improvements. - -\section1 JavaScript Code - -Most QML applications will have a large amount of JavaScript code in them, in the -form of dynamic functions, signal handlers, and property binding expressions. -This is generally not a problem. Thanks to some optimizations in the QML engine, -such as those done to the bindings compiler, it can (in some use-cases) be faster -than calling a C++ function. However, care must be taken to ensure that unnecessary -processing isn't triggered accidentally. - -\section2 Type-Conversion - -One major cost of using JavaScript is that in most cases when a property from a QML -type is accessed, a JavaScript object with an external resource containing the -underlying C++ data (or a reference to it) is created. In most cases, this is fairly -inexpensive, but in others it can be quite expensive. One example of where it is -expensive is assigning a C++ QVariantMap Q_PROPERTY to a QML "variant" property. -Lists can also be expensive, although sequences of specific types (QList of int, -qreal, bool, QString, and QUrl) should be inexpensive; other list types involve an -expensive conversion cost (creating a new JavaScript Array, and adding new types -one by one, with per-type conversion from C++ type instance to JavaScript value). - -Converting between some basic property types (such as "string" and "url" properties) -can also be expensive. Using the closest matching property type will avoid unnecessary -conversion. - -If you must expose a QVariantMap to QML, use a "var" property rather than a "variant" -property. In general, "property var" should be considered to be superior to -"property variant" for every use-case from QtQuick 2.0 and newer (note that "property variant" -is marked as obsolete), as it allows a true JavaScript reference to be stored (which can -reduce the number of conversions required in certain expressions). - -\section2 Resolving Properties - -Property resolution takes time. While in some cases the result of a lookup can be -cached and reused, it is always best to avoid doing unnecessary work altogether, if -possible. - -In the following example, we have a block of code which is run often (in this case, it -is the contents of an explicit loop; but it could be a commonly-evaluated binding expression, -for example) and in it, we resolve the object with the "rect" id and its "color" property -multiple times: - -\qml -// bad.qml -import QtQuick - -Item { - width: 400 - height: 200 - Rectangle { - id: rect - anchors.fill: parent - color: "blue" - } - - function printValue(which, value) { - console.log(which + " = " + value); - } - - Component.onCompleted: { - var t0 = new Date(); - for (var i = 0; i < 1000; ++i) { - printValue("red", rect.color.r); - printValue("green", rect.color.g); - printValue("blue", rect.color.b); - printValue("alpha", rect.color.a); - } - var t1 = new Date(); - console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations"); - } -} -\endqml - -We could instead resolve the common base just once in the block: - -\qml -// good.qml -import QtQuick - -Item { - width: 400 - height: 200 - Rectangle { - id: rect - anchors.fill: parent - color: "blue" - } - - function printValue(which, value) { - console.log(which + " = " + value); - } - - Component.onCompleted: { - var t0 = new Date(); - for (var i = 0; i < 1000; ++i) { - var rectColor = rect.color; // resolve the common base. - printValue("red", rectColor.r); - printValue("green", rectColor.g); - printValue("blue", rectColor.b); - printValue("alpha", rectColor.a); - } - var t1 = new Date(); - console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations"); - } -} -\endqml - -Just this simple change results in a significant performance improvement. -Note that the code above can be improved even further (since the property -being looked up never changes during the loop processing), by hoisting the -property resolution out of the loop, as follows: - -\qml -// better.qml -import QtQuick - -Item { - width: 400 - height: 200 - Rectangle { - id: rect - anchors.fill: parent - color: "blue" - } - - function printValue(which, value) { - console.log(which + " = " + value); - } - - Component.onCompleted: { - var t0 = new Date(); - var rectColor = rect.color; // resolve the common base outside the tight loop. - for (var i = 0; i < 1000; ++i) { - printValue("red", rectColor.r); - printValue("green", rectColor.g); - printValue("blue", rectColor.b); - printValue("alpha", rectColor.a); - } - var t1 = new Date(); - console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations"); - } -} -\endqml - -\section2 Property Bindings - -A property binding expression will be re-evaluated if any of the properties -it references are changed. As such, binding expressions should be kept as -simple as possible. - -If you have a loop where you do some processing, but only the final result -of the processing is important, it is often better to update a temporary -accumulator which you afterwards assign to the property you need to update, -rather than incrementally updating the property itself, in order to avoid -triggering re-evaluation of binding expressions during the intermediate -stages of accumulation. - -The following contrived example illustrates this point: - -\qml -// bad.qml -import QtQuick - -Item { - id: root - width: 200 - height: 200 - property int accumulatedValue: 0 - - Text { - anchors.fill: parent - text: root.accumulatedValue.toString() - onTextChanged: console.log("text binding re-evaluated") - } - - Component.onCompleted: { - var someData = [ 1, 2, 3, 4, 5, 20 ]; - for (var i = 0; i < someData.length; ++i) { - accumulatedValue = accumulatedValue + someData[i]; - } - } -} -\endqml - -The loop in the onCompleted handler causes the "text" property binding to -be re-evaluated six times (which then results in any other property bindings -which rely on the text value, as well as the onTextChanged signal handler, -to be re-evaluated each time, and lays out the text for display each time). -This is clearly unnecessary in this case, since we really only care about -the final value of the accumulation. - -It could be rewritten as follows: - -\qml -// good.qml -import QtQuick - -Item { - id: root - width: 200 - height: 200 - property int accumulatedValue: 0 - - Text { - anchors.fill: parent - text: root.accumulatedValue.toString() - onTextChanged: console.log("text binding re-evaluated") - } - - Component.onCompleted: { - var someData = [ 1, 2, 3, 4, 5, 20 ]; - var temp = accumulatedValue; - for (var i = 0; i < someData.length; ++i) { - temp = temp + someData[i]; - } - accumulatedValue = temp; - } -} -\endqml - -\section2 Sequence tips - -As mentioned earlier, some sequence types are fast (for example, QList, QList, -QList, QList, QStringList and QList) while others will be -much slower. Aside from using these types wherever possible instead of slower types, -there are some other performance-related semantics you need to be aware of to achieve -the best performance. - -Firstly, there are two different implementations for sequence types: one for where -the sequence is a Q_PROPERTY of a QObject (we'll call this a reference sequence), -and another for where the sequence is returned from a Q_INVOKABLE function of a -QObject (we'll call this a copy sequence). - -A reference sequence is read and written via QMetaObject::property() and thus is read -and written as a QVariant. This means that changing the value of any element in the -sequence from JavaScript will result in three steps occurring: the complete sequence -will be read from the QObject (as a QVariant, but then cast to a sequence of the correct -type); the element at the specified index will be changed in that sequence; and the -complete sequence will be written back to the QObject (as a QVariant). - -A copy sequence is far simpler as the actual sequence is stored in the JavaScript -object's resource data, so no read/modify/write cycle occurs (instead, the resource -data is modified directly). - -Therefore, writes to elements of a reference sequence will be much slower than writes -to elements of a copy sequence. In fact, writing to a single element of an N-element -reference sequence is equivalent in cost to assigning a N-element copy sequence to that -reference sequence, so you're usually better off modifying a temporary copy sequence -and then assigning the result to a reference sequence, during computation. - -Assume the existence (and prior registration into the "Qt.example" namespace) of the -following C++ type: - -\code -class SequenceTypeExample : public QQuickItem -{ - Q_OBJECT - Q_PROPERTY (QList qrealListProperty READ qrealListProperty WRITE setQrealListProperty NOTIFY qrealListPropertyChanged) - -public: - SequenceTypeExample() : QQuickItem() { m_list << 1.1 << 2.2 << 3.3; } - ~SequenceTypeExample() {} - - QList qrealListProperty() const { return m_list; } - void setQrealListProperty(const QList &list) { m_list = list; emit qrealListPropertyChanged(); } - -signals: - void qrealListPropertyChanged(); - -private: - QList m_list; -}; -\endcode - -The following example writes to elements of a reference sequence in a -tight loop, resulting in bad performance: - -\qml -// bad.qml -import QtQuick -import Qt.example - -SequenceTypeExample { - id: root - width: 200 - height: 200 - - Component.onCompleted: { - var t0 = new Date(); - qrealListProperty.length = 100; - for (var i = 0; i < 500; ++i) { - for (var j = 0; j < 100; ++j) { - qrealListProperty[j] = j; - } - } - var t1 = new Date(); - console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); - } -} -\endqml - -The QObject property read and write in the inner loop caused by the -\c{"qrealListProperty[j] = j"} expression makes this code very suboptimal. Instead, -something functionally equivalent but much faster would be: - -\qml -// good.qml -import QtQuick -import Qt.example - -SequenceTypeExample { - id: root - width: 200 - height: 200 - - Component.onCompleted: { - var t0 = new Date(); - var someData = [1.1, 2.2, 3.3] - someData.length = 100; - for (var i = 0; i < 500; ++i) { - for (var j = 0; j < 100; ++j) { - someData[j] = j; - } - qrealListProperty = someData; - } - var t1 = new Date(); - console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); - } -} -\endqml - -Secondly, a change signal for the property is emitted if any element in it changes. -If you have many bindings to a particular element in a sequence property, it is better -to create a dynamic property which is bound to that element, and use that dynamic -property as the symbol in the binding expressions instead of the sequence element, -as it will only cause re-evaluation of bindings if its value changes. - -This is an unusual use-case which most clients should never hit, but is worth being -aware of, in case you find yourself doing something like this: - -\qml -// bad.qml -import QtQuick -import Qt.example - -SequenceTypeExample { - id: root - - property int firstBinding: qrealListProperty[1] + 10; - property int secondBinding: qrealListProperty[1] + 20; - property int thirdBinding: qrealListProperty[1] + 30; - - Component.onCompleted: { - var t0 = new Date(); - for (var i = 0; i < 1000; ++i) { - qrealListProperty[2] = i; - } - var t1 = new Date(); - console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); - } -} -\endqml - -Note that even though only the element at index 2 is modified in the loop, the three -bindings will all be re-evaluated since the granularity of the change signal is that -the entire property has changed. As such, adding an intermediate binding can -sometimes be beneficial: - -\qml -// good.qml -import QtQuick -import Qt.example - -SequenceTypeExample { - id: root - - property int intermediateBinding: qrealListProperty[1] - property int firstBinding: intermediateBinding + 10; - property int secondBinding: intermediateBinding + 20; - property int thirdBinding: intermediateBinding + 30; - - Component.onCompleted: { - var t0 = new Date(); - for (var i = 0; i < 1000; ++i) { - qrealListProperty[2] = i; - } - var t1 = new Date(); - console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); - } -} -\endqml - -In the above example, only the intermediate binding will be re-evaluated each time, -resulting in a significant performance increase. - -\section2 Value-Type tips - -Value-type properties (font, color, vector3d, etc) have similar QObject property -and change notification semantics to sequence type properties. As such, the tips -given above for sequences are also applicable for value-type properties. While -they are usually less of a problem with value-types (since the number of -sub-properties of a value-type is usually far less than the number of elements -in a sequence), any increase in the number of bindings being re-evaluated needlessly -will have a negative impact on performance. - -\section2 General Performance Tips - -General JavaScript performance considerations resulting from the language design are applicable also to QML. Most prominently: - -\list -\li Avoid using eval() if at all possible -\li Do not delete properties of objects -\endlist - -\section1 Common Interface Elements - -\section2 Text Elements - -Calculating text layouts can be a slow operation. Consider using the \c PlainText -format instead of \c StyledText wherever possible, as this reduces the amount of work -required of the layout engine. If you cannot use \c PlainText (as you need to embed -images, or use tags to specify ranges of characters to have certain formatting (bold, -italic, etc) as opposed to the entire text) then you should use \c StyledText. - -You should only use \c AutoText if the text might be (but probably isn't) -\c StyledText as this mode will incur a parsing cost. The \c RichText mode should -not be used, as \c StyledText provides almost all of its features at a fraction of -its cost. - -\section2 Images - -Images are a vital part of any user interface. Unfortunately, they are also a big -source of problems due to the time it takes to load them, the amount of memory they -consume, and the way in which they are used. - -\section3 Asynchronous Loading - -Images are often quite large, and so it is wise to ensure that loading an image doesn't -block the UI thread. Set the "asynchronous" property of the QML Image element to -\c true to enable asynchronous loading of images from the local file system (remote -images are always loaded asynchronously) where this would not result in a negative impact -upon the aesthetics of the user interface. - -Image elements with the "asynchronous" property set to \c true will load images in -a low-priority worker thread. - -\section3 Explicit Source Size - -If your application loads a large image but displays it in a small-sized element, set -the "sourceSize" property to the size of the element being rendered to ensure that the -smaller-scaled version of the image is kept in memory, rather than the large one. - -Beware that changing the sourceSize will cause the image to be reloaded. - -\section3 Avoid Run-time Composition - -Also remember that you can avoid doing composition work at run-time by providing the -pre-composed image resource with your application (for example, providing elements with shadow -effects). - -\section3 Avoid Smoothing Images - -Enable \c{image.smooth} only if required. It is slower on some hardware, and it has no visual -effect if the image is displayed in its natural size. - -\section3 Painting - -Avoid painting the same area several times. Use Item as root element rather than Rectangle -to avoid painting the background several times. - -\section2 Position Elements With Anchors - -It is more efficient to use anchors rather than bindings to position items -relative to each other. Consider this use of bindings to position rect2 -relative to rect1: - -\code -Rectangle { - id: rect1 - x: 20 - width: 200; height: 200 -} -Rectangle { - id: rect2 - x: rect1.x - y: rect1.y + rect1.height - width: rect1.width - 20 - height: 200 -} -\endcode - -This is achieved more efficiently using anchors: - -\code -Rectangle { - id: rect1 - x: 20 - width: 200; height: 200 -} -Rectangle { - id: rect2 - height: 200 - anchors.left: rect1.left - anchors.top: rect1.bottom - anchors.right: rect1.right - anchors.rightMargin: 20 -} -\endcode - -Positioning with bindings (by assigning binding expressions to the x, y, width -and height properties of visual objects, rather than using anchors) is -relatively slow, although it allows maximum flexibility. - -If the layout is not dynamic, the most performant way to specify the layout is -via static initialization of the x, y, width and height properties. Item -coordinates are always relative to their parent, so if you wanted to be a fixed -offset from your parent's 0,0 coordinate you should not use anchors. In the -following example the child Rectangle objects are in the same place, but the -anchors code shown is not as resource efficient as the code which -uses fixed positioning via static initialization: - -\code -Rectangle { - width: 60 - height: 60 - Rectangle { - id: fixedPositioning - x: 20 - y: 20 - width: 20 - height: 20 - } - Rectangle { - id: anchorPositioning - anchors.fill: parent - anchors.margins: 20 - } -} -\endcode - -\section1 Models and Views - -Most applications will have at least one model feeding data to a view. There are -some semantics which application developers need to be aware of, in order to achieve -maximal performance. - -\section2 Custom C++ Models - -It is often desirable to write your own custom model in C++ for use with a view in -QML. While the optimal implementation of any such model will depend heavily on the -use-case it must fulfil, some general guidelines are as follows: - -\list -\li Be as asynchronous as possible -\li Do all processing in a (low priority) worker thread -\li Batch up backend operations so that (potentially slow) I/O and IPC is minimized -\endlist - -It is important to note that using a low-priority worker thread is recommended to -minimize the risk of starving the GUI thread (which could result in worse perceived -performance). Also, remember that synchronization and locking mechanisms can be a -significant cause of slow performance, and so care should be taken to avoid -unnecessary locking. - -\section2 ListModel QML Type - -QML provides a ListModel type which can be used to feed data to a ListView. -It should suffice for most use-cases and be relatively performant so long as -it is used correctly. - -\section3 Populate Within A Worker Thread - -ListModel elements can be populated in a (low priority) worker thread in JavaScript. The -developer must explicitly call "sync()" on the ListModel from within the WorkerScript to -have the changes synchronized to the main thread. See the WorkerScript documentation -for more information. - -Please note that using a WorkerScript element will result in a separate JavaScript engine -being created (as the JavaScript engine is per-thread). This will result in increased -memory usage. Multiple WorkerScript elements will all use the same worker thread, however, -so the memory impact of using a second or third WorkerScript element is negligible once -an application already uses one. - -\section3 Don't Use Dynamic Roles - -The ListModel element in QtQuick 2 is much more performant than in QtQuick 1. The -performance improvements mainly come from assumptions about the type of roles within each -element in a given model - if the type doesn't change, the caching performance improves -dramatically. If the type can change dynamically from element to element, this optimization -becomes impossible, and the performance of the model will be an order of magnitude worse. - -Therefore, dynamic typing is disabled by default; the developer must specifically set -the boolean "dynamicRoles" property of the model to enable dynamic typing (and suffer -the attendant performance degradation). We recommend that you do not use dynamic typing -if it is possible to redesign your application to avoid it. - -\section2 Views - -View delegates should be kept as simple as possible. Have just enough QML in the delegate -to display the necessary information. Any additional functionality which is not immediately -required (for example, if it displays more information when clicked) should not be created until -needed (see the upcoming section on lazy initialization). - -The following list is a good summary of things to keep in mind when designing a delegate: -\list -\li The fewer elements that are in a delegate, the faster they can be created, and thus - the faster the view can be scrolled. -\li Keep the number of bindings in a delegate to a minimum; in particular, use anchors - rather than bindings for relative positioning within a delegate. -\li Avoid using ShaderEffect elements within delegates. -\li Never enable clipping on a delegate. -\endlist - -You may set the \c cacheBuffer property of a view to allow asynchronous creation and -buffering of delegates outside of the visible area. Utilizing a \c cacheBuffer is -recommended for view delegates that are non-trivial and unlikely to be created within a -single frame. - -Bear in mind that a \c cacheBuffer keeps additional delegates in-memory. Therefore, the value derived from utilizing the \c cacheBuffer must be balanced against additional memory -usage. Developers should use benchmarking to find the best value for their use-case, since -the increased memory pressure caused by utilizing a \c cacheBuffer can, in some rare cases, -cause reduced frame rate when scrolling. - -\section1 Visual Effects - -\l {Qt Quick}{Qt Quick 2} includes several features which allow developers and designers to create -exceptionally appealing user interfaces. Fluidity and dynamic transitions as well -as visual effects can be used to great effect in an application, but some care must -be taken when using some of the features in QML as they can have performance implications. - -\section2 Animations - -In general, animating a property will cause any bindings which reference that property -to be re-evaluated. Usually, this is what is desired but in other cases it may be better -to disable the binding prior to performing the animation, and then reassign the binding -once the animation has completed. - -Avoid running JavaScript during animation. For example, running a complex JavaScript -expression for each frame of an x property animation should be avoided. - -Developers should be especially careful using script animations, as these are run in the main -thread (and therefore can cause frames to be skipped if they take too long to complete). - -\section2 Particles - -The \l {QtQuick.Particles}{Qt Quick Particles} module allows beautiful particle effects to be integrated -seamlessly into user interfaces. However, every platform has different graphics hardware -capabilities, and the Particles module is unable to limit parameters to what your hardware -can gracefully support. The more particles you attempt to render (and the larger they are), -the faster your graphics hardware will need to be in order to render at 60 FPS. Affecting -more particles requires a faster CPU. It is therefore important to test all -particle effects on your target platform carefully, to calibrate the number and size of -particles you can render at 60 FPS. - -It should be noted that a particle system can be disabled when not in use -(for example, on a non-visible element) to avoid doing unnecessary simulation. - -See the \l{Particle System Performance Guide} for more in-depth information. - -\section1 Controlling Element Lifetime - -By partitioning an application into simple, modular components, each contained in a single -QML file, you can achieve faster application startup time and better control over memory -usage, and reduce the number of active-but-invisible elements in your application. - -\section2 Lazy Initialization - -The QML engine does some tricky things to try to ensure that loading and initialization of -components doesn't cause frames to be skipped. However, there is no better way to reduce -startup time than to avoid doing work you don't need to do, and delaying the work until -it is necessary. This may be achieved by using either \l Loader or creating components -\l {Dynamic QML Object Creation from JavaScript}{dynamically}. - -\section3 Using Loader - -The Loader is an element which allows dynamic loading and unloading of components. - -\list -\li Using the "active" property of a Loader, initialization can be delayed until required. -\li Using the overloaded version of the "setSource()" function, initial property values can - be supplied. -\li Setting the Loader \l {Loader::asynchronous}{asynchronous} property to true may also - improve fluidity while a component is instantiated. -\endlist - -\section3 Using Dynamic Creation - -Developers can use the Qt.createComponent() function to create a component dynamically at -runtime from within JavaScript, and then call createObject() to instantiate it. Depending -on the ownership semantics specified in the call, the developer may have to delete the -created object manually. See \l{Dynamic QML Object Creation from JavaScript} for more -information. - -\section2 Destroy Unused Elements - -Elements which are invisible because they are a child of a non-visible element (for example, the -second tab in a tab-widget, while the first tab is shown) should be initialized lazily in -most cases, and deleted when no longer in use, to avoid the ongoing cost of leaving them -active (for example, rendering, animations, property binding evaluation, etc). - -An item loaded with a Loader element may be released by resetting the "source" or -"sourceComponent" property of the Loader, while other items may be explicitly -released by calling destroy() on them. In some cases, it may be necessary to -leave the item active, in which case it should be made invisible at the very least. - -See the upcoming section on Rendering for more information on active but invisible elements. - -\section1 Rendering - -The scene graph used for rendering in QtQuick 2 allows highly dynamic, animated user -interfaces to be rendered fluidly at 60 FPS. There are some things which can -dramatically decrease rendering performance, however, and developers should be careful -to avoid these pitfalls wherever possible. - -\target clipping-performance -\section2 Clipping - -Clipping is disabled by default, and should only be enabled when required. - -Clipping is a visual effect, NOT an optimization. It increases (rather than reduces) -complexity for the renderer. If clipping is enabled, an item will clip its own painting, -as well as the painting of its children, to its bounding rectangle. This stops the renderer -from being able to reorder the drawing order of elements freely, resulting in a sub-optimal -best-case scene graph traversal. - -Clipping inside a delegate is especially bad and should be avoided at all costs. - -\section2 Over-drawing and Invisible Elements - -If you have elements which are totally covered by other (opaque) elements, it is best to -set their "visible" property to \c false or they will be drawn needlessly. - -Similarly, elements which are invisible (for example, the second tab in a tab widget, while the -first tab is shown) but need to be initialized at startup time (for example, if the cost of -instantiating the second tab takes too long to be able to do it only when the tab is -activated), should have their "visible" property set to \c false, in order to avoid the -cost of drawing them (although as previously explained, they will still incur the cost of -any animations or bindings evaluation since they are still active). - -\section2 Translucent vs Opaque - -Opaque content is generally a lot faster to draw than translucent. The reason being -that translucent content needs blending and that the renderer can potentially optimize -opaque content better. - -An image with one translucent pixel is treated as fully translucent, even though it -is mostly opaque. The same is true for an \l BorderImage with transparent edges. - -\section2 Shaders - -The \l ShaderEffect type makes it possible to place GLSL code inline in a Qt Quick application with -very little overhead. However, it is important to realize that the fragment program needs to run -for every pixel in the rendered shape. When deploying to low-end hardware and the shader -is covering a large amount of pixels, one should keep the fragment shader to a few instructions -to avoid poor performance. - -Shaders written in GLSL allow for complex transformations and visual effects to be written, -however they should be used with care. Using a \l ShaderEffectSource causes a scene to be -prerendered into an FBO before it can be drawn. This extra overhead can be quite expensive. - -\section1 Memory Allocation And Collection - -The amount of memory which will be allocated by an application and the way in which that -memory will be allocated are very important considerations. Aside from the obvious -concerns about out-of-memory conditions on memory-constrained devices, allocating memory -on the heap is a fairly computationally expensive operation, and certain allocation -strategies can result in increased fragmentation of data across pages. JavaScript uses -a managed memory heap which is automatically garbage collected, and this has some -advantages, but also some important implications. - -An application written in QML uses memory from both the C++ heap and an automatically -managed JavaScript heap. The application developer needs to be aware of the subtleties -of each in order to maximise performance. - -\section2 Tips For QML Application Developers - -The tips and suggestions contained in this section are guidelines only, and may not be -applicable in all circumstances. Be sure to benchmark and analyze your application -carefully using empirical metrics, in order to make the best decisions possible. - -\section3 Instantiate and initialize components lazily - -If your application consists of multiple views (for example, multiple tabs) but only -one is required at any one time, you can use lazy instantiation to minimize the -amount of memory you need to have allocated at any given time. See the prior section -on \l{Lazy Initialization} for more information. - -\section3 Destroy unused objects - -If you lazy load components, or create objects dynamically during a JavaScript -expression, it is often better to \c{destroy()} them manually rather than wait for -automatic garbage collection to do so. See the prior section on -\l{Controlling Element Lifetime} for more information. - -\section3 Don't manually invoke the garbage collector - -In most cases, it is not wise to manually invoke the garbage collector, as it will block -the GUI thread for a substantial period of time. This can result in skipped frames and -jerky animations, which should be avoided at all costs. - -There are some cases where manually invoking the garbage collector is acceptable (and -this is explained in greater detail in an upcoming section), but in most cases, invoking -the garbage collector is unnecessary and counter-productive. - -\section3 Avoid defining multiple identical implicit types - -If a QML element has a custom property defined in QML, it becomes its own implicit type. -This is explained in greater detail in an upcoming section. If multiple identical -implicit types are defined inline in a component, some memory will be wasted. In that -situation it is usually better to explicitly define a new component which can then be -reused. - -Defining a custom property can often be a beneficial performance optimization (for -example, to reduce the number of bindings which are required or re-evaluated), or it -can improve the modularity and maintainability of a component. In those cases, using -custom properties is encouraged. However, the new type should, if it is used more than -once, be split into its own component (.qml file) in order to conserve memory. - -\section3 Reuse existing components - -If you are considering defining a new component, it's worth double checking that such a -component doesn't already exist in the component set for your platform. Otherwise, you -will be forcing the QML engine to generate and store type-data for a type which is -essentially a duplicate of another pre-existing and potentially already loaded component. - -\section3 Use singleton types instead of pragma library scripts - -If you are using a pragma library script to store application-wide instance data, -consider using a QObject singleton type instead. This should result in better performance, -and will result in less JavaScript heap memory being used. - -\section2 Memory Allocation in a QML Application - -The memory usage of a QML application may be split into two parts: its C++ heap usage -and its JavaScript heap usage. Some of the memory allocated in each will be unavoidable, -as it is allocated by the QML engine or the JavaScript engine, while the rest is -dependent upon decisions made by the application developer. - -The C++ heap will contain: -\list - \li the fixed and unavoidable overhead of the QML engine (implementation data - structures, context information, and so on); - \li per-component compiled data and type information, including per-type property - metadata, which is generated by the QML engine depending on which modules and - which components are loaded by the application; - \li per-object C++ data (including property values) plus a per-element metaobject - hierarchy, depending on which components the application instantiates; - \li any data which is allocated specifically by QML imports (libraries). -\endlist - -The JavaScript heap will contain: -\list - \li the fixed and unavoidable overhead of the JavaScript engine itself (including - built-in JavaScript types); - \li the fixed and unavoidable overhead of our JavaScript integration (constructor - functions for loaded types, function templates, and so on); - \li per-type layout information and other internal type-data generated by the JavaScript - engine at runtime, for each type (see note below, regarding types); - \li per-object JavaScript data ("var" properties, JavaScript functions and signal - handlers, and non-optimized binding expressions); - \li variables allocated during expression evaluation. -\endlist - -Furthermore, there will be one JavaScript heap allocated for use in the main thread, and -optionally one other JavaScript heap allocated for use in the WorkerScript thread. If an -application does not use a WorkerScript element, that overhead will not be incurred. The -JavaScript heap can be several megabytes in size, and so applications written for -memory-constrained devices may be best served by avoiding the WorkerScript element -despite its usefulness in populating list models asynchronously. - -Note that both the QML engine and the JavaScript engine will automatically generate their -own caches of type-data about observed types. Every component loaded by an application -is a distinct (explicit) type, and every element (component instance) that defines its -own custom properties in QML is an implicit type. Any element (instance of a component) -that does not define any custom property is considered by the JavaScript and QML engines -to be of the type explicitly defined by the component, rather than its own implicit type. - -Consider the following example: -\qml -import QtQuick - -Item { - id: root - - Rectangle { - id: r0 - color: "red" - } - - Rectangle { - id: r1 - color: "blue" - width: 50 - } - - Rectangle { - id: r2 - property int customProperty: 5 - } - - Rectangle { - id: r3 - property string customProperty: "hello" - } - - Rectangle { - id: r4 - property string customProperty: "hello" - } -} -\endqml - -In the previous example, the rectangles \c r0 and \c r1 do not have any custom properties, -and thus the JavaScript and QML engines consider them both to be of the same type. That -is, \c r0 and \c r1 are both considered to be of the explicitly defined \c Rectangle type. -The rectangles \c r2, \c r3 and \c r4 each have custom properties and are each considered -to be of different (implicit) types. Note that \c r3 and \c r4 are each considered to be of -different types, even though they have identical property information, simply because the -custom property was not declared in the component which they are instances of. - -If \c r3 and \c r4 were both instances of a \c RectangleWithString component, and that -component definition included the declaration of a string property named \c customProperty, -then \c r3 and \c r4 would be considered to be of the same type (that is, they would be -instances of the \c RectangleWithString type, rather than defining their own implicit type). - -\section2 In-Depth Memory Allocation Considerations - -Whenever making decisions regarding memory allocation or performance trade-offs, it is -important to keep in mind the impact of CPU-cache performance, operating system paging, -and JavaScript engine garbage collection. Potential solutions should be benchmarked -carefully in order to ensure that the best one is selected. - -No set of general guidelines can replace a solid understanding of the underlying -principles of computer science combined with a practical knowledge of the implementation -details of the platform for which the application developer is developing. Furthermore, -no amount of theoretical calculation can replace a good set of benchmarks and analysis -tools when making trade-off decisions. - -\section3 Fragmentation - -Fragmentation is a C++ development issue. If the application developer is not defining -any C++ types or plugins, they may safely ignore this section. - -Over time, an application will allocate large portions of memory, write data to that -memory, and subsequently free some portions of it once it has finished using -some of the data. This can result in "free" memory being located in non-contiguous -chunks, which cannot be returned to the operating system for other applications to use. -It also has an impact on the caching and access characteristics of the application, as -the "living" data may be spread across many different pages of physical memory. This -in turn could force the operating system to swap, which can cause filesystem I/O - which -is, comparatively speaking, an extremely slow operation. - -Fragmentation can be avoided by utilizing pool allocators (and other contiguous memory -allocators), by reducing the amount of memory which is allocated at any one time by -carefully managing object lifetimes, by periodically cleansing and rebuilding caches, -or by utilizing a memory-managed runtime with garbage collection (such as JavaScript). - -\section3 Garbage Collection - -JavaScript provides garbage collection. Memory which is allocated on the JavaScript -heap (as opposed to the C++ heap) is owned by the JavaScript engine. The engine will -periodically collect all unreferenced data on the JavaScript heap. - -\section4 Implications of Garbage Collection - -Garbage collection has advantages and disadvantages. It means that manually managing -object lifetime is less important. -However, it also means that a potentially long-lasting operation may be initiated by the -JavaScript engine at a time which is out of the application developer's control. Unless -JavaScript heap usage is considered carefully by the application developer, the frequency -and duration of garbage collection may have a negative impact upon the application -experience. - -\section4 Manually Invoking the Garbage Collector - -An application written in QML will (most likely) require garbage collection to be -performed at some stage. While garbage collection will be automatically triggered by -the JavaScript engine when the amount of available free memory is low, it is occasionally -better if the application developer makes decisions about when to invoke the garbage -collector manually (although usually this is not the case). - -The application developer is likely to have the best understanding of when an application -is going to be idle for substantial periods of time. If a QML application uses a lot -of JavaScript heap memory, causing regular and disruptive garbage collection cycles -during particularly performance-sensitive tasks (for example, list scrolling, animations, -and so forth), the application developer may be well served to manually invoke the -garbage collector during periods of zero activity. Idle periods are ideal for performing -garbage collection since the user will not notice any degradation of user experience -(skipped frames, jerky animations, and so on) which would result from invoking the garbage -collector while activity is occurring. - -The garbage collector may be invoked manually by calling \c{gc()} within JavaScript. -This will cause a comprehensive collection cycle to be performed, which -may take from between a few hundred to more than a thousand milliseconds to complete, and -so should be avoided if at all possible. - -\section3 Memory vs Performance Trade-offs - -In some situations, it is possible to trade-off increased memory usage for decreased -processing time. For example, caching the result of a symbol lookup used in a tight loop -to a temporary variable in a JavaScript expression will result in a significant performance -improvement when evaluating that expression, but it involves allocating a temporary variable. -In some cases, these trade-offs are sensible (such as the case above, which is almost always -sensible), but in other cases it may be better to allow processing to take slightly longer -in order to avoid increasing the memory pressure on the system. - -In some cases, the impact of increased memory pressure can be extreme. In some situations, -trading off memory usage for an assumed performance gain can result in increased page-thrash -or cache-thrash, causing a huge reduction in performance. It is always necessary to benchmark -the impact of trade-offs carefully in order to determine which solution is best in a given -situation. - -For in-depth information on cache performance and memory-time trade-offs, refer to the following -articles: -\list - \li Ulrich Drepper's excellent article: "What Every Programmer Should Know About Memory", - at: \l{https://people.freebsd.org/~lstewart/articles/cpumemory.pdf}. - \li Agner Fog's excellent manuals on optimizing C++ applications at: - \l{http://www.agner.org/optimize/}. -\endlist - -*/ diff --git a/doc/src/qmlapp/qml.qdoc b/doc/src/qmlapp/qml.qdoc deleted file mode 100644 index 769fae80f..000000000 --- a/doc/src/qmlapp/qml.qdoc +++ /dev/null @@ -1,145 +0,0 @@ -// Copyright (C) 2021 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - \page qtquick-qml-runtime.html - \ingroup qtquick-tools - \title Prototyping with the QML Runtime Tool - \target qml_runtime_tool - \ingroup qttools - \brief Utility to test and load QML files - - Qt includes the \c qml executable, a utility that loads and displays QML - documents. - - The \c qml utility is meant mainly for testing your QML applications and - components. To launch a QML application in a production environment, often - you need to develop a custom C++ application, or bundle the QML file in a - module. See \l {Deploying QML applications} for more information. When - given a bare \l Item as root element, \c qml will automatically create a - window to show the scene. Notably, \l QQmlComponent::create() will not do - that. Therefore, when moving from a prototype developed with \c qml to a - C++ application, you need to either make sure the root element is a - \l Window, or create a \l QQuickView in C++ to hold the root \l Item. - But in the meantime, you can load and test parts of your prototype - separately with the \c qml tool. - - To load a .qml file, provide the file path on the command prompt: - - \code - $ qml myqmlfile.qml - \endcode - - To see the configuration options, run \c qml with the \c --help argument. - - When the root object in the QML file that you are loading is an Item - rather than a Window, it needs to be wrapped in a Window to be shown. - While this work is pending, the top-level object that is already loaded - is represented by a \c PartialScene object. The \c qml tool then loads - additional QML files to decide what to do next: one is a configuration - file that specifies in what sort of container to wrap the \c PartialScene. - The \c PartialScene.container property gives a URL pointing to QML source - code for the container component, which normally should declare a \l Window - in which to wrap the \l Item that was loaded first. Thus, the process of - wrapping an Item into a Window is programmable; and by default, these - two additional QML files are loaded from resources inside the qml - executable. You can list the available configurations with the - \c --list-conf command: - - \code - $ qml --list-conf - Built-in configurations: - default - resizeToItem - \endcode - - The \c default configuration provides default behavior: the root Item will - be resized to fill the wrapper Window at startup, and also when the user - resizes the window. The alternative \c resizeToItem configuration works the - other way around: the Item can programmatically set its own size (for - example by creating bindings to its own \c width and \c height properties), - and the wrapper Window will be resized to fit (subject to any limits - that may be imposed by the window system). You can choose either of - these using the \c -c or \c --config option: - - \code - $ qml -c resizeToItem selfResizingItem.qml - \endcode - - Additional configurations can be added by creating configuration - directories in \l QStandardPaths::AppConfigLocation, each with two QML - files inside: a configuration file named \c configuration.qml, and a QML - file that declares the Item wrapper, which can have any name. If this has - been done, the \c {qml --list-conf} command will also list those extra - configurations, while the \c --verbose option will expand those to give the - complete paths to those configurations, and the additional locations that - were searched: - - \code - $ qml --list-conf --verbose - Built-in configurations: - default - resizeToItem - Other configurations: - /home/myuser/.config/QtProject/Qml Runtime/simplest - Checked in: - /home/myuser/.config/QtProject/Qml Runtime - /etc/xdg/QtProject/Qml Runtime - \endcode - - Here is an example \c configuration.qml file: - - \qml - import QmlRuntime.Config - - Configuration { - PartialScene { - itemType: "QQuickItem" - container: Qt.resolvedUrl("ItemWrapper.qml") - } - } - \endqml - - And here is the simplest-possible \c ItemWrapper.qml that the \c container - property could point to: - - \qml - import QtQuick - - Window { - required property Item containedObject: null - onContainedObjectChanged: { - if (containedObject == undefined || containedObject == null) { - visible = false; - } else { - containedObject.parent = contentItem; - visible = true; - } - } - } - \endqml - - When these files have been created, you can use the \c {qml -c} option - giving the name of the directory containing the \c configuration.qml file, - which specifies the path to the container object: - - \code - $ qml -c simplest mycomponent.qml - \endcode - - The \c qml runtime will directly set the \c containedObject property, which - is required to have that name; and when it is set, the \l Item will be - reparented to the \l Window and shown. Since this Window is declared in - QML, when you write your own wrapper window, you are free to add whatever - additional features you would like: to handle resizing in a customized - way, or to add capabilities that you may find useful during prototyping. - - Regardless of what was found in \c AppConfigLocation, you can alternatively - use the \c {qml -c} option giving the complete path to the - \c configuration.qml file, and it can in turn specify the complete path to - the container object; so these files can be located anywhere. - - In addition to the features that can be declared in the configuration files, - the \c qml tool also provides a few more features via command-line options. - Use the \c --help option to get an up-to-date list. -*/ diff --git a/doc/src/qmlapp/usecases/animations.qdoc b/doc/src/qmlapp/usecases/animations.qdoc deleted file mode 100644 index c82d13591..000000000 --- a/doc/src/qmlapp/usecases/animations.qdoc +++ /dev/null @@ -1,49 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only -/*! -\page qtquick-usecase-animations.html -\title Use case - Animations In QML -\brief Example of how to include animations in QML applications - -\l {Qt Quick} provides the ability to animate properties. Animating properties allows property values to move through -intermediate values instead of immediately changing to the target value. To animate the position of an item, you can -animate the properties that control the item's position, x and y for example, so that the item's position -changes each frame on the way to the target position. - -\section1 Fluid UIs - -QML was designed to facilitate the creation of fluid UIs. These are user interfaces where the UI components animate instead of appearing, disappearing, or jumping abruptly. Qt Quick provides two simple ways to have UI -components move with animation instead of instantly appearing at their new location. - -\section2 States and Transitions - -Qt Quick allows you to declare various UI states in \l State objects. These states are comprised of property changes from a -base state, and can be a useful way of organizing your UI logic. Transitions are objects you can associate with an item -to define how its properties will animate when they change due to a state change. - -States and transitions for an item can be declared with the \l Item::states and \l Item::transitions properties. -States are declared inside the states list property of an item, usually the root item of the component. Transitions -defined on the same item are used to animate the changes in the state. Here is an example. - -\snippet qmlapp/usecases/animations.qml states - -\section2 Animating Property Changes. - -Behaviors can be used to specify an animation for a property to use when it changes. This is then applied to all -changes, regardless of their source. The following example animates a button moving around the -screen using behaviors. - -\snippet qmlapp/usecases/animations.qml behave - -\section1 Other Animations - -Not all animations have to be tied to a specific property or state. You can also create animations more generally, and -specify target items and properties inside the animation. Here are some examples of different ways to do this: - -\snippet qmlapp/usecases/animations.qml constant -\snippet qmlapp/usecases/animations.qml scripted -\image qmlapp/qml-uses-animation.png - -More information about animations can be found on the \l{Important Concepts in Qt Quick - States, Transitions and -Animations} page. -*/ diff --git a/doc/src/qmlapp/usecases/integratingjs.qdoc b/doc/src/qmlapp/usecases/integratingjs.qdoc deleted file mode 100644 index b6234226b..000000000 --- a/doc/src/qmlapp/usecases/integratingjs.qdoc +++ /dev/null @@ -1,46 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only -/*! -\page qtquick-usecase-integratingjs.html -\title Use Case - Integrating JavaScript in QML -\brief Example of how to integrate JavaScript code in QML applications - -JavaScript code can be easily integrated into QML to provide UI logic, imperative control, or other benefits. - -\section1 Using JavaScript Expressions for Property Values - -JavaScript expressions can be used in QML as bindings. For example: -\code -Item { - width: Math.random() - height: width < 100 ? 100 : (width + 50) / 2 -} -\endcode - -Note that function calls, like Math.random(), will not be reevaluated unless their arguments -change. So binding to Math.random() will be one random number and not reevaluated, but if the width is changed in some -other manner, the height binding will be reevaluated to take that into account. - -\section1 Adding JavaScript Functions in QML - -JavaScript functions can be declared on QML items, like in the below example. This allows you to call the method -using the item id. - -\snippet qmlapp/usecases/integratingjs-inline.qml 0 - -\section1 Using JavaScript Files - -JavaScript files can be used for abstracting out logic from QML files. To do this, first place your functions inside a -.js file like in the example shown. - -\snippet qmlapp/usecases/myscript.js 0 - -Then import the file into any .qml file that needs to use the functions, like the example QML file below. - -\snippet qmlapp/usecases/integratingjs.qml 0 - -\image qmlapp/qml-uses-integratingjs.png - -For further details on the JavaScript engine used by QML, as well as the difference from browser JS, see the full -documentation on \l {JavaScript Expressions in QML Documents}. -*/ diff --git a/doc/src/qmlapp/usecases/layouts.qdoc b/doc/src/qmlapp/usecases/layouts.qdoc deleted file mode 100644 index fb5d95913..000000000 --- a/doc/src/qmlapp/usecases/layouts.qdoc +++ /dev/null @@ -1,111 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only -/*! -\page qtquick-usecase-layouts.html -\title Use Case - Positioners and Layouts In QML -\brief Example of how to create layouts for visual components in a QML application -\ingroup explanations-programminglanguages - -There are several ways to position items in QML. - -Below is a brief overview. For more details, see \l {Important Concepts In Qt Quick - Positioning}. - -\section1 Manual Positioning - -Items can be placed at specific x,y coordinates on the screen by setting their x,y properties. This will -setup their position relative to the top left corner of their parent, according to the -\l {Concepts - Visual Coordinates in Qt Quick}{visual coordinate system} rules. - -Combined with using \l{Property Binding}{bindings} instead of constant values for these properties, relative positioning is also easily -accomplished by setting the x and y coordinates to the appropriate bindings. - -\snippet qmlapp/usecases/layouts.qml import -\snippet qmlapp/usecases/layouts.qml direct - -\image qmlapp/qml-uses-layouts-direct.png - - -\section1 Anchors - -The \c Item type provides the abilitiy to anchor to other \l Item types. There -are seven anchor lines for each item: \e left, \e right, \e{vertical center}, -\e top, \e bottom, \e baseline and \e{horizontal center}. The three vertical -anchor lines can be anchored to any of the three vertical anchor lines of -another item, and the four horizontal anchor lines can be anchored to the -horizontal anchor lines of another item. - -For full details, see \l {Positioning with Anchors} and the documentation of the \l{Item::anchors.top}{anchors property}. - -\snippet qmlapp/usecases/layouts.qml import -\snippet qmlapp/usecases/layouts.qml anchors - -\image qmlapp/qml-uses-layouts-anchors.png - - -\section1 Positioners - -For the common case of wanting to \e position a set of types in a regular pattern, Qt Quick provides some positioner -types. Items placed in a positioner are automatically positioned in some way; for example, a \l [QML] Row positions items to be -horizontally adjacent (forming a row). - -For full details see \l {Item Positioners}. - -\snippet qmlapp/usecases/layouts.qml import -\snippet qmlapp/usecases/layouts.qml positioners - -\image qmlapp/qml-uses-layouts-positioners.png - -\section1 Layout Types - -\e{Layout types} function in a similar way as positioners but allow further refinement or -restrictions to the layout. Specifically, the layout types allow you to: - -\list -\li set the alignment of text and other items -\li resize and fill the allotted application areas automatically -\li set size constraints such as minimum or maximum dimensions -\li set the spacing between items within the layout -\endlist - -\qml - GroupBox { - id: gridBox - title: "Grid layout" - Layout.fillWidth: true - - GridLayout { - id: gridLayout - rows: 3 - flow: GridLayout.TopToBottom - anchors.fill: parent - Label { text: "Line 1" } - Label { text: "Line 2" } - Label { text: "Line 3" } - - TextField { } - TextField { } - TextField { } - - TextArea { - text: "This widget spans over three rows in the GridLayout.\n" - + "All items in the GridLayout are implicitly positioned from top to bottom." - Layout.rowSpan: 3 - Layout.fillHeight: true - Layout.fillWidth: true - } - } - } -\endqml -The snippet above comes from the \l{Qt Quick Layouts - Basic Example}{Basic Layouts} example. The -snippet shows the simplicity of adding various fields and items in a layout. The \l [QML] {GridLayout} can -be resized and its format is customizable through various properties. - -For more information about the layout types, visit: -\list -\li \l{Qt Quick Layouts Overview} -\li \l{Qt Quick Layouts - Basic Example}{Basic Layouts} example -\endlist - -\note \l{Qt Quick Layouts} was introduced in Qt 5.1 and requires \l{Qt Quick} 2.1. - -*/ diff --git a/doc/src/qmlapp/usecases/styling.qdoc b/doc/src/qmlapp/usecases/styling.qdoc deleted file mode 100644 index f5ebed882..000000000 --- a/doc/src/qmlapp/usecases/styling.qdoc +++ /dev/null @@ -1,44 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only -/*! -\page qtquick-usecase-styling.html -\title Use Case - Style And Theme Support -\brief Example of how to style user interface components in QML. - -Styling with QML involves creating a visual type and binding that to a property -or by directly assigning a value to a property. For types that incorporate -Qt Quick's \l{Models and Views in Qt Quick}{delegates} the visual type attaches -to the \e delegate property. - -\omit -When using Qt Quick Controls 1, the controls automatically set -the appropriate style from the respective \l{Supported Platforms}{platforms}. -\endomit - -\omit -\section1 Using the Styling QML Types - -The Qt Quick Controls 1 controls have a \c style property to which the -\e{styling types} bind. The controls have a corresponding styling type -from the Qt Quick Controls 1 Styles QML Types module. -For example, QtQuickControls1 Button has a ButtonStyle type and Menu -has a MenuStyle type. The styling types provide properties -applicable to their respective controls such as the background, label, -or for some controls, the cursor appearance. - -\snippet qmlapp/usecases/styling.qml 0 - -\note Qt Quick Controls 1 Styles was introduced in Qt 5.1 and requires -\l{Qt Quick} 2.1. -\endomit - -\section1 Accessing the System Palette - -The \l{SystemPalette} type provides information about the system's palette -information. QML applications can use this information to set the appearance -of visual types to match the native look and feel. In addition, on -\l{Desktop Platforms}{desktop} platforms, different color palettes are employed -when changing states, for example, when the application loses keyboard focus. - -When using the controls, the system colors are already used. -*/ diff --git a/doc/src/qmlapp/usecases/text.qdoc b/doc/src/qmlapp/usecases/text.qdoc deleted file mode 100644 index 66aaae126..000000000 --- a/doc/src/qmlapp/usecases/text.qdoc +++ /dev/null @@ -1,46 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only -/*! -\page qtquick-usecase-text.html -\title Use Case - Displaying Text In QML -\brief Example of how to display text in QML -To display text the Text type is provided by the \l {Qt Quick} module. For related uses, the \l{TextInput} and -\l{TextEdit} types provide editable text controls. For full HTML markup, see the \l {Qt WebEngine} module. - -\section1 Displaying and Formatting Text - -To display text in QML, create a Text item and set the text property to the text you wish to display. The Text item -will now display that text. - -Several properties can be set on the Text item to style the entire block of text. These include color, font family, -font size, bold and italic. For a full list of properties, consult the \l{Text} type documentation. - -Rich text like markup can be used to selectively style specific sections of text with a Text item. Set \l -Text::textFormat to Text.StyledText to use this functionality. More details are available in the documentation of the -\l{Text} type. - -\section1 Laying Out Text - -By default, Text will display the text as a single line unless it contains embedded newlines. To wrap the line, set the -wrapMode property and give the text an explicit width for it to wrap to. If the width or height is not explicitly set, -reading these properties will return the parameters of the bounding rect of the text (if you have explicitly set width -or height, you can still use paintedWidth and paintedHeight). With these parameters in mind, the Text can be positioned -like any other Item. - -\section1 Example Code -\snippet qmlapp/usecases/text.qml 0 -\image qmlapp/qml-uses-text.png - -\section1 Internationalization and Scalability - -When dealing with texts, applications must take into account various topics such as the device's -orientation and the language settings. - -The following pages go into detail about these various topics. -\list -\li \l{Right-to-left User Interfaces} -\li \l{Internationalization with Qt} -\li \l{Scalability} -\endlist - -*/ diff --git a/doc/src/qmlapp/usecases/userinput.qdoc b/doc/src/qmlapp/usecases/userinput.qdoc deleted file mode 100644 index 33931e927..000000000 --- a/doc/src/qmlapp/usecases/userinput.qdoc +++ /dev/null @@ -1,53 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only -/*! -\page qtquick-usecase-userinput.html -\title Use Case - Responding To User Input in QML -\brief Example of how to accept user input and respond to it in a QML application - -\section1 Supported types of user input - -The \l {Qt Quick} module provides support for the most common types of user input, -including mouse and touch events, text input, and key-press events. Other -modules provide support for other types of user input. -\omit -For example, the \l {Qt Sensors} module provides support for shake-gestures -in QML applications. -For further information about motion-gesture support, see the -\l {Qt Sensors} documentation. -\endomit - -This article covers how to handle basic user input. -For information about audio-visual input, see the \l {Qt Multimedia} documentation. - -\section2 Mouse and touch events - -The \l{Input Handlers}{input handlers} let QML applications handle mouse and -touch events. For example, you could create a button by adding a -\l TapHandler to an Image, or to a \l Rectangle with a \l Text object inside. -The \l TapHandler responds to taps or clicks on any type of pointing device. - -\snippet qmlapp/usecases/userinput.qml 0 - -\note Some Item types have their own built-in input handling. For example, -\l Flickable responds to mouse dragging, touch flicking, and mouse wheel scrolling. - -\section2 Keyboard and button events - -Button and key presses, from buttons on a device, a keypad, or a keyboard, -can all be handled using the \l Keys attached property. This attached property -is available on all \l Item derived types, and works with the \l Item::focus property -to determine which type receives the key event. For simple key handling, you can set the focus -to true on a single \l Item and do all your key handling there. - -\snippet qmlapp/usecases/userinput-keys.qml 0 - -For text input, we have several QML types to choose from. TextInput provides an -unstyled single-line editable text, while TextField is more suitable for -form fields in applications. TextEdit can handle multi-line editable text, -but TextArea is a better alternative as it adds styling. - -The following snippet demonstrates how to use these types in your application: - -\snippet qmlapp/usecases/userinput-text.qml 0 -*/ diff --git a/doc/src/qmlapp/usecases/visual.qdoc b/doc/src/qmlapp/usecases/visual.qdoc deleted file mode 100644 index 96f1c59b8..000000000 --- a/doc/src/qmlapp/usecases/visual.qdoc +++ /dev/null @@ -1,61 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only -/*! -\page qtquick-usecase-visual.html -\title Use Case - Visual Elements In QML -\brief Example of how to display visual item types in a QML application - -\section1 The Rectangle Type - -For the most basic of visuals, \l {Qt Quick} provides a \l Rectangle type to draw rectangles. These rectangles can be colored with a -color or a vertical gradient. The \l Rectangle type can also draw borders on the rectangle. - -For drawing custom shapes beyond rectangles, see the \l Canvas type or display -a pre-rendered image using the \l Image type. - -\snippet qmlapp/usecases/visual-rects.qml 0 -\image qmlapp/qml-uses-visual-rectangles.png - -\section1 The Image Type - -\l {Qt Quick} provides an \l Image type which may be used to display images. The -\l Image type has a \l {Image::}{source} property whose value can be a remote or local -URL, or the URL of an image file embedded in a compiled resource file. - -\snippet qmlapp/usecases/visual.qml image - -For more complex images there are other types similar to \l Image. -\l BorderImage draws an image with grid scaling, suitable for images used as -borders. \l AnimatedImage plays animated .gif and .mng images. \l AnimatedSprite -and \l SpriteSequence play animations comprised of multiple frames stored adjacently -in a non animated image format. - -For displaying video files and camera data, see the \l {Qt Multimedia} module. - -\section1 Shared Visual Properties - -All visual items provided by \l {Qt Quick} are based on the Item type, which provides a common set of attributes for -visual items, including opacity and transform attributes. - -\section2 Opacity and Visibility - -The QML object types provided by Qt Quick have built-in support for \l{Item::opacity}{opacity}. -Opacity can be animated to allow smooth transitions to or from a transparent -state. Visibility can also be managed with the \l{Item::visible}{visible} property more efficiently, -but at the cost of not being able to animate it. - -\snippet qmlapp/usecases/visual-opacity.qml 0 -\image qmlapp/qml-uses-visual-opacity.png - -\section2 Transforms - -Qt Quick types have built-in support for transformations. If you wish to have your -visual content rotated or scaled, you can set the \l Item::rotation or \l Item::scale -property. These can also be animated. - -\snippet qmlapp/usecases/visual-transforms.qml 0 -\image qmlapp/qml-uses-visual-transforms.png - -For more complex transformations, see the \l Item::transform property. - -*/ diff --git a/doc/src/qtdoc-toc.qdoc b/doc/src/qtdoc-toc.qdoc index e2ad4a202..af139a85f 100644 --- a/doc/src/qtdoc-toc.qdoc +++ b/doc/src/qtdoc-toc.qdoc @@ -176,24 +176,6 @@ \li \l {User Interface Compiler (uic)} \endlist \li \l {User Interfaces}{UI Frameworks} - \li \l {QML Applications}{Building UIs with Qt Quick} - \list - \li \l {First Steps with QML} - \li \l {QML Coding Conventions} - \li \l {Debugging QML Applications} - \li \l {Deploying QML Applications} - \li \l {QML Performance Considerations And Suggestions} - \li \l {Glossary Of QML Terms} - \li \l {Prototyping with the QML Runtime Tool} - \li \l {Scalability} - \li \l {Use case - Animations In QML}{Animations in QML} - \li \l {Use Case - Integrating JavaScript in QML}{Integrating JavaScript in QML} - \li \l {Use Case - Positioners and Layouts In QML}{Positioners and layouts in QML} - \li \l {Use Case - Style And Theme Support}{Style and theme support} - \li \l {Use Case - Displaying Text In QML}{Displaying text in QML} - \li \l {Use Case - Responding To User Input in QML}{Responding to user input in QML} - \li \l {Use Case - Visual Elements In QML}{Visual elements in QML} - \endlist \li \l {Desktop Integration} \li \l {Networking and Connectivity} \li \l {Inter-process communication in Qt}{Inter-process communication} diff --git a/doc/src/userinterfaces.qdoc b/doc/src/userinterfaces.qdoc index 36a34ddf6..ed71ebe8e 100644 --- a/doc/src/userinterfaces.qdoc +++ b/doc/src/userinterfaces.qdoc @@ -15,24 +15,25 @@ platform's native look and feel. \section1 Building UIs with Qt Quick -Qt Quick is for creating dynamic and fluid user interfaces. The +\l [Quick]{Qt Quick} is for creating dynamic and fluid user interfaces. The \l{Qt Quick Controls} module supplies QML types such as buttons, dialogs, and menus. You can use \l{The QML Reference}{QML}, a declarative language, to build the UI and JavaScript to implement the logic. The following list contains related overviews: \list -\li \l{Qt Quick Controls} -\li \l{QML Applications} - introduction to QML -\li \l{qtquick-usecase-visual.html}{Visual types in QML} -\li \l{qtquick-usecase-userinput.html}{Responding to User Input in QML} -\li \l{qtquick-usecase-animations.html}{Animations in QML} -\li \l{qtquick-usecase-text.html}{Displaying Text in QML} -\li \l{qtquick-usecase-layouts.html}{Layouts in QML} -\li \l{qtquick-usecase-styling.html}{Style and Theme Support} -\li \l{qtquick-usecase-integratingjs.html}{Integrating JavaScript in QML} -\li \l{Qt Quick 3D} - add-on for 3D graphics -\li \l{Qt Shader Tools} - add-on shader effects +\li \l {Qt Quick Controls} +\li \l {Getting started with Qt Quick applications} +\li \l {First Steps with QML} +\li \l {Glossary Of QML Terms} +\li \l {Visual types} +\li \l {Positioners and layouts} +\li \l {Handling user input} +\li \l {Displaying text} +\li \l {Animations} +\li \l {Integrating JavaScript in QML} +\li \l {Qt Quick 3D} - add-on for 3D graphics +\li \l {Qt Shader Tools} - add-on shader effects \endlist \section1 Qt Widgets User Interfaces @@ -98,7 +99,7 @@ The following table compares Qt Widgets and Qt Quick interfaces. \li \inlineimage ok.png \li \li Qt Widgets often require a mouse cursor for good interaction, whereas - Qt Quick provides QML types for touch interaction. + Qt Quick provides QML types for both mouse and touch interaction. \row \li Standard industry widgets \li