tor-browser

WheelHandlingHelper.h (17834B)

---

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef mozilla_WheelHandlingHelper_h_
#define mozilla_WheelHandlingHelper_h_

#include "mozilla/Attributes.h"
#include "mozilla/EventForwards.h"
#include "nsCoord.h"
#include "nsIFrame.h"  // for AutoWeakFrame only
#include "nsPoint.h"

class nsIFrame;
class nsITimer;

namespace mozilla {

class EventStateManager;
class ScrollContainerFrame;

/**
* DeltaValues stores two delta values which are along X and Y axis.  This is
* useful for arguments and results of some methods.
*/

struct DeltaValues {
 constexpr DeltaValues() : deltaX(0.0), deltaY(0.0) {}

 constexpr DeltaValues(double aDeltaX, double aDeltaY)
     : deltaX(aDeltaX), deltaY(aDeltaY) {}

 explicit DeltaValues(WidgetWheelEvent* aEvent);

 double deltaX;
 double deltaY;
};

/**
* WheelHandlingUtils provides some static methods which are useful at handling
* wheel events.
*/

class WheelHandlingUtils {
public:
 /**
  * Returns true if aFrame is a scrollable frame and it can be scrolled to
  * either aDirectionX or aDirectionY along each axis.  Or if aFrame is a
  * plugin frame (in this case, aDirectionX and aDirectionY are ignored).
  * Otherwise, false.
  */
 static bool CanScrollOn(nsIFrame* aFrame, double aDirectionX,
                         double aDirectionY);
 /**
  * Returns true if the scroll container frame can be scrolled to either
  * aDirectionX or aDirectionY along each axis.  Otherwise, false.
  */
 static bool CanScrollOn(ScrollContainerFrame* aScrollContainerFrame,
                         double aDirectionX, double aDirectionY);

 // For more details about the concept of a disregarded direction, refer to the
 // code in struct mozilla::layers::ScrollMetadata which defines
 // mDisregardedDirection.
 static Maybe<layers::ScrollDirection> GetDisregardedWheelScrollDirection(
     const nsIFrame* aFrame);

private:
 static bool CanScrollInRange(nscoord aMin, nscoord aValue, nscoord aMax,
                              double aDirection);
};

/**
* ScrollbarsForWheel manages scrollbars state during wheel operation.
* E.g., on some platforms, scrollbars should show only while user attempts to
* scroll.  At that time, scrollbars which may be possible to scroll by
* operation of wheel at the point should show temporarily.
*/

class ScrollbarsForWheel {
public:
 static void PrepareToScrollText(EventStateManager* aESM,
                                 nsIFrame* aTargetFrame,
                                 WidgetWheelEvent* aEvent);
 static void SetActiveScrollTarget(ScrollContainerFrame* aScrollTarget);
 // Hide all scrollbars (both mActiveOwner's and mActivatedScrollTargets')
 static void MayInactivate();
 static void Inactivate();
 static bool IsActive();
 static void OwnWheelTransaction(bool aOwn);

protected:
 static const size_t kNumberOfTargets = 4;
 static constexpr DeltaValues directions[kNumberOfTargets] = {
     DeltaValues(-1, 0), DeltaValues(+1, 0), DeltaValues(0, -1),
     DeltaValues(0, +1)};
 static AutoWeakFrame sActiveOwner;
 static AutoWeakFrame sActivatedScrollTargets[kNumberOfTargets];
 static bool sHadWheelStart;
 static bool sOwnWheelTransaction;

