src/controls/CardsGridView.qml

0001 /*
0002  *  SPDX-FileCopyrightText: 2018 Marco Martin <mart@kde.org>
0003  *
0004  *  SPDX-License-Identifier: LGPL-2.0-or-later
0005  */
0006
0007 import QtQuick 2.10
0008 import QtQuick.Layouts 1.2
0009 import org.kde.kirigami 2.4 as Kirigami
0010 import "private" as P
0011
0012
0013 //TODO KF6: remove the whole class?
0014 /**
0015  * @brief CardsGridView is used to display a grid of Cards generated from any model.
0016  *
0017  * The behavior is same as CardsLayout, and it allows cards to be put in one or two
0018  * columns depending on the available width.
0019  *
0020  * GridView has the limitation that every Card must have the same exact height,
0021  * so cellHeight must be manually set to a value in which the content fits
0022  * for every item.
0023  *
0024  * If possible use cards only when you don't need to instantiate a lot
0025  * and use CardsLayout instead.
0026  *
0027  * @see kirigami::CardsLayout
0028  * @see kirigami::CardsListView
0029  * @see <a href="https://develop.kde.org/hig/components/editing/grid">KDE Human Interface Guidelines on Grids</a>
0030  * @since org.kde.kirigami 2.4
0031  * @inherit QtQuick.GridView
0032  */
0033 P.CardsGridViewPrivate {
0034     id: root
0035
0036     /**
0037      * @brief This property sets whether the view should fill the first row with columns
0038      * even when there is not enough space.
0039      *
0040      * Set this to @c true if you want to stop the view from filling the first row with columns,
0041      * even when delegates can't even fill the first row.
0042      *
0043      * default: ``true``
0044      */
0045     property bool extraColumns: true
0046
0047     /**
0048      * @brief This property holds the number of columns the gridview has.
0049      * @since org.kde.kirigami 2.5
0050      */
0051     readonly property int columns: {
0052         const minFromWidth = Math.floor(width / minimumColumnWidth)
0053         const maxFromWidth = Math.ceil(width / maximumColumnWidth)
0054         const maxColumns = extraColumns ? maximumColumns : count
0055         return Math.max(1,Math.min(minFromWidth,maxFromWidth,maxColumns))
0056     }
0057
0058     /**
0059      * @brief This property holds the maximum number of columns the gridview may have.
0060      *
0061      * default: ``Kirigami.Units.maximumInteger()``
0062      *
0063      * @since org.kde.kirigami 2.5
0064      */
0065     property int maximumColumns: Kirigami.Units.maximumInteger
0066
0067     /**
0068      * @brief This property holds the maximum width that the columns may have.
0069      *
0070      * The cards will never become wider than this size; when the GridView is wider
0071      * than maximumColumnWidth, it will switch from one to two columns.
0072      *
0073      * If the default needs to be overridden for some reason,
0074      * it is advised to express this unit as a multiple
0075      * of Kirigami.Units.gridUnit.
0076      *
0077      * default: ``20 * Kirigami.Units.gridUnit``
0078      */
0079     property int maximumColumnWidth: Kirigami.Units.gridUnit * 20
0080
0081     /**
0082      * @brief This property holds the minimum width that the columns may have.
0083      *
0084      * The cards will never become thinner than this.
0085      *
0086      * If the default needs to be overridden for some reason,
0087      * it is advised to express this unit as a multiple
0088      * of Kirigami.Units.gridUnit.
0089      *
0090      * default: ``12 * Kirigami.Units.gridUnit``
0091      *
0092      * @since org.kde.kirigami 2.5
0093      */
0094     property int minimumColumnWidth: Kirigami.Units.gridUnit * 12
0095
0096     cellWidth: Math.floor(width/columns)
0097     cellHeight: Math.max(Kirigami.Units.gridUnit * 15, Math.min(cellWidth, maximumColumnWidth) / 1.2)
0098
0099     /**
0100      * @brief This property holds the delegate of the CardsGridView.
0101      * @see <a href="https://doc.qt.io/qt-5/qml-qtquick-gridview.html#delegate-prop">GridView.delegate</a>
0102      */
0103     default property alias delegate: root._delegateComponent
0104
0105     topMargin: Kirigami.Units.largeSpacing * 2
0106
0107     Keys.onPressed: event => {
0108         if (event.key === Qt.Key_Home) {
0109             positionViewAtBeginning();
0110             currentIndex = 0;
0111             event.accepted = true;
0112         }
0113         else if (event.key === Qt.Key_End) {
0114             positionViewAtEnd();
0115             currentIndex = count - 1;
0116             event.accepted = true;
0117         }
0118     }
0119 }