xpfe/appshell/nsIAppShellService.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIXULWindow;
   9 interface nsIWebNavigation;
  10 interface nsIURI;
  11 interface nsIDOMWindow;
  12 interface nsIAppShell;
  13 interface nsITabParent;
  14
  15 [ptr] native JSContext(JSContext);
  16
  17 %{C++
  18 #include "js/TypeDecls.h"
  19 %}
  20
  21 [scriptable, uuid(41a2f0c6-3ca1-44f9-8efa-744a43aa399d)]
  22 interface nsIAppShellService : nsISupports
  23 {
  24   /**
  25    * Create a window, which will be initially invisible.
  26    * @param aParent the parent window.  Can be null.
  27    * @param aUrl the contents of the new window.
  28    * @param aChromeMask chrome flags affecting the kind of OS border
  29    *                    given to the window. see nsIBrowserWindow for
  30    *                    bit/flag definitions.
  31    * @param aCallbacks interface providing C++ hooks for window initialization
  32    *                   before the window is made visible.  Can be null.
  33    *                   Deprecated.
  34    * @param aInitialWidth width, in pixels, of the window.  Width of window
  35    *                      at creation.  Can be overridden by the "width"
  36    *                      tag in the XUL.  Set to NS_SIZETOCONTENT to force
  37    *                      the window to wrap to its contents.
  38    * @param aInitialHeight like aInitialWidth, but subtly different.
  39    * @param aOpeningTab The TabParent that requested that this window be opened.
  40    *                    Can be left null.
  41    */
  42   const long SIZE_TO_CONTENT = -1;
  43   nsIXULWindow createTopLevelWindow(in nsIXULWindow aParent,
  44                                     in nsIURI aUrl,
  45                                     in uint32_t aChromeMask,
  46                                     in long aInitialWidth,
  47                                     in long aInitialHeight,
  48                                     in nsITabParent aOpeningTab);
  49
  50   /**
  51    * This is the constructor for creating an invisible DocShell.
  52    * It is used to simulate DOM windows without an actual physical
  53    * representation.
  54    * @param aIsChrome Set true if you want to use it for chrome content.
  55    */
  56   nsIWebNavigation createWindowlessBrowser([optional] in bool aIsChrome);
  57
  58   [noscript]
  59   void createHiddenWindow();
  60
  61   void destroyHiddenWindow();
  62
  63   /**
  64    * Return the (singleton) application hidden window, automatically created
  65    * and maintained by this AppShellService.
  66    * @param aResult the hidden window.  Do not unhide hidden window.
  67    *                Do not taunt hidden window.
  68    */
  69   readonly attribute nsIXULWindow hiddenWindow;
  70
  71   /**
  72    * Return the (singleton) application hidden window, automatically created
  73    * and maintained by this AppShellService.
  74    * @param aResult the hidden window.  Do not unhide hidden window.
  75    *                Do not taunt hidden window.
  76    */
  77   readonly attribute nsIDOMWindow hiddenDOMWindow;
  78
  79   /**
  80    * Return the (singleton) application hidden private window, automatically
  81    * created and maintained by this AppShellService.  This window is created
  82    * in private browsing mode.
  83    * @param aResult the hidden private window.  Do not unhide hidden window.
  84    *                Do not taunt hidden window.
  85    */
  86   readonly attribute nsIXULWindow hiddenPrivateWindow;
  87
  88   /**
  89    * Return the (singleton) application hidden private window, automatically
  90    * created and maintained by this AppShellService.  This window is created
  91    * in private browsing mode.
  92    * @param aResult the hidden private window.  Do not unhide hidden window.
  93    *                Do not taunt hidden window.
  94    */
  95   readonly attribute nsIDOMWindow hiddenPrivateDOMWindow;
  96
  97   /**
  98    * Return the (singleton) application hidden window as an nsIDOMWindow,
  99    * and, the corresponding JavaScript context pointer.  This is useful
 100    * if you'd like to subsequently call OpenDialog on the hidden window.
 101    * @aHiddenDOMWindow the hidden window QI'd to type nsIDOMWindow
 102    * @aJSContext       the corresponding JavaScript context
 103    */
 104   [noscript]
 105   void getHiddenWindowAndJSContext(out nsIDOMWindow aHiddenDOMWindow,
 106                                    out JSContext aJSContext);
 107
 108   /**
 109    * Return true if the application hidden window was provided by the
 110    * application. If it wasn't, the default hidden window was used. This will
 111    * usually be false on all non-mac platforms.
 112    */
 113   readonly attribute boolean applicationProvidedHiddenWindow;
 114
 115   /**
 116    * Add a window to the application's registry of windows.  These windows
 117    * are generally shown in the Windows taskbar, and the application
 118    * knows it can't quit until it's out of registered windows.
 119    * @param aWindow the window to register
 120    * @note When this method is successful, it fires the global notification
 121    *       "xul-window-registered"
 122    */
 123   void registerTopLevelWindow(in nsIXULWindow aWindow);
 124
 125   /**
 126    * Remove a window from the application's window registry. Note that
 127    * this method won't automatically attempt to quit the app when
 128    * the last window is unregistered. For that, see Quit().
 129    * @param aWindow you see the pattern
 130    */
 131   void unregisterTopLevelWindow(in nsIXULWindow aWindow);
 132
 133   /**
 134    * Whether the hidden private window has been lazily created.
 135    */
 136   [noscript]
 137   readonly attribute boolean hasHiddenPrivateWindow;
 138
 139   /**
 140    * Start/stop tracking lags in the event loop.
 141    * If the event loop gets unresponsive, a "event-loop-lag" notification
 142    * is sent. Note that calling `startEventLoopLagTracking` when tracking
 143    * is already enabled has no effect.
 144    * @return true if tracking succeeded.
 145    */
 146   bool startEventLoopLagTracking();
 147   void stopEventLoopLagTracking();
 148 };