SecureActionButtonTemplate

The SecureActionButtonTemplate was introduced in Patch 2.0 to allow addons to perform protected actions — casting spells, executing macros, etc — by specifying button behavior via its attributes. A non-protected variant, InsecureActionButtonTemplate, was added in Patch 7.2.0, and allows protected actions to be performed only while combat lockdown is not in effect.

To create a SecureActionButton, simply create a button that inherits from the SecureActionButtonTemplate; to make the button instance useful, specify interesting attributes. This can be done in both XML, Lua and a mix of the two:

Using XML: <Button name="myButton" inherits="SecureActionButtonTemplate" parent="UIParent"> <Attributes> <Attribute name="type" value="action" /> <Attribute name="action" value="1" type="number" /> </Attributes> </Button> Using Lua: local btn = CreateFrame("Button", "myButton", UIParent, "SecureActionButtonTemplate") btn:SetAttribute("type", "action") btn:SetAttribute("action", 1) Macro Example in Lua: local macroBtn = CreateFrame("Button", "myMacroButton", UIParent, "SecureActionButtonTemplate") macroBtn:SetAttribute("type1", "macro") -- left click causes macro macroBtn:SetAttribute("macrotext1", "/raid zomg a left click!") -- text for macro on left click

Some attribute may change value based on whether a particular combination of modifier keys is held down and/or a particular button is being clicked. Those attributes are typically called modified attributes, and are resolved by the SecureButton_GetModifiedAttribute function.

The "modified attribute" name takes the form of: modifier-name-button. The modifier is one of "alt-", "ctrl-", "shift-", or a combination of them in that order, and the button is a normally number from 1 through 5 or hyphen followed by an arbitrary string. Both the prefix and the suffix can be "*" to signify no regard to the modifier/button; "*attribute*" is thus equivalent to "attribute". Some examples are shown in the table to the right; both the modifier and the button must match the click details in order for the attribute value to be used.

Please note that non-default button clicks (this includes right-clicks) need to be registered with the actual button, by means of Button:RegisterForClicks.

A limited precedence order is defined by the Frame:GetAttribute method.

SecureActionButtons are also able to change the button being clicked in response to whether your target can be assisted ([help]) or attacked ([harm]) by you; the two relevant attributes are "helpbutton" and "harmbutton". The value of those attributes, should they match, will be used as the button to resolve the "type" and other required arguments.

For example, suppose we wanted to create a button that would alter behavior based on whether you can attack your target. Setting the following attributes has the desired effect:

If the button is remapped by the "harmbutton" or "helpbutton" attributes, the value of the "unit" attribute is reevaluated with the new button suffix: it is therefore to make a button that would check the hostility of one unit, and perform a reactive action on an entirely different unit.

The action the SecureActionButtonTemplate-inheriting frame actually performs is dependent on the value of its modified type attribute, and possibly additional attributes specific to a type.

The table below lists all valid type values and the attributes they use to perform their actions. All relevant attributes can be modified as previously described; and, to the extent possible, all types respect the "unit" attribute for targeting. Generally, variable names are used to refer to the value of the modified attribute sharing their name.

Additionally, the "target-item" or "target-bag", "target-slot" attributes allow you to create a button that would target a specific item in your inventory for a spell being cast. This targeting is performed after the main type processing, and only if a spell is currently being targetted. It is therefore possible to create a button that would cast a specific spell on a specific item by setting the relevant attributes. For instance, to disenchant an item in bag 1, slot 1: btn:SetAttribute("type", "spell"); btn:SetAttribute("spell", "Disenchant"); btn:SetAttribute("target-item", "1 1"); -- ("bag slot")

A few more attributes can affect how the button functions: