Page tree
Skip to end of metadata
Go to start of metadata

Introduction

Button controls display a line of text over a rectangular background, which can have an optional drop shadow.
When the control is clicked, the text & background are moved a bit, to simulate a depressed button, and one or more script commands can be executed.

Related commands: Interactions - User Dialogs - Buttons

Properties

Only properties unique to this control type are listed. For general properties, see the Properties page.
If a property doesn't have a default value, then it must be defined explicitly.

Sounds

Different sounds can be assigned to specific button states, via the properties 'soundClick', 'soundEnter', etc.
These definition though, can only use sound files that reside in an addon. Sound files from a mission cannot be used this way! In order to use sounds from mission folders, use Reference List instead. (see demo mission Dialog Sounds.zip for examples)

NameTypeDefaultRemarkScript
typeInteger-Control type: 1 (or CT_BUTTON, if using constants)-
styleInteger-Display options:
  • 0 (ST_LEFT)  : Text is left-aligned.
  • 1 (ST_RIGHT)  : Text is right-aligned.
  • 2 (ST_CENTER)  : Text is centered.
  • 48 (ST_PICTURE): 'text' property points to an image.
-
actionString-Script command(s) to execute when button is pressed.
Must use double quotes; single quotes or curly brackets will not work.
Since V3.6 the array _this is also available; its first (and only) element contains the current control (i.e. the button).
buttonSetAction
borderSizeFloat-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.-
colorBackgroundColor-Button's background color if not "active" (i.e. the mouse isn't hovering over it).
ctrlSetBackgroundColor has no effect.
-
colorBackgroundActiveColor-Background color if "active" (i.e. mouse pointer is over it).
ctrlSetActiveColor has no effect.
-
colorBackgroundDisabledColor-Background color if control is disabled.-
colorBorderColor-
-
colorDisabledColor-Text color if control is disabled (via ctrlEnable)-
colorFocusedColor-Alternating background color. While the control has focus (but without the mouse pointer being over it) the background will cycle between 'colorFocused' and 'colorFocused2'. If both are the same, then the color will be steady.-
colorFocused2Color'colorBackground'Alternating background color when control has focus.-
colorShadowColor-Color of drop shadow behind button (not visible if button disabled)-
colorTextColor-Color of text.ctrlSetTextColor
defaultBoolean0Whether the button will have focus upon loading the dialog.ctrlSetFocus
offsetPressedX
offsetPressedY
Float-The button's text & background will move by this distance when pressed. (If a shadow is defined, it will stay in place.)-
offsetX
offsetY
Float-Horizontal and vertical offset of drop shadow. if 0, then shadow will be placed directly behind button-
soundClickArray Sound{}Sound to play when button is released after a click.-
soundEnterArray Sound{}Sound to play when the mouse cursor is moved over the button.-
soundEscapeArray Sound{}Sound to play when the button was clicked via the mouse, and then released outside the button area.-
soundPushArray Sound{}Sound to play when button is clicked.-
textString""Text to display. Will be vertically centered.
If the text is too long, it will be cut off - Button controls do not support multi-line text, neither via style options nor line breaks.
ctrlSetText

Event Handlers

Several event handlers can be assigned to buttons. Check Reference List for details (if the column "scope" contains a "B", then that respective event can be used with buttons).

Examples

The mission Dialog Button.zip contains a demonstration of all of the styles shown below.

Button with text caption

