WoW:SecureTemplates: Difference between revisions

From AddOn Studio
Jump to navigation Jump to search
m (Move page script moved page SecureTemplates to SecureTemplates without leaving a redirect)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Category:UI Technical Details]]
{{uitech}}
[[API SecureTemplates|Secure Templates]] are an option for UI Developers to use secure functions indirectly by creating secure objects (through inheriting Secure Templates) and altering their attributes.
'''SecureTemplates''' are a family of protected frame and button templates defined as part of FrameXML. Through attribute-based configuration, they allow addons to access some of the protected functionality. The templates are defined in FrameXML/SecureTemplates.xml, and functionality supporting them resides in FrameXML/SecureTemplates.lua


However it is still not posiible to invoke protected functions directly from objects inheriting Secure Templates.
{| class="darktable"
|+ SecureTemplates
|-
! Template
! Widget Type
! Function
|-
| [[SecureActionButtonTemplate]] || Button || Perform protected actions.
|-
| style="padding-left: 2em" | [[SecureUnitButtonTemplate]] || Button || Unit frames.
|- class="row1"
| [[SecureGroupHeaderTemplate]] || Frame || Managing group members.
|-
| style="padding-left: 2em" | [[SecurePartyHeaderTemplate]] || Frame || Managing party members.
|-
| style="padding-left: 2em" | [[SecureRaidGroupHeaderTemplate]] || Frame || Managing raid group members.
|-
| [[SecureGroupPetHeaderTemplate]] || Frame || Managing group pets.
|-
| style="padding-left: 2em" | [[SecurePartyPetHeaderTemplate]] || Frame || Managing party pets.
|-
| style="padding-left: 2em" | [[SecureRaidPetHeaderTemplate]] || Frame || Managing raid group pets.
|}


''This article contains information taken from extracted .lua files on 25, Jan 2007''
== An example ==
Suppose we wanted to create a button that, when clicked, would cast Thorns on the player. This can be solved by inheriting from SecureActionButtonTemplate and setting the relevant attributes. For example, using only XML:
<Ui>
  <Button name="MyThornsButton" inherits="SecureActionButtonTemplate" parent="UIParent">
  <Attributes>
    <Attribute name="type" type="string" value="spell"/>
    <Attribute name="spell" type="string" value="Thorns"/>
    <Attribute name="unit" type="string" value="player"/>
  </Attributes>
  <Size x="64" y="64"/>
  <Layers><Layer level="OVERLAY">
    <Texture name="$parentIcon" file="Interface\Icons\Spell_Nature_Thorns" setAllPoints="true" />
  </Layer></Layers>
  <Anchors><Anchor point="CENTER" /></Anchors>
  </Button>
</Ui>


==[[UI SecureFrameTemplate|SecureFrameTemplate]]==
This is the basic secure template. All other secure templates inherit it.


==[[UI SecureActionButtonTemplate|SecureActionButtonTemplate]]==
{{API Trail Secure}}
A basic action button capable of using actions through [[ActionSlot]] or by given spell/ability names


====Attributes====
[[Category:UI technical details]]
;unit:any valid [[UnitId]]
;type:known values for this are: action, actionbar, assist, attribute, click, focus, item, macro, menu, pet, spell, stop, target
 
;action:any valid action - defined by the "type" argument
;harmbutton:Special attribute that calls the attribute given by "type-''string''" and "''typestring''-''string''" instead of action. Well that seems a bit complicated so I should clarify this with an example
harmbutton1="myname1"
type-myname1="spell"
spell-myname1="Shadow Bolt"
harmbutton2="myname2"
type-myname2="action"
action-myname2="4"
<small>(this example was not tested yet, it should work but may not, it is purely to make clear why 3 attributes are needed)</small>
:So the flow is like this: an attribute "harmbutton1" is found (because we clicked with the left mouse button), and it's value is used as the new action attribute. For this, the type attribute ''type-myname1'' must be set to the type of action executed - spell in this case. Then WoW looks for the attribute spell-myname1 and executes it.
;helpbutton:Same as harmbutton but for abilities that can only be used on friendly units
 
 
Any of the attributes may have a number attached that corresponds to the mouse button - i.e. action2 specifies an action executed when rightclicking the button. Or the special character "*" (asterisk) meaning any button.
 
