ButtonFacade/Addons

From WowAce Wiki

The proper way to access the library to allow optional support of Button Facade is to use:

local LBF = LibStub("LibButtonFacade",true)

This allows you to test whether the library is loaded, and only use library functions if it is. Otherwise you would default to a normal system.

Contents 1 Callbacks 1.1 :ElementListCallback(callback, arg) 1.1.1 Args 1.1.2 Remarks 1.1.3 Example 1.2 :RegisterSkinCallback("AddonID", callback, arg) 1.2.1 Args 1.2.2 Remarks 1.2.3 Example 2 Skins 2.1 :AddSkin("SkinID", definition[, overwrite]) 2.1.1 Args 2.1.2 Remarks 2.1.3 Example 2.2 :ListSkins() 2.2.1 Returns 2.2.2 Example 3 Special Functions 3.1 :SetNormalVertexColor(button, r, g, b, a) 3.1.1 Args 3.1.2 Example 3.2 :GetNormalVertexColor(button) 3.2.1 Args 3.2.2 Returns 3.2.3 Example 3.3 :GetGlossLayer(button) 3.3.1 Args 3.3.2 Returns 3.3.3 Example 3.4 :GetBackdropLayer(button) 3.4.1 Args 3.4.2 Returns 3.4.3 Example 4 Button Groups 4.1 :Group("Addon"[, "Group"[, "Button"]]) 4.1.1 Args 4.1.2 Returns 4.1.3 Example 4.2 :DeleteGroup("Addon"[, "Group"[, "Button"]]) 4.2.1 Args 4.2.2 Remarks 4.2.3 Example 4.3 :ListAddons() 4.3.1 Returns 4.3.2 Remarks 4.3.3 Example 4.4 :ListGroups("Addon") 4.4.1 Args 4.4.2 Returns 4.4.3 Remarks 4.4.4 Example 4.5 :ListButtons("Addon","Group") 4.5.1 Args 4.5.2 Returns 4.5.3 Remarks 4.5.4 Example 4.6 <LBFGroup>:AddButton(button[, buttondata]) 4.6.1 Args 4.6.2 Remarks 4.6.3 Example 4.7 <LBFGroup>:RemoveButton(button[, noReskin]) 4.7.1 Args 4.7.2 Example 4.8 <LBFGroup>:Skin("SkinID",Gloss,Backdrop) 4.8.1 Args 4.8.2 Remarks 4.8.3 Example 4.9 <LBFGroup>:Delete([noReskin]) 4.9.1 Args 4.9.2 Remarks 4.9.3 Example 4.10 <LBFGroup>.SkinID 4.10.1 Example 4.11 <LBFGroup>.Gloss 4.11.1 Example 4.12 <LBFGroup>.Backdrop 4.12.1 Example

Callbacks

 :ElementListCallback(callback, arg)

Registers a callback that is called whenever a new Button Group is created. Generally, this is only used by ButtonFacade itself.

Args

callback 

function - The function to be called.

arg 

any - The first parameter to be passed to the callback function.

Remarks

The callback is called as:

callback(arg,Addon,Group)

Where Addon and Group are the group identifiers of the group that gained a new sub-group.

Example

local LBF = LibStub("LibButtonFacade",true)
LBF:ElementListCallback(self.BFGroupCallback,self)

 :RegisterSkinCallback("AddonID", callback, arg)

Registers a callback that is called whenever a group using the given AddonID has its skin changed. This is allows actionbar addons to save the changed skin parameters in its Saved Variables.

Args

"AddonID" 

string - The AddonID you wish to listen for. This prevents one actionbar addon from receiving notices about other addon's buttons.

callback 

function - The function to be called.

arg 

any - The first parameter to be passed to the callback function.

Remarks

The callback is called as:

callback(arg,SkinID,Gloss,Backdrop,Group,Button,Colors)

Where SkinID, Gloss, Backdrop, and Colors are the Skin Parameters, and Group and Button are the remaining identifiers of the group that has changed. Colors comes last in the list for historical/backwards compatibility reasons.

Example

local LBF = LibStub("LibButtonFacade",true)
LBF:RegisterSkinCallback("MonkeyBar",self.SkinChanged,self)

Skins

 :AddSkin("SkinID", definition[, overwrite])

Registers a new skin with Button Facade.

