Enabling Multiselection in the MMC

Multiselection is allowed only in the result pane. By default, multiselection is disabled in the list view. To enable multiselection, set the MMC_VIEW_OPTIONS_MULTISELECT flag in the ViewOptions parameter during calls to the snap-in's IComponent::GetResultViewType implementation.

What happens on multiselection depends on the items that are selected in the result pane. Possible scenarios include:

• Scope or result items owned by a single snap-in are selected.
• Scope items owned by multiple snap-ins are selected.

Multiselection and Items Owned by a Single Snap-in

Multiselection for items owned by a single snap-in works in the following way:

1. In a list view for which multiselection is enabled, the user selects one scope or result item and then selects another one.

2. Upon selection of the next item, MMC calls the current view's IComponent::QueryDataObject implementation. The cookie parameter passed into the call contains the value of the MMC_MULTI_SELECT_COOKIE special cookie, indicating to the snap-in that MMC is requesting a special, snap-in-defined multiselection data object.

   Be aware that, in general, snap-ins can use the IS_SPECIAL_COOKIE macro to determine whether or not the value contained in the cookie parameter refers to a special cookie.

3. The snap-in creates the multiselection data object that identifies the items currently selected in the result pane, and returns it to MMC. The snap-in should call IResultData::GetNextItem with RESULTDATAITEM.nState = LVIS_SELECTED to get all its selected items.

   The multiselection data object provided by the snap-in must also provide the list of node type GUIDs of all its currently selected items. This is done by supporting the CCF_OBJECT_TYPES_IN_MULTI_SELECT clipboard format in the multiselection data object's IDataObject::GetData implementation. The data format used with the clipboard format is an SMMCObjectTypes structure. MMC uses this structure to determine the extension snap-ins that extend any of the selected items.

4. MMC calls the snap-in's IComponent::Notify implementation for the current view with the MMCN_SELECT notification to indicate that items are selected in the result pane. The lpDataObject parameter contains the multiselection data object created by the snap-in.

5. The snap-in examines the multiselection data object and enables verbs for the selected items. Be aware that the snap-in only must explicitly enable verbs for any one of the selected items. MMC then sets the verbs for the other items. For more information about verb behavior during multiselection, see Multiselection and Standard Verbs.

6. MMC then calls the GetData method of the multiselection data object with the CCF_OBJECT_TYPES_IN_MULTI_SELECT clipboard format to request a list of the node type GUIDs of all the currently selected items. The snap-in uses the SMMCObjectTypes structure for providing the requested information. MMC uses CCF_OBJECT_TYPES_IN_MULTI_SELECT to determine which extension snap-ins extend any of the selected items.

7. MMC then finds which extensions can extend all of the selected items and creates them when the appropriate extension feature is required, for example, when the user displays a selected item's context menu.

8. Control now returns to the user. If the user selects another item as part of the multiselection, MMC releases its interface to the multiselection data object and requests a new one. Steps 2 through 6 in this process are then repeated.

   If the user instead operates on the multiselection by, for example, activating one of the enabled verbs, what happens next depends on the performed operation. See User Operations During Multiselection for details.

9. After the multiselection operation is completed, MMC releases its interface to the multiselection data object.

Multiselection and Items Owned by Multiple Snap-ins

Scope items owned (inserted) by multiple snap-ins can be part of a multiselection. In this case, multiselection works in essentially the same way as it does in the case when all items are owned by a single snap-in, with the following differences:

• MMC calls the IComponent::QueryDataObject implementation (with cookie == MMC_MULTI_SELECT_COOKIE) of the primary snap-in and each namespace extension that owns any of the selected items to request a multiselection data object. Consequently, all namespace extensions whose items are allowed to be part of a multiselection must implement IComponent.

  Be aware that, in the call to IResultData::GetNextItem with RESULTDATAITEM.nState = LVIS_SELECTED, MMC will only return items that the calling snap-in owns, skipping over the items owned by other snap-ins. Therefore, each snap-in involved in a multiselection provides a multiselection data object that identifies only its items currently selected in the result pane.

