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>\r
   9 The #GtkLabel widget is usually used directly by the programmer to display\r
  10 word(s) describing an adjacent widget or its use.  It is also used internally\r
  11 by Gtk+ as #GtkButton labels, #GtkMenu items, and many other widgets which\r
  12 use text.\r
  13 </para>
  14
  15 <!-- ##### SECTION See_Also ##### -->
  16 <para>\r
  17 \r
  18 </para>
  19
  20 <!-- ##### STRUCT GtkLabel ##### -->
  21 <para>\r
  22 This should not be accessed directly.  Use the accessor functions as\r
  23 described below.\r
  24 </para>
  25
  26
  27 <!-- ##### FUNCTION gtk_label_new ##### -->
  28 <para>\r
  29 Creates a new label with the given string of text inside it.  You can\r
  30 pass NULL to get an empty label widget.\r
  31 </para>
  32
  33 @str: The string you want to display in the #GtkLabel
  34 @Returns: The newly allocated #GtkLabel widget
  35
  36
  37 <!-- ##### FUNCTION gtk_label_set_text ##### -->
  38 <para>\r
  39 Sets the text within the #GtkLabel widget.  It overwrites any text that\r
  40 was there before.  Note that underlines that were there before do not\r
  41 get overwritten.  If you want to erase underlines just send NULL to\r
  42 gtk_label_set_pattern().\r
  43 </para>
  44
  45 @label: The #GtkLabel you want to set the text for.
  46 @str: The text you want to add.
  47
  48
  49 <!-- ##### FUNCTION gtk_label_set_attributes ##### -->
  50 <para>
  51
  52 </para>
  53
  54 @label:
  55 @attrs:
  56
  57
  58 <!-- ##### FUNCTION gtk_label_set_markup ##### -->
  59 <para>
  60
  61 </para>
  62
  63 @label:
  64 @str:
  65
  66
  67 <!-- ##### FUNCTION gtk_label_set_markup_with_mnemonic ##### -->
  68 <para>
  69
  70 </para>
  71
  72 @label:
  73 @str:
  74
  75
  76 <!-- ##### FUNCTION gtk_label_set_pattern ##### -->
  77 <para>\r
  78 The pattern of underlines you want under the existing text within the\r
  79 #GtkLabel widget.  For example if the current text of the label says\r
  80 &quot;FooBarBaz&quot; passing a pattern of &quot;___   ___&quot; will underline\r
  81 &quot;Foo&quot; and &quot;Baz&quot; but not &quot;Bar&quot;.\r
  82 </para>
  83
  84 @label: The #GtkLabel you want to set the pattern to.
  85 @pattern: The pattern as described above.
  86
  87
  88 <!-- ##### FUNCTION gtk_label_set_justify ##### -->
  89 <para>\r
  90 Set where the text within the #GtkLabel will align to.  This can be one of\r
  91 four values: GTK_JUSTIFY_LEFT, GTK_JUSTIFY_RIGHT, GTK_JUSTIFY_CENTER,\r
  92 and GTK_JUSTIFY_FILL.  GTK_JUSTIFY_CENTER is the default value when the\r
  93 widget is first created with gtk_label_new().\r
  94 </para>
  95
  96 @label: The #GtkLabel widget you want to set justification for.
  97 @jtype: The #GtkJustification type as described above.
  98
  99
 100 <!-- ##### FUNCTION gtk_label_get ##### -->
 101 <para>\r
 102 Gets the current string of text within the #GtkLabel and writes it to\r
 103 the given str argument.  It does not make a copy of this string so you\r
 104 must not write to it.\r
 105 </para>
 106
 107 @label: The #GtkLabel widget you want to get the text from.
 108 @str: The reference to the pointer you want to point to the text.
 109
 110
 111 <!-- ##### FUNCTION gtk_label_parse_uline ##### -->
 112 <para>\r
 113 Parses the given string for underscores and converts the next\r
 114 character to an underlined character.  The last character that\r
 115 was underlined will have its lower-cased accelerator keyval returned  (i.e.\r
 116 &quot;_File&quot; would return the keyval for &quot;f&quot;.  This is\r
 117 probably only used within the Gtk+ library itself for menu items and such.\r
 118 </para>
 119
 120 @label: The #GtkLabel you want to affect.
 121 @string: The string you want to parse for underlines.
 122 @Returns: The lowercase keyval of the last character underlined.
 123
 124
 125 <!-- ##### FUNCTION gtk_label_set_line_wrap ##### -->
 126 <para>\r
 127 Toggles line wrapping within the #GtkLabel widget.  TRUE makes it break\r
 128 lines if text exceeds the widget's size.  FALSE lets the text get cut off\r
 129 by the edge of the widget if it exceeds the widget size.\r
 130 </para>
 131
 132 @label: The #GtkLabel you want to set line wrapping for.
 133 @wrap: TRUE turns it on; FALSE turns it off.
 134
 135
 136 <!-- ##### MACRO gtk_label_set ##### -->
 137 <para>\r
 138 Aliases gtk_label_set_text.  Probably used for backward compatibility with\r
 139 Gtk+ 1.0.x.\r
 140 </para>
 141
 142
 143
 144 <!-- ##### FUNCTION gtk_label_get_layout_offsets ##### -->
 145 <para>
 146
 147 </para>
 148
 149 @label:
 150 @x:
 151 @y:
 152
 153
 154 <!-- ##### FUNCTION gtk_label_get_mnemonic_keyval ##### -->
 155 <para>
 156
 157 </para>
 158
 159 @label:
 160 @Returns:
 161
 162
 163 <!-- ##### FUNCTION gtk_label_get_selectable ##### -->
 164 <para>
 165
 166 </para>
 167
 168 @label:
 169 @Returns:
 170
 171
 172 <!-- ##### FUNCTION gtk_label_get_text ##### -->
 173 <para>
 174
 175 </para>
 176
 177 @label:
 178 @Returns:
 179
 180
 181 <!-- ##### FUNCTION gtk_label_new_with_mnemonic ##### -->
 182 <para>
 183
 184 </para>
 185
 186 @str:
 187 @Returns:
 188
 189
 190 <!-- ##### FUNCTION gtk_label_select_region ##### -->
 191 <para>
 192
 193 </para>
 194
 195 @label:
 196 @start_offset:
 197 @end_offset:
 198
 199
 200 <!-- ##### FUNCTION gtk_label_set_mnemonic_widget ##### -->
 201 <para>
 202
 203 </para>
 204
 205 @label:
 206 @widget:
 207
 208
 209 <!-- ##### FUNCTION gtk_label_set_selectable ##### -->
 210 <para>
 211
 212 </para>
 213
 214 @label:
 215 @setting:
 216
 217
 218 <!-- ##### FUNCTION gtk_label_set_text_with_mnemonic ##### -->
 219 <para>
 220
 221 </para>
 222
 223 @label:
 224 @str:
 225 <!-- # Unused Parameters # -->
 226 @string:
 227
 228
 229 <!-- ##### FUNCTION gtk_label_get_attributes ##### -->
 230 <para>
 231
 232 </para>
 233
 234 @label:
 235 @Returns:
 236
 237
 238 <!-- ##### FUNCTION gtk_label_get_justify ##### -->
 239 <para>
 240
 241 </para>
 242
 243 @label:
 244 @Returns:
 245
 246
 247 <!-- ##### FUNCTION gtk_label_get_label ##### -->
 248 <para>
 249
 250 </para>
 251
 252 @label:
 253 @Returns:
 254
 255
 256 <!-- ##### FUNCTION gtk_label_get_layout ##### -->
 257 <para>
 258
 259 </para>
 260
 261 @label:
 262 @Returns:
 263
 264
 265 <!-- ##### FUNCTION gtk_label_get_line_wrap ##### -->
 266 <para>
 267
 268 </para>
 269
 270 @label:
 271 @Returns:
 272
 273
 274 <!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### -->
 275 <para>
 276
 277 </para>
 278
 279 @label:
 280 @Returns:
 281
 282
 283 <!-- ##### FUNCTION gtk_label_get_selection_bounds ##### -->
 284 <para>
 285
 286 </para>
 287
 288 @label:
 289 @start:
 290 @end:
 291 @Returns:
 292
 293
 294 <!-- ##### FUNCTION gtk_label_get_use_markup ##### -->
 295 <para>
 296
 297 </para>
 298
 299 @label:
 300 @Returns:
 301
 302
 303 <!-- ##### FUNCTION gtk_label_get_use_underline ##### -->
 304 <para>
 305
 306 </para>
 307
 308 @label:
 309 @Returns:
 310
 311
 312 <!-- ##### FUNCTION gtk_label_set_label ##### -->
 313 <para>
 314
 315 </para>
 316
 317 @label:
 318 @str:
 319
 320
 321 <!-- ##### FUNCTION gtk_label_set_use_markup ##### -->
 322 <para>
 323
 324 </para>
 325
 326 @label:
 327 @setting:
 328
 329
 330 <!-- ##### FUNCTION gtk_label_set_use_underline ##### -->
 331 <para>
 332
 333 </para>
 334
 335 @label:
 336 @setting:
 337
 338
 339 <!-- ##### SIGNAL GtkLabel::copy-clipboard ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @label: the object which received the signal.
 345
 346 <!-- ##### SIGNAL GtkLabel::move-cursor ##### -->
 347 <para>
 348
 349 </para>
 350
 351 @label: the object which received the signal.
 352 @arg1:
 353 @arg2:
 354 @arg3:
 355
 356 <!-- ##### SIGNAL GtkLabel::populate-popup ##### -->
 357 <para>
 358
 359 </para>
 360
 361 @label: the object which received the signal.
 362 @arg1:
 363
 364 <!-- ##### ARG GtkLabel:label ##### -->
 365 <para>\r
 366 The actual label text.  Do not write to this pointer, it is not copied.\r
 367 </para>
 368
 369 <!-- ##### ARG GtkLabel:attributes ##### -->
 370 <para>
 371
 372 </para>
 373
 374 <!-- ##### ARG GtkLabel:use-markup ##### -->
 375 <para>
 376
 377 </para>
 378
 379 <!-- ##### ARG GtkLabel:use-underline ##### -->
 380 <para>
 381
 382 </para>
 383
 384 <!-- ##### ARG GtkLabel:justify ##### -->
 385 <para>\r
 386 The #GtkJustification setting.  See gtk_label_set_justify() for more info.\r
 387 </para>
 388
 389 <!-- ##### ARG GtkLabel:pattern ##### -->
 390 <para>\r
 391 The pattern of underlines under the existing text.  Do not change the\r
 392 pointer, it isn't copied.\r
 393 </para>
 394
 395 <!-- ##### ARG GtkLabel:wrap ##### -->
 396 <para>
 397
 398 </para>
 399
 400 <!-- ##### ARG GtkLabel:selectable ##### -->
 401 <para>
 402
 403 </para>
 404
 405 <!-- ##### ARG GtkLabel:mnemonic-keyval ##### -->
 406 <para>
 407
 408 </para>
 409
 410 <!-- ##### ARG GtkLabel:mnemonic-widget ##### -->
 411 <para>
 412
 413 </para>
 414
 415 <!-- ##### ARG GtkLabel:cursor-position ##### -->
 416 <para>
 417
 418 </para>
 419
 420 <!-- ##### ARG GtkLabel:selection-bound ##### -->
 421 <para>
 422
 423 </para>
 424