SecureAuraHeaderTemplate

Main Menu
WoW API Lua API FrameXML Widget API Widget scripts XML schema Events CVars Macro commands Combat Log Escape sequences Hyperlinks API changes HOWTOs wowuidev

→ UI Tech. Details

SecureAuraHeaderTemplate is one of the SecureTemplates. It's purpose is to automate the creation of SecureActionButtonTemplate frames associated with a unit's auras. These secure frames permit players to use protected functions in combat such as right-clicking to cancel a helpful buff.

Attributes

Essential

template

String - Name of a custom XML template which should inherit SecureActionButtonTemplate and include useful code for interactivity

unit

String (UnitId), normally "player" (because the principle benefit of secure frames is allowing players to cancel their own buffs)

Layout

point

String - Where the first child SecureActionButtonTemplate should appear

xOffset, yOffset

Numbers - Where subsequent children should appear

wrapAfter, wrapXOffset, wrapYOffset, maxWraps

Numbers - Organizing children into rows/cols

minWidth, minHeight

Numbers - Minimum size of the container frame

Ordering and Filtering

filter

String - Comma separated list of possible filter values found in UnitAura, except "RAID" will be ignored

sortMethod

String - Sort the resulting auras by "INDEX", "NAME" or "TIME"

sortDirection

String - "+" or "-" to reverse-sort

separateOwn

Number - Whether to place auras you cast yourself before (1) or after (-1) others; if nil or 0, no separation is done

groupBy

String - If present, a series of comma-separated filters appended to the base filter to separate auras into groups within a single stream

includeWeapons

Number - The aura sub-stream before which to include temporary weapon enchants; if nil or 0, weapon enchants are ignored

weaponTemplate

String - Name of a custom XML template corresponding to the use of includeWeapons (may be nil if you preset tempEnchant1 and tempEnchant2, or if not includeWeapons)

Consolidation Frame

consolidateTo

Number - The aura sub-stream before which to place a proxy for the consolidated header; if nil or 0, consolidation is ignored.

consolidateDuration

Number - the minimum total duration an aura should have to be considered for consolidation (Default: 30)

consolidateThreshold

Number - buffs with less remaining duration than this many seconds should not be consolidated (Default: 10)

consolidateFraction

Number - The fraction of remaining duration a buff should still have to be eligible for consolidation (Default: .10)

Child Frames

• SecureActionButtonTemplate children should use UnitAura, setting the second parameter to their ID using Frame:GetID.
• Normally one would arrange right-clicking to remove cancellable buffs via SetAttribute("type2", "cancelaura") and RegisterForClicks("RightButtonUp") in the OnLoad header.
• One can access each child via SecureAuraHeader:GetAttribute("child" .. i) or GetAttribute("tempEnchant1") or GetAttribute("tempEnchant2")

Example

-- create a template in XML
<Ui ...>
<Button name="myAuraButtonTemplate" inherits="SecureActionButtonTemplate" virtual="true">
<Size x="10 y="10" />
<Attributes>
  <Attribute name="type2" value="cancelaura" />  
</Attributes>
<Scripts>
  <OnLoad>
    self:RegisterForClicks("RightButtonUp")
  </OnLoad>
</Button>
</Ui>


-- create the SecureAuraHeader in lua
assert(not InCombatLockdown());
local mySecureHeader = CreateFrame("Frame", "mySecureHeader", UIParent, "SecureAuraHeaderTemplate");
mysecureHeader:SetAttribute("template", "myAuraButtonTemplate"); -- it will use
mySecureHeader:SetAttribute("unit", "player"); -- to show auras on the player
mySecureHeader:SetAttribute("minWidth", 1);
mySecureHeader:SetAttribute("minHeight", 1);
mySecureHeader:Show();

-- customize via these attributes
mySecureHeader:SetAttribute("filter", "HELPFUL"); -- see UnitAura() for a list of possible filters
mySecureHeader:SetAttribute("sortMethod", "TIME"); -- also could be "INDEX" or "NAME"
mySecureHeader:SetAttribute("sortDirection", "+"); -- also could be "-" for reverse sorting
mySecureHeader:SetAttribute("point", "CENTER"); -- start creating buff icons in the middle of the screen
mySecureHeader:SetAttribute("xOffset", 15); -- position each buff relative to the previous one
mySecureHeader:SetAttribute("yOffset", 0);
mySecureHeader:SetAttribute("wrapAfter", 5); -- create a new row if there are 6 or more buffs
mySecureHeader:SetAttribute("wrapXOffset", 0);
mySecureHeader:SetAttribute("wrapYOffset", -15);

-- create a function to update the appearance of each button (see UnitAura earlier)
-- use HookScript here so we don't override the built-in OnEvent script, which causes the frame to behave incorrectly.
mySecureHeader:HookScript("OnEvent", function()
  for i=1, 40 do
    local child = header:GetAttribute("child" .. i);  -- gets the i'th automatically created button
    if (not child or not child:IsShown()) then
      return;  -- the player has fewer than 40 buffs
    end
    child.texture = child.texture or child:CreateTexture(nil, "ARTWORK")  -- create a texture if one doesn't exist already
    child.texture:SetAllPoints();
    
    -- the 2nd parameter should accomodate the secure header's sortMethod and sortDirection attributes, by using GetID()
    -- the 3rd parameter should match the secure header's filter attribute, by using the same string
    local name, icon = UnitAura("player", child:GetID(), "HELPFUL"); 
    if (name) then
      child.texture:SetTexture(icon);
      child.texture:Show();
    else
      child.texture:Hide();
    end
  end
end); -- end of the OnEvent handler

-- register the handler to a useful event so it triggers
mySecureHeader:RegisterUnitEvent("UNIT_AURA", "player"); -- triggers when buffs/debuffs on the player change

See Also

SecureAuraHeaderTemplate was contributed by non-employee Nevin Flanagan