Kirigami-addons

FormCard.qml
1/*
2 * Copyright 2022 Devin Lin <devin@kde.org>
3 * SPDX-License-Identifier: LGPL-2.0-or-later
4 */
5
6import QtQuick
7import QtQuick.Controls
8import QtQuick.Layouts
9
10import org.kde.kirigami as Kirigami
11
12import "private" as Private
13
14/**
15 * @brief A single card that follows a form style.
16 *
17 * This is the entrypoint component for FormCard.
18 *
19 * A FormCard consists of a container that can be used to create your
20 * own Settings pages. It has a different color than the background.
21 *
22 * Each FormCard can contain one or more Form delegates in its ::contentItem.
23 * To add more than one Form delegate to a FormCard, use a
24 * QtQuick.Layouts.ColumnLayout to group them.
25 *
26 * Multiple FormCards can be grouped with a QtQuick.Layouts.ColumnLayout to
27 * represent different Settings sections.
28 *
29 * Each section is expected to contain a FormCardHeader as the first
30 * delegate, which serves the role of a section title.
31 *
32 * The height of the FormCard matches the implicit height of the
33 * ::contentItem and does not need to be set, while the width is expected
34 * to be given by the parent, for example, via a Layout.fillWidth.
35 *
36 * @since KirigamiAddons 0.11.0
37 *
38 * @inherit QtQuick.Item
39 */
40Item {
41 id: root
42
43 /**
44 * @brief The delegates inside the Form card.
45 *
46 * This is where you should add new Form delegates.
47 */
48 default property alias delegates: internalColumn.data
49
50 /**
51 * @brief The maximum width of the card.
52 *
53 * This can be set to a specific value to force its delegates to wrap
54 * instead of using the entire width of the parent.
55 *
56 * default: `Kirigami.Units.gridUnit * 30`
57 *
58 * @see cardWidthRestricted
59 */
60 property real maximumWidth: Kirigami.Units.gridUnit * 30
61
62 /**
63 * @brief The padding used around the content edges.
64 *
65 * default: `0`
66 */
67 property real padding: 0
68 property real verticalPadding: padding
69 property real horizontalPadding: padding
70 property real topPadding: verticalPadding
71 property real bottomPadding: verticalPadding
72 property real leftPadding: horizontalPadding
73 property real rightPadding: horizontalPadding
74
75 /**
76 * Whether the card's width is being restricted.
77 */
78 readonly property bool cardWidthRestricted: root.width > root.maximumWidth
79
80 Kirigami.Theme.colorSet: Kirigami.Theme.View
81 Kirigami.Theme.inherit: false
82
83 Layout.fillWidth: true
84
85 implicitHeight: topPadding + bottomPadding + internalColumn.implicitHeight + rectangle.borderWidth * 2
86
87 Kirigami.ShadowedRectangle {
88 id: rectangle
89
90 readonly property real borderWidth: 1
91 readonly property bool isDarkColor: {
92 const temp = Qt.darker(Kirigami.Theme.backgroundColor, 1);
93 return temp.a > 0 && getDarkness(Kirigami.Theme.backgroundColor) >= 0.4;
94 }
95
96 // only have card radius if it isn't filling the entire width
97 radius: root.cardWidthRestricted ? Kirigami.Units.cornerRadius : 0
98 color: Kirigami.Theme.backgroundColor
99
100 function getDarkness(background: color): real {
101 // Thanks to Gojir4 from the Qt forum
102 // https://forum.qt.io/topic/106362/best-way-to-set-text-color-for-maximum-contrast-on-background-color/
103 var temp = Qt.darker(background, 1);
104 var a = 1 - ( 0.299 * temp.r + 0.587 * temp.g + 0.114 * temp.b);
105 return a;
106 }
107
108 anchors {
109 top: parent.top
110 bottom: parent.bottom
111 left: parent.left
112 right: parent.right
113
114 leftMargin: root.cardWidthRestricted ? Math.round((root.width - root.maximumWidth) / 2) : -1
115 rightMargin: root.cardWidthRestricted ? Math.round((root.width - root.maximumWidth) / 2) : -1
116 }
117
118 border {
119 color: isDarkColor ? Qt.darker(Kirigami.Theme.backgroundColor, 1.2) : Kirigami.ColorUtils.linearInterpolation(Kirigami.Theme.backgroundColor, Kirigami.Theme.textColor, 0.15)
120 width: borderWidth
121 }
122
123 shadow {
124 size: isDarkColor ? Kirigami.Units.smallSpacing : Kirigami.Units.largeSpacing
125 color: Qt.alpha(Kirigami.Theme.textColor, 0.10)
126 }
127
128 ColumnLayout {
129 id: internalColumn
130
131 // used in FormDelegateBackground to determine whether to round corners of the background
132 readonly property bool _roundCorners: root.cardWidthRestricted
133
134 spacing: 0
135
136 // add 1 to margins to account for the border (so content doesn't overlap it)
137 anchors {
138 fill: parent
139 leftMargin: root.leftPadding + rectangle.borderWidth
140 rightMargin: root.rightPadding + rectangle.borderWidth
141 topMargin: root.topPadding + rectangle.borderWidth
142 bottomMargin: root.bottomPadding + rectangle.borderWidth
143 }
144 }
145 }
146}
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 13 2024 11:46:08 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.