WowAce

Example:
First of all, here is a general example of how to use this module together with LuaText:

-- Query threat, holder and color
local namespace           = _G.ThreatLine_LuaTexts
local maxThreat, maxID    = namespace.GetPlayerRelativeThreat(unit)
local r, g, b             = namespace.GetPlayerTankedColor(unit, (maxThreat or 0) / 100)
-- Query holders name
local name = ""
if maxID and not UnitIsUnit(maxID, "player") then
	name = UnitName(maxID)
end
-- Threat info available
if maxThreat and maxThreat ~= 0 then
	return "|cff%02x%02x%02x%s%%\n%s|r", r*255, g*255, b*255, Round(maxThreat, 1), name
end
return ConfigMode()

What this code does is the following:

• "local namespace = _G.ThreatLine_LuaTexts" will give you access to new methods provided by this module. All methods are inside this namespace since I didn't want to over populate the global namespace.
  
• "local maxThreat, maxID" = namespace.GetPlayerRelativeThreat(unit)" will return the highest threat on "unit" and the unitID who corresponds to this threat, but ignoring yourself. "unit" is given by PitBull4 itself when using LuaText. "GetPlayerRelativeThreat" tries to be smart about which mob to query threat on, see description for more details.
  
• "local r, g, b = namespace.GetPlayerTankedColor(unit, (maxThreat or 0) / 100)" will return an appropriate color corresponding to the current aggro status. The last argument (maxThreat or 0) / 100 is optional an enables coloring by threat amount.
  
• The rest of the code only formats the text for output. All in all this LuaText will display your relative threat on your current target (or it's targettarget) and displays aggro holder if it isn't yourself.

Important:
The following function can not be found in the global namespace itself, but rather via ThreatLine_LuaTexts. Thus, to call GetPlayerRelativeThreat(unitID) you need to do ThreatLine_LuaTexts.GetPlayerRelativeThreat(unitID). (Note the dot!)

function GetTankedStatus(unitID, mobID)
This function will return a value similar to GetThreatStatus(unitID, mobID), but with raid tank support.

Parameters:

• unitID - The unit of who's aggro status should be queried
  
• mobID - The mob who's threat list should be used

Return values:

• int - 0 = You have aggro, 1 = Another tank has aggro, 2 = Non tank aggro, 3 unknown

function GetTankedColor(unitID, mobID, value)
This function will return a color according to aggro status between unitID and mobID. (Color's may be changed via PitBull4 -> Colors)

Parameters:

• unitID - The unit of who's aggro status should be queried
  
• mobID - The mob who's threat list should be used
  
• value - (optional) Pass relative threat, to allow coloring by amount of threat (must be [0-1])

Return values:

• r - Color information
  
• g - Color information
  
• b - Color information

function GetMaxThreatUnit(mobID, exclude)
Returns the amount of threat [0-100] of the highest party-/raid member on mobIDs threat list. Excluding players is possible.

Parameters:

• mobID - The mob who's threat list should be used
  
• exclude - Unit's to exclude from scanning. Must be of the format {["unitID1"] = true, ["unitID2"] = true, ...}. Accepted are player, pet, partyN, partyNpet, raidN, raidNpet.

Return values:

• Threat Threat of the highest party-/raid member on the mobs threat list. (Will return a value [0-100])
  
• unitID - unitID of this party-/raid member

function GetMaxThreatNonPlayerUnit(mobID)
See GetMaxThreatUnit. Will exclude Player by default.

function GetRelativeThreat(unitID, mobID)
Return highest person threat on mobIDs threat list relative to unitIDs threat on mobIDs threat list

Parameters:

• unitID - The unit of who's aggro status should be queried
  
• mobID - The mob who's threat list should be used

Return values:

• Threat Threat of the highest party-/raid member on the mobs threat list. (Will return a value [0-100])
  
• unitID - unitID of this party-/raid member

function GetPlayerRelativeID(unitID)
This function will try be return a smart mobID. That is for example, if unitID is the unitID of a PitBull frame. Than this function will either return your target (unitID="player" or unitID="target" and you are targeting a mob), or unitIDs target (unitID="raid" or unitID="party", ect.), ...
Parameters:

• The unitID you want to try smart selection for.

Return values:

• Best found mobID for this unitID

function GetPlayerRelativeThreat(unitID)
See GetRelativeThreat. Calls GetPlayerRelativeID to get mobID.

function GetPlayerTankedColor(unitID, value)
See GetTankedColor. Calls GetPlayerRelativeID to get mobID.