Button

The button element automates generic button functionality, such as swapping texture and font colors automatically according to mouse over and state.

Summary

Button	The button element automates generic button functionality, such as swapping texture and font colors automatically according to mouse over and state.
Implementation Details	A button is composed of 5 levels of components.
XML Definition	This is the button xml definition.
XML Tag
Optional Attributes	These are optional.
mirrorTexCoords	Allows you to display a horizontal mirror image of the button textures.
backgroundtexture	Name of the UI Texture to use for the background image layer.
highlighttexture	Name of the UI Texture to use for the highlight image layer.
overlaytexture	Name of the UI Texture to use for the overlay image layer.
overlayhighlighttexture	Name of the UI Texture to use for the overlay highlight image layer.
font	The name of the Font definition to use.
textalign	The text alignment.
linespacing	An override value for the font line spacing.
autoresize	Should the height of the button be automatically resized according to it’s text?
autoresizewidth	Should the width be shrunk automatically to fit it’s text?
textAutoFitMinScale	If the text min scale value is set to something other than 1.0, the Label Button automatically drop the point size of the font on a non-re sizable Button until the text fits within the Button’s text dimensions, up to the min font scale.
texturescale	The scale of the texture to be used for the button artwork.
drawchildrenfirst	This flag allow you to specify the draw order for the button.
warnOnTextCropped	Should this Button log warning messages if the text is cut off?
drawHighlightOverBackground	When drawing this button, should the highlight state be drawn over-top the background image?
Elements
TextOffset	The offset for the text within the button dimensions.
OverlayOffset (DOES NOT WORK)	The offset for the overlay and overlayhighlight images.
TextColors	The text colors for each button state.
TexCoords	The texture coordinates for each button state.
TexSlices	Slice of the associated Ui Texture to display.
OverlayTexCoords	The texture coordinates for each button state.
AnimatedImages	The names of AnimatedImage windows to be used as top-level overlays for the various button states.
ResizeImages	The names of resize images to be used for the various button states.
Constants
Constants
Button States
Functions
Functions
ButtonSetText()	Sets the text displayed on the button
ButtonGetText()	Returns the text currently displayed on the button.
ButtonSetPressedFlag()	Sets if button should display it’s ‘pressed’ state.
ButtonGetPressedFlag()	Returns if button is currently pressed.
ButtonSetHighlightFlag()	Sets if button should be highlighted.
ButtonGetHighlightFlag()	Sets if button should be highlighted.
ButtonSetDisabledFlag()	Sets if button is disabled.
ButtonGetDisabledFlag()	Returns if the button is currently set to disabled.
ButtonSetStayDownFlag()	Sets if button if the button should remained pressed when the user release the left mouse button.
ButtonGetStayDownFlag()	Returns if a button is currently set to ‘stay down’ when pressed.
ButtonSetCheckButtonFlag()	Sets if the button should behave like a check button.
ButtonGetCheckButtonFlag()	Returns if the button is currently behaving like a check button.
ButtonStartFlash()	Starts a scriped flash animation with the highlighted image.
ButtonStopFlash()	Stops an active flash animation.
ButtonSetTexture()	Sets the texture used for a particular button state.
ButtonSetTextColor()	Sets the text color used for a particular button state.
ButtonGetTextDimensions()	Returns the the current text dimensions.

Implementation Details

Components

A button is composed of 5 levels of components. A particular button may contain any subset of the available components. In order, top to bottom, these are:

The text.
The overlay highlight image.
The overlay image.
The background highlight image.
The background image.

Background

The background layer texture component that is visible at all times. This texture may in one of four states

