HeaderPane
Main
Hide
Share Link
Print

InsertString

Inserts a new item using a string.

C

LONG WINAPI SftBox_InsertString(HWND hwndCtl, LONG insertTC, LPCTSTR lpszText);

C++

LONG CSftBox::InsertString(LONG insertTC, LPCTSTR lpszText);

Parameters

hwndCtl

The window handle of the combo box control.

insertTC

The zero-based index of the location where the item is to be inserted. If -1 (or any value that is not the index of an existing item) is specified, the item will be added at the end of the list.

lpszText

Points to the null-terminated string that is to be used as text for the first (or only) column. This parameter may be NULL.

Returns

The return value is the zero-based index of the newly added item. The return value is -1 if an error occurred.

Comments

The InsertString function inserts a new item using a string.

By default, new items are added at level 0. Use SetItemLevel to change an item's level.

The combo box control creates a copy of the string supplied. The text of additional columns can be defined using SetText.

AddString can be used to add items at the end of the list.

If the dropdown portion of a dropdown or dropdown list combo box is currently shown, it is closed when InsertString is called. This can be suppressed using SetRollupOnChange.

The WM_SETREDRAW Windows message (CWnd::SetRedraw) can be used to suppress the combo box control from being redrawn when many items are added. The use of WM_SETREDRAW is strongly recommended when adding many items to the combo box control, as it avoids significant processing while items are added and drastically reduces the time needed to populate the combo box. WM_SETREDRAW (FALSE) should be used once, then all items should be added followed by one final WM_SETREDRAW (TRUE) message.

In a combo box control using a virtual data source, this function cannot be used and an error is returned.

Examples

C View entire sample code

    GetWindowText(hwndBox, szCity, sizeof(szCity) / sizeof(szCity[0]));
    if (!szCity[0])
        return;

    index = SftBox_FindStringExact(hwndBox, -1, 0, szCity, FALSE);
    if (index > 0)
        index = SftBox_MoveItem(hwndBox, index, 0);
    else if (index < 0) {
        index = SftBox_InsertString(hwndBox, 0, szCity);
        if (SftBox_GetCount(hwndBox) > MAX_HISTORY)
            SftBox_DeleteString(hwndBox, SftBox_GetCount(hwndBox) - 1);
    }
    SftBox_SetCurSel(hwndBox, index);
}

/**********************************************************************/

C++ View entire sample code

    m_City.GetWindowText(city);
    if (city.IsEmpty())
        return;

    index = m_City.FindStringExact(-1, 0, city, FALSE);
    if (index > 0)
        index = m_City.MoveItem(index, 0);
    else if (index < 0) {
        index = m_City.InsertString(0, city);
        if (m_City.GetCount() > MAX_HISTORY)
            m_City.DeleteString(m_City.GetCount() - 1);
    }
    m_City.SetCurSel(index);
}

void CMainDlg::OnOK()

See Also C/C++ API | Categories | Notifications


Last Updated 11/21/2026 - (email)
© 2026 Softel vdm, Inc.