Editing WoW:SecureHandlers

{{Uitech}}
'''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==
{| class="darktable"
! 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 <code>[=[ ... ]=]</code> 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 [[RestrictedEnvironment|restricted environment]]. Limitations include inability to handle native Lua tables (instead resorting to [[RestrictedEnvironment#Restricted tables|restricted tables]] and [[RestrictedEnvironment#Frame handle methods|frame references]]), and lack of direct access to functions (although some [[RestrictedEnvironment#Control methods|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<nowiki>:</nowiki>Execute("codeSnippet") : executes codeSnippet in the [[RestrictedEnvironment|restricted environment]] owned by the widget.
; widget<nowiki>:</nowiki>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<nowiki>:</nowiki>UnwrapScript(frame, "script") : returns the outermost wrapped handler for the frame's script handler.
; widget<nowiki>:</nowiki>SetFrameRef("id", frame) : creates a frame reference that can be accessed inside the restricted environment.

== See also ==
* {{elink|link=http://forums.worldofwarcraft.com/thread.html?topicId=11162847431&sid=1|icon=externalarticle|site=Introduction to the SecureHandlers|desc=by alestane.}}



{{API Trail Secure}}