Welcome to the 6th part of my addon tutorial! Today we'll be taking a look at the core elements in any World of Warcraft UI element, the Frames and their Events! Or put more simply, what happens in the game and how your addon can know about it!
Table of Contents
What is a Frame?
In World of Warcraft, a 'Frame' is a container for special UI items. These 'Frames' can react to happenings in the game, you can use them to display art, or let the user click something in them. They are what the UI is made of. Technically speaking, a Frame is a Lua table. So you can assign methods to it, and it can have 'children'. But don't worry about that for now.
What is an Event?
An 'Event' in World of Warcraft is a message sent by the WoW client to the user interface mostly in reaction to things occurring in the game world. Events are how the addon know what's going on. There are Events for nearly everything. When the player logs in, and Event fires. When you reload the user interface or zone into an instance, an Event fires. Events occur when you die, enter combat, leave combat, gain health or mana, join a battleground, receive a chat message, gain gold, and so on. A full list can be found here!
To track an Event, you need to make a Frame listen for it. You also need to create a script handler telling the Frame what to do when an Event occurs. So let's do that right now.
What we're going to do today, is to track when your character enters and leaves combat. This is one of the most important things to be aware of, as a lot of abilities like drinking, eating, mounting up and so forth are blocked in combat. There are also a lot of things the UI can't do during combat, like changing visibility and position of existing unitframes and so on. So let's get to it!
The Events we use to watch for combat, isn't what you might think from looking at the Event list on wowpedia. It's not "PLAYER_ENTER_COMBAT", as that only fires when your auto-attack starts. What you instead should listen for is when the out of combat regen starts and stops. That's the true indicator of when you're in combat or not, when abilities like mounting up, eating and drinking are available. The Events are called "PLAYER_REGEN_DISABLED" and "PLAYER_REGEN_ENABLED".
-- create the frame
local frame = CreateFrame("Frame", nil, UIParent)
-- assign the Events to it
-- create a script handler to react to the Events
frame:SetScript("OnEvent", function(self, event, ...)
-- we don't need it in this example,
-- but this is how you retrieve arguments passed along with Events:
local arg1, arg2, arg3 = ...
if event == "PLAYER_REGEN_DISABLED" then
print("You're in combat!")
elseif event == "PLAYER_REGEN_ENABLED" then
print("Combat ended, mount up and run!")
You can add this to the addon we made last time, or make a new addon for it. When it's saved properly and the game client restarted, you should now be getting warnings in the default chatframe when you enter and leave combat.
True, not a very useful addon as the UI already does this for you, but the point here wasn't to reinvent the powder, it was to show you how Events work, give you something to play around with!
The Event Tracer
Blizzard have provided us with a handful of useful debugging tools. One of them is the Event Tracer. Which is exactly what it sounds like, something that traces Events. You can activate it with the following command written into the chatframe inside the game:
Try it, and then wait for a while. You'll notice all sorts of Events occurring. If you mouse over any of them, you'll get more details about it like the arguments passed along with it. I find the Event Tracer to be one of the most useful tools in learning how the game and the UI works. No theory can beat actually seeing with your own eyes what's going on!
So, that was all I had for you today. I recommend that you study the list of Events at wowpedia, as well as checking out what other addon users are doing. A trick to figuring out stuff, is to find an addon that does something you like, then simply search that addon's code for "RegisterEvent" and "OnEvent". You can consider that one of my major secrets, actually. It doesn't seem like much, but it will take you straight to the heart of what's going on. You'll know what the addon is listening for, and what it does when it happens. I've spent countless hours gazing at what others have done, it's simply the best way to learn.
See you all next time!