DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (31ec81b5d7bb)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

typedef long AccessibleTextBoundary;

interface nsIAccessible;
interface nsIPersistentProperties;

[scriptable, uuid(1e63dd8b-173d-4a68-8ade-fd671abbe1ee)]
interface nsIAccessibleText : nsISupports
{
  // In parameters for character offsets:
  //  -1 will be treated as the equal to the end of the text
  //  -2 will be treated as the caret position
  const int32_t TEXT_OFFSET_END_OF_TEXT = -1;
  const int32_t TEXT_OFFSET_CARET       = -2;

  const AccessibleTextBoundary BOUNDARY_CHAR = 0;
  const AccessibleTextBoundary BOUNDARY_WORD_START = 1;
  const AccessibleTextBoundary BOUNDARY_WORD_END = 2;
  const AccessibleTextBoundary BOUNDARY_SENTENCE_START = 3; // don't use, deprecated
  const AccessibleTextBoundary BOUNDARY_SENTENCE_END = 4;  // don't use, deprecated
  const AccessibleTextBoundary BOUNDARY_LINE_START = 5;
  const AccessibleTextBoundary BOUNDARY_LINE_END = 6;

  /**
   * The current current caret offset.
   * If set < 0 then caret will be placed  at the end of the text
   */
  [binaryname(ScriptableCaretOffset)]
  attribute long caretOffset;

  readonly attribute long characterCount;
  readonly attribute long selectionCount;

    /**
      * String methods may need to return multibyte-encoded strings,
      * since some locales can't be encoded using 16-bit chars.
      * So the methods below might return UTF-16 strings, or they could
      * return "string" values which are UTF-8.
      */
  AString getText (in long startOffset, in long endOffset);

  AString getTextAfterOffset (in long offset,
                              in AccessibleTextBoundary boundaryType,
                              out long startOffset,
                              out long endOffset);

  AString getTextAtOffset (in long offset,
                           in AccessibleTextBoundary boundaryType,
                           out long startOffset,
                           out long endOffset);

  AString getTextBeforeOffset (in long offset,
                               in AccessibleTextBoundary boundaryType,
                               out long startOffset,
                               out long endOffset);

    /**
      * It would be better to return an unsigned long here,
      * to allow unicode chars > 16 bits
      */
  wchar getCharacterAtOffset (in long offset);

  /**
   * Get the accessible start/end offsets around the given offset,
   * return the text attributes for this range of text.
   *
   * @param  includeDefAttrs   [in] points whether text attributes applied to
   *                           the entire accessible should be included or not.
   * @param  offset            [in] text offset
   * @param  rangeStartOffset  [out] start offset of the range of text
   * @param  rangeEndOffset    [out] end offset of the range of text
   */
  nsIPersistentProperties getTextAttributes(in boolean includeDefAttrs,
                                            in long offset,
                                            out long rangeStartOffset,
                                            out long rangeEndOffset);

  /**
   * Return the text attributes that apply to the entire accessible.
   */
  readonly attribute nsIPersistentProperties defaultTextAttributes;

  /**
   * Returns the bounding box of the specified position.
   *
   * The virtual character after the last character of the represented text,
   * i.e. the one at position length is a special case. It represents the
   * current input position and will therefore typically be queried by AT more
   * often than other positions. Because it does not represent an existing
   * character its bounding box is defined in relation to preceding characters.
   * It should be roughly equivalent to the bounding box of some character when
   * inserted at the end of the text. Its height typically being the maximal
   * height of all the characters in the text or the height of the preceding
   * character, its width being at least one pixel so that the bounding box is
   * not degenerate.
   *
   * @param offset - Index of the character for which to return its bounding
   *                  box. The valid range is 0..length.
   * @param x - X coordinate of the bounding box of the referenced character.
   * @param y - Y coordinate of the bounding box of the referenced character.
   * @param width - Width of the bounding box of the referenced character.
   * @param height - Height of the bounding box of the referenced character.
   * @param coordType - Specifies if the coordinates are relative to the screen
   *                    or to the parent window (see constants declared in
   *                    nsIAccessibleCoordinateType).
  */
  void getCharacterExtents (in long offset,
                            out long x,
                            out long y,
                            out long width,
                            out long height,
                            in unsigned long coordType);

  void getRangeExtents (in long startOffset,
                        in long endOffset,
                        out long x,
                        out long y,
                        out long width,
                        out long height,
                        in unsigned long coordType);

  /**
   * Get the text offset at the given point, or return -1
   * if no character exists at that point
   *
   * @param x - The position's x value for which to look up the index of the
   *            character that is rendered on to the display at that point.
   * @param y - The position's y value for which to look up the index of the
   *            character that is rendered on to the display at that point.
   * @param coordType - Screen coordinates or window coordinates (see constants
   *                    declared in nsIAccessibleCoordinateType).
   * @return offset - Index of the character under the given point or -1 if
   *                  the point is invalid or there is no character under
   *                  the point.
   */
  long getOffsetAtPoint (in long x, in long y,
                         in unsigned long coordType);

  void getSelectionBounds (in long selectionNum,
                           out long startOffset,
                           out long endOffset);

  /**
   * Set the bounds for the given selection range
   */
  void setSelectionBounds (in long selectionNum,
                           in long startOffset,
                           in long endOffset);

  void addSelection (in long startOffset, in long endOffset);

  void removeSelection (in long selectionNum);


  /**
   * Makes a specific part of string visible on screen.
   *
   * @param startIndex  0-based character offset
   * @param endIndex    0-based character offset - the offset of the
   *                    character just past the last character of the
   *                    string
   * @param scrollType  defines how to scroll (see nsIAccessibleScrollType for
   *                    available constants)
   */
  [binaryname(ScriptableScrollSubstringTo)]
  void scrollSubstringTo(in long startIndex, in long endIndex,
                         in unsigned long scrollType);

  /**
   * Moves the top left of a substring to a specified location.
   *
   * @param startIndex      0-based character offset
   * @param endIndex        0-based character offset - the offset of the
   *                        character just past the last character of
   *                        the string
   * @param coordinateType  specifies the coordinates origin (for available
   *                        constants refer to nsIAccessibleCoordinateType)
   * @param x               defines the x coordinate
   * @param y               defines the y coordinate
   */
  [binaryname(ScriptableScrollSubstringToPoint)]
  void scrollSubstringToPoint(in long startIndex, in long endIndex,
                              in unsigned long coordinateType,
                              in long x, in long y);
};

/*
 Assumptions:

 Using wstring (UCS2) instead of string encoded in UTF-8.
 Multibyte encodings (or at least potentially multi-byte
 encodings) would be preferred for the reasons cited above.

 The following methods will throw an exception on failure
 (since not every text component will allow every operation):
 setSelectionBounds, addSelection, removeSelection, setCaretOffset.

 we assume that all text components support the idea of
 a caret offset, whether visible or "virtual".  If this
 isn't the case, caretOffset can be made readonly and
 a setCaretOffset method provided which throws an exception
 on failure (as with *selection methods above).
*/