Disabled (Typically a grayed out version of the Normal artwork )
Normal (The standard image for when the button is usable.
Pressed (The mouse is currently over the button or ButtonSetStayDownFlag() is set.)
DisabledPressed (Typically a grayed out version of the Pressed artwork )

Background Highlight

When the mouse is over the button, the highlight layer will be drawn on top of the background layer. Depending on the current pressed state, one of the following will be shown

NormalHighlight (The standard mouse over image)
PressedHighlight (The pressed state mouse over image)

This laying method allows you to create pressed highlight images that are either complete button artwork, or ‘glow’ effects that expose the background layer behind it.

Overlay

The overlay and overlay highlight, if defined, behaves the same as the background and background highlight.

Text

The text is always drawn last (that is, on top of everything else), with it’s color corresponding to the current button state.

XML Definition

This is the button xml definition.

Summary

XML Tag
Optional Attributes	These are optional.
mirrorTexCoords	Allows you to display a horizontal mirror image of the button textures.
backgroundtexture	Name of the UI Texture to use for the background image layer.
highlighttexture	Name of the UI Texture to use for the highlight image layer.
overlaytexture	Name of the UI Texture to use for the overlay image layer.
overlayhighlighttexture	Name of the UI Texture to use for the overlay highlight image layer.
font	The name of the Font definition to use.
textalign	The text alignment.
linespacing	An override value for the font line spacing.
autoresize	Should the height of the button be automatically resized according to it’s text?
autoresizewidth	Should the width be shrunk automatically to fit it’s text?
textAutoFitMinScale	If the text min scale value is set to something other than 1.0, the Label Button automatically drop the point size of the font on a non-re sizable Button until the text fits within the Button’s text dimensions, up to the min font scale.
texturescale	The scale of the texture to be used for the button artwork.
drawchildrenfirst	This flag allow you to specify the draw order for the button.
warnOnTextCropped	Should this Button log warning messages if the text is cut off?
drawHighlightOverBackground	When drawing this button, should the highlight state be drawn over-top the background image?
Elements
TextOffset	The offset for the text within the button dimensions.
OverlayOffset (DOES NOT WORK)	The offset for the overlay and overlayhighlight images.
TextColors	The text colors for each button state.
TexCoords	The texture coordinates for each button state.
TexSlices	Slice of the associated Ui Texture to display.
OverlayTexCoords	The texture coordinates for each button state.
AnimatedImages	The names of AnimatedImage windows to be used as top-level overlays for the various button states.
ResizeImages	The names of resize images to be used for the various button states.

XML Tag

<Button>
....
</Button>

Optional Attributes

These are optional. You can use whichever apply to the button you are creating.

mirrorTexCoords

Allows you to display a horizontal mirror image of the button textures. This swaps the topleft and bottom left coordinates with those used for the topright and bottomright of the button.

Expects

A boolean value.

”true”	Mirror the texture coordinates
”false”	Use normal texture coordinates

Default Value

”false”

backgroundtexture

Name of the UI Texture to use for the background image layer.

Expects

A string value, which is the name of a valid UI texture.

Default Value

””

highlighttexture

Name of the UI Texture to use for the highlight image layer.

Expects

A string value, which is the name of a valid Texture

Default Value

””

overlaytexture

Name of the UI Texture to use for the overlay image layer.

Expects

A string value, which is the name of a valid UI texture.

Default Value

””

overlayhighlighttexture

Name of the UI Texture to use for the overlay highlight image layer.

Expects

A string value, which is the name of a valid Texture

Default Value

””

font

The name of the Font definition to use. This is required if you wish to display text on the button.

Expects

A string value of a valid Font.

textalign

The text alignment.

Expects

A string value, which is one of the following:

”left”	Aligned to the left.
”top”	Centered horizontally.
”center”	Centered horizontally (and vertically when autoresize is false).
”right”	Aligned to the right.
”leftcenter”	Aligned to the left and centered vertically.
”rightcenter”	Aligned to the right and centered vertically.
”bottom”	Aligned to the bottom and centered horizontally
”bottomleft”	Aligned to the bottom and left.
”bottomright”	Aligned to the bottom and right.

Default Value

”left”

linespacing

An override value for the font line spacing.

Expects

A number. If 0, the font height is used.

Default Value

autoresize

Should the height of the button be automatically resized according to it’s text?

Expects

The word “true” or “false”

true: Yes, size the button to fit it’s text.
false: No, cut off the button text if it reaches the max height.

Default Value

”false”

Notes

Auto-resize should be used with text-only, horizontal resize, or full resize buttons.

autoresizewidth

Should the width be shrunk automatically to fit it’s text?

Expects

The word “true” or “false”

true: Yes, reduce the width of the button to fit it’s text.
false: No, never reduce the width of the button.

Default Value

”false”

Notes

When auto-resizing the width of a button, the button will only size up to it’s specified dimensions. This attribute only reduces the size when the full width is not needed.

textAutoFitMinScale

If the text min scale value is set to something other than 1.0, the Label Button automatically drop the point size of the font on a non-re sizable Button until the text fits within the Button’s text dimensions, up to the min font scale.

Expects

A number value. (1.0 = 100% and no auto-scaling)

Default Value

texturescale

The scale of the texture to be used for the button artwork. This is multiplied by the button’s <Size> to determine the texture dimensions.

Expects

A number value. (1.0 = 100%)

Default Value

Notes

You can specify either a texture scale or override it with a <TexDimensions> element.

drawchildrenfirst

This flag allow you to specify the draw order for the button. You can elect to place child windows below or above the text/highlight button components.

Expects

A boolean value.

”true”	Draw any children before drawing highlight and text.
”false”	Draw any children after drawing highlight and text.

Default Value

”false”

Notes

none

warnOnTextCropped

Should this Button log warning messages if the text is cut off?

Expects

true: Yes, log error messages when the text is cut off.
false: No, do not log error messages when the text is cut off.

Default Value

true

drawHighlightOverBackground

When drawing this button, should the highlight state be drawn over-top the background image?

Expects

true: Yes, the background image should always be drawn behind the highlight image.
false: No, don’t draw the background image when drawing the highlight images.

Default Value

true

Elements

TextOffset

The offset for the text within the button dimensions. This allows you restrict the button text to only the center portion.

Syntax

<TextOffset x="5" y="10" />

x	The x-pixel offset from the top left corner.
y	The y-pixel offset from the top left corner.

Defaults

x	0
y	0

Notes

The offset is The distance subtracted from both the top/bottom and left/right edges of the button.

OverlayOffset (DOES NOT WORK)

The offset for the overlay and overlayhighlight images. This allows you use overlays that are smaller or larger than the background images.

Syntax

<OverlayOffset x="5" y="10" />

x	The x-pixel offset from the top left corner.
y	The y-pixel offset from the top left corner.

Defaults

x	0
y	0

Notes

The offset is The distance subtracted from both the top/bottom and left/right edges of the button.

TextColors

The text colors for each button state.

Syntax

<TextColors>
      <Normal             r="255" g="204" b="102" />
      <NormalHighlit      r="255" g="85" b="0" />
      <Pressed            r="255" g="85" b="0" />
      <PressedHighlit     r="255" g="85" b="0"/>
      <Disabled           r="92" g="92" b="92" />
      <DisabledPressed    r="92" g="92" b="92" />
</TextColors>

r	The red color value
g	The green color value
b	The blue color value

Defaults

For all button states.

r	255
g	255
b	255

Notes

You can include only the button states that you care about. Any unspecified states will default to white.

TexCoords

The texture coordinates for each button state. The texture field is optional if you have set the backgroundtexture and highlighttexture attributes.

Syntax

<TexCoords>
      <Normal          texture="" x="474" y="6" />
      <NormalHighlit   texture="" x="474" y="45" />
      <Pressed         texture="" x="474" y="45" />
      <PressedHighlit  texture="" x="474" y="45" />
      <Disabled        texture="" x="474" y="6" />
      <DisabledPressed texture="" x="474" y="6" />
</TexCoords>

texture	The name of the UI Texture to use for this button state.
x	The x texture coordinate.
y	The y texture coordinate.

Defaults

For all button states.

texture	””
x	0
y	0

TexSlices

Slice of the associated Ui Texture to display. The texture field is optional if you have set the backgroundtexture and highlighttexture attributes.

Syntax

<TexSlices>
      <Normal          texture="" id="Bag-Button"  />
      <NormalHighlit   texture="" id="Bag-Button-Highlighted"   />
      <Pressed         texture="" id="Bag-Button-Selected"   />
      <PressedHighlit  texture="" id="Bag-Button-Highlighted"   />
      <Disabled        texture="" id="Bag-Button"   />
      <DisabledPressed texture="" id="Bag-Button"   />
</TexSlices>

texture	The name of the UI Texture to use for this button state.
id	The id of the slice of the associated Ui Texture to display.

Defaults

For all button states.

texture	””
id	””

OverlayTexCoords

The texture coordinates for each button state. The texture field is optional if you have set the overlaytexture and overlayhighlighttexture attributes.

Syntax

<OverlayTexCoords>
      <Normal          texture="" x="474" y="6" />
      <NormalHighlit   texture="" x="474" y="45" />
      <Pressed         texture="" x="474" y="45" />
      <PressedHighlit  texture="" x="474" y="45" />
      <Disabled        texture="" x="474" y="6" />
      <DisabledPressed texture="" x="474" y="6" />
</OverlayTexCoords>

texture	The name of the UI Texture to use for this button state.
x	The x texture coordinate.
y	The y texture coordinate.

Defaults

For all button states.

texture	””
x	0
y	0

AnimatedImages

The names of AnimatedImage windows to be used as top-level overlays for the various button states.

Syntax

<AnimatedImages>
      <Normal          def="DefaultAnimatedImageNormal"  />
      <NormalHighlit   def="DefaultAnimatedImageNormalHightlite" />
      <Pressed         def="DefaultAnimatedImagePressed" />
      <PressedHighlit  def="DefaultAnimatedImagePressedHightlite"  />
      <Disabled        def=""  />
      <DisabledPressed def=""  />
</AnimatedImages>

def	The name of the AnimatedImage to use for this button state.

Defaults

For all button states.

def

””

ResizeImages

The names of resize images to be used for the various button states. This allows you to create buttons based on any of the resizable window types.

Syntax

<ResizeImages>
      <Normal          def="DefaultHorizResizeButtonNormal"  />
      <NormalHighlit   def="DefaultHorizResizeButtonHightlite" />
      <Pressed         def="DefaultHorizResizeButtonPressed" />
      <PressedHighlit  def="DefaultHorizResizeButtonPressedHightlite"  />
      <Disabled        def="DefaultHorizResizeButtonDisabled"  />
      <DisabledPressed def="DefaultHorizResizeButtonDisabled"  />
</ResizeImages>

def	The name of the resize image to use for this button state.

Defaults

For all button states.

def

””

Constants

Summary

Constants
Button States

Constants

Button States

Button.ButtonState.NORMAL	Normal button state.
Button.ButtonState.HIGHLIGHTED	Normal highlighted button state.
Button.ButtonState.PRESSED	Pressed button state.
Button.ButtonState.PRESSED_HIGHLIGHTED	Pressed highlighted button state.
Button.ButtonState.DISABLED	Disabled button state.
Button.ButtonState.DISABLED_PRESSED	Disabled pressed button state.

Functions

Summary

Functions
ButtonSetText()	Sets the text displayed on the button
ButtonGetText()	Returns the text currently displayed on the button.
ButtonSetPressedFlag()	Sets if button should display it’s ‘pressed’ state.
ButtonGetPressedFlag()	Returns if button is currently pressed.
ButtonSetHighlightFlag()	Sets if button should be highlighted.
ButtonGetHighlightFlag()	Sets if button should be highlighted.
ButtonSetDisabledFlag()	Sets if button is disabled.
ButtonGetDisabledFlag()	Returns if the button is currently set to disabled.
ButtonSetStayDownFlag()	Sets if button if the button should remained pressed when the user release the left mouse button.
ButtonGetStayDownFlag()	Returns if a button is currently set to ‘stay down’ when pressed.
ButtonSetCheckButtonFlag()	Sets if the button should behave like a check button.
ButtonGetCheckButtonFlag()	Returns if the button is currently behaving like a check button.
ButtonStartFlash()	Starts a scriped flash animation with the highlighted image.
ButtonStopFlash()	Stops an active flash animation.
ButtonSetTexture()	Sets the texture used for a particular button state.
ButtonSetTextColor()	Sets the text color used for a particular button state.
ButtonGetTextDimensions()	Returns the the current text dimensions.

Functions

ButtonSetText()

Sets the text displayed on the button

Parameters

buttonName	(string) The name of the button.
text	(wstring) The text string.

Returns

nil	no return value

Notes

none

Example

ButtonSetText("InteractionWindowQuestAccept", GetString( StringTables.Default.LABEL_ACCEPT ))

ButtonGetText()

Returns the text currently displayed on the button.

Parameters

buttonName

(string) The name of the button.

Returns

text	(wstring) The text string.

Notes

none

Example

local currText = ButtonGetText( name )

ButtonSetPressedFlag()

Sets if button should display it’s ‘pressed’ state.

Parameters

buttonName	(string) The name of the button.
isPressed	(boolean) Should the pressed state be set?

Returns

nil	no return value

Notes

If you are manually setting the pressed state in code, you need to set the ButtonSetStayDownFlag() so that the pressed state will continue to remain visiable.

Example

ButtonSetPressedFlag( "SettingsResolutionUseFullscreenButton", SystemData.Settings.Resolution.useFullScreen )

ButtonGetPressedFlag()

Returns if button is currently pressed.

Parameters

buttonName

(string) The name of the button.

Returns

isPressed

(boolean)Is the button currently pressed?

Notes

none

Example

SystemData.Settings.Resolution.useFullScreen = ButtonGetPressedFlag( "SettingsResolutionUseFullscreenButton" )

ButtonSetHighlightFlag()

Sets if button should be highlighted.

Parameters

buttonName	(string) The name of the button.
isHighlighted	(boolean) Should the highlighted state be set?

Returns

nil	no return value

Notes

Normal button processing will turn on/off the highlight based on the mouse position. If you wish to manually modify the highlight in code, make sure that you hand the <OnMouseOver()> and <OnMouseOverEnd()> on this window or one of it’s parents.

Example

ButtonSetHighlightFlag( "SomeButton", true )

ButtonGetHighlightFlag()

Sets if button should be highlighted.

Parameters

buttonName

(string) The name of the button.

Returns

isHighlighted

(boolean) Is the button currently highlighted?

Notes

none

Example

local isHighlighted = ButtonGetHighlightFlag( "SomeButton" )

ButtonSetDisabledFlag()

Sets if button is disabled. When disabled, the button will display it’s ‘disabled’ artwork and never highlight images.

Parameters

buttonName	(string) The name of the button.
isDisabled.	(boolean) Should the button be disabled?

Returns

nil	no return value

Notes

Setting a button to disabled will only update it’s artwork. Mouse events will continue to be proccess when you click on the button (as they would on any other window). A good way to handle this to to just call ButtonGetDisabledFlag() at the top of your mouse event handler. If the button is disabled, just return.

Example

ButtonSetDisabledFlag("GroupMenuWindowGroupKickButton", GameData.Player.isGroupLeader == false )

ButtonGetDisabledFlag()

Returns if the button is currently set to disabled.

Parameters

buttonName

(string) The name of the button.

Returns

isDisabled.

(boolean) Is the button currently disabled?

Notes

none

Example

local isDisabled = ButtonSetDisabledFlag("GroupMenuWindowGroupKickButton" )

ButtonSetStayDownFlag()

Sets if button if the button should remained pressed when the user release the left mouse button.

Parameters

buttonName	(string) The name of the button.
stayDown	(boolean) Should the button stay down when pressed?

Returns

nil	no return value

Notes

This setting is very useful when used in conjunction with the ButtonSetPressedFlag() function. This allows you to use the generic button as a tab, a radio button, or to show generic ‘state’ information.

Example

ButtonSetStayDownFlag( ChatWindow.Tabs[index].tabButton, true )

ButtonGetStayDownFlag()

Returns if a button is currently set to ‘stay down’ when pressed.

Parameters

buttonName

(string) The name of the button.

Returns

stayDown

(boolean) Does the button stay down when pressed?

Notes

none

Example

local stayDown = ButtonGetStayDownFlag( "SomeWindow" )

ButtonSetCheckButtonFlag()

Sets if the button should behave like a check button. When set, the button will toggle between pressed and unpressed with each click.

Parameters

buttonName	(string) The name of the button.
isCheckButton	(boolean) Should the button behave like a check button?

Returns

nil	no return value

Notes

To create a check button, register a callback for the <OnLButtonUp> event and call ButtonGetPressedFlag() to determine if the button is currently checked.

Example

ButtonSetCheckButtonFlag( "SettingsResolutionUseFullscreenButton", true )

ButtonGetCheckButtonFlag()

Returns if the button is currently behaving like a check button.

Parameters

buttonName

(string) The name of the button.

Returns

isCheckButton

(boolean) Is the button behaving like a check button?

Notes

none

Example

local isCheckButton = ButtonGetCheckButtonFlag( "SettingsResolutionUseFullscreenButton" )

ButtonStartFlash()

Starts a scriped flash animation with the highlighted image.

Parameters

buttonName	(string) The name of the button.
flashDuration	(string) The duration to flash the button (in seconds).
flashFrequency	(string) How frequently the flash should occur (in seconds).

Returns

nil	no return value

Notes

none

Example

ButtonStartFlash("SomeButton", 10, 0.5);

ButtonStopFlash()

Stops an active flash animation.

Parameters

buttonName

(string) The name of the button.

Returns

nil	no return value

Notes

none

Example

ButtonStopFlash("SomeButton")

ButtonSetTexture()

Sets the texture used for a particular button state.

Parameters

buttonName	(string) The name of the button.
buttonState	(number) The button state to set, see <Button State> for valid values.
textureName	(string) The name of the ui Texture to use.
x	(number) The x coordinate within the texture.
y	(number) The y coordinate within the texture.

Returns

nil	no return value

Notes

none

Example

ButtonSetTexture("SomeButton", Button.ButtonState.NORMAL, "texture_name", 156, 40);

ButtonSetTextColor()

Sets the text color used for a particular button state.

Parameters

buttonName	(string) The name of the button.
buttonState	(number) The button state to set, see <Button State> for valid values.
r	(number) The red value for the text color.
g	(number) The green value for the text color.
b	(number) The blue value for the text color.

Returns

nil	no return value

Notes

none

Example

ButtonSetTextColor("SomeButton", Button.ButtonState.NORMAL, 255, 0, 255);

ButtonGetTextDimensions()

Returns the the current text dimensions.

Parameters

buttonName

(string) The name of the button.

Returns

x	(number) The width of the current text
y	(number) The height of the current text

Notes

This call is very usefully for manually resizing window to fit their data.

Example

local x, y = ButtonGetTextDimensions("SomeWindow")