BaseWindow
Create and control windows.
Process: Main
Note
BaseWindow
provides a flexible way to compose multiple web views in a single window. For windows with only a single, full-size web view, theBrowserWindow
class may be a simpler option.
This module cannot be used until the ready
event of the app
module is emitted.
// In the main process.
const { BaseWindow, WebContentsView } = require('electron')
const win = new BaseWindow({ width: 800, height: 600 })
const leftView = new WebContentsView()
leftView.webContents.loadURL('https://electronjs.org')
win.contentView.addChildView(leftView)
const rightView = new WebContentsView()
rightView.webContents.loadURL('https://github.com/electron/electron')
win.contentView.addChildView(rightView)
leftView.setBounds({ x: 0, y: 0, width: 400, height: 600 })
rightView.setBounds({ x: 400, y: 0, width: 400, height: 600 })
Parent and child windows
By using parent
option, you can create child windows:
const { BaseWindow } = require('electron')
const parent = new BaseWindow()
const child = new BaseWindow({ parent })
The child
window will always show on top of the parent
window.
Modal windows
A modal window is a child window that disables parent window. To create a modal
window, you have to set both the parent
and modal
options:
const { BaseWindow } = require('electron')
const parent = new BaseWindow()
const child = new BaseWindow({ parent, modal: true })
Platform notices
- On macOS modal windows will be displayed as sheets attached to the parent window.
- On macOS the child windows will keep the relative position to parent window when parent window moves, while on Windows and Linux child windows will not move.
- On Linux the type of modal windows will be changed to
dialog
. - On Linux many desktop environments do not support hiding a modal window.
Class: BaseWindow
Create and control windows.
Process: Main
BaseWindow
is an EventEmitter.
It creates a new BaseWindow
with native properties as set by the options
.
new BaseWindow([options])
When setting minimum or maximum window size with minWidth
/maxWidth
/
minHeight
/maxHeight
, it only constrains the users. It won't prevent you from
passing a size that does not follow size constraints to setBounds
/setSize
or
to the constructor of BrowserWindow
.
The possible values and behaviors of the type
option are platform dependent.
Possible values are:
- On Linux, possible types are
desktop
,dock
,toolbar
,splash
,notification
.- The
desktop
type places the window at the desktop background window level (kCGDesktopWindowLevel - 1). However, note that a desktop window will not receive focus, keyboard, or mouse events. You can still use globalShortcut to receive input sparingly. - The
dock
type creates a dock-like window behavior. - The
toolbar
type creates a window with a toolbar appearance. - The
splash
type behaves in a specific way. It is not draggable, even if the CSS styling of the window's body contains -webkit-app-region: drag. This type is commonly used for splash screens. - The
notification
type creates a window that behaves like a system notification.
- The
- On macOS, possible types are
desktop
,textured
,panel
.- The
textured
type adds metal gradient appearance (NSWindowStyleMaskTexturedBackground
). - The
desktop
type places the window at the desktop background window level (kCGDesktopWindowLevel - 1
). Note that desktop window will not receive focus, keyboard or mouse events, but you can useglobalShortcut
to receive input sparingly. - The
panel
type enables the window to float on top of full-screened apps by adding theNSWindowStyleMaskNonactivatingPanel
style mask,normally reserved for NSPanel, at runtime. Also, the window will appear on all spaces (desktops).
- The
- On Windows, possible type is
toolbar
.
Instance Events
Objects created with new BaseWindow
emit the following events:
Note: Some events are only available on specific operating systems and are labeled as such.
Event: 'close'
Returns:
event
Event
Emitted when the window is going to be closed. It's emitted before the
beforeunload
and unload
event of the DOM. Calling event.preventDefault()
will cancel the close.
Usually you would want to use the beforeunload
handler to decide whether the
window should be closed, which will also be called when the window is
reloaded. In Electron, returning any value other than undefined
would cancel the
close. For example:
window.onbeforeunload = (e) => {
console.log('I do not want to be closed')
// Unlike usual browsers that a message box will be prompted to users, returning
// a non-void value will silently cancel the close.
// It is recommended to use the dialog API to let the user confirm closing the
// application.
e.returnValue = false
}
Note: There is a subtle difference between the behaviors of window.onbeforeunload = handler
and window.addEventListener('beforeunload', handler)
. It is recommended to always set the event.returnValue
explicitly, instead of only returning a value, as the former works more consistently within Electron.
Event: 'closed'
Emitted when the window is closed. After you have received this event you should remove the reference to the window and avoid using it any more.
Event: 'session-end' Windows
Emitted when window session is going to end due to force shutdown or machine restart or session log off.
Event: 'blur'
Emitted when the window loses focus.
Event: 'focus'
Emitted when the window gains focus.
Event: 'show'
Emitted when the window is shown.
Event: 'hide'
Emitted when the window is hidden.
Event: 'maximize'
Emitted when window is maximized.
Event: 'unmaximize'
Emitted when the window exits from a maximized state.
Event: 'minimize'
Emitted when the window is minimized.
Event: 'restore'
Emitted when the window is restored from a minimized state.
Event: 'will-resize' macOS Windows
Returns:
event
EventnewBounds
Rectangle - Size the window is being resized to.details
Objectedge
(string) - The edge of the window being dragged for resizing. Can bebottom
,left
,right
,top-left
,top-right
,bottom-left
orbottom-right
.
Emitted before the window is resized. Calling event.preventDefault()
will prevent the window from being resized.
Note that this is only emitted when the window is being resized manually. Resizing the window with setBounds
/setSize
will not emit this event.
The possible values and behaviors of the edge
option are platform dependent. Possible values are:
- On Windows, possible values are
bottom
,top
,left
,right
,top-left
,top-right
,bottom-left
,bottom-right
. - On macOS, possible values are
bottom
andright
.- The value
bottom
is used to denote vertical resizing. - The value
right
is used to denote horizontal resizing.
- The value
Event: 'resize'
Emitted after the window has been resized.
Event: 'resized' macOS Windows
Emitted once when the window has finished being resized.
This is usually emitted when the window has been resized manually. On macOS, resizing the window with setBounds
/setSize
and setting the animate
parameter to true
will also emit this event once resizing has finished.
Event: 'will-move' macOS Windows
Returns:
event
EventnewBounds
Rectangle - Location the window is being moved to.
Emitted before the window is moved. On Windows, calling event.preventDefault()
will prevent the window from being moved.
Note that this is only emitted when the window is being moved manually. Moving the window with setPosition
/setBounds
/center
will not emit this event.
Event: 'move'
Emitted when the window is being moved to a new position.
Event: 'moved' macOS Windows
Emitted once when the window is moved to a new position.
Note: On macOS this event is an alias of move
.
Event: 'enter-full-screen'
Emitted when the window enters a full-screen state.
Event: 'leave-full-screen'
Emitted when the window leaves a full-screen state.
Event: 'always-on-top-changed'
Returns:
event
EventisAlwaysOnTop
boolean
Emitted when the window is set or unset to show always on top of other windows.
Event: 'app-command' Windows Linux
Returns:
event
Eventcommand
string
Emitted when an App Command is invoked. These are typically related to keyboard media keys or browser commands, as well as the "Back" button built into some mice on Windows.
Commands are lowercased, underscores are replaced with hyphens, and the
APPCOMMAND_
prefix is stripped off.
e.g. APPCOMMAND_BROWSER_BACKWARD
is emitted as browser-backward
.
const { BaseWindow } = require('electron')
const win = new BaseWindow()
win.on('app-command', (e, cmd) => {
// Navigate the window back when the user hits their mouse back button
if (cmd === 'browser-backward') {
// Find the appropriate WebContents to navigate.
}
})
The following app commands are explicitly supported on Linux:
browser-backward
browser-forward
Event: 'swipe' macOS
Returns:
event
Eventdirection
string
Emitted on 3-finger swipe. Possible directions are up
, right
, down
, left
.
The method underlying this event is built to handle older macOS-style trackpad swiping,
where the content on the screen doesn't move with the swipe. Most macOS trackpads are not
configured to allow this kind of swiping anymore, so in order for it to emit properly the
'Swipe between pages' preference in System Preferences > Trackpad > More Gestures
must be
set to 'Swipe with two or three fingers'.
Event: 'rotate-gesture' macOS
Returns:
event
Eventrotation
Float
Emitted on trackpad rotation gesture. Continually emitted until rotation gesture is
ended. The rotation
value on each emission is the angle in degrees rotated since
the last emission. The last emitted event upon a rotation gesture will always be of
value 0
. Counter-clockwise rotation values are positive, while clockwise ones are
negative.
Event: 'sheet-begin' macOS
Emitted when the window opens a sheet.
Event: 'sheet-end' macOS
Emitted when the window has closed a sheet.
Event: 'new-window-for-tab' macOS
Emitted when the native new tab button is clicked.
Event: 'system-context-menu' Windows
Returns:
event
Eventpoint
Point - The screen coordinates the context menu was triggered at
Emitted when the system context menu is triggered on the window, this is
normally only triggered when the user right clicks on the non-client area
of your window. This is the window titlebar or any area you have declared
as -webkit-app-region: drag
in a frameless window.
Calling event.preventDefault()
will prevent the menu from being displayed.
Static Methods
The BaseWindow
class has the following static methods:
BaseWindow.getAllWindows()
Returns BaseWindow[]
- An array of all opened browser windows.
BaseWindow.getFocusedWindow()
Returns BaseWindow | null
- The window that is focused in this application, otherwise returns null
.
BaseWindow.fromId(id)
id
Integer
Returns BaseWindow | null
- The window with the given id
.
Instance Properties
Objects created with new BaseWindow
have the following properties:
const { BaseWindow } = require('electron')
// In this example `win` is our instance
const win = new BaseWindow({ width: 800, height: 600 })
win.id
Readonly
A Integer
property representing the unique ID of the window. Each ID is unique among all BaseWindow
instances of the entire Electron application.
win.contentView
A View
property for the content view of the window.
win.tabbingIdentifier
macOS Readonly
A string
(optional) property that is equal to the tabbingIdentifier
passed to the BrowserWindow
constructor or undefined
if none was set.
win.autoHideMenuBar
A boolean
property that determines whether the window menu bar should hide itself automatically. Once set, the menu bar will only show when users press the single Alt
key.
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.fullScreen
A boolean
property that determines whether the window is in fullscreen mode.
win.focusable
Windows macOS
A boolean
property that determines whether the window is focusable.
win.visibleOnAllWorkspaces
macOS Linux
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
.