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 nsIAppWindow;
   9 interface nsIWindowlessBrowser;
  10 interface nsIURI;
  11 interface mozIDOMWindowProxy;
  12 interface nsIAppShell;
  13 interface nsIRemoteTab;
  14
  15 [ptr] native JSContext(JSContext);
  16
  17 %{C++
  18 #include "js/TypeDecls.h"
  19 %}
  20
  21 [scriptable, uuid(19266025-354c-4bb9-986b-3483b2b1cdef)]
  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 nsIWebBrowserChrome 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    */
  40   const long SIZE_TO_CONTENT = -1;
  41   nsIAppWindow createTopLevelWindow(in nsIAppWindow aParent,
  42                                     in nsIURI aUrl,
  43                                     in uint32_t aChromeMask,
  44                                     in long aInitialWidth,
  45                                     in long aInitialHeight);
  46
  47   /**
  48    * This is the constructor for creating an invisible DocShell.
  49    * It is used to simulate DOM windows without an actual physical
  50    * representation.
  51    * @param aIsChrome Set true if you want to use it for chrome content.
  52    * @param aChromeMask Used to specify chrome flags that should be set on the
  53    *                    window. See nsIWebBrowserChrome for flag definitions.
  54    */
  55   nsIWindowlessBrowser createWindowlessBrowser([optional] in bool aIsChrome,
  56                                                [optional] in uint32_t aChromeMask);
  57
  58   [noscript]
  59   void createHiddenWindow();
  60
  61   void destroyHiddenWindow();
  62
  63   /**
  64    * B2G multi-screen support. When open another top-level window on b2g,
  65    * a screen ID is needed for identifying which screen this window is
  66    * opened to.
  67    * @param aScreenId Differentiate screens of windows. It is platform-
  68    *                  specific due to the hardware limitation for now.
  69    */
  70   [noscript]
  71   void setScreenId(in uint32_t aScreenId);
  72
  73   /**
  74    * Return the (singleton) application hidden window, automatically created
  75    * and maintained by this AppShellService.
  76    * @param aResult the hidden window.  Do not unhide hidden window.
  77    *                Do not taunt hidden window.
  78    */
  79   readonly attribute nsIAppWindow hiddenWindow;
  80
  81   /**
  82    * Return the (singleton) application hidden window, automatically created
  83    * and maintained by this AppShellService.
  84    * @param aResult the hidden window.  Do not unhide hidden window.
  85    *                Do not taunt hidden window.
  86    */
  87   readonly attribute mozIDOMWindowProxy hiddenDOMWindow;
  88
  89   /**
  90    * Return true if the application hidden window was provided by the
  91    * application. If it wasn't, the default hidden window was used. This will
  92    * usually be false on all non-mac platforms.
  93    */
  94   readonly attribute boolean applicationProvidedHiddenWindow;
  95
  96   /**
  97    * Add a window to the application's registry of windows.  These windows
  98    * are generally shown in the Windows taskbar, and the application
  99    * knows it can't quit until it's out of registered windows.
 100    * @param aWindow the window to register
 101    * @note When this method is successful, it fires the global notification
 102    *       "xul-window-registered"
 103    */
 104   void registerTopLevelWindow(in nsIAppWindow aWindow);
 105
 106   /**
 107    * Remove a window from the application's window registry. Note that
 108    * this method won't automatically attempt to quit the app when
 109    * the last window is unregistered. For that, see Quit().
 110    * @param aWindow you see the pattern
 111    */
 112   void unregisterTopLevelWindow(in nsIAppWindow aWindow);
 113
 114   /**
 115    * Whether the hidden window has been lazily created.
 116    */
 117   readonly attribute boolean hasHiddenWindow;
 118
 119   /**
 120    * Start/stop tracking lags in the event loop.
 121    * If the event loop gets unresponsive, a "event-loop-lag" notification
 122    * is sent. Note that calling `startEventLoopLagTracking` when tracking
 123    * is already enabled has no effect.
 124    * @return true if tracking succeeded.
 125    */
 126   bool startEventLoopLagTracking();
 127   void stopEventLoopLagTracking();
 128 };