Widget script handlers

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

Widget scripts allow you to respond to user interaction and other types of widget events (such as a frame being shown or hidden). This page lists the available scripts and the list of widget types for which each script is valid. Script types are defined in the XML Schema Definition.

Widget hierarchy

Base	Frame	Animation
ScriptObject Frame Animation AnimationGroup	Browser Button CheckButton ItemButton Checkout ColorSelect Cooldown EditBox FogOfWarFrame GameTooltip MessageFrame Minimap Model PlayerModel CinematicModel DressUpModel TabardModel ModelScene ModelSceneActor MovieFrame OffScreenFrame POIFrame ArchaeologyDigSiteFrame QuestPOIFrame ScenarioPOIFrame ScrollFrame ScrollingMessageFrame SimpleHTML Slider StatusBar UnitPositionFrame WorldFrame	Alpha Scale LineScale Translation LineTranslation Path Rotation TextureCoordTranslation

Widget API

ScriptObject:GetScript(scriptType [, bindingType]) - Returns the widget's script handler.

ScriptObject:SetScript(scriptType, handler) - Sets the widget's script handler.

ScriptObject:HookScript(scriptType, handler [, bindingType]) - Securely hooks a script handler.

ScriptObject:HasScript(scriptType) - Returns whether the widget supports a script type.

Example

Registers for clicks on a Button widget with the OnClick script.

local btn = CreateFrame("Button", nil, UIParent, "UIPanelButtonTemplate")
btn:SetPoint("CENTER")
btn:SetSize(100, 40)
btn:SetText("Click me")
btn:SetScript("OnClick", function(self, button)
	print("You clicked me with "..button)
end)
-- You clicked me with LeftButton

Note: This list is up to date as of Patch 9.0.5 (38134) Mar 29 2021

ScriptObject

[Edit ScriptObject]

ScriptObject is an abstract widget type that provides support for widget scripts.

OnLoad(self) - Run when the frame is created.

OnUpdate(self, elapsed) - Run each time the screen is drawn by the game engine.

AnimationGroup

AnimationGroup has the handlers from ScriptObject, plus the following:

OnFinished(self, requested) - Run when the animation (or animation group) finishes animating.

OnLoop(self, loopState) - Run when the animation group's loop state changes.

OnPause(self) - Run when the animation (or animation group) is paused.

OnPlay(self) - Run when the animation (or animation group) begins to play.

OnStop(self, requested) - Run when the animation (or animation group) is stopped.

Animation

Animation has the handlers from ScriptObject, plus the following:

OnFinished(self, requested)

OnPause(self)

OnPlay(self)

OnStop(self, requested)

Frame

Frame:AbortDrag()

Frame:CanChangeAttribute() : canChangeAttributes

Frame:CreateFontString([name, drawLayer, templateName]) : line - Creates a fontstring.

Frame:CreateLine([name, drawLayer, templateName, subLevel]) : line - Draws a line.

Frame:CreateMaskTexture([name, drawLayer, templateName, subLevel]) : maskTexture - Creates a mask texture.

Frame:CreateTexture([name, drawLayer, templateName, subLevel]) : texture - Creates a texture.

Frame:DesaturateHierarchy(desaturation [, excludeRoot])

Frame:DisableDrawLayer(layer) - Prevents display of the frame on the specified draw layer.

Frame:DoesClipChildren() : clipsChildren

Frame:EnableDrawLayer(layer) - Allows display of the frame on the specified draw layer.

Frame:EnableGamePadButton([enable]) - Allows the receipt of gamepad button inputs for this frame.

Frame:EnableGamePadStick([enable]) - Allows the receipt of gamepad stick inputs for this frame.

Frame:EnableKeyboard([enable]) - Allows this frame to receive keyboard input.

Frame:ExecuteAttribute(attributeName, unpackedPrimitiveType, ...) : success, unpackedPrimitiveType, ...

Frame:GetAlpha() : alpha -> Region:GetAlpha

