feat: add property support for remainder of BrowserWindow (#23208)

Adds property-based support for the remainder of primitive getter/setter pairs on `BrowserWindow`.

Namely:
- `win.simpleFullScreen`
- `win.title`
- `win.visibleOnAllWorkspaces`
- `win.documentEdited`
- `win.representedFilename`
- `win.shadow`
- `win.kiosk`
- `win.menuBarVisible`

docs/api/browser-window.md

@@ -177,7 +177,7 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
   * `simpleFullscreen` Boolean (optional) - Use pre-Lion fullscreen on macOS. Default is `false`.
   * `skipTaskbar` Boolean (optional) - Whether to show the window in taskbar. Default is
     `false`.
-  * `kiosk` Boolean (optional) - The kiosk mode. Default is `false`.
+  * `kiosk` Boolean (optional) - Whether the window is in kiosk mode. Default is `false`.
   * `title` String (optional) - Default window title. Default is `"Electron"`. If the HTML tag `<title>` is defined in the HTML file loaded by `loadURL()`, this property will be ignored.
   * `icon` ([NativeImage](native-image.md) | String) (optional) - The window icon. On Windows it is
     recommended to use `ICO` icons to get best visual effects, you can also
@@ -803,6 +803,47 @@ A `Boolean` property that determines whether the window menu bar should hide its
 If the menu bar is already visible, setting this property to `true` won't
 hide it immediately.
 
+#### `win.simpleFullScreen`
+
+A `Boolean` property that determines whether the window is in simple (pre-Lion) fullscreen mode.
+
+#### `win.visibleOnAllWorkspaces`
+
+A `Boolean` property that determines whether the window is visible on all workspaces.
+
+**Note:** Always returns false on Windows.
+
+#### `win.shadow`
+
+A `Boolean` property that determines whether the window has a shadow.
+
+#### `win.menuBarVisible` _Windows_ _Linux_
+
+A `Boolean` property that determines whether the menu bar should be visible.
+
+**Note:** If the menu bar is auto-hide, users can still bring up the menu bar by pressing the single `Alt` key.
+
+####  `win.kiosk`
+
+A `Boolean` property that determines whether the window is in kiosk mode.
+
+#### `win.documentEdited` _macOS_
+
+A `Boolean` property that specifies whether the window’s document has been edited.
+
+The icon in title bar will become gray when set to `true`.
+
+#### `win.representedFilename` _macOS_
+
+A `String` property that determines the pathname of the file the window represents,
+and the icon of the file will show in window's title bar.
+
+#### `win.title`
+
+A `String` property that determines the title of the native window.
+
+**Note:** The title of the web page can be different from the title of the native window.
+
 #### `win.minimizable`
 
 A `Boolean` property that determines whether the window can be manually minimized by user.
@@ -1282,7 +1323,7 @@ Makes the window not show in the taskbar.
 
 * `flag` Boolean
 
-Enters or leaves the kiosk mode.
+Enters or leaves kiosk mode.
 
 #### `win.isKiosk()`
 

docs/api/modernization/property-updates.md

@@ -5,14 +5,7 @@ The Electron team is currently undergoing an initiative to convert separate gett
 ## Candidates
 
 * `BrowserWindow`
-  * `fullscreen`
-  * `simpleFullscreen`
-  * `alwaysOnTop`
-  * `title`
-  * `documentEdited`
-  * `hasShadow`
   * `menubarVisible`
-  * `visibleOnAllWorkspaces`
 * `crashReporter` module
   * `uploadToServer`
 * `webFrame` modules

lib/browser/api/browser-window.js

@@ -92,43 +92,6 @@ BrowserWindow.prototype._init = function () {
       return this.webContents.devToolsWebContents;
     }
   });
