WoW:SecureActionButtonTemplate: Difference between revisions
Jump to navigation
Jump to search
→Other attributes: width
(→Other attributes: width) |
|||
Line 1: | Line 1: | ||
{{ | {{uitech}} | ||
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. | |||
== Creating a SecureActionButton == | |||
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> | </Button> | ||
'''Using Lua''': | |||
local btn = CreateFrame("Button", "myButton", UIParent, "SecureActionButtonTemplate"); | |||
btn:SetAttribute("type", "action"); | |||
btn:SetAttribute("action", 1); | |||
== Modified attributes == | |||
{| class="darktable" style="float:right" | |||
! Attribute !! Used on... | |||
|- | |||
| style="padding-right: 1em"| "type" || Any clicks. | |||
|- | |||
| style="padding-right: 1em"| "*type1" || Any left click. | |||
|- | |||
= | | style="padding-right: 1em"| "type1" || Unmodified left click. | ||
|- | |||
| style="padding-right: 1em"| "shift-type2" || Shift+right click. (But not Alt+Shift+right click) | |||
|- | |||
| style="padding-right: 1em"| "shift-type*" || Shift+any button click. | |||
|- | |||
| style="padding-right: 1em"| "alt-ctrl-shift-type*" || Alt+Control+Shift+any button click. | |||
--- | |- | ||
| style="padding-right: 1em"| <span style="color:red">"ctrl-alt-shift-type*"</span> || Invalid, as modifiers are in the wrong order. | |||
|----- | |||
| | |||
| | |||
|} | |} | ||
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. | |||
A limited precedence order is defined by the Frame:[[API Frame GetAttribute|GetAttribute]] method. | |||
==Button remapping== | |||
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: | ||
|----- | {| class="darktable" | ||
| | !Attribute !! Value !! Purpose | ||
| | |- | ||
|----- | | "unit" || "target" || Make all actions target the player's target. | ||
| | |- | ||
| | | "*harmbutton1" || "nuke1" || Remap any left clicks to "nuke1" clicks when target is hostile. | ||
|- | |||
| "*harmbutton2" || "nuke2" || Remap any right clicks to "nuke2" clicks when target is hostile. | |||
|- | |||
| "helpbutton1" || "heal1" || Remap unmodified left clicks to "heal1" clicks when target is friendly. | |||
|- | |||
| "type" || "spell" || Make all clicks cast a spell. | |||
|- | |||
| "spell-nuke1" || "Mind Flay" || Cast Mind Flay on "hostile" left click. | |||
|- | |||
| "spell-nuke2" || "Shadow Word: Death" || Cast Shadow Word: Death on "hostile" right click. | |||
|- | |||
| "alt-spell-nuke2" || "Mind Blast" || Cast Mind Blast on "hostile" alt-right click. | |||
|- | |||
| "spell-heal1" || "Flash Heal" || Cast Flash Heal on "friendly" left click. | |||
|} | |} | ||
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. | |||
== | == Action Types == | ||
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. | |||
{| class="darktable" | |||
|+ SecureActionButtonTemplate "type" attributes | |||
! style="width: 8em" | Type | |||
! style="width: 8em" | Used attributes | |||
! Behavior | |||
===spell== | |- | ||
| valign="top" | "actionbar" | |||
<br /> | | valign="top" | "action" | ||
''' | | Switches the current action bar depending on the value of the "action" attribute: | ||
* A number: switches to a the bar specified by the number. | |||
{| | * "increment" or "decrement": move one bar up/down. | ||
|-- | * "a, b", where a, and b are numeric, switches between bars a and b. | ||
| | |- | ||
| ( | | valign="top" | "action" | ||
|----- | | valign="top" | "unit", "action"<br />["actionpage"] | ||
| | | Performs an action specified by the "action" attribute (a number).<br /> | ||
| ( | If the button:GetID() > 0, paging behavior is supported; see the ActionButton_CalculateAction FrameXML function. | ||
|- | |||
| valign="top" | "pet" | |||
| valign="top" | "unit", "action" | |||
| Calls {{api|CastPetAction}}(action, unit); | |||
|- | |||
| valign="top" | "pet" | |||
| valign="top" | "unit", "action" | |||
| Calls {{api|CastPetAction}}(action, unit); | |||
|- | |||
| valign="top" | "spell" | |||
| valign="top" | "unit", "spell" | |||
| Calls {{api|CastSpellByName}}(spell, unit); | |||
|- | |||
| valign="top" | "item" | |||
| valign="top" | "unit"<br />"item" OR<br />["bag", "slot"] | |||
| Equips or uses the specified item, as resolved by {{api|SecureCmdItemParse}}. | |||
* "item" attribute value may be a macro conditioned string, item name, or "bag slot" string (i.e. "1 3"). | |||
* If "item" is nil, the "bag" and "slot" attributes are used; those are deprecated -- use a "bag slot" item string. | |||
|- | |||
| valign="top" | "macro" | |||
| valign="top" | "macro" OR<br/>"macrotext" | |||
| valign="top" | If "macro" attribute is specified, calls {{api|RunMacro}}(macro, button); otherwise, {{api|RunMacroText}}(macrotext, button); | |||
|- | |||
| valign="top" | "cancelaura" | |||
| valign="top" | "unit"<br />"index" OR<br />"spell"[, "rank"] | |||
| Calls either {{api|CancelUnitBuff}}(unit, index) or CancelUnitBuff(unit, spell, rank). The first version | |||
'''Note''': the value of the "index" attribute must resolve to nil/false for the "spell", "rank" attributes to be considered. | |||
|- | |||
| valign="top" | "stop" || || Calls {{api|SpellStopTargeting}}(). | |||
|- | |||
| valign="top" | "target" | |||
| valign="top" | "unit" | |||
| Changes target, targets a unit for a spell, or trades unit an item on the cursor.<br /> | |||
If "unit" attribute value is "none", your target is cleared. | |||
|- | |||
| valign="top" | "focus" | |||
| valign="top" | "unit" | |||
| Calls {{api|FocusUnit}}(unit). | |||
|- | |||
| valign="top" | "assist" | |||
| valign="top" | "unit" | |||
| Calls {{api|AssistUnit}}(unit). | |||
|- | |||
| valign="top" | "mainassist" | |||
| valign="top" | "action", "unit" | |||
| Performs a main assist status on the unit based on the value of the "action" attribute: | |||
* nil or "set": the unit is assigned main assist status. ({{api|SetPartyAssignment}}) | |||
* "clear": the unit is stripped main assist status. ({{api|ClearPartyAssignment}}) | |||
* "toggle": the main assist status of the unit is inverted. | |||
|- | |||
| valign="top" | "maintank" | |||
| valign="top" | "action", "unit" | |||
| As "mainassist", but for main tank status. | |||
|- | |||
| valign="top" | "click" | |||
| valign="top" | "clickbutton" | |||
| Calls clickbutton:Click(button) | |||
|- | |||
| valign="top" | "attribute" | |||
| valign="top" | ["attribute-frame",]<br /> "attribute-name"<br /> "attribute-value" | |||
| valign="top" | Calls frame:SetAttribute(attributeName, attributeValue). If "attribute-frame" is not specified, the button itself is assumed. | |||
|- | |||
| valign="top" | Any other value | |||
| valign="top"| "_''type''" | |||
| Action depends on the value of the modified ("_" .. type) attribute, or rawget(button, type), in that order. | |||
* If the value is a function, it is called with (self, unit, button, actionType) arguments | |||
* If the value is a string, a restricted snippet stored in the attribute specified by the value on the button is executed as if it was OnClick. | |||
|} | |} | ||
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") | |||
== | == Other attributes == | ||
A few more attributes can affect how the button functions: | |||
{| class="darktable" | |||
! style="width: 8em" | Attribute | |||
! style="width: 8em" | Values | |||
{| | ! Function | ||
| | |- | ||
| | | valign="top" | "downbutton" | ||
| valign="top" | Any string | |||
| | | Remaps the mouse button if this is a "down" click. This transformation is applied before all others. | ||
| | |- | ||
| | | valign="top" | "unitsuffix" | ||
| | | valign="top" | "pet", "target", etc. | ||
| | | Appends the attribute's value to the "unit" attribute value when resolving units. | ||
| | |- | ||
| | | valign="top" | "toggleForVehicle" | ||
| | | valign="top" | true, false | ||
| When the unit's owner is in a vehicle, remap the pet to its owner, and its owner to its pet (the vehicle). Based on the original unit: | |||
| | * If it was a pet unit ("raidpetX", "pet", etc), and owner is in a vehicle, remap to owner. | ||
* If it did not contain "target", or "allowVehicleTarget" attribute is set to true, remap the original unit to its pet. | |||
|- | |||
| valign="top" | "allowVehicleTarget" | |||
| valign="top" | true, false | |||
| If true, allows "toggleForVehicle" to remap units like "party1target" to "partypet1target". | |||
= | |||
|- | |- | ||
| | | valign="top" | "checkselfcast" | ||
| valign="top" | true, false | |||
| If true, and the SELFCAST modifier is held down, resolves the unit to "player". | |||
|- | |- | ||
| | | valign="top" | "checkfocuscast" | ||
| valign="top" | true, false | |||
| If true, and the FOCUSCAST modifier is held down, resolves the unit to "focus". | |||
| | |||
| | |||
|} | |} | ||
{{API Trail Secure}} |