Window

Window API 기능은 node-webkit v0.3.0 이상이 필요합니다.

Window 객체는 DOM의 window 객체를 대체합니다. 이 객체를 통해 확장하거나 window 이벤트를 제공받을 수 있습니다.

모든 Window 객체는 EventEmitter 클래스에 상속되어 Window.on(...) 메소드를 통하여 네이티브 윈도우 이벤트를 응답받을 수 있습니다.

시놉시스

// native UI library 를 불러옵니다.
var gui = require('nw.gui'); //또는 global.window.nwDispatcher.requireNwGui() (see https://github.com/rogerwang/node-webkit/issues/707)

// 현재 윈도우 객체를 받습니다.
var win = gui.Window.get();

// 윈도우 최소화 이벤트를 받습니다.
win.on('minimize', function() {
  console.log('Window is minimized');
});

// 윈도우를 최소화합니다.
win.minimize();

// 최소화 이벤트를 끊습니다.
win.removeAllListeners('minimize');

// 새 윈도우를 받은 후 윈도우 객체를 받습니다.
var new_win = gui.Window.open('https://github.com');

// 윈도우의 `focus` 이벤트를 받습니다.
new_win.on('focus', function() {
  console.log('New window is focused');
});

레퍼런스

get([window_object])

window_object를 지정하지 않으면 현재 윈도우의 Window 객체를 받으며, 그 외에는 window_object의 Window 객체를 받습니다.

// 현재 윈도우 객체를 받습니다.
var win = gui.Window.get();

// 새 윈도우를 만들고 윈도우 객체를 받습니다.
var new_win = gui.Window.open('https://github.com');

open(url[, options])

url 인터넷 주소를 통한 새 창을 생성하여 불러옵니다. 여기서 두번째 인자인 options을 지정할 수 있는데, 모든 윈도우의 하위 필드는 매니페스트 형식을 따릅니다. v0.4.0 부터는 하위 필드에 new-instance 부울 인자를 지정할 수 있고, 지정하면 새 인스턴스가 생성됩니다. 그리고 v0.9.0 과 0.8.5 에서는 inject-js-start 와 inject-js-end 필드를 통해 자바스크립트 파일을 주입할 수 있습니다. 매니페스트 형식을 참조하세요.

v0.7.3 부터는 윈도우가 열릴 경우 포커스되지 않는 상태가 기본값입니다. 이는 각 플랫폼에 예기치 않은 상황에 대비하기 위한 것입니다. 만약 포커스된 상태를 원한다면 options 필드상 focus 필드에 true 를 주면 됩니다.

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

Window.window

네이티브 윈도우 객체로부터 DOM의 window 객체를 받습니다.

Window.x/Window.y

화면의 가로/세로 위치를 받거나 설정합니다.

Window.width/Window.height

윈도우 크기를 받거나 설정합니다.

Window.title

윈도우 제목 표시줄에 있는 제목을 받거나 설정합니다.

Window.menu

윈도우 메뉴바를 받거나 설정합니다. 메뉴바를 설정하는 방법은 메뉴 기능을 참조하세요.

Window.isFullscreen

v0.3.5 부터 지원

풀스크린 여부를 받거나 설정합니다.

Window.isTransparent

v0.11.2 부터 지원

창의 투명 여부를 받습니다.

Window.isKioskMode

since v0.3.5

키오스크 모드 활성화 여부를 받거나 설정합니다.

Window.zoomLevel

since v0.4.1

확대 비율을 받거나 설정합니다. 0은 기본 비율이며, 양수를 통해 확대 비율, 음수를 통해 축소 비율을 설정할 수 있습니다.

Window.moveTo(x, y)

지정된 윈도우의 가로와 세로 위치를 스크린 기준에서 이동합니다.

Window.moveBy(x, y)

지정된 윈도우의 가로와 세로 위치를 기존 위치 기준에서 이동합니다.

Window.resizeTo(width, height)

