logo
back Back to Downloads

Pkg-MayronEvents

A lightweight event management package for World of Warcraft with support for custom addon events.

downloaddownloaddownloadDownload from WoWInterfacedownloaddownloaddownloadDownload from CurseForge
1

About

Pkg-MayronEvents is a lightweight package for managing World of Warcraft in-game events, as well as custom addon events, and supports both Retail and Classic. The prefix Pkg- refers to it being a package that is part of the MayronObjects packaging ecosystem and leverages its features to build a well-defined API to deliver a smooth development experience. Therefore, this package has a dependency on the MayronObjects framework. Please make sure to have downloaded this framework and have it loaded when using this package.

Pkg-MayronEvents lets you:

  • Create only a single Blizzard frame to register all Blizzard events, including unit events, using the package's EventManager class. The event manager takes care of registering and unregistering events on the frame. The event manager triggers each callback function registered with an event when the event fires.
  • Create custom events for your addon to fire, which can be handled by other addons using callback functions.
  • Assign custom event arguments to be passed automatically to your callback functions.
  • Set a callback function to execute only once. After it fires, it will automatically be unregistered from the event manager.

This package includes two classes:

  1. EventManager: Controls the registering and unregistering of Blizzard events using a Blizzard frame widget, and controls the execution of callback functions by detecting fired events. Allows you to create EventListener instances from the event manager.
  2. EventListener: Acts as a proxy for registering and unregistering Blizzard events (including unit events), as well as custom events. Event listeners are created with a callback function, which executes when one of its registered events fire. The event listener can be disabled and re-enabled to pause the execution of its callback function. Event listeners can also be assigned custom callback arguments to be passed to its callback function when the event executes. The event listener can be assigned an ID, making it easier to manage using the event manager.

There is a Test.lua file included in the downloaded addon folder to see other working examples of how to use this package.

As mentioned, this package has a dependency on the MayronObjects framework. Make sure you have that installed first.

2

Using the Package

Event listeners must be created from the event manager class. Therefore, you first need to create an event manager. To do this, import the EventManager class from the MayronEvents package using the MayronObjects framework:

local obj = MayronObjects:GetFramework(); ---@type MayronObjects local C_EventManager = obj:Import("Pkg-MayronEvents.EventManager");

When using MayronObjects, it is conventional to include the C_ prefix for class variables.

You can then create an instance of an event manager from this class:

local eventManager = C_EventManager();

To create event listeners from the event manager, you can use one of the following event manager methods:

  • CreateEventListener
  • CreateEventListenerWithID

The event listener's SetID method lets you assign an ID at any point, so the CreateEventListenerWithID is only a helper method that allows you to skip this step. By assigning an ID to an event listener, you can easily retrieve, trigger, enable, disable, and destroy the listener using its event manager by supply its ID used as a reference.

2.1 Event Listener Callback Functions

Each CreateEventListener method expects a callback function to be passed to it:

local function myCallback(self, event, customArg1, ...) print("Event: ", event); assert(customArg1 == "Hello"); -- will pass print("Blizzard event args: ", ...); end local listener = eventManager:CreateEventListenerByID("MyListener", myCallback); listener:SetCallbackArgs("Hello"); listener:RegisterEvent("PLAYER_ENTERING_WORLD");

Usually, the callback function would be declared inline with the call to the create method, but for simplicity the code snippet assigns the callback function to the myCallback local variable and then passes it to the create method.

Line 8 shows how to specify custyom callback arguments to pass to your callback function. The custom arguments are always added after the name of the event (the 2nd parameter) and before the variable argument list of extra event arguments.

Line 9 shows how to register a basic Blizzard event. There are several other methods available for registering event. Below is the full list of methods used to register events (see section 4 for more details for each method):

  • RegisterEvent: Register 1 Blizzard event.
  • RegisterEvents: A helper method to register multiple Blizzard events.
  • RegisterUnitEvent: Register 1 Blizzard unit event with a list of units.
  • RegisterUnitEvents: A helper method to register multiple Blizzard unit events for the same list of units passed to this method.
  • RegisterCustomEvent: Register a custom (non-Blizzard) addon event.
  • RegisterCustomEvents: A helper method to register multiple custom addon events.

There are also several unregister methods:

  • UnregisterEvent: Unregisters 1 Blizzard event (can be a unit event).
  • UnregisterEvents: A helper method to unregister multiple Blizzard events.
  • UnregisterCustomEvent: Unregister a custom (non-Blizzard) addon event.
  • UnregisterCustomEvents: A helper metod to unregister multiple custom events.
  • UnregisterAllEvents: Unregister all events. By default it will unregister all Blizzard events and custom addon events, but cna be passed false to the includeCustomEvents parameter to only unregister Blizzard events.

2.2 Custom AddOn Events

