nsIAppShell

Method overview

Attributes

Methods

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.

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.

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.

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.

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.

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.

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.

Prepare to stop processing events.

void Spindown();

Parameters

None.

Prepare to process events.

void Spinup();

Parameters

None.

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.