CT_CONTROLS_TABLE

Introduction

This control type is a crossover between CT_LISTNBOX and CT_CONTROLS_GROUP. It is a list of user defined controls.

Rows and headers

Each Controls Table consists of N lines, with each line being either row or header. Header is a collection of controls that are located on the same row. Row is similar to header, with added functionality of selection. If user clicks on a row or any control in it, the row is selected and highlighted. Up and down keys can be used to change selection to the previous or next row, respectively. When the selection is changed, the event onLBSelChanged is emitted. If the highlight colour is set to fully transparent, rows can act as another type of header as user does not perceive any selection.

Row and header templates

Structure of row and header is defined using a template. Apart from their names (RowTemplate and HeaderTemplate), structure of both templates is the same. Each defines a set of columns and their properties. The column class (the name of which is currently not used) defines key properties of control that is created upon creation of new row or header.

controlBaseClassPath - Defines config path to control. See next section for detailed info.
columnX - Position of the created control, in table coordinates (0 is the table's left side).
columnW - Width of the created control. UI element created inside the column will be as wide as the column is.
controlOffsetY - Optional, default value 0. Defines offset of control from top of its line. Negative values are ignored.
controlH - Optional, default value 0. If set to non-negative value, it overrides height of the control from base class. Otherwise, the height from control base class is used.

It is important to note that even if a Controls Table uses only rows or only headers, both templates must be defined in config.

Base class

Each column must have its base class defined by the controlBaseClassPath[] parameter. This array of strings defines config path to class that is instantiated each time a new row (or header) is added to the table. The given class must be a valid UI control, i.e. it must contain parameter type that has a valid value and any other parameters that correspond to the given type.

controlBaseClassPath[] = {"RscDisplayTemp", "RscDisplayTemp_LineTextBase"};

Expands to config path:

configFile >> RscDisplayTemp >> RscDisplayTemp_LineTextBase;

Since Arma 3 v2.01 base classes are now also searched for in the missionConfigFile and campaignConfigFile (https://feedback.bistudio.com/T153452)

White list

Some control types are not suitable for use inside of Controls Table. These include e.g. control containers (Controls Group and Controls Table) or controls that exceed their defined bounds while being drawn (Combo box). For this reason, the Controls Table only supports limited subset of UI controls that have been tested and confirmed to work.

The currently supported types are:
CT_STATIC
CT_BUTTON
CT_EDIT
CT_ACTIVETEXT
CT_STRUCTURED_TEXT
CT_SHORTCUTBUTTON
CT_XSLIDER
CT_CHECKBOX

IDC pool

Each control created by the RV engine has an IDC which can be used for its identification among other controls which are part of the same display. For obvious reasons, each IDC should be unique in the context of its parent display. As the Controls Table can be set to create and remove controls at run time (for example, click on a button can result in addition of a row to the table) and can potentially be used to create thousands of controls, it was necessary to implement a system which would Allow the creator/designer to limit total number of controls. Make sure that each control created by ControlsTable has a unique IDC. For this reason, ControlsTable requires two parameters that define range of IDCs which are assigned to controls upon their creation. These parameters are firstIDC and lastIDC and together they define a range of values. If an instance of ControlsTable runs out of IDCs to create a new row or header, no elements are created. The IDC range is used for both row and header controls. When a line of controls is removed, IDCs that were assigned to them are returned to the pool and reused for new lines. It is therefore not recommended to rely on a control to have the same IDC, unless you're certain that it won't be removed and replaced by a another one. ControlsTable A has 3 controls in its row template (image, text and checkbox) and 1 control in its header template (text). firstIDC is set to 500 and lastIDC is set to 799. This means that table A has 300 IDCs at its disposal and may contain up to 100 rows (if it has no headers) or up to 300 headers (if it has no rows). If table A contains 50 headers and 83 rows, it is using 299 IDCs and no additional row can be created. However, it is still possible to add one more header.

Note: Currently, the system doesn't check if there's any other control, the IDC of which lies in the range.

Draw order

Vertical and horizontal scrollbars (if necessary). Rectangle that highlights currently selected row. All rows and headers, from row/header that was created first to the one that was created last. In each row/header, controls are drawn in the same order as they're defined in the row/header template - starting with control from the first column. This approach is different than the one used by ControlsGroup where the currently focused control is always drawn last (and is therefore drawn on top of the others in case of overlap). In ControlsTable, focus does not affect draw order in any way. Note: If the columns of the table overlap, it is possible to change draw order by reordering columns in the row/header template. This is used in lobby of Project Argo where multiple non-interactive controls (each defined by a different column) overlap each other.

• 

  CT_CONTROLS_TABLE control.

Related commands & functions

• Commands: General
• Commands: UI Eventhandlers
• Commands: Controls Table

Related User Interface Eventhandlers

• Events: General

Alphabetical Order

ⓘ

TokenNames common to most controls, such as x, y, w, h, text, idc... can be found here.

⚠

Not all of the listed attributes might have an effect nor might the list be complete. All attributes were gathered with this config crawler.

#define CT_CONTROLS_TABLE 19

F

firstIDC

Type

Numer

Description

The start IDC.

firstIDC = 9000;

H

headerHeight

Type

Number, String

Description

The height of the header row.

Number example:

headerHeight = 0.025;

String example:

headerHeight = "5 * 0.5 * pixelGrid * pixeH";

HeaderTemplate

Type

Class

Description

Template for headers (unlike rows, cannot be selected).

class HeaderTemplate
{
	class HeaderBackground
	{
		controlBaseClassPath[] = {"RscText"};
		columnX = 0;
		columnW = 14.7 * GUI_GRID_W;
		controlOffsetY = 0;
	};
	class Column1
	{
		controlBaseClassPath[] = {"RscPictureKeepAspect"};
		columnX = 0.2 * GUI_GRID_W;
		columnW = 0.6 * GUI_GRID_W;
		controlOffsetY = 0.2 * GUI_GRID_H;
		controlH = 0.6 * GUI_GRID_H;
	};
	class Column2
	{
		controlBaseClassPath[] = {"RscText"};
		columnX = 0.8 * GUI_GRID_W;
		columnW = 9 * GUI_GRID_W;
		controlOffsetY = 0.1 * GUI_GRID_H;
	};
};

L

lastIDC

Type

Numer

Description

The last IDC.

lastIDC = 9999;

lineSpacing

Type

Number, String

Description

The amount of space to leave between rows.

Number example:

lineSpacing = 0.1;

String example:

lineSpacing = "1 * 0.5 * pixelGrid * pixelH";

R

rowHeight

Type

Number, String

Description

The height of one row.

Number example:

rowHeight = 0.025;

String example:

rowHeight = "5 * 0.5 * pixelGrid * pixeH";

RowTemplate

Type

Class

Description

Template for selectable rows.

class RowTemplate
{
	class RowBackground
	{
		controlBaseClassPath[] = {"RscText"};
		columnX = 0;
		columnW = 14.7 * GUI_GRID_W;
		controlOffsetY = 0;
	};
	class Column1
	{
		controlBaseClassPath[] = {"RscPictureKeepAspect"};
		columnX = 0;
		columnW = 2 * GUI_GRID_W;
		controlOffsetY = 0;
		controlH = 1 * GUI_GRID_H;
	};
	class Column2
	{
		controlBaseClassPath[] = {"RscText"};
		columnX = 2 * GUI_GRID_W;
		columnW = 8.7 * GUI_GRID_W;
		controlOffsetY = 0.1 * GUI_GRID_H;
	};
	class Column3
	{
		controlBaseClassPath[] = {"RscButton"};
		columnX = 11.2 * GUI_GRID_W;
		columnW = 2 * GUI_GRID_W;
		controlOffsetY = 0.1 * GUI_GRID_H;
	};
};

S

selectedRowAnimLength

Type

Number

Description

Length of the animation cycle in seconds.

selectedRowAnimLength = 1.2;

selectedRowColorFrom

Type

Array

Description

Colours which are used for animation (i.e. change of colour) of the selected line.

selectedRowColorFrom[] = {1,1,1,1};

selectedRowColorTo

Type

Array

Description

Colours which are used for animation (i.e. change of colour) of the selected line.

selectedRowColorTo[] = {1,1,1,0};

Default Classes

AddOns: Classes need to be initialised first with class SomeClass;

---

Missions: Since Arma 3 v2.02 one can use import SomeClass; to initialise a class (see the import keyword).

In older versions, use "Default" call BIS_fnc_exportGUIBaseClasses; and paste the result into the description.ext.

⚠

The default class seems to be broken. For a working example which replicates the controls table from the image above see: https://feedback.bistudio.com/T155872#2144204

class MyControlsTable
{
	idc = 107;
	x = SafezoneX + 16.5 * GUI_GRID_W;
	y = SafezoneY + 3.5 * GUI_GRID_H;
	w = 15 * GUI_GRID_W;
	h = 20 * GUI_GRID_H;
	 
	type = CT_CONTROLS_TABLE;
	style = SL_TEXTURES;
	 
	lineSpacing = 0;
	rowHeight = 1 * GUI_GRID_H;
	headerHeight = 1 * GUI_GRID_H;
	 
	firstIDC = 42000;
	lastIDC = 44999;
	 
	// Colours which are used for animation (i.e. change of colour) of the selected line.
	selectedRowColorFrom[]  = {0.7, 0.85, 1, 0.25};
	selectedRowColorTo[]	= {0.7, 0.85, 1, 0.5};
	// Length of the animation cycle in seconds.
	selectedRowAnimLength = 1.2;
	 
	class VScrollBar : ScrollBar
	{
		width = 0.021;
		autoScrollEnabled = 0;
		autoScrollDelay = 1;
		autoScrollRewind = 1;
		autoScrollSpeed = 1;
	};
 
	class HScrollBar : ScrollBar
	{
		height = 0.028;
	};
	 
	// Template for selectable rows
	class RowTemplate
	{
		class RowBackground
		{
			controlBaseClassPath[] = {"RscText"};
			columnX = 0;
			columnW = 14.7 * GUI_GRID_W;
			controlOffsetY = 0;
		};
		class Column1
		{
			controlBaseClassPath[] = {"RscPictureKeepAspect"};
			columnX = 0;
			columnW = 2 * GUI_GRID_W;
			controlOffsetY = 0;
			controlH = 1 * GUI_GRID_H;
		};
		class Column2
		{
			controlBaseClassPath[] = {"RscText"};
			columnX = 2 * GUI_GRID_W;
			columnW = 8.7 * GUI_GRID_W;
			controlOffsetY = 0.1 * GUI_GRID_H;
		};
		class Column3
		{
			controlBaseClassPath[] = {"RscButton"};
			columnX = 11.2 * GUI_GRID_W;
			columnW = 2 * GUI_GRID_W;
			controlOffsetY = 0.1 * GUI_GRID_H;
		};
	};
	 
	// Template for headers (unlike rows, cannot be selected)
	class HeaderTemplate
	{
		class HeaderBackground
		{
			controlBaseClassPath[] = {"RscText"};
			columnX = 0;
			columnW = 14.7 * GUI_GRID_W;
			controlOffsetY = 0;
		};
		class Column1
		{
			controlBaseClassPath[] = {"RscPictureKeepAspect"};
			columnX = 0.2 * GUI_GRID_W;
			columnW = 0.6 * GUI_GRID_W;
			controlOffsetY = 0.2 * GUI_GRID_H;
			controlH = 0.6 * GUI_GRID_H;
		};
		class Column2
		{
			controlBaseClassPath[] = {"RscText"};
			columnX = 0.8 * GUI_GRID_W;
			columnW = 9 * GUI_GRID_W;
			controlOffsetY = 0.1 * GUI_GRID_H;
		};
	};
};