Unlike Blizzard events that are fired by World of Warcraft, custom addon events must be fired manually by the event manager. The FireCustomEvent event manager method also accepts a number of custom event arguments, which are sent to each callback function for event listeners who have registered the cutom event. Custom event arguments are included after the list of event listener specific arguments defined using SetCallbackArgs, as demonstrated in section 2.1.

local listener; local function callback(self, event, customArg1, eventArg1, eventArg2) -- each of these will pass: assert(self == listener); assert(event == "MY_CUSTOM_EVENT"); assert(customArg1 == "Hello"); assert(eventArg1 == "Foo"); assert(eventArg1 == "Bar"); end listener = eventManager:CreateEventListener(callback); listener:SetCallbackArgs("Hello"); listener:RegisterCustomEvent("MY_CUSTOM_EVENT"); -- Fire the custom event from the manager: eventManager:FireCustomEvent("MY_CUSTOM_EVENT", "Foo", "Bar");

The above code snippet shows how to pass custom event arguments to each event listener's callback function after their own custom arguments. You cannot register a custom event using RegisterEvent as this is for Blizzard-only events to be registered with a Blizzard frame. Custom events cannot be registered with a frame as this would result in an "Unknown event name" Lua error.

Similarly, you cannot fire Blizzard events manually, using FireCustomEvent as this would potentially cause addon bugs to occur by tricking addons into believing that a specific Blizzard event has fired. However, you can execute the callback function manually by using one of the following trigger methods. The only difference is that the event parameter will be set to nil and the World of Warcraft API will not be able to provide the usual event arguments:

  • TriggerEventListenerByID: Reference the event listener using its ID to execute its callback function.
  • TriggerEventListener: Pass the event listener object directly to this method to execute its callback function.

Each of these trigger methods also accepts an optional list of arguments to be passed to the targetted event listener's callback function, as shown below:

local function callback(self, event, message) -- triggering it manually will set this to nil. -- because no event was fired. assert(event == nil); assert(message = "Triggered Manually"); end local listener = eventManager:CreateEventListenerWithID( "MyEventListener", callback); local message = "Triggered Manually"; -- both of these will execute the callback function: eventManager:TriggerEventListener(listener, message); eventManager:TriggerEventListenerByID("MyEventListener", message);

2.3 Enabling, Disabling, and Destroying Event Listeners

In addition to being able to trigger the event listener's callback function using the ID as a reference, you can also use this ID to enable, disable, and destroy the event listener. By disabling an event listener, even if one of its registered events fires, the event manager will not locate and trigger its callback function. By default, the event listener will be enabled and so you do not need to manually enable it.

Unlike a disabled event listener, a destoryed event listener can never be re-enabled. You can not create an event listener with the same ID as another event listener already registered with the targetted event manager unless the original event listener was destroyed. Therefore, iof you ever need to "re-enable" a destroyed event listener, you would need to recreate it with the same ID and callback function. It is much simpler to simply disable and re-enable the same event listener rather than destroying it and recreating it. You should only destroy an event listener if it should never execute its callback function again.

Sometimes, callback functions should only ever execute once. For these typical scenarios, you would unregister the event straight after it executes. You can still do this, but a better solution would be to destroy the event listener, which also unregisters all of its events during the destruction process:

local listener = eventManager:CreateEventListener(function(self) print("Hello, World"); -- destroys the event listener and unregisters all of its events -- Ensures the callback function will never execute again self:Destroy(); end); listener:RegisterEvent("PLAYER_ENTERING_WORLD");

You can also mark the listener to be executed only once. If marked as "execute once", MayronEvents will automatically destroy it for you, which achieves the same results as the previous code snippet:

local listener = eventManager:CreateEventListener(function(self) print("Hello, World"); end); listener:RegisterEvent("PLAYER_ENTERING_WORLD"); -- destroys event listener after the callback functions first execution: listener:SetExecuteOnce(true);
3

EventManager API

The following documentation describes each EventManager method. You must first create an instance of the EventManager to be able to use these methods by calling them from the instance object:

local obj = MayronObjects:GetFramework(); local C_EventManager = obj:Import("Pkg-MayronEvents.EventManager") local eventManager = C_EventManager();

CreateEventListener(callback)

  • @param callback (function): A callback function to execute when a registered event is fired (while the event listener is enabled).
  • @return (EventListener): The event listener object used to register/unregister events, set custom arguments and more.

Creates an EventListener that calls the provided callback function when a registered event is fired (while the event listener is enabled).

CreateEventListenerWithID(callback)

  • @param id (string): The ID to reference the event listener object using the EventManager API.
  • @param callback (function): A callback function to execute when a registered event is fired (while the event listener is enabled).
  • @return (EventListener): The event listener object used to register/unregister events, set custom arguments and more.

Creates an EventListener with an ID that calls the provided callback function when a registered event is fired (while the event listener is enabled).

