dom/events/WheelHandlingHelper.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_WheelHandlingHelper_h_
   8 #define mozilla_WheelHandlingHelper_h_
   9
  10 #include "mozilla/Attributes.h"
  11 #include "mozilla/EventForwards.h"
  12 #include "nsCoord.h"
  13 #include "nsIFrame.h"  // for AutoWeakFrame only
  14 #include "nsPoint.h"
  15
  16 class nsIFrame;
  17 class nsIScrollableFrame;
  18 class nsITimer;
  19
  20 namespace mozilla {
  21
  22 class EventStateManager;
  23
  24 /**
  25  * DeltaValues stores two delta values which are along X and Y axis.  This is
  26  * useful for arguments and results of some methods.
  27  */
  28
  29 struct DeltaValues {
  30   DeltaValues() : deltaX(0.0), deltaY(0.0) {}
  31
  32   DeltaValues(double aDeltaX, double aDeltaY)
  33       : deltaX(aDeltaX), deltaY(aDeltaY) {}
  34
  35   explicit DeltaValues(WidgetWheelEvent* aEvent);
  36
  37   double deltaX;
  38   double deltaY;
  39 };
  40
  41 /**
  42  * WheelHandlingUtils provides some static methods which are useful at handling
  43  * wheel events.
  44  */
  45
  46 class WheelHandlingUtils {
  47  public:
  48   /**
  49    * Returns true if aFrame is a scrollable frame and it can be scrolled to
  50    * either aDirectionX or aDirectionY along each axis.  Or if aFrame is a
  51    * plugin frame (in this case, aDirectionX and aDirectionY are ignored).
  52    * Otherwise, false.
  53    */
  54   static bool CanScrollOn(nsIFrame* aFrame, double aDirectionX,
  55                           double aDirectionY);
  56   /**
  57    * Returns true if the scrollable frame can be scrolled to either aDirectionX
  58    * or aDirectionY along each axis.  Otherwise, false.
  59    */
  60   static bool CanScrollOn(nsIScrollableFrame* aScrollFrame, double aDirectionX,
  61                           double aDirectionY);
  62
  63   // For more details about the concept of a disregarded direction, refer to the
  64   // code in struct mozilla::layers::ScrollMetadata which defines
  65   // mDisregardedDirection.
  66   static Maybe<layers::ScrollDirection> GetDisregardedWheelScrollDirection(
  67       const nsIFrame* aFrame);
  68
  69  private:
  70   static bool CanScrollInRange(nscoord aMin, nscoord aValue, nscoord aMax,
  71                                double aDirection);
  72 };
  73
  74 /**
  75  * ScrollbarsForWheel manages scrollbars state during wheel operation.
  76  * E.g., on some platforms, scrollbars should show only while user attempts to
  77  * scroll.  At that time, scrollbars which may be possible to scroll by
  78  * operation of wheel at the point should show temporarily.
  79  */
  80
  81 class ScrollbarsForWheel {
  82  public:
  83   static void PrepareToScrollText(EventStateManager* aESM,
  84                                   nsIFrame* aTargetFrame,
  85                                   WidgetWheelEvent* aEvent);
  86   static void SetActiveScrollTarget(nsIScrollableFrame* aScrollTarget);
  87   // Hide all scrollbars (both mActiveOwner's and mActivatedScrollTargets')
  88   static void MayInactivate();
  89   static void Inactivate();
  90   static bool IsActive();
  91   static void OwnWheelTransaction(bool aOwn);
  92
  93  protected:
  94   static const size_t kNumberOfTargets = 4;
  95   static const DeltaValues directions[kNumberOfTargets];
  96   static AutoWeakFrame sActiveOwner;
  97   static AutoWeakFrame sActivatedScrollTargets[kNumberOfTargets];
  98   static bool sHadWheelStart;
  99   static bool sOwnWheelTransaction;
 100
 101   /**
 102    * These two methods are called upon eWheelOperationStart/eWheelOperationEnd
 103    * events to show/hide the right scrollbars.
 104    */
 105   static void TemporarilyActivateAllPossibleScrollTargets(
 106       EventStateManager* aESM, nsIFrame* aTargetFrame,
 107       WidgetWheelEvent* aEvent);
 108   static void DeactivateAllTemporarilyActivatedScrollTargets();
 109 };
 110
 111 /**
 112  * WheelTransaction manages a series of wheel events as a transaction.
 113  * While in a transaction, every wheel event should scroll the same scrollable
 114  * element even if a different scrollable element is under the mouse cursor.
 115  *
 116  * Additionally, this class also manages wheel scroll speed acceleration.
 117  */
 118
 119 class WheelTransaction {
 120  public:
 121   static nsIFrame* GetTargetFrame() { return sTargetFrame; }
 122   static void EndTransaction();
 123   /**
 124    * WillHandleDefaultAction() is called before handling aWheelEvent on
 125    * aTargetFrame.
 126    *
 127    * @return    false if the caller cannot continue to handle the default
 128    *            action.  Otherwise, true.
 129    */
 130   static bool WillHandleDefaultAction(WidgetWheelEvent* aWheelEvent,
 131                                       AutoWeakFrame& aTargetWeakFrame);
 132   static bool WillHandleDefaultAction(WidgetWheelEvent* aWheelEvent,
 133                                       nsIFrame* aTargetFrame) {
 134     AutoWeakFrame targetWeakFrame(aTargetFrame);
 135     return WillHandleDefaultAction(aWheelEvent, targetWeakFrame);
 136   }
 137   static void OnEvent(WidgetEvent* aEvent);
 138   static void Shutdown();
 139
 140   static void OwnScrollbars(bool aOwn);
 141
 142   static DeltaValues AccelerateWheelDelta(WidgetWheelEvent* aEvent,
 143                                           bool aAllowScrollSpeedOverride);
 144
 145  protected:
 146   static void BeginTransaction(nsIFrame* aTargetFrame,
 147                                const WidgetWheelEvent* aEvent);
 148   // Be careful, UpdateTransaction may fire a DOM event, therefore, the target
 149   // frame might be destroyed in the event handler.
 150   static bool UpdateTransaction(const WidgetWheelEvent* aEvent);
 151   static void MayEndTransaction();
 152
 153   static LayoutDeviceIntPoint GetScreenPoint(WidgetGUIEvent* aEvent);
 154   static void OnFailToScrollTarget();
 155   static void OnTimeout(nsITimer* aTimer, void* aClosure);
 156   static void SetTimeout();
 157   static DeltaValues OverrideSystemScrollSpeed(WidgetWheelEvent* aEvent);
 158   static double ComputeAcceleratedWheelDelta(double aDelta, int32_t aFactor);
 159   static bool OutOfTime(uint32_t aBaseTime, uint32_t aThreshold);
 160
 161   static AutoWeakFrame sTargetFrame;
 162   static uint32_t sTime;        // in milliseconds
 163   static uint32_t sMouseMoved;  // in milliseconds
 164   static nsITimer* sTimer;
 165   static int32_t sScrollSeriesCounter;
 166   static bool sOwnScrollbars;
 167 };
 168
 169 // For some kinds of scrollings, the delta values of WidgetWheelEvent are
 170 // possbile to be adjusted. For example, the user has configured the pref to let
 171 // [vertical wheel + Shift key] to perform horizontal scrolling instead of
 172 // vertical scrolling.
 173 // The values in this enumeration list all kinds of scrollings whose delta
 174 // values are possible to be adjusted.
 175 enum class WheelDeltaAdjustmentStrategy : uint8_t {
 176   // There is no strategy, don't adjust delta values in any cases.
 177   eNone,
 178   // This strategy means we're receiving a horizontalized scroll, so we should
 179   // apply horizontalization strategy for its delta values.
 180   // Horizontalized scrolling means treating vertical wheel scrolling as
 181   // horizontal scrolling by adjusting delta values.
 182   // It's important to keep in mind with the percise concept of horizontalized
 183   // scrolling: Delta values are *ONLY* going to be adjusted during the process
 184   // of its default action handling; in views of any programmes other than the
 185   // default action handler, such as a DOM event listener or a plugin, delta
 186   // values are never going to be adjusted, they will still retrive original
 187   // delta values when horizontalization occured for default actions.
 188   eHorizontalize,
 189   // The following two strategies mean we're receving an auto-dir scroll, so we
 190   // should apply auto-dir adjustment to the delta of the wheel event if needed.
 191   // Auto-dir is a feature which treats any single-wheel scroll as a scroll in
 192   // the only one scrollable direction if the target has only one scrollable
 193   // direction. For example, if the user scrolls a vertical wheel inside a
 194   // target which is horizontally scrollable but vertical unscrollable, then the
 195   // vertical scroll is converted to a horizontal scroll for that target.
 196   // So why do we need two different strategies for auto-dir scrolling? That's
 197   // because when a wheel scroll is converted due to auto-dir, there is one
 198   // thing called "honoured target" which decides which side the converted
 199   // scroll goes towards. If the content of the honoured target horizontally
 200   // is RTL content, then an upward scroll maps to a rightward scroll and a
 201   // downward scroll maps to a leftward scroll; otherwise, an upward scroll maps
 202   // to a leftward scroll and a downward scroll maps to a rightward scroll.
 203   // |eAutoDir| considers the scrolling target as the honoured target.
 204   // |eAutoDirWithRootHonour| takes the root element of the document with the
 205   // scrolling element, and considers that as the honoured target. But note that
 206   // there's one exception: for targets in an HTML document, the real root
 207   // element(I.e. the <html> element) is typically not considered as a root
 208   // element, but the <body> element is typically considered as a root element.
 209   // If there is no <body> element, then consider the <html> element instead.
 210   // And also note that like |eHorizontalize|, delta values are *ONLY* going to
 211   // be adjusted during the process of its default action handling; in views of
 212   // any programmes other than the default action handler, such as a DOM event
 213   // listener or a plugin, delta values are never going to be adjusted.
 214   eAutoDir,
 215   eAutoDirWithRootHonour,
 216   // Not an actual strategy. This is just used as an upper bound for
 217   // ContiguousEnumSerializer.
 218   eSentinel,
 219 };
 220
 221 /**
 222  * When a *pure* vertical wheel event should be treated as if it was a
 223  * horizontal scroll because the user wants to horizontalize the wheel scroll,
 224  * an instance of this class will adjust the delta values upon calling
 225  * Horizontalize(). And the horizontalized delta values will be restored
 226  * automatically when the instance of this class is being destructed. Or you can
 227  * restore them in advance by calling CancelHorizontalization().
 228  */
 229 class MOZ_STACK_CLASS WheelDeltaHorizontalizer final {
 230  public:
 231   /**
 232    * @param aWheelEvent        A wheel event whose delta values will be adjusted
 233    *                           upon calling Horizontalize().
 234    */
 235   explicit WheelDeltaHorizontalizer(WidgetWheelEvent& aWheelEvent)
 236       : mWheelEvent(aWheelEvent),
 237         mOldDeltaX(0.0),
 238         mOldDeltaZ(0.0),
 239         mOldOverflowDeltaX(0.0),
 240         mOldLineOrPageDeltaX(0),
 241         mHorizontalized(false) {}
 242   /**
 243    * Converts vertical scrolling into horizontal scrolling by adjusting the
 244    * its delta values.
 245    */
 246   void Horizontalize();
 247   ~WheelDeltaHorizontalizer();
 248   void CancelHorizontalization();
 249
 250  private:
 251   WidgetWheelEvent& mWheelEvent;
 252   double mOldDeltaX;
 253   double mOldDeltaZ;
 254   double mOldOverflowDeltaX;
 255   int32_t mOldLineOrPageDeltaX;
 256   bool mHorizontalized;
 257 };
 258
 259 /**
 260  * This class is used to adjust the delta values for wheel scrolling with the
 261  * auto-dir functionality.
 262  * A traditional wheel scroll only allows the user use the wheel in the same
 263  * scrollable direction as that of the scrolling target to scroll the target,
 264  * whereas an auto-dir scroll lets the user use any wheel(either a vertical
 265  * wheel or a horizontal tilt wheel) to scroll a frame which is scrollable in
 266  * only one direction. For detailed information on auto-dir scrolling,
 267  * @see mozilla::WheelDeltaAdjustmentStrategy.
 268  */
 269 class MOZ_STACK_CLASS AutoDirWheelDeltaAdjuster {
 270  protected:
 271   /**
 272    * @param aDeltaX            DeltaX for a wheel event whose delta values will
 273    *                           be adjusted upon calling Adjust() when
 274    *                           ShouldBeAdjusted() returns true.
 275    * @param aDeltaY            DeltaY for a wheel event, like DeltaX.
 276    */
 277   AutoDirWheelDeltaAdjuster(double& aDeltaX, double& aDeltaY)
 278       : mDeltaX(aDeltaX),
 279         mDeltaY(aDeltaY),
 280         mCheckedIfShouldBeAdjusted(false),
 281         mShouldBeAdjusted(false) {}
 282
 283  public:
 284   /**
 285    * Gets whether the values of the delta should be adjusted for auto-dir
 286    * scrolling. Note that if Adjust() has been called, this function simply
 287    * returns false.
 288    *
 289    * @return true if the delta should be adjusted; otherwise false.
 290    */
 291   bool ShouldBeAdjusted();
 292   /**
 293    * Adjusts the values of the delta values for auto-dir scrolling when
 294    * ShouldBeAdjusted() returns true. If you call it when ShouldBeAdjusted()
 295    * returns false, this function will simply do nothing.
 296    */
 297   void Adjust();
 298
 299  private:
 300   /**
 301    * Called by Adjust() if Adjust() successfully adjusted the delta values.
 302    */
 303   virtual void OnAdjusted() {}
 304
 305   virtual bool CanScrollAlongXAxis() const = 0;
 306   virtual bool CanScrollAlongYAxis() const = 0;
 307   virtual bool CanScrollUpwards() const = 0;
 308   virtual bool CanScrollDownwards() const = 0;
 309   virtual bool CanScrollLeftwards() const = 0;
 310   virtual bool CanScrollRightwards() const = 0;
 311
 312   /**
 313    * Gets whether the horizontal content starts at rightside.
 314    *
 315    * @return If the content is in vertical-RTL writing mode(E.g. "writing-mode:
 316    *         vertical-rl" in CSS), or if it's in horizontal-RTL writing-mode
 317    *         (E.g. "writing-mode: horizontal-tb; direction: rtl;" in CSS), then
 318    *         this function returns true. From the representation perspective,
 319    *         frames whose horizontal contents start at rightside also cause
 320    *         their horizontal scrollbars, if any, initially start at rightside.
 321    *         So we can also learn about the initial side of the horizontal
 322    *         scrollbar for the frame by calling this function.
 323    */
 324   virtual bool IsHorizontalContentRightToLeft() const = 0;
 325
 326  protected:
 327   double& mDeltaX;
 328   double& mDeltaY;
 329
 330  private:
 331   bool mCheckedIfShouldBeAdjusted;
 332   bool mShouldBeAdjusted;
 333 };
 334
 335 /**
 336  * This is the implementation of AutoDirWheelDeltaAdjuster for EventStateManager
 337  *
 338  * Detailed comments about some member functions are given in the base class
 339  * AutoDirWheelDeltaAdjuster.
 340  */
 341 class MOZ_STACK_CLASS ESMAutoDirWheelDeltaAdjuster final
 342     : public AutoDirWheelDeltaAdjuster {
 343  public:
 344   /**
 345    * @param aEvent             The auto-dir wheel scroll event.
 346    * @param aScrollFrame       The scroll target for the event.
 347    * @param aHonoursRoot       If set to true, the honoured frame is the root
 348    *                           frame in the same document where the target is;
 349    *                           If false, the honoured frame is the scroll
 350    *                           target. For the concept of an honoured target,
 351    *                           @see mozilla::WheelDeltaAdjustmentStrategy
 352    */
 353   ESMAutoDirWheelDeltaAdjuster(WidgetWheelEvent& aEvent, nsIFrame& aScrollFrame,
 354                                bool aHonoursRoot);
 355
 356  private:
 357   virtual void OnAdjusted() override;
 358   virtual bool CanScrollAlongXAxis() const override;
 359   virtual bool CanScrollAlongYAxis() const override;
 360   virtual bool CanScrollUpwards() const override;
 361   virtual bool CanScrollDownwards() const override;
 362   virtual bool CanScrollLeftwards() const override;
 363   virtual bool CanScrollRightwards() const override;
 364   virtual bool IsHorizontalContentRightToLeft() const override;
 365
 366   nsIScrollableFrame* mScrollTargetFrame;
 367   bool mIsHorizontalContentRightToLeft;
 368
 369   int32_t& mLineOrPageDeltaX;
 370   int32_t& mLineOrPageDeltaY;
 371   double& mOverflowDeltaX;
 372   double& mOverflowDeltaY;
 373 };
 374
 375 /**
 376  * This class is used for restoring the delta in an auto-dir wheel.
 377  *
 378  * An instance of this calss monitors auto-dir adjustment which may happen
 379  * during its lifetime. If the delta values is adjusted during its lifetime, the
 380  * instance will restore the adjusted delta when it's being destrcuted.
 381  */
 382 class MOZ_STACK_CLASS ESMAutoDirWheelDeltaRestorer final {
 383  public:
 384   /**
 385    * @param aEvent             The wheel scroll event to be monitored.
 386    */
 387   explicit ESMAutoDirWheelDeltaRestorer(WidgetWheelEvent& aEvent);
 388   ~ESMAutoDirWheelDeltaRestorer();
 389
 390  private:
 391   WidgetWheelEvent& mEvent;
 392   double mOldDeltaX;
 393   double mOldDeltaY;
 394   int32_t mOldLineOrPageDeltaX;
 395   int32_t mOldLineOrPageDeltaY;
 396   double mOldOverflowDeltaX;
 397   double mOldOverflowDeltaY;
 398 };
 399
 400 }  // namespace mozilla
 401
 402 #endif  // mozilla_WheelHandlingHelper_h_