Skip to content

Adding Event Handlers to Classes of Objects

commy2 edited this page Dec 8, 2017 · 3 revisions

Class Event Handlers

About

Class Event Handlers can be used to add the usual object event handlers to whole classes of objects including their child classes. This can be used to add the same event to multiple objects at once and to ensure that these events apply to objects that are created during a mission (i.e. via createUnit or createVehicle).
The concept is very similar to the Extended Event Handlers (XEH), but there are two key differences: Class Event Handlers can be used in mission scripts like the init.sqf and support units and vehicles which do not follow the necessary steps to be compatible with XEH.

Supported Events

https://github.com/CBATeam/CBA_A3/wiki/Extended-Event-Handlers-%28new%29#supported

CBA_fnc_addClassEventHandler

Description:
    Add an eventhandler to a class and all children.

Parameters:
    0: _className        - The classname of objects you wish to add the eventhandler too. Can be a base class. <STRING>
    1: _eventName        - The type of the eventhandler. E.g. "init", "fired", "killed" etc. <STRING>
    2: _eventFunc        - Function to execute when event happens. <CODE>
    3: _allowInheritance - Allow event for objects that only inherit from the given classname? [optional] <BOOLEAN> (default: true)
    4: _excludedClasses  - Exclude these classes from this event including their children [optional] <ARRAY> (default: [])
    5: _applyInitRetroactively - Apply "init" event type on existing units that have already been initilized. [optional] <BOOLEAN> ((default: false)

Returns:
    _success - Whether adding the event was successful or not. <BOOLEAN>

Examples:
    (begin example)
        ["CAManBase", "fired", {systemChat str _this}] call CBA_fnc_addClassEventHandler;
        ["All", "init", {systemChat str _this}] call CBA_fnc_addClassEventHandler;
        ["Car", "init", {(_this select 0) engineOn true}, true, [], true] call CBA_fnc_addClassEventHandler; //Starts all current cars and those created later
    (end)

The function only adds the event handler on the machine where the function is executed. If the event function should be executed on a remote machine, CBA_fnc_addClassEventHandler has to be executed on that client as well.
The same limitations regarding object locality that apply to object event handlers like respawn, killed etc. apply to Class Event Handlers as well. A "respawn"-Class Event Handler will only fire on the machine where the respawned unit is local.

Examples

["CAManBase", "Fired", {systemChat str _this}] call CBA_fnc_addClassEventHandler;

This will show a chat message every time a soldier fires a weapon. It is advised to use CAManBase instead of Man when dealing with soldiers, because Man is the parent class of all animals, including the randomly spawning rabbits, snakes and fish. Using CAManBase slightly reduces the overhead that would happen when any of these spawn (which actually happens pretty frequently).

["AllVehicles", "GetIn", {hint str _this}] call CBA_fnc_addClassEventHandler;

This event happens every time a soldier enters a vehicle.

["All", "InitPost", {diag_log _this}, nil, nil, true] call CBA_fnc_addClassEventHandler;

Init and InitPost events can execute code retroactively for already existing objects. This is useful when working with scheduled scripts like init.sqf or a postInit function defined in CfgFunctions.

Limitations

Class Event Handlers will only work on mission objects. These are objects placed by the mission maker or objects created during the mission via createUnit and createVehicle. Class Event Handlers do not work on map objects (houses, trees, stones etc. not placed by the mission maker).

Removing an event handler?

Class Event Handlers can not be removed. If an event should be "disabled" during a mission, it is advised to use a global boolean variable combined with exitWith instead.

My_disableFiredEvent = true;

["CAManBase", "killed", {
    if (My_disableFiredEvent) exitWith {};

    ...

}] call CBA_fnc_addClassEventHandler;