UIOBJECT Button

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

Button (inherits from Frame)

Of all the various subtypes of Frame in the user interface system, Buttons are the most visible, since users interact with them frequently during game play. They are the primary means by which the user controls the game and their characters.

Buttons have an intrinsic FontString built-in, so they support both the SetText and the GetText methods. In addition, a button has three special visual states that can be decorated independently: one when the button is disabled, one when the button has been pushed but not yet released, and one when the mouse is over the button. The changes to the button's presentation happen automatically based on the button's definition.

The most important aspect of a Button is the fact that it can be clicked by the user. When a button is clicked the PreClick script handler will fire, followed by the OnClick handler, and finally the PostClick handler. These allow an addon developer lots of flexibility when creating an addon, especially in the presence of the secure environment and tainting system introduced in WoW 2.0.

To create a button, call CreateFrame with "Button" as the first argument, or construct one in an XML file with a <Button> element. Some handy templates for this include UIPanelButtonTemplate (which provides a standard red button), UIPanelCloseButton (a small red square with a yellow X in it) and SecureHandlerClickTemplate.

The most famous Buttons are probably unit frames, which make use of the SecureActionButtonTemplate (or its derivative, SecureUnitButtonTemplate) to control targeting and sometimes spell-casting. There are many insecure buttons as well (or more accurately, buttons which do not require security), such as the micro buttons on the action bar for opening various panels and menus, or the buttons around the minimap for revealing the calendar or displaying the world map.

Defined Methods

Button:Click() - Execute the click action of the button.

Button:Disable() - Disable the Button so that it cannot be clicked.

Button:Enable() - Enable to the Button so that it may be clicked.

Button:GetButtonState() - Return the current state ("PUSHED","NORMAL") of the Button.

Button:GetDisabledFontObject() - Return the font object for the Button when disabled - New in 1.10.

Button:GetDisabledTexture() - Get the texture for this button when disabled - New in 1.11.

Button:GetFontString() - Get this button's label FontString - New in 1.11.

Button:GetHighlightFontObject() - Return the font object for the Button when highlighted - New in 1.10.

Button:GetHighlightTexture() - Get the texture for this button when highlighted.

Button:GetMotionScriptsWhileDisabled() - Get whether the button is allowed to run its OnEnter and OnLeave scripts even while disabled - New in 3.3.

Button:GetNormalFontObject() - Get the Font Object of the button.

Button:GetNormalTexture() - Get the normal texture for this button - New in 1.11.

Button:GetPushedTextOffset() - Get the text offset when this button is pushed (x, y) - New in 1.11.

Button:GetPushedTexture() - Get the texture for this button when pushed - New in 1.11.

Button:GetText() - Get the text label for the Button.

Button:GetTextHeight() - Get the height of the Button's text.

Button:GetTextWidth() - Get the width of the Button's text.

Button:IsEnabled() - Determine whether the Button is enabled.

Button:LockHighlight() - Set the Button to always be drawn highlighted.

Button:RegisterForClicks(clickType1 [, clickType2, ...]) - Specify which mouse button up/down actions cause this button to receive an OnClick notification.

Button:RegisterForMouse()

Button:SetButtonState(state[, lock]) - Set the state of the Button ("PUSHED", "NORMAL") and whether it is locked.

Button:SetDisabledAtlas(atlasName)

Button:SetDisabledFontObject([font]) - Set the font object for settings when disabled - New in 1.10.

Button:SetDisabledTexture(texture or texturePath) - Set the disabled texture for the Button - Updated in 1.10.

Button:SetEnabled(boolean) - Same as Enable() or Disable()

Button:SetFontString(fontString) - Set the button's label FontString - New in 1.11.

Button:SetFormattedText(formatstring[, ...]) - Set the formatted text label for the Button. - New in 2.3.

Button:SetHighlightAtlas(atlasName[, blendmode)

Button:SetHighlightFontObject([font]) - Set the font object for settings when highlighted - New in 1.10.

Button:SetHighlightTexture(texture or texturePath[,alphaMode]) - Set the highlight texture for the Button.

Button:SetMotionScriptsWhileDisabled([bool]) - Set whether button should fire its OnEnter and OnLeave scripts even while disabled - New in 3.3.

Button:SetNormalAtlas(atlasName)

Button:SetNormalFontObject(FontObject) - Set the Font Object of the button.

Button:SetNormalTexture(texture or texturePath) - Set the normal texture for the Button - Updated in 1.10.

Button:SetPushedAtlas(atlasName)

Button:SetPushedTextOffset(x, y) - Set the text offset for this button when pushed - New in 1.11.

Button:SetPushedTexture(texture or texturePath) - Set the pushed texture for the Button - Updated in 1.10.

Button:SetText(text) - Set the text label for the Button.

Button:UnlockHighlight() - Set the Button to not always be drawn highlighted.

Defined Script Handlers

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

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

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

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

See also

• SecureActionButtonTemplate - Allows protected functions
• SecureUnitButtonTemplate - Allows protected functions directed toward a UnitId
• InsecureActionButtonTemplate - Allows protected functions outside combat

External links

• wowprogramming, Jim Whitehead