diff options
Diffstat (limited to 'src/imports/controls/doc')
5 files changed, 247 insertions, 25 deletions
diff --git a/src/imports/controls/doc/snippets/qtquickcontrols2-combobox-custom.qml b/src/imports/controls/doc/snippets/qtquickcontrols2-combobox-custom.qml index 1bb68bdf..b902dab1 100644 --- a/src/imports/controls/doc/snippets/qtquickcontrols2-combobox-custom.qml +++ b/src/imports/controls/doc/snippets/qtquickcontrols2-combobox-custom.qml @@ -55,7 +55,7 @@ ComboBox { Connections { target: control - onPressedChanged: canvas.requestPaint() + function onPressedChanged() { canvas.requestPaint(); } } onPaint: { diff --git a/src/imports/controls/doc/snippets/qtquickcontrols2-delaybutton-custom.qml b/src/imports/controls/doc/snippets/qtquickcontrols2-delaybutton-custom.qml index 86c6a0b7..4bcbaa67 100644 --- a/src/imports/controls/doc/snippets/qtquickcontrols2-delaybutton-custom.qml +++ b/src/imports/controls/doc/snippets/qtquickcontrols2-delaybutton-custom.qml @@ -62,7 +62,7 @@ DelayButton { Connections { target: control - onProgressChanged: canvas.requestPaint() + function onProgressChanged() { canvas.requestPaint(); } } onPaint: { diff --git a/src/imports/controls/doc/snippets/qtquickcontrols2-headerview-simple.qml b/src/imports/controls/doc/snippets/qtquickcontrols2-headerview-simple.qml new file mode 100644 index 00000000..bea46bf3 --- /dev/null +++ b/src/imports/controls/doc/snippets/qtquickcontrols2-headerview-simple.qml @@ -0,0 +1,123 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//![file] +import QtQuick 2.15 +import QtQuick.Controls 2.15 +import Qt.labs.qmlmodels 1.0 + +ApplicationWindow { + visible: true + width: 640 + height: 480 + + //! [horizontal] + HorizontalHeaderView { + id: horizontalHeader + syncView: tableView + anchors.left: tableView.left + width: parent.width + height: contentHeight + } + //! [horizontal] + + //! [vertical] + VerticalHeaderView { + id: verticalHeader + syncView: tableView + anchors.top: tableView.top + width: contentWidth + height: parent.height + } + //! [vertical] + + TableView { + id: tableView + anchors.fill: parent + anchors.topMargin: horizontalHeader.height + anchors.leftMargin: verticalHeader.width + columnSpacing: 1 + rowSpacing: 1 + clip: true + + model: TableModel { + TableModelColumn { display: "name" } + TableModelColumn { display: "color" } + + rows: [ + { + "name": "cat", + "color": "black" + }, + { + "name": "dog", + "color": "brown" + }, + { + "name": "bird", + "color": "white" + } + ] + } + + delegate: Rectangle { + implicitWidth: 100 + implicitHeight: 50 + border.width: 1 + + Text { + text: display + anchors.centerIn: parent + } + } + } +} + +//![file] diff --git a/src/imports/controls/doc/src/includes/customize-button-background.qdocinc b/src/imports/controls/doc/src/includes/customize-button-background.qdocinc new file mode 100644 index 00000000..59df7d8e --- /dev/null +++ b/src/imports/controls/doc/src/includes/customize-button-background.qdocinc @@ -0,0 +1,25 @@ +//! [file] +\qml \QtMinorVersion +import QtQuick 2.\1 +import QtQuick.Controls 2.\1 + +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 + } + } +} +\endqml +//! [file] diff --git a/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc index ca1ecf48..5901663a 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc @@ -48,29 +48,7 @@ can override the \l {Control::}{background} item and set the radius property of Rectangle: - \qml \QtMinorVersion - import QtQuick 2.\1 - import QtQuick.Controls 2.\1 - - 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 - } - } - } - \endqml + \include customize-button-background.qdocinc file The second way to create the button is good if you plan to use your rounded button in several places. It involves moving the code into its own QML file @@ -214,6 +192,102 @@ files. \endlist + \section3 Considerations for custom styles + + When implementing your own style and customizing controls, there are some + points to keep in mind to ensure that your application is as performant as + possible. + + \section4 Avoid assigning an id to styles' implementations of item delegates + + As explained in \l {Definition of a Style}, when you implement your + own style for a control, you start off with the relevant template for + that control. For example, a style's \c Button.qml will be structured + similarly to this: + + \qml + T.Button { + // ... + + background: Rectangle { + // ... + } + + contentItem: Text { + // ... + } + + // ... + } + \endqml + + When you use a Button in your application, the \c background and + \c contentItem items will be created and parented to the root \c Button + item: + + \qml + // Creates the Button root item, the Rectangle background, + // and the Text contentItem. + Button { + text: qsTr("Confirm") + } + \endqml + + Suppose you then needed to do a one-off customization of the Button (as + explained in \l {Customizing a Control}): + + \include customize-button-background.qdocinc file + + In QML, this would normally result in both the default \c background + implementation and the one-off, custom \c background items being created. + Qt Quick Controls uses a technique that avoids creating both items, and + instead only creates the custom \c background, greatly improving the + creation performance of controls. + + This technique relies on the absence of an \l {The id Attribute}{id} in the + style's implementation of that item. If an id is assigned, the technique + cannot work, and both items will be created. For example, it can be + tempting to assign an id to the \c background or \c contentItem so that + other objects within the file can refer to those items: + + \qml + T.Button { + // ... + + background: Rectangle { + id: backgroundRect + // ... + } + + contentItem: Text { + // Use backgroundRect in some way... + } + + // ... + } + \endqml + + With this code, every time a Button instance with a customized background + is created, both backgrounds will be created, resulting in sub-optimal + creation performance. + + Prior to Qt 5.15, the old, unused background would be deleted to release + the resources associated with it. However, as the control does not own the + items, it should not delete them. As of Qt 5.15, old items are no longer + deleted, and so the \c backgroundRect item will live longer than it needs + to—typically until the application exits. Although the old item will be + hidden, visually unparented from the control, and removed from the + accessibility tree, it is important to keep the creation time and memory + usage of these unused items in mind when assigning an id in this context. + + \section4 Avoid imperative assignments of custom items + + The technique mentioned in the section above only works when an item is + \l {Prefer Declarative Bindings Over Imperative Assignments}{declaratively} + assigned for the first time, and so imperative assignments will result in + orphaned items. Always use declarative bindings to assign custom items + when possible. + \section3 Attached properties It is common for a style to have certain properties or attributes that |