From Wowpedia
Jump to: navigation, search

SecureHandlers is a new set of widget templates provided in Patch 3.0 to enhance addon functionality while in combat lockdown, replacing most variations of SecureStateHeader behavior in 2.0. The templates enable execution of a limited subset of addon code in a restricted but secure environment, allowing addons to perform actions that would normally be impossible.

SecureHandlers are implemented entirely in Lua/XML code, and code is publicly visible as part of FrameXML. The templates are defined in SecureHandlerTemplates.xml, supporting code is in SecureHandlers.lua, and the restricted environment/execution framework is provided by RestrictedExecution.lua, RestrictedFrames.lua, and RestrictedEnvironment.lua files.

SecureHandler templates

Template Function Executed snippets
SecureHandlerBaseTemplate Enables use of SecureHandler methods on the frame. none
SecureHandlerStateTemplate Fires snippet when a state-xxx attribute changes. _onstate-xxx(self, stateid, newstate)
SecureHandlerAttributeTemplate Responds to attribute changes _onattributechanged(self, name, value)
SecureHandlerClickTemplate Responds to clicks _onclick(self, button, down)
SecureHandlerDoubleClickTemplate Responds to double clicks _ondoubleclick(self, button, down)
SecureHandlerDragTemplate Enables dragging _ondragstart(self, button), _onreceivedrag(self, button, kind, value, ...)
SecureHandlerMouseUpDownTemplate Mouse up/down events _onmouseup(self, button), _onmousedown(self, button)
SecureHandlerMouseWheelTemplate Mouse wheel _onmousewheel(self, delta)
SecureHandlerEnterLeaveTemplate Mouse entering/leaving frame _onenter(self), _onleave(self)


To add a snippet for a SecureHandler template to call, you should set it as an attribute on the widget inheriting from a SecureHandler template. For example:

-- Assume widget is a frame inheriting from SecureHandlerClickTemplate.
widget:SetAttribute("_onclick", [=[ -- self, button, down are considered "arguments" to the _onclick handler
 if button == "RightButton" then

The [=[ ... ]=] syntax allows you to specify long strings without escaping characters within them.

Snippets can access a limited subset of the World of Warcraft API; they are said to execute in a restricted environment. Limitations include inability to handle native Lua tables (instead resorting to restricted tables and frame references), and lack of direct access to functions (although some control methods can be used to emulate a call stack).


If widget inherits from a SecureHandler template, you can use the following methods:

executes codeSnippet in the restricted environment owned by the widget.
widget:WrapScript(frame, "script", "preBody", "postBody") 
wraps the specified script handler of an explicitly protected frame with the specified pre and post snippets. The snippets are executed within the widget's restricted environment.
widget:UnwrapScript(frame, "script") 
returns the outermost wrapped handler for the frame's script handler.
widget:SetFrameRef("id", frame) 
creates a frame reference that can be accessed inside the restricted environment.

See also