1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
.. _ZInputBox:
ZInputBox
=========
.. rst-class:: tw-flex-imgs
* .. figure:: tpi/inputbox.tpi
text input box with text "InputBox"
* .. figure:: tpi/inputbox-focus.tpi
in focused state
* .. figure:: tpi/inputbox-disabled.tpi
in disabled state
* .. figure:: tpi/inputbox-password.tpi
as password input
ZInputBox is a single line text input widget.
If the input text is longer than the width of the widget it supports scrolling the text so the currently edited portion
of the text is visible.
Example
-------
.. literalinclude:: examples/widgets/inputbox.cpp
:start-after: // snippet-start
:end-before: // snippet-end
:dedent:
Keyboard Usage
--------------
.. list-table::
:class: noborder
:align: left
:header-rows: 1
* - Key
- Result
* - (text input)
- Insert text at cursor position.
* - :kbd:`Backspace`
- Remove one letter/character before cursor position.
* - :kbd:`Del`
- Remove one letter/character after cursor position.
* - :kbd:`←`
- Move cursor position one letter/character to the left.
* - :kbd:`→`
- Move cursor position one letter/character to the right.
* - :kbd:`Home`
- Move cursor position to the start of the text.
* - :kbd:`End`
- Move cursor position to the position just after the end of the text.
* - :kbd:`Insert`
- Toggle overwrite mode.
Behavior
--------
Input boxes by default accept focus, are one cell high and have a expanding vertical layout policy.
The size request of a checkbox is fixed at 10 cells width to avoid the layout changing when text is entered.
The user can edit the text by using the keys described in the keyboard usage section.
Additionally the input box accepts text pasted into the terminal and inserts it at the cursor position.
On each change to the text the input box
emits a :cpp:func:`~void Tui::ZInputBox::textChanged(const QString &text)` signal.
When unfocused the text is always scrolled such that the start of the text is visible.
When focused the text is scrolled so that the cursor position is visible.
Newline (``\n``) characters in the text are displayed as in the following example (displaying ``one\ntwo``):
.. image:: tpi/inputbox-newline.tpi
Other non printable characters are displayed using similar visual conventions.
..
TODO link to docs regarding this.
Palette
-------
.. list-table::
:class: noborder
:align: left
:header-rows: 1
* - Palette Color
- Usage
* - ``lineedit.fg``, ``lineedit.bg``
- Body of the |control| (active, **unfocused**)
* - ``lineedit.focused.fg``, ``lineedit.focused.bg``
- Body of the |control| (active, **focused**)
* - ``lineedit.disabled.fg``, ``lineedit.disabled.bg``
- Body of the |control| (**disabled**)
ZInputBox
---------
.. cpp:class:: Tui::ZInputBox : public Tui::ZWidget
A single line text input widget.
**Enums**
.. cpp:enum:: EchoMode
.. cpp:enumerator:: Normal
Display text normally
.. cpp:enumerator:: NoEcho
Do not display any text and show cursor at start of the widget.
This is the classic everything hidden password input.
.. cpp:enumerator:: Password
Display text masked by ``*``.
This is the modern masked password input that leaks passwort length but provides better feedback and editing.
**Constructors**
.. cpp:function:: ZInputBox(const QString &text, Tui::ZWidget *parent=nullptr)
Create the |control| with the given ``text``.
**Functions**
.. cpp:function:: QString text() const
Get the text from the |control|.
.. cpp:function:: void setEchoMode(Tui::ZInputBox::EchoMode echoMode)
.. cpp:function:: Tui::ZInputBox::EchoMode echoMode() const
The ``echoMode`` allows selecting how the input text is displayed.
This allows selecting normal display or password input modes.
.. cpp:function:: void setOverwriteMode(bool overwriteMode)
.. cpp:function:: bool overwriteMode() const
The ``overwriteMode`` allows for user input to overwrite existing text.
If :cpp:expr:`true` user input letters will overwrite the existing letter the cursor is placed on.
Otherwise it will be inserted after the cursor.
.. cpp:function:: int cursorPosition() const
.. cpp:function:: void setCursorPosition(int pos)
The cursor position in code units.
If the cursor position is out of range it will be adjusted to be in the range from 0 to the length of the current
text (in code units).
The cursor position is conceptually between letters/characters (clusters).
If the given cursor position is not at the start of a cluster (or at the end of the text) in text,
it will be adjusted to the preceding valid cursor position.
.. cpp:function:: void insertAtCursorPosition(const QString &text)
Insert the text given in ``text`` at the current cursor position and
emits :cpp:func:`~void Tui::ZInputBox::textChanged(const QString &text)`.
**Signals**
.. cpp:function:: void textChanged(const QString &text)
This signal is emitted when the user changes the text or the text is changed using functions on this widget.
**Slots**
.. cpp:function:: void setText(const QString &text)
If ``text`` differs from the current text:
Replace the text with ``text`` and emits :cpp:func:`~void Tui::ZInputBox::textChanged(const QString &text)`.
Sets cursor position to the end of the text.
.. |control| replace:: input box
|
