Window

---

Window is a wrapper of the DOM’s topmost window object. It has extended operations and can receive various window events.

Every Window is an instance of the EventEmitter class, and you’re able to use Window.on(...) to respond to native window’s events.

Synopsis

// Get the current window
var win = nw.Window.get();

// Listen to the minimize event
win.on('minimize', function() {
  console.log('Window is minimized');
});

// Minimize the window
win.minimize();

// Unlisten the minimize event
win.removeAllListeners('minimize');

// Create a new window and get it
nw.Window.open('https://github.com', {}, function(new_win) {
  // And listen to new window's focus event
  new_win.on('focus', function() {
    console.log('New window is focused');
  });

});

Window.get([window_object])

• window_object {DOM Window} Optional is the DOM window
• Returns {Window} the native Window object

If window_object is not specifed, then return current window’s Window object, otherwise return window_object‘s Window object.

// Get the current window
var win = nw.Window.get();

// Get iframe's window
var iframeWin = nw.Window.get(iframe.contentWindow);

//This will return true
console.log(iframeWin === win);

// Create a new window and get it
nw.Window.open('https://github.com/nwjs/nw.js', {}, function(new_win) {
  // do something with the newly created window
});

Window.open(url, [options], [callback])

• url {String} URL to be loaded in the opened window
• options {Object} Optional see Window subfields in manifest format. And following extra fields can also be used in options.
  • new_instance {Boolean} Optional whether to open a new window in a separate render process.
  • inject_js_start {String} Optional the script to be injected before document loaded. See Manifest format
  • inject_js_end {String} Optional the script to be injected before document unloaded. See Manifest format
  • id {String} Optional the id used to identify the window. This will be used to remember the size and position of the window and restore that geometry when a window with the same id is later opened. See also the Chrome App documentation
• callback(win) {Function} Optional callback when with the opened native Window object

Open a new window and load url in it.

win.window

Get the corresponding DOM window object of the native window.

win.x

win.y

Get or set left/top offset from window to screen.

win.width

win.height

Get or set window’s size.

win.title

Get or set window’s title.

win.menu

Get or set window’s menubar. Set with a Menu with type menubar. When win.menu is set to null, the menubar is completely removed for Windows and Linux, and the menubar is cleared out on Mac.

See Customize Menubar for the usage of menubars. And see Menu and MenuItem for detailed APIs.

win.isAlwaysOnTop

Get whether the window is always on top of other windows.

win.isFullscreen

Get whether we’re in fullscreen mode.

win.isTransparent

Get whether transparency is turned on

win.isKioskMode

Get whether we’re in kiosk mode.

win.zoomLevel

Get or set the page zoom. 0 for normal size; positive value for zooming in; negative value for zooming out.

win.cookies.*

This includes multiple functions to manipulate the cookies. The API is defined in the same way as Chrome Extensions. NW.js supports the get, getAll, remove and set methods; onChanged event (supporting both addListener and removeListener function on this event).

And anything related to CookieStore in the Chrome extension API is not supported, because there is only one global cookie store in NW.js apps.

win.moveTo(x, y)

• x {Integer} offset to the left of the screen
• y {Integer} offset to the top of the screen

Moves a window’s left and top edge to the specified coordinates.

win.moveBy(x, y)

• x {Integer} horizontal offset
• y {Integer} vertical offset

Moves a window a specified number of pixels relative to its current coordinates.

win.resizeTo(width, height)

• width {Integer} the width of the window
• height {Integer} the height of the window

Resizes a window to the specified width and height.

win.resizeBy(width, height)

• width {Integer} the offset width of the window
• height {Integer} the offset height of the window

Resizes a window by the specified amount.

win.focus()

Focus on the window.

win.blur()

Move focus away. Usually it will move focus to other windows of your app, since on some platforms there is no concept of blur.

win.show([is_show])

• is_show {Boolean} Optional specify whether the window should be shown or hidden. It’s set to true by default.

Show the window if it’s not shown.

show(false) has the same effect with hide().

win.hide()

Hide the window. User will not be able to find the window once it’s hidden.

win.close([force])

• force {Boolean} specify whether to close the window forcely and bypass close event.

Close current window. And you can prevent the closing by listening to the close event. If force is specified and equals to true, then the close event will be ignored.

