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
115 /**
116 * @brief This property holds the `cursorPosition` of the internal TextField.
117 *
118 * The `cursorPosition` property holds the position of the cursor in the
119 * text field. A value of 0 indicates that the cursor is at the beginning
120 * of the text field.
121 *
122 * This property allows you to programmatically control and access the
123 * cursor position within the text field, which can be useful for
124 * integrating the `FormTextFieldDelegate` component into your project.
125 *
126 * @see <a href="https://doc.qt.io/qt-6/qml-qtquick-textinput.html#cursorPosition-prop">TextInput.cursorPosition</a>
127 */
128 property alias cursorPosition: textField.cursorPosition
129
130 /**
131 * @brief This property holds the current status message type of
132 * the text field.
133 *
134 * This consists of an inline message with a colorful background
135 * and an appropriate icon.
136 *
137 * The status property will affect the color of ::statusMessage used.
138 *
139 * Accepted values:
140 * - `Kirigami.MessageType.Information` (blue color)
141 * - `Kirigami.MessageType.Positive` (green color)
142 * - `Kirigami.MessageType.Warning` (orange color)
143 * - `Kirigami.MessageType.Error` (red color)
144 *
145 * default: `Kirigami.MessageType.Information` if ::statusMessage is set,
146 * nothing otherwise.
147 *
148 * @see Kirigami.MessageType
149 */
150 property var status: Kirigami.MessageType.Information
151
152 /**
153 * @brief This property holds the current status message of
154 * the text field.
155 *
156 * If this property is not set, no ::status will be shown.
157 */
158 property string statusMessage: ""
159
160 /**
161 * @This signal is emitted when the Return or Enter key is pressed.
162 *
163 * Note that if there is a validator or inputMask set on the text input,
164 * the signal will only be emitted if the input is in an acceptable
165 * state.
166 */
167 signal accepted();
169 /**
170 * @brief This signal is emitted when the Return or Enter key is pressed
171 * or the text input loses focus.
172 *
173 * Note that if there is a validator or inputMask set on the text input
174 * and enter/return is pressed, this signal will only be emitted if
175 * the input follows the inputMask and the validator returns an
176 * acceptable state.
177 */
178 signal editingFinished();
179
180 /**
181 * @brief This signal is emitted whenever the text is edited.
183 * Unlike textChanged(), this signal is not emitted when the text
184 * is changed programmatically, for example, by changing the
185 * value of the text property or by calling ::clear().
186 */
187 signal textEdited();
188
189 /**
190 * @brief Clears the contents of the text input and resets partial
191 * text input from an input method.
192 */
193 function clear(): void {
194 textField.clear();
195 }
196
197 /**
198 * Inserts text into the TextInput at position.
199 */
200 function insert(position: int, text: string): void {
201 textField.insert(position, text);
202 }
203
204 /**
205 * Causes all text to be selected.
206 * @since Kirigami Addons 1.4.0
207 */
208 function selectAll(): void {
209 textField.selectAll();
210 }
211
212 /**
213 * Causes the text from start to end to be selected.
214 * @since Kirigami Addons 1.4.0
215 */
216 function select(start: int, end: int): void {
217 textField.select(start, end);
218 }
219
220 onActiveFocusChanged: { // propagate focus to the text field
221 if (activeFocus) {
222 textField.forceActiveFocus();
223 }
224 }
225
226 onClicked: textField.forceActiveFocus()
227 background: null
228 Accessible.role: Accessible.EditableText
229
230 contentItem: ColumnLayout {
231 spacing: Private.FormCardUnits.verticalSpacing
232 RowLayout {
233 spacing: Private.FormCardUnits.horizontalSpacing
234
235 Layout.fillWidth: true
236
237 Label {
238 Layout.fillWidth: true
239 text: label
240 elide: Text.ElideRight
241 color: root.enabled ? Kirigami.Theme.textColor : Kirigami.Theme.disabledTextColor
242 wrapMode: Text.Wrap
243 maximumLineCount: 2
244 Accessible.ignored: true
245 }
246 Label {
247 TextMetrics {
248 id: metrics
249 text: label(root.maximumLength, root.maximumLength)
250 font: Kirigami.Theme.smallFont
251
252 function label(current: int, maximum: int): string {
253 return i18ndc("kirigami-addons6", "@label %1 is current text length, %2 is maximum length of text field", "%1/%2", current, maximum)
254 }
255 }
256 // 32767 is the default value for TextField.maximumLength
257 visible: root.maximumLength < 32767
258 text: metrics.label(textField.text.length, root.maximumLength)
259 font: Kirigami.Theme.smallFont
260 color: textField.text.length === root.maximumLength
261 ? Kirigami.Theme.neutralTextColor
262 : Kirigami.Theme.textColor
263 horizontalAlignment: Text.AlignRight
264
265 Accessible.ignored: !visible
266
267 Layout.preferredWidth: metrics.advanceWidth
268 }
269 }
270 TextField {
271 id: textField
272 Accessible.name: root.label
273 Layout.fillWidth: true
274 placeholderText: root.placeholderText
275 text: root.text
276 onTextChanged: root.text = text
277 onAccepted: root.accepted()
278 onEditingFinished: root.editingFinished()
279 onTextEdited: root.textEdited()
280 activeFocusOnTab: false
281 }
282
283 Kirigami.InlineMessage {
284 id: formErrorHandler
285 visible: root.statusMessage.length > 0
286 Layout.topMargin: visible ? Kirigami.Units.smallSpacing : 0
287 Layout.fillWidth: true
288 text: root.statusMessage
289 type: root.status
290 }
291 }
292}
293
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:03:50 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.