Working with the Scope Pane
This section discusses how the features associated with a snap-in's scope pane are implemented.
MMC defines several interfaces and other language constructs that a snap-in can use to work with the scope pane.
The IConsoleNamespace2 interface enables snap-ins to manipulate items in the scope pane. InsertItem and DeleteItem insert or remove single items from the scope pane. You can set or retrieve single items by using the SetItem and GetItem methods. GetChildItem, GetNextItem, and GetParentItem walk the tree's items. The Expand method enables a snap-in to expand an item in the namespace without visibly expanding the item in the scope pane. Finally, AddExtension enables a snap-in to add an extension snap-in that dynamically extends the namespace of a selected item.
The IConsole2 interface also contains a number of methods that snap-ins can use for working with scope items. The Expand method enables a snap-in to expand or collapse an item in the scope pane. The SelectScopeItem method enables a snap-in to force the selection of a specified item, and the NewWindow method allows the snap-in to programmatically create a new multiple-document interface (MDI) child window rooted at the specified item.
When the user selects a snap-in's scope item in the scope pane for the first time, the snap-in receives an MMCN_EXPAND notification. If the selected item has any child items, the snap-in responds to the notification by inserting the child items. The SCOPEDATAITEM structure is used for specifying each item's information, such as the snap-in object that corresponds to the item, whether the item also has child items to insert, and where the item should be inserted relative to its parent item.
After filling the SCOPEDATAITEM structure for each child item of the selected item, the snap-in inserts the items into the scope pane using the IConsoleNamespace2::InsertItem method. When InsertItem returns (with S_OK), the ID member of the SCOPEDATAITEM structure contains the HSCOPEITEM of the newly inserted item. MMC uses an item's HSCOPEITEM to uniquely identify the item.
MMC calls the snap-in's IComponentData::GetDisplayInfo method if it requires information to display a specific item in the scope pane; for example, a snap-in does not explicitly specify the display name of items (when filling the SCOPEDATAITEM structure) before inserting them in the scope pane. MMC then must rely on the snap-in to provide this information during calls to its GetDisplayInfo method.
On certain occasions, MMC may send the snap-in an MMCN_EXPANDSYNC notification to inform it that a specific scope item must be expanded synchronously; for example, when a console file is reloaded with an item expanded, the snap-in receives the notification so that it can insert any child items of the expanded item.
Be aware that MMC gives namespace extensions the opportunity to insert their own child items to scope items inserted by a primary snap-in. For more information, see Extending a Primary Snap-in's Namespace.
Related topics