DispatchEventAlt

A function added by the New Vegas Script Extender version 6.2.8.

Description

Similar to Call, but executes multiple Event Handler UDFs that were registered for the User-Defined Event of a certain name, assuming the filters for those event handlers match with the dispatched arguments.

Can dispatch up to 15 arguments of any type (numeric, form, string, array), as well as passing an optional calling reference to invoke the UDFs with.

Users can register to these custom events via SetEventHandler / SetEventHandlerAlt, though SetEventHandlerAlt is more suited for this task, as it allows filters that dictate when the handler should run for each individual arg.

Syntax

[help]

(success:bool) callingRef.DispatchEventAlt eventName:string multi:arg(up to 15)

Example

player.DispatchEventAlt "MyCustomEvent" SunnyREF, (Ar_List 1, 2), "test", 2.5

If a user were to register to this event, their event handler UDF script would look like this:

scn MyEventHandlerUDF
begin Function { ref rArg1, array_var aArg2, string_var aArg3, float fArg4 }
   ; do stuff
end

And they could register their event handler like so:

SetEventHandlerAlt "MyCustomEvent" MyEventHandlerUDF

Since that event handler is unfiltered, it will run for this dispatch.

However, if it has filters, then it depends on if the filters match the provided args for the handler to run. For example,

SetEventHandlerAlt "MyCustomEvent" MyEventHandlerUDF 1::SunnyREF

Since the first arg dispatched is SunnyREF, and the filter for the 1st arg (1::) is SunnyREF, the filters match.

However, if we had:

SetEventHandlerAlt "MyCustomEvent" MyEventHandlerUDF 1::EasyPeteREF

EasyPeteREF does not match with SunnyREF, so this registered event handler will not run for this particular dispatch. Though it may run for another one in the future, if the first arg dispatched becomes EasyPeteREF.

More information on this filtering system is available on SetEventHandlerAlt and New xNVSE Event Filtering System.

Notes

• The UDFs are not forced to have the same amount of arguments as the event dispatches; they may choose to receive less. This property allows events to increase the amount of args they pass without fearing to break existing event handlers that were set for that event.

See Also

• SetEventHandlerAlt - can set an event handler with filters for each arg, and the calling reference.
• SetEventHandler - uses the old filtering system, i.e won't support non-form filters, and can only have up to 2 filters.
• RemoveEventHandler - works with both the old and new filtering system.
• GetCurrentEventName
• DispatchEvent - passes a StringMap of arguments, instead of any number of differently-typed arguments.