COXListBoxEx Overview
Copyright © The Code Project 1997-1999, All Rights Reserved

COXListBoxEx is CListBox derived class that provides a lot of additional functionality that might be at different circumstances. New features mostly have to do with the way list box items are displayed. Using this class you can set images to be displayed altogether with text. You can easily assign any font, text and background color, indention from the left side for any item in a list box. Also you can assign a tooltip to any item so whenever mouse is moved in the item rectangle the corresponding tooltip will be displayed. You can specify background color and tooltip for the 
list box control as well.

COXListBoxEx class introduces new functionality that might be especially useful in combo box control (to use COXListBoxEx derived class as combo box dropdown list box). This functionality allows you to assign some items as Most Recent Used (MRU) items. MRU items always reside at the top of the list and separated from the rest of the items by separator (line is drawn between last MRU and first normal items). COXListBoxEx allows you to specify the maximum number of MRU items. And also it supports the functionality of saving and restoring MRU items to/from the registry.

Usage

In order to use COXListBoxEx object in your application you have to create it using standard CListBox::Create function or subclass the existing control (e.g. using DDX/DDV technology). When creating control explicitly or defining it in dialog template you have to make sure that the following requirements are met:

LBS_OWNERDRAWVARIABLE style must be specified
if control is supposed to display text then LBS_HASSTRINGS style must be specified

After control was successfully created or subclassed you might want to populate it with items. The process of adding new items is exactly the same as for the standard CListBox control. We extended standard declaration of some functions in order to accommodate new functionality. Use following functions in order to add or insert new item:

int AddString(LPCTSTR lpszItem, int nMask, OXLISTBOXITEM* pLBI);
int AddString(LPCTSTR lpszItem, int nMask=0, CFont* pFont=NULL, COLORREF clrText=::GetSysColor(COLOR_WINDOWTEXT), COLORREF clrBackground=::GetSysColor(COLOR_WINDOW), CString sTooltipText=_T(""), int nImageIndex=-1,  int nIndent=0);
int InsertString(int nIndex, LPCTSTR lpszItem, int nMask, OXLISTBOXITEM* pLBI);
int InsertString(int nIndex, LPCTSTR lpszItem, int nMask=0, CFont* pFont=NULL, COLORREF clrText=::GetSysColor(COLOR_WINDOWTEXT), COLORREF clrBackground=::GetSysColor(COLOR_WINDOW), CString sTooltipText=_T(""), int nImageIndex=-1, int nIndent=0);

As you can see you can specify all new item settings at the moment this item is added.

You can change any item property at runtime using the following functions:
BOOL SetItemInfo(int nIndex, int nMask, OXLISTBOXITEM* pLBI);
virtual BOOL SetItemInfo(int nIndex, int nMask=0, CFont* pFont=NULL, COLORREF clrText=::GetSysColor(COLOR_WINDOWTEXT), COLORREF clrBackground=::GetSysColor(COLOR_WINDOW), CString sTooltipText=_T(""), int nImageIndex=-1, int nIndent=0);
BOOL SetItemFont(int nIndex, CFont* pFont);
BOOL SetItemTextColor(int nIndex, COLORREF clrText);
BOOL SetItemBkColor(int nIndex, COLORREF clrBackground);
BOOL SetItemImageIndex(int nIndex, int nImageIndex);
BOOL SetItemIndent(int nIndex, int nIndent);
BOOL SetItemTooltipText(int nIndex, CString sTooltipText);

You can retrieve any item property at runtime using the following functions:
OXLISTBOXITEM* GetItemInfo(int nIndex) const;
CFont* GetItemFont(int nIndex) const;
COLORREF GetItemTextColor(int nIndex) const;
COLORREF GetItemBkColor(int nIndex) const;
int GetItemImageIndex(int nIndex) const;
int GetItemIndent(int nIndex) const;
CString GetItemTooltipText(int nIndex) const;

You can specify a background color of the control using:
void SetBkColor(COLORREF clrBackground);

And tooltip for the control can be set using:
BOOL SetItemTooltipText(int nIndex, CString sTooltipText);

We already mentioned MRU items paradigm that is supported by COXListBoxEx class. Here is the list of functions that can be used in order to specify maximum number of MRU items, to move/remove items to/from the MRU section and to save and restore the state of MRU items:
int MRUAdd(int nItemIndex) ;
int MRUMove(int nMRUIndex, int nMRUIndexNew); 
virtual int MRUInsert(int nItemIndex, int nMRUIndex, BOOL bForceToInsert=TRUE);
virtual int MRUDelete(int nMRUIndex);
void SetSaveRestoreMRUState(BOOL bSaveRestore);
BOOL GetSaveRestoreMRUState() const;
 
Even greater level of customization can be achieved through deriving your own class from COXListBoxEx. This class has a big set of protected virtual functions that are responsible for implementing class features. By overriding those functions you can provide your own logic in the control. Refer to class reference for details.