DialogControls-Buttons

General

ⓘ

TokenNames common to most controls, such as x, y, w, h, text, idc... are not listed here.

Buttons are one way to add interactivity to your dialogs. Their corresponding type property is CT_BUTTON.

Buttons can have different states (see screenshot) and will render slightly different to give the user a visual feedback on the button's state:

• Enabled: the button has not been disabled, it currently doesn't have any mouse or keyboard related focus
• Disabled: the button has been explicitly disabled. It will not be clickable.
• Enabled + Focused: As enabled; additionally it will have a small border of the color defined in the colorFocused property. This occurs when the button currently has focus (ie. is the default button or has been selected via the Tab key).
• Enabled + Active: As enabled; additionally it will have a different background as specified in the colorBackgroundActive background. This occurs when the mouse is currently hovering over an unfocused button.
• Enabled + Active + Focused: The combined result of the above two states. The mouse is currently hovering over the button in question and it has input focus.

Button can also have code attached to it in the action property. This code will be run when the button is clicked. Most often, you will have at least one button that closes the dialog via closeDialog. In this case you can provide 0 as the right-side parameter to close the currently open dialog.

Reserved IDCs

The engine reserves:

• IDC = 1 for (contextually) OK, or CONTINUE
• IDC = 2 for (contextually) CANCEL, ESCAPE, ABORT

⚠

If you use these idc values, no action, no script, no event handler will operate on them.

CT_BUTTON=1

Name	Type	Required	Remark	Script
type	Integer	Yes	Control type: 1 (or CT_BUTTON, if using constants)	N/A
style	Integer	Yes	Display options: 0 (ST_LEFT): Text is left-aligned. 1 (ST_RIGHT) : Text is right-aligned. 2 (ST_CENTER): Text is centered.	N/A
action	String	No	Script command(s) to execute when button is pressed. Must use double quotes; single quotes or curly brackets will not work. The variable "this" is available, and contains the unit that pressed the button, but unlike User Interface Event Handlers no "_this" information about the current control is passed.	buttonSetAction
borderSize	Float	Yes	If > 0 then a background (in the color defined in 'colorBorder') is drawn behind the button. It extends to the left by the distance defined here, its height is slightly less than that of the button, and it is vertically centered. The width extends to the right, to where the drop shadow starts. Stays static when button is pressed.	N/A
colorBackground	Color	Yes	Button's background color if not "active" (i.e. the mouse pointer is not over it).	ctrlSetBackgroundColor
colorBackgroundActive	Color	Yes	Background color if "active" (i.e. mouse pointer is over it).	ctrlSetActiveColor
colorBackgroundDisabled	Color	Yes	Background color if control is disabled	N/A
colorBorder	Color	Yes	Color of left border, defined in 'borderSize'	N/A
colorDisabled	Color	Yes	Text color if control is disabled (via ctrlEnable)	N/A
colorFocused	Color	Yes	Alternating background color. While the control has focus (but without the mouse pointer being over it) the background will cycle between 'colorFocused' and 'colorBackground'. If both are the same, then the color will be steady.	N/A
colorShadow	Color	Yes	Color of drop shadow behind button (not visible if button disabled)	N/A
colorText	Color	Yes	Color of text.	ctrlSetTextColor
default	Boolean	No	Whether the button will have focus upon loading the dialog.	ctrlSetFocus
offsetPressedX offsetPressedY	Float	Yes	The button's text & background will move by this distance when pressed. (If a shadow is defined, it will stay in place.)	N/A
offsetX offsetY	Float	Yes	Horizontal and vertical offset of drop shadow. If 0, then shadow will be placed directly behind button	N/A
url	String	No	URL which will be opened with default web browser. If tooltip is empty, URL will also be set as that.	N/A
soundClick	Sound	No	Sound to play when button is released after a click.	N/A
soundEnter	Sound	No	Sound to play when the mouse cursor is moved over the button.	N/A
soundEscape	Sound	No	Sound to play when the button was clicked via the mouse, and then released outside the button area.	N/A
soundPush	Sound	No	Sound to play when button is clicked.	N/A
text	String	No	Text to display. Will be vertically centered.	ctrlSetText
toolTip	String	No	Text that is shown in a little popup box when the mouse pointer is hovering over the button.	ctrlSetTooltip

Attributes class

