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.
10 // Previously named Bounds.
11 dictionary ContentBounds {
18 dictionary BoundsSpecification {
19 // The X coordinate of the content or window.
22 // The Y coordinate of the content or window.
25 // The width of the content or window.
28 // The height of the content or window.
31 // The minimum width of the content or window.
34 // The minimum height of the content or window.
37 // The maximum width of the content or window.
40 // The maximum height of the content or window.
45 // This property can be used to read or write the current X coordinate of
46 // the content or window.
49 // This property can be used to read or write the current Y coordinate of
50 // the content or window.
53 // This property can be used to read or write the current width of the
57 // This property can be used to read or write the current height of the
61 // This property can be used to read or write the current minimum width of
62 // the content or window. A value of <code>null</code> indicates
66 // This property can be used to read or write the current minimum height of
67 // the content or window. A value of <code>null</code> indicates
71 // This property can be used to read or write the current maximum width of
72 // the content or window. A value of <code>null</code> indicates
76 // This property can be used to read or write the current maximum height of
77 // the content or window. A value of <code>null</code> indicates
81 // Set the left and top position of the content or window.
82 static void setPosition(long left, long top);
84 // Set the width and height of the content or window.
85 static void setSize(long width, long height);
87 // Set the minimum size constraints of the content or window. The minimum
88 // width or height can be set to <code>null</code> to remove the constraint.
89 // A value of <code>undefined</code> will leave a constraint unchanged.
90 static void setMinimumSize(long minWidth, long minHeight);
92 // Set the maximum size constraints of the content or window. The maximum
93 // width or height can be set to <code>null</code> to remove the constraint.
94 // A value of <code>undefined</code> will leave a constraint unchanged.
95 static void setMaximumSize(long maxWidth, long maxHeight);
98 dictionary FrameOptions {
99 // Frame type: <code>none</code> or <code>chrome</code> (defaults to
100 // <code>chrome</code>).<br>
101 // For <code>none</code>, the <code>-webkit-app-region</code> CSS property
102 // can be used to apply draggability to the app's window.
103 // <code>-webkit-app-region: drag</code> can be used to mark regions
104 // draggable. <code>no-drag</code> can be used to disable this style on
105 // nested elements.<br>
107 // Allows the frame color to be set. Frame coloring is only available if the
108 // frame type is <code>chrome</code>.
109 // Frame coloring is experimental and only available in dev channel.
113 // State of a window: normal, fullscreen, maximized, minimized.
114 enum State { normal, fullscreen, maximized, minimized };
116 // 'shell' is the default window type. 'panel' is managed by the OS
117 // (Currently experimental, Ash only).
118 [nodoc] enum WindowType { shell, panel };
120 dictionary CreateWindowOptions {
121 // Id to identify the window. This will be used to remember the size
122 // and position of the window and restore that geometry when a window
123 // with the same id is later opened.
124 // If a window with a given id is created while another window with the same
125 // id already exists, the currently opened window will be focused instead of
126 // creating a new window.
129 // Used to specify the initial position, initial size and constraints of the
130 // window's content (excluding window decorations).
131 // If an <code>id</code> is also specified and a window with a matching
132 // <code>id</code> has been shown before, the remembered bounds will be used
135 // Note that the padding between the inner and outer bounds is determined by
136 // the OS. Therefore setting the same bounds property for both the
137 // <code>innerBounds</code> and <code>outerBounds</code> will result in an
140 // Currently only available on the Dev channel from Chrome 35.
141 BoundsSpecification? innerBounds;
143 // Used to specify the initial position, initial size and constraints of the
144 // window (including window decorations such as the title bar and frame).
145 // If an <code>id</code> is also specified and a window with a matching
146 // <code>id</code> has been shown before, the remembered bounds will be used
149 // Note that the padding between the inner and outer bounds is determined by
150 // the OS. Therefore setting the same bounds property for both the
151 // <code>innerBounds</code> and <code>outerBounds</code> will result in an
154 // Currently only available on the Dev channel from Chrome 35.
155 BoundsSpecification? outerBounds;
157 // Default width of the window.
158 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? defaultWidth;
160 // Default height of the window.
161 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? defaultHeight;
163 // Default X coordinate of the window.
164 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? defaultLeft;
166 // Default Y coordinate of the window.
167 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? defaultTop;
169 // Width of the window.
170 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? width;
172 // Height of the window.
173 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? height;
175 // X coordinate of the window.
176 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? left;
178 // Y coordinate of the window.
179 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? top;
181 // Minimum width of the window.
184 // Minimum height of the window.
187 // Maximum width of the window.
190 // Maximum height of the window.
193 // Type of window to create.
194 [nodoc] WindowType? type;
196 // Frame type: <code>none</code> or <code>chrome</code> (defaults to
197 // <code>chrome</code>). For <code>none</code>, the
198 // <code>-webkit-app-region</code> CSS property can be used to apply
199 // draggability to the app's window. <code>-webkit-app-region: drag</code>
200 // can be used to mark regions draggable. <code>no-drag</code> can be used
201 // to disable this style on nested elements.<br>
202 // Use of <code>FrameOptions</code> is only supported in dev channel.
203 (DOMString or FrameOptions)? frame;
205 // Size and position of the content in the window (excluding the titlebar).
206 // If an id is also specified and a window with a matching id has been shown
207 // before, the remembered bounds of the window will be used instead.
208 ContentBounds? bounds;
210 // Enable window background transparency.
211 // Only supported in ash. Requires experimental API permission.
212 boolean? transparentBackground;
214 // The initial state of the window, allowing it to be created already
215 // fullscreen, maximized, or minimized. Defaults to 'normal'.
218 // If true, the window will be created in a hidden state. Call show() on
219 // the window to show it once it has been created. Defaults to false.
222 // If true, the window will be resizable by the user. Defaults to true.
225 // By default if you specify an id for the window, the window will only be
226 // created if another window with the same id doesn't already exist. If a
227 // window with the same id already exists that window is activated instead.
228 // If you do want to create multiple windows with the same id, you can
229 // set this property to false.
230 [deprecated="Multiple windows with the same id is no longer supported."] boolean? singleton;
232 // If true, the window will stay above most other windows. If there are
233 // multiple windows of this kind, the currently focused window will be in
234 // the foreground. Requires the <code>"app.window.alwaysOnTop"</code>
235 // permission. Defaults to false.<br>
236 // Call <code>setAlwaysOnTop()</code> on the window to change this property
237 // after creation.<br>
238 boolean? alwaysOnTop;
240 // If true, the window will be focused when created. Defaults to true.
244 // Called in the creating window (parent) before the load event is called in
245 // the created window (child). The parent can set fields or functions on the
246 // child usable from onload. E.g. background.js:<br>
247 // <code>function(createdWindow) { createdWindow.contentWindow.foo =
248 // function () { }; };</code>
249 // <br>window.js:<br>
250 // <code>window.onload = function () { foo(); }</code>
251 callback CreateWindowCallback =
252 void ([instanceOf=AppWindow] object createdWindow);
254 [noinline_doc] dictionary AppWindow {
258 // Fullscreens the window.<br>
259 // The user will be able to restore the window by pressing ESC. An
260 // application can prevent the fullscreen state to be left when ESC is
261 // pressed by requesting the <b>app.window.fullscreen.overrideEsc</b>
262 // permission and canceling the event by calling .preventDefault(), like
264 // <code>window.onKeyDown = function(e) { if (e.keyCode == 27 /* ESC */) {
265 // e.preventDefault(); } };</code>
266 static void fullscreen();
268 // Is the window fullscreen?
269 static boolean isFullscreen();
271 // Minimize the window.
272 static void minimize();
274 // Is the window minimized?
275 static boolean isMinimized();
277 // Maximize the window.
278 static void maximize();
280 // Is the window maximized?
281 static boolean isMaximized();
283 // Restore the window, exiting a maximized, minimized, or fullscreen state.
284 static void restore();
286 // Move the window to the position (|left|, |top|).
287 static void moveTo(long left, long top);
289 // Resize the window to |width|x|height| pixels in size.
290 static void resizeTo(long width, long height);
292 // Draw attention to the window.
293 static void drawAttention();
295 // Clear attention to the window.
296 static void clearAttention();
301 // Show the window. Does nothing if the window is already visible.
302 // Focus the window if |focused| is set to true or omitted.
303 static void show(optional boolean focused);
305 // Hide the window. Does nothing if the window is already hidden.
308 // Get the window's inner bounds as a $(ref:ContentBounds) object.
309 [nocompile] static ContentBounds getBounds();
311 // Set the window's inner bounds.
312 [nocompile] static void setBounds(ContentBounds bounds);
314 // Set the app icon for the window (experimental).
315 // Currently this is only being implemented on Ash.
316 // TODO(stevenjb): Investigate implementing this on Windows and OSX.
317 [nodoc] static void setIcon(DOMString iconUrl);
319 // Set a badge icon for the window.
320 // TODO(benwells): Document this properly before going to stable.
321 [nodoc] static void setBadgeIcon(DOMString iconUrl);
323 // Clear the current for the window.
324 // TODO(benwells): Document this properly before going to stable.
325 [nodoc] static void clearBadge();
327 // Is the window always on top?
328 static boolean isAlwaysOnTop();
330 // Accessors for testing.
331 [nodoc] boolean hasFrameColor;
332 [nodoc] long frameColor;
334 // Set whether the window should stay above most other windows. Requires the
335 // <code>"app.window.alwaysOnTop"</code> permission.
336 static void setAlwaysOnTop(boolean alwaysOnTop);
338 // The JavaScript 'window' object for the created child.
339 [instanceOf=Window] object contentWindow;
341 // The id the window was created with.
344 // The position, size and constraints of the window's content, which does
345 // not include window decorations.
346 // Currently only available on the Dev channel from Chrome 35.
349 // The position, size and constraints of the window, which includes window
350 // decorations, such as the title bar and frame.
351 // Currently only available on the Dev channel from Chrome 35.
355 interface Functions {
356 // The size and position of a window can be specified in a number of
357 // different ways. The most simple option is not specifying anything at
358 // all, in which case a default size and platform dependent position will
361 // Another option is to use the <code>bounds</code> property, which will put
362 // the window at the specified coordinates with the specified size. If the
363 // window has a frame, it's total size will be the size given plus the size
364 // of the frame; that is, the size in bounds is the content size, not the
367 // To automatically remember the positions of windows you can give them ids.
368 // If a window has an id, This id is used to remember the size and position
369 // of the window whenever it is moved or resized. This size and position is
370 // then used instead of the specified bounds on subsequent opening of a
371 // window with the same id. If you need to open a window with an id at a
372 // location other than the remembered default, you can create it hidden,
373 // move it to the desired location, then show it.
374 static void create(DOMString url,
375 optional CreateWindowOptions options,
376 optional CreateWindowCallback callback);
378 // Returns an $(ref:AppWindow) object for the
379 // current script context (ie JavaScript 'window' object). This can also be
380 // called on a handle to a script context for another page, for example:
381 // otherWindow.chrome.app.window.current().
382 [nocompile] static AppWindow current();
383 [nocompile, nodoc] static void initializeAppWindow(object state);
385 // Gets an array of all currently created app windows. This method is new in
387 [nocompile] static AppWindow[] getAll();
389 // Gets an $(ref:AppWindow) with the given id. If no window with the given id
390 // exists null is returned. This method is new in Chrome 33.
391 [nocompile] static AppWindow get(DOMString id);
395 // Fired when the window is resized.
396 [nocompile] static void onBoundsChanged();
398 // Fired when the window is closed.
399 [nocompile] static void onClosed();
401 // Fired when the window is fullscreened.
402 [nocompile] static void onFullscreened();
404 // Fired when the window is maximized.
405 [nocompile] static void onMaximized();
407 // Fired when the window is minimized.
408 [nocompile] static void onMinimized();
410 // Fired when the window is restored from being minimized or maximized.
411 [nocompile] static void onRestored();