---
title: "createListBox"
canonical: "https://help.vicon.com/space/ShogunPost121/1253738733/createListBox"
format: markdown
---
# Description

Creates a list box user control on the user window that is specified by `windowId`.

A list box enables the user to select from a set of list of items.

The control is initially placed in the top-left corner of the user window, and must be placed by using the `-pos` option, or by using the [setControlPos](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253737132) command.

The command returns the Control ID of the user control, which should be saved for later operations on the control.

## Functional area

User Window

# Command syntax

## Syntax

> Macro (scroll-tablelayout)

|  |
| --- |
| `createListBox parentWindowID "itemStr1" "itemStr2"...[-hidden] [-pos integer array] [-form integer] [-multi] [-sort] [-sel integer]` |

### Arguments

| Name | Type | Required | Comments |
| --- | --- | --- | --- |
| `item1` | string | no | One or more strings are allowed to populate the list box. |
| `windowId` | int | yes | ID of user window to place the control on. |

> Macro (scroll-pagebreak)

### Flags

> Macro (scroll-tablelayout)

| Name | Flag arguments | Argument type | Exclusive to | Comments |
| --- | --- | --- | --- | --- |
| `multi` | 0 | — | — | Specifies that the control should allow multiple selections. The default is single selection only. |
| `sort` | 0 | — | — | Forces the control to automatically sort the items in the list box. The default is unsorted |
| `hidden` | 0 | — | — | Specifies that the control should be hidden initially. Call [showControl](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253736955) to subsequently make it visible. The default is for it to be visible. |
| `sel` | 1 | integer | — | A zero based index of the item to be selected. The default is no selection. |
| `pos` | 1 | integer array | — | A four-element int array representing a rectangle, which specifies the initial size/position of the control relative to the top left corner of the user window. The element order is Left, Top, Right, and Bottom. The default is a drop list 150 units high by 50 units wide. |
| `form` | 1 | integer | — | Control ID of the form user control which will dynamically position this control. |

## Return value

integer 

> Macro (scroll-pagebreak)

## Examples

```plaintext
// Create a list box user control.
int $windowId;
int $controlId; 
int $rect[4];
 
// First create a user window to place the Control on
$windowId = `createWindow "MyWindow"`; 
// Specify the size of the Control - 80 units high
$rect[0] = 20;  // Left
$rect[1] = 20;  // Top
$rect[2] = 70;  // Right
$rect[3] = 100; // Bottom
 
// Create the Control on the Window, passing
// in the Window Id of the user window we 
// just created. Make the list sorted, add some items,
// and set the initial selection. Also allow for multiple
// selection
$controlId = `createListBox $windowId "Item #3" "Item #1" "Item #2" -sort -sel 1 -multi -pos $rect`;
```

# Additional information

## Related commands

- [addListBoxItem](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253737108)
- [deleteAllListBoxItems](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253736453)
- [deleteListBoxItem](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253736724)
- [findListBoxItem](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253736496)
- [getListBoxItem](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253736807)
- [getListBoxSelItems](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253737388)
- [selectListBoxItem](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253736476)