accessible/basetypes/HyperTextAccessibleBase.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef _HyperTextAccessibleBase_H_
   7 #define _HyperTextAccessibleBase_H_
   8
   9 #include "AccAttributes.h"
  10 #include "nsIAccessibleText.h"
  11 #include "nsIAccessibleTypes.h"
  12
  13 namespace mozilla::a11y {
  14 class Accessible;
  15 class TextLeafPoint;
  16 class TextRange;
  17
  18 // This character marks where in the text returned via Text interface,
  19 // that embedded object characters exist
  20 const char16_t kEmbeddedObjectChar = 0xfffc;
  21 const char16_t kImaginaryEmbeddedObjectChar = ' ';
  22 const char16_t kForcedNewLineChar = '\n';
  23
  24 /**
  25  * An index type. Assert if out of range value was attempted to be used.
  26  */
  27 class index_t {
  28  public:
  29   MOZ_IMPLICIT index_t(int32_t aVal) : mVal(aVal) {}
  30
  31   operator uint32_t() const {
  32     MOZ_ASSERT(mVal >= 0, "Attempt to use wrong index!");
  33     return mVal;
  34   }
  35
  36   bool IsValid() const { return mVal >= 0; }
  37
  38  private:
  39   int32_t mVal;
  40 };
  41
  42 class HyperTextAccessibleBase {
  43  public:
  44   /**
  45    * Return child accessible at the given text offset.
  46    *
  47    * @param  aOffset  [in] the given text offset
  48    */
  49   virtual int32_t GetChildIndexAtOffset(uint32_t aOffset) const;
  50
  51   /**
  52    * Return child accessible at the given text offset.
  53    *
  54    * @param  aOffset  [in] the given text offset
  55    */
  56   virtual Accessible* GetChildAtOffset(uint32_t aOffset) const;
  57
  58   /**
  59    * Return text offset of the given child accessible within hypertext
  60    * accessible.
  61    *
  62    * @param  aChild           [in] accessible child to get text offset for
  63    * @param  aInvalidateAfter [in, optional] indicates whether to invalidate
  64    *                           cached offsets for subsequent siblings of the
  65    *                           child.
  66    */
  67   int32_t GetChildOffset(const Accessible* aChild,
  68                          bool aInvalidateAfter = false) const;
  69
  70   /**
  71    * Return text offset for the child accessible index.
  72    */
  73   virtual int32_t GetChildOffset(uint32_t aChildIndex,
  74                                  bool aInvalidateAfter = false) const;
  75
  76   /**
  77    * Return character count within the hypertext accessible.
  78    */
  79   uint32_t CharacterCount() const;
  80
  81   /**
  82    * Get/set caret offset, if no caret then -1.
  83    */
  84   virtual int32_t CaretOffset() const;
  85   virtual void SetCaretOffset(int32_t aOffset) = 0;
  86
  87   /**
  88    * Provide the line number for the caret.
  89    * @return 1-based index for the line number with the caret
  90    */
  91   virtual int32_t CaretLineNumber();
  92
  93   /**
  94    * Transform magic offset into text offset.
  95    */
  96   index_t ConvertMagicOffset(int32_t aOffset) const;
  97
  98   /**
  99    * Return text between given offsets.
 100    */
 101   void TextSubstring(int32_t aStartOffset, int32_t aEndOffset,
 102                      nsAString& aText) const;
 103
 104   /**
 105    * Get a character at the given offset (don't support magic offsets).
 106    */
 107   bool CharAt(int32_t aOffset, nsAString& aChar,
 108               int32_t* aStartOffset = nullptr, int32_t* aEndOffset = nullptr);
 109
 110   char16_t CharAt(int32_t aOffset) {
 111     nsAutoString charAtOffset;
 112     CharAt(aOffset, charAtOffset);
 113     return charAtOffset.CharAt(0);
 114   }
 115
 116   /**
 117    * Return a rect (in dev pixels) for character at given offset relative
 118    * given coordinate system.
 119    */
 120   LayoutDeviceIntRect CharBounds(int32_t aOffset, uint32_t aCoordType);
 121
 122   /**
 123    * Return a rect (in dev pixels) of the given text range relative given
 124    * coordinate system.
 125    */
 126   LayoutDeviceIntRect TextBounds(
 127       int32_t aStartOffset, int32_t aEndOffset,
 128       uint32_t aCoordType =
 129           nsIAccessibleCoordinateType::COORDTYPE_SCREEN_RELATIVE);
 130
 131   /**
 132    * Return the offset of the char that contains the given coordinates.
 133    */
 134   virtual int32_t OffsetAtPoint(int32_t aX, int32_t aY, uint32_t aCoordType);
 135
 136   /**
 137    * Get a TextLeafPoint for a given offset in this HyperTextAccessible.
 138    * If the offset points to an embedded object and aDescendToEnd is true,
 139    * the point right at the end of this subtree will be returned instead of the
 140    * start.
 141    */
 142   TextLeafPoint ToTextLeafPoint(int32_t aOffset, bool aDescendToEnd = false);
 143
 144   /**
 145    * Return text before/at/after the given offset corresponding to
 146    * the boundary type.
 147    */
 148   void TextBeforeOffset(int32_t aOffset, AccessibleTextBoundary aBoundaryType,
 149                         int32_t* aStartOffset, int32_t* aEndOffset,
 150                         nsAString& aText);
 151   void TextAtOffset(int32_t aOffset, AccessibleTextBoundary aBoundaryType,
 152                     int32_t* aStartOffset, int32_t* aEndOffset,
 153                     nsAString& aText);
 154   void TextAfterOffset(int32_t aOffset, AccessibleTextBoundary aBoundaryType,
 155                        int32_t* aStartOffset, int32_t* aEndOffset,
 156                        nsAString& aText);
 157
 158   /**
 159    * Return true if the given offset/range is valid.
 160    */
 161   bool IsValidOffset(int32_t aOffset);
 162   bool IsValidRange(int32_t aStartOffset, int32_t aEndOffset);
 163
 164   /**
 165    * Return link count within this hypertext accessible.
 166    */
 167   uint32_t LinkCount();
 168
 169   /**
 170    * Return link accessible at the given index.
 171    */
 172   Accessible* LinkAt(uint32_t aIndex);
 173
 174   /**
 175    * Return index for the given link accessible.
 176    */
 177   int32_t LinkIndexOf(Accessible* aLink);
 178
 179   /**
 180    * Return link accessible at the given text offset.
 181    */
 182   int32_t LinkIndexAtOffset(uint32_t aOffset) {
 183     Accessible* child = GetChildAtOffset(aOffset);
 184     return child ? LinkIndexOf(child) : -1;
 185   }
 186
 187   /**
 188    * Transform the given a11y point into an offset relative to this hypertext.
 189    * Returns {success, offset}, where success is true if successful.
 190    * If unsuccessful, the returned offset will be CharacterCount() if
 191    * aIsEndOffset is true, 0 otherwise. This means most callers can ignore the
 192    * success return value.
 193    */
 194   std::pair<bool, int32_t> TransformOffset(Accessible* aDescendant,
 195                                            int32_t aOffset,
 196                                            bool aIsEndOffset) const;
 197
 198   /**
 199    * Return text attributes for the given text range.
 200    */
 201   already_AddRefed<AccAttributes> TextAttributes(bool aIncludeDefAttrs,
 202                                                  int32_t aOffset,
 203                                                  int32_t* aStartOffset,
 204                                                  int32_t* aEndOffset);
 205
 206   /**
 207    * Return text attributes applied to the accessible.
 208    */
 209   virtual already_AddRefed<AccAttributes> DefaultTextAttributes() = 0;
 210
 211   /**
 212    * Return an array of disjoint ranges for selected text within the text
 213    * control or the document this accessible belongs to.
 214    */
 215   virtual void SelectionRanges(nsTArray<TextRange>* aRanges) const = 0;
 216
 217   /**
 218    * Return text selection ranges cropped to this Accessible (rather than for
 219    * the entire text control or document). This also excludes collapsed ranges.
 220    */
 221   void CroppedSelectionRanges(nsTArray<TextRange>& aRanges) const;
 222
 223   /**
 224    * Return selected regions count within the accessible.
 225    */
 226   virtual int32_t SelectionCount();
 227
 228   /**
 229    * Return the start and end offset of the specified selection.
 230    */
 231   virtual bool SelectionBoundsAt(int32_t aSelectionNum, int32_t* aStartOffset,
 232                                  int32_t* aEndOffset);
 233
 234   /**
 235    * Changes the start and end offset of the specified selection.
 236    * @return true if succeeded
 237    */
 238   // TODO: annotate this with `MOZ_CAN_RUN_SCRIPT` instead.
 239   MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual bool SetSelectionBoundsAt(
 240       int32_t aSelectionNum, int32_t aStartOffset, int32_t aEndOffset);
 241
 242   /**
 243    * Adds a selection bounded by the specified offsets.
 244    * @return true if succeeded
 245    */
 246   bool AddToSelection(int32_t aStartOffset, int32_t aEndOffset) {
 247     return SetSelectionBoundsAt(-1, aStartOffset, aEndOffset);
 248   }
 249
 250   /**
 251    * Removes the specified selection.
 252    * @return true if succeeded
 253    */
 254   // TODO: annotate this with `MOZ_CAN_RUN_SCRIPT` instead.
 255   MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual bool RemoveFromSelection(
 256       int32_t aSelectionNum) = 0;
 257
 258   /**
 259    * Scroll the given text range into view.
 260    */
 261   MOZ_CAN_RUN_SCRIPT_BOUNDARY void ScrollSubstringTo(int32_t aStartOffset,
 262                                                      int32_t aEndOffset,
 263                                                      uint32_t aScrollType);
 264
 265   /**
 266    * Scroll the given text range to the given point.
 267    */
 268   virtual void ScrollSubstringToPoint(int32_t aStartOffset, int32_t aEndOffset,
 269                                       uint32_t aCoordinateType, int32_t aX,
 270                                       int32_t aY) = 0;
 271
 272   //////////////////////////////////////////////////////////////////////////////
 273   // EditableTextAccessible
 274
 275   MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual void ReplaceText(
 276       const nsAString& aText) = 0;
 277   MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual void InsertText(const nsAString& aText,
 278                                                       int32_t aPosition) = 0;
 279   MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual void CopyText(int32_t aStartPos,
 280                                                     int32_t aEndPos) = 0;
 281   MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual void CutText(int32_t aStartPos,
 282                                                    int32_t aEndPos) = 0;
 283   MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual void DeleteText(int32_t aStartPos,
 284                                                       int32_t aEndPos) = 0;
 285   MOZ_CAN_RUN_SCRIPT virtual void PasteText(int32_t aPosition) = 0;
 286
 287  protected:
 288   virtual const Accessible* Acc() const = 0;
 289   Accessible* Acc() {
 290     const Accessible* acc =
 291         const_cast<const HyperTextAccessibleBase*>(this)->Acc();
 292     return const_cast<Accessible*>(acc);
 293   }
 294
 295   /**
 296    * Get the cached map of child indexes to HyperText offsets.
 297    * This is an array which contains the exclusive end offset for each child.
 298    * That is, the start offset for child c is array index c - 1.
 299    */
 300   virtual nsTArray<int32_t>& GetCachedHyperTextOffsets() = 0;
 301
 302  private:
 303   /**
 304    * Helper method for TextBefore/At/AfterOffset.
 305    * If BOUNDARY_LINE_END was requested and the origin is itself a line end
 306    * boundary, we must use the line which ends at the origin. We must do
 307    * similarly for BOUNDARY_WORD_END. This method adjusts the origin
 308    * accordingly.
 309    */
 310   void AdjustOriginIfEndBoundary(TextLeafPoint& aOrigin,
 311                                  AccessibleTextBoundary aBoundaryType,
 312                                  bool aAtOffset = false) const;
 313 };
 314
 315 }  // namespace mozilla::a11y
 316
 317 #endif