WowAce

LuaTexts is a text provider module for PitBull4. It's a more efficient alternative to DogTagTexts. Texts are entered using Lua rather that DogTags. You can select which events cause the text to update. Custom texts are harder to write than DogTags as it requires some knowledge of Lua.

The Basics

When configuring a LuaText you have the normal basics of font, size, and positioning just like any other text provider. Additionally you can configure some code (in this case a Lua script) and select some events.

The script is wrapped into a function by LuaTexts for you. So you can consider the text to be the body of a function. Your function will have the parameter unit passed to it which is the unit id for the frames unit.

Let's start with a basic text that shows the current and max HP for the frames unit.

return "%s / %s",HP(unit),MaxHP(unit)

You'll see we're returning three values. A static string and the return values of the HP and MaxHP functions.

All of these return values are passed along to the SetFormattedText() function of the FontString that the text will be displayed on. SetFormattedText does two things it takes your parameters and puts them together the same way as the Lua string.format function (or similar format functions in pretty much every language).

This means that the first parameter is a format string. You can think of this string as a template for building your other text. The two %s placeholders are replaced with the current and max HP values.

If you do not wish to display anything do not return any values and LuaTexts will set the FontString to an empty string for you.

The Format String

You can find more information on the possible values for the placeholders on the WoWPedia entry for the format API: http://wowpedia.org/API_format

If you want to insert the actual % character just put two of them in. For instance: "25%%" would actually display "25%".

WoW uses the pipe character "|" as an escape for special sequences that they use for formatting characters. So if you want to insert a pipe character, you'll want to insert two of them as well. For instance "||" would actually output "|".

If you want to display a single string and don't need to do any formatting. You can simply return that single string. For instance:

return Name(unit)

Formatting your text

Colors

You can set the color by wrapping the text with the proper escape codes. For colors you start with |cff followed by the hex RGB 2 digit color codes. You return the color back to normal by using |r. For example let's say we want our example current and max HP to show the current HP in red we would do:

return "|cffff0000%s|r / %s",HP(unit),MaxHP(unit)

A lot of Blizzard functions can provide color values to you. Note that these color functions usually provide the color in the range of 0 to 1.0 as a decimal value. The escape code however expects the color codes to be in the range of 0 to 255. You can convert those by multiplying the 0 to 1.0 values by 255. For example:

local _,status,percent = UnitDetailedThreatSituation("player",unit)
local r,g,b = GetThreatStatusColor(status)
return "|cff%02x%02x%02x%s%%",r*255,g*255,b*255,percent

The format placeholder %02x asks for the color values to be shown as 2 digit, zero padded hex values.

There are several functions provided by LuaTexts to help you get colors. These functions will always return the color codes as 0 to 255, but you will still need to format that into hex values as shown above.

Icons

You can insert icons into the text using the proper escape codes: |TPATH_TO_ICON:SIZE|t

For example:

return "|TInterface/Icons/ability_warrior_decisivestrike:0|t"

Which would display the Icon for Decisive Strike. Setting the size to zero just uses the default size for the texture.

Outline

You can set an outline for the entire text. Unfortunately there is no way to set this just for some text. Calling the function Outline() in your code will set the Outline().

Outline()
return Name(unit)

ThickOutline() is also available to have a thicker outline.

Transparency

You can adjust the transparency of the text. Like outlines this can only be done for the entire text. The function Alpha(number) takes a number between 0 and 1.0 to specify how opaque the value should be. 0 would be completely transparent. 1.0 would be completely solid and 0.5 would be half transparent.

Alpha(0.5)
return Name(unit)

Updating

Most of the time you'll want your text to update when the text changes. This is done in one of 3 ways.

Events

The game generates events to tell us about specific changes. These events are the best way to specify when to update your text. Below the Lua script there is an Events dropdown box which allows you to set the events to trigger an update for the text.

If an event is not available in the dropdown box already you can add it. Go under Modules, LuaTexts and add the event. The name of the event needs to be exact. There are several checkboxes to specify that only texts that point to specific units should be updated. Player and pet will only update units specifically pointing at the player or pet. All will update all texts that have requested to be updated by that event. Unit means updating texts that point to the unit passed from the event in the first argument passed by Blizzard.

Timer

You can request that your text be updated at a specific time in the future. The UpdateIn(seconds) function lets you do that. The seconds can be fractional e.g. 0.5 would do the update in half a second. The text is only updated once, however as long as UpdateIn() is called in your code it will keep updating. This function is particularly useful for when you want to display a timer.

Displaying the time left before your PVP flag drops would look like this:

if IsPVPTimerRunning() then
  UpdateIn(0.25)
  return FormatDuration(GetPVPTimer()/1000)
end

Care should be taken not to set timers unnecessarily. You should trigger the initial display of the text with an event. Then keep it updating with UpdateIn(). Once the you no longer need the text you should stop calling UpdateIn(). The above example handles this by only calling UpdateIn() when there's something to actually display.