Usually you would like to listen to the close event and do some shutdown work and then do a close(true) to really close the window.

win.on('close', function() {
  this.hide(); // Pretend to be closed already
  console.log("We're closing...");
  this.close(true); // then close it forcely
});

win.close();

win.reload()

Reloads the current window.

win.reloadDev()

Reloads the current page by starting a new renderer process from scratch.

win.reloadIgnoringCache()

Like reload(), but don’t use caches (aka “shift-reload”).

win.maximize()

Maximize the window on GTK and Windows, and zoom the window on Mac OS X.

win.unmaximize()

Unmaximize the window, i.e. the reverse of maximize().

win.minimize()

Minimize the window to task bar on Windows, iconify the window on GTK, and miniaturize the window on Mac OS X.

win.restore()

Restore window to previous state after the window is minimized, i.e. the reverse of minimize(). It’s not named unminimize since restore is used commonly.

win.enterFullscreen()

Make the window fullscreen.

win.leaveFullscreen()

Leave the fullscreen mode.

win.toggleFullscreen()

Toggle the fullscreen mode.

win.enterKioskMode()

Enter the Kiosk mode. In Kiosk mode, the app will be fullscreen and try to prevent users from leaving the app, so you should remember to provide a way in app to leave Kiosk mode. This mode is mainly used for presentation on public displays.

win.leaveKioskMode()

Leave the Kiosk mode.

win.toggleKioskMode()

Toggle the kiosk mode.

win.setTransparent(transparent)

• transparent {Boolean} whether to set the window to be transparent

Turn on/off the transparency support. See more info on Transparent Window.

win.setShadow(shadow) (Mac)

• shadow {Boolean} whether the window has a shadow

Turn the window’s native shadow on/off. Useful for frameless, transparent windows.

win.showDevTools([iframe], [callback])

• iframe {String} or {HTMLIFrameElement} Optional the id or the element of the <iframe> to be jailed on. By default, the DevTools is shown for entire window.
• callback(dev_win) {Function} callback with the native window of the DevTools window.

Open the devtools to inspect the window.

The optional iframe as String should be the value of id attribute of any <iframe> element in the window. It jails the DevTools to inspect the <iframe> only. If it is an empty string, this feature has no effect.

The optional iframe as HTMLIFrameElement should be the iframe object. And it serves the same purpose with the id argument.

This function returns a Window object via the callback. You can use any properties and methods of Window except the events.

See also in webview reference on how to open DevTools for webview or open DevTools in a webview.

win.closeDevTools()

Close the devtools window.

win.getPrinters(callback)

Enumerate the printers in the system. The callback function will receive an array of JSON objects for the printer information. The device name of the JSON object can be used as parameter in nw.Window.print().

win.isDevToolsOpen()

Query the status of devtools window.

See also win.showDevTools().

win.print(options)

Print the web contents in the window with or without the need for user’s interaction. options is a JSON object with the following fields:

• autoprint {Boolean} whether to print without the need for user’s interaction; optional, true by default
• printer {String} the device name of the printer returned by nw.Window.getPrinters(); No need to set this when printing to PDF
• pdf_path {String} the path of the output PDF when printing to PDF
• headerFooterEnabled {Boolean} whether to enable header and footer
• landscape {Boolean} whether to use landscape or portrait
• mediaSize {JSON Object} the paper size spec
• shouldPrintBackgrounds {Boolean} whether to print CSS backgrounds
• marginsType {Integer} 0 - Default; 1 - No margins; 2 - minimum; 3 - Custom, see marginsCustom.
• marginsCustom {JSON Object} the custom margin setting; units are points.
• copies {Integer} the number of copies to print.
• scaleFactor {Integer} the scale factor; 100 is the default.
• headerString {String} string to replace the URL in the header.
• footerString {String} string to replace the URL in the footer.

marginsCustom example: "marginsCustom":{"marginBottom":54,"marginLeft":70,"marginRight":28,"marginTop":32}
mediaSize example: 'mediaSize':{'name': 'CUSTOM', 'width_microns': 279400, 'height_microns': 215900, 'custom_display_name':'Letter', 'is_default': true}

NOTE: If no options are being passed, win.print({}) is what should be called.

win.setMaximumSize(width, height)

• width {Integer} the maximum width of the window
• height {Integer} the maximum height of the window

Set window’s maximum size.

win.setMinimumSize(width, height)

• width {Integer} the minimum width of the window
• height {Integer} the minimum height of the window

Set window’s minimum size.

win.setResizable(resizable)

• resizable {Boolean} whether the window can be resized

Set whether window is resizable.

win.setAlwaysOnTop(top)

• top {Boolean} whether the window should always be on top

Sets the widget to be on top of all other windows in the window system.

win.setVisibleOnAllWorkspaces(visible) (Mac and Linux)

• visible {Boolean} whether the window should be visible on all workspaces

For platforms that support multiple workspaces (currently Mac OS X and Linux), this allows NW.js windows to be visible on all workspaces simultaneously.

win.canSetVisibleOnAllWorkspaces() (Mac and Linux)

Returns a a boolean indicating if the platform (currently Mac OS X and Linux) support Window API method setVisibleOnAllWorkspace(Boolean).

win.setPosition(position)

• position {String} the position of the window. There are three valid positions: null or center or mouse

Move window to specified position. Currently only center is supported on all platforms, which will put window in the middle of the screen.

win.setShowInTaskbar(show)

• show {Boolean} whether show in task bar

Control whether to show window in taskbar or dock. See also show_in_taskbar in Manifest-format.

win.requestAttention(attension)

• attension {Boolean} or {Integer} If a Boolean, it indicates to request or cancel user’s attension. If an Integer, it indicates the number of times the window flashes.

Request the user’s attension by making the window flashes in the task bar.

win.capturePage(callback [, config ])

• callback {Function} the callback when finished capturing the window
• config {String} or {Object} Optional if a String, see config.format for valid values.
  • format {String} optional the image format used to generate the image. It supports two formats: "png" and "jpeg". If ignored, it’s "jpeg" by default.
  • datatype {String} it supports three types: "raw", "buffer" and "datauri". If ignored, it’s "datauri" by default.

Captures the visible area of the window.

Example usage:

// png as base64string
win.capturePage(function(base64string){
 // do something with the base64string
}, { format : 'png', datatype : 'raw'} );

// png as node buffer
win.capturePage(function(buffer){
 // do something with the buffer
}, { format : 'png', datatype : 'buffer'} );

win.setProgressBar(progress)

• progress {Float} valid values within [0, 1]. Setting to negative value (<0) removes the progress bar.

win.setBadgeLabel(label)

Set the badge label on the window icon in taskbar or dock.

win.eval(frame, script)

• frame {HTMLIFrameElement} the frame to execute in. If iframe is null, it assumes in current window / frame.
• script {String} the source code of the script to be executed

Execute a piece of JavaScript in the frame.

win.evalNWBin(frame, path)

• frame {HTMLIFrameElement} the frame to execute in. If iframe is null, it assumes in current window / frame.
• path {String|ArrayBuffer|Buffer} the path or Buffer or ArrayBuffer of the binary file generated by nwjc

Load and execute the compiled binary in the frame. See Protect JavaScript Source Code.

win.evalNWBinModule(frame, path, module_path)

• frame {HTMLIFrameElement} the frame to execute in. If iframe is null, it assumes in current window / frame.
• path {String|ArrayBuffer|Buffer} the path or Buffer or ArrayBuffer of the binary file generated by nwjc
• module_path {String} the module URL related to the current document. It will be used to resolve the module specifier.

Load and execute the compiled binary for Modules in the frame. The binary should be compiled with nwjc --nw-module. The following code will load lib.bin as module and other modules can refer to it with something like import * from './lib.js':

nw.Window.get().evalNWBinModule(null, 'lib.bin', 'lib.js');

win.removeAllListeners([eventName])

Removes all listeners, or those of the specified eventName.

Event: close

The close event is a special event that will affect the result of the Window.close() function. If developer is listening to the close event of a window, the Window.close() emit the close event without closing the window.

Usually you would do some shutdown work in the callback of close event, and then call this.close(true) to really close the window, which will not be caught again. Forgetting to add true when calling this.close() in the callback will result in infinite loop.

And if the shutdown work takes some time, users may feel that the app is exiting slowly, which is bad experience, so you could just hide the window in the close event before really closing it to make a smooth user experience.

See example code of win.close(true) above for the usage of close event.

Event: closed

The closed event is emitted after the corresponding window is closed. Normally you will not be able to get this event since after the window is closed all js objects will be released. But it is useful when listening to the window’s events in another window, whose objects will not be released.

// Open a new window.
nw.Window.open('popup.html', {}, function (win) {
  // Release the 'win' object here after the new window is closed.
  win.on('closed', function () {
    win = null;
  });

  // Listen to main window's close event
  nw.Window.get().on('close', function () {
    // Hide the window to give user the feeling of closing immediately
    this.hide();

    // If the new window is still open then close it.
    if (win !== null) {
      win.close(true);
    }

    // After closing the new window, close the main window.
    this.close(true);
  });
});

Event: loading

Emitted when the window starts to reload, normally you cannot catch this event because usually it’s emitted before you actually setup the callback.

The only situation that you can catch this event is when you refresh the window and listen to this event in another window.

Event: loaded

Emitted when the window is fully loaded, this event behaves the same with window.onload, but doesn’t rely on the DOM.

Event: document-start(frame)

• frame {HTMLIFrameElement} is the iframe object, or null if the event is for the window.

Emitted when the document object in this window or a child iframe is available, after all files are loaded, but before DOM is constructed or any script is run.
It will not be fired on the new window being created with nw.Window.open(): the callback of that function will be fired at the same point of this event.

See inject_js_start in Manifest-format.

Event: document-end(frame)

• frame {HTMLIFrameElement} is the iframe object, or null if the event is for the window.

Emitted when the document object in this window or a child iframe is unloaded, but before the onunload event is emitted.

See inject_js_end in Manifest-format

Event: focus

Emitted when window gets focus.

Event: blur

Emitted when window loses focus.

Event: minimize

Emitted when window is minimized.

Event: restore

Emitted when window is restored from minimize, maximize and fullscreen state.

Event: maximize

Emitted when window is maximized.

Event: move(x, y)

Emitted after window is moved. The callback is called with 2 arguments: (x, y) for the new location of the left / top corner of the window.

Event: resize(width, height)

Emitted after window is resized. The callback is called with 2 arguments: (width, height) for the new size of the window.

Event: enter-fullscreen

Emitted when window enters fullscreen state.

Event: leave-fullscreen

Emitted when window leaves fullscreen state.

Event: zoom

Emitted when window zooming changed. It has a parameter indicating the new zoom level. See win.zoom() method for the parameter’s value definition.

Event: capturepagedone

Emitted after the capturePage method is called and image data is ready. See win.capturePage() callback function for the parameter’s value definition.

Event: devtools-opened(url)

See win.showDevTools() method for more details.

Event: devtools-closed

Emitted after Devtools is closed.

See win.closeDevTools() method for more details.

Event: new-win-policy (frame, url, policy)

• frame {HTMLIFrameElement} is the object of the child iframe where the request is from, or null if it’s from the top window.
• url {String} is the address of the requested link
• policy {Object} is an object with the following methods:
  • ignore() : ignore the request, navigation won’t happen.
  • forceCurrent() : force the link to be opened in the same frame
  • forceDownload() : force the link to be a downloadable, or open by external program
  • forceNewWindow() : force the link to be opened in a new window
  • forceNewPopup() : force the link to be opened in a new popup window
  • setNewWindowManifest(m) : control the options for the new popup window. The object m is in the same format as the Window subfields in manifest format.

Emitted when a new window is requested from this window or a child iframe. You can call policy.* methods in the callback to change the default behavior of opening new windows.

For example, you can open the URL in system brower when user tries to open in a new window:

nw.Window.get().on('new-win-policy', function(frame, url, policy) {
  // do not open the window
  policy.ignore();
  // and open it in external browser
  nw.Shell.openExternal(url);
});

Event: navigation (frame, url, policy)

• frame {HTMLIFrameElement} is the object of the child iframe where the request is from, or null if it’s from the top window.
• url {String} is the address of the requested link
• policy {Object} is an object with the following methods:
  • ignore() : ignore the request, navigation won’t happen.

Emitted when navigating to another page. Similar to new-win-policy, you can call policy.ignore() within the callback to ignore the navigation.