Kirigami-addons

FormTextAreaDelegate.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
12/**
13 * @brief A Form delegate that corresponds to a text area.
14 *
15 * ```qml
16 *
17 * FormCard.FormHeader {
18 * title: "Information"
19 * }
20 *
21 * FormCard.FormCard {
22 * FormCard.FormTextAreaDelegate {
23 * label: "Account name"
24 * }
25 * }
26 * ```
27 *
28 * @since KirigamiAddons 0.11.0
29 *
30 * @inherit AbstractFormDelegate
31 */
32AbstractFormDelegate {
33 id: root
34
35 /**
36 * @brief A label containing primary text that appears above and
37 * to the left the text field.
38 */
39 required property string label
40
41 /**
42 * @brief set the maximum length of the text inside the TextArea if maxLength > 0
43 */
44 property int maximumLength: -1
45
46 /**
47 * @brief This hold the activeFocus state of the internal TextArea.
48 */
49 property alias fieldActiveFocus: textArea.activeFocus
50
51 /**
52 * @brief This hold the `readOnly` state of the internal TextArea.
53 */
54 property alias readOnly: textArea.readOnly
55
56 /**
57 * @brief This property holds the `inputMethodHints` of the
58 * internal TextArea.
59 *
60 * This consists of hints on the expected content or behavior of
61 * the text field, be it sensitive data, in a date format, or whether
62 * the characters will be hidden, for example.
63 *
64 * @see <a href="https://doc.qt.io/qt-6/qml-qtquick-textinput.html#inputMethodHints-prop">TextInput.inputMethodHints</a>
65 */
66 property alias inputMethodHints: textArea.inputMethodHints
67
68 /**
69 * @brief This property holds the `placeholderText` of the
70 * internal TextArea.
71 *
72 * This consists of secondary text shown by default on the text field
73 * if no text has been written in it.
74 */
75 property alias placeholderText: textArea.placeholderText
76
77 /**
78 * @brief This property holds the current status message type of
79 * the text field.
80 *
81 * This consists of an inline message with a colorful background
82 * and an appropriate icon.
83 *
84 * The status property will affect the color of ::statusMessage used.
85 *
86 * Accepted values:
87 * - `Kirigami.MessageType.Information` (blue color)
88 * - `Kirigami.MessageType.Positive` (green color)
89 * - `Kirigami.MessageType.Warning` (orange color)
90 * - `Kirigami.MessageType.Error` (red color)
91 *
92 * default: `Kirigami.MessageType.Information` if ::statusMessage is set,
93 * nothing otherwise.
94 *
95 * @see Kirigami.MessageType
96 */
97 property var status: Kirigami.MessageType.Information
98
99 /**
100 * @brief This property holds the current status message of
101 * the text field.
102 *
103 * If this property is not set, no ::status will be shown.
104 */
105 property string statusMessage: ""
106
107 /**
108 * @brief This signal is emitted when the Return or Enter key is pressed
109 * or the text input loses focus.
110 *
111 * Note that if there is a validator or inputMask set on the text input
112 * and enter/return is pressed, this signal will only be emitted if
113 * the input follows the inputMask and the validator returns an
114 * acceptable state.
115 */
116 signal editingFinished();
117
118 /**
119 * @brief Clears the contents of the text input and resets partial
120 * text input from an input method.
121 */
122 function clear() {
123 textArea.clear();
124 }
125
126 /**
127 * Inserts text into the TextInput at position.
128 */
129 function insert(position: int, text: string): void {
130 textArea.insert(position, text);
131 }
132
133 onActiveFocusChanged: { // propagate focus to the text field
134 if (activeFocus) {
135 textArea.forceActiveFocus();
136 }
137 }
138
139 onClicked: textArea.forceActiveFocus()
140 background: null
141 Accessible.role: Accessible.EditableText
142
143 contentItem: ColumnLayout {
144 spacing: Kirigami.Units.smallSpacing
145
146 RowLayout {
147 spacing: Kirigami.Units.largeSpacing
148
149 Label {
150 text: label
151 elide: Text.ElideRight
152 color: root.enabled ? Kirigami.Theme.textColor : Kirigami.Theme.disabledTextColor
153 wrapMode: Text.Wrap
154 maximumLineCount: 2
155
156 Accessible.ignored: true
157 Layout.fillWidth: true
158 }
159
160 Label {
161 TextMetrics {
162 id: metrics
163
164 text: label(root.maximumLength, root.maximumLength)
165 font: Kirigami.Theme.smallFont
166
167 function label(current: int, maximum: int): string {
168 return i18nc("@label %1 is current text length, %2 is maximum length of text field", "%1/%2", current, maximum)
169 }
170 }
171 visible:root.maximumLength != -1
172 text: metrics.label(textArea.text.length, root.maximumLength)
173 font: Kirigami.Theme.smallFont
174 color: textArea.text.length === root.maximumLength
175 ? Kirigami.Theme.neutralTextColor
176 : Kirigami.Theme.textColor
177 horizontalAlignment: Text.AlignRight
178
179 Layout.margins: Kirigami.Units.smallSpacing
180 Layout.preferredWidth: metrics.advanceWidth
181 }
182 }
183
184 TextArea {
185 id: textArea
186
187 placeholderText: root.placeholderText
188 text: root.text
189 onTextChanged: root.text = text
190 onEditingFinished: root.editingFinished()
191 activeFocusOnTab: false
192 wrapMode: TextEdit.Wrap
193
194 Accessible.name: root.label
195 Layout.fillWidth: true
196 }
197
198 Kirigami.InlineMessage {
199 id: formErrorHandler
200
201 visible: root.statusMessage.length > 0
202 text: root.statusMessage
203 type: root.status
204
205 Layout.topMargin: visible ? Kirigami.Units.smallSpacing : 0
206 Layout.fillWidth: true
207 }
208 }
209}
210
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:05:53 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.