xpfe/appshell/nsIAppShellService.idlScriptable
Provides the AppShellService.
Inherits from: nsISupports Last changed in Gecko 8.0 (Firefox 8.0 / Thunderbird 8.0 / SeaMonkey 2.5)

Implemented by: @mozilla.org/appshell/appShellService;1 as a service:

var appShellService = Components.classes["@mozilla.org/appshell/appShellService;1"]
                      .getService(Components.interfaces.nsIAppShellService);

Method overview

void closeTopLevelWindow(in nsIXULWindow aWindow); Obsolete since Gecko 1.8
void createHiddenWindow(in nsIAppShell aAppShell); Native code only!
boolean createStartupState(in long aWindowWidth, in long aWindowHeight); Obsolete since Gecko 1.8
nsIXULWindow createTopLevelWindow(in nsIXULWindow aParent, in nsIURI aUrl, in PRUint32 aChromeMask, in long aInitialWidth, in long aInitialHeight, in nsIAppShell aAppShell);
nsIWebNav createWindowlessBrowser (in bool aIsChrome)
void destroyHiddenWindow();
void doProfileStartup(in nsICmdLineService aCmdLineService, in boolean canInteract); Obsolete since Gecko 1.8
void ensure1Window(in nsICmdLineService aCmdLineService); Obsolete since Gecko 1.8
void enterLastWindowClosingSurvivalArea(); Obsolete since Gecko 1.8
void exitLastWindowClosingSurvivalArea(); Obsolete since Gecko 1.8
void getHiddenWindowAndJSContext(out nsIDOMWindow aHiddenDOMWindow, out JSContext aJSContext); Native code only!
void hideSplashScreen(); Obsolete since Gecko 1.8
void initialize(in nsICmdLineService aCmdLineService, in nsISupports nativeAppSupportOrSplashScreen); Obsolete since Gecko 1.8
void quit(in PRUint32 aFerocity); Obsolete since Gecko 1.8
void registerTopLevelWindow(in nsIXULWindow aWindow);
void run(); Obsolete since Gecko 1.8
void topLevelWindowIsModal(in nsIXULWindow aWindow, in boolean aModal); Obsolete since Gecko 1.9.1
void unregisterTopLevelWindow(in nsIXULWindow aWindow);

Note: Prior to Gecko 8.0, all references to nsIDOMWindow used in this interface were nsIDOMWindowInternal.

Attributes

Attribute Type Description
applicationProvidedHiddenWindow boolean Return true if the application hidden window was provided by the application. If it was not, the default hidden window was used. This will usually be false on all non-mac platforms. Read only.
hiddenDOMWindow nsIDOMWindow Return the (singleton) application hidden window, automatically created and maintained by this AppShellService. Read only.
hiddenWindow nsIXULWindow Return the (singleton) application hidden window, automatically created and maintained by this AppShellService. Read only.
nativeAppSupport nsINativeAppSupport Getter for "native application support." Read only. Obsolete since Gecko 1.8

Constants

Constant Value Description
SIZE_TO_CONTENT -1 Create a window, which will be initially invisible.
eConsiderQuit 1 Attempt to quit if all windows are closed. Obsolete since Gecko 1.8
eAttemptQuit 2 Try to close all windows, then quit if successful. Obsolete since Gecko 1.8
eForceQuit 3 Force all windows to close, then quit. Obsolete since Gecko 1.8

Methods

closeTopLevelWindow()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Close a window.

void closeTopLevelWindow(
  in nsIXULWindow aWindow
);
Parameters
aWindow
A window.

Native code only!

createHiddenWindow

Creates a hidden window.

void createHiddenWindow(
  in nsIAppShell aAppShell
);
Parameters
aAppShell
A widget "appshell" (event processor) to associate with the new window.

createStartupState()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Creates the initial state of the application by launching tasks specfied by "general.startup.*" prefs.

Note: SIZE_TO_CONTENT may be used for width or height.

boolean createStartupState(
  in long aWindowWidth,
  in long aWindowHeight
);
Parameters
aWindowWidth
The width to make the initial window(s) opened.
aWindowHeight
The height to make the initial window(s) opened.
Return value

true if a window was opened.

createTopLevelWindow()

This method creates a window, which will be initially invisible.

nsIXULWindow createTopLevelWindow(
  in nsIXULWindow aParent,
  in nsIURI aUrl,
  in boolean aShowWindow,
  in boolean aLoadDefaultPage,
  in PRUint32 aChromeMask,
  in long aInitialWidth,
  in long aInitialHeight,
  in nsIAppShell aAppShell
);
Parameters
aParent
The parent window. Can be null.
aUrl
The contents of the new window.
aShowWindow Obsolete since Gecko 1.8
The window remains invisible if PR_FALSE.
aLoadDefaultPage Obsolete since Gecko 1.8
Controls whether the window should try to load a default content page on its own.
aChromeMask
Chrome flags affecting the kind of OS border given to the window. (See nsIBrowserWindow for bit/flag definitions).
aInitialWidth
Width, in pixels, of the window. Width of window at creation. Can be overridden by the "width" tag in the XUL. Set to NS_SIZETOCONTENT to force the window to wrap to its contents.
aInitialHeight
Height, in pixels, of the window. Height of window at creation. Can be overridden by the "height" tag in the XUL. Set to NS_SIZETOCONTENT to force the window to wrap to its contents.
aAppShell
A widget "appshell" (event processor) to associate with the new window.
Return value

