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.
- 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
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.
- text (string) - The text displayed on the button. (partially overrides ButtonText if any)
- registerForClicks (string)
- motionScriptsWhileDisabled (bool) - Default is 'false'.
<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.
So... WTH...? you may be asking. Heres what's going on. Setting the optional 'ButtonText' is effectively defining a default base FontString for the Button, 'similar' to inheriting. For example, if both Button 'text' and ButtonText 'text' are set, then Button 'text' will override ButtonText 'text'. Likewise, setting a 'XxxxFont' element is effectivly defining a default set of attrs for ButtonText when the button is in a particular state, 'similar' to ButtonText inheriting a Font. 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.
- If ButtonText is set, and Button 'text' is set to "", Button 'text' will not override ButtonText 'text', and be teated as if Button 'text' not exist; which is unfortunate....
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.
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.
<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>