wxListCtrl

The list control displays items in one of four views: a multi-column list view, a multi-column report view with optional icons, a large icon view, and a small icon view. See Figure 12-2 for examples of these views from the wxListCtrl sample. Each item in a list control is identified by a long integer index representing its zero-based position in the list, which will change as items are added and deleted or as the content is sorted. Unlike the tree control, the default is to allow multiple selections, and single-selection can be specified with a window style. You can supply a sort function if you need the items to be sorted. The report view can display an optional header, whose columns respond to mouse clicksuseful for sorting the contents of the column, for example. The widths of a report view's columns can be changed either by the application or by dragging on the column dividers.

Figure 12-2. wxListCtrl in report, list, icon, and small icon modes

Client data can be associated with items, but it works differently from wxtreeCtrl. Each item has a long integer available for client data, so if you have objects to associate with items, this must be done by the applicationfor example, with a mapping from long integer to object pointerand you must free this data yourself.

wxListCtrl Styles

Table 12-3 lists the styles you can pass to the wxListCtrl constructor or Create function. Also refer to the available styles for wxWindow in Table 4-1.

Table 12-3. wxListCtrl Window Styles

wxLC_LIST	A multicolumn list view with optional small icons. Columns are computed automaticallyyou don't set columns as in wxLC_REPORT. In other words, the list wraps, unlike a wxListBox.
wxLC_REPORT	A single or multicolumn report view with optional header.
wxLC_VIRTUAL	Specifies that the application provides text on demand; may only be used with wxLC_REPORT.
wxLC_ICON	Large icon view with optional labels.
wxLC_SMALL_ICON	Small icon view with optional labels.
wxLC_ALIGN_TOP	Icons align to the top. Windows only.
wxLC_ALIGN_LEFT	Icons align to the left.
wxLC_AUTO_ARRANGE	Icons arrange themselves. Windows only.
wxLC_EDIT_LABELS	Labels are editable; the application will be notified when editing starts.
wxLC_NO_HEADER	No header will be shown in report mode.
wxLC_SINGLE_SEL	Specifies single-selection; the default is multiple-selection.
wxLC_SORT_ASCENDING	Sorts in ascending order. The application must still supply a comparison callback in SortItems.
wxLC_SORT_DESCENDING	Sorts in descending order. The application must still supply a comparison callback in SortItems.
wxLC_HRULES	Draws light horizontal rules between rows in report mode.
wxLC_VRULES	Draws light horizontal rules between columns in report mode.

wxListCtrl Events

wxListCtrl generates wxListEvent events, described in Table 12-4. These events propagate up the window parent-child hierarchy. Events dealing with a single item return the item index with wxListEvent::GetIndex.

Table 12-4. wxListCtrl Events

EVT_LIST_BEGIN_DRAG(id, func) EVT_LIST_BEGIN_RDRAG(id, func)	Use these events to detect a drag start event; you need to supply code toimplement the rest of the drag behavior. Call wxListEvent::GetPoint to get the position of the mouse pointer.
EVT_LIST_BEGIN_LABEL_EDIT(id, func) EVT_LIST_END_LABEL_EDIT(id, func)	Use these events to detect when the user has started or finished editing a label. The edit can be vetoed by calling the event object's Veto function. wxListEvent::GetText returns the label.
EVT_LIST_DELETE_ITEM(id, func) EVT_LIST_DELETE_ALL_ITEMS(id, func)	These events tell you when an item was deleted or when all items were deleted.
EVT_LIST_ITEM_SELECTED(id, func) EVT_LIST_ITEM_DESELECTED(id, func)	Used to detect a selection or deselection event.
EVT_LIST_ITEM_ACTIVATED(id, func)	Detect an activation with the Enter key or a double-click.
EVT_LIST_ITEM_FOCUSED(id, func)	Use to be notified when the focus has changed to a different item.
EVT_LIST_ITEM_MIDDLE_CLICK(id, func) EVT_LIST_ITEM_RIGHT_CLICK(id, func)	Use to detect when the middle or right mouse button has been clicked.
EVT_LIST_KEY_DOWN(id, func)	Use to detect when a key has been pressed. Use wxListEvent::GetKeyCode to find the key pressed.
EVT_LIST_INSERT_ITEM(id, func)	Use to detect the insertion of an item.
EVT_LIST_COL_CLICK(id, func) EVT_LIST_COL_RIGHT_CLICK(id, func)	Use to detect a left or right mouse click on a column. Use wxListEvent::Get Column in conjunction with these events.
EVT_LIST_COL_BEGIN_DRAG(id, func) EVT_LIST_COL_DRAGGING(id, func) EVT_LIST_COL_END_DRAG(id, func)	Generated when a column is being resized; you can veto the begin drag event. Use wxListEvent::GetColumn in conjunction with these events.
EVT_LIST_CACHE_HINT(id, func)	If you are implementing a virtual list control, you may want to update internal data structures before a range of items is drawn. Use this event to do the updating at the right time, calling wxListEvent::GetCacheFrom and wxListEvent::GetCacheTo to find the items that need updating.

