Using IColumnData
MMC allows snap-ins to access the column configuration data of a column set using the IColumnData interface. This section covers how and when snap-in developers can use the interface.
The IColumnData interface can be used in any of the following situations:
When handling an MMCN_EXPAND notification, a snap-in can use the methods of IColumnData to examine persisted column configuration data for the selected scope item's list view and to modify it if required. Also, if the snap-in initiates data fetching in this event, it can optimize by checking which columns will be visible.
The snap-in receives an MMCN_COLUMNS_CHANGED notification when the user changes the visible status of any column in the column set. Be aware that MMCN_COLUMNS_CHANGED provides information about the columns of the column set that will be visible after the snap-in returns with S_OK or S_FALSE. If the snap-in calls IColumnData::GetColumnConfigData before returning from its MMCN_COLUMNS_CHANGED notification handler (with S_OK or S_FALSE), it will receive the current column settings.
The param parameter of the MMCN_COLUMNS_CHANGED notification tells the snap-in which columns are going to be visible due to the user changes. The snap-in can reject the changes by returning E_UNEXPECTED in its MMCN_COLUMNS_CHANGED notification handler. In this case, the snap-in is responsible for informing the user why it is refusing the changes, for example, by means of a message box.
MMC applies persisted data to a list view during the snap-in's handling of the MMCN_SHOW notification message. MMC applies the data during MMCN_SHOW because it is during this event that the snap-in sets up the list view columns in the result pane.
When receiving an MMCN_SHOW notification with the arg parameter set to TRUE (indicating that the snap-in should set up the result pane), the snap-in can view or modify the configuration data before inserting columns. It can, for example, use the IColumnData::GetColumnConfigData method to see which columns in the column set are visible. Then, to optimize populating list view columns, the snap-in can choose to fetch data for and display only visible columns in the list view.
The snap-in can also modify (and persist) configuration data using IColumnData::SetColumnConfigData or IColumnData::SetColumnSortData.
Be aware that MMC applies the persisted column configuration data for the column set immediately after the snap-in has inserted the first item into the list view (using IResultData::InsertItem). MMC assumes at this point that the snap-in has completed adding its columns. If the snap-in must either view or modify configuration data that MMC will apply to the column set, it must do so before inserting the first list view item.
Before the snap-in receives an MMCN_SHOW notification with the arg parameter set to FALSE (indicating that the result pane is being torn down and possibly replaced), MMC has already persisted any user customizations made to the list view (such as which columns are visible or hidden).
When the snap-in receives MMCN_SHOW (with arg=FALSE), it can choose to modify the persisted data. MMC then applies the (newly) persisted data to the column set the next time the user selects its item. The persisted data is also applied to all column sets with the same ID, so if the user selects a different item with the same column set ID, MMC will also apply the persisted data to it.
Be aware that the snap-in can undo some or all of the user customizations made to the list view.
Currently, when handling an MMCN_SHOW notification, if a snap-in inserts result items asynchronously (the columns are inserted by the notification handler, but items are inserted in the list view later) then it cannot sort the items. In this case, the snap-in can use the methods of IColumnData to get the persisted sort data and then perform the sorting at a later time.
A snap-in can add or remove columns in a column set using the methods of IHeaderCtrl2. See IHeaderCtrl2 and Column Persistence for information on how this relates to column persistence.
Only user-initiated changes are persisted in memory automatically by MMC. The snap-in must use IColumnData to persist in memory any changes that it initiates. Examples of snap-in-initiated changes include changing the visibility status of a column during its insertion (with IHeaderCtrl2::InsertColumn) and modifying the width of a column (with IHeaderCtrl2::SetColumnWidth).
Be aware that the IColumnData interface is not designed to be an alternative to the IHeaderCtrl2 interface. Snap-ins should use IHeaderCtrl2 as much as possible, because it allows the user to see any snap-in changes to a list view immediately. IColumnData should only be used in situations for which IHeaderCtrl2 is not designed.
Related topics