Frame:GetAttribute(attributeName) : value - Returns the value of a secure frame attribute.

Frame:GetBoundsRect() : left, bottom, width, height

Frame:GetChildren() : child1, ... - Returns a list of child frames belonging to the frame.

Frame:GetClampRectInsets() : left, right, top, bottom - Returns the frame's clamp rectangle offsets.

Frame:GetDontSavePosition() : dontSave

Frame:GetEffectiveAlpha() : effectiveAlpha - Returns the effective alpha after propagating from the parent region.

Frame:GetEffectiveScale() : effectiveScale - Returns the effective scale after propagating from the parent region.

Frame:GetEffectivelyFlattensRenderLayers() : flatten - Returns true if render layer flattening has been implicitly enabled.

Frame:GetFlattensRenderLayers() : flatten - Returns true if render layer flattening has been enabled.

Frame:GetFrameLevel() : frameLevel - Returns the frame level of the frame.

Frame:GetFrameStrata() : strata - Returns the layering strata of the frame.

Frame:GetHitRectInsets() : left, right, top, bottom - Returns the insets of the frame's hit rectangle.

Frame:GetHyperlinksEnabled() : enabled - Returns true if mouse interaction with hyperlinks on the frame is enabled.

Frame:GetID() : id - Returns the frame's numeric identifier.

Frame:GetNumChildren() : numChildren - Returns the number of child frames belonging to the frame.

Frame:GetNumRegions() : numRegions - Returns the number of non-Frame child regions belonging to the frame.

Frame:GetPropagateKeyboardInput() : propagate - Returns whether the frame propagates keyboard events.

Frame:GetRegions() : region1, ... - Returns a list of non-Frame child regions belonging to the frame.

Frame:GetResizeBounds() : minWidth, minHeight, maxWidth, maxHeight - Returns the minimum and maximum size of the frame for user resizing.

Frame:GetScale() : frameScale -> Region:GetScale

Frame:HasFixedFrameLevel() : isFixed

Frame:HasFixedFrameStrata() : isFixed

Frame:Hide() -> ScriptRegion:Hide

Frame:InterceptStartDrag(delegate)

Frame:IsClampedToScreen() : clampedToScreen - Returns whether a frame is prevented from being moved off-screen.

Frame:IsEventRegistered(eventName) : isRegistered, unit1, ... - Returns whether a frame is registered to an event.

Frame:IsGamePadButtonEnabled() : enabled - Checks if this frame is configured to receive gamepad button inputs.

Frame:IsGamePadStickEnabled() : enabled - Checks if this frame is configured to receive gamepad stick inputs.

Frame:IsIgnoringParentAlpha() : ignore -> Region:IsIgnoringParentAlpha

Frame:IsIgnoringParentScale() : ignore -> Region:IsIgnoringParentScale

Frame:IsKeyboardEnabled() : enabled - Returns true if keyboard interactivity is enabled for the frame.

Frame:IsMovable() : isMovable - Returns true if the frame is movable.

Frame:IsObjectLoaded() : isLoaded -> Region:IsObjectLoaded

Frame:IsResizable() : resizable - Returns true if the frame can be resized by the user.

Frame:IsShown() : isShown -> ScriptRegion:IsShown

Frame:IsToplevel() : isTopLevel - Returns whether this frame should raise its frame level on mouse interaction.

Frame:IsUserPlaced() : isUserPlaced - Returns whether the frame has been moved by the user.

Frame:IsVisible() : isVisible -> ScriptRegion:IsVisible

Frame:Lower() - Reduces the frame's frame level below all other frames in its strata.

Frame:Raise() - Increases the frame's frame level above all other frames in its strata.

Frame:RegisterAllEvents() - Flags the frame to receive all events.

Frame:RegisterEvent(eventName) : registered - Registers the frame to an event.

Frame:RegisterForDrag([button1, ...]) - Registers the frame for dragging with a mouse button.

