WowAce

LibCandyBar-3.0 provides elegant timerbars with icons for use in addons.
It is based of the original ideas of the CandyBar and CandyBar-2.0 library. In contrary to the earlier libraries LibCandyBar-3.0 provides you with a timerbar object with a simple API.

Creating a new timerbar using the ':New' function will return a new timerbar object. This timerbar object inherits all of the barPrototype functions listed here.

Example

local candy = LibStub("LibCandyBar-3.0")
local texture = "Interface\\AddOns\\MyAddOn\\statusbar"
local mybar = candy:New(texture, 100, 16)
mybar:SetLabel("Yay!")
mybar:SetDuration(60)
mybar:Start()

barPrototype:AddUpdateFunction(func)

Adds a function to the timerbar.
The function will run every update and will receive the bar as a parameter.

Parameters

func

Function to run every update.

Usage

-- The example below will print the time remaining to the chatframe every update. Yes, that's a whole lot of spam
mybar:AddUpdateFunction( function(bar) print(bar.remaining) end )

barPrototype:Get(key)

Retrieves user data from the timerbar object.

Parameters

key

Key to retrieve

barPrototype:GetIcon()

Returns the icon texture path currently set on the bar, if it has an icon set.

barPrototype:GetLabel()

Returns the label (text) currently set on the bar.

barPrototype:Pause()

Pauses a running bar

barPrototype:Resume()

Resumes a paused bar

barPrototype:Set(key, data)

Sets user data in the timerbar object.

Parameters

key

Key to use for the data storage.

data

Data to store.

barPrototype:SetColor(r, g, b, a)

Sets the color of the bar.
This is basically a wrapper to SetStatusBarColor.

Parameters

r

Red component (0-1)

g

Green component (0-1)

b

Blue component (0-1)

a

Alpha (0-1)

barPrototype:SetDuration(duration, isApprox)

Sets the duration of the bar.
This can also be used while the bar is running to adjust the time remaining, within the bounds of the original duration.

Parameters

duration

Duration of the bar in seconds.

isApprox

Boolean. True if you wish the time display to be an approximate "5" instead of "5"

barPrototype:SetFill(fill)

Set whether the bar should drain (default) or fill up.

Parameters

fill

Boolean true/false

barPrototype:SetIcon(icon, ...)

Sets the icon next to the bar.

Parameters

icon

Path to the icon texture or nil to not display an icon.

...

Optional icon coordinates for texture trimming.

barPrototype:SetLabel(text)

Sets the label on the bar.

Parameters

text

Label text.

barPrototype:SetShadowColor(r, g, b, a)

Sets the shadow color of the bar label and bar duration text.

Parameters

r

Red component (0-1)

g

Green component (0-1)

b

Blue component (0-1)

a

Alpha (0-1)

barPrototype:SetTextColor(r, g, b, a)

Sets the color of the bar label and bar duration text.

Parameters

r

Red component (0-1)

g

Green component (0-1)

b

Blue component (0-1)

a

Alpha (0-1)

barPrototype:SetTexture(texture)

Sets the texture of the bar.
This should only be needed on running bars that get changed on the fly.

Parameters

texture

Path to the bar texture.

barPrototype:SetTimeVisibility(bool)

Sets wether or not the time indicator on the right of the bar should be shown.
Time is shown by default.

Parameters

bool

true to show the time, false/nil to hide the time.

barPrototype:Start(maxValue)

Shows the bar and starts it.

Parameters

maxValue

Number. If you don't wish your bar to start full, you can set a max value. A maxValue of 10 on a bar with a duration of 5 would start it at 50%.

barPrototype:Stop(...)

Stops the bar.
This will stop the bar, fire the LibCandyBar_Stop callback, and recycle the bar into the candybar pool. Note: make sure you remove all references to the bar in your addon upon receiving the LibCandyBar_Stop callback.

Parameters

...

Optional args to pass across in the LibCandyBar_Stop callback.

Usage

-- The example below shows the use of the LibCandyBar_Stop callback by printing the contents of the label in the chatframe
local function barstopped( callback, bar )
  print( bar.candybarLabel:GetText(), "stopped")
end
LibStub("LibCandyBar-3.0"):RegisterCallback(myaddonobject, "LibCandyBar_Stop", barstopped)

lib:New(texture, width, height)

Creates a new timerbar object and returns it.
Don't forget to set the duration, label and :Start the timer bar after you get a hold of it!

Parameters

texture

Path to the texture used for the bar.

width

Width of the bar.

height

Height of the bar.

Usage

mybar = LibStub("LibCandyBar-3.0"):New("Interface\\AddOns\\MyAddOn\\media\\statusbar", 100, 16)