/keys now only show the player name, before was showing the player name and the realm name

2023-01-02 16:02:48 -03:00
parent e98638cd83
commit 1e83cac1f2
9 changed files with 520 additions and 157 deletions
@@ -57,63 +57,91 @@ if (not PixelUtil) then
 	end
 end

+---return r, g, b, a for the default backdrop color used in addons
+---@return number
+---@return number
+---@return number
+---@return number
 function DF:GetDefaultBackdropColor()
 	return 0.1215, 0.1176, 0.1294, 0.8
 end

+---return if the wow version the player is playing is dragonflight or an expansion after it
+---@return boolean
 function DF.IsDragonflightAndBeyond()
 	return select(4, GetBuildInfo()) >= 100000
 end

+---return if the wow version the player is playing is dragonflight
+---@return boolean
 function DF.IsDragonflight()
 	local _, _, _, buildInfo = GetBuildInfo()
 	if (buildInfo < 110000 and buildInfo >= 100000) then
 		return true
 	end
+	return false
 end

+---return if the wow version the player is playing is a classic version of wow
+---@return boolean
 function DF.IsTimewalkWoW()
    local _, _, _, buildInfo = GetBuildInfo()
    if (buildInfo < 40000) then
        return true
    end
+	return false
 end

+---return if the wow version the player is playing is the vanilla version of wow
+---@return boolean
 function DF.IsClassicWow()
    local _, _, _, buildInfo = GetBuildInfo()
    if (buildInfo < 20000) then
        return true
    end
+	return false
 end

+---return true if the player is playing in the TBC version of wow
+---@return boolean
 function DF.IsTBCWow()
    local _, _, _, buildInfo = GetBuildInfo()
    if (buildInfo < 30000 and buildInfo >= 20000) then
        return true
    end
+	return false
 end

+---return true if the player is playing in the WotLK version of wow
+---@return boolean
 function DF.IsWotLKWow()
    local _, _, _, buildInfo = GetBuildInfo()
    if (buildInfo < 40000 and buildInfo >= 30000) then
        return true
    end
+	return false
 end

+---return true if the player is playing in the WotLK version of wow with the retail api
+---@return boolean
 function DF.IsWotLKWowWithRetailAPI()
    local _, _, _, buildInfo = GetBuildInfo()
    if (buildInfo < 40000 and buildInfo >= 30401) then
        return true
    end
+	return false
 end

+---return true if the version of wow the player is playing is the shadowlands
 function DF.IsShadowlandsWow()
    local _, _, _, buildInfo = GetBuildInfo()
    if (buildInfo < 100000 and buildInfo >= 90000) then
        return true
    end
+	return false
 end

