label.rst 10 KB
Newer Older
1
2
3
Labels
======

4
.. image:: images/label.png
5
6
7
8
9
10
11
12
13
14
15
16
17
18

``GtkLabel`` displays limited amounts of text.

Labels can contain plain text or `markup text
<https://docs.gtk.org/Pango/pango_markup.html#pango-markup>`__.

The text rendering is controlled by `Pango attributes
<https://docs.gtk.org/Pango/struct.Attribute.html>`__.

.. tabs::

   .. code-tab:: c

      // A plain text label
Emmanuele Bassi's avatar
Emmanuele Bassi committed
19
      GtkWidget *label = gtk_label_new ("Hello GNOME!");
20
21

      // A markup label
Emmanuele Bassi's avatar
Emmanuele Bassi committed
22
      GtkWidget *label = gtk_label_new ("<small>Hello</small> <b>GNOME</b>!");
23
24
25
26
27
28
29
30
31
32
33
      gtk_label_set_use_markup (GTK_LABEL (label), TRUE);


   .. code-tab:: python

      # A plain text label
      label = Gtk.Label(text="Hello GNOME!")

      # A markup label
      label = Gtk.Label(markup="<small>Hello</small> <b>GNOME</b>!")

Lorenz Wildberg's avatar
Lorenz Wildberg committed
34
35
36
37
38
39
40
41
42
43
   .. code-tab:: vala

      // A plain text label
      var label = new Gtk.Label ("Hello GNOME!");

      // A Label that uses markup
      var markup_label = new Gtk.Label ("<small>Hello</small> <b>GNOME</b>!") {
         use_markup = true
      };

Sonny Piers's avatar
Sonny Piers committed
44
45
46
47
48
49
50
51
52
53
54
   .. code-tab:: js

      // A plain text label
      const label = new Gtk.Label({ label: "Hello GNOME!" });

      // A Label that uses markup
      const markup_label = new Gtk.Label({
        label: "<small>Hello</small> <b>GNOME</b>!",
        use_markup: true,
      });

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

Wrapping labels
---------------

Two properties control the wrapping of the labels text:

- ``GtkLabel:wrap-mode``: Controls whether to wrap only at word boundaries, or
  anywhere
- ``GtkLabel:wrap``: If set, wrap lines if the text becomes too wide

One normally only sets the ``wrap`` property. It is safe to leave the
``wrap-mode`` property at its default value, `Pango.WrapMode.WORD
<https://docs.gtk.org/Pango/enum.WrapMode.html>`__.

When wrapping is enabled, the same label can appear with multiple different
height/width combinations. How far the label actually wraps depends on the
context in which it is used, and on the geometry management of its parent
container. There are two properties that allow you to influence the amount of
wrapping:

- ``GtkLabel::width-chars``: Specifies the minimum width of a wrapping label
- ``GtkLabel::max-width-chars``: Specified the natural width of a wrapping label

Note that both of these properties are using characters as unit. They are
converted to pixels using the average character width of the current font.

Ellipsized labels
-----------------

Sometimes, it is convenient to only show as much of text as fits, and indicate
that there is more by using an ellipsis (…). ``GtkLabel`` supports this with
this property:

- ``GtkLabel:ellipsize``: The preferred place to ellipsize the string

Setting it to a value other than the default ``PANGO_ELLIPSIZE_NONE`` enables
ellipsization. For the usual ellipsization at the end, use
``PANGO_ELLIPSIZE_END``.

To control how much of the label can be ellipsized away, use the
``GtkLabel:width-chars`` property:

.. tabs::

   .. code-tab:: c

Emmanuele Bassi's avatar
Emmanuele Bassi committed
101
102
      GtkWidget *label =
        gtk_label_new ("This is a long text that might need to get ellipsized");
103
104
105
106
107
108
109
110
111
      gtk_label_set_ellipsize (GTK_LABEL (label), PANGO_ELLIPSIZE_END);
      gtk_label_set_width_chars (GTK_LABEL (label), 15);

   .. code-tab:: python

      label = Gtk.Label(text="This is a long text that might need to get ellipsized")
      label.props.ellipsize = Pango.EllipsizeMode.END
      label.props.width_chars = 15