지정된 윈도우의 가로와 세로 크기를 스크린 기준에서 변경합니다.

Window.resizeBy(width, height)

지정된 윈도우의 가로와 세로 크기를 기존 크기에서 변경합니다.

Window.focus()

윈도우를 최상위로 보이게 합니다.

Window.blur()

윈도우를 뒤로 뺍니다. 이는 다른 윈도우 포커스를 부여할 때 유용합니다. 몇몇 플랫폼은 이 개념이 없을 수 있습니다.

Window.show()

윈도우가 보이지 않을 경우 보이게 합니다. 몇몇 플랫폼에서 포커스되지 않으면 보이게 할 수 없으므로 focus 먼저 실행하는 것이 좋습니다.

show(false) 이렇게 호출하면 hide() 메소드와 동일한 효과가 나타납니다.

Window.hide()

윈도우를 숨깁니다. 사용자는 해당 윈도우 화면을 찾을 수 없습니다.

Window.close([force])

현재 윈도우를 닫습니다. 이 때, Window 객체의 close 이벤트를 통해 막을 수 있습니다. 단, force 가 true일 경우 이벤트 호출 없이 닫게 됩니다.

close 를 그냥 호출하여 정말로 닫을 것인지 묻고, close(true) 를 호출하여 정말로 닫도록 하는 방식에 유용합니다.

win.on('close', function() {
  this.hide(); // 이미 닫았다는 효과를 부여
  console.log("We're closing...");
  this.close(true);
});

win.close();

Window.reload()

node-webkit v0.3.5 부터 지원

현재 윈도우를 새로고칩니다.

Window.reloadDev()

0.4.0 부터 지원
현재 페이지를 새로운 렌더러 프로세스로 활성화하여 새로고칩니다. 툴바 상단 오른쪽의 새로고침 버튼 역할과 동일합니다.

Window.reloadIgnoringCache()

node-webkit v0.3.5 부터 지원_

일반 새로고침과는 달리 캐시를 사용하지 않습니다. ("shift-reload" 로 알려짐).

Window.maximize()

윈도우와 GTK 에서는 최대화 역할을 수행하고, Mac OS X 에서는 윈도우를 확대합니다.

Window.unmaximize()

최대화한 윈도우를 초기상태로 되돌립니다.

Window.minimize()

보통 최소화와 동일합니다. Mac OS X 는 보통 지니 램프 애니메이션으로 최소화하는 효과를 가질 겁니다.

Window.restore()

최소화된 상태를 되돌립니다. 이름을 restore로 지은 이유는 윈도우 minimize 의 반대 개념이 restore이기 때문입니다.

Window.enterFullscreen()

풀스크린 모드로 들어갑니다. 이는 HTML5의 풀스크린 개념과 틀립니다. nw.js 는 사용자 승인여부를 묻지도 않고 따지지 않고 전체 화면을 현재 화면으로 최대화 시킵니다.

Window.leaveFullscreen()

풀스크린 모드를 빠져나갑니다.

Window.toggleFullscreen()

node-webkit v0.3.5 부터 지원

풀스크린 모드를 아니면 들어가고, 들어갔다면 빠져나가게 합니다.

Window.enterKioskMode()

node-webkit v0.3.1 부터 지원

키오스크 모드로 들어갑니다. 키오스크 모드에 들어가게 되면, 풀스크린 상태로 들어가게 되며, 사용자는 앱에서 못 빠져나가게 됩니다. 사용자가 빠져나가게 하려면 앱에서 키오스크모드를 빠져나가게 해야 합니다. 이는 프리젠테이션이나 게임 앱에 유용합니다.

Window.leaveKioskMode()

node-webkit v0.3.1 부터 지원

키오스크 모드에서 빠져 나갑니다.

Window.toggleKioskMode()

node-webkit v0.3.5 부터 지원

키오스크 모드가 아니면 들어가고, 들어갔다면 빠져나갑니다.

Window.setTransparent(transparent)

