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 IDC's

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

Properties
Name	Type	Remark
action	string	a statement that is executed when the button is not disabled and clicked
attributes	class	Possibly an irrelevant xbox class
BorderSize	float	thickness of border
default	boolean	Whether or not this button is the dialog's initially selected button
colorDisabled	color array	text color, if the control has been disabled via ctrlEnable
colorFocused	color array	color when control has received focus via tabbing or scripted methods
colorShadow	color array	the color of the shadow
colorBorder	color array	the color of the border, if any
borderSize	float	the width of the border
colorBackgroundActive	color array	color when control has received focus via mouse-over
colorBackgroundDisabled	color array	background color, if the control has disabled via ctrlEnable
offsetX	float	the relative X offset between the button and its shadow
offsetY	float	the relative Y offset between the button and its shadow
offsetPressedX	float	the relative X offset between the button and its shadow, when it's pressed
offsetPressedY	float	the relative Y offset between the button and its shadow, when it's pressed
soundEnter	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
size	float	possibly an irrelevant xbox dialog
tooltip	string	some help phrase when you hover over button

Attributes class

Properties
Name	Type	Remark
font	string
shadow	integer
align	string	"center"
color	color array	"#000000"

• Example:

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:

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
Attributes	class
AttributesImage	class
animTextureNormal	argb color array
animTextureDisabled	argb color array
animTextureOver	argb color array
animTextureFocused	class
animTexturePressed	argb color array
animTextureDefault	argb color array
textureNoShortcut	argb color array
color	color array
color2	color array
colorActiveBackground	color array
colorBackground	color array
colorBackground2	color array
colorDisabled	color array
default	boolean
HitZone	class
period	float
periodFocus	float
periodOver	float
ShortcutPos	class
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

• Example:

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 Arrohead, 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
colorDisabled	color
colorShade	color
colorText	color
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	floats
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:

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; };