AceEvent-3.0
From WowAce Wiki
AceEvent-3.0 handles registration and receiption of in-game events as well as custom messages between addons.
For in-game events, AceEvent is mainly provided as a convenience; there are no real benefits to using it performance wise over writing your own handlers.
- AceEvent allows you to easily unregister all registered events if your addon supports in-game disabling.
- If embedded into your addon object, AceEvent automatically unregisters all registered events when your addons is disabled.
- AceEvent simplifies binding events to member functions, e.g. MyAddon:PLAYER_ENTERS_WORLD(), including passing the right self to your member function.
Contents |
Events vs Messages
AceEvent-2.0 mixed the concept of Events and Messages in to the same category. AceEvent-3.0 separates them; there is no way to fire custom Events and fool other addons into thinking an event has occured. You can only fire custom Messages.
AceEvent Messages vs the CallbackHandler library
Most libraries providing events/callbacks to their users should use the CallbackHandler library to expose their events, as this removes the need for addons to be aware of AceEvent.
The only real reason to use AceEvent Messages over CallbackHandler callbacks is for events that can be triggered by multiple sources in the system. Those are very few.
How to access AceEvent
To simply get a reference to the library, query LibStub for it:
local AceEvent = LibStub:GetLibrary("AceEvent-3.0")
--- or, use the shorthand:
local AceEvent = LibStub("AceEvent-3.0")
Or, to embed AceEvent into your addon object, which may enable extra functionality in the library, such as automatically deregistering events, timers, closing frames, better error reporting, etc (see below):
local myAddon = LibStub("AceAddon-3.0"):NewAddon("myAddon", "AceEvent-3.0", ... )
Or, to embed it into an already-existing object/table:
LibStub("AceEvent-3.0"):Embed(myTable)
Embed behavior
If embedded in an AceAddon-3.0 object, AceEvent will automatically unregister all events and messages when the addon is disabled. If the addon supports being disabled, that is.
Event API
This is a wrapper for Blizzard's regular game events.
:RegisterEvent()
myAddon:RegisterEvent("eventName"[, method[, arg]])
AceEvent.RegisterEvent(myTable, "eventName"[, method[, arg]])
AceEvent.RegisterEvent("myAddonId", "eventName"[, method[, arg]])
- "eventName"
- (string) - the name of the event you want to listen to
- method
- (string or function) - which method to call. If string, self["method"] will be called. If left out (nil), self["eventName"] will be called.
- arg
- (optional) - If present (even nil), this value will be passed to the receiving function.
Registrations are always associated with the supplied self. This means that you'll want to embed AceEvent, or do the call like .RegisterEvent(myTable, ...). Note the use of " . " (period) rather than " : " (colon).
If you do not have a sane self table to associate your registrations with, you can substitute it for a string. Note the use of "." rather than ":".
-
AceEvent.RegisterEvent("myAddonId", "eventName", ...)
This string variant of a self will not be passed to the receiving function.
Callback arguments
If the method is a plain function, it will be called as:
-
method("eventName", (arguments to the event)) - or, with an arg specified when registering:
-
method(arg, "eventName", (arguments to the event))
If the method is a string (method name), it will be called as:
-
self["method"](self, "eventName", (arguments to the event)) - or, with an arg specified when registering:
-
self["method"](self, arg, "eventName", (arguments to the event))
:UnregisterEvent()
myAddon:UnregisterEvent("eventName")
AceEvent.UnregisterEvent(myTable, "eventName")
AceEvent.UnregisterEvent("myAddonId", "eventName")
- "eventName"
- the name of the event that you no longer wish to receive.
Note that the supplied self must match the self supplied to :RegisterEvent(), or nothing will be unregistered.
:UnregisterAllEvents()
:UnregisterAllEvents()
AceEvent.UnregisterAllEvents("myAddonId", myTable, ...)
UnregisterAllEvents will unregister all events associated with the given self, as well as with additional arguments given.
Message API
This is a light "inter-process-communication" API. Its purpose is to facilitate delivery of messages without a fixed source.
:RegisterMessage()
myAddon:RegisterMessage("messageName"[, method[, arg]])
AceEvent.RegisterMessage(myTable, "messageName"[, method[, arg]])
AceEvent.RegisterMessage("myAddonId", "messageName"[, method[, arg]])
- "messageName"
- (string) - the name of the event you want to listen to
- method
- (string or function) - which method to call. If string, self["method"] will be called. If left out (nil), self["eventName"] will be called.
- arg
- (optional) - If present (even nil), this value will be passed to the receiving function.
Registrations are always associated with the supplied self. This means that you'll want to embed AceEvent, or do the call like .RegisterMessage(myTable, ...). Note the use of " . " (period) rather than " : " (colon).
If you do not have a sane self table to associate your registrations with, you can substitute it for a string. Note the use of "." rather than ":".
-
AceEvent.RegisterMessage("myAddonId", "messageName", ...)
This string variant of a self will not be passed to the receiving function.
Callback arguments
If the method is a plain function, it will be called as:
-
method("messageName", (arguments to the event)) - or, with an arg specified when registering:
-
method(arg, "messageName", (arguments to the event))
If the method is a string (method name), it will be called as:
-
self["method"](self, "messageName", (arguments to the event)) - or, with an arg specified when registering:
-
self["method"](self, arg, "messageName", (arguments to the event))
:UnregisterMessage()
myAddon:UnregisterMessage("messageName")
AceEvent.UnregisterMessage(myTable, "messageName")
AceEvent.UnregisterMessage("myAddonId", "messageName")
- "messageName"
- the name of the event that you no longer wish to receive.
Note that the supplied self must match the self supplied to :RegisterMessage(), or nothing will be unregistered.
:UnregisterAllMessages()
:UnregisterAllMessages()
AceEvent.UnregisterAllMessages("myAddonId", myTable, ...)
UnregisterAllMessages will unregister all events associated with the given self, as well as with additional arguments given.
:SendMessage()
AceEvent:SendMessage("messageName"[, (arguments...)])
Send a message to all addons listening for it.
