CListBoxST, a CListBox derived control

• Download demo project - 137 Kb
• Download source - 7 Kb

Abstract

CListBoxST is a CListBox derived class that tries to reproduce the look and feel of the same control
that appears under Windows XP when a CD without autorun.inf is inserted into the CD-Rom drive.
Each list box item can be enabled or disabled, can have a icon on the left and its text can be multi-line.
Even if almost the same visual effects can be obtained using a standard CListCtrl control, there are
some differences that make CListBoxST better:

• Easy to use
• Standard CListBox methods
• Disabled items
• Multi-line text
• Methods to move items up, down, at top, at bottom
• Different hilight styles

How to integrate CListBoxST in your application

In your project include the following files:

• ListBoxST.h
• ListBoxST.cpp

With the dialog editor create a standard list box called, for example, IDC_LBXITEMS. You need to set the following properties:

The Notify property is not mandatory but it will be required to catch messages from the list box, like for example, the Double-click event.

Then create a member variable for this list box:

CListBoxST m_lbxItems;

// Create a image list to hold icons
CImageList m_ImageList;

Now attach the list box to CListBoxST. For dialog-based applications, in your OnInitDialog:

// Call the base-class method
CDialog::OnInitDialog();

// Create the IDC_LBXITEMS list box
m_lbxItems.SubclassDlgItem(IDC_LBXITEMS, this);

Or in your DoDataExchange:

// Call the base method
CDialog::DoDataExchange(pDX);

// Create the IDC_LBXITEMS list box
DDX_Control(pDX, IDC_LBXITEMS, m_lbxItems);

To support icons, a image list must be associated to the control:

BOOL   bRetValue = FALSE;
HICON  hIcon = NULL;

// Create image list
bRetValue = m_ImageList.Create(32, 32, ILC_COLOR32 | ILC_MASK, 5, 1);
ASSERT(bRetValue == TRUE);

// Add some icons
hIcon = AfxGetApp()->LoadIcon(IDI_SHELL32_203);
m_ImageList.Add(hIcon);
hIcon = AfxGetApp()->LoadIcon(IDI_SHELL32_141);
m_ImageList.Add(hIcon);

// Associate image list to list box
m_lbxItems.SetImageList(&m_ImageList);

// At this point the list box is ready to be used. Add some items
m_lbxItems.AddString(_T("First item"), 0);
m_lbxItems.AddString(_T("Second item\nThis is multi-line"), 1);

Class methods

AddString

Adds a string to the list box.

// Parameters:
//     [IN]   lpszItem
//            Points to the null-terminated string that is to be added.
//     [IN]   nImage
//            Image to be associated with the string.
//            Pass -1L to associate no image.
//
// Return value:
//     The zero-based index of the string in the list box.
//     The return value is LB_ERR if an error occurs; the return value 
//     is LB_ERRSPACE if insufficient space is available to store the new string.
//
int AddString(LPCTSTR lpszItem, int nImage = -1L)

InsertString

Inserts a string at a specific location in the list box.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the position to insert the string.
//            If this parameter is -1, the string is added to the end of the list.
//     [IN]   lpszItem
//            Pointer to the null-terminated string that is to be inserted.
//     [IN]   nImage
//            Image to be associated with the string.
//            Pass -1L to associate no image.
//
// Return value:
//     The zero-based index of the position at which the string was inserted.
//     The return value is LB_ERR if an error occurs; the return value 
//     is LB_ERRSPACE if insufficient space is available to store the new string.
//
int InsertString(int nIndex, LPCTSTR lpszString, int nImage = -1L)

DeleteString

Deletes a string from the list box.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the string to be deleted.
//
// Return value:
//     A count of the strings remaining in the list box.
//     The return value is LB_ERR if nIndex specifies an index greater than 
//     the number of items in the list.
//
int DeleteString(int nIndex)

ReplaceString

Replaces a string at a specific location in the list box.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the position to replace the string.
//     [IN]   lpszItem
//            Pointer to the null-terminated string that is to be replaced.
//     [IN]   nImage
//            Image to be associated with the string.
//            Pass -1L to associate no image.
//
// Return value:
//     The zero-based index of the position at which the string was replaced.
//     The return value is LB_ERR if an error occurs; the return value 
//     is LB_ERRSPACE if insufficient space is available to store the new string.
//
int ReplaceString(int nIndex, LPCTSTR lpszString, int nImage = -1L)

ResetContent

Clears all the entries from the list box.

void ResetContent()

SetImageList

Sets the image list to use in the list box.

// Parameters:
//     [IN]   pImageList
//            Pointer to an CImageList object containing the image list
//            to use in the list box. Pass NULL to remove any previous
//            associated image list.
//
void SetImageList(CImageList* pImageList)

SetImage

Sets the image to use in a list box item.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the string.
//     [IN]   nImage
//            Specifies the zero-based index of the image
//            inside the imagelist to use.
//     [IN]   bRepaint
//            If TRUE the control will be repainted.
//
void SetImage(int nIndex, int nImage, BOOL bRepaint = TRUE)

