CComboBox Class

Provides the functionality of a Windows combo box.

class CComboBox : public CWnd

A combo box consists of a list box combined with either a static control or edit control. The list-box portion of the control may be displayed at all times or may only drop down when the user selects the drop-down arrow next to the control.

The currently selected item (if any) in the list box is displayed in the static or edit control. In addition, if the combo box has the drop-down list style, the user can type the initial character of one of the items in the list, and the list box, if visible, will highlight the next item with that initial character.

The following table compares the three combo-box styles.

You can create a CComboBox object from either a dialog template or directly in your code. In both cases, first call the constructor CComboBox to construct the CComboBox object; then call the Create member function to create the control and attach it to the CComboBox object.

If you want to handle Windows notification messages sent by a combo box to its parent (usually a class derived from CDialog), add a message-map entry and message-handler member function to the parent class for each message.

Each message-map entry takes the following form:

ON_Notification( id, memberFxn )

where id specifies the child-window ID of the combo-box control sending the notification and memberFxn is the name of the parent member function you have written to handle the notification.

The parent's function prototype is as follows:

afx_msg void memberFxn( );

The order in which certain notifications will be sent cannot be predicted. In particular, a CBN_SELCHANGE notification may occur either before or after a CBN_CLOSEUP notification.

Potential message-map entries are the following:

• ON_CBN_CLOSEUP (Windows 3.1 and later.) The list box of a combo box has closed. This notification message is not sent for a combo box that has the CBS_SIMPLE style.

• ON_CBN_DBLCLK The user double-clicks a string in the list box of a combo box. This notification message is only sent for a combo box with the CBS_SIMPLE style. For a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style, a double-click cannot occur because a single click hides the list box.

• ON_CBN_DROPDOWN The list box of a combo box is about to drop down (be made visible). This notification message can occur only for a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

• ON_CBN_EDITCHANGE The user has taken an action that may have altered the text in the edit-control portion of a combo box. Unlike the CBN_EDITUPDATE message, this message is sent after Windows updates the screen. It is not sent if the combo box has the CBS_DROPDOWNLIST style.

• ON_CBN_EDITUPDATE The edit-control portion of a combo box is about to display altered text. This notification message is sent after the control has formatted the text but before it displays the text. It is not sent if the combo box has the CBS_DROPDOWNLIST style.

• ON_CBN_ERRSPACE The combo box cannot allocate enough memory to meet a specific request.

• ON_CBN_SELENDCANCEL (Windows 3.1 and later.) Indicates the user's selection should be canceled. The user clicks an item and then clicks another window or control to hide the list box of a combo box. This notification message is sent before the CBN_CLOSEUP notification message to indicate that the user's selection should be ignored. The CBN_SELENDCANCEL or CBN_SELENDOK notification message is sent even if the CBN_CLOSEUP notification message is not sent (as in the case of a combo box with the CBS_SIMPLE style).

• ON_CBN_SELENDOK The user selects an item and then either presses the ENTER key or clicks the DOWN ARROW key to hide the list box of a combo box. This notification message is sent before the CBN_CLOSEUP message to indicate that the user's selection should be considered valid. The CBN_SELENDCANCEL or CBN_SELENDOK notification message is sent even if the CBN_CLOSEUP notification message is not sent (as in the case of a combo box with the CBS_SIMPLE style).

• ON_CBN_KILLFOCUS The combo box is losing the input focus.

• ON_CBN_SELCHANGE The selection in the list box of a combo box is about to be changed as a result of the user either clicking in the list box or changing the selection by using the arrow keys. When processing this message, the text in the edit control of the combo box can only be retrieved via GetLBText or another similar function. GetWindowText cannot be used.

• ON_CBN_SETFOCUS The combo box receives the input focus.

If you create a CComboBox object within a dialog box (through a dialog resource), the CComboBox object is automatically destroyed when the user closes the dialog box.

If you embed a CComboBox object within another window object, you do not need to destroy it. If you create the CComboBox object on the stack, it is destroyed automatically. If you create the CComboBox object on the heap by using the new function, you must call delete on the object to destroy it when the Windows combo box is destroyed.

Note If you want to handle WM_KEYDOWN and WM_CHAR messages, you have to subclass the combo box's edit and list box controls, derive classes from CEdit and CListBox, and add handlers for those messages to the derived classes. For more information, see CWnd::SubclassWindow.

CObject

CCmdTarget

CWnd

CComboBox

Header: afxwin.h

Adds a string to the list box of a combo box.

int AddString(LPCTSTR lpszString);

lpszString
Points to the null-terminated string that is to be added.

If the return value is greater than or equal to 0, it is the zero-based index to the string in the list box. The return value is CB_ERR if an error occurs; the return value is CB_ERRSPACE if insufficient space is available to store the new string.

If the list box was not created with the CBS_SORT style, the string is added to the end of the list. Otherwise, the string is inserted into the list, and the list is sorted.

To insert a string into a specific location within the list, use the InsertString member function.

// Add 20 items to the combo box.
CString str;
for (int i = 0; i < 20; i++)
{
   str.Format(_T("item string %d"), i);
   m_pComboBox->AddString(str);
}

Constructs a CComboBox object.

CComboBox();

// Declare a local CComboBox object.
CComboBox myComboBox;

// Declare a dynamic CComboBox object.
CComboBox *pmyComboBox = new CComboBox;

Deletes (clears) the current selection, if any, in the edit control of the combo box.

void Clear();

To delete the current selection and place the deleted contents onto the Clipboard, use the Cut member function.

// Delete all of the text from the combo box's edit control.
m_MyComboBox.SetEditSel(0, -1);
m_MyComboBox.Clear();

Called by the framework to determine the relative position of a new item in the list-box portion of a sorted owner-draw combo box.

virtual int CompareItem(LPCOMPAREITEMSTRUCT lpCompareItemStruct);

