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. See the <a
8 // href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/window-state">
9 // Window State Sample</a> for a demonstration of these options.
10 namespace app.window {
12 // Previously named Bounds.
13 dictionary ContentBounds {
20 dictionary BoundsSpecification {
21 // The X coordinate of the content or window.
24 // The Y coordinate of the content or window.
27 // The width of the content or window.
30 // The height of the content or window.
33 // The minimum width of the content or window.
36 // The minimum height of the content or window.
39 // The maximum width of the content or window.
42 // The maximum height of the content or window.
47 // This property can be used to read or write the current X coordinate of
48 // the content or window.
51 // This property can be used to read or write the current Y coordinate of
52 // the content or window.
55 // This property can be used to read or write the current width of the
59 // This property can be used to read or write the current height of the
63 // This property can be used to read or write the current minimum width of
64 // the content or window. A value of <code>null</code> indicates
68 // This property can be used to read or write the current minimum height of
69 // the content or window. A value of <code>null</code> indicates
73 // This property can be used to read or write the current maximum width of
74 // the content or window. A value of <code>null</code> indicates
78 // This property can be used to read or write the current maximum height of
79 // the content or window. A value of <code>null</code> indicates
83 // Set the left and top position of the content or window.
84 static void setPosition(long left, long top);
86 // Set the width and height of the content or window.
87 static void setSize(long width, long height);
89 // Set the minimum size constraints of the content or window. The minimum
90 // width or height can be set to <code>null</code> to remove the constraint.
91 // A value of <code>undefined</code> will leave a constraint unchanged.
92 static void setMinimumSize(long minWidth, long minHeight);
94 // Set the maximum size constraints of the content or window. The maximum
95 // width or height can be set to <code>null</code> to remove the constraint.
96 // A value of <code>undefined</code> will leave a constraint unchanged.
97 static void setMaximumSize(long maxWidth, long maxHeight);
100 dictionary FrameOptions {
101 // Frame type: <code>none</code> or <code>chrome</code> (defaults to
102 // <code>chrome</code>).
104 // For <code>none</code>, the <code>-webkit-app-region</code> CSS property
105 // can be used to apply draggability to the app's window.
107 // <code>-webkit-app-region: drag</code> can be used to mark regions
108 // draggable. <code>no-drag</code> can be used to disable this style on
111 // Allows the frame color to be set. Frame coloring is only available if the
112 // frame type is <code>chrome</code>.
114 // Frame coloring is new in Chrome 36.
116 // Allows the frame color of the window when active to be set. Frame
117 // coloring is only available if the frame type is <code>chrome</code>.
119 // Frame coloring is only available if the frame type is
120 // <code>chrome</code>.
122 // Frame coloring is new in Chrome 36.
123 DOMString? activeColor;
124 // Allows the frame color of the window when inactive to be set differently
125 // to the active color. Frame
126 // coloring is only available if the frame type is <code>chrome</code>.
128 // <code>inactiveColor</code> must be used in conjunction with <code>
131 // Frame coloring is new in Chrome 36.
132 DOMString? inactiveColor;
135 // State of a window: normal, fullscreen, maximized, minimized.
136 enum State { normal, fullscreen, maximized, minimized };
138 // 'shell' is the default window type. 'panel' is managed by the OS
139 // (Currently experimental, Ash only).
140 [nodoc] enum WindowType { shell, panel };
142 [noinline_doc] dictionary CreateWindowOptions {
143 // Id to identify the window. This will be used to remember the size
144 // and position of the window and restore that geometry when a window
145 // with the same id is later opened.
146 // If a window with a given id is created while another window with the same
147 // id already exists, the currently opened window will be focused instead of
148 // creating a new window.
151 // Used to specify the initial position, initial size and constraints of the
152 // window's content (excluding window decorations).
153 // If an <code>id</code> is also specified and a window with a matching
154 // <code>id</code> has been shown before, the remembered bounds will be used
157 // Note that the padding between the inner and outer bounds is determined by
158 // the OS. Therefore setting the same bounds property for both the
159 // <code>innerBounds</code> and <code>outerBounds</code> will result in an
162 // This property is new in Chrome 36.
163 BoundsSpecification? innerBounds;
165 // Used to specify the initial position, initial size and constraints of the
166 // window (including window decorations such as the title bar and frame).
167 // If an <code>id</code> is also specified and a window with a matching
168 // <code>id</code> has been shown before, the remembered bounds will be used
171 // Note that the padding between the inner and outer bounds is determined by
172 // the OS. Therefore setting the same bounds property for both the
173 // <code>innerBounds</code> and <code>outerBounds</code> will result in an
176 // This property is new in Chrome 36.
177 BoundsSpecification? outerBounds;
179 // Default width of the window.
180 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? defaultWidth;
182 // Default height of the window.
183 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? defaultHeight;
185 // Default X coordinate of the window.
186 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? defaultLeft;
188 // Default Y coordinate of the window.
189 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? defaultTop;
191 // Width of the window.
192 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? width;
194 // Height of the window.
195 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? height;
197 // X coordinate of the window.
198 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? left;
200 // Y coordinate of the window.
201 [nodoc, deprecated="Use $(ref:BoundsSpecification)."] long? top;
203 // Minimum width of the window.
204 [deprecated="Use innerBounds or outerBounds."] long? minWidth;
206 // Minimum height of the window.
207 [deprecated="Use innerBounds or outerBounds."] long? minHeight;
209 // Maximum width of the window.
210 [deprecated="Use innerBounds or outerBounds."] long? maxWidth;
212 // Maximum height of the window.
213 [deprecated="Use innerBounds or outerBounds."] long? maxHeight;
215 // Type of window to create.
216 [nodoc] WindowType? type;
218 // Frame type: <code>none</code> or <code>chrome</code> (defaults to
219 // <code>chrome</code>). For <code>none</code>, the
220 // <code>-webkit-app-region</code> CSS property can be used to apply
221 // draggability to the app's window. <code>-webkit-app-region: drag</code>
222 // can be used to mark regions draggable. <code>no-drag</code> can be used
223 // to disable this style on nested elements.
225 // Use of <code>FrameOptions</code> is new in M36.
226 (DOMString or FrameOptions)? frame;
228 // Size and position of the content in the window (excluding the titlebar).
229 // If an id is also specified and a window with a matching id has been shown
230 // before, the remembered bounds of the window will be used instead.
231 [deprecated="Use innerBounds or outerBounds."] ContentBounds? bounds;
233 // Enable window background transparency.
234 // Only supported in ash. Requires app.window.alpha API permission.
235 boolean? alphaEnabled;
237 // The initial state of the window, allowing it to be created already
238 // fullscreen, maximized, or minimized. Defaults to 'normal'.
241 // If true, the window will be created in a hidden state. Call show() on
242 // the window to show it once it has been created. Defaults to false.
245 // If true, the window will be resizable by the user. Defaults to true.
248 // By default if you specify an id for the window, the window will only be
249 // created if another window with the same id doesn't already exist. If a
250 // window with the same id already exists that window is activated instead.
251 // If you do want to create multiple windows with the same id, you can
252 // set this property to false.
253 [deprecated="Multiple windows with the same id is no longer supported."] boolean? singleton;
255 // If true, the window will stay above most other windows. If there are
256 // multiple windows of this kind, the currently focused window will be in
257 // the foreground. Requires the <code>"alwaysOnTopWindows"</code>
258 // permission. Defaults to false.
260 // Call <code>setAlwaysOnTop()</code> on the window to change this property
262 boolean? alwaysOnTop;
264 // If true, the window will be focused when created. Defaults to true.
268 // Called in the creating window (parent) before the load event is called in
269 // the created window (child). The parent can set fields or functions on the
270 // child usable from onload. E.g. background.js:
272 // <code>function(createdWindow) { createdWindow.contentWindow.foo =
273 // function () { }; };</code>
277 // <code>window.onload = function () { foo(); }</code>
278 callback CreateWindowCallback =
279 void ([instanceOf=AppWindow] object createdWindow);
281 [noinline_doc] dictionary AppWindow {
285 // Fullscreens the window.
287 // The user will be able to restore the window by pressing ESC. An
288 // application can prevent the fullscreen state to be left when ESC is
289 // pressed by requesting the <b>overrideEscFullscreen</b> permission and
290 // canceling the event by calling .preventDefault(), like this:
292 // <code>window.onKeyDown = function(e) { if (e.keyCode == 27 /* ESC */) {
293 // e.preventDefault(); } };</code>
294 static void fullscreen();
296 // Is the window fullscreen?
297 static boolean isFullscreen();
299 // Minimize the window.
300 static void minimize();
302 // Is the window minimized?
303 static boolean isMinimized();
305 // Maximize the window.
306 static void maximize();
308 // Is the window maximized?
309 static boolean isMaximized();
311 // Restore the window, exiting a maximized, minimized, or fullscreen state.
312 static void restore();
314 // Move the window to the position (|left|, |top|).
315 static void moveTo(long left, long top);
317 // Resize the window to |width|x|height| pixels in size.
318 static void resizeTo(long width, long height);
320 // Draw attention to the window.
321 static void drawAttention();
323 // Clear attention to the window.
324 static void clearAttention();
329 // Show the window. Does nothing if the window is already visible.
330 // Focus the window if |focused| is set to true or omitted.
331 static void show(optional boolean focused);
333 // Hide the window. Does nothing if the window is already hidden.
336 // Get the window's inner bounds as a $(ref:ContentBounds) object.
337 [nocompile, deprecated="Use innerBounds or outerBounds."] static ContentBounds getBounds();
339 // Set the window's inner bounds.
340 [nocompile, deprecated="Use innerBounds or outerBounds."] static void setBounds(ContentBounds bounds);
342 // Set the app icon for the window (experimental).
343 // Currently this is only being implemented on Ash.
344 // TODO(stevenjb): Investigate implementing this on Windows and OSX.
345 [nodoc] static void setIcon(DOMString iconUrl);
347 // Set a badge icon for the window.
348 // TODO(benwells): Document this properly before going to stable.
349 [nodoc] static void setBadgeIcon(DOMString iconUrl);
351 // Clear the current for the window.
352 // TODO(benwells): Document this properly before going to stable.
353 [nodoc] static void clearBadge();
355 // Is the window always on top?
356 static boolean isAlwaysOnTop();
358 // Accessors for testing.
359 [nodoc] boolean hasFrameColor;
360 [nodoc] long activeFrameColor;
361 [nodoc] long inactiveFrameColor;
362 [nodoc] boolean? firstShowHasHappened;
364 // Set whether the window should stay above most other windows. Requires the
365 // <code>"alwaysOnTopWindows"</code> permission.
366 static void setAlwaysOnTop(boolean alwaysOnTop);
368 // Can the window use alpha transparency?
369 // TODO(jackhou): Document this properly before going to stable.
370 [nodoc] static boolean alphaEnabled();
372 // The JavaScript 'window' object for the created child.
373 [instanceOf=Window] object contentWindow;
375 // The id the window was created with.
378 // The position, size and constraints of the window's content, which does
379 // not include window decorations.
380 // This property is new in Chrome 36.
383 // The position, size and constraints of the window, which includes window
384 // decorations, such as the title bar and frame.
385 // This property is new in Chrome 36.
389 interface Functions {
390 // The size and position of a window can be specified in a number of
391 // different ways. The most simple option is not specifying anything at
392 // all, in which case a default size and platform dependent position will
395 // To set the position, size and constraints of the window, use the
396 // <code>innerBounds</code> or <code>outerBounds</code> properties. Inner
397 // bounds do not include window decorations. Outer bounds include the
398 // window's title bar and frame. Note that the padding between the inner and
399 // outer bounds is determined by the OS. Therefore setting the same property
400 // for both inner and outer bounds is considered an error (for example,
401 // setting both <code>innerBounds.left</code> and
402 // <code>outerBounds.left</code>).
404 // To automatically remember the positions of windows you can give them ids.
405 // If a window has an id, This id is used to remember the size and position
406 // of the window whenever it is moved or resized. This size and position is
407 // then used instead of the specified bounds on subsequent opening of a
408 // window with the same id. If you need to open a window with an id at a
409 // location other than the remembered default, you can create it hidden,
410 // move it to the desired location, then show it.
411 static void create(DOMString url,
412 optional CreateWindowOptions options,
413 optional CreateWindowCallback callback);
415 // Returns an $(ref:AppWindow) object for the
416 // current script context (ie JavaScript 'window' object). This can also be
417 // called on a handle to a script context for another page, for example:
418 // otherWindow.chrome.app.window.current().
419 [nocompile] static AppWindow current();
420 [nocompile, nodoc] static void initializeAppWindow(object state);
422 // Gets an array of all currently created app windows. This method is new in
424 [nocompile] static AppWindow[] getAll();
426 // Gets an $(ref:AppWindow) with the given id. If no window with the given id
427 // exists null is returned. This method is new in Chrome 33.
428 [nocompile] static AppWindow get(DOMString id);
432 // Fired when the window is resized.
433 [nocompile] static void onBoundsChanged();
435 // Fired when the window is closed. Note, this should be listened to from
436 // a window other than the window being closed, for example from the
437 // background page. This is because the window being closed will be in the
438 // process of being torn down when the event is fired, which means not all
439 // APIs in the window's script context will be functional.
440 [nocompile] static void onClosed();
442 // Fired when the window is fullscreened.
443 [nocompile] static void onFullscreened();
445 // Fired when the window is maximized.
446 [nocompile] static void onMaximized();
448 // Fired when the window is minimized.
449 [nocompile] static void onMinimized();
451 // Fired when the window is restored from being minimized or maximized.
452 [nocompile] static void onRestored();
454 // Fired when the window's ability to use alpha transparency changes.
455 [nocompile, nodoc] static void onAlphaEnabledChanged();
457 // Event for testing. Lets tests wait until a window has been shown.
458 [nocompile, nodoc] static void onWindowFirstShown();