Properties
Name	Type	Remark
font	string
shadow	Integer
align	String	"center"
color	Color Array	"#000000"

• Example Config:

class RscButton
{
	access = 0;
	type = CT_BUTTON;
	style = ST_LEFT;
	x = 0; y = 0; w = 0.3; h = 0.1;
	text = "";
	font = "TahomaB";
	sizeEx = 0.04;
	colorText[] = {0,0,0,1};
	colorDisabled[] = {0.3,0.3,0.3,1};
	colorBackground[] = {0.6,0.6,0.6,1};
	colorBackgroundDisabled[] = {0.6,0.6,0.6,1};
	colorBackgroundActive[] = {1,0.5,0,1};
	offsetX = 0.004;
	offsetY = 0.004;
	offsetPressedX = 0.002;
	offsetPressedY = 0.002;
	colorFocused[] = {0,0,0,1};
	colorShadow[] = {0,0,0,1};
	shadow = 0;
	colorBorder[] = {0,0,0,1};
	borderSize = 0.008;
	soundEnter[] = {"",0.1,1};
	soundPush[] = {"",0.1,1};
	soundClick[] = {"",0.1,1};
	soundEscape[] = {"",0.1,1};
};
class Dialog
{
	class Controls
	{
		class OK: RscButton
		{
			idc=1;// fixed engine constant
			x=y=w=y=whatever;
			text="OK"
			default=true;
		};
		class Cancel
		{
			idc=2; // fixed engine constant
			x=y=somewhere else
			default=false;
		};
	};
};

The following example uses almost the same code as the buttons shown in the example screenshot.

The same button four times in different states

• Example Config:

class MyButton 
{
  idc = -1;
  type = CT_BUTTON;
  style = ST_LEFT;
  default = false;
  font = FontM;
  sizeEx = 0.03;
  colorText[] = { 0, 0, 0, 1 };
  colorFocused[] = { 1, 0, 0, 1 };		// border color for focused state
  colorDisabled[] = { 0, 0, 1, 0.7 };		// text color for disabled state
  colorBackground[] = { 1, 1, 1, 0.8 };
  colorBackgroundDisabled[] = { 1, 1, 1, 0.5 };	// background color for disabled state
  colorBackgroundActive[] = { 1, 1, 1, 1 };		// background color for active state
  offsetX = 0.003;
  offsetY = 0.003;
  offsetPressedX = 0.002;
  offsetPressedY = 0.002;
  colorShadow[] = { 0, 0, 0, 0.5 };
  colorBorder[] = { 0, 0, 0, 1 };
  borderSize = 0;
  soundEnter[] = { "", 0, 1 };	// no sound
  soundPush[] = { "buttonpushed.ogg", 0.1, 1 };
  soundClick[] = { "", 0, 1 };	// no sound
  soundEscape[] = { "", 0, 1 };	// no sound
  x = 0.4; y = 0.475;
  w = 0.2; h = 0.05;
  text = "Close";
  action = "closeDialog 0; hint ""Dialog closed. You are good to go now!""";
};

CT_SHORTCUTBUTTON=16

Properties
Name	Type	Remark
action	String	Code executed when button is clicked.
Attributes	Class	see Dialog Control General
AttributesImage	Class	see Dialog Control General
animTextureNormal	Texture
animTextureDisabled	Texture
animTextureOver	Texture
animTextureFocused	Texture
animTexturePressed	Texture
animTextureDefault	Texture
textureNoShortcut	Texture	A custom Texture to be displayed alongside text. Position can be set in the ShortcutPos (Texture) and TextPos (text) class.
color	Color Array
color2	Color Array
colorActiveBackground	Color Array
colorBackground	Color Array
colorBackground2	Color Array
colorDisabled	Color Array
default	Boolean	If set to true, this control is focused when the GUI is opened
HitZone	Class
period	Float	Blinking period
periodFocus	Float	Blinking period when focused
periodOver	Float	Blinking period when mouse is hovering over the button
ShortcutPos	Class
Shadow	Integer	0,1 or 2
shortcuts	array	key short cuts. often over-ridden/ignored by engine
Size	Float	possibly a typo, used in conjunction with sizeEx
soundEnter	Sound Array
soundPush	Sound Array
soundClick	Sound Array
soundEscape	Sound Array
TextPos	Class

TextPos/HitZone

