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.

wow-api-widget