A list view control simplifies the job of building an application that works with lists of objects and organizes those objects in such a way that the program’s user can easily determine each object’s attributes. For example, consider a group of files on a disk. Each file is a separate object associated with a number of attributes, including the file’s name, size, and the most recent modification date. When you explore a folder, you see files either as icons in a window or as a table of entries, each entry showing the attributes associated with the files. You have full control over the way that the file objects are displayed, including which attributes are shown and which are unlisted. The common controls include something called a list view control, so you can organize lists in exactly the same way. If you’d like to see an example of a full-fledged list view control, open the Windows Explorer (see Figure 8.3). The right side of the window shows how the list view control can organize objects in a window. (The left side of the window contains a tree view control, which you will learn about later in this unit in the section titled "The Tree View Control.") In the figure, the list view is currently set to the report view, in which each object in the list receives its own line, showing not only the object’s name but also the attributes associated with that object.

FIG. 8.3 Windows Explorer uses a list view control to organize file information.

The user can change the way objects are organized in a list view control. Figure 8.4, for example, shows the list view portion of the Explorer set to the large-icon setting, and Figure 8.5 shows the small-icon setting, which enables the user to see more objects (in this case, files) in the window. With a list view control, the user can edit the names of objects in the list and in the report view can sort objects, based on data displayed in a particular column.

FIG. 8.4 Here’s Explorer’s list view control set to large icons.

FIG. 8.5 Here’s Explorer’s list view control set to small icons.

Common will also sport a list view control, although not as fancy as Explorer’s. You will add a list view and some buttons to switch between the small-icon, large-icon, list, and report views.

How does all this happen? Well, it does require more work than the progress bar, or up-down controls (it could hardly take less). You will write the rest of CreateListView(), which performs the following tasks:

After creating the image lists, CreateListView() goes on to create the list view control by calling the class’s Create() member function, as usual. Add these lines to CreateListView():

The CListCtrl class, of which m_listView is an object, defines special styles to be used with list view controls. Table 8.2 lists these special styles and their descriptions.

The third task in CreateListView() is to associate the control with its image lists with two calls to SetImageList(). Add these lines to CreateListView():

This function takes two parameters: a pointer to the image list and a flag indicating how the list is to be used. Three constants are defined for this flag: LVSIL_SMALL (which indicates that the list contains small icons), LVSIL_NORMAL (large icons), and LVSIL_STATE (state images). The SetImageList() function returns a pointer to the previously set image list, if any.

The fourth task is to create the columns for the control’s report view. You need one main column for the item itself and one column for each sub-item associated with an item. For example, in Explorer’s list view, the main column holds file and folder names. Each additional column holds the sub-items for each item, such as the file’s size, type, and modification date. To create a column, you must first declare a LV_COLUMN structure. You use this structure to pass information to and from the system. After you add the column to the control with InsertColumn(), you can use the structure to create and insert another column. Listing 8.4 shows the LV_COLUMN structure.

The mask member of the structure tells the system which members of the structure to use and which to ignore. The flags you can use are

The fmt member denotes the column’s alignment and can be LVCFMT_CENTER, LVCFMT_LEFT, or LVCFMT_RIGHT. The alignment determines how the column’s label and items are positioned in the column.

NOTE: The first column, which contains the main items, is always aligned to the left. The other columns in the report view can be aligned however you like.

The cx field specifies the width of each column, whereas pszText is the address of a string buffer. When you’re using the structure to create a column (you also can use this structure to obtain information about a column), this string buffer contains the column’s label. The cchTextMax member denotes the size of the string buffer and is valid only when retrieving information about a column.

CreateListView() creates a temporary LV_COLUMN structure, sets the elements, and then inserts it into the list view as column 0, the main column. This process is repeated for the other two columns. Add these lines to CreateListView():

The fifth task in CreateListView() is to create the items that will be listed in the columns when the control is in its report view. Creating items is not unlike creating columns. As with columns, Visual C++ defines a structure that you must initialize and pass to the function that creates the items. This structure is called LV_ITEM and is defined as shown in Listing 8.5.

In the LV_ITEM structure, the mask member specifies the other members of the structure that are valid. The flags you can use are

The iItem member is the index of the item, which you can think of as the row number in report view (although the items’ position can change when they’re sorted). Each item has a unique index. The iSubItem member is the index of the sub-item, if this structure is defining a sub-item. You can think of this value as the number of the column in which the item will appear. For example, if you’re defining the main item (the first column), this value should be 0.

The state and stateMask members hold the item’s current state and its valid states, which can be one or more of the following:

The pszText member is the address of a string buffer. When you use the LV_ITEM structure to create an item, the string buffer contains the item’s text. When you are obtaining information about the item, pszText is the buffer where the information will be stored, and cchTextMax is the size of the buffer. If pszText is set to LPSTR_TEXTCALLBACK, the item uses the callback mechanism. Finally, the iImage member is the index of the item’s icon in the small-icon and large-icon image lists. If set to I_IMAGECALLBACK, the iImage member indicates that the item uses the callback mechanism.

CreateListView() creates a temporary LV_ITEM structure, sets the elements, and then inserts it into the list view as item 0. Two calls to SetItemText() add sub-items to this item so that each column has some text in it, and the whole process is repeated for two other items. Add these lines:

Now you have created a list view with three columns and three items. Normally the values wouldn’t be hard-coded, as this was, but instead would be filled in with values calculated by the program.

You can set a list view control to four different types of views: small icon, large icon, list, and report. In Explorer, for example, the toolbar features buttons that you can click to change the view, or you can select the view from the View menu. Although Common doesn’t have a snazzy toolbar like Explorer, it will include four buttons (labeled Small, Large, List, and Report) that you can click to change the view. Those buttons are created as the sixth step in CreateListView(). Add these lines to complete the function:

Edit the message map in CommonView.h to declare the handlers for each of these buttons so that it looks like this:

Edit the message map in CommonView.cpp to associate the messages with the functions:

Choose View, Resource Symbols and click New to add new IDs for each constant referred to in this new code:

The four handlers will each call SetWindowLong(), which sets a window’s attribute. Its arguments are the window’s handle, a flag that specifies the value to be changed, and the new value. For example, passing GWL_STYLE as the second value means that the window’s style should be changed to the style given in the third argument. Changing the list view control’s style (for example, to LVS_SMALLICON) changes the type of view that it displays. With that in mind, add the four handler functions to the bottom of CommonView.cpp:

At this point you can build Common again and test it. Click each of the four buttons to change the view style. Also, try editing one of the labels in the first column of the list view.

Figure 8.1 already showed you the report view for this list view. Figure 8.6 shows the application’s list view control displaying small icons, and Figure 8.7 shows the large icons. (Some controls in these figures have yet to be covered in this unit.)

You can do a lot of other things with a list view control. A little time invested in exploring and experimenting can save you a lot of time writing your user interface.

FIG. 8.6 Here’s the sample application’s list view control set to small icons.

FIG. 8.7 Here’s the sample application’s list view control set to large icons.