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 example,
  87 literal &lt;/&gt;/&amp; characters must be escaped as &amp;lt;,
  88 &amp;gt;, and &amp;amp;. If you pass text obtained from the user, file,
  89 or a network to gtk_label_set_markup(), you'll want to escape it with
  90 g_markup_escape_text() or g_markup_printf_escaped().
  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:ellipsize ##### -->
 184 <para>
 185
 186 </para>
 187
 188 <!-- ##### ARG GtkLabel:justify ##### -->
 189 <para>
 190
 191 </para>
 192
 193 <!-- ##### ARG GtkLabel:label ##### -->
 194 <para>
 195
 196 </para>
 197
 198 <!-- ##### ARG GtkLabel:mnemonic-keyval ##### -->
 199 <para>
 200
 201 </para>
 202
 203 <!-- ##### ARG GtkLabel:mnemonic-widget ##### -->
 204 <para>
 205
 206 </para>
 207
 208 <!-- ##### ARG GtkLabel:pattern ##### -->
 209 <para>
 210
 211 </para>
 212
 213 <!-- ##### ARG GtkLabel:selectable ##### -->
 214 <para>
 215
 216 </para>
 217
 218 <!-- ##### ARG GtkLabel:selection-bound ##### -->
 219 <para>
 220
 221 </para>
 222
 223 <!-- ##### ARG GtkLabel:single-line-mode ##### -->
 224 <para>
 225
 226 </para>
 227
 228 <!-- ##### ARG GtkLabel:use-markup ##### -->
 229 <para>
 230
 231 </para>
 232
 233 <!-- ##### ARG GtkLabel:use-underline ##### -->
 234 <para>
 235
 236 </para>
 237
 238 <!-- ##### ARG GtkLabel:width-chars ##### -->
 239 <para>
 240
 241 </para>
 242
 243 <!-- ##### ARG GtkLabel:wrap ##### -->
 244 <para>
 245
 246 </para>
 247
 248 <!-- ##### FUNCTION gtk_label_new ##### -->
 249 <para>
 250
 251 </para>
 252
 253 @str:
 254 @Returns:
 255
 256
 257 <!-- ##### FUNCTION gtk_label_set_text ##### -->
 258 <para>
 259
 260 </para>
 261
 262 @label:
 263 @str:
 264
 265
 266 <!-- ##### FUNCTION gtk_label_set_attributes ##### -->
 267 <para>
 268
 269 </para>
 270
 271 @label:
 272 @attrs:
 273
 274
 275 <!-- ##### FUNCTION gtk_label_set_markup ##### -->
 276 <para>
 277
 278 </para>
 279
 280 @label:
 281 @str:
 282
 283
 284 <!-- ##### FUNCTION gtk_label_set_markup_with_mnemonic ##### -->
 285 <para>
 286
 287 </para>
 288
 289 @label:
 290 @str:
 291
 292
 293 <!-- ##### FUNCTION gtk_label_set_pattern ##### -->
 294 <para>
 295 The pattern of underlines you want under the existing text within the
 296 #GtkLabel widget.  For example if the current text of the label says
 297 &quot;FooBarBaz&quot; passing a pattern of &quot;___   ___&quot; will underline
 298 &quot;Foo&quot; and &quot;Baz&quot; but not &quot;Bar&quot;.
 299 </para>
 300
 301 @label: The #GtkLabel you want to set the pattern to.
 302 @pattern: The pattern as described above.
 303
 304
 305 <!-- ##### FUNCTION gtk_label_set_justify ##### -->
 306 <para>
 307
 308 </para>
 309
 310 @label:
 311 @jtype:
 312
 313
 314 <!-- ##### FUNCTION gtk_label_set_ellipsize ##### -->
 315 <para>
 316
 317 </para>
 318
 319 @label:
 320 @mode:
 321
 322
 323 <!-- ##### FUNCTION gtk_label_set_width_chars ##### -->
 324 <para>
 325
 326 </para>
 327
 328 @label:
 329 @n_chars:
 330
 331
 332 <!-- ##### FUNCTION gtk_label_get ##### -->
 333 <para>
 334 Gets the current string of text within the #GtkLabel and writes it to
 335 the given @str argument.  It does not make a copy of this string so you
 336 must not write to it.
 337 </para>
 338
 339 @label: The #GtkLabel widget you want to get the text from.
 340 @str: The reference to the pointer you want to point to the text.
 341
 342
 343 <!-- ##### FUNCTION gtk_label_parse_uline ##### -->
 344 <para>
 345 Parses the given string for underscores and converts the next
 346 character to an underlined character.  The last character that
 347 was underlined will have its lower-cased accelerator keyval returned  (i.e.
 348 &quot;_File&quot; would return the keyval for &quot;f&quot;.  This is
 349 probably only used within the Gtk+ library itself for menu items and such.
 350 </para>
 351
 352 @label: The #GtkLabel you want to affect.
 353 @string: The string you want to parse for underlines.
 354 @Returns: The lowercase keyval of the last character underlined.
 355
 356
 357 <!-- ##### FUNCTION gtk_label_set_line_wrap ##### -->
 358 <para>
 359
 360 </para>
 361
 362 @label:
 363 @wrap:
 364
 365
 366 <!-- ##### MACRO gtk_label_set ##### -->
 367 <para>
 368 Aliases gtk_label_set_text().  Probably used for backward compatibility with
 369 Gtk+ 1.0.x.
 370 </para>
 371
 372
 373
 374 <!-- ##### FUNCTION gtk_label_get_layout_offsets ##### -->
 375 <para>
 376
 377 </para>
 378
 379 @label:
 380 @x:
 381 @y:
 382
 383
 384 <!-- ##### FUNCTION gtk_label_get_mnemonic_keyval ##### -->
 385 <para>
 386
 387 </para>
 388
 389 @label:
 390 @Returns:
 391
 392
 393 <!-- ##### FUNCTION gtk_label_get_selectable ##### -->
 394 <para>
 395
 396 </para>
 397
 398 @label:
 399 @Returns:
 400
 401
 402 <!-- ##### FUNCTION gtk_label_get_text ##### -->
 403 <para>
 404
 405 </para>
 406
 407 @label:
 408 @Returns:
 409
 410
 411 <!-- ##### FUNCTION gtk_label_new_with_mnemonic ##### -->
 412 <para>
 413
 414 </para>
 415
 416 @str:
 417 @Returns:
 418
 419
 420 <!-- ##### FUNCTION gtk_label_select_region ##### -->
 421 <para>
 422
 423 </para>
 424
 425 @label:
 426 @start_offset:
 427 @end_offset:
 428
 429
 430 <!-- ##### FUNCTION gtk_label_set_mnemonic_widget ##### -->
 431 <para>
 432
 433 </para>
 434
 435 @label:
 436 @widget:
 437
 438
 439 <!-- ##### FUNCTION gtk_label_set_selectable ##### -->
 440 <para>
 441
 442 </para>
 443
 444 @label:
 445 @setting:
 446
 447
 448 <!-- ##### FUNCTION gtk_label_set_text_with_mnemonic ##### -->
 449 <para>
 450
 451 </para>
 452
 453 @label:
 454 @str:
 455
 456
 457 <!-- ##### FUNCTION gtk_label_get_attributes ##### -->
 458 <para>
 459
 460 </para>
 461
 462 @label:
 463 @Returns:
 464
 465
 466 <!-- ##### FUNCTION gtk_label_get_justify ##### -->
 467 <para>
 468
 469 </para>
 470
 471 @label:
 472 @Returns:
 473
 474
 475 <!-- ##### FUNCTION gtk_label_get_ellipsize ##### -->
 476 <para>
 477
 478 </para>
 479
 480 @label:
 481 @Returns:
 482
 483
 484 <!-- ##### FUNCTION gtk_label_get_width_chars ##### -->
 485 <para>
 486
 487 </para>
 488
 489 @label:
 490 @Returns:
 491
 492
 493 <!-- ##### FUNCTION gtk_label_get_label ##### -->
 494 <para>
 495
 496 </para>
 497
 498 @label:
 499 @Returns:
 500
 501
 502 <!-- ##### FUNCTION gtk_label_get_layout ##### -->
 503 <para>
 504
 505 </para>
 506
 507 @label:
 508 @Returns:
 509
 510
 511 <!-- ##### FUNCTION gtk_label_get_line_wrap ##### -->
 512 <para>
 513
 514 </para>
 515
 516 @label:
 517 @Returns:
 518
 519
 520 <!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### -->
 521 <para>
 522
 523 </para>
 524
 525 @label:
 526 @Returns:
 527
 528
 529 <!-- ##### FUNCTION gtk_label_get_selection_bounds ##### -->
 530 <para>
 531
 532 </para>
 533
 534 @label:
 535 @start:
 536 @end:
 537 @Returns:
 538
 539
 540 <!-- ##### FUNCTION gtk_label_get_use_markup ##### -->
 541 <para>
 542
 543 </para>
 544
 545 @label:
 546 @Returns:
 547
 548
 549 <!-- ##### FUNCTION gtk_label_get_use_underline ##### -->
 550 <para>
 551
 552 </para>
 553
 554 @label:
 555 @Returns:
 556
 557
 558 <!-- ##### FUNCTION gtk_label_get_single_line_mode ##### -->
 559 <para>
 560
 561 </para>
 562
 563 @label:
 564 @Returns:
 565
 566
 567 <!-- ##### FUNCTION gtk_label_set_label ##### -->
 568 <para>
 569
 570 </para>
 571
 572 @label:
 573 @str:
 574
 575
 576 <!-- ##### FUNCTION gtk_label_set_use_markup ##### -->
 577 <para>
 578
 579 </para>
 580
 581 @label:
 582 @setting:
 583
 584
 585 <!-- ##### FUNCTION gtk_label_set_use_underline ##### -->
 586 <para>
 587
 588 </para>
 589
 590 @label:
 591 @setting:
 592
 593
 594 <!-- ##### FUNCTION gtk_label_set_single_line_mode ##### -->
 595 <para>
 596
 597 </para>
 598
 599 @label:
 600 @single_line_mode:
 601
 602