Frame:RegisterUnitEvent(eventName [, unit1, ...]) : registered - Registers the frame for a specific event, triggering only for the specified units.

Frame:RotateTextures(radians [, x, y])

Frame:SetAlpha(alpha) -> Region:SetAlpha

Frame:SetAttribute(attributeName, value) - Sets an attribute on the frame.

Frame:SetAttributeNoHandler(attributeName, value) - Sets an attribute on the frame without triggering the OnAttributeChanged script handler.

Frame:SetClampRectInsets(left, right, top, bottom) - Controls how much of the frame may be moved off-screen.

Frame:SetClampedToScreen(clampedToScreen) - Prevents the frame from moving off-screen.

Frame:SetClipsChildren(clipsChildren)

Frame:SetDontSavePosition(dontSave)

Frame:SetDrawLayerEnabled(layer [, isEnabled])

Frame:SetFixedFrameLevel(isFixed)

Frame:SetFixedFrameStrata(isFixed)

Frame:SetFlattensRenderLayers(flatten) - Controls whether all subregions are composited into a single render layer.

Frame:SetFrameLevel(frameLevel) - Sets the level at which the frame is layered relative to others in its strata.

Frame:SetFrameStrata(strata) - Sets the layering strata of the frame.

Frame:SetHitRectInsets(left, right, top, bottom) #secureframe - Returns the insets of the frame's hit rectangle.

Frame:SetHyperlinksEnabled([enabled]) - Allows mouse interaction with hyperlinks on the frame.

Frame:SetID(id) - Returns the frame's numeric identifier.

Frame:SetIgnoreParentAlpha(ignore) -> Region:SetIgnoreParentAlpha

Frame:SetIgnoreParentScale(ignore) -> Region:SetIgnoreParentScale

Frame:SetIsFrameBuffer(isFrameBuffer) - Controls whether or not a frame is rendered to its own framebuffer prior to being composited atop the UI.

Frame:SetMovable(movable) - Sets whether the frame can be moved.

Frame:SetPropagateKeyboardInput(propagate) #nocombat - Sets whether keyboard input is consumed by this frame or propagates to further frames.

Frame:SetResizable(resizable) - Sets whether the frame can be resized by the user.

Frame:SetResizeBounds(minWidth, minHeight [, maxWidth, maxHeight]) - Sets the minimum and maximum size of the frame for user resizing.

Frame:SetScale(scale) -> Region:SetScale

Frame:SetShown([shown]) -> ScriptRegion:SetShown

Frame:SetToplevel(topLevel) #secureframe - Controls whether or not a frame should raise its frame level on mouse interaction.

Frame:SetUserPlaced(userPlaced) - Sets whether a frame has been moved by the user and will be saved in the layout cache.

Frame:Show() -> ScriptRegion:Show

Frame:StartMoving([alwaysStartFromMouse]) - Begins repositioning the frame via mouse movement.

Frame:StartSizing([resizePoint, alwaysStartFromMouse]) - Begins resizing the frame via mouse movement.

Frame:StopMovingOrSizing() - Stops moving or resizing the frame.

Frame:UnregisterAllEvents() - Unregisters all events from the frame.

Frame:UnregisterEvent(eventName) : registered - Unregisters an event from the frame.

OnAttributeChanged(self, key, value) - Invoked when a secure frame attribute is changed.

OnChar(self, text) - Invoked for each text character typed in the frame.

OnDisable(self) - Invoked when the frame is disabled.

OnDragStart(self, button) - Invoked when the mouse is dragged starting in the frame

OnDragStop(self) - Invoked when the mouse button is released after a drag started in the frame,

OnEnable(self) - Invoked when the frame is enabled.

OnEvent(self, event, ...) - Invoked whenever an event fires for which the frame is registered.

OnGamePadButtonDown(self, button) - Invoked when a gamepad button is pressed.

OnGamePadButtonUp(self, button) - Invoked when a gamepad button is released.

OnGamePadStick(self, stick, x, y, len) - Invoked when a gamepad stick is moved.

