GtkLabel
********

A widget that displays a small to medium amount of text

Overview
========

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

Mnemonics
=========

Labels may contain 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 "_File", to the functions gtk-label-new-with-mnemonic or gtk-label-set-text-with-mnemonic.

Mnemonics automatically activate any activatable widget the label is inside, such as a <gtk-button>; if the label is not inside the mnemonic's target widget, you have to tell the label about the target using 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 <gtk-entry>, you have to point the label at the entry with gtk-label-set-mnemonic-widget:

       /* 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);

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

       /* 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);

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.)

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

The markup passed to 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 gtk-label-set-markup, you'll want to escape it with g-markup-escape-text or g-markup-printf-escaped.

Markup strings are just a convenient way to set the <pango-attr-list> on a label; gtk-label-set-attributes may be a simpler way to set attributes in some cases. Be careful though; <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 <pango-attribute> requires knowledge of the exact string being displayed, so translations will cause problems.

Selectable labels
=================

Labels can be made selectable with 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.

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 gtk-label-set-line-wrap.

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 gtk-misc-set-alignment.

Usage
=====

     [file defuns-gtklabel.xml.texi not included]