24
24
#include <string.h>
28
* @Short_description: The ATK interface implemented by components
32
* #AtkText should be implemented by #AtkObjects on behalf of widgets
33
* that have text content which is either attributed or otherwise
34
* non-trivial. #AtkObjects whose text content is simple,
35
* unattributed, and very brief may expose that content via
36
* #atk_object_get_name instead; however if the text is editable,
37
* multi-line, typically longer than three or four words, attributed,
38
* selectable, or if the object already uses the 'name' ATK property
39
* for other information, the #AtkText interface should be used to
40
* expose the text content. In the case of editable text content,
41
* #AtkEditableText (a subtype of the #AtkText interface) should be
42
* implemented instead.
44
* #AtkText provides not only traversal facilities and change
45
* notification for text content, but also caret tracking and glyph
46
* bounding box calculations. Note that the text strings are exposed
47
* as UTF-8, and are therefore potentially multi-byte, and
48
* caret-to-byte offset mapping makes no assumptions about the
49
* character length; also bounding box glyph-to-offset mapping may be
50
* complex for languages which use ligatures.
26
53
static GPtrArray *extra_attributes = NULL;
162
188
class->get_range_extents = atk_text_real_get_range_extents;
163
189
class->get_bounded_ranges = atk_text_real_get_bounded_ranges;
192
* AtkText::text-changed:
193
* @atktext: the object which received the signal.
194
* @arg1: The position (character offset) of the insertion or deletion.
195
* @arg2: The length (in characters) of text inserted or deleted.
197
* The "text-changed" signal is emitted when the text of the
198
* object which implements the AtkText interface changes, This
199
* signal will have a detail which is either "insert" or
200
* "delete" which identifies whether the text change was an
201
* insertion or a deletion.
203
* Deprecated: Since 2.9.4. Use #AtkObject::text-insert or
204
* #AtkObject::text-remove instead.
165
206
atk_text_signals[TEXT_CHANGED] =
166
207
g_signal_new ("text_changed",
173
214
2, G_TYPE_INT, G_TYPE_INT);
217
* AtkText::text-insert:
218
* @atktext: the object which received the signal.
219
* @arg1: The position (character offset) of the insertion.
220
* @arg2: The length (in characters) of text inserted.
221
* @arg3: The new text inserted
223
* The "text-insert" signal is emitted when a new text is
175
226
atk_text_signals[TEXT_INSERT] =
176
227
g_signal_new ("text_insert",
183
234
3, G_TYPE_INT, G_TYPE_INT, G_TYPE_STRING);
237
* AtkText::text-remove:
238
* @atktext: the object which received the signal.
239
* @arg1: The position (character offset) of the removal.
240
* @arg2: The length (in characters) of text removed.
241
* @arg3: The old text removed
243
* The "text-remove" signal is emitted when a new text is
185
246
atk_text_signals[TEXT_REMOVE] =
186
247
g_signal_new ("text_remove",
193
254
3, G_TYPE_INT, G_TYPE_INT, G_TYPE_STRING);
195
atk_text_signals[TEXT_UPDATE] =
196
g_signal_new ("text_update",
198
G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
200
(GSignalAccumulator) NULL, NULL,
201
atk_marshal_VOID__INT_INT_INT_STRING,
203
4, G_TYPE_INT, G_TYPE_INT, G_TYPE_INT, G_TYPE_STRING);
257
* AtkText::text-caret-moved:
258
* @atktext: the object which received the signal.
259
* @arg1: The new position of the text caret.
261
* The "text-caret-moved" signal is emitted when the caret
262
* position of the text of an object which implements AtkText
205
265
atk_text_signals[TEXT_CARET_MOVED] =
206
266
g_signal_new ("text_caret_moved",
211
271
g_cclosure_marshal_VOID__INT,
276
* AtkText::text-selection-changed:
277
* @atktext: the object which received the signal.
279
* The "text-selection-changed" signal is emitted when the
280
* selected text of an object which implements AtkText changes.
214
282
atk_text_signals[TEXT_SELECTION_CHANGED] =
215
283
g_signal_new ("text_selection_changed",
219
287
(GSignalAccumulator) NULL, NULL,
220
288
g_cclosure_marshal_VOID__VOID,
291
* AtkText::text-attributes-changed:
292
* @atktext: the object which received the signal.
294
* The "text-attributes-changed" signal is emitted when the text
295
* attributes of the text of an object which implements AtkText
222
298
atk_text_signals[TEXT_ATTRIBUTES_CHANGED] =
223
299
g_signal_new ("text_attributes_changed",
302
378
* Gets the specified text.
304
* If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character after the
305
* offset is returned.
307
* If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string
308
* is from the word start after the offset to the next word start.
310
* The returned string will contain the word after the offset if the offset
311
* is inside a word or if the offset is not inside a word.
313
* If the boundary_type is ATK_TEXT_BOUNDARY_WORD_END the returned string
314
* is from the word end at or after the offset to the next work end.
316
* The returned string will contain the word after the offset if the offset
317
* is inside a word and will contain the word after the word after the offset
318
* if the offset is not inside a word.
320
* If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned
321
* string is from the sentence start after the offset to the next sentence
324
* The returned string will contain the sentence after the offset if the offset
325
* is inside a sentence or if the offset is not inside a sentence.
327
* If the boundary_type is ATK_TEXT_BOUNDARY_SENTENCE_END the returned string
328
* is from the sentence end at or after the offset to the next sentence end.
330
* The returned string will contain the sentence after the offset if the offset
331
* is inside a sentence and will contain the sentence after the sentence
332
* after the offset if the offset is not inside a sentence.
334
* If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned
335
* string is from the line start after the offset to the next line start.
337
* If the boundary_type is ATK_TEXT_BOUNDARY_LINE_END the returned string
338
* is from the line end at or after the offset to the next line end.
380
* Deprecated: This method is deprecated since ATK version
381
* 2.9.3. Please use atk_text_get_string_at_offset() instead.
340
383
* Returns: a newly allocated string containing the text after @offset bounded
341
384
* by the specified @boundary_type. Use g_free() to free the returned string.
388
431
* offset is returned.
390
433
* If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string
391
* is from the word start at or before the offset to the word start after
434
* is from the word start at or before the offset to the word start after
394
437
* The returned string will contain the word at the offset if the offset
395
* is inside a word and will contain the word before the offset if the
396
* offset is not inside a word.
398
* If the boundary_type is ATK_TEXT_BOUNDARY_WORD_END the returned string
399
* is from the word end before the offset to the word end at or after the
402
* The returned string will contain the word at the offset if the offset
403
* is inside a word and will contain the word after to the offset if the
438
* is inside a word and will contain the word before the offset if the
404
439
* offset is not inside a word.
406
441
* If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned
408
443
* start after the offset.
410
445
* The returned string will contain the sentence at the offset if the offset
411
* is inside a sentence and will contain the sentence before the offset
412
* if the offset is not inside a sentence.
414
* If the boundary_type is ATK_TEXT_BOUNDARY_SENTENCE_END the returned string
415
* is from the sentence end before the offset to the sentence end at or
418
* The returned string will contain the sentence at the offset if the offset
419
* is inside a sentence and will contain the sentence after the offset
446
* is inside a sentence and will contain the sentence before the offset
420
447
* if the offset is not inside a sentence.
422
449
* If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned
423
450
* string is from the line start at or before the offset to the line
424
451
* start after the offset.
426
* If the boundary_type is ATK_TEXT_BOUNDARY_LINE_END the returned string
427
* is from the line end before the offset to the line end at or after
453
* Deprecated: This method is deprecated since ATK version
454
* 2.9.4. Please use atk_text_get_string_at_offset() instead.
430
456
* Returns: a newly allocated string containing the text at @offset bounded by
431
457
* the specified @boundary_type. Use g_free() to free the returned string.
472
498
* Gets the specified text.
474
* If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character before the
475
* offset is returned.
477
* If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string
478
* is from the word start before the word start before or at the offset to
479
* the word start before or at the offset.
481
* The returned string will contain the word before the offset if the offset
482
* is inside a word and will contain the word before the word before the
483
* offset if the offset is not inside a word.
485
* If the boundary_type is ATK_TEXT_BOUNDARY_WORD_END the returned string
486
* is from the word end before the word end before the offset to the word
487
* end before the offset.
489
* The returned string will contain the word before the offset if the offset
490
* is inside a word or if the offset is not inside a word.
492
* If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned
493
* string is from the sentence start before the sentence start before
494
* the offset to the sentence start before the offset.
496
* The returned string will contain the sentence before the offset if the
497
* offset is inside a sentence and will contain the sentence before the
498
* sentence before the offset if the offset is not inside a sentence.
500
* If the boundary_type is ATK_TEXT_BOUNDARY_SENTENCE_END the returned string
501
* is from the sentence end before the sentence end at or before the offset to
502
* the sentence end at or before the offset.
504
* The returned string will contain the sentence before the offset if the
505
* offset is inside a sentence or if the offset is not inside a sentence.
507
* If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned
508
* string is from the line start before the line start ar or before the offset
509
* to the line start ar or before the offset.
511
* If the boundary_type is ATK_TEXT_BOUNDARY_LINE_END the returned string
512
* is from the line end before the line end before the offset to the
513
* line end before the offset.
500
* Deprecated: This method is deprecated since ATK version
501
* 2.9.3. Please use atk_text_get_string_at_offset() instead.
515
503
* Returns: a newly allocated string containing the text before @offset bounded
516
504
* by the specified @boundary_type. Use g_free() to free the returned string.
540
* atk_text_get_string_at_offset:
543
* @granularity: An #AtkTextGranularity
544
* @start_offset: (out): the start offset of the returned string, or -1
545
* if an error has occurred (e.g. invalid offset, not implemented)
546
* @end_offset: (out): the offset of the first character after the returned string,
547
* or -1 if an error has occurred (e.g. invalid offset, not implemented)
549
* Gets a portion of the text exposed through an #AtkText according to a given @offset
550
* and a specific @granularity, along with the start and end offsets defining the
551
* boundaries of such a portion of text.
553
* If @granularity is ATK_TEXT_GRANULARITY_CHAR the character at the
554
* offset is returned.
556
* If @granularity is ATK_TEXT_GRANULARITY_WORD the returned string
557
* is from the word start at or before the offset to the word start after
560
* The returned string will contain the word at the offset if the offset
561
* is inside a word and will contain the word before the offset if the
562
* offset is not inside a word.
564
* If @granularity is ATK_TEXT_GRANULARITY_SENTENCE the returned string
565
* is from the sentence start at or before the offset to the sentence
566
* start after the offset.
568
* The returned string will contain the sentence at the offset if the offset
569
* is inside a sentence and will contain the sentence before the offset
570
* if the offset is not inside a sentence.
572
* If @granularity is ATK_TEXT_GRANULARITY_LINE the returned string
573
* is from the line start at or before the offset to the line
574
* start after the offset.
576
* If @granularity is ATK_TEXT_GRANULARITY_PARAGRAPH the returned string
577
* is from the start of the paragraph at or before the offset to the start
578
* of the following paragraph after the offset.
582
* Returns: a newly allocated string containing the text at the @offset bounded
583
* by the specified @granularity. Use g_free() to free the returned string.
584
* Returns %NULL if the offset is invalid or no implementation is available.
586
gchar* atk_text_get_string_at_offset (AtkText *text,
588
AtkTextGranularity granularity,
593
gint local_start_offset, local_end_offset;
594
gint *real_start_offset, *real_end_offset;
596
g_return_val_if_fail (ATK_IS_TEXT (text), NULL);
601
real_start_offset = start_offset;
604
real_start_offset = &local_start_offset;
609
real_end_offset = end_offset;
612
real_end_offset = &local_end_offset;
617
iface = ATK_TEXT_GET_IFACE (text);
619
if (iface->get_string_at_offset)
620
return (*(iface->get_string_at_offset)) (text, offset, granularity, real_start_offset, real_end_offset);
552
626
* atk_text_get_caret_offset:
553
627
* @text: an #AtkText