Custom Bar Styles

How to register a custom bar styler

For a full working example, look at the code for the "Beauty Case" style.

If you're applying anything custom to a LibCandyBar bar that is not available as a function directly on the bar (i.e. :SetIcon), you need to reset that in your BarStopped function manually. If not, other addons using LibCandyBar will be screwed.

Generally, we recommend asking us to create API to suit you, rather than hacking it yourself.

You should not be creating new frames every time a bar is spawned - you should free up unused frames when a bar is stopped, and reuse those same frames again on the next bar. Again, the code for the "Beauty Case" style has an example of how that works.

When reusing a frame it's important to re-parent it to something else when a bar stops and to clear all points and such. Oh, and :Hide it.

RegisterBarStyle(identifier, propertyTable)

This is the API call that makes everything work. It is part of the BigWigsAPI global variable, you can access it using BigWigsAPI:RegisterBarStyle(identifier, propertyTable)

• identifier: [string] This is the internal name used for the style and must be unique. Note: This is not the value that is shown in the config to select your style.
• propertyTable: [table]
  • apiVersion: 1. Must match the current BigWigs bar style API version which is currently 1. A style that tries to register with the wrong version number will be ignored.
  • version: [number] The version of the style you're registering. If a style with the same identifier has already been registered, your attempt to re-register it will be ignored if the given version is less than or the same
  • barSpacing: [number] The default bar spacing. When a user chooses to use this style, their default bar spacing will be changed to the one set here. After that, the user will still be free to change the bar spacing. (optional)
  • barHeight: [number] The default bar height. When a user chooses to use this style, their default bar height will be changed to the one set here. After that, the user will still be free to change the bar height. (optional)
  • fontSizeNormal: [number] The default font size for normal bars. When a user chooses to use this style, their normal bar font size will be changed to the one set here. After that, the user will still be free to change the normal bar font size. (optional)
  • fontSizeEmphasized: [number] The default font size for emphasized bars. When a user chooses to use this style, their emphasized bar font size will be changed to the one set here. After that, the user will still be free to change the emphasized bar font size. (optional)
  • fontOutline: [string] The default font outline for all bars, choices being "NONE", "OUTLINE" or "THICKOUTLINE". When a user chooses to use this style, their font outline will be changed to the one set here. After that, the user will still be free to change the font outline. (optional)
  • GetSpacing: [function] This functionality is not recommended as it prevents the user from changing the bar spacing. The function will be invoked every time BigWigs positions a bar to see how far apart it should be from other bars. (optional)
  • ApplyStyle: [function] Called every time a bar is created. (optional)
  • BarStopped: [function] Called every time a bar is stopped. (optional)
  • GetStyleName: [function] Returns the name you want your bar style to have in the user interface.

Creating your own dedicated BigWigs bar style addon

This is an example showing how to create an addon named MyBigWigsSkin. Your TOC should have all of the following fields. The load fields are important!

MyBigWigsSkin.toc:

## Interface: 90002
## Title: MyBigWigsSkin
## Dependencies: BigWigs

MyBigWigsSkin.lua

MyBigWigsSkin.lua:

BigWigsAPI:RegisterBarStyle("MyBigWigsSkin", {
	apiVersion = 1,
	version = 1,
	--barSpacing = 1, -- optional
	--barHeight = 16, -- optional
	--fontSizeNormal = 10, -- optional
	--fontSizeEmphasized = 13, -- optional
	--fontOutline = "NONE", -- optional
	--GetSpacing = function(bar) end, -- optional (not recommended)
	ApplyStyle = function(bar) end,
	BarStopped = function(bar) end,
	GetStyleName = function() return "My BigWigs Skin" end,
})

Adding code to an existing addon, for example, a general skinning addon

BigWigsAPI:RegisterBarStyle("MyBigWigsSkin", {
	apiVersion = 1,
	version = 1,
	--barSpacing = 4, -- optional
	--barHeight = 20, -- optional
	--fontSizeNormal = 10, -- optional
	--fontSizeEmphasized = 11, -- optional
	--fontOutline = "NONE", -- optional
	--GetSpacing = function(bar) end, -- optional (not recommended)
	ApplyStyle = function(bar) end,
	BarStopped = function(bar) end,
	GetStyleName = function() return "My BigWigs Skin" end,
})

Your TOC should list BigWigs as an optional dependency. This will make BigWigs load before your addon does, ensuring the existence of the BigWigsAPI global.

## OptionalDeps: BigWigs

List of known bar style addons

• AddonSkins (General UI skinning addon with a BigWigs bar style included)
• RuriWigs (Dedicated BigWigs bar style addon)

Don't see yours in the list? Let us know!