-
-  // Properties
-
-  Object.defineProperty(this, 'autoHideMenuBar', {
-    get: () => this.isMenuBarAutoHide(),
-    set: (autoHide) => this.setAutoHideMenuBar(autoHide)
-  });
-
-  Object.defineProperty(this, 'minimizable', {
-    get: () => this.isMinimizable(),
-    set: (min) => this.setMinimizable(min)
-  });
-
-  Object.defineProperty(this, 'maximizable', {
-    get: () => this.isMaximizable(),
-    set: (max) => this.setMaximizable(max)
-  });
-
-  Object.defineProperty(this, 'resizable', {
-    get: () => this.isResizable(),
-    set: (res) => this.setResizable(res)
-  });
-
-  Object.defineProperty(this, 'fullScreenable', {
-    get: () => this.isFullScreenable(),
-    set: (full) => this.setFullScreenable(full)
-  });
-
-  Object.defineProperty(this, 'closable', {
-    get: () => this.isClosable(),
-    set: (close) => this.setClosable(close)
-  });
-
-  Object.defineProperty(this, 'movable', {
-    get: () => this.isMovable(),
-    set: (move) => this.setMovable(move)
-  });
 };
 
 const isBrowserWindow = (win) => {

lib/browser/api/top-level-window.js

@@ -17,6 +17,83 @@ TopLevelWindow.prototype._init = function () {
   }
 };
 
