1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // Use the <code>chrome.app.window</code> API to create windows. Windows
6 // have an optional frame with title bar and size controls. They are not
7 // associated with any Chrome browser windows.
16 // State of a window: normal, fullscreen, maximized, minimized.
17 enum State { normal, fullscreen, maximized, minimized };
19 // 'shell' is the default window type. 'panel' is managed by the OS
20 // (Currently experimental, Ash only).
21 [nodoc] enum WindowType { shell, panel };
23 dictionary CreateWindowOptions {
24 // Id to identify the window. This will be used to remember the size
25 // and position of the window and restore that geometry when a window
26 // with the same id is later opened.
27 // If a window with a given id is created while another window with the same
28 // id already exists, the currently opened window will be focused instead of
29 // creating a new window.
32 // Default width of the window.
33 [deprecated="Use $ref:Bounds."] long? defaultWidth;
35 // Default height of the window.
36 [deprecated="Use $ref:Bounds."] long? defaultHeight;
38 // Default X coordinate of the window.
39 [deprecated="Use $ref:Bounds."] long? defaultLeft;
41 // Default Y coordinate of the window.
42 [deprecated="Use $ref:Bounds."] long? defaultTop;
44 // Width of the window.
45 [deprecated="Use $ref:Bounds."] long? width;
47 // Height of the window.
48 [deprecated="Use $ref:Bounds."] long? height;
50 // X coordinate of the window.
51 [deprecated="Use $ref:Bounds."] long? left;
53 // Y coordinate of the window.
54 [deprecated="Use $ref:Bounds."] long? top;
56 // Minimum width of the window.
59 // Minimum height of the window.
62 // Maximum width of the window.
65 // Maximum height of the window.
68 // Type of window to create.
69 [nodoc] WindowType? type;
71 // Frame type: <code>none</code> or <code>chrome</code> (defaults to
72 // <code>chrome</code>). For <code>none</code>, the
73 // <code>-webkit-app-region</code> CSS property can be used to apply
74 // draggability to the app's window. <code>-webkit-app-region: drag</code>
75 // can be used to mark regions draggable. <code>no-drag</code> can be used
76 // to disable this style on nested elements.
79 // Size and position of the content in the window (excluding the titlebar).
80 // If an id is also specified and a window with a matching id has been shown
81 // before, the remembered bounds of the window will be used instead.
84 // Enable window background transparency.
85 // Only supported in ash. Requires experimental API permission.
86 boolean? transparentBackground;
88 // The initial state of the window, allowing it to be created already
89 // fullscreen, maximized, or minimized. Defaults to 'normal'.
92 // If true, the window will be created in a hidden state. Call show() on
93 // the window to show it once it has been created. Defaults to false.
96 // If true, the window will be resizable by the user. Defaults to true.
99 // By default if you specify an id for the window, the window will only be
100 // created if another window with the same id doesn't already exist. If a
101 // window with the same id already exists that window is activated instead.
102 // If you do want to create multiple windows with the same id, you can
103 // set this property to false.
104 [deprecated="Multiple windows with the same id is no longer supported."] boolean? singleton;
106 // If true, the window will stay above most other windows. If there are
107 // multiple windows of this kind, the currently focused window will be in
108 // the foreground. Requires the <code>"alwaysOnTopWindows"</code>
109 // permission. Defaults to false.<br>
110 // Call <code>setAlwaysOnTop()</code> on the window to change this property
111 // after creation.<br>
112 boolean? alwaysOnTop;
114 // If true, the window will be focused when created. Defaults to true.
118 // Called in the creating window (parent) before the load event is called in
119 // the created window (child). The parent can set fields or functions on the
120 // child usable from onload. E.g. background.js:<br>
121 // <code>function(createdWindow) { createdWindow.contentWindow.foo =
122 // function () { }; };</code>
123 // <br>window.js:<br>
124 // <code>window.onload = function () { foo(); }</code>
125 callback CreateWindowCallback =
126 void ([instanceOf=AppWindow] object createdWindow);
128 [noinline_doc] dictionary AppWindow {
132 // Fullscreens the window.<br>
133 // The user will be able to restore the window by pressing ESC. An
134 // application can prevent the fullscreen state to be left when ESC is
135 // pressed by requesting the <b>overrideEscFullscreen</b> permission and
136 // canceling the event by calling .preventDefault(), like this:<br>
137 // <code>window.onKeyDown = function(e) { if (e.keyCode == 27 /* ESC */) {
138 // e.preventDefault(); } };</code>
139 static void fullscreen();
141 // Is the window fullscreen?
142 static boolean isFullscreen();
144 // Minimize the window.
145 static void minimize();
147 // Is the window minimized?
148 static boolean isMinimized();
150 // Maximize the window.
151 static void maximize();
153 // Is the window maximized?
154 static boolean isMaximized();
156 // Restore the window, exiting a maximized, minimized, or fullscreen state.
157 static void restore();
159 // Move the window to the position (|left|, |top|).
160 static void moveTo(long left, long top);
162 // Resize the window to |width|x|height| pixels in size.
163 static void resizeTo(long width, long height);
165 // Draw attention to the window.
166 static void drawAttention();
168 // Clear attention to the window.
169 static void clearAttention();
174 // Show the window. Does nothing if the window is already visible.
175 // Focus the window if |focused| is set to true or omitted.
176 static void show(optional boolean focused);
178 // Hide the window. Does nothing if the window is already hidden.
181 // Get the window's bounds as a $ref:Bounds object.
182 [nocompile] static Bounds getBounds();
184 // Set the window's bounds.
185 static void setBounds(Bounds bounds);
187 // Get the current minimum width of the window. Returns |undefined| if there
189 [nocompile] static long getMinWidth();
191 // Get the current minimum height of the window. Returns |undefined| if
192 // there is no minimum.
193 [nocompile] static long getMinHeight();
195 // Get the current maximum width of the window. Returns |undefined| if there
197 [nocompile] static long getMaxWidth();
199 // Get the current maximum height of the window. Returns |undefined| if
200 // there is no maximum.
201 [nocompile] static long getMaxHeight();
203 // Set the current minimum width of the window. Set to |null| to remove the
205 static void setMinWidth(optional long minWidth);
207 // Set the current minimum height of the window. Set to |null| to remove the
209 static void setMinHeight(optional long minHeight);
211 // Set the current maximum width of the window. Set to |null| to remove the
213 static void setMaxWidth(optional long maxWidth);
215 // Set the current maximum height of the window. Set to |null| to remove the
217 static void setMaxHeight(optional long maxHeight);
219 // Set the app icon for the window (experimental).
220 // Currently this is only being implemented on Ash.
221 // TODO(stevenjb): Investigate implementing this on Windows and OSX.
222 [nodoc] static void setIcon(DOMString iconUrl);
224 // Set a badge icon for the window.
225 // TODO(benwells): Document this properly before going to stable.
226 [nodoc] static void setBadgeIcon(DOMString iconUrl);
228 // Clear the current for the window.
229 // TODO(benwells): Document this properly before going to stable.
230 [nodoc] static void clearBadge();
232 // Is the window always on top?
233 static boolean isAlwaysOnTop();
235 // Set whether the window should stay above most other windows. Requires the
236 // <code>"alwaysOnTopWindows"</code> permission.
237 static void setAlwaysOnTop(boolean alwaysOnTop);
239 // The JavaScript 'window' object for the created child.
240 [instanceOf=Window] object contentWindow;
242 // The id the window was created with.
246 interface Functions {
247 // The size and position of a window can be specified in a number of
248 // different ways. The most simple option is not specifying anything at
249 // all, in which case a default size and platform dependent position will
252 // Another option is to use the bounds property, which will put the window
253 // at the specified coordinates with the specified size. If the window has
254 // a frame, it's total size will be the size given plus the size of the
255 // frame; that is, the size in bounds is the content size, not the window
258 // To automatically remember the positions of windows you can give them ids.
259 // If a window has an id, This id is used to remember the size and position
260 // of the window whenever it is moved or resized. This size and position is
261 // then used instead of the specified bounds on subsequent opening of a
262 // window with the same id. If you need to open a window with an id at a
263 // location other than the remembered default, you can create it hidden,
264 // move it to the desired location, then show it.
265 static void create(DOMString url,
266 optional CreateWindowOptions options,
267 optional CreateWindowCallback callback);
269 // Returns an $ref:AppWindow object for the
270 // current script context (ie JavaScript 'window' object). This can also be
271 // called on a handle to a script context for another page, for example:
272 // otherWindow.chrome.app.window.current().
273 [nocompile] static AppWindow current();
274 [nocompile, nodoc] static void initializeAppWindow(object state);
276 // Gets an array of all currently created app windows. This method is new in
278 [nocompile] static AppWindow[] getAll();
280 // Gets an $ref:AppWindow with the given id. If no window with the given id
281 // exists null is returned. This method is new in Chrome 33.
282 [nocompile] static AppWindow get(DOMString id);
286 // Fired when the window is resized.
287 [nocompile] static void onBoundsChanged();
289 // Fired when the window is closed.
290 [nocompile] static void onClosed();
292 // Fired when the window is fullscreened.
293 [nocompile] static void onFullscreened();
295 // Fired when the window is maximized.
296 [nocompile] static void onMaximized();
298 // Fired when the window is minimized.
299 [nocompile] static void onMinimized();
301 // Fired when the window is restored from being minimized or maximized.
302 [nocompile] static void onRestored();