DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Implementation

Mercurial (19704452bd54)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401
/* -*- 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"
#include "nsPoint.h"

class nsIScrollableFrame;
class nsITimer;

namespace mozilla {

class EventStateManager;

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

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

  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 scrollable frame can be scrolled to either aDirectionX
   * or aDirectionY along each axis.  Otherwise, false.
   */
  static bool CanScrollOn(nsIScrollableFrame* aScrollFrame, 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(nsIScrollableFrame* 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 const DeltaValues directions[kNumberOfTargets];
  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:
  static nsIFrame* GetTargetFrame() { return sTargetFrame; }
  static void EndTransaction();
  /**
   * WillHandleDefaultAction() is called before handling aWheelEvent on
   * aTargetFrame.
   *
   * @return    false if the caller cannot continue to handle the default
   *            action.  Otherwise, true.
   */
  static bool WillHandleDefaultAction(WidgetWheelEvent* aWheelEvent,
                                      AutoWeakFrame& aTargetWeakFrame);
  static bool WillHandleDefaultAction(WidgetWheelEvent* aWheelEvent,
                                      nsIFrame* aTargetFrame) {
    AutoWeakFrame targetWeakFrame(aTargetFrame);
    return WillHandleDefaultAction(aWheelEvent, targetWeakFrame);
  }
  static void OnEvent(WidgetEvent* aEvent);
  static void Shutdown();

  static void OwnScrollbars(bool aOwn);

  static DeltaValues AccelerateWheelDelta(WidgetWheelEvent* aEvent,
                                          bool aAllowScrollSpeedOverride);

 protected:
  static void BeginTransaction(nsIFrame* aTargetFrame,
                               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);

  static AutoWeakFrame sTargetFrame;
  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;

  nsIScrollableFrame* 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_