m
Move page script moved page Hooking functions to WoW:Hooking functions without leaving a redirect
m (Move page script moved page Hooking functions to WoW:Hooking functions without leaving a redirect) |
|||
| (4 intermediate revisions by 3 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 {{api|ChatFrame_OnHyperlinkShow}} (a function called when the user clicks on a chat link) to display a faux tooltip for the | 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 origChatFrame_OnHyperlinkShow = ChatFrame_OnHyperlinkShow; -- (1) | <pre style="margin: 0; border: 0"><nowiki>local origChatFrame_OnHyperlinkShow = ChatFrame_OnHyperlinkShow; -- (1) | ||
| Line 64: | Line 64: | ||
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 135: | Line 133: | ||
== 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. | ||