layout/base/AccessibleCaretEventHub.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 mozilla_AccessibleCaretEventHub_h
   8 #define mozilla_AccessibleCaretEventHub_h
   9
  10 #include "LayoutConstants.h"
  11 #include "mozilla/EventForwards.h"
  12 #include "mozilla/MouseEvents.h"
  13 #include "mozilla/UniquePtr.h"
  14 #include "mozilla/WeakPtr.h"
  15 #include "nsCOMPtr.h"
  16 #include "nsDocShell.h"
  17 #include "nsIReflowObserver.h"
  18 #include "nsIScrollObserver.h"
  19 #include "nsPoint.h"
  20 #include "mozilla/RefPtr.h"
  21 #include "nsWeakReference.h"
  22
  23 class nsITimer;
  24
  25 namespace mozilla {
  26 class AccessibleCaretManager;
  27 class PresShell;
  28 class WidgetKeyboardEvent;
  29 class WidgetMouseEvent;
  30 class WidgetTouchEvent;
  31
  32 // -----------------------------------------------------------------------------
  33 // Each PresShell holds a shared pointer to an AccessibleCaretEventHub; each
  34 // AccessibleCaretEventHub holds a unique pointer to an AccessibleCaretManager.
  35 // Thus, there's one AccessibleCaretManager per PresShell.
  36 //
  37 // AccessibleCaretEventHub implements a state pattern. It receives events from
  38 // PresShell and callbacks by observers and listeners, and then relays them to
  39 // the current concrete state which calls necessary event-handling methods in
  40 // AccessibleCaretManager.
  41 //
  42 // We separate AccessibleCaretEventHub from AccessibleCaretManager to make the
  43 // state transitions in AccessibleCaretEventHub testable. We put (nearly) all
  44 // the operations involving PresShell, Selection, and AccessibleCaret
  45 // manipulation in AccessibleCaretManager so that we can mock methods in
  46 // AccessibleCaretManager in gtest. We test the correctness of the state
  47 // transitions by giving events, callbacks, and the return values by mocked
  48 // methods of AccessibleCaretEventHub. See TestAccessibleCaretEventHub.cpp.
  49 //
  50 // Besides dealing with real events, AccessibleCaretEventHub could also
  51 // synthesize fake long-tap events and inject those events to itself on the
  52 // platform lacks eMouseLongTap. Turn on this preference
  53 // "layout.accessiblecaret.use_long_tap_injector" for the fake long-tap events.
  54 //
  55 // Please see the in-tree document for state transition diagram and more
  56 // information.
  57 // HTML: https://firefox-source-docs.mozilla.org/layout/AccessibleCaret.html
  58 // Source rst: layout/docs/AccessibleCaret.rst
  59 //
  60 class AccessibleCaretEventHub : public nsIReflowObserver,
  61                                 public nsIScrollObserver,
  62                                 public nsSupportsWeakReference {
  63  public:
  64   explicit AccessibleCaretEventHub(PresShell* aPresShell);
  65   void Init();
  66   void Terminate();
  67
  68   MOZ_CAN_RUN_SCRIPT
  69   nsEventStatus HandleEvent(WidgetEvent* aEvent);
  70
  71   // Call this function to notify the blur event happened.
  72   MOZ_CAN_RUN_SCRIPT
  73   void NotifyBlur(bool aIsLeavingDocument);
  74
  75   NS_DECL_ISUPPORTS
  76
  77   // nsIReflowObserver
  78   MOZ_CAN_RUN_SCRIPT_BOUNDARY
  79   NS_IMETHOD Reflow(DOMHighResTimeStamp start, DOMHighResTimeStamp end) final;
  80   MOZ_CAN_RUN_SCRIPT_BOUNDARY
  81   NS_IMETHOD ReflowInterruptible(DOMHighResTimeStamp start,
  82                                  DOMHighResTimeStamp end) final;
  83
  84   // Override nsIScrollObserver methods.
  85   MOZ_CAN_RUN_SCRIPT_BOUNDARY
  86   virtual void ScrollPositionChanged() override;
  87   MOZ_CAN_RUN_SCRIPT
  88   virtual void AsyncPanZoomStarted() override;
  89   MOZ_CAN_RUN_SCRIPT
  90   virtual void AsyncPanZoomStopped() override;
  91
  92   // Base state
  93   class State;
  94   State* GetState() const;
  95
  96   MOZ_CAN_RUN_SCRIPT
  97   void OnSelectionChange(dom::Document* aDocument, dom::Selection* aSelection,
  98                          int16_t aReason);
  99
 100   bool ShouldDisableApz() const;
 101
 102  protected:
 103   virtual ~AccessibleCaretEventHub() = default;
 104
 105 #define MOZ_DECL_STATE_CLASS_GETTER(aClassName) \
 106   class aClassName;                             \
 107   static State* aClassName();
 108
 109 #define MOZ_IMPL_STATE_CLASS_GETTER(aClassName)                           \
 110   AccessibleCaretEventHub::State* AccessibleCaretEventHub::aClassName() { \
 111     static class aClassName singleton;                                    \
 112     return &singleton;                                                    \
 113   }
 114
 115   // Concrete state getters
 116   MOZ_DECL_STATE_CLASS_GETTER(NoActionState)
 117   MOZ_DECL_STATE_CLASS_GETTER(PressCaretState)
 118   MOZ_DECL_STATE_CLASS_GETTER(DragCaretState)
 119   MOZ_DECL_STATE_CLASS_GETTER(PressNoCaretState)
 120   MOZ_DECL_STATE_CLASS_GETTER(ScrollState)
 121   MOZ_DECL_STATE_CLASS_GETTER(LongTapState)
 122
 123   void SetState(State* aState);
 124
 125   MOZ_CAN_RUN_SCRIPT
 126   nsEventStatus HandleMouseEvent(WidgetMouseEvent* aEvent);
 127   MOZ_CAN_RUN_SCRIPT
 128   nsEventStatus HandleTouchEvent(WidgetTouchEvent* aEvent);
 129   MOZ_CAN_RUN_SCRIPT
 130   nsEventStatus HandleKeyboardEvent(WidgetKeyboardEvent* aEvent);
 131
 132   virtual nsPoint GetTouchEventPosition(WidgetTouchEvent* aEvent,
 133                                         int32_t aIdentifier) const;
 134   virtual nsPoint GetMouseEventPosition(WidgetMouseEvent* aEvent) const;
 135
 136   bool MoveDistanceIsLarge(const nsPoint& aPoint) const;
 137
 138   void LaunchLongTapInjector();
 139   void CancelLongTapInjector();
 140
 141   MOZ_CAN_RUN_SCRIPT_BOUNDARY
 142   static void FireLongTap(nsITimer* aTimer, void* aAccessibleCaretEventHub);
 143
 144   void LaunchScrollEndInjector();
 145   void CancelScrollEndInjector();
 146
 147   MOZ_CAN_RUN_SCRIPT_BOUNDARY
 148   static void FireScrollEnd(nsITimer* aTimer, void* aAccessibleCaretEventHub);
 149
 150   // Member variables
 151   State* mState = NoActionState();
 152
 153   // Will be set to nullptr in Terminate().
 154   PresShell* MOZ_NON_OWNING_REF mPresShell = nullptr;
 155
 156   UniquePtr<AccessibleCaretManager> mManager;
 157
 158   WeakPtr<nsDocShell> mDocShell;
 159
 160   // Use this timer for injecting a long tap event when APZ is disabled. If APZ
 161   // is enabled, it will send long tap event to us.
 162   nsCOMPtr<nsITimer> mLongTapInjectorTimer;
 163
 164   // Last mouse button down event or touch start event point.
 165   nsPoint mPressPoint{NS_UNCONSTRAINEDSIZE, NS_UNCONSTRAINEDSIZE};
 166
 167   // For filter multitouch event
 168   int32_t mActiveTouchId = kInvalidTouchId;
 169
 170   // Flag to indicate the class has been initialized.
 171   bool mInitialized = false;
 172
 173   // Flag to avoid calling Reflow() callback recursively.
 174   bool mIsInReflowCallback = false;
 175
 176   static const int32_t kMoveStartToleranceInPixel = 5;
 177   static const int32_t kInvalidTouchId = -1;
 178   static const int32_t kDefaultTouchId = 0;  // For mouse event
 179 };
 180
 181 // -----------------------------------------------------------------------------
 182 // The base class for concrete states. A concrete state should inherit from this
 183 // class, and override the methods to handle the events or callbacks. A concrete
 184 // state is also responsible for transforming itself to the next concrete state.
 185 //
 186 class AccessibleCaretEventHub::State {
 187  public:
 188   virtual const char* Name() const { return ""; }
 189
 190   MOZ_CAN_RUN_SCRIPT
 191   virtual nsEventStatus OnPress(AccessibleCaretEventHub* aContext,
 192                                 const nsPoint& aPoint, int32_t aTouchId,
 193                                 EventClassID aEventClass) {
 194     return nsEventStatus_eIgnore;
 195   }
 196
 197   MOZ_CAN_RUN_SCRIPT
 198   virtual nsEventStatus OnMove(AccessibleCaretEventHub* aContext,
 199                                const nsPoint& aPoint,
 200                                WidgetMouseEvent::Reason aReason) {
 201     return nsEventStatus_eIgnore;
 202   }
 203
 204   MOZ_CAN_RUN_SCRIPT
 205   virtual nsEventStatus OnRelease(AccessibleCaretEventHub* aContext) {
 206     return nsEventStatus_eIgnore;
 207   }
 208
 209   MOZ_CAN_RUN_SCRIPT
 210   virtual nsEventStatus OnLongTap(AccessibleCaretEventHub* aContext,
 211                                   const nsPoint& aPoint) {
 212     return nsEventStatus_eIgnore;
 213   }
 214
 215   MOZ_CAN_RUN_SCRIPT
 216   virtual void OnScrollStart(AccessibleCaretEventHub* aContext) {}
 217   MOZ_CAN_RUN_SCRIPT
 218   virtual void OnScrollEnd(AccessibleCaretEventHub* aContext) {}
 219   MOZ_CAN_RUN_SCRIPT
 220   virtual void OnScrollPositionChanged(AccessibleCaretEventHub* aContext) {}
 221   MOZ_CAN_RUN_SCRIPT
 222   virtual void OnBlur(AccessibleCaretEventHub* aContext,
 223                       bool aIsLeavingDocument) {}
 224   MOZ_CAN_RUN_SCRIPT
 225   virtual void OnSelectionChanged(AccessibleCaretEventHub* aContext,
 226                                   dom::Document* aDoc, dom::Selection* aSel,
 227                                   int16_t aReason) {}
 228   MOZ_CAN_RUN_SCRIPT
 229   virtual void OnReflow(AccessibleCaretEventHub* aContext) {}
 230   virtual void Enter(AccessibleCaretEventHub* aContext) {}
 231   virtual void Leave(AccessibleCaretEventHub* aContext) {}
 232
 233   explicit State() = default;
 234   virtual ~State() = default;
 235   State(const State&) = delete;
 236   State& operator=(const State&) = delete;
 237 };
 238
 239 }  // namespace mozilla
 240
 241 #endif  // mozilla_AccessibleCaretEventHub_h