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 id="GtkLabel-BUILDER-UI">
  15 <title>GtkLabel as GtkBuildable</title>
  16 <para>
  17 The GtkLabel implementation of the GtkBuildable interface supports a
  18 custom &lt;attributes&gt; element, which supports any number of &lt;attribute&gt;
  19 elements. the &lt;attribute&gt; element has attributes named name, value,
  20 start and end and allows you to specify #PangoAttribute values for this label.
  21 </para>
  22 <example>
  23 <title>A UI definition fragment specifying Pango attributes</title>
  24 <programlisting><![CDATA[
  25 <object class="GtkLabel">
  26   <attributes>
  27     <attribute name="weight" value="PANGO_WEIGHT_BOLD"/>
  28     <attribute name="background" value="red" start="5" end="10"/>"
  29   </attributes>
  30 </object>
  31 ]]></programlisting>
  32 </example>
  33 <para>
  34 The start and end attributes specify the range of characters to which the
  35 Pango attribute applies. If start and end are not specified, the attribute is
  36 applied to the whole text. Note that specifying ranges does not make much
  37 sense with translatable attributes. Use markup embedded in the translatable
  38 content instead.
  39 </para>
  40 </refsect2>
  41
  42
  43 <refsect2>
  44 <title>Mnemonics</title>
  45
  46 <para>
  47 Labels may contain <firstterm>mnemonics</firstterm>. Mnemonics are
  48 underlined characters in the label, used for keyboard navigation.
  49 Mnemonics are created by providing a string with an underscore before
  50 the mnemonic character, such as <literal>"_File"</literal>, to the
  51 functions gtk_label_new_with_mnemonic() or
  52 gtk_label_set_text_with_mnemonic().
  53 </para>
  54
  55 <para>
  56 Mnemonics automatically activate any activatable widget the label is
  57 inside, such as a #GtkButton; if the label is not inside the
  58 mnemonic's target widget, you have to tell the label about the target
  59 using gtk_label_set_mnemonic_widget(). Here's a simple example where
  60 the label is inside a button:
  61
  62 <informalexample>
  63 <programlisting>
  64   /* Pressing Alt+H will activate this button */
  65   button = gtk_button_new (<!-- -->);
  66   label = gtk_label_new_with_mnemonic ("_Hello");
  67   gtk_container_add (GTK_CONTAINER (button), label);
  68 </programlisting>
  69 </informalexample>
  70 There's a convenience function to create buttons with a mnemonic label
  71 already inside:
  72
  73 <informalexample>
  74 <programlisting>
  75   /* Pressing Alt+H will activate this button */
  76   button = gtk_button_new_with_mnemonic ("_Hello");
  77 </programlisting>
  78 </informalexample>
  79
  80 To create a mnemonic for a widget alongside the label, such as a
  81 #GtkEntry, you have to point the label at the entry with
  82 gtk_label_set_mnemonic_widget():
  83 <informalexample>
  84 <programlisting>
  85   /* Pressing Alt+H will focus the entry */
  86   entry = gtk_entry_new (<!-- -->);
  87   label = gtk_label_new_with_mnemonic ("_Hello");
  88   gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
  89 </programlisting>
  90 </informalexample>
  91
  92 </para>
  93
  94 </refsect2>
  95
  96 <refsect2>
  97 <title>Markup (styled text)</title>
  98
  99 <para>
 100 To make it easy to format text in a label (changing colors, fonts,
 101 etc.), label text can be provided in a simple <link
 102 linkend="PangoMarkupFormat">markup format</link>.
 103 Here's how to create a label with a small font:
 104 <informalexample>
 105 <programlisting>
 106   label = gtk_label_new (NULL);
 107   gtk_label_set_markup (GTK_LABEL (label), "&lt;small&gt;Small text&lt;/small&gt;");
 108 </programlisting>
 109 </informalexample>
 110 (See <link
 111 linkend="PangoMarkupFormat">complete documentation</link> of available
 112 tags in the Pango manual.)
 113 </para>
 114 <para>
 115 The markup passed to gtk_label_set_markup() must be valid; for example,
 116 literal &lt;/&gt;/&amp; characters must be escaped as &amp;lt;,
 117 &amp;gt;, and &amp;amp;. If you pass text obtained from the user, file,
 118 or a network to gtk_label_set_markup(), you'll want to escape it with
 119 g_markup_escape_text() or g_markup_printf_escaped().
 120 </para>
 121 <para>
 122 Markup strings are just a convenient way to set the #PangoAttrList on
 123 a label; gtk_label_set_attributes() may be a simpler way to set
 124 attributes in some cases. Be careful though; #PangoAttrList tends to
 125 cause internationalization problems, unless you're applying attributes
 126 to the entire string (i.e. unless you set the range of each attribute
 127 to [0, G_MAXINT)). The reason is that specifying the start_index and
 128 end_index for a #PangoAttribute requires knowledge of the exact string
 129 being displayed, so translations will cause problems.
 130 </para>
 131 </refsect2>
 132
 133 <refsect2>
 134 <title>Selectable labels</title>
 135
 136 <para>
 137 Labels can be made selectable with gtk_label_set_selectable().
 138 Selectable labels allow the user to copy the label contents to
 139 the clipboard. Only labels that contain useful-to-copy information
 140 &mdash; such as error messages &mdash; should be made selectable.
 141 </para>
 142 </refsect2>
 143
 144 <refsect2>
 145 <title>Text layout</title>
 146
 147 <para>
 148 A label can contain any number of paragraphs, but will have
 149 performance problems if it contains more than a small number.
 150 Paragraphs are separated by newlines or other paragraph separators
 151 understood by Pango.
 152 </para>
 153 <para>
 154 Labels can automatically wrap text if you call
 155 gtk_label_set_line_wrap().
 156 </para>
 157 <para>
 158 gtk_label_set_justify() sets how the lines in a label align
 159 with one another. If you want to set how the label as a whole
 160 aligns in its available space, see gtk_misc_set_alignment().
 161 </para>
 162
 163 </refsect2>
 164
 165 <refsect2>
 166 <title>Links</title>
 167
 168 <para>
 169 Since 2.18, GTK+ supports markup for clickable hyperlinks in addition
 170 to regular Pango markup. The markup for links is borrowed from HTML, using the
 171 <tag>a</tag> with href and title attributes. GTK+ renders links similar to the
 172 way they appear in web browsers, with colored, underlined text. The title
 173 attribute is displayed as a tooltip on the link. An example looks like this:
 174 <informalexample><programlisting>
 175 gtk_label_set_markup (label, "Go to the &lt;a href=\"http://www.gtk.org\" title=\"&amp;lt;i&amp;gt;Our&amp;/i&amp;gt; website\"&gt;GTK+ website&lt;/a&gt; for more...");
 176 </programlisting></informalexample>
 177 It is possible to implement custom handling for links and their tooltips with
 178 the #GtkLabel::activate-link signal and the gtk_label_get_current_uri() function.
 179 </para>
 180
 181 </refsect2>
 182
 183 <!-- ##### SECTION See_Also ##### -->
 184 <para>
 185
 186 </para>
 187
 188 <!-- ##### SECTION Stability_Level ##### -->
 189
 190
 191 <!-- ##### STRUCT GtkLabel ##### -->
 192 <para>
 193 This should not be accessed directly.  Use the accessor functions as
 194 described below.
 195 </para>
 196
 197
 198 <!-- ##### SIGNAL GtkLabel::activate-current-link ##### -->
 199 <para>
 200
 201 </para>
 202
 203 @label: the object which received the signal.
 204
 205 <!-- ##### SIGNAL GtkLabel::activate-link ##### -->
 206 <para>
 207
 208 </para>
 209
 210 @label: the object which received the signal.
 211 @arg1:
 212 @Returns:
 213
 214 <!-- ##### SIGNAL GtkLabel::copy-clipboard ##### -->
 215 <para>
 216
 217 </para>
 218
 219 @label: the object which received the signal.
 220
 221 <!-- ##### SIGNAL GtkLabel::move-cursor ##### -->
 222 <para>
 223
 224 </para>
 225
 226 @label: the object which received the signal.
 227 @arg1:
 228 @arg2:
 229 @arg3:
 230
 231 <!-- ##### SIGNAL GtkLabel::populate-popup ##### -->
 232 <para>
 233
 234 </para>
 235
 236 @label: the object which received the signal.
 237 @arg1:
 238
 239 <!-- ##### ARG GtkLabel:angle ##### -->
 240 <para>
 241
 242 </para>
 243
 244 <!-- ##### ARG GtkLabel:attributes ##### -->
 245 <para>
 246
 247 </para>
 248
 249 <!-- ##### ARG GtkLabel:cursor-position ##### -->
 250 <para>
 251
 252 </para>
 253
 254 <!-- ##### ARG GtkLabel:ellipsize ##### -->
 255 <para>
 256
 257 </para>
 258
 259 <!-- ##### ARG GtkLabel:justify ##### -->
 260 <para>
 261
 262 </para>
 263
 264 <!-- ##### ARG GtkLabel:label ##### -->
 265 <para>
 266
 267 </para>
 268
 269 <!-- ##### ARG GtkLabel:max-width-chars ##### -->
 270 <para>
 271
 272 </para>
 273
 274 <!-- ##### ARG GtkLabel:mnemonic-keyval ##### -->
 275 <para>
 276
 277 </para>
 278
 279 <!-- ##### ARG GtkLabel:mnemonic-widget ##### -->
 280 <para>
 281
 282 </para>
 283
 284 <!-- ##### ARG GtkLabel:pattern ##### -->
 285 <para>
 286
 287 </para>
 288
 289 <!-- ##### ARG GtkLabel:selectable ##### -->
 290 <para>
 291
 292 </para>
 293
 294 <!-- ##### ARG GtkLabel:selection-bound ##### -->
 295 <para>
 296
 297 </para>
 298
 299 <!-- ##### ARG GtkLabel:single-line-mode ##### -->
 300 <para>
 301
 302 </para>
 303
 304 <!-- ##### ARG GtkLabel:track-visited-links ##### -->
 305 <para>
 306
 307 </para>
 308
 309 <!-- ##### ARG GtkLabel:use-markup ##### -->
 310 <para>
 311
 312 </para>
 313
 314 <!-- ##### ARG GtkLabel:use-underline ##### -->
 315 <para>
 316
 317 </para>
 318
 319 <!-- ##### ARG GtkLabel:width-chars ##### -->
 320 <para>
 321
 322 </para>
 323
 324 <!-- ##### ARG GtkLabel:wrap ##### -->
 325 <para>
 326
 327 </para>
 328
 329 <!-- ##### ARG GtkLabel:wrap-mode ##### -->
 330 <para>
 331
 332 </para>
 333
 334 <!-- ##### FUNCTION gtk_label_new ##### -->
 335 <para>
 336
 337 </para>
 338
 339 @str:
 340 @Returns:
 341
 342
 343 <!-- ##### FUNCTION gtk_label_set_text ##### -->
 344 <para>
 345
 346 </para>
 347
 348 @label:
 349 @str:
 350
 351
 352 <!-- ##### FUNCTION gtk_label_set_attributes ##### -->
 353 <para>
 354
 355 </para>
 356
 357 @label:
 358 @attrs:
 359
 360
 361 <!-- ##### FUNCTION gtk_label_set_markup ##### -->
 362 <para>
 363
 364 </para>
 365
 366 @label:
 367 @str:
 368
 369
 370 <!-- ##### FUNCTION gtk_label_set_markup_with_mnemonic ##### -->
 371 <para>
 372
 373 </para>
 374
 375 @label:
 376 @str:
 377
 378
 379 <!-- ##### FUNCTION gtk_label_set_pattern ##### -->
 380 <para>
 381 The pattern of underlines you want under the existing text within the
 382 #GtkLabel widget.  For example if the current text of the label says
 383 &quot;FooBarBaz&quot; passing a pattern of &quot;___   ___&quot; will underline
 384 &quot;Foo&quot; and &quot;Baz&quot; but not &quot;Bar&quot;.
 385 </para>
 386
 387 @label: The #GtkLabel you want to set the pattern to.
 388 @pattern: The pattern as described above.
 389
 390
 391 <!-- ##### FUNCTION gtk_label_set_justify ##### -->
 392 <para>
 393
 394 </para>
 395
 396 @label:
 397 @jtype:
 398
 399
 400 <!-- ##### FUNCTION gtk_label_set_ellipsize ##### -->
 401 <para>
 402
 403 </para>
 404
 405 @label:
 406 @mode:
 407
 408
 409 <!-- ##### FUNCTION gtk_label_set_width_chars ##### -->
 410 <para>
 411
 412 </para>
 413
 414 @label:
 415 @n_chars:
 416
 417
 418 <!-- ##### FUNCTION gtk_label_set_max_width_chars ##### -->
 419 <para>
 420
 421 </para>
 422
 423 @label:
 424 @n_chars:
 425
 426
 427 <!-- ##### FUNCTION gtk_label_get ##### -->
 428 <para>
 429 Gets the current string of text within the #GtkLabel and writes it to
 430 the given @str argument.  It does not make a copy of this string so you
 431 must not write to it.
 432 </para>
 433
 434 @label: The #GtkLabel widget you want to get the text from.
 435 @str: The reference to the pointer you want to point to the text.
 436 @Deprecated: Use gtk_label_get_text() instead.
 437
 438
 439 <!-- ##### FUNCTION gtk_label_parse_uline ##### -->
 440 <para>
 441 Parses the given string for underscores and converts the next
 442 character to an underlined character.  The last character that
 443 was underlined will have its lower-cased accelerator keyval returned  (i.e.
 444 &quot;_File&quot; would return the keyval for &quot;f&quot;.  This is
 445 probably only used within the GTK+ library itself for menu items and such.
 446 </para>
 447
 448 @label: The #GtkLabel you want to affect.
 449 @string: The string you want to parse for underlines.
 450 @Returns: The lowercase keyval of the last character underlined.
 451 @Deprecated: Use gtk_label_set_use_underline() instead.
 452
 453
 454 <!-- ##### FUNCTION gtk_label_set_line_wrap ##### -->
 455 <para>
 456
 457 </para>
 458
 459 @label:
 460 @wrap:
 461
 462
 463 <!-- ##### FUNCTION gtk_label_set_line_wrap_mode ##### -->
 464 <para>
 465
 466 </para>
 467
 468 @label:
 469 @wrap_mode:
 470
 471
 472 <!-- ##### MACRO gtk_label_set ##### -->
 473 <para>
 474 Sets the text within the GtkLabel widget.
 475 </para>
 476
 477 @Deprecated: Use gtk_label_set_text() instead.
 478
 479
 480 <!-- ##### FUNCTION gtk_label_get_layout_offsets ##### -->
 481 <para>
 482
 483 </para>
 484
 485 @label:
 486 @x:
 487 @y:
 488
 489
 490 <!-- ##### FUNCTION gtk_label_get_mnemonic_keyval ##### -->
 491 <para>
 492
 493 </para>
 494
 495 @label:
 496 @Returns:
 497
 498
 499 <!-- ##### FUNCTION gtk_label_get_selectable ##### -->
 500 <para>
 501
 502 </para>
 503
 504 @label:
 505 @Returns:
 506
 507
 508 <!-- ##### FUNCTION gtk_label_get_text ##### -->
 509 <para>
 510
 511 </para>
 512
 513 @label:
 514 @Returns:
 515
 516
 517 <!-- ##### FUNCTION gtk_label_new_with_mnemonic ##### -->
 518 <para>
 519
 520 </para>
 521
 522 @str:
 523 @Returns:
 524
 525
 526 <!-- ##### FUNCTION gtk_label_select_region ##### -->
 527 <para>
 528
 529 </para>
 530
 531 @label:
 532 @start_offset:
 533 @end_offset:
 534
 535
 536 <!-- ##### FUNCTION gtk_label_set_mnemonic_widget ##### -->
 537 <para>
 538
 539 </para>
 540
 541 @label:
 542 @widget:
 543
 544
 545 <!-- ##### FUNCTION gtk_label_set_selectable ##### -->
 546 <para>
 547
 548 </para>
 549
 550 @label:
 551 @setting:
 552
 553
 554 <!-- ##### FUNCTION gtk_label_set_text_with_mnemonic ##### -->
 555 <para>
 556
 557 </para>
 558
 559 @label:
 560 @str:
 561
 562
 563 <!-- ##### FUNCTION gtk_label_get_attributes ##### -->
 564 <para>
 565
 566 </para>
 567
 568 @label:
 569 @Returns:
 570
 571
 572 <!-- ##### FUNCTION gtk_label_get_justify ##### -->
 573 <para>
 574
 575 </para>
 576
 577 @label:
 578 @Returns:
 579
 580
 581 <!-- ##### FUNCTION gtk_label_get_ellipsize ##### -->
 582 <para>
 583
 584 </para>
 585
 586 @label:
 587 @Returns:
 588
 589
 590 <!-- ##### FUNCTION gtk_label_get_width_chars ##### -->
 591 <para>
 592
 593 </para>
 594
 595 @label:
 596 @Returns:
 597
 598
 599 <!-- ##### FUNCTION gtk_label_get_max_width_chars ##### -->
 600 <para>
 601
 602 </para>
 603
 604 @label:
 605 @Returns:
 606
 607
 608 <!-- ##### FUNCTION gtk_label_get_label ##### -->
 609 <para>
 610
 611 </para>
 612
 613 @label:
 614 @Returns:
 615
 616
 617 <!-- ##### FUNCTION gtk_label_get_layout ##### -->
 618 <para>
 619
 620 </para>
 621
 622 @label:
 623 @Returns:
 624
 625
 626 <!-- ##### FUNCTION gtk_label_get_line_wrap ##### -->
 627 <para>
 628
 629 </para>
 630
 631 @label:
 632 @Returns:
 633
 634
 635 <!-- ##### FUNCTION gtk_label_get_line_wrap_mode ##### -->
 636 <para>
 637
 638 </para>
 639
 640 @label:
 641 @Returns:
 642
 643
 644 <!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### -->
 645 <para>
 646
 647 </para>
 648
 649 @label:
 650 @Returns:
 651
 652
 653 <!-- ##### FUNCTION gtk_label_get_selection_bounds ##### -->
 654 <para>
 655
 656 </para>
 657
 658 @label:
 659 @start:
 660 @end:
 661 @Returns:
 662
 663
 664 <!-- ##### FUNCTION gtk_label_get_use_markup ##### -->
 665 <para>
 666
 667 </para>
 668
 669 @label:
 670 @Returns:
 671
 672
 673 <!-- ##### FUNCTION gtk_label_get_use_underline ##### -->
 674 <para>
 675
 676 </para>
 677
 678 @label:
 679 @Returns:
 680
 681
 682 <!-- ##### FUNCTION gtk_label_get_single_line_mode ##### -->
 683 <para>
 684
 685 </para>
 686
 687 @label:
 688 @Returns:
 689
 690
 691 <!-- ##### FUNCTION gtk_label_get_angle ##### -->
 692 <para>
 693
 694 </para>
 695
 696 @label:
 697 @Returns:
 698
 699
 700 <!-- ##### FUNCTION gtk_label_set_label ##### -->
 701 <para>
 702
 703 </para>
 704
 705 @label:
 706 @str:
 707
 708
 709 <!-- ##### FUNCTION gtk_label_set_use_markup ##### -->
 710 <para>
 711
 712 </para>
 713
 714 @label:
 715 @setting:
 716
 717
 718 <!-- ##### FUNCTION gtk_label_set_use_underline ##### -->
 719 <para>
 720
 721 </para>
 722
 723 @label:
 724 @setting:
 725
 726
 727 <!-- ##### FUNCTION gtk_label_set_single_line_mode ##### -->
 728 <para>
 729
 730 </para>
 731
 732 @label:
 733 @single_line_mode:
 734
 735
 736 <!-- ##### FUNCTION gtk_label_set_angle ##### -->
 737 <para>
 738
 739 </para>
 740
 741 @label:
 742 @angle:
 743
 744
 745 <!-- ##### FUNCTION gtk_label_get_current_uri ##### -->
 746 <para>
 747
 748 </para>
 749
 750 @label:
 751 @Returns:
 752
 753
 754 <!-- ##### FUNCTION gtk_label_set_track_visited_links ##### -->
 755 <para>
 756
 757 </para>
 758
 759 @label:
 760 @track_links:
 761
 762
 763 <!-- ##### FUNCTION gtk_label_get_track_visited_links ##### -->
 764 <para>
 765
 766 </para>
 767
 768 @label:
 769 @Returns:
 770
 771