michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- michael@0: * michael@0: * This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: typedef long AccessibleTextBoundary; michael@0: michael@0: interface nsIAccessible; michael@0: interface nsIArray; michael@0: interface nsIPersistentProperties; michael@0: interface nsIAccessibleTextRange; michael@0: michael@0: [scriptable, uuid(88789f40-54c9-494a-846d-3acaaf4cf46a)] michael@0: interface nsIAccessibleText : nsISupports michael@0: { michael@0: // In parameters for character offsets: michael@0: // -1 will be treated as the equal to the end of the text michael@0: // -2 will be treated as the caret position michael@0: const int32_t TEXT_OFFSET_END_OF_TEXT = -1; michael@0: const int32_t TEXT_OFFSET_CARET = -2; michael@0: michael@0: const AccessibleTextBoundary BOUNDARY_CHAR = 0; michael@0: const AccessibleTextBoundary BOUNDARY_WORD_START = 1; michael@0: const AccessibleTextBoundary BOUNDARY_WORD_END = 2; michael@0: const AccessibleTextBoundary BOUNDARY_SENTENCE_START = 3; // don't use, deprecated michael@0: const AccessibleTextBoundary BOUNDARY_SENTENCE_END = 4; // don't use, deprecated michael@0: const AccessibleTextBoundary BOUNDARY_LINE_START = 5; michael@0: const AccessibleTextBoundary BOUNDARY_LINE_END = 6; michael@0: michael@0: /** michael@0: * The current current caret offset. michael@0: * If set < 0 then caret will be placed at the end of the text michael@0: */ michael@0: [binaryname(ScriptableCaretOffset)] michael@0: attribute long caretOffset; michael@0: michael@0: readonly attribute long characterCount; michael@0: readonly attribute long selectionCount; michael@0: michael@0: /** michael@0: * String methods may need to return multibyte-encoded strings, michael@0: * since some locales can't be encoded using 16-bit chars. michael@0: * So the methods below might return UTF-16 strings, or they could michael@0: * return "string" values which are UTF-8. michael@0: */ michael@0: AString getText (in long startOffset, in long endOffset); michael@0: michael@0: AString getTextAfterOffset (in long offset, michael@0: in AccessibleTextBoundary boundaryType, michael@0: out long startOffset, michael@0: out long endOffset); michael@0: michael@0: AString getTextAtOffset (in long offset, michael@0: in AccessibleTextBoundary boundaryType, michael@0: out long startOffset, michael@0: out long endOffset); michael@0: michael@0: AString getTextBeforeOffset (in long offset, michael@0: in AccessibleTextBoundary boundaryType, michael@0: out long startOffset, michael@0: out long endOffset); michael@0: michael@0: /** michael@0: * It would be better to return an unsigned long here, michael@0: * to allow unicode chars > 16 bits michael@0: */ michael@0: wchar getCharacterAtOffset (in long offset); michael@0: michael@0: /** michael@0: * Get the accessible start/end offsets around the given offset, michael@0: * return the text attributes for this range of text. michael@0: * michael@0: * @param includeDefAttrs [in] points whether text attributes applied to michael@0: * the entire accessible should be included or not. michael@0: * @param offset [in] text offset michael@0: * @param rangeStartOffset [out] start offset of the range of text michael@0: * @param rangeEndOffset [out] end offset of the range of text michael@0: */ michael@0: nsIPersistentProperties getTextAttributes(in boolean includeDefAttrs, michael@0: in long offset, michael@0: out long rangeStartOffset, michael@0: out long rangeEndOffset); michael@0: michael@0: /** michael@0: * Return the text attributes that apply to the entire accessible. michael@0: */ michael@0: readonly attribute nsIPersistentProperties defaultTextAttributes; michael@0: michael@0: /** michael@0: * Returns the bounding box of the specified position. michael@0: * michael@0: * The virtual character after the last character of the represented text, michael@0: * i.e. the one at position length is a special case. It represents the michael@0: * current input position and will therefore typically be queried by AT more michael@0: * often than other positions. Because it does not represent an existing michael@0: * character its bounding box is defined in relation to preceding characters. michael@0: * It should be roughly equivalent to the bounding box of some character when michael@0: * inserted at the end of the text. Its height typically being the maximal michael@0: * height of all the characters in the text or the height of the preceding michael@0: * character, its width being at least one pixel so that the bounding box is michael@0: * not degenerate. michael@0: * michael@0: * @param offset - Index of the character for which to return its bounding michael@0: * box. The valid range is 0..length. michael@0: * @param x - X coordinate of the bounding box of the referenced character. michael@0: * @param y - Y coordinate of the bounding box of the referenced character. michael@0: * @param width - Width of the bounding box of the referenced character. michael@0: * @param height - Height of the bounding box of the referenced character. michael@0: * @param coordType - Specifies if the coordinates are relative to the screen michael@0: * or to the parent window (see constants declared in michael@0: * nsIAccessibleCoordinateType). michael@0: */ michael@0: void getCharacterExtents (in long offset, michael@0: out long x, michael@0: out long y, michael@0: out long width, michael@0: out long height, michael@0: in unsigned long coordType); michael@0: michael@0: void getRangeExtents (in long startOffset, michael@0: in long endOffset, michael@0: out long x, michael@0: out long y, michael@0: out long width, michael@0: out long height, michael@0: in unsigned long coordType); michael@0: michael@0: /** michael@0: * Get the text offset at the given point, or return -1 michael@0: * if no character exists at that point michael@0: * michael@0: * @param x - The position's x value for which to look up the index of the michael@0: * character that is rendered on to the display at that point. michael@0: * @param y - The position's y value for which to look up the index of the michael@0: * character that is rendered on to the display at that point. michael@0: * @param coordType - Screen coordinates or window coordinates (see constants michael@0: * declared in nsIAccessibleCoordinateType). michael@0: * @return offset - Index of the character under the given point or -1 if michael@0: * the point is invalid or there is no character under michael@0: * the point. michael@0: */ michael@0: long getOffsetAtPoint (in long x, in long y, michael@0: in unsigned long coordType); michael@0: michael@0: void getSelectionBounds (in long selectionNum, michael@0: out long startOffset, michael@0: out long endOffset); michael@0: michael@0: /** michael@0: * Set the bounds for the given selection range michael@0: */ michael@0: void setSelectionBounds (in long selectionNum, michael@0: in long startOffset, michael@0: in long endOffset); michael@0: michael@0: void addSelection (in long startOffset, in long endOffset); michael@0: michael@0: void removeSelection (in long selectionNum); michael@0: michael@0: michael@0: /** michael@0: * Makes a specific part of string visible on screen. michael@0: * michael@0: * @param startIndex 0-based character offset michael@0: * @param endIndex 0-based character offset - the offset of the michael@0: * character just past the last character of the michael@0: * string michael@0: * @param scrollType defines how to scroll (see nsIAccessibleScrollType for michael@0: * available constants) michael@0: */ michael@0: [binaryname(ScriptableScrollSubstringTo)] michael@0: void scrollSubstringTo(in long startIndex, in long endIndex, michael@0: in unsigned long scrollType); michael@0: michael@0: /** michael@0: * Moves the top left of a substring to a specified location. michael@0: * michael@0: * @param startIndex 0-based character offset michael@0: * @param endIndex 0-based character offset - the offset of the michael@0: * character just past the last character of michael@0: * the string michael@0: * @param coordinateType specifies the coordinates origin (for available michael@0: * constants refer to nsIAccessibleCoordinateType) michael@0: * @param x defines the x coordinate michael@0: * @param y defines the y coordinate michael@0: */ michael@0: [binaryname(ScriptableScrollSubstringToPoint)] michael@0: void scrollSubstringToPoint(in long startIndex, in long endIndex, michael@0: in unsigned long coordinateType, michael@0: in long x, in long y); michael@0: michael@0: /** michael@0: * Return a range that encloses this text control or otherwise the document michael@0: * this text accessible belongs to. michael@0: */ michael@0: readonly attribute nsIAccessibleTextRange enclosingRange; michael@0: michael@0: /** michael@0: * Return an array of disjoint ranges for selected text within the text control michael@0: * or otherwise the document this accessible belongs to. michael@0: */ michael@0: readonly attribute nsIArray selectionRanges; michael@0: michael@0: /** michael@0: * Return an array of disjoint ranges of visible text within the text control michael@0: * or otherwise the document this accessible belongs to. michael@0: */ michael@0: readonly attribute nsIArray visibleRanges; michael@0: michael@0: /** michael@0: * Return a range containing the given accessible. michael@0: */ michael@0: nsIAccessibleTextRange getRangeByChild(in nsIAccessible child); michael@0: michael@0: /** michael@0: * Return a range containing an accessible at the given point. michael@0: */ michael@0: nsIAccessibleTextRange getRangeAtPoint(in long x, in long y); michael@0: }; michael@0: michael@0: /* michael@0: Assumptions: michael@0: michael@0: Using wstring (UCS2) instead of string encoded in UTF-8. michael@0: Multibyte encodings (or at least potentially multi-byte michael@0: encodings) would be preferred for the reasons cited above. michael@0: michael@0: The following methods will throw an exception on failure michael@0: (since not every text component will allow every operation): michael@0: setSelectionBounds, addSelection, removeSelection, setCaretOffset. michael@0: michael@0: we assume that all text components support the idea of michael@0: a caret offset, whether visible or "virtual". If this michael@0: isn't the case, caretOffset can be made readonly and michael@0: a setCaretOffset method provided which throws an exception michael@0: on failure (as with *selection methods above). michael@0: */