GetImage

Returns the image index associated to a list box item.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the string.
//     [OUT]  lpnImage
//            Pointer to a int variable that will receive the index
//            of the image inside the imagelist.
//            This variable will be set to -1L if no image is associated.
//
void GetImage(int nIndex, LPINT lpnImage)

SetItemData

Sets the 32-bit value associated with the list box item.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the item.
//     [IN]   dwItemData
//            Specifies the value to be associated with the item.
//
// Return value:
//     LB_ERR if an error occurs.
//
int SetItemData(int nIndex, DWORD dwItemData)

GetItemData

Returns the 32-bit value associated with the list box item.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the item.
//
// Return value:
//     The 32-bit value associated with the item, or LB_ERR if an error occurs.
//
DWORD GetItemData(int nIndex)

SetItemDataPtr

Sets a pointer to a list box item.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the item.
//     [IN]   pData
//            Specifies the pointer to be associated with the item.
//
// Return value:
//     LB_ERR if an error occurs.
//
int SetItemDataPtr(int nIndex, void* pData)

GetItemDataPtr

Returns a pointer of a list box item.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the item.
//
// Return value:
//     Pointer associated with the item, or -1 if an error occurs.
//
void* GetItemDataPtr(int nIndex)

MoveUp

Moves a list box item up by one position.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the item.
//     [IN]   bSetCurSel
//            If TRUE the item will be highlighted
//
// Return value:
//      The zero-based index of the position at which the string was moved.
//      The return value is LB_ERR if an error occurs; the return value 
//      is LB_ERRSPACE if insufficient space is available to store the string.
//
int MoveUp(int nIndex, BOOL bSetCurSel = TRUE)

MoveDown

Moves a list box item down by one position.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the item.
//     [IN]   bSetCurSel
//            If TRUE the item will be highlighted
//
// Return value:
//      The zero-based index of the position at which the string was moved.
//      The return value is LB_ERR if an error occurs; the return value 
//      is LB_ERRSPACE if insufficient space is available to store the string.
//
int MoveDown(int nIndex, BOOL bSetCurSel = TRUE)

MoveTop

Moves a list box item to the top most position.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the item.
//     [IN]   bSetCurSel
//            If TRUE the item will be highlighted
//
// Return value:
//      The zero-based index of the position at which the string was moved.
//      The return value is LB_ERR if an error occurs; the return value 
//      is LB_ERRSPACE if insufficient space is available to store the string.
//
int MoveTop(int nIndex, BOOL bSetCurSel = TRUE)

MoveBottom

Moves a list box item to the bottom most position.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the item.
//     [IN]   bSetCurSel
//            If TRUE the item will be highlighted
//
// Return value:
//      The zero-based index of the position at which the string was moved.
//      The return value is LB_ERR if an error occurs; the return value 
//      is LB_ERRSPACE if insufficient space is available to store the string.
//
int MoveBottom(int nIndex, BOOL bSetCurSel = TRUE)

EnableItem

Enables or disables a list box item.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the item.
//     [IN]   bEnable
//            Specifies whether the given item is to be enabled or disabled.
//            If this parameter is TRUE, the item will be enabled.
//            If this parameter is FALSE, the item will be disabled.
//     [IN]   bRepaint
//            If TRUE the control will be repainted.
//
void EnableItem(int nIndex, BOOL bEnable = TRUE, BOOL bRepaint = TRUE)

IsItemEnabled

Specifies whether a list box item is enabled.

// Parameters:
//     [IN]   nIndex
//            Specifies the zero-based index of the item.
//
// Return value:
//      TRUE if the item is enabled; otherwise FALSE.
//
BOOL IsItemEnabled(int nIndex)

SetRowSelect

Sets how a selected list box item will be highlighted.

// Parameters:
//     [IN]   byRowSelect
//            Selection type. Can be one of the following values:
//            ST_FULLROWSELECT   Hilight full list box item (Default)
//            ST_FULLTEXTSELECT  Hilight half list box item (Part containing text)
//            ST_TEXTSELECT      Hilight only list box text
//     [IN]   bRepaint
//            If TRUE the control will be repainted.
//
void SetRowSelect(BYTE byRowSelect = ST_FULLROWSELECT, BOOL bRepaint = TRUE)

GetVersionI

Returns the class version as a short value.

// Return value:
//     Class version. Divide by 10 to get actual version.
//
static short GetVersionI()

GetVersionC

Returns the class version as a string value.

// Return value:
//     Pointer to a null-terminated string containig the class version.
//
static LPCTSTR GetVersionC()

History

• v1.0 (13/March/2002) First release

Disclaimer

The software and the accompanying files are distributed "as is" and without any warranties whether expressed or implied. No responsibilities for possible damages or even functionality can be taken. The user must assume the entire risk of using this software.