1/*
2 * SPDX-FileCopyrightText: 2017 Marco Martin <mart@kde.org>
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 <QQmlEngine>
12
13class QQuickItem;
14
15/*!
16 *
17 * \qmltype FormData
18 * \inqmlmodule org.kde.kirigami.layouts
19 *
20 * \brief An attached property with information for decorating a FormLayout.
21 *
22 * It contains the text labels of fields and information about sections.
23 *
24 * Some of its properties can be used with other Layout types.
25 * \qml
26 * import org.kde.kirigami as Kirigami
27 *
28 * Kirigami.FormLayout {
29 * TextField {
30 * Kirigami.FormData.label: "User:"
31 * }
32 * TextField {
33 * Kirigami.FormData.label: "Password:"
34 * }
35 * }
36 * \endqml
37 * \sa FormLayout
38 * \since 2.3
39 */
40class FormLayoutAttached : public QObject
41{
42 Q_OBJECT
43 QML_NAMED_ELEMENT(FormData)
44 QML_ATTACHED(FormLayoutAttached)
45 QML_UNCREATABLE("")
46 /*!
47 * \qmlattachedproperty string FormData::label
48 *
49 * The label for a FormLayout field
50 */
51 Q_PROPERTY(QString label READ label WRITE setLabel NOTIFY labelChanged FINAL)
52 /*!
53 * \qmlattachedproperty int FormData::labelAlignment
54 *
55 * The alignment for the label of a FormLayout field
56 */
57 Q_PROPERTY(int labelAlignment READ labelAlignment WRITE setLabelAlignment NOTIFY labelAlignmentChanged FINAL)
58 /*!
59 * \qmlattachedproperty bool FormData::isSection
60 *
61 * If true, the child item of a FormLayout becomes a section separator, and
62 * may have different looks:
63 *
64 * To make it just a space between two fields, just put an empty item with \c{FormData.isSection}:
65 * \code
66 * TextField {
67 * Kirigami.FormData.label: "Label:"
68 * }
69 * Item {
70 * Kirigami.FormData.isSection: true
71 * }
72 * TextField {
73 * Kirigami.FormData.label: "Label:"
74 * }
75 * \endcode
76 *
77 * To make it a space with a section title:
78 * \code
79 * TextField {
80 * Kirigami.FormData.label: "Label:"
81 * }
82 * Item {
83 * Kirigami.FormData.label: "Section Title"
84 * Kirigami.FormData.isSection: true
85 * }
86 * TextField {
87 * Kirigami.FormData.label: "Label:"
88 * }
89 * \endcode
90 *
91 * To make it a space with a section title and a separator line:
92 * \code
93 * TextField {
94 * Kirigami.FormData.label: "Label:"
95 * }
96 * Kirigami.Separator {
97 * Kirigami.FormData.label: "Section Title"
98 * Kirigami.FormData.isSection: true
99 * }
100 * TextField {
101 * Kirigami.FormData.label: "Label:"
102 * }
103 * \endcode
104 */
105 Q_PROPERTY(bool isSection READ isSection WRITE setIsSection NOTIFY isSectionChanged FINAL)
106
107 /*!
108 * \qmlattachedproperty Item FormData::buddyFor
109 *
110 * This property can only be used
111 * in conjunction with a FormData::label,
112 * often in a layout that is a child of a 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 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 * By default buddy is the item that FormData is attached to.
122 * Custom buddy can only be a direct child of that item; nested components
123 * are not supported at the moment.
124 *
125 * \code
126 * Kirigami.FormLayout {
127 * Layouts.ColumnLayout {
128 * // If the accelerator is in the letter S,
129 * // pressing Alt+S gives focus to the slider.
130 * Kirigami.FormData.label: "Slider label:"
131 * Kirigami.FormData.buddyFor: slider
132 *
133 * QQC2.Slider {
134 * id: slider
135 * from: 0
136 * to: 100
137 * value: 50
138 * }
139 * }
140 * }
141 * \endcode
142 */
143 Q_PROPERTY(QQuickItem *buddyFor READ buddyFor WRITE setBuddyFor NOTIFY buddyForChanged FINAL)
144
145public:
146 explicit FormLayoutAttached(QObject *parent = nullptr);
147 ~FormLayoutAttached() override;
148
149 void setLabel(const QString &text);
150 QString label() const;
151
152 void setIsSection(bool section);
153 bool isSection() const;
154
155 QQuickItem *buddyFor() const;
156 void setBuddyFor(QQuickItem *aBuddyFor);
157
158 int labelAlignment() const;
159 void setLabelAlignment(int alignment);
160
161 // QML attached property
162 static FormLayoutAttached *qmlAttachedProperties(QObject *object);
163
164Q_SIGNALS:
165 void labelChanged();
166 void isSectionChanged();
167 void buddyForChanged();
168 void labelAlignmentChanged();
169
170private:
171 void resetBuddyFor();
172
173 QString m_label;
174 QString m_actualDecoratedLabel;
175 QString m_decoratedLabel;
176 QPointer<QQuickItem> m_buddyFor;
177 bool m_isSection = false;
178 int m_labelAlignment = 0;
179};
180
181QML_DECLARE_TYPEINFO(FormLayoutAttached, QML_HAS_ATTACHED_PROPERTIES)
182
183#endif // FORMLAYOUTATTACHED_H
184

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