Extended Event Handlers (XEH) by Solus and Killswitch

Version:  1.7
Released: 2008-03-16

Introduction
============
This addon allows a virtually infinite amount of event handlers to be used
together from different addons. The event handlers are executed for the matching
class and all inheriting classes. The event handler init line also contains the
extended event handler class to look for, so you can have a custom inheritance
for custom units.

Normally event handlers can only be added in configs, and trying to add a new
event handler caused all previous event handlers to be overwritten. This addon
allows that limitation to be overcome. This is mostly useful for having addons
that can add different functionality, for example in OFP addons that had their
own event handlers wouldn't inherit default event handlers, such as a custom
unit with EHs being used with ECP or FFUR wouldn't have the ECP or FFUR effects.


"Other" extended event handlers by Killswitch
=============================================
This adds support for using extended event handlers for all Arma event types


Extended fired event handler
=============================
This allows a virtually infinite amount of fired event handlers to be used
together from different addons.

The extended fired event handler has several different parts:

	First the extended init EH is run for all units to add together and compile
	all of the inherited fired event handlers and use setVariable to attach
	those to the unit.

	The extended fired event handler is added to the base class called
	Extended_EventHandlers so that all of the CfgVehicles class EventHandlers
	inherit it. When a unit fires and sets off the event handler the shot is
	immediately captured in the same game state cycle. Then the compiled
	extended fired events are called by using getVariable to retrieve them
	from the unit.


The fired event handler init line contains the extended event handler class to
look for, so you can have a custom inheritance for custom units. The event
handlers are executed for the matching class and all inheriting classes.

It allows more fired events to be used together, for example a script that makes
shots affected by wind and a tracer script could be used together.



Examples
========
There are two example Extended Init addons included to demonstrate how to assign
new event handlers and the event handler inheritance. The example pbos should
not be installed except for testing.

There is an example addon included to demonstrate how to assign new fired event
handlers and the event handler inheritance. The example also has a quickly
called function that is able to capture information on the shot in the same game
state cycle before the shot is updated and moves away from it's starting
position and changes it's status. The example pbo should not be installed except
for testing.

The addon "SightAdjustment_AutoInit.pbo" is an addon that makes gmJamez' 
"GMJ_SightAdjustment" addon compatible with XEH.

Note to addon makers: Before XEH 1.1, you had to make sure to add a ";" at the
end of your extended init line to separate it from other extended inits. This
is no longer necessary - the Extended Init EH will separate them automatically,
so ending without one won't cause a problem

New in 1.3: Limiting certain event handler to a specific vehicle class
======================================================================
The example addon "SLX_Advanced_Init_Example" shows how to create
an XEH init EH that will only be used on units that are of the class SoldierWB,
ie the West "Rifleman". Units that inherit from "SoldierWB", eg the Grenadier,
won't run the init EH. 

One can do the same thing for the other XEH event types. For example, to add a
"GetIn" event handler that works only on the the vehicle XYZ_BRDM2, but not on
the XYZ_BRDM2_ATGM variant you would do something like this:


...
class Extended_GetIn_Eventhandlers
{
	class XYZ_BRDM2
	{
		class XYZ_BRDM2_GetIn
		{
			scope = 0;
			getin = "[] exec ""\xyz_brdm2\getin.sqf""";
		};
	};
};


class Vehicles
{
	...
	class XYZ_BRDM2: BRDM2
	{
		...
	};
	class XYZ_BRDM2_ATGM: XYZ_BRDM2
	{
		...
	};
};

Note that within that innermost XEH class, you have to put a string value with
the same name as the desired event handler. In the above example it was "getin".
For the "fired" event handler, you would use

...
class Extended_Fired_Eventhandlers
{
        class SoldierEB
        {
            class XYZ_SoldierEB_fired
            {
                scope=0;
                // We wish to make a SoldierEB-specific *Fired* EH, so the
                // property name should be "fired"
                //
                fired = "_this call XYZ_SoldierEB_fired";
             };
         };
};
...


New in 1.5: Excluding certain descendant vehicle types 
======================================================
With XEH 1.5, you can exclude one or more subtypes of a vehicle from
getting a certain XEH event handler. To do this, you add a directive,
exclude, in an inner, "composite" XEH class (introduced in 1.3)

Here's an example of how to exclude the west pilot class from running
the basic Man class XEH init event handler. Instead, there's a special
init for the pilot ("SoldierWPilot"). Note that all subclasses of
"SoldierWPilot" will be excluded from using the basic class Man XEH
init too.


/*
 *   Init XEH exclusion example 1
 */
class CfgPatches
{
   class xeh_exclusion_example1
   {
       units[]={};
       weapons[]={};
       requiredVersion=0.1;
       requiredAddons[]={"Extended_Eventhandlers"};
   };
};

