feat: add force option to app.focus() (#22612) (#23447)

Co-authored-by: Shelley Vohr <[email protected]>

docs/api/app.md

@@ -554,11 +554,17 @@ Returns `Promise<void>` - fulfilled when Electron is initialized.
 May be used as a convenient alternative to checking `app.isReady()`
 and subscribing to the `ready` event if the app is not ready yet.
 
-### `app.focus()`
+### `app.focus([options])`
+
+* `options` Object (optional)
+  * `steal` Boolean _macOS_ - Make the receiver the active app even if another app is
+  currently active.
 
 On Linux, focuses on the first visible window. On macOS, makes the application
 the active app. On Windows, focuses on the application's first window.
 
+You should seek to use the `steal` option as sparingly as possible.
+
 ### `app.hide()` _macOS_
 
 Hides all application windows without minimizing them.

shell/browser/browser.h

@@ -57,7 +57,7 @@ class Browser : public WindowListObserver {
   void Shutdown();
 
   // Focus the application.
-  void Focus();
+  void Focus(gin_helper::Arguments* args);
 
   // Returns the version of the executable (or bundle).
   std::string GetVersion() const;

shell/browser/browser_linux.cc

@@ -84,7 +84,7 @@ bool SetDefaultWebClient(const std::string& protocol) {
   return ran_ok && exit_code == EXIT_SUCCESS;
 }
 
-void Browser::Focus() {
+void Browser::Focus(gin_helper::Arguments* args) {
   // Focus on the first visible window.
   for (auto* const window : WindowList::GetWindows()) {
     if (window->IsVisible()) {

shell/browser/browser_mac.mm

@@ -21,6 +21,8 @@
 #include "shell/browser/window_list.h"
 #include "shell/common/application_info.h"
 #include "shell/common/gin_helper/arguments.h"
+#include "shell/common/gin_helper/dictionary.h"
+#include "shell/common/gin_helper/error_thrower.h"
 #include "shell/common/gin_helper/promise.h"
 #include "shell/common/platform_util.h"
 #include "ui/gfx/image/image.h"
@@ -32,8 +34,20 @@ void Browser::SetShutdownHandler(base::Callback<bool()> handler) {
   [[AtomApplication sharedApplication] setShutdownHandler:std::move(handler)];
 }
 
-void Browser::Focus() {
-  [[AtomApplication sharedApplication] activateIgnoringOtherApps:NO];
+void Browser::Focus(gin_helper::Arguments* args) {
+  gin_helper::Dictionary opts;
+  bool steal_focus = false;
+
+  if (args->GetNext(&opts)) {
+    gin_helper::ErrorThrower thrower(args->isolate());
+    if (!opts.Get("steal", &steal_focus)) {
+      thrower.ThrowError(
+          "Expected options object to contain a 'steal' boolean property");
+      return;
+    }
+  }
+
+  [[AtomApplication sharedApplication] activateIgnoringOtherApps:steal_focus];
 }
 
 void Browser::Hide() {

shell/browser/browser_win.cc

@@ -163,7 +163,7 @@ Browser::UserTask::UserTask() = default;
 Browser::UserTask::UserTask(const UserTask&) = default;
 Browser::UserTask::~UserTask() = default;
 
-void Browser::Focus() {
+void Browser::Focus(gin_helper::Arguments* args) {
   // On Windows we just focus on the first window found for this process.
   DWORD pid = GetCurrentProcessId();
   EnumWindows(&WindowsEnumerationHandler, reinterpret_cast<LPARAM>(&pid));