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 <!-- ##### STRUCT GtkLabel ##### -->
143 This should not be accessed directly. Use the accessor functions as
148 <!-- ##### SIGNAL GtkLabel::copy-clipboard ##### -->
153 @label: the object which received the signal.
155 <!-- ##### SIGNAL GtkLabel::move-cursor ##### -->
160 @label: the object which received the signal.
165 <!-- ##### SIGNAL GtkLabel::populate-popup ##### -->
170 @label: the object which received the signal.
173 <!-- ##### ARG GtkLabel:attributes ##### -->
178 <!-- ##### ARG GtkLabel:cursor-position ##### -->
183 <!-- ##### ARG GtkLabel:ellipsize ##### -->
188 <!-- ##### ARG GtkLabel:justify ##### -->
193 <!-- ##### ARG GtkLabel:label ##### -->
198 <!-- ##### ARG GtkLabel:mnemonic-keyval ##### -->
203 <!-- ##### ARG GtkLabel:mnemonic-widget ##### -->
208 <!-- ##### ARG GtkLabel:pattern ##### -->
213 <!-- ##### ARG GtkLabel:selectable ##### -->
218 <!-- ##### ARG GtkLabel:selection-bound ##### -->
223 <!-- ##### ARG GtkLabel:use-markup ##### -->
228 <!-- ##### ARG GtkLabel:use-underline ##### -->
233 <!-- ##### ARG GtkLabel:wrap ##### -->
238 <!-- ##### FUNCTION gtk_label_new ##### -->
247 <!-- ##### FUNCTION gtk_label_set_text ##### -->
256 <!-- ##### FUNCTION gtk_label_set_attributes ##### -->
265 <!-- ##### FUNCTION gtk_label_set_markup ##### -->
274 <!-- ##### FUNCTION gtk_label_set_markup_with_mnemonic ##### -->
283 <!-- ##### FUNCTION gtk_label_set_pattern ##### -->
285 The pattern of underlines you want under the existing text within the
286 #GtkLabel widget. For example if the current text of the label says
287 "FooBarBaz" passing a pattern of "___ ___" will underline
288 "Foo" and "Baz" but not "Bar".
291 @label: The #GtkLabel you want to set the pattern to.
292 @pattern: The pattern as described above.
295 <!-- ##### FUNCTION gtk_label_set_justify ##### -->
304 <!-- ##### FUNCTION gtk_label_set_ellipsize ##### -->
313 <!-- ##### FUNCTION gtk_label_get ##### -->
315 Gets the current string of text within the #GtkLabel and writes it to
316 the given @str argument. It does not make a copy of this string so you
317 must not write to it.
320 @label: The #GtkLabel widget you want to get the text from.
321 @str: The reference to the pointer you want to point to the text.
324 <!-- ##### FUNCTION gtk_label_parse_uline ##### -->
326 Parses the given string for underscores and converts the next
327 character to an underlined character. The last character that
328 was underlined will have its lower-cased accelerator keyval returned (i.e.
329 "_File" would return the keyval for "f". This is
330 probably only used within the Gtk+ library itself for menu items and such.
333 @label: The #GtkLabel you want to affect.
334 @string: The string you want to parse for underlines.
335 @Returns: The lowercase keyval of the last character underlined.
338 <!-- ##### FUNCTION gtk_label_set_line_wrap ##### -->
347 <!-- ##### MACRO gtk_label_set ##### -->
349 Aliases gtk_label_set_text(). Probably used for backward compatibility with
355 <!-- ##### FUNCTION gtk_label_get_layout_offsets ##### -->
365 <!-- ##### FUNCTION gtk_label_get_mnemonic_keyval ##### -->
374 <!-- ##### FUNCTION gtk_label_get_selectable ##### -->
383 <!-- ##### FUNCTION gtk_label_get_text ##### -->
392 <!-- ##### FUNCTION gtk_label_new_with_mnemonic ##### -->
401 <!-- ##### FUNCTION gtk_label_select_region ##### -->
411 <!-- ##### FUNCTION gtk_label_set_mnemonic_widget ##### -->
420 <!-- ##### FUNCTION gtk_label_set_selectable ##### -->
429 <!-- ##### FUNCTION gtk_label_set_text_with_mnemonic ##### -->
438 <!-- ##### FUNCTION gtk_label_get_attributes ##### -->
447 <!-- ##### FUNCTION gtk_label_get_justify ##### -->
456 <!-- ##### FUNCTION gtk_label_get_ellipsize ##### -->
465 <!-- ##### FUNCTION gtk_label_get_label ##### -->
474 <!-- ##### FUNCTION gtk_label_get_layout ##### -->
483 <!-- ##### FUNCTION gtk_label_get_line_wrap ##### -->
492 <!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### -->
501 <!-- ##### FUNCTION gtk_label_get_selection_bounds ##### -->
512 <!-- ##### FUNCTION gtk_label_get_use_markup ##### -->
521 <!-- ##### FUNCTION gtk_label_get_use_underline ##### -->
530 <!-- ##### FUNCTION gtk_label_set_label ##### -->
539 <!-- ##### FUNCTION gtk_label_set_use_markup ##### -->
548 <!-- ##### FUNCTION gtk_label_set_use_underline ##### -->