Lorenz Wildberg's avatar
Lorenz Wildberg committed
112
113
114
115
116
117
118
119
   .. code-tab:: vala

      var label = new Gtk.Label ("This is a long text that" +
                                 "might need to get ellipsized") {
                                     ellipsize = Pango.EllipsizeMode.END,
                                     width_chars = 15
                                 };

Sonny Piers's avatar
Sonny Piers committed
120
121
122
123
124
125
126
127
   .. code-tab:: js

      const label = new Gtk.Label({
        label: "This is a long text that" + "might need to get ellipsized",
        ellipsize: Pango.EllipsizeMode.END,
        width_chars: 15,
      });

128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

.. note::

   The width-chars property is based on the average character with of the font,
   and thus the remaining text may not exactly be the number of characters you
   specified.

You can also use the ``GtkLabel:max-width-chars`` property to limit the natural
size requested by the label widget.

Fixed number of lines
---------------------

Sometimes it is necessary to keep text to a certain number of lines. One
approach is to turn off automatic wrapping and rely on inserting line breaks in
the text manually:

.. tabs::

Emmanuele Bassi's avatar
Emmanuele Bassi committed
147
148
149
150
151
   .. code-tab:: c

      GtkWidget *label =
        gtk_label_new ("This is a long text\nthat might need\nto be wrapped");

152
153
154
155
   .. code-tab:: python

      label = Gtk.Label(text="This is a long text\nthat might need\nto be wrapped")

Lorenz Wildberg's avatar
Lorenz Wildberg committed
156
157
158
159
160
   .. code-tab:: vala

      var label = new Gtk.Label ("This is a long text\n"+
                                 "that might need\nto be wrapped");

Sonny Piers's avatar
Sonny Piers committed
161
162
163
164
165
166
   .. code-tab:: js

      const label = new Gtk.Label({
        label: "This is a long text\n" + "that might need\nto be wrapped",
      });

167
168
169
170
171
172
173
174
175
176
177
178
179

This can be problematic because you have to balance line length yourself, and
translators may inadvertently change the number of lines by removing or adding
line breaks in their translations; also, text with fixed breaks is ellipsized in
each line, which may look unexpected.

A better alternative is to go back to automatic wrapping, and tell the label how
many lines of text you want, using the ``set_lines()`` method:

.. tabs::

   .. code-tab:: c

Emmanuele Bassi's avatar
Emmanuele Bassi committed
180
181
      GtkWidget *label =
        gtk_label_new ("This is a long text that might need to be wrapped");
182
183
184
185
186
187
188
189
190
191
192
193
      gtk_label_set_wrap (GTK_LABEL (label), TRUE);
      gtk_label_set_ellipsize (GTK_LABEL (label), PANGO_ELLIPSIZE_END);
      gtk_label_set_lines (GTK_LABEL (label), 3);


   .. code-tab:: python

      label = Gtk.Label(text="This is a long text that might need to be wrapped")
      label.props.wrap = True
      label.props.ellipsize = Pango.EllipsizeMode.END
      label.props.lines = 3

Lorenz Wildberg's avatar
Lorenz Wildberg committed
194
195
196
197
198
199
200
   .. code-tab:: vala

      var label = new Gtk.Label ("This is a long text that might need to be wrapped");
      label.wrap = true;
      label.ellipsize = Pango.EllipsizeMode.END;
      label.lines = 3;

Sonny Piers's avatar
Sonny Piers committed
201
202
203
204
205
206
207
208
209
   .. code-tab:: js

      const label = new Gtk.Label({
        label: "This is a long text that might need to be wrapped",
        wrap: true,
        ellipsize: Pango.EllipsizeMode.END,
        lines: 3,
      });

210
211
212
213
214
215
216
217
218
219
220
221
222
223

With this configuration, ``GtkLabel`` will automatically wrap lines to the right
width and only ellipsize the last one, if needed.

Mnemonics
---------

Labels can be used to describe other widgets, for instance:

.. tabs::

   .. code-tab:: c

      // Add a switch to enable a feature
Emmanuele Bassi's avatar
Emmanuele Bassi committed
224
225
226
      GtkWidget *box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 12);
      GtkWidget *sw = gtk_switch_new ();
      GtkWidget *label = gtk_label_new ("Enable feature");
