CandyBar-2.0

From WowAce Wiki

CandyBar API

 :RegisterCandyBar(name, time, text, icon, c1, c2, ...)

Registers a new bar.

Args

name 

string - name of the bar. If this name is already registered, the bar with the same name will be reset.

time 

integer - nr of seconds the bar will run for

text 

string - the string to be displayed on the bar. defaults to the name if not set.

icon 

string - path to the icon texture, or nil if no icon should be displayed. default nil.

c1 

string - the color of the bar. default green.

c2 

string - the color of the gradient; default is no gradient

... 

string tuple - more colors for the gradient of the bar

Returns

Returns true if the bar was registered successfully.

Remarks

The bar will not be started yet, use :StartCandyBar for that.

Example

self:RegisterCandyBar("Food_Banana", 60, "Eating banana", 
  "Interface\\Addons\\Food\\Banana.tga", 
  "red", "green", "yellow", "blue")

 :UnregisterCandyBar(...)

Unregisters a bar.

Args

... 

string tuple - names of more bars to unregister

Returns

Returns true if the removal was succesful.

Example

self:UnregisterCandyBar("Food_Banana", "Food_Apple", "Food_Cherry")

 :IsCandyBarRegistered(name)

Returns true if a CandyBar is registered

Args

name 

string - name of the bar to check

Returns

true if the bar was registered.

Example

if self:IsCandyBarRegistered("Food_Banana") then
: -- do something special
end

 :StartCandyBar(name, fireforget)

Starts a CandyBar.

Args

name 

string - name of the bar to start

fireforget 

boolean - if true, automatically unregister the CandyBar when it finishes

Returns

true if the bar was started sucessfully.

Example

self:StartCandyBar("Food_Banana")

 :StopCandyBar(name)

Stops a CandyBar.

Args

name 

string - name of the bar to stop.

Remarks

A stopped bar is not paused, it is reset. Use :PauseCandyBar to pause a bar.

Example

self:StopCandyBar("Food_Banana")

 :PauseCandyBar(name)

Pauses a CandyBar.

Args

name 

string - name of the bar to pause.

Example

self:PauseCandyBar("Food_Banana")

 :CandyBarStatus(name)

Returns the status of a CandyBar.

Args

name 

string - name of the bar to return the status for

Returns

registered 

boolean - true if this bar is registered

time 

integer - total time scheduled for this bar

elapsed 

integer - time elapsed for this bar

running 

boolean - true if the bar is currently running

Example

local reg, t, e, r = self:CandyBarStatus("Food_Banana")
self:Print("I've been eating banana for %d seconds", e)

 :SetCandyBarTexture(name, texture)

Sets the texture of the CandyBar.

Args

name 

string - name of the bar

texture 

string - name of the texture that will be applied to the bar. If nil, the texture will be reset to the default.

Example

self:SetCandyBarTexture("Food_Banana", "Interface\\Addons\\Food\\bananatexture")

 :SetCandyBarTime(name, time)

Sets the time that the CandyBar will run for.

Args

name 

string - name of the bar

time 

integer - nr of the seconds the bar will run for

Remarks

This will reset the maximum time of the bar, but not the elapsed time if it's already been running. See :SetCandyBarTimeLeft.

Example

self:SetCandyBarTime("Food_Banana", 300)

 :SetCandyBarColor(name, color, alpha)

Sets the color of a CandyBar.

Args

name 

string - name of the bar

color 

string - color of the bar

alpha 

float - alpha value of the bar

Example

-- Make the banana bar transparent yellow
self:SetCandyBarColor("Food_Banana", "yellow", 0.5)

 :SetCandyBarText(name, text)

Sets the text of a CandyBar.

Args

name 

string - name of the bar

text 

string - new text of the bar

Example

self:SetCandyBarText("Food_Banana", "Bananas are for eating")

 :SetCandyBarIcon(name, icon [, left, right, top, bottom])

Sets the icon of a CandyBar

Args

name 

string - name of the bar

icon 

string - path to the icon texture, or nil to remove the icon

left, right, top, bottom 

float - values for SetTexCoord (defaults: 0, 1, 0, 1)

Remarks

For the SetTexCoord to take effect, this should be called after a bar is started.

Example

