2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2001 Sun Microsystems, Inc.
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
23 module Accessibility {
26 * Specifies the boundary conditions determining a run of text as returned from
27 * getTextAtOffset, getTextAfterOffset, and getTextBeforeOffset.
29 enum TEXT_BOUNDARY_TYPE {
30 TEXT_BOUNDARY_CHAR,/**< Text is bounded by this character only.
31 * Start and end offsets differ by one, by definition, for this value.
33 TEXT_BOUNDARY_WORD_START,/**< Boundary condition is start of a word; i.e. range is from start of
34 * one word to the start of another word.
36 TEXT_BOUNDARY_WORD_END,/**< Boundary condition is the end of a word; i.e. range is from
37 * the end of one word to the end of another.
38 * @note some locales may not distinguish between words and
39 * characters or glyphs, in particular those locales which use
40 * wholly or partially ideographic character sets. In these cases,
41 * characters may be returned in lieu of multi-character substrings.
43 TEXT_BOUNDARY_SENTENCE_START,/**< Boundary condition is start of a sentence, as determined
45 * @note Some locales or character sets may not include explicit sentence
46 * delimiters, so this boundary type can not always be honored.
47 * Some locales will return lines of text instead of grammatical sentences.
49 TEXT_BOUNDARY_SENTENCE_END,/**< Boundary condition is end of a sentence, as determined by the application,
50 * including the sentence-delimiting character, for instance '.'
51 * @note Some locales or character sets may not include explicit sentence
52 * delimiters, so this boundary type can not always be honored.
53 * Some locales will return lines of text instead of grammatical sentences.
55 TEXT_BOUNDARY_LINE_START,/**< Boundary condition is the start of a line; i.e. range is
56 * from start of one line to the start of another. This generally
57 * means that an end-of-line character will appear at the end of the range.
59 TEXT_BOUNDARY_LINE_END /**< Boundary condition is the end of a line; i.e. range is
60 * from start of one line to the start of another. This generally
61 * means that an end-of-line character will be the first character of the range.
67 * CLIP_MIN means text clipped by min coordinate is omitted,
68 * CLIP_MAX clips text interescted by the max coord, and CLIP_BOTH
69 * will retain only text falling fully within the min/max bounds.
74 TEXT_CLIP_MIN,/**< characters/glyphs clipped by the minimum coordinate are omitted */
75 TEXT_CLIP_MAX,/**< characters/glyphs which intersect the maximum coordinate are omitted */
76 TEXT_CLIP_BOTH /**< only glyphs falling entirely within the region bounded by min and max are retained. */
80 * The text interface should be implemented by objects which place textual information onscreen as character
81 * strings or glyphs. The text interface allows access to textual content, including display attributes and
82 * semantic hints associated with runs of text, and access to bounding box information for glyphs and substrings.
83 * It also allows portions of textual content to be selected, if the object's StateSet includes
84 * STATE_SELECTABLE_TEXT.
86 * In some cases a Text object may have, as its content, an empty string. In particular this can
87 * occur in the case of Hypertext objects which do not display explicitly textual information onscreen,
88 * as Hypertext is derived from the Text interface. @see Hypertext.
90 * Typographic and semantic attributes of onscreen textual content, for instance typeface, weight,
91 * language, and such qualities as 'emphasis' or 'blockquote', are represented as text attributes.
92 * Contiguous sequences of characters over which these attributes are unchanged are referred to as
93 * "attribute runs", and are available via Text::getAttributeRun. Where possible, implementing clients
94 * will report textual attributes which are the same over the entire text object, for instance those
95 * inherited from a default or document-scope style, via getDefaultAttributes instead of reporting them
96 * explicitly for each character. Therefore, for any span of text, the attributes in effect are the union
97 * of the set returned by Text::getDefaultAttributes, and the set returned at a particular character
98 * offset via Text::getAttributeRun.
100 * @note Events that may be emitted by instances of Text include:
101 * \li \c "object:text-attributes-changed" The attributes of a range of text, or the range over
102 * which attributes apply, has changed.
103 * \li \c "object:text-changed" The text content of this object has changed.
104 * \li \c "object:text-bounds-changed" The character bounds of a text object have changed,
105 * for instance in response to a reformatting or reflow operation.
106 * \li \c "object:text-caret-moved" The character offset of the text caret (visible or notional) within
107 * this object has changed. Events of this type may also be generated when an onscreen
108 * text caret appears or disappears.
109 * \li \c "object:text-selection-changed" The range or number of text selections within this text object
112 * @note In some cases, objects which are not onscreen may implement Text, but if such objects
113 * implement Component, their potential visibility should be examined (via comparison with STATE_VISIBLE
114 * and STATE_SHOWING) before exposing them to the user. Objects which implement Text but not Component
115 * may be encountered in special-purpose interfaces or as special ¨accessibility¨ extensions to visual
116 * interfaces to allow non-graphical access to application features. These instances should be considered
117 * the exception, rather than the rule.
119 interface Text : Bonobo::Unknown {
121 /** A structure used to define a continguous range of text, including its
122 * (unattributed) textual content.
131 typedef sequence<Range> RangeList;
133 /** The total current number of characters in the Text object,
134 * including whitespace and non-spacing characters.
136 readonly attribute long characterCount;
138 /** The current offset of the text caret in the Text object.
139 * This caret may be virtual, e.g. non-visual and notional-only, but if an
140 * onscreen representation of the caret position is visible, it will correspond to this offset.
141 * The caret offset is given as a character offset, as opposed to a byte offset into
142 * a text buffer or a column offset.
144 readonly attribute long caretOffset;
147 * Obtain all or part of the onscreen textual content of a Text object. If endOffset is specified as
148 * "-1", then this method will return the entire onscreen textual contents of the Text object.
149 * @note 'onscreen' in this context means "potentially onscreen", this method does not perform any sort
150 * of coordinate visibility clipping or window-stack-ordering clipping. The text thus reported
151 * corresponds to the text which would be presented onscreen if the object implementing the Text interface
152 * were entirely unobscured.
153 * @returns the textual content of the current Text object beginning startOffset (inclusive)
154 * up to but not including the character at endOffset.
156 string getText (in long startOffset, in long endOffset);
158 /** Programmatically move the text caret (visible or virtual, as above) to a given position.
159 * @param offset a long int indicating the desired character offset. Not all implementations of
160 * Text will honor setCaretOffset requests, so the return value below should be checked by the client.
161 * @returns \c TRUE if the request was carried out, or \c FALSE if the caret could not be moved to
162 * the requested position.
164 boolean setCaretOffset (in long offset);
167 * Obtain a subset of the text content of an object which entirely precedes \c offset,
168 * delimited by character, word, line, or sentence boundaries as specified by \c type. The
169 * starting and ending offsets of the resulting substring are returned in \c startOffset
170 * and \c endOffset. By definition, if such a substring exists, \c endOffset is less than or
171 * equal to \c offset.
172 * @param offset the offset from which the substring search begins.
173 * @param type the text-boundary delimiter which determines whether the returned text constitures
174 * a character, word, line, or sentence (and possibly attendant whitespace),
175 * and whether the start or ending of such a substring forms the boundary condition.
176 * @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
177 * @param endOffset back-filled with the offset of the character immediately following the resulting
178 * substring, if one exists.
179 * @see TEXT_BOUNDARY_TYPE
180 * @returns a string which is a substring of the text content of the object, delimited by the
181 * specified boundary condition.
183 string getTextBeforeOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
184 out long startOffset, out long endOffset);
186 * Obtain a subset of the text content of an object which includes the specified \c offset,
187 * delimited by character, word, line, or sentence boundaries as specified by \c type. The
188 * starting and ending offsets of the resulting substring are returned in \c startOffset
190 * @param offset the offset from which the substring search begins, and which must
191 * lie within the returned substring.
192 * @param type the text-boundary delimiter which determines whether the returned text constitures
193 * a character, word, line, or sentence (and possibly attendant whitespace),
194 * and whether the start or ending of such a substring forms the boundary condition.
195 * @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
196 * @param endOffset back-filled with the offset of the character immediately following the resulting
197 * substring, if one exists.
198 * @see TEXT_BOUNDARY_TYPE
199 * @returns a string which is a substring of the text content of the object, delimited by the
200 * specified boundary condition.
202 string getTextAtOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
203 out long startOffset, out long endOffset);
205 * Obtain a subset of the text content of an object which entirely follows \c offset,
206 * delimited by character, word, line, or sentence boundaries as specified by \c type. The
207 * starting and ending offsets of the resulting substring are returned in \c startOffset
208 * and \c endOffset. By definition, if such a substring exists, \c startOffset must be greater than
210 * @param offset the offset from which the substring search begins, and which must
211 * lie before the returned substring.
212 * @param type the text-boundary delimiter which determines whether the returned text constitures
213 * a character, word, line, or sentence (and possibly attendant whitespace),
214 * and whether the start or ending of such a substring forms the boundary condition.
215 * @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
216 * @param endOffset back-filled with the offset of the character immediately following the resulting
217 * substring, if one exists.
218 * @see TEXT_BOUNDARY_TYPE
219 * @returns a string which is a substring of the text content of the object, delimited by the
220 * specified boundary condition.
222 string getTextAfterOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
223 out long startOffset, out long endOffset);
225 * @returns an unsigned long integer whose value corresponds to the UCS-4 representation of the
226 * character at the specified text offset, or 0 if offset is out of range.
228 unsigned long getCharacterAtOffset (in long offset); /* long instead of wchar,
229 * to allow unicode chars > 16 bits
232 * Get the string value of a named attribute at a given offset, if defined.
233 * @param offset the offset of the character for which the attribute run is to be obtained.
234 * @param attributeName the name of the attribute for which the value is to be returned, if defined.
235 * @param startOffset back-filled with the offset of the first character in the attribute run
236 * containing the character at \c offset.
237 * @param endOffset back-filled with the offset of the first character past the end of the
238 * attribute run containing the character at \c offset.
239 * @param defined back-filled with \c True if the attributeName has a defined value at \c offset,
240 * \c False otherwise.
241 * @returns the value of attribute (name-value pair) corresponding to "name", if defined.
243 string getAttributeValue (in long offset, in string attributeName,
244 out long startOffset,
246 out boolean defined);
248 * getAttributes is deprecated in favor of getAttributeRun.
249 * @returns the attributes at offset, as a semicolon-delimited set of colon-delimited name-value pairs.
250 * @see getAttributeRun
252 string getAttributes (in long offset,
253 out long startOffset, out long endOffset);
255 * Deprecated in favor of getDefaultAttributeSet.
256 * @returns the attributes which apply to the entire text content, but which were not explicitly
257 * specified by the content creator.
258 * @see getDefaultAttributeSet
260 string getDefaultAttributes ();
262 * Obtain a the bounding box, as x, y, width, and height, of the character or glyph at a particular
263 * character offset in this object's text content. The coordinate system in which the results are
264 * reported is specified by coordType. If an onscreen glyph corresponds to multiple character offsets,
265 * for instance if the glyph is a ligature, the bounding box reported will include the entire glyph and
266 * therefore may apply to more than one character offset.
267 * @param offset the character offset of the character or glyph being queried.
268 * @param x the minimum horizontal coordinate of the bounding box of the glyph representing
269 * the character at \c offset.
270 * @param y the minimum vertical coordinate of the bounding box of the glyph representing
271 * the character at \c offset.
272 * @param width the horizontal extent of the bounding box of the glyph representing
273 * the character at \c offset.
274 * @param height the vertical extent of the bounding box of the glyph representing
275 * the character at \c offset.
276 * @param coordType If 0, the results will be reported in screen coordinates, i.e. in pixels
277 * relative to the upper-left corner of the screen, with the x axis pointing right
278 * and the y axis pointing down.
279 * If 1, the results will be reported relative to the containing toplevel window,
280 * with the x axis pointing right and the y axis pointing down.
282 void getCharacterExtents (in long offset, out long x, out long y, out long width, out long height, in short coordType);
284 * Get the offset of the character at a given onscreen coordinate. The coordinate system used to interpret
285 * x and y is determined by parameter coordType.
288 * @param coordType if 0, the input coordinates are interpreted relative to the entire screen, if 1,
289 * they are relative to the toplevel window containing this Text object.
290 * @returns the text offset (as an offset into the character array) of the glyph whose onscreen bounds contain the point x,y, or -1 if the point is outside the bounds of any glyph.
292 long getOffsetAtPoint (in long x, in long y, in short coordType);
294 * Obtain the number of separate, contiguous selections in the current Text object.
295 * Text objects which do not implement selection of discontiguous text regions will always
296 * return '0' or '1'. Note that "contiguous" is defined by continuity of the offsets, i.e.
297 * a text 'selection' is defined by a start/end offset pair. In the case of bidirectional text,
298 * this means that a continguous selection may appear visually discontiguous, and vice-versa.
300 * @returns the number of contiguous selections in the current Text object.
302 long getNSelections ();
304 * The result of calling getSelection with an out-of-range selectionNum (i.e. for a selection
305 * which does not exist) is not strictly defined, but should set endOffset equal to startOffset.
307 void getSelection (in long selectionNum, out long startOffset, out long endOffset);
309 * The result of calling addSelection on objects which already have one selection present, and which
310 * do not include STATE_MULTISELECTABLE, is undefined, other than the return value.
311 * @returns \c True of the selection was successfully added, \c False otherwise. Selection may
312 * fail if the object does not support selection of text (see STATE_SELECTABLE_TEXT), if the
313 * object does not support multiple selections and a selection is already defined, or for other reasons
314 * (for instance if the user does not have permission to copy the text into the relevant selection
317 boolean addSelection (in long startOffset, in long endOffset);
319 * Deselect the text contained in the specified selectionNum, if such a selection
320 * exists, otherwise do nothing. Removal of a non-existant selectionNum has no effect.
321 * @returns \c True if the selection was successfully removed, \c False otherwise.
323 boolean removeSelection (in long selectionNum);
325 * Modify an existing selection's start or ending offset.
327 * Calling setSelection for a selectionNum that is not already defined has no effect.
328 * The result of calling setSelection with a selectionNum greater than 0 for objects that
329 * do not include STATE_MULTISELECTABLE is undefined.
330 * @param selectionNum indicates which of a set of non-contiguous selections to modify.
331 * @param startOffset the new starting offset for the selection
332 * @param endOffset the new ending offset for the selection
333 * @returns \c True if the selection corresponding to selectionNum is successfully modified,
334 * \c False otherwise.
336 boolean setSelection (in long selectionNum, in long startOffset, in long endOffset);
338 * Obtain the bounding box which entirely contains a given text range.
339 * Negative values may be returned for the bounding box parameters in the event
340 * that all or part of the text range is offscreen or not mapped to the screen.
341 * @param startOffset the offset of the first character in the specified range.
342 * @param endOffset the offset of the character immediately after the last
343 * character in the specified range.
344 * @param x an integer parameter which is back-filled with the minimum
345 * horizontal coordinate of the resulting bounding box.
346 * @param y an integer parameter which is back-filled with the minimum
347 * vertical coordinate of the resulting bounding box.
348 * @param width an integer parameter which is back-filled with the
349 * horizontal extent of the bounding box.
350 * @param height an integer parameter which is back-filled with the
351 * vertical extent of the bounding box.
352 * @param coordType If 0, the above coordinates are reported in pixels relative to
353 * corner of the screen; if 1, the coordinates are reported relative to the
354 * corner of the containing toplevel window.
356 void getRangeExtents (in long startOffset, in long endOffset,
357 out long x, out long y,
358 out long width, out long height, in short coordType);
361 * Return the text content within a bounding box,
362 * as a list of Range structures.
363 * Depending on the TEXT_CLIP_TYPE parameters, glyphs which are clipped by the
364 * bounding box (i.e. which lie partially inside and partially outside it)
365 * may or may not be included in the ranges returned.
366 * @note This method may be of particular interest to screen review algorithms.
367 * @see TEXT_CLIP_TYPE.
368 * @param x the minimum x ( i.e. leftmost) coordinate of the bounding box.
369 * @param y the minimum y coordinate of the bounding box.
370 * @param width the horizontal size of the bounding box. The rightmost bound of the bounding box
372 * @param height the vertical size of the bounding box. The maximum y value of the bounding box
374 * @param coordType If 0, the above coordinates are interpreted as pixels relative to
375 * corner of the screen; if 1, the coordinates are interpreted as pixels relative to the
376 * corner of the containing toplevel window.
377 * @param xClipType determines whether text which intersects the bounding box in the x direction
379 * @param yClipType determines whether text which intersects the bounding box in the y direction
382 RangeList getBoundedRanges (in long x, in long y,
383 in long width, in long height,
385 in TEXT_CLIP_TYPE xClipType,
386 in TEXT_CLIP_TYPE yClipType);
391 * placeholders for future expansion.
393 void unImplemented ();
394 void unImplemented2 ();
395 void unImplemented3 ();
396 void unImplemented4 ();