# Function Reference

# _GUICtrlListView_InsertItem

Inserts a new item in the control

#include <GuiListView.au3>
_GUICtrlListView_InsertItem ( $hWnd, $sText [, $iIndex = -1 [, $iImage = -1 [, $iParam = 0]]] )

## Parameters

$hWnd | Control ID/Handle to the control
$sText | Item text. If set to -1, the item text is set via the $LVN_GETDISPINFO notification message.
$iIndex | [optional] 0-based index at which the new item should be inserted. If this value is greater than the number of items currently contained by the control, the new item will be appended to the end of the list and assigned the correct index.
$iImage | [optional] 0-based index of the item's icon in the control's image list
$iParam | [optional] Application Defined Data

## Return Value

Success: | the index of the new item.
Failure: | -1.

## Remarks

You can not use this function to insert subitems. Use _GUICtrlListView_SetItemText() to insert subitems.
As AutoIt uses the $iParam parameter to store the controlID of native-created ListView items, this value should be set sufficiently high for UDF-created items to avoid possible conflict with any existing controls - a starting value of 1000 is recommended.

## Related

_GUICtrlListView_SetItemText

## Example

    #include <GUIConstantsEx.au3>
    #include <GuiListView.au3>

    Example()

    Func Example()
        GUICreate("ListView Insert Item (v" & @AutoItVersion & ")", 400, 300)
        Local $idListview = GUICtrlCreateListView("", 2, 2, 394, 268)
        GUISetState(@SW_SHOW)

        ; Set ANSI format
    ;~     _GUICtrlListView_SetUnicodeFormat($idListview, False)

        ; Insert columns
        _GUICtrlListView_InsertColumn($idListview, 0, "Column 1", 100)

        ; Add items
        _GUICtrlListView_InsertItem($idListview, "Item 1", 0)
        _GUICtrlListView_InsertItem($idListview, "Item 2", 1)
        _GUICtrlListView_InsertItem($idListview, "Item 3", 1)

        ; Loop until the user exits.
        Do
        Until GUIGetMsg() = $GUI_EVENT_CLOSE
        GUIDelete()
    EndFunc   ;==>Example