ItemBonusLib-1.0

From WowAce Wiki
Jump to: navigation, search

Description

A library to get the bonus values of items.

API Documentation

:GetBonus("<id>")

Get the bonus value of the currently equipped item set.

Args

"<id>" 
string - Bonus Identifier

Returns

number - The current bonus value

Example

local agi = ibl:GetBonus("AGI")

:GetSlotBonuses("<slotname>")

Get the bonus value of the given slot.

Args

"<slotname>" 
string - The slot name (does not have "Slot" at the end, to keep it compatible with BonusScanner). The list of valid slot names is here.

Returns

table - The bonuses of the item currently equipped in the given slot. index is the bonus identifier, value is the bonus value.

Example

local head = ibl:GetSlotBonuses("Head")

:GetBonusDetails("<id>")

Get detailed breakdown of the given bonus.

Args

"<id>" 
string - Bonus Identifier

(compatible with BonusScanner)

Returns

table - Index is the slot name, value is the bonus value.

Example

local agi = ibl:GetBonusDetails("Head")
if agi.Head then ... end

:GetBonusFriendlyName("<id>")

Get the localised and user readable name for the given bonus id.

Args

"<id>" 
string - Bonus Identifier

Returns

string - The human readable bonus name.

Example

myString:SetText(ibl:GetBonusFriendlyName("AGI"))

:IsActive()

Added for compatibility with Bonus Scanner, returns always true.

Returns

boolean - true, the library is always active if it's loaded.

:ScanItem("<itemlink>", <excludeSet>, <no_cache>)

Get the bonus of the given item link.

Args

"<itemlink>" 
string - item identifier. Supports item ID, itemLink and Hyperlinks.
<excludeSet> 
boolean - kept for compatibility. Should be true.
<no_cache> 
boolean - Do not use cached data and do not cache the data.

Returns

table - Index is the bonus identifier, value is the bonus value.

Example

local bonuses = ibl:ScanItem(myItemLink, true)

:ClearCache()

Clear the item cache. The item cache is set up to be collected whenever the itemlink strings are collected, however, when using item database, this might never be the case.

:IsValidName(name)

Check if a bonus name is valid.

Args

"name" 
string - bonus name string.

Returns

boolean - true if one pattern exists that returns this bonus name as a possible effect.

:GetNameList()

Returns the list of bonus names.

Returns

table - return the sorted table of bonus names that are valid (i.e. there is at least one pattern that returns this name as a possible effect). Warning : For speed purpose, the internal table is returned by this function. DO NOT CHANGE IT, treat this table as strictly read-only.

Events

ItemBonusLib_Update Event

This event is triggered each time the equipment has changed and has been rescanned by the library.

ItemBonusLib caching considerations

Scanning item tooltips is a slow process. ItemBonusLib cache the results of scans to avoid repeating this slow process too often. This cache is set up to be automatically garbage collected whenever the "itemlink" itself is collected.

How to convert an addon that uses BonusScanner to ItemBonusLib

Use an event

ItemBonusLib uses an event to notify addons that the currently equipped bonuses have changed.

Instead of something like this :

 self:Hook("BonusScanner_Update")

You should write :

 self:RegisterEvent("ItemBonusLib_Update")

Get the library

The library is not in the global name space, so you should write something like this :

 local ibl = AceLibrary("ItemBonusLib-1.0")

to get the library instance. Then replace every instances of "BonusScanner" with "ibl".

Fix BONUSSCANNER_NAMES

BonusScanner did not provide an API to get the user readable names of Bonuses. Addons used to directly index the global table BONUSSCANNER_NAMES. This is no longer possible.

Replace :

 BONUSSCANNER_NAMES["AGI"]

with :

 ibl:GetBonusFriendlyName("AGI")

Combat Rating Compatibility

The WoW 2.0 patch change several bonuses. Instead of pure number, like critical chance, you get a rating which in turn is tranlated to a chance.

ItemBonusLib provides a compatibility layer, thanks to the work of Whitetooth ([1]), so that if you request the critical chance bonus and the library has detected a critical rating, the rating will be converted to a percentage.