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 <!-- ##### STRUCT AtkText ##### -->
  35 <para>
  36 The AtkText structure does not contain any fields.
  37
  38 </para>
  39
  40
  41 <!-- ##### ENUM AtkTextBoundary ##### -->
  42 <para>
  43
  44 </para>
  45
  46 @ATK_TEXT_BOUNDARY_CHAR:
  47 @ATK_TEXT_BOUNDARY_WORD_START:
  48 @ATK_TEXT_BOUNDARY_WORD_END:
  49 @ATK_TEXT_BOUNDARY_SENTENCE_START:
  50 @ATK_TEXT_BOUNDARY_SENTENCE_END:
  51 @ATK_TEXT_BOUNDARY_LINE_START:
  52 @ATK_TEXT_BOUNDARY_LINE_END:
  53
  54 <!-- ##### ENUM AtkTextClipType ##### -->
  55 <para>
  56
  57 </para>
  58
  59 @ATK_TEXT_CLIP_NONE:
  60 @ATK_TEXT_CLIP_MIN:
  61 @ATK_TEXT_CLIP_MAX:
  62 @ATK_TEXT_CLIP_BOTH:
  63
  64 <!-- ##### STRUCT AtkTextRange ##### -->
  65 <para>
  66
  67 </para>
  68
  69 @bounds:
  70 @start_offset:
  71 @end_offset:
  72 @content:
  73
  74 <!-- ##### STRUCT AtkTextRectangle ##### -->
  75 <para>
  76
  77 </para>
  78
  79 @x:
  80 @y:
  81 @width:
  82 @height:
  83
  84 <!-- ##### STRUCT AtkAttribute ##### -->
  85 <para>
  86
  87 </para>
  88
  89 @name:
  90 @value:
  91
  92 <!-- ##### TYPEDEF AtkAttributeSet ##### -->
  93 <para>
  94
  95 </para>
  96
  97
  98 <!-- ##### ENUM AtkTextAttribute ##### -->
  99 <para>
 100
 101 </para>
 102
 103 @ATK_TEXT_ATTR_INVALID:
 104 @ATK_TEXT_ATTR_LEFT_MARGIN:
 105 @ATK_TEXT_ATTR_RIGHT_MARGIN:
 106 @ATK_TEXT_ATTR_INDENT:
 107 @ATK_TEXT_ATTR_INVISIBLE:
 108 @ATK_TEXT_ATTR_EDITABLE:
 109 @ATK_TEXT_ATTR_PIXELS_ABOVE_LINES:
 110 @ATK_TEXT_ATTR_PIXELS_BELOW_LINES:
 111 @ATK_TEXT_ATTR_PIXELS_INSIDE_WRAP:
 112 @ATK_TEXT_ATTR_BG_FULL_HEIGHT:
 113 @ATK_TEXT_ATTR_RISE:
 114 @ATK_TEXT_ATTR_UNDERLINE:
 115 @ATK_TEXT_ATTR_STRIKETHROUGH:
 116 @ATK_TEXT_ATTR_SIZE:
 117 @ATK_TEXT_ATTR_SCALE:
 118 @ATK_TEXT_ATTR_WEIGHT:
 119 @ATK_TEXT_ATTR_LANGUAGE:
 120 @ATK_TEXT_ATTR_FAMILY_NAME:
 121 @ATK_TEXT_ATTR_BG_COLOR:
 122 @ATK_TEXT_ATTR_FG_COLOR:
 123 @ATK_TEXT_ATTR_BG_STIPPLE:
 124 @ATK_TEXT_ATTR_FG_STIPPLE:
 125 @ATK_TEXT_ATTR_WRAP_MODE:
 126 @ATK_TEXT_ATTR_DIRECTION:
 127 @ATK_TEXT_ATTR_JUSTIFICATION:
 128 @ATK_TEXT_ATTR_STRETCH:
 129 @ATK_TEXT_ATTR_VARIANT:
 130 @ATK_TEXT_ATTR_STYLE:
 131 @ATK_TEXT_ATTR_LAST_DEFINED:
 132
 133 <!-- ##### FUNCTION atk_text_get_text ##### -->
 134 <para>
 135
 136 </para>
 137
 138 @text:
 139 @start_offset:
 140 @end_offset:
 141 @Returns:
 142
 143
 144 <!-- ##### FUNCTION atk_text_get_character_at_offset ##### -->
 145 <para>
 146
 147 </para>
 148
 149 @text:
 150 @offset:
 151 @Returns:
 152
 153
 154 <!-- ##### FUNCTION atk_text_get_text_after_offset ##### -->
 155 <para>
 156
 157 </para>
 158
 159 @text:
 160 @offset:
 161 @boundary_type:
 162 @start_offset:
 163 @end_offset:
 164 @Returns:
 165
 166
 167 <!-- ##### FUNCTION atk_text_get_text_at_offset ##### -->
 168 <para>
 169
 170 </para>
 171
 172 @text:
 173 @offset:
 174 @boundary_type:
 175 @start_offset:
 176 @end_offset:
 177 @Returns:
 178
 179
 180 <!-- ##### FUNCTION atk_text_get_text_before_offset ##### -->
 181 <para>
 182
 183 </para>
 184
 185 @text:
 186 @offset:
 187 @boundary_type:
 188 @start_offset:
 189 @end_offset:
 190 @Returns:
 191
 192
 193 <!-- ##### FUNCTION atk_text_get_caret_offset ##### -->
 194 <para>
 195
 196 </para>
 197
 198 @text:
 199 @Returns:
 200
 201
 202 <!-- ##### FUNCTION atk_text_get_character_extents ##### -->
 203 <para>
 204
 205 </para>
 206
 207 @text:
 208 @offset:
 209 @x:
 210 @y:
 211 @width:
 212 @height:
 213 @coords:
 214
 215
 216 <!-- ##### FUNCTION atk_text_get_run_attributes ##### -->
 217 <para>
 218
 219 </para>
 220
 221 @text:
 222 @offset:
 223 @start_offset:
 224 @end_offset:
 225 @Returns:
 226
 227
 228 <!-- ##### FUNCTION atk_text_get_default_attributes ##### -->
 229 <para>
 230
 231 </para>
 232
 233 @text:
 234 @Returns:
 235
 236
 237 <!-- ##### FUNCTION atk_text_get_character_count ##### -->
 238 <para>
 239
 240 </para>
 241
 242 @text:
 243 @Returns:
 244
 245
 246 <!-- ##### FUNCTION atk_text_get_offset_at_point ##### -->
 247 <para>
 248
 249 </para>
 250
 251 @text:
 252 @x:
 253 @y:
 254 @coords:
 255 @Returns:
 256
 257
 258 <!-- ##### FUNCTION atk_text_get_bounded_ranges ##### -->
 259 <para>
 260
 261 </para>
 262
 263 @text:
 264 @rect:
 265 @coord_type:
 266 @x_clip_type:
 267 @y_clip_type:
 268 @Returns:
 269
 270
 271 <!-- ##### FUNCTION atk_text_get_range_extents ##### -->
 272 <para>
 273
 274 </para>
 275
 276 @text:
 277 @start_offset:
 278 @end_offset:
 279 @coord_type:
 280 @rect:
 281
 282
 283 <!-- ##### FUNCTION atk_text_free_ranges ##### -->
 284 <para>
 285
 286 </para>
 287
 288 @ranges:
 289
 290
 291 <!-- ##### FUNCTION atk_text_get_n_selections ##### -->
 292 <para>
 293
 294 </para>
 295
 296 @text:
 297 @Returns:
 298
 299
 300 <!-- ##### FUNCTION atk_text_get_selection ##### -->
 301 <para>
 302
 303 </para>
 304
 305 @text:
 306 @selection_num:
 307 @start_offset:
 308 @end_offset:
 309 @Returns:
 310
 311
 312 <!-- ##### FUNCTION atk_text_add_selection ##### -->
 313 <para>
 314
 315 </para>
 316
 317 @text:
 318 @start_offset:
 319 @end_offset:
 320 @Returns:
 321
 322
 323 <!-- ##### FUNCTION atk_text_remove_selection ##### -->
 324 <para>
 325
 326 </para>
 327
 328 @text:
 329 @selection_num:
 330 @Returns:
 331
 332
 333 <!-- ##### FUNCTION atk_text_set_selection ##### -->
 334 <para>
 335
 336 </para>
 337
 338 @text:
 339 @selection_num:
 340 @start_offset:
 341 @end_offset:
 342 @Returns:
 343
 344
 345 <!-- ##### FUNCTION atk_text_set_caret_offset ##### -->
 346 <para>
 347
 348 </para>
 349
 350 @text:
 351 @offset:
 352 @Returns:
 353
 354
 355 <!-- ##### FUNCTION atk_attribute_set_free ##### -->
 356 <para>
 357
 358 </para>
 359
 360 @attrib_set:
 361
 362
 363 <!-- ##### FUNCTION atk_text_attribute_register ##### -->
 364 <para>
 365
 366 </para>
 367
 368 @name:
 369 @Returns:
 370
 371
 372 <!-- ##### FUNCTION atk_text_attribute_get_name ##### -->
 373 <para>
 374
 375 </para>
 376
 377 @attr:
 378 @Returns:
 379
 380
 381 <!-- ##### FUNCTION atk_text_attribute_for_name ##### -->
 382 <para>
 383
 384 </para>
 385
 386 @name:
 387 @Returns:
 388
 389
 390 <!-- ##### FUNCTION atk_text_attribute_get_value ##### -->
 391 <para>
 392
 393 </para>
 394
 395 @attr:
 396 @index_:
 397 @Returns:
 398
 399
 400 <!-- ##### SIGNAL AtkText::text-attributes-changed ##### -->
 401 <para>
 402 The "text-attributes-changed" signal is emitted when the text attributes of
 403 the text of an object which implements AtkText changes.
 404 </para>
 405
 406 @atktext: the object which received the signal.
 407
 408 <!-- ##### SIGNAL AtkText::text-caret-moved ##### -->
 409 <para>
 410 The "text-caret-moved" signal is emitted when the caret position of
 411 the text of an object which implements AtkText changes.
 412 </para>
 413
 414 @atktext: the object which received the signal.
 415 @arg1: The new position of the text caret.
 416
 417 <!-- ##### SIGNAL AtkText::text-changed ##### -->
 418 <para>
 419 The "text-changed" signal is emitted when the text of the object which
 420 implements the AtkText interface changes, This signal will have a detail
 421 which is either "insert" or "delete" which identifies whether the text
 422 change was an insertion or a deletion
 423 </para>
 424
 425 @atktext: the object which received the signal.
 426 @arg1: The position of the insertion or deletion.
 427 @arg2: The length of text inserted or deleted.
 428
 429 <!-- ##### SIGNAL AtkText::text-selection-changed ##### -->
 430 <para>
 431 The "text-selection-changed" signal is emitted when the selected text of
 432 an object which implements AtkText changes.
 433
 434 </para>
 435
 436 @atktext: the object which received the signal.
 437