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.
21 #include "atkmarshal.h"
29 static const gchar
* text_attr_name
[] = {
59 static const gchar
*bool[] = {"false",
61 static const gchar
*style
[] = {"normal",
64 static const gchar
*variant
[] = {"normal",
66 static const gchar
*stretch
[] = {"ultra_condensed",
75 static const gchar
*justification
[] = {"left",
80 static const gchar
*direction
[] = {"none",
83 static const gchar
*wrap_mode
[] = {"none",
86 static const gchar
*underline
[] = {"none",
91 struct _AtkTextIfaceClass
96 typedef struct _AtkTextIfaceClass AtkTextIfaceClass
;
98 static void atk_text_base_init (gpointer
*g_class
);
100 static guint atk_text_signals
[LAST_SIGNAL
] = { 0 };
105 static GType type
= 0;
109 static const GTypeInfo tinfo
=
111 sizeof (AtkTextIface
),
112 (GBaseInitFunc
) atk_text_base_init
,
113 (GBaseFinalizeFunc
) NULL
,
114 (GClassInitFunc
) NULL
/* atk_text_interface_init */ ,
115 (GClassFinalizeFunc
) NULL
,
119 type
= g_type_register_static (G_TYPE_INTERFACE
, "AtkText", &tinfo
, 0);
126 atk_text_base_init (gpointer
*g_class
)
128 static gboolean initialized
= FALSE
;
133 * Note that text_changed signal supports details "insert", "delete",
134 * possibly "replace".
137 atk_text_signals
[TEXT_CHANGED
] =
138 g_signal_new ("text_changed",
140 G_SIGNAL_RUN_LAST
| G_SIGNAL_DETAILED
,
141 G_STRUCT_OFFSET (AtkTextIface
, text_changed
),
142 (GSignalAccumulator
) NULL
, NULL
,
143 atk_marshal_VOID__INT_INT
,
145 2, G_TYPE_INT
, G_TYPE_INT
);
147 atk_text_signals
[CARET_MOVED
] =
148 g_signal_new ("text_caret_moved",
151 G_STRUCT_OFFSET (AtkTextIface
, caret_changed
),
152 (GSignalAccumulator
) NULL
, NULL
,
153 g_cclosure_marshal_VOID__INT
,
164 * @start_offset: start position
165 * @end_offset: end position
167 * Gets the specified text.
169 * Returns: the text from @start_offset up to, but not including @end_offset.
172 atk_text_get_text (AtkText
*text
,
178 g_return_val_if_fail (ATK_IS_TEXT (text
), NULL
);
180 iface
= ATK_TEXT_GET_IFACE (text
);
183 return (*(iface
->get_text
)) (text
, start_offset
, end_offset
);
189 * atk_text_get_character_at_offset:
193 * Gets the specified text.
195 * Returns: the character at @offset.
198 atk_text_get_character_at_offset (AtkText
*text
,
203 g_return_val_if_fail (ATK_IS_TEXT (text
), (gunichar
) 0);
205 iface
= ATK_TEXT_GET_IFACE (text
);
207 if (iface
->get_character_at_offset
)
208 return (*(iface
->get_character_at_offset
)) (text
, offset
);
214 * atk_text_get_text_after_offset:
217 * @boundary_type: An #AtkTextBoundary
218 * @start_offset: the start offset of the returned string.
219 * @end_offset: the end offset of the returned string.
221 * Gets the specified text.
223 * If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character after the
224 * offset is returned.
226 * If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string
227 * is from the word start after the offset to the next word start.
229 * The returned string will contain the word after the offset if the offset
230 * is inside a word or if the offset is not inside a word.
232 * If the boundary_type is ATK_TEXT_BOUNDARY_WORD_END the returned string
233 * is from the word end at or after the offset to the next work end.
235 * The returned string will contain the word after the offset if the offset
236 * is inside a word and will contain the word after the word after the offset
237 * if the offset is not inside a word.
239 * If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned
240 * string is from the sentence start after the offset to the next sentence
243 * The returned string will contain the sentence after the offset if the offset
244 * is inside a sentence or if the offset is not inside a sentence.
246 * If the boundary_type is ATK_TEXT_BOUNDARY_SENTENCE_END the returned string
247 * is from the sentence end at or after the offset to the next sentence end.
249 * The returned string will contain the sentence after the offset if the offset
250 * is inside a sentence and will contain the sentence after the sentence
251 * after the offset if the offset is not inside a sentence.
253 * If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned
254 * string is from the line start after the offset to the next line start.
256 * If the boundary_type is ATK_TEXT_BOUNDARY_LINE_END the returned string
257 * is from the line end at or after the offset to the next line start.
259 * Returns: the text after @offset bounded by the specified @boundary_type.
262 atk_text_get_text_after_offset (AtkText
*text
,
264 AtkTextBoundary boundary_type
,
269 gint local_start_offset
, local_end_offset
;
270 gint
*real_start_offset
, *real_end_offset
;
272 g_return_val_if_fail (ATK_IS_TEXT (text
), NULL
);
275 real_start_offset
= start_offset
;
277 real_start_offset
= &local_start_offset
;
279 real_end_offset
= end_offset
;
281 real_end_offset
= &local_end_offset
;
283 iface
= ATK_TEXT_GET_IFACE (text
);
285 if (iface
->get_text_after_offset
)
286 return (*(iface
->get_text_after_offset
)) (text
, offset
, boundary_type
, real_start_offset
, real_end_offset
);
292 * atk_text_get_text_at_offset:
295 * @boundary_type: An #AtkTextBoundary
296 * @start_offset: the start offset of the returned string.
297 * @end_offset: the end offset of the returned string.
299 * Gets the specified text.
301 * If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character at the
302 * offset is returned.
304 * If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string
305 * is from the word start at or before the offset to the word start after
308 * The returned string will contain the word at the offset if the offset
309 * is inside a word and will contain the word before the offset if the
310 * offset is not inside a word.
312 * If the boundary_type is ATK_TEXT_BOUNDARY_WORD_END the returned string
313 * is from the word end before the offset to the word end at or after the
316 * The returned string will contain the word at the offset if the offset
317 * is inside a word and will contain the word after to the offset if the
318 * 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 at or before the offset to the sentence
322 * start after the offset.
324 * The returned string will contain the sentence at the offset if the offset
325 * is inside a sentence and will contain the sentence before the offset
326 * if the offset is not inside a sentence.
328 * If the boundary_type is ATK_TEXT_BOUNDARY_SENTENCE_END the returned string
329 * is from the sentence end before the offset to the sentence end at or
332 * The returned string will contain the sentence at the offset if the offset
333 * is inside a sentence and will contain the sentence after the offset
334 * if the offset is not inside a sentence.
336 * If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned
337 * string is from the line start at or before the offset to the line
338 * start after the offset.
340 * If the boundary_type is ATK_TEXT_BOUNDARY_LINE_END the returned string
341 * is from the line end before the offset to the line end at or after
344 * Returns: the text at @offset bounded by the specified @boundary_type.
347 atk_text_get_text_at_offset (AtkText
*text
,
349 AtkTextBoundary boundary_type
,
354 gint local_start_offset
, local_end_offset
;
355 gint
*real_start_offset
, *real_end_offset
;
357 g_return_val_if_fail (ATK_IS_TEXT (text
), NULL
);
360 real_start_offset
= start_offset
;
362 real_start_offset
= &local_start_offset
;
364 real_end_offset
= end_offset
;
366 real_end_offset
= &local_end_offset
;
368 iface
= ATK_TEXT_GET_IFACE (text
);
370 if (iface
->get_text_at_offset
)
371 return (*(iface
->get_text_at_offset
)) (text
, offset
, boundary_type
, real_start_offset
, real_end_offset
);
377 * atk_text_get_text_before_offset:
380 * @boundary_type: An #AtkTextBoundary
381 * @start_offset: the start offset of the returned string.
382 * @end_offset: the end offset of the returned string.
384 * Gets the specified text.
386 * If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character before the
387 * offset is returned.
389 * If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string
390 * is from the word start before the word start before the offset to
391 * the word start before the offset.
393 * The returned string will contain the word before the offset if the offset
394 * is inside a word and will contain the word before the word before the
395 * offset if the offset is not inside a word.
397 * If the boundary_type is ATK_TEXT_BOUNDARY_WORD_END the returned string
398 * is from the word end before the word end at or before the offset to the
399 * word end at or before the offset.
401 * The returned string will contain the word before the offset if the offset
402 * is inside a word or if the offset is not inside a word.
404 * If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned
405 * string is from the sentence start before the sentence start before
406 * the offset to the sentence start before the offset.
408 * The returned string will contain the sentence before the offset if the
409 * offset is inside a sentence and will contain the sentence before the
410 * sentence before the offset if the offset is not inside a sentence.
412 * If the boundary_type is ATK_TEXT_BOUNDARY_SENTENCE_END the returned string
413 * is from the sentence end before the sentence end at or before the offset to
414 * the sentence end at or before the offset.
416 * The returned string will contain the sentence before the offset if the
417 * offset is inside a sentence or if the offset is not inside a sentence.
419 * If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned
420 * string is from the line start before the line start ar or before the offset
421 * to the line start ar or before the offset.
423 * If the boundary_type is ATK_TEXT_BOUNDARY_LINE_END the returned string
424 * is from the line end before the line end before the offset to the
425 * line end before the offset.
427 * Returns: the text before @offset bounded by the specified @boundary_type.
430 atk_text_get_text_before_offset (AtkText
*text
,
432 AtkTextBoundary boundary_type
,
437 gint local_start_offset
, local_end_offset
;
438 gint
*real_start_offset
, *real_end_offset
;
440 g_return_val_if_fail (ATK_IS_TEXT (text
), NULL
);
443 real_start_offset
= start_offset
;
445 real_start_offset
= &local_start_offset
;
447 real_end_offset
= end_offset
;
449 real_end_offset
= &local_end_offset
;
451 iface
= ATK_TEXT_GET_IFACE (text
);
453 if (iface
->get_text_before_offset
)
454 return (*(iface
->get_text_before_offset
)) (text
, offset
, boundary_type
, real_start_offset
, real_end_offset
);
460 * atk_text_get_caret_offset:
463 * Gets the offset position of the caret (cursor).
465 * Returns: the offset position of the caret (cursor).
468 atk_text_get_caret_offset (AtkText
*text
)
472 g_return_val_if_fail (ATK_IS_TEXT (text
), -1);
474 iface
= ATK_TEXT_GET_IFACE (text
);
476 if (iface
->get_caret_offset
)
477 return (*(iface
->get_caret_offset
)) (text
);
483 * atk_text_get_character_extents:
486 * @x: x-position of character
487 * @y: y-position of character
488 * @width: width of character
489 * @height: height of character
490 * @coords: specify whether coordinates are relative to the screen or widget window
492 * Given an @offset, the @x, @y, @width, and @height values are filled
496 atk_text_get_character_extents (AtkText
*text
,
505 gint local_x
, local_y
, local_width
, local_height
;
506 gint
*real_x
, *real_y
, *real_width
, *real_height
;
508 g_return_if_fail (ATK_IS_TEXT (text
));
521 real_width
= &local_width
;
523 real_height
= height
;
525 real_height
= &local_height
;
527 iface
= ATK_TEXT_GET_IFACE (text
);
529 if (iface
->get_character_extents
)
530 (*(iface
->get_character_extents
)) (text
, offset
, real_x
, real_y
, real_width
, real_height
, coords
);
541 *atk_text_get_run_attributes:
543 *@offset: the offset at which to get the attributes
544 *@start_offset: the address to put the start offset of the range
545 *@end_offset: the address to put the end offset of the range
547 *Creates an #AtkAttributeSet which consists of the attributes explicitly
548 *set at the position @offset in the text. @start_offset and @end_offset are
549 *set to the start and end of the range around @offset where the attributes are
550 *invariant. See the enum AtkTextAttribute for types of text attributes that
551 *can be returned. Note that other attributes may also be returned.
553 *Returns: an #AtkAttributeSet which contains the attributes explicitly set
554 *at @offset. This #AtkAttributeSet should be freed by a call to
555 *atk_attribute_set_free().
558 atk_text_get_run_attributes (AtkText
*text
,
564 gint local_start_offset
, local_end_offset
;
565 gint
*real_start_offset
, *real_end_offset
;
567 g_return_val_if_fail (ATK_IS_TEXT (text
), NULL
);
570 real_start_offset
= start_offset
;
572 real_start_offset
= &local_start_offset
;
574 real_end_offset
= end_offset
;
576 real_end_offset
= &local_end_offset
;
578 iface
= ATK_TEXT_GET_IFACE (text
);
580 if (iface
->get_run_attributes
)
581 return (*(iface
->get_run_attributes
)) (text
, offset
, real_start_offset
, real_end_offset
);
587 *atk_text_get_default_attributes:
590 *Creates an #AtkAttributeSet which consists of the default values of
591 *attributes for the text. See the enum AtkTextAttribute for types of text
592 *attributes that can be returned. Note that other attributes may also be
595 *Returns: an #AtkAttributeSet which contains the default values of attributes.
596 *at @offset. This #AtkAttributeSet should be freed by a call to
597 *atk_attribute_set_free().
600 atk_text_get_default_attributes (AtkText
*text
)
604 g_return_val_if_fail (ATK_IS_TEXT (text
), NULL
);
606 iface
= ATK_TEXT_GET_IFACE (text
);
608 if (iface
->get_default_attributes
)
609 return (*(iface
->get_default_attributes
)) (text
);
615 * atk_text_get_character_count:
618 * Gets the character count.
620 * Returns: the number of characters.
623 atk_text_get_character_count (AtkText
*text
)
627 g_return_val_if_fail (ATK_IS_TEXT (text
), -1);
629 iface
= ATK_TEXT_GET_IFACE (text
);
631 if (iface
->get_character_count
)
632 return (*(iface
->get_character_count
)) (text
);
638 * atk_text_get_offset_at_point:
640 * @x: screen x-position of character
641 * @y: screen y-position of character
642 * @coords: specify whether coordinates are relative to the screen or
645 * Gets the offset of the character located at coordinates @x and @y. @x and @y
646 * are interpreted as being relative to the screen or this widget's window
647 * depending on @coords.
649 * Returns: the offset to the character which is located at
650 * the specified @x and @y coordinates.
653 atk_text_get_offset_at_point (AtkText
*text
,
660 g_return_val_if_fail (ATK_IS_TEXT (text
), -1);
662 iface
= ATK_TEXT_GET_IFACE (text
);
664 if (iface
->get_offset_at_point
)
665 return (*(iface
->get_offset_at_point
)) (text
, x
, y
, coords
);
671 * atk_text_get_n_selections:
674 * Gets the number of selected regions.
676 * Returns: The number of selected regions, or -1 if a failure
680 atk_text_get_n_selections (AtkText
*text
)
684 g_return_val_if_fail (ATK_IS_TEXT (text
), -1);
686 iface
= ATK_TEXT_GET_IFACE (text
);
688 if (iface
->get_n_selections
)
689 return (*(iface
->get_n_selections
)) (text
);
695 * atk_text_get_selection:
697 * @selection_num: The selection number. The selected regions are
698 * assigned numbers that correspond to how far the region is from the
699 * start of the text. The selected region closest to the beginning
700 * of the text region is assigned the number 0, etc. Note that adding,
701 * moving or deleting a selected region can change the numbering.
702 * @start_offset: passes back the start position of the selected region
703 * @end_offset: passes back the end position of the selected region
705 * Gets the text from the specified selection.
707 * Returns: the selected text.
710 atk_text_get_selection (AtkText
*text
,
716 gint local_start_offset
, local_end_offset
;
717 gint
*real_start_offset
, *real_end_offset
;
719 g_return_val_if_fail (ATK_IS_TEXT (text
), NULL
);
722 real_start_offset
= start_offset
;
724 real_start_offset
= &local_start_offset
;
726 real_end_offset
= end_offset
;
728 real_start_offset
= &local_end_offset
;
730 iface
= ATK_TEXT_GET_IFACE (text
);
732 if (iface
->get_selection
)
734 return (*(iface
->get_selection
)) (text
, selection_num
,
735 real_start_offset
, real_end_offset
);
742 * atk_text_add_selection:
744 * @start_offset: the start position of the selected region
745 * @end_offset: the end position of the selected region
747 * Adds a selection bounded by the specified offsets.
749 * Returns: %TRUE if success, %FALSE otherwise
752 atk_text_add_selection (AtkText
*text
,
758 g_return_val_if_fail (ATK_IS_TEXT (text
), FALSE
);
760 iface
= ATK_TEXT_GET_IFACE (text
);
762 if (iface
->add_selection
)
763 return (*(iface
->add_selection
)) (text
, start_offset
, end_offset
);
769 * atk_text_remove_selection:
771 * @selection_num: The selection number. The selected regions are
772 * assigned numbers that correspond to how far the region is from the
773 * start of the text. The selected region closest to the beginning
774 * of the text region is assigned the number 0, etc. Note that adding,
775 * moving or deleting a selected region can change the numbering.
777 * Removes the specified selection.
779 * Returns: %TRUE if success, %FALSE otherwise
782 atk_text_remove_selection (AtkText
*text
,
787 g_return_val_if_fail (ATK_IS_TEXT (text
), FALSE
);
789 iface
= ATK_TEXT_GET_IFACE (text
);
791 if (iface
->remove_selection
)
792 return (*(iface
->remove_selection
)) (text
, selection_num
);
798 * atk_text_set_selection:
800 * @selection_num: The selection number. The selected regions are
801 * assigned numbers that correspond to how far the region is from the
802 * start of the text. The selected region closest to the beginning
803 * of the text region is assigned the number 0, etc. Note that adding,
804 * moving or deleting a selected region can change the numbering.
805 * @start_offset: the new start position of the selection
806 * @end_offset: the new end position of the selection
808 * Changes the start and end offset of the specified selection.
810 * Returns: %TRUE if success, %FALSE otherwise
813 atk_text_set_selection (AtkText
*text
,
820 g_return_val_if_fail (ATK_IS_TEXT (text
), FALSE
);
822 iface
= ATK_TEXT_GET_IFACE (text
);
824 if (iface
->set_selection
)
826 return (*(iface
->set_selection
)) (text
, selection_num
,
827 start_offset
, end_offset
);
834 * atk_text_set_caret_offset:
838 * Sets the caret (cursor) position to the specified @offset.
840 * Returns: %TRUE if success, %FALSE otherwise.
843 atk_text_set_caret_offset (AtkText
*text
,
848 g_return_val_if_fail (ATK_IS_TEXT (text
), FALSE
);
850 iface
= ATK_TEXT_GET_IFACE (text
);
852 if (iface
->set_caret_offset
)
854 return (*(iface
->set_caret_offset
)) (text
, offset
);
863 * atk_attribute_set_free:
864 * @attrib_set: The #AtkAttributeSet to free
866 * Frees the memory used by an #AtkAttributeSet, including all its
870 atk_attribute_set_free(AtkAttributeSet
*attrib_set
)
887 g_slist_free (attrib_set
);
891 * atk_attribute_get_name:
892 * @attr: The #AtkTextAttribute whose name is required
894 * Gets the name corresponding to the #AtkTextAttribute
896 * Returns: a string containing the name; this string should not be freed
898 G_CONST_RETURN gchar
*
899 atk_attribute_get_name (AtkTextAttribute attr
)
901 g_assert (attr
>= 0 && attr
<= ATK_TEXT_ATTR_STYLE
);
902 return text_attr_name
[attr
];
906 * atk_attribute_get_value:
907 * @attr: The #AtkTextAttribute for which a value is required
908 * @index: The index of the required value
910 * Gets the value for the index of the #AtkTextAttribute
912 * Returns: a string containing the value; this string should not be freed;
913 * NULL is returned if there are no values maintained for the attr value.
915 G_CONST_RETURN gchar
*
916 atk_attribute_get_value (AtkTextAttribute attr
,
921 case ATK_TEXT_ATTR_INVISIBLE
:
922 case ATK_TEXT_ATTR_EDITABLE
:
923 case ATK_TEXT_ATTR_BG_FULL_HEIGHT
:
924 case ATK_TEXT_ATTR_STRIKETHROUGH
:
925 case ATK_TEXT_ATTR_BG_STIPPLE
:
926 case ATK_TEXT_ATTR_FG_STIPPLE
:
927 g_assert (index
>= 0 && index
< 2);
929 case ATK_TEXT_ATTR_UNDERLINE
:
930 g_assert (index
>= 0 && index
< 4);
931 return underline
[index
];
932 case ATK_TEXT_ATTR_WRAP_MODE
:
933 g_assert (index
>= 0 && index
< 3);
934 return wrap_mode
[index
];
935 case ATK_TEXT_ATTR_DIRECTION
:
936 g_assert (index
>= 0 && index
< 3);
937 return direction
[index
];
938 case ATK_TEXT_ATTR_JUSTIFICATION
:
939 g_assert (index
>= 0 && index
< 3);
940 return justification
[index
];
941 case ATK_TEXT_ATTR_STRETCH
:
942 g_assert (index
>= 0 && index
< 9);
943 return stretch
[index
];
944 case ATK_TEXT_ATTR_VARIANT
:
945 g_assert (index
>= 0 && index
< 2);
946 return variant
[index
];
947 case ATK_TEXT_ATTR_STYLE
:
948 g_assert (index
>= 0 && index
< 3);