nsIAccessibleText.idl (9702B)
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, builtinclass, uuid(a4cc7576-45bb-44c5-b347-d9cb3ca4de9f)] 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 // A single Unicode character. For a user-perceived character, see 26 // BOUNDARY_CLUSTER. 27 const AccessibleTextBoundary BOUNDARY_CHAR = 0; 28 const AccessibleTextBoundary BOUNDARY_WORD_START = 1; 29 const AccessibleTextBoundary BOUNDARY_WORD_END = 2; 30 const AccessibleTextBoundary BOUNDARY_SENTENCE_START = 3; // don't use, deprecated 31 const AccessibleTextBoundary BOUNDARY_SENTENCE_END = 4; // don't use, deprecated 32 const AccessibleTextBoundary BOUNDARY_LINE_START = 5; 33 const AccessibleTextBoundary BOUNDARY_LINE_END = 6; 34 const AccessibleTextBoundary BOUNDARY_PARAGRAPH = 7; 35 // A grapheme cluster, AKA user-perceived character. This might consist of 36 // multiple Unicode characters, but a user will perceive this as a single 37 // character and it is treated as such by the caret, selection, etc. 38 const AccessibleTextBoundary BOUNDARY_CLUSTER = 8; 39 40 /** 41 * The current current caret offset. 42 * If set < 0 then caret will be placed at the end of the text 43 */ 44 attribute long caretOffset; 45 46 void getCaretRect(out long x, out long y, out long width, out long height); 47 48 readonly attribute long characterCount; 49 readonly attribute long selectionCount; 50 51 /** 52 * String methods may need to return multibyte-encoded strings, 53 * since some locales can't be encoded using 16-bit chars. 54 * So the methods below might return UTF-16 strings, or they could 55 * return "string" values which are UTF-8. 56 */ 57 AString getText (in long startOffset, in long endOffset); 58 59 AString getTextAfterOffset (in long offset, 60 in AccessibleTextBoundary boundaryType, 61 out long startOffset, 62 out long endOffset); 63 64 AString getTextAtOffset (in long offset, 65 in AccessibleTextBoundary boundaryType, 66 out long startOffset, 67 out long endOffset); 68 69 AString getTextBeforeOffset (in long offset, 70 in AccessibleTextBoundary boundaryType, 71 out long startOffset, 72 out long endOffset); 73 74 /** 75 * It would be better to return an unsigned long here, 76 * to allow unicode chars > 16 bits 77 */ 78 wchar getCharacterAtOffset (in long offset); 79 80 /** 81 * Get the accessible start/end offsets around the given offset, 82 * return the text attributes for this range of text. 83 * 84 * @param includeDefAttrs [in] points whether text attributes applied to 85 * the entire accessible should be included or not. 86 * @param offset [in] text offset 87 * @param rangeStartOffset [out] start offset of the range of text 88 * @param rangeEndOffset [out] end offset of the range of text 89 */ 90 nsIPersistentProperties getTextAttributes(in boolean includeDefAttrs, 91 in long offset, 92 out long rangeStartOffset, 93 out long rangeEndOffset); 94 95 /** 96 * Return the text attributes that apply to the entire accessible. 97 */ 98 readonly attribute nsIPersistentProperties defaultTextAttributes; 99 100 /** 101 * Returns the bounding box of the specified position. 102 * 103 * The virtual character after the last character of the represented text, 104 * i.e. the one at position length is a special case. It represents the 105 * current input position and will therefore typically be queried by AT more 106 * often than other positions. Because it does not represent an existing 107 * character its bounding box is defined in relation to preceding characters. 108 * It should be roughly equivalent to the bounding box of some character when 109 * inserted at the end of the text. Its height typically being the maximal 110 * height of all the characters in the text or the height of the preceding 111 * character, its width being at least one pixel so that the bounding box is 112 * not degenerate. 113 * 114 * @param offset - Index of the character for which to return its bounding 115 * box. The valid range is 0..length. 116 * @param x - X coordinate of the bounding box of the referenced character. 117 * @param y - Y coordinate of the bounding box of the referenced character. 118 * @param width - Width of the bounding box of the referenced character. 119 * @param height - Height of the bounding box of the referenced character. 120 * @param coordType - Specifies if the coordinates are relative to the screen 121 * or to the parent window (see constants declared in 122 * nsIAccessibleCoordinateType). 123 */ 124 void getCharacterExtents (in long offset, 125 out long x, 126 out long y, 127 out long width, 128 out long height, 129 in unsigned long coordType); 130 131 void getRangeExtents (in long startOffset, 132 in long endOffset, 133 out long x, 134 out long y, 135 out long width, 136 out long height, 137 in unsigned long coordType); 138 139 /** 140 * Get the text offset at the given point, or return -1 141 * if no character exists at that point 142 * 143 * @param x - The position's x value for which to look up the index of the 144 * character that is rendered on to the display at that point. 145 * @param y - The position's y value for which to look up the index of the 146 * character that is rendered on to the display at that point. 147 * @param coordType - Screen coordinates or window coordinates (see constants 148 * declared in nsIAccessibleCoordinateType). 149 * @return offset - Index of the character under the given point or -1 if 150 * the point is invalid or there is no character under 151 * the point. 152 */ 153 long getOffsetAtPoint (in long x, in long y, 154 in unsigned long coordType); 155 156 void getSelectionBounds (in long selectionNum, 157 out long startOffset, 158 out long endOffset); 159 160 /** 161 * Set the bounds for the given selection range. 162 * A reverse range where the start offset is larger than the end offset is 163 * acceptable. The caretOffset will be set to the endOffset argument. 164 */ 165 void setSelectionBounds (in long selectionNum, 166 in long startOffset, 167 in long endOffset); 168 169 void addSelection (in long startOffset, in long endOffset); 170 171 void removeSelection (in long selectionNum); 172 173 174 /** 175 * Makes a specific part of string visible on screen. 176 * 177 * @param startIndex 0-based character offset 178 * @param endIndex 0-based character offset - the offset of the 179 * character just past the last character of the 180 * string 181 * @param scrollType defines how to scroll (see nsIAccessibleScrollType for 182 * available constants) 183 */ 184 void scrollSubstringTo(in long startIndex, in long endIndex, 185 in unsigned long scrollType); 186 187 /** 188 * Moves the top left of a substring to a specified location. 189 * 190 * @param startIndex 0-based character offset 191 * @param endIndex 0-based character offset - the offset of the 192 * character just past the last character of 193 * the string 194 * @param coordinateType specifies the coordinates origin (for available 195 * constants refer to nsIAccessibleCoordinateType) 196 * @param x defines the x coordinate 197 * @param y defines the y coordinate 198 */ 199 void scrollSubstringToPoint(in long startIndex, in long endIndex, 200 in unsigned long coordinateType, 201 in long x, in long y); 202 203 /** 204 * Return an array of disjoint ranges for selected text within the text control 205 * or otherwise the document this accessible belongs to. 206 */ 207 readonly attribute nsIArray selectionRanges; 208 }; 209 210 /* 211 Assumptions: 212 213 Using wstring (UCS2) instead of string encoded in UTF-8. 214 Multibyte encodings (or at least potentially multi-byte 215 encodings) would be preferred for the reasons cited above. 216 217 The following methods will throw an exception on failure 218 (since not every text component will allow every operation): 219 setSelectionBounds, addSelection, removeSelection, setCaretOffset. 220 221 we assume that all text components support the idea of 222 a caret offset, whether visible or "virtual". If this 223 isn't the case, caretOffset can be made readonly and 224 a setCaretOffset method provided which throws an exception 225 on failure (as with *selection methods above). 226 */