lpCompareItemStruct
A long pointer to a COMPAREITEMSTRUCT structure.

Indicates the relative position of the two items described in the COMPAREITEMSTRUCT structure. It can be any of the following values:

See CWnd::OnCompareItem for a description of COMPAREITEMSTRUCT.

By default, this member function does nothing. If you create an owner-draw combo box with the LBS_SORT style, you must override this member function to assist the framework in sorting new items added to the list box.

// CMyComboBox is my owner-drawn combo box derived from CComboBox. This
// example compares two items using strcmp to sort items in reverse
// alphabetical order. The combo box control was created with the
// following code:
//   pmyComboBox->Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      CBS_SORT|CBS_OWNERDRAWVARIABLE,
//      myRect, pParentWnd, 1);
//
int CMyComboBox::CompareItem(LPCOMPAREITEMSTRUCT lpCompareItemStruct)
{
   int iComp = 0;
   ASSERT(lpCompareItemStruct->CtlType == ODT_COMBOBOX);
   LPCTSTR lpszText1 = (LPCTSTR)lpCompareItemStruct->itemData1;
   ASSERT(lpszText1 != NULL);
   LPCTSTR lpszText2 = (LPCTSTR)lpCompareItemStruct->itemData2;
   ASSERT(lpszText2 != NULL);

   if (NULL != lpszText1 && NULL != lpszText2)
   {
      iComp = _tcscmp(lpszText2, lpszText1);
   }

   return iComp;
}

Copies the current selection, if any, in the edit control of the combo box onto the Clipboard in CF_TEXT format.

void Copy();

// Copy all of the text from the combo box's edit control
// to the clipboard.
m_MyComboBox.SetEditSel(0, -1);
m_MyComboBox.Copy();

Creates the combo box and attaches it to the CComboBox object.

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

dwStyle
Specifies the style of the combo box. Apply any combination of combo-box styles to the box.

rect
Points to the position and size of the combo box. Can be a RECT structure or a CRect object.

pParentWnd
Specifies the combo box's parent window (usually a CDialog). It must not be NULL.

nID
Specifies the combo box's control ID.

Nonzero if successful; otherwise 0.

You construct a CComboBox object in two steps. First, call the constructor and then call Create, which creates the Windows combo box and attaches it to the CComboBox object.

When Create executes, Windows sends the WM_NCCREATE, WM_CREATE, WM_NCCALCSIZE, and WM_GETMINMAXINFO messages to the combo box.

These messages are handled by default by the OnNcCreate, OnCreate, OnNcCalcSize, and OnGetMinMaxInfo member functions in the CWnd base class. To extend the default message handling, derive a class from CComboBox, add a message map to the new class, and override the preceding message-handler member functions. Override OnCreate, for example, to perform needed initialization for a new class.

Apply the following window styles to a combo-box control. :

• WS_CHILD Always

• WS_VISIBLE Usually

• WS_DISABLED Rarely

• WS_VSCROLL To add vertical scrolling for the list box in the combo box

• WS_HSCROLL To add horizontal scrolling for the list box in the combo box

• WS_GROUP To group controls

• WS_TABSTOP To include the combo box in the tabbing order

m_pComboBox->Create(
    WS_CHILD | WS_VISIBLE | WS_VSCROLL | CBS_DROPDOWNLIST,
    CRect(10, 10, 200, 100), pParentWnd, 1);

Deletes (cuts) the current selection, if any, in the combo-box edit control and copies the deleted text onto the Clipboard in CF_TEXT format.

void Cut();

To delete the current selection without placing the deleted text onto the Clipboard, call the Clear member function.

// Delete all of the text from the combo box's edit control and copy it
// to the clipboard.
m_MyComboBox.SetEditSel(0, -1);
m_MyComboBox.Cut();

Called by the framework when the user deletes an item from an owner-draw CComboBox object or destroys the combo box.

virtual void DeleteItem(LPDELETEITEMSTRUCT lpDeleteItemStruct);

lpDeleteItemStruct
A long pointer to a Windows DELETEITEMSTRUCT structure that contains information about the deleted item. See CWnd::OnDeleteItem for a description of this structure.

The default implementation of this function does nothing. Override this function to redraw the combo box as needed.

// CMyComboBox is my owner-drawn combo box derived from CComboBox. This
// example simply dumps the item's text. The combo box control was
// created with the following code:
//   pmyComboBox->Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      CBS_SORT|CBS_OWNERDRAWVARIABLE,
//      myRect, pParentWnd, 1);
//
void CMyComboBox::DeleteItem(LPDELETEITEMSTRUCT lpDeleteItemStruct)
{
   ASSERT(lpDeleteItemStruct->CtlType == ODT_COMBOBOX);
   LPTSTR lpszText = (LPTSTR)lpDeleteItemStruct->itemData;
   ASSERT(lpszText != NULL);

   AFXDUMP(lpszText);
}

Deletes the item in position nIndex from the combo box.

int DeleteString(UINT nIndex);

nIndex
Specifies the index to the string that is to be deleted.

If the return value is greater than or equal to 0, then it is a count of the strings remaining in the list. The return value is CB_ERR if nIndex specifies an index greater than the number of items in the list.

All items following nIndex now move down one position. For example, if a combo box contains two items, deleting the first item will cause the remaining item to now be in the first position. nIndex=0 for the item in the first position.

// Delete every item from the combo box.
for (int i = m_pComboBox->GetCount() - 1; i >= 0; i--)
{
   m_pComboBox->DeleteString(i);
}

Adds a list of filenames or drives to the list box of a combo box.

int Dir(
    UINT attr,
    LPCTSTR lpszWildCard);

attr
Can be any combination of the enum values described in CFile::GetStatus or any combination of the following values:

• DDL_READWRITE File can be read from or written to.

• DDL_READONLY File can be read from but not written to.

• DDL_HIDDEN File is hidden and does not appear in a directory listing.

