BackdropTemplate

Main Menu
WoW API Lua API FrameXML Widget API Widget scripts XML schema Events CVars Macro commands Combat Log Escape sequences Hyperlinks API changes HOWTOs wowuidev

→ FrameXML Docs

A backdrop is a set of background and border textures created with BackdropTemplate {⁠, ⁠} or BackdropTemplateMixin.

Usage

Adding a new backdrop

1. Create a Frame that inherits BackdropTemplate.
2. Prepare a backdropInfo table, or choose an existing one from FrameXML/Backdrop.lua.
3. Apply the table in Lua using SetBackdrop(backdropInfo); or in XML using <KeyValue> tags.

Changing the backdrop

• Change the vertex colors by calling SetBackdropColor(r, g, b [, a]) and SetBackdropBorderColor(r, g, b [, a]).
• Change the other properties by calling SetBackdrop() with a new table (silently fails if its the same table, despite any changes).
• Remove a backdrop by calling SetBackdrop() without args

Alternatives

• Instead of SetBackdrop(backdropInfo), save the table as frame.backdropInfo and call ApplyBackdrop().
• Instead of SetBackdrop(nil), call ClearBackdrop()
• Instead of creating a new Frame, mixin BackdropTemplateMixin or create custom textures.

Table structure

backdropInfo

Key	Type	Description
bgFile	string	Texture path to use for the background.
edgeFile	string	Texture path to use for the edges.
tile	boolean	True to tile the background, false to stretch it.
tileSize	number	Width and height of each tile.
edgeSize	number	Border thickness and corner size.
insets	table	How far from the edges the background is drawn.

insets

Key	Type	Description
left	number	Distance inside the left edge.
right	number	Distance inside the right edge.
top	number	Distance inside the top edge.
bottom	number	Distance inside the bottom edge.

Methods

When applied to any Frame, BackdropTemplateMixin adds the following API:

ApplyBackdrop() - Applies the backdrop currently saved as frame.backdropInfo. {⁠}

ClearBackdrop() - Hides the current background and border textures. {⁠}

SetBackdrop(backdropInfo) - Saves the table to frame.backdropInfo and calls ApplyBackdrop(), or calls ClearBackdrop() if the argument is nil. {⁠}

GetBackdrop() : table - Returns a copy of frame.backdropInfo. {⁠}

GetBackdropColor() : r, g, b, a - Returns the background vertex color. {⁠}

GetBackdropBorderColor() : r, g, b, a - Returns the border color. {⁠}

SetBackdropColor(r, g, b [, a]) - Returns the background vertex color. {⁠}

SetBackdropBorderColor(: r, g, b [, a]) - Returns the border color. {⁠}

The following methods also exist, but should not need to be called as they are registered via BackdropTemplate:

OnBackdropLoaded() - OnLoad handler to apply a background if it was set in XML using <KeyValues> tags.

OnBackdropSizeChanged() - OnSizeChanged handler to update the textures.

Examples

Creating a Frame in Lua and calling SetBackdrop()

local backdropInfo =
{
	bgFile = "Interface\\Tooltips\\UI-Tooltip-Background",
 	edgeFile = "Interface\\Tooltips\\UI-Tooltip-Border",
 	tile = true,
 	tileEdge = true,
 	tileSize = 8,
 	edgeSize = 8,
 	insets = { left = 1, right = 1, top = 1, bottom = 1 },
}

local frame = CreateFrame("Frame", nil, nil, "BackdropTemplate")
frame:SetBackdrop(backdropInfo)

Creating a Frame in Lua and calling ApplyBackdrop()

local frame = CreateFrame("Frame", nil, nil, "BackdropTemplate")
frame.backdropInfo = BACKDROP_TOOLTIP_8_8_1111  -- from FrameXML/Backdrop.lua
frame:ApplyBackdrop()

Creating a Frame in XML with KeyValue tags

 <Frame inherits="BackdropTemplate">
 	<KeyValues>
 		<KeyValue key="backdropInfo" value="BACKDROP_TOOLTIP_8_8_1111" type="global" />
 	</KeyValues>
 </Frame>

Patch changes

• Patch 1.14.0 (2021-09-28): Now backported to all Classic flavors; backwards-compatible code is no longer necessary.
  
• Patch 9.0.1 (2020-10-13): Added to FrameXML, replacing Frame:SetBackdrop() and <Backdrop>.