layout/base/AccessibleCaret.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef AccessibleCaret_h__
   8 #define AccessibleCaret_h__
   9
  10 #include "mozilla/Attributes.h"
  11 #include "mozilla/dom/AnonymousContent.h"
  12 #include "nsCOMPtr.h"
  13 #include "nsIDOMEventListener.h"
  14 #include "nsIFrame.h"  // for WeakFrame only
  15 #include "nsISupports.h"
  16 #include "nsISupportsImpl.h"
  17 #include "nsLiteralString.h"
  18 #include "nsRect.h"
  19 #include "mozilla/RefPtr.h"
  20 #include "nsString.h"
  21
  22 class nsIFrame;
  23 struct nsPoint;
  24
  25 namespace mozilla {
  26 class PresShell;
  27 namespace dom {
  28 class Element;
  29 class Event;
  30 }  // namespace dom
  31
  32 // -----------------------------------------------------------------------------
  33 // Upon the creation of AccessibleCaret, it will insert DOM Element as an
  34 // anonymous content containing the caret image. The caret appearance and
  35 // position can be controlled by SetAppearance() and SetPosition().
  36 //
  37 // All the rect or point are relative to root frame except being specified
  38 // explicitly.
  39 //
  40 // None of the methods in AccessibleCaret will flush layout or style. To ensure
  41 // that SetPosition() works correctly, the caller must make sure the layout is
  42 // up to date.
  43 //
  44 // Please see the wiki page for more information.
  45 // https://wiki.mozilla.org/AccessibleCaret
  46 //
  47 class AccessibleCaret {
  48  public:
  49   explicit AccessibleCaret(PresShell* aPresShell);
  50   virtual ~AccessibleCaret();
  51
  52   // This enumeration representing the visibility and visual style of an
  53   // AccessibleCaret.
  54   //
  55   // Use SetAppearance() to change the appearance, and use GetAppearance() to
  56   // get the current appearance.
  57   enum class Appearance : uint8_t {
  58     // Do not display the caret at all.
  59     None,
  60
  61     // Display the caret in default style.
  62     Normal,
  63
  64     // The caret should be displayed logically but it is kept invisible to the
  65     // user. This enum is the only difference between "logically visible" and
  66     // "visually visible". It can be used for reasons such as:
  67     // 1. Out of scroll port.
  68     // 2. For UX requirement such as hide a caret in an empty text area.
  69     NormalNotShown,
  70
  71     // Display the caret which is tilted to the left.
  72     Left,
  73
  74     // Display the caret which is tilted to the right.
  75     Right
  76   };
  77
  78   friend std::ostream& operator<<(std::ostream& aStream,
  79                                   const Appearance& aAppearance);
  80
  81   Appearance GetAppearance() const { return mAppearance; }
  82
  83   virtual void SetAppearance(Appearance aAppearance);
  84
  85   // Return true if current appearance is either Normal, NormalNotShown, Left,
  86   // or Right.
  87   bool IsLogicallyVisible() const { return mAppearance != Appearance::None; }
  88
  89   // Return true if current appearance is either Normal, Left, or Right.
  90   bool IsVisuallyVisible() const {
  91     return (mAppearance != Appearance::None) &&
  92            (mAppearance != Appearance::NormalNotShown);
  93   }
  94
  95   // This enum represents the result returned by SetPosition().
  96   enum class PositionChangedResult : uint8_t {
  97     // Both position and the zoom level are not changed.
  98     NotChanged,
  99
 100     // The position is changed. (The zoom level may or may not be changed.)
 101     Position,
 102
 103     // Only the zoom level is changed. The position is *not* changed.
 104     Zoom,
 105
 106     // The position is out of scroll port.
 107     Invisible
 108   };
 109
 110   friend std::ostream& operator<<(std::ostream& aStream,
 111                                   const PositionChangedResult& aResult);
 112
 113   virtual PositionChangedResult SetPosition(nsIFrame* aFrame, int32_t aOffset);
 114
 115   // Does two AccessibleCarets overlap?
 116   bool Intersects(const AccessibleCaret& aCaret) const;
 117
 118   // Is the point within the caret's rect? The point should be relative to root
 119   // frame.
 120   enum class TouchArea {
 121     Full,  // Contains both text overlay and caret image.
 122     CaretImage
 123   };
 124   bool Contains(const nsPoint& aPoint, TouchArea aTouchArea) const;
 125
 126   // The geometry center of the imaginary caret (nsCaret) to which this
 127   // AccessibleCaret is attached. It is needed when dragging the caret.
 128   nsPoint LogicalPosition() const { return mImaginaryCaretRect.Center(); }
 129
 130   // Element for 'Intersects' test. This is the container of the caret image
 131   // and text-overlay elements. See CreateCaretElement() for the content
 132   // structure.
 133   dom::Element& CaretElement() const {
 134     return mCaretElementHolder->ContentNode();
 135   }
 136
 137   // Ensures that the caret element is made "APZ aware" so that the APZ code
 138   // doesn't scroll the page when the user is trying to drag the caret.
 139   void EnsureApzAware();
 140
 141   bool IsInPositionFixedSubtree() const;
 142
 143  protected:
 144   // Argument aRect should be relative to CustomContentContainerFrame().
 145   void SetCaretElementStyle(const nsRect& aRect, float aZoomLevel);
 146   void SetTextOverlayElementStyle(const nsRect& aRect, float aZoomLevel);
 147   void SetCaretImageElementStyle(const nsRect& aRect, float aZoomLevel);
 148
 149   // Get current zoom level.
 150   float GetZoomLevel();
 151
 152   // Element which contains the text overly for the 'Contains' test.
 153   dom::Element* TextOverlayElement() const {
 154     return mCaretElementHolder->GetElementById(sTextOverlayElementId);
 155   }
 156
 157   // Element which contains the caret image for 'Contains' test.
 158   dom::Element* CaretImageElement() const {
 159     return mCaretElementHolder->GetElementById(sCaretImageElementId);
 160   }
 161
 162   nsIFrame* RootFrame() const;
 163
 164   nsIFrame* CustomContentContainerFrame() const;
 165
 166   // Transform Appearance to CSS id used in ua.css.
 167   static nsAutoString AppearanceString(Appearance aAppearance);
 168
 169   already_AddRefed<dom::Element> CreateCaretElement(dom::Document*) const;
 170
 171   // Inject caret element into custom content container.
 172   void InjectCaretElement(dom::Document*);
 173
 174   // Remove caret element from custom content container.
 175   void RemoveCaretElement(dom::Document*);
 176
 177   // Clear the cached rects and zoom level.
 178   void ClearCachedData();
 179
 180   // The top-center of the imaginary caret to which this AccessibleCaret is
 181   // attached.
 182   static nsPoint CaretElementPosition(const nsRect& aRect) {
 183     return aRect.TopLeft() + nsPoint(aRect.width / 2, 0);
 184   }
 185
 186   class DummyTouchListener final : public nsIDOMEventListener {
 187    public:
 188     NS_DECL_ISUPPORTS
 189     NS_IMETHOD HandleEvent(mozilla::dom::Event* aEvent) override {
 190       return NS_OK;
 191     }
 192
 193    private:
 194     virtual ~DummyTouchListener() = default;
 195   };
 196
 197   // Member variables
 198   Appearance mAppearance = Appearance::None;
 199
 200   // AccessibleCaretManager owns us by a UniquePtr. When it's terminated by
 201   // AccessibleCaretEventHub::Terminate() which is called in
 202   // PresShell::Destroy(), it frees us automatically. No need to worry if we
 203   // outlive mPresShell.
 204   PresShell* const MOZ_NON_OWNING_REF mPresShell = nullptr;
 205
 206   RefPtr<dom::AnonymousContent> mCaretElementHolder;
 207
 208   // This cached rect is relative to the root frame, and is used in
 209   // LogicalPosition() when dragging a caret.
 210   nsRect mImaginaryCaretRect;
 211
 212   // This cached rect is relative to the custom content container, and is used
 213   // in SetPosition() to check whether the caret position has changed.
 214   nsRect mImaginaryCaretRectInContainerFrame;
 215
 216   // The reference frame we used to calculate mImaginaryCaretRect and
 217   // mImaginaryCaretRectInContainerFrame.
 218   WeakFrame mImaginaryCaretReferenceFrame;
 219
 220   // Cache current zoom level to determine whether position is changed.
 221   float mZoomLevel = 0.0f;
 222
 223   // A no-op touch-start listener which prevents APZ from panning when dragging
 224   // the caret.
 225   RefPtr<DummyTouchListener> mDummyTouchListener{new DummyTouchListener()};
 226
 227   // Static class variables
 228   static const nsLiteralString sTextOverlayElementId;
 229   static const nsLiteralString sCaretImageElementId;
 230
 231 };  // class AccessibleCaret
 232
 233 std::ostream& operator<<(std::ostream& aStream,
 234                          const AccessibleCaret::Appearance& aAppearance);
 235
 236 std::ostream& operator<<(std::ostream& aStream,
 237                          const AccessibleCaret::PositionChangedResult& aResult);
 238
 239 }  // namespace mozilla
 240
 241 #endif  // AccessibleCaret_h__