AceUnitFrames (AUF)

AUF is a framework for creating your own unit frames. Some lua/xml experiance is still required but 80-90% of the work to create using frame is done for you buy the framework.

Basics of creating your own unit frames.

1. Setup the xml. There are virtual templates in the AceUnitFrames.xml file for your use or create your own. See the advanced section if you plan on creating your own elements from scratch. Use AcePlayerGrid and AcePerl as examples
2. Add your emelemnts to the AUF framework to be maintained. This is done in your addons lua file or directly in the xml file in <Scripts><OnLoad> events. AUF automacily initializes elements as they are added or after everything is loaded in the case of xml OnLoad event adds.

That is all that is required. Now you will probably want to add some options like making your frames movable or turning various parts on/off etc. But that is all optional and all dependant on what you want your unit frames to do/support. AUF takes care of everything else letting you concentrat on the look/feel and features you want your unit frames to have.

Advantages of AUF over most other unit frame addons

AUF uses blizard events for all updates the only On_Update event uses by the framework is to update any target's target frames you add to the framework. There are no events for those units so an On_Update is the only way to maintain them. A Timex timer on a 1 sec counter is also used to maintain the player buff counters when the player has buffs and an element is set to display them.

AUF only registeres the events it needs to maintain the elements that have been added to it. For example if you don't add an xp bar to your unit frames then the events to maintain xp arn't registered.

AUF components

There are 16 compenents types that can be added to AUF to be maintained. Each of these components can be
added for any unit blizzard supports, ie player, target, targettarget, party1, partypet1 etc.

[b}Status bars{/b]
Status bars are your standare bars for displaying health, mana etc. AUF usest the standarized colors from blizard for all bars. An option of user defined color is planed for a later release.

AUF expects to all status bars to have the 3 text elemetns names <statusbar>Text1, <statusbar>Text2 and <statusbar>Text3. If found AUF will also maintain these text elements using properties <statusbar>.T1, <statusbar>.T2 and <statusbar>.T3 as templates for the text. T1-T3 can have the follow varibles in the text string that will be replaced in the status bar text string with the actual values.

New to 1.2 <statusbar>.T1RaidColor, <statusbar>.T2RaidColor, and <statusbar>.T3RaidColor if set to TRUE will color the text by the rail class colors regardless of the text being displayed

New to 1.2 <statusbar>.T1length, <statusbar>.T12ength, and <statusbar>.T3length if set will set the max length the text will display much like the name bar max length options.