Args

"SkinID" 

string - The name of the skin.

definition 

table - The definition table for the new skin.

[overwrite] 

false - If a skin already exists by the given name, this will fail without an error.

any other type - This will overwrite with the new data.

Remarks

For details on the format of the definition table, see: [[]].

Example

local LBF = LibStub("LibButtonFacade",true)
LBF:AddSkin("MySkin",MySkinDefinition)

 :ListSkins()

Returns a list of skins in a format usable by Ace3 and Rock dropdown config fields.

Returns

table - A list of skins in a table with keys and values equal to the name of the skin.

Example

local LBF = LibStub("LibButtonFacade",true)
LBF:ListSkins()

Special Functions

 :SetNormalVertexColor(button, r, g, b, a)

Sets the color of the Normal layer (after factoring in a skin's color specification). Use this instead of :GetNormalTexture():SetVertexColor(r, g, b, a).

Args

button 

Button Frame - The Button to apply the new Normal layer color to.

r 

number - The red component of the new color. Defaults to 1

g 

number - The green component of the new color. Defaults to 1

b 

number - The blue component of the new color. Defaults to 1

a 

number - The alpha component of the new color. Defaults to 1

Example

local LBF = LibStub("LibButtonFacade",true)
LBF:SetNormalVertexColor(myMonkeyButton, 1, 0, 0)

 :GetNormalVertexColor(button)

Returns the color of the Normal layer (after factoring out a skin's color specification). Use this instead of :GetNormalTexture():GetVertexColor().

Args

button 

Button Frame - The Button to retrieve the current Normal layer color of.

Returns

r, g, b, a - The color components of the current color.

Example

local LBF = LibStub("LibButtonFacade",true)
r,g,b = LBF:GetNormalVertexColor(myMonkeyButton)

 :GetGlossLayer(button)

Returns the Gloss layer, or nil if there is none.

Args

button 

Button Frame - The Button to retrieve the current Gloss layer of.

Returns

texture - The Gloss layer of the given button, or nil.

Example

local LBF = LibStub("LibButtonFacade",true)
gloss = LBF:GetGlossLayer(myMonkeyButton)

 :GetBackdropLayer(button)

Returns the Backdrop layer, or nil if there is none.

Args

button 

Button Frame - The Button to retrieve the current Backdrop layer of.

Returns

texture - The Backdrop layer of the given button, or nil.

Example

local LBF = LibStub("LibButtonFacade",true)
gloss = LBF:GetBackdropLayer(myMonkeyButton)

Button Groups

 :Group("Addon"[, "Group"[, "Button"]])

Returns the group specified by the parameters. Will create new groups as needed.

Args

"Addon" 

string - The name the Actionbar addon wishes to identify itself as.

["Group"] 

string - The name of the Group level sub-group.

nil - If this is nil, "Button" must also be nil, and :Group will return just the group for the entire addon.

["Button"] 

string - The name of the third level sub-group.

nil - If this is nil :Group will return just the group for the Group level sub-group.

Returns

LBFGroup - LBFGroups have their own API for setting their skin and adding buttons to the group.

Example

local LBF = LibStub("LibButtonFacade",true)
LBF:Group("MonkeyBar", "MonkeyBar1")

 :DeleteGroup("Addon"[, "Group"[, "Button"]])

Deletes the specified group. If a group doesn't exist with the given parameters, this function simply returns.

Args

"Addon" 

string - The name the Addon level group.

["Group"] 

string - The name of the Group level sub-group.

nil - If this is nil, "Button" must also be nil, and :DeleteGroup will delete just the group for the entire addon.

["Button"] 

string - The name of the third level sub-group.

nil - If this is nil :DeleteGroup will delete just the group for the Group level sub-group.

Remarks

One can instead call the :Delete() method on an existing LBFGroup table.

Example

local LBF = LibStub("LibButtonFacade",true)
self:DeleteGroup("MonkeyBar", "MonkeyBar1")

 :ListAddons()

Gives a list of the names of Addon groups, suitable for use in an Ace3 or Rock dropdown field.

Returns

table - A table of key value pairs where the value is the name of the Addon.

Remarks

The key of these tables is a unique internal value, and should not be used with any of the API functions.

Example

local LBF = LibStub("LibButtonFacade",true)
LBF:ListAddons()

 :ListGroups("Addon")

Gives a list of the names of sub-groups of the Addon group, suitable for use in an Ace3 or Rock dropdown field.

Args

"Addon" 

string - The name the Addon level group.

Returns

table - A table of key value pairs where the value is the name of the Group.

Remarks

The key of these tables is a unique internal value, and should not be used with any of the API functions.

Example

local LBF = LibStub("LibButtonFacade",true)
LBF:ListGroups("MonkeyBar")

 :ListButtons("Addon","Group")

Gives a list of the names of sub-groups of the given Group, suitable for use in an Ace3 or Rock dropdown field.

Args

"Addon" 

string - The name the Addon level group.

"Group" 

string - The name of the Group level sub-group.

Returns

table - A table of key value pairs where the value is the name of the Button level group.

Remarks

The key of these tables is a unique internal value, and should not be used with any of the API functions.

Example

local LBF = LibStub("LibButtonFacade",true)
LBF:ListAddons("MonkeyBar","MonkeyBar1")

<LBFGroup>:AddButton(button[, buttondata])

Adds the provided button to the group, and immediately skins it.

Args

button 

Button Frame - The Frame (of type Button or CheckButton) to be skinned with this group.

[buttondata] 

table - A table providing custom frames and textures to have ButtonFacade skin instead of trying to find them on its own.

Remarks

The following are valid keys to use in buttondata:

• Icon
• Border (Note this is what Blizzard uses to display the equipped item glow.)
• Flash
• Cooldown
• AutoCast
• AutoCastable
• Normal - defaults to button:GetNormalTexture() or a skin specified alternative.
• Pushed - defaults to button:GetPushedTexture()
• Disabled - defaults to button:GetDisabledTexture()
• Checked - defaults to button:GetCheckedTexture()
• Highlight - defaults to button:GetHighlightTexture()
• HotKey
• Count
• Name

Example

local group = LBF:Group("MonkeyBar","MonkeyBar1")
group:AddButton(myMonkeyButton)

<LBFGroup>:RemoveButton(button[, noReskin])

Removes the provided button from the group, and will reskin it to the Blizzard skin if noReskin is not true.

Args

button 

Button Frame - The Frame to be removed from the group.

[noReskin] 

boolean - When set to true, the button will not be reskinned with the Blizzard skin. Useful if you intend to add it immediately to a different group.

Example

local group = LBF:Group("MonkeyBar","MonkeyBar1")
group:RemoveButton(myMonkeyButton)

<LBFGroup>:Skin("SkinID",Gloss,Backdrop)

Sets the skin used by the buttons in this group, as well as its sub-groups.

Args

"SkinID" 

string - The identifier of the skin to use. If the skin does not exist, it will default to "Blizzard".

Gloss 

number - Sets the alpha of the Gloss layer. At 0, the Gloss layer is completely hidden, at 1 it is fully visible.

nil or false - Identical to using 0.

true - Identical to using 1.

Backdrop 

boolean - Makes the backdrop visible if this is a true value. Hides it otherwise.

Remarks

This stores the chosen skin parameters, so buttons added to the skin afterward are automatically skinned with the new values.

Example

local group = LBF:Group("MonkeyBar","MonkeyBar1")
group:Skin("DreamLayout",0,true)

<LBFGroup>:Delete([noReskin])

Deletes the button group.

Args

[noReskin] 

boolean - If noReskin is not a true value, will reskin the group's buttons to the Blizzard skin.

Remarks

Renaming a button group is done by deleting the old one with noReskin set to true, then creating the new group, setting the skin parameters, and adding the buttons into the new group.

Example

local group = LBF:Group("MonkeyBar","MonkeyBar1")
group:Delete()

<LBFGroup>.SkinID

string - The SkinID of the group's current skin parameters.

Example

local group = LBF:Group("MonkeyBar","MonkeyBar1")
db.mygroupskin = group.SkinID

<LBFGroup>.Gloss

string - The Gloss of the group's current skin parameters.

Example

local group = LBF:Group("MonkeyBar","MonkeyBar1")
db.mygroupgloss = group.Gloss

<LBFGroup>.Backdrop

string - The Backdrop of the group's current skin parameters.

Example

local group = LBF:Group("MonkeyBar","MonkeyBar1")
db.mygroupbackdrop = group.Backdrop