 /**
  * These two methods are called upon eWheelOperationStart/eWheelOperationEnd
  * events to show/hide the right scrollbars.
  */
 static void TemporarilyActivateAllPossibleScrollTargets(
     EventStateManager* aESM, nsIFrame* aTargetFrame,
     WidgetWheelEvent* aEvent);
 static void DeactivateAllTemporarilyActivatedScrollTargets();
};

/**
* WheelTransaction manages a series of wheel events as a transaction.
* While in a transaction, every wheel event should scroll the same scrollable
* element even if a different scrollable element is under the mouse cursor.
*
* Additionally, this class also manages wheel scroll speed acceleration.
*/

class WheelTransaction {
public:
 /**
  * Get the target scroll frame for this wheel transaction. This should
  * the the scrollable fame that will scroll for all wheel events in
  * this wheel transaction.
  */
 static nsIFrame* GetScrollTargetFrame() { return sScrollTargetFrame; }
 /*
  * The event target to use for all wheel events in this wheel transaction.
  * This should be the event target for all wheel events in this wheel
  * transaction. Note that this frame will likely be a child of the
  * scrollable frame.
  */
 static nsIFrame* GetEventTargetFrame() { return sEventTargetFrame; }
 static bool HandledByApz() { return sHandledByApz; }
 static void EndTransaction();
 /**
  * WillHandleDefaultAction() is called before handling aWheelEvent on
  * aScrollTargetWeakFrame given the event target aEventTargetWeakFrame.
  *
  * @return    false if the caller cannot continue to handle the default
  *            action.  Otherwise, true.
  */
 static bool WillHandleDefaultAction(WidgetWheelEvent* aWheelEvent,
                                     AutoWeakFrame& aScrollTargetWeakFrame,
                                     AutoWeakFrame& aEventTargetWeakFrame);
 static bool WillHandleDefaultAction(WidgetWheelEvent* aWheelEvent,
                                     nsIFrame* aScrollTargetFrame,
                                     nsIFrame* aEventTargetFrame) {
   AutoWeakFrame scrollTargetWeakFrame(aScrollTargetFrame);
   AutoWeakFrame eventTargetWeakFrame(aEventTargetFrame);
   return WillHandleDefaultAction(aWheelEvent, scrollTargetWeakFrame,
                                  eventTargetWeakFrame);
 }
 static void OnEvent(WidgetEvent* aEvent);
 static void OnRemoveElement(nsIContent* aContent);
 static void Shutdown();

 static void OwnScrollbars(bool aOwn);

 static DeltaValues AccelerateWheelDelta(WidgetWheelEvent* aEvent);

protected:
 static void BeginTransaction(nsIFrame* aScrollTargetFrame,
                              nsIFrame* aEventTargetFrame,
                              const WidgetWheelEvent* aEvent);
 // Be careful, UpdateTransaction may fire a DOM event, therefore, the target
 // frame might be destroyed in the event handler.
 static bool UpdateTransaction(const WidgetWheelEvent* aEvent);
 static void MayEndTransaction();

 static LayoutDeviceIntPoint GetScreenPoint(WidgetGUIEvent* aEvent);
 static void OnFailToScrollTarget();
 static void OnTimeout(nsITimer* aTimer, void* aClosure);
 static void SetTimeout();
 static DeltaValues OverrideSystemScrollSpeed(WidgetWheelEvent* aEvent);
 static double ComputeAcceleratedWheelDelta(double aDelta, int32_t aFactor);
 static bool OutOfTime(uint32_t aBaseTime, uint32_t aThreshold);

