src/controls/CheckableListItem.qml

0001 /*
0002  *  SPDX-FileCopyrightText: 2020 Nate Graham <nate@kde.org>
0003  *
0004  *  SPDX-License-Identifier: LGPL-2.0-or-later
0005  */
0006
0007 import QtQuick.Controls 2.0 as QQC2
0008 import org.kde.kirigami 2.14 as Kirigami
0009
0010 /**
0011  * A simple subclass of BasicListItem that adds a checkbox on the left side of
0012  * the layout. The list item's own
0013  * <a href="https://doc.qt.io/qt-5/qml-qtquick-controls2-abstractbutton.html#checked-prop">checked</a>
0014  * property controls the check state of the checkbox.
0015  *
0016  * When the list item or its checkbox is clicked, the QtQuick.Controls.Action
0017  * specified in the list item's ``actions:`` property will be triggered.
0018  *
0019  * @note Due to the way BasicListItem works, the QtQuick.Controls.Action MUST contain the
0020  * line "checked = !checked" as the first line within its
0021  * @link QtQuick.Controls.Action.triggered QtQuick.Controls.Action.onTriggered @endlink handler.
0022  *
0023  * Example usage:
0024  * @code{.qml}
0025  * import org.kde.kirigami 2.14 as Kirigami
0026  *
0027  * ListView {
0028  *     id: listView
0029  *     model: [...]
0030  *     delegate: Kirigami.CheckableListItem {
0031  *         label: model.display
0032  *
0033  *         checked: model.checked
0034  *
0035  *         action: Action {
0036  *             onTriggered: {
0037  *                 checked = !checked
0038  *                 [ do something amazing ]
0039  *             }
0040  *         }
0041  *     }
0042  * }
0043  * @endcode
0044  * @see <a href="https://develop.kde.org/hig/components/editing/list">KDE Human Interface Guidelines on List Views and List Items</a>
0045  * @see <a href="https://develop.kde.org/hig/components/editing/checkbox">KDE Human Interface Guidelines on Checkboxes</a>
0046  * @since org.kde.kirigami 2.14
0047  * @inherit kirigami::BasicListItem
0048  */
0049 Kirigami.BasicListItem {
0050     id: checkableListItem
0051
0052     checkable: true
0053     activeBackgroundColor: "transparent"
0054     activeTextColor: Kirigami.Theme.textColor
0055     iconSelected: false
0056
0057     leading: QQC2.CheckBox {
0058         checked: checkableListItem.checked
0059         onToggled: {
0060             checkableListItem.checked = !checkableListItem.checked
0061
0062             // TODO(Qt6): rephrase as `checkableListItem.action?.trigger();`
0063             if (checkableListItem.action) {
0064                 checkableListItem.action.trigger();
0065             }
0066         }
0067     }
0068 }