Implicitly

Some of the functions provided by LuaTexts help you out by flagging your text to be updated based on specific changes.

Power(unit)

Will flag the text for fast updates if the unit for the text is the player or the player's pet.

AFK(unit) and AFKDuration(unit)

Flags the text for update when the unit goes afk or comes back.

DND(unit)

Flags the text for update when the unit goes dnd or comes back.

Offline(unit) and OfflineDuration(unit)

Flags the text for update when the unit goes offline or comes back.

Dead(unit) and DeadDuration(unit)

Flags the text for update when the unit dies or resurrects.

PVPDuration(unit)

Flags the text for periodic updates when the timer for the pvp flag dropping is running.

IsMouseOver()

Flags the text for update when the mouse enters or leaves he frame the text is attached to.

CastData(unit)

Flags the text for update for fast updates while the unit is casting.

These implicit update flags are not a replacement for events. They fill in holes where the game does not provide events required for properly updating the texts.

Errors

Your Lua scripts can produce errors just like any other Lua code. The errors are trapped and should not break PitBull4. If there is an error your text will display {err} instead of the text. You can use an error addon such as BugSack or Swatter to display the actual errors.

They will be in one of two formats:

[string "PitBull4_LuaTexts:Target:Test"] line 1: attempt to call global 'retrun' (a nil value)

or

PitBull4_LuaTexts:Target:Test caused the following error: bad argument #2 to 'SetFormattedText' (string expected, got nil)

In the case of the first type this means there's some sort of syntax or run time error in your script. In the case of the second it means that argument #2 to SetFormattedText was nil when it should have been a string. Your return values from your script are the arguments to SetFormattedText. The FontString is actually argument #1 so argument #2 is the first return value and so on.

You'll note that both have this text: PitBull4_LuaTexts:Target:Test

This is there to help you identify the text causing the error. PitBull4_LuaTexts is of course the module. Target is the Layout the text is configured in. Test is the name of the text configuration.

Environment

The Lua code you enter and use for LuaTexts is run in a special environment. Within this environment a number of functions exist to help make it a little easier to get some commonly used text. This environment also allows you to save state between calls without cluttering the global namespace.

Variables that you use should be scoped within your script by using local in front of them e.g.

local foo
local bar = baz()

If you want to set a value within the namespace you should simply not use local. Keep in mind that any variables you set are shared with all the other scripts that run. If you really must set something within the global environment you must explicitly specify that by using _G

_G.foo = bar

You can however, access values and functions in the global environment without using _G. This allows easy access to Blizzard provided functions while still providing access to the functions in the ScriptEnv and protecting the global namespace.

Helper Functions

Name(unit)

Returns the name of the unit. If it is a Vehicle will display text like "Player's Vehicle"

VehicleName(unit)

Returns the name of the vehicle or the unit in the format of "Player's Vehicle" if the unit is a vehicle and the owner can be determined.

FormatDuration(seconds, format)

Converts time in seconds into a friendly format. format specifies the style of format. 'c' is the default format and stands for compressed e.g. "16:40" for 1000 seconds. 'f' for full e.g. "16m 40s" for 1000 seconds. 'e' for extended e.g. "16 Mins 40 Secs" for 1000 seconds. 's' for short e.g. "16.7 Mins" for 1000 seconds.

Angle(value)

Returns three values '<',value,'>' if value is not nil or ''. If value is '' or nil then it returns three empty strings.

Paren(value)

Returns three values '(',value,')' if value is not nil or ''. If value is '' or nil then it returns three empty strings.

UpdateIn(seconds)

Flag's the text to be updated one time in the given seconds (can be fractional)

AFKDuration(unit)

Return the seconds the unit has been AFK. Flags the text to be updated if the afk status changes and every 0.25 seconds when they are afk.

AFK(unit)

Returns "AFK (0:00)" for units that are AFK. Flags the text to be updated if the afk status changes and every 0.25 seconds when they are afk.

IsAFK(unit)

Returns true if the unit is AFK and false if not.

DND(unit)

Returns DND for units that are DND. Flags the text to be updated if the dnd status changes.

IsDND(unit)

Returns true if the unit is DND and false if not.

HostileColor(unit)

Returns r,g,b values (0-255) for the hostility of the unit.

ClassColor(unit)

Returns r,g,b values (0-255) for the class of the unit.

DifficultyColor(unit)

Returns r,g,b values (0-255) for the difficulty of the unit.

AggroColor(unit)

Returns r,g,b values(0-255) for the color provided by the WoW API UnitSelectionColor().

Classification(unit)

Returns the unit classification i.e. Rare, Rare-Elite, Elite, Boss

Class(unit)

Returns the class of the unit

Level(unit)

Returns the level of the unit or '??' if the level is too high to be known.

Creature(unit)

Returns the creature type for the unit.