Any of the attributes may have a modifier ''prepended'' that corresponds to modifier keys - i.e. alt-action means this action is only executed when the alt-key is pressed while clicking it. Or the special character "*" (asterisk) meaning any modifier key (this should be the default of the standard action buttons).
 
====Example====
A really basic example would be:
<pre><Button name="ReallyBasicButtonTemplate" inherits="SecureActionButtonTemplate">
<Size>
<AbsDimension x="36" y="36"/>
</Size>
<Anchors>
<Anchor point="CENTER"/>
</Anchors>
<NormalTexture>
<Color r="1" g="0" b="0" a="0.5"/>
</NormalTexture>
<PushedTexture>
<Color r="0" g="1" b="0" a="0.5"/>
</PushedTexture>
<Scripts>
<OnLoad>
this:SetAttribute("type*"  , "action");
this:SetAttribute("action1", 1);
</OnLoad>
</Scripts>
</Button></pre>
 
==[[UI SecureUnitButtonTemplate|SecureUnitButtonTemplate]]==
Unit button, for targeting units - like the group frames. Though it's basically a reduced version of SecureActionButton, since it calls the same functions anyway but overwriting type1 to target and type2 to menu which means it will open the unit menu on rightclick and target the given unit on leftclick.
 
====Attributes====
;target:Any valid [[UnitId]].
 
 
==[[UI SecureStateHeaderTemplate|SecureStateHeaderTemplate]]==
<small>''This is one more advanced template and I'm still not quite into it... Sorry. But I will write down what I know.''</small>
 
The template has four basic function it can control for it's child frames/objects
# Child Visibility
# (Mouse) Button Mapping
# State Transitions
# Key Rebinding
 
 
The template by itself will not do anything, it is meant to control child frames. But first a frame has to be registered with the state header. That means child frames don't have to be actual child frames in terms of setparent functions or parent attribute. (actually it won't probably work with only a parent attribute)
 