wxListItem

wxListItem is a class you can use to insert an item, set an item's properties, or retrieve information from an item.

Use SetMask to indicate which properties you want to be taken into account, as described in Table 12-5.

Table 12-5. wxListItem Mask Flags

wxLIST_MASK_STATE	The state property is valid.
wxLIST_MASK_TEXT	The text property is valid.
wxLIST_MASK_IMAGE	The image property is valid.
wxLIST_MASK_DATA	The data property is valid.
wxLIST_MASK_WIDTH	The width property is valid.
wxLIST_MASK_FORMAT	The format property is valid.

Call SetId to set the zero-based item position, and call SetColumn to set the zero-based column position if the control is in report mode.

Call SetState to set the item state, as listed in Table 12-6.

Table 12-6. wxListItem State Styles

wxLIST_STATE_DONTCARE	We don't care what the state is.
wxLIST_STATE_DROPHILITED	The item is highlighted to receive a drop event (Windows only).
wxLIST_STATE_FOCUSED	The item has the focus.
wxLIST_STATE_SELECTED	The item is selected.
wxLIST_STATE_CUT	The item is in the cut state (Windows only).

Call SetStateMask to indicate which states you are modifying. This method uses the same symbols as for SetState.

Call SetText to set the label or header text, and call SetImage to set the zero-based index into an image list.

Call SetData with a long integer argument to associate data with the item.

For columns only, call SetFormat with wxLIST_FORMAT_LEFT, wxLIST_FORMAT_RIGHT, or wxLIST_FORMAT_CENTRE (identical to wxLIST_FORMAT_CENTER). Also for columns only, call SetColumnWidth to set the column's width.

Other functions set various additional visual properties: SetAlign, SetBackgroundColour, SetTextColour, and SetFont. These don't require a mask flag to be specified. All wxListItem functions have equivalent accessors prefixed by Get for retrieving information about an item.

Here's an example of using wxListItem to select the second item, set its text label, and color it red:

 wxListItem item; item.SetId(1); item.SetMask(wxLIST_MASK_STATE|wxLIST_MASK_TEXT); item.SetStateMask(wxLIST_STATE_SELECTED); item.SetState(wxLIST_STATE_SELECTED); item.SetTextColour(*wxRED); item.SetText(wxT("Red thing")); listCtrl->SetItem(item); 

As an alternative to using wxListItem, you can set and get properties for an item with wxListCtrl convenience functions such as SetItemText, SetItemImage, SetItemState, GetItemText, GetItemImage, GetItemState, and so on as described in the following.

wxListCtrl Member Functions

These are the important wxListCtrl functions.

Call Arrange to arrange the items in icon or small icon view, on Windows only.

