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