WoW:Handling events - Revision history

Move page script: Move page script moved page Handling events to WoW:Handling events without leaving a redirect

2023-08-15T04:48:30Z

Move page script moved page Handling events to Handling events without leaving a redirect

← Older revision	Revision as of 04:48, 15 August 2023
(No difference)

Bear at 20:51, 13 October 2019

2019-10-13T20:51:21Z

← Older revision		Revision as of 20:51, 13 October 2019
Line 1:		Line 1:
	{{eventapi}}Events are messages sent by the WoW client to UI code (OnEvent script handlers of Frame derivatives), mostly in reaction to things occurring in the game world. To process events, an addon needs to create an event handler and register it for the events it wishes to receive.		{{eventapi}}
			Events are messages sent by the WoW client to UI code (OnEvent script handlers of Frame derivatives), mostly in reaction to things occurring in the game world. To process events, an addon needs to create an event handler and register it for the events it wishes to receive.

	== Setting up an event handler ==		== Setting up an event handler ==

77.56.249.216: deleted a redundant "can "

2019-10-12T21:44:34Z

deleted a redundant "can "

← Older revision		Revision as of 21:44, 12 October 2019
Line 1:		Line 1:
	{{eventapi}}		{{eventapi}}Events are messages sent by the WoW client to UI code (OnEvent script handlers of Frame derivatives), mostly in reaction to things occurring in the game world. To process events, an addon needs to create an event handler and register it for the events it wishes to receive.
	Events are messages sent by the WoW client to UI code (OnEvent script handlers of Frame derivatives), mostly in reaction to things occurring in the game world. To process events, an addon needs to create an event handler and register it for the events it wishes to receive.

	== Setting up an event handler ==		== Setting up an event handler ==
Line 11:		Line 10:
	The addon's OnEvent script handler function should either handle the event, or call another addon function to handle the event.		The addon's OnEvent script handler function should either handle the event, or call another addon function to handle the event.

	In order to receive event notifications, the event handler frame needs to be registered for events the addon needs to handle; use frame:[[API_Frame_RegisterEvent\|RegisterEvent]]("eventName") to achieve this. The RegisterEvent function ~~can~~ can be called at any time after the frame's creation; the OnLoad script handler is a convenient location to register for the desired events when using XML.		In order to receive event notifications, the event handler frame needs to be registered for events the addon needs to handle; use frame:[[API_Frame_RegisterEvent\|RegisterEvent]]("eventName") to achieve this. The RegisterEvent function can be called at any time after the frame's creation; the OnLoad script handler is a convenient location to register for the desired events when using XML.

	If you no longer wish to receive event notifications for a particular event, use the frame:[[API_Frame_UnregisterEvent\|UnregisterEvent]]() function. If you wish to disable all event notifications currently delivered to a frame, use the frame:[[API_Frame_UnregisterAllEvents\|UnregisterAllEvents]]().		If you no longer wish to receive event notifications for a particular event, use the frame:[[API_Frame_UnregisterEvent\|UnregisterEvent]]() function. If you wish to disable all event notifications currently delivered to a frame, use the frame:[[API_Frame_UnregisterAllEvents\|UnregisterAllEvents]]().

Bear at 22:05, 17 September 2013

2013-09-17T22:05:34Z

← Older revision		Revision as of 22:05, 17 September 2013
Line 1:		Line 1:
	{{~~UIHowTo~~}}		{{eventapi}}
	Events are messages sent by the WoW client to UI code (OnEvent script handlers of Frame derivatives), mostly in reaction to things occurring in the game world. To process events, an addon needs to create an event handler and register it for the events it wishes to receive.		Events are messages sent by the WoW client to UI code (OnEvent script handlers of Frame derivatives), mostly in reaction to things occurring in the game world. To process events, an addon needs to create an event handler and register it for the events it wishes to receive.