Use AssignImageList to associate an image list and have wxListCtrl handle its deletion; use SetImageList if you don't want wxListCtrl to delete it. Pass wxIMAGE_LIST_NORMAL or wxIMAGE_LIST_SMALL to tell wxListCtrl what set of icons this image list will be used for. GetImageList retrieves a pointer to either list.

InsertItem inserts an item at the specified position in the control. You can pass a wxListItem object having set its member variables. Alternatively, you can pass an item index and a string label, or an item index and an image index, or an item index, a label, and an image index. InsertColumn inserts a column in report view.

ClearAll deletes all items and (in report view) columns, and it generates an all-items deletion event. DeleteAllItems deletes all items but not columns and generates an all-items deletion event. DeleteItem deletes a single item and generates an item deletion event. DeleteColumn deletes a column in report view.

Use SetItem to set information about an item: you can pass a wxListItem object as explained previously, or you can pass an index, column, label, and image index. GetItem can be used to get information about the index specified with wxListItem::SetId.

Call SetItemData with an index and a long data value to associate application defined data with the item. For most platforms, you can store a pointer in this integer value, but on some platforms, a pointer will not fit into an integer. In these cases, you can use a hashmap to map from integer to object pointer, for example. GetItemData retrieves the item for the given index. Note that if the position of an item moves due to sorting, insertion, or removal, the index of the item may change, but its item data will remain the same, so this is a way of identifying an item.

Use SetItemImage to change the image associated with an item; it takes an item index and an index into the image list.

SetItemState sets the state for the given item; you must supply a state mask to specify which state flags are being changed. See the description for wxListItem in the previous section for more details. GetItemState is used to retrieve the state for a given item.

Use SetItemText to set the item's label and GetItemText to retrieve the label.

SetTextColour sets the text color for all items, and SetBackgroundColour sets the background color for the control. SetItemTextColour and SetItemBackgroundColour set an individual item's text and background colors, in report view only. The usual getters are available to retrieve text and background colors.

EditLabel starts editing a label and sends a wxEVT_LIST_BEGIN_LABEL_EDIT event. You can get the current text control used for editing with GetEditControl (Windows only).

Use EnsureVisible if you need a particular item to be visible. ScrollList scrolls by a given number of pixels in each orientation (Windows only). Use RefreshItem or RefreshItems to refresh the appearance of an item or a range of items, particularly when using a virtual list control when the underlying data has changed. GetTopItem returns the index of the topmost visible item when in list or report view.

FindItem is a versatile overloaded function that can be used to search for items with a given label, data, or position. GetNextItem is used to search for an item with the given state (for example, to find all selected items). Use HitTest to find an item at a given point. GetItemPosition returns the position of an item in icon or small icon view in client coordinates, and GetItemRect returns an item's size and position in client coordinates.

You can change the style of a wxListCtrl dynamically, without having to destroy and re-create it: use SetSingleStyle to set a style such as wxLC_REPORT. Pass false to this function to remove the style.

Use SetColumn in report mode to set information about a column, such as header label and width: see wxListItem in the previous section. Use SetColumnWidth to set a column's width, as a simpler alternative to SetColumn. You can get column information with GetColumn and GetColumnWidth. Get the number of columns with GetColumnCount (report view only).

Get the number of items in a list control with GetItemCount and the number of selected items with GetSelectedItemCount. GetCountPerPage returns the number of items that can fit vertically in the visible area of the control (in list or report view) or the total number of items in the control (icon or small icon view).

Finally, SortItems can be used to sort the items in a list control. Pass the address of a wxListCtrlCompare function that takes two item data values and a further data integer, and returns an integer representing the ordering of the two items. This integer should be zero for identity, negative if the first is less than the second, and positive if the first is greater than the second. For sorting to work, you must associate a long integer value with each item (via wxListItem::SetData, for example). These values will be passed to the comparison function.

Using wxListCtrl

