CListBox

The CListBox class provides the functionality of a Windows list box. A list box displays a list of items, such as filenames, that the user can view and select.

In a single-selection list box, the user can select only one item. In a multiple-selection list box, a range of items can be selected. When the user selects an item, it is highlighted and the list box sends a notification message to the parent window.

You can create a list box either from a dialog template or directly in your code. To create it directly, construct the CListBox object, then call the Create member function to create the Windows list-box control and attach it to the CListBox object. To use a list box in a dialog template, declare a list-box variable in your dialog box class, then use DDX_Control in your dialog box class's DoDataExchange function to connect the member variable to the control. (ClassWizard does this for you automatically when you add a control variable to your dialog box class.)

Construction can be a one-step process in a class derived from CListBox. Write a constructor for the derived class and call Create from within the constructor.

If you want to handle Windows notification messages sent by a list 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 list-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( );

Following is a list of potential message-map entries and a description of the cases in which they would be sent to the parent:

• ON_LBN_DBLCLK   The user double-clicks a string in a list box. Only a list box that has the LBS_NOTIFY style will send this notification message. 
  
  
• ON_LBN_ERRSPACE   The list box cannot allocate enough memory to meet the request.
  
  
• ON_LBN_KILLFOCUS   The list box is losing the input focus.
  
  
• ON_LBN_SELCANCEL   The current list-box selection is canceled. This message is only sent when a list box has the LBS_NOTIFY style.
  
  
• ON_LBN_SELCHANGE   The selection in the list box is about to change. This notification is not sent if the selection is changed by the CListBox::SetCurSel member function. This notification applies only to a list box that has the LBS_NOTIFY style. The LBN_SELCHANGE notification message is sent for a multiple-selection list box whenever the user presses an arrow key, even if the selection does not change.
  
  
• ON_LBN_SETFOCUS   The list box is receiving the input focus.
  
  
• ON_WM_CHARTOITEM   An owner-draw list box that has no strings receives a WM_CHAR message.
  
  
• ON_WM_VKEYTOITEM   A list box with the LBS_WANTKEYBOARDINPUT style receives a WM_KEYDOWN message.

If you create a CListBox object within a dialog box (through a dialog resource), the CListBox object is automatically destroyed when the user closes the dialog box.

If you create a CListBox object within a window, you may need to destroy the CListBox object. If you create the CListBox object on the stack, it is destroyed automatically. If you create the CListBox object on the heap by using the new function, you must call delete on the object to destroy it when the user closes the parent window.

If you allocate any memory in the CListBox object, override the CListBox destructor to dispose of the allocation.

#include <afxwin.h>

Class Members |  Base Class |  Hierarchy Chart

Sample   MFC Sample CTRLTEST

See Also   CWnd, CButton, CComboBox, CEdit, CScrollBar, CStatic