v0.11.2 부터 지원

투명화 모드를 지정합니다. 자세한 사항은 https://github.com/rogerwang/node-webkit/wiki/Transparency 를 참조하세요.

Window.showDevTools([id | iframe, headless])

해당 창의 개발자 도구를 활성화합니다.

id 인자는 0.6.0부터 지원하는데, iframe 요소의 id이여야 합니다. 이를 지정하게 되면 해당 iframe 내에서만 개발자 도구가 활성화하게 됩니다. id 가 빈 문자열이면 당연히 활성화되지 않습니다.

headless 인자는 0.6.0부터 지원하는데, true로 지정될 경우 개발자 도구는 열리지 않지만, 개발자 도구가 열렸다면 devtools-opened 속성이 Window 객체에 전달됩니다.

iframe 인자는 id 인자 대체로 0.7.2부터 지원합니다. 반드시 iframe 요소여야 하며, 효과는 id 인자와 동일합니다.

자세한 사항은 개발자 도구 격리기능 을 참고하세요.

0.8.1 부터는 headless 가 false (또는 설정되지 않음)임에 한정하여 Window 객체를 반환합니다. 이를 통해 개발자 도구의 Window 객체를 받을 수 있으나 아직 이벤트는 지원되지 않습니다.

Window.closeDevTools()

v0.7.3 부터 지원

개발자 도구를 닫습니다.

Window.isDevToolsOpen()

v0.8.0 부터 지원

개발자 도구가 열려있는지 알려줍니다. 참고: headless 가 true 이면 이 메소드는 항상 false 를 반환합니다.

Window.setMaximumSize(width, height)

윈도우의 가용 가능한 최대 크기를 설정합니다.

Window.setMinimumSize(width, height)

윈도우의 가용 가능한 최소 크기를 설정합니다.

Window.setResizable(Boolean resizable)

윈도우의 크기 조절 가능 여부를 설정합니다.

Window.setAlwaysOnTop(Boolean top)

node-webkit v0.3.4 이상 지원

윈도우 시스템에서 해당 앱 윈도우를 항상 위로 띄워주는 여부를 설정합니다.

Window.setVisibleOnAllWorkspaces(Boolean)

v0.11.3 부터 지원

다중 작업화면 (현재 Linux와 Mac OS X 지원. 역주: Windows 는 10 부터 지원할 듯)을 활성화하며 모든 워크스페이스에 nw.js 윈도우를 보이도록 합니다.

예제는 다음 링크를 참고하세요. visible_on_all_workspaces manual test.

자세한 사항은 https://github.com/rogerwang/node-webkit/issues/2523 를 참고하세요.

Window.canSetVisibleOnAllWorkspaces()

v0.11.3 부터 지원

위 메소드를 사용할 수 있는지 여부를 확인합니다. 당연히 Mac OS X와 리눅스에서만 현재 지원합니다.

Window.setPosition(String position)

윈도우 위치명을 설정하여 윈도우 위치를 변경합니다. 현재 모든 플랫폼에서는 center 가 지원되며, 정 가운데로 윈도우가 띄워집니다.

Window.setShowInTaskbar(Boolean show)

v0.9.2 부터 지원

윈도우나 리눅스의 작업 표시줄 또는 맥의 독 아이콘에 활성화 여부를 설정합니다. 매니페스트 형식 의 show_in_taskbar 속성을 참고하세요.

Window.requestAttention(Boolean attention)

true로 설정할 경우 사용자는 해당 창을 반드시 보도록 설정할 수 있습니다. (역자주: 경고 대화상자 같은 역할) false 로 해지할 수 있습니다. 플랫폼 행동에 따릅니다.

Window.requestAttention(Integer count)

v0.10.2 부터 지원

