`CComboBox` Class

Article
08/06/2021

Provides the functionality of a Windows combo box.

Syntax

class CComboBox : public CWnd

Members

Public Constructors

Name	Description
`CComboBox::CComboBox`	Constructs a `CComboBox` object.

Public Methods

Name	Description
`CComboBox::AddString`	Adds a string to the end of the list in the list box of a combo box, or at the sorted position for list boxes with the `CBS_SORT` style.
`CComboBox::Clear`	Deletes (clears) the current selection, if any, in the edit control.
`CComboBox::CompareItem`	Called by the framework to determine the relative position of a new list item in a sorted owner-drawn combo box.
`CComboBox::Copy`	Copies the current selection, if any, onto the Clipboard in `CF_TEXT` format.
`CComboBox::Create`	Creates the combo box and attaches it to the `CComboBox` object.
`CComboBox::Cut`	Deletes (cuts) the current selection, if any, in the edit control and copies the deleted text onto the Clipboard in `CF_TEXT` format.
`CComboBox::DeleteItem`	Called by the framework when a list item is deleted from an owner-drawn combo box.
`CComboBox::DeleteString`	Deletes a string from the list box of a combo box.
`CComboBox::Dir`	Adds a list of file names to the list box of a combo box.
`CComboBox::DrawItem`	Called by the framework when a visual aspect of an owner-drawn combo box changes.
`CComboBox::FindString`	Finds the first string that contains the specified prefix in the list box of a combo box.
`CComboBox::FindStringExact`	Finds the first list-box string (in a combo box) that matches the specified string.
`CComboBox::GetComboBoxInfo`	Retrieves information about the `CComboBox` object.
`CComboBox::GetCount`	Retrieves the number of items in the list box of a combo box.
`CComboBox::GetCueBanner`	Gets the cue text that is displayed for a combo box control.
`CComboBox::GetCurSel`	Retrieves the index of the currently selected item, if any, in the list box of a combo box.
`CComboBox::GetDroppedControlRect`	Retrieves the screen coordinates of the visible (dropped down) list box of a drop-down combo box.
`CComboBox::GetDroppedState`	Determines whether the list box of a drop-down combo box is visible (dropped down).
`CComboBox::GetDroppedWidth`	Retrieves the minimum allowed width for the drop-down list-box portion of a combo box.
`CComboBox::GetEditSel`	Gets the starting and ending character positions of the current selection in the edit control of a combo box.
`CComboBox::GetExtendedUI`	Determines whether a combo box has the default user interface or the extended user interface.
`CComboBox::GetHorizontalExtent`	Returns the width in pixels that the list-box portion of the combo box can be scrolled horizontally.
`CComboBox::GetItemData`	Retrieves the application-supplied 32-bit value associated with the specified combo-box item.
`CComboBox::GetItemDataPtr`	Retrieves the application-supplied 32-bit pointer that is associated with the specified combo-box item.
`CComboBox::GetItemHeight`	Retrieves the height of list items in a combo box.
`CComboBox::GetLBText`	Gets a string from the list box of a combo box.
`CComboBox::GetLBTextLen`	Gets the length of a string in the list box of a combo box.
`CComboBox::GetLocale`	Retrieves the locale identifier for a combo box.
`CComboBox::GetMinVisible`	Gets the minimum number of visible items in the drop-down list of the current combo box.
`CComboBox::GetTopIndex`	Returns the index of the first visible item in the list-box portion of the combo box.
`CComboBox::InitStorage`	Preallocates blocks of memory for items and strings in the list-box portion of the combo box.
`CComboBox::InsertString`	Inserts a string into the list box of a combo box.
`CComboBox::LimitText`	Limits the length of the text that the user can enter into the edit control of a combo box.
`CComboBox::MeasureItem`	Called by the framework to determine combo box dimensions when an owner-drawn combo box is created.
`CComboBox::Paste`	Inserts the data from the Clipboard into the edit control at the current cursor position. Data is inserted only if the Clipboard contains data in `CF_TEXT` format.
`CComboBox::ResetContent`	Removes all items from the list box and edit control of a combo box.
`CComboBox::SelectString`	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 the string to the edit control.
`CComboBox::SetCueBanner`	Sets the cue text that is displayed for a combo box control.
`CComboBox::SetCurSel`	Selects a string in the list box of a combo box.
`CComboBox::SetDroppedWidth`	Sets the minimum allowed width for the drop-down list-box portion of a combo box.
`CComboBox::SetEditSel`	Selects characters in the edit control of a combo box.
`CComboBox::SetExtendedUI`	Selects either the default user interface or the extended user interface for a combo box that has the `CBS_DROPDOWN` or `CBS_DROPDOWNLIST` style.
`CComboBox::SetHorizontalExtent`	Sets the width in pixels that the list-box portion of the combo box can be scrolled horizontally.
`CComboBox::SetItemData`	Sets the 32-bit value associated with the specified item in a combo box.
`CComboBox::SetItemDataPtr`	Sets the 32-bit pointer associated with the specified item in a combo box.
`CComboBox::SetItemHeight`	Sets the height of list items in a combo box or the height of the edit-control (or static-text) portion of a combo box.
`CComboBox::SetLocale`	Sets the locale identifier for a combo box.
`CComboBox::SetMinVisibleItems`	Sets the minimum number of visible items in the drop-down list of the current combo box.
`CComboBox::SetTopIndex`	Tells the list-box portion of the combo box to display the item with the specified index at the top.
`CComboBox::ShowDropDown`	Shows or hides the list box of a combo box that has the `CBS_DROPDOWN` or `CBS_DROPDOWNLIST` style.

