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


Stateboxes were introduced in V3.4, and are checkboxes that can have multiple states (which are indicated by different icons).

Related commands: Interactions - User Dialogs - Stateboxes

Demo mission: Dialog


Clicking on a statebox control will cause it to cycle through its available modes. These modes are defined by the 'stateIcons' array, which contains a list of images. State 0 corresponds to the first icon, state 1 to the 2nd, and so on.
Clicking the left mouse button will go to the next image, clicking the right button will go to the previous one (wrapping around at either end).
The current state (index) can be read via the sbGetCurrentState command.


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.

typeInteger-must be 112 (or CT_STATEBOX, if using constants)-
styleInteger-Display options:
  • 0 (ST_LEFT): Caption is left-aligned with icon
  • 1 (ST_RIGHT): Caption is right-aligned with icon
  • 2 (ST_CENTER): Caption is centered within control width
iconW, iconHFloat0Width and height of the icon. (If either is undefined, or 0, then no icon is shown.)
Due to the fact that a dialog sized 1x1 is a box with a ratio of 4:3, the width/height have to reverse this proportion, to generate an undistorted image (e.g iconW=.03; iconH=.04 would create a square).
iconLeftBoolean1If 0, then icon will be right-aligned within the control. If 1, it is left-aligned.-
colorTextColor-Color of text label, when it has neither focus, nor is it active.ctrlSetTextColor (V3.6+)
colorTextActiveColor-Color of the text when mouse is over this control.ctrlSetActiveColor (V3.6+)
colorTextFocusedColor-Color of the text when control has focus.-
colorTextDisabledColor-Color of the text when control is disabled.-
colorIconColor-Regular color of the icon (when it has neither focus, nor is it active).ctrlSetTextColor (V3.6+)
colorIconActiveColor-Color of the icon when mouse is over this control.ctrlSetActiveColor (V3.6+)
colorIconFocusedColor-Color of the icon when control has focus.-
colorIconDisabledColor-Color of the icon when control is disabled.-
colorBackgroundColor{0,0,0,0}Color of the control's background. (Only available since V3.6)ctrlSetBackgroundColor
stateIconsArray{}List of paths to PAA images (or Procedural Textures), to cycle through when control is clicked. If empty, then no control (not even the text label) is shown.
(In versions below 3.6, no drive letter could be specified - images were always taken from the internal VBS resources.)
textString""Text label to show next to icon.ctrlSetText

Event Handlers

An event handlers can be assigned to a statebox, to fire when it is clicked ('onStateBoxToggle').
Check Reference List for details.


The mission Dialog contains a demonstration of the example shown on the right.

Open with createDialog "Dlg" class Dlg { idd = 20000; movingEnable = 1; class controls { class CHK1 { type = 112; // CT_STATEBOX style = ST_LEFT; // or ST_RIGHT, ST_CENTER (text alignment relative to box) idc = 20000; x = .4; y = .6; // position w = .2; h = .036; // size iconH = .04; // height of icon iconW = .03; // width of icon iconLeft = 1; // 1: icon on left, 0: icon on right sizeEx = .036; text = "Position"; font = "TahomaB"; colorText[] = {1,1,1,1}; // Regular color of the text colorTextActive[] = {1,1,0,1}; // Color of the text when mouse is over this control colorTextFocused[] = {1,0.5,0,1}; // Color of the text when control has focus colorTextDisabled[] = {0.8,0.8,0.8,1}; // Color of the text when control is disabled colorIcon[] = {1,1,1,1}; // Regular color of the icon colorIconActive[] = {1,1,0,1}; // Color of the icon when mouse is over this control colorIconFocused[] = {1,0.5,0,1}; // Color of the icon when control has focus colorIconDisabled[] = {0.8,0.8,0.8,1}; // Color of the icon when control is disabled // four icons to cycle through (containing arrows pointing up, right, down, left) stateIcons[] = {"\vbs2\ui\data\vbs3_sortingUp_ca.paa","\vbs2\ui\data\vbs3_sortingRight_ca.paa","\vbs2\ui\data\vbs3_sortingDown_ca.paa","\vbs2\ui\data\vbs3_sortingLeft_ca.paa"}; }; class CHK2 : CHK1 { idc = 20001; y = .656; text = "Alive"; // state icons are an empty and filled checkbox stateIcons[] = {"\vbs2\ui\Data\vbs3_checkbox_empty_ca.paa", "\vbs2\ui\Data\vbs3_checkbox_full_ca.paa"}; }; }; };