nsIAppStartup

This interface is intended to be used as application startup service. It also helps in quitting applications as well.
1.0
39
Introduced
Gecko 1.8
Inherits from: nsISupports Last changed in Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6)

Implemented by: @mozilla.org/toolkit/app-startup;1. To use the service:

var appStartup = Components.classes["@mozilla.org/toolkit/app-startup;1"]
                 .getService(Components.interfaces.nsIAppStartup);

Method overview

void createHiddenWindow();
boolean createStartupState(in long aWindowWidth, in long aWindowHeight); Obsolete since Gecko 1.9.1
void destroyHiddenWindow();
void doProfileStartup(in nsICmdLineService aCmdLineService, in boolean canInteract); Obsolete since Gecko 1.9.1
void ensure1Window(in nsICmdLineService aCmdLineService); Obsolete since Gecko 1.9.1
void enterLastWindowClosingSurvivalArea();
void exitLastWindowClosingSurvivalArea();
void getStartupInfo();
void hideSplashScreen(); Obsolete since Gecko 1.9.1
void initialize(in nsISupports nativeAppSupportOrSplashScreen); Obsolete since Gecko 1.9.1
void quit(in PRUint32 aMode);
void restartInSafeMode(in PRUint32 aQuitMode);
void run();

Attributes

Attribute Type Description
interrupted boolean true if the startup process was interrupted by an interactive prompt. This can be used, for example, when doing performance testing of the startup process to discount numbers for tests that were interrupted by a user prompt.
nativeAppSupport nsINativeAppSupport Getter for "native application support." Read only. Obsolete since Gecko 1.9.1

Constants

The following flags may be passed as the aMode parameter to the quit() method. One and only one of the "Quit" flags must be specified. The eRestart flag may be bit-wise combined with one of the "Quit" flags to cause the application to restart after it quits.

Constant Value Description
eConsiderQuit 0x01 Attempt to quit if all windows are closed.
eAttemptQuit 0x02 Try to close all windows, then quit if successful.
eForceQuit 0x03 Force all windows to close, then quit.
eRestart 0x10 Restart the application after quitting. The application will be restarted with the same profile and an empty command line.
eRestarti386 0x20 When restarting attempt to start in the i386 architecture. Only supported on OSX.
eRestartx86_64 0x40 When restarting attempt to start in the x86_64 architecture. Only supported on OSX.
eRestartNotSameProfile 0x100 Restart the application after quitting. The application will be restarted with an empty command line and the normal profile selection process will take place on startup.

Methods

createHiddenWindow()

Create the hidden window.

void createHiddenWindow();
Parameters

None.

createStartupState()

Obsolete since Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.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.

destroyHiddenWindow()

Destroys the hidden window. This will have no effect if the hidden window has not yet been created.

void destroyHiddenWindow();
Parameters

None.

doProfileStartup()

Obsolete since Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.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.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.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()

Serves for situations when all application windows will be closed but we don't want to take this as a signal to quit the application. Bracket the code where the last window could close with these.

void enterLastWindowClosingSurvivalArea();
Parameters

None.

exitLastWindowClosingSurvivalArea()

This method serves for situations when all application windows will be closed but we don't want to take this as a signal to quit the application. Bracket the code where the last window could close with these.

void exitLastWindowClosingSurvivalArea();
Parameters

None.

getStartupInfo()

Returns a JavaScript object with events from startup and the timestamps indicating when they occurred.

Parameters

None.

Return value

A JavaScript object with the following fields. Keys are the event names and their values are the times. Events that didn't occur are not in the object.

Event identifier (key) Description
main

Time at which main application core was loaded.

Note: Only available with libxul builds.
firstPaint

Time  the first paint occurred.

Note: Only available with libxul builds.
sessionRestored Time  session restore finished.
Example

This example logs startup time information to the console.

var aConsoleService = Components.classes["@mozilla.org/consoleservice;1"]
                      .getService(Components.interfaces.nsIConsoleService);
var startupInfo = Components.classes["@mozilla.org/toolkit/app-startup;1"]
                      .getService(Ci.nsIAppStartup_MOZILLA_2_0).getStartupInfo();
var keys = Object.keys(startupInfo);
keys.sort(function(a, b) { return startupInfo[a] - startupInfo[b]; });
for each (var name in keys) {
  aConsoleService.logStringMessage(name + ": " + startupInfo[name]);
} 

To calculate how long startup took, compute the difference between the event's timestamp and the timestamp of the process event.

hideSplashScreen()

Obsolete since Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.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.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

Required initialization routine.

void initialize(
  in nsISupports nativeAppSupportOrSplashScreen
);
Parameters
nativeAppSupportOrSplashScreen
Is an object that can be QI'd to either an nsINativeAppSupport or nsISplashScreen; this object will be used to implement HideSplashScreen.

quit()

Exit the event loop, and shut down the application.

void quit(
  in PRUint32 aMode
);
Parameters
aMode
This parameter modifies how the application is shutdown, and it is constructed from the constants defined above.

restartInSafeMode()

Restart the application in safe mode.

void quit(
  in PRUint32 aQuitMode
);
Parameters
aQuitMode
This parameter modifies how the app is shutdown.

run()

Runs an application event loop: normally the main event pump which defines the lifetime of the application. If there are no windows open and no outstanding calls to enterLastWindowClosingSurvivalArea() this method will exit immediately.

void run();
Parameters

None.

Return value

Returns NS_SUCCESS_RESTART_APP code. This return code indicates that the application should be restarted because quit was called with the eRestart flag.

See also

Document Tags and Contributors

 Contributors to this page: johankj, Sheppy, mreid, trevorh, Arehman4
 Last updated by: johankj,