Kirigami2

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

KDE's Doxygen guidelines are available online.