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.
29 // Default width of the window. (Deprecated; regular bounds act like this
31 [nodoc] long? defaultWidth;
33 // Default height of the window. (Deprecated; regular bounds act like this
35 [nodoc] long? defaultHeight;
37 // Default X coordinate of the window. (Deprecated; regular bounds act like
39 [nodoc] long? defaultLeft;
41 // Default Y coordinate of the window. (Deprecated; regular bounds act like
43 [nodoc] long? defaultTop;
45 // Width of the window. (Deprecated; use 'bounds'.)
48 // Height of the window. (Deprecated; use 'bounds'.)
51 // X coordinate of the window. (Deprecated; use 'bounds'.)
54 // Y coordinate of the window. (Deprecated; use 'bounds'.)
57 // Minimum width of the window.
60 // Minimum height of the window.
63 // Maximum width of the window.
66 // Maximum height of the window.
69 // Type of window to create.
70 [nodoc] WindowType? type;
72 // Frame type: <code>none</code> or <code>chrome</code> (defaults to
73 // <code>chrome</code>). For <code>none</code>, the
74 // <code>-webkit-app-region</code> CSS property can be used to apply
75 // draggability to the app's window. <code>-webkit-app-region: drag</code>
76 // can be used to mark regions draggable. <code>no-drag</code> can be used
77 // to disable this style on nested elements.
80 // Size and position of the content in the window (excluding the titlebar).
81 // If an id is also specified and a window with a matching id has been shown
82 // before, the remembered bounds of the window will be used instead.
85 // Enable window background transparency.
86 // Only supported in ash. Requires experimental API permission.
87 boolean? transparentBackground;
89 // The initial state of the window, allowing it to be created already
90 // fullscreen, maximized, or minimized. Defaults to 'normal'.
93 // If true, the window will be created in a hidden state. Call show() on
94 // the window to show it once it has been created. Defaults to false.
97 // If true, the window will be resizable by the user. Defaults to true.
100 // By default if you specify an id for the window, the window will only be
101 // created if another window with the same id doesn't already exist. If a
102 // window with the same id already exists that window is activated instead.
103 // If you do want to create multiple windows with the same id, you can
104 // set this property to false.
107 // If true, the window will stay above most other windows. If there are
108 // multiple windows of this kind, the currently focused window will be in
109 // the foreground. Defaults to false. Call <code>setAlwaysOnTop()</code> on
110 // the window to change this property after creation.
111 boolean? alwaysOnTop;
114 // Called in the creating window (parent) before the load event is called in
115 // the created window (child). The parent can set fields or functions on the
116 // child usable from onload. E.g. background.js:<br>
117 // <code>function(createdWindow) { createdWindow.contentWindow.foo =
118 // function () { }; };</code>
119 // <br>window.js:<br>
120 // <code>window.onload = function () { foo(); }</code>
121 callback CreateWindowCallback =
122 void ([instanceOf=AppWindow] object createdWindow);
124 [noinline_doc] dictionary AppWindow {
128 // Fullscreens the window.
129 static void fullscreen();
131 // Is the window fullscreen?
132 static boolean isFullscreen();
134 // Minimize the window.
135 static void minimize();
137 // Is the window minimized?
138 static boolean isMinimized();
140 // Maximize the window.
141 static void maximize();
143 // Is the window maximized?
144 static boolean isMaximized();
146 // Restore the window, exiting a maximized, minimized, or fullscreen state.
147 static void restore();
149 // Move the window to the position (|left|, |top|).
150 static void moveTo(long left, long top);
152 // Resize the window to |width|x|height| pixels in size.
153 static void resizeTo(long width, long height);
155 // Draw attention to the window.
156 static void drawAttention();
158 // Clear attention to the window.
159 static void clearAttention();
164 // Show the window. Does nothing if the window is already visible.
167 // Hide the window. Does nothing if the window is already hidden.
170 // Get the window's bounds as a $ref:Bounds object.
171 [nocompile] static Bounds getBounds();
173 // Set the window's bounds.
174 static void setBounds(Bounds bounds);
176 // Get the current minimum width of the window. Returns |undefined| if there
178 [nocompile] static long getMinWidth();
180 // Get the current minimum height of the window. Returns |undefined| if
181 // there is no minimum.
182 [nocompile] static long getMinHeight();
184 // Get the current maximum width of the window. Returns |undefined| if there
186 [nocompile] static long getMaxWidth();
188 // Get the current maximum height of the window. Returns |undefined| if
189 // there is no maximum.
190 [nocompile] static long getMaxHeight();
192 // Set the current minimum width of the window. Set to |null| to remove the
194 static void setMinWidth(optional long minWidth);
196 // Set the current minimum height of the window. Set to |null| to remove the
198 static void setMinHeight(optional long minHeight);
200 // Set the current maximum width of the window. Set to |null| to remove the
202 static void setMaxWidth(optional long maxWidth);
204 // Set the current maximum height of the window. Set to |null| to remove the
206 static void setMaxHeight(optional long maxHeight);
208 // Set the app icon for the window (experimental).
209 // Currently this is only being implemented on Ash.
210 // TODO(stevenjb): Investigate implementing this on Windows and OSX.
211 [nodoc] static void setIcon(DOMString iconUrl);
213 // Is the window always on top?
214 static boolean isAlwaysOnTop();
216 // Set whether the window should stay above most other windows.
217 static void setAlwaysOnTop(boolean alwaysOnTop);
219 // The JavaScript 'window' object for the created child.
220 [instanceOf=Window] object contentWindow;
223 interface Functions {
224 // The size and position of a window can be specified in a number of
225 // different ways. The most simple option is not specifying anything at
226 // all, in which case a default size and platform dependent position will
229 // Another option is to use the bounds property, which will put the window
230 // at the specified coordinates with the specified size. If the window has
231 // a frame, it's total size will be the size given plus the size of the
232 // frame; that is, the size in bounds is the content size, not the window
235 // To automatically remember the positions of windows you can give them ids.
236 // If a window has an id, This id is used to remember the size and position
237 // of the window whenever it is moved or resized. This size and position is
238 // then used instead of the specified bounds on subsequent opening of a
239 // window with the same id. If you need to open a window with an id at a
240 // location other than the remembered default, you can create it hidden,
241 // move it to the desired location, then show it.
242 static void create(DOMString url,
243 optional CreateWindowOptions options,
244 optional CreateWindowCallback callback);
246 // Returns an $ref:AppWindow object for the
247 // current script context (ie JavaScript 'window' object). This can also be
248 // called on a handle to a script context for another page, for example:
249 // otherWindow.chrome.app.window.current().
250 [nocompile] static AppWindow current();
251 [nocompile, nodoc] static void initializeAppWindow(object state);
255 // Fired when the window is resized.
256 [nocompile] static void onBoundsChanged();
258 // Fired when the window is closed.
259 [nocompile] static void onClosed();
261 // Fired when the window is fullscreened.
262 [nocompile] static void onFullscreened();
264 // Fired when the window is maximized.
265 [nocompile] static void onMaximized();
267 // Fired when the window is minimized.
268 [nocompile] static void onMinimized();
270 // Fired when the window is restored from being minimized or maximized.
271 [nocompile] static void onRestored();