Remarks

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.

Style	When is list box visible	Static or edit control
Simple	Always	Edit
Drop-down	When dropped down	Edit
Drop-down list	When dropped down	Static

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.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CComboBox

Requirements

Header: afxwin.h

`CComboBox::AddString`

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

int AddString(LPCTSTR lpszString);

Parameters

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

Return Value

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.

Remarks

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.

Note

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

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

Example

// 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);
}

`CComboBox::CComboBox`

Constructs a CComboBox object.

CComboBox();

Example

// Declare a local CComboBox object.
CComboBox myComboBox;

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

`CComboBox::Clear`

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

void Clear();

Remarks

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

Example

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

`CComboBox::CompareItem`

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);

Parameters

lpCompareItemStruct
A long pointer to a COMPAREITEMSTRUCT structure.

Return Value

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

Value	Meaning
- 1	Item 1 sorts before item 2.
0	Item 1 and item 2 sort the same.
1	Item 1 sorts after item 2.

See CWnd::OnCompareItem for a description of COMPAREITEMSTRUCT.

Remarks

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.

Example

// 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;
}

`CComboBox::Copy`

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

void Copy();

Example

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

`CComboBox::Create`

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

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

Parameters

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.

Return Value

Nonzero if successful; otherwise 0.

Remarks

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

Example

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

`CComboBox::Cut`

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();

Remarks

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

Example

// 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();

`CComboBox::DeleteItem`

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);

Parameters

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.

Remarks

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

Example

// 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);
}

`CComboBox::DeleteString`

Deletes the item in position nIndex from the combo box.

int DeleteString(UINT nIndex);

Parameters

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

Return Value

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.

Remarks

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.

Example

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

`CComboBox::Dir`

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

int Dir(
    UINT attr,
    LPCTSTR lpszWildCard);

Parameters

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, *.*).

Return Value

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.

Remarks

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

Example

// 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);

`CComboBox::DrawItem`

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

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parameters

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

Remarks

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.

Example

// 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();
}

`CComboBox::FindString`

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;

Parameters

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.

Return Value

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.

Remarks

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

Example

// 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);
}

`CComboBox::FindStringExact`

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;

Parameters

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.

Return Value

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

Remarks

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.

Example

// 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);
}

`CComboBox::GetComboBoxInfo`

Retrieves information for the CComboBox object.

BOOL GetComboBoxInfo(PCOMBOBOXINFO pcbi) const;

Parameters

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

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

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

`CComboBox::GetCount`

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

int GetCount() const;

Return Value

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.

Example

// 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);

`CComboBox::GetCueBanner`

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

CString GetCueBanner() const;

BOOL GetCueBanner(
    LPTSTR lpszText,
    int cchText) const;

Parameters

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

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

