Kirigami2

formlayoutattached.h
1 /*
2  * SPDX-FileCopyrightText: 2017 Marco Martin <[email protected]>
3  *
4  * SPDX-License-Identifier: LGPL-2.0-or-later
5  */
6 
7 #ifndef FORMLAYOUTATTACHED_H
8 #define FORMLAYOUTATTACHED_H
9 
10 #include <QObject>
11 #include <QtQml>
12 
13 class QQuickItem;
14 
15 /**
16  * This attached property contains the information for decorating a org::kde::kirigami::FormLayout:
17  *
18  * It contains the text labels of fields and information about sections.
19  *
20  * Some of its properties can be used with other <a href="https://doc.qt.io/qt-6/qml-qtquick-layouts-layout.html">Layout</a> types.
21  * @code
22  * import org.kde.kirigami 2.3 as Kirigami
23  * Kirigami.FormLayout {
24  * TextField {
25  * Kirigami.FormData.label: "Label:"
26  * }
27  * TextField {
28  * Kirigami.FormData.label: "Label:"
29  * }
30  * }
31  * @endcode
32  * @see org::kde::kirigami::FormLayout
33  * @since 2.3
34  */
36 {
37  Q_OBJECT
38  /**
39  * The label for a org::kde::kirigami::FormLayout field
40  */
41  Q_PROPERTY(QString label READ label WRITE setLabel NOTIFY labelChanged)
42  /**
43  * The alignment for the label of a org::kde::kirigami::FormLayout field
44  */
45  Q_PROPERTY(int labelAlignment READ labelAlignment WRITE setLabelAlignment NOTIFY labelAlignmentChanged)
46  /**
47  * If true, the child item of a org::kde::kirigami::FormLayout becomes a section separator, and
48  * may have different looks:
49  * * To make it just a space between two fields, just put an empty item with FormData.isSection:
50  * @code
51  * TextField {
52  * Kirigami.FormData.label: "Label:"
53  * }
54  * Item {
55  * Kirigami.FormData.isSection: true
56  * }
57  * TextField {
58  * Kirigami.FormData.label: "Label:"
59  * }
60  * @endcode
61  *
62  * * To make it a space with a section title:
63  * @code
64  * TextField {
65  * Kirigami.FormData.label: "Label:"
66  * }
67  * Item {
68  * Kirigami.FormData.label: "Section Title"
69  * Kirigami.FormData.isSection: true
70  * }
71  * TextField {
72  * Kirigami.FormData.label: "Label:"
73  * }
74  * @endcode
75  *
76  * * To make it a space with a section title and a separator line:
77  * @code
78  * TextField {
79  * Kirigami.FormData.label: "Label:"
80  * }
81  * Kirigami.Separator {
82  * Kirigami.FormData.label: "Section Title"
83  * Kirigami.FormData.isSection: true
84  * }
85  * TextField {
86  * Kirigami.FormData.label: "Label:"
87  * }
88  * @endcode
89  * @see org::kde::kirigami::FormLayout
90  */
91  Q_PROPERTY(bool isSection READ isSection WRITE setIsSection NOTIFY isSectionChanged)
92 
93  /**
94  * If true, a checkbox is prepended to the org::kde::kirigami::FormLayout item.
95  */
96  Q_PROPERTY(bool checkable READ checkable WRITE setCheckable NOTIFY checkableChanged)
97 
98  /**
99  * This property is true when the checkbox of the org::kde::kirigami::FormLayout item is checked.
100  * @see checkable.
101  */
102  Q_PROPERTY(bool checked READ checked WRITE setChecked NOTIFY checkedChanged)
103 
104  /**
105  * This property holds whether the label and the checkbox of the org::kde::kirigami::FormLayout item receive mouse and keyboard events.
106  */
107  Q_PROPERTY(bool enabled READ enabled WRITE setEnabled NOTIFY enabledChanged)
108 
109  /**
110  * This property can only be used
111  * in conjunction with a Kirigami.FormData.label,
112  * often in a layout that is a child of a org::kde::kirigami::FormLayout.
113  *
114  * It then turns the item specified into a "buddy"
115  * of the label, making it work as if it were
116  * a child of the org::kde::kirigami::FormLayout.
117  *
118  * A buddy item is useful for instance when the label has a keyboard accelerator,
119  * which when triggered provides active keyboard focus to the buddy item.
120  *
121  * @code
122  * Kirigami.FormLayout {
123  * Layouts.ColumnLayout {
124  * // If the accelerator is in the letter S,
125  * // pressing Alt+S gives focus to the slider.
126  * Kirigami.FormData.label: "Slider label:"
127  * Kirigami.FormData.buddyFor: slider
128  *
129  * QQC2.Slider {
130  * id: slider
131  * from: 0
132  * to: 100
133  * value: 50
134  * }
135  * }
136  * }
137  * @endcode
138  */
139  Q_PROPERTY(QQuickItem *buddyFor READ buddyFor WRITE setBuddyFor NOTIFY buddyForChanged)
140 
141 public:
142  explicit FormLayoutAttached(QObject *parent = nullptr);
143  ~FormLayoutAttached() override;
144 
145  void setLabel(const QString &text);
146  QString label() const;
147 
148  void setIsSection(bool section);
149  bool isSection() const;
150 
151  void setCheckable(bool checkable);
152  bool checkable() const;
153 
154  void setChecked(bool checked);
155  bool checked() const;
156 
157  void setEnabled(bool enabled);
158  bool enabled() const;
159 
160  QQuickItem *buddyFor() const;
161  void setBuddyFor(QQuickItem *buddyfor);
162 
163  int labelAlignment() const;
164  void setLabelAlignment(int alignment);
165 
166  // QML attached property
167  static FormLayoutAttached *qmlAttachedProperties(QObject *object);
168 
169 Q_SIGNALS:
170  void labelChanged();
171  void isSectionChanged();
172  void checkableChanged();
173  void checkedChanged();
174  void enabledChanged();
175  void buddyForChanged();
176  void labelAlignmentChanged();
177 
178 private:
179  QString m_label;
180  QString m_actualDecoratedLabel;
181  QString m_decoratedLabel;
182  QPointer<QQuickItem> m_buddyFor;
183  bool m_isSection = false;
184  bool m_checkable = false;
185  bool m_checked = false;
186  bool m_enabled = true;
187  int m_labelAlignment = 0;
188 };
189 
190 QML_DECLARE_TYPEINFO(FormLayoutAttached, QML_HAS_ATTACHED_PROPERTIES)
191 
192 #endif // FORMLAYOUTATTACHED_H
Q_OBJECTQ_OBJECT
bool enabled
This property holds whether the label and the checkbox of the org::kde::kirigami::FormLayout item rec...
Q_PROPERTY(...)
QQuickItem buddyFor
This property can only be used in conjunction with a Kirigami.FormData.label, often in a layout that ...
bool checkable
If true, a checkbox is prepended to the org::kde::kirigami::FormLayout item.
bool isSection
If true, the child item of a org::kde::kirigami::FormLayout becomes a section separator,...
This attached property contains the information for decorating a org::kde::kirigami::FormLayout:
bool checked
This property is true when the checkbox of the org::kde::kirigami::FormLayout item is checked.
QString label
The label for a org::kde::kirigami::FormLayout field.
Q_SIGNALSQ_SIGNALS
int labelAlignment
The alignment for the label of a org::kde::kirigami::FormLayout field.
QObject * parent() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Jan 29 2023 04:11:03 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.