GetEventListenerByID(id)

  • @param id (string): The event listener's unique ID.
  • @return (EventListener): If an event listener with the provided ID is registered with the event manager, it will be returned.

GetEventListenersByEvent(event)

  • @param event (string): The Blizzard event name to check for.
  • @return ...: A variable list of EventListener objects who are registered with the provided Blizzard event.

Returns all event listeners created from the event manager that are also registered with the provided Blizzard event. These event listeners will trigger their associated callback functions when this Blizzard event is fired.

GetEventListenersByCustomEvent(customEvent)

  • @param event (string): The (non-BLizzard) custom addon event name to check for.
  • @return ...: A variable list of EventListener objects who are registered with the provided custom event.

Returns all event listeners created from the event manager that are also registered with the provided (non-BLizzard) custom addon event. These event listeners will trigger their associated callback functions when the custom event is fired using the event manager's FireCustomEvent method.

GetNumEventListenersByEvent(event)

  • @param event (string): The Blizzard event name to check for.
  • @return (number): The total number of event listeners listing out for the specified event.

A helper function to return the total number of event listener objects that are also registered with the provided Blizzard event, instead of a table containing all event listener objects using GetEventListenersByEvent.

GetNumEventListenersByCustomEvent(customEvent)

  • @param event (string): The (non-BLizzard) custom addon event name to check for.
  • @return (number): The total number of event listeners listing out for the specified custom event.

A helper function to return the total number of event listener objects that are also registered with the provided (non-Blizzard) custom addon event, instead of a table containing all event listener objects using GetEventListenersByCustomEvent.

TriggerEventListenerByID(id, ...)

  • @param id (string): The event listener's ID.
  • @vararg (any): Accepts a list of arguments to pass to the callback function being executed, in addition to the custom args assigned to the event listener object using SetCallbackArgs.

Manually executes the callback function associated with the event listener whose ID matches the provided ID. The callback function will receive a nil argument value for its event name parameter as no event was naturally fired.

TriggerEventListener(listener)

  • @param listener (EventListener): The event listener object.
  • @vararg (any): Accepts a list of arguments to pass to the callback function being executed, in addition to the custom args assigned to the event listener object using SetCallbackArgs.

Manually executes the callback function associated with the event listener. The callback function will receive a nil argument value for its event name parameter as no event was naturally fired.

FireCustomEvent(customEvent, ...)

  • @param customEvent (string): The name of the custom event to fire. ---@vararg any @Accepts a list of arguments to pass to the callback function being executed, in addition to the custom args assigned to the event listener object using SetCallbackArgs.
  • @vararg (any): Accepts a list of arguments to pass to the callback function being executed, in addition to the custom args assigned to the event listener object using SetCallbackArgs.

Fires a custom event to notify all event listeners registered with that custom event. This method cannot be used to fire Blizzard in-game events as this could cause unexpected bugs for other code using this event manager.

DestroyEventListeners(...)

  • @vararg (string): A variable argument list of IDs for referencing event listeners to be destroyed.

Destroys all event listeners and removes them from the event manager, whose IDs match those found in the list of provided arguments. Destroyed event listeners will not trigger their callback functions if the event is fired and can never be enabled.

DisableEventListeners(...)

  • @vararg (string): A variable argument list of IDs for referencing event listeners to be disabled.

Disables all event listeners whose IDs match those found in the list of provided arguments. Disabled event listeners will not trigger their callback functions if the event is fired.

EnableEventListeners(...)

  • @vararg (string): A variable argument list of IDs for referencing event listeners to be enabled.

Enables all event listeners whose IDs match those found in the list of provided arguments. Enables event listeners will trigger their callback functions if the event is fired.

4

EventListener API

The following documentation describes each event listener method. You can only call these methods on an instance of the EventListener class. Do not instantiate an instance directly from the class. Instead, use the event manager's CreateEventListener or CreateEventListenerWithID method (see section 3):

local listener = eventManager:CreateEventListener(function(self, event, ...) print("Hello, World"); end);

SetID(id)

  • @param id (string): A unique ID used to refer to the event listener when using the EventManager API. Can also be set when using the event manager's CreateEventListenerWithID method.

GetID()

  • @return (string): Returns the unique ID used to refer to the event listener when using the EventManager API.

If the event listener has not been assigned a custom unique ID, it will return the unique memory address of the handler object.

SetEnabled(enabled)

  • @param enabled (boolean): The new enabled state of the event listener.

Used to enable or disable the event listener. When disabled, the event listener will not trigger its associated callback function even if the event is fired.

IsEnabled()

  • @return (boolean): The current enabled state of the event listener.

Returns whether the event listener is enabled or disabled. When disabled, the event listener will not trigger its associated callback function even if the event is fired.

SetExecuteOnce(executeOnce)

  • @param executeOnce (boolean): Represents whether the event manager should destroy the event listener after executing it once.