Line 5:		Line 5:
	Events are sent to Frame-derived [[Widget API\|widgets]]; an add-on needs to create a frame if it does not already own one that can be used for the purpose of handling events. Frames may be created in Lua using the [[API_CreateFrame\|CreateFrame]] function; or constructed in XML (using the <Frame> tag).		Events are sent to Frame-derived [[Widget API\|widgets]]; an add-on needs to create a frame if it does not already own one that can be used for the purpose of handling events. Frames may be created in Lua using the [[API_CreateFrame\|CreateFrame]] function; or constructed in XML (using the <Frame> tag).

	Once a frame has been created, its OnEvent handler must be set to a function that would handle the event on behalf of the addon. The OnEvent script handler may be set using the Lua frame:[[API_Frame_SetScript\|SetScript]]() function; or constructed in XML (using <Scripts><OnEvent>function body</OnEvent></Scripts>). The OnEvent handler function receives at least two arguments:		Once a frame has been created, its OnEvent handler must be set to a function that would handle the event on behalf of the addon. The OnEvent script handler may be set using the Lua frame:[[API_Frame_SetScript\|SetScript]]() function; or constructed in XML (using <Scripts><OnEvent>function body</OnEvent></Scripts>). The OnEvent handler function receives at least two arguments:
	# self, a reference to the frame to which the script handler belongs		# self, a reference to the frame to which the script handler belongs
	# event, the name of the event being fired		# event, the name of the event being fired

WoWWiki>Egingell at 09:19, 12 August 2010

2010-08-12T09:19:26Z

← Older revision		Revision as of 09:19, 12 August 2010
Line 8:		Line 8:
	# self, a reference to the frame to which the script handler belongs		# self, a reference to the frame to which the script handler belongs
	# event, the name of the event being fired		# event, the name of the event being fired
	# The remaining event arguments are placed within the vararg expression (...), as well as in the arg1-arg9 variables (the ~~later~~ mechanic is deprecated and ~~may~~ be removed in ~~the future~~). You can extract variables from the vararg expression by simply assigning it to your local variables: <code>local arg1, arg2, arg3 = ...;</code>		# The remaining event arguments are placed within the vararg expression (...), as well as in the arg1-arg9 variables (the latter mechanic is deprecated and will be removed in Cataclysm<ref name="deprecated">[http://forums.worldofwarcraft.com/thread.html?topicId=25626580975 Preparing for Cataclysm]</ref>). You can extract variables from the vararg expression by simply assigning it to your local variables: <code>local arg1, arg2, arg3 = ...;</code>
	The addon's OnEvent script handler function should either handle the event, or call another addon function to handle the event.		The addon's OnEvent script handler function should either handle the event, or call another addon function to handle the event.

Line 98:		Line 98:

	== Notes ==		== Notes ==
	* ~~Avoid using the~~ global this, event, and ~~arg1-arg9~~ variables ~~(which~~ are ~~generally~~ deprecated). Instead, use the arguments passed to the OnEvent script handler.		* The global this, event, and argX variables are being removed in Cataclysm<ref name="deprecated"/>. Instead, use the arguments passed to the OnEvent script handler.

	== Relevant API ==		== Relevant API ==
	* [[API_CreateFrame\|CreateFrame]]("widgetType"[, "name"[, parent[, "inherits"]]])		* [[API_CreateFrame\|CreateFrame]]("widgetType"[, "name"[, parent[, "inherits"]]])
	* frame:[[API_Frame_SetScript\|SetScript]]("handlerType", func)		* frame:[[API_Frame_SetScript\|SetScript]]("handlerType", func)
			* frame:[[API_Frame_HookScript\|HookScript]]("handlerType", func)
	* frame:[[API_Frame_RegisterEvent\|RegisterEvent]]("eventName") (and possibly frame:[[API_Frame_RegisterAllEvents\|RegisterAllEvents]]() )		* frame:[[API_Frame_RegisterEvent\|RegisterEvent]]("eventName") (and possibly frame:[[API_Frame_RegisterAllEvents\|RegisterAllEvents]]() )
	* frame:[[API_Frame_UnregisterEvent\|UnregisterEvent]]("eventName") (and possibly frame:[[API_Frame_UnregisterAllEvents\|UnregisterAllEvents]]() )		* frame:[[API_Frame_UnregisterEvent\|UnregisterEvent]]("eventName") (and possibly frame:[[API_Frame_UnregisterAllEvents\|UnregisterAllEvents]]() )
	* [[Events (API)]], a listing of events you may subscribe to.		* [[Events (API)]], a listing of events you may subscribe to.

			== References ==
			{{reflist}}

