method Items.InsertItem ([Parent as HITEM], [UserData as Variant], [Value as Variant])

Inserts a new item, and returns a handle to the newly created item.

TypeDescription
Parent as HITEM A long expression that indicates the item's handle that indicates the parent item where the newly item is inserted
UserData as Variant A Variant expression that indicates the item's extra data. Use the ItemData property to retrieve later this value.
Value as Variant A Variant expression that indicates the cell's value on the first column, or a safe array that holds values for each column.
ReturnDescription
HITEMRetrieves the handle of the newly created item.

Use the InsertItem property to add a new child to an item. The InsertItem property fires the AddItem event. You can use the InsertItem(,,"Root") or AddItem("Root") to add a root item. An item that has no parent is a root item. To insert an ActiveX control, use the InsertControlItem property of the Items property.  Use the CellValue property to specify the values for cells in the second, third columns, and so on. Use the CellValueFormat property to specify whether the value contains HTML format or computed fields. The InsertItem method is not available if the control is running in the virtual mode. Use the LockedItemCount property to lock or unlock items to the top or bottom side of the control. Use the MergeCells method to combine one or more cells in a single cell. Use the SplitCell property to split a cell. If the CauseValidateValue property is True, the control fires the ValidateValue property when the user adds a new item. Use the ConditionalFormats method to apply formats to a cell or range of cells, and have that formatting change depending on the value of the cell or the value of a formula.

The following VB sample shows how to create a simple hierarchy ( few items and one column ):

With Grid1
    .BeginUpdate
    .ColumnAutoResize = True
    .LinesAtRoot = exLinesAtRoot
    .FullRowSelect = False
    .MarkSearchColumn = False
    .Columns.Add "Default"
    With .Items
        Dim h As HITEM, hx As HITEM
        h = .InsertItem(, , "Root")
        hx = .InsertItem(h, , "This is an item that should break the line")
        .CellSingleLine(hx, 0) = False
        h = .InsertItem(h, , "Child 2")
        .InsertItem h, , "SubChild 2.1"
        h = .InsertItem(h, , "SubChild 2.2")
    End With
    .EndUpdate
End With

The following VB sample insert items and multiple columns as well:

With Grid1
    .BeginUpdate
    .HeaderVisible = True
    .ColumnAutoResize = True
    .LinesAtRoot = exLinesAtRoot
    .FullRowSelect = False
    .MarkSearchColumn = False
    .Columns.Add "Column 1"
    .Columns.Add "Column 2"
    With .Items
        Dim h As HITEM, hx As HITEM
        h = .InsertItem(, , "Root")
        hx = .InsertItem(h, , Array("This is an item that should break the line", "Just another cell that holds some info"))
        .CellSingleLine(hx, 0) = False
        .CellSingleLine(hx, 1) = False
        h = .InsertItem(h, , "Child 2")
        .InsertItem h, , Array("SubChild 2.1", "SubItem 2.1")
        h = .InsertItem(h, , Array("SubChild 2.2", "SubItem 2.2"))
    End With
    .EndUpdate
End With

The following VB sample inserts a child item and expands the focused item:

With Grid1.Items
    .InsertItem .FocusItem, , "new child"
    .ExpandItem(.FocusItem) = True
End With

The following C++ sample inserts a child item and expands the focused item:

#include "Items.h"
CItems items = m_grid.GetItems();
COleVariant vtMissing; V_VT( &vtMissing ) = VT_ERROR;
long h = items.InsertItem( items.GetFocusItem(), vtMissing, COleVariant( "new child" ) );
items.SetExpandItem( items.GetFocusItem(), TRUE );

The following VB.NET sample inserts a child item and expands the focused item:

With AxGrid1.Items
    Dim hItem As Integer = .InsertItem(.FocusItem, , "new child")
    .ExpandItem(.FocusItem) = True
End With

The following C# sample inserts a child item and expands the focused item:

int hItem = axGrid1.Items.InsertItem(axGrid1.Items.FocusItem, null, "new child");
axGrid1.Items.set_ExpandItem(axGrid1.Items.FocusItem, true);

The following VFP sample inserts a child item and expands the focused item:

with thisform.Grid1.Items
	.DefaultItem = .InsertItem( .FocusItem, "", "new child" )
	.DefaultItem = .FocusItem
	.ExpandItem(0) = .t.
endwith