• During some multiselection operations (for example, paste operations) MMC creates a composite data object consisting of an array of multiselection data objects provided by all the snap-ins involved in a multiselection. This composite data object is forwarded to snap-ins, which can then use the CCF_MULTI_SELECT_SNAPINS clipboard format for extracting the array of multiselection data objects. The data format used with the clipboard format is the SMMCDataObjects structure.

Multiselection and Standard Verbs

For multiselection, verbs behave as follows:

• Open, rename, and refresh are disabled by default.
• Copy, cut, and delete are inclusive. That is, if one of the selected items can be copied, then copy is enabled. The same is true for the cut and delete verbs.
• Property and print are exclusive and are applicable only when items from a single snap-in are selected. Their state depends on the snap-in.

User Operations During Multiselection

MMC allows the following user operations on multiply selected items:

• Activation of any of the allowed verbs, either by using context menus or the corresponding toolbar buttons.
• Selection of any context menu items, placed either by the primary snap-in or any of its extensions. Be aware that MMC only gives extension snap-ins that extend all the selected items an opportunity to add their extensions.
• Drag-and-drop operations.

Data Objects Sent During Multiselection Operations

The following table lists the types of data objects that can be sent to snap-ins in response to user operations that involve multiselection items.

Multiselection and Drag and Drop Operations

The Drag and Drop section discusses how to support drag-and-drop functionality in a snap-in. However, the discussion and procedures outlined in that section only discuss drag-and-drop operations that involve a single selected item. Snap-ins that allow drag-and-drop operations on multiple items need to be aware of the following additional issues:

1. The procedure outlined in Multiselection: Implementation Details must be implemented in all source snap-ins that allow items inserted by them to be part of a multiselection.

2. During the MMCN_QUERY_PASTE notification message, MMC provides a composite data object that contains an array of multiselection data objects. The multiselection data objects are provided by the source snap-ins (primary or extension) that own items in the multiselection. Be aware that each source snap-in is responsible for defining the format of the multiselection data object that it provides.

   The destination snap-in can use the CCF_MMC_MULTISELECT_DATAOBJECT clipboard format to determine whether or not the data object it receives during MMCN_QUERY_PASTE is a composite data object.

   If the data object is a composite data object, the destination snap-in must use the CCF_MULTI_SELECT_SNAPINS clipboard format for extracting the array of multiselection data objects from it. The data format used with the clipboard format is the SMMCDataObjects structure.

   The destination snap-in can examine as many of the multiselection data objects as it must in determining whether or not to accept the paste.

3. If the destination accepts the paste operation, MMC sends it an MMCN_PASTE notification message, once for each multiselection data object. The lpDataObject parameter contains the pointer to a multiselection data object.

   If objects that are being pasted need to be deleted at the source as a result of a previous cut or move operation, then the param parameter contains a pointer to an IDataObject interface. If the paste is successful, the destination snap-in should return a data object with the list of successfully pasted items, which in turn will be passed to each source snap-in for the MMCN_CUTORMOVE notification.

   The format to communicate the list of items successfully pasted should be defined by each source snap-in. The most straightforward mechanism is for the destination snap-in to manipulate the multiselection data object in a manner defined by each source snap-in, increment the data object's reference count, and then return it in the param parameter.

   Be aware that the param for MMCN_PASTE will be 0 if it does not involve a previous cut or move operation.

4. After a successful cut or move operation, each source snap-in will receive the MMCN_CUTORMOVE notification message. The lpDataObject parameter contains the data object returned by the destination snap-in after a successful paste. The source snap-in must examine the data object for the list of the successfully pasted items and perform whatever actions it deems necessary on the items.

   If the mechanism suggested in Step 3 is followed by the destination snap-in, each source snap-in will receive back its own multiselection data object in the MMCN_CUTORMOVE notification message.

Related topics

Multiselection: Implementation Details

Enabling MMC Standard Verbs

Using IPropertySheetProvider Directly