Skip to content
Cong Liu edited this page Mar 30, 2016 · 13 revisions

NOTE: some content in this wiki applies only to 0.12 and earlier versions. For official documentation on 0.13 and later, see

Screen API requires node-webkit >= v0.10.2

Screen is an instance of EventEmitter object, and you're able to use Screen.on(...) to respond to native screen's events.

Screen is a singleton object, need to be initiated once by calling gui.Screen.Init()



Init the Screen singleton object, you only need to call this once


Get the array of screen (number of screen connected to the computer)

screen has following structure:

screen {
// unique id for a screen
  id: int,

// physical screen resolution, can be negative, not necessarily start from 0,depending on screen arrangement
  bounds: {
    x: int,
    y: int,
    width: int,
    height: int
// useable area within the screen bound
  work_area: {
    x: int,
    y: int,
    width: int,
    height: int

  scaleFactor: float,
  isBuiltIn: bool,
  rotation: int,
  touchSupport: int

Screen.chooseDesktopMedia (array of DesktopCaptureSourceType sources, function callback)

Screen.chooseDesktopMedia requires nwjs >= v0.12.0
Screen sharing by selection; Currently only working in Windows and OSX and some linux distribution.

DesktopCaptureSourceType: "window" or "screen"
The callback parameter should be a function that looks like this: function(string streamId) {...};
returns false if the function fails to execute or existing chooseDesktopMedia is still active


var gui = require('nw.gui');
gui.Screen.Init(); // you only need to call this once
  function(streamId) {
    var vid_constraint = {
      mandatory: {
        chromeMediaSource: 'desktop', 
        chromeMediaSourceId: streamId, 
        maxWidth: 1920, 
        maxHeight: 1080
      optional: []
    navigator.webkitGetUserMedia({audio: false, video: vid_constraint}, success_func, fallback_func);

More info:


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


emitted when the screen resolution, arrangement is changed, the callback is called with 1 argument `screen'


emitted when a new screen added, the callback is called with 1 argument `screen'


emitted when existing screen removed, the callback is called with 1 argument `screen'


function ScreenToString(screen) {
  var string = "";
  string += "screen " + + " ";
  var rect = screen.bounds;
  string += "bound{" + rect.x + ", " + rect.y + ", " + rect.width + ", " + rect.height + "} ";
  rect = screen.work_area;
  string += "work_area{" + rect.x + ", " + rect.y + ", " + rect.width + ", " + rect.height + "} ";
  string += " scaleFactor: " + screen.scaleFactor;
  string += " isBuiltIn: " + screen.isBuiltIn;
  string += "<br>";
  return string;

//init must be called once during startup, before any function to gui.Screen can be called
var string = "";
var screens = gui.Screen.screens;
// store all the screen information into string
for (var i=0; i<screens.length; i++) {
  string += ScreenToString(screens[i]);

var screenCB = {
  onDisplayBoundsChanged: function(screen) {
    var out = "OnDisplayBoundsChanged " + ScreenToString(screen);

  onDisplayAdded: function(screen) {
    var out = "OnDisplayAdded " + ScreenToString(screen);

  onDisplayRemoved: function(screen) {
    var out = "OnDisplayRemoved " + ScreenToString(screen);

// listen to screen events
gui.Screen.on('displayBoundsChanged', screenCB.onDisplayBoundsChanged);
gui.Screen.on('displayAdded', screenCB.onDisplayAdded);
gui.Screen.on('displayRemoved', screenCB.onDisplayRemoved);


Screen.DesktopCaptureMonitor requires nwjs >= v0.12.3

Screen.DesktopCaptureMonitor.start(should_include_screens, should_include_windows)

The DesktopCaptureMonitor will start monitoring the system and trigger the below events. The screen may flicker if while DesktopCaptureMonitor is running.


Boolean of whether the DesktopCaptureMonitor is started.


The DesktopCaptureMonitor will stop monitoring the system. The screen may flicker while DesktopCaptureMonitor is running. The id provided can be passed into chromeMediaSourceId in getUserMedia constraints. DesktopCaptureMonitor should be stopped after a stream is selected.


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

added (id, name, order, type, primary)

A new source was added.
id is unique id that can be passed as chromeMediaSourceId
name is the title of the window or screen
order is the z-order of the windows, if screens are selected they will appear first
type of the stream: "screen", "window", "other" or "unknown"
primary on Windows OS only, this will be true if the source is the primary monitor

removed (id)

A source was removed.
id is the chromeMediaSourceId of the screen or monitor that is no longer capturable

orderchanged (id, new_order, old_order)

The Z-order of a source changed (this may change for windows as others are focused).
id is the chromeMediaSourceId of the screen or window that has changed z-order
new_order is the new z-order
old_order is the old z-order

namechanged (id, name)

The name of the source has changed. This can happen when a window changes title.
id is the chromeMediaSourceId of the screen or window that has a name changed
name is the new new name of the screen or window

thumbnailchanged (id, thumbnail)

The thumbnail of a source changed.
id is the chromeMediaSourceId of the screen or window that has an updated thumbnail
thumbnail is the base64 encoded png of the thumbnail


gui.Screen.DesktopCaptureMonitor.on("added", function (id, name, order, type) {
   //select first stream and shutdown
   var constraints = {
      audio: { //Note: Audio desktop capture only supported in Chromium in WindowsOS 
         mandatory: {
             chromeMediaSource: "system",
             chromeMediaSourceId: id
      video: {
         mandatory: {
             chromeMediaSource: 'desktop',
             chromeMediaSourceId: id,

  // TODO: call getUserMedia with contraints


gui.Screen.DesktopCaptureMonitor.on("removed", function (id) { });
gui.Screen.DesktopCaptureMonitor.on("orderchanged", function (id, new_order, old_order) { });
gui.Screen.DesktopCaptureMonitor.on("namechanged", function (id, name) { });
gui.Screen.DesktopCaptureMonitor.on("thumbnailchanged", function (id, thumbnail) { });
gui.Screen.DesktopCaptureMonitor.start(true, true);
Clone this wiki locally
You can’t perform that action at this time.