UIButton is the generic, clickable object one expects to find on any PC game interface. It also acts as a 'restricted' container of sorts, as it can contain specific UI objects within it.

A button is made up of several child objects contained in a single pane. These pieces can be defined explicitly or left up to the engine to define.

The child objects that a UIButton can contain are:

Up to 1 UIText field. If a UIText object is not defined as a child object in the XML, the engine will create one automatically when creating the UIButton.

Up to 11 UIFrames. A UIFrame contained within a button must have a state attribute that only applies when specifically contained within a button. The following arguments are valid for the state attribute:

up

down

disabled

focused

hilited

hifocus

header

hiheader

downheader

base

These states can mean different things depending on the context of the button, so I'll just make some notes about a few of them. 'header', 'hiheader', and 'downheader' are the states for a button that is to be the header of a UICollapsable object, which will be explained further in a later article. 'base' is useful for when using state frames that leave some of the 'base' button visible, such as hotbar button icons.

An unlimited number of UIIcons that will be added to the 'overlay' list for that button. Overlays are extra icons that can be made visible by the engine that stay with the button. At this time, there is no way to manipulate these overlays via script.

UIButton supports the following attributes:

style

This is a 'style' name from the stylesheet.xml file that this button should adopt for its default parameters. At this time there is not support for custom styles.

repeatcallback

If this attribute is set to true, the OnLeftClick callback will get executed every frame as long as the left mouse button is held down on it. On the first update the OnLeftClick will execute on the mousedown. There will then be a 0.5 second pause, then after that the OnLeftClick callback will be executed every frame until the left mouse button is released.

OnSelected

This callback is applicable to radio buttons and toggle boxes. If the button is a toggle box, this callback is executed when the toggle box is activated. If the button is a radio button, this callback is executed when the button becomes the selected radio button.

OnUnselected

This callback is applicable to radio buttons and toggle boxes. If the button is a toggle box, this callback is executed when the toggle box is de-activated. If the button is a radio button, this callback is executed if thi sbutton was the selected radio button, but now another radio button has been selected.

groupid

This is a group number for radio buttons. Group IDs are global for the entire XML file that contains the button. That is to say, there can only be one group of radio buttons with the group id of '1', or '2', etc. All buttons that share the same group id form a 'set' of radio buttons. Only one button in that set can be selected at a time, all the rest are non-selected. Selecting any one button in the set will unselect the previously selected radio button.

groupmemberid

This gives the UI Button a unique within a set of radio buttons. There should only be one button with a specific groupmemberid in a set of buttons. Ideally these IDs should start with 1 and increment from there, but that is not completely necessary.

buttontype

This attribute accepts only 'radio' or 'check' as arguments, defining the button as a radio button or checkbox style button.

color

This attribute accepts color strings. These colors will blend with any other colors found in the textures of the button. So setting this to grey, for example, will make a grey-scale style icon for the button.

disabledcolor

This attribute accepts color strings. This will be the blending color for when the button is put into a disabled state.

disabledtextcolor

This attribute accepts color strings. This color will change the color of any text contained in the button's text field if the button is put into a disabled state.

strref

This is a STRREF that represents the string that should appear in the button.

text

This is hard coded text that should appear in the button. It overrides the strref attribute if it is present.