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 | |
13 | class 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 | */ |
63 | class 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 | |
181 | public: |
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 | |
222 | Q_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 | |
236 | protected: |
237 | void geometryChange(const QRectF &newGeometry, const QRectF &oldGeometry) override; |
238 | void updatePolish() override; |
239 | void componentComplete() override; |
240 | |
241 | private: |
242 | friend class PaddingPrivate; |
243 | const std::unique_ptr<PaddingPrivate> d; |
244 | }; |
245 | |
246 | #endif |
247 | |