gtk2/docs/reference/gtk/tmpl/gtklabel.sgml

696 lines
12 KiB
Plaintext
Raw Normal View History

1999-08-16 18:51:52 +00:00
<!-- ##### SECTION Title ##### -->
GtkLabel
<!-- ##### SECTION Short_Description ##### -->
A widget that displays a small to medium amount of text
1999-08-16 18:51:52 +00:00
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkLabel widget displays a small amount of text. As the name
implies, most labels are used to label another widget such as a
#GtkButton, a #GtkMenuItem, or a #GtkOptionMenu.
1999-08-16 18:51:52 +00:00
</para>
<refsect2 id="GtkLabel-BUILDER-UI">
<title>GtkLabel as GtkBuildable</title>
<para>
The GtkLabel implementation of the GtkBuildable interface supports a
custom &lt;attributes&gt; element, which supports any number of &lt;attribute&gt;
elements. the &lt;attribute&gt; element has attributes named name, value,
start and end and allows you to specify #PangoAttributs for this label.
</para>
<example>
<title>A UI definition fragment specifying pango attributes</title>
<programlisting><![CDATA[
<object class="GtkLabel">
<attributes>
<attribute name=\"weight\" value=\"PANGO_WEIGHT_BOLD\"/>
</attributes>
</object>
]]></programlisting>
</example>
</refsect2>
<refsect2>
<title>Mnemonics</title>
<para>
Labels may contain <firstterm>mnemonics</firstterm>. 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 <literal>"_File"</literal>, to the
functions gtk_label_new_with_mnemonic() or
gtk_label_set_text_with_mnemonic().
</para>
<para>
Mnemonics automatically activate any activatable widget the label is
inside, such as a #GtkButton; 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:
<informalexample>
<programlisting>
/* 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);
</programlisting>
</informalexample>
There's a convenience function to create buttons with a mnemonic label
already inside:
<informalexample>
<programlisting>
/* Pressing Alt+H will activate this button */
button = gtk_button_new_with_mnemonic ("_Hello");
</programlisting>
</informalexample>
To create a mnemonic for a widget alongside the label, such as a
#GtkEntry, you have to point the label at the entry with
gtk_label_set_mnemonic_widget():
<informalexample>
<programlisting>
/* 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);
</programlisting>
</informalexample>
</para>
</refsect2>
<refsect2>
<title>Markup (styled text)</title>
<para>
To make it easy to format text in a label (changing colors, fonts,
etc.), label text can be provided in a simple <link
linkend="PangoMarkupFormat">markup format</link>.
Here's how to create a label with a small font:
<informalexample>
<programlisting>
label = gtk_label_new (NULL);
gtk_label_set_markup (GTK_LABEL (label), "&lt;small&gt;Small text&lt;/small&gt;");
</programlisting>
</informalexample>
(See <link
linkend="PangoMarkupFormat">complete documentation</link> of available
tags in the Pango manual.)
</para>
<para>
The markup passed to gtk_label_set_markup() must be valid; for example,
literal &lt;/&gt;/&amp; characters must be escaped as &amp;lt;,
&amp;gt;, and &amp;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().
</para>
<para>
Markup strings are just a convenient way to set the #PangoAttrList on
a label; gtk_label_set_attributes() may be a simpler way to set
attributes in some cases. Be careful though; #PangoAttrList 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 #PangoAttribute requires knowledge of the exact string
being displayed, so translations will cause problems.
</para>
</refsect2>
<refsect2>
<title>Selectable labels</title>
<para>
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
&mdash; such as error messages &mdash; should be made selectable.
</para>
</refsect2>
<refsect2>
<title>Text layout</title>
<para>
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.
</para>
<para>
Labels can automatically wrap text if you call
gtk_label_set_line_wrap().
</para>
<para>
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().
</para>
</refsect2>
1999-08-16 18:51:52 +00:00
<!-- ##### SECTION See_Also ##### -->
<para>
1999-08-16 18:51:52 +00:00
</para>
2005-06-20 22:06:27 +00:00
<!-- ##### SECTION Stability_Level ##### -->
1999-08-16 18:51:52 +00:00
<!-- ##### STRUCT GtkLabel ##### -->
<para>
This should not be accessed directly. Use the accessor functions as
described below.
1999-08-16 18:51:52 +00:00
</para>
<!-- ##### SIGNAL GtkLabel::copy-clipboard ##### -->
<para>
</para>
@label: the object which received the signal.
<!-- ##### SIGNAL GtkLabel::move-cursor ##### -->
<para>
</para>
@label: the object which received the signal.
@arg1:
@arg2:
@arg3:
<!-- ##### SIGNAL GtkLabel::populate-popup ##### -->
<para>
</para>
@label: the object which received the signal.
@arg1:
<!-- ##### ARG GtkLabel:angle ##### -->
<para>
</para>
<!-- ##### ARG GtkLabel:attributes ##### -->
<para>
</para>
<!-- ##### ARG GtkLabel:cursor-position ##### -->
<para>
</para>
2004-08-01 05:55:01 +00:00
<!-- ##### ARG GtkLabel:ellipsize ##### -->
<para>
</para>
<!-- ##### ARG GtkLabel:justify ##### -->
<para>
</para>
<!-- ##### ARG GtkLabel:label ##### -->
<para>
</para>
2004-12-16 18:21:44 +00:00
<!-- ##### ARG GtkLabel:max-width-chars ##### -->
<para>
</para>
<!-- ##### ARG GtkLabel:mnemonic-keyval ##### -->
<para>
</para>
<!-- ##### ARG GtkLabel:mnemonic-widget ##### -->
<para>
</para>
<!-- ##### ARG GtkLabel:pattern ##### -->
<para>
</para>
<!-- ##### ARG GtkLabel:selectable ##### -->
<para>
</para>
<!-- ##### ARG GtkLabel:selection-bound ##### -->
<para>
</para>
2004-11-12 17:52:08 +00:00
<!-- ##### ARG GtkLabel:single-line-mode ##### -->
<para>
</para>
<!-- ##### ARG GtkLabel:use-markup ##### -->
<para>
</para>
<!-- ##### ARG GtkLabel:use-underline ##### -->
<para>
</para>
Rework of GtkFileChooserButton, some cleanups. Fixes #154388, #154390, 2004-10-25 James M. Cape <jcape@ignore-your.tv> Rework of GtkFileChooserButton, some cleanups. Fixes #154388, #154390, #154390, #156272. * docs/reference/gtk/gtk-docs.sgml: Moved GtkFileChooserButton below GtkFileChooser. * docs/reference/gtk/gtk-sections.txt: Added gtk_file_chooser_button_get_width_chars(), gtk_file_chooser_button_set_width_chars(), gtk_label_set_width_chars(), gtk_label_get_width_chars(). * docs/reference/gtk/gtk.types: Added gtk_cell_renderer_combo_get_type, gtk_cell_view_get_type, gtk_text_iter_get_type. * docs/reference/gtk/tmpl/gtkaboutdialog.sgml: Add "logo-icon-name" property. * docs/reference/gtk/tmpl/gtkcellview.sgml: Updates for properties (b/c of get_type() inclusion above). * docs/reference/gtk/tmpl/gtkfilechooserbutton.sgml: * docs/reference/gtk/tmpl/gtklabel.sgml: Add "width-chars" property, getters/setters. * docs/reference/gtk/tmpl/gtkcellrenderercombo.sgml: Added. * gtk/gtkentrycompletion.c: (_gtk_entry_completion_popdown): Don't show if the entry isn't mapped. * gtk/gtkfilechooserbutton.[c,h]: (*): About 45% rewritten, adds "width-chars" property, icons, working save modes, volume/Home/Desktop friendly-naming support. * gtk/gtklabel.[c,h]: (gtk_label_class_init), (gtk_label_init), (gtk_label_get_property), (gtk_label_set_property), (gtk_label_get_width_chars), (gtk_label_set_width_chars), (gtk_label_size_request): Add "width-chars" property. * tests/testfilechooserbutton.c: Update, use 4 different buttons for the different ACTIONs. * gtk/.cvsignore: Ignore gtk-update-icon-cache. * tests/.cvsignore: Ignore testimage.
2004-10-26 04:29:56 +00:00
<!-- ##### ARG GtkLabel:width-chars ##### -->
<para>
</para>
<!-- ##### ARG GtkLabel:wrap ##### -->
<para>
</para>
2006-06-22 02:09:31 +00:00
<!-- ##### ARG GtkLabel:wrap-mode ##### -->
<para>
</para>
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_label_new ##### -->
<para>
1999-08-16 18:51:52 +00:00
</para>
@str:
@Returns:
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_label_set_text ##### -->
<para>
</para>
@label:
@str:
<!-- ##### FUNCTION gtk_label_set_attributes ##### -->
<para>
</para>
@label:
@attrs:
<!-- ##### FUNCTION gtk_label_set_markup ##### -->
<para>
</para>
@label:
@str:
<!-- ##### FUNCTION gtk_label_set_markup_with_mnemonic ##### -->
<para>
</para>
@label:
@str:
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_label_set_pattern ##### -->
<para>
The pattern of underlines you want under the existing text within the
#GtkLabel widget. For example if the current text of the label says
&quot;FooBarBaz&quot; passing a pattern of &quot;___ ___&quot; will underline
&quot;Foo&quot; and &quot;Baz&quot; but not &quot;Bar&quot;.
1999-08-16 18:51:52 +00:00
</para>
@label: The #GtkLabel you want to set the pattern to.
@pattern: The pattern as described above.
<!-- ##### FUNCTION gtk_label_set_justify ##### -->
<para>
1999-08-16 18:51:52 +00:00
</para>
@label:
@jtype:
1999-08-16 18:51:52 +00:00
2004-08-01 05:55:01 +00:00
<!-- ##### FUNCTION gtk_label_set_ellipsize ##### -->
<para>
</para>
@label:
@mode:
Rework of GtkFileChooserButton, some cleanups. Fixes #154388, #154390, 2004-10-25 James M. Cape <jcape@ignore-your.tv> Rework of GtkFileChooserButton, some cleanups. Fixes #154388, #154390, #154390, #156272. * docs/reference/gtk/gtk-docs.sgml: Moved GtkFileChooserButton below GtkFileChooser. * docs/reference/gtk/gtk-sections.txt: Added gtk_file_chooser_button_get_width_chars(), gtk_file_chooser_button_set_width_chars(), gtk_label_set_width_chars(), gtk_label_get_width_chars(). * docs/reference/gtk/gtk.types: Added gtk_cell_renderer_combo_get_type, gtk_cell_view_get_type, gtk_text_iter_get_type. * docs/reference/gtk/tmpl/gtkaboutdialog.sgml: Add "logo-icon-name" property. * docs/reference/gtk/tmpl/gtkcellview.sgml: Updates for properties (b/c of get_type() inclusion above). * docs/reference/gtk/tmpl/gtkfilechooserbutton.sgml: * docs/reference/gtk/tmpl/gtklabel.sgml: Add "width-chars" property, getters/setters. * docs/reference/gtk/tmpl/gtkcellrenderercombo.sgml: Added. * gtk/gtkentrycompletion.c: (_gtk_entry_completion_popdown): Don't show if the entry isn't mapped. * gtk/gtkfilechooserbutton.[c,h]: (*): About 45% rewritten, adds "width-chars" property, icons, working save modes, volume/Home/Desktop friendly-naming support. * gtk/gtklabel.[c,h]: (gtk_label_class_init), (gtk_label_init), (gtk_label_get_property), (gtk_label_set_property), (gtk_label_get_width_chars), (gtk_label_set_width_chars), (gtk_label_size_request): Add "width-chars" property. * tests/testfilechooserbutton.c: Update, use 4 different buttons for the different ACTIONs. * gtk/.cvsignore: Ignore gtk-update-icon-cache. * tests/.cvsignore: Ignore testimage.
2004-10-26 04:29:56 +00:00
<!-- ##### FUNCTION gtk_label_set_width_chars ##### -->
<para>
</para>
@label:
@n_chars:
2004-12-16 18:21:44 +00:00
<!-- ##### FUNCTION gtk_label_set_max_width_chars ##### -->
<para>
</para>
@label:
@n_chars:
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_label_get ##### -->
<para>
Gets the current string of text within the #GtkLabel and writes it to
the given @str argument. It does not make a copy of this string so you
must not write to it.
1999-08-16 18:51:52 +00:00
</para>
@label: The #GtkLabel widget you want to get the text from.
@str: The reference to the pointer you want to point to the text.
<!-- ##### FUNCTION gtk_label_parse_uline ##### -->
<para>
Parses the given string for underscores and converts the next
character to an underlined character. The last character that
was underlined will have its lower-cased accelerator keyval returned (i.e.
&quot;_File&quot; would return the keyval for &quot;f&quot;. This is
probably only used within the GTK+ library itself for menu items and such.
1999-08-16 18:51:52 +00:00
</para>
@label: The #GtkLabel you want to affect.
@string: The string you want to parse for underlines.
@Returns: The lowercase keyval of the last character underlined.
<!-- ##### FUNCTION gtk_label_set_line_wrap ##### -->
<para>
1999-08-16 18:51:52 +00:00
</para>
@label:
@wrap:
1999-08-16 18:51:52 +00:00
2006-06-22 02:09:31 +00:00
<!-- ##### FUNCTION gtk_label_set_line_wrap_mode ##### -->
<para>
</para>
@label:
@wrap_mode:
<!-- ##### MACRO gtk_label_set ##### -->
<para>
Aliases gtk_label_set_text(). Probably used for backward compatibility with
GTK+ 1.0.x.
1999-08-16 18:51:52 +00:00
</para>
<!-- ##### FUNCTION gtk_label_get_layout_offsets ##### -->
<para>
</para>
@label:
@x:
@y:
<!-- ##### FUNCTION gtk_label_get_mnemonic_keyval ##### -->
<para>
</para>
@label:
@Returns:
<!-- ##### FUNCTION gtk_label_get_selectable ##### -->
<para>
</para>
@label:
@Returns:
<!-- ##### FUNCTION gtk_label_get_text ##### -->
<para>
</para>
@label:
@Returns:
<!-- ##### FUNCTION gtk_label_new_with_mnemonic ##### -->
<para>
</para>
@str:
@Returns:
<!-- ##### FUNCTION gtk_label_select_region ##### -->
<para>
</para>
@label:
@start_offset:
@end_offset:
<!-- ##### FUNCTION gtk_label_set_mnemonic_widget ##### -->
<para>
</para>
@label:
@widget:
<!-- ##### FUNCTION gtk_label_set_selectable ##### -->
<para>
</para>
@label:
@setting:
<!-- ##### FUNCTION gtk_label_set_text_with_mnemonic ##### -->
<para>
</para>
@label:
@str:
<!-- ##### FUNCTION gtk_label_get_attributes ##### -->
<para>
</para>
@label:
@Returns:
<!-- ##### FUNCTION gtk_label_get_justify ##### -->
<para>
</para>
@label:
@Returns:
2004-08-01 05:55:01 +00:00
<!-- ##### FUNCTION gtk_label_get_ellipsize ##### -->
<para>
</para>
@label:
@Returns:
Rework of GtkFileChooserButton, some cleanups. Fixes #154388, #154390, 2004-10-25 James M. Cape <jcape@ignore-your.tv> Rework of GtkFileChooserButton, some cleanups. Fixes #154388, #154390, #154390, #156272. * docs/reference/gtk/gtk-docs.sgml: Moved GtkFileChooserButton below GtkFileChooser. * docs/reference/gtk/gtk-sections.txt: Added gtk_file_chooser_button_get_width_chars(), gtk_file_chooser_button_set_width_chars(), gtk_label_set_width_chars(), gtk_label_get_width_chars(). * docs/reference/gtk/gtk.types: Added gtk_cell_renderer_combo_get_type, gtk_cell_view_get_type, gtk_text_iter_get_type. * docs/reference/gtk/tmpl/gtkaboutdialog.sgml: Add "logo-icon-name" property. * docs/reference/gtk/tmpl/gtkcellview.sgml: Updates for properties (b/c of get_type() inclusion above). * docs/reference/gtk/tmpl/gtkfilechooserbutton.sgml: * docs/reference/gtk/tmpl/gtklabel.sgml: Add "width-chars" property, getters/setters. * docs/reference/gtk/tmpl/gtkcellrenderercombo.sgml: Added. * gtk/gtkentrycompletion.c: (_gtk_entry_completion_popdown): Don't show if the entry isn't mapped. * gtk/gtkfilechooserbutton.[c,h]: (*): About 45% rewritten, adds "width-chars" property, icons, working save modes, volume/Home/Desktop friendly-naming support. * gtk/gtklabel.[c,h]: (gtk_label_class_init), (gtk_label_init), (gtk_label_get_property), (gtk_label_set_property), (gtk_label_get_width_chars), (gtk_label_set_width_chars), (gtk_label_size_request): Add "width-chars" property. * tests/testfilechooserbutton.c: Update, use 4 different buttons for the different ACTIONs. * gtk/.cvsignore: Ignore gtk-update-icon-cache. * tests/.cvsignore: Ignore testimage.
2004-10-26 04:29:56 +00:00
<!-- ##### FUNCTION gtk_label_get_width_chars ##### -->
<para>
</para>
@label:
@Returns:
2004-12-16 18:21:44 +00:00
<!-- ##### FUNCTION gtk_label_get_max_width_chars ##### -->
<para>
</para>
@label:
@Returns:
<!-- ##### FUNCTION gtk_label_get_label ##### -->
<para>
</para>
@label:
@Returns:
<!-- ##### FUNCTION gtk_label_get_layout ##### -->
<para>
</para>
@label:
@Returns:
<!-- ##### FUNCTION gtk_label_get_line_wrap ##### -->
<para>
</para>
@label:
@Returns:
2006-06-22 02:09:31 +00:00
<!-- ##### FUNCTION gtk_label_get_line_wrap_mode ##### -->
<para>
</para>
@label:
@Returns:
<!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### -->
<para>
</para>
@label:
@Returns:
<!-- ##### FUNCTION gtk_label_get_selection_bounds ##### -->
<para>
</para>
@label:
@start:
@end:
@Returns:
<!-- ##### FUNCTION gtk_label_get_use_markup ##### -->
<para>
</para>
@label:
@Returns:
<!-- ##### FUNCTION gtk_label_get_use_underline ##### -->
<para>
</para>
@label:
@Returns:
2004-11-12 17:52:08 +00:00
<!-- ##### FUNCTION gtk_label_get_single_line_mode ##### -->
<para>
</para>
@label:
@Returns:
<!-- ##### FUNCTION gtk_label_get_angle ##### -->
<para>
</para>
@label:
@Returns:
<!-- ##### FUNCTION gtk_label_set_label ##### -->
<para>
</para>
@label:
@str:
<!-- ##### FUNCTION gtk_label_set_use_markup ##### -->
<para>
</para>
@label:
@setting:
<!-- ##### FUNCTION gtk_label_set_use_underline ##### -->
<para>
</para>
@label:
@setting:
2004-11-12 17:52:08 +00:00
<!-- ##### FUNCTION gtk_label_set_single_line_mode ##### -->
<para>
</para>
@label:
@single_line_mode:
<!-- ##### FUNCTION gtk_label_set_angle ##### -->
<para>
</para>
@label:
@angle: