Window - Hosting-Site/node-webkit GitHub Wiki

Window API requires node-webkit >= v0.3.0

Window is a wrapper of DOM's window object, it has extended operations and can receive various window events.

Every Window is an instance of EventEmitter object, and you're able to use Window.on(...) to response to native window's events.

// Load native UI library
var gui = require('nw.gui'); //or global.window.nwDispatcher.requireNwGui() (see https://github.com/rogerwang/node-webkit/issues/707)

// Get the current window
var win = gui.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
var new_win = gui.Window.get(
  window.open('https://github.com')
);

// And listen to new window's focus event
new_win.on('focus', function() {
  console.log('New window is focused');
});

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 = gui.Window.get();

// Create a new window and get it
var new_win = gui.Window.get(
  window.open('https://github.com')
);

Open a new window and load url in it, you can specify extra options with the window. All window subfields in Manifest format can be used. Since v0.4.0, a boolean field new-instance can be used to start a new Node instance (webkit process). Since v0.9.0 and 0.8.5, inject-js-start and inject-js-end field can be used to inject a javascript file, see Manifest format .

Since v0.7.3 the opened window is not focused by default. It's a result of unifying behavior across platforms. If you want it to be focused by default, you can set focus to true in options.

var win = gui.Window.open('https://github.com', {
  position: 'center',
  width: 901,
  height: 127
});

Get DOM's window object in the native window.

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

Get or Set window's size.

Get or Set window's title.

Get or Set window's menubar. Set with a Menu with type menubar. See Menu.

since v0.3.5

Get or Set whether we're in fullscreen mode.

since v0.3.5

Get or Set whether we're in kiosk mode.

since v0.4.1

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

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

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

Resizes a window to the specified width and height.

Resizes a window by the specified amount.

Focus on the window.

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

Show the window if it's not showed, show will not focus on the window on some platforms, so you need to call focus if you want to.

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

Hide the window. Users will not be able to find the window if it's hidden.

Close current window, you can catch the close event to prevent the closing. 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);
});

win.close();

Requires node-webkit >= v0.3.5

Reloads the current window.

Requires node-webkit >= v0.3.5

Like reload(), but don't use caches (aka "shift-reload").

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

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

Minimize the window to taskbar on Windows, iconify the window on GTK, and miniaturize the window on Mac.

Restore window to previous state after the window is minimized, e.g. the reverse of minimize(). It's not named unminimize since restore is already used commonly on Window.

Make the window fullscreen. This function is different with HTML5 FullScreen API, which can make part of the page fullscreen, Window.enterFullscreen() will only fullscreen the whole window.

Leave the fullscreen mode.

Requires node-webkit >= v0.3.5

Toggle the fullscreen mode.

Requires node-webkit >= v0.3.1

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.

Requires node-webkit >= v0.3.1

Leave the Kiosk mode.

Requires node-webkit >= v0.3.5

Toggle the kiosk mode.

Open the devtools to inspect the window.

The optional id argument is supported since v0.6.0. It should be the value of id attribute of any iframe element in the window. It can be used to limit the devtools window to inspect only the iframe. If id is empty string, this feature is not effective.

The optional headless argument is supported since v0.6.0. When it is true, the Devtools window will not be opened. Instead, a devtools-opened will be sent to the Window object after Devtools is ready.

The optional iframe argument is supported since v0.7.2. It should be the iframe object. And it serves the same purpose with the id argument.

For more information, please read Devtools Jail Feature.

Since v0.8.1, this function returns a Window object when headless is false, so the devtools Window can be manipulated. Note that the events on this object is not working yet.

since v0.7.3

Close the devtools window.

since v0.8.0

Query the status of devtools window

Set window's maximum size.

Set window's minimum size.

Set whether window is resizable.

Requires node-webkit >= v0.3.4

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

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

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

Pass true to indicate that the window needs user's action, pass false to cancel it. The final behaviour depends on the platform.

