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