OnHyperlinkClick(self, link, text, button, region, left, bottom, width, height) - Invoked when the mouse clicks a hyperlink on the FontInstance object.

OnHyperlinkEnter(self, link, text, region, left, bottom, width, height) - Invoked when the mouse moves over a hyperlink on the FontInstance object.

OnHyperlinkLeave(self) - Invoked when the mouse moves away from a hyperlink on the FontInstance object.

OnKeyDown(self, key) - Invoked when a keyboard key is pressed if the frame is keyboard enabled.

OnKeyUp(self, key) - Invoked when a keyboard key is released if the frame is keyboard enabled.

OnReceiveDrag(self) - Invoked when the mouse button is released after dragging into the frame.

OnSizeChanged(self, width, height) - Invoked when a frame's size changes.

Browser

OnButtonUpdate(self, action)

OnEditFocusGained(self)

OnEditFocusLost(self)

OnError(self, msg)

OnEscapePressed(self)

OnExternalLink(self, url)

Button

Button:ClearDisabledTexture()

Button:ClearHighlightTexture()

Button:ClearNormalTexture()

Button:ClearPushedTexture()

Button:Click([button, isDown]) - Performs a virtual mouse click on the button.

Button:Disable()

Button:Enable()

Button:GetButtonState() : buttonState

Button:GetDisabledFontObject() : font

Button:GetDisabledTexture() : texture

Button:GetFontString() : fontString

Button:GetHighlightFontObject() : font

Button:GetHighlightTexture() : texture - Returns the highlight texture for the button.

Button:GetMotionScriptsWhileDisabled() : motionScriptsWhileDisabled

Button:GetNormalFontObject() : font - Returns the font object for the button's normal state.

Button:GetNormalTexture() : texture

Button:GetPushedTextOffset() : offsetX, offsetY

Button:GetPushedTexture() : texture

Button:GetText() : text - Returns the text on the button.

Button:GetTextHeight() : height

Button:GetTextWidth() : width

Button:IsEnabled() : isEnabled - Returns true if the button is enabled.

Button:LockHighlight()

Button:RegisterForClicks([button1, ...]) - Registers the button widget to receive mouse clicks.

Button:RegisterForMouse(unpackedPrimitiveType, ...)

Button:SetButtonState(buttonState [, lock])

Button:SetDisabledAtlas(atlas)

Button:SetDisabledFontObject(font)

Button:SetDisabledTexture(asset)

Button:SetEnabled([enabled])

Button:SetFontString(fontString)

Button:SetFormattedText(text)

Button:SetHighlightAtlas(atlas [, blendMode])

Button:SetHighlightFontObject(font)

Button:SetHighlightLocked(locked)

Button:SetHighlightTexture(asset [, blendMode])

Button:SetMotionScriptsWhileDisabled(motionScriptsWhileDisabled)

Button:SetNormalAtlas(atlas)

Button:SetNormalFontObject(font) - Sets the font object used for the button's normal state.

Button:SetNormalTexture(asset) - Sets the normal texture for a button.

Button:SetPushedAtlas(atlas)

Button:SetPushedTextOffset(offsetX, offsetY)

Button:SetPushedTexture(asset)

Button:SetText([text]) - Sets the text of the button.

Button:UnlockHighlight()

OnClick(self, self, button, down) - Invoked when clicking a button.

OnDoubleClick(self, self, button) - Invoked when double-clicking a button.

PostClick(self, button, down) - Invoked immediately after `OnClick`.

PreClick(self, button, down) - Invoked immediately before `OnClick`.

Checkout

OnButtonUpdate(self, action)

OnEditFocusGained(self)

OnEditFocusLost(self)

OnError(self, msg)

OnEscapePressed(self)

OnExternalLink(self, url)

OnRequestNewSize(self, width, height)

ColorSelect

OnColorSelect(self, r, g, b) - Run when the color select frame's color selection changes.

Cooldown

[Edit Cooldown]

