1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/accessible/public/nsIAccessibleText.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,240 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +typedef long AccessibleTextBoundary;
1.13 +
1.14 +interface nsIAccessible;
1.15 +interface nsIArray;
1.16 +interface nsIPersistentProperties;
1.17 +interface nsIAccessibleTextRange;
1.18 +
1.19 +[scriptable, uuid(88789f40-54c9-494a-846d-3acaaf4cf46a)]
1.20 +interface nsIAccessibleText : nsISupports
1.21 +{
1.22 + // In parameters for character offsets:
1.23 + // -1 will be treated as the equal to the end of the text
1.24 + // -2 will be treated as the caret position
1.25 + const int32_t TEXT_OFFSET_END_OF_TEXT = -1;
1.26 + const int32_t TEXT_OFFSET_CARET = -2;
1.27 +
1.28 + const AccessibleTextBoundary BOUNDARY_CHAR = 0;
1.29 + const AccessibleTextBoundary BOUNDARY_WORD_START = 1;
1.30 + const AccessibleTextBoundary BOUNDARY_WORD_END = 2;
1.31 + const AccessibleTextBoundary BOUNDARY_SENTENCE_START = 3; // don't use, deprecated
1.32 + const AccessibleTextBoundary BOUNDARY_SENTENCE_END = 4; // don't use, deprecated
1.33 + const AccessibleTextBoundary BOUNDARY_LINE_START = 5;
1.34 + const AccessibleTextBoundary BOUNDARY_LINE_END = 6;
1.35 +
1.36 + /**
1.37 + * The current current caret offset.
1.38 + * If set < 0 then caret will be placed at the end of the text
1.39 + */
1.40 + [binaryname(ScriptableCaretOffset)]
1.41 + attribute long caretOffset;
1.42 +
1.43 + readonly attribute long characterCount;
1.44 + readonly attribute long selectionCount;
1.45 +
1.46 + /**
1.47 + * String methods may need to return multibyte-encoded strings,
1.48 + * since some locales can't be encoded using 16-bit chars.
1.49 + * So the methods below might return UTF-16 strings, or they could
1.50 + * return "string" values which are UTF-8.
1.51 + */
1.52 + AString getText (in long startOffset, in long endOffset);
1.53 +
1.54 + AString getTextAfterOffset (in long offset,
1.55 + in AccessibleTextBoundary boundaryType,
1.56 + out long startOffset,
1.57 + out long endOffset);
1.58 +
1.59 + AString getTextAtOffset (in long offset,
1.60 + in AccessibleTextBoundary boundaryType,
1.61 + out long startOffset,
1.62 + out long endOffset);
1.63 +
1.64 + AString getTextBeforeOffset (in long offset,
1.65 + in AccessibleTextBoundary boundaryType,
1.66 + out long startOffset,
1.67 + out long endOffset);
1.68 +
1.69 + /**
1.70 + * It would be better to return an unsigned long here,
1.71 + * to allow unicode chars > 16 bits
1.72 + */
1.73 + wchar getCharacterAtOffset (in long offset);
1.74 +
1.75 + /**
1.76 + * Get the accessible start/end offsets around the given offset,
1.77 + * return the text attributes for this range of text.
1.78 + *
1.79 + * @param includeDefAttrs [in] points whether text attributes applied to
1.80 + * the entire accessible should be included or not.
1.81 + * @param offset [in] text offset
1.82 + * @param rangeStartOffset [out] start offset of the range of text
1.83 + * @param rangeEndOffset [out] end offset of the range of text
1.84 + */
1.85 + nsIPersistentProperties getTextAttributes(in boolean includeDefAttrs,
1.86 + in long offset,
1.87 + out long rangeStartOffset,
1.88 + out long rangeEndOffset);
1.89 +
1.90 + /**
1.91 + * Return the text attributes that apply to the entire accessible.
1.92 + */
1.93 + readonly attribute nsIPersistentProperties defaultTextAttributes;
1.94 +
1.95 + /**
1.96 + * Returns the bounding box of the specified position.
1.97 + *
1.98 + * The virtual character after the last character of the represented text,
1.99 + * i.e. the one at position length is a special case. It represents the
1.100 + * current input position and will therefore typically be queried by AT more
1.101 + * often than other positions. Because it does not represent an existing
1.102 + * character its bounding box is defined in relation to preceding characters.
1.103 + * It should be roughly equivalent to the bounding box of some character when
1.104 + * inserted at the end of the text. Its height typically being the maximal
1.105 + * height of all the characters in the text or the height of the preceding
1.106 + * character, its width being at least one pixel so that the bounding box is
1.107 + * not degenerate.
1.108 + *
1.109 + * @param offset - Index of the character for which to return its bounding
1.110 + * box. The valid range is 0..length.
1.111 + * @param x - X coordinate of the bounding box of the referenced character.
1.112 + * @param y - Y coordinate of the bounding box of the referenced character.
1.113 + * @param width - Width of the bounding box of the referenced character.
1.114 + * @param height - Height of the bounding box of the referenced character.
1.115 + * @param coordType - Specifies if the coordinates are relative to the screen
1.116 + * or to the parent window (see constants declared in
1.117 + * nsIAccessibleCoordinateType).
1.118 + */
1.119 + void getCharacterExtents (in long offset,
1.120 + out long x,
1.121 + out long y,
1.122 + out long width,
1.123 + out long height,
1.124 + in unsigned long coordType);
1.125 +
1.126 + void getRangeExtents (in long startOffset,
1.127 + in long endOffset,
1.128 + out long x,
1.129 + out long y,
1.130 + out long width,
1.131 + out long height,
1.132 + in unsigned long coordType);
1.133 +
1.134 + /**
1.135 + * Get the text offset at the given point, or return -1
1.136 + * if no character exists at that point
1.137 + *
1.138 + * @param x - The position's x value for which to look up the index of the
1.139 + * character that is rendered on to the display at that point.
1.140 + * @param y - The position's y value for which to look up the index of the
1.141 + * character that is rendered on to the display at that point.
1.142 + * @param coordType - Screen coordinates or window coordinates (see constants
1.143 + * declared in nsIAccessibleCoordinateType).
1.144 + * @return offset - Index of the character under the given point or -1 if
1.145 + * the point is invalid or there is no character under
1.146 + * the point.
1.147 + */
1.148 + long getOffsetAtPoint (in long x, in long y,
1.149 + in unsigned long coordType);
1.150 +
1.151 + void getSelectionBounds (in long selectionNum,
1.152 + out long startOffset,
1.153 + out long endOffset);
1.154 +
1.155 + /**
1.156 + * Set the bounds for the given selection range
1.157 + */
1.158 + void setSelectionBounds (in long selectionNum,
1.159 + in long startOffset,
1.160 + in long endOffset);
1.161 +
1.162 + void addSelection (in long startOffset, in long endOffset);
1.163 +
1.164 + void removeSelection (in long selectionNum);
1.165 +
1.166 +
1.167 + /**
1.168 + * Makes a specific part of string visible on screen.
1.169 + *
1.170 + * @param startIndex 0-based character offset
1.171 + * @param endIndex 0-based character offset - the offset of the
1.172 + * character just past the last character of the
1.173 + * string
1.174 + * @param scrollType defines how to scroll (see nsIAccessibleScrollType for
1.175 + * available constants)
1.176 + */
1.177 + [binaryname(ScriptableScrollSubstringTo)]
1.178 + void scrollSubstringTo(in long startIndex, in long endIndex,
1.179 + in unsigned long scrollType);
1.180 +
1.181 + /**
1.182 + * Moves the top left of a substring to a specified location.
1.183 + *
1.184 + * @param startIndex 0-based character offset
1.185 + * @param endIndex 0-based character offset - the offset of the
1.186 + * character just past the last character of
1.187 + * the string
1.188 + * @param coordinateType specifies the coordinates origin (for available
1.189 + * constants refer to nsIAccessibleCoordinateType)
1.190 + * @param x defines the x coordinate
1.191 + * @param y defines the y coordinate
1.192 + */
1.193 + [binaryname(ScriptableScrollSubstringToPoint)]
1.194 + void scrollSubstringToPoint(in long startIndex, in long endIndex,
1.195 + in unsigned long coordinateType,
1.196 + in long x, in long y);
1.197 +
1.198 + /**
1.199 + * Return a range that encloses this text control or otherwise the document
1.200 + * this text accessible belongs to.
1.201 + */
1.202 + readonly attribute nsIAccessibleTextRange enclosingRange;
1.203 +
1.204 + /**
1.205 + * Return an array of disjoint ranges for selected text within the text control
1.206 + * or otherwise the document this accessible belongs to.
1.207 + */
1.208 + readonly attribute nsIArray selectionRanges;
1.209 +
1.210 + /**
1.211 + * Return an array of disjoint ranges of visible text within the text control
1.212 + * or otherwise the document this accessible belongs to.
1.213 + */
1.214 + readonly attribute nsIArray visibleRanges;
1.215 +
1.216 + /**
1.217 + * Return a range containing the given accessible.
1.218 + */
1.219 + nsIAccessibleTextRange getRangeByChild(in nsIAccessible child);
1.220 +
1.221 + /**
1.222 + * Return a range containing an accessible at the given point.
1.223 + */
1.224 + nsIAccessibleTextRange getRangeAtPoint(in long x, in long y);
1.225 +};
1.226 +
1.227 +/*
1.228 + Assumptions:
1.229 +
1.230 + Using wstring (UCS2) instead of string encoded in UTF-8.
1.231 + Multibyte encodings (or at least potentially multi-byte
1.232 + encodings) would be preferred for the reasons cited above.
1.233 +
1.234 + The following methods will throw an exception on failure
1.235 + (since not every text component will allow every operation):
1.236 + setSelectionBounds, addSelection, removeSelection, setCaretOffset.
1.237 +
1.238 + we assume that all text components support the idea of
1.239 + a caret offset, whether visible or "virtual". If this
1.240 + isn't the case, caretOffset can be made readonly and
1.241 + a setCaretOffset method provided which throws an exception
1.242 + on failure (as with *selection methods above).
1.243 +*/
