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 <!-- ##### FUNCTION gtk_label_new ##### -->
 149 <para>
 150
 151 </para>
 152
 153 @str:
 154 @Returns:
 155
 156
 157 <!-- ##### FUNCTION gtk_label_set_text ##### -->
 158 <para>
 159
 160 </para>
 161
 162 @label:
 163 @str:
 164
 165
 166 <!-- ##### FUNCTION gtk_label_set_attributes ##### -->
 167 <para>
 168
 169 </para>
 170
 171 @label:
 172 @attrs:
 173
 174
 175 <!-- ##### FUNCTION gtk_label_set_markup ##### -->
 176 <para>
 177
 178 </para>
 179
 180 @label:
 181 @str:
 182
 183
 184 <!-- ##### FUNCTION gtk_label_set_markup_with_mnemonic ##### -->
 185 <para>
 186
 187 </para>
 188
 189 @label:
 190 @str:
 191
 192
 193 <!-- ##### FUNCTION gtk_label_set_pattern ##### -->
 194 <para>
 195 The pattern of underlines you want under the existing text within the
 196 #GtkLabel widget.  For example if the current text of the label says
 197 &quot;FooBarBaz&quot; passing a pattern of &quot;___   ___&quot; will underline
 198 &quot;Foo&quot; and &quot;Baz&quot; but not &quot;Bar&quot;.
 199 </para>
 200
 201 @label: The #GtkLabel you want to set the pattern to.
 202 @pattern: The pattern as described above.
 203
 204
 205 <!-- ##### FUNCTION gtk_label_set_justify ##### -->
 206 <para>
 207
 208 </para>
 209
 210 @label:
 211 @jtype:
 212
 213
 214 <!-- ##### FUNCTION gtk_label_get ##### -->
 215 <para>
 216 Gets the current string of text within the #GtkLabel and writes it to
 217 the given @str argument.  It does not make a copy of this string so you
 218 must not write to it.
 219 </para>
 220
 221 @label: The #GtkLabel widget you want to get the text from.
 222 @str: The reference to the pointer you want to point to the text.
 223
 224
 225 <!-- ##### FUNCTION gtk_label_parse_uline ##### -->
 226 <para>
 227 Parses the given string for underscores and converts the next
 228 character to an underlined character.  The last character that
 229 was underlined will have its lower-cased accelerator keyval returned  (i.e.
 230 &quot;_File&quot; would return the keyval for &quot;f&quot;.  This is
 231 probably only used within the Gtk+ library itself for menu items and such.
 232 </para>
 233
 234 @label: The #GtkLabel you want to affect.
 235 @string: The string you want to parse for underlines.
 236 @Returns: The lowercase keyval of the last character underlined.
 237
 238
 239 <!-- ##### FUNCTION gtk_label_set_line_wrap ##### -->
 240 <para>
 241
 242 </para>
 243
 244 @label:
 245 @wrap:
 246
 247
 248 <!-- ##### MACRO gtk_label_set ##### -->
 249 <para>
 250 Aliases gtk_label_set_text().  Probably used for backward compatibility with
 251 Gtk+ 1.0.x.
 252 </para>
 253
 254
 255
 256 <!-- ##### FUNCTION gtk_label_get_layout_offsets ##### -->
 257 <para>
 258
 259 </para>
 260
 261 @label:
 262 @x:
 263 @y:
 264
 265
 266 <!-- ##### FUNCTION gtk_label_get_mnemonic_keyval ##### -->
 267 <para>
 268
 269 </para>
 270
 271 @label:
 272 @Returns:
 273
 274
 275 <!-- ##### FUNCTION gtk_label_get_selectable ##### -->
 276 <para>
 277
 278 </para>
 279
 280 @label:
 281 @Returns:
 282
 283
 284 <!-- ##### FUNCTION gtk_label_get_text ##### -->
 285 <para>
 286
 287 </para>
 288
 289 @label:
 290 @Returns:
 291
 292
 293 <!-- ##### FUNCTION gtk_label_new_with_mnemonic ##### -->
 294 <para>
 295
 296 </para>
 297
 298 @str:
 299 @Returns:
 300
 301
 302 <!-- ##### FUNCTION gtk_label_select_region ##### -->
 303 <para>
 304
 305 </para>
 306
 307 @label:
 308 @start_offset:
 309 @end_offset:
 310
 311
 312 <!-- ##### FUNCTION gtk_label_set_mnemonic_widget ##### -->
 313 <para>
 314
 315 </para>
 316
 317 @label:
 318 @widget:
 319
 320
 321 <!-- ##### FUNCTION gtk_label_set_selectable ##### -->
 322 <para>
 323
 324 </para>
 325
 326 @label:
 327 @setting:
 328
 329
 330 <!-- ##### FUNCTION gtk_label_set_text_with_mnemonic ##### -->
 331 <para>
 332
 333 </para>
 334
 335 @label:
 336 @str:
 337
 338
 339 <!-- ##### FUNCTION gtk_label_get_attributes ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @label:
 345 @Returns:
 346
 347
 348 <!-- ##### FUNCTION gtk_label_get_justify ##### -->
 349 <para>
 350
 351 </para>
 352
 353 @label:
 354 @Returns:
 355
 356
 357 <!-- ##### FUNCTION gtk_label_get_label ##### -->
 358 <para>
 359
 360 </para>
 361
 362 @label:
 363 @Returns:
 364
 365
 366 <!-- ##### FUNCTION gtk_label_get_layout ##### -->
 367 <para>
 368
 369 </para>
 370
 371 @label:
 372 @Returns:
 373
 374
 375 <!-- ##### FUNCTION gtk_label_get_line_wrap ##### -->
 376 <para>
 377
 378 </para>
 379
 380 @label:
 381 @Returns:
 382
 383
 384 <!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### -->
 385 <para>
 386
 387 </para>
 388
 389 @label:
 390 @Returns:
 391
 392
 393 <!-- ##### FUNCTION gtk_label_get_selection_bounds ##### -->
 394 <para>
 395
 396 </para>
 397
 398 @label:
 399 @start:
 400 @end:
 401 @Returns:
 402
 403
 404 <!-- ##### FUNCTION gtk_label_get_use_markup ##### -->
 405 <para>
 406
 407 </para>
 408
 409 @label:
 410 @Returns:
 411
 412
 413 <!-- ##### FUNCTION gtk_label_get_use_underline ##### -->
 414 <para>
 415
 416 </para>
 417
 418 @label:
 419 @Returns:
 420
 421
 422 <!-- ##### FUNCTION gtk_label_set_label ##### -->
 423 <para>
 424
 425 </para>
 426
 427 @label:
 428 @str:
 429
 430
 431 <!-- ##### FUNCTION gtk_label_set_use_markup ##### -->
 432 <para>
 433
 434 </para>
 435
 436 @label:
 437 @setting:
 438
 439
 440 <!-- ##### FUNCTION gtk_label_set_use_underline ##### -->
 441 <para>
 442
 443 </para>
 444
 445 @label:
 446 @setting:
 447
 448
 449 <!-- ##### SIGNAL GtkLabel::copy-clipboard ##### -->
 450 <para>
 451
 452 </para>
 453
 454 @label: the object which received the signal.
 455
 456 <!-- ##### SIGNAL GtkLabel::move-cursor ##### -->
 457 <para>
 458
 459 </para>
 460
 461 @label: the object which received the signal.
 462 @arg1:
 463 @arg2:
 464 @arg3:
 465
 466 <!-- ##### SIGNAL GtkLabel::populate-popup ##### -->
 467 <para>
 468
 469 </para>
 470
 471 @label: the object which received the signal.
 472 @arg1:
 473
 474 <!-- ##### ARG GtkLabel:attributes ##### -->
 475 <para>
 476
 477 </para>
 478
 479 <!-- ##### ARG GtkLabel:cursor-position ##### -->
 480 <para>
 481
 482 </para>
 483
 484 <!-- ##### ARG GtkLabel:justify ##### -->
 485 <para>
 486
 487 </para>
 488
 489 <!-- ##### ARG GtkLabel:label ##### -->
 490 <para>
 491
 492 </para>
 493
 494 <!-- ##### ARG GtkLabel:mnemonic-keyval ##### -->
 495 <para>
 496
 497 </para>
 498
 499 <!-- ##### ARG GtkLabel:mnemonic-widget ##### -->
 500 <para>
 501
 502 </para>
 503
 504 <!-- ##### ARG GtkLabel:pattern ##### -->
 505 <para>
 506
 507 </para>
 508
 509 <!-- ##### ARG GtkLabel:selectable ##### -->
 510 <para>
 511
 512 </para>
 513
 514 <!-- ##### ARG GtkLabel:selection-bound ##### -->
 515 <para>
 516
 517 </para>
 518
 519 <!-- ##### ARG GtkLabel:use-markup ##### -->
 520 <para>
 521
 522 </para>
 523
 524 <!-- ##### ARG GtkLabel:use-underline ##### -->
 525 <para>
 526
 527 </para>
 528
 529 <!-- ##### ARG GtkLabel:wrap ##### -->
 530 <para>
 531
 532 </para>
 533