AceHook-3.0

embeddable This library can be embedded into your addon as a mixin; list it when you create the addon and its methods become available directly on your addon object (via self).
Creating an addon object →

AceHook-3.0 offers safe Hooking/Unhooking of functions, methods and frame scripts. Using AceHook-3.0 is recommended when you need to unhook your hooks again, so the hook chain isn't broken when you manually restore the original function.

Usage

Embedding as a mixin is best, so hooks are cleaned up automatically if the user disables your addon:

lua

MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon", "AceHook-3.0")

Standard (pre-) hooks

A standard hook runs before the original and automatically calls the original afterward. Specify a function name, or an object + method name:

lua

MyAddon:Hook("APIFunctionName")
MyAddon:Hook(TargetObject, "TargetMethod")

By default the call is routed to a same-named method on your addon. Provide a custom handler if you prefer:

lua

MyAddon:Hook("APIFunctionName", handlerFunc)
MyAddon:Hook("APIFunctionName", "handlerMethod")

To hook a secure function despite the tainting risk, pass true as the final argument:

lua

MyAddon:Hook("APISecureFunctionName", handlerFunc, true)

Raw hooks

A raw hook completely replaces the original: you must call it yourself (via self.hooks) if you want it to run:

lua

MyAddon:RawHook("APIFunctionName")

function MyAddon:APIFunctionName(...)
    -- call the original through self.hooks
    self.hooks["APIFunctionName"](...)
end

Secure (post-) hooks

Secure hooks run after the original; return values are ignored. Use these for protected Blizzard UI elements to avoid taint:

lua

MyAddon:SecureHook("APISecureFunctionName")

Hooking scripts

Hook frame scripts with the *Script variants:

lua

MyAddon:HookScript(TargetFrame, "ScriptName")
MyAddon:RawHookScript(TargetFrame, "ScriptName")
MyAddon:SecureHookScript(TargetFrame, "ScriptName")

Checking for an existing hook

lua

local hookexists, hookhandler = MyAddon:IsHooked("APIFunctionName")

API Reference

Embed

method#

lua

AceHook:Embed(target)

Copies AceHook's methods onto target so you can call them on it directly. See The :Embed method.

Parameters

Parameter	Type	Default	Description
`target`	`table`		Target object to embed AceHook in.

Returns

Type	Description
`table`	The `target` object that was embedded.

Hook

method#

lua

AceHook:Hook(object?, method, handler?, hookSecure?)

Hook a function or a method on an object.

The hook created will be a "safe hook", that means that your handler will be called before the hooked function ("Pre-Hook"), and you don't have to call the original function yourself, however you cannot stop the execution of the function, or modify any of the arguments/return values.

This type of hook is typically used if you need to know if some function got called, and don't want to modify it.

Parameters

Parameter	Type	Description
`object` (optional)	`table`	The object to hook a method from.
`method`	`string`	The name of the method (if `object` is given), or the name of the function to hook.
`handler` (optional)	`function` \| `methodname`	The handler for the hook, a funcref or a method name. (Defaults to the name of the hooked function).
`hookSecure` (optional)	`boolean`	If true, AceHook will allow hooking of secure functions.

Example

lua

function MyAddon:OnEnable()
    -- Hook ActionButton_UpdateHotkeys, overwriting the secure status
    self:Hook("ActionButton_UpdateHotkeys", true)
end

function MyAddon:ActionButton_UpdateHotkeys(button, type)
    print(button:GetName() .. " is updating its HotKey")
end

RawHook

method#

lua

AceHook:RawHook(object?, method, handler?, hookSecure?)

RawHook a function or a method on an object.

The hook created will be a "raw hook", that means that your handler will completely replace the original function, and your handler has to call the original function (or not, depending on your intentions).

The original function will be stored in self.hooks[object][method] or self.hooks[functionName] respectively.

This type of hook can be used for all purposes, and is usually the most common case when you need to modify arguments or want to control execution of the original function.

Parameters

Parameter	Type	Description
`object` (optional)	`table`	The object to hook a method from.
`method`	`string`	The name of the method (if `object` is given), or the name of the function to hook.
`handler` (optional)	`function` \| `methodname`	The handler for the hook, a funcref or a method name. (Defaults to the name of the hooked function).
`hookSecure` (optional)	`boolean`	If true, AceHook will allow hooking of secure functions.

Example

lua

function MyAddon:OnEnable()
    -- Hook ActionButton_UpdateHotkeys, overwriting the secure status
    self:RawHook("ActionButton_UpdateHotkeys", true)
end

function MyAddon:ActionButton_UpdateHotkeys(button, type)
    if button:GetName() == "MyButton" then
        -- do stuff here
    else
        self.hooks.ActionButton_UpdateHotkeys(button, type)
    end
end

SecureHook

method#

lua

AceHook:SecureHook(object?, method, handler?)

SecureHook a function or a method on an object.

This function is a wrapper around the hooksecurefunc function in the WoW API. Using AceHook extends the functionality of secure hooks, and adds the ability to unhook once the hook isn't required anymore, or the addon is being disabled.

Secure Hooks should be used if the secure-status of the function is vital to its function, and taint would block execution. Secure Hooks are always called after the original function was called ("Post Hook"), and you cannot modify the arguments, return values or control the execution.

Parameters

Parameter	Type	Description
`object` (optional)	`table`	The object to hook a method from.
`method`	`string`	The name of the method (if `object` is given), or the name of the function to hook.
`handler` (optional)	`function` \| `methodname`	The handler for the hook, a funcref or a method name. (Defaults to the name of the hooked function).

Example

lua

function MyAddon:OnEnable()
    -- run our handler after the original UseAction fires
    self:SecureHook("UseAction", "OnUseAction")
end

function MyAddon:OnUseAction(slot)
    print("Action slot used: " .. slot)
end

HookScript

method#

lua

AceHook:HookScript(frame, script, handler?)

Hook a script handler on a frame.

The hook created will be a "safe hook", that means that your handler will be called before the hooked script ("Pre-Hook"), and you don't have to call the original function yourself, however you cannot stop the execution of the function, or modify any of the arguments/return values.

This is the frame script equivalent of the :Hook safe-hook. It would typically be used to be notified when a certain event happens to a frame.

Parameters

Parameter	Type	Description
`frame`	`table`	The Frame to hook the script on.
`script`	`string`	The script to hook.
`handler` (optional)	`function` \| `methodname`	The handler for the hook, a funcref or a method name. (Defaults to the name of the hooked script).

Example

lua

function MyAddon:OnEnable()
    -- Hook the OnShow of FriendsFrame
    self:HookScript(FriendsFrame, "OnShow", "FriendsFrameOnShow")
end

function MyAddon:FriendsFrameOnShow(frame)
    print("The FriendsFrame was shown!")
end

RawHookScript

method#

lua

AceHook:RawHookScript(frame, script, handler?)

RawHook a script handler on a frame.

The hook created will be a "raw hook", that means that your handler will completely replace the original script, and your handler has to call the original script (or not, depending on your intentions).

The original script will be stored in self.hooks[frame][script].

This type of hook can be used for all purposes, and is usually the most common case when you need to modify arguments or want to control execution of the original script.

Parameters

Parameter	Type	Description
`frame`	`table`	The Frame to hook the script on.
`script`	`string`	The script to hook.
`handler` (optional)	`function` \| `methodname`	The handler for the hook, a funcref or a method name. (Defaults to the name of the hooked script).

Example

lua

function MyAddon:OnEnable()
    -- Hook the OnShow of FriendsFrame
    self:RawHookScript(FriendsFrame, "OnShow", "FriendsFrameOnShow")
end

function MyAddon:FriendsFrameOnShow(frame)
    -- Call the original function
    self.hooks[frame].OnShow(frame)
    -- Do our processing
    -- .. stuff
end

SecureHookScript

method#

lua

AceHook:SecureHookScript(frame, script, handler?)

SecureHook a script handler on a frame.

This function is a wrapper around the frame:HookScript function in the WoW API. Using AceHook extends the functionality of secure hooks, and adds the ability to unhook once the hook isn't required anymore, or the addon is being disabled.

Parameters

Parameter	Type	Description
`frame`	`table`	The Frame to hook the script on.
`script`	`string`	The script to hook.
`handler` (optional)	`function` \| `methodname`	The handler for the hook, a funcref or a method name. (Defaults to the name of the hooked script).

Example

lua

function MyAddon:OnEnable()
    -- run after the FriendsFrame's OnShow script
    self:SecureHookScript(FriendsFrame, "OnShow", "FriendsFrameOnShow")
end

function MyAddon:FriendsFrameOnShow(frame)
    print("The FriendsFrame was shown!")
end

Unhook

method#

lua

AceHook:Unhook(obj?, method)

Unhook from the specified function, method or script.

Parameters

Parameter	Type	Default	Description
`obj` (optional)	`table`		The object or frame to unhook from.
`method`	`string`		The name of the method, function or script to unhook from.

Returns

Type	Description
`boolean`	`true` if a hook was removed, `false` if there was no active hook to remove.

UnhookAll

method#

lua

AceHook:UnhookAll()

Unhook all existing hooks for this addon.

Example

lua

function MyAddon:OnDisable()
    self:UnhookAll()
end

IsHooked

method#

lua

AceHook:IsHooked(obj?, method)

Check if the specific function, method or script is already hooked.

Parameters

Parameter	Type	Default	Description
`obj` (optional)	`table`		The object or frame to check.
`method`	`string`		The name of the method, function or script to check.

Returns

Type	Description
`isHooked`	Boolean: `true` if the function/method/script is hooked, otherwise `false`.
`handler`	Function\|methodname: the registered handler if hooked, otherwise `nil`.

AceHook-3.0 ​

Usage ​

Standard (pre-) hooks ​

Raw hooks ​

Secure (post-) hooks ​

Hooking scripts ​

Checking for an existing hook ​

API Reference ​

Embed ​

Hook ​

RawHook ​

SecureHook ​

HookScript ​

RawHookScript ​

SecureHookScript ​

Unhook ​

UnhookAll ​

IsHooked ​

AceHook-3.0

Usage

Standard (pre-) hooks

Raw hooks

Secure (post-) hooks

Hooking scripts

Checking for an existing hook

API Reference

Embed

Hook

RawHook

SecureHook

HookScript

RawHookScript

SecureHookScript

Unhook

UnhookAll

IsHooked