위 메소드와 비슷하지만 윈도우의 경우 사용자가 반드시 봐야 하는 깜박임 표시 횟수를 설정할 수 있다는 점에서 다릅니다.
맥에서는 값이 양수일 경우 NSCriticalRequest 트리거가 실행되는 동안 값이 음수이면 NSInformationalRequest 트리거를 호출합니다.
리눅스에서는 boolean 버전의 메소드와 동일한 역할을 수행합니다. 즉, 숫자가 적용되지 않습니다.

Window.capturePage(callback [, image_format | config_object ])

v0.4.2부터 지원

보이는 윈도우 영역을 캡쳐합니다. 데모는 https://gist.github.com/zhchbin/4749217 에서 볼 수 있습니다.

callback 은 이미지 데이터가 준비될 경우에 대한 이벤트 콜백 함수여야 합니다. 이렇게요:

function(dataUrl) {...};

dataURL(string) 을 통해서 data:uri 로 인코딩 된 이미지 데이터 문자열을 받아 이미지 태그의 src 속성에 놓을 수 있습니다.

image_format 인자는 ["jpeg", "png"] 중 하나를 지원하며. 기본값은 'jpeg' 입니다.

v0.9.3부터 지원

여기서부터 datatype 속성을 config_object 인자로 정의하여 이미지 데이터 방식을 설정할 수 있습니다.

객체의 쓰임새는 이렇습니다:

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

기본적으로:
format 속성은 jpeg
datatype 속성은 datauri

예제:

// png 를 base64string 으로 받음
win.capturePage(function(base64string){
 // base64string 을 핸들링
}, { format : 'png', datatype : 'raw'} );

// png 를 node.js buffer 객체로 받음
win.capturePage(function(buffer){
 // buffer 로 핸들링
}, { format : 'png', datatype : 'buffer'} );

setProgressBar(progress)

v0.10.2 부터 지원
유효 값은 0 부터 1 까지 입니다.
val < 0 일 경우 프로그래스 바가 없어집니다.
val > 1 일 경우 진행중인 프로그래스바임을 표시합니다.
리눅스의 경우 현재 우분트에서만 지원됩니다. 그리고 .desktop 파일에 NW_DESKTOP 환경 변수를 적용해야 합니다. 그렇지 않을 경우 nw.desktop 으로 인식됩니다.

setBadgeLabel(label)

v0.10.0-rc1 부터 지원

윈도우와 맥에서 지원됩니다. 뱃지 레이블을 윈도우 아이콘과 함께 작업 표시줄 또는 독에서 표시되도록 설정합니다.
v0.10.2 부터 지원 리눅스의 경우 우분투에서 지원되지만 숫자만 들어간 문자열이 지원되며, setProgressBar 메소드와 같이 .desktop 에 환경변수를 설정해야 합니다.

Window.cookies.*

v0.8.1 부터 지원

쿠키를 관리하는 메소드를 지원합니다. 이 API는 크롬 확장과 같습니다. nw.js 에서는 get, getAll, remove, 그리고 set 메소드가 지원되며, onChanged 이벤트가 addListener 와removeListener 이벤트 메소드에서 지원됩니다.

그리고 크롬 확장 API 의 CookieStore 에 기재된 멤버는 지원되지 않습니다. nw.js 는 쿠키가 전역으로만 지원하기 때문입니다.

Window.eval(frame, script)

v0.9.0 과 v0.8.5 부터 지원

frame 이 null 이거나, iframe 요소 내이면 현재 창 기준으로 스크립트가 실행되고, frame 이 iframe 요소이면, 해당 iframe 기준으로 스크립트를 실행합니다. script 인자는 자바스크립트 소스 코드 문자열입니다.

Window.evalNWBin(frame, path)

v0.12.0-rc1 부터 지원

nwjc 를 통하여 컴파일된 자바스크립트 바이너리를 실행합니다. frame 이 null이거나 iframe 내이면 윈도우 기준, frame 인자가 iframe 요소이면 해당 iframe 내에서 실행합니다. nwjc 스크립트 컴파일링은 https://github.com/nwjs/nw.js/wiki/Protect-JavaScript-source-code-with-v8-snapshot 링크를 참고하세요.

