WoW:XML/Button

Reference e
AddOns WoW API Widget API XML UI Event API WoW Lua Macro API CVars Battle.net HOWTOs Snippets UI tech Categories

→ XML elements

← XML UI ← XML elements < Button

Button is a complex element that allows drawing automatically animated text and textures when clicked, and with special event handling. Is a managed combination of Textures and FontStrings and is placed in a Frames element.

Inheritance

Inherited by: CheckButton, UnitButton, Inherits: Frame, Runtime object: Button

Defined in: Frames, Ui

Elements

• NormalTexture (Texture) - defines texture to use in 'normal' state
• PushedTexture (Texture) - defines texture to use in 'pushed' state
• DisabledTexture (Texture) - defines texture to use in 'disabled' state
• HighlightTexture (Texture) - defines texture to use in 'highlight' state

• ButtonText (FontString) - defines a FontString to be used for the button text (optional if styles are used)

• NormalFont (ButtonStyle) - font style to be used normally
• HighlightFont (ButtonStyle) - font style to be used when highlighted or pushed
• DisabledFont (ButtonStyle) - font style to be used when disabled

• NormalColor (Color) - texture color (or just vertex color) when normal
• HighlightColor (Color) - texture color (or just vertex color) when highlight or pushed
• DisabledColor (Color) - texture color (or just vertex color) when disabled

• PushedTextOffset (Dimension) - positional offset to move the text when pressed

Attributes

• text (string) - The text displayed on the button. (overrides text attribute of ButtonText, if any)
• registerForClicks (string) - registers a button to receive click events through the OnClick event handler. Default is 'LeftButtonUp' only. See also RegisterForClicks for Lua version.
• motionScriptsWhileDisabled (bool) - Default is 'false'.

Removed

• As of 1.11.0 the implementation of Button objects has been changed to use only one FontString and several alternate Font objects for the various styles. NormalText, HighlightText, and DisabledText are deprecated (but still work for now), and have been replaced with ButtonText, NormalFont, HighlightFont, and DisabledFont. See: patch 1.11.0 changes.
• NormalText
• HighlightText
• DisabledText

Summary

Example

 <Frame name="MyFrame">
   <Layers>
     <Layer>
       <Texture>
         <Size x="100" y="100" />
         <Color a="1" r="1" g="1" b="1" />
       </Texture>
     </Layer>
   </Layers>
   <Button inherits="UIPanelButtonTemplate" text="Big Text">
     <Size x="150" y="60"/>
     <Anchors><Anchor point="BOTTOM"/></Anchors>
     <NormalFont style="GameFontNormalHuge"/>
   </Button>
 </Frame>

This example will show a opaque color texture, painted white, and a button where the normal state font have been changed to a large font.

Details

States

Button is one of the most complex and confusing types, and probably the most important from a UI perspective for user interaction. Each button has 'states' where each state depends on mouse interaction in order to give feedback to the user about what it being or going to be clicked on. 'Normal' state is the button at rest and how its normally drawn. 'Highlight' is the state when a user hovers over the button with the mouse. 'Pushed' is the state when the mouse button is held down. And 'Disabled' is the state where a button shows its disabled and cannot be clicked. Settings defined for the 'Normal' state will be used for other states if those states settings aren't set.

Fonts

The font's overall text style is defined by a series of 'overriding' properties. Each state's 'style' can use a different Font or FontString template. And the state's 'Color' if set, overrides the color in the state's style template. Setting 'ButtonText' definies a singular explicit FontString for the Button, which overrides any button state options set in the Button's state properties.

Setting a 'XxxxFont' element is then effectively defining a default set of attributes for ButtonText when the button is in a particular state. For example, if ButtonText is defined and sets a 'FontHeight', it will override a NormalFont 'FontHeight'. If there is no ButtonText, then the values used to fabricate a FontString for display, come purely from 'text' attribute and the 'XxxxFont' elements. This overall 'Button > ButtonText > Switchabe ...Font' arrangement allows a Button to use predefined but flexible text and font constructs, and to automatically switch visual states with no further work.

Text

If both Button 'text' and the Button's ButtonText 'text' are set, then Button 'text' will override text set in ButtonText. Oddly however, if Button 'text' is set to "", Button.text will not override, which can be frustrating. Additionally, the text is automatically offset three unscaled pixels lower than normal, for an aligned FontString. This makes most capitol case button text look centered vertically in such a tight space, effectively ignoring font 'underhang' in centering.

Textures

The various textures, once inherited or set to the art of your choice, will automatically behave as expect. (highlight on mouseover, pushed while clicked, disabled when disabled) The same goes for the different texts.

Inheritance

Basically 'ButtonText' is a FontString which is optional, and which dynamically inherits from a button state 'Font' template, depending on which state the button is in, and... the state color overrides everything else for the font color. An odd quirk is that the ButtonText property can use 'inherits' itself, however this will be ignored if a style is set. Effectively ButtonText will inherit, on the fly, from one of the button state styles if defined, replacing the 'inherits' attribute. For the 'text' attribute, and to reiterate from before, the ButtonText text is overriden by the Button text attribute. For 'texture' each state is independent, and there is no means for inheritance from any other element.

Layers and Render Order

Button's normal Text and Texture are like implicit Layer Frames. Button Text is rendered as a FontString, and the Button texture as a Texture. Both following the same rules as explicit defined layer frames. They rendered before any other explicit layer frames at a particular layer. The Button text 'FontString' is rendered at DrawLayer of 'Overlay'. The Button texure is rendered at the DrawLayer of 'Artwork'. Thus, if you added an explicit Texture to the Artwork layer of a Button, it would get rendered on top of the state texture, but under the button text.

Example

<Button name="$parentButtonClose" inherits="OptionsButtonTemplate" text="Close">
  <Anchors>
    <Anchor point="BOTTOMRIGHT">
      <Offset x="-12" y="16"/>
    </Anchor> 
  </Anchors>
  <Scripts>
    <OnClick> self:GetParent():Hide(); </OnClick>
  </Scripts>
</Button>