WoWWiki>Alicanc: fixed typo in example code

2009-11-22T18:19:19Z

fixed typo in example code

← Older revision		Revision as of 18:19, 22 November 2009
Line 5:		Line 5:
	Events are sent to Frame-derived [[Widget API\|widgets]]; an add-on needs to create a frame if it does not already own one that can be used for the purpose of handling events. Frames may be created in Lua using the [[API_CreateFrame\|CreateFrame]] function; or constructed in XML (using the <Frame> tag).		Events are sent to Frame-derived [[Widget API\|widgets]]; an add-on needs to create a frame if it does not already own one that can be used for the purpose of handling events. Frames may be created in Lua using the [[API_CreateFrame\|CreateFrame]] function; or constructed in XML (using the <Frame> tag).

	Once a frame has been created, its OnEvent handler must be set to a function that would handle the event on behalf of the addon. The OnEvent script handler may be set using the Lua frame:[[API_Frame_SetScript\|SetScript]]() function; or constructed in XML (using <Scripts><OnEvent>function body</OnEvent</Scripts>). The OnEvent handler function receives at least two arguments:		Once a frame has been created, its OnEvent handler must be set to a function that would handle the event on behalf of the addon. The OnEvent script handler may be set using the Lua frame:[[API_Frame_SetScript\|SetScript]]() function; or constructed in XML (using <Scripts><OnEvent>function body</OnEvent></Scripts>). The OnEvent handler function receives at least two arguments:
	# self, a reference to the frame to which the script handler belongs		# self, a reference to the frame to which the script handler belongs
	# event, the name of the event being fired		# event, the name of the event being fired

WoWWiki>Starlightblunder: /* Relevant API */ quote widget type

2009-11-14T19:03:23Z

Relevant API: quote widget type

← Older revision		Revision as of 19:03, 14 November 2009
Line 101:		Line 101:

	== Relevant API ==		== Relevant API ==
	* [[API_CreateFrame\|CreateFrame]](widgetType[, "name"[, parent[, "inherits"]]])		* [[API_CreateFrame\|CreateFrame]]("widgetType"[, "name"[, parent[, "inherits"]]])
	* frame:[[API_Frame_SetScript\|SetScript]]("handlerType", func)		* frame:[[API_Frame_SetScript\|SetScript]]("handlerType", func)
	* frame:[[API_Frame_RegisterEvent\|RegisterEvent]]("eventName") (and possibly frame:[[API_Frame_RegisterAllEvents\|RegisterAllEvents]]() )		* frame:[[API_Frame_RegisterEvent\|RegisterEvent]]("eventName") (and possibly frame:[[API_Frame_RegisterAllEvents\|RegisterAllEvents]]() )
	* frame:[[API_Frame_UnregisterEvent\|UnregisterEvent]]("eventName") (and possibly frame:[[API_Frame_UnregisterAllEvents\|UnregisterAllEvents]]() )		* frame:[[API_Frame_UnregisterEvent\|UnregisterEvent]]("eventName") (and possibly frame:[[API_Frame_UnregisterAllEvents\|UnregisterAllEvents]]() )
	* [[Events (API)]], a listing of events you may subscribe to.		* [[Events (API)]], a listing of events you may subscribe to.

WoWWiki>Viperaberus: Fix typo in UnregisterEvent

