1
<refentry id="GtkLabel">
3
<refentrytitle role="top_of_page">GtkLabel</refentrytitle>
4
<manvolnum>3</manvolnum>
5
<refmiscinfo>GTK Library</refmiscinfo>
9
<refname>GtkLabel</refname>
10
<refpurpose>A widget that displays a small to medium amount of text</refpurpose>
11
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
14
<refsynopsisdiv role="synopsis">
15
<title role="synopsis.title">Synopsis</title>
19
#include <gtk/gtk.h>
22
<link linkend="GtkLabel-struct">GtkLabel</link>;
23
<link linkend="GtkWidget">GtkWidget</link>* <link linkend="gtk-label-new">gtk_label_new</link> (const <link linkend="gchar">gchar</link> *str);
24
<link linkend="void">void</link> <link linkend="gtk-label-set-text">gtk_label_set_text</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
25
const <link linkend="gchar">gchar</link> *str);
26
<link linkend="void">void</link> <link linkend="gtk-label-set-attributes">gtk_label_set_attributes</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
27
<link linkend="PangoAttrList">PangoAttrList</link> *attrs);
28
<link linkend="void">void</link> <link linkend="gtk-label-set-markup">gtk_label_set_markup</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
29
const <link linkend="gchar">gchar</link> *str);
30
<link linkend="void">void</link> <link linkend="gtk-label-set-markup-with-mnemonic">gtk_label_set_markup_with_mnemonic</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
31
const <link linkend="gchar">gchar</link> *str);
32
<link linkend="void">void</link> <link linkend="gtk-label-set-pattern">gtk_label_set_pattern</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
33
const <link linkend="gchar">gchar</link> *pattern);
34
<link linkend="void">void</link> <link linkend="gtk-label-set-justify">gtk_label_set_justify</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
35
<link linkend="GtkJustification">GtkJustification</link> jtype);
36
<link linkend="void">void</link> <link linkend="gtk-label-set-ellipsize">gtk_label_set_ellipsize</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
37
<link linkend="PangoEllipsizeMode">PangoEllipsizeMode</link> mode);
38
<link linkend="void">void</link> <link linkend="gtk-label-set-width-chars">gtk_label_set_width_chars</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
39
<link linkend="gint">gint</link> n_chars);
40
<link linkend="void">void</link> <link linkend="gtk-label-set-max-width-chars">gtk_label_set_max_width_chars</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
41
<link linkend="gint">gint</link> n_chars);
42
<link linkend="void">void</link> <link linkend="gtk-label-get">gtk_label_get</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
43
<link linkend="gchar">gchar</link> **str);
44
<link linkend="guint">guint</link> <link linkend="gtk-label-parse-uline">gtk_label_parse_uline</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
45
const <link linkend="gchar">gchar</link> *string);
46
<link linkend="void">void</link> <link linkend="gtk-label-set-line-wrap">gtk_label_set_line_wrap</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
47
<link linkend="gboolean">gboolean</link> wrap);
48
<link linkend="void">void</link> <link linkend="gtk-label-set-line-wrap-mode">gtk_label_set_line_wrap_mode</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
49
<link linkend="PangoWrapMode">PangoWrapMode</link> wrap_mode);
50
#define <link linkend="gtk-label-set">gtk_label_set</link>
51
<link linkend="void">void</link> <link linkend="gtk-label-get-layout-offsets">gtk_label_get_layout_offsets</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
52
<link linkend="gint">gint</link> *x,
53
<link linkend="gint">gint</link> *y);
54
<link linkend="guint">guint</link> <link linkend="gtk-label-get-mnemonic-keyval">gtk_label_get_mnemonic_keyval</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
55
<link linkend="gboolean">gboolean</link> <link linkend="gtk-label-get-selectable">gtk_label_get_selectable</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
56
const <link linkend="gchar">gchar</link>* <link linkend="gtk-label-get-text">gtk_label_get_text</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
57
<link linkend="GtkWidget">GtkWidget</link>* <link linkend="gtk-label-new-with-mnemonic">gtk_label_new_with_mnemonic</link> (const <link linkend="gchar">gchar</link> *str);
58
<link linkend="void">void</link> <link linkend="gtk-label-select-region">gtk_label_select_region</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
59
<link linkend="gint">gint</link> start_offset,
60
<link linkend="gint">gint</link> end_offset);
61
<link linkend="void">void</link> <link linkend="gtk-label-set-mnemonic-widget">gtk_label_set_mnemonic_widget</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
62
<link linkend="GtkWidget">GtkWidget</link> *widget);
63
<link linkend="void">void</link> <link linkend="gtk-label-set-selectable">gtk_label_set_selectable</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
64
<link linkend="gboolean">gboolean</link> setting);
65
<link linkend="void">void</link> <link linkend="gtk-label-set-text-with-mnemonic">gtk_label_set_text_with_mnemonic</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
66
const <link linkend="gchar">gchar</link> *str);
67
<link linkend="PangoAttrList">PangoAttrList</link>* <link linkend="gtk-label-get-attributes">gtk_label_get_attributes</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
68
<link linkend="GtkJustification">GtkJustification</link> <link linkend="gtk-label-get-justify">gtk_label_get_justify</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
69
<link linkend="PangoEllipsizeMode">PangoEllipsizeMode</link> <link linkend="gtk-label-get-ellipsize">gtk_label_get_ellipsize</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
70
<link linkend="gint">gint</link> <link linkend="gtk-label-get-width-chars">gtk_label_get_width_chars</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
71
<link linkend="gint">gint</link> <link linkend="gtk-label-get-max-width-chars">gtk_label_get_max_width_chars</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
72
const <link linkend="gchar">gchar</link>* <link linkend="gtk-label-get-label">gtk_label_get_label</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
73
<link linkend="PangoLayout">PangoLayout</link>* <link linkend="gtk-label-get-layout">gtk_label_get_layout</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
74
<link linkend="gboolean">gboolean</link> <link linkend="gtk-label-get-line-wrap">gtk_label_get_line_wrap</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
75
<link linkend="PangoWrapMode">PangoWrapMode</link> <link linkend="gtk-label-get-line-wrap-mode">gtk_label_get_line_wrap_mode</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
76
<link linkend="GtkWidget">GtkWidget</link>* <link linkend="gtk-label-get-mnemonic-widget">gtk_label_get_mnemonic_widget</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
77
<link linkend="gboolean">gboolean</link> <link linkend="gtk-label-get-selection-bounds">gtk_label_get_selection_bounds</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
78
<link linkend="gint">gint</link> *start,
79
<link linkend="gint">gint</link> *end);
80
<link linkend="gboolean">gboolean</link> <link linkend="gtk-label-get-use-markup">gtk_label_get_use_markup</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
81
<link linkend="gboolean">gboolean</link> <link linkend="gtk-label-get-use-underline">gtk_label_get_use_underline</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
82
<link linkend="gboolean">gboolean</link> <link linkend="gtk-label-get-single-line-mode">gtk_label_get_single_line_mode</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
83
<link linkend="gdouble">gdouble</link> <link linkend="gtk-label-get-angle">gtk_label_get_angle</link> (<link linkend="GtkLabel">GtkLabel</link> *label);
84
<link linkend="void">void</link> <link linkend="gtk-label-set-label">gtk_label_set_label</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
85
const <link linkend="gchar">gchar</link> *str);
86
<link linkend="void">void</link> <link linkend="gtk-label-set-use-markup">gtk_label_set_use_markup</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
87
<link linkend="gboolean">gboolean</link> setting);
88
<link linkend="void">void</link> <link linkend="gtk-label-set-use-underline">gtk_label_set_use_underline</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
89
<link linkend="gboolean">gboolean</link> setting);
90
<link linkend="void">void</link> <link linkend="gtk-label-set-single-line-mode">gtk_label_set_single_line_mode</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
91
<link linkend="gboolean">gboolean</link> single_line_mode);
92
<link linkend="void">void</link> <link linkend="gtk-label-set-angle">gtk_label_set_angle</link> (<link linkend="GtkLabel">GtkLabel</link> *label,
93
<link linkend="gdouble">gdouble</link> angle);
99
<refsect1 role="object_hierarchy">
100
<title role="object_hierarchy.title">Object Hierarchy</title>
103
<link linkend="GObject">GObject</link>
104
+----<link linkend="GInitiallyUnowned">GInitiallyUnowned</link>
105
+----<link linkend="GtkObject">GtkObject</link>
106
+----<link linkend="GtkWidget">GtkWidget</link>
107
+----<link linkend="GtkMisc">GtkMisc</link>
109
+----<link linkend="GtkAccelLabel">GtkAccelLabel</link>
110
+----<link linkend="GtkTipsQuery">GtkTipsQuery</link>
117
<refsect1 role="impl_interfaces">
118
<title role="impl_interfaces.title">Implemented Interfaces</title>
121
<link linkend="AtkImplementorIface">AtkImplementorIface</link>.</para>
126
<refsect1 role="properties">
127
<title role="properties.title">Properties</title>
130
"<link linkend="GtkLabel--angle">angle</link>" <link linkend="gdouble">gdouble</link> : Read / Write
131
"<link linkend="GtkLabel--attributes">attributes</link>" <link linkend="PangoAttrList">PangoAttrList</link> : Read / Write
132
"<link linkend="GtkLabel--cursor-position">cursor-position</link>" <link linkend="gint">gint</link> : Read
133
"<link linkend="GtkLabel--ellipsize">ellipsize</link>" <link linkend="PangoEllipsizeMode">PangoEllipsizeMode</link> : Read / Write
134
"<link linkend="GtkLabel--justify">justify</link>" <link linkend="GtkJustification">GtkJustification</link> : Read / Write
135
"<link linkend="GtkLabel--label">label</link>" <link linkend="gchararray">gchararray</link> : Read / Write
136
"<link linkend="GtkLabel--max-width-chars">max-width-chars</link>" <link linkend="gint">gint</link> : Read / Write
137
"<link linkend="GtkLabel--mnemonic-keyval">mnemonic-keyval</link>" <link linkend="guint">guint</link> : Read
138
"<link linkend="GtkLabel--mnemonic-widget">mnemonic-widget</link>" <link linkend="GtkWidget">GtkWidget</link> : Read / Write
139
"<link linkend="GtkLabel--pattern">pattern</link>" <link linkend="gchararray">gchararray</link> : Write
140
"<link linkend="GtkLabel--selectable">selectable</link>" <link linkend="gboolean">gboolean</link> : Read / Write
141
"<link linkend="GtkLabel--selection-bound">selection-bound</link>" <link linkend="gint">gint</link> : Read
142
"<link linkend="GtkLabel--single-line-mode">single-line-mode</link>" <link linkend="gboolean">gboolean</link> : Read / Write
143
"<link linkend="GtkLabel--use-markup">use-markup</link>" <link linkend="gboolean">gboolean</link> : Read / Write
144
"<link linkend="GtkLabel--use-underline">use-underline</link>" <link linkend="gboolean">gboolean</link> : Read / Write
145
"<link linkend="GtkLabel--width-chars">width-chars</link>" <link linkend="gint">gint</link> : Read / Write
146
"<link linkend="GtkLabel--wrap">wrap</link>" <link linkend="gboolean">gboolean</link> : Read / Write
147
"<link linkend="GtkLabel--wrap-mode">wrap-mode</link>" <link linkend="PangoWrapMode">PangoWrapMode</link> : Read / Write
151
<refsect1 role="signal_proto">
152
<title role="signal_proto.title">Signals</title>
155
"<link linkend="GtkLabel-copy-clipboard">copy-clipboard</link>" : Run Last / Action
156
"<link linkend="GtkLabel-move-cursor">move-cursor</link>" : Run Last / Action
157
"<link linkend="GtkLabel-populate-popup">populate-popup</link>" : Run Last
162
<refsect1 role="desc">
163
<title role="desc.title">Description</title>
165
The <link linkend="GtkLabel"><type>GtkLabel</type></link> widget displays a small amount of text. As the name
166
implies, most labels are used to label another widget such as a
167
<link linkend="GtkButton"><type>GtkButton</type></link>, a <link linkend="GtkMenuItem"><type>GtkMenuItem</type></link>, or a <link linkend="GtkOptionMenu"><type>GtkOptionMenu</type></link>.
171
<title>Mnemonics</title>
174
Labels may contain <firstterm>mnemonics</firstterm>. Mnemonics are
175
underlined characters in the label, used for keyboard navigation.
176
Mnemonics are created by providing a string with an underscore before
177
the mnemonic character, such as <literal>"_File"</literal>, to the
178
functions <link linkend="gtk-label-new-with-mnemonic"><function>gtk_label_new_with_mnemonic()</function></link> or
179
<link linkend="gtk-label-set-text-with-mnemonic"><function>gtk_label_set_text_with_mnemonic()</function></link>.
183
Mnemonics automatically activate any activatable widget the label is
184
inside, such as a <link linkend="GtkButton"><type>GtkButton</type></link>; if the label is not inside the
185
mnemonic's target widget, you have to tell the label about the target
186
using <link linkend="gtk-label-set-mnemonic-widget"><function>gtk_label_set_mnemonic_widget()</function></link>. Here's a simple example where
187
the label is inside a button:
191
/* Pressing Alt+H will activate this button */
192
button = gtk_button_new (<!-- -->);
193
label = gtk_label_new_with_mnemonic ("_Hello");
194
gtk_container_add (GTK_CONTAINER (button), label);
197
There's a convenience function to create buttons with a mnemonic label
202
/* Pressing Alt+H will activate this button */
203
button = gtk_button_new_with_mnemonic ("_Hello");
207
To create a mnemonic for a widget alongside the label, such as a
208
<link linkend="GtkEntry"><type>GtkEntry</type></link>, you have to point the label at the entry with
209
<link linkend="gtk-label-set-mnemonic-widget"><function>gtk_label_set_mnemonic_widget()</function></link>:
212
/* Pressing Alt+H will focus the entry */
213
entry = gtk_entry_new (<!-- -->);
214
label = gtk_label_new_with_mnemonic ("_Hello");
215
gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
224
<title>Markup (styled text)</title>
227
To make it easy to format text in a label (changing colors, fonts,
228
etc.), label text can be provided in a simple <link
229
linkend="PangoMarkupFormat">markup format</link>.
230
Here's how to create a label with a small font:
233
label = gtk_label_new (NULL);
234
gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");
238
linkend="PangoMarkupFormat">complete documentation</link> of available
239
tags in the Pango manual.)
242
The markup passed to <link linkend="gtk-label-set-markup"><function>gtk_label_set_markup()</function></link> must be valid; for example,
243
literal </>/& characters must be escaped as &lt;,
244
&gt;, and &amp;. If you pass text obtained from the user, file,
245
or a network to <link linkend="gtk-label-set-markup"><function>gtk_label_set_markup()</function></link>, you'll want to escape it with
246
<link linkend="g-markup-escape-text"><function>g_markup_escape_text()</function></link> or <link linkend="g-markup-printf-escaped"><function>g_markup_printf_escaped()</function></link>.
249
Markup strings are just a convenient way to set the <link linkend="PangoAttrList"><type>PangoAttrList</type></link> on
250
a label; <link linkend="gtk-label-set-attributes"><function>gtk_label_set_attributes()</function></link> may be a simpler way to set
251
attributes in some cases. Be careful though; <link linkend="PangoAttrList"><type>PangoAttrList</type></link> tends to
252
cause internationalization problems, unless you're applying attributes
253
to the entire string (i.e. unless you set the range of each attribute
254
to [0, G_MAXINT)). The reason is that specifying the start_index and
255
end_index for a <link linkend="PangoAttribute"><type>PangoAttribute</type></link> requires knowledge of the exact string
256
being displayed, so translations will cause problems.
261
<title>Selectable labels</title>
264
Labels can be made selectable with <link linkend="gtk-label-set-selectable"><function>gtk_label_set_selectable()</function></link>.
265
Selectable labels allow the user to copy the label contents to
266
the clipboard. Only labels that contain useful-to-copy information
267
— such as error messages — should be made selectable.
272
<title>Text layout</title>
275
A label can contain any number of paragraphs, but will have
276
performance problems if it contains more than a small number.
277
Paragraphs are separated by newlines or other paragraph separators
281
Labels can automatically wrap text if you call
282
<link linkend="gtk-label-set-line-wrap"><function>gtk_label_set_line_wrap()</function></link>.
285
<link linkend="gtk-label-set-justify"><function>gtk_label_set_justify()</function></link> sets how the lines in a label align
286
with one another. If you want to set how the label as a whole
287
aligns in its available space, see <link linkend="gtk-misc-set-alignment"><function>gtk_misc_set_alignment()</function></link>.
293
<refsect1 role="details">
294
<title role="details.title">Details</title>
296
<title><anchor id="GtkLabel-struct" role="struct"/>GtkLabel</title>
297
<indexterm><primary>GtkLabel</primary></indexterm><programlisting>typedef struct _GtkLabel GtkLabel;</programlisting>
299
This should not be accessed directly. Use the accessor functions as
303
<title><anchor id="gtk-label-new" role="function"/>gtk_label_new ()</title>
304
<indexterm><primary>gtk_label_new</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>* gtk_label_new (const <link linkend="gchar">gchar</link> *str);</programlisting>
306
Creates a new label with the given text inside it. You can
307
pass <link linkend="NULL:CAPS"><literal>NULL</literal></link> to get an empty label widget.</para>
310
</para><variablelist role="params">
311
<varlistentry><term><parameter>str</parameter> :</term>
312
<listitem><simpara> The text of the label
313
</simpara></listitem></varlistentry>
314
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the new <link linkend="GtkLabel"><type>GtkLabel</type></link>
315
</simpara></listitem></varlistentry>
316
</variablelist></refsect2>
318
<title><anchor id="gtk-label-set-text" role="function"/>gtk_label_set_text ()</title>
319
<indexterm><primary>gtk_label_set_text</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_text (<link linkend="GtkLabel">GtkLabel</link> *label,
320
const <link linkend="gchar">gchar</link> *str);</programlisting>
322
Sets the text within the <link linkend="GtkLabel"><type>GtkLabel</type></link> widget. It overwrites any text that
326
This will also clear any previously set mnemonic accelerators.</para>
329
</para><variablelist role="params">
330
<varlistentry><term><parameter>label</parameter> :</term>
331
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
332
</simpara></listitem></varlistentry>
333
<varlistentry><term><parameter>str</parameter> :</term>
334
<listitem><simpara> The text you want to set.
335
</simpara></listitem></varlistentry>
336
</variablelist></refsect2>
338
<title><anchor id="gtk-label-set-attributes" role="function"/>gtk_label_set_attributes ()</title>
339
<indexterm><primary>gtk_label_set_attributes</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_attributes (<link linkend="GtkLabel">GtkLabel</link> *label,
340
<link linkend="PangoAttrList">PangoAttrList</link> *attrs);</programlisting>
342
Sets a <link linkend="PangoAttrList"><type>PangoAttrList</type></link>; the attributes in the list are applied to the
343
label text. The attributes set with this function will be ignored
344
if the "use_underline" property or the "use_markup" property
345
is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>.</para>
348
</para><variablelist role="params">
349
<varlistentry><term><parameter>label</parameter> :</term>
350
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
351
</simpara></listitem></varlistentry>
352
<varlistentry><term><parameter>attrs</parameter> :</term>
353
<listitem><simpara> a <link linkend="PangoAttrList"><type>PangoAttrList</type></link>
354
</simpara></listitem></varlistentry>
355
</variablelist></refsect2>
357
<title><anchor id="gtk-label-set-markup" role="function"/>gtk_label_set_markup ()</title>
358
<indexterm><primary>gtk_label_set_markup</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_markup (<link linkend="GtkLabel">GtkLabel</link> *label,
359
const <link linkend="gchar">gchar</link> *str);</programlisting>
361
Parses <parameter>str</parameter> which is marked up with the <link
362
linkend="PangoMarkupFormat">Pango text markup language</link>, setting the
363
label's text and attribute list based on the parse results. If the <parameter>str</parameter> is
364
external data, you may need to escape it with <link linkend="g-markup-escape-text"><function>g_markup_escape_text()</function></link> or
365
<link linkend="g-markup-printf-escaped"><function>g_markup_printf_escaped()</function></link><!-- -->:
366
<informalexample><programlisting>
369
markup = g_markup_printf_escaped ("<span style=\"italic\">%s</span>", str);
370
gtk_label_set_markup (GTK_LABEL (label), markup);
372
</programlisting></informalexample></para>
375
</para><variablelist role="params">
376
<varlistentry><term><parameter>label</parameter> :</term>
377
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
378
</simpara></listitem></varlistentry>
379
<varlistentry><term><parameter>str</parameter> :</term>
380
<listitem><simpara> a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>)
381
</simpara></listitem></varlistentry>
382
</variablelist></refsect2>
384
<title><anchor id="gtk-label-set-markup-with-mnemonic" role="function"/>gtk_label_set_markup_with_mnemonic ()</title>
385
<indexterm><primary>gtk_label_set_markup_with_mnemonic</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_markup_with_mnemonic (<link linkend="GtkLabel">GtkLabel</link> *label,
386
const <link linkend="gchar">gchar</link> *str);</programlisting>
388
Parses <parameter>str</parameter> which is marked up with the <link linkend="PangoMarkupFormat">Pango text markup language</link>,
389
setting the label's text and attribute list based on the parse results.
390
If characters in <parameter>str</parameter> are preceded by an underscore, they are underlined
391
indicating that they represent a keyboard accelerator called a mnemonic.
394
The mnemonic key can be used to activate another widget, chosen automatically,
395
or explicitly using <link linkend="gtk-label-set-mnemonic-widget"><function>gtk_label_set_mnemonic_widget()</function></link>.</para>
398
</para><variablelist role="params">
399
<varlistentry><term><parameter>label</parameter> :</term>
400
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
401
</simpara></listitem></varlistentry>
402
<varlistentry><term><parameter>str</parameter> :</term>
403
<listitem><simpara> a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>)
404
</simpara></listitem></varlistentry>
405
</variablelist></refsect2>
407
<title><anchor id="gtk-label-set-pattern" role="function"/>gtk_label_set_pattern ()</title>
408
<indexterm><primary>gtk_label_set_pattern</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_pattern (<link linkend="GtkLabel">GtkLabel</link> *label,
409
const <link linkend="gchar">gchar</link> *pattern);</programlisting>
411
The pattern of underlines you want under the existing text within the
412
<link linkend="GtkLabel"><type>GtkLabel</type></link> widget. For example if the current text of the label says
413
"FooBarBaz" passing a pattern of "___ ___" will underline
414
"Foo" and "Baz" but not "Bar".
415
</para><variablelist role="params">
416
<varlistentry><term><parameter>label</parameter> :</term>
417
<listitem><simpara>The <link linkend="GtkLabel"><type>GtkLabel</type></link> you want to set the pattern to.
418
</simpara></listitem></varlistentry>
419
<varlistentry><term><parameter>pattern</parameter> :</term>
420
<listitem><simpara>The pattern as described above.
423
</simpara></listitem></varlistentry>
424
</variablelist></refsect2>
426
<title><anchor id="gtk-label-set-justify" role="function"/>gtk_label_set_justify ()</title>
427
<indexterm><primary>gtk_label_set_justify</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_justify (<link linkend="GtkLabel">GtkLabel</link> *label,
428
<link linkend="GtkJustification">GtkJustification</link> jtype);</programlisting>
430
Sets the alignment of the lines in the text of the label relative to
431
each other. <link linkend="GTK-JUSTIFY-LEFT:CAPS"><literal>GTK_JUSTIFY_LEFT</literal></link> is the default value when the
432
widget is first created with <link linkend="gtk-label-new"><function>gtk_label_new()</function></link>. If you instead want
433
to set the alignment of the label as a whole, use
434
<link linkend="gtk-misc-set-alignment"><function>gtk_misc_set_alignment()</function></link> instead. <link linkend="gtk-label-set-justify"><function>gtk_label_set_justify()</function></link> has no
435
effect on labels containing only a single line.</para>
438
</para><variablelist role="params">
439
<varlistentry><term><parameter>label</parameter> :</term>
440
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
441
</simpara></listitem></varlistentry>
442
<varlistentry><term><parameter>jtype</parameter> :</term>
443
<listitem><simpara> a <link linkend="GtkJustification"><type>GtkJustification</type></link>
444
</simpara></listitem></varlistentry>
445
</variablelist></refsect2>
447
<title><anchor id="gtk-label-set-ellipsize" role="function" condition="since:2.6"/>gtk_label_set_ellipsize ()</title>
448
<indexterm role="2.6"><primary>gtk_label_set_ellipsize</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_ellipsize (<link linkend="GtkLabel">GtkLabel</link> *label,
449
<link linkend="PangoEllipsizeMode">PangoEllipsizeMode</link> mode);</programlisting>
451
Sets the mode used to ellipsize (add an ellipsis: "...") to the text if there
452
is not enough space to render the entire string.</para>
455
</para><variablelist role="params">
456
<varlistentry><term><parameter>label</parameter> :</term>
457
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
458
</simpara></listitem></varlistentry>
459
<varlistentry><term><parameter>mode</parameter> :</term>
460
<listitem><simpara> a <link linkend="PangoEllipsizeMode"><type>PangoEllipsizeMode</type></link>
461
</simpara></listitem></varlistentry>
462
</variablelist><para role="since">Since 2.6
465
<title><anchor id="gtk-label-set-width-chars" role="function" condition="since:2.6"/>gtk_label_set_width_chars ()</title>
466
<indexterm role="2.6"><primary>gtk_label_set_width_chars</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_width_chars (<link linkend="GtkLabel">GtkLabel</link> *label,
467
<link linkend="gint">gint</link> n_chars);</programlisting>
469
Sets the desired width in characters of <parameter>label</parameter> to <parameter>n_chars</parameter>.</para>
472
</para><variablelist role="params">
473
<varlistentry><term><parameter>label</parameter> :</term>
474
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
475
</simpara></listitem></varlistentry>
476
<varlistentry><term><parameter>n_chars</parameter> :</term>
477
<listitem><simpara> the new desired width, in characters.
478
</simpara></listitem></varlistentry>
479
</variablelist><para role="since">Since 2.6
482
<title><anchor id="gtk-label-set-max-width-chars" role="function" condition="since:2.6"/>gtk_label_set_max_width_chars ()</title>
483
<indexterm role="2.6"><primary>gtk_label_set_max_width_chars</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_max_width_chars (<link linkend="GtkLabel">GtkLabel</link> *label,
484
<link linkend="gint">gint</link> n_chars);</programlisting>
486
Sets the desired maximum width in characters of <parameter>label</parameter> to <parameter>n_chars</parameter>.</para>
489
</para><variablelist role="params">
490
<varlistentry><term><parameter>label</parameter> :</term>
491
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
492
</simpara></listitem></varlistentry>
493
<varlistentry><term><parameter>n_chars</parameter> :</term>
494
<listitem><simpara> the new desired maximum width, in characters.
495
</simpara></listitem></varlistentry>
496
</variablelist><para role="since">Since 2.6
499
<title><anchor id="gtk-label-get" role="function" condition="deprecated:"/>gtk_label_get ()</title>
500
<indexterm role="deprecated"><primary>gtk_label_get</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_get (<link linkend="GtkLabel">GtkLabel</link> *label,
501
<link linkend="gchar">gchar</link> **str);</programlisting>
502
<warning><para><literal>gtk_label_get</literal> is deprecated and should not be used in newly-written code.</para></warning>
504
Gets the current string of text within the <link linkend="GtkLabel"><type>GtkLabel</type></link> and writes it to
505
the given <parameter>str</parameter> argument. It does not make a copy of this string so you
506
must not write to it.
507
</para><variablelist role="params">
508
<varlistentry><term><parameter>label</parameter> :</term>
509
<listitem><simpara>The <link linkend="GtkLabel"><type>GtkLabel</type></link> widget you want to get the text from.
510
</simpara></listitem></varlistentry>
511
<varlistentry><term><parameter>str</parameter> :</term>
512
<listitem><simpara>The reference to the pointer you want to point to the text.
515
</simpara></listitem></varlistentry>
516
</variablelist></refsect2>
518
<title><anchor id="gtk-label-parse-uline" role="function" condition="deprecated:"/>gtk_label_parse_uline ()</title>
519
<indexterm role="deprecated"><primary>gtk_label_parse_uline</primary></indexterm><programlisting><link linkend="guint">guint</link> gtk_label_parse_uline (<link linkend="GtkLabel">GtkLabel</link> *label,
520
const <link linkend="gchar">gchar</link> *string);</programlisting>
521
<warning><para><literal>gtk_label_parse_uline</literal> is deprecated and should not be used in newly-written code.</para></warning>
523
Parses the given string for underscores and converts the next
524
character to an underlined character. The last character that
525
was underlined will have its lower-cased accelerator keyval returned (i.e.
526
"_File" would return the keyval for "f". This is
527
probably only used within the Gtk+ library itself for menu items and such.
528
</para><variablelist role="params">
529
<varlistentry><term><parameter>label</parameter> :</term>
530
<listitem><simpara>The <link linkend="GtkLabel"><type>GtkLabel</type></link> you want to affect.
531
</simpara></listitem></varlistentry>
532
<varlistentry><term><parameter>string</parameter> :</term>
533
<listitem><simpara>The string you want to parse for underlines.
534
</simpara></listitem></varlistentry>
535
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>The lowercase keyval of the last character underlined.
538
</simpara></listitem></varlistentry>
539
</variablelist></refsect2>
541
<title><anchor id="gtk-label-set-line-wrap" role="function"/>gtk_label_set_line_wrap ()</title>
542
<indexterm><primary>gtk_label_set_line_wrap</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_line_wrap (<link linkend="GtkLabel">GtkLabel</link> *label,
543
<link linkend="gboolean">gboolean</link> wrap);</programlisting>
545
Toggles line wrapping within the <link linkend="GtkLabel"><type>GtkLabel</type></link> widget. <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> makes it break
546
lines if text exceeds the widget's size. <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> lets the text get cut off
547
by the edge of the widget if it exceeds the widget size.
550
Note that setting line wrapping to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> does not make the label
551
wrap at its parent container's width, because GTK+ widgets
552
conceptually can't make their requisition depend on the parent
553
container's size. For a label that wraps at a specific position,
554
set the label's width using <link linkend="gtk-widget-set-size-request"><function>gtk_widget_set_size_request()</function></link>.</para>
557
</para><variablelist role="params">
558
<varlistentry><term><parameter>label</parameter> :</term>
559
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
560
</simpara></listitem></varlistentry>
561
<varlistentry><term><parameter>wrap</parameter> :</term>
562
<listitem><simpara> the setting
563
</simpara></listitem></varlistentry>
564
</variablelist></refsect2>
566
<title><anchor id="gtk-label-set-line-wrap-mode" role="function" condition="since:2.10"/>gtk_label_set_line_wrap_mode ()</title>
567
<indexterm role="2.10"><primary>gtk_label_set_line_wrap_mode</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_line_wrap_mode (<link linkend="GtkLabel">GtkLabel</link> *label,
568
<link linkend="PangoWrapMode">PangoWrapMode</link> wrap_mode);</programlisting>
570
If line wrapping is on (see <link linkend="gtk-label-set-line-wrap"><function>gtk_label_set_line_wrap()</function></link>) this controls how
571
the line wrapping is done. The default is <link linkend="PANGO-WRAP-WORD:CAPS"><literal>PANGO_WRAP_WORD</literal></link> which means
572
wrap on word boundaries.</para>
575
</para><variablelist role="params">
576
<varlistentry><term><parameter>label</parameter> :</term>
577
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
578
</simpara></listitem></varlistentry>
579
<varlistentry><term><parameter>wrap_mode</parameter> :</term>
580
<listitem><simpara> the line wrapping mode
581
</simpara></listitem></varlistentry>
582
</variablelist><para role="since">Since 2.10
585
<title><anchor id="gtk-label-set" role="macro" condition="deprecated:"/>gtk_label_set</title>
586
<indexterm role="deprecated"><primary>gtk_label_set</primary></indexterm><programlisting>#define gtk_label_set gtk_label_set_text
588
<warning><para><literal>gtk_label_set</literal> is deprecated and should not be used in newly-written code.</para></warning>
590
Aliases <link linkend="gtk-label-set-text"><function>gtk_label_set_text()</function></link>. Probably used for backward compatibility with
594
<title><anchor id="gtk-label-get-layout-offsets" role="function"/>gtk_label_get_layout_offsets ()</title>
595
<indexterm><primary>gtk_label_get_layout_offsets</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_get_layout_offsets (<link linkend="GtkLabel">GtkLabel</link> *label,
596
<link linkend="gint">gint</link> *x,
597
<link linkend="gint">gint</link> *y);</programlisting>
599
Obtains the coordinates where the label will draw the <link linkend="PangoLayout"><type>PangoLayout</type></link>
600
representing the text in the label; useful to convert mouse events
601
into coordinates inside the <link linkend="PangoLayout"><type>PangoLayout</type></link>, e.g. to take some action
602
if some part of the label is clicked. Of course you will need to
603
create a <link linkend="GtkEventBox"><type>GtkEventBox</type></link> to receive the events, and pack the label
604
inside it, since labels are a <link linkend="GTK-NO-WINDOW:CAPS"><type>GTK_NO_WINDOW</type></link> widget. Remember
605
when using the <link linkend="PangoLayout"><type>PangoLayout</type></link> functions you need to convert to
606
and from pixels using <link linkend="PANGO-PIXELS:CAPS"><function>PANGO_PIXELS()</function></link> or <link linkend="PANGO-SCALE:CAPS"><type>PANGO_SCALE</type></link>.</para>
609
</para><variablelist role="params">
610
<varlistentry><term><parameter>label</parameter> :</term>
611
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
612
</simpara></listitem></varlistentry>
613
<varlistentry><term><parameter>x</parameter> :</term>
614
<listitem><simpara> location to store X offset of layout, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
615
</simpara></listitem></varlistentry>
616
<varlistentry><term><parameter>y</parameter> :</term>
617
<listitem><simpara> location to store Y offset of layout, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
618
</simpara></listitem></varlistentry>
619
</variablelist></refsect2>
621
<title><anchor id="gtk-label-get-mnemonic-keyval" role="function"/>gtk_label_get_mnemonic_keyval ()</title>
622
<indexterm><primary>gtk_label_get_mnemonic_keyval</primary></indexterm><programlisting><link linkend="guint">guint</link> gtk_label_get_mnemonic_keyval (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
624
If the label has been set so that it has an mnemonic key this function
625
returns the keyval used for the mnemonic accelerator. If there is no
626
mnemonic set up it returns <link linkend="GDK-VoidSymbol"><type>GDK_VoidSymbol</type></link>.</para>
629
</para><variablelist role="params">
630
<varlistentry><term><parameter>label</parameter> :</term>
631
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
632
</simpara></listitem></varlistentry>
633
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> GDK keyval usable for accelerators, or <link linkend="GDK-VoidSymbol"><type>GDK_VoidSymbol</type></link>
634
</simpara></listitem></varlistentry>
635
</variablelist></refsect2>
637
<title><anchor id="gtk-label-get-selectable" role="function"/>gtk_label_get_selectable ()</title>
638
<indexterm><primary>gtk_label_get_selectable</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_label_get_selectable (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
640
Gets the value set by <link linkend="gtk-label-set-selectable"><function>gtk_label_set_selectable()</function></link>.</para>
643
</para><variablelist role="params">
644
<varlistentry><term><parameter>label</parameter> :</term>
645
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
646
</simpara></listitem></varlistentry>
647
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the user can copy text from the label
648
</simpara></listitem></varlistentry>
649
</variablelist></refsect2>
651
<title><anchor id="gtk-label-get-text" role="function"/>gtk_label_get_text ()</title>
652
<indexterm><primary>gtk_label_get_text</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* gtk_label_get_text (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
654
Fetches the text from a label widget, as displayed on the
655
screen. This does not include any embedded underlines
656
indicating mnemonics or Pango markup. (See <link linkend="gtk-label-get-label"><function>gtk_label_get_label()</function></link>)</para>
659
</para><variablelist role="params">
660
<varlistentry><term><parameter>label</parameter> :</term>
661
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
662
</simpara></listitem></varlistentry>
663
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the text in the label widget. This is the internal
664
string used by the label, and must not be modified.
665
</simpara></listitem></varlistentry>
666
</variablelist></refsect2>
668
<title><anchor id="gtk-label-new-with-mnemonic" role="function"/>gtk_label_new_with_mnemonic ()</title>
669
<indexterm><primary>gtk_label_new_with_mnemonic</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>* gtk_label_new_with_mnemonic (const <link linkend="gchar">gchar</link> *str);</programlisting>
671
Creates a new <link linkend="GtkLabel"><type>GtkLabel</type></link>, containing the text in <parameter>str</parameter>.
674
If characters in <parameter>str</parameter> are preceded by an underscore, they are
675
underlined. If you need a literal underscore character in a label, use
676
'__' (two underscores). The first underlined character represents a
677
keyboard accelerator called a mnemonic. The mnemonic key can be used
678
to activate another widget, chosen automatically, or explicitly using
679
<link linkend="gtk-label-set-mnemonic-widget"><function>gtk_label_set_mnemonic_widget()</function></link>.
682
If <link linkend="gtk-label-set-mnemonic-widget"><function>gtk_label_set_mnemonic_widget()</function></link>
683
is not called, then the first activatable ancestor of the <link linkend="GtkLabel"><type>GtkLabel</type></link>
684
will be chosen as the mnemonic widget. For instance, if the
685
label is inside a button or menu item, the button or menu item will
686
automatically become the mnemonic widget and be activated by
690
</para><variablelist role="params">
691
<varlistentry><term><parameter>str</parameter> :</term>
692
<listitem><simpara> The text of the label, with an underscore in front of the
694
</simpara></listitem></varlistentry>
695
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the new <link linkend="GtkLabel"><type>GtkLabel</type></link>
696
</simpara></listitem></varlistentry>
697
</variablelist></refsect2>
699
<title><anchor id="gtk-label-select-region" role="function"/>gtk_label_select_region ()</title>
700
<indexterm><primary>gtk_label_select_region</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_select_region (<link linkend="GtkLabel">GtkLabel</link> *label,
701
<link linkend="gint">gint</link> start_offset,
702
<link linkend="gint">gint</link> end_offset);</programlisting>
704
Selects a range of characters in the label, if the label is selectable.
705
See <link linkend="gtk-label-set-selectable"><function>gtk_label_set_selectable()</function></link>. If the label is not selectable,
706
this function has no effect. If <parameter>start_offset</parameter> or
707
<parameter>end_offset</parameter> are -1, then the end of the label will be substituted.</para>
710
</para><variablelist role="params">
711
<varlistentry><term><parameter>label</parameter> :</term>
712
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
713
</simpara></listitem></varlistentry>
714
<varlistentry><term><parameter>start_offset</parameter> :</term>
715
<listitem><simpara> start offset (in characters not bytes)
716
</simpara></listitem></varlistentry>
717
<varlistentry><term><parameter>end_offset</parameter> :</term>
718
<listitem><simpara> end offset (in characters not bytes)
719
</simpara></listitem></varlistentry>
720
</variablelist></refsect2>
722
<title><anchor id="gtk-label-set-mnemonic-widget" role="function"/>gtk_label_set_mnemonic_widget ()</title>
723
<indexterm><primary>gtk_label_set_mnemonic_widget</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_mnemonic_widget (<link linkend="GtkLabel">GtkLabel</link> *label,
724
<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>
726
If the label has been set so that it has an mnemonic key (using
727
i.e. <link linkend="gtk-label-set-markup-with-mnemonic"><function>gtk_label_set_markup_with_mnemonic()</function></link>,
728
<link linkend="gtk-label-set-text-with-mnemonic"><function>gtk_label_set_text_with_mnemonic()</function></link>, <link linkend="gtk-label-new-with-mnemonic"><function>gtk_label_new_with_mnemonic()</function></link>
729
or the "use_underline" property) the label can be associated with a
730
widget that is the target of the mnemonic. When the label is inside
731
a widget (like a <link linkend="GtkButton"><type>GtkButton</type></link> or a <link linkend="GtkNotebook"><type>GtkNotebook</type></link> tab) it is
732
automatically associated with the correct widget, but sometimes
733
(i.e. when the target is a <link linkend="GtkEntry"><type>GtkEntry</type></link> next to the label) you need to
734
set it explicitly using this function.
737
The target widget will be accelerated by emitting "mnemonic_activate" on it.
738
The default handler for this signal will activate the widget if there are no
739
mnemonic collisions and toggle focus between the colliding widgets otherwise.</para>
742
</para><variablelist role="params">
743
<varlistentry><term><parameter>label</parameter> :</term>
744
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
745
</simpara></listitem></varlistentry>
746
<varlistentry><term><parameter>widget</parameter> :</term>
747
<listitem><simpara> the target <link linkend="GtkWidget"><type>GtkWidget</type></link>
748
</simpara></listitem></varlistentry>
749
</variablelist></refsect2>
751
<title><anchor id="gtk-label-set-selectable" role="function"/>gtk_label_set_selectable ()</title>
752
<indexterm><primary>gtk_label_set_selectable</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_selectable (<link linkend="GtkLabel">GtkLabel</link> *label,
753
<link linkend="gboolean">gboolean</link> setting);</programlisting>
755
Selectable labels allow the user to select text from the label, for
756
copy-and-paste.</para>
759
</para><variablelist role="params">
760
<varlistentry><term><parameter>label</parameter> :</term>
761
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
762
</simpara></listitem></varlistentry>
763
<varlistentry><term><parameter>setting</parameter> :</term>
764
<listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to allow selecting text in the label
765
</simpara></listitem></varlistentry>
766
</variablelist></refsect2>
768
<title><anchor id="gtk-label-set-text-with-mnemonic" role="function"/>gtk_label_set_text_with_mnemonic ()</title>
769
<indexterm><primary>gtk_label_set_text_with_mnemonic</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_text_with_mnemonic (<link linkend="GtkLabel">GtkLabel</link> *label,
770
const <link linkend="gchar">gchar</link> *str);</programlisting>
772
Sets the label's text from the string <parameter>str</parameter>.
773
If characters in <parameter>str</parameter> are preceded by an underscore, they are underlined
774
indicating that they represent a keyboard accelerator called a mnemonic.
775
The mnemonic key can be used to activate another widget, chosen automatically,
776
or explicitly using <link linkend="gtk-label-set-mnemonic-widget"><function>gtk_label_set_mnemonic_widget()</function></link>.</para>
779
</para><variablelist role="params">
780
<varlistentry><term><parameter>label</parameter> :</term>
781
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
782
</simpara></listitem></varlistentry>
783
<varlistentry><term><parameter>str</parameter> :</term>
784
<listitem><simpara> a string
785
</simpara></listitem></varlistentry>
786
</variablelist></refsect2>
788
<title><anchor id="gtk-label-get-attributes" role="function"/>gtk_label_get_attributes ()</title>
789
<indexterm><primary>gtk_label_get_attributes</primary></indexterm><programlisting><link linkend="PangoAttrList">PangoAttrList</link>* gtk_label_get_attributes (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
791
Gets the attribute list that was set on the label using
792
<link linkend="gtk-label-set-attributes"><function>gtk_label_set_attributes()</function></link>, if any. This function does
793
not reflect attributes that come from the labels markup
794
(see <link linkend="gtk-label-set-markup"><function>gtk_label_set_markup()</function></link>). If you want to get the
795
effective attributes for the label, use
796
pango_layout_get_attribute (gtk_label_get_layout (label)).</para>
799
</para><variablelist role="params">
800
<varlistentry><term><parameter>label</parameter> :</term>
801
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
802
</simpara></listitem></varlistentry>
803
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the attribute list, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if none was set.
804
</simpara></listitem></varlistentry>
805
</variablelist></refsect2>
807
<title><anchor id="gtk-label-get-justify" role="function"/>gtk_label_get_justify ()</title>
808
<indexterm><primary>gtk_label_get_justify</primary></indexterm><programlisting><link linkend="GtkJustification">GtkJustification</link> gtk_label_get_justify (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
810
Returns the justification of the label. See <link linkend="gtk-label-set-justify"><function>gtk_label_set_justify()</function></link>.</para>
813
</para><variablelist role="params">
814
<varlistentry><term><parameter>label</parameter> :</term>
815
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
816
</simpara></listitem></varlistentry>
817
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GtkJustification"><type>GtkJustification</type></link>
818
</simpara></listitem></varlistentry>
819
</variablelist></refsect2>
821
<title><anchor id="gtk-label-get-ellipsize" role="function" condition="since:2.6"/>gtk_label_get_ellipsize ()</title>
822
<indexterm role="2.6"><primary>gtk_label_get_ellipsize</primary></indexterm><programlisting><link linkend="PangoEllipsizeMode">PangoEllipsizeMode</link> gtk_label_get_ellipsize (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
824
Returns the ellipsizing position of the label. See <link linkend="gtk-label-set-ellipsize"><function>gtk_label_set_ellipsize()</function></link>.</para>
827
</para><variablelist role="params">
828
<varlistentry><term><parameter>label</parameter> :</term>
829
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
830
</simpara></listitem></varlistentry>
831
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="PangoEllipsizeMode"><type>PangoEllipsizeMode</type></link>
833
</simpara></listitem></varlistentry>
834
</variablelist><para role="since">Since 2.6
837
<title><anchor id="gtk-label-get-width-chars" role="function" condition="since:2.6"/>gtk_label_get_width_chars ()</title>
838
<indexterm role="2.6"><primary>gtk_label_get_width_chars</primary></indexterm><programlisting><link linkend="gint">gint</link> gtk_label_get_width_chars (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
840
Retrieves the desired width of <parameter>label</parameter>, in characters. See
841
<link linkend="gtk-label-set-width-chars"><function>gtk_label_set_width_chars()</function></link>.</para>
844
</para><variablelist role="params">
845
<varlistentry><term><parameter>label</parameter> :</term>
846
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
847
</simpara></listitem></varlistentry>
848
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the width of the label in characters.
850
</simpara></listitem></varlistentry>
851
</variablelist><para role="since">Since 2.6
854
<title><anchor id="gtk-label-get-max-width-chars" role="function" condition="since:2.6"/>gtk_label_get_max_width_chars ()</title>
855
<indexterm role="2.6"><primary>gtk_label_get_max_width_chars</primary></indexterm><programlisting><link linkend="gint">gint</link> gtk_label_get_max_width_chars (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
857
Retrieves the desired maximum width of <parameter>label</parameter>, in characters. See
858
<link linkend="gtk-label-set-width-chars"><function>gtk_label_set_width_chars()</function></link>.</para>
861
</para><variablelist role="params">
862
<varlistentry><term><parameter>label</parameter> :</term>
863
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
864
</simpara></listitem></varlistentry>
865
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the maximum width of the label in characters.
867
</simpara></listitem></varlistentry>
868
</variablelist><para role="since">Since 2.6
871
<title><anchor id="gtk-label-get-label" role="function"/>gtk_label_get_label ()</title>
872
<indexterm><primary>gtk_label_get_label</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* gtk_label_get_label (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
874
Fetches the text from a label widget including any embedded
875
underlines indicating mnemonics and Pango markup. (See
876
<link linkend="gtk-label-get-text"><function>gtk_label_get_text()</function></link>).</para>
879
</para><variablelist role="params">
880
<varlistentry><term><parameter>label</parameter> :</term>
881
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
882
</simpara></listitem></varlistentry>
883
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the text of the label widget. This string is
884
owned by the widget and must not be modified or freed.
885
</simpara></listitem></varlistentry>
886
</variablelist></refsect2>
888
<title><anchor id="gtk-label-get-layout" role="function"/>gtk_label_get_layout ()</title>
889
<indexterm><primary>gtk_label_get_layout</primary></indexterm><programlisting><link linkend="PangoLayout">PangoLayout</link>* gtk_label_get_layout (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
891
Gets the <link linkend="PangoLayout"><type>PangoLayout</type></link> used to display the label.
892
The layout is useful to e.g. convert text positions to
893
pixel positions, in combination with <link linkend="gtk-label-get-layout-offsets"><function>gtk_label_get_layout_offsets()</function></link>.
894
The returned layout is owned by the label so need not be
895
freed by the caller.</para>
898
</para><variablelist role="params">
899
<varlistentry><term><parameter>label</parameter> :</term>
900
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
901
</simpara></listitem></varlistentry>
902
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="PangoLayout"><type>PangoLayout</type></link> for this label
903
</simpara></listitem></varlistentry>
904
</variablelist></refsect2>
906
<title><anchor id="gtk-label-get-line-wrap" role="function"/>gtk_label_get_line_wrap ()</title>
907
<indexterm><primary>gtk_label_get_line_wrap</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_label_get_line_wrap (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
909
Returns whether lines in the label are automatically wrapped. See <link linkend="gtk-label-set-line-wrap"><function>gtk_label_set_line_wrap()</function></link>.</para>
912
</para><variablelist role="params">
913
<varlistentry><term><parameter>label</parameter> :</term>
914
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
915
</simpara></listitem></varlistentry>
916
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the lines of the label are automatically wrapped.
917
</simpara></listitem></varlistentry>
918
</variablelist></refsect2>
920
<title><anchor id="gtk-label-get-line-wrap-mode" role="function" condition="since:2.10"/>gtk_label_get_line_wrap_mode ()</title>
921
<indexterm role="2.10"><primary>gtk_label_get_line_wrap_mode</primary></indexterm><programlisting><link linkend="PangoWrapMode">PangoWrapMode</link> gtk_label_get_line_wrap_mode (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
923
Returns line wrap mode used by the label. See <link linkend="gtk-label-set-line-wrap-mode"><function>gtk_label_set_line_wrap_mode()</function></link>.</para>
926
</para><variablelist role="params">
927
<varlistentry><term><parameter>label</parameter> :</term>
928
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
929
</simpara></listitem></varlistentry>
930
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the lines of the label are automatically wrapped.
932
</simpara></listitem></varlistentry>
933
</variablelist><para role="since">Since 2.10
936
<title><anchor id="gtk-label-get-mnemonic-widget" role="function"/>gtk_label_get_mnemonic_widget ()</title>
937
<indexterm><primary>gtk_label_get_mnemonic_widget</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>* gtk_label_get_mnemonic_widget (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
939
Retrieves the target of the mnemonic (keyboard shortcut) of this
940
label. See <link linkend="gtk-label-set-mnemonic-widget"><function>gtk_label_set_mnemonic_widget()</function></link>.</para>
943
</para><variablelist role="params">
944
<varlistentry><term><parameter>label</parameter> :</term>
945
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
946
</simpara></listitem></varlistentry>
947
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the target of the label's mnemonic, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if none
948
has been set and the default algorithm will be used.
949
</simpara></listitem></varlistentry>
950
</variablelist></refsect2>
952
<title><anchor id="gtk-label-get-selection-bounds" role="function"/>gtk_label_get_selection_bounds ()</title>
953
<indexterm><primary>gtk_label_get_selection_bounds</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_label_get_selection_bounds (<link linkend="GtkLabel">GtkLabel</link> *label,
954
<link linkend="gint">gint</link> *start,
955
<link linkend="gint">gint</link> *end);</programlisting>
957
Gets the selected range of characters in the label, returning <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>
958
if there's a selection.</para>
961
</para><variablelist role="params">
962
<varlistentry><term><parameter>label</parameter> :</term>
963
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
964
</simpara></listitem></varlistentry>
965
<varlistentry><term><parameter>start</parameter> :</term>
966
<listitem><simpara> return location for start of selection, as a character offset
967
</simpara></listitem></varlistentry>
968
<varlistentry><term><parameter>end</parameter> :</term>
969
<listitem><simpara> return location for end of selection, as a character offset
970
</simpara></listitem></varlistentry>
971
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if selection is non-empty
972
</simpara></listitem></varlistentry>
973
</variablelist></refsect2>
975
<title><anchor id="gtk-label-get-use-markup" role="function"/>gtk_label_get_use_markup ()</title>
976
<indexterm><primary>gtk_label_get_use_markup</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_label_get_use_markup (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
978
Returns whether the label's text is interpreted as marked up with
979
the <link linkend="PangoMarkupFormat">Pango text markup
980
language</link>. See <link linkend="gtk-label-set-use-markup"><function>gtk_label_set_use_markup()</function></link>.</para>
983
</para><variablelist role="params">
984
<varlistentry><term><parameter>label</parameter> :</term>
985
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
986
</simpara></listitem></varlistentry>
987
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the label's text will be parsed for markup.
988
</simpara></listitem></varlistentry>
989
</variablelist></refsect2>
991
<title><anchor id="gtk-label-get-use-underline" role="function"/>gtk_label_get_use_underline ()</title>
992
<indexterm><primary>gtk_label_get_use_underline</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_label_get_use_underline (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
994
Returns whether an embedded underline in the label indicates a
995
mnemonic. See <link linkend="gtk-label-set-use-underline"><function>gtk_label_set_use_underline()</function></link>.</para>
998
</para><variablelist role="params">
999
<varlistentry><term><parameter>label</parameter> :</term>
1000
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
1001
</simpara></listitem></varlistentry>
1002
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> whether an embedded underline in the label indicates
1003
the mnemonic accelerator keys.
1004
</simpara></listitem></varlistentry>
1005
</variablelist></refsect2>
1007
<title><anchor id="gtk-label-get-single-line-mode" role="function" condition="since:2.6"/>gtk_label_get_single_line_mode ()</title>
1008
<indexterm role="2.6"><primary>gtk_label_get_single_line_mode</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gtk_label_get_single_line_mode (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
1010
Returns whether the label is in single line mode.</para>
1013
</para><variablelist role="params">
1014
<varlistentry><term><parameter>label</parameter> :</term>
1015
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
1016
</simpara></listitem></varlistentry>
1017
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> when the label is in single line mode.
1019
</simpara></listitem></varlistentry>
1020
</variablelist><para role="since">Since 2.6
1023
<title><anchor id="gtk-label-get-angle" role="function" condition="since:2.6"/>gtk_label_get_angle ()</title>
1024
<indexterm role="2.6"><primary>gtk_label_get_angle</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link> gtk_label_get_angle (<link linkend="GtkLabel">GtkLabel</link> *label);</programlisting>
1026
Gets the angle of rotation for the label. See
1027
gtk_label_set_angle.</para>
1030
</para><variablelist role="params">
1031
<varlistentry><term><parameter>label</parameter> :</term>
1032
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
1033
</simpara></listitem></varlistentry>
1034
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the angle of rotation for the label
1036
</simpara></listitem></varlistentry>
1037
</variablelist><para role="since">Since 2.6
1040
<title><anchor id="gtk-label-set-label" role="function"/>gtk_label_set_label ()</title>
1041
<indexterm><primary>gtk_label_set_label</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_label (<link linkend="GtkLabel">GtkLabel</link> *label,
1042
const <link linkend="gchar">gchar</link> *str);</programlisting>
1044
Sets the text of the label. The label is interpreted as
1045
including embedded underlines and/or Pango markup depending
1046
on the values of label->use_underline and label->use_markup.</para>
1049
</para><variablelist role="params">
1050
<varlistentry><term><parameter>label</parameter> :</term>
1051
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
1052
</simpara></listitem></varlistentry>
1053
<varlistentry><term><parameter>str</parameter> :</term>
1054
<listitem><simpara> the new text to set for the label
1055
</simpara></listitem></varlistentry>
1056
</variablelist></refsect2>
1058
<title><anchor id="gtk-label-set-use-markup" role="function"/>gtk_label_set_use_markup ()</title>
1059
<indexterm><primary>gtk_label_set_use_markup</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_use_markup (<link linkend="GtkLabel">GtkLabel</link> *label,
1060
<link linkend="gboolean">gboolean</link> setting);</programlisting>
1062
Sets whether the text of the label contains markup in <link
1063
linkend="PangoMarkupFormat">Pango's text markup
1064
language</link>. See <link linkend="gtk-label-set-markup"><function>gtk_label_set_markup()</function></link>.</para>
1067
</para><variablelist role="params">
1068
<varlistentry><term><parameter>label</parameter> :</term>
1069
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
1070
</simpara></listitem></varlistentry>
1071
<varlistentry><term><parameter>setting</parameter> :</term>
1072
<listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the label's text should be parsed for markup.
1073
</simpara></listitem></varlistentry>
1074
</variablelist></refsect2>
1076
<title><anchor id="gtk-label-set-use-underline" role="function"/>gtk_label_set_use_underline ()</title>
1077
<indexterm><primary>gtk_label_set_use_underline</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_use_underline (<link linkend="GtkLabel">GtkLabel</link> *label,
1078
<link linkend="gboolean">gboolean</link> setting);</programlisting>
1080
If true, an underline in the text indicates the next character should be
1081
used for the mnemonic accelerator key.</para>
1084
</para><variablelist role="params">
1085
<varlistentry><term><parameter>label</parameter> :</term>
1086
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
1087
</simpara></listitem></varlistentry>
1088
<varlistentry><term><parameter>setting</parameter> :</term>
1089
<listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if underlines in the text indicate mnemonics
1090
</simpara></listitem></varlistentry>
1091
</variablelist></refsect2>
1093
<title><anchor id="gtk-label-set-single-line-mode" role="function" condition="since:2.6"/>gtk_label_set_single_line_mode ()</title>
1094
<indexterm role="2.6"><primary>gtk_label_set_single_line_mode</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_single_line_mode (<link linkend="GtkLabel">GtkLabel</link> *label,
1095
<link linkend="gboolean">gboolean</link> single_line_mode);</programlisting>
1097
Sets whether the label is in single line mode.</para>
1100
</para><variablelist role="params">
1101
<varlistentry><term><parameter>label</parameter> :</term>
1102
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
1103
</simpara></listitem></varlistentry>
1104
<varlistentry><term><parameter>single_line_mode</parameter> :</term>
1105
<listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the label should be in single line mode
1106
</simpara></listitem></varlistentry>
1107
</variablelist><para role="since">Since 2.6
1110
<title><anchor id="gtk-label-set-angle" role="function" condition="since:2.6"/>gtk_label_set_angle ()</title>
1111
<indexterm role="2.6"><primary>gtk_label_set_angle</primary></indexterm><programlisting><link linkend="void">void</link> gtk_label_set_angle (<link linkend="GtkLabel">GtkLabel</link> *label,
1112
<link linkend="gdouble">gdouble</link> angle);</programlisting>
1114
Sets the angle of rotation for the label. An angle of 90 reads from
1115
from bottom to top, an angle of 270, from top to bottom. The angle
1116
setting for the label is ignored if the label is selectable,
1117
wrapped, or ellipsized.</para>
1120
</para><variablelist role="params">
1121
<varlistentry><term><parameter>label</parameter> :</term>
1122
<listitem><simpara> a <link linkend="GtkLabel"><type>GtkLabel</type></link>
1123
</simpara></listitem></varlistentry>
1124
<varlistentry><term><parameter>angle</parameter> :</term>
1125
<listitem><simpara> the angle that the baseline of the label makes with
1126
the horizontal, in degrees, measured counterclockwise
1127
</simpara></listitem></varlistentry>
1128
</variablelist><para role="since">Since 2.6
1132
<refsect1 role="property_details">
1133
<title role="property_details.title">Property Details</title>
1134
<refsect2><title><anchor id="GtkLabel--angle"/>The "<literal>angle</literal>" property</title>
1135
<indexterm role="2.6"><primary>GtkLabel:angle</primary></indexterm><programlisting> "angle" <link linkend="gdouble">gdouble</link> : Read / Write</programlisting>
1137
The angle that the baseline of the label makes with the horizontal,
1138
in degrees, measured counterclockwise. An angle of 90 reads from
1139
from bottom to top, an angle of 270, from top to bottom. Ignored
1140
if the label is selectable, wrapped, or ellipsized.</para>
1143
</para><para>Allowed values: [0,360]</para>
1144
<para>Default value: 0</para>
1148
<refsect2><title><anchor id="GtkLabel--attributes"/>The "<literal>attributes</literal>" property</title>
1149
<indexterm><primary>GtkLabel:attributes</primary></indexterm><programlisting> "attributes" <link linkend="PangoAttrList">PangoAttrList</link> : Read / Write</programlisting>
1150
<para>A list of style attributes to apply to the text of the label.</para></refsect2>
1151
<refsect2><title><anchor id="GtkLabel--cursor-position"/>The "<literal>cursor-position</literal>" property</title>
1152
<indexterm><primary>GtkLabel:cursor-position</primary></indexterm><programlisting> "cursor-position" <link linkend="gint">gint</link> : Read</programlisting>
1153
<para>The current position of the insertion cursor in chars.</para><para>Allowed values: >= 0</para>
1154
<para>Default value: 0</para>
1156
<refsect2><title><anchor id="GtkLabel--ellipsize"/>The "<literal>ellipsize</literal>" property</title>
1157
<indexterm role="2.6"><primary>GtkLabel:ellipsize</primary></indexterm><programlisting> "ellipsize" <link linkend="PangoEllipsizeMode">PangoEllipsizeMode</link> : Read / Write</programlisting>
1159
The preferred place to ellipsize the string, if the label does not have
1160
enough room to display the entire string, specified as a <link linkend="PangoEllisizeMode"><type>PangoEllisizeMode</type></link>.
1163
Note that setting this property to a value other than <link linkend="PANGO-ELLIPSIZE-NONE:CAPS"><literal>PANGO_ELLIPSIZE_NONE</literal></link>
1164
has the side-effect that the label requests only enough space to display the
1165
ellipsis "...". In particular, this means that ellipsizing labels don't
1166
work well in notebook tabs, unless the tab's ::tab-expand property is set
1167
to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>. Other means to set a label's width are
1168
<link linkend="gtk-widget-set-size-request"><function>gtk_widget_set_size_request()</function></link> and <link linkend="gtk-label-set-width-chars"><function>gtk_label_set_width_chars()</function></link>.</para>
1171
</para><para>Default value: PANGO_ELLIPSIZE_NONE</para>
1175
<refsect2><title><anchor id="GtkLabel--justify"/>The "<literal>justify</literal>" property</title>
1176
<indexterm><primary>GtkLabel:justify</primary></indexterm><programlisting> "justify" <link linkend="GtkJustification">GtkJustification</link> : Read / Write</programlisting>
1177
<para>The alignment of the lines in the text of the label relative to each other. This does NOT affect the alignment of the label within its allocation. See GtkMisc::xalign for that.</para><para>Default value: GTK_JUSTIFY_LEFT</para>
1179
<refsect2><title><anchor id="GtkLabel--label"/>The "<literal>label</literal>" property</title>
1180
<indexterm><primary>GtkLabel:label</primary></indexterm><programlisting> "label" <link linkend="gchararray">gchararray</link> : Read / Write</programlisting>
1181
<para>The text of the label.</para><para>Default value: NULL</para>
1183
<refsect2><title><anchor id="GtkLabel--max-width-chars"/>The "<literal>max-width-chars</literal>" property</title>
1184
<indexterm role="2.6"><primary>GtkLabel:max-width-chars</primary></indexterm><programlisting> "max-width-chars" <link linkend="gint">gint</link> : Read / Write</programlisting>
1186
The desired maximum width of the label, in characters. If this property
1187
is set to -1, the width will be calculated automatically, otherwise the
1188
label will request space for no more than the requested number of
1189
characters. If the width-chars property is set to a positive value,
1190
then the max-width-chars property is ignored.</para>
1193
</para><para>Allowed values: >= -1</para>
1194
<para>Default value: -1</para>
1198
<refsect2><title><anchor id="GtkLabel--mnemonic-keyval"/>The "<literal>mnemonic-keyval</literal>" property</title>
1199
<indexterm><primary>GtkLabel:mnemonic-keyval</primary></indexterm><programlisting> "mnemonic-keyval" <link linkend="guint">guint</link> : Read</programlisting>
1200
<para>The mnemonic accelerator key for this label.</para><para>Default value: 16777215</para>
1202
<refsect2><title><anchor id="GtkLabel--mnemonic-widget"/>The "<literal>mnemonic-widget</literal>" property</title>
1203
<indexterm><primary>GtkLabel:mnemonic-widget</primary></indexterm><programlisting> "mnemonic-widget" <link linkend="GtkWidget">GtkWidget</link> : Read / Write</programlisting>
1204
<para>The widget to be activated when the label's mnemonic key is pressed.</para></refsect2>
1205
<refsect2><title><anchor id="GtkLabel--pattern"/>The "<literal>pattern</literal>" property</title>
1206
<indexterm><primary>GtkLabel:pattern</primary></indexterm><programlisting> "pattern" <link linkend="gchararray">gchararray</link> : Write</programlisting>
1207
<para>A string with _ characters in positions correspond to characters in the text to underline.</para><para>Default value: NULL</para>
1209
<refsect2><title><anchor id="GtkLabel--selectable"/>The "<literal>selectable</literal>" property</title>
1210
<indexterm><primary>GtkLabel:selectable</primary></indexterm><programlisting> "selectable" <link linkend="gboolean">gboolean</link> : Read / Write</programlisting>
1211
<para>Whether the label text can be selected with the mouse.</para><para>Default value: FALSE</para>
1213
<refsect2><title><anchor id="GtkLabel--selection-bound"/>The "<literal>selection-bound</literal>" property</title>
1214
<indexterm><primary>GtkLabel:selection-bound</primary></indexterm><programlisting> "selection-bound" <link linkend="gint">gint</link> : Read</programlisting>
1215
<para>The position of the opposite end of the selection from the cursor in chars.</para><para>Allowed values: >= 0</para>
1216
<para>Default value: 0</para>
1218
<refsect2><title><anchor id="GtkLabel--single-line-mode"/>The "<literal>single-line-mode</literal>" property</title>
1219
<indexterm role="2.6"><primary>GtkLabel:single-line-mode</primary></indexterm><programlisting> "single-line-mode" <link linkend="gboolean">gboolean</link> : Read / Write</programlisting>
1221
Whether the label is in single line mode. In single line mode,
1222
the height of the label does not depend on the actual text, it
1223
is always set to ascent + descent of the font. This can be an
1224
advantage in situations where resizing the label because of text
1225
changes would be distracting, e.g. in a statusbar.</para>
1228
</para><para>Default value: FALSE</para>
1232
<refsect2><title><anchor id="GtkLabel--use-markup"/>The "<literal>use-markup</literal>" property</title>
1233
<indexterm><primary>GtkLabel:use-markup</primary></indexterm><programlisting> "use-markup" <link linkend="gboolean">gboolean</link> : Read / Write</programlisting>
1234
<para>The text of the label includes XML markup. See pango_parse_markup().</para><para>Default value: FALSE</para>
1236
<refsect2><title><anchor id="GtkLabel--use-underline"/>The "<literal>use-underline</literal>" property</title>
1237
<indexterm><primary>GtkLabel:use-underline</primary></indexterm><programlisting> "use-underline" <link linkend="gboolean">gboolean</link> : Read / Write</programlisting>
1238
<para>If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key.</para><para>Default value: FALSE</para>
1240
<refsect2><title><anchor id="GtkLabel--width-chars"/>The "<literal>width-chars</literal>" property</title>
1241
<indexterm role="2.6"><primary>GtkLabel:width-chars</primary></indexterm><programlisting> "width-chars" <link linkend="gint">gint</link> : Read / Write</programlisting>
1243
The desired width of the label, in characters. If this property is set to
1244
-1, the width will be calculated automatically, otherwise the label will
1245
request either 3 characters or the property value, whichever is greater.
1246
If the width-chars property is set to a positive value, then the
1247
max-width-chars property is ignored.</para>
1250
</para><para>Allowed values: >= -1</para>
1251
<para>Default value: -1</para>
1255
<refsect2><title><anchor id="GtkLabel--wrap"/>The "<literal>wrap</literal>" property</title>
1256
<indexterm><primary>GtkLabel:wrap</primary></indexterm><programlisting> "wrap" <link linkend="gboolean">gboolean</link> : Read / Write</programlisting>
1257
<para>If set, wrap lines if the text becomes too wide.</para><para>Default value: FALSE</para>
1259
<refsect2><title><anchor id="GtkLabel--wrap-mode"/>The "<literal>wrap-mode</literal>" property</title>
1260
<indexterm role="2.10"><primary>GtkLabel:wrap-mode</primary></indexterm><programlisting> "wrap-mode" <link linkend="PangoWrapMode">PangoWrapMode</link> : Read / Write</programlisting>
1262
If line wrapping is on (see the wrap property) this controls how
1263
the line wrapping is done. The default is <link linkend="PANGO-WRAP-WORD:CAPS"><literal>PANGO_WRAP_WORD</literal></link> which means
1264
wrap on word boundaries.</para>
1267
</para><para>Default value: PANGO_WRAP_WORD</para>
1274
<refsect1 role="signals">
1275
<title role="signals.title">Signal Details</title>
1276
<refsect2><title><anchor id="GtkLabel-copy-clipboard"/>The "copy-clipboard" signal</title>
1277
<indexterm><primary>GtkLabel::copy-clipboard</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="GtkLabel">GtkLabel</link> *label,
1278
<link linkend="gpointer">gpointer</link> user_data) : Run Last / Action</programlisting>
1281
</para><variablelist role="params">
1282
<varlistentry><term><parameter>label</parameter> :</term>
1283
<listitem><simpara>the object which received the signal.
1285
</simpara></listitem></varlistentry>
1286
<varlistentry><term><parameter>user_data</parameter> :</term>
1287
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
1288
</variablelist></refsect2><refsect2><title><anchor id="GtkLabel-move-cursor"/>The "move-cursor" signal</title>
1289
<indexterm><primary>GtkLabel::move-cursor</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="GtkLabel">GtkLabel</link> *label,
1290
<link linkend="GtkMovementStep">GtkMovementStep</link> arg1,
1291
<link linkend="gint">gint</link> arg2,
1292
<link linkend="gboolean">gboolean</link> arg3,
1293
<link linkend="gpointer">gpointer</link> user_data) : Run Last / Action</programlisting>
1296
</para><variablelist role="params">
1297
<varlistentry><term><parameter>label</parameter> :</term>
1298
<listitem><simpara>the object which received the signal.
1299
</simpara></listitem></varlistentry>
1300
<varlistentry><term><parameter>arg1</parameter> :</term>
1302
</simpara></listitem></varlistentry>
1303
<varlistentry><term><parameter>arg2</parameter> :</term>
1305
</simpara></listitem></varlistentry>
1306
<varlistentry><term><parameter>arg3</parameter> :</term>
1309
</simpara></listitem></varlistentry>
1310
<varlistentry><term><parameter>user_data</parameter> :</term>
1311
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
1312
</variablelist></refsect2><refsect2><title><anchor id="GtkLabel-populate-popup"/>The "populate-popup" signal</title>
1313
<indexterm><primary>GtkLabel::populate-popup</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="GtkLabel">GtkLabel</link> *label,
1314
<link linkend="GtkMenu">GtkMenu</link> *arg1,
1315
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
1318
</para><variablelist role="params">
1319
<varlistentry><term><parameter>label</parameter> :</term>
1320
<listitem><simpara>the object which received the signal.
1321
</simpara></listitem></varlistentry>
1322
<varlistentry><term><parameter>arg1</parameter> :</term>
1325
</simpara></listitem></varlistentry>
1326
<varlistentry><term><parameter>user_data</parameter> :</term>
1327
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
1328
</variablelist></refsect2>
added
removed
docs/reference/gtk/xml/gtklabel.xml