+// Properties
+
+Object.defineProperty(TopLevelWindow.prototype, 'autoHideMenuBar', {
+  get: function () { return this.isMenuBarAutoHide(); },
+  set: function (autoHide) { this.setAutoHideMenuBar(autoHide); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'visibleOnAllWorkspaces', {
+  get: function () { return this.isVisibleOnAllWorkspaces(); },
+  set: function (visible) { this.setVisibleOnAllWorkspaces(visible); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'simpleFullScreen', {
+  get: function () { return this.isSimpleFullScreen(); },
+  set: function (simple) { this.setSimpleFullScreen(simple); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'kiosk', {
+  get: function () { return this.isKiosk(); },
+  set: function (kiosk) { this.setKiosk(kiosk); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'documentEdited', {
+  get: function () { return this.isFullscreen(); },
+  set: function (edited) { this.setDocumentEdited(edited); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'shadow', {
+  get: function () { return this.hasShadow(); },
+  set: function (shadow) { this.setHasShadow(shadow); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'representedFilename', {
+  get: function () { return this.getRepresentedFilename(); },
+  set: function (filename) { this.setRepresentedFilename(filename); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'minimizable', {
+  get: function () { return this.isMinimizable(); },
+  set: function (min) { this.setMinimizable(min); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'title', {
+  get: function () { return this.getTitle(); },
+  set: function (title) { this.setTitle(title); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'maximizable', {
+  get: function () { return this.isMaximizable(); },
+  set: function (max) { this.setMaximizable(max); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'resizable', {
+  get: function () { return this.isResizable(); },
+  set: function (res) { this.setResizable(res); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'menuBarVisible', {
+  get: function () { return this.isMenuBarVisible(); },
+  set: function (visible) { this.setMenuBarVisibility(visible); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'fullScreenable', {
+  get: function () { return this.isFullScreenable(); },
+  set: function (full) { this.setFullScreenable(full); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'closable', {
+  get: function () { return this.isClosable(); },
+  set: function (close) { this.setClosable(close); }
+});
+
+Object.defineProperty(TopLevelWindow.prototype, 'movable', {
+  get: function () { return this.isMovable(); },
+  set: function (move) { this.setMovable(move); }
+});
+
 TopLevelWindow.getFocusedWindow = () => {
   return TopLevelWindow.getAllWindows().find((win) => win.isFocused());
 };

spec-main/api-browser-window-spec.ts

@@ -943,8 +943,9 @@ describe('BrowserWindow module', () => {
           w.setPosition(pos[0], pos[1]);
         });
       });
-      ifdescribe(process.platform !== 'linux')(`Maximized state`, () => {
-        it(`checks normal bounds when maximized`, (done) => {
+
+      ifdescribe(process.platform !== 'linux')('Maximized state', () => {
+        it('checks normal bounds when maximized', (done) => {
           const bounds = w.getBounds();
           w.once('maximize', () => {
             expectBoundsEqual(w.getNormalBounds(), bounds);
@@ -966,8 +967,9 @@ describe('BrowserWindow module', () => {
           w.maximize();
         });
       });
-      ifdescribe(process.platform !== 'linux')(`Minimized state`, () => {
-        it(`checks normal bounds when minimized`, (done) => {
+
+      ifdescribe(process.platform !== 'linux')('Minimized state', () => {
+        it('checks normal bounds when minimized', (done) => {
           const bounds = w.getBounds();
           w.once('minimize', () => {
             expectBoundsEqual(w.getNormalBounds(), bounds);
@@ -989,6 +991,7 @@ describe('BrowserWindow module', () => {
           w.minimize();
         });
       });
+
       ifdescribe(process.platform === 'win32')(`Fullscreen state`, () => {
         it(`checks normal bounds when fullscreen'ed`, (done) => {
           const bounds = w.getBounds();
@@ -999,6 +1002,7 @@ describe('BrowserWindow module', () => {
           w.show();
           w.setFullScreen(true);
         });
+
         it(`checks normal bounds when unfullscreen'ed`, (done) => {
           const bounds = w.getBounds();
           w.once('enter-full-screen', () => {
@@ -3403,6 +3407,96 @@ describe('BrowserWindow module', () => {
       });
     });
 
+    describe('visibleOnAllWorkspaces state', () => {
+      it('with properties', () => {
+        it('can be changed', () => {
+          const w = new BrowserWindow({ show: false });
+          expect(w.visibleOnAllWorkspaces).to.be.false();
+          w.visibleOnAllWorkspaces = true;
+          expect(w.visibleOnAllWorkspaces).to.be.true();
+        });
+      });
+
+      it('with functions', () => {
+        it('can be changed', () => {
+          const w = new BrowserWindow({ show: false });
+          expect(w.isVisibleOnAllWorkspaces()).to.be.false();
+          w.setVisibleOnAllWorkspaces(true);
+          expect(w.isVisibleOnAllWorkspaces()).to.be.true();
+        });
+      });
+    });
+
+    ifdescribe(process.platform === 'darwin')('documentEdited state', () => {
+      it('with properties', () => {
+        it('can be changed', () => {
+          const w = new BrowserWindow({ show: false });
+          expect(w.documentEdited).to.be.false();
+          w.documentEdited = true;
+          expect(w.documentEdited).to.be.true();
+        });
+      });
+
+      it('with functions', () => {
+        it('can be changed', () => {
+          const w = new BrowserWindow({ show: false });
+          expect(w.isDocumentEdited()).to.be.false();
+          w.setDocumentEdited(true);
+          expect(w.isDocumentEdited()).to.be.true();
+        });
+      });
+    });
+
+    ifdescribe(process.platform === 'darwin')('representedFilename', () => {
+      it('with properties', () => {
+        it('can be changed', () => {
+          const w = new BrowserWindow({ show: false });
+          expect(w.representedFilename).to.eql('');
+          w.representedFilename = 'a name';
+          expect(w.representedFilename).to.eql('a name');
+        });
+      });
+
+      it('with functions', () => {
+        it('can be changed', () => {
+          const w = new BrowserWindow({ show: false });
+          expect(w.getRepresentedFilename()).to.eql('');
+          w.setRepresentedFilename('a name');
+          expect(w.getRepresentedFilename()).to.eql('a name');
+        });
+      });
+    });
+
+    describe('native window title', () => {
+      it('with properties', () => {
+        it('can be set with title constructor option', () => {
+          const w = new BrowserWindow({ show: false, title: 'mYtItLe' });
+          expect(w.title).to.eql('mYtItLe');
+        });
+
+        it('can be changed', () => {
+          const w = new BrowserWindow({ show: false });
+          expect(w.title).to.eql('Electron Test Main');
+          w.title = 'NEW TITLE';
+          expect(w.title).to.eql('NEW TITLE');
+        });
+      });
+
+      it('with functions', () => {
+        it('can be set with minimizable constructor option', () => {
+          const w = new BrowserWindow({ show: false, title: 'mYtItLe' });
+          expect(w.getTitle()).to.eql('mYtItLe');
+        });
+
+        it('can be changed', () => {
+          const w = new BrowserWindow({ show: false });
+          expect(w.getTitle()).to.eql('Electron Test Main');
+          w.setTitle('NEW TITLE');
+          expect(w.getTitle()).to.eql('NEW TITLE');
+        });
+      });
+    });
+
     describe('minimizable state', () => {
       it('with properties', () => {
         it('can be set with minimizable constructor option', () => {
@@ -3535,23 +3629,31 @@ describe('BrowserWindow module', () => {
       });
     });
 
-    ifdescribe(process.platform === 'darwin')('fullscreenable state', () => {
-      it('with properties', () => {
-        it('can be set with fullscreenable constructor option', () => {
-          const w = new BrowserWindow({ show: false, fullscreenable: false });
-          expect(w.fullScreenable).to.be.false('fullScreenable');
+    ifdescribe(process.platform !== 'darwin')('menuBarVisible state', () => {
+      describe('with properties', () => {
+        it('can be changed', () => {
+          const w = new BrowserWindow({ show: false });
+          expect(w.menuBarVisible).to.be.true();
+          w.menuBarVisible = false;
+          expect(w.menuBarVisible).to.be.false();
+          w.menuBarVisible = true;
+          expect(w.menuBarVisible).to.be.true();
         });
+      });
 
+      describe('with functions', () => {
         it('can be changed', () => {
           const w = new BrowserWindow({ show: false });
-          expect(w.fullScreenable).to.be.true('fullScreenable');
-          w.fullScreenable = false;
-          expect(w.fullScreenable).to.be.false('fullScreenable');
-          w.fullScreenable = true;
-          expect(w.fullScreenable).to.be.true('fullScreenable');
+          expect(w.isMenuBarVisible()).to.be.true('isMenuBarVisible');
+          w.setMenuBarVisibility(false);
+          expect(w.isMenuBarVisible()).to.be.false('isMenuBarVisible');
+          w.setMenuBarVisibility(true);
+          expect(w.isMenuBarVisible()).to.be.true('isMenuBarVisible');
         });
       });
+    });
 
+    ifdescribe(process.platform === 'darwin')('fullscreenable state', () => {
       it('with functions', () => {
         it('can be set with fullscreenable constructor option', () => {
           const w = new BrowserWindow({ show: false, fullscreenable: false });
@@ -3573,18 +3675,46 @@ describe('BrowserWindow module', () => {
     const tick = () => new Promise(resolve => setTimeout(resolve));
 
     ifdescribe(process.platform === 'darwin')('kiosk state', () => {
-      it('can be changed with setKiosk method', (done) => {
-        const w = new BrowserWindow();
-        w.once('enter-full-screen', async () => {
-          await tick();
-          w.setKiosk(false);
-          expect(w.isKiosk()).to.be.false('isKiosk');
+      it('with properties', () => {
+        it('can be set with a constructor property', () => {
+          const w = new BrowserWindow({ kiosk: true });
+          expect(w.kiosk).to.be.true();
         });
-        w.once('leave-full-screen', () => {
-          done();
+
+        it('can be changed ', (done) => {
+          const w = new BrowserWindow();
+          w.once('enter-full-screen', async () => {
+            await tick();
+            w.kiosk = false;
+            expect(w.kiosk).to.be.false();
+          });
+          w.once('leave-full-screen', () => {
+            done();
+          });
+          w.kiosk = true;
+          expect(w.kiosk).to.be.true();
+        });
+      });
+
+      it('with functions', () => {
+        it('can be set with a constructor property', () => {
+          const w = new BrowserWindow({ kiosk: true });
+          expect(w.isKiosk()).to.be.true();
+        });
+
+        it('can be changed ', (done) => {
+          const w = new BrowserWindow();
+          w.once('enter-full-screen', async () => {
+            await tick();
+            w.setKiosk(false);
+            expect(w.isKiosk()).to.be.false('isKiosk');
+          });
+          w.once('leave-full-screen', () => {
+            done();
+          });
+          w.setKiosk(true);
+          expect(w.isKiosk()).to.be.true('isKiosk');
         });
-        w.setKiosk(true);
-        expect(w.isKiosk()).to.be.true('isKiosk');
       });
     });
 
@@ -3619,7 +3749,7 @@ describe('BrowserWindow module', () => {
         w.setFullScreen(true);
       });
 
-      it('does not crash when exiting simpleFullScreen', (done) => {
+      it('does not crash when exiting simpleFullScreen (properties)', (done) => {
         const w = new BrowserWindow();
         w.setSimpleFullScreen(true);
 
@@ -3629,6 +3759,16 @@ describe('BrowserWindow module', () => {
         }, 1000);
       });
 
+      it('does not crash when exiting simpleFullScreen (functions)', (done) => {
+        const w = new BrowserWindow();
+        w.simpleFullScreen = true;
+
+        setTimeout(() => {
+          w.setFullScreen(!w.isFullScreen());
+          done();
+        }, 1000);
+      });
+
       it('should not be changed by setKiosk method', (done) => {
         const w = new BrowserWindow();
         w.once('enter-full-screen', async () => {
@@ -3683,27 +3823,53 @@ describe('BrowserWindow module', () => {
     });
 
     describe('hasShadow state', () => {
-      it('returns a boolean on all platforms', () => {
-        const w = new BrowserWindow({ show: false });
-        const hasShadow = w.hasShadow();
-        expect(hasShadow).to.be.a('boolean');
-      });
+      it('with properties', () => {
+        it('returns a boolean on all platforms', () => {
+          const w = new BrowserWindow({ show: false });
+          expect(w.shadow).to.be.a('boolean');
+        });
+
+        // On Windows there's no shadow by default & it can't be changed dynamically.
+        it('can be changed with hasShadow option', () => {
+          const hasShadow = process.platform !== 'darwin';
+          const w = new BrowserWindow({ show: false, hasShadow });
+          expect(w.shadow).to.equal(hasShadow);
+        });
 
-      // On Windows there's no shadow by default & it can't be changed dynamically.
-      it('can be changed with hasShadow option', () => {
-        const hasShadow = process.platform !== 'darwin';
-        const w = new BrowserWindow({ show: false, hasShadow });
-        expect(w.hasShadow()).to.equal(hasShadow);
+        it('can be changed with setHasShadow method', () => {
+          const w = new BrowserWindow({ show: false });
+          w.shadow = false;
+          expect(w.shadow).to.be.false('hasShadow');
+          w.shadow = true;
+          expect(w.shadow).to.be.true('hasShadow');
+          w.shadow = false;
+          expect(w.shadow).to.be.false('hasShadow');
+        });
       });
 
-      it('can be changed with setHasShadow method', () => {
-        const w = new BrowserWindow({ show: false });
-        w.setHasShadow(false);
-        expect(w.hasShadow()).to.be.false('hasShadow');
-        w.setHasShadow(true);
-        expect(w.hasShadow()).to.be.true('hasShadow');
-        w.setHasShadow(false);
-        expect(w.hasShadow()).to.be.false('hasShadow');
+      describe('with functions', () => {
+        it('returns a boolean on all platforms', () => {
+          const w = new BrowserWindow({ show: false });
+          const hasShadow = w.hasShadow();
+          expect(hasShadow).to.be.a('boolean');
+        });
+
+        // On Windows there's no shadow by default & it can't be changed dynamically.
+        it('can be changed with hasShadow option', () => {
+          const hasShadow = process.platform !== 'darwin';
+          const w = new BrowserWindow({ show: false, hasShadow });
+          expect(w.hasShadow()).to.equal(hasShadow);
+        });
+
+        it('can be changed with setHasShadow method', () => {
+          const w = new BrowserWindow({ show: false });
+          w.setHasShadow(false);
+          expect(w.hasShadow()).to.be.false('hasShadow');
+          w.setHasShadow(true);
+          expect(w.hasShadow()).to.be.true('hasShadow');
+          w.setHasShadow(false);
+          expect(w.hasShadow()).to.be.false('hasShadow');
+        });
       });
     });
   });