2009-06-16T12:17:38Z

Fix typo in UnregisterEvent

← Older revision		Revision as of 12:17, 16 June 2009
Line 104:		Line 104:
	* frame:[[API_Frame_SetScript\|SetScript]]("handlerType", func)		* frame:[[API_Frame_SetScript\|SetScript]]("handlerType", func)
	* frame:[[API_Frame_RegisterEvent\|RegisterEvent]]("eventName") (and possibly frame:[[API_Frame_RegisterAllEvents\|RegisterAllEvents]]() )		* frame:[[API_Frame_RegisterEvent\|RegisterEvent]]("eventName") (and possibly frame:[[API_Frame_RegisterAllEvents\|RegisterAllEvents]]() )
	* frame:[[API_Frame_UnregisterEvent\|~~UnegisterEvent~~]]("eventName") (and possibly frame:[[API_Frame_UnregisterAllEvents\|UnregisterAllEvents]]() )		* frame:[[API_Frame_UnregisterEvent\|UnregisterEvent]]("eventName") (and possibly frame:[[API_Frame_UnregisterAllEvents\|UnregisterAllEvents]]() )
	* [[Events (API)]], a listing of events you may subscribe to.		* [[Events (API)]], a listing of events you may subscribe to.

WoWWiki>Starlightblunder: Content from Events (API)

2009-02-20T08:56:19Z

Content from Events (API)

New page

{{UIHowTo}}
Events are messages sent by the WoW client to UI code (OnEvent script handlers of Frame derivatives), mostly in reaction to things occurring in the game world. To process events, an addon needs to create an event handler and register it for the events it wishes to receive.

== Setting up an event handler ==
Events are sent to Frame-derived [[Widget API|widgets]]; an add-on needs to create a frame if it does not already own one that can be used for the purpose of handling events. Frames may be created in Lua using the [[API_CreateFrame|CreateFrame]] function; or constructed in XML (using the <Frame> tag).

Once a frame has been created, its OnEvent handler must be set to a function that would handle the event on behalf of the addon. The OnEvent script handler may be set using the Lua frame:[[API_Frame_SetScript|SetScript]]() function; or constructed in XML (using <Scripts><OnEvent>function body</OnEvent</Scripts>). The OnEvent handler function receives at least two arguments:
# self, a reference to the frame to which the script handler belongs
# event, the name of the event being fired
# The remaining event arguments are placed within the vararg expression (...), as well as in the arg1-arg9 variables (the later mechanic is deprecated and may be removed in the future). You can extract variables from the vararg expression by simply assigning it to your local variables: <code>local arg1, arg2, arg3 = ...;</code>
The addon's OnEvent script handler function should either handle the event, or call another addon function to handle the event.

In order to receive event notifications, the event handler frame needs to be registered for events the addon needs to handle; use frame:[[API_Frame_RegisterEvent|RegisterEvent]]("eventName") to achieve this. The RegisterEvent function can can be called at any time after the frame's creation; the OnLoad script handler is a convenient location to register for the desired events when using XML.

If you no longer wish to receive event notifications for a particular event, use the frame:[[API_Frame_UnregisterEvent|UnregisterEvent]]() function. If you wish to disable all event notifications currently delivered to a frame, use the frame:[[API_Frame_UnregisterAllEvents|UnregisterAllEvents]]().

== Examples ==
===Hello World===
The two implementations below are functionally identical: they print "Hello World! Hello PLAYER_ENTERING_WORLD" to the default chat frame when the character zones into the world. Note that the event variable is implicit in the XML OnEvent handler: it is supplied by the OnEvent closure signature.

'''Using XML'''
<Ui>
<Frame name="FooAddonFrame">
<Scripts>
<OnLoad> self:RegisterEvent("PLAYER_ENTERING_WORLD"); </OnLoad>
<OnEvent> print("Hello World! Hello " .. event); </OnEvent>
</Scripts>
</Frame>
</Ui>

