HyperTextAccessibleBase.h (10991B)
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 MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual void SetCaretOffset(int32_t aOffset); 86 87 /** 88 * Return the caret rect and the widget containing the caret within this 89 * text accessible. 90 * 91 * @return the caret rect and containing widget 92 */ 93 virtual std::pair<mozilla::LayoutDeviceIntRect, nsIWidget*> 94 GetCaretRect() = 0; 95 96 /** 97 * Provide the line number for the caret. 98 * @return 1-based index for the line number with the caret 99 */ 100 virtual int32_t CaretLineNumber(); 101 102 /** 103 * Transform magic offset into text offset. 104 */ 105 index_t ConvertMagicOffset(int32_t aOffset) const; 106 107 /** 108 * Return text between given offsets. 109 */ 110 void TextSubstring(int32_t aStartOffset, int32_t aEndOffset, 111 nsAString& aText) const; 112 113 /** 114 * Get a character at the given offset (don't support magic offsets). 115 */ 116 bool CharAt(int32_t aOffset, nsAString& aChar, 117 int32_t* aStartOffset = nullptr, int32_t* aEndOffset = nullptr); 118 119 char16_t CharAt(int32_t aOffset) { 120 nsAutoString charAtOffset; 121 CharAt(aOffset, charAtOffset); 122 return charAtOffset.CharAt(0); 123 } 124 125 /** 126 * Return a rect (in dev pixels) for character at given offset relative 127 * given coordinate system. 128 */ 129 LayoutDeviceIntRect CharBounds(int32_t aOffset, uint32_t aCoordType); 130 131 /** 132 * Return a rect (in dev pixels) of the given text range relative given 133 * coordinate system. 134 */ 135 LayoutDeviceIntRect TextBounds( 136 int32_t aStartOffset, int32_t aEndOffset, 137 uint32_t aCoordType = 138 nsIAccessibleCoordinateType::COORDTYPE_SCREEN_RELATIVE); 139 140 /** 141 * Return the offset of the char that contains the given coordinates. 142 */ 143 virtual int32_t OffsetAtPoint(int32_t aX, int32_t aY, uint32_t aCoordType); 144 145 /** 146 * Get a TextLeafPoint for a given offset in this HyperTextAccessible. 147 * If the offset points to an embedded object and aDescendToEnd is true, 148 * the point right at the end of this subtree will be returned instead of the 149 * start. 150 */ 151 TextLeafPoint ToTextLeafPoint(int32_t aOffset, bool aDescendToEnd = false); 152 153 /** 154 * Return text before/at/after the given offset corresponding to 155 * the boundary type. 156 */ 157 void TextBeforeOffset(int32_t aOffset, AccessibleTextBoundary aBoundaryType, 158 int32_t* aStartOffset, int32_t* aEndOffset, 159 nsAString& aText); 160 void TextAtOffset(int32_t aOffset, AccessibleTextBoundary aBoundaryType, 161 int32_t* aStartOffset, int32_t* aEndOffset, 162 nsAString& aText); 163 void TextAfterOffset(int32_t aOffset, AccessibleTextBoundary aBoundaryType, 164 int32_t* aStartOffset, int32_t* aEndOffset, 165 nsAString& aText); 166 167 /** 168 * Return true if the given offset/range is valid. 169 */ 170 bool IsValidOffset(int32_t aOffset); 171 bool IsValidRange(int32_t aStartOffset, int32_t aEndOffset); 172 173 /** 174 * Return link count within this hypertext accessible. 175 */ 176 uint32_t LinkCount(); 177 178 /** 179 * Return link accessible at the given index. 180 */ 181 Accessible* LinkAt(uint32_t aIndex); 182 183 /** 184 * Return index for the given link accessible. 185 */ 186 int32_t LinkIndexOf(Accessible* aLink); 187 188 /** 189 * Return link accessible at the given text offset. 190 */ 191 int32_t LinkIndexAtOffset(uint32_t aOffset) { 192 Accessible* child = GetChildAtOffset(aOffset); 193 return child ? LinkIndexOf(child) : -1; 194 } 195 196 /** 197 * Transform the given a11y point into an offset relative to this hypertext. 198 * Returns {success, offset}, where success is true if successful. 199 * If unsuccessful, the returned offset will be CharacterCount() if 200 * aIsEndOffset is true, 0 otherwise. This means most callers can ignore the 201 * success return value. 202 */ 203 std::pair<bool, int32_t> TransformOffset(Accessible* aDescendant, 204 int32_t aOffset, 205 bool aIsEndOffset) const; 206 207 /** 208 * Return text attributes for the given text range. 209 */ 210 already_AddRefed<AccAttributes> TextAttributes(bool aIncludeDefAttrs, 211 int32_t aOffset, 212 int32_t* aStartOffset, 213 int32_t* aEndOffset); 214 215 /** 216 * Return text attributes applied to the accessible. 217 */ 218 virtual already_AddRefed<AccAttributes> DefaultTextAttributes() = 0; 219 220 /** 221 * Return an array of disjoint ranges for selected text within the text 222 * control or the document this accessible belongs to. 223 */ 224 virtual void SelectionRanges(nsTArray<TextRange>* aRanges) const = 0; 225 226 /** 227 * Return text selection ranges cropped to this Accessible (rather than for 228 * the entire text control or document). This also excludes collapsed ranges. 229 */ 230 void CroppedSelectionRanges(nsTArray<TextRange>& aRanges) const; 231 232 /** 233 * Return selected regions count within the accessible. 234 */ 235 virtual int32_t SelectionCount(); 236 237 /** 238 * Return the start and end offset of the specified selection. 239 */ 240 virtual bool SelectionBoundsAt(int32_t aSelectionNum, int32_t* aStartOffset, 241 int32_t* aEndOffset); 242 243 /** 244 * Changes the start and end offset of the specified selection. 245 * @return true if succeeded 246 */ 247 // TODO: annotate this with `MOZ_CAN_RUN_SCRIPT` instead. 248 MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual bool SetSelectionBoundsAt( 249 int32_t aSelectionNum, int32_t aStartOffset, int32_t aEndOffset); 250 251 /** 252 * Adds a selection bounded by the specified offsets. 253 * @return true if succeeded 254 */ 255 bool AddToSelection(int32_t aStartOffset, int32_t aEndOffset) { 256 return SetSelectionBoundsAt(-1, aStartOffset, aEndOffset); 257 } 258 259 /** 260 * Removes the specified selection, or removes all selections if aSelectionNum 261 *is TextLeafRange::kRemoveAllExistingSelectedRanges. 262 * @return true if succeeded 263 */ 264 // TODO: annotate this with `MOZ_CAN_RUN_SCRIPT` instead. 265 MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual bool RemoveFromSelection( 266 int32_t aSelectionNum) = 0; 267 268 /** 269 * Scroll the given text range into view. 270 */ 271 MOZ_CAN_RUN_SCRIPT_BOUNDARY void ScrollSubstringTo(int32_t aStartOffset, 272 int32_t aEndOffset, 273 uint32_t aScrollType); 274 275 /** 276 * Scroll the given text range to the given point. 277 */ 278 virtual void ScrollSubstringToPoint(int32_t aStartOffset, int32_t aEndOffset, 279 uint32_t aCoordinateType, int32_t aX, 280 int32_t aY) = 0; 281 282 ////////////////////////////////////////////////////////////////////////////// 283 // EditableTextAccessible 284 285 MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual void ReplaceText( 286 const nsAString& aText) = 0; 287 MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual void InsertText(const nsAString& aText, 288 int32_t aPosition) = 0; 289 MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual void CopyText(int32_t aStartPos, 290 int32_t aEndPos) = 0; 291 MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual void CutText(int32_t aStartPos, 292 int32_t aEndPos) = 0; 293 MOZ_CAN_RUN_SCRIPT_BOUNDARY virtual void DeleteText(int32_t aStartPos, 294 int32_t aEndPos) = 0; 295 MOZ_CAN_RUN_SCRIPT virtual void PasteText(int32_t aPosition) = 0; 296 297 protected: 298 virtual const Accessible* Acc() const = 0; 299 Accessible* Acc() { 300 const Accessible* acc = 301 const_cast<const HyperTextAccessibleBase*>(this)->Acc(); 302 return const_cast<Accessible*>(acc); 303 } 304 305 /** 306 * Get the cached map of child indexes to HyperText offsets. 307 * This is an array which contains the exclusive end offset for each child. 308 * That is, the start offset for child c is array index c - 1. 309 */ 310 virtual nsTArray<int32_t>& GetCachedHyperTextOffsets() = 0; 311 312 private: 313 /** 314 * Helper method for TextBefore/At/AfterOffset. 315 * If BOUNDARY_LINE_END was requested and the origin is itself a line end 316 * boundary, we must use the line which ends at the origin. We must do 317 * similarly for BOUNDARY_WORD_END. This method adjusts the origin 318 * accordingly. 319 */ 320 void AdjustOriginIfEndBoundary(TextLeafPoint& aOrigin, 321 AccessibleTextBoundary aBoundaryType, 322 bool aAtOffset = false) const; 323 }; 324 325 } // namespace mozilla::a11y 326 327 #endif