1/*
2 * SPDX-FileCopyrightText: 2023 Marco Martin <mart@kde.org>
3 * SPDX-FileCopyrightText: 2024 Harald Sitter <sitter@kde.org>
4 *
5 * SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7#ifndef PADDING_H
8#define PADDING_H
9
10#include <QQuickItem>
11#include <qtmetamacros.h>
12
13class PaddingPrivate;
14
15/**
16 * This item simply adds an external padding to contentItem's size.
17 *
18 * Padding item behaves similarly to QtQuick.Controls/Control::padding,
19 * but is more lightweight and thus efficient. Its implicit size is set
20 * to that of its contentItem's implicit size plus padding.
21 *
22 * @code
23 * import QtQuick.Controls as QQC2
24 * import org.kde.kirigami as Kirigami
25 *
26 * Kirigami.Padding {
27 * padding: Kirigami.Units.largeSpacing
28 * contentItem: QQC2.Button {}
29 * }
30 * @endcode
31 *
32 * With this component it is possible to add external paddings as a
33 * placeholder for an item, whereas with QtQuick.Layouts you would need to
34 * manually assign or bind attached properties whenever content item changes.
35 *
36 * @code
37 * import QtQuick
38 * import QtQuick.Layouts
39 * import QtQuick.Controls as QQC2
40 * import org.kde.kirigami as Kirigami
41 *
42 * ColumnLayout {
43 * property alias contentItem: container.contentItem
44 *
45 * Kirigami.Heading {
46 * Layout.fillWidth: true
47 * Layout.margins: Kirigami.Units.largeSpacing
48 * }
49 *
50 * Kirigami.Padding {
51 * id: container
52 * Layout.fillWidth: true
53 * padding: Kirigami.Units.largeSpacing
54 * }
55 * }
56 * @endcode
57 *
58 * @since KDE Frameworks 6.0
59 */
60class Padding : public QQuickItem
61{
62 Q_OBJECT
63 QML_ELEMENT
64
65 /**
66 * @brief This property holds the visual content Item.
67 *
68 * It will automatically resized taking into account all the paddings
69 */
70 Q_PROPERTY(QQuickItem *contentItem READ contentItem WRITE setContentItem NOTIFY contentItemChanged FINAL)
71
72 /**
73 * @brief This property holds the default padding.
74 *
75 * Padding adds a space between each edge of this ITem and its contentItem, effectively controlling its size.
76 * To specify a padding value for a specific edge of the control, set its relevant property:
77 * * leftPadding
78 * * rightPadding
79 * * topPadding
80 * * bottomPadding
81 */
82 Q_PROPERTY(qreal padding READ padding WRITE setPadding NOTIFY paddingChanged RESET resetPadding FINAL)
83
84 /**
85 * @brief This property holds the horizontal padding.
86 *
87 * Unless explicitly set, the value is equal to padding.
88 */
89 Q_PROPERTY(qreal horizontalPadding READ horizontalPadding WRITE setHorizontalPadding NOTIFY horizontalPaddingChanged RESET resetHorizontalPadding FINAL)
90
91 /**
92 * @brief This property holds the vertical padding.
93 *
94 * Unless explicitly set, the value is equal to padding.
95 */
96 Q_PROPERTY(qreal verticalPadding READ verticalPadding WRITE setVerticalPadding NOTIFY verticalPaddingChanged RESET resetVerticalPadding FINAL)
97
98 /**
99 * @brief This property holds the padding on the left side.
100 *
101 * Unless explicitly set, it falls back to horizontalPadding and then to padding.
102 * This always refers to the actual left, it won't be flipped on RTL layouts.
103 */
104 Q_PROPERTY(qreal leftPadding READ leftPadding WRITE setLeftPadding NOTIFY leftPaddingChanged RESET resetLeftPadding FINAL)
105
106 /**
107 * @brief the padding on the top side.
108 *
109 * Unless explicitly set, it falls back to verticalPadding and then to padding.
110 */
111 Q_PROPERTY(qreal topPadding READ topPadding WRITE setTopPadding NOTIFY topPaddingChanged RESET resetTopPadding FINAL)
112
113 /**
114 * @brief This property holds the padding on the right side.
115 *
116 * Unless explicitly set, it falls back to horizontalPadding and then to padding.
117 * This always refers to the actual right, it won't be flipped on RTL layouts.
118 */
119 Q_PROPERTY(qreal rightPadding READ rightPadding WRITE setRightPadding NOTIFY rightPaddingChanged RESET resetRightPadding FINAL)
120
121 /**
122 * @brief This property holds the padding on the bottom side.
123 *
124 * Unless explicitly set, it falls back to verticalPadding and then to padding.
125 */
126 Q_PROPERTY(qreal bottomPadding READ bottomPadding WRITE setBottomPadding NOTIFY bottomPaddingChanged RESET resetBottomPadding FINAL)
127
128 /**
129 * @brief The width available to the contentItem after deducting horizontal padding from the width of the Padding.
130 */
131 Q_PROPERTY(qreal availableWidth READ availableWidth NOTIFY availableWidthChanged FINAL)
132
133 /**
134 * @brief The height available to the contentItem after deducting vertical padding from the width of the Padding.
135 */
136 Q_PROPERTY(qreal availableHeight READ availableHeight NOTIFY availableHeightChanged FINAL)
137
138 /**
139 * @brief The implicitWidth of its contentItem, or 0 if not present.
140 */
141 Q_PROPERTY(qreal implicitContentWidth READ implicitContentWidth NOTIFY implicitContentWidthChanged FINAL)
142
143 /**
144 * @brief The implicitHeight of its contentItem, or 0 if not present.
145 */
146 Q_PROPERTY(qreal implicitContentHeight READ implicitContentHeight NOTIFY implicitContentHeightChanged FINAL)
147
148public:
149 Padding(QQuickItem *parent = nullptr);
150 ~Padding() override;
151
152 void setContentItem(QQuickItem *item);
153 QQuickItem *contentItem();
154
155 void setPadding(qreal padding);
156 void resetPadding();
157 qreal padding() const;
158
159 void setHorizontalPadding(qreal padding);
160 void resetHorizontalPadding();
161 qreal horizontalPadding() const;
162
163 void setVerticalPadding(qreal padding);
164 void resetVerticalPadding();
165 qreal verticalPadding() const;
166
167 void setLeftPadding(qreal padding);
168 void resetLeftPadding();
169 qreal leftPadding() const;
170
171 void setTopPadding(qreal padding);
172 void resetTopPadding();
173 qreal topPadding() const;
174
175 void setRightPadding(qreal padding);
176 void resetRightPadding();
177 qreal rightPadding() const;
178
179 void setBottomPadding(qreal padding);
180 void resetBottomPadding();
181 qreal bottomPadding() const;
182
183 qreal availableWidth() const;
184 qreal availableHeight() const;
185
186 qreal implicitContentWidth() const;
187 qreal implicitContentHeight() const;
188
189Q_SIGNALS:
190 void contentItemChanged();
191 void paddingChanged();
192 void horizontalPaddingChanged();
193 void verticalPaddingChanged();
194 void leftPaddingChanged();
195 void topPaddingChanged();
196 void rightPaddingChanged();
197 void bottomPaddingChanged();
198 void availableHeightChanged();
199 void availableWidthChanged();
200 void implicitContentWidthChanged();
201 void implicitContentHeightChanged();
202
203protected:
204 void geometryChange(const QRectF &newGeometry, const QRectF &oldGeometry) override;
205 void updatePolish() override;
206 void componentComplete() override;
207
208private:
209 friend class PaddingPrivate;
210 const std::unique_ptr<PaddingPrivate> d;
211};
212
213#endif
214

source code of kirigami/src/padding.h