Bug 1516722 - Update usage notes for nsIPresShell::ScrollToVisual(). r=kats
authorBotond Ballo <botond@mozilla.com>
Tue, 07 May 2019 03:04:06 +0000
changeset 531648 f1d9dca026c389f6c1cc1f71b695a565fd129a13
parent 531647 9e64b394951d590347507ced94692d6be8b36d28
child 531649 7aee5a30dd15cf0e203705808de4fc84cd56393d
push id11265
push userffxbld-merge
push dateMon, 13 May 2019 10:53:39 +0000
treeherdermozilla-beta@77e0fe8dbdd3 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerskats
bugs1516722
milestone68.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1516722 - Update usage notes for nsIPresShell::ScrollToVisual(). r=kats Differential Revision: https://phabricator.services.mozilla.com/D30106
layout/base/PresShell.h
--- a/layout/base/PresShell.h
+++ b/layout/base/PresShell.h
@@ -1188,23 +1188,30 @@ class PresShell final : public nsStubDoc
   struct VisualScrollUpdate {
     nsPoint mVisualScrollOffset;
     FrameMetrics::ScrollOffsetUpdateType mUpdateType;
     bool mAcknowledged = false;
   };
 
   // Ask APZ in the next transaction to scroll to the given visual viewport
   // offset (relative to the document).
-  // Use this sparingly, as it will clobber JS-driven scrolling that happens
-  // in the same frame. This is mostly intended to be used in special
-  // situations like "first paint" or session restore.
+  // This is intended to be used when desired in cases where the browser
+  // internally triggers scrolling; scrolling triggered explicitly by web
+  // content (such as via window.scrollTo() should scroll the layout viewport
+  // only).
   // If scrolling "far away", i.e. not just within the existing layout
   // viewport, it's recommended to use both nsIScrollableFrame.ScrollTo*()
   // (via window.scrollTo if calling from JS) *and* this function; otherwise,
-  // temporary checkerboarding may result.
+  // temporary checkerboarding may result. If doing this:
+  //   * Be sure to call ScrollTo*() first, as a subsequent layout scroll
+  //     in the same transaction will cancel the pending visual scroll.
+  //   * Keep in mind that ScrollTo*() can tear down the pres shell and
+  //     frame tree. Depending on how the pres shell is obtained for the
+  //     subsequent ScrollToVisual() call, AutoWeakFrame or similar may
+  //     need to be used.
   // Please request APZ review if adding a new call site.
   void ScrollToVisual(const nsPoint& aVisualViewportOffset,
                       FrameMetrics::ScrollOffsetUpdateType aUpdateType,
                       ScrollMode aMode);
   void AcknowledgePendingVisualScrollUpdate();
   void ClearPendingVisualScrollUpdate();
   const Maybe<VisualScrollUpdate>& GetPendingVisualScrollUpdate() const {
     return mPendingVisualScrollUpdate;