accessible/public/nsIAccessibleText.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is the Mozilla browser.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications Corporation.
  20  * Portions created by the Initial Developer are Copyright (C) 1999
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Paul Sandoz (paul.sandoz@sun.com)
  25  *   Bill Haneman (bill.haneman@sun.com)
  26  *   John Gaunt (jgaunt@netscape.com)
  27  *
  28  * Alternatively, the contents of this file may be used under the terms of
  29  * either of the GNU General Public License Version 2 or later (the "GPL"),
  30  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  31  * in which case the provisions of the GPL or the LGPL are applicable instead
  32  * of those above. If you wish to allow use of your version of this file only
  33  * under the terms of either the GPL or the LGPL, and not to allow others to
  34  * use your version of this file under the terms of the MPL, indicate your
  35  * decision by deleting the provisions above and replace them with the notice
  36  * and other provisions required by the GPL or the LGPL. If you do not delete
  37  * the provisions above, a recipient may use your version of this file under
  38  * the terms of any one of the MPL, the GPL or the LGPL.
  39  *
  40  * ***** END LICENSE BLOCK ***** */
  41
  42 #include "nsISupports.idl"
  43
  44 typedef long nsAccessibleTextBoundary;
  45
  46 interface nsIAccessible;
  47 interface nsIPersistentProperties;
  48
  49 [scriptable, uuid(0f4633b1-550c-4b50-8c04-0eb1005eef2f)]
  50 interface nsIAccessibleText : nsISupports
  51 {
  52   // In parameters for character offsets:
  53   //  -1 will be treated as the equal to the end of the text
  54   //  -2 will be treated as the caret position
  55   const PRInt32 TEXT_OFFSET_END_OF_TEXT = -1;
  56   const PRInt32 TEXT_OFFSET_CARET       = -2;
  57
  58   const nsAccessibleTextBoundary BOUNDARY_CHAR = 0;
  59   const nsAccessibleTextBoundary BOUNDARY_WORD_START = 1;
  60   const nsAccessibleTextBoundary BOUNDARY_WORD_END = 2;
  61   const nsAccessibleTextBoundary BOUNDARY_SENTENCE_START = 3; // don't use, deprecated
  62   const nsAccessibleTextBoundary BOUNDARY_SENTENCE_END = 4;  // don't use, deprecated
  63   const nsAccessibleTextBoundary BOUNDARY_LINE_START = 5;
  64   const nsAccessibleTextBoundary BOUNDARY_LINE_END = 6;
  65   const nsAccessibleTextBoundary BOUNDARY_ATTRIBUTE_RANGE = 7;
  66
  67   /**
  68    * The current current caret offset.
  69    * If set < 0 then caret will be placed  at the end of the text
  70    */
  71   attribute long caretOffset;
  72
  73   readonly attribute long characterCount;
  74   readonly attribute long selectionCount;
  75
  76     /**
  77       * String methods may need to return multibyte-encoded strings,
  78       * since some locales can't be encoded using 16-bit chars.
  79       * So the methods below might return UTF-16 strings, or they could
  80       * return "string" values which are UTF-8.
  81       */
  82   AString getText (in long startOffset, in long endOffset);
  83
  84   AString getTextAfterOffset (in long offset,
  85                               in nsAccessibleTextBoundary boundaryType,
  86                               out long startOffset,
  87                               out long endOffset);
  88
  89   AString getTextAtOffset (in long offset,
  90                            in nsAccessibleTextBoundary boundaryType,
  91                            out long startOffset,
  92                            out long endOffset);
  93
  94   AString getTextBeforeOffset (in long offset,
  95                                in nsAccessibleTextBoundary boundaryType,
  96                                out long startOffset,
  97                                out long endOffset);
  98
  99     /**
 100       * It would be better to return an unsigned long here,
 101       * to allow unicode chars > 16 bits
 102       */
 103   wchar getCharacterAtOffset (in long offset);
 104
 105   /**
 106    * Get the accessible start/end offsets around the given offset,
 107    * return the text attributes for this range of text.
 108    *
 109    * @param  includeDefAttrs   [in] points whether text attributes applied to
 110    *                           the entire accessible should be included or not.
 111    * @param  offset            [in] text offset
 112    * @param  rangeStartOffset  [out] start offset of the range of text
 113    * @param  rangeEndOffset    [out] end offset of the range of text
 114    */
 115   nsIPersistentProperties getTextAttributes(in boolean includeDefAttrs,
 116                                             in long offset,
 117                                             out long rangeStartOffset,
 118                                             out long rangeEndOffset);
 119
 120   /**
 121    * Return the text attributes that apply to the entire accessible.
 122    */
 123   readonly attribute nsIPersistentProperties defaultTextAttributes;
 124
 125   /**
 126    * Returns the bounding box of the specified position.
 127    *
 128    * The virtual character after the last character of the represented text,
 129    * i.e. the one at position length is a special case. It represents the
 130    * current input position and will therefore typically be queried by AT more
 131    * often than other positions. Because it does not represent an existing
 132    * character its bounding box is defined in relation to preceding characters.
 133    * It should be roughly equivalent to the bounding box of some character when
 134    * inserted at the end of the text. Its height typically being the maximal
 135    * height of all the characters in the text or the height of the preceding
 136    * character, its width being at least one pixel so that the bounding box is
 137    * not degenerate.
 138    *
 139    * @param offset - Index of the character for which to return its bounding
 140    *                  box. The valid range is 0..length.
 141    * @param x - X coordinate of the bounding box of the referenced character.
 142    * @param y - Y coordinate of the bounding box of the referenced character.
 143    * @param width - Width of the bounding box of the referenced character.
 144    * @param height - Height of the bounding box of the referenced character.
 145    * @param coordType - Specifies if the coordinates are relative to the screen
 146    *                    or to the parent window (see constants declared in
 147    *                    nsIAccessibleCoordinateType).
 148   */
 149   void getCharacterExtents (in long offset,
 150                             out long x,
 151                             out long y,
 152                             out long width,
 153                             out long height,
 154                             in unsigned long coordType);
 155
 156   void getRangeExtents (in long startOffset,
 157                         in long endOffset,
 158                         out long x,
 159                         out long y,
 160                         out long width,
 161                         out long height,
 162                         in unsigned long coordType);
 163
 164   /**
 165    * Get the text offset at the given point, or return -1
 166    * if no character exists at that point
 167    *
 168    * @param x - The position's x value for which to look up the index of the
 169    *            character that is rendered on to the display at that point.
 170    * @param y - The position's y value for which to look up the index of the
 171    *            character that is rendered on to the display at that point.
 172    * @param coordType - Screen coordinates or window coordinates (see constants
 173    *                    declared in nsIAccessibleCoordinateType).
 174    * @return offset - Index of the character under the given point or -1 if
 175    *                  the point is invalid or there is no character under
 176    *                  the point.
 177    */
 178   long getOffsetAtPoint (in long x, in long y,
 179                          in unsigned long coordType);
 180
 181   void getSelectionBounds (in long selectionNum,
 182                            out long startOffset,
 183                            out long endOffset);
 184
 185   /**
 186    * Set the bounds for the given selection range
 187    */
 188   void setSelectionBounds (in long selectionNum,
 189                            in long startOffset,
 190                            in long endOffset);
 191
 192   void addSelection (in long startOffset, in long endOffset);
 193
 194   void removeSelection (in long selectionNum);
 195
 196
 197   /**
 198    * Makes a specific part of string visible on screen.
 199    *
 200    * @param startIndex  0-based character offset
 201    * @param endIndex    0-based character offset - the offset of the
 202    *                    character just past the last character of the
 203    *                    string
 204    * @param scrollType  defines how to scroll (see nsIAccessibleScrollType for
 205    *                    available constants)
 206    */
 207   void scrollSubstringTo(in long startIndex, in long endIndex,
 208                          in unsigned long scrollType);
 209
 210   /**
 211    * Moves the top left of a substring to a specified location.
 212    *
 213    * @param startIndex      0-based character offset
 214    * @param endIndex        0-based character offset - the offset of the
 215    *                        character just past the last character of
 216    *                        the string
 217    * @param coordinateType  specifies the coordinates origin (for available
 218    *                        constants refer to nsIAccessibleCoordinateType)
 219    * @param x               defines the x coordinate
 220    * @param y               defines the y coordinate
 221    */
 222   void scrollSubstringToPoint(in long startIndex, in long endIndex,
 223                               in unsigned long coordinateType,
 224                               in long x, in long y);
 225 };
 226
 227 /*
 228  Assumptions:
 229
 230  Using wstring (UCS2) instead of string encoded in UTF-8.
 231  Multibyte encodings (or at least potentially multi-byte
 232  encodings) would be preferred for the reasons cited above.
 233
 234  The following methods will throw an exception on failure
 235  (since not every text component will allow every operation):
 236  setSelectionBounds, addSelection, removeSelection, setCaretOffset.
 237
 238  we assume that all text components support the idea of
 239  a caret offset, whether visible or "virtual".  If this
 240  isn't the case, caretOffset can be made readonly and
 241  a setCaretOffset method provided which throws an exception
 242  on failure (as with *selection methods above).
 243 */