If executeOnce is set to true, then the event listener object will be destroyed and removed from the event manager after its first execution. Some callback functions only need to be executed once. You can also call the Destroy() method on the event listener at any time to destroy it manually.

SetCallbackArgs(...)

  • @vararg (any): A list of custom callback arguments to be passed to the callback function each time it is executed.

Sets a custom list of callback arguments to be passed to the callback function each time it is triggered. These callback arguments will appear after the first two arguments (self, event), and before the event-specific arguments. Each time this method is called, it will replace previously specified custom callback arguments. Therefore, calling this method with no arguments will remove all of them. Note: If you call this method with only nil then nil will still be passed as a custom callback argument.

RegisterEvent(event)

  • @param event (string): The Blizzard event to register.

Register a Blizzard event for the event listener to listen out for. If enabled, the event listener will execute its callback function when the event fires.

RegisterEvents(...)

  • @vararg (string): A variable argument list of Blizzard event names register.

A helper method that takes a variable argument list of Blizzard event names and calls RegisterEvent for each one.

RegisterUnitEvent(event, unit1, unit2, unit3)

  • @param event (string): The Blizzard unit event to register.
  • @param unit1 (string): A unitID to register with the unit event (e.g., "player").
  • @param unit2 (string): An optional 2nd unitID to register with the unit event (e.g., "target").
  • @param unit3 (string): An optional 3rd unitID to register with the unit event (e.g., "focus").

Register a Blizzard unit event for the event listener to listen out for. If enabled, the event listener will execute its callback function when the event fires for one of the specified units.

RegisterUnitEvents(events, unit1, unit2, unit3, pushTable)

  • @param events (table): A table containing the Blizzard unit events to register.
  • @param unit1 (string): A unitID to register with the unit event (e.g., "player").
  • @param unit2 (string): An optional 2nd unitID to register with the unit event (e.g., "target").
  • @param unit3 (string): An optional 3rd unitID to register with the unit event (e.g., "focus").
  • @param pushTable (boolean): Optional boolean value to override the default "true" to avoid recycling the table passed to the events parameter. If not set to false, the table will be emptied and added to an internal stack for later use by the MayronObjects framework.

A helper method that takes a table of Blizzard event names and calls RegisterUnitEvent for each one with the provided unitIDs.

RegisterCustomEvent(customEvent)

  • @param customEvent (string): The non-Blizzard, custom addon event to register.

Register a non-Blizzard, custom addon event for the event listener to listen out for. If enabled, the event listener will execute its callback function when the event manager fires the custom event using its FireCustomEvent method.

RegisterCustomEvents(...)

  • @vararg (string): A variable argument list of (non-Blizzard) custom addon events to register.

A helper method that takes a variable argument list of custom event names and calls RegisterCustomEvent for each one.

UnregisterEvent(event)

  • @param event (string): The Blizzard event to unregister.

Unregister a Blizzard event to stop the event listener from triggering its callback function when the event is fired.

UnregisterEvents(...)

  • @vararg (string): A variable argument list of Blizzard events to unregister.

A helper method that takes a variable argument list of Blizzard event names and calls UnregisterEvent for each one.

UnregisterCustomEvent(customEvent)

  • @param customEvent (string): The non-Blizzard, custom addon event to unregister.

Unregister a (non-Blizzard) custom addon event to stop the event listener from triggering its callback function when the event manager fires the custom event using its FireCustomEvent method.

UnregisterCustomEvents(...)

  • @vararg (string): A variable argument list of (non-Blizzard) custom addon events to unregister.

A helper method that takes a variable argument list of custom event names and calls UnregisterCustomEvent for each one.

UnregisterAllEvents(includeCustomEvents)

  • @param includeCustomEvents (string): If set to false, only the Blizzard events will be unregistered and the custom addon events will remain registered with the event listener. By default, this parameter will be assigned true.

Unregister all Blizzard events and custom addon events from the event listener. This will stop the callback function from being executed when any previously registered event fires.

GetRegisteredEvents()

  • @return (table): A table containing all registered Blizzard events.

Returns all Blizzard events registered with this event listener. If any of these Blizzard events trigger when the event listener is enabled, the callback function will execute.

GetNumRegisteredEvents()

  • @return (number): The total number of Blizzard events registered with this event listener.

GetRegisteredCustomEvents()

@return (table): A table containing all registered (non-Blizzard) custom addon events.

Returns all (non-Blizzard) custom addon events registered with this event listener. Custom events are triggered using the EventManager API using the event manager's FireCustomEvent method, which will execute the callback function if the handler is enabled.

GetNumRegisteredCustomEvents()

  • @return (number): The total number of (non-Blizzard) custom addon events registered with this event listener.
back Back to Downloads

© 2021 MayronUI.com, All rights reserved.