widget/public/nsIAppShell.idlNot scriptable
Interface for the native event system layer. This interface is designed to be used on the main application thread only.
Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

Method overview

void Create(inout int argc, inout string argv); Obsolete since Gecko 1.9
void DispatchNativeEvent(in PRBool aRealEvent, in voidPtr aEvent); Obsolete since Gecko 1.9
void exit();
void favorPerformanceHint(in boolean favorPerfOverStarvation, in unsigned long starvationDelay);
void GetNativeEvent(in PRBoolRef aRealEvent, in voidPtrRef aEvent); Obsolete since Gecko 1.9
void ListenToEventQueue(in nsIEventQueue aQueue, in PRBool aListen); Obsolete since Gecko 1.9
void resumeNative();
void run();
void runInStableState(in nsIRunnable aRunnable);
void Spindown(); Obsolete since Gecko 1.9
void Spinup(); Obsolete since Gecko 1.9
void suspendNative();

Attributes

Attribute Type Description
eventloopNestingLevel unsigned long The current event loop nesting level. Read only.

Methods

Create()

Obsolete since Gecko 1.9 (Firefox 3)

Creates an application shell.

void Create(
  inout int argc,
  inout string argv
);
Parameters
argc
The number of parameters passed in on the command line.
argv
A direct reference to the parameter array.

DispatchNativeEvent()

Obsolete since Gecko 1.9 (Firefox 3)

After event dispatch execute app specific code.

void DispatchNativeEvent(
  in PRBool aRealEvent,
  in voidPtr aEvent
);
Parameters
aRealEvent
Event is real or a null placeholder (Macintosh).
aEvent
Void pointer to native event structure.

exit()

Exit the handle event loop.

void exit();
Parameters

None.

favorPerformanceHint()

Give hint to native event queue notification mechanism. If the native platform needs to tradeoff performance vs. native event starvation this hint tells the native dispatch code which to favor. The default is to prevent native event starvation.

Calls to this function may be nested. When the number of calls that pass PR_TRUE is subtracted from the number of calls that pass PR_FALSE is greater than 0, performance is given precedence over preventing event starvation.

void favorPerformanceHint(
  in boolean favorPerfOverStarvation,
  in unsigned long starvationDelay
);
Parameters
favorPerfOverStarvation
true to favor event performance over event starvation, false to favor event starvation over event performance.
starvationDelay
Is only used when favorPerfOverStarvation is PR_FALSE. It is the amount of time in milliseconds to wait before the PR_FALSE actually takes effect.

GetNativeEvent()

Obsolete since Gecko 1.9 (Firefox 3)

After event dispatch execute app specific code.

void GetNativeEvent(
  in PRBoolRef aRealEvent,
  in voidPtrRef aEvent
);
Parameters
aRealEvent
Event is real or a null placeholder (Macintosh).
aEvent
Void pointer to native event structure.

ListenToEventQueue()

Obsolete since Gecko 1.9 (Firefox 3)

An event queue has been created or destroyed. Hook or unhook it from your system, as necessary.

void ListenToEventQueue(
  in nsIEventQueue aQueue,
  in PRBool aListen
);
Parameters
aQueue
The queue in question.
aListen
PR_TRUE for a new queue wanting hooking up. PR_FALSE for a queue wanting to be unhooked.

resumeNative()

Resumes the use of additional platform-specific methods to run() Gecko events on the main application thread. Calls to suspendNative() and resumeNative may be nested. On some platforms this will be a no-op.

void resumeNative();
Parameters

None.

run()

Enter an event loop. Do not leave until exit() is called.

void run();
Parameters

None.

runInStableState()

Allows running of a "synchronous section", in the form of an nsIRunnable once the event loop has reached a "stable state". A stable state is reached when the currently executing task/event has finished, (see: webappapis.html#synchronous-section). In practice this runs aRunnable once the currently executing event finishes. If called multiple times per task/event, all the runnables will be executed, in the order in which runInStableState was called.

void runInStableState(
  in nsIRunnable aRunnable
);
Parameters
aRunnable
An nsIRunnable to run.

Spindown()

Obsolete since Gecko 1.9 (Firefox 3)

Prepare to stop processing events.

void Spindown();
Parameters

None.

Spinup()

Obsolete since Gecko 1.9 (Firefox 3)

Prepare to process events.

void Spinup();
Parameters

None.

suspendNative()

Suspends the use of additional platform-specific methods (besides the nsIAppShell->run() event loop) to run Gecko events on the main application thread. Under some circumstances these "additional methods" can cause Gecko event handlers to be re-entered, sometimes leading to hangs and crashes. Calls to suspendNative and resumeNative() may be nested. On some platforms (those that do not use any "additional methods") this will be a no-op. Does not (in itself) stop Gecko events from being processed on the main application thread. But if the nsIAppShell->run() event loop is blocked when this call is made, Gecko events will stop being processed until resumeNative() is called (even if a plugin or library is temporarily processing events on a nested event loop).

void suspendNative();
Parameters

None.