SmartRace(unit)

Returns the race for units that are players and creature type for NPCs.

IsPet(unit)

Returns true if the unit is a pet.

OfflineDuration(unit)

Returns the time the unit has been offline. Flags the text for update when the offline state of the unit changes or ever 0.25 seconds.

Offline(unit)

Returns "Offline (0:00)". Flags the text for update when the offline state of the unit changes or ever 0.25 seconds.

IsOffline(unit)

Returns true if the unit is Offline and false if not.

DeadDuration(unit)

Returns the time the unit has been dead. Flags the text for update when the dead state of the unit changes or ever 0.25 seconds.

Dead(unit)

Returns "Dead (0:00)" or "Ghost (0:00)". Flags the text for update when the dead state of the unit changes or ever 0.25 seconds.

DruidForm(unit)

Returns the druid form of the unit if there is one.

Status(unit)

Returns "Offline (0:00)" if offline, "Divine Intervention" if they have the buff, "Feigned Death" if feigned or "Dead (0:00)" or "Ghost (0:00)". Flags the text for update as Offline() and Dead() does.

HP(unit, no_fast)

Returns HP or 0 if the unit is dead. If no_fast is true, do not enable fast updates for this text.

MaxHP(unit)

Returns unit's max HP.

Power(unit,power_type)

Returns the power for the unit of the power_type. If power_type is not passed then returns the power for the current power_type.

MaxPower(unit,power_type)

Returns the max power for the unit of the power_type. If power_type is not passed then returns the max power for the current power_type.

Round(number,digits)

Rounds the number to the given number of digits.

Short(number,format)

Shortens the number e.g. 1234 becomes 1.23k. If format is true then calls the format function for you and returns a single pre-formatted string. Otherwise returns the format string and the number.

VeryShort(number,format)

Shortens the number e.g. 1234 becomes 1k. If format is true then calls the format function for you and returns a single pre-formatted string. Otherwise returns the format string and the number.

IsMouseOver()

Returns true if the mouse is over the frame. Flags the text to be updated whenever the mouse enters or leaves the frame.

Combos(unit,target)

Returns the combo points for the unit. If target is not passed it's presumed to be the "target". If the unit is left blank it will return the player's combo points or if they have a vehicle their vehicle's combo points.

ComboPoints(symbol,unit,target)

Returns a string with the symbol string repeated for every combo point. unit and target are handled the same as Combos(unit,target)

Percent(x,y)

Figures the percent of y that x is.

XP(unit)

Returns the XP for the unit.

MaxXP(unit)

Returns the maximum XP for the unit.

RestXP(unit)

Returns the rest XP for the unit.

ThreatPair(unit)

Figures the pair of units to show threat for considering if the unit is friendly or not.

ThreatStatusColor(status)

Returns the color for the status of threat (0-255).

CastData(unit)

Returns a table with information about what the unit is casting. The keys are as follows: spell is the spell they are casting, rank is the rank of the spell, start_time is the time the spell started being cast, end_time is when the spell will finish, delay is how long the cast has been delayed, target is the target of the spell if available, casting is true if the spell is a spell cast, channeling is the cast is channeled, fade_out is true if the spell is canceled and it's during the fade time for the display, stop_time is when the spell stopped casting, stop_message is why the spell was stopped. Flags the text to be updated quickly when the unit is casting.

Alpha(number)

Sets the transparency of the text. 0 is invisible, 1 is solid.

Outline()

Sets the text to have an outline.

ThickOutline()

Sets the text to have a thick outline.

Abbreviate(text)

Abbreviates the text if it has a space in it. E.G. Blood Elf becomes BE

PVPDuration(unit)

Returns the time for the PVP flag to go away. Flags the text for fast updates when the timer is running.

HPColor(cur, max)

Returns r,g,b for the color of the text where 100% is green and going towards red at 0%. Values are in the 0-255 range.

PowerColor(power_type)

Returns the r,g,b for the given power type. Values are in the 0-255 range.

ConfigMode()

Returns the name of the text in curly braces if in config mode. Useful for some texts texts where there might not always be a value but config mode will show the bar they are attached to. For example cast bars.

ShortClassification(unit or classification)

Returns a shortened classification given a unit or a classifcation.

ShortClass(unit or class)

Returns a shortened class given a unit or class.

ShortRace(unit or race)

Returns a shortened race given a unit or class.

AggroColor(unit)

Wrapper for UnitSelectionColor()

HPColor(cur,max)

Returns a color for the HP with green being full, yellow being half and red being empty.

PowerColor(power_type)

Returns the color for the power type.

ReputationColor(reaction)

Returns the color for the reputation level given.

SeparateDigits(number, thousands, decimal)

Returns the number formatted as a string with the string passed in thousands separating the thousand places and the string passed in decimal separating the integer from the fractional. If thousands is omitted "," is used and if decimal is omitted "." is used.