이벤트

여기에 나열된 이벤트는 Window.on() 함수에서 설정할 수 있습니다. 이벤트 다루는 방법의 자세한 사항은 EventEmitter 를 참고하세요.

close

close 이벤트는 창이 닫히는 Window.close() 함수가 실행될 때 발생되는 특별한 이벤트입니다. 개발자가 close 이벤트를 설정하면, Window.close() 함수는 윈도우를 닫는 대신 close 이벤트를 발생시킵니다.

close 이벤트를 통해 사용자가 앱이 닫히는 시점을 잡고, this.close(true) 로 완전히 창이 닫히게 할 수 있습니다. 이후 더이상의 작업은 없습니다. 만약 실제로 닫아야 할 close() 함수에 true 인자를 주지 않게 되면 close 이벤트가 무한 호출되는 사태가 발생됩니다.

그리고 앱이 닫히는 작업은 좀 걸립니다. 사용자는 앱이 종료되는데 느리게 닫히는 걸 느낄 수 있습니다. 이건 아무래도 좋지 않은 사용자 경험이죠. 그래서 hide 메소드를 통하여 실제로 앱이 닫히는 동시에 창을 숨겨 바로 닫히는 것처럼 하여 사용자 경험을 향상시킬 수 있습니다.

사용 예제에 대해서는 Window.close() 의 데모 코드를 참조하세요.

0.8.4 버전부터 맥에서는 콜백 인자에서 Cmd-Q 종료 단축키를 누를 경우에만 quit 메시지를 받게 될 것이며, 그 외에는 undefined 가 됩니다. 자세한 사항은 https://github.com/rogerwang/node-webkit/issues/430 를 참고하세요.

closed

창이 닫히고 난 다음 발생하는 이벤트입니다. 보통 이 이벤트는 앱이 완전히 닫히게 되면 발생하지 않습니다. 하지만 여러 창을 열었을 경우, 다른 창을 닫게 된 다면 이 이벤트가 발생되어 설정할 수 있습니다.

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

  // 윈도우를 엽니다.
  var win = gui.Window.open('popup.html');

  // 윈도우가 닫힌 다음의 이벤트를 설정합니다.
  win.on('closed', function() {
    win = null;
  });

  // 메인 윈도우가 닫힐 경우의 이벤트를 설정합니다.
  gui.Window.get().on('close', function() {
    // 창을 숨겨 사용자가 바로 종료된 느낌을 주도록 합니다.
    this.hide();

    // 새 창이 아직도 열렸을 경우 완전히 종료합니다.
    if (win != null)
      win.close(true);

    // 다른 창이 종료된 후 메인 창도 완전히 종료합니다.
    this.close(true);
  });
</script>

loading

node-webkit v0.3.5 이상 지원

윈도우의 웹 페이지를 불러오기 시작할 경우 발생합니다. 하지만 보통 이 이벤트를 잡을 수 없는데 이 이벤트가 설정되기도 전에 발생되기 때문입니다.

대신, 다른 창의 이벤트에서 페이지 불러오기를 시작할 경우에는 잡을 수 있습니다.

loaded

node-webkit v0.3.5 이상 지원

윈도우 내 페이지가 모두 불러와지면 발생합니다. window.onload 와는 비슷하지만 DOM 과는 영향받지 않습니다.

document-start

v0.9.0 또는 v0.8.5 부터 지원

function (frame) {} CSS 파일이 불러온 후 문서 요소 또는 자식 프레임이 활성화될 경우 발생합니다. 단, DOM이 설계되거나 스크립트 실행되기 전 시점입니다.

frame 은 iframe 요소입니다, null 이면 윈도우입니다.

같이보기: 매니페스트 형식의 inject-js-start 속성

document-end

v0.9.0 또는 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. 문서 요소나 윈도우의 자식 프레임이 불러와 DOM 설계가 모두 끝났을 경우 onload 발생 전에 발생합니다.

