Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtklabel.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkLabel
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A widget that displays a small to medium amount of text.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkLabel widget displays a small amount of text. As the name
  10 implies, most labels are used to label another widget such as a
  11 #GtkButton, a #GtkMenuItem, or a #GtkOptionMenu.
  12 </para>
  13
  14 <refsect2>
  15 <title>Mnemonics</title>
  16
  17 <para>
  18 Labels may contain <firstterm>mnemonics</firstterm>. Mnemonics are
  19 underlined characters in the label, used for keyboard navigation.
  20 Mnemonics are created by providing a string with an underscore before
  21 the mnemonic character, such as <literal>"_File"</literal>, to the
  22 functions gtk_label_new_with_mnemonic() or
  23 gtk_label_set_text_with_mnemonic().
  24 </para>
  25
  26 <para>
  27 Mnemonics automatically activate any activatable widget the label is
  28 inside, such as a #GtkButton; if the label is not inside the
  29 mnemonic's target widget, you have to tell the label about the target
  30 using gtk_label_set_mnemonic_widget(). Here's a simple example where
  31 the label is inside a button:
  32
  33 <informalexample>
  34 <programlisting>
  35   /* Pressing Alt+H will activate this button */
  36   button = gtk_button_new (<!-- -->);
  37   label = gtk_label_new_with_mnemonic ("_Hello");
  38   gtk_container_add (GTK_CONTAINER (button), label);
  39 </programlisting>
  40 </informalexample>
  41 There's a convenience function to create buttons with a mnemonic label
  42 already inside:
  43
  44 <informalexample>
  45 <programlisting>
  46   /* Pressing Alt+H will activate this button */
  47   button = gtk_button_new_with_mnemonic ("_Hello");
  48 </programlisting>
  49 </informalexample>
  50
  51 To create a mnemonic for a widget alongside the label, such as a
  52 #GtkEntry, you have to point the label at the entry with
  53 gtk_label_set_mnemonic_widget():
  54 <informalexample>
  55 <programlisting>
  56   /* Pressing Alt+H will focus the entry */
  57   entry = gtk_entry_new (<!-- -->);
  58   label = gtk_label_new_with_mnemonic ("_Hello");
  59   gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
  60 </programlisting>
  61 </informalexample>
  62
  63 </para>
  64
  65 </refsect2>
  66
  67 <refsect2>
  68 <title>Markup (styled text)</title>
  69
  70 <para>
  71 To make it easy to format text in a label (changing colors, fonts,
  72 etc.), label text can be provided in a simple <link
  73 linkend="PangoMarkupFormat">markup format</link>.
  74 Here's how to create a label with a small font:
  75 <informalexample>
  76 <programlisting>
  77   label = gtk_label_new (NULL);
  78   gtk_label_set_markup (GTK_LABEL (label), "&lt;small&gt;Small text&lt;/small&gt;");
  79 </programlisting>
  80 </informalexample>
  81 (See <link
  82 linkend="PangoMarkupFormat">complete documentation</link> of available
  83 tags in the Pango manual.)
  84 </para>
  85 <para>
  86 The markup passed to gtk_label_set_markup() must be valid; for
  87 example, literal &lt;/&gt;/&amp; characters must be escaped as
  88 &amp;lt;, &amp;gt;, and &amp;amp;. If you pass text obtained from
  89 the user, file, or a network to gtk_label_set_markup(),
  90 you'll want to escape it with g_markup_escape_text().
  91 </para>
  92 <para>
  93 Markup strings are just a convenient way to set the #PangoAttrList on
  94 a label; gtk_label_set_attributes() may be a simpler way to set
  95 attributes in some cases. Be careful though; #PangoAttrList tends to
  96 cause internationalization problems, unless you're applying attributes
  97 to the entire string (i.e. unless you set the range of each attribute
  98 to [0, G_MAXINT)). The reason is that specifying the start_index and
  99 end_index for a #PangoAttribute requires knowledge of the exact string
 100 being displayed, so translations will cause problems.
 101 </para>
 102 </refsect2>
 103
 104 <refsect2>
 105 <title>Selectable labels</title>
 106
 107 <para>
 108 Labels can be made selectable with gtk_label_set_selectable().
 109 Selectable labels allow the user to copy the label contents to
 110 the clipboard. Only labels that contain useful-to-copy information
 111 &mdash; such as error messages &mdash; should be made selectable.
 112 </para>
 113 </refsect2>
 114
 115 <refsect2>
 116 <title>Text layout</title>
 117
 118 <para>
 119 A label can contain any number of paragraphs, but will have
 120 performance problems if it contains more than a small number.
 121 Paragraphs are separated by newlines or other paragraph separators
 122 understood by Pango.
 123 </para>
 124 <para>
 125 Labels can automatically wrap text if you call
 126 gtk_label_set_line_wrap().
 127 </para>
 128 <para>
 129 gtk_label_set_justify() sets how the lines in a label align
 130 with one another. If you want to set how the label as a whole
 131 aligns in its available space, see gtk_misc_set_alignment().
 132 </para>
 133
 134 </refsect2>
 135
 136 <!-- ##### SECTION See_Also ##### -->
 137 <para>
 138
 139 </para>
 140
 141 <!-- ##### STRUCT GtkLabel ##### -->
 142 <para>
 143 This should not be accessed directly.  Use the accessor functions as
 144 described below.
 145 </para>
 146
 147
 148 <!-- ##### SIGNAL GtkLabel::copy-clipboard ##### -->
 149 <para>
 150
 151 </para>
 152
 153 @label: the object which received the signal.
 154
 155 <!-- ##### SIGNAL GtkLabel::move-cursor ##### -->
 156 <para>
 157
 158 </para>
 159
 160 @label: the object which received the signal.
 161 @arg1:
 162 @arg2:
 163 @arg3:
 164
 165 <!-- ##### SIGNAL GtkLabel::populate-popup ##### -->
 166 <para>
 167
 168 </para>
 169
 170 @label: the object which received the signal.
 171 @arg1:
 172
 173 <!-- ##### ARG GtkLabel:attributes ##### -->
 174 <para>
 175
 176 </para>
 177
 178 <!-- ##### ARG GtkLabel:cursor-position ##### -->
 179 <para>
 180
 181 </para>
 182
 183 <!-- ##### ARG GtkLabel:justify ##### -->
 184 <para>
 185
 186 </para>
 187
 188 <!-- ##### ARG GtkLabel:label ##### -->
 189 <para>
 190
 191 </para>
 192
 193 <!-- ##### ARG GtkLabel:mnemonic-keyval ##### -->
 194 <para>
 195
 196 </para>
 197
 198 <!-- ##### ARG GtkLabel:mnemonic-widget ##### -->
 199 <para>
 200
 201 </para>
 202
 203 <!-- ##### ARG GtkLabel:pattern ##### -->
 204 <para>
 205
 206 </para>
 207
 208 <!-- ##### ARG GtkLabel:selectable ##### -->
 209 <para>
 210
 211 </para>
 212
 213 <!-- ##### ARG GtkLabel:selection-bound ##### -->
 214 <para>
 215
 216 </para>
 217
 218 <!-- ##### ARG GtkLabel:use-markup ##### -->
 219 <para>
 220
 221 </para>
 222
 223 <!-- ##### ARG GtkLabel:use-underline ##### -->
 224 <para>
 225
 226 </para>
 227
 228 <!-- ##### ARG GtkLabel:wrap ##### -->
 229 <para>
 230
 231 </para>
 232
 233 <!-- ##### FUNCTION gtk_label_new ##### -->
 234 <para>
 235
 236 </para>
 237
 238 @str:
 239 @Returns:
 240
 241
 242 <!-- ##### FUNCTION gtk_label_set_text ##### -->
 243 <para>
 244
 245 </para>
 246
 247 @label:
 248 @str:
 249
 250
 251 <!-- ##### FUNCTION gtk_label_set_attributes ##### -->
 252 <para>
 253
 254 </para>
 255
 256 @label:
 257 @attrs:
 258
 259
 260 <!-- ##### FUNCTION gtk_label_set_markup ##### -->
 261 <para>
 262
 263 </para>
 264
 265 @label:
 266 @str:
 267
 268
 269 <!-- ##### FUNCTION gtk_label_set_markup_with_mnemonic ##### -->
 270 <para>
 271
 272 </para>
 273
 274 @label:
 275 @str:
 276
 277
 278 <!-- ##### FUNCTION gtk_label_set_pattern ##### -->
 279 <para>
 280 The pattern of underlines you want under the existing text within the
 281 #GtkLabel widget.  For example if the current text of the label says
 282 &quot;FooBarBaz&quot; passing a pattern of &quot;___   ___&quot; will underline
 283 &quot;Foo&quot; and &quot;Baz&quot; but not &quot;Bar&quot;.
 284 </para>
 285
 286 @label: The #GtkLabel you want to set the pattern to.
 287 @pattern: The pattern as described above.
 288
 289
 290 <!-- ##### FUNCTION gtk_label_set_justify ##### -->
 291 <para>
 292
 293 </para>
 294
 295 @label:
 296 @jtype:
 297
 298
 299 <!-- ##### FUNCTION gtk_label_get ##### -->
 300 <para>
 301 Gets the current string of text within the #GtkLabel and writes it to
 302 the given @str argument.  It does not make a copy of this string so you
 303 must not write to it.
 304 </para>
 305
 306 @label: The #GtkLabel widget you want to get the text from.
 307 @str: The reference to the pointer you want to point to the text.
 308
 309
 310 <!-- ##### FUNCTION gtk_label_parse_uline ##### -->
 311 <para>
 312 Parses the given string for underscores and converts the next
 313 character to an underlined character.  The last character that
 314 was underlined will have its lower-cased accelerator keyval returned  (i.e.
 315 &quot;_File&quot; would return the keyval for &quot;f&quot;.  This is
 316 probably only used within the Gtk+ library itself for menu items and such.
 317 </para>
 318
 319 @label: The #GtkLabel you want to affect.
 320 @string: The string you want to parse for underlines.
 321 @Returns: The lowercase keyval of the last character underlined.
 322
 323
 324 <!-- ##### FUNCTION gtk_label_set_line_wrap ##### -->
 325 <para>
 326
 327 </para>
 328
 329 @label:
 330 @wrap:
 331
 332
 333 <!-- ##### MACRO gtk_label_set ##### -->
 334 <para>
 335 Aliases gtk_label_set_text().  Probably used for backward compatibility with
 336 Gtk+ 1.0.x.
 337 </para>
 338
 339
 340
 341 <!-- ##### FUNCTION gtk_label_get_layout_offsets ##### -->
 342 <para>
 343
 344 </para>
 345
 346 @label:
 347 @x:
 348 @y:
 349
 350
 351 <!-- ##### FUNCTION gtk_label_get_mnemonic_keyval ##### -->
 352 <para>
 353
 354 </para>
 355
 356 @label:
 357 @Returns:
 358
 359
 360 <!-- ##### FUNCTION gtk_label_get_selectable ##### -->
 361 <para>
 362
 363 </para>
 364
 365 @label:
 366 @Returns:
 367
 368
 369 <!-- ##### FUNCTION gtk_label_get_text ##### -->
 370 <para>
 371
 372 </para>
 373
 374 @label:
 375 @Returns:
 376
 377
 378 <!-- ##### FUNCTION gtk_label_new_with_mnemonic ##### -->
 379 <para>
 380
 381 </para>
 382
 383 @str:
 384 @Returns:
 385
 386
 387 <!-- ##### FUNCTION gtk_label_select_region ##### -->
 388 <para>
 389
 390 </para>
 391
 392 @label:
 393 @start_offset:
 394 @end_offset:
 395
 396
 397 <!-- ##### FUNCTION gtk_label_set_mnemonic_widget ##### -->
 398 <para>
 399
 400 </para>
 401
 402 @label:
 403 @widget:
 404
 405
 406 <!-- ##### FUNCTION gtk_label_set_selectable ##### -->
 407 <para>
 408
 409 </para>
 410
 411 @label:
 412 @setting:
 413
 414
 415 <!-- ##### FUNCTION gtk_label_set_text_with_mnemonic ##### -->
 416 <para>
 417
 418 </para>
 419
 420 @label:
 421 @str:
 422
 423
 424 <!-- ##### FUNCTION gtk_label_get_attributes ##### -->
 425 <para>
 426
 427 </para>
 428
 429 @label:
 430 @Returns:
 431
 432
 433 <!-- ##### FUNCTION gtk_label_get_justify ##### -->
 434 <para>
 435
 436 </para>
 437
 438 @label:
 439 @Returns:
 440
 441
 442 <!-- ##### FUNCTION gtk_label_get_label ##### -->
 443 <para>
 444
 445 </para>
 446
 447 @label:
 448 @Returns:
 449
 450
 451 <!-- ##### FUNCTION gtk_label_get_layout ##### -->
 452 <para>
 453
 454 </para>
 455
 456 @label:
 457 @Returns:
 458
 459
 460 <!-- ##### FUNCTION gtk_label_get_line_wrap ##### -->
 461 <para>
 462
 463 </para>
 464
 465 @label:
 466 @Returns:
 467
 468
 469 <!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### -->
 470 <para>
 471
 472 </para>
 473
 474 @label:
 475 @Returns:
 476
 477
 478 <!-- ##### FUNCTION gtk_label_get_selection_bounds ##### -->
 479 <para>
 480
 481 </para>
 482
 483 @label:
 484 @start:
 485 @end:
 486 @Returns:
 487
 488
 489 <!-- ##### FUNCTION gtk_label_get_use_markup ##### -->
 490 <para>
 491
 492 </para>
 493
 494 @label:
 495 @Returns:
 496
 497
 498 <!-- ##### FUNCTION gtk_label_get_use_underline ##### -->
 499 <para>
 500
 501 </para>
 502
 503 @label:
 504 @Returns:
 505
 506
 507 <!-- ##### FUNCTION gtk_label_set_label ##### -->
 508 <para>
 509
 510 </para>
 511
 512 @label:
 513 @str:
 514
 515
 516 <!-- ##### FUNCTION gtk_label_set_use_markup ##### -->
 517 <para>
 518
 519 </para>
 520
 521 @label:
 522 @setting:
 523
 524
 525 <!-- ##### FUNCTION gtk_label_set_use_underline ##### -->
 526 <para>
 527
 528 </para>
 529
 530 @label:
 531 @setting:
 532
 533