
@c %start of fragment

@node GtkLabel
@chapter GtkLabel
A widget that displays a small to medium amount of text

@section Overview
The @code{<gtk-label>} widget displays a small amount of text. As the name
implies, most labels are used to label another widget such as a
@code{<gtk-button>}, a @code{<gtk-menu-item>}, or a @code{<gtk-option-menu>}.

@section Mnemonics
Labels may contain @dfn{mnemonics}. Mnemonics are underlined characters in the
label, used for keyboard navigation. Mnemonics are created by providing a string
with an underscore before the mnemonic character, such as @samp{"_File"}, to the
functions @code{gtk-label-new-with-mnemonic} or
@code{gtk-label-set-text-with-mnemonic}.

Mnemonics automatically activate any activatable widget the label is inside,
such as a @code{<gtk-button>}; if the label is not inside the mnemonic's target
widget, you have to tell the label about the target using
@code{gtk-label-set-mnemonic-widget}. Here's a simple example where the label is
inside a button: There's a convenience function to create buttons with a
mnemonic label already inside: To create a mnemonic for a widget alongside the
label, such as a @code{<gtk-entry>}, you have to point the label at the entry
with @code{gtk-label-set-mnemonic-widget}:

@example 

  /* Pressing Alt+H will activate this button */
  button = gtk_button_new ();
  label = gtk_label_new_with_mnemonic ("_Hello");
  gtk_container_add (GTK_CONTAINER (button), label);
@end example

@example 

  /* Pressing Alt+H will activate this button */
  button = gtk_button_new_with_mnemonic ("_Hello");
@end example

@example 

  /* Pressing Alt+H will focus the entry */
  entry = gtk_entry_new ();
  label = gtk_label_new_with_mnemonic ("_Hello");
  gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
@end example

@section Markup (styled text)
To make it easy to format text in a label (changing colors, fonts, etc.), label
text can be provided in a simple markup format. Here's how to create a label
with a small font: (See complete documentation of available tags in the Pango
manual.)

@example 

  label = gtk_label_new (NULL);
  gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");
@end example

The markup passed to @code{gtk-label-set-markup} must be valid; for example,
literal </>/& characters must be escaped as &lt;, &gt;, and &amp;. If you pass
text obtained from the user, file, or a network to @code{gtk-label-set-markup},
you'll want to escape it with @code{g-markup-escape-text} or
@code{g-markup-printf-escaped}.

Markup strings are just a convenient way to set the @code{<pango-attr-list>} on
a label; @code{gtk-label-set-attributes} may be a simpler way to set attributes
in some cases. Be careful though; @code{<pango-attr-list>} tends to cause
internationalization problems, unless you're applying attributes to the entire
string (i.e. unless you set the range of each attribute to [0, G_MAXINT)). The
reason is that specifying the start_index and end_index for a
@code{<pango-attribute>} requires knowledge of the exact string being displayed,
so translations will cause problems.

@section Selectable labels
Labels can be made selectable with @code{gtk-label-set-selectable}. Selectable
labels allow the user to copy the label contents to the clipboard. Only labels
that contain useful-to-copy information &#x2014; such as error messages &#x2014;
should be made selectable.

@section Text layout
A label can contain any number of paragraphs, but will have performance problems
if it contains more than a small number. Paragraphs are separated by newlines or
other paragraph separators understood by Pango.

Labels can automatically wrap text if you call @code{gtk-label-set-line-wrap}.

@code{gtk-label-set-justify} sets how the lines in a label align with one
another. If you want to set how the label as a whole aligns in its available
space, see @code{gtk-misc-set-alignment}.

@section Usage
@include defuns-gtklabel.xml.texi

@c %end of fragment