since v0.4.2

Captures the visible area of the window. Note: a simple demo usage can be found here: https://gist.github.com/zhchbin/4749217

callback should be a function that will be called when the the image data is ready. It looks like this:

function(dataUrl) {...};

A dataURL(string) which encodes an image of the visible area of the captured window. May be assigned to the 'src' property of an HTML Image element for display.

image_format is enumerated string ["jpeg", "png"]. Default is 'jpeg'.

since v0.9.3

It is now possible to define the datatype of the returned image by using an config_object as the second parameter.

This object should be like:

{ 
 format : "[jpeg|png]", 
 datatype : "[raw|buffer|datauri]" 
}

Where:
format defaults to jpeg
datatype defaults to datauri

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'} );

since v0.8.1

This includes multiple functions to manipulate the cookies. The API is defined in the same way as Chrome Extensions'. node-webkit 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 node-webkit apps.

Since v0.9.0 and v0.8.5
Execute a piece of JavaScript in the window, if frame argument is null, or in the context of an iframe, if frame is an iframe object. The script argument is the content of the JavaScript source code.

Following events can be listened by using Window.on() function, for more information on how to receive events, you can visit EventEmitter.

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() call to that window will not close the window but send the close event.

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.

For use case you can see demo code of Window.close() above.

Since v0.8.4 on OSX, there is a parameter on the callback of this event. Its value will be set to 'quit' if the window is being closed by pressing 'Cmd-Q' (intent to quit application). Otherwise the value is undefined. See https://github.com/rogerwang/node-webkit/issues/430

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

<script>
  var gui = require('nw.gui');

  // Open a new window.
  var win = gui.Window.get(
    window.open('popup.html')
  );

  // Release the 'win' object here after the new window is closed.
  win.on('closed', function() {
    win = null;
  });

  // Listen to main window's close event
  gui.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);
  });
</script>

Requires node-webkit >= v0.3.5

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.

Requires node-webkit >= v0.3.5

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

since v0.9.0 and v0.8.5

function (frame) {}
Emitted when the document object in this window or a child iframe is available, after any files from css, but before any other DOM is constructed or any other script is run;

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

See also: inject-js-start in Manifest-format

since v0.9.0 and v0.8.5

function (frame) {}
Emitted when the document object in this window or a child iframe is loaded, before the onload event is emitted.

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

See also: inject-js-end in Manifest-format

Emitted when window gets focus.

Emitted when window loses focus.

Emitted when window is minimized.

Emitted when window is restored from minimize state.

Emitted when window is maximized.

Emitted when window is restored from maximize state. Note that on some platforms window can be resized even when maximized, so the unmaximize may not be emitted when a maximized window is resized instead of being unmaximized

since v0.8.2
Emitted after window is moved. The callback is called with 2 arguments: (x, y) for the new location of the upper-left corner of the window.

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

Emitted when window enters fullscreen state.

Emitted when window leaves fullscreen state.

Emitted when window zooming changed. It has a parameter indicating the new zoom level. See Window.zoom for the parameter's value definition.

Emitted after the capturePage method is called and image data is ready. See Window.capturePage's callback function for the parameter's value definition.

Emitted after Devtools is opened by any means (since v0.8.0), or ready after calling Window.showDevTools(id, headless) with headless = true. The event callback has an url argument, which is the URL to load Devtools UI. See Devtools jail feature and Window for more information.

since v0.8.0

Emitted after Devtools is closed.

since v0.9.0 and v0.8.5

function (frame, url, policy) {}
Emitted when a new window is requested from this window or a child iframe, e.g. user clicks a link with _blank target.

• frame is the object of the child iframe where the request is from, or null if it's from the top window.
• url is the address of the requested link
• policy 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

Now on linux, the function setMaximumSize()/setMinimumSize() and setResizable() can not be set at the same time. If do so, they all do not work. Please take this into consideration.

• EventEmitter