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

Adds a string that is specified by `itemString` to the list view user control that is specified by `userControlID`.

Strings are added to the end of the list view, unless the `-insert` flag is provided, in which case, the string is inserted at the index specified.

For multi-column list views, this command sets the value of the first column. To set subsequent column values, call the [setListViewItemText](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253737858) command.

## Functional area

User Window

# Command syntax

## Syntax

> Macro (scroll-tablelayout)

|  |
| --- |
| `addListViewItem userControlID "itemString"[-insert integer]` |

### Arguments

> Macro (scroll-tablelayout)

| **Name** | **Type** | **Required** | **Comments** |
| --- | --- | --- | --- |
| `userControlId` | integer | yes | ID of User Control to operate on. |
| `itemString` | string | yes | String to add to the List View. |

### Flags

> Macro (scroll-tablelayout)

| **Name** | **Flag arguments** | **Argument type** | **Exclusive to** | **Comments** |
| --- | --- | --- | --- | --- |
| `insert` | 1 | integer | — | Specifies the zero based index in which to insert the string. If this flag isn't specified, the item is appended to the end of the list. |

> Macro (16dcb1b2-c6fb-4c23-a096-38455b87e6a8/1fa5e51a-a28e-46e1-9b5c-734b339f025f/static/scroll-pagebreak)

## Return value

integer

Returns the index that the item was inserted at.

## Examples

```plaintext
// Demonstrate usage of a List View User Control
int $windowID, $listViewID, $formID;
 
// Destroy window if it already exists
if( `windowExists "ListViewTesting"` == true )
{
 destroyWindow "ListViewTesting";
}
// Create window and list view and position them
$windowID = `createWindow "ListViewTesting"`;
$formID = `getTopLevelForm $windowID`;
$listViewID = `createListView $windowID -form $formID -checkBoxes`;
setControlAnchor $listViewID "left" "left" 3;
setControlAnchor $listViewID "top" "top" 3;
setControlAnchor $listViewID "right" "right" 3;
setControlAnchor $listViewID "bottom" "bottom" 3;
 
// Create the columnsstring $columns[3];
int $widths[3];
$columns[0] = "Name";
$columns[1] = "Age";
$columns[2] = "Gender";
$widths[0] = 150;
$widths[1] = 50;
$widths[2] = 100;
setListViewColumns $listViewID $columns $widths;
 
// Add some items to the list view.
// The text we supply is for the first column.
// We supply text for subsequent columns using setListViewItemText
addListViewItem $listViewID "Bob";
addListViewItem $listViewID "Mary";
addListViewItem $listViewID "Jim";
addListViewItem $listViewID "Ann";
 
// Set additional details
setListViewItemText $listViewID 0 1 "50";
setListViewItemText $listViewID 0 2 "Male";
setListViewItemText $listViewID 1 1 "32";
setListViewItemText $listViewID 1 2 "Female";
setListViewItemText $listViewID 2 1 "21";
setListViewItemText $listViewID 2 2 "Male";
setListViewItemText $listViewID 3 1 "44";
setListViewItemText $listViewID 3 2 "Female";
 
// Set the check box to true for the males.
setListViewItemCheck $listViewID 0 true;
setListViewItemCheck $listViewID 2 true;
 
// Change Bob's name
setListViewItemText $listViewID 0 0 "Ken";
 
// Select Mary and Jim 
selectListViewItem $listViewID 2 true;
selectListViewItem $listViewID 1 true;

// Print out some of what we just did
print( `getListViewSelItems $listViewID` );
print( `getListViewItemText $listViewID 1 2` );
print( `getListViewItemCheck $listViewID 1` );
print( `getListViewItemCheck $listViewID 0` );
layoutForm $formID;
```

# Additional information

## Related commands

- [createListView](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253737803)
- [deleteAllListViewItems](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253737469)
- [deleteListViewItem](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253736986)
- [getListViewItemCheck](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253736774)
- [getListViewSelItems](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253736753)
- [getNumListViewItems](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253736852)
- [selectListViewItem](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253739440)
- [setListViewColumns](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253738749)
- [setListViewHandler](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253737377)
- [setListViewItemCheck](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253737441)
- [setListViewItemText](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253737858)