The Tor Browser / file comparison

comparison: accessible/public/nsIAccessibleText.idl

accessible/public/nsIAccessibleText.idl

branch
TOR_BUG_9701
changeset 15
b8a032363ba2
equal deleted inserted replaced
-1:000000000000 0:73df398d37a1
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 *
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6
7 #include "nsISupports.idl"
8
9 typedef long AccessibleTextBoundary;
10
11 interface nsIAccessible;
12 interface nsIArray;
13 interface nsIPersistentProperties;
14 interface nsIAccessibleTextRange;
15
16 [scriptable, uuid(88789f40-54c9-494a-846d-3acaaf4cf46a)]
17 interface nsIAccessibleText : nsISupports
18 {
19 // In parameters for character offsets:
20 // -1 will be treated as the equal to the end of the text
21 // -2 will be treated as the caret position
22 const int32_t TEXT_OFFSET_END_OF_TEXT = -1;
23 const int32_t TEXT_OFFSET_CARET = -2;
24
25 const AccessibleTextBoundary BOUNDARY_CHAR = 0;
26 const AccessibleTextBoundary BOUNDARY_WORD_START = 1;
27 const AccessibleTextBoundary BOUNDARY_WORD_END = 2;
28 const AccessibleTextBoundary BOUNDARY_SENTENCE_START = 3; // don't use, deprecated
29 const AccessibleTextBoundary BOUNDARY_SENTENCE_END = 4; // don't use, deprecated
30 const AccessibleTextBoundary BOUNDARY_LINE_START = 5;
31 const AccessibleTextBoundary BOUNDARY_LINE_END = 6;
32
33 /**
34 * The current current caret offset.
35 * If set < 0 then caret will be placed at the end of the text
36 */
37 [binaryname(ScriptableCaretOffset)]
38 attribute long caretOffset;
39
40 readonly attribute long characterCount;
41 readonly attribute long selectionCount;
42
43 /**
44 * String methods may need to return multibyte-encoded strings,
45 * since some locales can't be encoded using 16-bit chars.
46 * So the methods below might return UTF-16 strings, or they could
47 * return "string" values which are UTF-8.
48 */
49 AString getText (in long startOffset, in long endOffset);
50
51 AString getTextAfterOffset (in long offset,
52 in AccessibleTextBoundary boundaryType,
53 out long startOffset,
54 out long endOffset);
55
56 AString getTextAtOffset (in long offset,
57 in AccessibleTextBoundary boundaryType,
58 out long startOffset,
59 out long endOffset);
60
61 AString getTextBeforeOffset (in long offset,
62 in AccessibleTextBoundary boundaryType,
63 out long startOffset,
64 out long endOffset);
65
66 /**
67 * It would be better to return an unsigned long here,
68 * to allow unicode chars > 16 bits
69 */
70 wchar getCharacterAtOffset (in long offset);
71
72 /**
73 * Get the accessible start/end offsets around the given offset,
74 * return the text attributes for this range of text.
75 *
76 * @param includeDefAttrs [in] points whether text attributes applied to
77 * the entire accessible should be included or not.
78 * @param offset [in] text offset
79 * @param rangeStartOffset [out] start offset of the range of text
80 * @param rangeEndOffset [out] end offset of the range of text
81 */
82 nsIPersistentProperties getTextAttributes(in boolean includeDefAttrs,
83 in long offset,
84 out long rangeStartOffset,
85 out long rangeEndOffset);
86
87 /**
88 * Return the text attributes that apply to the entire accessible.
89 */
90 readonly attribute nsIPersistentProperties defaultTextAttributes;
91
92 /**
93 * Returns the bounding box of the specified position.
94 *
95 * The virtual character after the last character of the represented text,
96 * i.e. the one at position length is a special case. It represents the
97 * current input position and will therefore typically be queried by AT more
98 * often than other positions. Because it does not represent an existing
99 * character its bounding box is defined in relation to preceding characters.
100 * It should be roughly equivalent to the bounding box of some character when
101 * inserted at the end of the text. Its height typically being the maximal
102 * height of all the characters in the text or the height of the preceding
103 * character, its width being at least one pixel so that the bounding box is
104 * not degenerate.
105 *
106 * @param offset - Index of the character for which to return its bounding
107 * box. The valid range is 0..length.
108 * @param x - X coordinate of the bounding box of the referenced character.
109 * @param y - Y coordinate of the bounding box of the referenced character.
110 * @param width - Width of the bounding box of the referenced character.
111 * @param height - Height of the bounding box of the referenced character.
112 * @param coordType - Specifies if the coordinates are relative to the screen
113 * or to the parent window (see constants declared in
114 * nsIAccessibleCoordinateType).
115 */
116 void getCharacterExtents (in long offset,
117 out long x,
118 out long y,
119 out long width,
120 out long height,
121 in unsigned long coordType);
122
123 void getRangeExtents (in long startOffset,
124 in long endOffset,
125 out long x,
126 out long y,
127 out long width,
128 out long height,
129 in unsigned long coordType);
130
131 /**
132 * Get the text offset at the given point, or return -1
133 * if no character exists at that point
134 *
135 * @param x - The position's x value for which to look up the index of the
136 * character that is rendered on to the display at that point.
137 * @param y - The position's y value for which to look up the index of the
138 * character that is rendered on to the display at that point.
139 * @param coordType - Screen coordinates or window coordinates (see constants
140 * declared in nsIAccessibleCoordinateType).
141 * @return offset - Index of the character under the given point or -1 if
142 * the point is invalid or there is no character under
143 * the point.
144 */
145 long getOffsetAtPoint (in long x, in long y,
146 in unsigned long coordType);
147
148 void getSelectionBounds (in long selectionNum,
149 out long startOffset,
150 out long endOffset);
151
152 /**
153 * Set the bounds for the given selection range
154 */
155 void setSelectionBounds (in long selectionNum,
156 in long startOffset,
157 in long endOffset);
158
159 void addSelection (in long startOffset, in long endOffset);
160
161 void removeSelection (in long selectionNum);
162
163
164 /**
165 * Makes a specific part of string visible on screen.
166 *
167 * @param startIndex 0-based character offset
168 * @param endIndex 0-based character offset - the offset of the
169 * character just past the last character of the
170 * string
171 * @param scrollType defines how to scroll (see nsIAccessibleScrollType for
172 * available constants)
173 */
174 [binaryname(ScriptableScrollSubstringTo)]
175 void scrollSubstringTo(in long startIndex, in long endIndex,
176 in unsigned long scrollType);
177
178 /**
179 * Moves the top left of a substring to a specified location.
180 *
181 * @param startIndex 0-based character offset
182 * @param endIndex 0-based character offset - the offset of the
183 * character just past the last character of
184 * the string
185 * @param coordinateType specifies the coordinates origin (for available
186 * constants refer to nsIAccessibleCoordinateType)
187 * @param x defines the x coordinate
188 * @param y defines the y coordinate
189 */
190 [binaryname(ScriptableScrollSubstringToPoint)]
191 void scrollSubstringToPoint(in long startIndex, in long endIndex,
192 in unsigned long coordinateType,
193 in long x, in long y);
194
195 /**
196 * Return a range that encloses this text control or otherwise the document
197 * this text accessible belongs to.
198 */
199 readonly attribute nsIAccessibleTextRange enclosingRange;
200
201 /**
202 * Return an array of disjoint ranges for selected text within the text control
203 * or otherwise the document this accessible belongs to.
204 */
205 readonly attribute nsIArray selectionRanges;
206
207 /**
208 * Return an array of disjoint ranges of visible text within the text control
209 * or otherwise the document this accessible belongs to.
210 */
211 readonly attribute nsIArray visibleRanges;
212
213 /**
214 * Return a range containing the given accessible.
215 */
216 nsIAccessibleTextRange getRangeByChild(in nsIAccessible child);
217
218 /**
219 * Return a range containing an accessible at the given point.
220 */
221 nsIAccessibleTextRange getRangeAtPoint(in long x, in long y);
222 };
223
224 /*
225 Assumptions:
226
227 Using wstring (UCS2) instead of string encoded in UTF-8.
228 Multibyte encodings (or at least potentially multi-byte
229 encodings) would be preferred for the reasons cited above.
230
231 The following methods will throw an exception on failure
232 (since not every text component will allow every operation):
233 setSelectionBounds, addSelection, removeSelection, setCaretOffset.
234
235 we assume that all text components support the idea of
236 a caret offset, whether visible or "virtual". If this
237 isn't the case, caretOffset can be made readonly and
238 a setCaretOffset method provided which throws an exception
239 on failure (as with *selection methods above).
240 */

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial