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

source code of kirigami/src/layouts/padding.h