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

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

TypeDescription
Parent as HITEM An long expression that indicates the handle of the parent item. The parent item must not be a locked item.
UserData as Variant A Variant expression that indicates the item's extra data.
Caption as Variant A Variant expression that indicates the item's caption. The Caption supports built-in HTML format if CellCaptionFormat property is exHTML.
ReturnDescription
HITEMRetrieves the handle of the newly created item.

Use the InsertItem method to insert child items. Use the AddItem method to add a new item. The InsertItem method fails, if the control contains no columns. Use the Add method to add new columns to the control. The InsertItem event is fired when a new item is inserted. The Parent parameter indicates the handle of the parent item. The UserData parameter indicates the item's user data. The Caption argument indicates the caption of the newly inserted item for the first column. Use the ItemPosition property to change the item's position. If the control has multiple columns use the CellCaption property to set caption for the rest of the columns. Use the PutItems method to load an array of elements. Use the ItemData property to retrieve the UserData parameter, after item is inserted. Use the LockedItemCount property to lock or unlock items to the top or bottom side of the control's list. Use the MergeCells method to combine two or more cells in a single cell. Use the ItemChild property to get the first child item. Use the ItemParent property to retrieve the handle of the parent item. Use the SelectableItem property to specify whether the user can select the item. Use the LinesAtRoot property to link items at the root of the hierarchy. The exComputedField type specifies a computed cell.

The following VB sample loads some items using safe arrays:

With ComboBox1
    .BeginUpdate
    
    .Columns.Add "Column 1"
    .Columns.Add "Column 2"
    .Columns.Add "Column 3"
    
    With .Items
        Dim h As HITEM
        h = .AddItem(Array("Item 1", "Item 2", "Item 3"))
        .InsertItem h, , Array(1, 2, 3)
        .ExpandItem(h) = True
    End With
    
    .EndUpdate
End With

  

The following VB sample adds items to a single column control:

With ComboBox1
    .BeginUpdate
    
    .ColumnAutoResize = True
    .HeaderVisible = False
    .LinesAtRoot = exLinesAtRoot
    .HasButtons = exCircle
    
    .Columns.Add "Column 1"
    
    With .Items
        Dim h As HITEM
        h = .AddItem("Item 1")
        .InsertItem h, , "Item 1.1"
        .InsertItem h, , "Item 1.2"
        .ExpandItem(h) = True
    End With
    
    .EndUpdate
End With

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

With ComboBox1.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_combobox.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 AxComboBox1.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 = axComboBox1.Items.InsertItem(axComboBox1.Items.FocusItem, null, "new child");
axComboBox1.Items.set_ExpandItem(axComboBox1.Items.FocusItem, true);

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

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