• DDL_SYSTEM File is a system file.

• DDL_DIRECTORY The name specified by lpszWildCard specifies a directory.

• DDL_ARCHIVE File has been archived.

• DDL_DRIVES Include all drives that match the name specified by lpszWildCard.

• DDL_EXCLUSIVE Exclusive flag. If the exclusive flag is set, only files of the specified type are listed. Otherwise, files of the specified type are listed in addition to "normal" files.

lpszWildCard
Points to a file-specification string. The string can contain wildcards (for example, *.*).

If the return value is greater than or equal to 0, it is the zero-based index of the last filename added to the list. The return value is CB_ERR if an error occurs; the return value is CB_ERRSPACE if insufficient space is available to store the new strings.

This function is not supported by the Windows ComboBoxEx control. For more information on this control, see ComboBoxEx Controls in the Windows SDK.

// Add all the files and directories in the windows directory.
TCHAR lpszWinPath[MAX_PATH], lpszOldPath[MAX_PATH];
VERIFY(0 < ::GetWindowsDirectory(lpszWinPath, MAX_PATH));

// Make the windows directory the current directory.
::GetCurrentDirectory(MAX_PATH, lpszOldPath);
::SetCurrentDirectory(lpszWinPath);

m_pComboBox->ResetContent();
m_pComboBox->Dir(DDL_READWRITE | DDL_DIRECTORY, _T("*.*"));

// Reset the current directory to its previous path.
::SetCurrentDirectory(lpszOldPath);

Called by the framework when a visual aspect of an owner-draw combo box changes.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

lpDrawItemStruct
A pointer to a DRAWITEMSTRUCT structure that contains information about the type of drawing required.

The itemAction member of the DRAWITEMSTRUCT structure defines the drawing action that is to be performed. See CWnd::OnDrawItem for a description of this structure.

By default, this member function does nothing. Override this member function to implement drawing for an owner-draw CComboBox object. Before this member function terminates, the application should restore all graphics device interface (GDI) objects selected for the display context supplied in lpDrawItemStruct.

// CMyComboBox is my owner-drawn combo box derived from CComboBox. This
// example draws an item's text centered vertically and horizontally. The
// combo box control was created with the following code:
//   pmyComboBox->Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      CBS_SORT|CBS_OWNERDRAWVARIABLE,
//      myRect, pParentWnd, 1);
//
void CMyComboBox::DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct)
{
   ASSERT(lpDrawItemStruct->CtlType == ODT_COMBOBOX);
   LPCTSTR lpszText = (LPCTSTR)lpDrawItemStruct->itemData;
   ASSERT(lpszText != NULL);
   CDC dc;

   dc.Attach(lpDrawItemStruct->hDC);

   // Save these value to restore them when done drawing.
   COLORREF crOldTextColor = dc.GetTextColor();
   COLORREF crOldBkColor = dc.GetBkColor();

   // If this item is selected, set the background color
   // and the text color to appropriate values. Erase
   // the rect by filling it with the background color.
   if ((lpDrawItemStruct->itemAction & ODA_SELECT) &&
       (lpDrawItemStruct->itemState & ODS_SELECTED))
   {
      dc.SetTextColor(::GetSysColor(COLOR_HIGHLIGHTTEXT));
      dc.SetBkColor(::GetSysColor(COLOR_HIGHLIGHT));
      dc.FillSolidRect(&lpDrawItemStruct->rcItem, ::GetSysColor(COLOR_HIGHLIGHT));
   }
   else
   {
      dc.FillSolidRect(&lpDrawItemStruct->rcItem, crOldBkColor);
   }

   // Draw the text.
   dc.DrawText(
       lpszText,
       (int)_tcslen(lpszText),
       &lpDrawItemStruct->rcItem,
       DT_CENTER | DT_SINGLELINE | DT_VCENTER);

   // Reset the background color and the text color back to their
   // original values.
   dc.SetTextColor(crOldTextColor);
   dc.SetBkColor(crOldBkColor);

   dc.Detach();
}

Finds, but doesn't select, the first string that contains the specified prefix in the list box of a combo box.

int FindString(
    int nStartAfter,
    LPCTSTR lpszString) const;

nStartAfter
Contains the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by nStartAfter. If -1, the entire list box is searched from the beginning.

lpszString
Points to the null-terminated string that contains the prefix to search for. The search is case independent, so this string can contain any combination of uppercase and lowercase letters.

If the return value is greater than or equal to 0, it is the zero-based index of the matching item. It is CB_ERR if the search was unsuccessful.

This function is not supported by the Windows ComboBoxEx control. For more information on this control, see ComboBoxEx Controls in the Windows SDK.

// The string to match.
LPCTSTR lpszmyString = _T("item");

// Delete all items that begin with the specified string.
int nItem = 0;
while ((nItem = m_pComboBox->FindString(nItem, lpszmyString)) != CB_ERR)
{
   m_pComboBox->DeleteString(nItem);
}

Call the FindStringExact member function to find the first list-box string (in a combo box) that matches the string specified in lpszFind.

int FindStringExact(
    int nIndexStart,
    LPCTSTR lpszFind) const;

nIndexStart
Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by nIndexStart. If nIndexStart is -1, the entire list box is searched from the beginning.

lpszFind
Points to the null-terminated string to search for. This string can contain a complete filename, including the extension. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

The zero-based index of the matching item, or CB_ERR if the search was unsuccessful.

If the combo box was created with an owner-draw style but without the CBS_HASSTRINGS style, FindStringExact attempts to match the doubleword value against the value of lpszFind.

// The string to match.
LPCTSTR lpszmyExactString = _T("item 5");

// Delete all items that exactly match the specified string.
int nDex = 0;
while ((nDex = m_pComboBox->FindStringExact(nDex, lpszmyExactString)) != CB_ERR)
{
   m_pComboBox->DeleteString(nDex);
}

