nsIAppShellService

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

Attributes

Constants

Methods

Close a window.

void closeTopLevelWindow(
  in nsIXULWindow aWindow
);

Parameters

aWindow

A window.

Creates a hidden window.

void createHiddenWindow(
  in nsIAppShell aAppShell
);

Parameters

aAppShell

A widget "appshell" (event processor) to associate with the new window.

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

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.

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.

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.

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.

void exitLastWindowClosingSurvivalArea();

Parameters

None.

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.

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

void hideSplashScreen();

Parameters

None.

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.

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.

void registerTopLevelWindow(
  in nsIXULWindow aWindow
);

Parameters

aWindow

The window to register.

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

void run();

Parameters

None.

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.

void unregisterTopLevelWindow(
  in nsIXULWindow aWindow
);

Parameters

aWindow

The window to register.

See also

• nsIAppShell