accessible/interfaces/nsIAccessibleText.idl

   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 */