Document fullscreen/ESC behaviour.

chrome/common/extensions/api/app_window.idl

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Use the <code>chrome.app.window</code> API to create windows. Windows
 // have an optional frame with title bar and size controls. They are not
 // associated with any Chrome browser windows.
 namespace app.window {
   dictionary Bounds {
     long? left;
@@ skipping 117 matching lines @@
   // function () { }; };</code>
   // <br>window.js:<br>
   // <code>window.onload = function () { foo(); }</code>
   callback CreateWindowCallback =
       void ([instanceOf=AppWindow] object createdWindow);
 
   [noinline_doc] dictionary AppWindow {
     // Focus the window.
     static void focus();
 
-    // Fullscreens the window.
+    // Fullscreens the window.<br>
+    // The user will be able to restore the window by pressing ESC. An
+    // application can prevent the fullscreen state to be left when ESC is
+    // pressed by requesting the <b>overrideEscFullscreen</b> permission and
+    // canceling the event by calling .preventDefault(), like this:<br>
+    // <code>function(createdWindow) { createdWindow.contentWindow.onKeyDown =
+    // function(e) { if (e.keyCode == 27 /* ESC */) { e.preventDefault(); } } };

[benwells, 2014/01/06 05:28:24]

Nit: Just having the below is enough:

window.onKeyDown = function(e) .....

+    // </code>
     static void fullscreen();
 
     // Is the window fullscreen?
     static boolean isFullscreen();
 
     // Minimize the window.
     static void minimize();
 
     // Is the window minimized?
     static boolean isMinimized();
@@ skipping 139 matching lines @@
     // Fired when the window is maximized.
     [nocompile] static void onMaximized();
 
     // Fired when the window is minimized.
     [nocompile] static void onMinimized();
 
     // Fired when the window is restored from being minimized or maximized.
     [nocompile] static void onRestored();
   };
 };