self:SetCandyBarIcon("Food_Banana", "Interface\\Addons\\Food\\banana.tga")

 :SetCandyBarIconPosition(name, position)

Sets the icon position of a CandyBar.

Args

name 

string - name of the bar

position 

string - position of icon, "LEFT" or "RIGHT"

Example

self:SetCandyBarIconPosition("Food_Banana", "RIGHT")

 :SetCandyBarBackgroundColor(name, color, alpha)

Sets the background color of a CandyBar.

Args

name 

string - name of the bar

color 

string - the new color of the background

alpha 

float - the alpha value of the background

Remarks

Calling this function resets any smooth transitions set for the bar.

Example

-- Set the background color to transparant green
self:SetCandyBarBackgroundColor("Food_Banana", "green", 0.5)

 :SetCandyBarTextColor(name, color, alpha)

Sets the text color of a CandyBar.

Args

name 

string - name of the bar

color 

string - the new color of the text

alpha 

float - the alpha value of the text

Example

-- Set the text color to a shimmering green
self:SetCandyBarTextColor("Food_Banana", "green", 0.25)

 :SetCandyBarTimerTextColor(name, color, alpha)

Sets the color of the timer text of a CandyBar.

Args

name 

string - name of the bar

color 

string - the new color of the timer text

alpha 

float - the alpha value of the timer text

Example

self:SetCandyBarTimerTextColor("Food_Banana", "red", 0.75)

 :SetCandyBarFontSize(name, size)

Sets the font size of the text on a CandyBar.

Args

name 

string - name of the bar

size 

number - size of the font

Example

self:SetCandyBarFontSize("Food_Banana", 20)

 :SetCandyBarPoint(name, point, rframe, rpoint, xoffset, yoffset)

Sets the anchoring point of a CandyBar.

Args

name 

string - name of the bar

point 

string - point to anchor this bar to (BOTTOMLEFT, TOPRIGHT, etc)

rframe 

string - frame relative to which this bar will be positioned (may be nil)

rpoint 

string - point on the relative frame to which this bar will be positioned (may be nil)

xoffset 

number - X offset for the anchor (may be nil)

yoffset 

number - Y offset for the anchor (may be nil)

Remarks

Works just like the regular WoW Frame:SetPoint. Look up that function for more information about positioning in WoW.

Example

self:SetCandyBarPoint("Food_Banana", "BOTTOMLEFT", "FoodFrame", "TOPLEFT", -10, 10)

 :SetCandyBarScale(name, scale)

Sets the scale of a CandyBar.

Args

name 

string - name of the bar

scale 

float - new scale of the bar

Remarks

Works just like the regular WoW Frame:SetScale. Look up that function for more information about scaling in WoW.

Example

-- I like big bananas
self:SetCandyBarScale("Food_Banana", 1.5)

 :SetCandyBarTimeFormat(name, func, ...)

Specifies a function that will format the timer text for a CandyBar.

Args

name 

string - name of the bar

func 

function - name of a function that will return the formatted string to be displayed on the timer text of the bar

... 

variable tuple - optional arguments to be passed to the function

Example

function ReturnTimerText(bar)
: local _,_,elapsed,_ = self:CandyBarStatus(bar)
: return string.format("%f hours", elapsed / 3600)
end
self:SetCandyBarTimeFormat("Food_Banana", ReturnTimerText, "Food_Banana")

 :SetCandyBarTimeLeft(name, time)

Sets the time that's left for a CandyBar.

Args

name 

string - name of the bar

time 

number - number of seconds left on the bar

Returns

true if the time left could be set

Example

-- Nearly finished eating
self:SetCandyBarTimeLeft("Food_Banana", 10)

 :SetCandyBarCompletion(name, func, ...)

Sets the function to be called upon completion of a CandyBar.

Args

name 

string - name of the bar

func 

function - the function that will be called

... 

variable tuple - optional arguments that will be passed to the function

Example

function BananaFinished()
: self:Print("Finished eating a banana")
end
self:SetCandyBarCompletion("Food_Banana", BananaFinished)

 :SetCandyBarOnClick(name, func, ...)

Set the OnClick function for a CandyBar.

Args

name 

string - name of the bar

func 

function - function to call when the bar is clicked

... 

variable tuple - optional arguments that will be passed to the function

Returns