%c - current value
%max - max value
%d - deficit value (max-current)
%p - percent of value
%r - rest xp in the format of (+123), only value on xp bars
%status = Resting, Agro, Combat, Dead, Ghost, Disconnected or nothing
%level = units level
%class = units class
%race = units race
%name = units name
%cp = combo points on unit (will only work for target)
%pvp = PVP, FFA or nothing
%tapped = Tapped or nothing
%rank = PVP rank or nothing
%type = Creature type
%sex = gender of unit Male, Female or Neuter
%classification = "worldboss", "rareelite", "elite", "rare" or nothing
%faction = Horde, Alliance
%elite = + or nothing
%smarthealth = currenthealth/maxhealth if MobHealth2 info is availible or percent% if not
%happiness = pet happiness as :), :| or :(

AUF also expects all status bars to have a second status bar of <statusbar>BG to be used as the background for the status bar. Its color will be maintained to match the status bar is a background for.

AUF also supports the use of bar textures. There are 5 built in textures 4 custome texture and the default blizzard status bar texture. You can also use your own bar textures. If a bar has the property <statusbar>.texture set to a value of 0-4 one of the built in texures will be used, 0 being the default blizard texture. If you set <statusbar>.texture to the path of your own texture file it will be used.

HealthBar - Status bar to show the unit health. A health bar can have an additonal property of <statusbar>.SmoothBar If this is set to TRUE (not nil) the bar will change colors from green to red as the units health drops.

ManaBar - Status bar to show the units mana, rage, energy etc. This bar will automaticly change color depending on the power type. Standadized colors from Blizzard are current used.

XPBar - Status bar for player or pet xp. An additional status bar of <statusbar>Rest to show rest xp bonus.

NameBar - Frame to display the units name. If a property of <namebar>.length is found it will be used to shorten long name to the length - 1 + "...". Faction color coding is automaticly applied to names. The name will also be diplays in gray if the unit is offline. New to 1.2 <namebar>.RaidColor if set to TRUE will color the text by the raidl class colors.

PVPRank - PVP rank icon. If the unit has a PvP rank this will display the rank icon. AUF expects to find a texture <PVPRank>Icon to update.

Portrait - shows the player portraint. AUF expects to find a texture of <Portrait>Icon to set the unit portrain texture and an optional fontstring <Portrait>HitIndicator to display combat spam.

LevelBar - shows the units level. AUF expects to find a fontstring of <LevelBar>Text to set the leve text to. AUF will also color code target level, display unknown levels as ?? and elite mobs as "xx+"

Class - Class icon. AUF expect to find a texture of <Class>Icon to diplay the units class icon in.

BuffBar - Buff bar to display the unit buffs. AUF expects to find elements <BuffBar>Buff<#> where # starts at 1 and counts up to the maximun # of buffs you wish to display on the bar. AUF also expects to find the follow properties
<BuffBar>.maxbuffs - the total number of buff buttons
<BuffBar>.showBuffs - TRUE to display helpful buffs
<BuffBar>.showDebuffs - TRUE to display harful buffs
<BuffBar>.showEnchants - TRUE to display weapon enchants buffs. Only used on player buff bars.

AUF expectst the buff buttons themselvs to have the following elements.
<BuffBar>Buff<#>Icon - texture to display the buff icon
<BuffBar>Buff<#>Count - fontstring to display the dubuf stacking
<BuffBar>Buff<#>DurationText - fontstring to display the buff duration
<BuffBar>Buff<#>DebuffBorder - texture to display debuff border (red outline)
<BuffBar>Buff<#>EnchantBorder - texture to display enchant border (purple outline)

Buff buttons are automaticly registerd for right click canceling of player buffs and tooltip display if you use the AUF_BuffTemplate in AceUnitFrames.xml

CastingBar - currently not supported. planed for future release

ActivityIcon - Activity icon to display rest and combat icons. AUF expects this to the texture element itself. This is only useful for the player. If the player has agro or enters combat mode the combat icon is displayed. at an inn the rest icon is displayed.

PVPStatus - Icon to display PVP status. AUF expect this to be the texture element itself.

PartyLeader - Icon to display party leader (crown). AUF expect this to be the texture element itself.

PartyMasterLooter - Icon to display master looter in a party (money bag). AUF expect this to be the texture element itself.

DeadIcon - Death icon (skull and cross bones). AUF expect this to be the texture element itself.

CPPoints - Combo point display. AUF will set the child textstring <CPPoints>Text if it finds one to the current combo point count. An event of AUF_UPDATECOMBOPOINTS(<combo point count>) is also raised.

Happiness - pet happiness icon/element. AUF will update the <Happiness>texture if it finds one to the blizzard happiness icon. AUF will also update and %happiness strings on health or mana bars for player pets.


AUF functions

These are the funtions your addon will need to use to add/remove elements from AUF or force updates as desired.

AceUnitFrames:AddBar(bartype, bar, unit) - Adds an element to AUF to be maintained
bartype(string) - see AUF components above.
bar(xml element) - The xml element you are adding.
unit(string) - the unit this element is for, ie "player", "pet", "target" etc.

AceUnitFrames:RemoveBar(bartype, bar) - Removes a previously added element
bartype(string) - see AUF components above.
bar(xml element) - The xml element you are removing


AceUnitFrames:UpdateHealthBar(element)
AceUnitFrames:UpdatePowerBar(element)
AceUnitFrames:UpdateNameBar(element)
AceUnitFrames:UpdatePVPIcon(element)
AceUnitFrames:UpdateActivityIcon(element)
AceUnitFrames:UpdateLevelBar(element)
AceUnitFrames:UpdatePlayerXP(element)
AceUnitFrames:UpdatePortraitBar(element)
- element is the element previousl added via AddBar

AceUnitFrames:UpdatePet(unit)
AceUnitFrames:UpdateBuffs(unit)
- unit is the unit you wish to update

AceUnitFrames:UpdateBarText(bar)
- bar is a status bar previously added via AddBar. Use this whenever you change the <statusbar>.T1 - T3 values to display the changes.

AceUnitFrames:UpdateXPBarText(bar)
- bar is a XP status bar previously added via AddBar. Use this whenever you change the <statusbar>.T1 - T3 values to display the changes.

AceUnitFrames:ChangeBarTexture() updates all bars that have a .texture set to use the texture.

AceUnitFrames:HidePartyInRaid(true/false) true = party frames to hide when in a raid, false = party frames show when in a raid.

These fuctions show/hide the blizzard frames

AceUnitFrames:HideBlizzardPlayer(TRUE)
AceUnitFrames:HideBlizzardTarget(TRUE)
AceUnitFrames:HideBlizzardBuff(TRUE)
AceUnitFrames:HideBlizzardParty(TRUE)


Setting custom status bar colors.

Currently you can set both HealthBar and ManaBar custom colors

AceUnitFrames:SetBarColor(<bartype>, <colortable>)
<bartype> = "HealthBar" or "ManaBar"
<colortable> = a table of the color values to use see below examples.
r1,g1,b1 = bar color at full
r2,g2,b2 = bar color at empty if bar.SmoothBar is set to true

ManaBar = {}
ManaBar[0] = { r1 = 0.00, g1 = 0.00, b1 = 1.00} -- Mana
ManaBar[1] = { r1 = 1.00, g1 = 0.00, b1 = 0.00} -- Rage
ManaBar[2] = { r1 = 1.00, g1 = 0.50, b1 = 0.25} -- Focus
ManaBar[3] = { r1 = 1.00, g1 = 1.00, b1 = 0.00} -- Energy
ManaBar[4] = { r1 = 0.00, g1 = 1.00, b1 = 1.00} -- Happiness

HealthBar = {}
HealthBar[0] = { r1 = 0.00, g1 = 1.00, b1 = 0.00, r2 = 1.00, g2 = 0.00, b2 = 0.00}