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

Introduction

Listboxes and Comboboxes show multiple lines of content (text and/or images), which can have hidden data attached to them.

Related commands: Interactions - User Dialogs - Listboxes

Single column listbox

Shows one column of text, or text with a preceding image.
Each cell can have a string and/or an integer assigned to it (via lbSetValue and lbSetData). These values are invisible, and can be read via the respective script commands.

Usage

A listbox always starts out empty (i.e. there is no way to assign any default values in the control's definition).
Once the listbox has been displayed, items (rows) can be added via lbAdd, lbFillVehicleClass or lbFillVehicleType.
In addition to the displayed text, each item can also contain a lbSetData and lbSetValue, which can be read when that item is selected (e.g. a list could show the display names for objects, but the invisible class name that is stored alongside the name is used when the item is activated).

Demo mission: ColorPicker.zip

Properties

Only properties unique to this control type are listed. For general properties, see the VBS Displays page.

Properties
NameTypeDefaultRemarkScript
typeinteger-must be 5 (or CT_LISTBOX if using a definition file)-
styleInteger (constant)-Display options:
  • 0 (ST_LEFT): Text is left-aligned.
  • 1 (ST_RIGHT) : Text is right-aligned.
  • 2 (ST_CENTER): Text is centered.
  • 16 (0x10, LB_TEXTURES): solid scrollbar
  • 32 (0x20, LB_MULTI): multiple items can be selected

Options can be combined by adding them, e.g. 2+32 = 34, to have centered text, and allow multiple selections.

-
canDragBoolean0Whether items from the listbox can be dragged and dropped onto another control.-
disableFilteringBoolean0Whether listbox can be filtered by keystrokes (e.g. press 'A', and only entries that contain a 'A' will be shown). V1.46+-
periodFloat2Length (in seconds) of color cycling period, when cursor is over a selected line (i.e. time it takes to change from e.g. 'colorSelect' to 'colorSelect2'). Set to 0 to disable cycling.-
rowHeightFloat-Height of one row in the listbox. If set to 0, then height will be adjusted to the selected font size.-
shadowInteger0If set to 2, a black outline is drawn around the text. Set to 0 to disable.-
colorColor'colorText'Color of border and scrollbars.ctrlSetForegroundColor (scrollbar not affected)
colorTextColor-Color of unselected text.lbSetColor (per line)
colorSelectColor-Color of selected text.-
colorSelect2Color'colorSelect'If 'period' is !=0 then the color of selected text will alternate between 'colorSelect' and 'colorSelect2'.-
colorSelectBackgroundColor'colorText'Color of background for selected line(s).-
colorSelectBackground2Color'colorSelectBackground'If 'period' is !=0 then the background color of selected lines will alternate between 'colorSelectBackground' and 'colorSelectBackground2'.-
soundSelectArray Sound-Must be defined (as an empty array), but has no effect.-

Example

description.ext:

class Dlg {
  idd = 20000;
  movingEnable = 0;
  
  class controls {
    class LIST {
      idc = 20000;
      type = 5;       // CT_LISTBOX
      style = 0;      // ST_LEFT
      x = 0.4; y = 0.4;
      w = 0.4; h = 0.4;
      rowHeight = 0;  // row height
      color[] = {1, 0, 0, 1};                 // outline and scrollbars
      colorText[] = {1, 1, 0, 1};             // unselected text
      colorSelect[] = {1, 1, 1, 1};           // selected text
      colorSelect2[] = {1, 1, 1, 1};          // alternating text color 
      colorSelectBackground[] = {0, 0, 0, 1}; // background for selected line(s)
      colorSelectBackground2[] = {1, 0, 0, 1};// alternating background color
      soundSelect[] = {};
      font = "vbs_unicode_lite";
      sizeEx = .04;
    };
  };
};

dialog.sqf: (used to open the dialog and populate the listbox)

// open the dialog
createDialog "Dlg";
// get the control for the listbox
_list = (findDisplay 20000) displayCtrl 20000;
// populate the list with vehicle classes
_list lbFillVehicleClass ["veh",""];

Single row listbox

Shows one row of text, or text with a preceding image.
Each cell can have a string and/or an integer assigned to it (via lbSetValue and lbSetData). These values are invisible, and can be read via the respective script commands.

Usage

Scripted usage is identical to single column listboxes, but only one line is displayed, and the user has to click the left or right arrow to see the next option. When clicking on the main text area, the selection always jumps to the next one.
(When defining the width of this type of listbox, make it somewhat bigger than the text would require, as in V2.x+ only about 70% of the text box width is actually utilized.)
Demo mission: HorizontalListBox.zip

Properties

Only properties unique to this control type are listed. For general properties, see the VBS Displays page.

Properties
NameTypeDefaultRemarkScript
typeinteger-must be 42 (or CT_XLISTBOX if using a definition file)-
styleInteger (constant)-Display options:
  • 0 (ST_LEFT): Text is left-aligned.
  • 1 (ST_RIGHT) : Text is right-aligned.
  • 2 (ST_CENTER): Text is centered.
  • 16 (0x10, LB_TEXTURES): Solid arrows and background (otherwise only an outline will be drawn).
    In VBS 1.x this creates items that looks "hand-drawn"; in V2.x+ the default outline is always a bit short for the background, so it is recommended to always enable this.
  • 1024 (0x400, SL_HORZ): Arrows will be drawn on the left and right of control. Should always be on in V2.x+ (In V1.x it is also possible to have vertical buttons -above and below the text-, but LB_TEXTURES has to be off, as they would only be drawn as outlines.)

Options can be combined by adding them, e.g. 2+16+1024 = 1026, to have centered text, background color, and horizontal buttons.

-
blinkingPeriodFloat0Control will fade in and out over the specified number of seconds. Set to 0 to disable.-
colorColor{0,0,0,.5}Arrow & background color if control doesn't have focus.V1.x: ctrlSetTextColor
V2.x+: ctrlSetForegroundColor
colorActiveColor-Arrow & background color if control does have focus.V1.x: ctrlSetActiveColor
No command in V2.x+
colorDisabledColor-Arrow & background color if control has been disabled.-
colorTextColor-Text color if control doesn't have focus.-
colorSelectColor-Text color if control does have focus.-
shadowInteger0If text should have a black outline (0: no outline, 2: outline)-
arrowEmptyString-Texture (JPG, PAA or Procedural Textures) to display the for the decrease/increase buttons, when neither button is pressed. The image specified is mirrored horizontally for the right button. If the string is empty (""), then a square is shown.-
arrowFullString-Image to display the for the decrease/increase buttons, when a button is pressed. Otherwise same specs as 'arrowEmpty'.-
borderString-Texture (JPG, PAA or Procedural Textures) to use for the slider background.-
soundSelectArray Sound-Sound played when an item is selected.-

Example

description.ext:

class Dlg {
  idd = 20000;
  movingEnable = 0;
  
  class controls {
    class HLIST {
      idc = 20000;
      type = 42;       // CT_XLISTBOX; 
      style = 1024+16; // SL_HORZ + LB_TEXTURES; 
      x = 0.4; y = 0.4;
      w = 0.4; h = 0.04;
      sizeEx = .03; 
      font = "vbs_unicode_lite"; 
      colorActive[] = {1,.5,0,1};    // Arrow & background color if focussed
      colorDisabled[] = {1,1,1,0.2}; // Arrow & background color if disabled 
      colorText[] = {0,0,0,.5};      // Text color if unfocussed
      colorSelect[] = {0,0,0,1};     // Text color if focussed 
      arrowEmpty = "\ca\ui\data\arrow_left_ca.paa"; // button texture when unpressed
      arrowFull = "\ca\ui\data\arrow_left_ca.paa"; // button texture when pressed
      border = ""; // background texture
      soundSelect[] = {};
    };    
  };
};

dialog.sqf: (used to open the dialog and populate the listbox)

// open the dialog
createDialog "Dlg";
// get the control for the listbox
_list = (findDisplay 20000) displayCtrl 20000;
// populate the list with vehicle classes
_list lbFillVehicleClass ["veh",""];

Multi column listbox

Shows several columns with aligned data (text or images).

Usage

The number of columns used, and their offset from the left edge of the row, are defined via the columns[] property.
Each cell can have a string and/or an integer assigned to them (via lnbSetValue and lnbSetData). These values are invisible, and can be read via the respective script commands.

Two extra buttons can be displayed at the side of the listbox. These will only be displayed at the currently active row, and will move up and down the listbox, as the selection changes.
They are separate controls (and referenced via the idcLeft/Right property), and can have specific actions assigned to them. To make them clickable, they should either be buttons or active text.

If two multi-column listboxes are displayed in the same dialog (e.g. one for the header and one for the content), the focus must be forced onto the content listbox via a script, otherwise it is not possible to select it via mouse clicks (it would only be possible to change the focus via <Tab>).

A ctrlEnable multi-column listbox will not change its color, but will only have the selection indicator (i.e. the row highlighting) removed.

Demo mission: 2DListBox_Demo.zip

Properties

Only properties unique to this control type are listed. For general properties, see the VBS Displays page.

Properties
NameTypeDefaultRemarkScript
typeInteger-must be 102 (or CT_LISTNBOX if using a definition file)-
styleInteger (constant)-Display options:
  • 0 only a single row can be selected
  • 32 (0x20, LB_MULTI): multiple rows can be selected
-
canDragBoolean0Whether items from the listbox can be dragged and dropped onto another control.-
columnsArray of Float{0}define the left starting position of each column. The values are offsets ratios with the listbox's defined width (i.e. the left edge is 0, and the right edge is 1). Each value is calculated from the left edge of the row-it is NOT incremental from the previous column! Tip: Use {-0.01} in first column to fix unwanted offset, if desired.-
drawSideArrowsBoolean0Each row can be linked to 2 arrow buttons which are shown on the left and right of the row.
If set to 1 (true), then 'idcLeft' and 'idcRight' must be defined.
-
idcLeftInteger-The IDC of the control (defined separately) to be used for the left button.-
idcRightInteger-The IDC of the control (defined separately) to be used for the right button.-
periodFloat2Length (in seconds) of color cycling period, when cursor is over a selected line (i.e. time it takes to change from e.g. 'colorSelect' to 'colorSelect2'). Set to 0 to disable cycling.-
rowHeightFloat-The height of a single row.-
shadowInteger0If set to 2, a black outline is drawn around the text. Set to 0 to disable.-
colorColor'colorText'Color of scrollbar.-
colorTextColor-Color of unselected text.-
colorSelectColor-Color of selected text.-
colorSelect2Color'colorSelect'If 'period' is !=0 then the color of selected text will alternate between 'colorSelect' and 'colorSelect2'.-
colorSelectBackgroundColor'colorText'Color of background for selected line.-
colorSelectBackground2Color'colorText'If 'period' is !=0 then the background color of the selected line will alternate between 'colorSelect' and 'colorSelect2'.-
soundSelectArray Sound-Must be defined (as an empty array), but has no effect.-

Example

description.ext:

class Dlg {
  idd = 20000;
  movingEnable = 0;
  
  class controls {
    class LISTNBOX { 
      idc = 20000; 
      type = 102; // CT_LISTNBOX; 
      style = 0;  // single selection only
      x = 0.1; y = 0.4;
      w = 0.8; h = 0.4;
    
      columns[] = {0, 0.06, 0.5};    // left position of each column used
      rowHeight = .05;               // height of each row
      colorText[] = {0, 0, 0, 1};    // color of unselected text
      colorSelect[] = {1, .5, 0, 1}; // color of selected text
    
      font = "vbs_unicode_lite"; 
      sizeEx = ".026";
      soundSelect[] = {}; 
    };
  };
};

dialog.sqf: (used to open the dialog and populate the listbox)

// open the dialog
createDialog "Dlg";
// get the control for the listbox
_list = (findDisplay 20000) displayCtrl 20000;
// get some vehicles to put into the list
_vehicles = "(getNumber(_x>>'scope') == 2) && ('_us_mc_' in configName _x)" configClasses (configFile >> "cfgVehicles");
{
  _dName = getText(_x>>"displayName"); // get the vehicles class and display name
  _class = configName _x;
  // create a new row, and fill cells 2 & 3 with the class and display name
  _idx = _list lnbAddRow ["",_class,_dName];
  // put the vehicle image into the first cell
  _list lnbSetPicture [[_idx,0],previewPicture _class];
}forEach _vehicles;

Combobox

A combobox is a listbox which is normally shown in a collapsed view. Once selected, it will expand (towards the bottom), and show multiple lines. Once an item is selected (and only one item can be selected) it will collapse again, and show the selection.

Usage

Population of comboboxes is practically identical to single column listboxes, in that it starts out empty, and is populated once displayed. It can also have hidden strings and numbers associated with each item.

Demo mission: DialogMap.zip

Properties

Only properties unique to this control type are listed. For general properties, see the VBS: Dialogs page.

Properties
NameTypeDefaultRemarkScript
typeInteger (constant)-must be 4 (or CT_COMBO if using a definition file)-
styleInteger (constant)-Only 0 is available (for left-aligned text).-
rowHeightFloat0Height of one row in the listbox. If set to 0, then height will be adjusted to the selected font size.-
wholeHeightFloat-Height of the expanded box.-
colorColor'colorText'Color of border and scrollbar.-
colorTextColor-Color of unselected text.-
colorSelectColor-color of selected text.-
colorSelectBackgroundColor'colorText'Background color of selected lines.-
soundSelect, soundExpand, soundCollapseArray Sound-Must be defined (as an empty array), but has no effect.-

Example

description.ext:

class Dlg {
  idd = 20000;
  movingEnable = 0;
  
  class controls {
    class COMBO {
      idc = 20000;
      type = 4;   // CT_COMBO;
      style = 0;  // left-aligned
      x = 0.4; y = 0.4;
      w = 0.4; h = 0.04;
    
      wholeHeight = 0.2;                // expanded height 
      colorText[] = {1, .5, 0, 1};      // unselected text
      colorSelect[] = {0, 0, 0, 1};     // selected text
      colorBackground[] = {1, 1, 1, 1}; // selection background
      
      font = "vbs_unicode_lite";
      sizeEx = ".026";
      soundSelect[] = {"", 0.10, 1};
      soundExpand[] = {"", 0.10, 1};
      soundCollapse[] = {"", 0.10, 1};
    };
  };
};

dialog.sqf: (used to open the dialog and populate the listbox)

// open the dialog
createDialog "Dlg";
// get the control for the listbox
_list = (findDisplay 20000) displayCtrl 20000;
// populate the list with vehicle classes
_list lbFillVehicleClass ["veh",""];