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