This library was created by Niketa (Nikketa-Hyjal-US) as a collection of basic addon development tools.
- LibAddonUtils
- Table of Contents
- Embedding the library
- API
- .CacheItem(item, callback, args)
- .CloneTable(tbl)
- .ColorFontString(str, color)
- .IncrementString(str, obj, validationFunc, args)
- .StringToTitle(str)
- .GetTableKey(tbl, value)
- .iformat(int, fType, roundDown)
- .pairs(tbl, func)
- .printt(tbl, condition)
- .round(number, decimals, roundDown)
- .tcount(tbl, key, value)
- .tpairs(tbl, callback, duration, key, value, sorting)
- .unpack(tbl, default)
1. Create a folder called Libs in your addon directory and copy LibAddonUtils to this folder. You can also place LibAddonUtils in your main directory, but having your libraries separate can help keep things organized.
ExampleAddon/Libs/LibAddonUtils
2. Create an XML file.
ExampleAddon/Libs/embeds.xml
If you are using multiple libraries, you can call them in the same file. The paths to libraries you are including should be relative to the embeds file.
In this example, my embeds.xml is in the Libs folder with all of the libraries I want to load:
<Ui xmlns="http://www.blizzard.com/wow/ui/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.blizzard.com/wow/ui/ ..\FrameXML\UI.xsd">
<Include file="LibAddonUtils\LibAddonUtils.xml"/>
</Ui>
Note: You don't have to use an XML file to load libraries. You may also call them directly in your TOC.
3. Update your TOC.
## Interface: 80200
## Title: ExampleAddon
## Notes: This addon does cool stuff!
## Author: Me
## Version: 1.0
Libs\embeds.xml
Core.lua
Always call libraries before your core addon files. Any files loaded before your embeds will not have access to the libraries.
If you would rather skip the XML, point to the library's XML file instead:
Libs\LibAddonUtils\LibAddonUtils.xml
4. Create an addon object. In your core addon file, you need to create an object to reference LibAddonUtils. This library uses LibStub, so you can do that like this:
local LibAddonUtils = LibStub("LibAddonUtils-1.0")
You can now access any of this library's functions with this reference.
LibStub is required to use this library.
Use this method to cache items before calling GetItemInfo. You can supply a callback to execute when the item table is available.
Args:
itemID: valid itemID, itemLink, itemName, or itemString.
callback: function to be called when the item has successfully been cached.
args: arguments to be sent to your callback function after itemID, as a vararg.
Returns: true or false when item table is available.
Example:
> local itemName = GetItemInfo(168487)
> print(itemName)
nil
> LibAddonUtils.CacheItem(168487, function(itemID, arg)
> print(GetItemInfo(itemID), arg)
> end, "Test argument")
Zin'anthid Test argument
Recursively clones the supplied table.
Args: tbl: table to be cloned.
Returns: cloned table.
Colors the supplied font string.
Args:
str: string to be colored.
color: valid color key:
LIGHTRED, LIGHTBLUE, TORQUISEBLUE, SPRINGGREEN, GREENYELLOW, BLUE, PURPLE, GREEN, RED, GOLD, GOLD2, GREY, WHITE, SUBWHITE, MAGENTA, YELLOW, ORANGEY, CHOCOLATE, CYAN, IVORY, LIGHTYELLOW, SEXGREEN, SEXTEAL, SEXPINK, SEXBLUE, SEXHOTPINK.
Returns: the colored font string.
Adds an incremental number to the provided string.
Args:
str: string to be enumerated.
obj: Object of which validationFunc should be called from. Must return an object or nil.
validationFunc: function to validate the enumerated string.
args: args to be passed to validationfunc. The string provided to this function will be called last in the validation function.
Returns: the enumerated font string.
Example:
> local db = {New = true, "New 2" = true, "New 4" = true}
> function(key)
> return db[key]
> end
> print(LibAddonUtils.IncrementString("New", nil, "KeyExists"))
New 3
> print(LibAddonUtils.IncrementString("New", nil, "KeyExists"))
New 5
Converts the provided string to title case.
Args: str: string to be transformed.
Returns: the transformed font string.
Finds the key of the supplied table value.
Args:
tbl: table to be searched.
value: value to match.
Returns: all matched keys.
Formats the supplied integer.
Args:
int: integer to be formatted.
fType:
1 - adds commas to the integer (2000 > 2,000).
2 - abbreviates the integer (2000 > 2k).
roundDown: floors (rounds down) the number.
Returns: the formatted integer.
Iterates through a table based on keys.
Args:
tbl: table to be iterated.
func: custom sort function.
Prints out table keys/values.
Args:
tbl: table to be printed.
condition:
1 - prints key names.
2 - prints table values.
nil - prints key/value pairs.
Rounds a number to x decimals.
Args:
number: integer to be rounded.
decimals: the number of decimal places to round to.
roundDown: floors (rounds down) the number.
Example:
> print(LibAddonUtils.round(3.14, 0))
3
Counts the number of entries in a table.
Args:
tbl: table to be counted.
key: only count table entries with keys that match this paramater.
value: only count table entries with values that match this paramater.
Returns: count as an integer.
Throttles iterations over a table to one table entry per duration seconds.
Args:
tbl: table to be iterated.
callback: function to be called at each iteration.
duration: number of seconds between each iteration, as an integer.
key: only iterate table entries with keys that match this paramater.
value: only iterate table entries with values that match this paramater.
sorting: custom sort func.
Returns: tbl and key are returned to the callback function.
Example:
>local myTable = {key1 = "specialValue", key2 = "value", key3 = "value", key4 = "specialValue"}
>LibAddonUtils.tpairs(myTable, function(tbl, key)
> print(key, tbl[key])
> end, 0.01, nil, "specialValue")
key1, specialValue
key4, specialValue
Unpacks tables with or without indexes (unlike the default behavior of unpack, which only accepts non-indexed tables) and allows you to specify a default table to return if tbl cannot be unpacked.
Args:
tbl: table to be unpacked.
default: table to unpack if tbl is invalid.
Example:
> db.style = "minimal"
> local styles = {
> ["default"] = {
> rgba = {1, 1, 1, 1}
> },
> ["minimal"] = {
> },
> }
> texture:SetColorTexture(unpack(styles[db.style].rgba))
bad argument #1 to 'unpack' (table expected, got nil)
> texture:SetColorTexture(LibAddonUtils.unpack(styles[db.style].rgba, {0, 0, 0, .75}))
>