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