+---for classic wow, get the role using the texture from the talents frame
 local roleBySpecTextureName = {
 	DruidBalance = "DAMAGER",
 	DruidFeralCombat = "DAMAGER",
@@ -157,7 +185,8 @@ local roleBySpecTextureName = {
 	DeathKnightUnholy = "DAMAGER",
 }

--classic, tbc and wotlk role guesser based on the weights of each talent tree
+---classic, tbc and wotlk role guesser based on the weights of each talent tree
+---@return string
 function DF:GetRoleByClassicTalentTree()
 	if (not DF.IsTimewalkWoW()) then
 		return "NONE"
@@ -197,6 +226,9 @@ function DF:GetRoleByClassicTalentTree()
 	return "DAMAGER"
 end

+---return the role of the unit, this is safe to use for all versions of wow
+---@param unitId string
+---@return string
 function DF.UnitGroupRolesAssigned(unitId)
 	if (not DF.IsTimewalkWoW()) then --Was function exist check. TBC has function, returns NONE. -Flamanis 5/16/2022
 		local role = UnitGroupRolesAssigned(unitId)
@@ -231,7 +263,8 @@ function DF.UnitGroupRolesAssigned(unitId)
 	end
 end

--return the specialization of the player it self
+---return the specialization of the player it self
+---@return number|nil
 function DF.GetSpecialization()
 	if (GetSpecialization) then
 		return GetSpecialization()
@@ -239,9 +272,11 @@ function DF.GetSpecialization()
 	return nil
 end

-function DF.GetSpecializationInfoByID(...)
+---return the specialization using the specId
+---@param specId unknown
+function DF.GetSpecializationInfoByID(specId)
 	if (GetSpecializationInfoByID) then
-		return GetSpecializationInfoByID(...)
+		return GetSpecializationInfoByID(specId)
 	end
 	return nil
 end
@@ -430,6 +465,10 @@ end

 DF.table = {}

+---find a value inside a table and return the index
+---@param t table
+---@param value any
+---@return integer|nil
 function DF.table.find(t, value)
 	for i = 1, #t do
 		if (t[i] == value) then
@@ -438,6 +477,11 @@ function DF.table.find(t, value)
 	end
 end

+---find the value inside the table, and it it's not found, add it
+---@param t table
+---@param index integer|any
+---@param value any
+---@return boolean
 function DF.table.addunique(t, index, value)
 	if (not value) then
 		value = index
@@ -454,6 +498,9 @@ function DF.table.addunique(t, index, value)
 	return true
 end

+---get the table 't' and reverse the order of the values within it
+---@param t table
+---@return table
 function DF.table.reverse(t)
 	local new = {}
 	local index = 1
@@ -464,6 +511,10 @@ function DF.table.reverse(t)
 	return new
 end

+---copy the values from table2 to table1, ignore the metatable and UIObjects
+---@param t1 table
+---@param t2 table
+---@return table
 function DF.table.duplicate(t1, t2)
 	for key, value in pairs(t2) do
 		if (key ~= "__index" and key ~= "__newindex") then
@@ -484,7 +535,10 @@ function DF.table.duplicate(t1, t2)
 	return t1
 end

--copy from table2 to table1 overwriting values
+---copy from the table 't2' to table 't1' ignoring the metatable and overwriting values, does copy UIObjects
+---@param t1 table
+---@param t2 table
+---@return table
 function DF.table.copy(t1, t2)
 	for key, value in pairs(t2) do
 		if (key ~= "__index" and key ~= "__newindex") then
@@ -499,7 +553,10 @@ function DF.table.copy(t1, t2)
 	return t1
 end

--copy from table2 to table1 overwriting values but do not copy data that cannot be compressed
+---copy from table2 to table1 overwriting values but do not copy data that cannot be compressed
+---@param t1 table
+---@param t2 table
+---@return table
 function DF.table.copytocompress(t1, t2)
 	for key, value in pairs(t2) do
 		if (key ~= "__index" and type(value) ~= "function") then
@@ -516,7 +573,10 @@ function DF.table.copytocompress(t1, t2)
 	return t1
 end

--add the indexes of table2 into table1
+---add the indexes of table2 into the end of the table table1
+---@param t1 table
+---@param t2 table
+---@return table
 function DF.table.append(t1, t2)
 	for i = 1, #t2 do
 		t1[#t1+1] = t2[i]
@@ -524,7 +584,10 @@ function DF.table.append(t1, t2)
 	return t1
 end

--copy values that does exist on table2 but not on table1
+---copy values that does exist on table2 but not on table1
+---@param t1 table
+---@param t2 table
+---@return table
 function DF.table.deploy(t1, t2)
 	for key, value in pairs(t2) do
 		if (type(value) == "table") then
@@ -537,6 +600,11 @@ function DF.table.deploy(t1, t2)
 	return t1
 end

+---get the contends of table 't' and return it as a string
+---@param t table
+---@param resultString string
+---@param deep integer
+---@return string
 function DF.table.dump(t, resultString, deep)
 	resultString = resultString or ""
 	deep = deep or 0
@@ -584,7 +652,9 @@ function DF.table.dump(t, resultString, deep)
 	return resultString
 end

--grab a text and split it into lines adding each line to a indexed table
+---grab a text and split it into lines adding each line to an array table
+---@param text string
+---@return table
 function DF:SplitTextInLines(text)
 	local lines = {}
 	local position = 1
@@ -624,6 +694,10 @@ elseif (GetLocale() == "zhTW") then
 	symbol_1K, symbol_10K, symbol_1B = "千", "萬", "億"
 end

+---get the game localization and return which symbol need to be used after formatting numbers, this is for asian languages
+---@return string
+---@return string
+---@return string
 function DF:GetAsianNumberSymbols()
 	if (GetLocale() == "koKR") then
 		return "천", "만", "억"
@@ -640,6 +714,9 @@ function DF:GetAsianNumberSymbols()
 end

 if (symbol_1K) then
+	---if symbol_1K is valid, the game has an Asian localization, 'DF.FormatNumber' will use Asian symbols to format numbers
+	---@param number number
+	---@return string
 	function DF.FormatNumber(number)
 		if (number > 99999999) then
 			return format("%.2f", number/100000000) .. symbol_1B
@@ -655,7 +732,10 @@ if (symbol_1K) then
 		return format("%.1f", number)
 	end
 else
-	function DF.FormatNumber (number)
+	---if symbol_1K isn't valid, 'DF.FormatNumber' will use western symbols to format numbers
+	---@param number number
+	---@return string|number
+	function DF.FormatNumber(number)
 		if (number > 999999999) then
 			return format("%.2f", number/1000000000) .. "B"
 		elseif (number > 999999) then
@@ -669,6 +749,9 @@ else
 	end
 end

+---format a number with commas
+---@param value number
+---@return string
 function DF:CommaValue(value)
 	if (not value) then
 		return "0"
@@ -684,6 +767,9 @@ function DF:CommaValue(value)
 	return left .. (num:reverse():gsub('(%d%d%d)','%1,'):reverse()) .. right
 end

+---call the function 'callback' for each group member passing the unitID and the extra arguments
+---@param callback function
+---@vararg any
 function DF:GroupIterator(callback, ...)
 	if (IsInRaid()) then
 		for i = 1, GetNumGroupMembers() do
@@ -701,23 +787,39 @@ function DF:GroupIterator(callback, ...)
 	end
 end

+---get an integer an format it as string with the time format 16:45
+---@param value number
+---@return string
 function DF:IntegerToTimer(value) --~formattime
 	return "" .. floor(value/60) .. ":" .. format("%02.f", value%60)
 end

+---remove the realm name from a name
+---@param name string
+---@return string
 function DF:RemoveRealmName(name)
 	return name:gsub(("%-.*"), "")
 end

+---remove the realm name from a name
+---@param name string
+---@return string
 function DF:RemoveRealName(name)
 	return name:gsub(("%-.*"), "")
 end

+---get the UIObject of type 'FontString' named fontString and set the font size to the maximum value of the arguments
+---@param fontString FontString
+---@vararg number
 function DF:SetFontSize(fontString, ...)
 	local font, _, flags = fontString:GetFont()
 	fontString:SetFont(font, max(...), flags)
 end

+---get the UIObject of type 'FontString' named fontString and set the font to the argument fontface
+---@param fontString FontString
+---@param fontface string
+---@return nil
 function DF:SetFontFace(fontString, fontface)
 	local font = SharedMedia:Fetch("font", fontface, true)
 	if (font) then
@@ -727,11 +829,28 @@ function DF:SetFontFace(fontString, fontface)
 	local _, size, flags = fontString:GetFont()
 	fontString:SetFont(fontface, size, flags)
 end
+
+---get the FontString passed and set the font color
+---@param fontString FontString
+---@param r any
+---@param g number|nil
+---@param b number|nil
+---@param a number|nil
+---@return nil
 function DF:SetFontColor(fontString, r, g, b, a)
 	r, g, b, a = DF:ParseColors(r, g, b, a)
 	fontString:SetTextColor(r, g, b, a)
 end

+---get the FontString passed and set the font shadow color and offset
+---@param fontString FontString
+---@param r number
+---@param g number
+---@param b number
+---@param a number
+---@param x number
+---@param y number
+---@return nil
 function DF:SetFontShadow(fontString, r, g, b, a, x, y)
 	r, g, b, a = DF:ParseColors(r, g, b, a)
 	fontString:SetShadowColor(r, g, b, a)
@@ -743,6 +862,10 @@ function DF:SetFontShadow(fontString, r, g, b, a, x, y)
 	fontString:SetShadowOffset(x, y)
 end

+---get the FontString object passed and set the rotation of the text shown
+---@param fontString FontString
+---@param degrees number
+---@return nil
 function DF:SetFontRotation(fontString, degrees)
 	if (type(degrees) == "number") then
 		if (not fontString.__rotationAnimation) then
@@ -757,6 +880,10 @@ function DF:SetFontRotation(fontString, degrees)
 	end
 end

+---receives a string and a color and return the string wrapped with the color using |c and |r scape codes
+---@param text string
+---@param color any
+---@return string
 function DF:AddColorToText(text, color) --wrap text with a color
 	local r, g, b = DF:ParseColors(color)
 	if (not r) then
@@ -770,6 +897,10 @@ function DF:AddColorToText(text, color) --wrap text with a color
 	return text
 end

+---receives a string 'text' and a class name and return the string wrapped with the class color using |c and |r scape codes
+---@param text string
+---@param className string
+---@return string
 function DF:AddClassColorToText(text, className)
 	if (type(className) ~= "string") then
 		return DF:RemoveRealName(text)
@@ -788,19 +919,33 @@ function DF:AddClassColorToText(text, className)
 	return text
 end

+---create a string with the spell icon and the spell name using |T|t scape codes to add the icon inside the string
+---@param spellId any
+---@return string
 function DF:MakeStringFromSpellId(spellId)
 	local spellName, _, spellIcon = GetSpellInfo(spellId)
 	if (spellName) then
 		return "|T" .. spellIcon .. ":16:16:0:0:64:64:4:60:4:60|t " .. spellName
 	end
+	return ""
 end

+---returns the class icon texture coordinates and texture file path
+---@param class string
+---@return number, number, number, number, string
 function DF:GetClassTCoordsAndTexture(class)
 	local l, r, t, b = unpack(CLASS_ICON_TCOORDS[class])
 	return l, r, t, b, [[Interface\WORLDSTATEFRAME\Icons-Classes]]
 end

-function DF:AddClassIconToText(text, playerName, class, useSpec, iconSize)
+---wrap 'text' with the class icon of 'playerName' using |T|t scape codes
+---@param text string
+---@param playerName string
+---@param englishClassName string this is the english class name, not the localized one, english class name is upper case
+---@param useSpec boolean|nil
+---@param iconSize number|nil
+---@return string
+function DF:AddClassIconToText(text, playerName, englishClassName, useSpec, iconSize)
 	local size = iconSize or 16

 	local spec
@@ -825,9 +970,10 @@ function DF:AddClassIconToText(text, playerName, class, useSpec, iconSize)
 		end
 	end

-	if (class) then
+	if (englishClassName) then
 		local classString = ""
-		local L, R, T, B = unpack(Details.class_coords[class])
+		--Details.class_coords uses english class names as keys and the values are tables containing texture coordinates
+		local L, R, T, B = unpack(Details.class_coords[englishClassName])
 		if (L) then
 			local imageSize = 128
 			classString = "|TInterface\\AddOns\\Details\\images\\classes_small:" .. size .. ":" .. size .. ":0:0:" .. imageSize .. ":" .. imageSize .. ":" .. (L * imageSize) .. ":" .. (R * imageSize) .. ":" .. (T * imageSize) .. ":" .. (B * imageSize) .. "|t"
@@ -838,11 +984,17 @@ function DF:AddClassIconToText(text, playerName, class, useSpec, iconSize)
 	return text
 end

+---return the size of a fontstring
+---@param fontString table
+---@return number
 function DF:GetFontSize(fontString)
 	local _, size = fontString:GetFont()
 	return size
 end

+---return the font of a fontstring
+---@param fontString table
+---@return string
 function DF:GetFontFace(fontString)
 	local fontface = fontString:GetFont()
 	return fontface
@@ -855,6 +1007,9 @@ local ValidOutlines = {
 	["THICKOUTLINE"] = true,
 }

+---set the outline of a fontstring, outline is a black border around the text, can be "NONE", "MONOCHROME", "OUTLINE" or "THICKOUTLINE"
+---@param fontString table
+---@param outline any
 function DF:SetFontOutline(fontString, outline)
 	local font, fontSize = fontString:GetFont()
 	if (outline) then
@@ -882,6 +1037,9 @@ function DF:SetFontOutline(fontString, outline)
 	fontString:SetFont(font, fontSize, outline)
 end

+---remove spaces from the start and end of the string
+---@param string string
+---@return string
 function DF:Trim(string)
 	return DF:trim(string)
 end
@@ -947,7 +1105,10 @@ function DF:CleanTruncateUTF8String(text)
 	return text
 end

--DF:TruncateNumber(number, fractionDigits): truncate the amount of numbers used to show fraction.
+---truncate the amount of numbers used to show the fraction part of a number
+---@param number number
+---@param fractionDigits number
+---@return number
 function DF:TruncateNumber(number, fractionDigits)
 	fractionDigits = fractionDigits or 2
 	local truncatedNumber = number
@@ -964,10 +1125,14 @@ function DF:TruncateNumber(number, fractionDigits)
 	return truncatedNumber
 end

+---attempt to get the ID of an npc from a GUID
+---@param GUID string
+---@return number
 function DF:GetNpcIdFromGuid(GUID)
 	local npcId = select(6, strsplit("-", GUID ))
 	if (npcId) then
-		return tonumber(npcId)
+		npcId = tonumber(npcId)
+		return npcId or 0
 	end
 	return 0
 end
@@ -1257,7 +1422,17 @@ end
 		IsColorTable = true,
 	}

-	--convert a any format of color to any other format of color
+	---convert a any format of color to any other format of color
+	---@param newFormat string
+	---@param r number|string
+	---@param g number|nil
+	---@param b number|nil
+	---@param a number|nil
+	---@param decimalsAmount number|nil
+	---@return string|table|number|nil
+	---@return number|nil
+	---@return number|nil
+	---@return number|nil
 	function DF:FormatColor(newFormat, r, g, b, a, decimalsAmount)
 		a = a or 1
 		r, g, b, a = DF:ParseColors(r, g, b, a)
@@ -1299,10 +1474,24 @@ end
 		return t
 	end

-	function DF:IsHtmlColor(color)
-		return DF.alias_text_colors[color]
+	---return true if DF.alias_text_colors has the colorName as a key
+	---DF.alias_text_colors is a table where key is a color name and value is an indexed table with the r g b values
+	---@param colorName any
+	---@return unknown
+	function DF:IsHtmlColor(colorName)
+		return DF.alias_text_colors[colorName]
 	end

+	---get the values passed and return r g b a color values
+	---the function accept color name, tables with r g b a members, indexed tables with r g b a values, numbers, html hex color
+	---@param red any
+	---@param green any
+	---@param blue any
+	---@param alpha any
+	---@return number
+	---@return number
+	---@return number
+	---@return number
 	function DF:ParseColors(red, green, blue, alpha)
 		local firstParameter = red

@@ -1365,6 +1554,7 @@ end
 			alpha = 1
 		end

+		--saturate the values before returning to make sure they are on the 0 to 1 range
 		return Saturate(red), Saturate(green), Saturate(blue), Saturate(alpha)
 	end