Aura (API Type)

__NOTOC__
Auras are buffs and debuffs that may exist on any unit.
== Returns ==
==Examples==
===UnitAura===
UnitAura provides several return values describing up to 40 auras on a unit matching an optional filter (such as "HELPFUL" or "HARMFUL").
 for i=1, 40 do
 local name, __, count = UnitAura("player", i, "HARMFUL"); -- debuffs only
 if (not name) then
 break; --end the loop
 end
 if (count > 1) then
 print("Yikes! You have " .. count .. " stacks of " .. name);
 else
 print("Look out! You have " .. name);
 end
 end
UnitAura may be used in conjunction with event handlers to display an insecure icon of an aura
 -- create a frame to hold the texture and handle events
 local myFrame = CreateFrame("Frame", nil, UIParent)
 myFrame:SetSize(64, 64)
 myFrame:SetPoint("CENTER")
 
 -- create the texture
 local myTexture = frame:CreateTexture(nil, "ARTWORK")
 myTexture:SetAllPoints();
 
 -- create the handler that updates the texture
 myFrame:SetScript("OnEvent", function()
 if (UnitExists("target")) the
 local name, icon = UnitAura("target", 1)
 if (name) then
 -- the target has at least one buff or debuff
 myTexture:SetTexture(icon);
 myTexture:Show();
 else
 -- the target has no buffs or debuffs
 myTexture:Hide();
 end
 else
 -- there is no currently selected target
 myTexture:Hide();
 end
 end); --end of the OnUpdate handler
 
 -- register the handler so it triggers on useful events
 myFrame:RegisterUnitEvent("UNIT_AURA", "target"); -- the player's current target recently gained or lost an aura
 myFrame:RegisterUnitEvent("UNIT_TARGET, "player"); -- the player recently has a new target, or no longer has a target
===SecureAuraHeaderTemplate===
SecureAuraHeaderTemplate automatically creates, filters and sorts secure frames that allow players to perform protected functions like removing buffs during combat (normally via right clicking). By comparison, the insecure method shown earlier is more appropriate for party or target frames because you only see their buffs but cannot interact with them.
This secure approach requires the creation of a custom xml template describing the appearance of each buff button, and then a secure header frame that will use the custom temlplate to produce buttons as new buffs appear.
 -- 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)
 mySecureHeader:SetScript("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", i, "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
==Patch changes==
* The return values to , or have changed many times (see those articles for details)
* 
*