DogTag-1.0

From WowAce Wiki
Jump to: navigation, search
Summary
Lib: DogTag-1.0
A library to provide a markup syntax for unit frame FontStrings
TOC 2.1 (20100)
Category Library
Author ckknight
Details
Version 1.0
OptionalDeps Babble-2.2, Babble-Spell-2.2, MobHealth, MobInfo2, Threat-1.0, RangeCheck-1.0
Dependencies Ace2
Links
Betas Ace SVN Zip
Changelog FishEye

DogTag-1.0 is a library to provide a markup syntax for unit frame FontStrings. DogTag-1.0 requires AceLibrary.

For the list of tags generated by DogTag, see DogTag-1.0/Tags.

Syntax

Syntax is in the standard form "alpha [Tag] bravo" where alpha is a literal word, bravo is a literal word and [Tag] will be replaced by the associated dynamic text. All tags and modifiers are case-insensitive, but will be corrected to proper casing if the tags are legal.

Modifiers

Modifiers can change how a tag's output looks. For example, the HideZero modifier will hide the result if it is equal to the number 0. e.g. [CurHP:HideZero] will show the current health except when it's equal to 0, at which point it will be blank. You can chain together multiple modifiers as well, e.g. [MissingHP:HideZero:Negate] will show the missing health as a negative and not show it if it's equal to 0.

Arguments

Tags and modifiers can also take an argument, and can be fed in in a syntax similar to [MyTag(argument)] or [MyTag:Modifier(argument)]. You do not need to wrap in quotes for strings, this is done for you.

Logic branching (if statements)

Logic branching might be a little difficult for some to understand. It will help to read Programming in Lua: 3.3, Logical Operators before continuing in this section.

  • The ? as used by DogTag serves as a boolean AND.
  • The : as used by DogTag serves as a boolean OR.
  • The ! as used by DogTag serves as an else.

Examples

[Status:SureHP:PercentHP]

Will return one of the following (but only one):
  • Dead, Offline, Ghost, etc -- no further information since the OR indicates that there is already a legitimate return
  • 3560/8490 or 130/6575 (but not 62/100 unless the target in fact has 100 hit points) -- and not 0/2340 or 0/3592 because that would mean it is dead and that would have already been taken care of by the first tag in the sequence
  • 25 or 35 or 72 (percent health) -- if the unit is not dead, offline, etc, and your addon is uncertain of your target's maximum and current health, it will display percent health.
[Status:[SureHP?CurHP]:PercentHP:Percent] will deliver similar returns as to that above, but in a slightly different format which should be fairly apparent already.
But to clarify, the nested [SureHP?CurHP] uses a boolean AND which means that if SureHP is nil or blank, the whole value is taken to be nil or blank. If SureHP is not nil or blank, the actual returned value of this nested expression is actually the term following the AND -- in this case, CurHP. So this will show CurHP if SureHP is found nonblank (if your addon knows how much health the unit has).

[IsFriend?MissingHP:Negate:Green!CurHP:Red]

Will return one of the following (but only one):
  • If the unit is friendly, it will display the amount of health they must be healed to meet their maximum. It will be displayed in green, and with a negative sign in front of it.
  • If the unit is enemy, it will display the current health. As this sequence is written, it will not consider whether it is a valid health value or not. On enemies where their health is uncertain, it will show a percentage (but not with a following percent sign), until a more reliable value can be determined by your addon. This value will be displayed in red.

Negation of tags

You can negate a tag or modifier by prefixing it with ~. For tags, any non-blank value will turn blank and any blank value will turn into "True". For modifiers, any non-blank value will turn blank and any blank value will turn into the previous value (which in and of itself was non-blank). e.g. [CurHP:~IsEqual(50)] will hide any value not equal to 50.

Unit specification

In order to specify a certain tag or modifier for a specific unit and not necessarily the unit the fontstring belongs to, you can append the tag/modifier with #unit, e.g. [Name#target] will get the name of the target.

Internal expressions

It is possible to embed DogTag-1.0 sequences within other sequences. e.g. [Text([Level] [Class])] is functionally equivalent to [Level] [Class]. This can be useful in such occasions such as [Level:IsLess(Level#player)]. It is also possible to embed sequences within the core sequence itself, e.g. [[Status:CurHP]:Green] will highlight the result of [Status:CurHP] green, whereas [Status:CurHP:Green] would actually only highlight the result of [CurHP].

Example

local DogTag = AceLibrary("DogTag-1.0")

local myFS = myFrame:CreateFontString("myFS", "ARTWORK")

DogTag:RegisterFontString(myFS, "player", "[CurHP]")

DogTag:UpdateFontString(myFS)

DogTag:UnregisterFontString(myFS)

API Documentation

:RegisterFontString(fontstring, frame, "unit", "code")

Register a fontstring according to a certain unit and code.

Args

fontstring 
FontString - a FontString object
frame 
Frame - the unit frame the the fontstring belongs to.
"unit" 
string - the unit associated with the fontstring
"code" 
string - the DogTag code.

Remarks

You can register twice without unregistering. It will just overwrite the previous registration.

Example

DogTag:RegisterFontString(myFS, myPlayerFrame, "player", "[CurHP]")


:UnregisterFontString(fontstring)

Unregister a fontstring from DogTag-1.0

Args

fontstring 
FontString - a FontString object

Remarks

You can unregister a fontstring not registered to DogTag-1.0. It won't hurt anything.

Example

DogTag:UnregisterFontString(myFS)

:UpdateFontString(fontstring)

Manually update a fontstring registered with DogTag-1.0

Args

fontstring 
FontString - a FontString object

Remarks

Updating a fontstring not registered with DogTag-1.0 will not do anything.

Example

DogTag:UpdateFontString(myFS)

:UpdateAllForUnit("unit")

Manually update the fontstrings registered for "unit"

Args

"unit" 
string - the unit associated with the fontstrings.

Remarks

This will need to be called on units not handled by the Blizzard event system (e.g. targettarget, focustarget, raid1pet, etc.)

Example

DogTag:UpdateAllForUnit("player")

:UpdateAllForFrame(frame)

Manually update the fontstrings registered with the given frame

Args

frame 
Frame - the unit frame associated with the fontstrings.

Remarks

This will need to be called on units not handled by the Blizzard event system (e.g. targettarget, focustarget, raid1pet, etc.)

Example

DogTag:UpdateAllForFrame(myPlayerFrame)

:Evaluate("unit", "code")

Return the result of the evaluated code for the given unit.

Args

"unit" 
string - the associated unit
"code" 
string - the tag code to parse and evaluate.

Returns

string - result of the evaluated code for the given unit.

Example

local result = DogTag:Evaluate("target", "[Name]")

:FixCasing("code")

Returns the given code in the correct casing.

Remarks

Although DogTag-1.0 is case-insensitive, things typically look nicer when they're the proper case.

Args

"code" : string - the tag code examine.

Returns

string - the given code in the correct casing

Example

assert(DogTag:FixCasing("[name]") == "[Name]")