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
|
.. _ZLabel:
ZLabel
======
.. rst-class:: tw-flex-imgs
* .. figure:: tpi/label.tpi
Checkbox with text "CheckBox"
* .. figure:: tpi/label-focus.tpi
reflecting focus of "buddy" widget
* .. figure:: tpi/label-disabled.tpi
in disabled state
* .. figure:: tpi/label-color.tpi
with custom palette
* .. figure:: tpi/label-buddy.tpi
with "buddy" input box
Labels display user interface text in a dialog.
They are often used to label other widgets and if setup with a "buddy" widget also serve to show focus for that widget.
For example :cpp:class:`Tui::ZInputBox` and :cpp:class:`Tui::ZListView` do not display focus indication themselves and can be
augmented with a label to show focus.
In contract to a label the :cpp:class:`Tui::ZTextLine` does not reserve a cell as focus indicator and doesn't have
support for a "buddy" widget or showing a keyboard shortcut.
See also: :cpp:class:`Tui::ZTextLine`
Example
-------
.. literalinclude:: examples/widgets/label.cpp
:start-after: // snippet-start
:end-before: // snippet-end
:dedent:
Keyboard Usage
--------------
.. list-table::
:class: noborder
:align: left
:header-rows: 1
* - Key
- Result
* - :kbd:`Alt` + (setup mnemonic)
- Focus the label's "buddy" widget.
Behavior
--------
Labels by default don't accept focus, are one cell high and have a preferred vertical layout policy.
The size request of a label is the length of the text plus 1 cells plus the contents margins.
The effective enabled/disabled status for its visual appearance is the logical-AND combination of both its own status and
the "buddy" widget's status (if a buddy is set).
For its visual appearance the relevant focus status is that of its "buddy" widget, if there is no "buddy" widget, the
label will always appear as unfocused.
The shortcut from the label's markup is used to focus the "buddy" widget.
Palette
-------
.. list-table::
:class: noborder
:align: left
:header-rows: 1
* - Palette Color
- Usage
* - ``control.fg``, ``control.bg``
- Body of the |control| (active, **unfocused**)
* - ``control.focused.fg``, ``control.focused.bg``
- Body of the |control| (active, **focused**)
* - ``control.disabled.fg``, ``control.disabled.bg``
- Body of the |control| (**disabled**)
* - ``control.shortcut.fg``, ``control.shortcut.bg``
- Shortcut character in |control| text.
ZLabel
------
.. cpp:class:: Tui::ZLabel : public Tui::ZWidget
A label widget.
**Constructors**
.. cpp:function:: ZLabel(const QString &text, Tui::ZWidget *parent = nullptr)
.. cpp:function:: ZLabel(WithMarkupTag, const QString &markup, Tui::ZWidget *parent = nullptr)
Create the |control| with the given ``text`` or ``markup``.
**Functions**
.. cpp:function:: QString text() const
.. cpp:function:: void setText(const QString &text)
Get or set the plain text content of the |control|.
When set the shortcut is also reset.
When the content of the |control| was most recently set using :cpp:func:`setMarkup` the returned text is empty.
.. cpp:function:: QString markup() const
.. cpp:function:: void setMarkup(const QString &markup)
Get or set the text content of the |control| using markup.
When set the shortcut is also reset, if the markup contains a mnemonic it is setup as new shortcut.
When the content of the |control| was most recently set using :cpp:func:`setText` the returned markup is empty.
.. cpp:function:: Tui::ZWidget *buddy() const
.. cpp:function:: void setBuddy(Tui::ZWidget *buddy)
The "buddy" of a label is a related widget for which the label displays the focus and which inputting the
shortcut of the label will focus.
.. |control| replace:: label
|
