Support the "desktop" window type on Mac OS X

Adds the desktop window type referenced in https://github.com/atom/electron/issues/2899 for compatiblity with the linux version. Note that on Mac OS X, the desktop window cannot receive input events (seems to be a limitation of being behind the desktop).

In this diff I also removed the `standardWindow` option from the docs, in favor of an additional `textured` value for window `type` on Mac OS X. The old `standardWindow` option continues to work, but seemed more confusing. If this seems like a bad idea, I can revert that change.

atom/browser/native_window_mac.mm

@@ -211,6 +211,8 @@ bool ScopedDisableResize::disable_resize_ = false;
 }
 @property BOOL acceptsFirstMouse;
 @property BOOL disableAutoHideCursor;
+@property BOOL disableKeyOrMainWindow;
+
 - (void)setShell:(atom::NativeWindowMac*)shell;
 - (void)setEnableLargerThanScreen:(bool)enable;
 @end
@@ -257,6 +259,16 @@ bool ScopedDisableResize::disable_resize_ = false;
   return [children filteredArrayUsingPredicate:predicate];
 }
 
+- (BOOL)canBecomeMainWindow
+{
+    return !self.disableKeyOrMainWindow;
+}
+
+- (BOOL)canBecomeKeyWindow
+{
+    return !self.disableKeyOrMainWindow;
+}
+
 @end
 
 @interface ControlRegionView : NSView
@@ -330,8 +342,6 @@ NativeWindowMac::NativeWindowMac(
       width,
       height);
 
-  bool useStandardWindow = true;
-  options.Get(options::kStandardWindow, &useStandardWindow);
   bool resizable = true;
   options.Get(options::kResizable, &resizable);
 
@@ -340,6 +350,17 @@ NativeWindowMac::NativeWindowMac(
   if (base::mac::IsOSYosemiteOrLater())
     options.Get(options::kTitleBarStyle, &titleBarStyle);
 
+  std::string windowType;
+  options.Get(options::kType, &windowType);
+
+  bool useStandardWindow = true;
+  // eventually deprecate separate "standardWindow" option in favor of
+  // standard / textured window types
+  options.Get(options::kStandardWindow, &useStandardWindow);
+  if (windowType == "textured") {
+    useStandardWindow = false;
+  }
+
   NSUInteger styleMask = NSTitledWindowMask | NSClosableWindowMask |
                          NSMiniaturizableWindowMask;
   if (!useStandardWindow || transparent() || !has_frame()) {
@@ -371,6 +392,15 @@ NativeWindowMac::NativeWindowMac(
     [window_ setBackgroundColor:[NSColor clearColor]];
   }
 
+  if (windowType == "desktop") {
+    [window_ setLevel:kCGDesktopWindowLevel - 1];
+    [window_ setDisableKeyOrMainWindow: YES];
+    [window_ setCollectionBehavior:
+        (NSWindowCollectionBehaviorCanJoinAllSpaces |
+         NSWindowCollectionBehaviorStationary |
+         NSWindowCollectionBehaviorIgnoresCycle)];
+  }
+
   // Remove non-transparent corners, see http://git.io/vfonD.
   if (!has_frame())
     [window_ setOpaque:NO];

docs/api/browser-window.md

@@ -66,11 +66,14 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
 * `darkTheme` Boolean - Forces using dark theme for the window, only works on
   some GTK+3 desktop environments.
 * `transparent` Boolean - Makes the window [transparent](frameless-window.md).
-* `type` String - Specifies the type of the window, possible types are
+* `type` String - Specifies the type of the window, which applies
-  `desktop`, `dock`, `toolbar`, `splash`, `notification`. This only works on
+  additional platform-specific properties.
-  Linux.
+  - On Linux, possible types are `desktop`, `dock`, `toolbar`, `splash`, `notification`.
-* `standardWindow` Boolean - Uses the OS X's standard window instead of the
+  - On Mac OS X:
-  textured window. Defaults to `true`.
+    - `textured`: Adds metal gradient appearance (NSTexturedBackgroundWindowMask)
+    - `desktop`: Places the window at the desktop background window level (kCGDesktopWindowLevel - 1).
+      Note that the window will not receive focus, keyboard or mouse events, but
+      you can use `globalShortcut` to receive input sparingly.
 * `titleBarStyle` String, OS X - specifies the style of window title bar.
   This option is supported on OS X 10.10 Yosemite and newer. There are three
   possible values:
@@ -86,11 +89,11 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
     is `true`.
   * `preload` String - Specifies a script that will be loaded before other
     scripts run in the page. This script will always have access to node APIs
-    no matter whether node integration is turned on or off. The value should 
+    no matter whether node integration is turned on or off. The value should
     be the absolute file path to the script.
 
-    When node integration is turned off, the preload script can reintroduce 
+    When node integration is turned off, the preload script can reintroduce
-    Node global symbols back to the global scope. See example 
+    Node global symbols back to the global scope. See example
     [here](process.md#event-loaded).
   * `partition` String - Sets the session used by the page. If `partition`
     starts with `persist:`, the page will use a persistent session available to