Cooldown (inherits from Frame) displays "clock-like" sweep and leading-edge effects over abilities and buffs.

OnCooldownDone(self) - Run when a cooldown has finished.

EditBox

OnArrowPressed(self, key)

OnCharComposition(self, text) - Run when the edit box's input composition mode changes.

OnCursorChanged(self, x, y, w, h) - Run when the position of the text insertion cursor in the edit box changes.

OnEditFocusGained(self) - Run when the edit box becomes focused for keyboard input.

OnEditFocusLost(self) - Run when the edit box loses keyboard input focus.

OnEnterPressed(self) - Run when the Enter (or Return) key is pressed while the edit box has keyboard focus.

OnEscapePressed(self) - Run when the Escape key is pressed while the edit box has keyboard focus.

OnInputLanguageChanged(self, language) - Run when the edit box's language input mode changes.

OnSpacePressed(self) - Run when the space bar is pressed while the edit box has keyboard focus.

OnTabPressed(self) - Run when the Tab key is pressed while the edit box has keyboard focus.

OnTextChanged(self, userInput) - Run when the edit box's text is changed.

OnTextSet(self) - Run when the edit box's text is set programmatically.

FogOfWarFrame

OnUiMapChanged(self, uiMapID)

GameTooltip

OnTooltipAddMoney(self, cost, maxcost) - Run when an amount of money should be added to the tooltip.

OnTooltipCleared(self) - Run when the tooltip is hidden or its content is cleared.

OnTooltipSetAchievement(self) - Run when the tooltip is filled with information about an achievement.

OnTooltipSetDefaultAnchor(self) - Run when the tooltip is repositioned to its default anchor location.

OnTooltipSetEquipmentSet(self) - Run when the tooltip is filled with information about an equipment set.

OnTooltipSetFramestack(self, highlightFrame) - Run when the tooltip is filled with a list of frames under the mouse cursor.

OnTooltipSetItem(self) - Run when the tooltip is filled with information about an item.

OnTooltipSetQuest(self) - Run when the tooltip is filled with information about a quest.

OnTooltipSetSpell(self) - Run when the tooltip is filled with information about a spell.

OnTooltipSetUnit(self) - Run when the tooltip is filled with information about a unit.

Model

PlayerModel / TabardModel inherit the handlers from Model.

OnAnimFinished(self) - Run when the model's animation finishes.

OnAnimStarted(self)

OnModelLoaded(self)

CinematicModel

OnPanFinished

DressUpModel

OnDressModel(self)

MovieFrame

OnMovieFinished(self) - Run when a movie frame's movie ends.

OnMovieHideSubtitle(self) - Runs when the movie's most recently displayed subtitle should be hidden.

OnMovieShowSubtitle(self, text) - Runs when a subtitle for the playing movie should be displayed.

ScrollFrame

OnHorizontalScroll(self, offset) - Run when the scroll frame's horizontal scroll position changes.

OnScrollRangeChanged(self, xrange, yrange) - Run when the scroll frame's scroll position is changed.

OnVerticalScroll(self, offset) - Run when the scroll frame's vertical scroll position changes.

Slider

OnMinMaxChanged(self, min, max) - Run when the slider's or status bar's minimum and maximum values change.

OnValueChanged(self, value, userInput) - Run when the slider's or status bar's value changes.

StatusBar

OnMinMaxChanged(self, min, max) - Run when the slider's or status bar's minimum and maximum values change.

OnValueChanged(self, value) - Run when the slider's or status bar's value changes.

ModelSceneActor

Scripts for this widget can only be set from XML.

OnAnimFinished(self)

OnModelLoaded(self)

OnModelLoading

References

• James Whitehead II 2010-02-05. World of Warcraft Programming: A Guide and Reference for Creating WoW Addons - 2nd Edition.
• wowprogramming 2017-09-03. Widget script handlers listing.
• Townlong Yak 2017-06-27. WidgetAPI.lua.
• Resike 2019-05-21. WidgetReference.lua.