227
228
229
230
231
232
233
234
235
236
237
238
      gtk_box_append (GTK_BOX (box), label);
      gtk_box_append (GTK_BOX (box), sw);

   .. code-tab:: python

      # Add a switch to enable a feature
      box = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=12)
      switch = Gtk.Switch()
      label = Gtk.Label(text="Enable feature")
      box.append(label)
      box.append(switch)

Lorenz Wildberg's avatar
Lorenz Wildberg committed
239
240
241
242
243
244
245
246
   .. code-tab:: vala

      var box = new Gtk.Box (Gtk.Orientation.HORIZONTAL, 12);
      var switch = new Gtk.Switch ();
      var label = new Gtk.Label ("Enable feature");
      box.append (label);
      box.append (switch);

Sonny Piers's avatar
Sonny Piers committed
247
248
249
250
251
252
253
254
255
256
257
258
259
   .. code-tab:: js

      const box = new Gtk.Box({
        orientation: Gtk.Orientation.HORIZONTAL,
        spacing: 12,
      });
      const sw = new Gtk.Switch();
      const label = new Gtk.Label({
        label: "Enable feature",
      });
      box.append(label);
      box.append(sw);

260
261
262
263
264
265
266
267
268
269
270

To simplify keyboard navigation, labels can include "mnemonics": underlined
characters that are used as shortcuts for activating the widget that is
described by the label:

.. tabs::

   .. code-tab:: c
      :emphasize-lines: 4,5,9

      // Add a switch to enable a feature
Emmanuele Bassi's avatar
Emmanuele Bassi committed
271
272
273
      GtkWidget *box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 12);
      GtkWidget *sw = gtk_switch_new ();
      GtkWidget *label = gtk_label_new ("Enable _feature");
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
      gtk_label_set_use_underline (GTK_LABEL (label), TRUE);
      gtk_box_append (GTK_BOX (box), label);
      gtk_box_append (GTK_BOX (box), sw);
      // Bind the switch to the label's mnemonic
      gtk_label_set_mnemonic_widget (GTK_LABEL (label), switch);


   .. code-tab:: python
      :emphasize-lines: 4,8

      # Add a switch to enable a feature
      box = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=12)
      switch = Gtk.Switch()
      label = Gtk.Label(text="Enable _feature", use_underline=True)
      box.append(label)
      box.append(switch)
      # Bind the switch to the label's mnemonic
      label.set_mnemonic_widget(switch)

Lorenz Wildberg's avatar
Lorenz Wildberg committed
293
   .. code-tab:: vala
Sonny Piers's avatar
Sonny Piers committed
294
      :emphasize-lines: 4,5,9
Lorenz Wildberg's avatar
Lorenz Wildberg committed
295
296
297
298
299
300
301
302
303
304
305

      // Add a switch to enable a feature
      var box = new Gtk.Box (Gtk.Orientation.HORIZONTAL, 12);
      var switch = new Gtk.Switch ();
      var label = new Gtk.Label ("Enable _feature");
      label.use_underline = true;
      box.append (label);
      box.append (switch);
      // Bind the switch to the label's mnemonic
      label.mnemonic_widget = switch;

Sonny Piers's avatar
Sonny Piers committed
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
   .. code-tab:: js
      :emphasize-lines: 8,9,15

      // Add a switch to enable a feature
      const box = new Gtk.Box({
        orientation: Gtk.Orientation.HORIZONTAL,
        spacing: 12,
      });
      const sw = new Gtk.Switch();
      const label = new Gtk.Label({
        label: "Enable _feature",
        use_underline: true,
        mnemonic_widget: sw,
      });
      box.append(label);
      box.append(sw);
      // Bind the switch to the label's mnemonic
      label.mnemonic_widget = sw;

325

326
Now, pressing :kbd:`Alt` + :kbd:`F` will toggle the switch.
327
328
329
330
331
332
333

Useful methods for a Label widget
---------------------------------

- ``set_selectable()`` will mark the contents of the label as user selectable;
  the contents of selectable labels can also be copied in the clipboard.

Emmanuele Bassi's avatar
Emmanuele Bassi committed
334
API references
335
336
337
338
339
340
341
--------------

In this sample we used the following:

- `GtkLabel <https://docs.gtk.org/gtk4/class.Label.html>`__
- `GtkSwitch <https://docs.gtk.org/gtk4/class.Switch.html>`__
- `GtkBox <https://docs.gtk.org/gtk4/class.Box.html>`__