Xiiph@0: --- AceEvent-3.0 provides event registration and secure dispatching.
Xiiph@0: -- All dispatching is done using **CallbackHandler-1.0**. AceEvent is a simple wrapper around
Xiiph@0: -- CallbackHandler, and dispatches all game events or addon message to the registrees.
Xiiph@0: --
Xiiph@0: -- **AceEvent-3.0** can be embeded into your addon, either explicitly by calling AceEvent:Embed(MyAddon) or by 
Xiiph@0: -- specifying it as an embeded library in your AceAddon. All functions will be available on your addon object
Xiiph@0: -- and can be accessed directly, without having to explicitly call AceEvent itself.\\
Xiiph@0: -- It is recommended to embed AceEvent, otherwise you'll have to specify a custom `self` on all calls you
Xiiph@0: -- make into AceEvent.
Xiiph@0: -- @class file
Xiiph@0: -- @name AceEvent-3.0
Xiiph@0: -- @release $Id: AceEvent-3.0.lua 975 2010-10-23 11:26:18Z nevcairiel $
Xiiph@0: local MAJOR, MINOR = "AceEvent-3.0", 3
Xiiph@0: local AceEvent = LibStub:NewLibrary(MAJOR, MINOR)
Xiiph@0: 
Xiiph@0: if not AceEvent then return end
Xiiph@0: 
Xiiph@0: -- Lua APIs
Xiiph@0: local pairs = pairs
Xiiph@0: 
Xiiph@0: local CallbackHandler = LibStub:GetLibrary("CallbackHandler-1.0")
Xiiph@0: 
Xiiph@0: AceEvent.frame = AceEvent.frame or CreateFrame("Frame", "AceEvent30Frame") -- our event frame
Xiiph@0: AceEvent.embeds = AceEvent.embeds or {} -- what objects embed this lib
Xiiph@0: 
Xiiph@0: -- APIs and registry for blizzard events, using CallbackHandler lib
Xiiph@0: if not AceEvent.events then
Xiiph@0: 	AceEvent.events = CallbackHandler:New(AceEvent, 
Xiiph@0: 		"RegisterEvent", "UnregisterEvent", "UnregisterAllEvents")
Xiiph@0: end
Xiiph@0: 
Xiiph@0: function AceEvent.events:OnUsed(target, eventname) 
Xiiph@0: 	AceEvent.frame:RegisterEvent(eventname)
Xiiph@0: end
Xiiph@0: 
Xiiph@0: function AceEvent.events:OnUnused(target, eventname) 
Xiiph@0: 	AceEvent.frame:UnregisterEvent(eventname)
Xiiph@0: end
Xiiph@0: 
Xiiph@0: 
Xiiph@0: -- APIs and registry for IPC messages, using CallbackHandler lib
Xiiph@0: if not AceEvent.messages then
Xiiph@0: 	AceEvent.messages = CallbackHandler:New(AceEvent, 
Xiiph@0: 		"RegisterMessage", "UnregisterMessage", "UnregisterAllMessages"
Xiiph@0: 	)
Xiiph@0: 	AceEvent.SendMessage = AceEvent.messages.Fire
Xiiph@0: end
Xiiph@0: 
Xiiph@0: --- embedding and embed handling
Xiiph@0: local mixins = {
Xiiph@0: 	"RegisterEvent", "UnregisterEvent",
Xiiph@0: 	"RegisterMessage", "UnregisterMessage",
Xiiph@0: 	"SendMessage",
Xiiph@0: 	"UnregisterAllEvents", "UnregisterAllMessages",
Xiiph@0: }
Xiiph@0: 
Xiiph@0: --- Register for a Blizzard Event.
Xiiph@0: -- The callback will be called with the optional `arg` as the first argument (if supplied), and the event name as the second (or first, if no arg was supplied)
Xiiph@0: -- Any arguments to the event will be passed on after that.
Xiiph@0: -- @name AceEvent:RegisterEvent
Xiiph@0: -- @class function
Xiiph@0: -- @paramsig event[, callback [, arg]]
Xiiph@0: -- @param event The event to register for
Xiiph@0: -- @param callback The callback function to call when the event is triggered (funcref or method, defaults to a method with the event name)
Xiiph@0: -- @param arg An optional argument to pass to the callback function
Xiiph@0: 
Xiiph@0: --- Unregister an event.
Xiiph@0: -- @name AceEvent:UnregisterEvent
Xiiph@0: -- @class function
Xiiph@0: -- @paramsig event
Xiiph@0: -- @param event The event to unregister
Xiiph@0: 
Xiiph@0: --- Register for a custom AceEvent-internal message.
Xiiph@0: -- The callback will be called with the optional `arg` as the first argument (if supplied), and the event name as the second (or first, if no arg was supplied)
Xiiph@0: -- Any arguments to the event will be passed on after that.
Xiiph@0: -- @name AceEvent:RegisterMessage
Xiiph@0: -- @class function
Xiiph@0: -- @paramsig message[, callback [, arg]]
Xiiph@0: -- @param message The message to register for
Xiiph@0: -- @param callback The callback function to call when the message is triggered (funcref or method, defaults to a method with the event name)
Xiiph@0: -- @param arg An optional argument to pass to the callback function
Xiiph@0: 
Xiiph@0: --- Unregister a message
Xiiph@0: -- @name AceEvent:UnregisterMessage
Xiiph@0: -- @class function
Xiiph@0: -- @paramsig message
Xiiph@0: -- @param message The message to unregister
Xiiph@0: 
Xiiph@0: --- Send a message over the AceEvent-3.0 internal message system to other addons registered for this message.
Xiiph@0: -- @name AceEvent:SendMessage
Xiiph@0: -- @class function
Xiiph@0: -- @paramsig message, ...
Xiiph@0: -- @param message The message to send
Xiiph@0: -- @param ... Any arguments to the message
Xiiph@0: 
Xiiph@0: 
Xiiph@0: -- Embeds AceEvent into the target object making the functions from the mixins list available on target:..
Xiiph@0: -- @param target target object to embed AceEvent in
Xiiph@0: function AceEvent:Embed(target)
Xiiph@0: 	for k, v in pairs(mixins) do
Xiiph@0: 		target[v] = self[v]
Xiiph@0: 	end
Xiiph@0: 	self.embeds[target] = true
Xiiph@0: 	return target
Xiiph@0: end
Xiiph@0: 
Xiiph@0: -- AceEvent:OnEmbedDisable( target )
Xiiph@0: -- target (object) - target object that is being disabled
Xiiph@0: --
Xiiph@0: -- Unregister all events messages etc when the target disables.
Xiiph@0: -- this method should be called by the target manually or by an addon framework
Xiiph@0: function AceEvent:OnEmbedDisable(target)
Xiiph@0: 	target:UnregisterAllEvents()
Xiiph@0: 	target:UnregisterAllMessages()
Xiiph@0: end
Xiiph@0: 
Xiiph@0: -- Script to fire blizzard events into the event listeners
Xiiph@0: local events = AceEvent.events
Xiiph@0: AceEvent.frame:SetScript("OnEvent", function(this, event, ...)
Xiiph@0: 	events:Fire(event, ...)
Xiiph@0: end)
Xiiph@0: 
Xiiph@0: --- Finally: upgrade our old embeds
Xiiph@0: for target, v in pairs(AceEvent.embeds) do
Xiiph@0: 	AceEvent:Embed(target)
Xiiph@0: end