frame 은 iframe 요소입니다, null 이면 윈도우입니다.

같이보기: 매니페스트 형식의 inject-js-end 속성

focus

윈도우가 최상위로 보일 경우에 발생합니다.

blur

윈도우가 다른 윈도우로 가려져 있을 때 발생합니다.

minimize

윈도우가 최소화할 경우 발생합니다.

restore

최소화 후 원상태로 되돌아갈 경우 발생합니다.

maximize

윈도우가 최대화될 경우 발생합니다.

unmaximize

최대화된 윈도우가 원상태로 복귀될 때 발생합니다. 몇몇 플랫폼은 최대화할 때 윈도우 크기가 조절되는 방식일 경우 unmaximize 이벤트가 발생하지 않습니다.

move

v0.8.2 부터 지원

윈도우가 이동할 경우 발생합니다. 이 때 콜백에서는 이동한 후 가로, 세로 위치를 받아내는 2개의 인자가 (x, y) 에서 제공합니다.

resize

v0.8.2 부터 지원

윈도우 크기가 조절될 경우 발생합니다. 이 때 콜백에서는 조절된 후 가로, 세로 크기를 받아내는 2개의 인자가 (width, height) 에서 제공합니다.

enter-fullscreen

풀스크린이 활성화될 경우 발생합니다.

leave-fullscreen

풀스크린에서 빠져나갈 경우 발생합니다.

zoom

윈도우의 확대/축소 배율이 변경될 경우 발생합니다. 이 때 인자에서는 이후 확대축소 비율을 받아낼 수 있습니다. Window.zoom 메소드를 통해 배율값을 참조하세요.

capturepagedone

윈도우 캡쳐가 완료되고 이미지 데이터가 준비된 경우 발생합니다. 콜백은 Window.capturePage 메소드의 콜백을 참고하시기 바랍니다.

devtools-opened

어떠한 경우 상관없이 개발자 도구가 활성화된 경우 발생합니다. (0.8.0부터), 또는 Window.showDevTools(id, headless) 에서headless = true 로 설정한 경우에도 발생합니다. 콜백에서는 url 인자를 받으며, 이는 불러온 개발자 도구 UI의 주소를 나태냅니다. 개발자 도구 격리기능 과 윈도우 를 참고하세요.

devtools-closed

v0.8.0 부터 지원

개발자 도구가 닫힐 경우 발생됩니다.

new-win-policy

v0.9.0 과 v0.8.5 부터 지원

function (frame, url, policy) {}

현재 윈도우 또는 자식 프레임이 새 창 열기를 요청할 경우 발생합니다. (예: 사용자가 _blank 기준의 링크를 열어 새 창이 띄워질 경우)

frame 인자는 새 창을요청한 객체나 자식 프레임을 나타냅니다. null 이면 메인 윈도우를 가리킵니다.
url 은 요청한 링크 주소를 나타냅니다.
policy 는 아래 메소드를 포함한 객체입니다.
ignore() : 요청을 무시하며 아무 일도 일어나지 않게 합니다.
forceCurrent() : 해당 프레임에 무조건 표시하도록 합니다.
forceDownload() : 무조건 다운로드 또는 연결된 프로그램에 열도록 합니다.
forceNewWindow() : 무조건 새 창으로 열게 만듭니다.
forceNewPopup() : 무조건 새 팝업 창으로 열게 만듭니다.
setNewWindowManifest(m) : 해당 팝업 윈도우의 매니페스트를 설정합니다. m 인자는 매니페스트 형식 의 window 필드 내 속성과동일합니다. (예: {"frame" : false}). v0.11.3 부터 지원

알려진 문제점

이제 리눅스에서는 setMaximumSize()/setMinimumSize() 메소드와 setResizable() 메소드를 동시에 호출할 수 없습니다. 동시에 부를 경우 아예 작동되지 않으니 이 점에 주의해 주세요.

같이보기

EventEmitter