 /**
  * The scrollable element the current wheel event group is bound to.
  */
 static AutoWeakFrame sScrollTargetFrame;
 /**
  * The initial target of the first wheel event in the wheel event group.
  * This frame is typically a child of the scrollable element. The wheel
  * event should target the topmost-event-target. For a wheel event
  * group, we'll use this target for the entire group.
  *
  * See https://w3c.github.io/uievents/#topmost-event-target and
  * https://w3c.github.io/uievents/#event-type-wheel for details.
  *
  * Note: this is only populated if dom.event.wheel-event-groups.enabled is
  * set.
  */
 static AutoWeakFrame sEventTargetFrame;
 /**
  * The wheel events for this transaction are handled by APZ.
  */
 static bool sHandledByApz;
 static uint32_t sTime;        // in milliseconds
 static uint32_t sMouseMoved;  // in milliseconds
 static nsITimer* sTimer;
 static int32_t sScrollSeriesCounter;
 static bool sOwnScrollbars;
};

// For some kinds of scrollings, the delta values of WidgetWheelEvent are
// possbile to be adjusted. For example, the user has configured the pref to let
// [vertical wheel + Shift key] to perform horizontal scrolling instead of
// vertical scrolling.
// The values in this enumeration list all kinds of scrollings whose delta
// values are possible to be adjusted.
enum class WheelDeltaAdjustmentStrategy : uint8_t {
 // There is no strategy, don't adjust delta values in any cases.
 eNone,
 // This strategy means we're receiving a horizontalized scroll, so we should
 // apply horizontalization strategy for its delta values.
 // Horizontalized scrolling means treating vertical wheel scrolling as
 // horizontal scrolling by adjusting delta values.
 // It's important to keep in mind with the percise concept of horizontalized
 // scrolling: Delta values are *ONLY* going to be adjusted during the process
 // of its default action handling; in views of any programmes other than the
 // default action handler, such as a DOM event listener or a plugin, delta
 // values are never going to be adjusted, they will still retrive original
 // delta values when horizontalization occured for default actions.
 eHorizontalize,
 // The following two strategies mean we're receving an auto-dir scroll, so we
 // should apply auto-dir adjustment to the delta of the wheel event if needed.
 // Auto-dir is a feature which treats any single-wheel scroll as a scroll in
 // the only one scrollable direction if the target has only one scrollable
 // direction. For example, if the user scrolls a vertical wheel inside a
 // target which is horizontally scrollable but vertical unscrollable, then the
 // vertical scroll is converted to a horizontal scroll for that target.
 // So why do we need two different strategies for auto-dir scrolling? That's
 // because when a wheel scroll is converted due to auto-dir, there is one
 // thing called "honoured target" which decides which side the converted
 // scroll goes towards. If the content of the honoured target horizontally
 // is RTL content, then an upward scroll maps to a rightward scroll and a
 // downward scroll maps to a leftward scroll; otherwise, an upward scroll maps
 // to a leftward scroll and a downward scroll maps to a rightward scroll.
 // |eAutoDir| considers the scrolling target as the honoured target.
 // |eAutoDirWithRootHonour| takes the root element of the document with the
 // scrolling element, and considers that as the honoured target. But note that
 // there's one exception: for targets in an HTML document, the real root
 // element(I.e. the <html> element) is typically not considered as a root
 // element, but the <body> element is typically considered as a root element.
 // If there is no <body> element, then consider the <html> element instead.
 // And also note that like |eHorizontalize|, delta values are *ONLY* going to
 // be adjusted during the process of its default action handling; in views of
 // any programmes other than the default action handler, such as a DOM event
 // listener or a plugin, delta values are never going to be adjusted.
 eAutoDir,
 eAutoDirWithRootHonour,
 // Not an actual strategy. This is just used as an upper bound for
 // ContiguousEnumSerializer.
 eSentinel,
};

/**
* When a *pure* vertical wheel event should be treated as if it was a
* horizontal scroll because the user wants to horizontalize the wheel scroll,
* an instance of this class will adjust the delta values upon calling
* Horizontalize(). And the horizontalized delta values will be restored
* automatically when the instance of this class is being destructed. Or you can
* restore them in advance by calling CancelHorizontalization().
*/
class MOZ_STACK_CLASS WheelDeltaHorizontalizer final {
public:
 /**
  * @param aWheelEvent        A wheel event whose delta values will be adjusted
  *                           upon calling Horizontalize().
  */
 explicit WheelDeltaHorizontalizer(WidgetWheelEvent& aWheelEvent)
     : mWheelEvent(aWheelEvent),
       mOldDeltaX(0.0),
       mOldDeltaZ(0.0),
       mOldOverflowDeltaX(0.0),
       mOldLineOrPageDeltaX(0),
       mHorizontalized(false) {}
 /**
  * Converts vertical scrolling into horizontal scrolling by adjusting the
  * its delta values.
  */
 void Horizontalize();
 ~WheelDeltaHorizontalizer();
 void CancelHorizontalization();

private:
 WidgetWheelEvent& mWheelEvent;
 double mOldDeltaX;
 double mOldDeltaZ;
 double mOldOverflowDeltaX;
 int32_t mOldLineOrPageDeltaX;
 bool mHorizontalized;
};

/**
* This class is used to adjust the delta values for wheel scrolling with the
* auto-dir functionality.
* A traditional wheel scroll only allows the user use the wheel in the same
* scrollable direction as that of the scrolling target to scroll the target,
* whereas an auto-dir scroll lets the user use any wheel(either a vertical
* wheel or a horizontal tilt wheel) to scroll a frame which is scrollable in
* only one direction. For detailed information on auto-dir scrolling,
* @see mozilla::WheelDeltaAdjustmentStrategy.
*/
class MOZ_STACK_CLASS AutoDirWheelDeltaAdjuster {
protected:
 /**
  * @param aDeltaX            DeltaX for a wheel event whose delta values will
  *                           be adjusted upon calling Adjust() when
  *                           ShouldBeAdjusted() returns true.
  * @param aDeltaY            DeltaY for a wheel event, like DeltaX.
  */
 AutoDirWheelDeltaAdjuster(double& aDeltaX, double& aDeltaY)
     : mDeltaX(aDeltaX),
       mDeltaY(aDeltaY),
       mCheckedIfShouldBeAdjusted(false),
       mShouldBeAdjusted(false) {}

public:
 /**
  * Gets whether the values of the delta should be adjusted for auto-dir
  * scrolling. Note that if Adjust() has been called, this function simply
  * returns false.
  *
  * @return true if the delta should be adjusted; otherwise false.
  */
 bool ShouldBeAdjusted();
 /**
  * Adjusts the values of the delta values for auto-dir scrolling when
  * ShouldBeAdjusted() returns true. If you call it when ShouldBeAdjusted()
  * returns false, this function will simply do nothing.
  */
 void Adjust();

private:
 /**
  * Called by Adjust() if Adjust() successfully adjusted the delta values.
  */
 virtual void OnAdjusted() {}

