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