Properties
Name	Type	Remark
Left	Float
Top	Float
Right	Float
Bottom	Float

ShortcutPos

Properties
Name	Type	Remark
Left	Float
Top	Float
w	Float	clearly an inconsistency with 'right'
h	Float	clearly an inconsistency with 'bottom'

• Example Config:

class RscShortcutButton
{
  type = 16;

  class HitZone
  {
    left = 0.0;
    top = 0.0;
    right = 1.0;
    bottom = 1.0;
  };
  class ShortcutPos
  {
    left = 0.005;
    top = 0.005;
    w = 0.0225;
    h = 0.03;
  };
  class TextPos
  {
    left = 0.02;
    top = 0.005;
    right = 0.005;
    bottom = 0.005;
  };
  animTextureNormal = "#(argb,8,8,3)color(1,1,1,1)";
  animTextureDisabled = "#(argb,8,8,3)color(0.3,0.3,0.3,1)";
  animTextureOver = "#(argb,8,8,3)color(0.8,0.3,0,1)";
  animTextureFocused = "#(argb,8,8,3)color(1,0.5,0,1)";
  animTexturePressed = "#(argb,8,8,3)color(1,0,0,1)";
  animTextureDefault = "#(argb,8,8,3)color(0,1,0,1)";
  period = 0.1;
  periodFocus = 0.4;
  periodOver = 0.4;
  shortcuts[] = {};
  textureNoShortcut = "#(argb,8,8,3)color(0,0,0,0)";
  color[] = {0,0,0,0.6};
  color2[] = {0,0,0,1};
  colorDisabled[] = {0,0,0,0.3};
  colorBackground[] = {1,1,1,1};
  colorBackground2[] = {1,1,1,0.5};
  text = "";
  size = 0.04;
  class Attributes
  {
    font = "TahomaB";
    color = "#000000";
    align = "left";
    shadow = 0;
  };
};

CT_ACTIVETEXT=11

The active text control behaves very similar to buttons. It shows up as regular text with the additional functionality that you can click and select it. The dialog's currently selected Active Text control will be underlined to indicate it's status. By default, the first Active Text control is selected. When the mouse cursor hovers over an instance of this control, it will show up in the color defined in the colorActive property.

Notice: This control doesn't render the usually common colorBackground property and colorText is replaced with color.

• For Arrowhead, this is not true. The properties are there, and it might be an attempt to standardise, or to account for pictures

Properties
Name	Type	Remark
action	String	a statement that is executed when the control has been clicked
candrag	Boolean
blinkingPeriod	Float (Seconds)	Makes the text start transparent, go to full opacity and back to full transparent in the amount of time specified.
color	Color Array	replaces colorText, standard text and underline color
colorActive	Color Array	text and underline color whenever the mouse hovers over the control
colorShade	Color Array
colorFocused	Color Array
colorDisabled	Color Array
colorShade	Color Array
colorText	Color Array
colorBackground	Color Array	not applicable
colorBackground2	Color Array
default	Boolean	Whether or not this control is the dialog's initially selected active text
pictureWidth/Height	Float
sideDisabled	argb
picture	Texture
sideToggle	argb
textHeight	Float
soundEnter	Sound Array	the sound to play, when the cursor enters the button's bounds
soundDoubleClick	Sound Array	the sound to play, when the cursor enters the button's bounds
soundPush	Sound Array	the sound to play, when the button has been pushed
soundClick	Sound Array	the sound to play, when the button is being released
soundEscape	Sound Array	the sound to play, when the button has been pushed and the mouse button is released when not over the control.

The following example uses almost the same code as the controls shown in the example screenshot.

Simple dialog with three Active Text controls

• Example Config:

class MyActiveText
{
  idc = -1;
  type = CT_ACTIVETEXT;
  style = ST_LEFT;
  x = 0.75; y = 0.5;
  w = 0.2; h = 0.035;
  font = FontM;
  sizeEx = 0.024;
  color[] = { 1, 1, 1, 1 };
  colorActive[] = { 1, 0.2, 0.2, 1 };
  soundEnter[] = { "", 0, 1 };	// no sound
  soundPush[] = { "", 0, 1 };
  soundClick[] = { "", 0, 1 };
  soundEscape[] = { "", 0, 1 };
  action = "hint ""Good choice!""";
  text = "Text";
  default = true;
};