 virtual bool CanScrollAlongXAxis() const = 0;
 virtual bool CanScrollAlongYAxis() const = 0;
 virtual bool CanScrollUpwards() const = 0;
 virtual bool CanScrollDownwards() const = 0;
 virtual bool CanScrollLeftwards() const = 0;
 virtual bool CanScrollRightwards() const = 0;

 /**
  * Gets whether the horizontal content starts at rightside.
  *
  * @return If the content is in vertical-RTL writing mode(E.g. "writing-mode:
  *         vertical-rl" in CSS), or if it's in horizontal-RTL writing-mode
  *         (E.g. "writing-mode: horizontal-tb; direction: rtl;" in CSS), then
  *         this function returns true. From the representation perspective,
  *         frames whose horizontal contents start at rightside also cause
  *         their horizontal scrollbars, if any, initially start at rightside.
  *         So we can also learn about the initial side of the horizontal
  *         scrollbar for the frame by calling this function.
  */
 virtual bool IsHorizontalContentRightToLeft() const = 0;

protected:
 double& mDeltaX;
 double& mDeltaY;

private:
 bool mCheckedIfShouldBeAdjusted;
 bool mShouldBeAdjusted;
};

/**
* This is the implementation of AutoDirWheelDeltaAdjuster for EventStateManager
*
* Detailed comments about some member functions are given in the base class
* AutoDirWheelDeltaAdjuster.
*/
class MOZ_STACK_CLASS ESMAutoDirWheelDeltaAdjuster final
   : public AutoDirWheelDeltaAdjuster {
public:
 /**
  * @param aEvent             The auto-dir wheel scroll event.
  * @param aScrollFrame       The scroll target for the event.
  * @param aHonoursRoot       If set to true, the honoured frame is the root
  *                           frame in the same document where the target is;
  *                           If false, the honoured frame is the scroll
  *                           target. For the concept of an honoured target,
  *                           @see mozilla::WheelDeltaAdjustmentStrategy
  */
 ESMAutoDirWheelDeltaAdjuster(WidgetWheelEvent& aEvent, nsIFrame& aScrollFrame,
                              bool aHonoursRoot);

private:
 virtual void OnAdjusted() override;
 virtual bool CanScrollAlongXAxis() const override;
 virtual bool CanScrollAlongYAxis() const override;
 virtual bool CanScrollUpwards() const override;
 virtual bool CanScrollDownwards() const override;
 virtual bool CanScrollLeftwards() const override;
 virtual bool CanScrollRightwards() const override;
 virtual bool IsHorizontalContentRightToLeft() const override;

 ScrollContainerFrame* mScrollTargetFrame;
 bool mIsHorizontalContentRightToLeft;

 int32_t& mLineOrPageDeltaX;
 int32_t& mLineOrPageDeltaY;
 double& mOverflowDeltaX;
 double& mOverflowDeltaY;
};

/**
* This class is used for restoring the delta in an auto-dir wheel.
*
* An instance of this calss monitors auto-dir adjustment which may happen
* during its lifetime. If the delta values is adjusted during its lifetime, the
* instance will restore the adjusted delta when it's being destrcuted.
*/
class MOZ_STACK_CLASS ESMAutoDirWheelDeltaRestorer final {
public:
 /**
  * @param aEvent             The wheel scroll event to be monitored.
  */
 explicit ESMAutoDirWheelDeltaRestorer(WidgetWheelEvent& aEvent);
 ~ESMAutoDirWheelDeltaRestorer();

private:
 WidgetWheelEvent& mEvent;
 double mOldDeltaX;
 double mOldDeltaY;
 int32_t mOldLineOrPageDeltaX;
 int32_t mOldLineOrPageDeltaY;
 double mOldOverflowDeltaX;
 double mOldOverflowDeltaY;
};

}  // namespace mozilla

#endif  // mozilla_WheelHandlingHelper_h_