WoW:Hooking functions - Revision history

Move page script: Move page script moved page Hooking functions to WoW:Hooking functions without leaving a redirect

2023-08-15T04:48:30Z

Move page script moved page Hooking functions to Hooking functions without leaving a redirect

← Older revision

Revision as of 04:48, 15 August 2023

Bear at 09:15, 21 May 2020

2020-05-21T09:15:29Z

← Older revision		Revision as of 09:15, 21 May 2020
Line 1:		Line 1:
	{{~~UIHowTo~~}}		{{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.

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 {{item\|Tinfoil Hat}}, an item currently not in the game.		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)

5.15.197.19: Modified a word,it wasn't spelled right.

2014-09-03T19:49:24Z

Modified a word,it wasn't spelled right.

← Older revision		Revision as of 19:49, 3 September 2014
Line 2:		Line 2:
	'''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 be modified, one or more of three hook types may be used:		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.

Bear at 02:49, 30 November 2013

2013-11-30T02:49:11Z

← Older revision		Revision as of 02:49, 30 November 2013
Line 133:		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.

WoWWiki>Starlightblunder: /* Hooking a function */ bullet does not belong under this section

2010-10-01T19:46:19Z

Hooking a function: bullet does not belong under this section

← Older revision		Revision as of 19:46, 1 October 2010
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.

	* ''You can hook a function like "AddonName:Function()" by replaceing the ":" with a "."'' (See [[Hooking_functions#Hooking_object_methods\|Hooking object methods]])

	== Post-hooking ==		== Post-hooking ==

WoWWiki>Zasurus: /* Hooking a function */

2010-10-01T18:52:50Z

Hooking a function

← Older revision		Revision as of 18:52, 1 October 2010
Line 65:		Line 65:
	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.

	* ''You can hook a function like "AddonName:Function()" by replaceing the ":" with a "."''		* ''You can hook a function like "AddonName:Function()" by replaceing the ":" with a "."'' (See [[Hooking_functions#Hooking_object_methods\|Hooking object methods]])

	== Post-hooking ==		== Post-hooking ==

WoWWiki>Starlightblunder: /* Hooking a function */ SetItemRef -> ChatFrame_OnHyperlinkShow

2010-09-17T15:44:12Z

Hooking a function: SetItemRef -> ChatFrame_OnHyperlinkShow

← Older revision		Revision as of 15:44, 17 September 2010
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_SetItemRef~~\|~~SetItemRef]]~~ (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.		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 ~~origSetItemRef~~ = ~~SetItemRef~~; -- (1)		<pre style="margin: 0; border: 0"><nowiki>local origChatFrame_OnHyperlinkShow = ChatFrame_OnHyperlinkShow; -- (1)
	~~SetItemRef~~ = function(...) -- (2)		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 ~~origSetItemRef~~(...); -- (6)		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 55:		Line 55:
	[[File:Hooking functions demo.png\|thumb\|right\|The resulting tooltip.]]		[[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 ~~SetItemRef~~ value (original function) into a local variable		# Stores the old ChatFrame_OnHyperlinkShow value (original function) into a local variable
	# Changes the value of the ~~SetItemRef~~ variable to a new function (the pre-hook). Note the vararg expression (...) in the function signature.		# 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
Line 103:		Line 103:
	; 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 131:
	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 ~~want to~~ remove your hook, it won't get called, but the library's hook function stays in place.		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.

	~~== Hooking functions with ":" in their name ==~~
	~~You can hook a function like "AddonName:Function()" by replaceing the ":" with a ".".~~
	~~For example if the below code is from someone's addon:~~
	~~function AnAddon.Module:FuncName(per1,per2)~~
	~~-- Things happen here...~~
	~~end;~~

	~~You can use the following to pre-hook it:~~
	~~local original_AnAddon_Module_FuncName = AnAddon.Module.FuncName; -- Store the original function encase you want to use it.~~
	~~function AnAddon.Module:FuncName(per1,per2) -- This is the new function to overwrite the original one~~
	~~if (per1 > 10) then~~
	~~ChatFrame1:AddMessage(tostring(per1));~~
	~~else~~
	~~original_AnAddon_Module_FuncName(self,...); -- Calls original function like nothing happened~~
	~~end;~~
	~~end;~~

	~~Assuming per1 is a number greater than 10 then per2 will be printed and if per1 isn't then the original function will run~~.

	== 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]], [[Ace]], or [[Ace2]] offer functions to assist in hooking.

WoWWiki>Earthceltic at 02:25, 5 July 2010

2010-07-05T02:25:34Z

← Older revision		Revision as of 02:25, 5 July 2010
Line 116:		Line 116:
	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 want to remove your hook, it won't get called, but the library's hook function stays in place.		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 want to remove your hook, it won't get called, but the library's hook function stays in place.

	== Hooking functions with ":" in ~~there~~ name ==		== Hooking functions with ":" in their name ==
	You can hook a function like "AddonName:Function()" by replaceing the ":" with a ".".		You can hook a function like "AddonName:Function()" by replaceing the ":" with a ".".
	For example if the below code is from someone's addon:		For example if the below code is from someone's addon:

WoWWiki>Starlightblunder: /* Hooking functions with ":" in there name */ avoid tags for formatting

2010-07-05T02:21:30Z

Hooking functions with ":" in there name: avoid tags for formatting

← Older revision		Revision as of 02:21, 5 July 2010
Line 119:		Line 119:
	You can hook a function like "AddonName:Function()" by replaceing the ":" with a ".".		You can hook a function like "AddonName:Function()" by replaceing the ":" with a ".".
	For example if the below code is from someone's addon:		For example if the below code is from someone's addon:
			function AnAddon.Module:FuncName(per1,per2)
	~~<div style="max-height: 200px; overflow: auto; border: 2px solid black; padding: 0.5em; margin-left: 0.5em">~~		-- Things happen here...
	~~<pre style="margin: 0; border: 0"><nowiki>~~		end;
	function AnAddon.Module:FuncName(per1,per2)
	-- Things happen here...
	end;
	~~</nowiki></pre></div>~~

	You can use the following to pre-hook it:		You can use the following to pre-hook it:
			local original_AnAddon_Module_FuncName = AnAddon.Module.FuncName; -- Store the original function encase you want to use it.
	~~<div style="max-height: 200px; overflow: auto; border: 2px solid black; padding: 0.5em; margin-left: 0.5em">~~		function AnAddon.Module:FuncName(per1,per2) -- This is the new function to overwrite the original one
	~~<pre style="margin: 0; border: 0"><nowiki>~~		if (per1 > 10) then
	local original_AnAddon_Module_FuncName = AnAddon.Module.FuncName; -- Store the original function encase you want to use it.		ChatFrame1:AddMessage(tostring(per1));
			else
	function AnAddon.Module:FuncName(per1,per2) -- This is the new function to overwrite the original one		original_AnAddon_Module_FuncName(self,...); -- Calls original function like nothing happened
	if (per1 > 10) then		end;
	ChatFrame1:AddMessage(tostring(per1));		end;
	else
	original_AnAddon_Module_FuncName(self,...); -- Calls original function like nothing happened
	end;
	end;
	~~</nowiki></pre></div>~~

	Assuming per1 is a number greater than 10 then per2 will be printed and if per1 isn't then the original function will run.		Assuming per1 is a number greater than 10 then per2 will be printed and if per1 isn't then the original function will run.

WoWWiki>Zasurus: /* Hooking functions with ":" in there name */ Added a comment to clear up example

2010-07-04T16:12:19Z

Hooking functions with ":" in there name: Added a comment to clear up example

@@ Line 65: / Line 65: @@
 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.
+* ''You can hook a function like "AddonName:Function()" by replaceing the ":" with a "."''
 == Post-hooking ==
@@ Line 115: / Line 115: @@
   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 want to remove your hook, it won't get called, but the library's hook function stays in place.
 == 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.
 * Some libraries, like [[Sea]], [[Ace]], or [[Ace2]] offer functions to assist in hooking.