class Extended_Init_Eventhandlers
{
    class Man
    {
        // To use the exclude directive, we'll have to make this an
        // "inner" (composite) XEH init EH class
	class XEH_Exclusion1_Man
	{
            exclude="SoldierWPilot";
            init = "[] execVM ""\xeh_exclusion_example1\init_man.sqf""";
	};
    };

    class SoldierWPilot
    {
        xeh_init = "[] execVM ""\xeh_exclusion_example1\init_west_pilot.sqf""";
    };
};


In the second example, we'll exclude both the standard west and east
pilots and add unique init EH:S to them and the BIS Camel pilot. To do
so, use the exclude[] directive in array form:

/*
 *   Init XEH exclusion example 2
 */
class CfgPatches
{
   class xeh_exclusion_example2
   {
       units[]={};
       weapons[]={};
       requiredVersion=0.1;
       requiredAddons[]={"Extended_Eventhandlers"};
   };
};

class Extended_Init_Eventhandlers
{
    class Man
    {
        // To use the exclude directive, we'll have to make this an
        // "inner" (composite) XEH init EH class
	class XEH_Exclusion2_Man
        {
            exclude[] = {"SoldierWPilot", "SoldierEPilot"};
            init = "[] execVM ""\xeh_exclusion_example2\init_man.sqf""";
        };
    };

    // All descendants of SoldierEPilot will use this XEH init EH
    class SoldierEPilot
    {
        xeh_init = "[] execVM ""\xeh_exclusion_example2\init_east_pilot.sqf""";
    };

    // Using scope=0, only SoldierWPilot will get this particular XEH init
    class SoldierWPilot
    {
        scope=0;
        xeh_init = "[] execVM ""\xeh_exclusion_example2\init_west_pilot.sqf""";
    };

    // Here, we add an event handler for the BIS Camel Pilot (which is a
    // descendant of "SoldierWPilot". It won't run "init_west_pilot.sqf" though
    // since we used "scope=0" above.
    class BISCamelPilot
    {
        xeh_init = "[] execVM ""\xeh_exclusion_example2\init_west_camel_pilot.sqf""";
    };
};



You can do the same thing with the other XEH event types (fired, hit and so on).




XEH Change log
==============
1.7
Fixed: Removed XEH from class Static, which stops ArmA from crashing to desktop
       when resuming saved games.

1.6
Fixed: The "exclude" property will apply to the specified class(es) and all
       subclasses thereof.

1.5
Added: Composite ("inner") XEH classes can have an extra property, "exclude"
       which is either a string or an array of strings with the class name(s)
       of vehicles that should *not* get a particular XEH event handler.

1.4
Added: "Static" class vehicles can now have XEH event handlers.
Added: A respawn monitor that restores non-init XEH event handlers after
       the player respawns. Many thanks to Sickboy, LoyalGuard, ViperMaul for
	   the initial research and suggestions!

1.3
Added: The ability to use "nested" XEH classes with a "scope" feature
       to limit certain event handlers to objects of specific classes.

1.2
Fixed: SightAdjustment_AutoInit.
Fixed: Extended Dammaged EventHandler.

1.1 
Fixed: XEH can now handle extended event handlers that are missing a trailing
       semicolon.
Fixed: the example addons now require the Extended_Eventhandlers addon instead
       of the two older ones. Also, the debug sideChats are now guaranteed to
	   be seen when previewing a mission with the example addons loaded.
Fixed: XEH init EH:s are now actually being called on units inside vehicles.

1.0 Initial Release
Combined Extended Init, Fired, and Other event handlers. Thanks to Killswitch
for combining them and adding the other extended event handlers!
Added signature and bikey.


Init EH Change log:
===================
1.26
Fixed signature files, bikey, and .pbos.

1.25
Fixed signature files and added bikey.

1.2
Added signature file.
Fixed a bug that caused crashes on some missions. Thanks to LCD344!
Changed ExecVM to Call Compile. Thanks to UNN!

1.1
Fixed people in vehicles having no inits.
Included SightAdjustment example "bridge" addon that allows the GMJ_SightAdjustment
addon to be used with other extended init event handler addons.

1.0 Initial Release


Fired EH Change log
===================
1.0 @ 12-09-07 Initial release



References
==========
BI Forums: http://www.flashpoint1985.com/cgi-bin/ikonboard311/ikonboard.cgi

gmJamez Sight adjustment addon thread: http://www.flashpoint1985.com/cgi-bin/ikonboard311/ikonboard.cgi?s=60ba6482bbaa47a50e83f8ae5674bdd8;act=ST;f=70;t=65706