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 id="label-text-layout">
 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 <para>
 163 The #GtkLabel:width-chars and #GtkLabel:max-width-chars properties
 164 can be used to control the size allocation of ellipsized or wrapped
 165 labels. For ellipsizing labels, if either is specified (and less
 166 than the actual text size), it is used as the minimum width, and the actual
 167 text size is used as the natural width of the label. For wrapping labels,
 168 width-chars is used as the minimum width, if specified, and max-width-chars
 169 is used as the natural width. Even if max-width-chars specified, wrapping
 170 labels will be rewrapped to use all of the available width.
 171 </para>
 172 <note><para>Note that the interpretation of #GtkLabel:width-chars and
 173 #GtkLabel:max-width-chars has changed a bit with the introduction of
 174 width-for-height geometry management and #GtkExtendedLayout.</para></note>
 175 </refsect2>
 176
 177 <refsect2>
 178 <title>Links</title>
 179
 180 <para>
 181 Since 2.18, GTK+ supports markup for clickable hyperlinks in addition
 182 to regular Pango markup. The markup for links is borrowed from HTML, using the
 183 <tag>a</tag> with href and title attributes. GTK+ renders links similar to the
 184 way they appear in web browsers, with colored, underlined text. The title
 185 attribute is displayed as a tooltip on the link. An example looks like this:
 186 <informalexample><programlisting>
 187 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...");
 188 </programlisting></informalexample>
 189 It is possible to implement custom handling for links and their tooltips with
 190 the #GtkLabel::activate-link signal and the gtk_label_get_current_uri() function.
 191 </para>
 192
 193 </refsect2>
 194
 195 <!-- ##### SECTION See_Also ##### -->
 196 <para>
 197
 198 </para>
 199
 200 <!-- ##### SECTION Stability_Level ##### -->
 201
 202
 203 <!-- ##### STRUCT GtkLabel ##### -->
 204 <para>
 205 This should not be accessed directly.  Use the accessor functions as
 206 described below.
 207 </para>
 208
 209
 210 <!-- ##### SIGNAL GtkLabel::activate-current-link ##### -->
 211 <para>
 212
 213 </para>
 214
 215 @label: the object which received the signal.
 216
 217 <!-- ##### SIGNAL GtkLabel::activate-link ##### -->
 218 <para>
 219
 220 </para>
 221
 222 @label: the object which received the signal.
 223 @arg1:
 224 @Returns:
 225
 226 <!-- ##### SIGNAL GtkLabel::copy-clipboard ##### -->
 227 <para>
 228
 229 </para>
 230
 231 @label: the object which received the signal.
 232
 233 <!-- ##### SIGNAL GtkLabel::move-cursor ##### -->
 234 <para>
 235
 236 </para>
 237
 238 @label: the object which received the signal.
 239 @arg1:
 240 @arg2:
 241 @arg3:
 242
 243 <!-- ##### SIGNAL GtkLabel::populate-popup ##### -->
 244 <para>
 245
 246 </para>
 247
 248 @label: the object which received the signal.
 249 @arg1:
 250
 251 <!-- ##### ARG GtkLabel:angle ##### -->
 252 <para>
 253
 254 </para>
 255
 256 <!-- ##### ARG GtkLabel:attributes ##### -->
 257 <para>
 258
 259 </para>
 260
 261 <!-- ##### ARG GtkLabel:cursor-position ##### -->
 262 <para>
 263
 264 </para>
 265
 266 <!-- ##### ARG GtkLabel:ellipsize ##### -->
 267 <para>
 268
 269 </para>
 270
 271 <!-- ##### ARG GtkLabel:justify ##### -->
 272 <para>
 273
 274 </para>
 275
 276 <!-- ##### ARG GtkLabel:label ##### -->
 277 <para>
 278
 279 </para>
 280
 281 <!-- ##### ARG GtkLabel:max-width-chars ##### -->
 282 <para>
 283
 284 </para>
 285
 286 <!-- ##### ARG GtkLabel:mnemonic-keyval ##### -->
 287 <para>
 288
 289 </para>
 290
 291 <!-- ##### ARG GtkLabel:mnemonic-widget ##### -->
 292 <para>
 293
 294 </para>
 295
 296 <!-- ##### ARG GtkLabel:pattern ##### -->
 297 <para>
 298
 299 </para>
 300
 301 <!-- ##### ARG GtkLabel:selectable ##### -->
 302 <para>
 303
 304 </para>
 305
 306 <!-- ##### ARG GtkLabel:selection-bound ##### -->
 307 <para>
 308
 309 </para>
 310
 311 <!-- ##### ARG GtkLabel:single-line-mode ##### -->
 312 <para>
 313
 314 </para>
 315
 316 <!-- ##### ARG GtkLabel:track-visited-links ##### -->
 317 <para>
 318
 319 </para>
 320
 321 <!-- ##### ARG GtkLabel:use-markup ##### -->
 322 <para>
 323
 324 </para>
 325
 326 <!-- ##### ARG GtkLabel:use-underline ##### -->
 327 <para>
 328
 329 </para>
 330
 331 <!-- ##### ARG GtkLabel:width-chars ##### -->
 332 <para>
 333
 334 </para>
 335
 336 <!-- ##### ARG GtkLabel:wrap ##### -->
 337 <para>
 338
 339 </para>
 340
 341 <!-- ##### ARG GtkLabel:wrap-mode ##### -->
 342 <para>
 343
 344 </para>
 345
 346 <!-- ##### FUNCTION gtk_label_new ##### -->
 347 <para>
 348
 349 </para>
 350
 351 @str:
 352 @Returns:
 353
 354
 355 <!-- ##### FUNCTION gtk_label_set_text ##### -->
 356 <para>
 357
 358 </para>
 359
 360 @label:
 361 @str:
 362
 363
 364 <!-- ##### FUNCTION gtk_label_set_attributes ##### -->
 365 <para>
 366
 367 </para>
 368
 369 @label:
 370 @attrs:
 371
 372
 373 <!-- ##### FUNCTION gtk_label_set_markup ##### -->
 374 <para>
 375
 376 </para>
 377
 378 @label:
 379 @str:
 380
 381
 382 <!-- ##### FUNCTION gtk_label_set_markup_with_mnemonic ##### -->
 383 <para>
 384
 385 </para>
 386
 387 @label:
 388 @str:
 389
 390
 391 <!-- ##### FUNCTION gtk_label_set_pattern ##### -->
 392 <para>
 393 The pattern of underlines you want under the existing text within the
 394 #GtkLabel widget.  For example if the current text of the label says
 395 &quot;FooBarBaz&quot; passing a pattern of &quot;___   ___&quot; will underline
 396 &quot;Foo&quot; and &quot;Baz&quot; but not &quot;Bar&quot;.
 397 </para>
 398
 399 @label: The #GtkLabel you want to set the pattern to.
 400 @pattern: The pattern as described above.
 401
 402
 403 <!-- ##### FUNCTION gtk_label_set_justify ##### -->
 404 <para>
 405
 406 </para>
 407
 408 @label:
 409 @jtype:
 410
 411
 412 <!-- ##### FUNCTION gtk_label_set_ellipsize ##### -->
 413 <para>
 414
 415 </para>
 416
 417 @label:
 418 @mode:
 419
 420
 421 <!-- ##### FUNCTION gtk_label_set_width_chars ##### -->
 422 <para>
 423
 424 </para>
 425
 426 @label:
 427 @n_chars:
 428
 429
 430 <!-- ##### FUNCTION gtk_label_set_max_width_chars ##### -->
 431 <para>
 432
 433 </para>
 434
 435 @label:
 436 @n_chars:
 437
 438
 439 <!-- ##### FUNCTION gtk_label_get ##### -->
 440 <para>
 441 Gets the current string of text within the #GtkLabel and writes it to
 442 the given @str argument.  It does not make a copy of this string so you
 443 must not write to it.
 444 </para>
 445
 446 @label: The #GtkLabel widget you want to get the text from.
 447 @str: The reference to the pointer you want to point to the text.
 448 @Deprecated: Use gtk_label_get_text() instead.
 449
 450
 451 <!-- ##### FUNCTION gtk_label_parse_uline ##### -->
 452 <para>
 453 Parses the given string for underscores and converts the next
 454 character to an underlined character.  The last character that
 455 was underlined will have its lower-cased accelerator keyval returned  (i.e.
 456 &quot;_File&quot; would return the keyval for &quot;f&quot;.  This is
 457 probably only used within the GTK+ library itself for menu items and such.
 458 </para>
 459
 460 @label: The #GtkLabel you want to affect.
 461 @string: The string you want to parse for underlines.
 462 @Returns: The lowercase keyval of the last character underlined.
 463 @Deprecated: Use gtk_label_set_use_underline() instead.
 464
 465
 466 <!-- ##### FUNCTION gtk_label_set_line_wrap ##### -->
 467 <para>
 468
 469 </para>
 470
 471 @label:
 472 @wrap:
 473
 474
 475 <!-- ##### FUNCTION gtk_label_set_line_wrap_mode ##### -->
 476 <para>
 477
 478 </para>
 479
 480 @label:
 481 @wrap_mode:
 482
 483
 484 <!-- ##### MACRO gtk_label_set ##### -->
 485 <para>
 486 Sets the text within the GtkLabel widget.
 487 </para>
 488
 489 @Deprecated: Use gtk_label_set_text() instead.
 490
 491
 492 <!-- ##### FUNCTION gtk_label_get_layout_offsets ##### -->
 493 <para>
 494
 495 </para>
 496
 497 @label:
 498 @x:
 499 @y:
 500
 501
 502 <!-- ##### FUNCTION gtk_label_get_mnemonic_keyval ##### -->
 503 <para>
 504
 505 </para>
 506
 507 @label:
 508 @Returns:
 509
 510
 511 <!-- ##### FUNCTION gtk_label_get_selectable ##### -->
 512 <para>
 513
 514 </para>
 515
 516 @label:
 517 @Returns:
 518
 519
 520 <!-- ##### FUNCTION gtk_label_get_text ##### -->
 521 <para>
 522
 523 </para>
 524
 525 @label:
 526 @Returns:
 527
 528
 529 <!-- ##### FUNCTION gtk_label_new_with_mnemonic ##### -->
 530 <para>
 531
 532 </para>
 533
 534 @str:
 535 @Returns:
 536
 537
 538 <!-- ##### FUNCTION gtk_label_select_region ##### -->
 539 <para>
 540
 541 </para>
 542
 543 @label:
 544 @start_offset:
 545 @end_offset:
 546
 547
 548 <!-- ##### FUNCTION gtk_label_set_mnemonic_widget ##### -->
 549 <para>
 550
 551 </para>
 552
 553 @label:
 554 @widget:
 555
 556
 557 <!-- ##### FUNCTION gtk_label_set_selectable ##### -->
 558 <para>
 559
 560 </para>
 561
 562 @label:
 563 @setting:
 564
 565
 566 <!-- ##### FUNCTION gtk_label_set_text_with_mnemonic ##### -->
 567 <para>
 568
 569 </para>
 570
 571 @label:
 572 @str:
 573
 574
 575 <!-- ##### FUNCTION gtk_label_get_attributes ##### -->
 576 <para>
 577
 578 </para>
 579
 580 @label:
 581 @Returns:
 582
 583
 584 <!-- ##### FUNCTION gtk_label_get_justify ##### -->
 585 <para>
 586
 587 </para>
 588
 589 @label:
 590 @Returns:
 591
 592
 593 <!-- ##### FUNCTION gtk_label_get_ellipsize ##### -->
 594 <para>
 595
 596 </para>
 597
 598 @label:
 599 @Returns:
 600
 601
 602 <!-- ##### FUNCTION gtk_label_get_width_chars ##### -->
 603 <para>
 604
 605 </para>
 606
 607 @label:
 608 @Returns:
 609
 610
 611 <!-- ##### FUNCTION gtk_label_get_max_width_chars ##### -->
 612 <para>
 613
 614 </para>
 615
 616 @label:
 617 @Returns:
 618
 619
 620 <!-- ##### FUNCTION gtk_label_get_label ##### -->
 621 <para>
 622
 623 </para>
 624
 625 @label:
 626 @Returns:
 627
 628
 629 <!-- ##### FUNCTION gtk_label_get_layout ##### -->
 630 <para>
 631
 632 </para>
 633
 634 @label:
 635 @Returns:
 636
 637
 638 <!-- ##### FUNCTION gtk_label_get_line_wrap ##### -->
 639 <para>
 640
 641 </para>
 642
 643 @label:
 644 @Returns:
 645
 646
 647 <!-- ##### FUNCTION gtk_label_get_line_wrap_mode ##### -->
 648 <para>
 649
 650 </para>
 651
 652 @label:
 653 @Returns:
 654
 655
 656 <!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### -->
 657 <para>
 658
 659 </para>
 660
 661 @label:
 662 @Returns:
 663
 664
 665 <!-- ##### FUNCTION gtk_label_get_selection_bounds ##### -->
 666 <para>
 667
 668 </para>
 669
 670 @label:
 671 @start:
 672 @end:
 673 @Returns:
 674
 675
 676 <!-- ##### FUNCTION gtk_label_get_use_markup ##### -->
 677 <para>
 678
 679 </para>
 680
 681 @label:
 682 @Returns:
 683
 684
 685 <!-- ##### FUNCTION gtk_label_get_use_underline ##### -->
 686 <para>
 687
 688 </para>
 689
 690 @label:
 691 @Returns:
 692
 693
 694 <!-- ##### FUNCTION gtk_label_get_single_line_mode ##### -->
 695 <para>
 696
 697 </para>
 698
 699 @label:
 700 @Returns:
 701
 702
 703 <!-- ##### FUNCTION gtk_label_get_angle ##### -->
 704 <para>
 705
 706 </para>
 707
 708 @label:
 709 @Returns:
 710
 711
 712 <!-- ##### FUNCTION gtk_label_set_label ##### -->
 713 <para>
 714
 715 </para>
 716
 717 @label:
 718 @str:
 719
 720
 721 <!-- ##### FUNCTION gtk_label_set_use_markup ##### -->
 722 <para>
 723
 724 </para>
 725
 726 @label:
 727 @setting:
 728
 729
 730 <!-- ##### FUNCTION gtk_label_set_use_underline ##### -->
 731 <para>
 732
 733 </para>
 734
 735 @label:
 736 @setting:
 737
 738
 739 <!-- ##### FUNCTION gtk_label_set_single_line_mode ##### -->
 740 <para>
 741
 742 </para>
 743
 744 @label:
 745 @single_line_mode:
 746
 747
 748 <!-- ##### FUNCTION gtk_label_set_angle ##### -->
 749 <para>
 750
 751 </para>
 752
 753 @label:
 754 @angle:
 755
 756
 757 <!-- ##### FUNCTION gtk_label_get_current_uri ##### -->
 758 <para>
 759
 760 </para>
 761
 762 @label:
 763 @Returns:
 764
 765
 766 <!-- ##### FUNCTION gtk_label_set_track_visited_links ##### -->
 767 <para>
 768
 769 </para>
 770
 771 @label:
 772 @track_links:
 773
 774
 775 <!-- ##### FUNCTION gtk_label_get_track_visited_links ##### -->
 776 <para>
 777
 778 </para>
 779
 780 @label:
 781 @Returns:
 782
 783