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 * 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 */
35class FormLayoutAttached : public QObject
36{
37 Q_OBJECT
38 QML_NAMED_ELEMENT(FormData)
39 QML_ATTACHED(FormLayoutAttached)
40 QML_UNCREATABLE("")
41 /**
42 * The label for a org::kde::kirigami::FormLayout field
43 */
44 Q_PROPERTY(QString label READ label WRITE setLabel NOTIFY labelChanged FINAL)
45 /**
46 * The alignment for the label of a org::kde::kirigami::FormLayout field
47 */
48 Q_PROPERTY(int labelAlignment READ labelAlignment WRITE setLabelAlignment NOTIFY labelAlignmentChanged FINAL)
49 /**
50 * If true, the child item of a org::kde::kirigami::FormLayout becomes a section separator, and
51 * may have different looks:
52 * * To make it just a space between two fields, just put an empty item with FormData.isSection:
53 * @code
54 * TextField {
55 * Kirigami.FormData.label: "Label:"
56 * }
57 * Item {
58 * Kirigami.FormData.isSection: true
59 * }
60 * TextField {
61 * Kirigami.FormData.label: "Label:"
62 * }
63 * @endcode
64 *
65 * * To make it a space with a section title:
66 * @code
67 * TextField {
68 * Kirigami.FormData.label: "Label:"
69 * }
70 * Item {
71 * Kirigami.FormData.label: "Section Title"
72 * Kirigami.FormData.isSection: true
73 * }
74 * TextField {
75 * Kirigami.FormData.label: "Label:"
76 * }
77 * @endcode
78 *
79 * * To make it a space with a section title and a separator line:
80 * @code
81 * TextField {
82 * Kirigami.FormData.label: "Label:"
83 * }
84 * Kirigami.Separator {
85 * Kirigami.FormData.label: "Section Title"
86 * Kirigami.FormData.isSection: true
87 * }
88 * TextField {
89 * Kirigami.FormData.label: "Label:"
90 * }
91 * @endcode
92 * @see org::kde::kirigami::FormLayout
93 */
94 Q_PROPERTY(bool isSection READ isSection WRITE setIsSection NOTIFY isSectionChanged FINAL)
95
96 /**
97 * This property can only be used
98 * in conjunction with a Kirigami.FormData.label,
99 * often in a layout that is a child of a org::kde::kirigami::FormLayout.
100 *
101 * It then turns the item specified into a "buddy"
102 * of the label, making it work as if it were
103 * a child of the org::kde::kirigami::FormLayout.
104 *
105 * A buddy item is useful for instance when the label has a keyboard accelerator,
106 * which when triggered provides active keyboard focus to the buddy item.
107 *
108 * By default buddy is the item that Kirigami.FormData is attached to.
109 * Custom buddy can only be a direct child of that item; nested components
110 * are not supported at the moment.
111 *
112 * @code
113 * Kirigami.FormLayout {
114 * Layouts.ColumnLayout {
115 * // If the accelerator is in the letter S,
116 * // pressing Alt+S gives focus to the slider.
117 * Kirigami.FormData.label: "Slider label:"
118 * Kirigami.FormData.buddyFor: slider
119 *
120 * QQC2.Slider {
121 * id: slider
122 * from: 0
123 * to: 100
124 * value: 50
125 * }
126 * }
127 * }
128 * @endcode
129 */
130 Q_PROPERTY(QQuickItem *buddyFor READ buddyFor WRITE setBuddyFor NOTIFY buddyForChanged FINAL)
131
132public:
133 explicit FormLayoutAttached(QObject *parent = nullptr);
134 ~FormLayoutAttached() override;
135
136 void setLabel(const QString &text);
137 QString label() const;
138
139 void setIsSection(bool section);
140 bool isSection() const;
141
142 QQuickItem *buddyFor() const;
143 void setBuddyFor(QQuickItem *aBuddyFor);
144
145 int labelAlignment() const;
146 void setLabelAlignment(int alignment);
147
148 // QML attached property
149 static FormLayoutAttached *qmlAttachedProperties(QObject *object);
150
151Q_SIGNALS:
152 void labelChanged();
153 void isSectionChanged();
154 void buddyForChanged();
155 void labelAlignmentChanged();
156
157private:
158 void resetBuddyFor();
159
160 QString m_label;
161 QString m_actualDecoratedLabel;
162 QString m_decoratedLabel;
163 QPointer<QQuickItem> m_buddyFor;
164 bool m_isSection = false;
165 int m_labelAlignment = 0;
166};
167
168QML_DECLARE_TYPEINFO(FormLayoutAttached, QML_HAS_ATTACHED_PROPERTIES)
169
170#endif // FORMLAYOUTATTACHED_H
171

source code of kirigami/src/formlayoutattached.h