feat: Exposing methods required by capturing a hidden webContents (#21895)

docs/api/web-contents.md

@@ -1247,6 +1247,29 @@ Returns `Promise<NativeImage>` - Resolves with a [NativeImage](native-image.md)
 
 Captures a snapshot of the page within `rect`. Omitting `rect` will capture the whole visible page.
 
+#### `contents.isBeingCaptured()`
+
+Returns `Boolean` - Whether this page is being captured. It returns true when the capturer count
+is large then 0.
+
+#### `contents.incrementCapturerCount([size, stayHidden])`
+
+* `size` [Size](structures/size.md) (optional) - The perferred size for the capturer.
+* `stayHidden` Boolean (optional) -  Keep the page hidden instead of visible.
+
+Increase the capturer count by one. The page is considered visible when its browser window is
+hidden and the capturer count is non-zero. If you would like the page to stay hidden, you should ensure that `stayHidden` is set to true.
+
+This also affects the Page Visibility API.
+
+#### `contents.decrementCapturerCount([stayHidden])`
+
+* `stayHidden` Boolean (optional) -  Keep the page in hidden state instead of visible.
+
+Decrease the capturer count by one. The page will be set to hidden or occluded state when its
+browser window is hidden or occluded and the capturer count reaches zero. If you want to
+decrease the hidden capturer count instead you should set `stayHidden` to true.
+
 #### `contents.getPrinters()`
 
 Get the system printer list.

shell/browser/api/atom_api_web_contents.cc

@@ -2248,6 +2248,34 @@ v8::Local<v8::Promise> WebContents::CapturePage(mate::Arguments* mate_args) {
   return handle;
 }
 
+void WebContents::IncrementCapturerCount(mate::Arguments* mate_args) {
+  gin::Arguments gin_args(mate_args->info());
+  gin_helper::Arguments* args = static_cast<gin_helper::Arguments*>(&gin_args);
+
+  gfx::Size size;
+  bool stay_hidden = false;
+
+  // get size arguments if they exist
+  args->GetNext(&size);
+  // get stayHidden arguments if they exist
+  args->GetNext(&stay_hidden);
+
+  web_contents()->IncrementCapturerCount(size, stay_hidden);
+}
+
+void WebContents::DecrementCapturerCount(mate::Arguments* args) {
+  bool stay_hidden = false;
+
+  // get stayHidden arguments if they exist
+  args->GetNext(&stay_hidden);
+
+  web_contents()->DecrementCapturerCount(stay_hidden);
+}
+
+bool WebContents::IsBeingCaptured() {
+  return web_contents()->IsBeingCaptured();
+}
+
 void WebContents::OnCursorChange(const content::WebCursor& cursor) {
   const content::CursorInfo& info = cursor.info();
 
@@ -2627,6 +2655,9 @@ void WebContents::BuildPrototype(v8::Isolate* isolate,
       .SetMethod("setEmbedder", &WebContents::SetEmbedder)
       .SetMethod("setDevToolsWebContents", &WebContents::SetDevToolsWebContents)
       .SetMethod("getNativeView", &WebContents::GetNativeView)
+      .SetMethod("incrementCapturerCount", &WebContents::IncrementCapturerCount)
+      .SetMethod("decrementCapturerCount", &WebContents::DecrementCapturerCount)
+      .SetMethod("isBeingCaptured", &WebContents::IsBeingCaptured)
       .SetMethod("setWebRTCIPHandlingPolicy",
                  &WebContents::SetWebRTCIPHandlingPolicy)
       .SetMethod("getWebRTCIPHandlingPolicy",

shell/browser/api/atom_api_web_contents.h

@@ -182,6 +182,9 @@ class WebContents : public mate::TrackableObject<WebContents>,
   void SetEmbedder(const WebContents* embedder);
   void SetDevToolsWebContents(const WebContents* devtools);
   v8::Local<v8::Value> GetNativeView() const;
+  void IncrementCapturerCount(mate::Arguments* args);
+  void DecrementCapturerCount(mate::Arguments* args);
+  bool IsBeingCaptured();
 
 #if BUILDFLAG(ENABLE_PRINTING)
   void Print(mate::Arguments* args);