An editable list box is a Windows list box that contains items that the user can modify. For example, the user can modify the order of the list box items, create and delete items, and edit the content of individual items. The editable list box is similar to Visual Studio's Include and Library path editors, which is accessible by selecting Options from the Tools menu.

Table 14: Command Buttons for SECListBoxEditor

4.11.1 SECListBoxEditor

The SECListBoxEditor class implements an editable list box that supports item creation, deletion, reordering, and in-place text editing.

4.11.2 SECListBoxFileEditor

The SECListBoxFileEditor class is an editable list box that is specialized for entering a list of filenames.

An SECListBoxFileEditor object allows users to enter a filename by typing it or by selecting it from a file selection dialog. SECListBoxFileEditor inherits most of its functionality from SECListBoxEditor. In fact, its only method is an override of OnBrowse(), which launches a file selection dialog when the user presses a browse button.

4.11.3 SECListBoxDirEditor

An SECListBoxDirEditor object allows you to enter a directory name by typing it or by selecting it from a directory selection dialog. SECListBoxDirEditor inherits most of its functionality from SECListBoxEditor. In fact, its only method is an override of OnBrowse(), which launches a directory selection dialog when a browse button is pressed.

4.11.4 Using the List Box Edit Classes

The SECListBoxEditor-based classes are intended to replace existing list box controls in a parent window. Typically, the parent window is a dialog box, but the parent can be any CWnd with a list box control as a child. The steps for creating a list box edit control are the same whether you are using SECListBoxEditor, SECListBoxFileEditor, or SECListBoxDirEditor.

To incorporate an editable list box into a dialog window:

1. Use the resource editor to create a dialog template. Drop a list box control on the dialog.

2. Create a new dialog class and attach it to the dialog template created in the last step.

3. Add a member variable of type SECListBoxEditor to the class created in the last step.

4. Override the OnInitDialog() member of the dialog you created earlier. In your override, call SECListBoxEditor::Initialize() and pass the window ID of the list box control you want to convert to an editable list box. For example:

   BOOL MyDialogBox::OnInitDialog() { CDialog::OnInitDialog(); m_LBEditor.Initialize(this, IDC_LIST); m_LBEditor.SetWindowText("My Editable List Box:"); .. }

After the control is initialized, use the GetListBoxPtr() method to obtain a pointer to the CListBox-based helper object for manipulating and querying the list box control.

To incorporate an editable list box into an arbitrary CWnd:

1. Construct a CListBox object and then create the control in the parent window with the Create() method, assigning it a unique control ID.

2. After the list box control is created, construct an SECListBoxEditor object and call the Initialize() method, using the control ID you just created.

   ---

   It is important that both the CListBox and SECListBoxEditor objects have sufficient scope to exist while the control lives in the parent window.

   ---

4.11.5 Customizing the List Box Edit Classes

The command buttons are optional. A style flag passed into the initialization of the editable list box controls their creation. These style flags allow you to select editing features for the list box.

The style flags and their definitions are as follows.

Table 15: Style Flags for the List Box Edit Classes

Use these style flags with the SECListBoxEditor::Initialize() method by passing a style flag to its third parameter. Note that the styles for displaying the individual command buttons (LBE_NEWBUTTON, etc.) must be combined with LBE_BUTTONS.

4.11.6 Extending the Editable List Box Classes

The SECListBoxEditor and SECListBoxEditor-derived classes have a number of virtual methods that you can override to modify the standard behaviors. Some of the virtual callbacks provided by these classes are as follows:

Table 16: Virtual Callbacks for Edit List Box Classes

The SECListBoxEditor class implements an editable list box into which the user can enter arbitrary text. It does not support browsing. To support browsing, the control must understand the nature of the text contained in the list box. This is why the SECListBoxFileEditor and SECListBoxDirEditor classes exist. These classes inherit the functionality of an editable list box from SECListBoxEditor and add the ability to browse for a file or directory name. If you need to create an editable list box that supports browsing, derive a class from SECListBoxEditor and override its OnBrowse() method.

Typically, an overridden OnBrowse() method opens an application-specific modal dialog, accepts the user's choice and writes the new value back to the selected list box item. Refer to the implementations of OnBrowse() in SECListBoxDirEditor and SECListBoxFileEditor for examples of how to do this.

4.11.7 Editable List Box Sample