Returns the newly created window.

destroyHiddenWindow()

Destroys a hidden window.

void destroyHiddenWindow();
Parameters

None.

doProfileStartup()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Starts up the profile manager with the given arguments.

void doProfileStartup(
  in nsICmdLineService aCmdLineService,
  in boolean canInteract
);
Parameters
aCmdLineService
The arguments given to the program.
canInteract
If false and UI is needed, will fail.

ensure1Window()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Ensures that at least one window exists after creating the startup state. If one has not been made, this will create a browser window.

void ensure1Window(
  in nsICmdLineService aCmdLineService
);
Parameters
aCmdLineService
The command line from which startup args can be read.

enterLastWindowClosingSurvivalArea()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

During application startup (and at other times!) we may temporarily encounter a situation where all application windows will be closed but we do not want to take this as a signal to quit the application. Bracket the code where the last window could close with these. (And at application startup, on platforms that do not normally quit when the last window has closed, call Enter once, but not Exit)

void enterLastWindowClosingSurvivalArea();
Parameters

None.

exitLastWindowClosingSurvivalArea()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

void exitLastWindowClosingSurvivalArea();
Parameters

None.

Native code only!

getHiddenWindowAndJSContext

Return the (singleton) application hidden window as an nsIDOMWindow, and, the corresponding JavaScript context pointer. This is useful if you'd like to subsequently call OpenDialog on the hidden window.

void getHiddenWindowAndJSContext(
  out nsIDOMWindow aHiddenDOMWindow,
  out JSContext aJSContext
);
Parameters
aHiddenDOMWindow
The hidden window QueryInterface'd to type nsIDOMWindow.
aJSContext
The corresponding JavaScript context.

hideSplashScreen()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Remove the splash screen (if visible). This need be called only once per application session.

void hideSplashScreen();
Parameters

None.

initialize()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Required initialization routine.

void initialize(
  in nsICmdLineService aCmdLineService,
  in nsISupports nativeAppSupportOrSplashScreen
);
Parameters
aCmdLineService
Is stored and passed to appshell components as they are initialized.
nativeAppSupportOrSplashScreen
Is an object that can be QueryInterface'd to either an nsINativeAppSupport or nsISplashScreen; this object will be used to implement HideSplashScreen.

quit()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Exit the event loop, shut down the app.

void quit(
  in PRUint32 aFerocity
);
Parameters
aFerocity
One of the e* constants.

createWindowlessBrowser()

This method creates a browser that does not have a window. If the browser is exited, this windowless browser will not prevent Firefox from exiting. E10s notes: The browser is created in process. To get an out of process element you want to communicate with via message manager, then append a browser element with remote attribute set to true. Follow this bug - Bugzilla - Bug 1280028

nsIWebNav createWindowlessBrowser(
  in bool aIsChrome
);
var webnav = Services.appShell.createWindowlessBrowser(true);
var docshell = webnav.QueryInterface(Ci.nsIInterfaceRequestor).getInterface(Ci.nsIDocShell);
var systemPrincipal = Cc["@mozilla.org/systemprincipal;1"].createInstance(Ci.nsIPrincipal);
docshell.createAboutBlankContentViewer(systemPrincipal);
var contentWindow = docshell.contentViewer.DOMDocument.defaultView;

// when you are done with it, destroy it
if (webnav.close) { webnav.close() }; // only available in Firefox 46+, and is needed for good measure
webnav = null; // in Firefox <= 45 setting to null will cause it to get GC'ed which will destroy it

 

registerTopLevelWindow()

Add a window to the application's registry of windows. These windows are generally shown in the Windows taskbar, and the application knows it can not quit until it is out of registered windows.

Note: When this method is successful, it fires the global notification "xul-window-registered"

void registerTopLevelWindow(
  in nsIXULWindow aWindow
);
Parameters
aWindow
The window to register.

run()

Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Runs an application event loop: normally the main event pump which defines the lifetime of the application.

void run();
Parameters

None.

topLevelWindowIsModal()

Obsolete since Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

The appshell service needs to be informed of modal XUL windows currently open. Call this method as a window becomes modal or as it becomes nonmodal.

void topLevelWindowIsModal(
  in nsIXULWindow aWindow,
  in boolean aModal
);
Parameters
aWindow
The window to register.
aModal
true if aWindow is becoming modal or false if aWindow is becoming nonmodal (or being closed).

unregisterTopLevelWindow()

Remove a window from the application's window registry.

Note: This method will not automatically attempt to quit the application when the last window is unregistered. For that, see Quit().

void unregisterTopLevelWindow(
  in nsIXULWindow aWindow
);
Parameters
aWindow
The window to register.

See also