//--------------------------------
// Welcome to the documentation
//--------------------------------
// System made by : IaMfReNcH
//
// Hope you'll find all you want
// to know here. If you don't,
// feel free to ask your questions
//--------------------------------
// Short description :
// This system was made in order to allow easily interfacing between user and systems.
// Because when you create a system, sometimes, you may want to allow user to react to what you are doing.
// With this system, this is possible. You can trigger custom events, so it's up to the user to decide
// which trigger(s) may handle your events, or simply ignore them.
// For a basic use, you may only need 1 function
// if you are a user :
call TriggerRegisterCustomEventString(your_trigger, EventName)
// if you are want to trigger user's triggers
call TriggerCustomEventString(EventName)
// Well, everytime you (or someone) calls TriggerCustomEventString, all trigger registered with
// TriggerRegisterCustomEventString will be fired after checking conditions
// Then is the in depth doc, describing all available functions (if I didn't forget to update anything)
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
// 0 - Tips
// * You can register several events for a same trigger
// * You can register several triggers for a same event
// * This is not intended for debuging purpose only.
// You may use it in various situations, giving custom data with globals
// * If you're trigger doesn't instant use data, you shall copy globals into locals
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
// 1 - Functions to register an event handler
// those functions enables you register an event for your trigger in the same way you would do with blizzard's ones.
function TriggerRegisterCustomEvent takes trigger whichTrigger, integer EventId returns boolean
function TriggerRegisterCustomEventString takes trigger whichTrigger, string Event returns boolean
// both functions takes the handler has the first trigger argument
// The first function takes an integer for the event id to be handled by the trigger.
// It's meant to be a constant used here. Here is a sample.
constant integer GenericErrorCode = StringHash("GenericError")
// So, it's easier to avoid clashes with names
// The second function takes a string as parameter,
// so you don't need to use a constant or cast the string yourself
// Your line will looks shorter.
// If you enable inlining, you won't loss efficiency
// the functions will return false if the trigger is already bound to the event
// Once a event is triggered, you can check the event with
function GetEventId takes nothing returns integer
// Then, you may use the triggerer's function/globals to gather data
// Whenever an event is registered, a TriggerRegisteredAnyEvent event is sent.
// here is the code :
constant integer TriggerRegisteredAnyEventCode = StringHash("TriggerRegisteredAnyEvent")
// Another specific event is sent. Register it with the following line :
TriggerRegisterCustomEventString(trigger, "TriggerRegisteredEvent" + I2S(EVENT_ID))
// you can also retrieve EVENT_ID by StringHash(EVENT_NAME)
// then retrieve data with :
function GetRegisteringTrigger takes nothing returns trigger
function GetRegisteredEventId takes nothing returns integer
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
// 2 - functions to unregister an event handler
// those functions simply unregister an event for a trigger, so it won't fire when the event will be summoned again
function TriggerUnregisterCustomEvent takes trigger whichTrigger, integer EventId returns boolean
function TriggerUnregisterCustomEventString takes trigger whichTrigger, string Event returns boolean
// Those functions works same as the registering ones.
// But they'll return false if the trigger isn't bound or if an error happened
// if an error happens, an EventManagerError will be triggered. Use the function below for more details on the error
function GetEventManagerError takes nothing returns string
// an event is sent, like the one sent by TriggerRegisterCustomEvent :
constant integer TriggerRegisteredAnyEventCode = StringHash("TriggerUnregisteredAnyEvent")
// special event line :
TriggerRegisterCustomEventString(trigger, "TriggerUnregisteredEvent" + I2S(EVENT_ID))
// data functions :
function GetUnregisteringTrigger takes nothing returns trigger
function GetUnregisteredEventId takes nothing returns integer
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
// 3 - function to trigger an event
// those functions cause the system firing all the trigger registered with the specified event id
function TriggerCustomEvent takes integer EventId returns boolean
function TriggerCustomEventString takes string Event returns boolean
// You just give as an argument the event id/name.
// the function will return false if there is no handler for this event
// You may give your own data with globals.
// The following function will trigger a GenericError event, and put message into the string GenericError.
// It's just to trigger easily error, in one meaningful line.
function TriggerError takes string message returns boolean
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
// 4 - checking functions
// those functions allows you to check a register state
// returns true if the trigger has registered the event, false else
function IsRegisteredEvent takes trigger whichTrigger, integer EventId returns boolean
function IsRegisteredEventString takes trigger whichTrigger, string Event returns boolean
// returns true if the event have registered triggers, false else
function HasRegisteredTriggers takes integer EventId returns boolean
function HasRegisteredTriggersString takes string Event returns boolean
call TriggerCustomEventString("your event name")
call TriggerRegisterCustomEventString(his trigger, "your event name")
"MyEvent" + I2S(GetHandleId(what I want to embed))
globals
// there is the data you want. Should be initialized with null values
endglobals
function Trig_MyEventRegisterHandler_Actions takes nothing returns nothing
// now check the event id
if GetEventId() != "TriggerRegisteredEvent" + I2S(MY_EVENT_ID) then
return
endif
// check the data
if invalid or missing data then
// unbind the trigger
call TriggerUnregisterCustomEvent(GetRegisteringTrigger(), GetRegisteredEventId())
call TriggerError("invalid or missing data") // you may also tell which data is wrong
// eventually spread your own error event with the invalid globals
else
// process data. Do what you want
endif
// reset the data to ensure it won't hide a missing error on a further registering
// you can eventually store into locals and reset then if you need some waits.
endfunction
//===========================================================================
function InitTrig_MyEventRegisterHandler takes nothing returns nothing
set gg_trg_MyEventRegisterHandler = CreateTrigger( )
// register the event like any other event.
call TriggerRegisterCustomEventString(gg_trg_MyEventRegisterHandler, "TriggerRegisteredEvent" + I2S(MY_EVENT_ID))
call TriggerAddAction( gg_trg_MyEventRegisterHandler, function Trig_MyEventRegisterHandler_Actions )
endfunction
library EventManager
private struct TriggerList
TriggerList next
TriggerList prev
trigger handler
// just init with default values
static method create takes nothing returns TriggerList
local TriggerList this = TriggerList.allocate()
set this.next = 0
set this.prev = 0
set this.handler = null
return this
endmethod
endstruct
globals
// public data
// errors code, use for EventId
constant integer EventManagerErrorCode = StringHash("EventManagerError")
constant integer GenericErrorCode = StringHash("GenericError")
// code to use as EventId when people (un)registers a trigger
constant integer TriggerRegisteredAnyEventCode = StringHash("TriggerRegisteredAnyEvent")
constant integer TriggerUnregisteredAnyEventCode = StringHash("TriggerUnregisteredAnyEvent")
// string you can use for a GenericError
string GenericError = ""
// private data
private string EventManagerError = ""
private hashtable EventManagerHash = InitHashtable()
private integer EventIdG
private trigger RegisteringTrigger
private integer RegisteredEventId
private trigger UnregisteringTrigger
private integer UnregisteredEventId
endglobals
// returns the triggering event id
function GetEventId takes nothing returns integer
return EventIdG
endfunction
// returns the internal event manager error description
function GetEventManagerError takes nothing returns string
return EventManagerError
endfunction
// returns the registering trigger
function GetRegisteringTrigger takes nothing returns trigger
return RegisteringTrigger
endfunction
// returns the registered event
function GetRegisteredEventId takes nothing returns integer
return RegisteredEventId
endfunction
// returns the unregistering trigger
function GetUnregisteringTrigger takes nothing returns trigger
return UnregisteringTrigger
endfunction
// returns the unregistered event
function GetUnregisteredEventId takes nothing returns integer
return UnregisteredEventId
endfunction
// we'll return true to notify at least one handler, false if there is no handler
function TriggerCustomEvent takes integer EventId returns boolean
local TriggerList iterator = LoadInteger(EventManagerHash, EventId, 0) // the value into the hashtable is the first index
// check the List
if iterator == 0 then
return false
endif
set EventIdG = EventId
// enumerate and execute every trigger into the list
loop
// check conditions, and execute the trigger then
if IsTriggerEnabled(iterator.handler) then
if TriggerEvaluate(iterator.handler) then
call TriggerExecute(iterator.handler)
endif
endif
// exit when there is no next elements
exitwhen iterator.next == 0
// select the next element
set iterator = iterator.next
endloop
// if it's a generic error, back the string to "", to avoid bad infos next time if the string doesn't change
if EventId == GenericErrorCode then
set GenericError = ""
endif
// reset the EventId's global
set EventIdG = 0
return true
endfunction
function TriggerCustomEventString takes string Event returns boolean
return TriggerCustomEvent(StringHash(Event))
endfunction
// this function just do the triggering error easy in a single line (instead of two)
// This function is just more readable and meaningfull
function TriggerError takes string message returns boolean
set GenericError = message
return TriggerCustomEvent(GenericErrorCode)
endfunction
// register a trigger with an event, so it'll be called back when the event happens
// returns false if the trigger was already registered
function TriggerRegisterCustomEvent takes trigger whichTrigger, integer EventId returns boolean
// try to load the list
local TriggerList iterator = LoadInteger(EventManagerHash, EventId, 0)
// check the trigger isn't already bound to the event
local TriggerList element = LoadInteger(EventManagerHash, EventId, GetHandleId(whichTrigger))
// the trigger is already bound to an event
if element != 0 then
// check an eventual error
if iterator == 0 then
set EventManagerError = "The trigger is bound to a list element for this event, but the event list could not be found... please report"
call TriggerCustomEvent(EventManagerErrorCode)
endif
if element.handler != whichTrigger then
set EventManagerError = "The trigger is bound to an element in the list, but the element is not bound to the trigger... please report"
call TriggerCustomEvent(EventManagerErrorCode)
endif
return false
endif
// allocate a list element
set element = TriggerList.create()
// if the list isn't yet created, we do this right now
if iterator == 0 then
set iterator = element
call SaveInteger(EventManagerHash, EventId, 0, iterator)
else
// push as a first element
set iterator.prev = element
set element.next = iterator
set iterator = element
endif
set element.handler = whichTrigger
//and the trigger to the element
call SaveInteger(EventManagerHash, EventId, GetHandleId(whichTrigger), element)
// send an event to notify that a trigger registered an event
set RegisteringTrigger = whichTrigger
set RegisteredEventId = EventId
call TriggerCustomEvent(TriggerRegisteredAnyEventCode)
call TriggerCustomEventString("TriggerRegisteredEvent" + I2S(EventId))
set RegisteringTrigger = null
set RegisteredEventId = 0
return true
endfunction
function TriggerRegisterCustomEventString takes trigger whichTrigger, string Event returns boolean
return TriggerRegisterCustomEvent(whichTrigger, StringHash(Event))
endfunction
// return false if something is weird or if the trigger isn't registered
// if something is weird, a EventManagerError event will be triggered
function TriggerUnregisterCustomEvent takes trigger whichTrigger, integer EventId returns boolean
local TriggerList iterator = LoadInteger(EventManagerHash, EventId, 0)
local TriggerList element = LoadInteger(EventManagerHash, EventId, GetHandleId(whichTrigger))
// if the element is null, the event isn't registered : abort
if element == 0 then
return false
endif
if iterator == 0 then
set EventManagerError = "The trigger seems to be registered: an element has been found, but the list couldn't be found... please report"
call TriggerCustomEvent(EventManagerErrorCode)
// abort
return false
endif
if element.handler != whichTrigger then
set EventManagerError = "The trigger is bound to a list element, but the element isn't bound to the trigger... please report"
call TriggerCustomEvent(EventManagerErrorCode)
// abort
return false
endif
// remove the binding
call RemoveSavedInteger(EventManagerHash, EventId, GetHandleId(whichTrigger))
if element.next == 0 and element.prev == 0 then
// first case : single element into the list
if element != iterator then
set EventManagerError = "The list element says he is the single of the list(so the first), but the hashtable says he isn't the first... please report"
call TriggerCustomEvent(EventManagerErrorCode)
return false
endif
call RemoveSavedInteger(EventManagerHash, EventId, 0)
call element.destroy()
elseif element.next == 0 then
// last element of the list
set element.prev.next = 0
call element.destroy()
elseif element.prev == 0 then
// first element of the list
if element != iterator then
set EventManagerError = "The list element says he is the first of the list, but the hashtable says he isn't the first... please report"
call TriggerCustomEvent(EventManagerErrorCode)
return false
endif
set element.next.prev = 0
call SaveInteger(EventManagerHash, EventId, 0, element.next)
call element.destroy()
else
// element between other elements
set element.next.prev = element.prev
set element.prev.next = element.next
call element.destroy()
endif
// send an event to notify that a trigger unregistered an event
set UnregisteringTrigger = whichTrigger
set UnregisteredEventId = EventId
call TriggerCustomEvent(TriggerUnregisteredAnyEventCode)
call TriggerCustomEventString("TriggerUnregisteredEvent" + I2S(EventId))
set UnregisteringTrigger = null
set UnregisteredEventId = 0
// sucess
return true
endfunction
function TriggerUnregisterCustomEventString takes trigger whichTrigger, string Event returns boolean
return TriggerUnregisterCustomEvent(whichTrigger, StringHash(Event))
endfunction
// returns true if the trigger has registered the event, false else
function IsRegisteredEvent takes trigger whichTrigger, integer EventId returns boolean
local TriggerList element = LoadInteger(EventManagerHash, EventId, GetHandleId(whichTrigger))
return element != 0
endfunction
function IsRegisteredEventString takes trigger whichTrigger, string Event returns boolean
return IsRegisteredEvent(whichTrigger, StringHash(Event))
endfunction
// returns true if the event have registered triggers, false else
function HasRegisteredTriggers takes integer EventId returns boolean
// Get the list
local TriggerList iterator = LoadInteger(EventManagerHash, EventId, 0)
return iterator != 0
endfunction
function HasRegisteredTriggersString takes string Event returns boolean
return HasRegisteredTriggers(StringHash(Event))
endfunction
endlibrary
//--------------------------------
// Welcome to the documentation
//--------------------------------
// System made by : IaMfReNcH
//
// Hope you'll find all you want
// to know here. If you don't,
// feel free to ask your questions
//--------------------------------
// Short description :
// This system was made in order to allow easily interfacing between user and systems.
// Because when you create a system, sometimes, you may want to allow user to react to what you are doing.
// With this system, this is possible. You can trigger custom events, so it's up to the user to decide
// which trigger(s) may handle your events, or simply ignore them.
// For a basic use, you may only need 1 function
// if you are a user :
call TriggerRegisterCustomEventString(your_trigger, EventName)
// if you are want to trigger user's triggers
call TriggerCustomEventString(EventName)
// Well, everytime you (or someone) calls TriggerCustomEventString, all trigger registered with
// TriggerRegisterCustomEventString will be fired after checking conditions
// Then is the in depth doc, describing all available functions (if I didn't forget to update anything)
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
// 0 - Tips
// * You can register several events for a same trigger
// * You can register several triggers for a same event
// * This is not intended for debuging purpose only.
// You may use it in various situations, giving custom data with globals
// * If you're trigger doesn't instant use data, you shall copy globals into locals
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
// 1 - Functions to register an event handler
// those functions enables you register an event for your trigger in the same way you would do with blizzard's ones.
function TriggerRegisterCustomEvent takes trigger whichTrigger, integer EventId returns boolean
function TriggerRegisterCustomEventString takes trigger whichTrigger, string Event returns boolean
// both functions takes the handler has the first trigger argument
// The first function takes an integer for the event id to be handled by the trigger.
// It's meant to be a constant used here. Here is a sample.
constant integer GenericErrorCode = StringHash("GenericError")
// So, it's easier to avoid clashes with names
// The second function takes a string as parameter,
// so you don't need to use a constant or cast the string yourself
// Your line will looks shorter.
// If you enable inlining, you won't loss efficiency
// the functions will return false if the trigger is already bound to the event
// Once a event is triggered, you can check the event with
function GetEventId takes nothing returns integer
// Then, you may use the triggerer's function/globals to gather data
// Whenever an event is registered, a TriggerRegisteredAnyEvent event is sent.
// here is the code :
constant integer TriggerRegisteredAnyEventCode = StringHash("TriggerRegisteredAnyEvent")
// Another specific event is sent. Register it with the following line :
TriggerRegisterCustomEventString(trigger, "TriggerRegisteredEvent" + I2S(EVENT_ID))
// you can also retrieve EVENT_ID by StringHash(EVENT_NAME)
// then retrieve data with :
function GetRegisteringTrigger takes nothing returns trigger
function GetRegisteredEventId takes nothing returns integer
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
// 2 - functions to unregister an event handler
// those functions simply unregister an event for a trigger, so it won't fire when the event will be summoned again
function TriggerUnregisterCustomEvent takes trigger whichTrigger, integer EventId returns boolean
function TriggerUnregisterCustomEventString takes trigger whichTrigger, string Event returns boolean
// Those functions works same as the registering ones.
// But they'll return false if the trigger isn't bound or if an error happened
// if an error happens, an EventManagerError will be triggered. Use the function below for more details on the error
function GetEventManagerError takes nothing returns string
// an event is sent, like the one sent by TriggerRegisterCustomEvent :
constant integer TriggerRegisteredAnyEventCode = StringHash("TriggerUnregisteredAnyEvent")
// special event line :
TriggerRegisterCustomEventString(trigger, "TriggerUnregisteredEvent" + I2S(EVENT_ID))
// data functions :
function GetUnregisteringTrigger takes nothing returns trigger
function GetUnregisteredEventId takes nothing returns integer
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
// 3 - function to trigger an event
// those functions cause the system firing all the trigger registered with the specified event id
function TriggerCustomEvent takes integer EventId returns boolean
function TriggerCustomEventString takes string Event returns boolean
// You just give as an argument the event id/name.
// the function will return false if there is no handler for this event
// You may give your own data with globals.
// The following function will trigger a GenericError event, and put message into the string GenericError.
// It's just to trigger easily error, in one meaningful line.
function TriggerError takes string message returns boolean
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------------------------
// 4 - checking functions
// those functions allows you to check a register state
// returns true if the trigger has registered the event, false else
function IsRegisteredEvent takes trigger whichTrigger, integer EventId returns boolean
function IsRegisteredEventString takes trigger whichTrigger, string Event returns boolean
// returns true if the event have registered triggers, false else
function HasRegisteredTriggers takes integer EventId returns boolean
function HasRegisteredTriggersString takes string Event returns boolean
//! textmacro AutoEnable takes TRIGGER, EVENT, ALLOWDISABLE, DOINIT
scope AutoEnable$TRIGGER$ initializer InitTrig_Auto_Enable_$TRIGGER$
globals
private trigger Auto_Enable_$TRIGGER$ = CreateTrigger()
private trigger Auto_Disable_$TRIGGER$ = CreateTrigger()
endglobals
function Trig_Auto_Enable_$TRIGGER$_Actions takes nothing returns nothing
call EnableTrigger(gg_trg_$TRIGGER$)
call EnableTrigger(Auto_Disable_$TRIGGER$)
call DisableTrigger(Auto_Enable_$TRIGGER$)
static if $DOINIT$ then
call InitTrig_$TRIGGER$()
endif
endfunction
function Trig_Auto_Disable_$TRIGGER$_Actions takes nothing returns nothing
if not HasRegisteredTriggers($EVENT$) then
call DisableTrigger(gg_trg_$TRIGGER$)
call DisableTrigger(Auto_Disable_$TRIGGER$)
call EnableTrigger(Auto_Enable_$TRIGGER$)
endif
endfunction
//===========================================================================
function InitTrig_Auto_Enable_$TRIGGER$ takes nothing returns nothing
call TriggerRegisterCustomEventString(Auto_Enable_$TRIGGER$, "TriggerRegisteredEvent" + I2S($EVENT$))
call TriggerAddAction( Auto_Enable_$TRIGGER$, function Trig_Auto_Enable_$TRIGGER$_Actions )
static if $ALLOWDISABLE$ then
call TriggerRegisterCustomEventString(Auto_Disable_$TRIGGER$, "TriggerUnregisteredEvent" + I2S($EVENT$))
call TriggerAddAction( Auto_Disable_$TRIGGER$, function Trig_Auto_Disable_$TRIGGER$_Actions )
if not HasRegisteredTriggers($EVENT$) then
call DisableTrigger(Auto_Disable_$TRIGGER$)
endif
endif
endfunction
endscope
//! endtextmacro
library AnyUnitDamaged requires EventManager
globals
unit source = null
unit target = null
real amount = 0
integer AnyUnitDamagedCode = StringHash("AnyUnitDamaged")
endglobals
function Trig_AnyUnitDamaged_Actions takes nothing returns nothing
if GetTriggerEventId() == EVENT_UNIT_DAMAGED then
set source = GetEventDamageSource()
set target = GetTriggerUnit()
set amount = GetEventDamage()
call TriggerCustomEvent(AnyUnitDamagedCode)
else
call TriggerRegisterUnitEvent( gg_trg_AnyUnitDamaged, GetTriggerUnit(), EVENT_UNIT_DAMAGED )
endif
endfunction
//===========================================================================
function InitTrig_AnyUnitDamaged takes nothing returns nothing
local region r = null
local group g = null
local unit u = null
if HasRegisteredTriggers(AnyUnitDamagedCode) then
set r = CreateRegion()
set gg_trg_AnyUnitDamaged = CreateTrigger( )
set g = GetUnitsInRectMatching(bj_mapInitialPlayableArea, null)
loop
set u = FirstOfGroup(g)
exitwhen u == null
call GroupRemoveUnit(g, u)
call TriggerRegisterUnitEvent( gg_trg_AnyUnitDamaged, u, EVENT_UNIT_DAMAGED )
endloop
call RegionAddRect(r, bj_mapInitialPlayableArea)
call TriggerRegisterEnterRegion(gg_trg_AnyUnitDamaged, r, null)
set g = null
set u = null
set r = null
call TriggerAddAction( gg_trg_AnyUnitDamaged, function Trig_AnyUnitDamaged_Actions )
endif
endfunction
endlibrary
//! runtextmacro AutoEnable ("AnyUnitDamaged", "AnyUnitDamagedCode", "false", "true")
//! textmacro EventEmulator takes FUNCTION, NAME
scope EventEmulator$NAME$ initializer InitTrig_event_emulator_$NAME$
globals
constant integer EmulatedEventId = StringHash("$NAME$")
constant trigger event_emulator_$NAME$ = CreateTrigger()
endglobals
function Trig_event_emulator_$NAME$_Actions takes nothing returns nothing
call TriggerCustomEvent(EmulatedEventId)
endfunction
//===========================================================================
function InitTrig_event_emulator_$NAME$ takes nothing returns nothing
call $FUNCTION$
call TriggerAddAction( event_emulator_$NAME$, function Trig_event_emulator_$NAME$_Actions )
endfunction
endscope
//! endtextmacro