You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

Porting the XP Event Loop

By Travis Bogard
Last Modified: 9-8-99


Welcome to the XP Event Loop Porting Page.  The links below are provided to help provide the needed information to allow easy porting of the XP Event Loop to all platforms.
 

General Event Loop Information:

Porting Process Overview:

  1. Setting up to Build
  2. Implement the Event component
  3. Implement the EventFilter component
  4. Implement the nsCPlatformBaseLoop class
  5. Implement the nsCAppLoop, nsCBreathLoop and nsCThreadLoop class

Detailed Porting Process:

Setting up to Build:

The first step to getting the event loop ported to your platform is to setup the build environment.  The code is for the event loop is broken up into two main directories.  The first is an "xp" directory.  The second is a platform directory named for the platform, for instance "windows".  The xp directory need not change as everything there should be completely cross platform.  This directory houses the base classes that the platform and various event loop types subclass from (nsCBaseLoop, nsCBaseAppLoop, nsCBaseThreadLoop, and nsCBaseBreathLoop).  You will need to create a new directory for your platform files that you will implement.  Your build then needs to be setup so that your final Module builds cpp files from both the xp directory and the platform directory.  You will also need to ensure that the xp directory has the platform directory in it's include path and that inversely the platform directory has the xp directory in it's include path.  This is important as the xp code references files that the platform code is responsible for providing.  The platform code likewise uses the xp code to subclass from as well.  Once you have this setup, you are ready to start coding.  At this point, you will most likely need to get all the code framed out before anything will link as all the pure virtual functions will need to be implemented.  This means basically all the code must be framed out before you will finally get a compiled module.  The good news is that there isn't too terribly much to write to get to this point.

Implement the Event component:

The event component is really straightforward and simple to implement.
  1. First you must decide if you can re-use a platform structure for your event data or if you need to encapsulate a few pieces of native data into a structure you make yourself.  If you need to make your own, you need to write a class or structure for this and make sure it is public so others can find it from the outside world.
  2. You then need to define a new constant for this type in nsNativeEventDataTypes found in the nsIEvent interface file.
  3. Once you have these setup, you can start implementing the component.  You must make the class name "nsCEvent" and must have a file in your directory that is called "nsCEvent.h".
  4. From here simply implement the needed v-table entries from nsIEvent.  For an example, look at the windows implementation.

Implement the EventFilter component:

The event filter component is really straightforward and simple to implement.
  1. First you must decide if you can re-use a platform structure for your event data or if you need to encapsulate a few pieces of native data into a structure you make yourself.  If you need to make your own, you need to write a class or structure for this and make sure it is public so others can find it from the outside world.
  2. You then need to define a new constant for this type in nsNativeFilterDataTypes found in the nsIEventFilter interface file.
  3. Once you have these setup, you can start implementing the component.  You must make the class name "nsCEventFilter" and must have a file in your directory that is called "nsCEventFilter.h".
  4. From here simply implement the needed v-table entries from nsIEventFilter.  For an example, look at the windows implementation.

Implement the nsCPlatformBaseLoop class:

The nsCPlatformBaseLoop class provides the interjection point for platform specific implementation that can be shared across the event loop types.  More info on this can be found in the code structure document.
  1. First you must decide what if anything can be shared at a base level across all the loop types.  If there is nothing, you can simply provide a virtually empty class aside from the constructor and destructor.  Chances are you can at least implement a few methods and you will want to do so to avoid copy and paste across implementation for each of the event loop types.  In fact even if an implementation can only be shared by two of the types, it may be of value to provide the implementation in line and then override it in the one odd case.
  2. Once you have figured out how to factor things, you can start implementing the class.  You must make the class name "nsCPlatformBaseLoop" and must have a file in your directory that is called "nsCPlatformBaseLoop.h"
  3. From here simply implement the v-table entries from nsCBaseLoop that you wish to override at this level.  For an example, look at the windows implementation.

Implement the nsCAppLoop, nsCBreathLoop, and nsCThreadLoop class:

These three classes provide the final and complete implementation of the event loop for the given type.  This level must provide implementation for any pure virtuals that have not yet been overridden by classes higher up the class hierarchy.  This level is where a given event loop type and platform distinguishes itself from another.  For more information on this level, look at the code structure document.
  1. You should have already decided what should live in this level versus the nsCPlatformBaseLoop level, but as you think more about this level you may find more similarities that you can then apply to nsCPlatformBaseLoop.
  2. When you start implementing, you must name your class "nsCAppLoop", "nsCBreathLoop", or "nsCThreadLoop" depending on which you are implementing.  You also must provide a corresponding "name.h" file in your directory.
  3. From here simply implement the remaining v-table entries that were not implemented in the above classes.  Also provide any overrides that are needed for this event loop type.  For an example, look at the windows implementation for nsCAppLoop, nsCBreathLoop and nsCThreadLoop.