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 | |
13 | class 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 | */ |
40 | class 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 | |
145 | public: |
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 | |
164 | Q_SIGNALS: |
165 | void labelChanged(); |
166 | void isSectionChanged(); |
167 | void buddyForChanged(); |
168 | void labelAlignmentChanged(); |
169 | |
170 | private: |
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 | |
181 | QML_DECLARE_TYPEINFO(FormLayoutAttached, QML_HAS_ATTACHED_PROPERTIES) |
182 | |
183 | #endif // FORMLAYOUTATTACHED_H |
184 | |