src/controls/CardsLayout.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.6
0008 import QtQuick.Layouts 1.2
0009 import org.kde.kirigami 2.4 as Kirigami
0010
0011 /**
0012  * @brief A QtQuick.Layouts.GridLayout optimized for showing a couple of columns
0013  * of cards, depending on the available space.
0014  *
0015  * This should be used when the cards to be displayed, are not instantiated by
0016  * a model or are instantiated by a model that always has very few items
0017  * (in the case of a big model, use CardsListView or CardsGridView instead).
0018  *
0019  * The cards are presented in a grid of at least one column, which will remain
0020  * centered. Note that the layout will automatically add and remove columns
0021  * depending on the size available.
0022  *
0023  * @note A CardsLayout should always be contained within a
0024  * QtQuick.Layouts.ColumnLayout.
0025  *
0026  * @since org.kde.kirigami 2.4
0027  * @inherit QtQuick.Layouts.GridLayout
0028  */
0029 GridLayout {
0030     /**
0031      * @brief This property holds the maximum number of columns.
0032      *
0033      * default: ``2``
0034      *
0035      * @since org.kde.kirigami 2.5
0036      */
0037     property int maximumColumns: 2
0038
0039     /**
0040      * @brief This property holds the maximum width the columns may have.
0041      *
0042      * If the default needs to be overridden for some reason,
0043      * it is advised to express this unit as a multiple
0044      * of Kirigami.Units.gridUnit.
0045      *
0046      * default: ``20 * Kirigami.Units.gridUnit``
0047      */
0048     property int maximumColumnWidth: Kirigami.Units.gridUnit * 20
0049
0050     /**
0051      * @brief This property holds the minimum width the columns may have.
0052      *
0053      * default: ``12 * Kirigami.Units.gridUnit``
0054      *
0055      * @since org.kde.kirigami 2.5
0056      */
0057     property int minimumColumnWidth: Kirigami.Units.gridUnit * 12
0058
0059     columns: Math.max(1, Math.min(maximumColumns > 0 ? maximumColumns : Infinity,
0060                                   Math.floor(width/minimumColumnWidth),
0061                                   Math.ceil(width/maximumColumnWidth)));
0062
0063     rowSpacing: Kirigami.Units.largeSpacing * columns
0064     columnSpacing: Kirigami.Units.largeSpacing * columns
0065
0066
0067     // NOTE: this default width which defaults to 2 columns is just to remove a binding loop on columns
0068     width: maximumColumnWidth*2 + Kirigami.Units.largeSpacing
0069     // same computation of columns, but on the parent size
0070     Layout.preferredWidth: maximumColumnWidth * Math.max(1, Math.min(maximumColumns > 0 ? maximumColumns : Infinity,
0071                                   Math.floor(parent.width/minimumColumnWidth),
0072                                   Math.ceil(parent.width/maximumColumnWidth))) + Kirigami.Units.largeSpacing * (columns - 1)
0073
0074     Layout.maximumWidth: Layout.preferredWidth
0075     Layout.alignment: Qt.AlignHCenter
0076
0077     Component.onCompleted: childrenChanged()
0078     onChildrenChanged: {
0079         for (let i = 0; i < children.length; ++i) {
0080             children[i].Layout.fillHeight = true;
0081         }
0082     }
0083 }