The following fragment shows how to create and populate a report list control. The list has three columns and ten items, each with a 16x16 file icon at the start of the row.

 #include "wx/listctrl.h" // Images for report items #include "file.xpm" #include "folder.xpm" // Create a list in report mode wxListCtrl* listCtrlReport = new wxListCtrl(     this, wxID_ANY, wxDefaultPosition, wxSize(400, 400),     wxLC_REPORT|wxLC_SINGLE_SEL); // Assign an image list to the control wxImageList* imageList = new wxImageList(16, 16); imageList->Add(wxIcon(folder_xpm)); imageList->Add(wxIcon(file_xpm)); listCtrlReport->AssignImageList(imageList, wxIMAGE_LIST_SMALL); // Insert three columns wxListItem itemCol; itemCol.SetText(wxT("Column 1")); itemCol.SetImage(-1); listCtrlReport->InsertColumn(0, itemCol); listCtrlReport->SetColumnWidth(0, wxLIST_AUTOSIZE ); itemCol.SetText(wxT("Column 2")); itemCol.SetAlign(wxLIST_FORMAT_CENTRE); listCtrlReport->InsertColumn(1, itemCol); listCtrlReport->SetColumnWidth(1, wxLIST_AUTOSIZE ); itemCol.SetText(wxT("Column 3")); itemCol.SetAlign(wxLIST_FORMAT_RIGHT); listCtrlReport->InsertColumn(2, itemCol); listCtrlReport->SetColumnWidth(2, wxLIST_AUTOSIZE ); // Insert ten items for ( int i = 0; i < 10; i++ ) {     int imageIndex = 0;     wxString buf;     // Insert an item, with a string for column 0,     // and image index 0     buf.Printf(wxT("This is item %d"), i);     listCtrlReport->InsertItem(i, buf, imageIndex);     // The item may change position due to e.g. sorting,     // so store the original index in the item's data     listCtrlReport->SetItemData(i, i);     // Set a string for column 1     buf.Printf(wxT("Col 1, item %d"), i);     listCtrlReport->SetItem(i, 1, buf);     // Set a string for column 2     buf.Printf(wxT("Item %d in column 2"), i);     listCtrlReport->SetItem(i, 2, buf); } 

Virtual List Controls

Normally, wxListCtrl stores the label, image, and visual attributes for each item. This is fine for a modest amount of data, but if you have thousands of items, you may want to consider implementing a virtual list control. You supply the virtual functions OnGetItemLabel, OnGetItemImage, and OnGetItemAttr for the control to call when it needs the information. You must call SetItemCount to indicate how many items there are in the list control because you won't be appending any items in the usual way. You can optionally use EVT_LIST_CACHE_HINT to update your internal structures for a given range of items, just before painting is about to happen. Here are trivial examples of the three overridden functions:

 wxString MyListCtrl::OnGetItemText(long item, long column) const {     return wxString::Format(wxT("Column %ld of item %ld"), column, item); } int MyListCtrl::OnGetItemImage(long WXUNUSED(item)) const {     // Return the zeroth image for all items     return 0; } wxListItemAttr *MyListCtrl::OnGetItemAttr(long item) const {     // Use internally stored attributes for every other items     return item % 2 ? NULL : (wxListItemAttr *)&m_attr; } 

To create and populate the virtual list, we don't append any items; we simply set the item count to a ridiculously large number:

 virtualListCtrl = new MyListCtrl(parent, wxID_ANY,       wxDefaultPosition, wxDefaultSize, wxLC_REPORT|wxLC_VIRTUAL); virtualListCtrl->SetImageList(imageListSmall, wxIMAGE_LIST_SMALL); virtualListCtrl->InsertColumn(0, wxT("First Column")); virtualListCtrl->InsertColumn(1, wxT("Second Column")); virtualListCtrl->SetColumnWidth(0, 150); virtualListCtrl->SetColumnWidth(1, 150); virtualListCtrl->SetItemCount(1000000); 

When the underlying data changes in the control, set the item count if it has changed and call wxListCtrl::RefreshItem or wxListCtrl::RefreshItems.

For a full sample, please see samples/listctrl.