class Dlg { idd = -1; movingEnable = true; class controls { class BUTTON { type = 1; // CT_BUTTON style = 2; // ST_CENTER idc = -1; x = .4; y = .1; w = .2; h = .1; text = "Button"; font = "TahomaB"; sizeEx = .05; colorText[] = {1,0,0,1}; // colors of text and background colorBackground[] = {0,0,1,.8}; // red text on blue background colorFocused[] = {0,0,1,.5}; // background's opacity changes when having focus colorBackgroundActive[] = {0,1,0,.5}; // background turns green on mouseOver colorDisabled[] = {.3,.3,.3,1}; // colors if disabled colorBackgroundDisabled[] = {.1,.1,.1,1}; colorShadow[] = {0,0,0,.3}; // color and offset of drop shadow offsetX = .01; offsetY = .01; offsetPressedX = .01; // offset when pressed offsetPressedY = .01; borderSize = 0; // no left-hand border colorBorder[] = {}; soundEnter[] = {}; // no sounds soundPush[] = {}; soundClick[] = {}; soundEscape[] = {}; action = "player sidechat 'button pressed'"; // action when pressed toolTip = "click me"; // tooltip }; }; };

Button with toggled state

Normally, button presses are momentary (only stay down while the mouse is pressed). This method allows the use of a toggled state.
The secondary button (ON mode) has to be initially hidden by the script that opens the dialog, e.g. via ((findDisplay 10500) displayCtrl 10502) ctrlShow false

class Dlg { idd = -1; movingEnable = true; class controls { // first button, for "OFF" mode class BUTTON1 { type = 1; // CT_BUTTON style = 2; // ST_CENTER idc = 10501; x = .4; y = .4; w = .2; h = .1; font = "TahomaB"; sizeEx = .05; colorText[] = {1,0,0,1}; colorBackground[] = {0,0,1,.8}; colorFocused[] = {0,0,1,1}; colorBackgroundActive[] = {0,0,1,1}; colorDisabled[] = {.3,.3,.3,1}; colorBackgroundDisabled[] = {.1,.1,.1,1}; colorShadow[] = {0,0,0,.3}; offsetX = .01; offsetY = .01; offsetPressedX = .006; // leave a bit of the drop shadow visible offsetPressedY = .006; // when button is pressed borderSize = 0; colorBorder[] = {}; soundEnter[] = {}; soundPush[] = {}; soundClick[] = {}; soundEscape[] = {}; text = "OFF"; // when pressed, hide this button, and show the other one action = "ctrlShow [10502,true]; ctrlShow [10501,false]"; toolTip = "Activate"; }; // first button, for "ON" mode class BUTTON2 : BUTTON1 { idc = 10502; x = .406; // default button position offset to match y = .406; // the pressed position of the first one offsetX = .004; // smaller offset of drop shadow offsetY = .004; offsetPressedX = 0; // no movement when pressed offsetPressedY = 0; text = "ON"; action = "ctrlShow [10501,true]; ctrlShow [10502,false]"; toolTip = "Deactivate"; }; }; };

Button with sound and toggled image

To use images with buttons, an image has to be displayed as a Images, and then overlaid by an invisible button. The button control can then change the image when clicked. An alternative way to use button images is with an Dialogs_ActiveText control.

// sound definition, to be used in button control class CfgSounds { class click { sound[] = {"\click.ogg", 20, 1}; titles[] = {}; }; }; class Dlg { idd = 10500; movingEnable = true; class controls { // background image, to be changed by button control class IMG { type = 0; // CT_STATIC style = 48; // ST_PICTURE idc = 10500; // IDC required, as image (text) will be changed x = .45; y = .4; w = .1; h = .16; text = "Off.paa"; // default image, switch is up colorBackground[] = {}; colorText[] = {}; font = "TahomaB"; sizeEx = .1; }; // invisible button, overlays background image class BUTTON1 : IMG { type = 1; style = 0; idc = -1; colorText[] = {0,0,0,0}; // colors have to be defined with alpha==0 (totally transparent) colorBackground[] = {0,0,0,0}; colorFocused[] = {0,0,0,0}; colorBackgroundActive[] = {0,0,0,0}; colorDisabled[] = {0,0,0,0}; colorBackgroundDisabled[] = {0,0,0,0}; colorShadow[] = {0,0,0,0}; offsetX = 0; offsetY = 0; offsetPressedX = 0; offsetPressedY = 0; borderSize = 0 colorBorder[] = {}; soundEnter[] = {}; soundPush[] = {}; soundClick[] = {}; soundEscape[] = {}; tooltip = "Flip switch"; // when button is clicked, sound is played, and background image is toggled action = "playSound 'click'; \ _imgCtrl=(findDisplay 10500) displayCtrl 10500; \ _img=ctrlText _imgCtrl; \ _newImg = if ('Off' in _img) then {'On.paa'} else {'Off.paa'}; \ _imgCtrl ctrlSetText _newImg"; }; }; };