Kirigami-addons

FormTextFieldDelegate.qml
1/*
2 * Copyright 2022 Carl Schwan <carl@carlschwan.eu>
3 * SPDX-License-Identifier: LGPL-2.0-or-later
4 */
5
6import QtQuick
7import QtQuick.Controls
8import QtQuick.Layouts
9
10import org.kde.kirigami as Kirigami
11
12import './private' as Private
13
14/**
15 * @brief A Form delegate that corresponds to a text field.
16 *
17 * ```qml
18 *
19 * FormCard.FormHeader {
20 * title: "Information"
21 * }
22 *
23 * FormCard.FormCard {
24 * FormCard.FormTextFieldDelegate {
25 * label: "Account name"
26 * }
27 *
28 * FormCard.FormTextFieldDelegate {
29 * label: "Password"
30 * statusMessage: "Password incorrect"
31 * status: Kirigami.MessageType.Error
32 * echoMode: TextInput.Password
33 * text: "666666666"
34 * }
35 *
36 * FormCard.FormTextFieldDelegate {
37 * label: "Password"
38 * statusMessage: "Password match"
39 * text: "4242424242"
40 * status: Kirigami.MessageType.Positive
41 * echoMode: TextInput.Password
42 * }
43 * }
44 * ```
45 *
46 * @since KirigamiAddons 0.11.0
47 *
48 * @inherit AbstractFormDelegate
49 */
50AbstractFormDelegate {
51 id: root
53 /**
54 * @brief A label containing primary text that appears above and
55 * to the left the text field.
56 */
57 required property string label
58
59 /**
60 * @brief set the maximum length of the text inside the TextField if maxLength > 0
61 */
62 property alias maximumLength: textField.maximumLength
63
64 /**
65 * @brief This hold the activeFocus state of the internal TextField.
66 */
67 property alias fieldActiveFocus: textField.activeFocus
68
69 /**
70 * @brief This hold the `readOnly` state of the internal TextField.
71 */
72 property alias readOnly: textField.readOnly
74 /**
75 * @brief This property holds the `echoMode` of the internal TextField.
76 *
77 * This consists of how the text inside the text field will be
78 * displayed to the user.
79 *
80 * @see <a href="https://doc.qt.io/qt-6/qml-qtquick-textinput.html#echoMode-prop">TextInput.echoMode</a>
81 */
82 property alias echoMode: textField.echoMode
83
84 /**
85 * @brief This property holds the `inputMethodHints` of the
86 * internal TextField.
87 *
88 * This consists of hints on the expected content or behavior of
89 * the text field, be it sensitive data, in a date format, or whether
90 * the characters will be hidden, for example.
91 *
92 * @see <a href="https://doc.qt.io/qt-6/qml-qtquick-textinput.html#inputMethodHints-prop">TextInput.inputMethodHints</a>
93 */
94 property alias inputMethodHints: textField.inputMethodHints
95
96 /**
97 * @brief This property holds the `placeholderText` of the
98 * internal TextField.
99 *
100 * This consists of secondary text shown by default on the text field
101 * if no text has been written in it.
102 */
103 property alias placeholderText: textField.placeholderText
104
105 /**
106 * @brief This property holds the `validator` of the internal TextField.
107 */
108 property alias validator: textField.validator
109
110 /**
111 * @brief This property holds the `acceptableInput` of the internal TextField.
112 */
113 property alias acceptableInput: textField.acceptableInput
114
115 /**
116 * @brief This property holds the current status message type of
117 * the text field.
118 *
119 * This consists of an inline message with a colorful background
120 * and an appropriate icon.
122 * The status property will affect the color of ::statusMessage used.
123 *
124 * Accepted values:
125 * - `Kirigami.MessageType.Information` (blue color)
126 * - `Kirigami.MessageType.Positive` (green color)
127 * - `Kirigami.MessageType.Warning` (orange color)
128 * - `Kirigami.MessageType.Error` (red color)
129 *
130 * default: `Kirigami.MessageType.Information` if ::statusMessage is set,
131 * nothing otherwise.
132 *
133 * @see Kirigami.MessageType
134 */
135 property var status: Kirigami.MessageType.Information
137 /**
138 * @brief This property holds the current status message of
139 * the text field.
140 *
141 * If this property is not set, no ::status will be shown.
142 */
143 property string statusMessage: ""
144
145 /**
146 * @This signal is emitted when the Return or Enter key is pressed.
147 *
148 * Note that if there is a validator or inputMask set on the text input,
149 * the signal will only be emitted if the input is in an acceptable
150 * state.
151 */
152 signal accepted();
153
154 /**
155 * @brief This signal is emitted when the Return or Enter key is pressed
156 * or the text input loses focus.
157 *
158 * Note that if there is a validator or inputMask set on the text input
159 * and enter/return is pressed, this signal will only be emitted if
160 * the input follows the inputMask and the validator returns an
161 * acceptable state.
162 */
163 signal editingFinished();
164
165 /**
166 * @brief This signal is emitted whenever the text is edited.
167 *
168 * Unlike textChanged(), this signal is not emitted when the text
169 * is changed programmatically, for example, by changing the
170 * value of the text property or by calling ::clear().
171 */
172 signal textEdited();
174 /**
175 * @brief Clears the contents of the text input and resets partial
176 * text input from an input method.
177 */
178 function clear(): void {
179 textField.clear();
180 }
181
182 /**
183 * Inserts text into the TextInput at position.
184 */
185 function insert(position: int, text: string): void {
186 textField.insert(position, text);
187 }
188
189 /**
190 * Causes all text to be selected.
191 * @since Kirigami Addons 1.4.0
192 */
193 function selectAll(): void {
194 textField.selectAll();
195 }
196
197 /**
198 * Causes the text from start to end to be selected.
199 * @since Kirigami Addons 1.4.0
200 */
201 function select(start: int, end: int): void {
202 textField.select(start, end);
203 }
204
205 onActiveFocusChanged: { // propagate focus to the text field
206 if (activeFocus) {
207 textField.forceActiveFocus();
208 }
209 }
210
211 onClicked: textField.forceActiveFocus()
212 background: null
213 Accessible.role: Accessible.EditableText
214
215 contentItem: ColumnLayout {
216 spacing: Private.FormCardUnits.verticalSpacing
217 RowLayout {
218 spacing: Private.FormCardUnits.horizontalSpacing
219
220 Layout.fillWidth: true
221
222 Label {
223 Layout.fillWidth: true
224 text: label
225 elide: Text.ElideRight
226 color: root.enabled ? Kirigami.Theme.textColor : Kirigami.Theme.disabledTextColor
227 wrapMode: Text.Wrap
228 maximumLineCount: 2
229 Accessible.ignored: true
230 }
231 Label {
232 TextMetrics {
233 id: metrics
234 text: label(root.maximumLength, root.maximumLength)
235 font: Kirigami.Theme.smallFont
236
237 function label(current: int, maximum: int): string {
238 return i18nc("@label %1 is current text length, %2 is maximum length of text field", "%1/%2", current, maximum)
239 }
240 }
241 // 32767 is the default value for TextField.maximumLength
242 visible: root.maximumLength < 32767
243 text: metrics.label(textField.text.length, root.maximumLength)
244 font: Kirigami.Theme.smallFont
245 color: textField.text.length === root.maximumLength
246 ? Kirigami.Theme.neutralTextColor
247 : Kirigami.Theme.textColor
248 horizontalAlignment: Text.AlignRight
249
250 Accessible.ignored: !visible
251
252 Layout.preferredWidth: metrics.advanceWidth
253 }
254 }
255 TextField {
256 id: textField
257 Accessible.name: root.label
258 Layout.fillWidth: true
259 placeholderText: root.placeholderText
260 text: root.text
261 onTextChanged: root.text = text
262 onAccepted: root.accepted()
263 onEditingFinished: root.editingFinished()
264 onTextEdited: root.textEdited()
265 activeFocusOnTab: false
266 }
267
268 Kirigami.InlineMessage {
269 id: formErrorHandler
270 visible: root.statusMessage.length > 0
271 Layout.topMargin: visible ? Kirigami.Units.smallSpacing : 0
272 Layout.fillWidth: true
273 text: root.statusMessage
274 type: root.status
275 }
276 }
277}
278
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:33:45 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.