content/browser/android/overscroll_refresh.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CONTENT_BROWSER_ANDROID_OVERSCROLL_REFRESH_H_
   6 #define CONTENT_BROWSER_ANDROID_OVERSCROLL_REFRESH_H_
   7
   8 #include "base/macros.h"
   9 #include "content/common/content_export.h"
  10 #include "ui/gfx/geometry/size_f.h"
  11 #include "ui/gfx/geometry/vector2d_f.h"
  12
  13 namespace content {
  14
  15 class CONTENT_EXPORT OverscrollRefreshHandler {
  16  public:
  17   // Signals the start of an overscrolling pull. Returns whether the handler
  18   // will consume the overscroll gesture, in which case it will receive the
  19   // remaining pull updates.
  20   virtual bool PullStart() = 0;
  21
  22   // Signals a pull update, where |delta| is in device pixels.
  23   virtual void PullUpdate(float delta) = 0;
  24
  25   // Signals the release of the pull, and whether the release is allowed to
  26   // trigger the refresh action.
  27   virtual void PullRelease(bool allow_refresh) = 0;
  28
  29   // Reset the active pull state.
  30   virtual void PullReset() = 0;
  31
  32  protected:
  33   virtual ~OverscrollRefreshHandler() {}
  34 };
  35
  36 // Simple pull-to-refresh styled effect. Listens to scroll events, conditionally
  37 // activating when:
  38 //   1) The scroll begins when the page's root layer 1) has no vertical scroll
  39 //      offset and 2) lacks the overflow-y:hidden property.
  40 //   2) The page doesn't consume the initial scroll events.
  41 //   3) The initial scroll direction is upward.
  42 // The actuall pull response, animation and action are delegated to the
  43 // provided refresh handler.
  44 class CONTENT_EXPORT OverscrollRefresh {
  45  public:
  46   // Minmum number of overscrolling pull events required to activate the effect.
  47   // Useful for avoiding accidental triggering when a scroll janks (is delayed),
  48   // capping the impulse per event.
  49   enum { kMinPullsToActivate = 3 };
  50
  51   explicit OverscrollRefresh(OverscrollRefreshHandler* handler);
  52   ~OverscrollRefresh();
  53
  54   // Scroll event stream listening methods.
  55   void OnScrollBegin();
  56   // Returns whether the refresh was activated.
  57   void OnScrollEnd(const gfx::Vector2dF& velocity);
  58
  59   // Scroll ack listener. The effect will only be activated if the initial
  60   // updates go unconsumed.
  61   void OnScrollUpdateAck(bool was_consumed);
  62
  63   // Returns true if the effect has consumed the |scroll_delta|.
  64   bool WillHandleScrollUpdate(const gfx::Vector2dF& scroll_delta);
  65
  66   // Release the effect (if active), preventing any associated refresh action.
  67   void ReleaseWithoutActivation();
  68
  69   // Notify the effect of the latest scroll offset and overflow properties.
  70   // The effect will be disabled when the offset is non-zero or overflow is
  71   // hidden. Note: All dimensions are in device pixels.
  72   void OnFrameUpdated(const gfx::Vector2dF& content_scroll_offset,
  73                       bool root_overflow_y_hidden);
  74
  75   // Reset the effect to its inactive state, immediately detaching and
  76   // disabling any active effects.
  77   void Reset();
  78
  79   // Returns true if the refresh effect is either being manipulated or animated.
  80   bool IsActive() const;
  81
  82   // Returns true if the effect is waiting for an unconsumed scroll to start.
  83   bool IsAwaitingScrollUpdateAck() const;
  84
  85  private:
  86   void Release(bool allow_refresh);
  87
  88   bool scrolled_to_top_;
  89   bool overflow_y_hidden_;
  90
  91   enum ScrollConsumptionState {
  92     DISABLED,
  93     AWAITING_SCROLL_UPDATE_ACK,
  94     ENABLED,
  95   } scroll_consumption_state_;
  96
  97   OverscrollRefreshHandler* const handler_;
  98
  99   DISALLOW_COPY_AND_ASSIGN(OverscrollRefresh);
 100 };
 101
 102 }  // namespace content
 103
 104 #endif  // CONTENT_BROWSER_ANDROID_OVERSCROLL_REFRESH_H_