[Android] Add a native pull-to-refresh overscroll effect

content/browser/android/overscroll_refresh.h

+// Copyright 2014 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef CONTENT_BROWSER_ANDROID_OVERSCROLL_REFRESH_H_
+#define CONTENT_BROWSER_ANDROID_OVERSCROLL_REFRESH_H_
+
+#include "base/memory/scoped_ptr.h"
+#include "base/time/time.h"
+#include "content/common/content_export.h"
+#include "ui/gfx/size_f.h"
+#include "ui/gfx/vector2d_f.h"
+
+namespace cc {
+class Layer;
+}
+
+namespace ui {
+class SystemUIResourceManager;
+}
+
+namespace content {
+
+// Allows both page reload activation and page reloading state queries.
+class CONTENT_EXPORT OverscrollRefreshClient {
+ public:
+  virtual ~OverscrollRefreshClient() {}
+  virtual void TriggerRefresh() = 0;
+  virtual bool IsTriggeredRefreshActive() const = 0;
+};
+
+// Simple pull-to-refresh styled effect. Listens to scroll events, conditionally
+// activating when:
+//   1) The scroll begins when the page has no vertical scroll offset.
+//   2) The page doesn't consume the initial scroll events.
+//   3) The initial scroll direction is upward.
+// The actual page reload action is triggered only when the effect is active
+// and beyond a particular threshold when released.
+class CONTENT_EXPORT OverscrollRefresh {
+ public:
+  OverscrollRefresh(ui::SystemUIResourceManager* resource_manager,
+                    OverscrollRefreshClient* client);
+  ~OverscrollRefresh();
+
+  // Scroll event stream listening methods.
+  void OnScrollBegin();
+  void OnScrollEnd(const gfx::Vector2dF& velocity);
+
+  // Scroll ack listener. The effect will only be activated if the initial
+  // update ack specifies ALLOW_ACTIVATION.
+  enum ActivationAllowance { ALLOW_ACTIVATION, PREVENT_ACTIVATION };

[aelias_OOO_until_Jul13, 2014/11/06 22:28:49]

This enum seems like an unnecessary abstraction.  Please just make
OnScrollUpdateAck take "bool was_consumed"

[jdduke (slow), 2014/11/07 18:33:45]

Hmm, yeah, I had a bool, then I needed a second bool, then a made it an enum,
and then I removed one of the enum states, so yeah, bool it is...

+  void OnScrollUpdateAck(ActivationAllowance allowance);
+
+  // Returns true if the supplied |scroll_delta| is consumed, in which case it

[aelias_OOO_until_Jul13, 2014/11/06 22:28:48]

Please avoid the slightly ambiguous passive tense here: "Returns true if the
refresh effect has consumed the |scroll_delta|"

+  // should cease propagation.
+  bool WillHandleScrollUpdate(const gfx::Vector2dF& scroll_delta);
+
+  // Returns true if the effect still needs animation ticks, with effect layers
+  // attached to |parent| if necessary.
+  // Note: The effect will detach itself when no further animation is required.
+  bool Animate(base::TimeTicks current_time, cc::Layer* parent_layer);
+
+  // Update the effect according to the most recent display parameters,
+  // Note: All dimensions are in device pixels.
+  void UpdateDisplay(const gfx::SizeF& viewport_size,
+                     const gfx::Vector2dF& content_scroll_offset);
+
+  // Reset the effect to its inactive state, detaching any active effects.
+  void Reset();
+
+  // Returns true if the refresh effect is either being manipulated or animated.
+  bool IsActive() const;

[aelias_OOO_until_Jul13, 2014/11/06 22:28:49]

Here you use "active" to mean "exists at all" and elsewhere you use the same
wording to mean "confirmed to cause a refresh".  Could you rename this one to
"Exists()" maybe?

[jdduke (slow), 2014/11/07 18:33:45]

Yeah, the other |Active()| is prefixed to |IsTriggeredRefreshActive()|, but it
is a bit confusing. What about |IsAlive()|?

Actually, I'm not a huge fan of Exists or Alive, I'll rename the other Active
term to something else.

+
+  // Returns true if the effect is waiting for an unconsumed scroll to start.
+  bool IsPendingScrollUpdateAck() const;

[aelias_OOO_until_Jul13, 2014/11/06 22:28:48]

Please rename to IsAwaitingScrollUpdateAck, I think using the word "waiting"
makes this easier to follow.

[jdduke (slow), 2014/11/07 18:33:44]

Done.

+
+ private:
+  void Release(bool allow_activation);
+
+  OverscrollRefreshClient* const client_;
+
+  gfx::SizeF viewport_size_;
+  gfx::Vector2dF scroll_offset_;

[aelias_OOO_until_Jul13, 2014/11/06 22:28:49]

I'd prefer this as a "bool scrolled_to_top_" as this is rich information and
raises the question of why the refresh effect needs it. 

[jdduke (slow), 2014/11/07 18:33:44]

Done.

+
+  enum ScrollConsumptionState {
+    DISABLED,
+    PENDING_SCROLL_UPDATE_ACK,

[aelias_OOO_until_Jul13, 2014/11/06 22:28:48]

Please rename to AWAITING_SCROLL_UPDATE_ACK.

[jdduke (slow), 2014/11/07 18:33:45]

Done.

+    ENABLED,
+  } scroll_consumption_state_;
+
+  class Effect;
+  scoped_ptr<Effect> effect_;
+
+  DISALLOW_COPY_AND_ASSIGN(OverscrollRefresh);
+};
+
+}  // namespace content
+
+#endif  // CONTENT_BROWSER_ANDROID_OVERSCROLL_REFRESH_H_