michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef mozilla_a11y_HyperTextAccessible_h__
michael@0: #define mozilla_a11y_HyperTextAccessible_h__
michael@0: 
michael@0: #include "AccessibleWrap.h"
michael@0: #include "nsIAccessibleTypes.h"
michael@0: #include "xpcAccessibleHyperText.h"
michael@0: 
michael@0: #include "nsFrameSelection.h"
michael@0: #include "nsISelectionController.h"
michael@0: 
michael@0: namespace mozilla {
michael@0: namespace a11y {
michael@0: 
michael@0: class TextRange;
michael@0: 
michael@0: struct DOMPoint {
michael@0:   DOMPoint() : node(nullptr), idx(0) { }
michael@0:   DOMPoint(nsINode* aNode, int32_t aIdx) : node(aNode), idx(aIdx) { }
michael@0: 
michael@0:   nsINode* node;
michael@0:   int32_t idx;
michael@0: };
michael@0: 
michael@0: // This character marks where in the text returned via nsIAccessibleText(),
michael@0: // that embedded object characters exist
michael@0: const char16_t kEmbeddedObjectChar = 0xfffc;
michael@0: const char16_t kImaginaryEmbeddedObjectChar = ' ';
michael@0: const char16_t kForcedNewLineChar = '\n';
michael@0: 
michael@0: /**
michael@0:   * Special Accessible that knows how contain both text and embedded objects
michael@0:   */
michael@0: class HyperTextAccessible : public AccessibleWrap,
michael@0:                             public xpcAccessibleHyperText
michael@0: {
michael@0: public:
michael@0:   HyperTextAccessible(nsIContent* aContent, DocAccessible* aDoc);
michael@0:   virtual ~HyperTextAccessible() { }
michael@0: 
michael@0:   NS_DECL_ISUPPORTS_INHERITED
michael@0: 
michael@0:   // Accessible
michael@0:   virtual int32_t GetLevelInternal();
michael@0:   virtual already_AddRefed<nsIPersistentProperties> NativeAttributes() MOZ_OVERRIDE;
michael@0:   virtual mozilla::a11y::role NativeRole();
michael@0:   virtual uint64_t NativeState();
michael@0: 
michael@0:   virtual void InvalidateChildren();
michael@0:   virtual bool RemoveChild(Accessible* aAccessible);
michael@0: 
michael@0:   // HyperTextAccessible (static helper method)
michael@0: 
michael@0:   // Convert content offset to rendered text offset
michael@0:   nsresult ContentToRenderedOffset(nsIFrame *aFrame, int32_t aContentOffset,
michael@0:                                    uint32_t *aRenderedOffset) const;
michael@0: 
michael@0:   // Convert rendered text offset to content offset
michael@0:   nsresult RenderedToContentOffset(nsIFrame *aFrame, uint32_t aRenderedOffset,
michael@0:                                    int32_t *aContentOffset) const;
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // HyperLinkAccessible
michael@0: 
michael@0:   /**
michael@0:    * Return link count within this hypertext accessible.
michael@0:    */
michael@0:   uint32_t LinkCount()
michael@0:     { return EmbeddedChildCount(); }
michael@0: 
michael@0:   /**
michael@0:    * Return link accessible at the given index.
michael@0:    */
michael@0:   Accessible* LinkAt(uint32_t aIndex)
michael@0:   {
michael@0:     return GetEmbeddedChildAt(aIndex);
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return index for the given link accessible.
michael@0:    */
michael@0:   int32_t LinkIndexOf(Accessible* aLink)
michael@0:   {
michael@0:     return GetIndexOfEmbeddedChild(aLink);
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return link accessible at the given text offset.
michael@0:    */
michael@0:   int32_t LinkIndexAtOffset(uint32_t aOffset)
michael@0:   {
michael@0:     Accessible* child = GetChildAtOffset(aOffset);
michael@0:     return child ? LinkIndexOf(child) : -1;
michael@0:   }
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // HyperTextAccessible: DOM point to text offset conversions.
michael@0: 
michael@0:   /**
michael@0:    * Turn a DOM point (node and offset) into a character offset of this
michael@0:    * hypertext. Will look for closest match when the DOM node does not have
michael@0:    * an accessible object associated with it. Will return an offset for the end
michael@0:    * of the string if the node is not found.
michael@0:    *
michael@0:    * @param aNode         [in] the node to look for
michael@0:    * @param aNodeOffset   [in] the offset to look for
michael@0:    *                       if -1 just look directly for the node
michael@0:    *                       if >=0 and aNode is text, this represents a char offset
michael@0:    *                       if >=0 and aNode is not text, this represents a child node offset
michael@0:    * @param aIsEndOffset  [in] if true, then then this offset is not inclusive. The character
michael@0:    *                       indicated by the offset returned is at [offset - 1]. This means
michael@0:    *                       if the passed-in offset is really in a descendant, then the offset returned
michael@0:    *                       will come just after the relevant embedded object characer.
michael@0:    *                       If false, then the offset is inclusive. The character indicated
michael@0:    *                       by the offset returned is at [offset]. If the passed-in offset in inside a
michael@0:    *                       descendant, then the returned offset will be on the relevant embedded object char.
michael@0:    */
michael@0:   int32_t DOMPointToOffset(nsINode* aNode, int32_t aNodeOffset,
michael@0:                            bool aIsEndOffset = false) const;
michael@0: 
michael@0:   /**
michael@0:    * Transform the given a11y point into the offset relative this hypertext.
michael@0:    */
michael@0:   int32_t TransformOffset(Accessible* aDescendant, int32_t aOffset,
michael@0:                           bool aIsEndOffset) const;
michael@0: 
michael@0:   /**
michael@0:    * Convert start and end hypertext offsets into DOM range.
michael@0:    *
michael@0:    * @param  aStartOffset  [in] the given start hypertext offset
michael@0:    * @param  aEndOffset    [in] the given end hypertext offset
michael@0:    * @param  aRange        [in, out] the range whose bounds to set
michael@0:    * @return true   if conversion was successful
michael@0:    */
michael@0:   bool OffsetsToDOMRange(int32_t aStartOffset, int32_t aEndOffset,
michael@0:                          nsRange* aRange);
michael@0: 
michael@0:   /**
michael@0:    * Convert the given offset into DOM point.
michael@0:    *
michael@0:    * If offset is at text leaf then DOM point is (text node, offsetInTextNode),
michael@0:    * if before embedded object then (parent node, indexInParent), if after then
michael@0:    * (parent node, indexInParent + 1).
michael@0:    */
michael@0:   DOMPoint OffsetToDOMPoint(int32_t aOffset);
michael@0: 
michael@0:   /**
michael@0:    * Return true if the used ARIA role (if any) allows the hypertext accessible
michael@0:    * to expose text interfaces.
michael@0:    */
michael@0:   bool IsTextRole();
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // TextAccessible
michael@0: 
michael@0:   /**
michael@0:    * Return character count within the hypertext accessible.
michael@0:    */
michael@0:   uint32_t CharacterCount() const
michael@0:     { return GetChildOffset(ChildCount()); }
michael@0: 
michael@0:   /**
michael@0:    * Get a character at the given offset (don't support magic offsets).
michael@0:    */
michael@0:   bool CharAt(int32_t aOffset, nsAString& aChar,
michael@0:               int32_t* aStartOffset = nullptr, int32_t* aEndOffset = nullptr)
michael@0:   {
michael@0:     NS_ASSERTION(!aStartOffset == !aEndOffset,
michael@0:                  "Offsets should be both defined or both undefined!");
michael@0: 
michael@0:     int32_t childIdx = GetChildIndexAtOffset(aOffset);
michael@0:     if (childIdx == -1)
michael@0:       return false;
michael@0: 
michael@0:     Accessible* child = GetChildAt(childIdx);
michael@0:     child->AppendTextTo(aChar, aOffset - GetChildOffset(childIdx), 1);
michael@0: 
michael@0:     if (aStartOffset && aEndOffset) {
michael@0:       *aStartOffset = aOffset;
michael@0:       *aEndOffset = aOffset + aChar.Length();
michael@0:     }
michael@0:     return true;
michael@0:   }
michael@0: 
michael@0:   char16_t CharAt(int32_t aOffset)
michael@0:   {
michael@0:     nsAutoString charAtOffset;
michael@0:     CharAt(aOffset, charAtOffset);
michael@0:     return charAtOffset.CharAt(0);
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return true if char at the given offset equals to given char.
michael@0:    */
michael@0:   bool IsCharAt(int32_t aOffset, char16_t aChar)
michael@0:     { return CharAt(aOffset) == aChar; }
michael@0: 
michael@0:   /**
michael@0:    * Return true if terminal char is at the given offset.
michael@0:    */
michael@0:   bool IsLineEndCharAt(int32_t aOffset)
michael@0:     { return IsCharAt(aOffset, '\n'); }
michael@0: 
michael@0:   /**
michael@0:    * Return text between given offsets.
michael@0:    */
michael@0:   void TextSubstring(int32_t aStartOffset, int32_t aEndOffset, nsAString& aText);
michael@0: 
michael@0:   /**
michael@0:    * Return text before/at/after the given offset corresponding to
michael@0:    * the boundary type.
michael@0:    */
michael@0:   void TextBeforeOffset(int32_t aOffset, AccessibleTextBoundary aBoundaryType,
michael@0:                        int32_t* aStartOffset, int32_t* aEndOffset,
michael@0:                        nsAString& aText);
michael@0:   void TextAtOffset(int32_t aOffset, AccessibleTextBoundary aBoundaryType,
michael@0:                     int32_t* aStartOffset, int32_t* aEndOffset,
michael@0:                     nsAString& aText);
michael@0:   void TextAfterOffset(int32_t aOffset, AccessibleTextBoundary aBoundaryType,
michael@0:                        int32_t* aStartOffset, int32_t* aEndOffset,
michael@0:                        nsAString& aText);
michael@0: 
michael@0:   /**
michael@0:    * Return text attributes for the given text range.
michael@0:    */
michael@0:   already_AddRefed<nsIPersistentProperties>
michael@0:     TextAttributes(bool aIncludeDefAttrs, int32_t aOffset,
michael@0:                    int32_t* aStartOffset, int32_t* aEndOffset);
michael@0: 
michael@0:   /**
michael@0:    * Return text attributes applied to the accessible.
michael@0:    */
michael@0:   already_AddRefed<nsIPersistentProperties> DefaultTextAttributes();
michael@0: 
michael@0:   /**
michael@0:    * Return text offset of the given child accessible within hypertext
michael@0:    * accessible.
michael@0:    *
michael@0:    * @param  aChild           [in] accessible child to get text offset for
michael@0:    * @param  aInvalidateAfter [in, optional] indicates whether invalidate
michael@0:    *                           cached offsets for next siblings of the child
michael@0:    */
michael@0:   int32_t GetChildOffset(Accessible* aChild,
michael@0:                          bool aInvalidateAfter = false) const
michael@0:   {
michael@0:     int32_t index = GetIndexOf(aChild);
michael@0:     return index == -1 ? -1 : GetChildOffset(index, aInvalidateAfter);
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return text offset for the child accessible index.
michael@0:    */
michael@0:   int32_t GetChildOffset(uint32_t aChildIndex,
michael@0:                          bool aInvalidateAfter = false) const;
michael@0: 
michael@0:   /**
michael@0:    * Return child accessible at the given text offset.
michael@0:    *
michael@0:    * @param  aOffset  [in] the given text offset
michael@0:    */
michael@0:   int32_t GetChildIndexAtOffset(uint32_t aOffset) const;
michael@0: 
michael@0:   /**
michael@0:    * Return child accessible at the given text offset.
michael@0:    *
michael@0:    * @param  aOffset  [in] the given text offset
michael@0:    */
michael@0:   Accessible* GetChildAtOffset(uint32_t aOffset) const
michael@0:   {
michael@0:     return GetChildAt(GetChildIndexAtOffset(aOffset));
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return true if the given offset/range is valid.
michael@0:    */
michael@0:   bool IsValidOffset(int32_t aOffset);
michael@0:   bool IsValidRange(int32_t aStartOffset, int32_t aEndOffset);
michael@0: 
michael@0:   /**
michael@0:    * Return an offset at the given point.
michael@0:    */
michael@0:   int32_t OffsetAtPoint(int32_t aX, int32_t aY, uint32_t aCoordType);
michael@0: 
michael@0:   /**
michael@0:    * Return a rect of the given text range relative given coordinate system.
michael@0:    */
michael@0:   nsIntRect TextBounds(int32_t aStartOffset, int32_t aEndOffset,
michael@0:                        uint32_t aCoordType = nsIAccessibleCoordinateType::COORDTYPE_SCREEN_RELATIVE);
michael@0: 
michael@0:   /**
michael@0:    * Return a rect for character at given offset relative given coordinate
michael@0:    * system.
michael@0:    */
michael@0:   nsIntRect CharBounds(int32_t aOffset, uint32_t aCoordType)
michael@0:     { return TextBounds(aOffset, aOffset + 1, aCoordType); }
michael@0: 
michael@0:   /**
michael@0:    * Get/set caret offset, if no caret then -1.
michael@0:    */
michael@0:   int32_t CaretOffset() const;
michael@0:   void SetCaretOffset(int32_t aOffset) { SetSelectionRange(aOffset, aOffset); }
michael@0: 
michael@0:   /**
michael@0:    * Provide the line number for the caret.
michael@0:    * @return 1-based index for the line number with the caret
michael@0:    */
michael@0:   int32_t CaretLineNumber();
michael@0: 
michael@0:   /**
michael@0:    * Return the caret rect and the widget containing the caret within this
michael@0:    * text accessible.
michael@0:    *
michael@0:    * @param [out] the widget containing the caret
michael@0:    * @return      the caret rect
michael@0:    */
michael@0:   nsIntRect GetCaretRect(nsIWidget** aWidget);
michael@0: 
michael@0:   /**
michael@0:    * Return selected regions count within the accessible.
michael@0:    */
michael@0:   int32_t SelectionCount();
michael@0: 
michael@0:   /**
michael@0:    * Return the start and end offset of the specified selection.
michael@0:    */
michael@0:   bool SelectionBoundsAt(int32_t aSelectionNum,
michael@0:                          int32_t* aStartOffset, int32_t* aEndOffset);
michael@0: 
michael@0:   /*
michael@0:    * Changes the start and end offset of the specified selection.
michael@0:    * @return true if succeeded
michael@0:    */
michael@0:   bool SetSelectionBoundsAt(int32_t aSelectionNum,
michael@0:                             int32_t aStartOffset, int32_t aEndOffset);
michael@0: 
michael@0:   /**
michael@0:    * Adds a selection bounded by the specified offsets.
michael@0:    * @return true if succeeded
michael@0:    */
michael@0:   bool AddToSelection(int32_t aStartOffset, int32_t aEndOffset);
michael@0: 
michael@0:   /*
michael@0:    * Removes the specified selection.
michael@0:    * @return true if succeeded
michael@0:    */
michael@0:   bool RemoveFromSelection(int32_t aSelectionNum);
michael@0: 
michael@0:   /**
michael@0:    * Scroll the given text range into view.
michael@0:    */
michael@0:   void ScrollSubstringTo(int32_t aStartOffset, int32_t aEndOffset,
michael@0:                          uint32_t aScrollType);
michael@0: 
michael@0:   /**
michael@0:    * Scroll the given text range to the given point.
michael@0:    */
michael@0:   void ScrollSubstringToPoint(int32_t aStartOffset,
michael@0:                               int32_t aEndOffset,
michael@0:                               uint32_t aCoordinateType,
michael@0:                               int32_t aX, int32_t aY);
michael@0: 
michael@0:   /**
michael@0:    * Return a range that encloses the text control or the document this
michael@0:    * accessible belongs to.
michael@0:    */
michael@0:   void EnclosingRange(TextRange& aRange) const;
michael@0: 
michael@0:   /**
michael@0:    * Return an array of disjoint ranges for selected text within the text control
michael@0:    * or the document this accessible belongs to.
michael@0:    */
michael@0:   void SelectionRanges(nsTArray<TextRange>* aRanges) const;
michael@0: 
michael@0:   /**
michael@0:    * Return an array of disjoint ranges of visible text within the text control
michael@0:    * or the document this accessible belongs to.
michael@0:    */
michael@0:   void VisibleRanges(nsTArray<TextRange>* aRanges) const;
michael@0: 
michael@0:   /**
michael@0:    * Return a range containing the given accessible.
michael@0:    */
michael@0:   void RangeByChild(Accessible* aChild, TextRange& aRange) const;
michael@0: 
michael@0:   /**
michael@0:    * Return a range containing an accessible at the given point.
michael@0:    */
michael@0:   void RangeAtPoint(int32_t aX, int32_t aY, TextRange& aRange) const;
michael@0: 
michael@0:   //////////////////////////////////////////////////////////////////////////////
michael@0:   // EditableTextAccessible
michael@0: 
michael@0:   void ReplaceText(const nsAString& aText);
michael@0:   void InsertText(const nsAString& aText, int32_t aPosition);
michael@0:   void CopyText(int32_t aStartPos, int32_t aEndPos);
michael@0:   void CutText(int32_t aStartPos, int32_t aEndPos);
michael@0:   void DeleteText(int32_t aStartPos, int32_t aEndPos);
michael@0:   void PasteText(int32_t aPosition);
michael@0: 
michael@0:   /**
michael@0:    * Return the editor associated with the accessible.
michael@0:    */
michael@0:   virtual already_AddRefed<nsIEditor> GetEditor() const;
michael@0: 
michael@0: protected:
michael@0:   // Accessible
michael@0:   virtual ENameValueFlag NativeName(nsString& aName) MOZ_OVERRIDE;
michael@0:   virtual void CacheChildren() MOZ_OVERRIDE;
michael@0: 
michael@0:   // HyperTextAccessible
michael@0: 
michael@0:   /**
michael@0:    * Transform magic offset into text offset.
michael@0:    */
michael@0:   int32_t ConvertMagicOffset(int32_t aOffset);
michael@0: 
michael@0:   /**
michael@0:    * Adjust an offset the caret stays at to get a text by line boundary.
michael@0:    */
michael@0:   int32_t AdjustCaretOffset(int32_t aOffset) const;
michael@0: 
michael@0:   /**
michael@0:    * Return true if caret is at end of line.
michael@0:    */
michael@0:   bool IsCaretAtEndOfLine() const;
michael@0: 
michael@0:   /**
michael@0:    * Return true if the given offset points to terminal empty line if any.
michael@0:    */
michael@0:   bool IsEmptyLastLineOffset(int32_t aOffset)
michael@0:   {
michael@0:     return aOffset == static_cast<int32_t>(CharacterCount()) &&
michael@0:       IsLineEndCharAt(aOffset - 1);
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Return an offset of the found word boundary.
michael@0:    */
michael@0:   int32_t FindWordBoundary(int32_t aOffset, nsDirection aDirection,
michael@0:                            EWordMovementType aWordMovementType)
michael@0:   {
michael@0:     return FindOffset(aOffset, aDirection, eSelectWord, aWordMovementType);
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * Used to get begin/end of previous/this/next line. Note: end of line
michael@0:    * is an offset right before '\n' character if any, the offset is right after
michael@0:    * '\n' character is begin of line. In case of wrap word breaks these offsets
michael@0:    * are equal.
michael@0:    */
michael@0:   enum EWhichLineBoundary {
michael@0:     ePrevLineBegin,
michael@0:     ePrevLineEnd,
michael@0:     eThisLineBegin,
michael@0:     eThisLineEnd,
michael@0:     eNextLineBegin,
michael@0:     eNextLineEnd
michael@0:   };
michael@0: 
michael@0:   /**
michael@0:    * Return an offset for requested line boundary. See constants above.
michael@0:    */
michael@0:   int32_t FindLineBoundary(int32_t aOffset,
michael@0:                            EWhichLineBoundary aWhichLineBoundary);
michael@0: 
michael@0:   /**
michael@0:    * Return an offset corresponding to the given direction and selection amount
michael@0:    * relative the given offset. A helper used to find word or line boundaries.
michael@0:    */
michael@0:   int32_t FindOffset(int32_t aOffset, nsDirection aDirection,
michael@0:                      nsSelectionAmount aAmount,
michael@0:                      EWordMovementType aWordMovementType = eDefaultBehavior);
michael@0: 
michael@0:   /**
michael@0:    * Return the boundaries of the substring in case of textual frame or
michael@0:    * frame boundaries in case of non textual frame, offsets are ignored.
michael@0:    */
michael@0:   nsIntRect GetBoundsInFrame(nsIFrame* aFrame,
michael@0:                              uint32_t aStartRenderedOffset,
michael@0:                              uint32_t aEndRenderedOffset);
michael@0: 
michael@0:   // Selection helpers
michael@0: 
michael@0:   /**
michael@0:    * Return frame/DOM selection object for the accessible.
michael@0:    */
michael@0:   already_AddRefed<nsFrameSelection> FrameSelection() const;
michael@0:   dom::Selection* DOMSelection() const;
michael@0: 
michael@0:   /**
michael@0:    * Return selection ranges within the accessible subtree.
michael@0:    */
michael@0:   void GetSelectionDOMRanges(int16_t aType, nsTArray<nsRange*>* aRanges);
michael@0: 
michael@0:   nsresult SetSelectionRange(int32_t aStartPos, int32_t aEndPos);
michael@0: 
michael@0:   // Helpers
michael@0:   nsresult GetDOMPointByFrameOffset(nsIFrame* aFrame, int32_t aOffset,
michael@0:                                     Accessible* aAccessible,
michael@0:                                     mozilla::a11y::DOMPoint* aPoint);
michael@0: 
michael@0:   /**
michael@0:    * Set 'misspelled' text attribute and return range offsets where the
michael@0:    * attibute is stretched. If the text is not misspelled at the given offset
michael@0:    * then we expose only range offsets where text is not misspelled. The method
michael@0:    * is used by TextAttributes() method.
michael@0:    *
michael@0:    * @param aIncludeDefAttrs  [in] points whether text attributes having default
michael@0:    *                          values of attributes should be included
michael@0:    * @param aSourceNode       [in] the node we start to traverse from
michael@0:    * @param aStartOffset      [in, out] the start offset
michael@0:    * @param aEndOffset        [in, out] the end offset
michael@0:    * @param aAttributes       [out, optional] result attributes
michael@0:    */
michael@0:   nsresult GetSpellTextAttribute(nsINode* aNode, int32_t aNodeOffset,
michael@0:                                  int32_t *aStartOffset,
michael@0:                                  int32_t *aEndOffset,
michael@0:                                  nsIPersistentProperties *aAttributes);
michael@0: 
michael@0: private:
michael@0:   /**
michael@0:    * End text offsets array.
michael@0:    */
michael@0:   mutable nsTArray<uint32_t> mOffsets;
michael@0: };
michael@0: 
michael@0: 
michael@0: ////////////////////////////////////////////////////////////////////////////////
michael@0: // Accessible downcasting method
michael@0: 
michael@0: inline HyperTextAccessible*
michael@0: Accessible::AsHyperText()
michael@0: {
michael@0:   return IsHyperText() ? static_cast<HyperTextAccessible*>(this) : nullptr;
michael@0: }
michael@0: 
michael@0: } // namespace a11y
michael@0: } // namespace mozilla
michael@0: 
michael@0: #endif
michael@0: