 |
The API is no longer being updated here until further notice. |
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) |
Snippets
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
self:Hide();
end
]=]);
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).
Methods
If widget inherits from a SecureHandler template, you can use the following methods:
- widget:Execute("codeSnippet")
- 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
Iriel's Field Guide to Secure Handlers 4.0 revision 1
| |||||||||||||||||