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

docs/api/app.md

@@ -564,11 +564,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

@@ -54,7 +54,7 @@ class Browser : public WindowListObserver {
   void Shutdown();
 
   // Focus the application.
-  void Focus();
+  void Focus(mate::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(mate::Arguments* args) {
   // Focus on the first visible window.
   for (auto* const window : WindowList::GetWindows()) {
     if (window->IsVisible()) {

shell/browser/browser_mac.mm

@@ -13,6 +13,7 @@
 #include "base/mac/scoped_cftyperef.h"
 #include "base/strings/string_number_conversions.h"
 #include "base/strings/sys_string_conversions.h"
+#include "native_mate/dictionary.h"
 #include "net/base/mac/url_conversions.h"
 #include "shell/browser/mac/dict_util.h"
 #include "shell/browser/mac/electron_application.h"
@@ -20,6 +21,9 @@
 #include "shell/browser/native_window.h"
 #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/platform_util.h"
 #include "shell/common/promise_util.h"
 #include "ui/gfx/image/image.h"
@@ -31,8 +35,20 @@ void Browser::SetShutdownHandler(base::Callback<bool()> handler) {
   [[AtomApplication sharedApplication] setShutdownHandler:std::move(handler)];
 }
 
-void Browser::Focus() {
-  [[AtomApplication sharedApplication] activateIgnoringOtherApps:NO];
+void Browser::Focus(mate::Arguments* args) {
+  mate::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(mate::Arguments* args) {
   // On Windows we just focus on the first window found for this process.
   DWORD pid = GetCurrentProcessId();
   EnumWindows(&WindowsEnumerationHandler, reinterpret_cast<LPARAM>(&pid));