
A ComboBoxEx control is an extension of the combo box control that provides native support for item images. To make item images easily accessible, the control provides image list support. By using this control, you can provide the functionality of a combo box without having to manually draw item graphics.
Effectively, a ComboBoxEx control creates a child combo box and performs owner draw tasks for you based on an assigned image list. Therefore, the CBS_OWNERDRAWFIXED style is implied and you need not use it when creating the control. Because image lists are used to provide item graphics, the CBS_OWNERDRAWVARIABLE style cannot be used.
A ComboBoxEx control must be initialized by calling the InitCommonControlsEx function, specifying ICC_USEREX_CLASSES in the accompanying INITCOMMONCONTROLSEX structure.
You can create a ComboBoxEx control by using the CreateWindowEx function and specifying WC_COMBOBOXEX as the window class. The class is registered when the InitCommonControlsEx function is called as explained above.
ComboBoxEx controls are created without a default image list. To use item images, you must create an image list for the ComboBoxEx control and assign it to the control using the CBEM_SETIMAGELIST message. If you do not assign an image list to the ComboBoxEx control, the control displays item text only.
ComboBoxEx controls only support the following styles. All other styles are ignored by the controls.
Because the ComboBoxEx control performs owner draw tasks for you based on an assigned image list, the CBS_OWNERDRAWFIXED style is implied; you need not use it when creating the control. Because image lists are used to provide item graphics, the CBS_OWNERDRAWVARIABLE style cannot be used. The ComboBoxEx control also supports extended styles that provide additional features.
ComboBoxEx controls maintain item information using a COMBOBOXEXITEM structure. This structure includes members for item indexes, image indexes (normal, selection state, and overlay), indentation values, text strings, and item-specific values.
The ComboBoxEx control provides easy access to and manipulation of items through messaging. To add or delete an item, send the CBEM_INSERTITEM or CBEM_DELETEITEM message. You can modify items currently in the control using the CBEM_SETITEM message.
ComboBoxEx controls support callback item attributes. You can specify an item as a callback item when you add it to the control using CBEM_INSERTITEM. When you assign values to an item's COMBOBOXEXITEM structure, you must specify the appropriate callback flag values. The following are COMBOBOXEXITEM structure members and their corresponding callback flag values.
| Member | Callback value |
| pszText | LPSTR_TEXTCALLBACK |
| iImage | I_IMAGECALLBACK |
| iSelectedImage | I_IMAGECALLBACK |
| iOverlay | I_IMAGECALLBACK |
| iIndent | I_INDENTCALLBACK |
The control will request information about callback items by sending CBEN_GETDISPINFO notification messages. This notification is sent in the form of a WM_NOTIFY message. When your application processes this message, it must provide the requested information for the control. If you set the mask member of the accompanying COMBOBOXEXITEM structure to CBEIF_DI_SETITEM, the control will store the item data and will not request it again.
If you want a ComboBoxEx control to display icons with items, you must provide an image list. ComboBoxEx controls support up to three images for an itemone for its selected state, one for its nonselected state, and one for an overlay image. Assign an existing image list to a ComboBoxEx control using the CBEM_SETIMAGELIST message.
The COMBOBOXEXITEM structure contains members that represent the image indexes for each image list (selected, unselected, and overlay). For each item, set these members to display the desired images. It is not necessary to specify image indexes for each type of image. You can mix and match image types as you like, but always set the mask member of the COMBOBOXEXITEM structure to indicate which members are being used. The control ignores members that have not been flagged as valid.
A ComboBoxEx control sends notification messages to report changes within itself or to request callback item information. The parent of the control receives all WM_COMMAND messages from the combo box contained within the ComboBoxEx control. The ComboBoxEx control sends its own notifications using WM_NOTIFY messages. As a result, the control's owner must be prepared to process both forms of notification messages.
Following are the ComboBoxEx-specific notification messages.
| Notification | Description |
| CBEN_BEGINEDIT | Signals that the user has activated the drop-down list or clicked in the control's edit box. |
| CBEN_ENDEDIT | Signals that the user has selected an item from the drop-down list or has concluded an edit operation within the edit box. |
| CBEN_DELETEITEM | Reports that an item was deleted. |
| CBEN_GETDISPINFO | Requests information about an item's attributes. |
| CBEN_INSERTITEM | Signals that an item was inserted in the control. |
The following are the standard combo box messages that a ComboBoxEx control forwards to its child combo box. Some of these messages may be processed by the ComboBoxEx control either before or after the message has been forwarded.
Following are the windows messages that a ComboBoxEx control forwards to its parent window:
This section contains sample code and information about the following topics related to ComboBoxEx controls:
To create a ComboBoxEx control, call the CreateWindowEx function, using WC_COMBOBOXEX as the window class. You must first register the window class by calling the InitCommonControlsEx function, while specifying the ICC_USEREX_CLASSES bit in the accompanying INITCOMMONCONTROLSEX structure.
The following application-defined function creates a ComboBoxEx control with the CBS_DROPDOWN style in the main window.
// CreateComboEx - Registers the ComboBoxEx window class and creates
// a ComboBoxEx control in the client area of the main window.
//
// g_hwndMain - A handle to the main window.
// g_hinst - A handle to the program instance.
HWND WINAPI CreateComboEx(void)
{
HWND hwnd;
INITCOMMONCONTROLSEX icex;
icex.dwSize = sizeof(INITCOMMONCONTROLSEX);
icex.dwICC = ICC_USEREX_CLASSES;
InitCommonControlsEx(&icex);
hwnd = CreateWindowEx(0, WC_COMBOBOXEX, NULL,
WS_BORDER | WS_VISIBLE |
WS_CHILD | CBS_DROPDOWN,
// No size yet--resize after setting image list.
0,0,0,0,
g_hwndMain,
NULL,
g_hinst,
NULL);
return (hwnd);
}
To add an item to a ComboBoxEx control, first define a COMBOBOXEXITEM structure. Set the mask member of the structure to indicate which members you want the control to use. Set the specified members of the structure to the values you want, and then send the CBEM_INSERTITEM message to add the item to the control.
The following application-defined function adds 15 items to an existing ComboBoxEx control. Note that the mask member of the COMBOBOXEXITEM structure includes flag values that tell the control to display images for each item.
#define MAX_ITEMS 15
// AddItems - Uses the CBEM_INSERTITEM message to add items to an
// existing ComboBoxEx control.
BOOL WINAPI AddItems(HWND hwndCB)
{
// Declare and init locals.
COMBOBOXEXITEM cbei;
int iCnt;
typedef struct {
int iImage;
int iSelectedImage;
int iIndent;
LPTSTR pszText;
} ITEMINFO, *PITEMINFO;
ITEMINFO IInf[] = {
{ 0, 3, 0, "first"},
{ 1, 4, 1, "second"},
{ 2, 5, 2, "third"},
{ 0, 3, 0, "fourth"},
{ 1, 4, 1, "fifth"},
{ 2, 5, 2, "sixth"},
{ 0, 3, 0, "seventh"},
{ 1, 4, 1, "eighth"},
{ 2, 5, 2, "ninth"},
{ 0, 3, 0, "tenth"},
{ 1, 4, 1, "eleventh"},
{ 2, 5, 2, "twelfth"},
{ 0, 3, 0, "thirteenth"},
{ 1, 4, 1, "fourteenth"},
{ 2, 5, 2, "fifteenth"}
};
// Set the mask common to all items.
cbei.mask = CBEIF_TEXT | CBEIF_INDENT |
CBEIF_IMAGE| CBEIF_SELECTEDIMAGE;
for(iCnt=0;iCnt<MAX_ITEMS;iCnt++){
// Initialize the COMBOBOXEXITEM struct.
cbei.iItem = iCnt;
cbei.pszText = IInf[iCnt].pszText;
cbei.cchTextMax = sizeof(IInf[iCnt].pszText);
cbei.iImage = IInf[iCnt].iImage;
cbei.iSelectedImage = IInf[iCnt].iSelectedImage;
cbei.iIndent = IInf[iCnt].iIndent;
// Tell the ComboBoxEx to add the item. Return FALSE if
// this fails.
if(SendMessage(hwndCB,CBEM_INSERTITEM,0,(LPARAM)&cbei) == -1)
return FALSE;
}
// Assign the existing image list to the ComboBoxEx control
// and return TRUE.
SendMessage(hwndCB,CBEM_SETIMAGELIST,0,(LPARAM)g_himl);
// Set size of control to make sure it's displayed correctly now
// that the image list is set.
SetWindowPos(hwndCB,NULL,20,20,250,120,SWP_NOACTIVATE);
return TRUE;
}
If your application is going to use callback items in a ComboBoxEx control, it must be prepared to handle the CBEN_GETDISPINFO notification message. A ComboBoxEx control sends this notification whenever it needs the owner to provide specific item information. For more information about callback items, see Callback Items.
The following application-defined function processes CBEN_GETDISPINFO by providing attributes for a given item. Note that it sets the mask member of the incoming COMBOBOXEXITEM structure to CBEIF_DI_SETITEM. Setting mask to this value makes the control retain the item information so it will not need to request the information again.
// DoItemCallback - Processes CBEN_GETDISPINFO by providing item
// attributes for a given callback item.
void WINAPI DoItemCallback(PNMCOMBOBOXEX pNMCBex)
{
DWORD dwMask = pNMCBex->ceItem.mask;
if(dwMask & CBEIF_TEXT)
;// Provide item text.
if(dwMask & CBEIF_IMAGE)
;// Provide an item image index.
/*
* Provide other callback information as desired.
*/
// Make the ComboBoxEx control hold onto the item information.
pNMCBex->ceItem.mask = CBEIF_DI_SETITEM;
}
A ComboBoxEx control notifies its parent window of events by sending WM_NOTIFY messages. Because the control uses a child combo box, it forwards all WM_COMMAND notification messages it receives to the parent window to be processed. Therefore, your application must be prepared to process WM_NOTIFY messages from the ComboBoxEx and WM_COMMAND messages forwarded from the ComboBoxEx's child combo box control.
The example in this section handles the WM_NOTIFY and WM_COMMAND messages from a ComboBoxEx control by calling a corresponding application-defined function to process them.
LRESULT CALLBACK WndProc (HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
switch(msg){
case WM_COMMAND:
// If this is an "old style" combo box notification, handle it.
if((HWND)lParam == g_hwndCB)
DoOldNotify(hwnd, wParam);
break;
case WM_NOTIFY:
return (DoCBEXNotify(hwnd, lParam));
case WM_PAINT:
hdc = BeginPaint(hwnd, &ps);
EndPaint(hwnd, &ps);
break;
case WM_DESTROY:
PostQuitMessage(0);
break;
default:
return DefWindowProc(hwnd, msg, wParam, lParam);
break;
}
return FALSE;
}
This section contains information about the programming elements used with ComboBoxEx controls.
ComboBoxEx control extended styles
| Notifications |
| CBEN_BEGINEDIT |
| CBEN_DELETEITEM |
| CBEN_DRAGBEGIN |
| CBEN_ENDEDIT |
| CBEN_GETDISPINFO |
| CBEN_INSERTITEM |
| NM_SETCURSOR (ComboBoxEx) |
| Structures |
| COMBOBOXEXITEM |
| NMCBEDRAGBEGIN |
| NMCBEENDEDIT |
| NMCOMBOBOXEX |
This section contains information about the constants used with ComboBoxEx controls.
ComboBoxEx controls support most standard combo box control styles. Additionally, ComboBoxEx controls support the following extended styles, which you can set and retrieve by using CBEM_SETEXTENDEDSTYLE and CBEM_GETEXTENDEDSTYLE messages:
| CBES_EX_CASESENSITIVE | String searches in the list will be case sensitive. This includes searches as a result of text being typed in the edit box and the CB_FINDSTRINGEXACT message. |
| CBES_EX_NOEDITIMAGE | The edit box will not display an item image. |
| CBES_EX_NOEDITIMAGEINDENT | The edit box will not indent text to make room for an item image. |
| CBES_EX_NOSIZELIMIT | Allows the ComboBoxEx control to be vertically sized smaller than its contained combo box control. If the ComboBoxEx is sized smaller than the combo box, the combo box will be clipped. |
| CBES_EX_PATHWORDBREAKPROC | Windows NT only. The edit box will use the slash (/), backslash (\), and period (.) characters as word delimiters. This makes keyboard shortcuts for word-by-word cursor movement (CTRL+ARROW) effective in path names and URLs. |
This section contains information about the messages used with ComboBoxEx controls.
CBEM_DELETEITEM
wParam = (WPARAM)(int) iIndex;
lParam = 0;
Removes an item from a ComboBoxEx control.
This message maps to the combo box control message CB_DELETESTRING.
CBEM_GETCOMBOCONTROL
wParam = 0;
lParam = 0;
Retrieves the handle to the child combo box control.
CBEM_GETEDITCONTROL
wParam = 0;
lParam = 0;
Retrieves the handle to the edit control portion of a ComboBoxEx control. A ComboBoxEx control uses an edit box when it is set to the CBS_DROPDOWN style.
CBEM_GETEXTENDEDSTYLE
wParam = 0;
lParam = 0;
Retrieves the extended styles that are in use for a ComboBoxEx control.
CBEM_GETIMAGELIST
wParam = 0;
lParam = 0;
Retrieves the handle to an image list assigned to a ComboBoxEx control.
CBEM_GETITEM
wParam = 0;
lParam = (LPARAM)(PCOMBOBOXEXITEM) pCBItem;
Retrieves item information for a given ComboBoxEx item.
CBEM_GETUNICODEFORMAT
wParam = 0;
lParam = 0;
Retrieves the UNICODE character format flag for the control.
See also CBEM_SETUNICODEFORMAT
CBEM_HASEDITCHANGED
wParam = 0;
lParam = 0;
Determines if the user has changed the contents of the ComboBoxEx edit control by typing. A ComboBoxEx control uses an edit box when it is set to the CBS_DROPDOWN style.
CBEM_INSERTITEM
wParam = 0;
lParam = (LPARAM)(const COMBOBOXEXITEM FAR *) lpcCBItem;
Inserts a new item in a ComboBoxEx control.
CBEM_SETEXTENDEDSTYLE
wParam = (WPARAM)(DWORD) dwExMask;
lParam = (LPARAM)(DWORD) dwExStyle;
Sets extended styles within a ComboBoxEx control.
dwExMask allows you to modify one or more extended styles without having to retrieve the existing styles first. For example, if you pass CBES_EX_NOEDITIMAGE for dwExMask and 0 for dwExStyle, the CBES_EX_NOEDITIMAGE style will be cleared, but all other styles will remain the same.
CBEM_SETIMAGELIST
wParam = 0;
lParam = (LPARAM)(HIMAGELIST) himl;
Sets an image list for a ComboBoxEx control.
Note The height of images within your image list might change the size requirements of the ComboBoxEx control. It is recommended that you resize the control after sending this message to ensure that it is displayed properly.
CBEM_SETITEM
wParam = 0;
lParam = (LPARAM) (const COMBOBOXEXITEM FAR *) lpcCBItem;
Sets the attributes for an item in a ComboBoxEx control.
CBEM_SETUNICODEFORMAT
wParam = (WPARAM)(BOOL)fUnicode;
lParam = 0;
Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control.
See also CBEM_GETUNICODEFORMAT
This section contains information about the notification messages sent by ComboBoxEx controls.
CBEN_BEGINEDIT
lpnmhdr = (LPNMHDR) lParam;
Sent when the user activates the drop-down list or clicks in the control's edit box. This notification is sent in the form of a WM_NOTIFY message.
CBEN_DELETEITEM
pCBEx= (PNMCOMBOBOXEX) lParam;
Sent when an item has been deleted. This notification is sent in the form of a WM_NOTIFY message.
CBEN_DRAGBEGIN
lpnmdb = (LPNMCBEDRAGBEGIN) lParam;
Sent when the user begins dragging the image of the item displayed in the edit portion of the control. This notification is sent in the form of a WM_NOTIFY message.
If the receiving application implements drag-and-drop functionality from the control, the application will begin the drag-and-drop operation in response to this notification.
CBEN_ENDEDIT
pnmEditInfo = (PNMCBEENDEDIT) lParam;
Sent when the user has concluded an operation within the edit box or has selected an item from the control's drop-down list. This notification is sent in the form of a WM_NOTIFY message.
CBEN_GETDISPINFO
pDispInfo = (PNMCOMBOBOXEX) lParam;
Sent to retrieve display information about a callback item. This notification is sent in the form of a WM_NOTIFY message.
The NMCOMBOBOXEX structure contains a COMBOBOXEXITEM structure. The mask member specifies the information being requested by the control.
Fill the appropriate members of the structure to return the requested information to the control. If your message handler sets the mask member of the COMBOBOXEXITEM structure to CBEIF_DI_SETITEM, the header control stores the information and will not request it again.
CBEN_INSERTITEM
pNMInfo = (PNMCOMBOBOXEX) lParam;
Sent when a new item has been inserted in the control. This notification is sent in the form of a WM_NOTIFY message.
NM_SETCURSOR
lpnmm = (LPNMMOUSE) lParam;
Notifies a ComboBoxEx control's parent window that the control is setting the cursor in response to a WM_SETCURSOR message. This notification is sent in the form of a WM_NOTIFY message.
Version 4.71
This section contains information about the structures used with ComboBoxEx controls.
typedef struct {
UINT mask;
int iItem;
LPTSTR pszText;
int cchTextMax;
int iImage;
int iSelectedImage;
int iOverlay;
int iIndent;
LPARAM lParam;
} COMBOBOXEXITEM, *PCOMBOBOXEXITEM;
Contains information about an item in a ComboBoxEx control.
| CBEIF_DI_SETITEM | The control should store the item data and not ask for it again. This flag is used only with the CBEN_GETDISPINFO notification message. |
| CBEIF_IMAGE | The iImage member is valid or must be filled in. |
| CBEIF_INDENT | The iIndent member is valid or must be filled in. |
| CBEIF_LPARAM | The lParam member is valid or must be filled in. |
| CBEIF_OVERLAY | The iOverlay member is valid or must be filled in. |
| CBEIF_SELECTEDIMAGE | The iSelectedImage member is valid or must be filled in. |
| CBEIF_TEXT | The pszText member is valid or must be filled in. |
typedef struct {
NMHDR hdr;
BOOL fChanged;
int iNewSelection;
TCHAR szText[CBEMAXSTRLEN]; // CBEMAXSTRLEN is 260
int iWhy;
} NMCBEENDEDIT, *PNMCBEENDEDIT;
Contains information about the conclusion of an edit operation within a ComboBoxEx control. This structure is used with the CBEN_ENDEDIT notification message.
| CBENF_DROPDOWN | The user activated the drop-down list. |
| CBENF_ESCAPE | The user pressed ESC. |
| CBENF_KILLFOCUS | The edit box lost the keyboard focus. |
| CBENF_RETURN | The user completed the edit operation by pressing ENTER. |
typedef struct {
NMHDR hdr;
int iItemid;
TCHAR szText[CBEMAXSTRLEN];
}NMCBEDRAGBEGIN, *LPNMCBEDRAGBEGIN;
Contains information used with the CBEN_DRAGBEGIN notification message.
typedef struct {
NMHDR hdr;
COMBOBOXEXITEM ceItem;
} NMCOMBOBOXEX, *PNMCOMBOBOXEX;
Holds information specific to ComboBoxEx items for use with notification messages.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.