1 /* ATK - The Accessibility Toolkit for GTK+
2 * Copyright 2001 Sun Microsystems Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
23 #include "atkmarshal.h"
29 * @Short_description: The ATK interface implemented by components
33 * #AtkText should be implemented by #AtkObjects on behalf of widgets
34 * that have text content which is either attributed or otherwise
35 * non-trivial. #AtkObjects whose text content is simple,
36 * unattributed, and very brief may expose that content via
37 * #atk_object_get_name instead; however if the text is editable,
38 * multi-line, typically longer than three or four words, attributed,
39 * selectable, or if the object already uses the 'name' ATK property
40 * for other information, the #AtkText interface should be used to
41 * expose the text content. In the case of editable text content,
42 * #AtkEditableText (a subtype of the #AtkText interface) should be
43 * implemented instead.
45 * #AtkText provides not only traversal facilities and change
46 * notification for text content, but also caret tracking and glyph
47 * bounding box calculations. Note that the text strings are exposed
48 * as UTF-8, and are therefore potentially multi-byte, and
49 * caret-to-byte offset mapping makes no assumptions about the
50 * character length; also bounding box glyph-to-offset mapping may be
51 * complex for languages which use ligatures.
54 static GPtrArray *extra_attributes = NULL;
59 TEXT_SELECTION_CHANGED,
60 TEXT_ATTRIBUTES_CHANGED,
66 static const char boolean[] =
69 static const guint8 boolean_offsets[] = {
73 static const char style[] =
77 static const guint8 style_offsets[] = {
81 static const char variant[] =
84 static const guint8 variant_offsets[] = {
88 static const char stretch[] =
98 static const guint8 stretch_offsets[] = {
99 0, 16, 32, 42, 57, 64, 78, 87, 102
102 static const char justification[] =
107 static const guint8 justification_offsets[] = {
111 static const char direction[] =
115 static const guint8 direction_offsets[] = {
119 static const char wrap_mode[] =
124 static const guint8 wrap_mode_offsets[] = {
128 static const char underline[] =
134 static const guint8 underline_offsets[] = {
138 static const char text_position[] =
142 static const guint8 text_position_offsets[] = {
146 static void atk_text_base_init (AtkTextIface *class);
148 static void atk_text_real_get_range_extents (AtkText *text,
151 AtkCoordType coord_type,
152 AtkTextRectangle *rect);
154 static AtkTextRange** atk_text_real_get_bounded_ranges (AtkText *text,
155 AtkTextRectangle *rect,
156 AtkCoordType coord_type,
157 AtkTextClipType x_clip_type,
158 AtkTextClipType y_clip_type);
160 static guint atk_text_signals[LAST_SIGNAL] = { 0 };
163 atk_text_get_type (void)
165 static GType type = 0;
169 static const GTypeInfo tinfo =
171 sizeof (AtkTextIface),
172 (GBaseInitFunc) atk_text_base_init,
173 (GBaseFinalizeFunc) NULL,
174 (GClassInitFunc) NULL /* atk_text_interface_init */ ,
175 (GClassFinalizeFunc) NULL,
179 type = g_type_register_static (G_TYPE_INTERFACE, "AtkText", &tinfo, 0);
186 atk_text_base_init (AtkTextIface *class)
188 static gboolean initialized = FALSE;
193 * Note that text_changed signal supports details "insert", "delete",
194 * possibly "replace".
197 class->get_range_extents = atk_text_real_get_range_extents;
198 class->get_bounded_ranges = atk_text_real_get_bounded_ranges;
201 * AtkText::text-changed:
202 * @atktext: the object which received the signal.
203 * @arg1: The position (character offset) of the insertion or deletion.
204 * @arg2: The length (in characters) of text inserted or deleted.
206 * The "text-changed" signal is emitted when the text of the
207 * object which implements the AtkText interface changes, This
208 * signal will have a detail which is either "insert" or
209 * "delete" which identifies whether the text change was an
210 * insertion or a deletion.
212 * Deprecated: 2.9.4: Use #AtkObject::text-insert or
213 * #AtkObject::text-remove instead.
215 atk_text_signals[TEXT_CHANGED] =
216 g_signal_new ("text_changed",
218 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
219 G_STRUCT_OFFSET (AtkTextIface, text_changed),
220 (GSignalAccumulator) NULL, NULL,
221 atk_marshal_VOID__INT_INT,
223 2, G_TYPE_INT, G_TYPE_INT);
226 * AtkText::text-insert:
227 * @atktext: the object which received the signal.
228 * @arg1: The position (character offset) of the insertion.
229 * @arg2: The length (in characters) of text inserted.
230 * @arg3: The new text inserted
232 * The "text-insert" signal is emitted when a new text is
233 * inserted. If the signal was not triggered by the user
234 * (e.g. typing or pasting text), the "system" detail should be
237 atk_text_signals[TEXT_INSERT] =
238 g_signal_new ("text_insert",
240 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
242 (GSignalAccumulator) NULL, NULL,
243 atk_marshal_VOID__INT_INT_STRING,
245 3, G_TYPE_INT, G_TYPE_INT, G_TYPE_STRING);
248 * AtkText::text-remove:
249 * @atktext: the object which received the signal.
250 * @arg1: The position (character offset) of the removal.
251 * @arg2: The length (in characters) of text removed.
252 * @arg3: The old text removed
254 * The "text-remove" signal is emitted when a new text is
255 * removed. If the signal was not triggered by the user
256 * (e.g. typing or pasting text), the "system" detail should be
259 atk_text_signals[TEXT_REMOVE] =
260 g_signal_new ("text_remove",
262 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
264 (GSignalAccumulator) NULL, NULL,
265 atk_marshal_VOID__INT_INT_STRING,
267 3, G_TYPE_INT, G_TYPE_INT, G_TYPE_STRING);
270 * AtkText::text-caret-moved:
271 * @atktext: the object which received the signal.
272 * @arg1: The new position of the text caret.
274 * The "text-caret-moved" signal is emitted when the caret
275 * position of the text of an object which implements AtkText
278 atk_text_signals[TEXT_CARET_MOVED] =
279 g_signal_new ("text_caret_moved",
282 G_STRUCT_OFFSET (AtkTextIface, text_caret_moved),
283 (GSignalAccumulator) NULL, NULL,
284 g_cclosure_marshal_VOID__INT,
289 * AtkText::text-selection-changed:
290 * @atktext: the object which received the signal.
292 * The "text-selection-changed" signal is emitted when the
293 * selected text of an object which implements AtkText changes.
295 atk_text_signals[TEXT_SELECTION_CHANGED] =
296 g_signal_new ("text_selection_changed",
299 G_STRUCT_OFFSET (AtkTextIface, text_selection_changed),
300 (GSignalAccumulator) NULL, NULL,
301 g_cclosure_marshal_VOID__VOID,
304 * AtkText::text-attributes-changed:
305 * @atktext: the object which received the signal.
307 * The "text-attributes-changed" signal is emitted when the text
308 * attributes of the text of an object which implements AtkText
311 atk_text_signals[TEXT_ATTRIBUTES_CHANGED] =
312 g_signal_new ("text_attributes_changed",
315 G_STRUCT_OFFSET (AtkTextIface, text_attributes_changed),
316 (GSignalAccumulator) NULL, NULL,
317 g_cclosure_marshal_VOID__VOID,
328 * @start_offset: a starting character offset within @text
329 * @end_offset: an ending character offset within @text, or -1 for the end of the string.
331 * Gets the specified text.
333 * Returns: a newly allocated string containing the text from @start_offset up
334 * to, but not including @end_offset. Use g_free() to free the returned
338 atk_text_get_text (AtkText *text,
344 g_return_val_if_fail (ATK_IS_TEXT (text), NULL);
346 iface = ATK_TEXT_GET_IFACE (text);
348 if (start_offset < 0 || end_offset < -1 ||
349 (end_offset != -1 && end_offset < start_offset))
353 return (*(iface->get_text)) (text, start_offset, end_offset);
359 * atk_text_get_character_at_offset:
361 * @offset: a character offset within @text
363 * Gets the specified text.
365 * Returns: the character at @offset or 0 in the case of failure.
368 atk_text_get_character_at_offset (AtkText *text,
373 g_return_val_if_fail (ATK_IS_TEXT (text), (gunichar) 0);
375 iface = ATK_TEXT_GET_IFACE (text);
377 if (iface->get_character_at_offset)
378 return (*(iface->get_character_at_offset)) (text, offset);
384 * atk_text_get_text_after_offset:
387 * @boundary_type: An #AtkTextBoundary
388 * @start_offset: (out): the starting character offset of the returned string
389 * @end_offset: (out): the offset of the first character after the
392 * Gets the specified text.
394 * Deprecated: 2.9.3: Please use atk_text_get_string_at_offset() instead.
396 * Returns: a newly allocated string containing the text after @offset bounded
397 * by the specified @boundary_type. Use g_free() to free the returned
401 atk_text_get_text_after_offset (AtkText *text,
403 AtkTextBoundary boundary_type,
408 gint local_start_offset, local_end_offset;
409 gint *real_start_offset, *real_end_offset;
411 g_return_val_if_fail (ATK_IS_TEXT (text), NULL);
414 real_start_offset = start_offset;
416 real_start_offset = &local_start_offset;
418 real_end_offset = end_offset;
420 real_end_offset = &local_end_offset;
425 iface = ATK_TEXT_GET_IFACE (text);
427 if (iface->get_text_after_offset)
428 return (*(iface->get_text_after_offset)) (text, offset, boundary_type, real_start_offset, real_end_offset);
434 * atk_text_get_text_at_offset:
437 * @boundary_type: An #AtkTextBoundary
438 * @start_offset: (out): the starting character offset of the returned string
439 * @end_offset: (out): the offset of the first character after the
442 * Gets the specified text.
444 * If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character at the
445 * offset is returned.
447 * If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string
448 * is from the word start at or before the offset to the word start after
451 * The returned string will contain the word at the offset if the offset
452 * is inside a word and will contain the word before the offset if the
453 * offset is not inside a word.
455 * If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned
456 * string is from the sentence start at or before the offset to the sentence
457 * start after the offset.
459 * The returned string will contain the sentence at the offset if the offset
460 * is inside a sentence and will contain the sentence before the offset
461 * if the offset is not inside a sentence.
463 * If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned
464 * string is from the line start at or before the offset to the line
465 * start after the offset.
467 * Deprecated: This method is deprecated since ATK version
468 * 2.9.4. Please use atk_text_get_string_at_offset() instead.
470 * Returns: a newly allocated string containing the text at @offset bounded
471 * by the specified @boundary_type. Use g_free() to free the returned
475 atk_text_get_text_at_offset (AtkText *text,
477 AtkTextBoundary boundary_type,
482 gint local_start_offset, local_end_offset;
483 gint *real_start_offset, *real_end_offset;
485 g_return_val_if_fail (ATK_IS_TEXT (text), NULL);
488 real_start_offset = start_offset;
490 real_start_offset = &local_start_offset;
492 real_end_offset = end_offset;
494 real_end_offset = &local_end_offset;
496 iface = ATK_TEXT_GET_IFACE (text);
498 if (iface->get_text_at_offset)
499 return (*(iface->get_text_at_offset)) (text, offset, boundary_type, real_start_offset, real_end_offset);
505 * atk_text_get_text_before_offset:
508 * @boundary_type: An #AtkTextBoundary
509 * @start_offset: (out): the starting character offset of the returned string
510 * @end_offset: (out): the offset of the first character after the
513 * Gets the specified text.
515 * Deprecated: 2.9.3: Please use atk_text_get_string_at_offset() instead.
517 * Returns: a newly allocated string containing the text before @offset bounded
518 * by the specified @boundary_type. Use g_free() to free the returned
522 atk_text_get_text_before_offset (AtkText *text,
524 AtkTextBoundary boundary_type,
529 gint local_start_offset, local_end_offset;
530 gint *real_start_offset, *real_end_offset;
532 g_return_val_if_fail (ATK_IS_TEXT (text), NULL);
535 real_start_offset = start_offset;
537 real_start_offset = &local_start_offset;
539 real_end_offset = end_offset;
541 real_end_offset = &local_end_offset;
546 iface = ATK_TEXT_GET_IFACE (text);
548 if (iface->get_text_before_offset)
549 return (*(iface->get_text_before_offset)) (text, offset, boundary_type, real_start_offset, real_end_offset);
555 * atk_text_get_string_at_offset:
558 * @granularity: An #AtkTextGranularity
559 * @start_offset: (out): the starting character offset of the returned string, or -1
560 * in the case of error (e.g. invalid offset, not implemented)
561 * @end_offset: (out): the offset of the first character after the returned string,
562 * or -1 in the case of error (e.g. invalid offset, not implemented)
564 * Gets a portion of the text exposed through an #AtkText according to a given @offset
565 * and a specific @granularity, along with the start and end offsets defining the
566 * boundaries of such a portion of text.
568 * If @granularity is ATK_TEXT_GRANULARITY_CHAR the character at the
569 * offset is returned.
571 * If @granularity is ATK_TEXT_GRANULARITY_WORD the returned string
572 * is from the word start at or before the offset to the word start after
575 * The returned string will contain the word at the offset if the offset
576 * is inside a word and will contain the word before the offset if the
577 * offset is not inside a word.
579 * If @granularity is ATK_TEXT_GRANULARITY_SENTENCE the returned string
580 * is from the sentence start at or before the offset to the sentence
581 * start after the offset.
583 * The returned string will contain the sentence at the offset if the offset
584 * is inside a sentence and will contain the sentence before the offset
585 * if the offset is not inside a sentence.
587 * If @granularity is ATK_TEXT_GRANULARITY_LINE the returned string
588 * is from the line start at or before the offset to the line
589 * start after the offset.
591 * If @granularity is ATK_TEXT_GRANULARITY_PARAGRAPH the returned string
592 * is from the start of the paragraph at or before the offset to the start
593 * of the following paragraph after the offset.
597 * Returns: (nullable): a newly allocated string containing the text at
598 * the @offset bounded by the specified @granularity. Use g_free()
599 * to free the returned string. Returns %NULL if the offset is invalid
600 * or no implementation is available.
602 gchar* atk_text_get_string_at_offset (AtkText *text,
604 AtkTextGranularity granularity,
609 gint local_start_offset, local_end_offset;
610 gint *real_start_offset, *real_end_offset;
612 g_return_val_if_fail (ATK_IS_TEXT (text), NULL);
617 real_start_offset = start_offset;
620 real_start_offset = &local_start_offset;
625 real_end_offset = end_offset;
628 real_end_offset = &local_end_offset;
633 iface = ATK_TEXT_GET_IFACE (text);
635 if (iface->get_string_at_offset)
636 return (*(iface->get_string_at_offset)) (text, offset, granularity, real_start_offset, real_end_offset);
642 * atk_text_get_caret_offset:
645 * Gets the offset of the position of the caret (cursor).
647 * Returns: the character offset of the position of the caret or -1 if
648 * the caret is not located inside the element or in the case of
652 atk_text_get_caret_offset (AtkText *text)
656 g_return_val_if_fail (ATK_IS_TEXT (text), 0);
658 iface = ATK_TEXT_GET_IFACE (text);
660 if (iface->get_caret_offset)
661 return (*(iface->get_caret_offset)) (text);
667 * atk_text_get_character_extents:
669 * @offset: The offset of the text character for which bounding information is required.
670 * @x: (out) (optional): Pointer for the x coordinate of the bounding box
671 * @y: (out) (optional): Pointer for the y coordinate of the bounding box
672 * @width: (out) (optional): Pointer for the width of the bounding box
673 * @height: (out) (optional): Pointer for the height of the bounding box
674 * @coords: specify whether coordinates are relative to the screen or widget window
676 * If the extent can not be obtained (e.g. missing support), all of x, y, width,
677 * height are set to -1.
679 * Get the bounding box containing the glyph representing the character at
680 * a particular text offset.
683 atk_text_get_character_extents (AtkText *text,
692 gint local_x, local_y, local_width, local_height;
693 gint *real_x, *real_y, *real_width, *real_height;
695 g_return_if_fail (ATK_IS_TEXT (text));
708 real_width = &local_width;
710 real_height = height;
712 real_height = &local_height;
722 iface = ATK_TEXT_GET_IFACE (text);
724 if (iface->get_character_extents)
725 (*(iface->get_character_extents)) (text, offset, real_x, real_y, real_width, real_height, coords);
729 *real_x = *real_x + *real_width;
735 * atk_text_get_run_attributes:
737 *@offset: the character offset at which to get the attributes, -1 means the offset of
738 *the character to be inserted at the caret location.
739 *@start_offset: (out): the address to put the start offset of the range
740 *@end_offset: (out): the address to put the end offset of the range
742 *Creates an #AtkAttributeSet which consists of the attributes explicitly
743 *set at the position @offset in the text. @start_offset and @end_offset are
744 *set to the start and end of the range around @offset where the attributes are
745 *invariant. Note that @end_offset is the offset of the first character
746 *after the range. See the enum AtkTextAttribute for types of text
747 *attributes that can be returned. Note that other attributes may also be
750 *Returns: (transfer full): an #AtkAttributeSet which contains the attributes
751 * explicitly set at @offset. This #AtkAttributeSet should be freed by
752 * a call to atk_attribute_set_free().
755 atk_text_get_run_attributes (AtkText *text,
761 gint local_start_offset, local_end_offset;
762 gint *real_start_offset, *real_end_offset;
764 g_return_val_if_fail (ATK_IS_TEXT (text), NULL);
767 real_start_offset = start_offset;
769 real_start_offset = &local_start_offset;
771 real_end_offset = end_offset;
773 real_end_offset = &local_end_offset;
778 iface = ATK_TEXT_GET_IFACE (text);
780 if (iface->get_run_attributes)
781 return (*(iface->get_run_attributes)) (text, offset, real_start_offset, real_end_offset);
787 * atk_text_get_default_attributes:
790 *Creates an #AtkAttributeSet which consists of the default values of
791 *attributes for the text. See the enum AtkTextAttribute for types of text
792 *attributes that can be returned. Note that other attributes may also be
795 *Returns: (transfer full): an #AtkAttributeSet which contains the default text
796 * attributes for this #AtkText. This #AtkAttributeSet should be freed by
797 * a call to atk_attribute_set_free().
800 atk_text_get_default_attributes (AtkText *text)
804 g_return_val_if_fail (ATK_IS_TEXT (text), NULL);
806 iface = ATK_TEXT_GET_IFACE (text);
808 if (iface->get_default_attributes)
809 return (*(iface->get_default_attributes)) (text);
815 * atk_text_get_character_count:
818 * Gets the character count.
820 * Returns: the number of characters or -1 in case of failure.
823 atk_text_get_character_count (AtkText *text)
827 g_return_val_if_fail (ATK_IS_TEXT (text), -1);
829 iface = ATK_TEXT_GET_IFACE (text);
831 if (iface->get_character_count)
832 return (*(iface->get_character_count)) (text);
838 * atk_text_get_offset_at_point:
840 * @x: screen x-position of character
841 * @y: screen y-position of character
842 * @coords: specify whether coordinates are relative to the screen or
845 * Gets the offset of the character located at coordinates @x and @y. @x and @y
846 * are interpreted as being relative to the screen or this widget's window
847 * depending on @coords.
849 * Returns: the offset to the character which is located at the specified
850 * @x and @y coordinates of -1 in case of failure.
853 atk_text_get_offset_at_point (AtkText *text,
860 g_return_val_if_fail (ATK_IS_TEXT (text), -1);
862 iface = ATK_TEXT_GET_IFACE (text);
864 if (iface->get_offset_at_point)
865 return (*(iface->get_offset_at_point)) (text, x, y, coords);
871 * atk_text_get_n_selections:
874 * Gets the number of selected regions.
876 * Returns: The number of selected regions, or -1 in the case of failure.
879 atk_text_get_n_selections (AtkText *text)
883 g_return_val_if_fail (ATK_IS_TEXT (text), -1);
885 iface = ATK_TEXT_GET_IFACE (text);
887 if (iface->get_n_selections)
888 return (*(iface->get_n_selections)) (text);
894 * atk_text_get_selection:
896 * @selection_num: The selection number. The selected regions are
897 * assigned numbers that correspond to how far the region is from the
898 * start of the text. The selected region closest to the beginning
899 * of the text region is assigned the number 0, etc. Note that adding,
900 * moving or deleting a selected region can change the numbering.
901 * @start_offset: (out): passes back the starting character offset of the selected region
902 * @end_offset: (out): passes back the ending character offset (offset immediately past)
903 * of the selected region
905 * Gets the text from the specified selection.
907 * Returns: a newly allocated string containing the selected text. Use g_free()
908 * to free the returned string.
911 atk_text_get_selection (AtkText *text,
917 gint local_start_offset, local_end_offset;
918 gint *real_start_offset, *real_end_offset;
920 g_return_val_if_fail (ATK_IS_TEXT (text), NULL);
923 real_start_offset = start_offset;
925 real_start_offset = &local_start_offset;
927 real_end_offset = end_offset;
929 real_end_offset = &local_end_offset;
931 iface = ATK_TEXT_GET_IFACE (text);
933 if (iface->get_selection)
935 return (*(iface->get_selection)) (text, selection_num,
936 real_start_offset, real_end_offset);
943 * atk_text_add_selection:
945 * @start_offset: the starting character offset of the selected region
946 * @end_offset: the offset of the first character after the selected region.
948 * Adds a selection bounded by the specified offsets.
950 * Returns: %TRUE if successful, %FALSE otherwise
953 atk_text_add_selection (AtkText *text,
959 g_return_val_if_fail (ATK_IS_TEXT (text), FALSE);
961 iface = ATK_TEXT_GET_IFACE (text);
963 if (iface->add_selection)
964 return (*(iface->add_selection)) (text, start_offset, end_offset);
970 * atk_text_remove_selection:
972 * @selection_num: The selection number. The selected regions are
973 * assigned numbers that correspond to how far the region is from the
974 * start of the text. The selected region closest to the beginning
975 * of the text region is assigned the number 0, etc. Note that adding,
976 * moving or deleting a selected region can change the numbering.
978 * Removes the specified selection.
980 * Returns: %TRUE if successful, %FALSE otherwise
983 atk_text_remove_selection (AtkText *text,
988 g_return_val_if_fail (ATK_IS_TEXT (text), FALSE);
990 iface = ATK_TEXT_GET_IFACE (text);
992 if (iface->remove_selection)
993 return (*(iface->remove_selection)) (text, selection_num);
999 * atk_text_set_selection:
1000 * @text: an #AtkText
1001 * @selection_num: The selection number. The selected regions are
1002 * assigned numbers that correspond to how far the region is from the
1003 * start of the text. The selected region closest to the beginning
1004 * of the text region is assigned the number 0, etc. Note that adding,
1005 * moving or deleting a selected region can change the numbering.
1006 * @start_offset: the new starting character offset of the selection
1007 * @end_offset: the new end position of (e.g. offset immediately past)
1010 * Changes the start and end offset of the specified selection.
1012 * Returns: %TRUE if successful, %FALSE otherwise
1015 atk_text_set_selection (AtkText *text,
1020 AtkTextIface *iface;
1022 g_return_val_if_fail (ATK_IS_TEXT (text), FALSE);
1024 iface = ATK_TEXT_GET_IFACE (text);
1026 if (iface->set_selection)
1028 return (*(iface->set_selection)) (text, selection_num,
1029 start_offset, end_offset);
1036 * atk_text_set_caret_offset:
1037 * @text: an #AtkText
1038 * @offset: the character offset of the new caret position
1040 * Sets the caret (cursor) position to the specified @offset.
1042 * In the case of rich-text content, this method should either grab focus
1043 * or move the sequential focus navigation starting point (if the application
1044 * supports this concept) as if the user had clicked on the new caret position.
1045 * Typically, this means that the target of this operation is the node containing
1046 * the new caret position or one of its ancestors. In other words, after this
1047 * method is called, if the user advances focus, it should move to the first
1048 * focusable node following the new caret position.
1050 * Calling this method should also scroll the application viewport in a way
1051 * that matches the behavior of the application's typical caret motion or tab
1052 * navigation as closely as possible. This also means that if the application's
1053 * caret motion or focus navigation does not trigger a scroll operation, this
1054 * method should not trigger one either. If the application does not have a caret
1055 * motion or focus navigation operation, this method should try to scroll the new
1056 * caret position into view while minimizing unnecessary scroll motion.
1058 * Returns: %TRUE if successful, %FALSE otherwise.
1061 atk_text_set_caret_offset (AtkText *text,
1064 AtkTextIface *iface;
1066 g_return_val_if_fail (ATK_IS_TEXT (text), FALSE);
1068 iface = ATK_TEXT_GET_IFACE (text);
1070 if (iface->set_caret_offset)
1072 return (*(iface->set_caret_offset)) (text, offset);
1081 * atk_text_get_range_extents:
1082 * @text: an #AtkText
1083 * @start_offset: The offset of the first text character for which boundary
1084 * information is required.
1085 * @end_offset: The offset of the text character after the last character
1086 * for which boundary information is required.
1087 * @coord_type: Specify whether coordinates are relative to the screen or widget window.
1088 * @rect: (out): A pointer to a AtkTextRectangle which is filled in by this function.
1090 * Get the bounding box for text within the specified range.
1092 * If the extents can not be obtained (e.g. or missing support), the rectangle
1093 * fields are set to -1.
1098 atk_text_get_range_extents (AtkText *text,
1101 AtkCoordType coord_type,
1102 AtkTextRectangle *rect)
1104 AtkTextIface *iface;
1106 g_return_if_fail (ATK_IS_TEXT (text));
1107 g_return_if_fail (rect);
1108 g_return_if_fail (start_offset >= 0 && start_offset < end_offset);
1110 iface = ATK_TEXT_GET_IFACE (text);
1112 if (iface->get_range_extents)
1113 (*(iface->get_range_extents)) (text, start_offset, end_offset, coord_type, rect);
1124 * atk_text_get_bounded_ranges: (virtual get_bounded_ranges)
1125 * @text: an #AtkText
1126 * @rect: An AtkTextRectangle giving the dimensions of the bounding box.
1127 * @coord_type: Specify whether coordinates are relative to the screen or widget window.
1128 * @x_clip_type: Specify the horizontal clip type.
1129 * @y_clip_type: Specify the vertical clip type.
1131 * Get the ranges of text in the specified bounding box.
1135 * Returns: (array zero-terminated=1): Array of AtkTextRange. The last
1136 * element of the array returned by this function will be NULL.
1139 atk_text_get_bounded_ranges (AtkText *text,
1140 AtkTextRectangle *rect,
1141 AtkCoordType coord_type,
1142 AtkTextClipType x_clip_type,
1143 AtkTextClipType y_clip_type)
1145 AtkTextIface *iface;
1147 g_return_val_if_fail (ATK_IS_TEXT (text), NULL);
1148 g_return_val_if_fail (rect, NULL);
1150 iface = ATK_TEXT_GET_IFACE (text);
1152 if (iface->get_bounded_ranges)
1153 return (*(iface->get_bounded_ranges)) (text, rect, coord_type, x_clip_type, y_clip_type);
1159 * atk_attribute_set_free:
1160 * @attrib_set: The #AtkAttributeSet to free
1162 * Frees the memory used by an #AtkAttributeSet, including all its
1166 atk_attribute_set_free (AtkAttributeSet *attrib_set)
1172 while (temp != NULL)
1179 g_free (att->value);
1183 g_slist_free (attrib_set);
1187 * atk_text_attribute_register:
1188 * @name: a name string
1190 * Associate @name with a new #AtkTextAttribute
1192 * Returns: an #AtkTextAttribute associated with @name
1195 atk_text_attribute_register (const gchar *name)
1197 g_return_val_if_fail (name, ATK_TEXT_ATTR_INVALID);
1199 if (!extra_attributes)
1200 extra_attributes = g_ptr_array_new ();
1202 g_ptr_array_add (extra_attributes, g_strdup (name));
1203 return extra_attributes->len + ATK_TEXT_ATTR_LAST_DEFINED;
1207 * atk_text_attribute_get_name:
1208 * @attr: The #AtkTextAttribute whose name is required
1210 * Gets the name corresponding to the #AtkTextAttribute
1212 * Returns: a string containing the name; this string should not be freed
1215 atk_text_attribute_get_name (AtkTextAttribute attr)
1217 GTypeClass *type_class;
1219 const gchar *name = NULL;
1221 type_class = g_type_class_ref (ATK_TYPE_TEXT_ATTRIBUTE);
1222 g_return_val_if_fail (G_IS_ENUM_CLASS (type_class), NULL);
1224 value = g_enum_get_value (G_ENUM_CLASS (type_class), attr);
1228 name = value->value_nick;
1232 if (extra_attributes)
1236 n -= ATK_TEXT_ATTR_LAST_DEFINED + 1;
1238 if (n < extra_attributes->len)
1240 name = g_ptr_array_index (extra_attributes, n);
1243 g_type_class_unref (type_class);
1248 * atk_text_attribute_for_name:
1249 * @name: a string which is the (non-localized) name of an ATK text attribute.
1251 * Get the #AtkTextAttribute type corresponding to a text attribute name.
1253 * Returns: the #AtkTextAttribute enumerated type corresponding to the specified
1254 * name, or #ATK_TEXT_ATTRIBUTE_INVALID if no matching text attribute
1258 atk_text_attribute_for_name (const gchar *name)
1260 GTypeClass *type_class;
1262 AtkTextAttribute type = ATK_TEXT_ATTR_INVALID;
1264 g_return_val_if_fail (name, ATK_TEXT_ATTR_INVALID);
1266 type_class = g_type_class_ref (ATK_TYPE_TEXT_ATTRIBUTE);
1267 g_return_val_if_fail (G_IS_ENUM_CLASS (type_class), ATK_TEXT_ATTR_INVALID);
1269 value = g_enum_get_value_by_nick (G_ENUM_CLASS (type_class), name);
1273 type = value->value;
1279 if (extra_attributes)
1281 for (i = 0; i < extra_attributes->len; i++)
1283 gchar *extra_attribute = (gchar *)g_ptr_array_index (extra_attributes, i);
1285 g_return_val_if_fail (extra_attribute, ATK_TEXT_ATTR_INVALID);
1287 if (strcmp (name, extra_attribute) == 0)
1289 type = i + 1 + ATK_TEXT_ATTR_LAST_DEFINED;
1295 g_type_class_unref (type_class);
1301 * atk_text_attribute_get_value:
1302 * @attr: The #AtkTextAttribute for which a value is required
1303 * @index_: The index of the required value
1305 * Gets the value for the index of the #AtkTextAttribute
1307 * Returns: (nullable): a string containing the value; this string
1308 * should not be freed; %NULL is returned if there are no values
1309 * maintained for the attr value.
1312 atk_text_attribute_get_value (AtkTextAttribute attr,
1317 case ATK_TEXT_ATTR_INVISIBLE:
1318 case ATK_TEXT_ATTR_EDITABLE:
1319 case ATK_TEXT_ATTR_BG_FULL_HEIGHT:
1320 case ATK_TEXT_ATTR_STRIKETHROUGH:
1321 case ATK_TEXT_ATTR_BG_STIPPLE:
1322 case ATK_TEXT_ATTR_FG_STIPPLE:
1323 g_assert (index >= 0 && index < G_N_ELEMENTS (boolean_offsets));
1324 return boolean + boolean_offsets[index];
1325 case ATK_TEXT_ATTR_UNDERLINE:
1326 g_assert (index >= 0 && index < G_N_ELEMENTS (underline_offsets));
1327 return underline + underline_offsets[index];
1328 case ATK_TEXT_ATTR_WRAP_MODE:
1329 g_assert (index >= 0 && index < G_N_ELEMENTS (wrap_mode_offsets));
1330 return wrap_mode + wrap_mode_offsets[index];
1331 case ATK_TEXT_ATTR_DIRECTION:
1332 g_assert (index >= 0 && index < G_N_ELEMENTS (direction_offsets));
1333 return direction + direction_offsets[index];
1334 case ATK_TEXT_ATTR_JUSTIFICATION:
1335 g_assert (index >= 0 && index < G_N_ELEMENTS (justification_offsets));
1336 return justification + justification_offsets[index];
1337 case ATK_TEXT_ATTR_STRETCH:
1338 g_assert (index >= 0 && index < G_N_ELEMENTS (stretch_offsets));
1339 return stretch + stretch_offsets[index];
1340 case ATK_TEXT_ATTR_VARIANT:
1341 g_assert (index >= 0 && index < G_N_ELEMENTS (variant_offsets));
1342 return variant + variant_offsets[index];
1343 case ATK_TEXT_ATTR_STYLE:
1344 g_assert (index >= 0 && index < G_N_ELEMENTS (style_offsets));
1345 return style + style_offsets[index];
1346 case ATK_TEXT_ATTR_TEXT_POSITION:
1347 g_assert (index >= 0 && index < G_N_ELEMENTS (text_position_offsets));
1348 return text_position + text_position_offsets[index];
1355 atk_text_rectangle_union (AtkTextRectangle *src1,
1356 AtkTextRectangle *src2,
1357 AtkTextRectangle *dest)
1359 gint dest_x, dest_y;
1362 * Some invocations of e.g. atk_text_get_character_extents
1363 * may return "-1" rectangles for character positions without support for
1364 * getting an extent. In that case we have to ignore them instead of using -1
1365 * values in computations.
1367 if (src1->width == -1)
1372 if (src2->width == -1)
1378 dest_x = MIN (src1->x, src2->x);
1379 dest_y = MIN (src1->y, src2->y);
1380 dest->width = MAX (src1->x + src1->width, src2->x + src2->width) - dest_x;
1381 dest->height = MAX (src1->y + src1->height, src2->y + src2->height) - dest_y;
1387 atk_text_rectangle_contain (AtkTextRectangle *clip,
1388 AtkTextRectangle *bounds,
1389 AtkTextClipType x_clip_type,
1390 AtkTextClipType y_clip_type)
1392 gboolean x_min_ok, x_max_ok, y_min_ok, y_max_ok;
1394 x_min_ok = (bounds->x >= clip->x) ||
1395 ((bounds->x + bounds->width >= clip->x) &&
1396 ((x_clip_type == ATK_TEXT_CLIP_NONE) ||
1397 (x_clip_type == ATK_TEXT_CLIP_MAX)));
1399 x_max_ok = (bounds->x + bounds->width <= clip->x + clip->width) ||
1400 ((bounds->x <= clip->x + clip->width) &&
1401 ((x_clip_type == ATK_TEXT_CLIP_NONE) ||
1402 (x_clip_type == ATK_TEXT_CLIP_MIN)));
1404 y_min_ok = (bounds->y >= clip->y) ||
1405 ((bounds->y + bounds->height >= clip->y) &&
1406 ((y_clip_type == ATK_TEXT_CLIP_NONE) ||
1407 (y_clip_type == ATK_TEXT_CLIP_MAX)));
1409 y_max_ok = (bounds->y + bounds->height <= clip->y + clip->height) ||
1410 ((bounds->y <= clip->y + clip->height) &&
1411 ((y_clip_type == ATK_TEXT_CLIP_NONE) ||
1412 (y_clip_type == ATK_TEXT_CLIP_MIN)));
1414 return (x_min_ok && x_max_ok && y_min_ok && y_max_ok);
1419 * atk_text_scroll_substring_to:
1420 * @text: an #AtkText
1421 * @start_offset: start offset in the @text
1422 * @end_offset: end offset in the @text, or -1 for the end of the text.
1423 * @type: specify where the object should be made visible.
1425 * Makes a substring of @text visible on the screen by scrolling all necessary parents.
1429 * Returns: whether scrolling was successful.
1432 atk_text_scroll_substring_to (AtkText *text,
1437 AtkTextIface *iface = NULL;
1438 g_return_val_if_fail (ATK_IS_TEXT (text), FALSE);
1440 iface = ATK_TEXT_GET_IFACE (text);
1442 if (iface->scroll_substring_to)
1443 return (iface->scroll_substring_to) (text, start_offset, end_offset, type);
1449 * atk_text_scroll_substring_to_point:
1450 * @text: an #AtkText
1451 * @start_offset: start offset in the @text
1452 * @end_offset: end offset in the @text, or -1 for the end of the text.
1453 * @coords: specify whether coordinates are relative to the screen or to the
1455 * @x: x-position where to scroll to
1456 * @y: y-position where to scroll to
1458 * Move the top-left of a substring of @text to a given position of the screen
1459 * by scrolling all necessary parents.
1463 * Returns: whether scrolling was successful.
1466 atk_text_scroll_substring_to_point (AtkText *text,
1469 AtkCoordType coords,
1473 AtkTextIface *iface = NULL;
1474 g_return_val_if_fail (ATK_IS_TEXT (text), FALSE);
1476 iface = ATK_TEXT_GET_IFACE (text);
1478 if (iface->scroll_substring_to_point)
1479 return (iface->scroll_substring_to_point) (text, start_offset, end_offset, coords, x, y);
1485 atk_text_real_get_range_extents (AtkText *text,
1488 AtkCoordType coord_type,
1489 AtkTextRectangle *rect)
1492 AtkTextRectangle cbounds, bounds;
1494 atk_text_get_character_extents (text, start_offset,
1495 &bounds.x, &bounds.y,
1496 &bounds.width, &bounds.height,
1499 for (i = start_offset + 1; i < end_offset; i++)
1501 atk_text_get_character_extents (text, i,
1502 &cbounds.x, &cbounds.y,
1503 &cbounds.width, &cbounds.height,
1505 atk_text_rectangle_union (&bounds, &cbounds, &bounds);
1510 rect->width = bounds.width;
1511 rect->height = bounds.height;
1514 static AtkTextRange**
1515 atk_text_real_get_bounded_ranges (AtkText *text,
1516 AtkTextRectangle *rect,
1517 AtkCoordType coord_type,
1518 AtkTextClipType x_clip_type,
1519 AtkTextClipType y_clip_type)
1521 gint bounds_min_offset, bounds_max_offset;
1522 gint min_line_start, min_line_end;
1523 gint max_line_start, max_line_end;
1527 gint num_ranges = 0;
1528 gint range_size = 1;
1529 AtkTextRectangle cbounds;
1530 AtkTextRange **range;
1533 bounds_min_offset = atk_text_get_offset_at_point (text, rect->x, rect->y, coord_type);
1534 bounds_max_offset = atk_text_get_offset_at_point (text, rect->x + rect->width, rect->y + rect->height, coord_type);
1536 if (bounds_min_offset == 0 &&
1537 bounds_min_offset == bounds_max_offset)
1540 line = atk_text_get_text_at_offset (text, bounds_min_offset,
1541 ATK_TEXT_BOUNDARY_LINE_START,
1542 &min_line_start, &min_line_end);
1544 line = atk_text_get_text_at_offset (text, bounds_max_offset,
1545 ATK_TEXT_BOUNDARY_LINE_START,
1546 &max_line_start, &max_line_end);
1548 bounds_min_offset = MIN (min_line_start, max_line_start);
1549 bounds_max_offset = MAX (min_line_end, max_line_end);
1551 curr_offset = bounds_min_offset;
1552 while (curr_offset < bounds_max_offset)
1554 offset = curr_offset;
1556 while (curr_offset < bounds_max_offset)
1558 atk_text_get_character_extents (text, curr_offset,
1559 &cbounds.x, &cbounds.y,
1560 &cbounds.width, &cbounds.height,
1562 if (!atk_text_rectangle_contain (rect, &cbounds, x_clip_type, y_clip_type))
1566 if (curr_offset > offset)
1568 AtkTextRange *one_range = g_new (AtkTextRange, 1);
1570 one_range->start_offset = offset;
1571 one_range->end_offset = curr_offset;
1572 one_range->content = atk_text_get_text (text, offset, curr_offset);
1573 atk_text_get_range_extents (text, offset, curr_offset, coord_type, &one_range->bounds);
1575 if (num_ranges >= range_size - 1)
1578 range = g_realloc (range, range_size * sizeof (gpointer));
1580 range[num_ranges] = one_range;
1585 range[num_ranges] = NULL;
1591 * atk_text_free_ranges:
1592 * @ranges: (array): A pointer to an array of #AtkTextRange which is
1595 * Frees the memory associated with an array of AtkTextRange. It is assumed
1596 * that the array was returned by the function atk_text_get_bounded_ranges
1597 * and is NULL terminated.
1602 atk_text_free_ranges (AtkTextRange **ranges)
1604 AtkTextRange **first = ranges;
1610 AtkTextRange *range;
1614 g_free (range->content);
1621 static AtkTextRange *
1622 atk_text_range_copy (AtkTextRange *src)
1624 AtkTextRange *dst = g_new0 (AtkTextRange, 1);
1625 dst->bounds = src->bounds;
1626 dst->start_offset = src->start_offset;
1627 dst->end_offset = src->end_offset;
1629 dst->content = g_strdup (src->content);
1634 atk_text_range_free (AtkTextRange *range)
1636 g_free (range->content);
1640 G_DEFINE_BOXED_TYPE (AtkTextRange, atk_text_range, atk_text_range_copy,
1641 atk_text_range_free)