accessible/public/nsIAccessibleText.idl@6474c204b198
accessible/public/nsIAccessibleText.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
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/. */
7 #include "nsISupports.idl"
9 typedef long AccessibleTextBoundary;
11 interface nsIAccessible;
12 interface nsIArray;
13 interface nsIPersistentProperties;
14 interface nsIAccessibleTextRange;
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;
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;
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;
40 readonly attribute long characterCount;
41 readonly attribute long selectionCount;
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);
51 AString getTextAfterOffset (in long offset,
52 in AccessibleTextBoundary boundaryType,
53 out long startOffset,
54 out long endOffset);
56 AString getTextAtOffset (in long offset,
57 in AccessibleTextBoundary boundaryType,
58 out long startOffset,
59 out long endOffset);
61 AString getTextBeforeOffset (in long offset,
62 in AccessibleTextBoundary boundaryType,
63 out long startOffset,
64 out long endOffset);
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);
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);
87 /**
88 * Return the text attributes that apply to the entire accessible.
89 */
90 readonly attribute nsIPersistentProperties defaultTextAttributes;
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);
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);
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);
148 void getSelectionBounds (in long selectionNum,
149 out long startOffset,
150 out long endOffset);
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);
159 void addSelection (in long startOffset, in long endOffset);
161 void removeSelection (in long selectionNum);
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);
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);
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;
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;
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;
213 /**
214 * Return a range containing the given accessible.
215 */
216 nsIAccessibleTextRange getRangeByChild(in nsIAccessible child);
218 /**
219 * Return a range containing an accessible at the given point.
220 */
221 nsIAccessibleTextRange getRangeAtPoint(in long x, in long y);
222 };
224 /*
225 Assumptions:
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.
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.
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 */
