1
<!-- ##### SECTION Title ##### -->
4
<!-- ##### SECTION Short_Description ##### -->
5
A widget that displays a small to medium amount of text
7
<!-- ##### SECTION Long_Description ##### -->
9
The #GtkLabel widget displays a small amount of text. As the name
10
implies, most labels are used to label another widget such as a
11
#GtkButton, a #GtkMenuItem, or a #GtkOptionMenu.
15
<title>Mnemonics</title>
18
Labels may contain <firstterm>mnemonics</firstterm>. Mnemonics are
19
underlined characters in the label, used for keyboard navigation.
20
Mnemonics are created by providing a string with an underscore before
21
the mnemonic character, such as <literal>"_File"</literal>, to the
22
functions gtk_label_new_with_mnemonic() or
23
gtk_label_set_text_with_mnemonic().
27
Mnemonics automatically activate any activatable widget the label is
28
inside, such as a #GtkButton; if the label is not inside the
29
mnemonic's target widget, you have to tell the label about the target
30
using gtk_label_set_mnemonic_widget(). Here's a simple example where
31
the label is inside a button:
35
/* Pressing Alt+H will activate this button */
36
button = gtk_button_new (<!-- -->);
37
label = gtk_label_new_with_mnemonic ("_Hello");
38
gtk_container_add (GTK_CONTAINER (button), label);
41
There's a convenience function to create buttons with a mnemonic label
46
/* Pressing Alt+H will activate this button */
47
button = gtk_button_new_with_mnemonic ("_Hello");
51
To create a mnemonic for a widget alongside the label, such as a
52
#GtkEntry, you have to point the label at the entry with
53
gtk_label_set_mnemonic_widget():
56
/* Pressing Alt+H will focus the entry */
57
entry = gtk_entry_new (<!-- -->);
58
label = gtk_label_new_with_mnemonic ("_Hello");
59
gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
68
<title>Markup (styled text)</title>
71
To make it easy to format text in a label (changing colors, fonts,
72
etc.), label text can be provided in a simple <link
73
linkend="PangoMarkupFormat">markup format</link>.
74
Here's how to create a label with a small font:
77
label = gtk_label_new (NULL);
78
gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");
82
linkend="PangoMarkupFormat">complete documentation</link> of available
83
tags in the Pango manual.)
86
The markup passed to gtk_label_set_markup() must be valid; for example,
87
literal </>/& characters must be escaped as &lt;,
88
&gt;, and &amp;. If you pass text obtained from the user, file,
89
or a network to gtk_label_set_markup(), you'll want to escape it with
90
g_markup_escape_text() or g_markup_printf_escaped().
93
Markup strings are just a convenient way to set the #PangoAttrList on
94
a label; gtk_label_set_attributes() may be a simpler way to set
95
attributes in some cases. Be careful though; #PangoAttrList tends to
96
cause internationalization problems, unless you're applying attributes
97
to the entire string (i.e. unless you set the range of each attribute
98
to [0, G_MAXINT)). The reason is that specifying the start_index and
99
end_index for a #PangoAttribute requires knowledge of the exact string
100
being displayed, so translations will cause problems.
105
<title>Selectable labels</title>
108
Labels can be made selectable with gtk_label_set_selectable().
109
Selectable labels allow the user to copy the label contents to
110
the clipboard. Only labels that contain useful-to-copy information
111
— such as error messages — should be made selectable.
116
<title>Text layout</title>
119
A label can contain any number of paragraphs, but will have
120
performance problems if it contains more than a small number.
121
Paragraphs are separated by newlines or other paragraph separators
125
Labels can automatically wrap text if you call
126
gtk_label_set_line_wrap().
129
gtk_label_set_justify() sets how the lines in a label align
130
with one another. If you want to set how the label as a whole
131
aligns in its available space, see gtk_misc_set_alignment().
136
<!-- ##### SECTION See_Also ##### -->
141
<!-- ##### SECTION Stability_Level ##### -->
144
<!-- ##### STRUCT GtkLabel ##### -->
146
This should not be accessed directly. Use the accessor functions as
151
<!-- ##### SIGNAL GtkLabel::copy-clipboard ##### -->
156
@label: the object which received the signal.
158
<!-- ##### SIGNAL GtkLabel::move-cursor ##### -->
163
@label: the object which received the signal.
168
<!-- ##### SIGNAL GtkLabel::populate-popup ##### -->
173
@label: the object which received the signal.
176
<!-- ##### ARG GtkLabel:angle ##### -->
181
<!-- ##### ARG GtkLabel:attributes ##### -->
186
<!-- ##### ARG GtkLabel:cursor-position ##### -->
191
<!-- ##### ARG GtkLabel:ellipsize ##### -->
196
<!-- ##### ARG GtkLabel:justify ##### -->
201
<!-- ##### ARG GtkLabel:label ##### -->
206
<!-- ##### ARG GtkLabel:max-width-chars ##### -->
211
<!-- ##### ARG GtkLabel:mnemonic-keyval ##### -->
216
<!-- ##### ARG GtkLabel:mnemonic-widget ##### -->
221
<!-- ##### ARG GtkLabel:pattern ##### -->
226
<!-- ##### ARG GtkLabel:selectable ##### -->
231
<!-- ##### ARG GtkLabel:selection-bound ##### -->
236
<!-- ##### ARG GtkLabel:single-line-mode ##### -->
241
<!-- ##### ARG GtkLabel:use-markup ##### -->
246
<!-- ##### ARG GtkLabel:use-underline ##### -->
251
<!-- ##### ARG GtkLabel:width-chars ##### -->
256
<!-- ##### ARG GtkLabel:wrap ##### -->
261
<!-- ##### ARG GtkLabel:wrap-mode ##### -->
266
<!-- ##### FUNCTION gtk_label_new ##### -->
275
<!-- ##### FUNCTION gtk_label_set_text ##### -->
284
<!-- ##### FUNCTION gtk_label_set_attributes ##### -->
293
<!-- ##### FUNCTION gtk_label_set_markup ##### -->
302
<!-- ##### FUNCTION gtk_label_set_markup_with_mnemonic ##### -->
311
<!-- ##### FUNCTION gtk_label_set_pattern ##### -->
313
The pattern of underlines you want under the existing text within the
314
#GtkLabel widget. For example if the current text of the label says
315
"FooBarBaz" passing a pattern of "___ ___" will underline
316
"Foo" and "Baz" but not "Bar".
319
@label: The #GtkLabel you want to set the pattern to.
320
@pattern: The pattern as described above.
323
<!-- ##### FUNCTION gtk_label_set_justify ##### -->
332
<!-- ##### FUNCTION gtk_label_set_ellipsize ##### -->
341
<!-- ##### FUNCTION gtk_label_set_width_chars ##### -->
350
<!-- ##### FUNCTION gtk_label_set_max_width_chars ##### -->
359
<!-- ##### FUNCTION gtk_label_get ##### -->
361
Gets the current string of text within the #GtkLabel and writes it to
362
the given @str argument. It does not make a copy of this string so you
363
must not write to it.
366
@label: The #GtkLabel widget you want to get the text from.
367
@str: The reference to the pointer you want to point to the text.
370
<!-- ##### FUNCTION gtk_label_parse_uline ##### -->
372
Parses the given string for underscores and converts the next
373
character to an underlined character. The last character that
374
was underlined will have its lower-cased accelerator keyval returned (i.e.
375
"_File" would return the keyval for "f". This is
376
probably only used within the Gtk+ library itself for menu items and such.
379
@label: The #GtkLabel you want to affect.
380
@string: The string you want to parse for underlines.
381
@Returns: The lowercase keyval of the last character underlined.
384
<!-- ##### FUNCTION gtk_label_set_line_wrap ##### -->
393
<!-- ##### FUNCTION gtk_label_set_line_wrap_mode ##### -->
402
<!-- ##### MACRO gtk_label_set ##### -->
404
Aliases gtk_label_set_text(). Probably used for backward compatibility with
410
<!-- ##### FUNCTION gtk_label_get_layout_offsets ##### -->
420
<!-- ##### FUNCTION gtk_label_get_mnemonic_keyval ##### -->
429
<!-- ##### FUNCTION gtk_label_get_selectable ##### -->
438
<!-- ##### FUNCTION gtk_label_get_text ##### -->
447
<!-- ##### FUNCTION gtk_label_new_with_mnemonic ##### -->
456
<!-- ##### FUNCTION gtk_label_select_region ##### -->
466
<!-- ##### FUNCTION gtk_label_set_mnemonic_widget ##### -->
475
<!-- ##### FUNCTION gtk_label_set_selectable ##### -->
484
<!-- ##### FUNCTION gtk_label_set_text_with_mnemonic ##### -->
493
<!-- ##### FUNCTION gtk_label_get_attributes ##### -->
502
<!-- ##### FUNCTION gtk_label_get_justify ##### -->
511
<!-- ##### FUNCTION gtk_label_get_ellipsize ##### -->
520
<!-- ##### FUNCTION gtk_label_get_width_chars ##### -->
529
<!-- ##### FUNCTION gtk_label_get_max_width_chars ##### -->
538
<!-- ##### FUNCTION gtk_label_get_label ##### -->
547
<!-- ##### FUNCTION gtk_label_get_layout ##### -->
556
<!-- ##### FUNCTION gtk_label_get_line_wrap ##### -->
565
<!-- ##### FUNCTION gtk_label_get_line_wrap_mode ##### -->
574
<!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### -->
583
<!-- ##### FUNCTION gtk_label_get_selection_bounds ##### -->
594
<!-- ##### FUNCTION gtk_label_get_use_markup ##### -->
603
<!-- ##### FUNCTION gtk_label_get_use_underline ##### -->
612
<!-- ##### FUNCTION gtk_label_get_single_line_mode ##### -->
621
<!-- ##### FUNCTION gtk_label_get_angle ##### -->
630
<!-- ##### FUNCTION gtk_label_set_label ##### -->
639
<!-- ##### FUNCTION gtk_label_set_use_markup ##### -->
648
<!-- ##### FUNCTION gtk_label_set_use_underline ##### -->
657
<!-- ##### FUNCTION gtk_label_set_single_line_mode ##### -->
666
<!-- ##### FUNCTION gtk_label_set_angle ##### -->