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.

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.

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.

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.

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",""];