m
Move page script moved page Hooking functions to WoW:Hooking functions without leaving a redirect
({{UIHowTo}}) |
m (Move page script moved page Hooking functions to WoW:Hooking functions without leaving a redirect) |
||
| (11 intermediate revisions by 7 users not shown) | |||
| Line 1: | Line 1: | ||
{{ | {{wow/uihowto}} | ||
'''Hooking functions''' allows you to replace a function value in an accessible environment by a function of your own, calling the original function before or after execution of new code. Hooking enables addons to modify and/or extend the behavior of the default UI and API. | '''Hooking functions''' allows you to replace a function value in an accessible environment by a function of your own, calling the original function before or after execution of new code. Hooking enables addons to modify and/or extend the behavior of the default UI and API. | ||
Depending on how the behavior of the original function is | Depending on how the behavior of the original function is modified, one or more of three hook types may be used: | ||
;Pre-hooks : New code executes before calling the original function, potentially choosing to modify the parameters passed to it, or not call it at all | ;Pre-hooks : New code executes before calling the original function, potentially choosing to modify the parameters passed to it, or not call it at all | ||
;Post-hooks : New code executes after the original function, potentially using the original function's return values. | ;Post-hooks : New code executes after the original function, potentially using the original function's return values. | ||
| Line 20: | Line 20: | ||
== Hooking a function == | == Hooking a function == | ||
To illustrate the concept, let's create a pre-hook. Pre-hooks are commonly used to override user interface functions that perform an (unprotected) action, potentially adding behavior to existing UI. In this example, hook | To illustrate the concept, let's create a pre-hook. Pre-hooks are commonly used to override user interface functions that perform an (unprotected) action, potentially adding behavior to existing UI. In this example, hook {{api|ChatFrame_OnHyperlinkShow}} (a function called when the user clicks on a chat link) to display a faux tooltip for the item Tinfoil Hat, an item currently not in the game. | ||
<div style="max-height: 200px; overflow: auto; border: 2px solid black; padding: 0.5em; margin-left: 0.5em"> | <div style="max-height: 200px; overflow: auto; border: 2px solid black; padding: 0.5em; margin-left: 0.5em"> | ||
<pre style="margin: 0; border: 0"><nowiki>local | <pre style="margin: 0; border: 0"><nowiki>local origChatFrame_OnHyperlinkShow = ChatFrame_OnHyperlinkShow; -- (1) | ||
ChatFrame_OnHyperlinkShow = function(...) -- (2) | |||
local link, text, button = ...; -- (3) | local chatFrame, link, text, button = ...; -- (3) | ||
if type(text) == "string" and text:match("%[Tinfoil Hat%]") and not IsModifiedClick() then --(4) | if type(text) == "string" and text:match("%[Tinfoil Hat%]") and not IsModifiedClick() then --(4) | ||
return ShowTinfoilHat(); -- (5) | return ShowTinfoilHat(); -- (5) | ||
end | end | ||
return | return origChatFrame_OnHyperlinkShow(...); -- (6) | ||
end | end | ||
print("Click me: \124cff0070dd\124Hitem:8191:0:0:0:0:0:0:0:0:1\124h[Tinfoil Hat]\124h\124r"); -- (7) | print("Click me: \124cff0070dd\124Hitem:8191:0:0:0:0:0:0:0:0:1\124h[Tinfoil Hat]\124h\124r"); -- (7) | ||
| Line 53: | Line 53: | ||
ItemRefTooltip:Show(); ItemRefTooltip:Show(); | ItemRefTooltip:Show(); ItemRefTooltip:Show(); | ||
end</nowiki></pre></div> | end</nowiki></pre></div> | ||
[[ | [[File:Hooking functions demo.png|thumb|right|The resulting tooltip.]] | ||
Explained in detail, the preceding code does: | Explained in detail, the preceding code does: | ||
# Stores the old | # Stores the old ChatFrame_OnHyperlinkShow value (original function) into a local variable | ||
# Changes the value of the | # Changes the value of the ChatFrame_OnHyperlinkShow variable to a new function (the pre-hook). Note the vararg expression (...) in the function signature. | ||
# Extract known arguments from the vararg expression for local use. | # Extract known arguments from the vararg expression for local use. | ||
# Check whether link text is a string, whether it matches [Tinfoil Hat], and whether we should display a tooltip | # Check whether link text is a string, whether it matches [Tinfoil Hat], and whether we should display a tooltip | ||
# If all of the | # If all of the preceding conditions are true, call our ShowTinfoilHat() function to construct the faux tooltip, and do not call the original handler. | ||
# Otherwise, call the original handler and let it handle the click. | # Otherwise, call the original handler and let it handle the click. | ||
# Add a faux Tinfoil Hat item link to the chat frame to enable testing of this code. | # Add a faux Tinfoil Hat item link to the chat frame to enable testing of this code. | ||
The example used the vararg expression to make sure that, should the API change, the hook will still pass exactly the arguments it was given (no more, no less) to the original function. An additional sanity check on the type of the link argument in 3 prevents a potential error: if the function was not passed a string as expected (for example, by another addon), we do not want to block the default behavior. | The example used the vararg expression to make sure that, should the API change, the hook will still pass exactly the arguments it was given (no more, no less) to the original function. An additional sanity check on the type of the link argument in 3 prevents a potential error: if the function was not passed a string as expected (for example, by another addon), we do not want to block the default behavior. | ||
== Post-hooking == | == Post-hooking == | ||
| Line 103: | Line 101: | ||
; Insecure hooking : If you want to alter behavior significantly, it may be easier to call widget:[[API_Frame_GetScript|GetScript]] to get the original handler, and widget:[[API_Frame_SetScript|SetScript]] to set a hooked verson. | ; Insecure hooking : If you want to alter behavior significantly, it may be easier to call widget:[[API_Frame_GetScript|GetScript]] to get the original handler, and widget:[[API_Frame_SetScript|SetScript]] to set a hooked verson. | ||
; Secure hooking: widget:[[API_Frame_HookScript|HookScript]] allows you to set up a secure post-hook that will be called after the original handler, with the same arguments as the original handler. | ; Secure hooking: widget:[[API_Frame_HookScript|HookScript]] allows you to set up a secure post-hook that will be called after the original handler, with the same arguments as the original handler. | ||
== Hooking object methods == | |||
Functions called using the object calling syntax, <code>object:method(...)</code>, can also be hooked; one simply has to remember that the construct is merely syntactic sugar for <code>object.method(object, ...);</code>. To hook a function that was originally declared as: | |||
function AnAddon.Module:FuncName(arg1) | |||
-- Things happen here... | |||
end | |||
We store the original function and replace it with a hook: | |||
local original_AnAddon_Module_FuncName = AnAddon.Module.FuncName; | |||
function AnAddon.Module:FuncName(...) | |||
local arg1 = ...; -- Use the vararg expression in case the function signature changes | |||
if type(arg1) == "number" and arg1 > 0 then | |||
-- Call the original function; because of object calling syntax, | |||
-- pass self as the first argument. | |||
return original_AnAddon_Module_FuncName(self, ...); | |||
end | |||
end | |||
The example hook above will only allow the original function to be called if the first argument is a strictly positive number. | |||
== Removing existing hooks == | == Removing existing hooks == | ||
Removing hooks is generally problematic: there's no way to remove a hooksecurefunc-based post-hook, and insecure hooks may only be removed in some situations. The difficulty arises from the fact that multiple addons may want to hook the same function -- and if any addon but the top-most in the hooking chain wants to unhook, there's no way to tell the hook on top of your function to call the function below. It is therefore recommended to simply make your existing hook pass arguments and return values directly through if you don't want to deal with the data. For example: | Removing hooks is generally problematic: there's no way to remove a hooksecurefunc-based post-hook, and insecure hooks may only be removed in some situations. The difficulty arises from the fact that multiple addons may want to hook the same function -- and if any addon but the top-most in the hooking chain wants to unhook, there's no way to tell the hook on top of your function to call the function below. It is therefore recommended to simply make your existing hook pass arguments and return values directly through if you don't want to deal with the data. For example: | ||
local oldFunction = someGlobalFunc; | local oldFunction, noLongerRelevant = someGlobalFunc, false; | ||
function someGlobalFunc(...) | function someGlobalFunc(...) | ||
if noLongerRelevant then | if noLongerRelevant then | ||
| Line 114: | Line 129: | ||
end | end | ||
end | end | ||
Libraries may contain functions that allow you to "unhook" your method -- those operate primarily by moving the ignore switch further up the execution tree: if you | Libraries may contain functions that allow you to "unhook" your method -- those operate primarily by moving the ignore switch further up the execution tree: if you remove your hook, it won't get called, but the library's hook function stays in place. | ||
== Notes == | == Notes == | ||
* Warning! Blizzard has moved some pieces of the UI to be loaded on demand. The functions in those pieces cannot be hooked until they are loaded. | * Warning! Blizzard has moved some pieces of the UI to be loaded on demand. The functions in those pieces cannot be hooked until they are loaded. | ||
* Some libraries, like [[Sea]], [[Ace]], or [[Ace2]] offer functions to assist in hooking. | * Some libraries, like [[Sea (AddOn)]], [[Ace (AddOn)]], or [[Ace2 (AddOn)]] offer functions to assist in hooking. | ||