Return Value

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.

Remarks

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.

`CComboBox::GetCurSel`

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

int GetCurSel() const;

Return Value

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.

Remarks

GetCurSel returns an index into the list.

Example

// 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);
}

`CComboBox::GetDroppedControlRect`

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;

Parameters

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

Example

// 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);

`CComboBox::GetDroppedState`

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

BOOL GetDroppedState() const;

Return Value

Nonzero if the list box is visible; otherwise 0.

Example

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

`CComboBox::GetDroppedWidth`

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

int GetDroppedWidth() const;

Return Value

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

Remarks

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.

Example

See the example for SetDroppedWidth.

`CComboBox::GetEditSel`

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

DWORD GetEditSel() const;

Return Value

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.

Example

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);
}

`CComboBox::GetExtendedUI`

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

BOOL GetExtendedUI() const;

Return Value

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

Remarks

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).

Example

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

`CComboBox::GetHorizontalExtent`

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;

Return Value

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

Remarks

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

Example

// 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);
}

`CComboBox::GetItemData`

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

DWORD_PTR GetItemData(int nIndex) const;

Parameters

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

Return Value

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

Remarks

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 *).

Example

// 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);
   }
}

`CComboBox::GetItemDataPtr`

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

void* GetItemDataPtr(int nIndex) const;

Parameters

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

Return Value

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

Example

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);
   }
}

`CComboBox::GetItemHeight`

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

int GetItemHeight(int nIndex) const;

Parameters

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.

Return Value

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

Example

// 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);

`CComboBox::GetLBText`

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;

Parameters

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.

Return Value

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.

Remarks

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).

Example

// 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);
}

`CComboBox::GetLBTextLen`

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

int GetLBTextLen(int nIndex) const;

Parameters

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

Return Value

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.

Example

See the example for CComboBox::GetLBText.

`CComboBox::GetLocale`

Retrieves the locale used by the combo box.

LCID GetLocale() const;

Return Value

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

Remarks

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

Example

See the example for CComboBox::SetLocale.

`CComboBox::GetMinVisible`

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

int GetMinVisible() const;

Return Value

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

Remarks

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

`CComboBox::GetTopIndex`

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

int GetTopIndex() const;

Return Value

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

Remarks

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.

Example

// 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);
}

`CComboBox::InitStorage`

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

int InitStorage(
    int nItems,
    UINT nBytes);

Parameters

nItems
Specifies the number of items to add.

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

Return Value

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.

Remarks

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.

Example

// 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);
}

`CComboBox::InsertString`

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

int InsertString(
    int nIndex,
    LPCTSTR lpszString);

Parameters

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.

Return Value

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.

Remarks

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

Note

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

Example

// 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);
}

`CComboBox::LimitText`

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);

Parameters

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.

Return Value

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.

Remarks

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.

Example

// 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);

`CComboBox::MeasureItem`

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

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

Parameters

lpMeasureItemStruct
A long pointer to a MEASUREITEMSTRUCT structure.

Remarks

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.

Example

// 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;
   }
}

`CComboBox::Paste`

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

void Paste();

Remarks

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

Example

// 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();

`CComboBox::ResetContent`

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

void ResetContent();

Example

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

`CComboBox::SelectString`

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);

Parameters

Return Value

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.

Remarks

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.

Example

// 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);

`CComboBox::SetCueBanner`

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

BOOL SetCueBanner(LPCTSTR lpszText);

Parameters

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

Return Value

TRUE if the method is successful; otherwise, FALSE.

Remarks

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.

Example

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.

`CComboBox::SetCurSel`

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

int SetCurSel(int nSelect);

Parameters

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.

Return Value

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.

Remarks

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.

Example

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

`CComboBox::SetDroppedWidth`

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

int SetDroppedWidth(UINT nWidth);

Parameters

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

Return Value

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

Remarks

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.

Example

// 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);

`CComboBox::SetEditSel`

Selects characters in the edit control of a combo box.

BOOL SetEditSel(
    int nStartChar,
    int nEndChar);

Parameters

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.

Return Value

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.

Remarks

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.

Note

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

Example

See the example for CComboBox::GetEditSel.

`CComboBox::SetExtendedUI`

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);

