The Ultimate Toolbox Extended Listbox

• Download demo executable - 398.5 KB

• Download the Ultimate Toolbox source code - 3 MB
• Download the Ultimate Toolbox sample projects - 5.4 MB
• Download the Ultimate Toolbox documentation in compiled HTML help (CHM) format - 4.9 MB

Visit the Ultimate Toolbox main page for an overview and configuration guide to the Ultimate Toolbox library.

Source code and project files for this sample can be found in the samples\gui\ExtendedListBox directory of the sample projects download.

Overview

The ExtendedListBox sample shows a basic, font, and font combo picker. The font combo shows the use of the COXListBoxEx displaying a number of most recently used items.

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

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

Usage

In order to use a COXListBoxEx object in your application, you have to create it using the standard CListBox::Create function or subclass the existing control (e.g. using DDX/DDV technology).

The second option is as simple as including the OXListBoxEx.h header and subclassing an existing CListBox control that has been integrated into the class with the Add Member Variable (VS2005) or Class Wizard (VC6) - from the sample:

#include "OXListBoxEx.h"

class CExtendedListBoxView : public CFormView
{
protected: // create from serialization only
    CExtendedListBoxView();
    DECLARE_DYNCREATE(CExtendedListBoxView)

public:
    //{{AFX_DATA(CExtendedListBoxView)
    enum { IDD = IDD_EXTENDEDLISTBOX_FORM };
    ...
    COXListBoxEx    m_listBoxEx;
    ...

When creating a control explicitly or defining it in a dialog template, you have to make sure that the following requirements are met:

• The LBS_OWNERDRAWVARIABLE style must be specified.
• If the control is supposed to display text, then LBS_HASSTRINGS style must be specified.

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

• 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 an 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 a tooltip for the control can be set using:

• BOOL SetItemTooltipText(int nIndex, CString sTooltipText);

The MRU items paradigm that is supported by the COXListBoxEx class has already been mentioned. Here is the list of functions that can be used in order to specify the 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 levels of customization can be achieved through deriving your own class from the COXListBoxEx. This class has many 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 the COXListBoxEx class reference in the Graphical User Interface | List Controls section of the compiled HTML help and the samples\gui\ExtendedListBox sample for more details.

History

Initial CodeProject release August 2007.