Retrieves information for the CComboBox object.

BOOL GetComboBoxInfo(PCOMBOBOXINFO pcbi) const;

*pcbi*<br/> A pointer to the [COMBOBOXINFO`](/windows/win32/api/winuser/ns-winuser-comboboxinfo) structure.

Returns TRUE on success, FALSE on failure.

This member function emulates the functionality of the CB_GETCOMBOBOXINFO message, as described in the Windows SDK.

Call this member function to retrieve the number of items in the list-box portion of a combo box.

int GetCount() const;

The number of items. The returned count is one greater than the index value of the last item (the index is zero-based). It is CB_ERR if an error occurs.

// Add 10 items to the combo box.
CString strItem;
for (int i = 0; i < 10; i++)
{
   strItem.Format(_T("item %d"), i);
   m_pComboBox->AddString(strItem);
}

// Verify the 10 items were added to the combo box.
ASSERT(m_pComboBox->GetCount() == 10);

Gets the cue text that is displayed for a combo box control.

CString GetCueBanner() const;

BOOL GetCueBanner(
    LPTSTR lpszText,
    int cchText) const;

lpszText
[out] Pointer to a buffer that receives the cue banner text.

cchText
[in] Size of the buffer that the lpszText parameter points to.

In the first overload, a CString object that contains the cue banner text if it exists; otherwise, a CString object that has zero length.

-or-

In the second overload, TRUE if this method is successful; otherwise, FALSE.

Cue text is a prompt that is displayed in the input area of the combo box control. The cue text is displayed until the user provides input.

This method sends the CB_GETCUEBANNER message, which is described in the Windows SDK.

Call this member function to determine which item in the combo box is selected.

int GetCurSel() const;

The zero-based index of the currently selected item in the list box of a combo box, or CB_ERR if no item is selected.

GetCurSel returns an index into the list.

// Select the next item of the currently selected item
// in the combo box.
int nIndex = m_pComboBox->GetCurSel();
int nCount = m_pComboBox->GetCount();
if ((nIndex != CB_ERR) && (nCount > 1))
{
   if (++nIndex < nCount)
      m_pComboBox->SetCurSel(nIndex);
   else
      m_pComboBox->SetCurSel(0);
}

Call the GetDroppedControlRect member function to retrieve the screen coordinates of the visible (dropped-down) list box of a drop-down combo box.

void GetDroppedControlRect(LPRECT lprect) const;

lprect
Points to the RECT structure that is to receive the coordinates.

// This example move a combo box so that the upper left
// corner of the combo box is at a specific point.

// The point to move the combo box to.
CPoint myPoint(30, 10);

CRect r;

m_pComboBox->GetDroppedControlRect(&r);

m_pComboBox->GetParent()->ScreenToClient(&r);
r.OffsetRect(myPoint - r.TopLeft());
m_pComboBox->MoveWindow(&r);

Call the GetDroppedState member function to determine whether the list box of a drop-down combo box is visible (dropped down).

BOOL GetDroppedState() const;

Nonzero if the list box is visible; otherwise 0.

// Show the dropdown list box if it is not already dropped.
if (!m_pComboBox->GetDroppedState())
   m_pComboBox->ShowDropDown(TRUE);

Call this function to retrieve the minimum allowable width, in pixels, of the list box of a combo box.

int GetDroppedWidth() const;

If successful, the minimum allowable width, in pixels; otherwise, CB_ERR.

This function only applies to combo boxes with the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

By default, the minimum allowable width of the drop-down list box is 0. The minimum allowable width can be set by calling SetDroppedWidth. When the list-box portion of the combo box is displayed, its width is the larger of the minimum allowable width or the combo box width.

See the example for SetDroppedWidth.

Gets the starting and ending character positions of the current selection in the edit control of a combo box.

DWORD GetEditSel() const;

A 32-bit value that contains the starting position in the low-order word and the position of the first nonselected character after the end of the selection in the high-order word. If this function is used on a combo box without an edit control, CB_ERR is returned.

DWORD dwSel;

// Set the selection to be all characters after the current selection.
if ((dwSel = m_MyComboBox.GetEditSel()) != CB_ERR)
{
   m_MyComboBox.SetEditSel(HIWORD(dwSel), -1);
}

Call the GetExtendedUI member function to determine whether a combo box has the default user interface or the extended user interface.

BOOL GetExtendedUI() const;

Nonzero if the combo box has the extended user interface; otherwise 0.

The extended user interface can be identified in the following ways:

• Clicking the static control displays the list box only for combo boxes with the CBS_DROPDOWNLIST style.

• Pressing the DOWN ARROW key displays the list box (F4 is disabled).

Scrolling in the static control is disabled when the item list is not visible (arrow keys are disabled).

// Use the extended UI if it is not already set.
if (!m_pComboBox->GetExtendedUI())
   m_pComboBox->SetExtendedUI(TRUE);

Retrieves from the combo box the width in pixels by which the list-box portion of the combo box can be scrolled horizontally.

UINT GetHorizontalExtent() const;

The scrollable width of the list-box portion of the combo box, in pixels.

This is applicable only if the list-box portion of the combo box has a horizontal scroll bar.

// Find the longest string in the combo box.
CString strText;
CSize sz;
UINT dxText = 0;
CDC *pDCCombo = m_pComboBox->GetDC();
for (int i = 0; i < m_pComboBox->GetCount(); i++)
{
   m_pComboBox->GetLBText(i, strText);
   sz = pDCCombo->GetTextExtent(strText);

   if (sz.cx > (LONG)dxText)
      dxText = sz.cx;
}
m_pComboBox->ReleaseDC(pDCCombo);

// Set the horizontal extent only if the current extent is not large enough.
if (m_pComboBox->GetHorizontalExtent() < dxText)
{
   m_pComboBox->SetHorizontalExtent(dxText);
   ASSERT(m_pComboBox->GetHorizontalExtent() == dxText);
}

Retrieves the application-supplied 32-bit value associated with the specified combo-box item.

DWORD_PTR GetItemData(int nIndex) const;

nIndex
Contains the zero-based index of an item in the combo box's list box.

The 32-bit value associated with the item, or CB_ERR if an error occurs.

The 32-bit value can be set with the dwItemData parameter of a SetItemData member function call. Use the GetItemDataPtr member function if the 32-bit value to be retrieved is a pointer (void *).

// If any item's data is equal to zero then reset it to -1.
for (int i = 0; i < m_pComboBox->GetCount(); i++)
{
   if (m_pComboBox->GetItemData(i) == 0)
   {
      m_pComboBox->SetItemData(i, (DWORD)-1);
   }
}

Retrieves the application-supplied 32-bit value associated with the specified combo-box item as a pointer (void *).

void* GetItemDataPtr(int nIndex) const;

nIndex
Contains the zero-based index of an item in the combo box's list box.

Retrieves a pointer, or -1 if an error occurs.

LPVOID lpmyPtr = m_pComboBox->GetItemDataPtr(5);

// Check all the items in the combo box; if an item's
// data pointer is equal to my pointer then reset it to NULL.
for (int i = 0; i < m_pComboBox->GetCount(); i++)
{
   if (m_pComboBox->GetItemDataPtr(i) == lpmyPtr)
   {
      m_pComboBox->SetItemDataPtr(i, NULL);
   }
}

Call the GetItemHeight member function to retrieve the height of list items in a combo box.

int GetItemHeight(int nIndex) const;

nIndex
Specifies the component of the combo box whose height is to be retrieved. If the nIndex parameter is -1, the height of the edit-control (or static-text) portion of the combo box is retrieved. If the combo box has the CBS_OWNERDRAWVARIABLE style, nIndex specifies the zero-based index of the list item whose height is to be retrieved. Otherwise, nIndex should be set to 0.

The height, in pixels, of the specified item in a combo box. The return value is CB_ERR if an error occurs.

// Set the height of every item so the item
// is completely visible.
CString strLBText;
CSize size;
CDC *pDC = m_pComboBox->GetDC();
for (int i = 0; i < m_pComboBox->GetCount(); i++)
{
   m_pComboBox->GetLBText(i, strLBText);
   size = pDC->GetTextExtent(strLBText);

   // Only want to set the item height if the current height
   // is not big enough.
   if (m_pComboBox->GetItemHeight(i) < size.cy)
      m_pComboBox->SetItemHeight(i, size.cy);
}
m_pComboBox->ReleaseDC(pDC);

Gets a string from the list box of a combo box.

int GetLBText(
    int nIndex,
    LPTSTR lpszText) const;

void GetLBText(
    int nIndex,
    CString& rString) const;

nIndex
Contains the zero-based index of the list-box string to be copied.

lpszText
Points to a buffer that is to receive the string. The buffer must have sufficient space for the string and a terminating null character.

rString
A reference to a CString.

The length (in bytes) of the string, excluding the terminating null character. If nIndex does not specify a valid index, the return value is CB_ERR.

The second form of this member function fills a CString object with the item's text.
If nIndex is invalid, this function throws an E_INVALIDARG exception (error code: -2147024809, 0x80070057).

// Dump all of the items in the combo box.
CString str1, str2;
int n;
for (int i = 0; i < m_pComboBox->GetCount(); i++)
{
   n = m_pComboBox->GetLBTextLen(i);
   m_pComboBox->GetLBText(i, str1.GetBuffer(n));
   str1.ReleaseBuffer();

   str2.Format(_T("item %d: %s\r\n"), i, str1.GetBuffer(0));
   AFXDUMP(str2);
}

Gets the length of a string in the list box of a combo box.

int GetLBTextLen(int nIndex) const;

nIndex
Contains the zero-based index of the list-box string.

The length of the string in bytes, excluding the terminating null character. If nIndex does not specify a valid index, the return value is CB_ERR.

See the example for CComboBox::GetLBText.

Retrieves the locale used by the combo box.

LCID GetLocale() const;

The locale identifier (LCID) value for the strings in the combo box.

The locale is used, for example, to determine the sort order of the strings in a sorted combo box.

See the example for CComboBox::SetLocale.

Gets the minimum number of visible items in the drop-down list of the current combo box control.

int GetMinVisible() const;

The minimum number of visible items in the current drop-down list.

This method sends the CB_GETMINVISIBLE message, which is described in the Windows SDK.

Retrieves the zero-based index of the first visible item in the list-box portion of the combo box.

int GetTopIndex() const;

The zero-based index of the first visible item in the list-box portion of the combo box if successful, CB_ERR otherwise.

Initially, item 0 is at the top of the list box, but if the list box is scrolled, another item may be at the top.

// Want an item in the bottom half to be the first visible item.
int nTop = m_pComboBox->GetCount() / 2;
if (m_pComboBox->GetTopIndex() < nTop)
{
   m_pComboBox->SetTopIndex(nTop);
   ASSERT(m_pComboBox->GetTopIndex() == nTop);
}

Allocates memory for storing list box items in the list-box portion of the combo box.

int InitStorage(
    int nItems,
    UINT nBytes);

nItems
Specifies the number of items to add.

nBytes
Specifies the amount of memory, in bytes, to allocate for item strings.

If successful, the maximum number of items that the list-box portion of the combo box can store before a memory reallocation is needed, otherwise CB_ERRSPACE, meaning not enough memory is available.

Call this function before adding a large number of items to the list-box portion of the CComboBox.

Windows 95/98 only: The wParam parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size of the items in a list box is limited only by available memory.

This function helps speed up the initialization of list boxes that have a large number of items (more than 100). It preallocates the specified amount of memory so that subsequent AddString, InsertString, and Dir functions take the shortest possible time. You can use estimates for the parameters. If you overestimate, some extra memory is allocated; if you underestimate, the normal allocation is used for items that exceed the preallocated amount.

// Initialize the storage of the combo box to be 256 strings with
// about 10 characters per string, performance improvement.
int nAlloc = pmyComboBox->InitStorage(256, 10);
ASSERT(nAlloc != CB_ERRSPACE);

// Add 256 items to the combo box.
CString strAdd;
for (int i = 0; i < 256; i++)
{
   strAdd.Format(_T("item string %d"), i);
   m_pComboBox->AddString(strAdd);
}

Inserts a string into the list box of a combo box.

int InsertString(
    int nIndex,
    LPCTSTR lpszString);

nIndex
Contains the zero-based index to the position in the list box that will receive the string. If this parameter is -1, the string is added to the end of the list.

lpszString
Points to the null-terminated string that is to be inserted.

The zero-based index of the position at which the string was inserted. The return value is CB_ERR if an error occurs. The return value is CB_ERRSPACE if insufficient space is available to store the new string.

Unlike the AddString member function, the InsertString member function does not cause a list with the CBS_SORT style to be sorted.

// Insert items in between existing items.
CString strIns;
int nItems = m_pComboBox->GetCount();
for (int i = 0; i < nItems; i++)
{
   strIns.Format(_T("item string %c"), (char)('A' + i));
   m_pComboBox->InsertString(2 * i, strIns);
}

Limits the length in bytes of the text that the user can enter into the edit control of a combo box.

BOOL LimitText(int nMaxChars);

nMaxChars
Specifies the length (in bytes) of the text that the user can enter. If this parameter is 0, the text length is set to 65,535 bytes.

Nonzero if successful. If called for a combo box with the style CBS_DROPDOWNLIST or for a combo box without an edit control, the return value is CB_ERR.

If the combo box does not have the style CBS_AUTOHSCROLL, setting the text limit to be larger than the size of the edit control will have no effect.

LimitText only limits the text the user can enter. It has no effect on any text already in the edit control when the message is sent, nor does it affect the length of the text copied to the edit control when a string in the list box is selected.

// Limit the number of characters in the combo box's edit control to
// be the maximum number visible.

// Get the text metrics for the combo box; needed for the
// average character width.
TEXTMETRIC tm;
CDC *pDCCB = m_pComboBox->GetDC();
pDCCB->GetTextMetrics(&tm);
m_pComboBox->ReleaseDC(pDCCB);

CRect rect;
m_pComboBox->GetClientRect(&rect);

m_pComboBox->LimitText(rect.Width() / tm.tmAveCharWidth);

Called by the framework when a combo box with an owner-draw style is created.

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

lpMeasureItemStruct
A long pointer to a MEASUREITEMSTRUCT structure.

By default, this member function does nothing. Override this member function and fill in the MEASUREITEMSTRUCT structure to inform Windows of the dimensions of the list box in the combo box. If the combo box is created with the CBS_OWNERDRAWVARIABLE style, the framework calls this member function for each item in the list box. Otherwise, this member is called only once.

Using the CBS_OWNERDRAWFIXED style in an owner-draw combo box created with the SubclassDlgItem member function of CWnd involves further programming considerations. See the discussion in Technical Note 14.

See CWnd::OnMeasureItem for a description of the MEASUREITEMSTRUCT structure.

// CMyComboBox is my owner-drawn combo box derived from CComboBox. This
// example measures an item and sets the height of the item to twice the
// vertical extent of its text. The combo box control was created with
// the following code:
//   pmyComboBox->Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      CBS_SORT|CBS_OWNERDRAWVARIABLE,
//      myRect, pParentWnd, 1);
//
void CMyComboBox::MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct)
{
   ASSERT(lpMeasureItemStruct->CtlType == ODT_COMBOBOX);

   if (lpMeasureItemStruct->itemID != (UINT)-1)
   {
      LPCTSTR lpszText = (LPCTSTR)lpMeasureItemStruct->itemData;
      ASSERT(lpszText != NULL);
      CSize sz;
      CDC *pDC = GetDC();

      sz = pDC->GetTextExtent(lpszText);

      ReleaseDC(pDC);

      lpMeasureItemStruct->itemHeight = 2 * sz.cy;
   }
}

Inserts the data from the Clipboard into the edit control of the combo box at the current cursor position.

void Paste();

Data is inserted only if the Clipboard contains data in CF_TEXT format.

// Replace all of the text in the combo box's edit control with the text
// in the clipboard.
m_MyComboBox.SetEditSel(0, -1);
m_MyComboBox.Paste();

Removes all items from the list box and edit control of a combo box.

void ResetContent();

// Delete all the items from the combo box.
m_pComboBox->ResetContent();
ASSERT(m_pComboBox->GetCount() == 0);

Searches for a string in the list box of a combo box, and if the string is found, selects the string in the list box and copies it to the edit control.

int SelectString(
    int nStartAfter,
    LPCTSTR lpszString);

nStartAfter
Contains the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by nStartAfter. If -1, the entire list box is searched from the beginning.

lpszString
Points to the null-terminated string that contains the prefix to search for. The search is case independent, so this string can contain any combination of uppercase and lowercase letters.

The zero-based index of the selected item if the string was found. If the search was unsuccessful, the return value is CB_ERR and the current selection is not changed.

A string is selected only if its initial characters (from the starting point) match the characters in the prefix string.

Note that the SelectString and FindString member functions both find a string, but the SelectString member function also selects the string.

// The string to match.
LPCTSTR lpszSelect = _T("item");

// Select the item that begins with the specified string.
int nSel = m_pComboBox->SelectString(0, lpszSelect);
ASSERT(nSel != CB_ERR);

Sets the cue text that is displayed for a combo box control.

BOOL SetCueBanner(LPCTSTR lpszText);

lpszText
[in] Pointer to a null-terminated buffer that contains the cue text.

TRUE if the method is successful; otherwise, FALSE.

Cue text is a prompt that is displayed in the input area of the combo box control. The cue text is displayed until the user provides input.

This method sends the CB_SETCUEBANNER message, which is described in the Windows SDK.

The first code example defines the variable, m_combobox, that is used to programmatically access the combo box control. This variable is used in the next example.

// Variable to access the combo box control
CComboBox m_combobox;

The next code example sets the cue banner for the combo box control.

// Add extra initialization here.

// Add 20 items to the combo box. The Resource Editor
// has already been used to set the style of the combo
// box to CBS_SORT.
CString str;
for (int i = 1; i <= 20; i++)
{
    str.Format(_T("Item %2d"), i);
    m_combobox.AddString(str);
}
// Set the minimum visible item
m_combobox.SetMinVisibleItems(10);
// Set the cue banner
m_combobox.SetCueBanner(_T("Select an item..."));

// End of extra initialization.

Selects a string in the list box of a combo box.

int SetCurSel(int nSelect);

nSelect
Specifies the zero-based index of the string to select. If -1, any current selection in the list box is removed and the edit control is cleared.

The zero-based index of the item selected if the message is successful. The return value is CB_ERR if nSelect is greater than the number of items in the list or if nSelect is set to -1, which clears the selection.

If necessary, the list box scrolls the string into view (if the list box is visible). The text in the edit control of the combo box is changed to reflect the new selection. Any previous selection in the list box is removed.

// Select the last item in the combo box.
int nLast = pmyComboBox->GetCount() - 1;
if (nLast >= 0)
   m_pComboBox->SetCurSel(nLast);

Call this function to set the minimum allowable width, in pixels, of the list box of a combo box.

int SetDroppedWidth(UINT nWidth);

nWidth
The minimum allowable width of the list-box portion of the combo box, in pixels.

If successful, the new width of the list box, otherwise CB_ERR.

This function only applies to combo boxes with the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

By default, the minimum allowable width of the drop-down list box is 0. When the list-box portion of the combo box is displayed, its width is the larger of the minimum allowable width or the combo box width.

// Find the longest string in the combo box.
CString str;
CSize sz;
int dx = 0;
TEXTMETRIC tm;
CDC *pDC = m_pComboBox->GetDC();
CFont *pFont = m_pComboBox->GetFont();

// Select the listbox font, save the old font
CFont *pOldFont = pDC->SelectObject(pFont);
// Get the text metrics for avg char width
pDC->GetTextMetrics(&tm);

for (int i = 0; i < m_pComboBox->GetCount(); i++)
{
   m_pComboBox->GetLBText(i, str);
   sz = pDC->GetTextExtent(str);

   // Add the avg width to prevent clipping
   sz.cx += tm.tmAveCharWidth;

   if (sz.cx > dx)
      dx = sz.cx;
}
// Select the old font back into the DC
pDC->SelectObject(pOldFont);
m_pComboBox->ReleaseDC(pDC);

// Adjust the width for the vertical scroll bar and the left and right border.
dx += ::GetSystemMetrics(SM_CXVSCROLL) + 2 * ::GetSystemMetrics(SM_CXEDGE);

// Set the width of the list box so that every item is completely visible.
m_pComboBox->SetDroppedWidth(dx);

Selects characters in the edit control of a combo box.

BOOL SetEditSel(
    int nStartChar,
    int nEndChar);

nStartChar
Specifies the starting position. If the starting position is set to -1, then any existing selection is removed.

nEndChar
Specifies the ending position. If the ending position is set to -1, then all text from the starting position to the last character in the edit control is selected.

Nonzero if the member function is successful; otherwise 0. It is CB_ERR if CComboBox has the CBS_DROPDOWNLIST style or does not have a list box.

The positions are zero-based. To select the first character of the edit control, you specify a starting position of 0. The ending position is for the character just after the last character to select. For example, to select the first four characters of the edit control, you would use a starting position of 0 and an ending position of 4.

See the example for CComboBox::GetEditSel.

Call the SetExtendedUI member function to select either the default user interface or the extended user interface for a combo box that has the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

int SetExtendedUI(BOOL bExtended = TRUE);

bExtended
Specifies whether the combo box should use the extended user interface or the default user interface. A value of TRUE selects the extended user interface; a value of FALSE selects the standard user interface.

CB_OKAY if the operation is successful, or CB_ERR if an error occurs.

The extended user interface can be identified in the following ways:

• Clicking the static control displays the list box only for combo boxes with the CBS_DROPDOWNLIST style.

• Pressing the DOWN ARROW key displays the list box (F4 is disabled).

Scrolling in the static control is disabled when the item list is not visible (the arrow keys are disabled).

See the example for CComboBox::GetExtendedUI.

Sets the width, in pixels, by which the list-box portion of the combo box can be scrolled horizontally.

void SetHorizontalExtent(UINT nExtent);

nExtent
Specifies the number of pixels by which the list-box portion of the combo box can be scrolled horizontally.

If the width of the list box is smaller than this value, the horizontal scroll bar will horizontally scroll items in the list box. If the width of the list box is equal to or greater than this value, the horizontal scroll bar is hidden or, if the combo box has the CBS_DISABLENOSCROLL style, disabled.

// Find the longest string in the combo box.
CString str;
CSize sz;
int dx = 0;
TEXTMETRIC tm;
CDC *pDC = m_pComboBox->GetDC();
CFont *pFont = m_pComboBox->GetFont();

// Select the listbox font, save the old font
CFont *pOldFont = pDC->SelectObject(pFont);
// Get the text metrics for avg char width
pDC->GetTextMetrics(&tm);

for (int i = 0; i < m_pComboBox->GetCount(); i++)
{
   m_pComboBox->GetLBText(i, str);
   sz = pDC->GetTextExtent(str);

   // Add the avg width to prevent clipping
   sz.cx += tm.tmAveCharWidth;

   if (sz.cx > dx)
      dx = sz.cx;
}
// Select the old font back into the DC
pDC->SelectObject(pOldFont);
m_pComboBox->ReleaseDC(pDC);

// Set the horizontal extent so every character of all strings can
// be scrolled to.
m_pComboBox->SetHorizontalExtent(dx);

Sets the 32-bit value associated with the specified item in a combo box.

int SetItemData(
    int nIndex,
    DWORD_PTR dwItemData);

nIndex
Contains a zero-based index to the item to set.

dwItemData
Contains the new value to associate with the item.

CB_ERR if an error occurs.

Use the SetItemDataPtr member function if the 32-bit item is to be a pointer.

// Set the data of each item to be equal to its index.
for (int i = 0; i < m_pComboBox->GetCount(); i++)
{
   m_pComboBox->SetItemData(i, i);
}

Sets the 32-bit value associated with the specified item in a combo box to be the specified pointer (void *).

int SetItemDataPtr(
    int nIndex,
    void* pData);

nIndex
Contains a zero-based index to the item.

pData
Contains the pointer to associate with the item.

CB_ERR if an error occurs.

This pointer remains valid for the life of the combo box, even though the item's relative position within the combo box might change as items are added or removed. Hence, the item's index within the box can change, but the pointer remains reliable.

// Set the data pointer of each item to be NULL.
for (int i = 0; i < m_pComboBox->GetCount(); i++)
{
   m_pComboBox->SetItemDataPtr(i, NULL);
}

Call the SetItemHeight member function to set the height of list items in a combo box or the height of the edit-control (or static-text) portion of a combo box.

int SetItemHeight(
    int nIndex,
    UINT cyItemHeight);

nIndex
Specifies whether the height of list items or the height of the edit-control (or static-text) portion of the combo box is set.

If the combo box has the CBS_OWNERDRAWVARIABLE style, nIndex specifies the zero-based index of the list item whose height is to be set; otherwise, nIndex must be 0 and the height of all list items will be set.

If nIndex is -1, the height of the edit-control or static-text portion of the combo box is to be set.

cyItemHeight
Specifies the height, in pixels, of the combo-box component identified by nIndex.

CB_ERR if the index or height is invalid; otherwise 0.

The height of the edit-control (or static-text) portion of the combo box is set independently of the height of the list items. An application must ensure that the height of the edit-control (or static-text) portion is not smaller than the height of a particular list-box item.

// Set the height of every item to be the
// vertical size of the item's text extent.
CString str;
CSize sz;
CDC *pDC = m_pComboBox->GetDC();
for (int i = 0; i < m_pComboBox->GetCount(); i++)
{
   m_pComboBox->GetLBText(i, str);
   sz = pDC->GetTextExtent(str);

   m_pComboBox->SetItemHeight(i, sz.cy);
}
m_pComboBox->ReleaseDC(pDC);

Sets the locale identifier for this combo box.

LCID SetLocale(LCID nNewLocale);

nNewLocale
The new locale identifier (LCID) value to set for the combo box.

The previous locale identifier (LCID) value for this combo box.

If SetLocale is not called, the default locale is obtained from the system. This system default locale can be modified by using Control Panel's Regional (or International) application.

// My LCID to use.
LCID mylcid = MAKELCID(MAKELANGID(LANG_SPANISH, SUBLANG_SPANISH_MEXICAN),
                       SORT_DEFAULT);

// Force the list box to use my locale.
m_pComboBox->SetLocale(mylcid);
ASSERT(m_pComboBox->GetLocale() == mylcid);

Sets the minimum number of visible items in the drop-down list of the current combo box control.

BOOL SetMinVisibleItems(int iMinVisible);

iMinVisible
[in] Specifies the minimum number of visible items.

TRUE if this method is successful; otherwise, FALSE.

This method sends the CB_SETMINVISIBLE message, which is described in the Windows SDK.

The first code example defines the variable, m_combobox, that is used to programmatically access the combo box control. This variable is used in the next example.

// Variable to access the combo box control
CComboBox m_combobox;

The next code example inserts 20 items into the drop-down list of a combo box control. Then it specifies that a minimum of 10 items be displayed when a user presses the drop-down arrow.

// Add extra initialization here.

// Add 20 items to the combo box. The Resource Editor
// has already been used to set the style of the combo
// box to CBS_SORT.
CString str;
for (int i = 1; i <= 20; i++)
{
    str.Format(_T("Item %2d"), i);
    m_combobox.AddString(str);
}
// Set the minimum visible item
m_combobox.SetMinVisibleItems(10);
// Set the cue banner
m_combobox.SetCueBanner(_T("Select an item..."));

// End of extra initialization.

Ensures that a particular item is visible in the list-box portion of the combo box.

int SetTopIndex(int nIndex);

nIndex
Specifies the zero-based index of the list-box item.

Zero if successful, or CB_ERR if an error occurs.

The system scrolls the list box until either the item specified by nIndex appears at the top of the list box or the maximum scroll range has been reached.

// Set the first visible item in the combo box to be the middle item
m_pComboBox->SetTopIndex(m_pComboBox->GetCount() / 2);

Shows or hides the list box of a combo box that has the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

void ShowDropDown(BOOL bShowIt = TRUE);

bShowIt
Specifies whether the drop-down list box is to be shown or hidden. A value of TRUE shows the list box. A value of FALSE hides the list box.

By default, a combo box of this style will show the list box.

This member function has no effect on a combo box created with the CBS_SIMPLE style.

See the example for CComboBox::GetDroppedState.

MFC Sample CTRLBARS
CWnd Class
Hierarchy Chart
CWnd Class
CButton Class
CEdit Class
CListBox Class
CScrollBar Class
CStatic Class
CDialog Class