WoW Widget API (Curated)
This skill documents the Widget API for World of Warcraft Retail. It is curated: it highlights the core types, methods, and patterns you use most. For exhaustive lists, follow the source links.
Source of truth: https://warcraft.wiki.gg/wiki/Widget_API Script handlers: https://warcraft.wiki.gg/wiki/Widget_script_handlers XML schema: https://warcraft.wiki.gg/wiki/XML_schema Current as of: Patch 12.0.0 (Retail)
When to Use This Skill
Use this skill when you need to:
-
Create or manipulate UI frames (CreateFrame , Frame:SetPoint , Frame:Show )
-
Work with textures and visual regions (Texture:SetTexture , TextureBase:SetAtlas )
-
Handle font strings and text display (FontString:SetText , FontInstance:SetFont )
-
Build animations (AnimationGroup:Play , Animation:SetDuration )
-
Manage tooltips (GameTooltip:SetOwner , GameTooltip:AddLine )
-
Handle buttons and interactive controls (Button:SetText , EditBox:SetText , Slider:SetValue )
-
Work with status bars and cooldowns (StatusBar:SetValue , Cooldown:SetCooldown )
-
Use model frames for 3D displays (Model:SetModel , ModelScene:CreateActor )
-
Anchor, size, show or hide, and parent UI elements
-
Register frames for events (Frame:RegisterEvent , Frame:RegisterUnitEvent )
-
Set up script handlers (ScriptObject:SetScript , ScriptObject:HookScript )
Widget Hierarchy (Short)
FrameScriptObject Object ScriptObject ScriptRegion (+ ScriptRegionResizing + AnimatableObject) Region TextureBase -> Texture, MaskTexture, Line FontString (+ FontInstance) Frame (+ FontInstance) Button -> CheckButton EditBox, MessageFrame, ScrollFrame, Slider, StatusBar, Cooldown GameTooltip, SimpleHTML, ColorSelect, MovieFrame Model -> PlayerModel -> CinematicModel, DressUpModel -> TabardModel ModelScene -> ModelSceneActor
AnimationGroup -> Animation -> Alpha, Rotation, Scale, Translation, Path, FlipBook Font (FrameScriptObject + FontInstance)
How to Use This Skill
-
Identify the widget type you are working with (for example: Frame , Texture , Button ).
-
Check the hierarchy above to find base types it inherits from.
-
Open the relevant reference file for core methods and examples.
-
Use the source links for exhaustive method lists.
Reference Files
Reference Contents
BASE-WIDGETS.md Base types, anchoring, input, scripts, visibility
TEXTURE-WIDGETS.md TextureBase, Texture, MaskTexture, Line
FONT-WIDGETS.md FontInstance, Font, FontString
ANIMATION-WIDGETS.md AnimationGroup, Animation, Alpha, Rotation, Scale, Translation, Path
FRAME-WIDGETS.md Frame core behavior, events, layering, movement
FRAME-CONTROLS.md Button, CheckButton, EditBox, ScrollFrame, Slider, StatusBar, Cooldown, MessageFrame, SimpleHTML
ADVANCED-WIDGETS.md GameTooltip, Model/PlayerModel, ModelScene, ColorSelect, MovieFrame
Core Patterns
Create and Anchor
local frame = CreateFrame("Frame", "MyFrame", UIParent, "BackdropTemplate") frame:SetSize(240, 120) frame:SetPoint("CENTER")
local title = frame:CreateFontString(nil, "OVERLAY", "GameFontNormal") title:SetPoint("TOP", 0, -12) title:SetText("Hello")
Events and Scripts
local f = CreateFrame("Frame") f:RegisterEvent("PLAYER_LOGIN") f:SetScript("OnEvent", function(self, event) print("Ready", event) end)
Buttons
local btn = CreateFrame("Button", nil, UIParent, "UIPanelButtonTemplate") btn:SetSize(120, 32) btn:SetPoint("CENTER") btn:SetText("Click") btn:RegisterForClicks("AnyUp") btn:SetScript("OnClick", function(self, button) print("Clicked", button) end)
Animations
local ag = frame:CreateAnimationGroup() local fade = ag:CreateAnimation("Alpha") fade:SetFromAlpha(0) fade:SetToAlpha(1) fade:SetDuration(0.25) ag:Play()
XML Schema Quickstart
<Ui> <Frame name="MyXmlFrame" parent="UIParent" hidden="true"> <Size x="240" y="120"/> <Anchors> <Anchor point="CENTER"/> </Anchors> <Scripts> <OnLoad> self:RegisterEvent("PLAYER_LOGIN") </OnLoad> <OnEvent> print(event) </OnEvent> </Scripts> </Frame> </Ui>
Script Handlers Quick Map
-
ScriptRegion: OnShow , OnHide , OnEnter , OnLeave , OnMouseDown , OnMouseUp , OnMouseWheel
-
Frame: OnEvent , OnUpdate , OnSizeChanged , OnDragStart , OnDragStop , OnKeyDown , OnKeyUp
-
Button: OnClick , OnDoubleClick , PreClick , PostClick
-
EditBox: OnTextChanged , OnEnterPressed , OnEscapePressed , OnTabPressed
-
Slider/StatusBar: OnValueChanged , OnMinMaxChanged
-
AnimationGroup/Animation: OnPlay , OnStop , OnFinished , OnUpdate
For the full handler list by widget type, see https://warcraft.wiki.gg/wiki/Widget_script_handlers.
Specialized Widgets (Summary)
For advanced widgets (GameTooltip, Model, ModelScene, ColorSelect, MovieFrame), see ADVANCED-WIDGETS.md. Use the Widget API page for full method lists and specialized widget details.
Security Annotations
Methods tagged in the API reference have usage restrictions:
-
#protected
-
Blizzard secure code only.
-
#secureframe
-
Not callable on protected frames during combat.
-
#nocombat
-
Not callable during combat lockdown.
-
#restrictedframe
-
Returns nil for protected frames from insecure code in combat.
-
#anchorfamily
-
Anchor family restrictions apply.
Sources