m
Move page script moved page Handling events to WoW:Handling events without leaving a redirect
(→Relevant API: quote widget type) |
m (Move page script moved page Handling events to WoW:Handling events without leaving a redirect) |
||
| (5 intermediate revisions by 4 users not shown) | |||
| 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. | 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 | ||
# The remaining event arguments are placed within the vararg expression (...), as well as in the arg1-arg9 variables (the | # 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. | ||
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 | 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]](). | ||
| Line 98: | Line 98: | ||
== Notes == | == Notes == | ||
* | * 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}} | |||