'''Using Lua'''
local frame = CreateFrame("FRAME", "FooAddonFrame");
frame:RegisterEvent("PLAYER_ENTERING_WORLD");
local function eventHandler(self, event, ...)
print("Hello World! Hello " .. event);
end
frame:SetScript("OnEvent", eventHandler);

=== XML-Specific ===
You may bind an already declared Lua function to the OnEvent handler in XML directly, rather than creating another function by providing a function body within the <OnEvent></OnEvent> tags. Doing so will save you memory:

'''FooAddOn.lua'''
function FooHandler_OnEvent(self, event, ...)
-- insert event handling code here
end

'''FooAddOn.xml'''
<Ui>
<Script file="FooAddon.lua"/>
<Frame name="FooHandler">
<Scripts>
<OnEvent function="FooHandler_OnEvent"/>
</Scripts>
</Frame>
</Ui>

=== Lua-specific ===
If your frame registers a large number of events, you could reduce the required number of if clauses, and generally simplify your design by doing:
local frame, events = CreateFrame("Frame"), {};
function events:PLAYER_ENTERING_WORLD(...)
-- handle PLAYER_ENTERING_WORLD here
end
function events:PLAYER_LEAVING_WORLD(...)
-- handle PLAYER_LEAVING_WORLD here
end
frame:SetScript("OnEvent", function(self, event, ...)
events[event](self, ...); -- call one of the functions above
end);
for k, v in pairs(events) do
frame:RegisterEvent(k); -- Register all events for which handlers have been defined
end
Note that in the case of the events:XXX functions above, the variable self, implicitly defined by using the function table:functionName notation, will point to the frame handling the event rather than the events table.

=== The vararg expression ===
The vararg expression (...) may contain additional arguments supplied by the event. Arguments contained in ... can be read by simply assigning them to other variables, possibly using the [[API_select|select]] function to skip forward to a specific argument in the list.

Consider the example of handling [[API_COMBAT_LOG_EVENT|COMBAT_LOG_EVENT]]:
function eventHandler(self, event, ...)
if event == "COMBAT_LOG_EVENT" then
local timestamp, combatEvent, sourceGUID, sourceName, sourceFlags, destGUID, destName, destFlags =
...; -- Those arguments appear for all combat event variants.
local eventPrefix, eventSuffix = combatEvent:match("^(.-)_?([^_]*)$");
if eventSuffix == "DAMAGE" then
-- Something dealt damage. The last 9 arguments in ... describe how it was dealt.
-- To extract those, we can use the select function:
local amount, overkill, school, resisted, blocked, absorbed, critical, glancing, crushing =
select(select("#", ...)-8, ...); -- select("#", ...) returns number of arguments in the vararg expression
-- Do something with the damage details ...
if eventPrefix == "RANGE" or eventPrefix:match("^SPELL") then
-- The first three arguments after destFlags in ... describe the spell or ability dealing damage.
-- Extract this data using select as well:
local spellId, spellName, spellSchool = select(9, ...); -- Everything from 9th argument in ... onward
-- Do something with the spell details ...
end
end
end
end

== Notes ==
* Avoid using the global this, event, and arg1-arg9 variables (which are generally deprecated). Instead, use the arguments passed to the OnEvent script handler.

== Relevant API ==
* [[API_CreateFrame|CreateFrame]](widgetType[, "name"[, parent[, "inherits"]]])
* frame:[[API_Frame_SetScript|SetScript]]("handlerType", func)
* frame:[[API_Frame_RegisterEvent|RegisterEvent]]("eventName") (and possibly frame:[[API_Frame_RegisterAllEvents|RegisterAllEvents]]() )
* frame:[[API_Frame_UnregisterEvent|UnegisterEvent]]("eventName") (and possibly frame:[[API_Frame_UnregisterAllEvents|UnregisterAllEvents]]() )
* [[Events (API)]], a listing of events you may subscribe to.