Parameters

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.

Return Value

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

Remarks

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).

Example

See the example for CComboBox::GetExtendedUI.

`CComboBox::SetHorizontalExtent`

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

void SetHorizontalExtent(UINT nExtent);

Parameters

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

Remarks

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.

Example

// 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);

`CComboBox::SetItemData`

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

int SetItemData(
    int nIndex,
    DWORD_PTR dwItemData);

Parameters

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

dwItemData
Contains the new value to associate with the item.

Return Value

CB_ERR if an error occurs.

Remarks

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

Example

// 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);
}

`CComboBox::SetItemDataPtr`

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);

Parameters

nIndex
Contains a zero-based index to the item.

pData
Contains the pointer to associate with the item.

Return Value

CB_ERR if an error occurs.

Remarks

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.

Example

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

`CComboBox::SetItemHeight`

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);

Parameters

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.

Return Value

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

Remarks

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.

Example

// 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);

`CComboBox::SetLocale`

Sets the locale identifier for this combo box.

LCID SetLocale(LCID nNewLocale);

Parameters

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

Return Value

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

Remarks

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.

Example

// 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);

`CComboBox::SetMinVisibleItems`

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

BOOL SetMinVisibleItems(int iMinVisible);

Parameters

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

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

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

Example

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.

`CComboBox::SetTopIndex`

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

int SetTopIndex(int nIndex);

Parameters

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

Return Value

Zero if successful, or CB_ERR if an error occurs.

Remarks

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.

Example

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

`CComboBox::ShowDropDown`

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

void ShowDropDown(BOOL bShowIt = TRUE);

Parameters

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.

Remarks

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.

Example

See the example for CComboBox::GetDroppedState.

CComboBox Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

CComboBox::AddString

Parameters

Return Value

Remarks

Example

CComboBox::CComboBox

Example

CComboBox::Clear

Remarks

Example

CComboBox::CompareItem

Parameters

Return Value

Remarks

Example

CComboBox::Copy

Example

CComboBox::Create

Parameters

Return Value

Remarks

Example

CComboBox::Cut

Remarks

Example

CComboBox::DeleteItem

Parameters

Remarks

Example

CComboBox::DeleteString

Parameters

Return Value

Remarks

Example

CComboBox::Dir

Parameters

Return Value

Remarks

Example

CComboBox::DrawItem

Parameters

Remarks

Example

CComboBox::FindString

Parameters

Return Value

Remarks

Example

CComboBox::FindStringExact

Parameters

Return Value

Remarks

Example

CComboBox::GetComboBoxInfo

Parameters

Return Value

Remarks

CComboBox::GetCount

Return Value

Example

CComboBox::GetCueBanner

Parameters

Return Value

Remarks

CComboBox::GetCurSel

Return Value

Remarks

Example

CComboBox::GetDroppedControlRect

Parameters

Example

CComboBox::GetDroppedState

`CComboBox` Class

`CComboBox::AddString`

`CComboBox::CComboBox`

`CComboBox::Clear`

`CComboBox::CompareItem`

`CComboBox::Copy`

`CComboBox::Create`

`CComboBox::Cut`

`CComboBox::DeleteItem`

`CComboBox::DeleteString`

`CComboBox::Dir`

`CComboBox::DrawItem`

`CComboBox::FindString`

`CComboBox::FindStringExact`

`CComboBox::GetComboBoxInfo`

`CComboBox::GetCount`

`CComboBox::GetCueBanner`

`CComboBox::GetCurSel`

`CComboBox::GetDroppedControlRect`

`CComboBox::GetDroppedState`

`CComboBox::GetDroppedWidth`

`CComboBox::GetEditSel`

`CComboBox::GetExtendedUI`

`CComboBox::GetHorizontalExtent`

`CComboBox::GetItemData`

`CComboBox::GetItemDataPtr`

`CComboBox::GetItemHeight`

`CComboBox::GetLBText`

`CComboBox::GetLBTextLen`

`CComboBox::GetLocale`

`CComboBox::GetMinVisible`

`CComboBox::GetTopIndex`

`CComboBox::InitStorage`

`CComboBox::InsertString`

`CComboBox::LimitText`

`CComboBox::MeasureItem`