Bug 1037643 - Part 1 - Add ResponsiveImageSelector::SelectImage r=jst

content/base/src/ResponsiveImageSelector.cpp

@@ -263,6 +263,19 @@ ResponsiveImageSelector::GetSelectedImageDensity()
   return mCandidates[bestIndex].Density(this);
 }
 
+bool
+ResponsiveImageSelector::SelectImage(bool aReselect)
+{
+  if (!aReselect && mBestCandidateIndex != -1) {
+    // Already have selection
+    return false;
+  }
+
+  int oldBest = mBestCandidateIndex;
+  mBestCandidateIndex = -1;
+  return GetBestCandidateIndex() != oldBest;
+}
+
 int
 ResponsiveImageSelector::GetBestCandidateIndex()
 {

content/base/src/ResponsiveImageSelector.h

@@ -25,6 +25,18 @@ public:
   NS_DECL_ISUPPORTS
   explicit ResponsiveImageSelector(nsIContent* aContent);
 
+  // NOTE ABOUT CURRENT SELECTION
+  //
+  // The best candidate is selected lazily when GetSelectedImage*() is
+  // called, or when SelectImage() is called explicitly. This result
+  // is then cached until either invalidated by further Set*() calls,
+  // or explicitly by replaced by SelectImage(aReselect = true).
+  //
+  // Because the selected image depends on external variants like
+  // viewport size and device pixel ratio, the time at which image
+  // selection occurs can affect the result.
+
+
   // Given a srcset string, parse and replace current candidates (does not
   // replace default source)
   bool SetCandidatesFromSourceSet(const nsAString & aSrcSet);
@@ -41,10 +53,19 @@ public:
 
   nsIContent *Content() { return mContent; }
 
-  // Get the URL for the selected best candidate
+  // Get the url and density for the selected best candidate. These
+  // implicitly cause an image to be selected if necessary.
   already_AddRefed<nsIURI> GetSelectedImageURL();
   double GetSelectedImageDensity();
 
+  // Runs image selection now if necessary. If an image has already
+  // been choosen, takes no action unless aReselect is true.
+  //
+  // aReselect - Always re-run selection, replacing the previously
+  //             choosen image.
+  // return - true if the selected image result changed.
+  bool SelectImage(bool aReselect = false);
+
 protected:
   virtual ~ResponsiveImageSelector();