true if succesful

Example

-- Clicking on the bar will cancel it
self:SetCandyBarOnClick("Food_Banana", CancelBar)

 :SetCandyBarReversed(name, reversed)

Sets direction of a CandyBar's growth.

Args

name 

string - name of the bar

reversed

boolean - if true, the bar will fill instead of deplete

Returns

true if successful

Example

self:SetCandyBarReversed:("Food_Banana", true)

 :IsCandyBarReversed(name)

Returns whether or not a CandyBar is reversed

Args

name 

string - name of the bar

Returns

reversed 

boolean - whether or not the bar is reversed

Example

self:SetCandyBarReversed:("Food_Banana")

 :RegisterCandyBarGroup(name)

Registers a new CandyBar group that will hold multiple CandyBars.

Args

name 

string - name of the new group

Example

self:RegisterCandyBarGroup("Food_Table")

 :UnregisterCandyBarGroup(name)

Releases a CandyBar group.

Args

name 

string - name of the group to be released.

Example

-- Finished eating everything on the table
self:UnregisterCandyBarGroup("Food_Table")

 :IsCandyBarGroupRegistered(name)

Returns true if the specified group name is registered.

Args

name 

string - name of the group to check

Returns

true if the specified name has been registered as a CandyBar group.

Example

if self:IsCandyBarGroupRegistered("Food_Ground") then
: -- do something with food on the ground
end

 :SetCandyBarGroupPoint(name, point, rframe, rpoint, xoffset, yoffset)

Sets the anchoring point of a CandyBar group.

Args

name 

string - name of the group

point 

string - point to anchor this group to (BOTTOMLEFT, TOPRIGHT, etc)

rframe 

string - frame relative to which this group will be positioned (may be nil)

rpoint 

string - point on the relative frame to which this group will be positioned (may be nil)

xoffset 

number - X offset for the anchor (may be nil)

yoffset 

number - Y offset for the anchor (may be nil)

Remarks

Works just like the regular WoW Frame:SetPoint. Look up that function for more information about positioning in WoW.

Example

-- Put the table in the center of the screen
self:SetCandyBarGroupPoint("Food_Table", "CENTER", "UIParent", "CENTER")

 :SetCandyBarGroupGrowth(name, growup)

Sets whether the CandyBar group grows up or down.

Args

name 

string - name of the group

growup 

boolean - true if the group grows upwards (ie new bars will be added at the top)

Example

-- Food on a table stacks upwards
self:SetCandyBarGroupGrowth("Food_Table", true)

 :SetCandyBarGroupVerticalSpacing(name, spacing)

Sets a vertical spacing between the bars of the group

Args

name 

string - name of the group

spacing

number - y offset between the bars

Example

- Sets a 10 unit vertical spacing between the bars of the group Food_table
self:SetCandyBarGroupVerticalSpacing("Food_Table", 10)

 :UpdateCandyBarGroup(name)

Updates the locations of bars in the group.

Args

name 

string - name of the group

Example

self:UpdateCandyBarGroup("Food_Table")

 :SetCandyBarFade(name, time)

Sets the fade duration of a bar.

Args

name 

string - name of the bar

time 

float - nr of seconds the bar will take to fade out. set it to a negative value to let the bar stay on screen.

Example

-- The banana shell will stay on the table
self:SetCandyBarFade("Food_Banana", -1)

 :RegisterCandyBarWithGroup(name, group)

Registers a CandyBar with a group.

Args

name 

string - name of the bar

group 

string - name of the group to put the bar in (must have been registered using :RegisterCandyBarGroup)

Example

self:RegisterCandyBarWithGroup("Food_Banana", "Food_Table")

 :UnregisterCandyBarWithGroup(name, group)

Removes a CandyBar from a group.

Args

name 

string - name of the bar

group 

string - name of the group to remove the bar from

Example

self:UnregisterCandyBarWithGroup("Food_Banana", "Food_Table")

 :IsCandyBarRegisteredWithGroup(name, group)

Returns true if the specified bar is registered with the specified group.

Args

name 

string - name of the bar

group 

string - name of the group

Returns

true if the bar is registered with the group.

Example

if self:IsCandyBarRegisteredWithGroup("Food_Banana", "Food_Table") then<br />
: -- bananas are on the table
end