docs/tmpl/atktext.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 AtkText
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 The ATK interface implemented by components with text content.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 #AtkText should be implemented by #AtkObjects on behalf of widgets that
  10 have text content which is either attributed or otherwise non-trivial.
  11 #AtkObjects whose text content is simple, unattributed, and very brief
  12 may expose that content via #atk_object_get_name instead; however if the
  13 text is editable, multi-line, typically longer than three or four words,
  14 attributed, selectable, or if the object already uses the 'name' ATK
  15 property for other information, the #AtkText interface should be used
  16 to expose the text content.  In the case of editable text content,
  17 #AtkEditableText (a subtype of the #AtkText interface) should be
  18 implemented instead.
  19 </para>
  20 <para>
  21 #AtkText provides not only traversal facilities and change notification
  22 for text content, but also caret tracking and glyph bounding box
  23 calculations.  Note that the text strings are exposed as UTF-8, and are
  24 therefore potentially multi-byte, and caret-to-byte offset mapping makes
  25 no assumptions about the character length; also bounding box
  26 glyph-to-offset mapping may be complex for languages which use ligatures.
  27 </para>
  28
  29 <!-- ##### SECTION See_Also ##### -->
  30 <para>
  31
  32 </para>
  33
  34 <!-- ##### SECTION Stability_Level ##### -->
  35
  36
  37 <!-- ##### SECTION Image ##### -->
  38
  39
  40 <!-- ##### STRUCT AtkText ##### -->
  41 <para>
  42 The AtkText structure does not contain any fields.
  43
  44 </para>
  45
  46
  47 <!-- ##### SIGNAL AtkText::text-attributes-changed ##### -->
  48 <para>
  49 The "text-attributes-changed" signal is emitted when the text attributes of
  50 the text of an object which implements AtkText changes.
  51 </para>
  52
  53 @atktext: the object which received the signal.
  54
  55 <!-- ##### SIGNAL AtkText::text-caret-moved ##### -->
  56 <para>
  57 The "text-caret-moved" signal is emitted when the caret position of
  58 the text of an object which implements AtkText changes.
  59 </para>
  60
  61 @atktext: the object which received the signal.
  62 @arg1: The new position of the text caret.
  63
  64 <!-- ##### SIGNAL AtkText::text-changed ##### -->
  65 <para>
  66 The "text-changed" signal is emitted when the text of the object which
  67 implements the AtkText interface changes, This signal will have a detail
  68 which is either "insert" or "delete" which identifies whether the text
  69 change was an insertion or a deletion
  70 </para>
  71
  72 @atktext: the object which received the signal.
  73 @arg1: The position (character offset) of the insertion or deletion.
  74 @arg2: The length (in characters) of text inserted or deleted.
  75
  76 <!-- ##### SIGNAL AtkText::text-insert ##### -->
  77 <para>
  78
  79 </para>
  80
  81 @atktext: the object which received the signal.
  82 @arg1:
  83 @arg2:
  84 @arg3:
  85
  86 <!-- ##### SIGNAL AtkText::text-remove ##### -->
  87 <para>
  88
  89 </para>
  90
  91 @atktext: the object which received the signal.
  92 @arg1:
  93 @arg2:
  94 @arg3:
  95
  96 <!-- ##### SIGNAL AtkText::text-selection-changed ##### -->
  97 <para>
  98 The "text-selection-changed" signal is emitted when the selected text of
  99 an object which implements AtkText changes.
 100
 101 </para>
 102
 103 @atktext: the object which received the signal.
 104
 105 <!-- ##### SIGNAL AtkText::text-update ##### -->
 106 <para>
 107
 108 </para>
 109
 110 @atktext: the object which received the signal.
 111 @arg1:
 112 @arg2:
 113 @arg3:
 114 @arg4:
 115
 116 <!-- ##### ENUM AtkTextBoundary ##### -->
 117 <para>
 118
 119 </para>
 120
 121 @ATK_TEXT_BOUNDARY_CHAR:
 122 @ATK_TEXT_BOUNDARY_WORD_START:
 123 @ATK_TEXT_BOUNDARY_WORD_END:
 124 @ATK_TEXT_BOUNDARY_SENTENCE_START:
 125 @ATK_TEXT_BOUNDARY_SENTENCE_END:
 126 @ATK_TEXT_BOUNDARY_LINE_START:
 127 @ATK_TEXT_BOUNDARY_LINE_END:
 128
 129 <!-- ##### ENUM AtkTextClipType ##### -->
 130 <para>
 131
 132 </para>
 133
 134 @ATK_TEXT_CLIP_NONE:
 135 @ATK_TEXT_CLIP_MIN:
 136 @ATK_TEXT_CLIP_MAX:
 137 @ATK_TEXT_CLIP_BOTH:
 138
 139 <!-- ##### STRUCT AtkTextRange ##### -->
 140 <para>
 141
 142 </para>
 143
 144 @bounds:
 145 @start_offset:
 146 @end_offset:
 147 @content:
 148
 149 <!-- ##### STRUCT AtkTextRectangle ##### -->
 150 <para>
 151
 152 </para>
 153
 154 @x:
 155 @y:
 156 @width:
 157 @height:
 158
 159 <!-- ##### STRUCT AtkAttribute ##### -->
 160 <para>
 161
 162 </para>
 163
 164 @name:
 165 @value:
 166
 167 <!-- ##### TYPEDEF AtkAttributeSet ##### -->
 168 <para>
 169
 170 </para>
 171
 172
 173 <!-- ##### ENUM AtkTextAttribute ##### -->
 174 <para>
 175
 176 </para>
 177
 178 @ATK_TEXT_ATTR_INVALID:
 179 @ATK_TEXT_ATTR_LEFT_MARGIN:
 180 @ATK_TEXT_ATTR_RIGHT_MARGIN:
 181 @ATK_TEXT_ATTR_INDENT:
 182 @ATK_TEXT_ATTR_INVISIBLE:
 183 @ATK_TEXT_ATTR_EDITABLE:
 184 @ATK_TEXT_ATTR_PIXELS_ABOVE_LINES:
 185 @ATK_TEXT_ATTR_PIXELS_BELOW_LINES:
 186 @ATK_TEXT_ATTR_PIXELS_INSIDE_WRAP:
 187 @ATK_TEXT_ATTR_BG_FULL_HEIGHT:
 188 @ATK_TEXT_ATTR_RISE:
 189 @ATK_TEXT_ATTR_UNDERLINE:
 190 @ATK_TEXT_ATTR_STRIKETHROUGH:
 191 @ATK_TEXT_ATTR_SIZE:
 192 @ATK_TEXT_ATTR_SCALE:
 193 @ATK_TEXT_ATTR_WEIGHT:
 194 @ATK_TEXT_ATTR_LANGUAGE:
 195 @ATK_TEXT_ATTR_FAMILY_NAME:
 196 @ATK_TEXT_ATTR_BG_COLOR:
 197 @ATK_TEXT_ATTR_FG_COLOR:
 198 @ATK_TEXT_ATTR_BG_STIPPLE:
 199 @ATK_TEXT_ATTR_FG_STIPPLE:
 200 @ATK_TEXT_ATTR_WRAP_MODE:
 201 @ATK_TEXT_ATTR_DIRECTION:
 202 @ATK_TEXT_ATTR_JUSTIFICATION:
 203 @ATK_TEXT_ATTR_STRETCH:
 204 @ATK_TEXT_ATTR_VARIANT:
 205 @ATK_TEXT_ATTR_STYLE:
 206 @ATK_TEXT_ATTR_LAST_DEFINED:
 207
 208 <!-- ##### FUNCTION atk_text_get_text ##### -->
 209 <para>
 210
 211 </para>
 212
 213 @text:
 214 @start_offset:
 215 @end_offset:
 216 @Returns:
 217
 218
 219 <!-- ##### FUNCTION atk_text_get_character_at_offset ##### -->
 220 <para>
 221
 222 </para>
 223
 224 @text:
 225 @offset:
 226 @Returns:
 227
 228
 229 <!-- ##### FUNCTION atk_text_get_text_after_offset ##### -->
 230 <para>
 231
 232 </para>
 233
 234 @text:
 235 @offset:
 236 @boundary_type:
 237 @start_offset:
 238 @end_offset:
 239 @Returns:
 240
 241
 242 <!-- ##### FUNCTION atk_text_get_text_at_offset ##### -->
 243 <para>
 244
 245 </para>
 246
 247 @text:
 248 @offset:
 249 @boundary_type:
 250 @start_offset:
 251 @end_offset:
 252 @Returns:
 253
 254
 255 <!-- ##### FUNCTION atk_text_get_text_before_offset ##### -->
 256 <para>
 257
 258 </para>
 259
 260 @text:
 261 @offset:
 262 @boundary_type:
 263 @start_offset:
 264 @end_offset:
 265 @Returns:
 266
 267
 268 <!-- ##### FUNCTION atk_text_get_caret_offset ##### -->
 269 <para>
 270
 271 </para>
 272
 273 @text:
 274 @Returns:
 275
 276
 277 <!-- ##### FUNCTION atk_text_get_character_extents ##### -->
 278 <para>
 279
 280 </para>
 281
 282 @text:
 283 @offset:
 284 @x:
 285 @y:
 286 @width:
 287 @height:
 288 @coords:
 289
 290
 291 <!-- ##### FUNCTION atk_text_get_run_attributes ##### -->
 292 <para>
 293
 294 </para>
 295
 296 @text:
 297 @offset:
 298 @start_offset:
 299 @end_offset:
 300 @Returns:
 301
 302
 303 <!-- ##### FUNCTION atk_text_get_default_attributes ##### -->
 304 <para>
 305
 306 </para>
 307
 308 @text:
 309 @Returns:
 310
 311
 312 <!-- ##### FUNCTION atk_text_get_character_count ##### -->
 313 <para>
 314
 315 </para>
 316
 317 @text:
 318 @Returns:
 319
 320
 321 <!-- ##### FUNCTION atk_text_get_offset_at_point ##### -->
 322 <para>
 323
 324 </para>
 325
 326 @text:
 327 @x:
 328 @y:
 329 @coords:
 330 @Returns:
 331
 332
 333 <!-- ##### FUNCTION atk_text_get_bounded_ranges ##### -->
 334 <para>
 335
 336 </para>
 337
 338 @text:
 339 @rect:
 340 @coord_type:
 341 @x_clip_type:
 342 @y_clip_type:
 343 @Returns:
 344
 345
 346 <!-- ##### FUNCTION atk_text_get_range_extents ##### -->
 347 <para>
 348
 349 </para>
 350
 351 @text:
 352 @start_offset:
 353 @end_offset:
 354 @coord_type:
 355 @rect:
 356
 357
 358 <!-- ##### FUNCTION atk_text_free_ranges ##### -->
 359 <para>
 360
 361 </para>
 362
 363 @ranges:
 364
 365
 366 <!-- ##### FUNCTION atk_text_get_n_selections ##### -->
 367 <para>
 368
 369 </para>
 370
 371 @text:
 372 @Returns:
 373
 374
 375 <!-- ##### FUNCTION atk_text_get_selection ##### -->
 376 <para>
 377
 378 </para>
 379
 380 @text:
 381 @selection_num:
 382 @start_offset:
 383 @end_offset:
 384 @Returns:
 385
 386
 387 <!-- ##### FUNCTION atk_text_add_selection ##### -->
 388 <para>
 389
 390 </para>
 391
 392 @text:
 393 @start_offset:
 394 @end_offset:
 395 @Returns:
 396
 397
 398 <!-- ##### FUNCTION atk_text_remove_selection ##### -->
 399 <para>
 400
 401 </para>
 402
 403 @text:
 404 @selection_num:
 405 @Returns:
 406
 407
 408 <!-- ##### FUNCTION atk_text_set_selection ##### -->
 409 <para>
 410
 411 </para>
 412
 413 @text:
 414 @selection_num:
 415 @start_offset:
 416 @end_offset:
 417 @Returns:
 418
 419
 420 <!-- ##### FUNCTION atk_text_set_caret_offset ##### -->
 421 <para>
 422
 423 </para>
 424
 425 @text:
 426 @offset:
 427 @Returns:
 428
 429
 430 <!-- ##### FUNCTION atk_attribute_set_free ##### -->
 431 <para>
 432
 433 </para>
 434
 435 @attrib_set:
 436
 437
 438 <!-- ##### FUNCTION atk_text_attribute_register ##### -->
 439 <para>
 440
 441 </para>
 442
 443 @name:
 444 @Returns:
 445
 446
 447 <!-- ##### FUNCTION atk_text_attribute_get_name ##### -->
 448 <para>
 449
 450 </para>
 451
 452 @attr:
 453 @Returns:
 454
 455
 456 <!-- ##### FUNCTION atk_text_attribute_for_name ##### -->
 457 <para>
 458
 459 </para>
 460
 461 @name:
 462 @Returns:
 463
 464
 465 <!-- ##### FUNCTION atk_text_attribute_get_value ##### -->
 466 <para>
 467
 468 </para>
 469
 470 @attr:
 471 @index_:
 472 @Returns:
 473
 474