2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2001, 2002 Sun Microsystems Inc.,
6 * Copyright 2001, 2002 Ximian, Inc.
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 * Boston, MA 02111-1307, USA.
24 #include <cspi/spi-private.h>
26 static Accessibility_TEXT_BOUNDARY_TYPE
27 get_accessible_text_boundary_type (AccessibleTextBoundaryType type)
31 case SPI_TEXT_BOUNDARY_CHAR:
32 return Accessibility_TEXT_BOUNDARY_CHAR;
34 case SPI_TEXT_BOUNDARY_CURSOR_POS:
36 return Accessibility_TEXT_BOUNDARY_CHAR;
38 case SPI_TEXT_BOUNDARY_WORD_START:
39 return Accessibility_TEXT_BOUNDARY_WORD_START;
41 case SPI_TEXT_BOUNDARY_WORD_END:
42 return Accessibility_TEXT_BOUNDARY_WORD_END;
44 case SPI_TEXT_BOUNDARY_SENTENCE_START:
45 return Accessibility_TEXT_BOUNDARY_SENTENCE_START;
47 case SPI_TEXT_BOUNDARY_SENTENCE_END:
48 return Accessibility_TEXT_BOUNDARY_SENTENCE_END;
50 case SPI_TEXT_BOUNDARY_LINE_START:
51 return Accessibility_TEXT_BOUNDARY_LINE_START;
53 case SPI_TEXT_BOUNDARY_LINE_END:
54 return Accessibility_TEXT_BOUNDARY_LINE_END;
56 case SPI_TEXT_BOUNDARY_ATTRIBUTE_RANGE:
58 return Accessibility_TEXT_BOUNDARY_CHAR;
62 return Accessibility_TEXT_BOUNDARY_CHAR;
66 static Accessibility_TEXT_CLIP_TYPE
67 get_accessible_text_clip_type (AccessibleTextClipType type)
71 case SPI_TEXT_CLIP_NONE:
72 return Accessibility_TEXT_CLIP_NONE;
74 case SPI_TEXT_CLIP_MIN:
75 return Accessibility_TEXT_CLIP_MIN;
77 case SPI_TEXT_CLIP_MAX:
78 return Accessibility_TEXT_CLIP_MAX;
81 return Accessibility_TEXT_CLIP_BOTH;
85 static AccessibleTextRange **
86 get_accessible_text_ranges_from_range_seq (Accessibility_Text_RangeList *range_seq)
88 AccessibleTextRange **ranges = NULL;
89 AccessibleTextRange *array = NULL;
91 if (range_seq && range_seq->_length > 0)
93 ranges = g_new0 (AccessibleTextRange *, range_seq->_length + 1);
95 array = g_new0 (AccessibleTextRange, range_seq->_length);
96 for (i = 0; i < range_seq->_length; i++)
98 AccessibleTextRange *range;
100 range->start = range_seq->_buffer[i].startOffset;
101 range->end = range_seq->_buffer[i].endOffset;
102 range->contents = CORBA_string_dup (range_seq->_buffer[i].content);
105 ranges[i] = NULL; /* null-terminated list! */
106 CORBA_free (range_seq);
113 * AccessibleText_ref:
114 * @obj: a pointer to the #AccessibleText object on which to operate.
116 * Increment the reference count for an #AccessibleText object.
119 AccessibleText_ref (AccessibleText *obj)
121 cspi_object_ref (obj);
125 * AccessibleText_unref:
126 * @obj: a pointer to the #Accessible object on which to operate.
128 * Decrement the reference count for an #AccessibleText object.
131 AccessibleText_unref (AccessibleText *obj)
133 cspi_object_unref (obj);
137 * AccessibleText_getCharacterCount:
138 * @obj: a pointer to the #AccessibleText object to query.
140 * Get the character count of an #AccessibleText object.
142 * Returns: a long integer indicating the total number of
143 * characters in the #AccessibleText object.
146 AccessibleText_getCharacterCount (AccessibleText *obj)
150 cspi_return_val_if_fail (obj != NULL, -1);
152 retval = Accessibility_Text__get_characterCount (CSPI_OBJREF (obj), cspi_ev ());
154 cspi_return_val_if_ev ("getCharacterCount", -1);
160 * AccessibleText_getText:
161 * @obj: a pointer to the #AccessibleText object to query.
162 * @startOffset: a #long indicating the start of the desired text range.
163 * @endOffset: a #long indicating the first character past the desired range.
165 * Get a range of text from an #AccessibleText object. The number of bytes
166 * in the returned string may exceed endOffset-startOffset, since
167 * UTF-8 is a variable-width encoding.
169 * Returns: a text string containing characters from @startOffset
170 * to @endOffset-1, inclusive, encoded as UTF-8.
173 AccessibleText_getText (AccessibleText *obj,
174 long int startOffset,
179 cspi_return_val_if_fail (obj != NULL, NULL);
182 Accessibility_Text_getText (CSPI_OBJREF (obj),
187 cspi_return_val_if_ev ("getText", NULL);
193 * AccessibleText_getCaretOffset:
194 * @obj: a pointer to the #AccessibleText object to query.
196 * Get the current offset of the text caret in an #AccessibleText object.
198 * Returns: a long integer indicating the current position of the text caret.
201 AccessibleText_getCaretOffset (AccessibleText *obj)
205 cspi_return_val_if_fail (obj != NULL, -1);
208 Accessibility_Text__get_caretOffset (CSPI_OBJREF (obj), cspi_ev ());
210 cspi_return_val_if_ev ("getCaretOffset", -1);
216 * AccessibleText_getAttributes:
217 * @obj: a pointer to the #AccessibleText object to query.
218 * @offset: a long integer indicating the offset from which the attribute
220 * @startOffset: a #long indicating the start of the desired text range.
221 * @endOffset: a #long indicating the first character past the desired range.
223 * Get the attributes applied to a range of text from an #AccessibleText
224 * object, and the bounds of the range.
225 * The text attributes correspond to CSS attributes where possible,
226 * keys and values are delimited from one another via ":", and
227 * the delimiter between key/value pairs is ";". Thus
228 * "font-size:10;foreground-color:0,0,0" would be a valid
231 * Returns: a text string describing the attributes occurring within the
232 * attribute run containing @offset, encoded as UTF-8.
235 AccessibleText_getAttributes (AccessibleText *obj,
237 long int *startOffset,
240 CORBA_long retStartOffset, retEndOffset;
245 *startOffset = *endOffset = -1;
249 retval = Accessibility_Text_getAttributes (CSPI_OBJREF (obj),
255 if (!cspi_check_ev ("getAttributes"))
257 *startOffset = *endOffset = -1;
262 *startOffset = retStartOffset;
263 *endOffset = retEndOffset;
270 * AccessibleText_getDefaultAttributes:
271 * @obj: a pointer to the #AccessibleText object to query.
273 * Get the default attributes applied to an #AccessibleText
275 * The text attributes correspond to CSS attributes where possible,
276 * keys and values are delimited from one another via ":", and
277 * the delimiter between key/value pairs is ";". Thus
278 * "font-size:10;foreground-color:0,0,0" would be a valid
279 * return string. The combination of this attribute set and
280 * the attributes reported by #AccessibleText_getAttributes
281 * describes the entire set of text attributes over a range.
283 * Returns: a text string describing the default attributes
284 * applied to a text object, (exclusive of explicitly-set
285 * attributes), encoded as UTF-8.
288 AccessibleText_getDefaultAttributes (AccessibleText *obj)
297 retval = Accessibility_Text_getDefaultAttributes (CSPI_OBJREF (obj),
300 if (!cspi_check_ev ("getAttributes"))
309 * AccessibleText_setCaretOffset:
310 * @obj: a pointer to the #AccessibleText object on which to operate.
311 * @newOffset: the offset to which the text caret is to be moved.
313 * Set the text caret position for an #AccessibleText object.
315 * Returns: #TRUE if successful, #FALSE otherwise.
318 AccessibleText_setCaretOffset (AccessibleText *obj,
323 cspi_return_val_if_fail (obj != NULL, FALSE);
326 Accessibility_Text_setCaretOffset (CSPI_OBJREF (obj),
327 newOffset, cspi_ev ());
329 cspi_return_val_if_ev ("setCaretOffset", FALSE);
335 * AccessibleText_getTextBeforeOffset:
336 * @obj: a pointer to the #AccessibleText object on which to operate.
337 * @offset: a long integer indicating the offset from which the delimiter
339 * @type: an #AccessibleTextBoundaryType indicating whether the desired
340 * text string is a word, sentence, line, or attribute run.
341 * @startOffset: a pointer to a long integer which is assigned the
342 * starting offset of the returned string, relative to the
343 * original #AccessibleText.
344 * @endOffset: a pointer to a long integer which is assigned the
345 * ending offset of the returned string, relative to the original
348 * Get delimited text from an #AccessibleText object which precedes a given
351 * Returns: a UTF-8 string representing the delimited text, both of whose
352 * delimiting boundaries are before the current offset, or
353 * an empty string if no such text exists.
356 AccessibleText_getTextBeforeOffset (AccessibleText *obj,
358 AccessibleTextBoundaryType type,
359 long int *startOffset,
363 CORBA_long retStartOffset, retEndOffset;
367 *startOffset = *endOffset = -1;
371 retval = Accessibility_Text_getTextBeforeOffset (CSPI_OBJREF (obj),
373 get_accessible_text_boundary_type (type),
374 &retStartOffset, &retEndOffset,
376 if (!cspi_check_ev ("getTextBeforeOffset"))
378 *startOffset = *endOffset = -1;
383 *startOffset = retStartOffset;
384 *endOffset = retEndOffset;
390 * AccessibleText_getTextAtOffset:
391 * @obj: a pointer to the #AccessibleText object on which to operate.
392 * @offset: a long integer indicating the offset from which the delimiter
394 * @type: an #AccessibleTextBoundaryType indicating whether the desired
395 * text string is a word, sentence, line, or attribute run.
396 * @startOffset: a pointer to a long integer which is assigned the
397 * starting offset of the returned string, relative to the
398 * original #AccessibleText.
399 * @endOffset: a pointer to a long integer which is assigned the
400 * ending offset of the returned string, relative to the original
403 * Get delimited text from an #AccessibleText object which includes a given
406 * Returns: a UTF-8 string representing the delimited text, whose
407 * delimiting boundaries bracket the current offset, or
408 * an empty string if no such text exists.
411 AccessibleText_getTextAtOffset (AccessibleText *obj,
413 AccessibleTextBoundaryType type,
414 long int *startOffset, long int *endOffset)
416 CORBA_long corbaStartOffset;
417 CORBA_long corbaEndOffset;
422 *startOffset = *endOffset = -1;
426 retval = Accessibility_Text_getTextAtOffset (CSPI_OBJREF (obj),
428 get_accessible_text_boundary_type (type),
433 if (!cspi_check_ev ("getTextAtOffset"))
435 *startOffset = *endOffset = -1;
440 *startOffset = corbaStartOffset;
441 *endOffset = corbaEndOffset;
447 * AccessibleText_getTextAfterOffset:
448 * @obj: a pointer to the #AccessibleText object on which to operate.
449 * @offset: a long integer indicating the offset from which the delimiter
451 * @type: an #AccessibleTextBoundaryType indicating whether the desired
452 * text string is a word, sentence, line, or attribute run.
453 * @startOffset: a pointer to a long integer which is assigned the
454 * starting offset of the returned string, relative to the
455 * original #AccessibleText.
456 * @endOffset: a pointer to a long integer which is assigned the
457 * ending offset of the returned string, relative to the original
460 * Get delimited text from an #AccessibleText object which follows a given
463 * Returns: a UTF-8 string representing the delimited text, both of whose
464 * delimiting boundaries are after or inclusive of the current
465 * offset, or an empty string if no such text exists.
468 AccessibleText_getTextAfterOffset (AccessibleText *obj,
470 AccessibleTextBoundaryType type,
471 long int *startOffset, long int *endOffset)
474 CORBA_long retStartOffset, retEndOffset;
478 *startOffset = *endOffset = -1;
482 retval = Accessibility_Text_getTextAfterOffset (CSPI_OBJREF (obj),
484 get_accessible_text_boundary_type (type),
485 &retStartOffset, &retEndOffset,
488 if (!cspi_check_ev ("getTextAfterOffset"))
490 *startOffset = *endOffset = -1;
495 *startOffset = retStartOffset;
496 *endOffset = retEndOffset;
502 * AccessibleText_getCharacterAtOffset:
503 * @obj: a pointer to the #AccessibleText object on which to operate.
504 * @offset: a long integer indicating the text offset where the desired
505 * character is located.
507 * Get the character at a given offset for an #AccessibleText object.
509 * Returns: an #unsigned long integer which represents the
510 * UCS-4 unicode code point of the given character, or
511 * 0xFFFFFFFF if the character in question cannot be represented
512 * in the UCS-4 encoding.
515 AccessibleText_getCharacterAtOffset (AccessibleText *obj,
520 cspi_return_val_if_fail (obj != NULL, -1);
523 Accessibility_Text_getCharacterAtOffset (CSPI_OBJREF (obj),
527 cspi_return_val_if_ev ("getCharacterAtOffset", -1);
533 * AccessibleText_getCharacterExtents:
534 * @obj: a pointer to the #AccessibleText object on which to operate.
535 * @offset: an integer indicating the offset of the text character for
536 * whom boundary information is requested.
537 * @x: a pointer to a long integer into which the nominal x coordinate
538 * of the corresponding glyph will be returned.
539 * @y:a pointer to a long integer into which the nominal y coordinate
540 * of the corresponding glyph will be returned.
541 * @width:a pointer to a long integer into which the width
542 * of the corresponding glyph will be returned.
543 * @height: a pointer to a long integer into which the height
544 * of the corresponding glyph will be returned.
545 * @type: an #AccessibleCoordType indicating the coordinate system to use
546 * for the returned values.
548 * Get the bounding box containing the glyph representing
549 * the character at a particular text offset.
552 AccessibleText_getCharacterExtents (AccessibleText *obj,
558 AccessibleCoordType type)
560 CORBA_long retX, retY, retWidth, retHeight;
565 *width = *height = -1;
569 Accessibility_Text_getCharacterExtents (CSPI_OBJREF (obj),
577 if (!cspi_check_ev ("getCharacterExtents"))
580 *width = *height = -1;
592 * AccessibleText_getOffsetAtPoint:
593 * @obj: a pointer to the #AccessibleText object on which to operate.
594 * @x: the x coordinate of the point to be queried.
595 * @y: the y coordinate of the point to be queried.
596 * @type: an #AccessibleCoordType indicating the coordinate system in which
597 * the values should be returned.
599 * Get the bounding box for a glyph at a certain #AccessibleText offset.
601 * Returns: the offset (as a long integer) at the point (@x, @y)
602 * in the specified coordinate system.
606 AccessibleText_getOffsetAtPoint (AccessibleText *obj,
609 AccessibleCoordType type)
613 cspi_return_val_if_fail (obj != NULL, -1);
616 Accessibility_Text_getOffsetAtPoint (CSPI_OBJREF (obj),
621 cspi_return_val_if_ev ("getOffsetAtPoint", -1);
627 * AccessibleText_getRangeExtents:
628 * @obj: a pointer to the #AccessibleText object on which to operate.
629 * @startOffset: an integer indicating the offset of the first text character for
630 * whom boundary information is requested.
631 * @endOffset: an integer indicating the offset of the text character
632 * after the last character for whom boundary information is requested.
633 * @x: a pointer to a long integer into which the nominal x coordinate
634 * of the corresponding bounding box will be returned.
635 * @y:a pointer to a long integer into which the nominal y coordinate
636 * of the corresponding bounding box will be returned.
637 * @width:a pointer to a long integer into which the width
638 * of the corresponding bounding box will be returned.
639 * @height: a pointer to a long integer into which the height
640 * of the corresponding bounding box will be returned.
641 * @type: an #AccessibleCoordType indicating the coordinate system to use
642 * for the returned values.
644 * Get the bounding box for text within a range in an #AccessibleText object.
648 AccessibleText_getRangeExtents (AccessibleText *obj,
649 long int startOffset,
655 AccessibleCoordType type)
657 CORBA_long retX, retY, retWidth, retHeight;
662 *width = *height = -1;
666 Accessibility_Text_getRangeExtents (CSPI_OBJREF (obj),
675 if (!cspi_check_ev ("getRangeExtents"))
678 *width = *height = -1;
690 * AccessibleText_getBoundedRanges:
691 * @obj: a pointer to the #AccessibleText object on which to operate.
692 * @x: the 'starting' x coordinate of the bounding box.
693 * @y: the 'starting' y coordinate of the bounding box.
694 * @width: the x extent of the bounding box.
695 * @height: the y extent of the bounding box.
696 * @type: an #AccessibleCoordType indicating the coordinate system to use
697 * for the returned values.
698 * @clipTypeX: an #AccessibleTextClipType indicating how to treat characters that
699 * intersect the bounding box's x extents.
700 * @clipTypeY: an #AccessibleTextClipType indicating how to treat characters that
701 * intersect the bounding box's y extents.
703 * Get the ranges of text from an #AccessibleText object which lie within the
704 * bounds defined by (@x, @y) and (@x+@width, @y+@height).
706 * Returns: a null-terminated list of pointers to AccessibleTextRange structs
707 * detailing the bounded text.
709 AccessibleTextRange **
710 AccessibleText_getBoundedRanges (AccessibleText *obj,
715 AccessibleCoordType type,
716 AccessibleTextClipType clipTypeX,
717 AccessibleTextClipType clipTypeY)
719 Accessibility_Text_RangeList *range_seq;
721 cspi_return_val_if_fail (obj != NULL, NULL);
724 Accessibility_Text_getBoundedRanges (CSPI_OBJREF (obj),
727 get_accessible_text_clip_type (clipTypeX),
728 get_accessible_text_clip_type (clipTypeY),
731 cspi_return_val_if_ev ("getBoundedRanges", NULL);
733 return get_accessible_text_ranges_from_range_seq (range_seq);
737 * AccessibleTextRange_freeRanges:
738 * @ranges: a pointer to an array of AccessibleTextRange structs.
740 * Free the memory used by a list of AccessibleTextRange structs.
741 * The argument passed in should be an array of pointers
742 * AccessibleTextRange structs.
745 AccessibleTextRange_freeRanges (AccessibleTextRange **ranges)
747 /* this was a contiguously allocated block, only free the first element */
753 * AccessibleText_getNSelections:
754 * @obj: a pointer to the #AccessibleText object on which to operate.
756 * Get the number of active non-contiguous selections for an
757 * #AccessibleText object.
759 * Returns: a long integer indicating the current
760 * number of non-contiguous text selections active
761 * within an #AccessibleText object.
764 AccessibleText_getNSelections (AccessibleText *obj)
768 cspi_return_val_if_fail (obj != NULL, -1);
771 Accessibility_Text_getNSelections (CSPI_OBJREF (obj), cspi_ev ());
773 cspi_return_val_if_ev ("getNSelections", -1);
779 * AccessibleText_getSelection:
780 * @obj: a pointer to the #AccessibleText object on which to operate.
781 * @selectionNum: an integer indicating which selection to query.
782 * @startOffset: a pointer to a long integer into which the start offset
783 * of the selection will be returned.
784 * @endOffset: a pointer to a long integer into which the start offset
785 * of the selection will be returned.
787 * Get the bounds of the @selectionNum-th active text selection for an
788 * #AccessibleText object.
791 AccessibleText_getSelection (AccessibleText *obj,
792 long int selectionNum,
793 long int *startOffset,
796 CORBA_long retStartOffset, retEndOffset;
800 *endOffset = *startOffset = -1;
804 Accessibility_Text_getSelection (CSPI_OBJREF (obj),
806 &retStartOffset, &retEndOffset,
809 if (!cspi_check_ev ("getSelection"))
811 *startOffset = *endOffset = -1;
815 *startOffset = retStartOffset;
816 *endOffset = retEndOffset;
821 * AccessibleText_addSelection:
822 * @obj: a pointer to the #AccessibleText object on which to operate.
823 * @startOffset: the starting offset of the desired new selection.
824 * @endOffset: the offset of the first character after the new selection.
826 * Select some text (add a text selection) in an #AccessibleText object.
828 * Returns: #TRUE if successful, #FALSE otherwise.
831 AccessibleText_addSelection (AccessibleText *obj,
832 long int startOffset, long int endOffset)
836 cspi_return_val_if_fail (obj != NULL, FALSE);
839 Accessibility_Text_addSelection (
840 CSPI_OBJREF (obj), startOffset,
841 endOffset, cspi_ev ());
843 cspi_return_val_if_ev ("addSelection", FALSE);
849 * AccessibleText_removeSelection:
850 * @obj: a pointer to the #AccessibleText object on which to operate.
851 * @selectionNum: an integer indicating which (possibly of several)
852 * text selection to remove.
854 * De-select a text selection.
856 * Returns: #TRUE if successful, #FALSE otherwise.
859 AccessibleText_removeSelection (AccessibleText *obj,
860 long int selectionNum)
864 cspi_return_val_if_fail (obj != NULL, FALSE);
867 Accessibility_Text_removeSelection (
868 CSPI_OBJREF (obj), selectionNum, cspi_ev ());
870 cspi_return_val_if_ev ("removeSelection", FALSE);
876 * AccessibleText_setSelection:
877 * @obj: a pointer to the #AccessibleText object on which to operate.
878 * @selectionNum: a zero-offset index indicating which text selection to modify.
879 * @startOffset: a long int, the new starting offset for the selection.
880 * @endOffset: a long int, the desired new offset of the first character
881 * after the selection.
883 * Change the bounds of an existing #AccessibleText text selection.
885 * Returns: #TRUE if successful, #FALSE otherwise.
888 AccessibleText_setSelection (AccessibleText *obj,
889 long int selectionNum,
890 long int startOffset,
895 cspi_return_val_if_fail (obj != NULL, FALSE);
897 retval = Accessibility_Text_setSelection (CSPI_OBJREF (obj),
900 endOffset, cspi_ev ());
902 cspi_return_val_if_ev ("setSelection", FALSE);