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
0008 import QtQuick.Layouts
0009 import org.kde.kirigami as Kirigami
0010
0011 /**
0012  * @brief A GridLayout optimized for showing one or two columns of cards,
0013  * depending on the available space.
0014  *
0015  * It Should be used when the cards are not instantiated by a model or by a
0016  * model which has always very few items.
0017  *
0018  * They are presented as a grid of two columns which will remain
0019  * centered if the application is really wide, or become a single
0020  * column if there is not enough space for two columns,
0021  * such as a mobile phone screen.
0022  *
0023  * A CardsLayout should always be contained within a ColumnLayout.
0024  *
0025  * @since 2.4
0026  * @inherit QtQuick.Layouts.GridLayout
0027  */
0028 GridLayout {
0029     /**
0030      * @brief This property holds the maximum number of columns.
0031      *
0032      * This layout will never lay out the items in more columns than maximumColumns
0033      *
0034      * default: ``2``
0035      *
0036      * @since 2.5
0037      */
0038     property int maximumColumns: 2
0039
0040     /**
0041      * @brief This property holds the maximum width the columns may have.
0042      *
0043      * The cards will never become wider than this size; when the GridLayout is wider than
0044      * maximumColumnWidth, it will switch from one to two columns.
0045      *
0046      * If the default needs to be overridden for some reason,
0047      * it is advised to express this unit as a multiple
0048      * of Kirigami.Units.gridUnit.
0049      *
0050      * default: ``20 * Kirigami.Units.gridUnit``
0051      */
0052     property int maximumColumnWidth: Kirigami.Units.gridUnit * 20
0053
0054     /**
0055      * @brief This property holds the minimum width the columns may have.
0056      *
0057      * The layout will try to dispose of items
0058      * in a number of columns that will respect this size constraint.
0059      *
0060      * default: ``12 * Kirigami.Units.gridUnit``
0061      *
0062      * @since 2.5
0063      */
0064     property int minimumColumnWidth: Kirigami.Units.gridUnit * 12
0065
0066     columns: Math.max(1, Math.min(maximumColumns > 0 ? maximumColumns : Infinity,
0067                                   Math.floor(width/minimumColumnWidth),
0068                                   Math.ceil(width/maximumColumnWidth)));
0069
0070     rowSpacing: Kirigami.Units.largeSpacing
0071     columnSpacing: Kirigami.Units.largeSpacing
0072
0073
0074     // NOTE: this default width which defaults to 2 columns is just to remove a binding loop on columns
0075     width: maximumColumnWidth*2 + Kirigami.Units.largeSpacing
0076     // same computation of columns, but on the parent size
0077     Layout.preferredWidth: maximumColumnWidth * Math.max(1, Math.min(maximumColumns > 0 ? maximumColumns : Infinity,
0078                                   Math.floor(parent.width/minimumColumnWidth),
0079                                   Math.ceil(parent.width/maximumColumnWidth))) + Kirigami.Units.largeSpacing * (columns - 1)
0080
0081     Layout.maximumWidth: Layout.preferredWidth
0082     Layout.alignment: Qt.AlignHCenter
0083
0084     Component.onCompleted: childrenChanged()
0085     onChildrenChanged: {
0086         for (const child of children) {
0087             child.Layout.fillHeight = true;
0088         }
0089     }
0090 }