To register a frame with the template, use the following example:
''SecureStateHeaderName'':SetAttribute("addchild", ''ChildName'');
 
 
===State names===
State names - according to the documentation - can be any string value, though I would not recommend using the characters '-', ',', ';' and ':' in them, though positive integer values are recommended. One reason is that they can be combined like "1,2,3,4,5,6,7,8,9" may also be written as "1-9". Naturally "pear,apple,cherry" can't be combined to "pear-cherry".
 
 
===Attribute Syntax===
The state header makes use of a specific attribute value syntax (other than the SecureActionButton's attribute '''name''' syntax, so they should not interfere).
Any attribute can contain state specific information, telling WoW which value applies to which state. The basic syntax should be
attribute="value11:value12;value21:value22;..."
  or
attribute="value1,value2,value3,..."
meaning value11 is mapped to value12 and value21 maps to value22. Or just listing values/states. The specific syntax of the value depends on it's attribute.
: There is a special syntax to combine integer values in a row. Use "1-5" instead of "1,2,3,4,5" or "1,3-9" instead of "1,3,4,5,6,7,8,9" etc.
 
 
===State Transitions===
After a child frame is clicked it's "newstate" attribute is parsed to retrieve the new state of the state header. The syntax is quite wicked though.
newstate="*:''x''"
  Means that no matter what state we're in, we go to state ''x''
newstate="''x''-''y''"
newstate="1-4" (example)
  Means that if we are in state 1, the next state is 2.
  If we are in state 4, the next state is 1
newstate="''x'':''y''"
newstate="1-4:9" (example)
  Means that if we are in states 1 to 4, we will transit to state 9
newstate="''x''-''y'':''u'':''v''"
newstate="1-2:5-6" (example)
  Means that if we are in state 1 the new state is 5 and
  If we are in state 2 the new state is 6.
newstate="1-2:5-6;7-8:1" (example)
  A combination.
 
====Attributes====
;newstate:Contains state transition rules
;delaystate:Contains state transition rules to be executed after ''delaytime''. The Syntax is the same as for ''newstate''
;delaytime:The time between parsing ''newstate'' and ''delaystate'' in seconds it is parsed similar to the attribute ''statebutton''
 
===Child Visibility===
Controls visibility of child elements depending on two attributes. Note: This attribute is an attribute of the child elements not the header!
 
====Attributes====
;showstates:Contains those states where the element should be visible
;hidestates:Contains those states where the element should ''not'' be visible
 
The attribute value syntax is rather easy: A comma separated list, listing the desired states where the elements can be ranges (x-y) too.
attribute="''x'',''y'',''z'',..."
attribute="3,4,7-9"
 
==[[UI SecureStateDriverTemplate|SecureStateDriverTemplate]]==
 
==[[UI SecureAnchorButtonTemplate|SecureAnchorButtonTemplate]]==
 
==[[UI SecureAnchorEnterTemplate|SecureAnchorEnterTemplate]]==
 
==[[UI SecureAnchorUpDownTemplate|SecureAnchorUpDownTemplate]]==
 
==[[UI SecurePieButtonTemplate|SecurePieButtonTemplate]]==
 
==[[UI SecurePartyHeaderTemplate|SecurePartyHeaderTemplate]]==
 
==[[UI SecureRaidGroupHeaderTemplate|SecureRaidGroupHeaderTemplate]]==
 
 
==Also See==
* [[Secure Frames Overview]] Note: This article contains outdated information!
 
<!-- Note: This article contains absolutely no quotes/text passages from the *.lua files' documentation written by Iriel/Blizzard. Since I don't own an US account I could not ask them for permission. If you are adding quotes etc. from Iriel or Blizzard employees ensure to get their permission first. Otherwise this article should be GNU FDL as all other contributions. ~~~~ -->

Latest revision as of 04:48, 15 August 2023

SecureTemplates are a family of protected frame and button templates defined as part of FrameXML. Through attribute-based configuration, they allow addons to access some of the protected functionality. The templates are defined in FrameXML/SecureTemplates.xml, and functionality supporting them resides in FrameXML/SecureTemplates.lua

SecureTemplates
Template Widget Type Function
SecureActionButtonTemplate Button Perform protected actions.
SecureUnitButtonTemplate Button Unit frames.
SecureGroupHeaderTemplate Frame Managing group members.
SecurePartyHeaderTemplate Frame Managing party members.
SecureRaidGroupHeaderTemplate Frame Managing raid group members.
SecureGroupPetHeaderTemplate Frame Managing group pets.
SecurePartyPetHeaderTemplate Frame Managing party pets.
SecureRaidPetHeaderTemplate Frame Managing raid group pets.

An example[edit]

Suppose we wanted to create a button that, when clicked, would cast Thorns on the player. This can be solved by inheriting from SecureActionButtonTemplate and setting the relevant attributes. For example, using only XML: 

<Ui>
 <Button name="MyThornsButton" inherits="SecureActionButtonTemplate" parent="UIParent">
  <Attributes>
   <Attribute name="type" type="string" value="spell"/>
   <Attribute name="spell" type="string" value="Thorns"/>
   <Attribute name="unit" type="string" value="player"/>
  </Attributes>
  <Size x="64" y="64"/>
  <Layers><Layer level="OVERLAY">
    <Texture name="$parentIcon" file="Interface\Icons\Spell_Nature_Thorns" setAllPoints="true" />
  </Layer></Layers>
  <Anchors><Anchor point="CENTER" /></Anchors>
 </Button>
</Ui>


v • d • e
Secure Execution
Overview
SecureTemplates
SecureHandlerTemplates
Restricted Environment
Overview · ...
API
Retrieved from "https://addonstudio.org/mw/index.php?title=WoW:SecureTemplates&oldid=20625"