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/memory/scoped_ptr.h"
   9 #include "base/time/time.h"
  10 #include "content/common/content_export.h"
  11 #include "ui/gfx/geometry/size_f.h"
  12 #include "ui/gfx/geometry/vector2d_f.h"
  13
  14 namespace cc {
  15 class Layer;
  16 }
  17
  18 namespace ui {
  19 class ResourceManager;
  20 }
  21
  22 namespace content {
  23
  24 // Allows both page reload activation and page reloading state queries.
  25 class CONTENT_EXPORT OverscrollRefreshClient {
  26  public:
  27   virtual ~OverscrollRefreshClient() {}
  28
  29   // Called when the effect is released beyond the activation threshold. This
  30   // should cause a refresh of some kind, e.g., page reload.
  31   virtual void TriggerRefresh() = 0;
  32
  33   // Whether the triggered refresh has yet to complete. The effect will continue
  34   // animating until the refresh completes (or it reaches a reasonable timeout).
  35   virtual bool IsStillRefreshing() const = 0;
  36 };
  37
  38 // Simple pull-to-refresh styled effect. Listens to scroll events, conditionally
  39 // activating when:
  40 //   1) The scroll begins when the page's root layer 1) has no vertical scroll
  41 //      offset and 2) lacks the overflow-y:hidden property.
  42 //   2) The page doesn't consume the initial scroll events.
  43 //   3) The initial scroll direction is upward.
  44 // The actual page reload action is triggered only when the effect is active
  45 // and beyond a particular threshold when released.
  46 class CONTENT_EXPORT OverscrollRefresh {
  47  public:
  48   // Minmum number of overscrolling pull events required to activate the effect.
  49   // Useful for avoiding accidental triggering when a scroll janks (is delayed),
  50   // capping the impulse per event.
  51   enum { kMinPullsToActivate = 3 };
  52
  53   // Both |resource_manager| and |client| must not be null.
  54   // |target_drag_offset_pixels| is the threshold beyond which the effect
  55   // will trigger a refresh action when released. When |mirror| is true,
  56   // the effect and its rotation will be mirrored about the y axis.
  57   OverscrollRefresh(ui::ResourceManager* resource_manager,
  58                     OverscrollRefreshClient* client,
  59                     float target_drag_offset_pixels,
  60                     bool mirror);
  61   ~OverscrollRefresh();
  62
  63   // Scroll event stream listening methods.
  64   void OnScrollBegin();
  65   void OnScrollEnd(const gfx::Vector2dF& velocity);
  66
  67   // Scroll ack listener. The effect will only be activated if the initial
  68   // updates go unconsumed.
  69   void OnScrollUpdateAck(bool was_consumed);
  70
  71   // Returns true if the effect has consumed the |scroll_delta|.
  72   bool WillHandleScrollUpdate(const gfx::Vector2dF& scroll_delta);
  73
  74   // Release the effect (if active), preventing any associated refresh action.
  75   void ReleaseWithoutActivation();
  76
  77   // Returns true if the effect still needs animation ticks, with effect layers
  78   // attached to |parent| if necessary.
  79   // Note: The effect will detach itself when no further animation is required.
  80   bool Animate(base::TimeTicks current_time, cc::Layer* parent_layer);
  81
  82   // Update the effect according to the most recent display parameters,
  83   // Note: All dimensions are in device pixels.
  84   void UpdateDisplay(const gfx::SizeF& viewport_size,
  85                      const gfx::Vector2dF& content_scroll_offset,
  86                      bool root_overflow_y_hidden);
  87
  88   // Reset the effect to its inactive state, immediately detaching and
  89   // disabling any active effects.
  90   void Reset();
  91
  92   // Returns true if the refresh effect is either being manipulated or animated.
  93   bool IsActive() const;
  94
  95   // Returns true if the effect is waiting for an unconsumed scroll to start.
  96   bool IsAwaitingScrollUpdateAck() const;
  97
  98  private:
  99   void Release(bool allow_activation);
 100
 101   OverscrollRefreshClient* const client_;
 102
 103   gfx::SizeF viewport_size_;
 104   bool scrolled_to_top_;
 105   bool overflow_y_hidden_;
 106
 107   enum ScrollConsumptionState {
 108     DISABLED,
 109     AWAITING_SCROLL_UPDATE_ACK,
 110     ENABLED,
 111   } scroll_consumption_state_;
 112
 113   class Effect;
 114   scoped_ptr<Effect> effect_;
 115
 116   DISALLOW_COPY_AND_ASSIGN(OverscrollRefresh);
 117 };
 118
 119 }  // namespace content
 120
 121 #endif  // CONTENT_BROWSER_ANDROID_OVERSCROLL_REFRESH_H_