MMC Snap-in Designer for Visual Basic

[This is preliminary documentation and subject to change.]

This section covers the following topics:

  • Introduction
  • Common Development Tasks
  • Developing Snap-ins
  • Programming Techniques
  • Using the Object Model
  • Order of Events for Typical Scenarios
  • Changes from Beta 2
  • Bugs and Caveats

Built on Wednesday, October 27, 1999


Introduction

[This is preliminary documentation and subject to change.]

The Snap-in Designer for Visual Basic is a development tool that enables Microsoft® Management Console snap-ins to be written in Microsoft Visual Basic®. The following topics provide an overview of the designer's features and introduce basic concepts.


Software Requirements

[This is preliminary documentation and subject to change.]

The following software is required to run the Snap-in Designer for Visual Basic:

  • Microsoft Windows NT® Workstation or Server version 4.0 with Service Pack 3 or later, or Microsoft Windows® 2000 beta 3 or later, or Microsoft Windows 95 or Windows 98.
  • Microsoft Visual Basic version 6.0 (no specific service pack required)
  • Microsoft Management Console version 1.1 or later


What Is the Snap-in Designer?

[This is preliminary documentation and subject to change.]

The Snap-in Designer for Visual Basic is an ActiveX® designer that allows a snap-in to be written entirely in Visual Basic. The designer supports 100% of MMC 1.1 and MMC 1.2 functionality, so a Visual Basic snap-in can do anything that can be done in a C++ snap-in. When the snap-in designer is installed, it is integrated into the Visual Basic integrated development environment (IDE) and it adds a new project type called "SnapIn."

The designer window is used to define most of the snap-in's user interface (UI) and run-time behavior. For behavior that can't be defined at design time, you write code for event handlers in the designer's code window. Examples of events are toolbar button clicks, menu clicks, snap-in loading, and so on. This is similar to using a Visual Basic form and writing code for events that occur throughout the form's life cycle and when the user interacts with its UI. Double-clicking any element in the designer window takes you to the relevant event handler in the code window.

The snap-in's code uses an object model defined by the designer that maps all of the UI elements in a snap-in. This is similar to a Visual Basic form in that the form object has its properties and events and all of the controls on the form have their properties and events.

Snap-ins can be debugged in Visual Basic's source debugger and they can be compiled into DLLs. The Visual Basic Package and Deployment Wizard can be used to create a setup program for your snap-in.

The designer allows for rapid development of snap-ins and requires significantly less code than C++ snap-ins. Both development and test time are greatly reduced and the learning curve is much shorter for new snap-in programmers. Simple snap-ins such as menu extensions can be written with a tiny amount of MMC "plumbing" code. For example, the ComDetect sample snap-in that extends the FileExplorer sample's context menus contains 35 lines of code and only 8 of them pertain to interfacing with MMC. Much of the very complex code in C++ snap-ins has been vastly simplified so features such as multiple selection in list views require no more than a few lines of very easy coding.


What Is an ActiveX Designer?

[This is preliminary documentation and subject to change.]

An ActiveX designer is an in-process ActiveX object that extends the functionality of the Visual Basic IDE. Visual Basic 6.0 ships with numerous ActiveX designers such as the Data Environment Designer, the DHTML Page Designer, webclasses, and so on. Designers must be written in C++ and they consist of a design-time component and a run-time DLL. Visual Basic defines a special set of interfaces in addition to the standard ActiveX control interfaces that it uses to communicate with designers. These interfaces allow a designer to seamlessly integrate into the IDE and handle such things as saving and loading of the designer's state information, registration, debugging, and so on.

When a designer is installed it appears on the Designers tab in the Components dialog box from the Project menu. When a designer is added to a project it appears like any other project window such as a form or a UserControl object. The developer interacts with the designer window to enter as much information as possible to determine its run-time behavior. When the project is saved the designer saves its information into a .dsr file and a .dsx file. This is similar to the way a form saves its information into an .frm file and an .frx file.

When the project is compiled into a DLL, the designer stores all of the settings entered by the developer as well as registration information in the compiled DLL. Visual Basic also stores all of the compiled event handler code in the DLL. The DLL can be registered just like any ActiveX DLL by using Regsvr32.exe.

When the designer object is loaded at run time, (for example, when MMC loads your snap-in), the Visual Basic runtime is loaded and then it loads the designer's runtime DLL and gives it the information stored at design time. The designer runtime communicates with the containing application (MMC.exe in the case of snap-ins) and uses the design-time information to answer most of the container's requests. When the designer runtime cannot answer a request or it needs to give the snap-in the opportunity to customize the response, it fires an event into the compiled Visual Basic code. The code you wrote for the event handler is run and will typically call back into the runtime using the object model or return a value that tells the runtime how to respond to the container. The snap-in designer runtime implements every method of every C++ interface defined by MMC. Calls into the object model either store information to be returned later to MMC or make calls to one of MMC's interfaces.


Starting a Snap-in Project

[This is preliminary documentation and subject to change.]

To start a snap-in project

  1. Start Visual Basic 6.0.
  2. If the New Project dialog box is not open, on the File menu, click New Project. In the New Project dialog box select SnapIn.
  3. Double-click SnapIn1 in the Project window to open the designer.

You may notice that in addition to the snap-in designer, the project also contains a user control called SnapInControl. This user control does not contain any code or controls. It is used when adding property pages to your snap-in. Do not remove SnapInControl from your project. See the section on property pages for more information.


The Designer Window

[This is preliminary documentation and subject to change.]

The designer window displays a tree view in which each node represents a set of properties related to some aspect of your snap-in. It is used to define the characteristics of your snap-in and also serves as documentation of the elements of your snap-in. Selecting any node shows the related properties in Visual Basic's property browser window (usually in the lower-right portion of the IDE). Most nodes have associated property sheets that can be invoked from the context menu or from the toolbar.

The structure of the tree view generally does not map to the nodes that your snap-in will add to MMC's scope pane. It is simply used as a visual tool to organize the properties of the snap-in.

The root node of the tree view displays the name of your snap-in. When a new snap-in project is started it displays SnapIn1. You should change SnapIn1 to your snap-in's name immediately after starting the project.

The Extensions node always has an entry for your snap-in. Using the context menu you can specify which features of the console your snap-in implements (that is, which features of the console it extends). If your snap-in extends other snap-ins' node types, then they will also appear along with the features extended.

The Nodes section describes nodes that your snap-in will add to MMC's scope pane at run time. The Auto-Create section describes nodes that will automatically be added by the designer runtime. This section of the tree view does actually map to the appearance of the nodes in MMC's scope pane at run time. The Other section describes nodes that will be added programmatically by your snap-in (for example, in response to the user expanding an existing node). Any node can have result views and child nodes.

The Tools section contains entries for all of the image lists, menus, and toolbars used by your snap-in.

The Result Views section contains entries for every result view defined by your snap-in. Every result view that appears in the Nodes section also appears in the Result Views section.


Building a Snap-in Project

[This is preliminary documentation and subject to change.]

To build a snap-in project

  1. Start a snap-in project.
  2. On the File menu, click Make SnapIn.ocx.
  3. When prompted for the file name, change the extension to .dll. A snap-in project is derived from an ActiveX control project so Visual Basic suggests an .ocx extension. There is no requirement to change the extension to .dll, but snap-ins generally use .dll rather than .ocx.
  4. After the DLL has been built, on the Project menu, click Properties.
  5. Click the Component tab.
  6. Select Binary Compatibility. This ensures that the snap-in will always use the same CLSID.


Deploying a Snap-in

[This is preliminary documentation and subject to change.]

A snap-in created in Visual Basic needs the following components on a target computer:

  1. The DLL created by Visual Basic
  2. The snap-in designer runtime (mssnapr.dll)
  3. The Visual Basic 6.0 runtime

You can use the Visual Basic Package and Deployment Wizard to create a setup program for your snap-in. If you would like to manually deploy your snap-in on a computer that already has the Visual Basic 6.0 runtime installed, do the following:

  1. Copy your snap-in's DLL to your target directory.
  2. Copy mssnapr.dll to
    \Program Files\Common Files\Microsoft Shared\SnapInDesigner.
  3. Use Regsvr32 to register both DLLs. The designer runtime (mssnapr.dll) must be registered before your snap-in's DLL. If it is not registered first then registration of your snap-in's DLL will fail.

Note that registering your snap-in's DLL adds all of the necessary entries to the MMC keys under HKEY_LOCAL_MACHINE\Software\Microsoft\MMC.

The Package and Deployment Wizard places the designer runtime in \Program Files\Common Files\Microsoft Shared\SnapInDesigner. If you create your own setup program you must install the designer runtime in the same directory. Failure to do this could cause installation problems for future versions of the designer.

When using the Package and Deployment Wizard you can also add a saved console file (.msc) to the package using the following steps:
  1. Start the Package and Deployment Wizard and proceed to the form entitled "Package and Deployment Wizard - Included Files" and click Add.
  2. Select "All Files" in the Files of type drop-down list box.
  3. Move to the saved console file (.msc), and click Open to add the file.
  4. Proceed to the form entitled "Package and Deployment Wizard - Start Menu Items" and click New Item.
  5. In the Target drop-down list box, click to select the .msc file.
  6. In the Name text box, enter the name you want for your icon, and click OK.
  7. Finish the Package and Deployment Wizard.

When the application is installed, the icon for the console file will be created in the Programs submenu of the Start menu.


Debugging a Snap-in

[This is preliminary documentation and subject to change.]

A snap-in can be debugged like any other Visual Basic project. Set your breakpoints and press F5 or click the run button on the toolbar. Visual Basic will prompt for the program to run for debugging. There are two options:

  1. Click Wait for components to be created, click OK, and then start MMC manually. During subsequent debugging sessions Visual Basic will not prompt for these options. After pressing F5 you will only need to start MMC.
  2. Click Start program: and enter the path to mmc.exe. Visual Basic will start MMC when you close the dialog box. During subsequent debugging sessions Visual Basic will start MMC when you press F5. You can also save a console file (.msc) when running your snap-in and specify its name as a parameter following the mmc.exe path. Subsequent debugging sessions will then start MMC with your snap-in loaded. To change the debugging settings click Project, click Properties, and then click the Debugging tab.

There are some caveats particular to snap-ins because while your snap-in is running within the Visual Basic IDE, MMC is running in a separate process. This can make things like selection events (for example, Views_Select or Views_UpdateControlbar) difficult to debug because new events are being fired while you step through the initial event. In general, it is advisable to remove the breakpoint and press F5 after stepping through one of these event handlers so that MMC has a chance to process the selection changes. If you do not remove the breakpoint you may find that it is hit repeatedly and you never have a chance to interact with MMC.


Common Development Tasks

[This is preliminary documentation and subject to change.]

The following topics describe the steps for some common development tasks using the designer, along with some sample event handler code.


Creating a Simple Snap-in with a URL Result View

[This is preliminary documentation and subject to change.]

  1. Start a snap-in project.
  2. In the tree view click SnapIn1/Nodes/Auto-Create/Static Node/Result Views.
  3. Right-click, click Add New Result View, and then click URL View.
  4. Click URLView1, right-click, and click Properties.
  5. In the URL text box, type the URL of a Web page that your computer has access to (for example, http://www.microsoft.com) and click OK.
  6. Click SnapIn1 at the top of the designer's tree view, right-click, and click Properties. In the Default Result View combo box at the bottom of the property page click URLView1. Click OK.
  7. On the Project menu, click Properties and click the Debugging tab. Select Start Program and type the path to MMC.exe on your computer (for example, c:\winnt\system32\mmc.exe). Click OK.
  8. Click the run button (right-facing triangle) or press F5.
  9. When MMC starts, on the Console menu, click Add/Remove Snap-in.
  10. Click Add.
  11. On the list of snap-ins click SnapIn1, click Add, and then click Close.
  12. Click OK.
  13. Your snap-in should appear under the console root.
  14. Click its static node and your selected Web page should appear in the result pane.
  15. Close MMC.
  16. Return to Visual Basic and click the stop button (square) or on the Run menu click End.


Creating a Simple Snap-in with a List View

[This is preliminary documentation and subject to change.]

  1. Start a snap-in project.
  2. In the tree view click SnapIn1/Nodes/Auto-Create/Static Node/Result Views.
  3. Right-click, click Add New Result View, and then click ListView.
  4. Click ListView1, right-click, and click Properties.
  5. Click the Column Headers tab.
  6. Click Insert Column.
  7. In the Text text box type My Column 1.
  8. Click Auto Width.
  9. In the Key text box type Col1 and click OK. You have now defined a list view with one column.
  10. On the View menu, click Code to open the code window.
  11. In the left combo box click ResultViews.
  12. In the right combo box click Initialize.
  13. In the ResultViews_Initialize event handler, type:
    ResultView.ListView.ListItems.Add 1, , "Item 1 Text"
ResultView.ListView.ListItems(1).ListSubItems.Add 1, , "Column 1 Text"

    This event handler is called when MMC is about to display the list view and the snap-in should populate it with display data. The preceding code added a single item to the list view. When the list view is in report mode it will display "Column 1 Text" in its one and only column. When the list view is in any other mode, it will display a single item with the text "Item 1 Text".

  14. Click SnapIn1 at the top of the tree view in the designer window. Right-click and click Properties.
  15. In the Default Result View combo box click ListView1.
  16. Change Display Name to ListViewTest. Click OK.
  17. Press F5 or click the run button.
  18. In MMC, on the Console menu, click Add/Remove Snap-in.
  19. Click Add.
  20. On the list of snap-ins click ListViewTest, click Add, and then click Close.
  21. Click OK.
  22. Your snap-in should appear under the console root.
  23. Click its static node and the list view will appear with the single item. Use the View menu to switch between view modes.


Creating a Simple Snap-in with an OCX Result View

[This is preliminary documentation and subject to change.]

  1. Start a snap-in project.
  2. In the tree view click SnapIn1/Nodes/Auto-Create/Static Node/Result Views.
  3. Right-click, click Add New Result View, and then click OCX View.
  4. Click OCXView1, right-click, and click Properties.
  5. In the ProgID text box, type the ProgID of an ActiveX control installed on your computer and click OK. For example, MSComCtl2.MonthView.2 is the ProgID of the MonthView control that ships with Visual Basic 6.0.
  6. Click SnapIn1 at the top of the designer's tree view, right-click, and click Properties. In the Default Result View combo box at the bottom of the property page click OCXView1. Click OK.
  7. On the Project menu, click Properties and click the Debugging tab. Select Start Program and type the path to mmc.exe on your computer (for example, c:\winnt\system32\mmc.exe). Click OK.
  8. Click the run button or press F5.
  9. When MMC starts, on the Console menu, click Add/Remove Snap-in.
  10. Click Add.
  11. On the list of snap-ins click SnapIn1, click Add, and then click Close.
  12. Click OK.
  13. Your snap-in should appear under the console root.
  14. Click its static node and your ActiveX control should appear in the result pane.
  15. Close MMC.
  16. Return to Visual Basic and click the stop button or on the Run menu click End.


Creating a Simple Snap-in with a Snap-in Taskpad Result View

[This is preliminary documentation and subject to change.]

  1. Start a snap-in project.
  2. In the tree view click SnapIn1/Nodes/Auto-Create/Static Node/Result Views.
  3. Right-click, click Add New Result View, and then click Taskpad.
  4. Click Taskpad1, right-click, and click Properties.
  5. In the Title text box, type My Taskpad Title.
  6. In the Description text box, type My Taskpad Description.
  7. Click the Tasks tab and click Insert Task.
  8. In the Text text box, type My Task.
  9. In the Help string text box, type My Help String.
  10. In the Image Type group box, click Symbol.
  11. In the Font family name text box, type GLYPH 100.
  12. In the EOT file text box, type res://mmc.exe/glyph100.eot.
  13. In the Symbol string text box, type 4 and click OK.
  14. Double click Taskpad1 to go to the code window for the ResultViews_TaskClick event. Enter the following line of code:
        ConsoleMsgBox "Task clicked: " & Task.Text
  15. Click SnapIn1 at the top of the designer's tree view, right-click, and click Properties. In the Default Result View combo box at the bottom of the property page click Taskpad1. Click OK.
  16. On the Project menu, click Properties and click the Debugging tab. Select Start Program and type the path to mmc.exe on your computer (for example, c:\winnt\system32\mmc.exe). Click OK.
  17. Click the run button or press F5.
  18. When MMC starts, on the Console menu, click Add/Remove Snap-in.
  19. Click Add.
  20. On the list of snap-ins click SnapIn1, click Add, and then click Close.
  21. Click OK.
  22. Your snap-in should appear under the console root.
  23. Click its static node and your taskpad should appear in the result pane.
  24. Hold the mouse over the task to see the Help string.
  25. Click the task to see the message box displayed in the ResultViews_TaskClick event handler.
  26. Close MMC.
  27. Return to Visual Basic and click the stop button or on the Run menu click End.


Creating a Simple Snap-in with Multiple Nodes

[This is preliminary documentation and subject to change.]

  1. Start a snap-in project.
  2. In the tree view click SnapIn1/Nodes/Auto-Create/Static Node/Children. Right-click and click Add Child Node.
  3. Click Node1, click Children, right-click, and click Add Child Node.
  4. Click SnapIn1 at the top of the tree view in the designer window. Right-click and click Properties.
  5. Change Display Name to Multi-Node Snap-in. Click OK.
  6. Press F5 or click the run button.
  7. In MMC, on the Console menu, click Add/Remove Snap-in.
  8. Click Add.
  9. On the list of snap-ins click Multi-Node Snap-in, click Add, and then click Close.
  10. Click OK.
  11. Your snap-in should appear under the console root.
  12. Expand the static node and then expand Node1.


Creating a Context Menu Extension Snap-in to Display FileExplorer File Names

[This is preliminary documentation and subject to change.]

  1. Start a snap-in project.
  2. Bring up the property sheet for the snap-in (root of the tree view).
  3. Select Extension. Click OK.
  4. Bring up the property sheet for the Extensions node (directly beneath the root of the tree view).
  5. Select lvExplorerFiles and click OK. If lvExplorerFiles does not appear, then FileExplorer may not be registered. It can be registered using Regsvr32 or by reinstalling the snap-in designer.
  6. Right-click the newly added lvExplorerFiles node. Click Context Menus and then click Task.
  7. Right-click Tools, click Menus and click Add Menu.
  8. Right-click the newly added Menu1 and click Add Menu. While the cursor is still blinking, change the name to DisplayFileName.
  9. In the property browser window, change the Caption property to Display File Name.
  10. Double-click the lvExplorerFiles/Context Menus/Task node to go to the code for the event handler where extension task menu items are added.
  11. Enter the following line of code to add your menu to MMC's task menu:
    ContextMenu.AddMenu Menu1
  12. In the left combo box in the code window, click DisplayFileName. The event handler for menu item selection is displayed. Add the following lines of code to extract the file name from FileExplorer's exported data and display it in a message box:
    Dim FileName As String
FileName = FormatData(Selection.DataObjects(1).GetData("File"), 1, siString)
MsgBox "The file name is: " & FileName, vbOKOnly, "Simple Extension"
  13. Press F5 or click the run button.
  14. In MMC, add FileExplorer to the console. Take all of the defaults in the configuration wizard.
  15. In the console, expand FileExplorer until you reach a drive or folder containing files. In the result pane, right-click a file, click All Tasks and then click Display File Name. You will see the message box displayed in the Visual Basic IDE. In a snap-in that is compiled and run outside of the IDE the message box would display directly in MMC.


Developing Snap-ins

[This is preliminary documentation and subject to change.]

The following topics describe the various portions of the designer window, related coding tasks, and how to use them to create the features of a snap-in.


Defining the Snap-in Properties

[This is preliminary documentation and subject to change.]

The snap-in Name is used to identify the snap-in in Visual Basic® code and in your project. (It is also used externally as the right portion of your snap-in's ProgID, but you should never need that for anything because registration is handled automatically.)

NodeTypeName is used to identify your snap-in's static node in its registry entry under HKEY_LOCAL_MACHINE\Software\Microsoft\MMC\SnapIns.

DisplayName appears in the console's Add Standalone Snap-in dialog box and will also appear as the text for your static node when it is displayed in the scope pane or in the result pane.

Provider, Version, and Description are used in the console's About box.

Default Result View is optional and specifies the name of a result view defined at design time that will be displayed by default for the static node if you do not change it dynamically in your code at run time.

Small Folders, Small OpenFolders, and Large Folders determine the images that will be used for scope items. If you do not want to use MMC's default images you must define three image lists for the snap-in. These image lists are used for your static node and for scope items when they appear in the scope pane. You must define corresponding images at the same index in each image list because you define only a single image index for the static node and for each scope item. If your scope items can also appear in a list view, then you must add the same images at the same indexes to the list view's image lists. An easy way of doing this is to use the same image lists for both the snap-in properties and the list view properties.

A snap-in's static node is extensible by other snap-ins. When the user interacts with the static node other snap-ins can add child nodes, context menu items, property pages, toolbar and menu buttons, and taskpad tasks. The designer will add a key for the node in the registration database under
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MMC\NodeTypes. Snap-in developers are strongly encouraged to make all of their node types extensible to allow for future enhancements. Extensibility is a key feature of the MMC architecture and to enable it requires no more than the registration database entry. Snap-ins can also attach data to the static node at run time to give extensions any extra information needed for their enhancements. For more information see "Developing Extension and Dual-Mode Snap-ins." Although it should rarely be needed, if a snap-in must disable extensibility, use the property browser to set Extensible to False.


Nodes

[This is preliminary documentation and subject to change.]

Nodes are the scope items added to the console's tree view. A stand-alone snap-in always has a static node that is created automatically when the snap-in is added to a console. The snap-in can choose to add children to the static node in response to the user's interaction with the UI or to changes in the underlying data managed by the snap-in.

Nodes can be defined at design time or at run time in your code. When you define a node at design time you must decide whether it will be created automatically or programmatically at run time. Nodes that appear in the Auto-Create section are created automatically as the user expands down from the static node.

The node name defined in the designer is the node's type name. The ScopeItems.AddPredefined method is used at run time to add a node using a design-time definition. Nodes can also be defined completely programmatically by using the ScopeItems.Add method. Both of these methods add the nodes to the scope pane and are typically called in the ScopeItems_Expand event.

It is possible to define a node at design time under Nodes\Other that has automatically created child nodes. ScopeItems.AddPredefined is called to add that node, and then the runtime automatically adds all of its auto-create children as the node and any of its descendants are subsequently expanded.

Nodes that are not auto-create can be grouped as desired under Nodes\Other. For example, suppose that whenever your snap-in creates NodeB it is always as a child of NodeA but neither node is auto-create. You can choose to place NodeB as a child of NodeA in the designer for organizational purposes only.

At run time, every node created by your snap-in has a ScopeItem object that is a member of the ScopeItems collection. A node defined at design time is essentially a template for a ScopeItem because it defines the initial values of the ScopeItem's properties. A scope item can be displayed in MMC's tree view in the scope pane or it can be displayed in the result pane when its parent displays a list view. (Even the static node can appear in the result pane when MMC's "Console Root" node is selected in the scope pane.) When a scope item is displayed in its parent's list view in report mode, you must define the data that is displayed in the columns of the list view. To define column headers for a ScopeItem, display the properties for a node in the designer and click the Column Headers tab. The definitions are the same as for a list view. The column headers defined for a scope item must use the same keys as those of the list view in which they will appear.

All nodes are extensible by other snap-ins. When the user interacts with a node, other snap-ins can add child nodes, context menu items, property pages, toolbar and menu buttons, and taskpad tasks. The designer will add a key for the node in the registration database under
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MMC\NodeTypes. Snap-in developers are strongly encouraged to make all of their node types extensible to allow for future enhancements. Extensibility is a key feature of the MMC architecture and to enable it requires no more than the registration database entry. Snap-ins can also attach data to a node at run time to give extensions any extra information needed for their enhancements. For more information see "Developing Extension and Dual-Mode Snap-ins." Although it should rarely be needed, if a snap-in must disable extensibility, use the property browser to set Extensible to False.


Image Lists

[This is preliminary documentation and subject to change.]

Image lists are very similar to the Visual Basic® Common Controls ImageList. Image lists are added under Tools\Image Lists. Add your images and choose your mask color the same as you would for a Common Controls ImageList. After defining an image list, you can specify it in snap-in, list view, or toolbar properties.

Small bitmaps must be 16x16 pixels. Large bitmaps must be 32x32 pixels. An image list must always contain bitmaps of a single size. Toolbars use only small bitmaps.


Result Views

[This is preliminary documentation and subject to change.]

The designer allows creating list views, OCX views, URL views, and taskpads. Message views can only be created at run time. Result views created at design time are known as predefined result views. You can create the result view directly under a node or in the general Result Views section at the bottom of the designer's tree view. The static node and any number of other nodes can use predefined views. You can also specify the use of a predefined view in your code at run time (see GetResultViewInfo in "ScopePaneItems").

All result view types can also be defined in code at run time although this is typically unnecessary for types other than the message view.

Result views can be created directly on a node or in the master Result Views section at the bottom of the designer tree view. When an existing result view is added to a node it is added as a reference and shared among the nodes. This means that regardless of where you invoke the result view's property sheet you will be accessing the same result view.

All result view properties include a check box indicating whether to add the result view to the console's View menu. If the check box is selected, two other fields are enabled for menu item text and corresponding status bar text. At run time, populating the View menu and switching between the result views is handled automatically.


List Views

[This is preliminary documentation and subject to change.]

List views, like image lists, are similar to the Visual Basic® Common Controls ListView. Column headers and sorting are defined just as in the Common Controls ListView except that MMC has no column header icon. Two image lists are required for a list view: one for small icons and one for large icons. The small icons list must contain only 16x16 bitmaps. The large icons list must contain only 32x32 bitmaps. Unlike a Common Controls ListItem, a snap-in list item only has one index property for its icon. This means that the large and small images in each image list must correspond.

If your snap-in will display scope items in a list view, then you must also define the scope item images in the list view image lists. These images must be at the same indexes as in the snap-in image lists. As mentioned in "Defining the Snap-in Properties," the scope items and the list view can share an image list.

At run time the snap-in has access to the list view's properties by using ResultView.ListView. Use the ResultViews_Initialize event to populate the list view.

All list views are extensible by other snap-ins. When the user interacts with a list item, other snap-ins can add context menu items, property pages, and toolbar and menu buttons. The designer will add a key for the list view's node type in the registration database under
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MMC\NodeTypes. Snap-in developers are strongly encouraged to make all of their list views extensible to allow for future enhancements. Extensibility is a key feature of the MMC architecture and to enable it requires no more than the registration database entry. Snap-ins can also attach data to a list item at run time to give extensions any extra information needed for their enhancements. For more information see "Developing Extension and Dual-Mode Snap-ins." Although it should rarely be needed, if a snap-in must disable extensibility, use the property browser to set Extensible to False.


URL Views

[This is preliminary documentation and subject to change.]

A URL view requires only defining the URL that MMC will navigate to in the result pane.

A snap-in may need to use a file:// URL that references an HTML file in the snap-in DLL's directory or relative to that directory. For more information see "Using Relative URLs."


OCX Views

[This is preliminary documentation and subject to change.]

An OCX view requires defining the ProgID of the control that will be displayed in the result pane. In your code, you can access the control in ResultView.Control starting from the ResultViews_InitializeControl event and continuing until the result view is destroyed following the ResultViews_Terminate event.

Your snap-in can indicate to MMC whether to create a single instance of the control and cache it or to create a new instance of the control every time it is used. To change this setting, select the OCX view's node in the tree view and use the property browser to set the AlwaysCreateNewOCX property. Note that if AlwaysCreateNewOCX=False then the snap-in will receive the ResultViews_InitializeControl event only once when the control is created. For subsequent uses of the OCX view, the snap-in can access ResultView.Control starting from the ResultViews_Activate event.


Snap-in Taskpads

[This is preliminary documentation and subject to change.]

All aspects of a snap-in taskpad can be defined at design time. Taskpads require the use of bitmaps, GIF files, and font files in resources. These can be added to the project using the Visual Basic® Resource Editor add-in. For custom taskpads, the HTML file should also be stored as a resource. See "Using Resources in Taskpads" for more information.

One option particular to taskpads is a check box indicating whether the taskpad should be used in the case where the user has selected the console option "Show taskpad views by default" in MMC 1.1. (This option is not in MMC 1.2.) If a node has both taskpads and non-taskpads, it can specify a non-taskpad as its default result view. The non-taskpad will be displayed if the user has not set the console option. If the user has set the option then the taskpad will be displayed.

If the node has multiple taskpads defined, then one of them must have "Use when taskpad preferred" selected. When the user has set the console option, the runtime will choose this taskpad regardless of the node's default result view.

At run time the snap-in has access to the taskpad's properties by using ResultView.Taskpad. This object has a Tasks collection that defines the tasks. A snap-in can change a taskpad's properties at run time in the ResultViews_Initialize event.

A list view taskpad can be designated horizontal or vertical (the default) by selecting the taskpad in the designer and setting ListpadStyle in the property browser. ListpadStyle can also be set at run time in the ResultViews_Initialize event.

A snap-in can define a taskpad and decide at run time to display only a subset of its tasks. This can be controlled by setting the Task.Visible property in ResultViews_Initialize.

If a task is defined using the Notify option, then the ResultViews_TaskClick event is fired when the user clicks the task. For list view taskpads, the ResultViews_ListpadButtonClick event is fired when the user clicks the listpad button. If a custom taskpad uses MMCCtrl.Notify to call into the snap-in, the ResultViews_TaskNotify event is fired.


Using Resources in Taskpads

[This is preliminary documentation and subject to change.]

MMC requires that taskpads store bitmaps, GIF files, font files, and custom taskpad HTML files as resources within the snap-in's DLL. This can be done for Visual Basic® snap-ins by using the Visual Basic Resource Editor add-in. An add-in is a program that can be activated from the Visual Basic IDE that has access to everything in your project. To activate the Resource Editor add-in click Add-In Manager on the Add-Ins menu. In the Add-In Manager dialog box click VB 6 Resource Editor and select Loaded or Load on Startup. In the project window right-click and click Add/Resource File. The Resource Editor will prompt for a file name and create a .res file that will become part of the project.

To use a bitmap in a taskpad, add it to your resource file and change the suggested resource ID to a meaningful name, for example, MyBitmap. To use the bitmap in the taskpad specify it as #2/MyBitmap. The #2 indicates that the resource is a bitmap.

To use a GIF, font file, or custom taskpad HTML file, add it as a custom resource. To specify the resource in taskpad properties use the prefix CUSTOM/. For example, to use a GIF added as a custom resource named MyGif, specify CUSTOM/MyGif.

Snap-ins can also use resources that are within mmc.exe. For example, MMC has a symbol font called "Glyph 100" that can be used for task images defined by a symbol string. To specify an MMC resource use "res://mmc.exe/<resource name>". For example, to use the Glyph 100 font for a symbol string specify "res://mmc.exe/glyph100.eot". The designer runtime will determine the full path of mmc.exe and expand the URL before it is returned to MMC.


Message Views

[This is preliminary documentation and subject to change.]

When running under MMC 1.2 snap-ins can also use message views. A message view is a simple ActiveX® control supplied by MMC that displays an icon, a title, and some message text. This can be useful when a snap-in needs to display an error message or other simple textual information in response to the selection of a scope item in the scope pane. For example, if selecting a scope item causes a lengthy asynchronous operation to fetch the data for the result pane, the snap-in should display a message view explaining the situation. When the data finally arrives, if the same scope item is still selected, then the snap-in can change the result view and display the data.

To display a message view call ScopePaneItem.DisplayMessageView or handle the ScopePaneItems_GetResultViewInfo event and return siMessageView. Using either technique, a snap-in can change the message view's parameters before MMC displays them by handling the ResultViews_Activate event and accessing ResultView.MessageView. A message view's parameters can also be changed at any time while it is displayed in the result view. This can be useful in the scenario described above to display progress updates to the user.


Toolbars

[This is preliminary documentation and subject to change.]

Toolbars are similar to the Visual Basic® Common Controls Toolbar. An image list must be defined and specified in the toolbar's general property page. Buttons are defined exactly as for a Common Controls Toolbar.

The toolbar is added to the console in the Views_SetControlbar event. An MMCControlbar object is passed to the event. Call the Attach method passing the toolbar.

The toolbar's state can be updated upon a selection change by handling the Views_UpdateControlbar event. This allows enabling/disabling/adding/removing buttons. Toolbars can also be changed in response to other events such as menu clicks. Toolbar button clicks are handled as for a Common Controls Toolbar in the <ToolbarName>_ButtonClick event.


Menu Buttons

[This is preliminary documentation and subject to change.]

Snap-ins are generally encouraged to use MMC's context menus, but they can also add menu buttons to the MMC control bar. Menu buttons are created the same way as the Visual Basic® Common Controls Toolbar. You define a menu button by adding a button to a toolbar and giving it the DropDown style. The ButtonMenu objects that define the items on the menu button are specified at the bottom of the property page. A toolbar that contains DropDown buttons must contain only buttons of that style. This restriction, which does not occur in the Common Controls Toolbar, is due to the fact that MMC does not allow mixing toolbar buttons and menu buttons.

The menu button is added to the console in the Views_SetControlbar event. An MMCControlbar object is passed to the event. Call the Attach method passing the toolbar object that defines the menu button(s).

A menu button's state can be updated upon a selection change by handling the Views_UpdateControlbar event. This allows enabling/disabling/adding/removing menu buttons. When a menu button is clicked, the <ToolbarName>_ButtonDropDown event is fired. That event is used to enable/disable/add/remove individual menu items by manipulating the button's ButtonMenus collection. Following that event, the drop-down menu is displayed and, if the user clicks an item, the <ToolbarName>_ButtonMenuClick event is fired.


Menus

[This is preliminary documentation and subject to change.]

Menus are handled similarly to the way pop-up menus are created using the Visual Basic® intrinsic menu control. The Visual Basic Menu Editor is not used for snap-ins. Instead, the menu definitions are done directly in the designer's tree view. To add a menu, right-click Tools/Menus and click Add Menu or click the menu button on the toolbar. This action creates a containing menu that will hold the items to be displayed at a given insertion point in MMC's context menu. The containing menu itself is not displayed at run time.

Right-click Menu1 and click Add Menu or click the menu button on the toolbar. This action creates the first menu item. Menu nodes can be demoted/promoted and moved up or down using the arrows on the toolbar.

The MMCMenu object represents both containing menus and menu items. To set the properties for a menu item, select it in the tree view and use the property browser. In particular, you should set the Caption property to something meaningful. Caption determines the text that will be displayed in MMC's context menu. For more information see "MMCMenu."

To use a menu, you must write a line of code to add it to the context menu. There are several events that allow adding menus to the various insertion points for primary snap-ins:

  • Views_AddTopMenuItems
  • Views_AddTaskMenuItems
  • Views_AddNewMenuItems
  • Views_AddViewMenuItems

For extension snap-ins, the events are:

  • ExtensionSnapIn_AddNewMenuItems
  • ExtensionSnapIn_AddTaskMenuItems

These events are fired when MMC gives the snap-in the opportunity to add menu items to the corresponding insertion point in its context menu. For example, when the user right-clicks a scope item, MMC displays a context menu that includes a New submenu. The snap-in will receive the Views_AddNewMenuItems event to allow it to add items to that submenu.

In all the events, a ContextMenu object is passed. Call the AddMenu method to add the containing menu. As mentioned previously, the containing menu will not appear at run time but all of its contained items will be added to the insertion point. Note that the ContextMenu object can only be used during the event and the snap-in should not store a reference to it.

To handle a menu item click, in the code window, click the menu item name in the left combo box. The <MenuName>_Click event will be displayed in the code window. Alternatively, double-click the menu in the designer window and the <MenuName>_Click event will be displayed in the code window.

Alternatively, the event can be handled in the <ContainingMenuName>_Click event. In this case you must examine the Index parameter to determine which item was clicked.

At run time, menu items can be disabled/grayed/hidden/checked by changing the properties of the MMCMenu object before calling ContextMenu.AddMenu.

Items can be added to a menu at run time by calling MMCMenu.Children.Add. For dynamic menu items added to an existing menu, it is easiest to handle the click event on the containing menu. It is also possible to handle the event on the new menu item itself by declaring a module-level variable of type MMCMenu using Dim WithEvents. Assign the object returned from MMCMenu.Children.Add to this variable.

Submenus can be added to a menu at run time by calling MMCMenu.Children.Add and then adding children to that new MMCMenu object. To handle the events on the submenu use a module-level variable and Dim WithEvents as described above.

A snap-in can define completely new menus in code by using Dim WithEvents as described above and passing that MMCMenu object to ContextMenu.Add. Menu items and submenus are added to the menu the same way as for menus defined at design time.


Property Pages

[This is preliminary documentation and subject to change.]

Property pages are added to the project just as for a user control. On the Project menu, click Add Property Page. The property page design and UI-handling code are done exactly as for a user control. The only significant difference is that in the PropertyPage_SelectionChanged event, SelectedControls contains the ScopeItem(s) and/or MMCListItem(s) for which properties are being displayed. The property page can store a reference to the ScopeItem(s) and/or MMCListItem(s) in module-level variables to be used when the user interacts with the property page.

For the property page to be registered, it must be associated with SnapInControl, the user control that is part of every snap-in project. Open the control and in the property browser select the Property Pages property and click the … button. Select the check boxes for your property pages. Do not select any of the stock property pages. If your project directory contains more than one snap-in, you must change the name of the additional SnapInControl source files from SnapIn.ctl to a name of your choice. Do not change the name of the control itself.

Primary snap-ins can enable the user to invoke properties for scope items and list items by enabling the properties verb in the Views_Select event:

ConsoleVerbs(siProperties).Enabled = True

When the user invokes properties using the context menu, the toolbar, or ALT+ENTER, the snap-in receives the Views_QueryPagesFor event. MMC fires this event to ask whether the snap-in has property pages for the selected item(s). If True is returned then the snap-in will receive the Views_CreatePropertyPages event to allow it to add property pages to the property sheet that MMC is about to display. This event has an MMCPropertySheet parameter that is used to add property pages. Call MMCPropertySheet.AddPage for each property page you wish to add. This object can only be used during the event and the snap-in should not store a reference to it.

When the user activates another page, clicks OK, or clicks Apply, the property page receives the ApplyChanges event just as it would for an ActiveX® control property page. This event handler serves the same purpose as it does in an ActiveX control for validating the user's input. If the input is not correct then the handler displays a message and sets Changed=True to prevent the property sheet from closing. The property page can inform the snap-in of property changes to the selected item(s) by calling ScopeItem.PropertyChanged or MMCListItem.PropertyChanged and passing a Variant containing any accompanying information the property page needs to communicate to the snap-in. These methods will generate the ScopeItems_PropertyChanged and ResultViews_PropertyChanged events. The Variant can contain any data type as long as any objects used support remotable interfaces because MMC runs the property page in a separate thread. Note that any object implemented by a Visual Basic® class will be remotable.

After displaying a property page for a list item(s) the user may select a different scope item in the scope pane. When this happens, the list view that owns the list item(s) will be destroyed but the property page may be holding on to the orphaned MMCListItem object(s). For more information on handling this situation see "Handling Orphaned Property Pages."

Property pages can optionally implement an interface defined by the designer runtime called IMMCPropertyPage. This interface gives the property page access to extra functionality in MMC that is not part of a standard Visual Basic property page.

Before the page is displayed, IMMCPropertyPage_GetDialogUnitSize is called to allow the page to determine its size using dialog units. For more information see "Creating Display-Independent Property Pages."

The IMMCPropertyPage_Initialize method is called when the page is created following the PropertyPage_SelectionChanged event. It receives a reference to the MMCPropertySheet object and the optional InitData parameter passed to MMCPropertySheet.AddPage. This allows the snap-in to communicate to the property page any extra data other than what is contained in the selected objects. The property page can store the MMCPropertySheet object in a module-level variable and use it to dynamically add and remove pages, activate pages, change button states, and request a reboot after the sheet is closed. For more information see "MMCPropertySheet."

When the user clicks the Help button on the property sheet the runtime calls IMMCPropertyPage_Help. The property page can call the MMCPropertyHelp function (exported from mssnapr.dll) to ask MMC to display its integrated Help.

When the user attempts to cancel the property sheet by pressing ESC, clicking Cancel, or clicking the X button in the upper-right corner, then IMMCPropertyPage_QueryCancel is called. The page uses this method to decide whether to allow the cancellation request. If it is allowed then IMMCPropertyPage_Cancel is called for ESC or Cancel and IMMCPropertyPage_Close is called for the X button.

To display a property sheet in response to an event other than Views_CreatePropertyPages use the MMCPropertySheetProvider object. See "Initiating Property Sheet and Wizard Displays Programmatically" for more information.


Configuration Wizards

[This is preliminary documentation and subject to change.]

Configuration wizards consist of a series of property pages displayed within a wizard property sheet. The sheet has Back, Next, Finish, and Help buttons that can be enabled and disabled by the property pages. Because Visual Basic® does not directly support Win32® wizard property sheets, the snap-in designer defines an interface called IWizardPage that must be implemented by every property page used within a wizard. Each property page must include the statement

Implements IWizardPage

at the top of the module. In the code window Visual Basic will add IWizardPage to the left combo box and all of its methods to the right combo box. The snap-in must implement each method but it does not necessarily have to write code in every one. The interface has methods that inform the property page of activation and button clicks. Using out parameters from IWizardPage methods, the property page can control the user's navigation among the pages. It can also determine whether to display a Finish button on each page and the text of that button. See "IWizardPage" for more information.

As with regular property pages, wizard property pages must be associated with SnapInControl.

When a snap-in is selected in the console's Add Standalone Snap-in dialog box, it will receive the SnapIn_QueryConfigurationWizard event. If the snap-in returns True then it will receive the SnapIn_CreateConfigurationWizard event, in which it can add its property pages to the wizard by calling MMCPropertySheet.AddWizardPage. Unlike MMCPropertySheet.AddPage, this method takes an extra argument that is an object of the snap-in's choosing. This object will be available to the property pages as SelectedControls(0) in their PropertyPage_SelectionChanged event. When the user has completed the wizard, the snap-in will receive the SnapIn_ConfigurationComplete event. The snap-in-defined object passed to MMCPropertySheet.AddWizardPage is passed as a parameter to that event.

To display a wizard at any other time use the MMCPropertySheetProvider object. See "Initiating Property Sheet and Wizard Displays Programmatically" for more information.


Initiating Property Sheet and Wizard Displays Programmatically

[This is preliminary documentation and subject to change.]

A primary snap-in can initiate the display of a property sheet or a wizard at any time by using the MMCPropertySheetProvider object. This object is available as a property of the current view and can be accessed using CurrentView.PropertySheetProvider. See "View" for more information.

MMCPropertySheetProvider.CreatePropertySheet creates a new property sheet. The new sheet can optionally omit the Apply button.

MMCPropertySheetProvider.AddPrimaryPages causes the snap-in's Views_QueryPagesFor and Views_CreatePropertyPages events to be called. The snap-in should respond just as it does for user-invoked property sheets. To create a property sheet, call MMCPropertySheet.AddPage for each page in Views_CreatePropertyPages. To create a wizard, call MMCPropertySheet.AddWizardPage for each page.

If the snap-in is creating a property sheet and would like extensions to add their pages then call MMCPropertySheetProvider.AddExtensionPages.

To display the property sheet or wizard call MMCPropertySheetProvider.Show.

Note Under MMC 1.1 MMCPropertySheetProvider cannot be used with the Visual Basic® debugger.

For more information see "MMCPropertySheetProvider."


Adding Help to a Snap-in

[This is preliminary documentation and subject to change.]

Starting in MMC 1.1, snap-ins can merge their HTML Help (.chm) files with MMC's Help so that MMC can display a single integrated Help system. If your snap-in uses HTML Help then specify the name of the .chm file in the SnapIn.HelpFile property. This can be done at design time using the property browser window or at run time in SnapIn_Load. The file can be specified with the full path to be used at run time or with no path. If no path is specified then the .chm file should be installed in the same directory as the snap-in's DLL.

When users select a scope item or a list item they can request Help for the selection by using F1, the toolbar Help button, or the Help item on MMC's context menu. For a scope item the snap-in will receive the ScopeItems_Help event. For a list item the snap-in will receive ResultViews_Help. Both events receive the selected item. In a multiple-selection list view the snap-in will receive the first list item in the selection. The snap-in can display a topic in the merged Help by calling DisplayHelpTopic and specifying the topic to display. The topic is identified using the following format:

helpfilename::topicfilename

where helpfilename is the file name of the snap-in's HTML Help file (.chm) that MMC merged into the MMC HTML Help file (this is the file name only, not the path to the original HTML Help file), and topicfilename is the internal path to the topic file within the snap-in's .chm file. The author of the snap-in's HTML Help file determines whether there is an internal directory structure for the topic HTML files or if all topic HTML files are at the root of the .chm file. For example, in ScopeItems_Help the FileExplorer sample displays Help for any scope item by specifying the topic for the section "File Explorer - Event Handling\ScopeItems" in VBSnapInsSamples.chm as follows:

ShowHelpTopic "VBSnapInsSamples.chm::VBSnapInsSamples/VBSnapInsSamples_23.htm"

Note that merged Help will not work while running under the Visual Basic® debugger.

If the .chm file has hyperlinks to other .chm files then these files can be specified in the property SnapIn.LinkedTopics. Topics should be specified as one or more strings separated by semicolons containing Help topics that have hyperlinks from the snap-in's main Help file. Setting this property tells MMC to merge those Help files along with the main file specified in SnapIn.HelpFile.

If the snap-in does not use a merged Help file, (that is, SnapIn.HelpFile is not set to the name of its .chm), then when the user requests Help the snap-in will receive the SnapIn_Help event. This event has no context information parameters such as the selected scope item. It is the snap-in's responsibility to display Help in response to this event. Snap-ins using an older WinHelp file might choose to display their Help in this manner. DisplayHelpTopic cannot be used because it can only display topics in the merged Help.

When the user clicks Help on the property sheet the property page can call the MMCPropertyHelp function (exported from mssnapr.dll) to ask MMC to display a topic in the merged Help file. See "Property Pages" for more information.


Developing Extension and Dual-Mode Snap-ins

[This is preliminary documentation and subject to change.]

Extension snap-ins extend the functionality of other snap-ins but they are not directly added to a console like stand-alone snap-ins. Extension snap-ins can add context menu items, property pages, toolbar buttons, taskpad tasks, and nodes to the namespace of the extended snap-in. An extension snap-in is only loaded when the snap-in it extends is loaded and the feature it extends is used. For example, when the user displays a context menu in a stand-alone snap-in, MMC builds the context menu, asks the stand-alone snap-in to add its items, and then asks the extension snap-in to add its items. After all snap-ins have added their items, MMC displays the context menu and then forwards the menu click to the snap-in that owns the item.

The sample snap-ins include examples of all the different extension types. FileViewer extends the toolbar, context menu, taskpad, and property pages of FileExplorer. ComDetect extends the context menu. DriveStats extends the namespace.

A dual-mode snap-in can be loaded both stand-alone and as an extension. The FileExplorer sample is an example of a dual-mode snap-in. It can be added to a console to run stand-alone or it can be added as an extension to Computer Management\System Tools on Microsoft® Windows® 2000.

To create an extension or dual-mode snap-in, display the snap-in properties (on the root of the designer's tree view), and choose the snap-in type. Close the snap-in properties and display properties for the Extensions node in the designer window. This will display a list of all the registered node types on your development computer. Select the node type(s) your snap-in will extend. If the snap-in you are extending is not registered on your computer you can add its node type to the list by clicking Add.

It is important to understand that a node type can represent either a scope item or a list item added by the extended snap-in. Consult the snap-in's documentation to determine what the node type represents and the format of its exported data.

After closing the Extensions property sheet the designer will add the chosen node types to the tree view. Select each node type and use the context menu or property browser to indicate which feature of the node type your snap-in will extend. The designer will add the features to its tree view. Double-click a feature to go to the event handler where your snap-in will add its extensions. To delete a feature or a node type, select it and use the DELETE key, the Delete item on the context menu, or the delete button on the toolbar.

All extension events are on the ExtensionSnapIn object. These events receive an MMCDataObject object (or a collection of MMCDataObject objects when multiple selection is enabled and multiple snap-ins are involved in the selection). This object gives the snap-in access to the data exported by the stand-alone snap-in. Visual Basic® snap-ins can read any data exported by a C++ snap-in. The data is received by the extension snap-in as a Byte array. MMCDataObject has a method called FormatData that can assign a portion of a Byte array to Visual Basic data types. For more information see "MMCDataObject" and "Importing Data from C++ Snap-ins."

The ExtensionSnapIn_AddNewMenuItems and ExtensionSnapIn_AddTaskMenuItems events are used to add items to the New and All Tasks submenus of MMC's context menus. Define your menus as you would for a stand-alone snap-in and add them using ContextMenu.AddMenu. Click events are handled on the menu object as in a stand-alone snap-in.

ExtensionSnapIn_SetControlbar is used to add a toolbar to MMC when the extended node type is selected. Define your toolbar as you would for a stand-alone snap-in and call Controlbar.Attach. Both toolbars and menu buttons can be added. Click events are handled on the toolbar object as in a stand-alone snap-in.

ExtensionSnapIn_CreatePropertyPages is used to add a property page to the property sheet being displayed for the extended node type. Define your property page as you would for a stand-alone snap-in and call MMCPropertySheet.AddPage. In the PropertyPage_SelectionChanged event, SelectedControls(0) will contain the same MMCDataObject passed to ExtensionSnapIn_CreatePropertyPages. Extensions for multiple-selection property pages are not supported by MMC 1.1 or by MMC 1.2 prior to Windows 2000 RC2.

ExtensionSnapIn_AddTasks is used to add tasks to a taskpad being displayed by the extended node type. It receives the taskpad's group name and an empty Tasks collection. The extension snap-in adds tasks to the collection and then receives the ExtensionSnapIn_TaskClick event when the user clicks one of its tasks. The group name of a taskpad displayed by a Visual Basic snap-in is the taskpad's name in the designer window. This can also be defined at run time using the Taskpad.Name property.

ExtensionSnapIn_Expand is called when the extended node type is expanded in the scope pane. The extension can call ScopeItems.AddPredefined or ScopeItems.Add just as it does for a stand-alone snap-in to add its nodes as children of the extended node. When the user selects the extension's child nodes the events fired are the same as for a node added by a stand-alone snap-in.

In addition to the extension features, you must also decide whether your extension will be dynamic. The Dynamic property can be set in the Visual Basic property browser. A dynamic extension is not automatically loaded when the feature it extends is used. The extended snap-in must explicitly tell MMC to load the snap-in.

Stand-alone and dual-mode Visual Basic snap-ins can load dynamic extensions by accessing ScopeItem.DynamicExtensions or MMCListItem.DynamicExtensions. These properties are collections of Extension objects for every extension registered for the node type. The Extension object has properties that indicate which features are extended. It also has Enabled and NameSpaceEnabled properties that determine whether the dynamic extension will be loaded for namespace and non-namespace features.


Printing

[This is preliminary documentation and subject to change.]

A snap-in can allow the user to request printing for selected items by enabling the print verb in its Views_Select event handler. For more information see "Views."

When the print verb is enabled MMC displays a printer button on the toolbar and adds a Print item to its Action and context menus. When the user makes a selection and invokes print the snap-in receives the Views_Print event. The selected items are passed as a parameter to this event. It is then up to the snap-in to determine what and how to print.


Programming Techniques

[This is preliminary documentation and subject to change.]

The following topics discuss various techniques for implementing common snap-in features such as exchanging data with other snap-ins, drag/drop, and multiple selection.


Using Forms

[This is preliminary documentation and subject to change.]

A Visual Basic® form is essentially a modal dialog box. (Forms can be modeless, but not within an ActiveX® DLL such as a snap-in.) Snap-ins are generally discouraged from displaying modal dialog boxes because the MMC UI is shared. A modal dialog box locks out other snap-ins within the console that might require user interaction. The preferred technique is to use a property page without an Apply button. MMC's property page mechanism uses a separate thread so as not to lock out the console UI. A snap-in can display a property page at any time using the MMCPropertySheetProvider object. An example of this can be found in the DriveStats sample in ResultView_ListpadButtonClick.

There still may be times when a modal dialog box is necessary and a snap-in can use a form for this purpose. An example of using a form is in the FileExplorer sample when the user invokes "Run As" to run a file with a specified command line. See the subroutine LaunchFileRunAs.

See "Initiating Property Sheet and Wizard Displays Programmatically" for more information.


Changing the Mouse Cursor

[This is preliminary documentation and subject to change.]

Visual Basic® UI code commonly changes the mouse cursor to an hourglass during lengthy operations by setting Screen.MousePointer. MMC does not provide a way for snap-ins to change the mouse cursor because the UI is shared and snap-ins should not lock out the user from interaction with other snap-ins in the console. Consequently, Screen.MousePointer does not work in Visual Basic snap-ins.

If your snap-in does have some lengthy operation to perform, it should be done in a property sheet if possible. By creating a property sheet programmatically using the MMCPropertySheetProvider object, the snap-in can simulate a modeless form with OK and Cancel buttons. MMC will run the property sheet in a separate thread and the page can change Screen.MousePointer.

See "Initiating Property Sheet and Wizard Displays Programmatically" for more information.


Asynchronous Population of Scope and Result Panes

[This is preliminary documentation and subject to change.]

Snap-ins may not always be able to populate the scope and result panes at the MMC-appointed times (when a scope item is expanded or when a list view is displayed). Snap-ins can retrieve their data from sources that fire events as data arrives (for example, the Internet Transfer control) or snap-ins can poll their data sources periodically. Snap-ins can call ScopeItems.AddPredefined, ScopeItems.Add, and CurrentListview.ListItems.Add during these events but the call must occur in the snap-in module. If the asynchronous event occurs in another module then the handler must call into a public method in the snap-in module that will add the items. The snap-in can pass a reference to itself to a public method in the data collection module where it can be stored in a module-level variable. The following code illustrates this technique. Assume that the snap-in has a class called clsDataCol that acquires the data asynchronously.

In the snap-in's module (for example, MySnapIn.dsr):

Private m_DataCol As clsDataCol

Private Sub SnapIn_Load
    Set m_DataCol = New clsDataCol
    m_DataCol.SetSnapIn Me
End Sub

Public Sub PopulateMMC(…)
    ' This method is called from clsDataCol when data arrives
    ScopeItems.AddPredefined(…)
End Sub

In the clsDataCol module (clsDataCol.cls):

Private m_MySnapIn As MySnapIn

Public Sub SetSnapIn(TheSnapIn As MySnapIn)
    Set m_MySnapIn = TheSnapIn
End Sub

Private Sub SomeEventHandler(…)
    ' Call into the snap-in so it can add a scope item
    m_MySnapIn.PopulateMMC …
End Sub

A snap-in can also fetch data using a separate thread or process. A separate data-fetching process can be written in Visual Basic®. The data-fetching project should be an ActiveX EXE and it should have a class that raises events. For example, consider an ActiveX EXE project called DataFetch with a class called Fetcher. The class defines an event called SendDataToSnapIn:

Public Event SendDataToSnapIn(Data As Variant)

When the class receives the data and is ready to send it to the snap-in it fires the event:

Dim SomeData As Variant
… code that sets SomeData …
RaiseEvent SendDataToSnapIn(SomeData)

In the snap-in, reference the DataFetch type library using References on the Project menu. The snap-in declares a module-level variable holding a Fetcher object and creates an instance of the object in the SnapIn_Load event:

Dim WithEvents m_Fetcher As DataFetch.Fetcher

Private Sub SnapIn_Load
    Set m_Fetcher = New DataFetch.Fetcher
End Sub

Creating the object instance starts an instance of DataFetch.exe and returns a reference to the Fetcher object. Because the snap-in uses Dim WithEvents in its declaration, it must implement the events defined by the Fetcher object. When Fetcher calls RaiseEvent, the snap-in's event handler is called and it can populate the scope pane or result pane:

Private Sub m_Fetcher_SendDataToSnapIn(Data As Variant)
    ScopeItems.AddPredefined etc.
End Sub

Using a separate thread requires writing a COM object in C++. The COM object should have a default dual interface and define an event interface that is also dual. It must also support IConnectionPointContainer and IConnectionPoint to allow the snap-in to sink its events. The snap-in code is the same as for the out-of-process example described above. When the COM object is created by the snap-in, it will be created on the same thread as the snap-in. The COM object can create a separate thread to do the data fetching. The COM object can marshal the event sink interface using CoMarshalInterThreadInterfaceInStream and pass it to the data-fetching thread so that it can fire the events directly. Alternatively, the data-fetching thread can communicate with the COM object using any desired communication mechanism and the COM object can fire the events.


Coordinating Image Lists

[This is preliminary documentation and subject to change.]

The various image lists used by a snap-in can be simplified by using the same image lists for both the scope and result panes. A snap-in that displays list views must specify five image lists.

In the scope pane these are SmallFolders, SmallOpenFolders, and LargeFolders. These can be specified at design time in the snap-in property sheet (displayed for the root node of the designer tree view) or in the property browser. They can also be specified at run time in SnapIn_Initialize.

In the result pane, the image lists are ResultView.ListView.Icons and ResultView.ListView.SmallIcons. These can be specified at design time in the list view property sheet or at run time in ResultViews_Initialize.

A list item only uses the result pane image lists. A scope item uses the snap-in image lists when it appears in the scope pane and it uses the result pane image lists when it appears in the result pane.

The easiest technique for keeping images coordinated in both panes is to create three image lists: one each for small, small open, and large bitmaps. Put the scope item images at the beginning of each image list. In the small and large lists, add the list view images following the scope item images. By doing this, the scope item's Folder property that is used to specify its image key or index will reference the same image regardless of whether it appears in the scope pane or in the result pane.


Importing Data from C++ Snap-ins

[This is preliminary documentation and subject to change.]

Visual Basic® snap-ins use MMCDataObject.GetData to import data from C++ snap-ins. The designer runtime uses the IDataObject interface to communicate with C++ snap-ins.

When a Visual Basic snap-in imports data from a C++ snap-in, the designer runtime will try both IDataObject::GetData and IDataObject::GetDataHere with TYMED_HGLOBAL and TYMED_ISTREAM. MMCDataObject.GetData has an optional parameter MaximumLength. If this parameter is passed in then the designer runtime will ask the extended snap-in for its data by calling IDataObject::GetDataHere(TYMED_HGLOBAL) with a buffer of the specified length. If the parameter is not passed the runtime will try various combinations of IDataObject::GetData and IDataObject::GetDataHere using TYMED_HGLOBAL and TYMED_ISTREAM.

The runtime will try ANSI clipboard format names on all systems and both Unicode and ANSI names on Windows NT® and Windows® 2000.

The MMCDataObject.FormatData method can convert portions of a byte stream from some common C++ data types to Visual Basic data types. The following table shows how to code these conversions. It assumes that the importing Visual Basic snap-in has executed the following code to assign the data to a local variable of type Variant and that the data type is at the first byte. When the data type is located later in the array, the second parameter to FormatData would specify the one-based index of that location.

Dim Data As Variant
Data = DataObject.GetData("SomeFormatName")
Exported data type from C++ snap-in Import in Visual Basic snap-in
BYTE or unsigned char
Dim Bytes As Bytes()

Dim TheByte As Byte
Bytes = Data
TheByte = Bytes(1)
short
Dim i As Integer

i = FormatData(Data, 1, siInteger)
int
Dim l as Long

l = FormatData(Data, 1, siLong)
long
Dim l As Long

l = FormatData(Data, 1, siLong)
float
Dim s As Single

s = FormatData(Data, 1, siSingle)
double
Dim d As Double

d = FormatData(Data, 1, siDouble)
BOOL
Dim b As Boolean

b = FormatData(Data, 1, siCBoolean)
DATE
Dim d as Date

d = FormatData(Data, 1, siDate)
CY
Dim c As Currency

c = FormatData(Data, 1, siCurrency)
Unicode string
Dim s As String

s = FormatData(Data, 1, siString)
Multiple concatenated null-terminated Unicode strings with double null termination
Dim Strings As String()

Strings = FormatData(Data, 1, siMultiString)

For more information see "MMCDataObject" and "Developing Extension and Dual-Mode Snap-ins."


Publishing and Interpreting Data Formats from a Visual Basic Snap-in

[This is preliminary documentation and subject to change.]

Snap-ins that have extensible node types must document their data formats so that other snap-ins will be able to interpret their exported data. Documentation should include both the interface methods and the format of the data.

Visual Basic® snap-ins always use MMCDataObject.GetData regardless of whether the source snap-in is written in Visual Basic or in C++. When a Visual Basic snap-in imports data from another snap-in (regardless of the source), it receives a Byte array within a Variant that must be converted into Visual Basic data types. MMCDataObject.FormatData and SnapIn.FormatData perform these conversions. See "MMCDataObject" for more information.

A Visual Basic snap-in can also import data from itself. If it calls MMCDataObject.GetData within the same instance of itself (for example, during a drag/drop operation), it will receive the same Variant that is passed to MMCDataObject.SetData and it does not need to call FormatData. If a snap-in imports data from a different instance of itself (for example, dragging and dropping between consoles), then it must call FormatData to interpret the Byte array.

When a C++ snap-in imports data from a Visual Basic snap-in it can use IDataObject::GetData or IDataObject::GetDataHere with TYMED_HGLOBAL or TYMED_ISTREAM. The designer runtime registers all clipboard format names as both ANSI and Unicode names on Windows NT and Windows 2000 using the Win32® API functions RegisterClipboardFormatA and RegisterClipboardFormatW. Formats are registered as ANSI names on Windows 95 and Windows 98.

The following table shows data types used in the Variant passed to MMCDataObject.SetData and how Visual Basic and C++ snap-ins must interpret them. The table assumes that the importing Visual Basic snap-in has executed the following code to assign the data to a local variable of type Variant:

Dim Data As Variant
Data = DataObject.GetData("SomeFormatName")
Exported data type from Visual Basic snap-in Import in Visual Basic snap-in Import in C++ snap-in
Byte
Dim Bytes As Bytes()

Dim TheByte As Byte
Bytes = Data
TheByte = Bytes(1)

Read sizeof(VARIANT.bVal) into VARIANT.bVal.

VARIANT.vt = VT_UI1.
Integer
Dim i As Integer

i = FormatData(Data, 1, siInteger)

Read sizeof(VARIANT.iVal) into VARIANT.iVal.

VARIANT.vt = VT_I2.
Long
Dim l as Long

l = FormatData(Data, 1, siLong)

Read sizeof(VARIANT.lVal) into VARIANT.lVal.

VARIANT.vt = VT_I4.
Single
Dim s As Single

s = FormatData(Data, 1, siSingle)

Read sizeof(VARIANT.fltVal) into VARIANT.fltVal.

VARIANT.vt = VT_R4.
Double
Dim d As Double

d = FormatData(Data, 1, siDouble)

Read sizeof(VARIANT.dblVal) into VARIANT.dblVal.

VARIANT.vt = VT_R8.
Boolean
Dim b As Boolean

b = FormatData(Data, 1, siBoolean)

Read sizeof(VARIANT.boolVal) into VARIANT.boolVal.

VARIANT.vt = VT_BOOL.
Date
Dim d as Date

d = FormatData(Data, 1, siDate)

Read sizeof(VARIANT.date) into VARIANT.date.

VARIANT.vt = VT_DATE.
Currency
Dim c As Currency

c = FormatData(Data, 1, siCurrency)

Read sizeof(VARIANT.cyVal) into VARIANT.cyVal.

VARIANT.vt = VT_CY.
String
Dim s As String

s = FormatData(Data, 1, siString)
Read data as a null-terminated Unicode string.
Persisted Object
Dim o As Object

Set o = FormatData(Data, 1, siObject)
Use TYMED_ISTREAM or use TYMED_GLOBAL and create stream on HGLOBAL. Use ReadClassStm to get CLSID. Call CoCreateInstance and then IUnknown::QueryInterface(IID_ IPersistStreamInit). Call IPersistStreamInit::Load().
Object Reference
Dim o As Object

Set o = FormatData(Data, 1, siObjectInstance)
Use TYMED_ISTREAM or use TYMED_GLOBAL and create stream on HGLOBAL. Use ReadClassStm to get CLSID. Call CoUnmarshalInterface(IID_IUnknown) and then IUnknown::QueryInterface for the desired interface.
Byte Array
Dim Bytes As Bytes()

Bytes = Data
Data is BYTE array.
String Array
Dim Strings As String()

Strings = FormatData(Data, 1, siMultiString)
Read data as concatenated null-terminated Unicode strings terminated by a double Unicode null character.


Establishing Two-Way Communication Between Primary and Extension Snap-ins

[This is preliminary documentation and subject to change.]

A common design technique is to use a primary snap-in with one or more extension snap-ins. For example, the Windows® 2000 Computer Management snap-in is really a shell that houses numerous extension snap-ins that configure all the systems on a given machine. In a situation where the same organization writes both the primary and the extension snap-ins, it is often desirable to have two-way communication between the primary snap-in and its extensions. This can be done by creating a Visual Basic® class in the primary snap-in and adding that class in Project/References of each extension snap-in. The primary snap-in should export a data format that holds an instance of the class. The following example exports an instance of MyClass in the data for a scope item:

Dim cls As New MyClass

cls.SomeProperty = SomeValue
ScopeItem.Data.SetData "MyClass Format", siObjectReference

The extension snap-in gets a reference to the object by using the SnapIn.FormatData or MMCDataObject.FormatData method. The following example assumes that the extension snap-in received the MMCDataObject in a parameter called Data:

Dim cls As MyClass
Dim v As Variant
v = Data.GetData("MyClass Format")
Set cls = FormatData(v, 1, siObjectInstance)

The extension snap-in can then access the methods and properties of the class.

If the primary and extension snap-ins need to asynchronously communicate then the class could also support events and both snap-ins can use Dim WithEvents. One snap-in can then call a method that will fire an event that is handled by the other snap-in. For more information on Visual Basic classes and using WithEvents see the Visual Basic documentation.


Using Virtual List Views

[This is preliminary documentation and subject to change.]

Virtual list views appear to the user as any other list view but the underlying code to populate them is optimized for large data sets. List views that contain more than several hundred items generally achieve significant performance improvement as virtual lists. The decision to use a virtual list view should be based on the cost of fetching the data as well as the volume of data. In the case of a remote database query with a huge result set a virtual list view would be an obvious choice. In other less clear-cut circumstances the developer should try both list view types before making a final choice.

In a nonvirtual list view the snap-in typically populates the entire list view in the ResultViews_Initialize or ResultViews_Activate event by calling MMCListItems.Add. As the user scrolls through the list view the snap-in does not receive any further events.

In a virtual list view the snap-in typically calls MMCListItems.SetItemCount in the ResultViews_Activate event to tell MMC how many items are in the list view. This allows MMC to adjust the scroll bars and calculate the index of the displayed list items as the user navigates using the PAGEUP, PAGEDOWN, HOME, and END keys. MMCListItems.SetItemCount must be called before any columns are added to the list view. If the snap-in uses a predefined list view then it should call MMCListItems.SetItemCount in the ResultViews_Activate event because the designer runtime will add the columns to MMC when this event handler returns. If the snap-in is adding the columns in code then it should do so in the ResultViews_Initialize event and the snap-in should then call MMCListItems.SetItemCount in ResultViews_Activate.

When MMC needs to display data for a list view the snap-in receives the GetVirtualItemDisplayInfo event:

Private Sub ResultViews_GetVirtualItemDisplayInfo(ByVal ResultView As SnapInLib.ResultView, ByVal ListItem As SnapInLib.MMCListItem)

The MMCListItem object passed to this event is only used for the duration of the event. The snap-in must examine ListItem.Index to determine which item MMC has requested and then set ListItem.Text. If the list view might be changed to detail or filtered mode then the snap-in must also populate ListItem.ListSubItems. ListItem.Icon should also be set at this time.

GetVirtualItemDisplayInfo is fired as the user navigates through the list view. For example, if the user has sized the console such that the list view can display 25 items then when the result pane is created the snap-in will receive this event 25 times. If the user then presses the PAGEDOWN key the snap-in will receive the event another 25 times so that MMC can repopulate the window.

A snap-in can also change the properties of any currently displayed list item by simply referencing it in the MMCListItems collection as it would for a nonvirtual list view:

CurrentListView.ListItems(23).Text = "Some new text"
CurrentListView.ListItems(23).Update

The only difference is that the snap-in must always use a numeric index. Keys cannot be used to reference virtual list items because the items are not actually stored in the MMCListItems collection.

When MMC needs the exported data for a virtual list item the snap-in receives the GetVirtualItemData event:

Private Sub ResultViews_GetVirtualItemData(ByVal ResultView As SnapInLib.ResultView, ByVal ListItem As SnapInLib.MMCListItem)

This event allows the snap-in to set exported data for extensions in MMCListItem.Data and to enable dynamic extensions for the list item using MMCListItem.DynamicExtensions. If the snap-in needs to use MMCListITem.Tag it should set it in this event.

In virtual list views MMCListItem.ID is set to a string containing the index of the list item. If the snap-in needs to set this property it should do so in the GetVirtualItemData event. MMCListItem.ID is used by the runtime to determine whether two list items represent the same underlying data. For more information see "MMCListItem."

SortItems is called to inform the snap-in that list items will be fetched in sorted order on a particular column. MMC does not do anything for sorting a virtual list view other than firing this event. The snap-in will continue to receive GetVirtualItemDisplayInfo events as needed to repopulate the window but it must return the appropriate data according to the sorting criteria.

The CacheHint event is called to allow the snap-in to begin asynchronous fetching of data for list items that are likely to be displayed soon:

Private Sub ResultViews_CacheHint(ByVal ResultView As SnapInLib.ResultView, ByVal StartingIndex As Long, ByVal EndingIndex As Long)

Typical usage of this event is to initiate the data fetch for the items from StartingIndex to EndingIndex. If the data arrives before it is needed then the snap-in can store it in locally until it is requested by MMC. If the user navigates to an area of the list view that is far from the prefetched data then the snap-in can discard it. The snap-in can monitor the user's navigation by examining MMCListItem.Index in the GetVirtualItemDisplayInfo event.

FindItem is called when the user searches for items by typing the initial letters:

Private Sub ResultViews_FindItem(ByVal ResultView As SnapInLib.ResultView, ByVal Name As String, ByVal StartingIndex As Long, ByVal Wrap As Boolean, ByVal PartialName As Boolean, Found As Boolean, Index As Long)

The user is typing characters to navigate to an item based on the value of the list item's text (MMCListItem.Text). Name contains the characters the user has typed so far. StartingIndex indicates which item the search should begin from. Wrap indicates whether the snap-in should continue searching from the beginning if it has not found the item between StartingIndex and the end of the data set. PartialName indicates whether the snap-in should consider item text that begins with Name to be a match.

DeselectAll is called when the user deselects everything in the list view so that the snap-in can update console verbs and toolbars.

Note Unlike nonvirtual list views, MMC does not automatically add child scope items to a virtual list view. If the snap-in needs to display a child scope item in a virtual list view, it must simulate it by using the scope item's image and column data for a virtual list item.


Using Column Persistence

[This is preliminary documentation and subject to change.]

This feature is introduced in MMC 1.2. It is not available in MMC 1.1.

Starting with version 1.2, MMC persists column customization and sorting parameters as the user moves between scope items in the scope pane. This allows a user to customize a list view, select another node, and then return to the original node with the customizations preserved. MMC also saves the customizations in the .msc file when the user saves the console and then restores them when the file is loaded.

MMC requires that every scope item have an ID for identifying its persisted column configuration within each view. If the snap-in does not explicitly supply an ID then MMC uses the scope item's node type GUID. This means that if the snap-in has multiple scope items of the same node type in the scope pane, and it does not explicitly set an ID, then the user's customization will be propagated across the different list views. Snap-ins can change the ID by setting ScopePaneItem.ColumnSetID. This property is on ScopePaneItem rather than ScopeItem because it only applies to the display of the ScopeItem within a particular view.

Customization affects column visibility, column width, column order, sort order, sort column, and sort icon display. Customization properties are available from View.ColumnSettings and View.SortSettings.

View.ColumnSettings returns a collection of ColumnSetting objects. The ColumnSetting object has properties for width, visibility, and position.

ViewSortSettings returns a collection of SortKey objects. The SortKey object has properties for column number, sort order, and sort icon display. As of MMC 1.2, there can only be one sort key.

If the snap-in needs to persist additional information related to column or sort settings (for example, the columns of a customized multicolumn sort) it can use ScopePaneItem.Tag to hold this information. If the snap-in needs to persist this information in the .msc file it should implement the Views_WriteProperties and Views_ReadProperties events. Those events allow persisting data on a per-view basis.

When a snap-in sets properties on ColumnSetting and SortKey objects, no changes are made to the persisted column data. To change the persisted column data the snap-in must call ColumnSettings.Persist and/or SortKeys.Persist.

Snap-ins can examine the column persistence data in ScopeItems_Expand, ExtensionSnapIn_Expand, and ResultViews_Activate to determine whether data fetching can be optimized (for example, data for a hidden column need not be fetched). If the snap-in needs to make changes it can change the corresponding properties and call ColumnSettings.Persist and/or SortKeys.Persist.

If the user makes any column setting changes while the list view is displayed the snap-in receives the ResultViews_ColumnsChanged event:

Private Sub ResultViews_ColumnsChanged(ByVal ResultView As SnapInLib.ResultView, ByVal Columns As Variant, Persist As Boolean)

The Columns parameter contains an array of column numbers of visible columns in the order set by the user. For example, if the list view had four columns and the user moved column 3 before column 2 and hid column 4, then the array would contain the numbers 1, 3, 2. If the snap-in returns Persist=False then the changes will not be persisted and they will only affect the current instance of the list view. In this case the snap-in should display a message box explaining why the user's changes will not be persisted.

If the snap-in needs to monitor sorting changes it should handle the ResultViews_ColumnClick event:

Private Sub ResultViews_ColumnClick(ByVal ResultView As SnapInLib.ResultView, ByVal ColumnNumber As Long, ByVal SortOrder As SnapInLib.SnapInSortOrderConstants)

ColumnNumber indicates the column clicked and SortOrder indicates in which direction MMC will do the sort.

Another opportunity to make changes is in ResultViews_Deactivate. In this event the snap-in can determine the user's configuration by examining the corresponding properties and then decide whether to make any changes. As in ResultViews_Activate, the snap-in must change the properties and then call ColumnSettings.Persist and/or SortKeys.Persist to persist the changes.


Using Column Filtering

[This is preliminary documentation and subject to change.]

This feature is introduced in MMC 1.2. It is not available in MMC 1.1.

In MMC 1.2 and later a list view can be displayed in filtered mode. The list view displays an edit control and a small button underneath each column header.

The typical user action is to type text into the edit control and press ENTER. The snap-in then receives the ResultViews_FilterChange event:

Private Sub ResultViews_FilterChange(ByVal ResultView As SnapInLib.ResultView, ByVal Column As SnapInLib.MMCColumnHeader, ByVal ChangeType As SnapInLib.SnapInFilterChangeTypeConstants)

ChangeType in this case will be set to siValueChange. MMC does nothing further in response to this user input. The snap-in can apply the new filtering criteria or ignore the input. If the user enters text and does not press ENTER then this event will be fired after a time-out specified in milliseconds by MMCListView.FilterChangeTimeout.

This event is also fired when the user switches in and out of filtered mode using the console's "View" mode. In those cases ChangeType will be set to siEnable or siDisable.

Filter values for a column are considered textual or numeric. The values can be read and written by a snap-in using the properties MMCColumnHeader.TextFilter and MMCColumnHeader.NumericFilter. MMCColumnHeader.NumericFilter is used to set a numeric filter value. The snap-in can also get its value to determine if the user has entered a numeric value in the column filter and examine that value. The MMCColumnHeader.TextFilter property serves the same function for text values. MMCColumnHeader.TextFilterMaxLen can be used to get and set the maximum length of text the user can enter. To prevent the user from entering a value, set MMCColumnHeader.TextFilterMaxLen to zero. If the filter value is blank then both properties return an empty Variant. To make the value empty set either property to an empty Variant.

If the user clicks the filter button the snap-in receives the ResultViews_FilterButtonClick event:

Private Sub ResultViews_FilterButtonClick(ByVal ResultView As SnapInLib.ResultView, ByVal Column As SnapInLib.MMCColumnHeader, ByVal Left As Long, ByVal Top As Long, ByVal Height As Long, ByVal Width As Long)

MMC also does nothing in response to this user input. The snap-in should display a pop-up menu using View.PopupMenu to allow the user to choose a filter operator. The coordinates passed to the ResultViews_FilterButtonClick event indicate the size and position of the filter button so that the snap-in can display the pop-up menu at the same location.


Implementing Multiple Selection

[This is preliminary documentation and subject to change.]

Multiple selection is possible in list views in which the snap-in has explicitly enabled this feature. It can be done at design time or at run time in the ResultViews_Initialize event by setting the list view's MultiSelect property.

Any event that has an MMCClipboard parameter can potentially involve multiple items in a list view with multiple selection enabled. The snap-in must simply iterate through MMCClipboard.ScopeItems and MMCClipboard.ListItems to determine which items are selected. No other action is needed on the part of the snap-in. Supporting multiple selection is only marginally more difficult than supporting single selection because the snap-in must iterate through these collections rather than examining only the first element. The added effort is trivial and snap-ins should support multiple selection wherever appropriate for their underlying data.

MMCClipboard also contains an MMCDataObject collection. If the selection occurred in a list view containing child scope items from multiple snap-ins then MMCClipboard.DataObjects will contain an element from each snap-in involved. This situation is not common but it could occur when a node is selected in the scope pane that has multiple namespace extensions and it is displaying a list view with multiple selection enabled.

As the user adds items to the selection the snap-in receives the Views_GetMultiSelectData event. This event is fired when the second item is selected and for every item thereafter. It allows the snap-in to export data specific to the multiple selection because the designer runtime cannot export the data attached to each item individually. For example, the FileExplorer sample handles this event by adding a "Folders" format and a "Files" format to the MMCDataObject. Each format contains a string array of the folder and file paths included in the selection. Note that the event handler does not need special logic to determine if the data object already contains data from an earlier invocation of the event — it should just set the data formats with the new data relevant to the selection. The designer runtime supplies a new MMCDataObject every time this event is fired.


Implementing Drag/Drop and Cut/Copy/Paste

[This is preliminary documentation and subject to change.]

Drag/drop and cut/copy/paste are implemented in a snap-in using MMC events rather than the standard Visual Basic® mechanism. MMC simplifies these operations into a single set of events so if a snap-in supports drag/drop then it also supports cut/copy/paste. MMC consolidates everything into two possible operations: copy and move. The events involved are:

  • Views_Select. The snap-in determines if cut, copy, and paste are permitted on the current selection.
  • Views_QueryPaste. MMC asks the destination snap-in whether it can accept a paste operation on a particular scope item.
  • Views_Paste. The destination snap-in receives the pasted items. If the operation is a move then it returns information on which items it pasted.
  • Views_Cut. Used only for a move operation. The source snap-in receives information telling it which items were pasted.

When the user makes a selection in either the scope pane or the result pane the snap-in receives the Views_Select event. The snap-in uses this event to examine the selection and then uses the MMCConsoleVerbs collection to determine the state of console verbs such as cut, copy, paste, delete, refresh, and so on. If the snap-in permits the user to cut or copy the selected item(s) then those verbs are enabled.

If the user starts a drag, clicks Copy or Cut on the context menu, or clicks the cut or copy toolbar button, then the snap-in does not receive any events. This is handled entirely by MMC.

When the user drags the selection over a scope item owned by the snap-in, or displays a context menu for that scope item, the snap-in receives the Views_QueryPaste event. If the snap-in returns True then the paste item appears on the context menu or the mouse cursor changes to the copy icon. As with any OLE drag operation, if the user presses the ALT key the drag cursor changes to the move icon.

If the user drops the selection with a copy cursor onto a scope item owned by the snap-in, or clicks Paste on the context menu for that scope item, the snap-in receives the Views_Paste event:

Private Sub Views_Paste(ByVal DestView As SnapInLib.View, ByVal SourceItems As SnapInLib.MMCClipboard, ByVal DestScopeItem As SnapInLib.ScopeItem, ByVal RetToSource As SnapInLib.MMCDataObject, ByVal Move As Boolean)

SourceItems contains the items being copied. DestScopeItem is the scope item to which the user would like to copy the items. RetToSource is not used in this case and Move is False.

The snap-in iterates through SourceItems and performs whatever operations are necessary on its underlying data to implement the copy into the containing scope item referenced by DestScopeItem. This completes the operation.

If the user drops the selection with a move cursor onto a scope item owned by the snap-in, or clicks Paste on the context menu for that scope item after cutting the source, then the snap-in also receives the Views_Paste event. In this case Move is True.

If the source and destination belong to the same instance of the same snap-in then RetToSource is not used. The snap-in must perform a copy operation on its underlying data and set ScopeItem.Pasted=True and MMCListItem=True for every item successfully copied. The snap-in will then receive the the Views_Cut event:

Private Sub Views_Cut(ByVal View As SnapInLib.View, ByVal ItemsPasted As SnapInLib.MMCClipboard, ByVal RetFromTarget As SnapInLib.MMCDataObject)

The contents of ItemsPasted are the same as that of SourceItems in the Views_Paste event. The snap-in must iterate through the items and examine ScopeItem.Pasted and MMCListItem.Pasted to determine which items were successfully copied to the destination and then delete them from the source.

For a move operation where the source and destination do not belong to the same instance of the same snap-in then RetToSource is used in the Views_Paste event. This is an MMCDataObject object and the snap-in must call MMCDataObject.SetData to return information to the source snap-in describing which items were successfully pasted. The format of this data is determined by the source snap-in. If you are moving items between instances of your own snap-in then you decide on the format. If your snap-in is accepting a paste from another snap-in then you must consult the source snap-in's documentation for information on how to format the data. For more information about exchanging data with other Visual Basic and C++ snap-ins see "Importing Data from C++ Snap-ins" and "Publishing and Interpreting Data Formats from a Visual Basic Snap-in."

When the cross-snap-in Views_Paste event completes then the source snap-in receives the Views_Cut event and uses RetFromTarget instead of examining ScopeItem.Pasted and MMCListItem.Pasted. RetFromTarget is the MMCDataObject used by the target snap-in in Views_Paste to communicate which items were successfully pasted. As mentioned above, the source snap-in determines the format of the data. In Views_Cut it should call MMCDataObject.GetData, examine the data, and delete the successfully pasted items from the source.


Handling Refresh

[This is preliminary documentation and subject to change.]

A snap-in can allow the user to request a refresh operation for selected items by enabling the refresh verb in its Views_Select event handler. For more information see "Views."

When the refresh verb is enabled MMC displays a refresh button on the toolbar, adds a Refresh item to its Action and context menus, and interprets the F5 key as a refresh request. When the user makes a selection and invokes refresh the snap-in receives the Views_Refresh event. The selected items are passed as a parameter to this event. It is then up to the snap-in to determine what and how to refresh.

Snap-ins typically enable refresh for single scope item selections in the scope pane. This is similar to how Windows® Explorer allows the user to refresh the contents of a folder. To test for this condition use the following code in the Views_Select event:

Private Sub Views_Select(ByVal View As SnapInLib.View, ByVal Selection As SnapInLib.MMCClipboard, ByVal Selected As Boolean, ByVal ConsoleVerbs As SnapInLib.MMCConsoleVerbs)

If Selected And (Selection.SelectionType = siSingleScopeItem) Then
    If Not CurrentScopePaneItem Is Nothing Then
        If CurrentScopePaneItem.ScopeItem Is Selection.ScopeItems(1) Then
            ConsoleVerbs(siRefresh).Enabled = True
        End If
    End If
End If

The code first checks that something has been selected (as opposed to deselected). It also checks that the selection consists of a single scope item. If there is a scope item selected in the scope pane then CurrentScopePaneItem will have a reference to it. If the scope item referenced by CurrentScopePaneItem is the same as the selected scope item then the snap-in knows that it has been selected in the scope pane and it enables the refresh verb.

When the user invokes refresh the snap-in should do whatever is appropriate to refresh the displayed data. The typical response would be to empty the list view by calling CurrentListView.ListItems.Clear and then repopulate it. If the selected scope item has children then it may be necessary to remove them by calling ScopeItem.RemoveChildren and then repopulate the scope pane.


History Navigation: Handling the Back and Forward Buttons

[This is preliminary documentation and subject to change.]

Snap-in developers do not need to write any code to handle history navigation within a console. The designer runtime takes care of restoring the appropriate result views. When the user clicks Back the snap-in will see the Views_Select event just as if the user had selected the previous node but there will be no ScopePaneItems_GetResultViewInfo or ScopePaneItems_GetResultView events because the user has already determined which result view should be displayed. Following Views_Select the snap-in will receive ResultViews_Initialize followed by ResultViews_Activate. If the result view was cached by specifying Keep=True in ResultViews_Deactivate, then the snap-in will only see ResultViews_Activate. For more information on caching result views see "ScopePaneItems."


Using Relative URLs

[This is preliminary documentation and subject to change.]

There are several situations in which a snap-in may need to specify a URL that references a location in the snap-in DLL's directory or relative to that directory:
  • A URL result view that references an HTML file shipped with the snap-in.
  • A URL result view that references an HTML file stored as a resource in the snap-in's DLL.
  • A taskpad task added in code that references a bitmap or GIF file stored as a resource in the snap-in's DLL.

All of these situations require assembling the URL string with App.Path and the relative portion of the URL. App is a global object present in all Visual Basic® applications that contains various properties of the execution environment. App.Path contains the path to the directory where the snap-in's DLL is installed.

To use a relative URL in a URL result view that references an HTML file installed in the same directory as the snap-in's DLL

  1. Do not define a URL result view in the designer.
  2. Code the ScopePaneItems_GetResultViewInfo event handler as follows (assuming the node's name is "URLNode"):
    Private Sub ScopePaneItems_GetResultViewInfo(_
ByVal ScopePaneItem As SnapInLib.ScopePaneItem, _
ViewType As SnapInLib._
SnapInResultViewTypeConstants, _
DisplayString As String)

If ScopePaneItem.Name = "URLNode" Then
        ViewType = siURLView
        DisplayString = "file://" & App.Path & "\MyFile.htm"
    End If

End Sub

To use a relative URL in a URL result view that references an HTML file stored as a custom resource in the snap-in's DLL

  1. Do not define a URL result view in the designer.
  2. Using the Visual Basic Resource Editor add-in, add a custom resource for the HTML file and change its ID to "MyResFile.htm". (For more information on using the Resource Editor add-in see "Using Resources in Taskpads.")
  3. Code the ScopePaneItems_GetResultViewInfo event handler as follows (assuming the node's name is "URLNode"):
    Private Sub ScopePaneItems_GetResultViewInfo(_
ByVal ScopePaneItem As SnapInLib.ScopePaneItem, _
ViewType As SnapInLib._
SnapInResultViewTypeConstants, _
DisplayString As String)

If ScopePaneItem.Name = "URLNode" Then
        ViewType = siURLView
        DisplayString = "res://" & App.Path & _
 "\MySnapIn.dll" & "/CUSTOM/MyResFile.htm"
    End If

End Sub

To use a relative URL for a taskpad task image that references a bitmap stored as a resource in the snap-in's DLL

  1. Define a Taskpad result view in the designer and make it the default result view for the node.
  2. Using the Visual Basic Resource Editor add-in, add a bitmap resource and change its ID to "MyBitmap". (For more information on using the resource editor add-in see "Using Resources in Taskpads.")
  3. Code the ResultViews_Initialize event handler as follows (assuming the node's name is "TaskpadNode"):
    Private Sub ResultViews_Initialize(_
ByVal ResultView As SnapInLib.ResultView)
    If ResultView.ScopePaneItem.Name = "TaskpadNode" Then
        Dim t As Task
        Set t = ResultView.Taskpad.Tasks.Add
        t.ActionType = siNotify
        t.Text = "My Task"
        t.HelpString = "My Task HelpString"
        t.ImageType = siBitmap
        t.MouseOverImage = "res://" & App.Path & _
    "\MySnapIn.dll" & "/#2/MyBitmap"
    End If
End Sub


Localization

[This is preliminary documentation and subject to change.]

Visual Basic® snap-ins can store all of their displayed strings in resources just as C++ snap-ins do. The Visual Basic Resource Editor add-in allows defining string resources. The Visual Basic function LoadResString is used to load the strings. Following are the various strings displayed at run time and the events in which they should be set:

  • SnapIn.DisplayName, SnapIn.Description, SnapIn.Provider, SnapIn.Version — set in SnapIn_Initialize.
  • ScopeItem.ScopeNode.DisplayName — set in ScopeItems_Initialize for auto-created ScopeItems or when calling ScopeItems.Add or ScopeItems.AddPredefined.
  • MMCColumnHeader.Text — set in ResultViews_Initialize.
  • MMCListItem.Text and MMCListSubItem.Text — set when the list item is added to the list view or in a virtual list view set in ResultViews_GetVirtualtemDisplayInfo.
  • MMCButton.Caption and MMCButtonMenu.Text — set only for menu buttons in Views_SetControlbar or ExtensionSnapIn_SetControlbar.
  • MMCButton.TooltipText — set only for toolbar buttons in Views_SetControlbar or ExtensionSnapIn_SetControlbar.
  • MMCMenu.Caption and MMCMenu.StatusBarText — set in Views_AddNewMenuItems, Views_AddTopMenuItems, Views_AddTaskMenuItems, Views_AddViewMenuItems, ExtensionSnapIn_AddNewMenuItems, or ExtensionSnapIn_AddTaskMenuItems. Note that automatic view menu strings set in result view property pages at design time are not localized. Snap-ins that need to localize these strings must handle the view menu manually using Views_AddViewMenuItems and MMCMenu_Click to switch result views.
  • Taskpad.Title, Taskpad.DescriptiveText, Taskpad.ListpadTitle, Taskpad.ListpadButtonText, Task.Text, Task.HelpString — set in ResultViews_Initialize.

For more information on localization of Visual Basic code see the topic "International Issues" in the Visual Basic documentation.


Using Unicode Strings

[This is preliminary documentation and subject to change.]

Unicode strings can be used for any string in the snap-in object model. In particular, if a snap-in needs to display a multilingual list view it can set MMCListView.UseFontLinking = True and then set both MMCListItem.Text and MMCListSubItem.Text to Unicode strings. The strings can come from a database or other data source or they can be hard-coded using Visual Basic's ChrW function. For example, to set a string S to the first three characters of the Cyrillic character set use:

S = ChrW(&H400) & ChrW(&H401) & ChrW(&H402)


ScopeItem and ScopeNode: Making Sense of Name, Key, NodeTypeName, and DisplayName

[This is preliminary documentation and subject to change.]

Snap-in developers are often confused about the relationship between the following properties:
  • ScopeItem.Name
  • ScopeItem.Key
  • ScopeNode.NodeTypeName
  • ScopeNode.NodeTypeGUID
  • ScopeNode.DisplayName

The following paragraphs describe each property and its relationship to the others.

ScopeItem.Name and ScopeItem.Key must always match. Early in the development of the snap-in designer there was a difference between the two, but their meanings have since merged. By the time the merge occurred, there were too many snap-ins in existence that might break if ScopeItem.Name were removed so it had to be kept.

ScopeItem.Key is simply the string that uniquely identifies the instance of the ScopeItem object within the ScopeItems collection, just like in any other Automation (formerly called OLE Automation) collection. If the snap-in changes ScopeItem.Key then it must change ScopeItem.Name to match (and vice-versa).

ScopeNode.DisplayName is the string displayed for the scope item in the scope pane and in the result pane when it is not in detail or filtered mode.

ScopeNode.NodeTypeName is the exported name for the node type that is used in the registration database under MMC's NodeTypes key. Think of it as a class name for a particular type of ScopeItem. Because node type names are not guaranteed to be unique among snap-ins, MMC also requires a node type GUID that is in ScopeNode.NodeTypeGUID. The designer generates this GUID but you can change it at run time.

When you define a node at design time, the name you give it in the designer is its node type name. When you call ScopeItems.AddPredefined, the first parameter is the node type name. A node defined at design time is really a template used to initialize the properties of the ScopeItem at run time. If you define a node completely in code by calling ScopeItems.Add, you must explicitly set ScopeNode.NodeTypeName and ScopeNode.NodeTypeGUID. Even if the scope item is not extensible, it is still important to set ScopeNode.NodeTypeGUID because MMC uses the GUID to preserve the selection of a scope item when it saves the console file (.msc). It also uses the GUID to preserve console taskpads that are created for the node.

Why is there a separate ScopeNode object? Why not make those properties part of ScopeItem? The answer is that ScopeNode represents a node in the scope pane regardless of ownership. That is why extension events like ExtensionSnapIn_Expand receive a ScopeNode. The ScopeNode is also used to navigate the scope tree using ScopeNode.Parent, ScopeNode.Child, and so on. ScopeNode.Owned tells you whether a node belongs to your snap-in. You can also index the ScopeItems collection with the ScopeNode; for example:
If SomeScopeNode.Owned Then
    Set MyScopeItem = ScopeItems(SomeScopeNode)
End If


Creating Display-Independent Property Pages

[This is preliminary documentation and subject to change.]

A property page is generally developed on a single computer that always uses the same video adapter with the same resolution and font size. When the snap-in is distributed to customers it may run on a variety of video adapters, resolutions, and with small or large fonts. To ensure that a property page will always appear correctly regardless of video configuration the following steps should be taken:

  1. Use the property page's default ScaleMode property value of Twip.
  2. If developing with small fonts and implementing IMMCPropertyPage_GetDialogUnitSize, leave some extra space between the controls and the bottom of the page. This is needed because when the page is displayed on a computer with large fonts its height will be squeezed slightly.
  3. If developing with large fonts and implementing IMMCPropertyPage_GetDialogUnitSize, leave some extra space between the controls and the right side of the page. This is needed because when the page is displayed on a computer with small fonts its width will be squeezed slightly.
  4. Always test the page with both small and large fonts.

Twips are used for the ScaleMode property because they are a device-independent measurement that also has a very fine granularity. The word twip is a contraction of "twentieth of a point." A point is 1/72 of an inch so a twip is 1/1440 of an inch. When printing, a point is 1/72 of a physical inch but on the screen it represents 1/72 of a logical inch. The physical size of a logical inch is determined by the video configuration and it is calculated to allow smaller font sizes (for example, 8-point) to appear in a reasonable size on the screen. If an 8-point font were displayed on the screen using its physical size it would not be readable. The logical inch provides the needed magnification and also allows programs to calculate the size of their windows and controls using a device-independent measurement.

The MMC guidelines for property page sizes, control sizes, and control spacing are all given in dialog units. The dialog unit is also a device-independent measurement that is based on the average height and width of the characters in the font used in a dialog box. For vertical measurements, a dialog unit is 1/8 of the height of the characters in the dialog box's font. For horizontal measurements a dialog unit is 1/4 of the average width of the characters in the dialog box's font. While dialog units are not as granular as twips, they are sufficient for the layout of windows containing text and controls such as property pages.

Visual Basic® does not use the dialog unit measurement, but the designer does allow a property page to specify its size in dialog units at run time. If a property page implements the IMMCPropertyPage interface, the designer runtime will call IMMCPropertyPage_GetDialogUnitSize(Height, Width). If the property page does not have code in this method then the design-time size will be used.

To determine the size to use at design time, use the default ScaleMode of Twip and use the dialog-unit-to-twips calculator that is available from the context menu on the root node of the designer tree view.

As explained earlier, when moving from small fonts to large fonts, the height of a page measured in dialog units becomes slightly smaller and the width becomes slight larger. This may seem counterintuitive, because one would expect that logical units should keep their proportions. Understanding how this happens requires some additional explanation. Continue reading only if you are interested in the theory.

Windows typically uses 96 pixels per logical inch for small fonts and 120 pixels per logical inch for large fonts. This means that a font in a given point size in small fonts must increase its physical size by 25 percent when moving to large fonts. Unfortunately, the system cannot always make such exact changes. For example, on a sample small-fonts system, the MS Sans Serif 8 font has a height of 13 pixels. When moving to large fonts, by adding 25 percent the size should change to 16.25 pixels. Video adapters do not allow addressing the screen in fractions of a pixel so the system rounds it down to 16 pixels.

Consider what happens to a measurement in dialog units such as MMC's recommended property page height of 218. A vertical dialog unit is 1/8 of the font height, so the height of a property page in logical inches on the sample small-fonts system is calculated as follows:

218 dlus ÷ 8 units/character = 27.25 characters
27.25 characters X 13 pixels/character = 354.25 pixels
354.25 pixels ÷ 96 pixels/logical inch = 3.69 logical inches

If we do the same calculation on a large-fonts system we find that the property page will actually be shorter in logical inches:

218 dlus ÷ 8 units/character = 27.25 characters
27.25 characters X 16 pixels/character = 440 pixels
440 pixels ÷ 120 pixels/logical inch = 3.66 logical inches

Because the property page size in a Visual Basic snap-in is measured in twips (1/1440 of a logical inch), the logical inch size will be the same regardless of the font size. For property pages coded in C++, the logical inch size will be slightly different on both systems. Using the preceding example, if there were no rounding errors, then when moving to large fonts, the 3.69 logical inches would be

3.69 logical inches X 120 pixels/logical inch = 442.8 pixels

Now you can see that a property page specified in twips will be about 3 pixels higher than a property page specified in dialog units when moving to large fonts. (In practice, due to rounding, the pixel difference may be slightly higher.) If your property page implements IMMCPropertyPage_GetDialogUnitSize and it returns 218 for the height, then on a large-fonts system, it will be created slightly smaller than what was expected at design time because of the difference in calculations. This should generally not be a problem, but pages that have controls close to the bottom may need to be moved up to allow for the decreased height.

A similar problem occurs in the width calculations except that the page becomes too large when moving to large fonts. On the sample system, the average width of a character in the MS Sans Serif 8 font is 6 pixels. When moving to large fonts, adding 25 percent would require 7.5 pixels. The system rounds this up to 8 pixels. Because the font is too large, the size of the horizontal dialog unit increases more than it should and the width of the page increases. Because of this, pages designed on a large-fonts system should leave some extra room on the right side, because the width of the page will be squeezed when moving to small fonts.

For more information see "IMMCPropertyPage."


Displaying Property Pages to Edit Security Attributes

[This is preliminary documentation and subject to change.]

Snap-ins often need to allow the user to configure the security attributes of an object such as a file or a folder. In Windows® 2000, the CreateSecurityPage Win32® API function can be used to create a property page that edits an access control list (ACL). Unfortunately, this convenient API is only available in C++. It can be used in a Visual Basic® snap-in with a little help from a small COM object written in C++ and by calling MMCPropertySheet.AddPageProvider from within a property page.

The Visual Basic property page should implement the IMMCPropertyPage interface and in IMMCPropertyPage_Initialize it should call MMCPropertySheet.AddPageProvider. This method receives the CLSID of an object and returns a reference to the object and the HWND of the property sheet. For example, assuming that the COM object's class is called PageProvider and the snap-in project has referenced its object library in Project/References:

Const CLSIDPageProvider = "{2205DFD5-E441-4144-AEBF-08B38F19760A}"

Private Sub IMMCPropertyPage_Initialize(ByVal Data As Variant, _
                 ByVal PropertySheet As SnapInLib.MMCPropertySheet)

    Dim Provider As PageProvider
    Dim hwndSheet As Long
    Set Provider=PropertySheet.AddPageProvider(CLSIDPageProvider,_
 hwndSheet)

The COM object must also implement a default interface that has methods allowing the Visual Basic property page to manipulate it. For example, the PageProvider object described above might be defined in its Interface Definition Language (IDL) file as follows:

[
    uuid(CFD7BADA-5BDD-4CEA-B9C1-EEB55A431439),
    version(1.0),
    helpstring("SecurityObject 1.0 Type Library")
]
library SECURITYOBJECTLib
{
    importlib("stdole32.tlb");
    importlib("stdole2.tlb");

    [
        object,
        uuid(5BA90939-218F-417E-BDC8-A56F11ADFC2F),
        dual,
        helpstring("IPageProvider Interface"),
        pointer_default(unique)
    ]
    interface IPageProvider : IDispatch
    {
        [id(1),
 helpstring("Add the security page to the property sheet")]
        HRESULT AddSecurityPage(BSTR ServerName,
                                BSTR ObjectName,
                                BSTR PageTitle,
                                long hwndSheet);
    };

    [
        uuid(2205DFD5-E441-4144-AEBF-08B38F19760A),
        helpstring("PageProvider Class")
    ]
    coclass PageProvider
    {
        [default] interface IPageProvider;
    };
};

After creating the sample PageProvider object, the Visual Basic property page would call its AddSecurityPage method passing the parameters needed to call the CreateSecurityPage API function:

Provider.AddSecurityPage "SomeServerName", _
                                     "C:\SomeFolder\SomeFile.ext", _
"Security", _
hwndSheet

The COM object's implementation of that method would then send a PSM_ADDPAGE message to the HWND of the property sheet. The following example assumes that the same object also implements the ISecurityInformation interface required by the CreateSecurityPage function:

STDMETHODIMP PageProvider::AddSecurityPage(BSTR ServerName,
                                           BSTR ObjectName,
                                           BSTR PageTitle,
                                           long hwndSheet)
{
    ... code to store the parameters ...

    HPROPSHEETPAGE hPage = ::CreateSecurityPage(
static_cast<ISecurityInformation *>(this));
    if (NULL == hPage)
    {
        return HRESULT_FROM_WIN32(::GetLastError());
    }

    ::SendMessage((HWND)hwndSheet, PSM_ADDPAGE, 0, (LPARAM)hPage);

    return S_OK;
}

For more information see "MMCPropertySheet" and "IMMCPropertyPage."


Communicating Between Property Pages and Coordinating Apply Events

[This is preliminary documentation and subject to change.]

Snap-ins often display multiple property pages for a single object such as a scope item or a list item. Each page receives its PropertyPage_ApplyChanges event separately but the snap-in needs to defer its changes to the underlying object until all pages have processed this event. The situation is further complicated by the fact that a page receives this event both when the user selects another page and when the user clicks OK or Apply. This means that the last page displayed will receive two successive ApplyChanges events when the user clicks OK or Apply.

This situation can be handled by using a Visual Basic® class that collects data from each page as the PropertyPage_ApplyChanges event is fired and changes the underlying data after all pages have reported. Here are the steps:

  1. Create a class with methods or properties that hold the changes to the underlying data and a reference to that data.
  2. In Views_CreatePropertyPages, create an instance of the class and pass it as the InitData parameter to MMCPropertySheet.AddPage.
  3. Implement IMMCPropertyPage in each page and store a reference to the class in IMMCPropertyPage_Initialize.
  4. In each page's PropertyPage_ApplyChanges event, if the user input is OK then set the changed properties on the class and call a method on the class to tell it that the page has applied changes (for example, MyClass.PageDone("General Page").
  5. In MyClass.PageDone, track the callers and when the same page calls twice in succession, update the underlying object.

If any page doesn't call MyClass.PageDone, then the user did not visit the page.

A related issue is how property pages can communicate with each other. This can be done using the same class as described above or it can be enhanced by defining an interface and having each page implement it. The class can implement a method that takes a reference to that interface as a parameter; for example:

MyClass.Register(PageName As String, PageInterface As MyInterface)

In IMMCPropertyPage_Initialize, each page calls MyClass.Register("MyPageName", Me) and that method keeps arrays of the page names and the corresponding MyInterface references. The class can implement another method such as

MyClass.GetPage(PageName As String) As MyInterface

that looks up a page by name and returns a reference to its MyInterface implementation. That would allow any page to talk to any other page at any time.


Creating Wizard97-Style Wizards

[This is preliminary documentation and subject to change.]

Visual Basic® snap-ins cannot directly implement Wizard97-style wizards, but they can be simulated by using Image and Shape objects on the property page for the watermark and header. For wizards initiated programmatically using MMCPropertySheetProvider.CreatePropertySheet, the snap-in must specify the siWizard97 style. For configuration wizards, MMC does this automatically, although a snap-in is not required to simulate a Wizard97-style wizard.

On the Welcome page, place an Image object on the left side of the page and set its Picture property to the watermark bitmap. In the page's PropertyPage_Paint event add code to stretch the Image to the height of the page at run time:

Private Sub PropertyPage_Paint()
PaintPicture PaintPicture imgWatermark.Picture, 0, 0, _
                                     imgWatermark.Width, Height
End Sub

Note that some bitmaps might not stretch perfectly. Some adjustment of the bitmap content may be necessary. Wizard97-style wizards should be tested on systems with both small and large fonts settings in Control Panel/Display. If the snap-in is to be deployed on both MMC 1.1 and MMC 1.2 then the wizard should be tested on both systems in both font sizes. On an MMC 1.1 system with Internet Explorer 4.0 installed, the bitmap will not be stretched. On an MMC 1.1 system with Internet Explorer 5, or on an MMC 1.2 system (that requires Internet Explorer 5), the bitmap will be stretched. The stretching occurs because Internet Explorer 5 installs a newer version of comctl32.dll that implements Win32® property sheets and wizards. This newer version sizes the wizard pages slightly larger than their design-time size.

On the interior pages, use a Label with a white background for both the header title and the subtitle text. For the header bitmap use a PictureBox. For the header background use a Shape control with a white background. The shape control is placed on top of the labels and the PictureBox. In the PropertyPage_Paint event call Shape.Move to stretch the Shape to the width of the property page at run time.

Private Sub PropertyPage_Paint()
    Shape1.Move 0, 0, Width
End Sub

For more information see "MMCPropertySheetProvider."


Why Doesn't a Right-Click in the Scope Pane Change the Current Selection?

[This is preliminary documentation and subject to change.]

If a ScopeItem is selected in the scope pane and the user right-clicks a different ScopeItem, the snap-in receives the Views_Select event but the new ScopeItem does not remain selected. After the user has dismissed the context menu, the selection returns to the original ScopeItem. This can be confusing because the Views_Select event might be interpreted to indicate that the right-clicked ScopeItem is about to display a result view and become CurrentScopeItem.

MMC uses the same behavior as the Windows® Explorer for a right-click in the scope pane. This allows the user to perform a paste operation on a ScopeItem without having to select it and change the result pane. For example, the user has selected a folder and is using context menus to copy and paste various files to other folders. If every right-click on a folder changed the contents of the result pane, this would become a very tedious operation.

The snap-in can tell when a ScopeItem has been selected with a left-click when it gets the ScopePaneItems_GetResultViewInfo event. This event is fired when MMC asks the snap-in what type of result view to display for the ScopeItem.


Why Don't ScopeItems in a List View Display Text in Detail Mode?

[This is preliminary documentation and subject to change.]

When a ScopeItem that has child ScopeItem objects is selected in the scope pane and it displays a list view, MMC will automatically add the child ScopeItem objects to the list view. When the list view is not in detail or filtered mode, MMC uses ScopeItem.ScopeNode.DIsplayName for the displayed text. When the list view is in detail or filtered mode, then MMC needs some way to determine the text to be displayed in the columns. This situation is sometimes difficult to understand because the parent ScopeItem defines the columns of the list view but the child ScopeItem objects must somehow define the text that will be displayed.

ScopeItem.ColumnHeaders contains the column definitions that are used when a ScopeItem appears in a list view in the result pane. ScopeItem.ListSubItems contains the strings that are displayed in the columns. ScopeItem.SubItems contains references to the same text as a string array rather than a collection of MMCListSubItem objects. ScopeItem.ColumnHeaders and ScopeItem.ListSubItems are used when the ScopeItem's parent is selected in the scope pane and MMC displays its child ScopeItem objects in the result pane. The child ScopeItem must define columns that have keys matching one or more of the parent's list view columns. When the designer runtime receives a request for a column's text from MMC, it uses the parent list view's column key to reference the corresponding column in ScopeItem.ColumnHeaders. It then uses that header's index to reference the MMCListSubItem. The algorithm is as follows. Assume that MMC requests the text for the child ScopeItem's column n:

Key = ParentListView.ColumnHeaders(n).Key
Header = ChildScopeItem.ColumnHeaders(Key)
Text = ChildScopeItem.ListSubItems(Header.Index)

The reason for matching keys rather than simply using the corresponding indexes is to allow a ScopeItem to appear in more than one list view. By using the keys, the snap-in can display only a subset of the MMCListSubItem objects in a particular list view. For more information see "ScopeItem," "MMCColumnHeaders," and "MMCListSubItems."


Handling Orphaned Property Pages

[This is preliminary documentation and subject to change.]

The following user scenarios require special handling for property pages displaying list item data:

  1. Multiple properties invocations on the same list item
    • User opens a property sheet for a list item.
    • User returns to list view and requests properties again for the same list item.
  2. Orphaned property pages
    • User opens a property sheet for a list item.
    • User selects a different scope item in the scope pane.
    • User reselects the original scope item in the scope pane.
    • User returns to list view and requests properties again for the same list item.

Case 2 is called an orphaned property page because the list view that owns the list item is destroyed when the user selects a different scope item. The existing property sheet will always be activated on the second request because MMC asks the designer runtime whether the list item in the open property sheet matches the list item for which the second properties invocation has occurred. In case 2, if the property page has stored a reference to the list item, then it is important to remember that the list view that owns that list item no longer exists. A new list view has replaced it and that list view contains a new list item representing the same underlying data. This is why the runtime needs the MMCListItem.ID property so that it can determine whether the two list items represent the same underlying data.

These are both important test cases and should be checked for your snap-in if you support property sheets for list items. In particular, you should check your property pages' behavior after the sheet has been orphaned. You can call MMCListItem.PropertyChanged in that situation but your ResultViews_PropertyChanged event handler will receive a ResultView parameter that is Nothing. This indicates to the snap-in that the result view has been destroyed since the user opened the sheet. If your event handler depends on the ResultView parameter then you must do the following check:

If Not ResultView Is Nothing Then
    ...code that uses ResultView...
End If

If your event handler needs to change existing list items' displayed text (MMCListItem.Text and MMCListItem.ListSubItem(n).Text), then it should enumerate the existing views and check whether a corresponding list item is being displayed. An example of this is:

Private Sub ResultViews_PropertyChanged(_
ByVal ResultView As SnapInLib.ResultView, _
ByVal ListItem As SnapInLib.MMCListItem, _
ByVal Data As Variant)

    On Error GoTo Trap

    Dim v As View
    Dim spi As ScopePaneItem
    Dim rv As ResultView
    Dim li As MMCListItem

    For Each v In Views
        For Each spi In v.ScopePaneItems
            For Each rv In spi.ResultViews
                On Error Resume Next
                Set li = rv.ListView.ListItems(Data)
                On Error GoTo Trap
                If Not li Is Nothing Then
                    li.Text = ListItem.Tag
                    li.Update
                End If
            Next rv
        Next spi
    Next v

    Exit Sub
Trap:
    DisplayError "ResultViews_PropertyChanged"
End Sub

The loop looks at every existing result view and checks whether it is displaying a list item for the data that has changed. In this example, the property page called MMCListItem.PropertyChanged and passed the index of the changed item as the Data parameter. The loop then uses the Data parameter to index the collection. In a more realistic situation a snap-in would likely use MMCListItem.Key. For example, the FileExplorer sample stores the full path of the file in MMCListItem.Key so it could use that to check whether a list item for that file is in each list view.

When testing this behavior you should also try it with multiple views. If you support multiple selection then you should test both single and multiple selections.

For more information see "MMCListItem."


Using the Object Model

[This is preliminary documentation and subject to change.]

Understanding the designer object model is essential for writing all but the most trivial of snap-ins. The following sections describe each object, its usage, and its properties, methods, and events. It is strongly recommended that you also use the Visual Basic object browser. Press F2 to invoke it in the Visual Basic IDE. When the designer is released a complete detailed object model reference will be included in the documentation.

The following diagram illustrates the main objects and their relationships. These are explained in detail in the following sections.


Collections

[This is preliminary documentation and subject to change.]

The object model makes extensive use of collections for objects that have an indeterminate number of instances at design time. For example, the View object represents a multiple-document interface (MDI) child window in the console. It is not possible to know how many windows the user will open at run time so a collection is used (Views). Objects are added and removed from the collection as the user opens and closes windows. All elements in collections have Key (string) and Index (numeric, one-based) properties that identify the object and its ordinal position within the collection. Most objects have a Tag property that is a Variant allowing the snap-in to associate any extra data with the object.

When objects in a collection can generate events, those events are handled on the collection rather than on the object itself. For example, a user can interact with a view so events are needed on the View object. If the number of views is known at design time then each one can have its own event handler much like controls on a form (for example, Button1_Click). Because the user can open any number of views, the events are fired on the Views collection and the individual View object is passed as a parameter to each event handler. This is similar to the use of control arrays on a form where there is one event handler that receives the index of the control that generated the event.


The Tag Property

[This is preliminary documentation and subject to change.]

Most objects in the snap-in object model have a Variant property called Tag. This is similar to the Tag property used in many Common Controls objects in standard Visual Basic applications. It can be used to store any data that the snap-in needs to associate with the object. Tag may contain something simple such as an Integer or it may contain an object. If a snap-in needs to store more than a simple value, it should use a Visual Basic class with properties to hold the needed data.


SnapIn

The SnapIn object is the top-level object. It represents the snap-in itself and handles global information and events such as the snap-in name, version, and so on as well as console serialization. Properties of Snap-in are module-level variables and are accessible without a prefix; for example, SnapIn.DisplayName can be coded as DisplayName.

Name is used to identify the snap-in within the Visual Basic code and is similar to a class name.

DisplayName is used in the scope pane as the text for the static node and it also appears in the Snap-in Manager when a user is adding or removing a snap-in from the console.

NodeTypeName is used to identify the snap-in's static node in its registration database entries.

NodeTypeGUID is generated by the designer and it is also used to identify the snap-in's static node in its registration database entries.

Description is displayed in the Snap-in Manager after the snap-in is added and when the user requests to display About information.

Provider, Version, and Icon are displayed in the Snap-in Manager as part of the About information.

Type indicates whether the snap-in is stand-alone, an extension, or dual-mode.

RuntimeMode is used by dual-mode snap-ins at run time to determine whether they were loaded as a primary or extension snap-in.

SmallFolders, SmallFoldersOpen, and LargeFolders specify the image lists that are used for nodes added to the scope pane by the snap-in. They must all contain the corresponding images at the same indexes. StaticFolder specifies the index or key of the image used for the static node.

HelpFile specifies the name of an HTML Help file (.chm) that the snap-in will merge with MMC's Help. If the snap-in's Help file contains links to other Help files then LinkedTopics specifies a semicolon-delimited list of the additional .chm files. The ShowHelpTopic method can be used to display a specific topic in the merged Help file. The Help event is for snap-ins that do not use MMC's merged Help and instead display their own Help. See "Adding Help to a Snap-in" for more information.

MMCCommandLine contains the contents of the command line used to start MMC.EXE. Snap-ins may use command line information to customize the use of a saved console file. When running under the Visual Basic debugger this property is not available in primary snap-ins prior to the SnapIn_Load event and it is not available at all in non-namespace extensions.

TaskpadViewPreferred indicates whether the user has set the corresponding console option in MMC 1.1.

RequiredExtensions is a collection that contains an Extension object representing all of the registered extensions for the snap-in. In the SnapIn_Initialize event the snap-in can set Extension.Enabled for each extension snap-in that must be loaded when the snap-in is loaded.

Preload can be set by a snap-in at run time to indicate that it should be loaded before its parent node is expanded the next time the console file is loaded. This can be useful in situations where a snap-in's static node has a dynamic display name (for example, contains the local computer name). If the snap-in is not preloaded then MMC will use the display name stored in the console file. A preloaded snap-in receives the Preload event in which it can set DisplayName.

The SnapIn object also has some properties that serve as shorthand to access frequently used objects within the hierarchy. These are CurrentView, CurrentScopePaneItem, CurrentScopeItem, CurrentResultView, and CurrentListView. The following table shows each of these properties and the corresponding full object path. Note that any of these properties may contain the value Nothing at any time depending on the state of the console. Always check the value before using the property (e.g. If Not CurrentView Is Nothng Then etc).

Property | Shorthand for
CurrentView | Views.CurrentView
CurrentScopePaneItem | Views.CurrentView.ScopePaneItems.SelectedItem
CurrentScopeItem | Views.CurrentView.ScopePaneItems.SelectedItem.ScopeItem
CurrentResultView | Views.CurrentView.ScopePaneItems.SelectedItem.ResultView
CurrentListView | Views.CurrentView.ScopePaneItems.SelectedItem.ResultView.ListView

StringTable is a reference to an MMCStringTable object that allows a snap-in to store strings in the saved console file. For more information see "MMCStringTable."

The ConsoleMsgBox method is used by primary snap-ins to display message boxes instead of the standard Visual Basic MsgBox function. MMC displays the message box on behalf of the snap-in. Extension snap-ins must use MsgBox.

The FormatData method is used by extension snap-ins when importing data. It can convert a range within a Byte array to any Visual Basic data type.

The Trace method can be used when debugging a snap-in using other debuggers such as Microsoft Visual C++® or NTSD (NT Symbolic Debugger). It calls the Win32 API function OutputDebugString.

Snap-ins can write to and read from the console file (.msc) in the WriteProperties and ReadProperties events. These events work exactly as for UserControl and persistable Visual Basic classes using a PropertyBag. In addition to these events the snap-in also receives Views_WriteProperties and Views_ReadProperties events that allow storing view-specific data in the console file. For more information see "Views".

The Load and Unload events are fired for primary snap-ins when MMC adds the snap-in to the console and when it is removed. The Initialize and Terminate events are similar to Visual Basic classes and signal the creation and destruction of the snap-in. When the Snap-in Manager displays its Add/Remove Standalone Snap-in dialog box, the snap-in is created but it is not loaded. The snap-in will only receive the Initialize event in this case. When the user chooses the snap-in and it is loaded into the console then the snap-in will receive another Initialize event followed by the Load event. When a console file is loaded the snap-in also receives Initialize followed by Load.

When the user chooses to add a snap-in in the Snap-in Manager, the snap-in receives the QueryConfigurationWizard event. If the snap-in returns True, then it receives the CreateConfigurationWizard event in which it can add its pages to the property sheet. When the user completes the wizard the snap-in receives the ConfigurationComplete event. See "Configuration Wizards" for more information.

The major objects below SnapIn in the object hierarchy are actually properties of SnapIn (for example, ExtensionSnapIn, ScopeItems, Views). This allows the snap-in to handle events from those objects. This is analogous to the way controls are used with Visual Basic Form objects. For example, after adding a button, a Form has a new property called Button1 and its events, such as Button1_Click, are handled in the Form's module.


Properties, Methods, and Events

Syntax

Properties and methods of the snap-in object have module level scope in a snap-in. They do not need to be qualified with the object name. For example, the following lines of code are equivalent:

SnapIn.DisplayName = "Some Name"
DisplayName = "Some Name"

Properties

Clipboard | MMCClipboard object that represents the current contents of the system clipboard.
CurrentListView | Returns the list view in the result pane of the current view.
CurrentResultView | Returns the ResultView in the result pane of the current view.
CurrentScopeItem | Returns the ScopeItem selected in the scope pane of the current view.
CurrentScopePaneItem | Returns the ScopePaneItem representing the ScopeItem selected in the scope pane of the current view.
CurrentView | Returns the currently active View.
Description | Description of the snap-in displayed by the console in the About box.
DisplayName | The name used to identify the snap-in and its static within the console UI.
ExtensionSnapIn | The ExtensionSnapIn object used by extensions and dual-mode snap-ins.
HelpFile | Name of snap-in's HTML help file to be merged with MMC's help.
Icon | Icon for MMC's About property page displayed from the Add/Remove Snap-in dialog.
LargeFolders | Image list for large folder images for scope items in the result pane.
LinkedTopics | String containing help files referenced by hyperlinks in the snap-in's main help file.
MMCCommandLine | Returns the contents of the command line used start MMC.EXE
Name | The name used to identify the snap-in within Visual Basic code.
NodeTypeGUID | The GUID used to identify the static node type in the registration database.
NodeTypeName | The name used to identify the snap-in's static node in the registration database.
Preload | Determines whether the snap-in will be loaded immediately upon expansion of its parent node when the console file is next loaded.
Provider | Name of the company or organization that created the snap-in.
RequiredExtensions | Collection of objects representing the set of registered extensions for the snap-in. Set Extension.Enabled in SnapIn_Initialize to require that the extension be created when your snap-in loads.
RuntimeMode | Mode in which snap-in was created at runtime: primary, extension, or for About page information only.
ScopeItems | Collection of ScopeItem objects containing the data for the snap-in's scope items.
SmallFolders | Image list for small folder images in the scope pane and scope items in the result pane.
SmallFoldersOpen | Image list for small open folder images in the scope pane.
StaticFolder | Position in image lists of image used for static node in scope pane, result pane, and in MMC's Add Standalone Snap-in dialog.
TaskpadViewPreferred | Indicates whether user has checked the 'Show Taskpad Views By Default' option in the MMC 1.1 Options dialog box.
Type | Type of snap-in: stand-alone, extension, or dual-mode.
Version | Version number of the snap-in.
Views | Collection of View objects representing the set of MDI child windows in the console.

Methods

ConsoleMsgBox | Asks MMC to display a message box on behalf of the snap-in.
FormatData | Formats raw data in a byte array into Visual Basic data types.
ShowHelpTopic | Displays the specified HTML help topic in the merged MMC HTML help file.
Trace | Calls the Win32 API function OutputDebugString.

Events

These events will appear in the Visual Basic code as SnapIn_<EventName>.

ConfigurationComplete | Called when a configuration wizard completes.
CreateConfigurationWizard | Called to request that the snap-in add its pages to its configuration wizard
Help | Called when the user has requested general help on the console.
Load | Called when the snap-in is first loaded into the console.
Preload | If Preload was True before the console was saved, then called when the snap-in is preloaded after its parent node is expanded.
QueryConfigurationWizard | Called when the user adds the snap-in to a consoleto ask whether it has a configuration wizard.
ReadProperties | Called when the user is loading the console from a saved console file.
Unload | Called when the snap-in is destroyed by the console.
WriteProperties | Called when the user is saving the console to a .MSC file.

Remarks

Built on Wednesday, October 27, 1999


Clipboard Property

The Clipboard property is an MMCClipboard object used to represent snap-in data present on the system clipboard.

Syntax

Clipboard As MMCClipboard

Remarks

Snap-ins typically do not need to access this property as all event handlers that reference data on the system clipboard pass an MMCClipboard object as a parameter. MMC never expects a snap-in to use the system clipboard.


ConfigurationComplete Event

The ConfigurationComplete event tells the snap-in that the user has completed its configuration wizard.

Syntax

Private Sub SnapIn_ConfigurationComplete(ConfigurationObject As Object)

TheConfigurationComplete event syntax has these parts:

Part | Description
ConfigurationObject | This is the object passed as the ConfigurationObject parameter when the snap-in called MMCPropertySheet.AddWizardPage in the SnapIn_CreateConfigurationWizard event.

Remarks

The configuration wizard is displayed when the snap-in as added to a console. This event informs the snap-in that the user has completed the wizard and it allows the snap-in to process any configuration data set by the wizard's pages in the configuration object.


ConsoleMsgBox Method

The ConsoleMsgBox method displays a message box in the console. Snap-ins should use this method rather than the Visual Basic function MsgBox so that the message box is correctly parented by the console.

Syntax

ConsoleMsgBox(Prompt As String, [Buttons As VbMsgBoxStyle = vbOKOnly], [Title]) As VbMsgBoxResult

The ConsoleMsgBox method syntax has these parts:

Part | Description
Prompt | Required. String expression displayed as the message in the dialog box. The maximum length of prompt is approximately 1024 characters, depending on the width of the characters used. If prompt consists of more than one line, you can separate the lines using a carriage return character (Chr(13)), a linefeed character (Chr(10)), or carriage return – linefeed character combination (Chr(13) & Chr(10)) between each line.
Buttons | Optional. Numeric expression that is the sum of values specifying the number and type of buttons to display, the icon style to use, the identity of the default button, and the modality of the message box. If omitted, the default value for buttons is 0.
Title | Optional. String expression displayed in the title bar of the dialog box.

Settings

The buttons argument settings are:

Constant | Value | Description
vbOKOnly | 0 | Display OK button only.
vbOKCancel | 1 | Display OK and Cancel buttons.
vbAbortRetryIgnore | 2 | Display Abort, Retry, and Ignore buttons.
vbYesNoCancel | 3 | Display Yes, No, and Cancel buttons.
vbYesNo | 4 | Display Yes and No buttons.
vbRetryCancel | 5 | Display Retry and Cancel buttons.
vbCritical | 16 | Display Critical Message icon.
vbQuestion | 32 | Display Warning Query icon.
vbExclamation | 48 | Display Warning Message icon.
vbInformation | 64 | Display Information Message icon.
vbDefaultButton1 | 0 | First button is default.
vbDefaultButton2 | 256 | Second button is default.
vbDefaultButton3 | 512 | Third button is default.
vbDefaultButton4 | 768 | Fourth button is default.
vbApplicationModal | 0 | Application modal; the user must respond to the message box before continuing work in the current application.
vbSystemModal | 4096 | System modal; all applications are suspended until the user responds to the message box.
vbMsgBoxHelpButton | 16384 | Adds Help button to the message box
vbMsgBoxSetForeground | 65536 | Specifies the message box window as the foreground window
vbMsgBoxRight | 524288 | Text is right aligned
vbMsgBoxRtlReading | 1048576 | Specifies text should appear as right-to-left reading on Hebrew and Arabic systems

The first group of values (0–5) describes the number and type of buttons displayed in the dialog box; the second group (16, 32, 48, 64) describes the icon style; the third group (0, 256, 512) determines which button is the default; and the fourth group (0, 4096) determines the modality of the message box. When adding numbers to create a final value for the buttons argument, use only one number from each group.

Note These constants are specified by Visual Basic for Applications. As a result, the names can be used anywhere in your code in place of the actual values.

Return Values

Constant | Value | Description
vbOK | 1 | OK
vbCancel | 2 | Cancel
vbAbort | 3 | Abort
vbRetry | 4 | Retry
vbIgnore | 5 | Ignore
vbYes | 6 | Yes
vbNo | 7 | No

Remarks

If the dialog box displays a Cancel button, pressing the ESC key has the same effect as clicking Cancel. If the dialog box contains a Help button, context-sensitive Help is provided for the dialog box. However, no value is returned until one of the other buttons is clicked.

Note To specify more than the first named argument, you must use MsgBox in an expression. To omit some positional arguments, you must include the corresponding comma delimiter.


CreateConfigurationWizard Event

The CreateConfigurationWizard event tells the snap-in to add its pages to the configuration wizard displayed when the user adds a standalone snap-in to a console.

Syntax

Private Sub SnapIn_CreateConfigurationWizard(PropertySheet As MMCPropertySheet)

The CreateConfigurationWizard event syntax has these parts:

Part | Description
PropertySheet | MMCPropertySheet object used to add the snap-in's pages by calling MMCPropertySheet.AddWizardPage

Remarks

This event is only fired if the snap-in returned True in the HaveWizard parameter of the Snapin_QueryConfigurationWizard event.

When the user completes the wizard the snap-in will receive the Snapin_ConfigurationWizardComplete event. The snap-in may pass any object as the ConfigurationObject parameter to MMCPropertySheet.AddWizardPage. Snap-ins typically create a Visual Basic class containing properties for all of their configuration settings for this purpose. The object passed to MMCPropertySheet.AddWizardPage is passed as the ConfigurationObject parameter to the Snapin_ConfigurationWizardComplete event. This allows the snap-in to process the configuration settings when the user completes the wizard.


CurrentListView Property

The CurrentListView property contains the MMCListView object that represents the list view currently displayed in the result pane of the currently active view.

Syntax

CurrentListView As MMCListView

Remarks

This property may be set to Nothing and the snap-in must check it before use. For example:

If Not CurrentListView Is Nothing Then
    …some code that uses CurrentListView…
End If

CurrentListView will contain a valid reference when the user has selected a scope item in the scope pane that is owned by the snap-in and the ScopePaneItems_GetResultViewInfo event has been fired for the scope item.

This property is shorthand for Views.CurrentView.ScopePaneItems.SelectedItem.ResultView.ListView.


CurrentResultView Property

Platform SDK: Management Console

CurrentResulttView Property

The CurrentResultView property contains the ResulttView object that represents the result view currently displayed in the result pane of the currently active view.

Syntax

CurrentResultView As ResultView

Remarks

This property may be set to Nothing and the snap-in must check it before use. For example:

If Not CurrentResulttView Is Nothing Then
    …some code that uses CurrentResulttView…
End If

CurrentResultView will contain a valid reference when the user has selected a scope item in the scope pane that is owned by the snap-in and the ScopePaneItems_GetResultViewInfo event has been fired for the scope item.

This property is shorthand for Views.CurrentView.ScopePaneItems.SelectedItem.ResultView.


CurrentScopeItem Property

The CurrentScopeItem property contains the ScopeItem object that represents the scope item currently selected in the scope pane of the currently active view.

Syntax

CurrentScopeItem As ScopeItem

Remarks

This property may be set to Nothing and the snap-in must check it before use. For example:

If Not CurrentScopeItem Is Nothing Then
    …some code that uses CurrentScopeItem…
End If

CurrentScopeItem will contain a valid reference when the user has selected a scope item in the scope pane that is owned by the snap-in and the ScopePaneItems_GetResultViewInfo event has been fired for the scope item.

This property is shorthand for Views.CurrentView.ScopePaneItems.SelectedItem.ScopeItem.


CurrentScopePaneItem Property

The CurrentScopePaneItem property contains the ScopePaneItem object that represents the scope item currently selected in the scope pane of the currently active view.

Syntax

CurrentScopePaneItem As ScopePaneItem

Remarks

This property may be set to Nothing and the snap-in must check it before use. For example:

If Not CurrentScopePaneItem Is Nothing Then
    …some code that uses CurrentScopePaneItem…
End If

CurrentScopePaneItem will contain a valid reference when the user has selected a scope item in the scope pane that is owned by the snap-in and the ScopePaneItems_GetResultViewInfo event has been fired for the scope item.

This property is shorthand for Views.CurrentView.ScopePaneItems.SelectedItem.


Description Property

The Description property contains the string used by MMC when display About Box information for the snap-in.

Syntax

Description As String

Remarks

The string contained in the Description property is displayed by MMC in the following places for standalone snap-ins:

At the bottom of the "Add Standalone Snap-in" dialog when the snap-in is selected in the dialog's list view.

At the bottom of the "Add/Remove Snap-in" dialog's "Standalone" page when the snap-in is selected in the page's list view.

In the center of the dialog displayed when the user clicks the "About" button in the "Add/Remove Snap-in" dialog's "Standalone" page when the snap-in is selected in the page's list view.

The string contained in the Description property is displayed by MMC in the following places for extension snap-ins:

At the bottom of the "Add/Remove Snap-in" dialog's "Extensions" page when the snap-in is selected in the page's list view.

In the center of the dialog displayed when the user clicks the "About" button in the "Add/Remove Snap-in" dialog's "Extensions" page when the snap-in is selected in the page's list view.


DisplayName Property

The DisplayName property provides the display name for the snap-in and its static node.

Syntax

DisplayName As String

Remarks

The string contained in the DisplayName property is displayed by MMC in the following places for standalone snap-ins:

In the "Snap-in" column of the "Add Standalone Snap-in" dialog's list view.

In the list view of the "Add/Remove Snap-in" dialog's "Standalone" page.

In the combobox of the "Add/Remove Snap-in" dialog's "Extensions" page.

At the top of the dialog displayed when the user clicks the "About" button in the "Add/Remove Snap-in" dialog's "Standalone" page when the snap-in is selected in the page's list view.

The text next to the static node's image when it is displayed in the scope pane.

The text next to the static node's image when it is displayed in the result pane in large, small, or list mode.

The string contained in the DisplayName property is displayed by MMC in the following places for extension snap-ins:

In the list view of the "Add/Remove Snap-in" dialog's "Extensions" page.

At the top of the dialog displayed when the user clicks the "About" button in the "Add/Remove Snap-in" dialog's "Extensions" page when the snap-in is selected in the page's list view.

The DisplayName property for the static node can also be referenced using ScopeItems("Static Node").ScopeNode.DisplayName.


ExtensionSnapIn Property

The ExtensionSnapIn property is the one and only ExtensionSnapIn object. It is used to fire events specific to extensions using the syntax ExtensionSnapIn_<EventName>. The snap-in never needs to reference this object directly.

Syntax

ExtensionSnapIn As ExtensionSnapIn

Remarks

Built on Wednesday, October 27, 1999


FormatData Method

The FormatData method is used in an extension snap-in to interpret data imported from the primary snap-in that it extends and convert it from a Byte array to a Visual Basic data type.

Syntax

FormatData(Data, StartingIndex As Long, Format As SnapInFormatContants, [BytesUsed])

The FormatData method syntax has these parts:

Part | Description
Data | A Variant containing a Byte array that holds the raw data received from a call to MMCDataObject.GetData.
StartingIndex | The one-based index of the element in the Byte array from which to begin interpreting the data.
Format | Determines the data type to which the raw data should be converted to.
BytesUsed | Optional. Returns the number of bytes read and converted into the requested data type.

Settings

The Format argument settings are:

Constant | Description
siBoolean | Read 4 bytes and return them as a Boolean
siCBoolean | Read 2 bytes, convert them from a C/C++ language BOOL and return them as a Boolean.
siCurrency | Read 8 bytes and return them as a Currency.
siDate | Read 8 bytes and return them as a Date.
siDouble | Read 8 bytes and return them as a Double.
siGUID | Read 16 bytes as a binary GUID and return them as string in string format {00000000-0000-0000-0000-000000000000}
siInteger | Read 2 bytes and return them as an Integer.
siLong | Read 4 bytes and return them as a Long.
siMultiString | Read bytes as concatenated null-terminated UNICODE strings terminated by a double UNICODE null character. Return as an array of String.
siObject | Read CLSID from start of bytes and remainder of bytes as the contents of a stream. Create an instance of the object and load it from the stream. Visual Basic classes that are marked Persistable can be exported by the primary snap-in for this type.
siObjectInstance | Read the data as a reference to an instance of an object and return it as an Object.
siSingle | Read 4 bytes and return them as a Single.
siString | Read bytes as a null-terminated UNICODE string. Return as a String. Visual Basic String variables exported by the primary snap-in are read using this type.

Return Values

The FormatData method returns a Variant containing the data type requested in the Format argument.

Remarks

This method is used in ExtensionSnapIn events to interpret the imported data. For more information see "MMCDataObject", "Importing Data from C++ Snap-ins", and "Publishing and Interpreting Data Formats from a Visual Basic Snap-in."


Help Event

The Help event is sent when the user requests help for the snap-in and the snap-in has not implemented merged HTML help.

Syntax

Private Sub SnapIn_Help()

Remarks

If the Help property is not set to the name of an HTML help file, then when the user requests help for the snap-in this event is fired. This event has no context information parameters such as the selected scope item. It is the snap-in's responsibility to display help information in response to this event. Snap-ins using an older WinHelp file might choose to display their help information in this manner. Note that the DisplayHelpTopic method cannot be used because it only displays topics in merged HTML help files.

For more information see "Adding Help to a Snap-in".


HelpFile Property

The HelpFile property provides the name of the HTML help file (.chm file) for the snap-in to be merged with MMC's integrated help. It is not required.

Syntax

HelpFile As String

Remarks

If HelpFile is set and the path is relative, then the runtime will resolve it to the directory containing the snap-in. This allows easy deployment by simply packaging the .chm file with the snap-in.

If HelpFile is set then MMC will not display a snap-in-specific help item in its Help menu (for example, "Help on Widget Manager"). Snap-ins should implement the ScopeItems_Help and ResultViews_Help events by calling SnapIn. ShowHelpTopic.

If HelpFile is not set the snap-in must implement the SnapIn_Help event and display help information using its own means (e.g. the Win32 WinHelp API).

HelpFile must be set before the user requests help or the snap-in calls ShowHelpTopic.

For more information see "Adding Help to a Snap-in".


Icon Property

The Icon property specifies the icon to be displayed by MMC for About information on the snap-in.

Syntax

Icon As StdPicture

Remarks

The Icon property must contain a StdPicture object that contains an icon. Bitmaps cannot be used for this property.

The icon is displayed by MMC in the following places for standalone snap-ins:

At the top of the dialog displayed when the user clicks the "About" button in the "Add/Remove Snap-in" dialog's "Standalone" page when the snap-in is selected in the page's list view.

The icon is displayed by MMC in the following places for extension snap-ins:

At the top of the dialog displayed when the user clicks the "About" button in the "Add/Remove Snap-in" dialog's "Extensions" page when the snap-in is selected in the page's list view.
Note that the Icon property is not used in the following places:
In the list view in the "Add Standalone Snap-in" dialog
In the list view in the "Add/Remove Snap-in" dialog's "Standlone" and "Extensions" pages.
In the scope pane
In the result pane

Those images are displayed from the SmallFolders, SmallFoldersOpen, and LargeFolders image lists using the image referenced by the StaticFolder property.


Initialize Event

The Initialize event is fired when the snap-in is created.

Syntax

Private Sub SnapIn_Initialize()

Remarks

The Initialize event is a standard Visual Basic event for all classes. It should be used for variable initialization and similar startup housekeeping. The snap-in might be created only for About box information, so any initialization needed for a running snap-in should be done in the Load event.

Note that when adding a snap-in to a console it will be created at least twice: once for display


LargeFolders Property

The LargeFolders property specifies the image list for large folder images for scope items in the result pane.

Syntax

LargeFolders As MMCImageList

Remarks

LargeFolders must have the same number of images as SmallFolders and SmallFoldersOpen. If the snap-in is using list views and there will be scope items in the list views, then the image list specified by ResultView.ListView.Icons must contain the same folder images at the same indexes as SnapIn.LargeFolders. Images for list items should be placed elsewhere in that image list.

For more information see "Coordinating Image Lists".


Load Event

The Load event is sent when the snap-in is loaded into the console.

Syntax

Private Sub SnapIn_Load()

Remarks

The Load event is fired only for primary snap-ins. Following this event the snap-in has access to MMC services such as the ConsoleMsgBox method. For standalone snap-ins, this event is fired when the snap-in is added to a console as well as when a console file is loaded that contains the snap-in. For namespace extensions, it is fired when the extension is loaded.

A snap-in that receives the SnapIn_Load event will also receive the SnapIn_Unload event when the snap-in is being removed from the console.


MMCCommandLine Property

The MMCCommandLine property contains the command line used to start MMC.EXE.

Syntax

MMCCommandLine As String

Remarks

Snap-ins may use the MMC command line information to customize the use of a saved console file. When running under the Visual Basic debugger this property is not available in primary snap-ins prior to the SnapIn_Load event and it is not available at all in non-namespace extensions.


Name Property

The Name property specifies the name used to identify the snap-in within the code. Read-only at runtime.

Syntax

Name As String

Remarks

Built on Wednesday, October 27, 1999


NodeTypeGUID Property

The NodeTypeGUID property specifies the GUID used to identify the static node type in the registration database. It is generated by the designer. Read-only.

Syntax

NodeTypeGUID As String

Remarks

The NodeTypeGUID property for the static node can also be referenced using ScopeItems("Static Node").ScopeNode.NodeTypeGUID.


NodeTypeName Property

The NodeTypeName property specifies the name used to identify the static node type in the registration database. It defaults to the same value as Name unless set by the developer at design time.

Syntax

NodeTypeName As String

Remarks

The NodeTypeName property for the static node can also be referenced using ScopeItems("Static Node").ScopeNode.NodeTypeName.


Preload Property

The Preload property determines whether the snap-in will be loaded immediately upon expansion of its parent node when the console file is next loaded or only when it is needed (e.g. when the static node is expanded).

Syntax

Preload As Boolean

Remarks

When MMC saves a console, primary snap-ins and namespace extensions may have their top-level nodes added to the scope pane without loading the snap-in. MMC defers loading the snap-in until the user expands the node. If the snap-in's static node (or top level node for a namespace extension) has a dynamic display name then the snap-in should set Preload to True when it is added to a console. When the console file is later reloaded the snap-in will be loaded as soon as its parent node is expanded and it will receive the SnapIn_Preload event.

For example, consider a standalone snap-in added under the "Console Root" node that uses the local machine name in its static node's display name. The user selects the console root and saves the console. The next time the console file is loaded, MMC will select "Console Root" and show the snap-in's static node, but the snap-in will not be loaded until the user expands the static node or selects it in the scope pane. If the machine name was changed and the console file reloaded, then the snap-in would not want MMC to display the old name that it stored in the .msc file. The snap-in should set Preload to True and then set DisplayName in the SnapIn_Preload event every time the .msc file is loaded.


Preload Event

The Preload event is sent when the snap-in's parent node is expanded after a console file is loaded if it set Preload to True before the console was saved.

Syntax

Private Sub SnapIn_Preoad()

Remarks

For more information see "Preload Property".


Provider Property

The Provider property specifies the provider's name for the snap-in. It is generally set to the name of the company or organization that created the snap-in.

Syntax

Provider As String

Remarks

The string contained in the Provider property is displayed by MMC in the following places for standalone snap-ins:

In the "Vendor" column of the list view in the "Add Standalone Snap-in" dialog.

On the second line of the dialog displayed when the user clicks the "About" button in the "Add/Remove Snap-in" dialog's "Standalone" page when the snap-in is selected in the page's list view.

The string contained in the Provider property is displayed by MMC in the following places for extension snap-ins:

On the second line of the dialog displayed when the user clicks the "About" button in the "Add/Remove Snap-in" dialog's "Extensions" page when the snap-in is selected in the page's list view.


QueryConfigurationWizard Event

The QueryConfigurationWizard event asks the snap-in whether it has a configuration wizard. This event is fired when the user is adding the snap-in to a console using the snap-in manager.

Syntax

Private Sub SnapIn_QueryConfigurationWizard(HaveWizard As Boolean)

Remarks

If the snap-in returns True in HaveWizard then it will receive a subsequent CreateConfigurationWizard event.


ReadProperties Event

The ReadProperties event loads any global snap-in state from the .msc file saved in the WriteProperties event.

Syntax

Private Sub SnapIn_ReadProperties(PropertyBag As PropertyBag)

The ReadProperties event syntax has these parts:

Part | Description
PropertyBag | PropertyBag object containing the properties saved by the snap-in in its SnapIn_WriteProperties event when the console file was saved.

Remarks

If the snap-in saved state in the SnapIn_WriteProperties event when the console file was saved, then it should handle this event to load its state. Snap-ins can save and load global state using SnapIn_WriteProperties and SnapIn_ReadProperties. Snap-ins can also save and load view-specific state using Views_WriteProperties and Views_ReadProperties.


RequiredExtensions Property

Collection of Extension objects representing the set of registered extensions for the snap-in. Set Extension.Enabled in SnapIn_Initialize to require that the extension be created when your snap-in loads. Runtime only. Primary snap-ins only.

Syntax

RequiredExtensions As Extensions

Remarks

The Extension object has properties containing the CLSID, node type name, and extension types as well as an Enabled property. The RequiredExtensions collection has an EnableAll method that allows the snap-in to specify that all registered extensions should be created when the snap-in is created.


RuntimeMode Property

The RuntimeMode property is an enumeration that allows a dual-mode snap-in to determine whether it was created as a primary or an extension snap-in. Read-only. Runtime only.

Syntax

RuntimeMode As SnapInRuntimeModeConstants

Settings

The settings for RuntimeMode are:

Constant | Description
siRTExtension | The snap-in was created as an extension.
siRTPrimary | The snap-in was created as a primary snap-in.
siRTSnapInAbout | The snap-in was created for About box information only.
siUnknown | MMC has not yet indicated why the snap-in was created.

Remarks

Built on Wednesday, October 27, 1999


ScopeItems Property

The ScopeItems property is a collection of all the ScopeItem objects belonging to the snap-in. Read-only.

Syntax

ScopeItems As ScopeItems

Remarks

There is only a single ScopeItems collection in a snap-in. The collection contains one and only one element for every node created by the snap-in regardless of how many views the user opens.


ShowHelpTopic Method

The ShowHelpTopic method displays the specified HTML help topic in the merged MMC HTML help file. HelpFile must be set before this method is called.

Syntax

ShowHelpTopic(Topic As String)

The ShowHelpTopic method syntax has these parts:

Part | Description
Topic | String identifying the topic to display in the HTML help file. This string must be in the format expected by the Win32 HTMLHelp API.

Remarks

Built on Wednesday, October 27, 1999


SmallFolders Property

The SmallFolders property specifies the image list for small folder images in the scope pane and scope items in the result pane.

Syntax

SmallFolders As MMCImageList

Remarks

SmallFolders must have the same number of images as SmallFoldersOpen and LargeFolders. If the snap-in is using list views and there will be scope items in the list views, then the image list specified by ResultView.ListView.SmallIcons must contain the same folder images at the same indexes as SnapIn.SmallFolders. Images for list items should be placed elsewhere in that image list.

For more information see "Coordinating Image Lists".


SmallFoldersOpen Property

The SmallFoldersOpen property specifies the image list for small open folder images in the scope pane.

Syntax

SmallFoldersOpen As MMCImageList

Remarks

SmallFoldersOpen must have the same number of images as SmallFolders and LargeFolders.

For more information see "Coordinating Image Lists".


StaticFolder Property

The StaticFolder property specifies the position in image lists of the image used for the static node in the scope pane and result pane. It can be an integer index or a key.

Syntax

StaticFolder As Variant

Remarks

The StaticFolder property is used to reference the image for the static node in the image lists specified by SmallFolders, SmallFoldersOpen, and LargeFolders.

The image referenced by StaticFolder is used in the following places:

In the list view in the "Add Standalone Snap-in" dialog
In the list view in the "Add/Remove Snap-in" dialog's "Standlone" and "Extensions" pages.
In the scope pane
In the result pane


TaskpadViewPreferred Property

The TaskpadViewPreferred property is True if the user has selected the "Show Taskpad Views By Default" option in the MMC Options dialog box. Read-only. Runtime only.

Syntax

TaskpadViewPreferred As Boolean

Remarks

This property is only available in MMC 1.1.


Terminate Event

The Terminate event is fired when the snap-in is destroyed.

Syntax

Private Sub SnapIn_Terminate()

Remarks

The Terminate event is a standard Visual Basic event for all classes. It should be used for cleanup of any initialization done during the SnapIn_Initialize event.


Trace Method

The Trace method calls the Win32 API function OutputDebugString with the specified message. When debugging a snap-in using Visual C++, this string is displayed in the output window.

Syntax

Trace(Message As String)

The Trace method syntax has these parts:

Part | Description
Message | Text to pass to the Win32 OutputDebugString API.

Remarks

Snap-ins debugged in the Visual Basic IDE do not need to use this method. If you are debugging a snap-in that calls into some C++ code and you are using the Visual C++ debugger, this method can be helpful for writing checkpoint messages to the Visual C++ output window.


Type Property

The Type property is an enumeration of available snap-in types (stand-alone, extension, dual-mode).

Syntax

Type As SnapInTypeConstants

Settings

The settings for Type are:

Constant | Description
siDualMode | Dual-mode snap-in. The snap-in can run stand-alone or as an extension.
siExtension | Extension snap-in. The snap-in can only run as an extension of another snap-in.
siStandAlone | Stand-alone snap-in. The snap-in does not extend node types of any other snap-in.

Remarks

The Type property is set at design time and is read-only at runtime.


Unload Event

The Unload event informs the snap-in that is being unloaded from the console and that it should perform cleanup.

Syntax

Private Sub SnapIn_Unload()

Remarks

A snap-in that received the SnapIn_Load event will always receive the SnapIn_Unload event. Only primary snap-ins will receive these events.


Version Property

The Version property provides a version string the snap-in.

Syntax

Version As String

Remarks

The version string can contain anything deemed appropriate by the snap-in developer. It is not examined by MMC and is only used for display purposes. Snap-ins typically set the string to a version number e.g. "1.0" as MMC prefixes its display of this string with "Version:".

The string contained in the Version property is displayed by MMC in the following places for standalone snap-ins:

At the bottom of the dialog displayed when the user clicks the "About" button in the "Add/Remove Snap-in" dialog's "Standalone" page when the snap-in is selected in the page's list view.

The string contained in the Provider property is displayed by MMC in the following places for extension snap-ins:

At the bottom of the dialog displayed when the user clicks the "About" button in the "Add/Remove Snap-in" dialog's "Extensions" page when the snap-in is selected in the page's list view.


Views Property

The Views property is a collection of all the View objects belonging to the snap-in. Read-only.

Syntax

Views As Views

Remarks

The snap-in does not explicitly add or remove elements from the Views collection. As the user opens and closes views, the designer runtime populates the collection accordingly. The snap-in is informed of the creating of a new view by the Views_Initialize event. When the view is destroyed the snap-in receives the Views_Terminate event. For more information see "Views."


WriteProperties Event

The WriteProperties event allows the snap-in to save any global state when the snap-in is part of a saved console file (.msc).

Syntax

WriteProperties(PropertyBag As PropertyBag)

The WriteProperties event syntax has these parts:

Part | Description
PropertyBag | PropertyBag object in which the snap-in can save its state by calling PropertyBag.WriteProperty.

Remarks

If the snap-in saves state in the SnapIn_WriteProperties event when the console file is saved, then it will receive the SnapIn_ReadProperties event to load its state when the console file is loaded. Snap-ins can save and load global state using SnapIn_WriteProperties and SnapIn_ReadProperties. Snap-ins can also save and load view-specific state using Views_WriteProperties and Views_ReadProperties.


ExtensionSnapIn

The ExtensionSnapIn object encapsulates the set of events that apply to snap-ins that extend other snap-ins in ways such as adding menu items, property pages, toolbars, tasks, and extending their namespace. It has no properties or methods. For more information on writing extensions see "Developing Extension and Dual-Mode Snap-ins."

AddNewMenuItems and AddTaskMenuItems are called for context menu extensions when MMC is about to display a context menu for a node type extended by the snap-in. An extension snap-in can only add items to the New and All Tasks submenus. When the user selects an item added by a context menu extension the MMCMenu object's Click event is fired just as for a primary snap-in's context menus.

AddTasks is called for taskpad extensions when MMC is displaying a taskpad for the node type extended by the snap-in. The snap-in uses a Tasks collection to add its tasks. When the user clicks a task added by an extension, the snap-in receives the TaskClick event.

CreatePropertyPages is called for property page extensions when MMC is creating a property sheet for the node type extended by the snap-in. The snap-in uses the event to add its pages to the sheet as it would for a primary snap-in. Note that unlike a primary snap-in, an extension does not receive a QueryPagesFor event. MMC does not need this information because it is the primary snap-in's QueryPagesFor event that determines whether the user can invoke properties on the node. If the extension does not have property pages then it can simply return without adding anything.

SetControlbar is called for toolbar extensions to allow them to add their toolbars and menu buttons to MMC. UpdateControlbar is called when the selection changes so that the extension can enable and disable its buttons based on the selected item(s). Toolbar and menu button events are handled on the Toolbar object as they are in a primary snap-in.

Expand is called for a namespace extension when the node type it extends is expanding. ExpandSync is called in the same situation when a console file is loading to indicate that MMC would like the snap-in to add its child nodes immediately. If the snap-in cannot complete its namespace population synchronously then it can return Handled=False. It will then receive an Expand event in which it can initiate asynchronous scope tree population.

Collapse and CollapseSync are the counterparts to the expand events. They are not currently supported by MMC but may be in future versions.

Events

These events will appear in the Visual Basic code as ExtensionSnapIn_<EventName>.

AddNewMenuItems | Allows a context menu extension to add items to the "New" submenu.
AddTaskMenuItems | Allows a context menu extension to add items to the "All Tasks" submenu.
AddTasks | Allows a taskpad extension to add tasks to the primary snap-in's taskpad.
Collapse | Not called in current versions of MMC
CollapseSync | Not called in current versions of MMC
CreatePropertyPages | Allows a property page extension to add its pages to the primary snap-in's property sheet.
Expand | Allows a namespace extension to add child nodes to instances of the node types it extends
ExpandSync | Allows a namespace extension to add child nodes to instances of the node types it extends when MMC requests synchronous scope pane population.
SetControlbar | Allows a toolbar extension to add its toolbars and menu buttons to MMC's controlbar.
TaskClick | Called when the user clicks a task added by a taskpad extension.
UpdateControlbar | Allows a toolbar extension to update the state of its toolbar and menu buttons.


AddNewMenuItems Event

The AddNewMenuItems event informs the snap-in that it has the opportunity to add items to the "New" submenu of the console's context menu for the object(s) represented by the MMCDataObject collection. Items will be added to the bottom of the "New" submenu.

Syntax

Private Sub ExtensionSnapIn_AddNewMenuItems(DataObjects As MMCDataObjects, ContextMenu As ContextMenu)

The AddNewMenuItems event syntax has these parts:

Part | Description
DataObjects | A collection of MMCDataObject objects. There is one element in the collection for every snap-in that owns objects in the selected items.
ContextMenu | A ContextMenu object that can be used by the snap-in to add its menu items.

Remarks

The snap-in should examine the MMCDataObject collection to determine whether it needs to add context menu items. This collection will typically contain one MMCDataObject. If the selection is in the result pane of a list view that supports multiple-selection the collection could contain more than one MMCDataObject. This could happen if the selection includes child scope items of namespace extensions as well as list items and child scope items of the scope item selected in the scope pane.

To add context menu items, the snap-in should call ContextMenu.AddMenu. The snap-in cannot store the ContextMenu object for use outside of this event. For more information see "ContextMenu."


AddTaskMenuItems Event

The AddTaskMenuItems event informs the snap-in that it has the opportunity to add items to the "Task" submenu of the console's context menu for the object(s) represented by the MMCDataObject collection. Items will be added to the bottom of the "Task" submenu.

Syntax

Private Sub ExtensionSnapIn_AddTaskMenuItems(DataObjects As MMCDataObjects, ContextMenu As ContextMenu)

The AddTaskMenuItems event syntax has these parts:

Part | Description
DataObjects | A collection of MMCDataObject objects. There is one element in the collection for every snap-in that owns objects in the selected items.
ContextMenu | A ContextMenu object that can be used by the snap-in to add its menu items.

Remarks

The snap-in should examine the MMCDataObject collection to determine whether it needs to add context menu items. This collection will typically contain one MMCDataObject. If the selection is in the result pane of a list view that supports multiple-selection the collection could contain more than one MMCDataObject. This could happen if the selection includes child scope items of namespace extensions as well as list items and child scope items of the scope item selected in the scope pane.

To add context menu items, the snap-in should call ContextMenu.AddMenu. The snap-in cannot store the ContextMenu object for use outside of this event. For more information see "ContextMenu."


AddTasks Event

The AddTasks event allows the snap-in to add tasks to the primary snap-in's taskpad for the node represented by the MMCDataObject.

Syntax

Private Sub ExtensionSnapIn_AddTasks(DataObject As MMCDataObject, GroupName As String, Tasks As Tasks)

The AddTasks event syntax has these parts:

Part | Description
DataObject | An MMCDataObject object representing the data exported by the primary snap-in's node that is displaying the taskpad.
GroupName | The group name exported by the primary snap-in. If the primary snap-in is written in Visual Basic then this is the name assigned to the taskpad at design time.
Tasks | A collection of Task objects. The snap-in adds an object to this collection for every task that is to be added to the taskpad.

Remarks

Upon entry to this event the tasks collection is empty because an extension does not have access to the other tasks in a taskpad. The snap-in should add its tasks by calling Tasks.Add. If the user clicks a task added by the snap-in then the ExtensionSnapIn_TaskClick event will be fired.


Collapse Event

This event is not fired in current versions of MMC. In future it may be fired when the user collapses a node that is an instance of a node type extended by the snap-in.

Syntax

Private Sub ExtensionSnapIn_Collapse(Data As MMCDataObject, ScopeNode As ScopeNode)

The Collapse event syntax has these parts:

Part | Description
Data | An MMCDataObject object representing the data exported by the node being collapsed.
ScopeNode | A ScopeNode object representing the node being collapsed.

Remarks

Built on Wednesday, October 27, 1999


CollapseSync Event

This event is not fired in current versions of MMC. In future it may be fired when the user collapses a node that is an instance of a node type extended by the snap-in when MMC requires that the snap-in complete its event handling synchronously.

Syntax

Private Sub ExtensionSnapIn_CollapseSync(Data As MMCDataObject, ScopeNode As ScopeNode, Handled As Boolean)

The Collapse event syntax has these parts:

Part | Description
Data | An MMCDataObject object representing the data exported by the node being collapsed.
ScopeNode | A ScopeNode object representing the node being collapsed.
Handled | Set Handled to True if the snap-in can handle this event synchronously.

Remarks

Built on Wednesday, October 27, 1999


CreatePropertyPages Event

The CreatePropertyPages event informs the snap-in to create its property pages for the object represented by the MMCDataObject.

Syntax

Private Sub ExtensionSnapIn_CreatePropertyPages(DataObject As MMCDataObject, PropertySheet As MMCPropertySheet)

The CreatePropertyPages event syntax has these parts:

Part | Description
DataObject | MMCDataObject representing the object(s) for which the property sheet is being displayed.
PropertySheet | MMCPropertySheet object that the snap-in should use to add its pages to the property sheet.

Remarks

MMCPropertySheet::AddPage allows adding pages to the property sheet during this call. Note that the MMCPropertySheet object is only valid during this call and should not be stored by the snap-in.


Expand Event

The Expand event informs the snap-in that the specified scope node has been expanded in the namespace. The snap-in can add child nodes to the expanding node during this event.

Syntax

Private Sub ExtensionSnapIn_Expand(Data As MMCDataObject, ScopeNode As ScopeNode)

The Expand event syntax has these parts:

Part | Description
Data | An MMCDataObject representing the data exported by the expanding node.
ScopeNode | A ScopeNode object representing the expanding node.

Remarks

If the snap-in extends more than one node type, it should examine ScopeNode.NodeTypeGUID to determine which node type is expanding.

To add a child node, call ScopeItems.AddPredefined or ScopeItems.Add and pass ScopeNode as the ScopeNodeRelative parameter.

If the snap-in cannot add its child nodes during this event it can store a reference to ScopeNode. For example, if the snap-in needs to retrieve some data asynchronously before adding its child nodes it can call ScopeItems.AddPredefined or ScopeItems.Add when the data arrives.


ExpandSync Event

The Expand event informs the snap-in that the specified scope node has been expanded in the namespace. The snap-in can add child nodes to the expanding node during this event if it can do so synchronously during the event.

Syntax

Private Sub ExtensionSnapIn_Expand(Data As MMCDataObject, ScopeNode As ScopeNode, Handled As Boolean)

The Expand event syntax has these parts:

Part | Description
Data | An MMCDataObject representing the data exported by the expanding node.
ScopeNode | A ScopeNode object representing the expanding node.
Handled | Set Handled to True if the snap-in can handle this event synchronously.

Remarks

This event is fired instead of ExtensionSnapIn_Expand when MMC needs to expand the scope tree quickly (e.g. when loading a console file and restoring the selection). If the snap-in cannot add its child nodes during this event then it should set Handled to False and it will receive an ExtensionSnapIn_Expand event.

If the snap-in extends more than one node type, it should examine ScopeNode.NodeTypeGUID to determine which node type is expanding.

To add a child node, call ScopeItems.AddPredefined or ScopeItems.Add and pass ScopeNode as the ScopeNodeRelative parameter.


SetControlbar Event

The SetControlbar event allows the snap-in to create controls and attach them to the console's controlbar.

Syntax

Private Sub ExtensionSnapIn_SetControlbar(ControlBar As MMCControlBar)

The SetControlbar event syntax has these parts:

Part | Description
ControlBar | MMCControlbar object that the snap-in can use to attach its controls to MMC's controlbar.

Remarks

The snap-in can add its toolbars and menu buttons by calling MMCControlbar.Attach.

The MMCControlbar object can only be used during this event handler and the snap-in should not store a reference to it.


TaskClick Event

The TaskClick event informs the snap-in that a task it added to the taskpad for the node represented by MMCDataObject was clicked.

Syntax

Private Sub ExtensionSnapIn_TaskClick(DataObject As MMCDataObject, Task As Task)

The TaskClick event syntax has these parts:

Part | Description
DataObject | An MMCDataObject object representing the data exported by the primary snap-in's node that is displaying the taskpad.
Task | A Task object representing the task that was clicked.

Remarks

The Task object is the same one added by the snap-in in its ExtensionSnapIn_AddTasks event handler.


UpdateControlbar Event

The UpdateControlbar event allows the snap-in to change the state of toolbar and menu buttons added in the ExtensionSnapIn_SetControlbar event.

Syntax

Private Sub ExtensionSnapIn_UpdateControlbar(SelectionInScopePane As Boolean, Selected As Boolean, DataObjects As MMCDataObjects, ControlBar As MMCControlBar)

The SetControlbar event syntax has these parts:

Part | Description
SelectionInScopePane | True if the user selected a node in the scope pane. False if the user selected item(s) in the result pane.
Selected | True is the user selected item(s). False if the user's action caused previously selected item(s) to be deselected.
DataObjects | A collection of MMCDataObject objects. There is one element in the collection for every snap-in that owns objects in the selected item(s).
ControlBar | MMCControlbar object that the snap-in can use to attach its controls to MMC's controlbar.

Remarks

The snap-in should examine the MMCDataObject collection to determine whether it needs to update its toolbar and menu buttons. This collection will typically contain one MMCDataObject. If the selection is in the result pane of a list view that supports multiple-selection the collection could contain more than one MMCDataObject. This could happen if the selection includes child scope items of namespace extensions as well as list items and child scope items of the scope item selected in the scope pane.

The snap-in can update the state of its toolbar and menu buttons by using MMCButton and MMCButtonMenu properties.

The MMCControlbar object can only be used during this event handler and the snap-in should not store a reference to it.


ScopeItems

The ScopeItems collection represents the collection of all nodes added to the namespace by the snap-in. (This includes the snap-in's own namespace and that of any snap-ins it extends.) ScopeItem represents a single scope item. Its properties represent the aspects of a scope item that are independent of the view in which it appears. Nodes defined at design time can optionally be created by the designer runtime. These are known as "auto-create" nodes and they simply appear in the ScopeItems collection as their parent nodes are expanded. To create dynamic nodes at run time the snap-in adds an item to the collection. To remove an item from the namespace its ScopeItem is removed from the collection. All scope item events are on the collection. ScopeItem does not have any events. Each event has a parameter that is the ScopeItem object for which the event applies.

The ScopeItems collection also includes an element for the static node in primary snap-ins. It can be referenced using the special key "Static Node" e.g. ScopeItems("Static Node").

The AddPredefined method adds a node to the scope pane using a design-time definition from the Nodes section of the designer's tree view. The Add method is used to add a node to the scope pane using run-time definitions only.

The Initialize event is fired when a scope item is created. This is particularly useful for auto-create nodes because this event informs the snap-in that the node was created.

The Terminate event is fired when a scope item is destroyed. When MMC is closed all scope items are destroyed. This event gives the snap-in a chance to do any associated cleanup.

The Expand event is fired when a node is expanded in the scope pane. Snap-ins use this event to add children to the expanding node. The ExpandSync event is called in the same situation when a console file is loading to indicate that MMC would like the snap-in to add its child nodes immediately. If the snap-in cannot complete its namespace population synchronously then it can return Handled=False. It will then receive an Expand event in which it can initiate asynchronous scope tree population.

Collapse and CollapseSync are the counterparts to the expand events. They are not currently supported by MMC but may be in future versions.

The Rename event is called when the user requests to rename a scope item. It can only be called if the snap-in has enabled the rename verb during the previous Views_Select event when the scope item was selected. See "Views" object for more information.

The PropertyChanged event is called when one of the snap-in's property pages calls ScopeItem.PropertyChanged. Snap-ins use this mechanism so that a property page (which MMC runs in a separate thread) can inform the snap-in of changes made to the scope item.

The Help event is called when the user requests Help while the scope item is selected. This event is only used if the snap-in is using a merged HTML Help file. See "Adding Help to a Snap-in" for more information.

When a primary snap-in is removed from the console all of its children are removed and the snap-in receives the RemoveChildren event. When the parent of a namespace extension's root node is removed then it will also receive this event.

Syntax

ScopeItems As ScopeItems

Properties

Count | Returns a count of the ScopeItem objects in the collection
Item | Returns a ScopeItem object in the collection referenced by key, index, or ScopeNode.

Methods

Add | Adds a ScopeItem to the collection and a corresponding node to the scope pane.
AddPreDefined | Adds a ScopeItem to the collection and a corresponding node to the scope pane based on a design time definition.
Remove | Removes a ScopeItem from the collection and its corresponding node from the scope pane.

Events

These events will appear in the Visual Basic code as ScopeItems_<EventName> because ScopeItems is the property of the SnapIn object that holds the one and only ScopeItems collection.

Collapse | Not called in current versions of MMC
CollapseSync | Not called in current versions of MMC
Expand | Allows the snap-in to add child nodes to the expanding node.
ExpandSync | Allows the snap-in to add child nodes to the expanding node when MMC requests synchronous scope pane population.
Help | Called when the user requests help for a ScopeItem.
Initialize | Called when a ScopeItem is created.
PropertyChanged | Called when a property page calls ScopeItem.PropertyChanged.
RemoveChildren | Called when MMC is about to remove the children of a ScopeItem.
Rename | Called when the user performs a rename operation on a ScopeItem.
Terminate | Called when a ScopeItem is about to be destroyed.


Add Method

The Add method adds a ScopeItem to the collection. This implicitly adds the a node to the console namespace. The name is used as the key for the scope item in the collection.

Syntax

ScopeItems.Add(Key As String, ScopeNodeRelative As ScopeNode, RelativeRelationship As SnapInNodeRelationshipConstants, [HasChildren]) As ScopeItem

The Add method syntax has these parts:

Part | Description
Key | A unique identifying string for the new ScopeItem that will be assigned to ScopeItem.Key. This value will be used to reference the new ScopeItem in the collection.
ScopeNodeRelative | A ScopeNode object representing an existing node in the scope pane. The new node is added in a position relative to this node.
RelativeRelationship | Enumerated value that determines the position of the new node relative to ScopeNodeRelative
HasChildren | Optional. If True then a '+' sign is displayed next to the new node in the scope pane. If not present the defaults to True.

Remarks

This method can be used in both standalone snap-ins and in namespace extensions.

Although the runtime chooses default values for all of the scope item's properties the snap-in should set the scope item's properties immediately after calling this method. In particular, the snap-in should set ScopeItem.ScopeNode.DisplayName, ScopeItem.Folder, ScopeItem.ScopeNode.NodeTypeGUID, and ScopeItem.ScopeNode.NodeTypeName.

ScopeItem.ScopeNode.DisplayName contains the string displayed next to the node.

If the snap-in does not set ScopeItem.ScopeNode.NodeTypeGUID, and ScopeItem.ScopeNode.NodeTypeName then MMC will not be able to persist the selection of the node or a console taskpad for the node when the user saves the console to an .msc file.

Note that a ScopeItem added with this method does not have a default result view. If the ScopeItem is selected in the scope pane then the snap-in must handle the ScopePaneItems_GetResultViewInfo event to determine the result view that will be displayed.

Snap-ins should rarely need to use this method. It is recommended that nodes be defined at design time and that the snap-in use the AddPreDefined method instead. The only time this method might be useful is when the snap-in needs to define a large number of nodes at runtime that have no properties known at design time and no default result view.

This method cannot be called from the ScopeItems_Initialize event using the newly created ScopeItem object as the parent. The snap-in must wait for the ScopeItems_Expand event. To programmatically expand a scope item in the namespace before the user has done so, call ScopeItem.ScopeNode.ExpandInNameSpace. This must be done after the ScopeItems_Initialize event completes.


AddPreDefined Method

The AddPreDefined method adds a ScopeItem defined at design time to the collection. This implicitly adds the item to the console namespace. The node name specified at design time is used as the node type name. This allows the design time definition to function as a template for scope items added at run time.

Syntax

ScopeItems.AddPreDefined(NodeTypeName As String, Key As String, ScopeNodeRelative As ScopeNode, RelativeRelationship As SnapInNodeRelationshipConstants, [HasChildren]) As ScopeItem

The AddPreDefined method syntax has these parts:

Part | Description
NodeTypeName | The name of the node assigned at design time.
Key | A unique identifying string for the new ScopeItem that will be assigned to ScopeItem.Key. This value will be used to reference the new ScopeItem in the collection.
ScopeNodeRelative | A ScopeNode object representing an existing node in the scope pane. The new node is added in a position relative to this node.
RelativeRelationship | Enumerated value that determines the position of the new node relative to ScopeNodeRelative
HasChildren | Optional. If True then a '+' sign is displayed next to the new node in the scope pane. If not present the defaults to True.

Remarks

This method can be used in both standalone snap-ins and in namespace extensions.

This method cannot be called from the ScopeItems_Initialize event using the newly created ScopeItem object as the parent. The snap-in must wait for the ScopeItems_Expand event. To programmatically expand a scope item in the namespace before the user has done so, call ScopeItem.ScopeNode.ExpandInNameSpace. This must be done after the ScopeItems_Initialize event completes.


Collapse Event

This event is not fired in current versions of MMC. In future it may be fired when the user collapses a node owned by the snap-in.

Syntax

Private Sub ScopeItems_Collapse(ScopeItem As ScopeItem)

The Collapse event syntax has these parts:

Part | Description
ScopeItem | ScopeItem that was collapsed.

Remarks

Built on Wednesday, October 27, 1999


CollapseSync Event

This event is not fired in current versions of MMC. In future it may be fired when the user collapses a node owned by the snap-in when MMC requires that the snap-in complete its event handling synchronously.

Syntax

Private Sub ScopeItems_CollapseSync(ScopeItem As ScopeItem)

The CollapseSync event syntax has these parts:

Part | Description
ScopeItem | ScopeItem that was collapsed.

Remarks

Built on Wednesday, October 27, 1999


Count Property

The ScopeItems.Count property represents the number of ScopeItems in the collection.

Syntax

Count As Long

Remarks

This number reflects the total number of nodes that have been added by the snap-in. Nodes may be added by calling ScopeItems.Add, ScopeItems.AddPredefined or they may be auto-create nodes added by the designer runtime.


Expand Event

The Expand event informs the snap-in that a node owned by the snap-in has been expanded in the namespace. If the snap-in needs to supply child items of the specified scope item, then they should be added to the scope item collection at this time. This event is fired only once in the lifetime of a scope item.

Syntax

Private Sub ScopeItems_Expand(ScopeItem As ScopeItem)

The Expand event syntax has these parts:

Part | Description
ScopeItem | The ScopeItem object representing the node that is being expanded.

Remarks

A node can be expanded in the namespace under the following circumstances:

The user has selected the node in the scope pane

The user has clicked the '+' sign next to the node in the scope pane

The user has double clicked the node in the result pane

A console file is being loaded and MMC is restoring the selection in the scope pane.

The snap-in has called ScopeItem.ScopeNode.ExpandInNameSpace.

All of the above except 5 will cause the treeview to be expanded in the scope pane as well.

A snap-in can add child nodes to the namespace by calling ScopeItems.Add or ScopeItems.AddPredefined.


ExpandSync Event

The ExpandSync event informs the snap-in that a node owned by the snap-in has been expanded in the namespace. If the snap-in needs to supply child items of the specified scope item, and it can do so synchronously during the event, then they should be added at this time. This event is fired only once in the lifetime of a scope item.

Syntax

Private Sub ScopeItems_ExpandSync(ScopeItem As ScopeItem, , Handled As Boolean)

The Expand event syntax has these parts:

Part | Description
ScopeItem | The ScopeItem object representing the node that is being expanded.
Handled | Set Handled to True if the snap-in can handle this event synchronously.

Remarks

This event is fired instead of ScopeItems_Expand when MMC needs to expand the scope tree quickly (e.g. when loading a console file and restoring the selection). If the snap-in cannot add its child nodes during this event then it should set Handled to False and it will receive an ScopeItems_Expand event.


Help Event

The Help event informs the snap-in that the user has requested help for the specified scope item.

Syntax

Private Sub ScopeItems_Help(ScopeItem As ScopeItem)

The Help event syntax has these parts:

Part | Description
ScopeItem | ScopeItem object for which the user has requested help.

Remarks

This event is only fired if the snap-in is using merged HTML help by setting SnapIn.Help. The snap-in should call SnapIn.ShowHelpTopic to display help for the scope item. See "Adding Help to a Snap-in" for more information.


Initialize Event

The Initialize event informs the snap-in that the specified scope item is being created.

Syntax

Private Sub ScopeItems_Initialize(ScopeItem As ScopeItem)

The Initialize event syntax has these parts:

Part | Description
ScopeItem | The ScopeItem object that was just created.

Remarks

This event is useful when an auto-create scope item needs some initial property settings. It allows the snap-in to take advantage of the auto-create feature while at the same time customizing the scope item.

The ScopeItems.Add ScopeItems.AddPredefined methods cannot be called from the ScopeItems_Initialize event using the newly created ScopeItem object as the parent. The snap-in must wait for the ScopeItems_Expand event. To programmatically expand a scope item in the namespace before the user has done so, call ScopeItem.ScopeNode.ExpandInNameSpace. This must be done after the ScopeItems_Initialize event completes.


Item Property

The Item property returns a ScopeItem indexed by ordinal integer, by key, or by ScopeNode.

Syntax

ScopeItems.Item(Index) As ScopeItem

or

ScopeItems(Index) As ScopeItem

The Item property syntax has these parts:

Part | Description
Index | Variant containing the ordinal index, key or ScopeNode object of a ScopeItem in the collection.

This is the default property of the ScopeItems collection and it can be used with the following shorthand:

Dim si As ScopeItem
Set si = ScopeItems("SomeKey")

To reference the ScopeItem object for the static node use ScopeItems("Static Node").

Remarks

A ScopeNode object can only be used as in index if its Owned property is True.


PropertyChange Event

Platform SDK: Management Console

PropertyChanged Event

The PropertyChanged event informs the snap-in that a property change has occurred for the specified scope item. This event is fired when the property page calls ScopeItem.PropertyChanged.

Syntax

Private Sub ScopeItems_PropertyChanged(ScopeItem As ScopeItem, Data As SnapInData)

The PropertyChanged event syntax has these parts:

Part | Description
ScopeItem | The ScopeItem object used by the property page to call ScopeItem.PropertyChanged.
Data | The Data parameter passed to ScopeItem.PropertyChanged.

Remarks

The runtime handles the marshaling of the Data parameter between the property page thread and the snap-in thread. The contents of Data are defined by the snap-in. Typically this event handler will examine Data and make corresponding changes to the object represented by the scope item.


Remove Method

The Remove method removes a ScopeItem from the collection refereneced by key. This implicitly removes the corresponding node from the console namespace and from the scope panes of all views showing the node.

Syntax

ScopeItems.Remove(Key As String)

The Remove method syntax has these parts:

Part | Description
Key | Key of ScopeItem to be removed.

Remarks

A snap-in cannot remove the static node. To remove all children of the static node call ScopeItems("Static Node").RemoveChildren.


RemoveChildren Event

The RemoveChildren event informs the snap-in that all children of the specified scope node have been removed from the scope pane.

Syntax

Private Sub ScopeItems_RemoveChildren(ScopeNode As ScopeNode)

The ChildrenRemoved event syntax has these parts:

Part | Description
ScopeNode | ScopeNode object representing the node whose children are being removed.

Remarks

This notification typically occurs for the static node when the snap-in is removed from the console using "Add/Remove Snap-in…". It can also occur for namespace extensions when the parent node of the extension's node has been deleted from the scope pane. The snap-in can use this event handler to clean up any resources associated with the child scope items. Alternatively, the snap-in can handle the ScopeItems_Terminate event for each scope item. The snap-in should not call ScopeItems.Remove for the child scope items. The designer runtime will remove the child scope items after this event handler completes.


Rename Event

The Rename event informs the snap-in that the user has elected to change the specified scope item's display name.

Syntax

Private Sub ScopeItems_Rename(ScopeItem As ScopeItem, NewName As String)

The Rename event syntax has these parts:

Part | Description
ScopeItem | ScopeItem object for which the rename has been requested.
NewName | New name entered by the user.

Remarks

The default behavior of MMC is to disable the rename verb. In order to support renaming scope items the snap-in must explicitly enable the rename verb in the Views_Select event.

MMC does nothing more than fire this event. It is up to the snap-in to determine the validity of the new name, update ScopeItem.ScopeNode.DisplayName and make any needed changes to the underlying data.


Terminate Event

The Terminate event informs the snap-in that the specified scope item is about to be destroyed. The scope item has been removed from the ScopeItems collection before this event is fired and it will be destroyed after this event completes.

Syntax

Private Sub ScopeItems_Terminate(ScopeItem As ScopeItem)

The Terminate event syntax has these parts:

Part | Description
ScopeItem | ScopeItem object that is about to be destroyed.

Remarks

The snap-in can use this event to clean up any resources associated with the scope item. Note that if ScopeItem.Tag contains an object there is no reason to set it to Nothing in the event handler as the designer runtime does this.


ScopeItem

The ScopeItem object represents a node added to the namespace by the snap-in. There is only one instance of a ScopeItem for every node added to the namespace regardless of the number of views in which it appears.

The Name property is identical to the Key and it is used to identify the individual ScopeItem within the ScopeItems collection. If you change either of these properties then you must change the other to match it. For more information see "ScopeItem and ScopeNode: Making sense of Name, Key, NodeTypeName and DisplayName ".

Folder contains the index or key of the image used for the ScopeItem in both the scope pane and list view image lists. Because there is only one Folder property, all image lists must contain the corresponding image at the same index or use the same key. See "Coordinating Image Lists" for more information on how to organize image list elements.

ScopeNode contains an object that encapsulates properties of the node that are available for all nodes regardless of ownership. It is used to navigate the namespace and also holds the scope item's display name. See "ScopeNode" for more information.

ColumnHeaders contains the column definitions that are used when a ScopeItem appears in a list view in the result pane. ListSubItems contains the strings that are displayed in the columns. SubItems contains references to the same text as a string array rather than a collection of MMCListSubItem objects. ColumnHeaders and ListSubItems are used when the ScopeItem's parent is selected in the scope pane and MMC displays its child ScopeItems in the result pane. If the user or the snap-in puts the list view into detail mode then the child scope items typically display some data in the columns. The parent's list view defines the columns. The child ScopeItem must define columns that have keys matching one or more of the parent's list view columns. When the designer runtime receives a request for a column's text from MMC, it uses the parent list view's column key to reference the corresponding column in ScopeItem.ColumnHeaders. It then uses that header's index to reference the MMCListSubItem. The algorithm is as follows. Assume that MMC requests the text for the child ScopeItem's column n:

Key = ParentListView.ColumnHeaders(n).Key
Header = ChildScopeItem.ColumnHeaders(Key)
Text = ChildScopeItem.ListSubItems(Header.Index)

The reason for matching keys rather than simply using the corresponding indexes is to allow a ScopeItem to appear in more than one list view. By using the keys, the snap-in can display only a subset of the ListSubItems objects in a particular list view. For more information on column headers and list subitems see "MMCColumnHeaders" and "MMCListSubItems."

Data contains an MMCDataObject that contains the data exported by the ScopeItem to be used by extension snap-ins that extend its node type. See "MMCDataObject" for more information on how to set data for export. See "Developing Extension and Dual-Mode Snap-ins" for more information on extensions.

For extensible nodes defined at design time the ScopeItem's node type name is the same as its name in the Nodes section of the designer's tree view. The node type GUID is generated by the designer and the node is automatically registered under MMC's NodeTypes key.

DynamicExtensions contains a collection of Extension objects that encapsulate the properties of all dynamic extensions registered for the scope item's node type. A snap-in can load a dynamic extension for namespace or other features by setting Extension.NamespaceEnabled=True or Extension.Enabled=True. For more information on registered extensions see "Extension." This can be done when the scope item is created or in the specific feature event handler (for example, Views_AddNewMenuItems). The first time DynamicExtensions is accessed the designer runtime will read the registration database. If performance is a concern then the snap-in should defer enabling dynamic extensions until the feature event handler.

ScopeItem.SlowRetrieval indicates to MMC whether a ScopeItem can be displayed quickly when a saved console file is reloaded. If this property is True then MMC will not reselect a scope item when the .msc file is reloaded unless it is the target of a console taskpad. The same rule applies for persisting a view if the scope item is at the root of a view (regardless of whether it is selected).

The Pasted property is used in cut-and-paste operations within a single instance of a snap-in. If True it indicates that the item was successfully pasted. See "Implementing Drag/Drop and Cut/Copy/Paste" for more information.

The PropertyChanged method is used from a property page when it changes some aspect of the data represented by the ScopeItem. When the property page calls this method the snap-in receives the ScopeItems_PropertyChanged event.

The RemoveChildren method removes all of the scope item's children from the scope pane.

Syntax

ScopeItem As ScopeItem

Properties

ColumnHeaders | Columns for scope item's display data when scope item is displayed in result pane in report mode.
Data | Data exported by the ScopeItem for extension snap-ins.
DynamicExtensions | Collection of objects representing dynamic extensions registered for the scope item type.
Folder | Position in SnapIn image lists of image used for scope item in scope pane and result pane.
Index | Index of the ScopeItem in the ScopeItems collection.
Key | Key of the ScopeItem in the ScopeItems collection.
ListSubItems | ListSubItem objects for text displayed when scope item is displayed in result pane in report mode.
Name | Name of the ScopeItem. Must always match key.
NodeID | Unique non-localized ID used to identify a scope item so that it can be reselected when a console file is loaded.
Pasted | Set by the snap-in during a paste operation to indicate that the scope item was successfully pasted.
ScopeNode | ScopeNode object associated with this scope item.
SlowRetrieval | Indicates whether the data for the scope item can be retrieved quickly when the console file (.msc) is reloaded.
SubItems | Text displayed when scope item is displayed in result pane in report mode.
Tag | Holds any private snap-in data associated with the ScopeItem.

Methods

PropertyChanged | Called from a property page to inform the snap-in of changes made in the property sheet. Causes ScopeItems_PropertyChanged event to be fired.
RemoveChildren | Deletes all child nodes of the scope item.

Events

This object has no events.


ColumnHeaders Property

ColumnHeaders contains the column definitions that are used when a ScopeItem appears in a list view in the result pane.

Syntax

ScopeItem.ColumnHeaders As MMCColumnHeaders

Remarks

ListSubItems contains the strings that are displayed in the columns. SubItems contains references to the same text as a string array rather than a collection of MMCListSubItem objects. ColumnHeaders and ListSubItems are used when the ScopeItem's parent is selected in the scope pane and MMC displays its child ScopeItems in the result pane. If the user or the snap-in puts the list view into detail mode then the child scope items typically display some data in the columns. The parent's list view defines the columns. The child ScopeItem must define columns that have keys matching one or more of the parent's list view columns. When the designer runtime receives a request for a column's text from MMC, it uses the parent list view's column key to reference the corresponding column in ScopeItem.ColumnHeaders. It then uses that header's index to reference the MMCListSubItem. The algorithm is as follows. Assume that MMC requests the text for the child ScopeItem's column n:

Key = ParentListView.ColumnHeaders(n).Key
Header = ChildScopeItem.ColumnHeaders(Key)
Text = ChildScopeItem.ListSubItems(Header.Index)

The reason for matching keys rather than simply using the corresponding indexes is to allow a ScopeItem to appear in more than one list view. By using the keys, the snap-in can display only a subset of the ListSubItems objects in a particular list view. For more information on column headers and list subitems see "MMCColumnHeaders" and "MMCListSubItems."


Data Property

The Data property is an MMCDataObject that contains data exported by the snap-in for extensions that extend the ScopeItem's node type.

Syntax

ScopeItem.Data As MMCDataObject

Remarks

See "MMCDataObject" for more information on how to set data for export. See "Developing Extension and Dual-Mode Snap-ins" for more information on extensions.

For extensible nodes defined at design time the ScopeItem's node type name is the same as its name in the Nodes section of the designer's tree view. The node type GUID is generated by the designer and the node is automatically registered under MMC's NodeTypes key.

For nodes defined at runtime by calling ScopeItems.Add, the node is extensible if the snap-in developer has added its node type the registration database.


Dynamic Extensions Property

DynamicExtensions contains a collection of Extension objects that encapsulate the properties of all dynamic extensions registered for the scope item's node type.

Syntax

ScopeItem.DynamicExtensions As Extensions

Remarks

A snap-in can load a dynamic extension for namespace or other features by setting Extension.NamespaceEnabled=True or Extension.Enabled=True. For more information on registered extensions see "Extension." This can be done when the scope item is created or in the specific feature event handler (for example, Views_AddNewMenuItems). The first time DynamicExtensions is accessed the designer runtime will read the registration database. If performance is a concern then the snap-in should defer enabling dynamic extensions until the feature event handler.


Folder Property

The Folder property represents the position in the SnapIn image lists of the image used for the scope item in scope pane and in the result pane. It can be an integer index or a key.

Syntax

ScopeItem.Folder As Variant

Remarks

Note that the index must be the same in SnapIn.SmallFolders, SnapIn.SmallFoldersOpen, and SnapIn.LargeFolders. If the scope item can be displayed in a result pane then the index must also be the same in ResultView.ListView.Icons and ResultView.ListView.SmallIcons.

For more information see "Coordinating Image Lists".


Index Property

Ordinal index of the ScopeItem in the ScopeItems collection.

Syntax

ScopeItem.Index As Long

Remarks

A Scopeitem can be referenced in the ScopeItems collection by index, key, or ScopeNode.


Key Property

Key of the ScopeItem in the ScopeItems collection.

Syntax

ScopeItem.Key As String

Remarks

A Scopeitem can be referenced in the ScopeItems collection by index, key, or ScopeNode.


ListSubItems Property

The ListSubItems property is a collection of MMCListSubItem objects. This collection contains the text strings that are displayed when the scope item appears in a list view that is in report mode.

Syntax

ScopeItem.ListSubItems As MMCListSubItems

Remarks

ListSubItems contains the strings that are displayed in the columns. SubItems contains references to the same text as a string array rather than a collection of MMCListSubItem objects. ColumnHeaders and ListSubItems are used when the ScopeItem's parent is selected in the scope pane and MMC displays its child ScopeItems in the result pane. If the user or the snap-in puts the list view into detail mode then the child scope items typically display some data in the columns. The parent's list view defines the columns. The child ScopeItem must define columns that have keys matching one or more of the parent's list view columns. When the designer runtime receives a request for a column's text from MMC, it uses the parent list view's column key to reference the corresponding column in ScopeItem.ColumnHeaders. It then uses that header's index to reference the MMCListSubItem. The algorithm is as follows. Assume that MMC requests the text for the child ScopeItem's column n:

Key = ParentListView.ColumnHeaders(n).Key
Header = ChildScopeItem.ColumnHeaders(Key)
Text = ChildScopeItem.ListSubItems(Header.Index)

The reason for matching keys rather than simply using the corresponding indexes is to allow a ScopeItem to appear in more than one list view. By using the keys, the snap-in can display only a subset of the ListSubItems objects in a particular list view. For more information on column headers and list subitems see "MMCColumnHeaders" and "MMCListSubItems."


Name Property

The Name property represents the name for the node used to identify it in Visual Basic code. Name and Key must always contain the same value.

Syntax

ScopeItem.Name As String

Remarks

The Name property is identical to the Key and it is used to identify the individual ScopeItem within the ScopeItems collection. If you change either of these properties then you must change the other to match it. For more information see "ScopeItem and ScopeNode: Making sense of Name, Key, NodeTypeName and DisplayName ".


NodeID Property

Unique non-localized ID used to identify a scope item.

Syntax

ScopeItem.NodeID As String

Remarks

The NodeID property is used by MMC when it saves the console file (.msc) to record the selected node in the scope pane. When the console file is reloaded, MMC begins expanding from the static node and checks the ID of each node until if reaches the formerly selected node. This property defaults to the value of ScopeItem.ScopeNode.NodeTypeGUID.


Pasted Property

The Pasted property is set in the Views_Paste event to indicate that the scope item was pasted successfully.

Syntax

ScopeItem.Pasted As Boolean

Remarks

Typical processing in the Views_Paste event when the pasted items include scope item(s) is to perform the operation on the underlying data and, if it succeeds, set ScopeItem.Pasted = True. If the operation is a move, and the source and target snap-in are the same, then in the Views_Cut event handler the snap-in checks each ScopeItem.Pasted property to determine which items were pasted.


PropertyChanged Method

The PropertyChanged method is called from a property page to inform the snap-in that the user has made changes to the underlying data represented by the ScopeItem. When this method is called the snap-in receives the ScopeItems_PropertyChanged event.

Syntax

ScopeItem.PropertyChanged(Data)

The PropertyChanged method syntax has these parts:

Part | Description
Data | Variant containing value to pass as the Data parameter to the ScopeItems_PropertyChanged event.

Remarks

If Data contains an object then it will be marshaled to the snap-in thread by the designer runtime. An instance of a Visual Basic class my be passed in Data.


RemoveChildren Method

The RemoveChildren method deletes all child nodes of the ScopeItem.

Syntax

ScopeItem.RemoveChildren()

Remarks

The RemoveChildren method deletes all child nodes owned by the snap-in as well as all child nodes owned by namespace extensions. This is the only way to delete a child node owned by a namespace extension.


ScopeNode Property

The ScopeNode property returns the ScopeNode object associated with the scope item.

Syntax

ScopeItem.ScopeNode As ScopeNode

Remarks

The ScopeNode object contains properties that are common to all nodes regardless of whether they are owned by the snap-in.


SlowRetrieval Property

The SlowRetrieval property indicates to MMC whether the node can be recreated quickly when a console file is loaded.

Syntax

ScopeItem.SlowRetrieval As Boolean

Remarks

ScopeItem.SlowRetrieval indicates to MMC whether a ScopeItem can be displayed quickly when a saved console file is reloaded. If this property is True, then MMC will not reselect a scope item when the .msc file is reloaded unless it is the target of a console taskpad. The same rule applies for persisting a view if the scope item is at the root of a view (regardless of whether it is selected). If SlowRetrieval is True then NodeID must be set to a valid string (non-zero length and unique among all scope items).


SubItems Property

The SubItems property is an indexed text property that can be used as a shorthand for getting/setting ScopeItem.ListSubItems(i).Text. The following statements are equivalent:

ScopeItem.ListSubItems(i).Text = "SomeString"
ScopeItem.SubItems(i) = "SomeString"

Syntax

ScopeItem.SubItems(Index As Integer) As String

Remarks

Built on Wednesday, October 27, 1999


Tag Property

The Tag property represents snap-in-defined data associated with the scope item.

Syntax

ScopeItem.Tag As Variant

Remarks

Tag is typically used to hold an identifier or reference to the underlying data represented by the ScopeItem. For example, a ScopeItem that represents a file might put the file's path in Tag. For more complex data Tag can hold a reference to an instance of a Visual Basic class or any other object that can be marshaled across threads. Marshaling is used when a property sheet is displayed for the ScopeItem because MMC displays property sheets in a separate thread.


ScopeNode

The ScopeNode object represents a node in the console namespace. It contains the properties that are available for all nodes regardless of ownership. ScopeItem has a property that returns its associated ScopeNode. When navigating the namespace snap-ins move between ScopeNode objects.

The Owned property indicates whether a ScopeNode is owned by the snap-in. For an owned scope node, its ScopeItem can be retrieved by using the ScopeNode object as an index into the ScopeItems collection.

Navigation in the scope pane is done using the Parent, Child, FirstSibling, Next, and LastSibling properties. Each of these returns a ScopeNode for the adjacent node.

HasChildren can be set to to tell MMC whether the node will have any children added to it when it is expanded. If HasChildren=False then a plus (+) sign is not displayed to the left of the node in the scope pane. Getting HasChildren indicates whether the node currently has any child nodes. When a node is added programmatically using ScopeItems.AddPredefined or ScopeItems.Add an optional parameter can be used to specify whether the node will have children. HasChildren can also be set for a node at design time using the property browser.

ExpandedOnce indicates whether the node has ever been expanded.

DisplayName contains the text displayed for the scope item in the scope pane and in the result pane when it is not in detail mode.

For extensible nodes defined at design time the ScopeItem's node type name is the same as its name in the Nodes section of the designer's tree view. The node type GUID is generated by the designer and the node is automatically registered under MMC's NodeTypes key. For nodes defined in code at run time the snap-in developer must manually register the node type. The developer must also choose a node type GUID in this case and set NodeTypeName and NodeTypeGUID.

The ExpandInTreeView and CollapseInTreeView methods expand and collapse the node in the scope pane. These are UI operations only and will have no effect if the node has not been expanded in the namespace.

ExpandInNameSpace programmatically initiates the expansion of the node and will generate a ScopeItems_Expand event. It has no effect on the UI.

The NewWindow method allows a snap-in to create a new view. There are numerous options to determine the appearance of the view (for example, no toolbars, no scope pane, and so on) and the snap-in can determine its title bar text.

Syntax

ScopeNode As ScopeNode

Properties

Child | Returns the ScopeNode that is the first child of the node.
DisplayName | The name displayed in the console for the node.
ExpandedOnce | Indicates whether the scope node has been expanded at least once.
FirstSibling | Returns the ScopeNode that is the first sibling of the node.
HasChildren | Setting this property determines whether a plus sign is displayed next to the node in the MMC treeview. Getting this property returns a value indicating whether the node currently has any children.
LastSibling | Returns the ScopeNode that is the last sibling of the node.
Next | Returns the ScopeNode that is the next sibling of the node.
NodeTypeGUID | GUID used to identify the type of node.
NodeTypeName | Name used to identify the type of node.
Owned | Indicates whether the node was created by the snap-in.
Parent | Returns the ScopeNode that is the parent of the node.

Methods

ExpandInNameSpace Expands the node in the namespace (but not in the treeview).

Events

This object has no events.


Child Property

The Child property returns the ScopeNode that is the first child of this node. Read-only.

Syntax

ScopeNode.Child As ScopeNode

Remarks

Built on Wednesday, October 27, 1999


DisplayName Property

The DisplayName property holds the string displayed in the console for the scope item. Read/write for owned scope nodes; read-only for non-owned nodes.

Syntax

ScopeNode.DisplayName As String

Remarks

Built on Wednesday, October 27, 1999


ExpandedOnce Property

The ExpandedOnce property indicates whether the scope item has ever been expanded. Read-only.

Syntax

ScopeNode.ExpandedOnce As Boolean

Remarks

Built on Wednesday, October 27, 1999


ExpandInNameSpace Method

The ExpandInNameSpace method expands the scope node in the namespace for the purpose of enumeration. It does not expand the node in the tree view. For nodes owned by the snap-in ScopeItems_Expand will be fired.

Syntax

ScopeNode.ExpandInNameSpace()

Remarks

This method is useful if the snap-in must add child nodes to a node before the user has expanded it in the scope pane. It is also typically used when implementing the refresh verb in Views_Refresh.after deleting a scope item and re-adding it.


FirstSibling Property

The FirstSibling property returns the ScopeNode that is the first sibling of the node. Read-only.

Syntax

ScopeNode.FirstSibling As ScopeNode

Remarks

Built on Wednesday, October 27, 1999


HasChildren Property

Setting the HasChildren property determines whether a plus sign is displayed next to the node in the scope pane. Getting this property returns a value indicating whether the node currently has any children.

Syntax

ScopeNode.HasChildren As Boolean

Remarks

Setting ScopeNode.HasChildren = True tells MMC that the node will at some point be expanded and have child nodes and MMC will display the '+' sign next to the node. Setting ScopeNode.HasChildren = False tells MMC that the node never have child nodes and MMC will not display the '+' sign next to the node so that the user cannot expand it.


LastSibling Property

The LastSibling property returns the ScopeNode that is the last sibling of the node. Read-only.

Syntax

ScopeNode.LastSibling As ScopeNode

Remarks

Built on Wednesday, October 27, 1999


Next Property

The Next property returns the ScopeNode that is the next sibling of the node. Read-only.

Syntax

ScopeNode.Next As ScopeNode

Remarks

Built on Wednesday, October 27, 1999


NodeTypeGUID Property

The NodeTypeGUID property represents the GUID used to identify the type of the node.

Syntax

ScopeNode.NodeTypeGUID As String

Remarks

For predefined nodes the value of NodeTypeGUID is set from a GUID generated by the designer at design time.

For nodes defined in code (added with ScopeItems.Add) the designer runtime generates a GUID when the node is added. If the snap-in supports extension of such a node then it should set NodeTypeGUID when the ScopeItem is created to the value it has published in the registration database.


NodeTypeName Property

The NodeTypeName property represents the name used to identify the type of the node.

Syntax

ScopeNode.NodeTypeName As String

Remarks

For predefined nodes, this is the name of the node in the designer window treeview, it is the value passed for the NodeTypeName parameter of ScopeItems.AddPredefined, and it is also used in the registration database. If another Visual Basic snap-in extends your snap-in, then this name will appear in the Extensions property sheet.


Owned Property

The Owned property indicates whether the snap-in owns this node. Read-only.

Syntax

ScopeNode.Owned As Boolean

Remarks

If the snap-in owns a node then it can get its ScopeItem by using it as an index into the ScopeItems collection. For example:

Dim si As ScopeItem
If SomeScopeNode.Owned Then
    Set si = ScopeItems(SomeScopeNode)
End If


Parent Property

The Parent property returns the ScopeNode that is the parent of the node. Read-only.

Syntax

ScopeNode.Parent As ScopeNode

Remarks

Built on Wednesday, October 27, 1999


Views

The Views collection is the collection of View objects representing the multiple-document interface (MDI) windows currently open in the console that contain nodes owned by the snap-in. The snap-in does not explicitly create View objects. Items are added to and removed from this collection in response to the user opening and closing windows in the console. Events on this collection handle MDI window life-cycle events such as activate/deactivate and minimize/maximize as well as many user interactions such as selection and cut/paste.

The CurrentView property returns the View object corresponding to the view that currently has focus. SnapIn.CurrentView is a shorthand reference to this property. This property can have the value Nothing if there is no current view (for example, while the snap-in is loading).

The Initialize event is fired when the view is created. This informs the snap-in that a new window has been opened. This can happen when the snap-in is first loaded into a console or when a saved console file (.msc) is loaded.

The Load event is fired after MMC has completed initialization of the new view. At this point the snap-in can check the MMC version using the View object's properties. See "View" for more information.

The Terminate event is fired when a window is destroyed. A window is destroyed when the user closes it or closes MMC.

The Activate and Deactivate events are fired as the view gains and loses focus.

The WriteProperties event is fired when the user saves a console that includes the View. The snap-in can use this event to store view-specific data that will be needed when the console file is loaded. When MMC is retoring the view during console file load, the snap-in will receive the ReadProperties event. These events work exactly as for UserControl and persistable Visual Basic classes using a PropertyBag. Note that these events are fired in addition to the SnapIn_ReadProperties and SnapIn_WriteProperties events that are used for serialization of the snap-in's global serialization data in a console file. For more information see "SnapIn".

The Select event is fired whenever the user changes the selection in either the scope pane or the result pane. The selection is passed in an MMCClipboard parameter. This object contains collections of scope items, list items, and data objects for foreign nodes (added by namespace extensions). The event also receives an MMCConsoleVerbs collection that the snap-in uses to enable or disable the console verbs such as cut, copy, paste, print, refresh, rename, and delete. When a verb is enabled its toolbar button will appear and a corresponding item will appear on MMC's context menu if the user right-clicks the selected item(s).

When the user makes a multiple selection the snap-in receives the GetMultiSelectData event so that it can determine the data that will be exported for the selected items as a group. The data is used by extension snap-ins that support multiple selection.

The SetControlbar event is fired to allow the snap-in to add or remove toolbars and menu buttons from the console. An MMCControlbar object is passed as a parameter and its Attach and Detach methods are used to access the console's control bar.

The UpdateControlbar event is fired so that the snap-in can enable/disable and set the visibility of its toolbar and menu buttons.

The Refresh event is fired if the console enabled the refresh verb in the Select event and the user invoked refresh from the context menu, the toolbar, or by pressing F5.

The Delete event is fired if the console enabled the delete verb in the Select event and the user invoked delete from the context menu, the toolbar, or by pressing the DELETE key.

The Print event is fired if the console enabled the print verb in the Select event and the user invoked print from the context menu or the toolbar.

The QueryPaste event is fired if the console enabled the paste verb in the Select event and the user is dragging selected item(s) over a scope item or displays the context menu. If the snap-in returns True and the user completes the operation then the snap-in receives the Paste event. If the operation was a move (as opposed to a copy) then the snap-in receives the Cut event. See "Implementing Drag/Drop and Cut/Copy/Paste" for more information.

The QueryPagesFor event is fired if the console enabled the properties verb in the Select event and the user invoked properties from the context menu, the toolbar, or by pressing ALT+ENTER. If the snap-in returns True then it receives the CreatePropertyPages event in which it can add its pages to the console's property sheet. See "Property Pages" for more information.

When the user displays a context menu the snap-in has the opportunity to add items to four different insertion points. There are four different events that correspond to each of these points. AddNewMenuItems is for MMC's New submenu. AddTaskMenuItems is for MMC's All Tasks submenu. AddTopMenuItems allows adding items to the top of the context menu. AddViewMenuItems is for MMC's View submenu. The new, task, and top insertion points are also used on MMC's Action menu button drop-down. The view insertion point is also used on MMC's View menu button drop-down.

The SpecialPropertiesClick event is fired when the result pane contains a non-list view (OCX, URL, or taskpad), and the result pane has focus, and the snap-in has enabled the properties verb, and the user clicks the properties button on the toolbar. It has a single SnapInSelectionTypeConstants parameter containing siSpecialWeb or siSpecialOcx. If the snap-in needs to display properties it can use View.PropertySheetProvider. If the snap-in is displaying an OCX view, then it can also pass View.PropertySheetProvider to the ActiveX control.

Syntax

Views As Views

Properties

Count | Count of View object currently in the collection
CurrentView | Reference to the View object that represents the currently active view in the console. Can also be accessed as SnapIn.CurrentView.
Item | Retrieves a View object from the collection references by index or key.

Methods

This collection has no methods.

Events

Events will appear in the Visual Basic code as Views_<EventName> because Views is the property of SnapIn that contains the collection.

Activate | Called when a view become the active view
AddNewMenuItems | Called to allow the snap-in to add items to the "New" submenu of MMC's context menu.
AddTopMenuItems | Called to allow the snap-in to add items to the top of MMC's context menu.
AddTaskMenuItems | Called to allow the snap-in to add items to the "All Tasks" submenu of MMC's context menu.
AddViewMenuItems | Called to allow the snap-in to add items to MMC's "View" menu.
CreatePropertyPages | Called to allow a snap-in to add its page(s) to a property sheet.
Cut | Called after a user has completed a cut and paste operation.
Deactivate | Called when the active view is changed.
Delete | Called when the user invokes the delete verb by clicking the delete button, context menu item, or pressing the delete key.
GetMultiSelectData | Called when the user selects multiple items in the result pane to allow the snap-in to export data for the selection.
Initialize | Called when a view is created.
Load | Called when MMC has completed initialization of the view. MMC version number and services are available at this time.
Maximize | The view has been maximized.
Minimize | The view has been minimized.
Paste | The user has invoked the paste verb by dropping, clicking the paste button, or selecting paste from the context menu.
Print | The user has invoked the print verb by clicking the print button or selecting print from the context menu.
QueryPagesFor | Asks the snap-in whether it has property pages to display for the selected item(s).
QueryPaste | Called to ask the snap-in if the selected item(s) can accept a paste operation.
ReadProperties | Called to allow the snap-in to read its view-specific serialization data from a saved console file (.msc).
Refresh | The user has invoked the refresh verb by clicking the refresh button, pressing F5, or selecting refresh from the context menu.
Select | Called when the selection changes in a view.
SetControlbar | Called to allow the snap-in to add its toolbars and menu buttons to MMC controlbar.
SpecialPropertiesClick | Called when the result pane contains a taskpad, URL result view, or OCX result view, and the user clicks the Properties button on the toolbar.
Terminate | Called when a view is destroyed.
UpdateControlbar | Called to allow the snap-in to update its toolbars and menu buttons according to the selected item(s).
WriteProperties | Called to allow the snap-in to write its view-specific serialization data to a saved console file (.msc).


Activate Event

The Activate event informs the snap-in that the specified view is being activated. This occurs when the user moves the input focus to the view.

Syntax

Private Sub Views_Activate(View As View)

The Activate event syntax has these parts:

Part | Description
View | View object representing the view being activated.

Remarks

Built on Wednesday, October 27, 1999


AddNewMenuItems Event

The AddNewMenuItems event informs the snap-in that it has the opportunity to add items to the top of the "New" submenu of the console's context menu and "Action" menu.

Syntax

Private Sub Views_AddNewMenuItems(View As View, Selection As MMCClipboard, ContextMenu As ContextMenu, InsertionAllowed As Boolean)

The AddNewMenuItems event syntax has these parts:

Part | Description
View | View object representing the view in which the context menu was invoked. The context menu may be in either the scope pane or in the result pane.
Selection | MMCClipboard object containing the selected item(s).
ContextMenu | ContextMenu object that can be used to add the snap-in's menu items to MMC's context menu.
InsertionAllowed | Snap-in can set this to False to prevent extensions from adding their menu items.

Remarks

The InsertionAllowed parameter is always passed as True. Snap-ins can optionally set it to False to indicate that it does not allow other snap-ins that may extend it to insert items into the "New" submenu. ContextMenu is an object provided by the designer that is used to add the menu items. It has a single method for adding menus that takes an MMCMenu object. This object is similar to Visual Basic's Menu object. The menu can be created at design time or in code at run time. Before adding a menu, the snap-in should ensure that all menu items are appropriately enabled and checked. Snap-ins should not store the ContextMenu object as it will only work during this event. For more information see "Menus."


AddTaskMenuItems Event

The AddTaskMenuItems event informs the snap-in that it has the opportunity to add items to the top of the "All Tasks" submenu of the console's context menu and "Action" menu.

Syntax

Private Sub Views_AddTaskMenuItems(View As View, Selection As MMCClipboard, ContextMenu As ContextMenu, InsertionAllowed As Boolean)

The AddTaskMenuItems event syntax has these parts:

Part | Description
View | View object representing the view in which the context menu was invoked. The context menu may be in either the scope pane or in the result pane.
Selection | MMCClipboard object containing the selected item(s).
ContextMenu | ContextMenu object that can be used to add the snap-in's menu items to MMC's context menu.
InsertionAllowed | Snap-in can set this to False to prevent extensions from adding their menu items.

Remarks

The InsertionAllowed parameter is always passed as True. Snap-ins can optionally set it to False to indicate that it does not allow other snap-ins that may extend it to insert items into the "All Tasks" submenu. ContextMenu is an object provided by the designer that is used to add the menu items. It has a single method for adding menus that takes an MMCMenu object. This object is similar to Visual Basic's Menu object. The menu can be created at design time or in code at run time. Before adding a menu, the snap-in should ensure that all menu items are appropriately enabled and checked. Snap-ins should not store the ContextMenu object as it will only work during this event. For more information see "Menus."


AddTopMenuItems Event

The AddTopMenuItems event informs the snap-in that it has the opportunity to add items to the top of the console's context menu and "Action" menu.

Syntax

Private Sub Views_AddTopMenuItems(View As View, Selection As MMCClipboard, ContextMenu As ContextMenu, InsertionAllowed As Boolean)

The AddTaskMenuItems event syntax has these parts:

Part | Description
View | View object representing the view in which the context menu was invoked. The context menu may be in either the scope pane or in the result pane.
Selection | MMCClipboard object containing the selected item(s).
ContextMenu | ContextMenu object that can be used to add the snap-in's menu items to MMC's context menu.
InsertionAllowed | Not used.

Remarks

ContextMenu is an object provided by the designer that is used to add the menu items. It has a single method for adding menus that takes an MMCMenu object. This object is similar to Visual Basic's Menu object. The menu can be created at design time or in code at run time. Before adding a menu, the snap-in should ensure that all menu items are appropriately enabled and checked. Snap-ins should not store the ContextMenu object as it will only work during this event. For more information see "Menus."


AddViewMenuItems Event

The AddViewMenuItems event informs the snap-in that it has the opportunity to add items to the top of the "View" submenu of the console's context menu and to its "View" menu.

Syntax

Private Sub Views_AddViewMenuItems(View As View, Selection As MMCClipboard, ContextMenu As ContextMenu, InsertionAllowed As Boolean, AddPredefinedViews As Boolean)

The AddTaskMenuItems event syntax has these parts:
Part | Description
View | View object representing the view in which the context menu was invoked. The context menu may be in either the scope pane or in the result pane.
Selection | MMCClipboard object containing the selected item(s).
ContextMenu | ContextMenu object that can be used to add the snap-in's menu items to MMC's context menu.
InsertionAllowed | Not used.
AddPredefinedViews | Indicates whether the designer runtime should add result views defined at design time to the "View" menu.

Remarks

ContextMenu is an object provided by the designer that is used to add the menu items. It has a single method for adding menus that takes an MMCMenu object. This object is similar to Visual Basic's Menu object. The menu can be created at design time or in code at run time. Before adding a menu, the snap-in should ensure that all menu items are appropriately enabled and checked. Snap-ins should not store the ContextMenu object as it will only work during this event.

AddPredfinedViews is only used when the selected node was defined at design-time and it has result views that were marked for automatic view menu inclusion. If AddPredfinedViews is True (the default) then the designer runtime will add these result views to the view menu after the event handler completes.

For more information see "Menus."


Count Property

The Count property represents the number of View objects in the collection.

Syntax

Views.Count As Long

Remarks

Built on Wednesday, October 27, 1999


CreatePropertyPages Event

The CreatePropertyPages event allows the snap-in to add its property pages to the property sheet that MMC is about to display.

Syntax

Private Sub Views_CreatePropertyPages(View As View, Selection As MMCClipboard, PropertySheet As MMCPropertySheet)

The CreatePropertyPages event syntax has these parts:
Part | Description
View | View object representing the view in which the property sheet will be displayed.
Selection | MMCClipboard object containing the selected item(s). The selection can be in either the scope pane or the result pane.
PropertySheet | MMCPropertySheet object that can be used to add the snap-in's property pages to MMC's property sheet.

Remarks

This event is only fired if the snap-in handled the Views_QueryPagesFor event and returned HasPropertyPages=True. The snap-in should call MMCPropertySheet.AddPage to add its property pages. The objects in Selection will be available to the property pages as the elements of PropertyPage.SelectedControls beginning with the PropertyPages_SelectionChanged event. For more information see "Property Pages."


CurrentView Property

The CurrentView property returns the currently active View.

Syntax

Views.CurrentView As View

Remarks

This property can sometimes have the value Nothing meaning that there is no active View. Snap-in should always check the value before using this property.

SnapIn.CurrentView is a shorthand reference to this property.


Cut Event

The Cut event informs the snap-in that the user has completed a cut and paste operation.

Syntax

Private Sub Views_Cut(View As View, ItemsPasted As MMCClipboard, RetFromTarget As MMCDataObject)

The Cut event syntax has these parts:
Part | Description
View | View object representing the view from which the items were cut.
ItemsPasted | MMCClipboard containing the item(s) that were pasted if the operation is within in a single instance of the same snap-in.
RetFromTarget | MMCDataObject containing information returned from the target snap-in's paste handler if the operation is between different snap-ins or between two instances of the same snap-in.

Remarks

For cut and paste within a single instance of the same snap-in, the contents of ItemsPasted are the same as that of SourceItems in the Views_Paste event. The snap-in must iterate through the items and examine ScopeItem.Pasted and MMCListItem.Pasted to determine which items were successfully copied to the destination and then delete them from the underlying data.

For a cut and paste operation where the source and destination do not belong to the same instance of the same snap-in, then RetFromTarget is used instead of examining ScopeItem.Pasted and MMCListItem.Pasted. RetFromTarget is an MMCDataObject containing the data returned by the target snap-in in its paste handler to communicate which items were successfully pasted. If the target snap-in is written in Visual Basic then the Views_Paste event is its paste handler. The source snap-in determines the format of this data. (The snap-in receiving Views_Cut is the source snap-in). In Views_Cut it should call MMCDataObject.GetData, examine the data, and perform the deletion from the underlying data.

For more information see "Implementing Drag/Drop and Cut/Copy/Paste."


Deactivate Event

The Deactivate event informs the snap-in that the specified view is being deactivated. This occurs when the View is destroyed or when the user moves the input focus away from the View.

Syntax

Private Sub Views_Deactivate(View As View)

The Deactivate event syntax has these parts:

Part | Description
View | View object representing the view being deactivated.

Remarks

Built on Wednesday, October 27, 1999


Delete Event

The Delete event informs the snap-in that the user has invoked the delete verb by clicking the delete button, the delete context menu item, or pressing the delete key.

Syntax

Private Sub Views_Delete(View As View, Selection As MMCClipboard)

The Delete event syntax has these parts:

Part | Description
View | View object representing the view in which the delete verb was invoked.
Selection | MMCClipboard object containing the item(s) currently selected. The selection can be in either the scope pane or the result pane.

Remarks

This event can only be fired if the snap-in enabled the delete verb in the Views_Select event. MMC does nothing more than fire the event. It is up to the snap-in to perform the operation on it is underlying data.


GetMultiSelectData Event

The GetMultiSelectData is called during a multiple-selection operation to allow the snap-in to export data that represents all of the selected items.

Syntax

Private Sub Views_GetMultiSelectData(View As View, Selection As MMCClipboard, Data As MMCDataObject)

The GetMultiSelectData event syntax has these parts:

Part | Description
View | View object representing the view in which the multiple-selection occurred.
Selection | MMCClipboard object containing the item(s) currently selected. The selection can be in either the scope pane or the result pane.
Data | MMCDataObject object in which the snap-in can set its exported data.

Remarks

In a multiple selection list view, this event will be fired when the user selects multiple items. The selection can include:

Scope items owned by the snap-in

Scope items owned by namespace extensions of the currently selected node in the scope pane

List items owned by the snap-in

For more information see "Implementing Multiple Selection."


Initialize Event

The Initialize event informs the snap-in that a new view (MDI child window) has been created.

Syntax

Private Sub Views_Initialize(View As View)

The Initialize event syntax has these parts:

Part | Description
View | View object representing the newly created view.

Remarks

The view has not yet been completely initialized by MMC at this point and services such View.MMCMajorVersion and View.SelectScopeItem are not yet available. The Views_Load event is fired when MMC completes its initialization.

The snap-in can set the View.Name and View.Key if it needs to identify the view in later events. It can also use View.Tag to hold any data that the snap-in needs to associate with the view.


Item Property

The Item property returns a View indexed by ordinal integer or by key. This is the default property.

Syntax

Views.Item(Index) As View

or

Views (Index) As View

The Item property syntax has these parts:

Part | Description
Index | Index or key of View object to retrieve.

Remarks

Built on Wednesday, October 27, 1999


Load Event

The Load event informs the snap-in that MMC has completed its initialization of a newly created view.

Syntax

Private Sub Views_Load(View As View)

The Load event syntax has these parts:

Part | Description
View | View object representing the newly created view.

Remarks

Once the view has been completely initialized by MMC services such as View.MMCMajorVersion and View.SelectScopeItem become available.


Maximize Event

The Maximize event informs the snap-in that the specified view is being maximized.

Syntax

Private Sub Views_Maximize(View As View)

The Maximize event syntax has these parts:

Part | Description
View | View object representing the view being maximized.

Remarks

Built on Wednesday, October 27, 1999


Minimize Event

The Minimize event informs the snap-in that the specified view is being minimized.

Syntax

Private Sub Views_Minimize(View As View)

The Minimize event syntax has these parts:

Part | Description
View | View object representing the view being minimized.

Remarks

Built on Wednesday, October 27, 1999


Paste Event

The Paste event informs the snap-in that the user has invoked the paste verb. This can be done by dropping, clicking the paste button, or selecting paste from the context menu.

Syntax

Private Sub Views_Paste(DestView As View, SourceItems As MMCClipboard, DestScopeItem As ScopeItem, RetToSource As MMCDataObject, Move As Boolean)

The Cut event syntax has these parts:
Part | Description
DestView | View object representing the view in which the paste has occurred.
SourceItems | MMCClipboard containing the item(s) that are being pasted.
DestScopeItem | ScopeItem onto which the user has pasted the source items.
RetToSource | MMCDataObject for returning information to the source snap-in's cut handler if the operation is between different snap-ins or between two instances of the same snap-in.
Move | If True then the operation is a move (as opposed to a copy).

Remarks

For operations within a single instance of the same snap-in, the contents of SourceItems are ScopeItem and MMCListItem objects belonging to the snap-in. For operations between snap-ins, the snap-in must examine SourceItems.DataObjects for data exported by each snap-in that owns items in the source.

For move operations within a single instance of the same snap-in, set ScopeItem.Pasted=True and MMCListItem.Pasted=True for each scope item and list item in SourceItems that was successfully pasted.

For operations between snap-ins, the snap-in must return information on the items successfully pasted in the MMCDataObject referenced by RetToSource. The format of the data that must be set in this MMCDataObject is determined by the source snap-in. Consult the documentation of the source snap-in for the format of this data.

This event can only be fired if the snap-in enabled the paste verb in the Views_Select event and it handled Views_QueryPaste and returned OkToPaste=True.

For more information see "Implementing Drag/Drop and Cut/Copy/Paste."


Print Event

The Print event informs the snap-in that the user has invoked the print verb by clicking the print button or the print context menu item.

Syntax

Private Sub Views_Print(View As View, Selection As MMCClipboard)

The Delete event syntax has these parts:

Part | Description
View | View object representing the view in which the print verb was invoked.
Selection | MMCClipboard object containing the item(s) currently selected. The selection can be in either the scope pane or the result pane.

Remarks

This event can only be fired if the snap-in enabled the print verb in the Views_Select event. MMC does nothing more than fire the event. It is up to the snap-in to perform the operation on it is underlying data.


QueryPageFor Event

Platform SDK: Management Console

QueryPagesFor Event

The QueryPagesFor event asks the snap-in whether it has property pages to for the selected item(s).

Syntax

Private Sub Views_QueryPagesFor(View As View, Selection As MMCClipboard, PropertySheet As MMCPropertySheet, HasPropertyPages As Boolean)

The QueryPagesFor event syntax has these parts:
Part | Description
View | View object representing the view in which the property sheet will be displayed.
Selection | MMCClipboard object containing the selected item(s). The selection can be in either the scope pane or the result pane.
HasPropertyPages | Set this to True to indicate that the snap-in has property pages for the selected item(s).

Remarks

This event is only fired if the snap-in has enabled the properties verb in Views_Select. If the snap-in returns HasPropertyPages=True then it will receive a subsequent Views_CreatePropertyPages event. For more information see "Property Pages."


QueryPaste Event

The QueryPaste event asks the snap-in whether it can accept a paste verb on the destination scope item.

Syntax

Private Sub Views_QueryPaste(DestView As View, SourceItems As MMCClipboard, DestScopeItem As ScopeItem, OkToPaste As Boolean)

The Cut event syntax has these parts:
Part | Description
DestView | View object representing the view in which the paste has occurred.
SourceItems | MMCClipboard containing the item(s) that are being pasted.
DestScopeItem | ScopeItem onto which the user has pasted the source items.
OKToPaste | If True then the snap-in can accept the paste operation.

Remarks

When the user drags selected item(s) over a scope item owned by the snap-in, or displays a context menu for that scope item, the snap-in receives the Views_QueryPaste event. If the snap-in returns True then the paste item appears on the context menu or the mouse cursor changes to the copy icon.

If the user drops the item(s), clicks the paste button, or clicks the paste context menu item, then the snap-in will receive the Views_Paste event.

This event can only be fired if the snap-in enabled the paste verb in the Views_Select event.

For more information see "Implementing Drag/Drop and Cut/Copy/Paste."


ReadProperties Event

The ReadProperties event loads any view-specific state from the .msc file saved in the WriteProperties event.

Syntax

Private Sub Views_ReadProperties(View As View, PropertyBag As PropertyBag)

The ReadProperties event syntax has these parts:
Part | Description
View | View object representing the view that is being loaded.
PropertyBag | PropertyBag object containing the properties saved by the snap-in in its Views_WriteProperties event when the console file was saved.

Remarks

If the snap-in saved state in the Views_WriteProperties event when the console file was saved, then it should handle this event to load its state. Snap-ins can also save and load global state using SnapIn_WriteProperties and SnapIn_ReadProperties.


Refresh Event

The Refresh event informs the snap-in that the user has invoked the refresh verb by clicking the refresh button, the refresh context menu item, or pressing the refresh key (F5).

Syntax

Private Sub Views_Refresh(View As View, Selection As MMCClipboard)

The Refresh event syntax has these parts:

Part | Description
View | View object representing the view in which the refresh verb was invoked.
Selection | MMCClipboard object containing the item(s) currently selected. The selection can be in either the scope pane or the result pane.

Remarks

This event can only be fired if the snap-in enabled the refresh verb in the Views_Select event. MMC does nothing more than fire the event. It is up to the snap-in to perform the operation on it is underlying data.


Select Event

The Select event notifies the snap-in that the user has selected or deselected item(s) in the scope pane or in the result pane. The snap-in should enable/disable the standard verbs (cut/copy/paste) as appropriate for the selection.

Syntax

Private Sub Views_Select(View As View, Selection As MMCClipboard, Selected As Boolean, ConsoleVerbs As MMCConsoleVerbs)

The Select event syntax has these parts:

Part | Description
View | The view in which the selection change occurred.
Selection | MMCClipboard object containing the item(s) in the selection operation.
Selected | Indicates whether the item(s) were selected or de-selected.
ConsoleVerbs | MMCConsoleVerbs collection used by the snap-in to enable/disable console verbs.

Remarks

The Select event is fired in response to the following user actions:

Right or left click a node in the scope pane that is not currently selected

Right or left click a node in the result pane that is not currently selected

Right or left click a list item in the result pane that is not currently selected

Add an item to a multiple selection by using up arrow, down arrow, page up, or page down with the shift key, or control + left click.

Moving focus to another view or application.

Setting focus to a view.

The snap-in uses this event to set the state of the console verbs. Console verbs are enabled and disabled using the MMCConsoleVerbs collection indexed by SnapInConsoleVerbConstants. For example, to enable the print verb use:

ConsoleVerbs(siPrint).Enabled = True

For more information see "MMConsoleVerbs".

Debugging the Views_Select event can be difficult because as focus moves between MMC and the Visual Basic IDE more select events will be generated. If a message box is displayed from this event it will also generate additional Views_Select events. It is generally easiest to set a breakpoint in the event and disable it before stepping out of it so that the breakpoint is only hit once. Using Debug.Print to send messages to the debug window is also a useful technique.


SetControlbar Event

The SetControlbar event allows the snap-in to attach and detach controls to and from the console's controlbar.

Syntax

Private Sub Views_SetControlbar(View As View, Controlbar As MMCControlbar)

The SetControlbar event syntax has these parts:

Part | Description
View | View object representing the view in which the snap-in can attach its controls.
Controlbar | MMCControlbar object that the snap-in can use to attach its controls.

Remarks

The snap-in can attach and detach its toolbars and menu buttons to and from MMC's controlbar by calling MMCControlbar.Attach and MMCControlbar.Detach.

The MMCControlbar object can only be used during this event handler and the snap-in should not store a reference to it.


SpecialPropertiesClick Event

The SpecialPropertiesClick is fired when the user clicks the properties button on the toolbar and the result pane contains something other than a list view.

Syntax

Private Sub Views_SpecialPropertiesClick(View As View, ResultViewType As SnapInSelectionTypeConstants)

The SpecialPropertiesClick event syntax has these parts:
Part | Description
View | View object representing the view in which the properties verb was invoked.
ResultViewType | Indicates the type of result view.

The possible ResultViewType argument settings are:

Constant | Value | Description
siSpecialWeb | 8 | The result pane contains a URL result view or a taskpad.
siSpecialOcx | 9 | The result pane contains an OCX result view.

Remarks

If the snap-in needs to display properties it can use View.PropertySheetProvider. If the snap-in is displaying an OCX result view, then it can also pass View.PropertySheetProvider to the ActiveX control. See "Initiating Property Sheet and Wizard Displays Programmatically" for more information.


Terminate Event

The Terminate event informs the snap-in that the specified view is being destroyed and that it should perform any related cleanup.

Syntax

Private Sub Views_Terminate(View As View)

The Terminate event syntax has these parts:

Part | Description
View | View object representing the view being destroyed.

Remarks

Built on Wednesday, October 27, 1999


UpdateControlbar Event

The UpdateControlbar event allows the snap-in to change the state of toolbar and menu buttons added in the Views_SetControlbar event.

Syntax

Private Sub Views_UpdateControlbar(View As View, Selection As MMCClipboard, Selected As Boolean, ControlBar As MMCControlBar)

The SetControlbar event syntax has these parts:

Part | Description
View | View object representing the view in which the controlbar must be updated.
Selection | MMCClipboard object containing the item(s) in the selection.
Selected | True is the user selected item(s). False if the user's action caused previously selected item(s) to be deselected.
ControlBar | MMCControlbar object that the snap-in can use to attach and detach its controls to and from MMC's controlbar.

Remarks

The snap-in should examine the selection to determine whether it needs to update its toolbar and menu buttons. The snap-in can update the state of its toolbar and menu buttons by using MMCButton and MMCButtonMenu properties.

The snap-in can attach and detach toolbars and menu buttons to and from MMC's controlbar by calling MMCControlbar.Attach and MMCControlbar.Detach.

The MMCControlbar object can only be used during this event handler and the snap-in should not store a reference to it.


WriteProperties Event

The WriteProperties event allows the snap-in to save any view-specific state when the snap-in is part of a saved console file (.msc).

Syntax

Private Sub Views_WriteProperties(PropertyBag As PropertyBag)

The WriteProperties event syntax has these parts:

Part | Description
View | View object representing the view that is being saved in the console file.
PropertyBag | PropertyBag object in which the snap-in can save its state by calling PropertyBag.WriteProperty.

Remarks

If the snap-in saves state in the Views_WriteProperties event when the console file is saved, then it will receive the Views_ReadProperties event to load its state when the console file is loaded. Snap-ins can also save and load global state using SnapIn_WriteProperties and SnapIn_ReadProperties.


View

The View object represents a single MDI child window in the console. All events for a view are fired on the Views collection.

The MMCMajorVersion and MMCMinorVersion properties allow primary snap-ins to determine the MMC version. They are available starting from the Views_Load event. Non-namespace extensions do not have access to the MMC version but as of MMC 1.2 there is no difference in available functionality between MMC 1.1 and MMC 1.2 for these extensions.

The Caption property is used when a new view is created programmatically using ScopeNode.NewWindow. It determines the text of the view's title bar.

PropertySheetProvider is an MMCPropertySheetProvider object that allows a snap-in to programmatically initiate the display of property sheets and wizards. See "Initiating Property Sheet and Wizard Displays Programmatically" for more information.

The SelectScopeItem method is used to select a scope item in the scope pane and optionally specify its result view. If the scope item does not appear in the view's scope pane then this method has no effect. This situation can occur if the user invokes New Window from Here on a node below the snap-in's static node or if the snap-in programmatically does the same using ScopeNode.NewWindow.

The SetStatusBarText method inserts text into the view's status bar in the lower-left corner. This method should only be called when a node added by the snap-in is currently selected in the scope pane. It cannot be used when the snap-in's static node is selected in the scope pane.

The status bar has three sections, which are delineated by the pipe character (|). For example, setting the text in the status bar to "Big| Bad| Wolf" places "Big" in the leftmost section of the status bar, " Bad" in the middle section, and " Wolf" in the rightmost section.

If more than three fields are delineated (that is, there are more than two pipes), then everything that would be placed in the fourth and higher fields is omitted.

In addition, the middle section is designed to function as a progress bar. This functionality is invoked by passing the percent (%) character as the first character, followed by a number between 0 and 100, into the middle section. Instead of text, this section then displays a progress bar that is zero to 100 percent complete. For example, passing "Done|%75" places "Done" in the left section and a progress bar 75% complete in the middle section.

If you want to display a string that begins with "%" in the middle section of the status bar, then begin the string with "%%". This causes the middle section to display text and removes the first "%". For example: "cheesy|%%poofs%" results in the left section containing "cheesy" and the middle section containing "%poofs%". If an invalid number or non-numeric text is entered in the middle section following a "%", then the middle section is empty. If a "%" is the only character in the section, then it will be shown as text.

The PopupMenu method is used only for column filtering. It allows the snap-in to display a menu defined at design time or in code as a pop-up menu at a specified location. For more information see "Using Column Filtering."

The ScopePaneItems property is a collection of ScopePaneItem objects representing the set of scope items owned by the snap-in that are currently in the view's scope pane. See "ScopePaneItems" for more information.

Syntax

View As View

Properties

Caption | For primary snap-ins sets the title bar in a view created by calling View.NewWindow(siCustomTitle, Caption)
ColumnSettings | Column persistence settings for the view. MMC 1.2 only.
Index | Ordinal position of the View in the Views collection.
Key | Key that uniquely identifies the View in the Views collection.
MMCMajorVersion | Returns the MMC major version number.
MMCMinorVersion | Returns the MMC minor version number.
Name | Name that uniquely identifies the View in the Views collection.
PropertySheetProvider | MMCPropertySheetProvider object that can be used initiate property sheet and wizard displays programmatically.
ScopePaneItems | Collection of ScopePaneItem object contained within the view.
SortSettings | Sort persistence settings for the view. MMC 1.2 only.
Tag | Holds any private snap-in data associated with the View.

Methods

CollapseInTreeview | Collapses a node in the view's scope pane.
ExpandInTreeview | Expands a node in the view's scope pane.
NewWindow | Creates a new view.
PopupMenu | Displays a popup menu. Used for column filtering.
SelectScopeItem | Selects a scope item in the view's scope pane.
SetStatusBarTest | Displays text in MMC status bar (at the bottom of the view window)

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Caption Property

The Caption property sets the text for the view window's title bar when the snap-in's static node or one of its children is selected in the scope pane of a window opened programmatically using View.NewWindow(siCustomTitle, Caption). This property can also be set during Views_Initialize. For primary snap-ins only.

Syntax

View.Caption As String

Remarks

Built on Wednesday, October 27, 1999


CollapseInTreeview Method

The CollapseInTreeView method collapse the specified node in the scope pane of the view. This is only a UI operation and does not alter the namespace.

Syntax

View.CollapseInTreeView(ScopeNode As ScopeNode)

The CollapseInTreeView method syntax has these parts:

Part | Description
ScopeNode | Node to be collapsed.

Remarks

Built on Wednesday, October 27, 1999


ColumnSettings Property

Returns the column persistence settings for a particular node in the view.

Syntax

View.ColumnSettings(ColumnSetID As String) As ColumnSettings

The ColumnSettings method syntax has these parts:

Part | Description
ColumnSetID | ID of the column set to be retrieved.

Remarks

MMC allows the user to customize the appearance of a list view by using the "Choose Columns…" option on the "View" menu. MMC persists these settings as the user navigates between nodes in the scope pane and restores them when the user returns to a previously customized node. The snap-in can examine these settings and make changes to them.

The value of ColumnSetID for a particular node in the scope pane is kept in View.ScopePaneItems(<key>).ColumnSetID and its value defaults to the node type GUID (View.ScopePaneItems(<key>).ScopeItem.ScopeNode.NodeTypeGUID).

Column persistence settings are not available before the Views_Load event. Requires MMC 1.2 or greater. For more information see "Using Column Persistence".


Add Method

Platform SDK: Management Console

ExpandInTreeview Method

The ExpandInTreeView method expand the specified node in the scope pane of the view. This is only a UI operation and does not alter the namespace.

Syntax

View.ExpandInTreeView(ScopeNode As ScopeNode)

The ExpandInTreeView method syntax has these parts:

Part | Description
ScopeNode | Node to be expanded.

Remarks

Built on Wednesday, October 27, 1999


Index Property

Ordinal index of the View in the Views collection.

Syntax

View.Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Key of the View in the Views collection.

Syntax

View.Key As String

Remarks

The snap-in may set this to any string in order to help it identify the view.


MMCMajorVersion Property

Returns the major version number of MMC.

Syntax

View.MMCMajorVersion As Long

Remarks

This property returns the portion of the version number on the left side of the dot. For example, for MMC 1.2 it returns 1. It is not available before the Views_Load event.


MMCMinorVersion Property

Returns the minor version number of MMC.

Syntax

View.MMCMinorVersion As Long

Remarks

This property returns the portion of the version number on the right side of the dot. For example, for MMC 1.2 it returns 2. It is not available before the Views_Load event.


Name Property

The Name property is a snap-in-defined name used to identify the view.

Syntax

View.Name As String

Remarks

The snap-in may set this to any string in order to help it identify the view.


NewWindow Method

The NewWindow method creates a new view using the specified node as the root of the scope pane.

Syntax

View.NewWindow(ScopeNode As ScopeNode, Options As SnapInNewWindowOptionConstants, [Caption])

The NewWindow method syntax has these parts:

Part | Description
ScopeNode | ScopeNode object representing node that will be at the root of the scope pane in the new view.
Options | Determine appearance of the new view window. See below.
Caption | If siCustomTitle is specified then this string specifies the title bar text of the new view window.

Options can be a combination of the following:

siDefaultWindow | Display a new window with default settings. This is the same as using "New Window From Here" on the View menu.
siNoScopePane | Hide the scope pane in the new window.
siNoToolbars | Hide the standard toolbars in the new window. Custom toolbars will appear.
siShortTitle | Title bar text contains only the name of the root node and does not contain the full namespace path.
siCustomTitle | Title bar text contains the scope node's display name. If a caption is specified then the new View window will have its Caption property set with this value. View.Caption can also be set during Views_Initialize. The caption will be displayed in the new window's title bar.
siNoPersist | Do not save the new window's properties when the console is saved.

Remarks

Built on Wednesday, October 27, 1999


PopupMenu Method

The PopupMenu method displays a popup menu at the specified coordinates.

Syntax

View.PopupWindow(Menu As MMCMenu, Left As Long, Top As Long)

The NewWindow method syntax has these parts:

Part | Description
Menu | MMCMenu object containing the menu to pop up.
Left | The horizontal position of the top-left corner of the menu in screen coordinates.
Top | The vertical position of the top-left corner of the menu in screen coordinates.

Remarks

This method is used for column filtering in MMC 1.2 to display a popup menu in response to the ResultViews_FilterButtonClick event. The suggested coordinates for Left and Top are passed as parameters to that event. For more information see "Using Column Filtering".


PropertySheetProvider Property

The PropertySheetProvider property returns a reference to an MMCPropertySheetProvider object that can be used to programmatically initiate property sheets and wizards.

Syntax

View.PropertySheetProvider As MMCPropertySheetProvider

Remarks

This property is not available prior to Views_Load. See "Initiating Property Sheet and Wizard Displays Programmatically" for more information.


ScopePaneItems Property

The ScopePaneItems property is the collection of ScopePaneItem object that represent the scope items present in the scope pane of the view

Syntax

View.ScopePaneItems As ScopePaneItems

Remarks

The purpose of the ScopePaneItems collection is to manage properties that are specific to an instance of a node within the scope pane of a particular view (e.g. the result view type). This collection is not always completely populated because MMC does not always inform the designer runtime of the presence of scope items in a particular scope pane. The only items that are guaranteed to be present are nodes that have been selected in the scope pane. The snap-in can only be sure that a node has been selected in the scope pane if it receives the ScopePaneItems_GetResultViewInfo or ScopePaneItems_GetResultView event. For more information see "ScopePaneItems".


SelectScopeItem Method

The SelectScopeItem method selects a node owned by the snap-in in the scope pane of a view.

Syntax

View.SelectScopeItem(ScopeItem As ScopeItem, [ViewType], [DisplayString])

The NewWindow method syntax has these parts:

Part | Description
ScopeItem | ScopeItem object representing the node to be selected.
ViewType | Optional. Specifies the result view that should be displayed when the scope item is selected.
DisplayStrring | Optional. If ViewType is specified, then certain types require extra information that is supplied in this string.

Remarks

This method programmatically simulates the action of a user selecting a node in the scope pane. For information on how to specify ViewType and DisplayString see "ScopePaneItem".


SetStatusBarText Method

The SetStatusBarText method sets the text in the status bar belonging to the MDI child window represented by the view. This method only works if the snap-in owns the currently selected node in the scope pane.

Syntax

View.SetStatusBarText(Text As String)

The SetStatusBarText method syntax has these parts:

Part | Description
Text | Text to display in the status bar

Remarks

The status bar has three sections, which are delineated by the pipe character ("|"). For example, setting the text in the status bar to "Big| Bad| Wolf" places "Big" in the leftmost section of the status bar, " Bad" in the middle section, and " Wolf" in the rightmost section.

If more than three fields are delineated (that is, there are more than two pipes), then everything that would be placed in the fourth and higher fields is omitted.

In addition, the middle section is designed to function as a progress bar. This functionality is invoked by passing the '%' character as the first character, followed by a number between 0 and 100, into the middle section. Instead of text, this section then displays a progress bar that is zero to 100 percent complete. For example, passing "Done|%75" places "Done" in the left section and a progress bar 75% complete in the middle section.

If you want to display a string that begins with '%' in the middle section of the status bar, then begin the string with '%%'. This causes the middle section to display text and removes the first '%'. For example: "foo|%%bar%" results in the left section containing "foo" and the middle section containing "%bar%". If an invalid number or non-numeric text is entered in the middle section following a '%', then the middle section is empty. If a '%' is the only character in the section, then it will be shown as text.


SortSettings Property

Returns the sort persistence settings for for a particular node in the view.

Syntax

View.SortSettings(ColumnSetID As String) As SortKeys

The SortSettings method syntax has these parts:

Part | Description
ColumnSetID | ID of the column set to be retrieved.

Remarks

MMC allows the user to customize the sorting of a list view by clicking the column headers. MMC persists these settings as the user navigates between nodes in the scope pane and restores them when the user returns to a previously customized node. The snap-in can examine these settings and make changes to them.

The value of ColumnSetID for a particular node in the scope pane is kept in View.ScopePaneItems(<key>).ColumnSetID and its value defaults to the node type GUID (View.ScopePaneItems(<key>).ScopeItem.ScopeNode.NodeTypeGUID).

Sort persistence settings are not available before the Views_Load event. Requires MMC 1.2 or greater. For more information see "Using Column Persistence".


Tag Property

The Tag property is used for snap-in-defined data associated with the view.

Syntax

View.Tag As Variant

Remarks

Built on Wednesday, October 27, 1999


ScopePaneItems

The ScopePaneItems collection represents the collection of scope items created by the snap-in that are currently visible in the scope pane within a single View. ScopePaneItem represents an instance of ScopeItem in a scope pane and its properties pertain to the view-specific aspects of a scope item such as its current ResultView. All events are on the collection. In order to check whether a scope item is currently in the scope pane the ScopeItem object can be used as an index into the ScopePaneItems collection. Unfortunately, if the ScopePaneItem is not present, it does not mean that the ScopeItem is not in the scope pane because MMC does not always tell the snap-in which items are there. The designer runtime collects all available hints in order to populate ScopePaneItems. Snap-ins do not add or remove items from this collection. The only time a ScopePaneItem is guaranteed to be present is when a ScopeItem is selected in the scope pane and a result view is displayed for it in the result pane.

The Parent property contains a reference to the View object that owns the ScopePaneItems collection.

The SelectedItem property contains a reference to the ScopePaneItem for the currently selected scope item in the scope pane. SnapIn.CurrentScopePaneItem is a shorthand reference to this property. SelectedItem can be Nothing if there is no selection in the scope pane belonging to the snap-in.

The Initialize event is called when a ScopePaneItem is created. The Terminate event is called when it is destroyed.

GetResultViewInfo is called when the user selects the scope item in the scope pane. It allows the snap-in to determine what type of result view will be displayed. The designer runtime determines a default based on design-time definitions. If the node was defined at run time or if no default result view was chosen at design time, then the runtime defaults to a list view. The parameters contain the runtime's default and the snap-in can change them as needed. See "ScopePaneItem" for more information on how to set the DisplayString parameter.

GetResultView is called when the snap-in is caching result views. Snap-ins can decide to cache a result view in the ResultViews_Deactivate event by returning Keep=True. Caching can be useful for a result view that is displayed often and requires significant time and/or processing to populate. If there are cached result views then the snap-in can handle this event and return the index of an existing result view in the ScopePaneItem.ResultViews collection. This event is only fired if the snap-in did not handle GetResultViewInfo or did not change any of the parameters in its handler.

Syntax

ScopePaneItems As ScopePaneItems

Properties

Count | Count of ScopePaneItem objects in the collection.
Item | Returns a ScopePaneItem object in the collection references by index or key.
Parent | Returns the View object that owns the collection.
SelectedItem | Returns the ScopePaneItem that represents the currently selected node in the scope pane of the owning view.

Methods

This collection has no methods.

Events

These events will appear in the Visual Basic code as ScopePaneItems_<EventName>..

GetResultView | If ScopePaneItems_GetResultViewInfo is not handled then this event is called to allow the snap-in to reuse an existing result view.
GetResultViewInfo | Called to allow the snap-in to set the result view type and display string for the specified scope pane item.
Initialize | Called when a ScopePaneItem object is created.
Terminate | Called when a ScopePaneItem object is destroyed.


Count Property

The Count property returns the number of ScopePaneItem objects in the collection.

Syntax

ScopePaneItem.Count As Long

Remarks

Built on Wednesday, October 27, 1999


GetResultView Event

The GetResultView event is called when the scope pane item has been selected and the console is requesting the type of result view to display in the result pane. This event allows the snap-in to use an existing ResultView that was cached by returning Keep=True in ResultViews_Deactivate.

Syntax

Private Sub ScopePaneItems_GetResultView(ScopePaneItem As ScopePaneItem, Index As Variant)

The GetResultView event syntax has these parts:

Part | Description
ScopePaneItem | The ScopePaneItem object representing the node that has been selected in the scope pane.
Index | If the snap-in wants to reuse and existing result view it should set Index to its index or key in ScopePaneItem.ResultViews.

Remarks

The only way an existing ResultView can be in the ScopePaneItem.ResultViews collection is if the snap-in earlier handled ResultViews_Deactivate and specified that the ResultView should not be destroyed by setting Keep=True. If the ScopePaneItems_GetResultView event is handled but the snap-in decides not to use an existing ResultView then Index should not be set. In this case the current values of the ScopePaneItem.ResultViewType and ScopePaneItem.ResultViewDisplayString will be used to determine the result view type.

This event is only fired if the snap-in did not handle the ScopePaneItems_GetResultViewInfo event or did not change any of the parameters to that event.


GetResultViewInfo Event

The GetResultViewInfo event is called when the scope pane item has been selected and the console is requesting the type of result view to display in the result pane. Handling this event allows the snap-in to dynamically change the view type for a scope pane item.

Syntax

Private Sub ScopePaneItems_GetResultViewInfo(ScopePaneItem As ScopePaneItem, ViewType As SnapInResultViewTypeConstants, DisplayString As String)

The GetResultViewInfo event syntax has these parts:

Part | Description
ScopePaneItem | The ScopePaneItem object representing the node that has been selected in the scope pane.
ViewType | Type of result view to display for the ScopePaneItem.
DisplayString | Additional info needed depending on value of ViewType (see below).

For information on how to specify ViewType and DisplayString see "ScopePaneItem".

Remarks

Upon entry to this event handler ViewType and Display are set to the values that will be used if the snap-in does not handle this event and it does not handle ResultViews_GetResultView. The designer runtime determines the default result view as follows:

If the ScopePaneItem does not represent a node defined at design time then use a list view.

If the ScopePaneItem does represent a node defined at design time and the node does not have a default result view then use a list view.

If the ScopePaneItem does represent a node defined at design time and the node does have a default result view then use that result view.

In case 3, if the snap-in is running on MMC 1.1 and it has both taskpads and non-taskpads defined at design time, and the default result view is not a taskpad, then the runtime checks the "Taskpad View Preferred" console option. If this option is set then the runtime chooses the taskpad. If the node has more than one taskpad, then it chooses the taskpad that set the "Use when taskpad view preferred" checkbox at design time. If more than one taskpad has this checkbox checked then the runtime uses the first one that has it.

If this event is not handled the designer runtime will use the default values and create a new result view. If the event is handled but the snap-in decides instead to use an existing ResultView then it should not change the values of ViewType and DisplayString and handle ScopePaneItems_GetResultView.


Initialize Event

The Initialize event informs the snap-in that the specified scope pane item has just been created and added to the collection.

Syntax

Private Sub ScopePaneItems_Initialize(ScopePaneItem As ScopePaneItem)

The Initialize event syntax has these parts:

Part | Description
ScopePaneItem | ScopePaneItem object that was created.

Remarks

Built on Wednesday, October 27, 1999


Item Property

The Item property returns a ScopePaneItem indexed by ordinal integeror by key. This is the default property.

Syntax

ScopePaneItems.Item(Index) As ScopePaneItem

or

ScopePaneItems(Index) As ScopePaneItem

The Item property syntax has these parts:

Part | Description
Index | Index or key of the ScopePaneItem in the collection.

Remarks

Built on Wednesday, October 27, 1999


Parent Property

The Parent property is the View object to which the scope pane belongs.

Syntax

ScopePaneItems.Parent As View

Remarks

Built on Wednesday, October 27, 1999


SelectedItem Property

The SelectedItem property returns the currently selected item in the scope pane.

Syntax

ScopePaneItem.SelectedItem As ScopePaneItem

Remarks

This property can return the value Nothing if there is no currently selected ScopePaneItem. The snap-in must check the value before using it e.g.

If Not View.ScopePaneItems.SelectItem Is Nothing Then
    … use the property …
End If


Terminate Event

The Terminate event informs the snap-in that the specified scope pane item is about to be destroyed. The item has been removed from the ScopePaneItems collection before this event is fired and it will be destroyed after this event completes.

Syntax

Private Sub ScopePaneItems_Terminate(ScopePaneItem As ScopePaneItem)

The Terminate event syntax has these parts:

Part | Description
ScopePaneItem | ScopePaneItem that is about to be destroyed.

Remarks

Built on Wednesday, October 27, 1999


ScopePaneItem

The ScopePaneItem object encapsulates all of the properties of a scope item that are particular to an instance of the scope item within a view. The Name and Key properties always match those of the underlying ScopeItem.

Parent contains a reference to the owning ScopePaneItems collection.

ScopeItem contains a reference to the underlying ScopeItem.

DisplayString contains information specific to the currently displayed result view for the ScopePaneItem. ResultViewType is an enumeration that contains the current type of result view. The following table describes the contents of DisplayString for the different result view types.

Result view type | DisplayString contents
siURLView | URL navigated to in result pane
siOCXView | ProgID of ActiveX control displayed in result pane
siTaskpad, siListpad, siCustomTaskpad | res:// URL to path of taskpad template followed by "#" and then the group name. See the MMC SDK documentation for IComponent::GetResultViewType for details on this format.
siListView | Empty
siMessageView | Empty
siPreDefined | Name of result view in designer window

ResultView contains a reference to the ResultView object for the current contents of the result pane.

ResultViews is a collection of all of the existing result views for the ScopePaneItem. Normally there is only one ResultView in this collection but if the snap-in chooses to cache result views in the ResultViews_Deactivate event then they are not removed from the collection and can be reused by handling ScopePaneItems_GetResultView. See "ScopePaneItems" for more information.

HasListViews indicates whether the ScopePaneItem is displaying or can display result views in the result pane. If HasListViews=True then MMC will add the list view options (large, small, list, report, filtered) to its View menu. The default is True. If the snap-in needs to set this property to False it must do so in the ResultViews_Initialize event.

ColumnSetID is used for column persistence and identifies the instance of the ScopeItem in the scope pane. If not set then it defaults to the scope item's node type GUID in ScopeItem.ScopeNode.NodeTypeGUID. Using the default tells MMC that all nodes of this type, when selected in the scope pane and displaying a list view, will use the same column settings. If a snap-in needs to maintain individual column settings then it should set ColumnSetID to a unique value for each instance of the ScopePaneItem object for the node. The FileExplorer sample is an example of using the default setting. This allows users to customize column settings in one folder and then have them preserved as they navigate to other folders. This happens because all folders use the same node type. If FileExplorer wanted to preserve the settings on a per-folder basis then it would give each folder's ScopePaneItem a unique value for ColumnSetID.

The DisplayNewResultView method is used to change the contents of the result pane. Parameters are the result view type and the display string. The same effect can be achieved by setting ResultViewType and DisplayString and then reselecting the scope item using View.SelectScopeItem.

DisplayMessageView displays a message view in the result pane and allows specifying all of its properties as parameters. This can also be done by using DisplayNewResultView and then setting the message view properties in ResultViews_Activate.

Syntax

ScopePaneItem As ScopePaneItem

Properties

ColumnSetID | Identifies a set of column and sort settings persisted by MMC.
DisplayString | Used in combination with ResultViewType to determine the type of result view displayed for the ScopePaneItem.
HasListViews | Indicates whether the scope pane item can display list views. Determines whether view menu options are enabled in the console.
Index | Index of the ScopePaneItem within its owning ScopePaneItems collection.
Key | Key of the ScopePaneItem within its owning ScopePaneItems collection.
Name | Name of the ScopePaneItem. Always the same as Key.
Parent | Returns the ScopePaneItems collection that owns the ScopePaneItem.
ResultView | A reference to the ResultView object representing the currently displayed result view for the ScopePaneItem.
ResultViews | The collection of ResultViews for the ScopePaneItem.
ResultViewType | Determines the type of result view displayed for the ScopePaneItem.
ScopeItem | Reference to the ScopeItem object that the ScopePaneItem represents in the scope pane of its view.
Tag | Can be used by the snap-in to associate data with the ScopePaneItem.

Methods

DisplayMessageView | Displays a message view in the result pane.
DisplayNewResultView | Displays the specified result view in the result pane.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


DisplayName Property

Platform SDK: Management Console

ColumnSetID Property

The ColumnSetID property identifies the current set of persisted column and sort settings for the ScopePaneItem.

Syntax

ScopePaneItem.ColumnSetID As String

Remarks

MMC allows the user to customize the appearance of a list view by using the "Choose Columns…" option on the "View" menu and by clicking the column headers to change the sort parameters. MMC persists these settings as the user navigates between nodes in the scope pane and restores them when the user returns to a previously customized node. The snap-in can examine these settings and make changes to them by using View.ColumnSettings and View.SortSettings. Both of those properties are indexed by ColumnSetID.

The value of ColumnSetID for a particular node in the scope pane is kept in ScopePaneItem.ColumnSetID and its value defaults to the node type GUID (ScopePaneItem.ScopeItem.ScopeNode.NodeTypeGUID).

Requires MMC 1.2 or greater. For more information see "Using Column Persistence".


DisplayMessageView Method

The DisplayMessageView method displays a message view in the result pane. If the node represented by the ScopePaneItem is not currently selected in the scope pane then it will be selected.

Syntax

ScopePaneItem.DisplayMessageView(TitleText As String, BodyText As String, IconType As SnapInMessageViewIconTypeContants)

The DisplayMessageView method syntax has these parts:

Part | Description
TitleText | Text for the title of the message view.
BodyText | Text for the body of the message view.
IconType | Icon for the message view.

IconType can be one of the following:

siIconError | The message view displays the error icon. Same as vbCritical in a message box.
siIconInformation | The message view displays the information icon. Same as vbInformation in a message box.
siIconNone | The message view does not display an icon.
siIconQuestion | The message view displays the question mark icon. Same as vbQuestion in a message box.
siIconWarning | The message view displays the warning icon. Same as vbExclamation in a message box.

Remarks

A message view consists of an OCX supplied by MMC that displays a title, some text, and an icon. Available only in MMC 1.2 or greater.

This event will cause the ScopePaneItems_GetResultViewInfo and ScopePaneItems_GetResultView events to be fired for the node. The snap-in should ignore these events.


DisplayNewResultView Method

The DisplayNewResultView method displays a new result view in the result pane. If the node represented by the ScopePaneItem is not currently selected in the scope pane then it will be selected.

Syntax

ScopePaneItem.DisplayNewResultView(DisplayString As String, ViewType As SnapInResultViewTypeContants)

The DisplayNewResultView method syntax has these parts:

Part | Description
DisplayString | Set according to the value of ViewType. See below.
ViewType | Determines the type of result view.

ViewType and DisplayString can be a combination of the following:

siURLView | Navigate to a URL in the result pane. DisplayString contains the URL.
siOCXView | Display an ActiveX control in result pane. DisplayString contains the ProgId of the control.
siTaskpad | Display a snap-in taskpad in the result pane. DisplayString contains a res:// URL to path of default taskpad template followed by "#" and then the group name. See the MMC C++ documentation for IComponent::GetResultViewType for details on this format.
siListpad | Display a list view taskpad in the result pane. DisplayString contains a res:// URL to path of default list view taskpad template followed by "#" and then the group name. See the MMC C++ documentation for IComponent::GetResultViewType for details on this format.
siCustomTaskpad | Display a custom taskpad in the result pane. DisplayString contains a res:// URL to path of taskpad template followed by "#" and then the group name. See the MMC SDK documentation for IComponent::GetResultViewType for details on this format.
siListView | Display a list view. DisplayString is empty.
siMessageView | Display a list view. DisplayString is empty.
siPreDefined | Display a result view defined at design time. DisplayString contains the name of a result view defined in the designer window in the Visual Basic IDE.

Remarks

This event will cause the ScopePaneItems_GetResultViewInfo and ScopePaneItems_GetResultView events to be fired for the node. The snap-in should ignore these events.

For displaying a message view it is more convenient to call ScopePaneItem.DisplayMessageView.


ResultViewDisplayString Property

Platform SDK: Management Console

DisplayString Property

The DisplayString property together with the ResultViewType property determine the result view displayed in the result pane when the node represented by a ScopePaneItem is selected in the scope pane.

Syntax

ScopePaneItem.ResultViewDisplayString As String

Remarks

See "DisplayNewResultView" for the possible settings of DisplayString.

This property and ScopePaneItem.ResultViewType have slightly different meanings depending on when they are set or retrieved. The following explains the possible uses of these properties:

The snap-in can set ScopePaneItem.ResultViewType and ScopePaneItem.DisplayString and then call View.SelectScopeItem to initiate the display of a new result view.

The snap-in can call ScopePaneItem.DisplayNewResultView to accomplish the same effect as #1.

The snap-in can call ScopePaneItem.DisplayMessageView. This is the same as calling ScopePaneItem.DisplayNewResultView(siMessageView, "")

The snap-in can call View.SelectScopeItem and set these properties in ScopePaneItems_GetResultViewInfo.

In all of the above cases the snap-in will receive the ScopePaneItems_GetResultViewInfo event. Upon entry to that event ScopePaneItem.ResultViewType and ScopePaneItem.DisplayString will have the values set in cases 1, 2, or 3 or their default values for case 4. (See "GetResultViewInfo" for an explanation of how the defaults are set). If the snap-in changes the ViewType and DisplayString parameters in that event then the designer runtime sets ScopePaneItem.ResultViewType and ScopePaneItem.DisplayString from those values.

At any time following the ScopePaneItems_GetResultViewInfo event while a node is selected in the scope pane, the snap-in can examine ScopePaneItem.ResultViewType and ScopePaneItem.DisplayString to check what type of result view is being displayed.


HasListViews Property

The HasListViews property indicates whether the scope pane item can display list views. The setting of this property determines whether view menu options (List, Details, Report, and so on) are enabled in the console.

Syntax

HasListViews As Boolean

Remarks

The default value for this property is set when the scope pane item is first created. Its value is determined by the presence of predefined list views for the scope item. If the snap-in displays a list view for the scope pane item at any time then the runtime sets this property to True. Other than these two circumstances the snap-in controls the value of this property. If the snap-in needs to change its value then this should be done in either the ScopePaneItems_GetResultViewInfo or ScopePaneItems_GetResultView event.


Index Property

Returns the index of the ScopePaneItem in the ScopePaneItems collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Returns the key of the ScopePaneItem in the ScopePaneItems collection.

Syntax

Key As String

Remarks

Name and key should always have the same value. This property is initialized with the value of ScopePaneItem.ScopeItem.Key.


Name Property

Returns the name of the ScopePaneItem in the ScopePaneItems collection.

Syntax

Name As String

Remarks

Name and key should always have the same value. This property is initialized with the value of ScopePaneItem.ScopeItem.Key.


Parent Property

The Parent property returns the ScopePaneItems collection to which the ScopePaneItem belongs. Read-only.

Syntax

Parent As ScopePaneItems

Remarks

Built on Wednesday, October 27, 1999


ResultView Property

If the scope pane item is currently selected then the ResultView property returns the ResultView object that is currently displayed in the result pane. Read-only.

Syntax

ResultView As ResultView

Remarks

Built on Wednesday, October 27, 1999


ResultViews Property

The ResultViews property returns the collection of result views owned by the scope pane item. Read-only.

Syntax

ResultViews As ResultViews

Remarks

Built on Wednesday, October 27, 1999


ResultViewType Property

The ResultViewType property together with the DisplayString property determine the result view displayed in the result pane when the node represented by a ScopePaneItem is selected in the scope pane.

Syntax

ResultViewType As SnapInResultViewTypeConstants

Remarks

See "DisplayNewResultView" for the possible settings of ResultViewType.

This property and ScopePaneItem.DisplayString have slightly different meanings depending on when they are set or retrieved. The following explains the possible uses of these properties:

The snap-in can set ScopePaneItem.ResultViewType and ScopePaneItem.DisplayString and then call View.SelectScopeItem to initiate the display of a new result view.

The snap-in can call ScopePaneItem.DisplayNewResultView to accomplish the same effect as #1.

The snap-in can call ScopePaneItem.DisplayMessageView. This is the same as calling ScopePaneItem.DisplayNewResultView(siMessageView, "")

The snap-in can call View.SelectScopeItem and set these properties in ScopePaneItems_GetResultViewInfo.

In all of the above cases the snap-in will receive the ScopePaneItems_GetResultViewInfo event. Upon entry to that event ScopePaneItem.ResultViewType and ScopePaneItem.DisplayString will have the values set in cases 1, 2, or 3 or their default values for case 4. (See "GetResultViewInfo" for an explanation of how the defaults are set). If the snap-in changes the ViewType and DisplayString parameters in that event then the designer runtime sets ScopePaneItem.ResultViewType and ScopePaneItem.DisplayString from those values.

At any time following the ScopePaneItems_GetResultViewInfo event while a node is selected in the scope pane, the snap-in can examine ScopePaneItem.ResultViewType and ScopePaneItem.DisplayString to check what type of result view is being displayed.


ScopeItem Property

The ScopeItem property holds a reference to the ScopeItem that the ScopePaneItem represents in the scope pane of its view. Read-only.

Syntax

ScopeItem As ScopeItem

Remarks

Built on Wednesday, October 27, 1999


Tag Property

The Tag property can be used to hold snap-in-defined data associated with the ScopePaneItem.

Syntax

Tag As Variant


ResultViews

The ResultViews collection represents the collection of result views displayed in the result pane by its owning ScopePaneItem. ResultView represents a single result view. The developer does not directly create result views — they are created by the designer runtime when needed. As with the other objects, all events are on the collection and each has a parameter that is the ResultView for which the event applies.

The Initialize event is called when a ResultView is created. If the result pane will contain a list view then the Initialize event is a good opportunity to populate the list view. For list views defined in code, column headers should be added at this time. This event is also used for setting list view properties such as HideSelection, LexicalSort, MultiSelect, ShowChildScopeItems, Virtual, and sorting properties if they were not set at design time. This event should also be used to hide columns if needed. If the result pane will contain a taskpad then tasks can be hidden at this time. If the result pane will contain an OCX view then ResultView.AlwaysCreateNewOCX can be set at this time to disable OCX caching. See "ResultView" for more information on OCX caching.

InitializeControl is fired when an ActiveX control in an OCX view is created. The snap-in can access the control in ResultView.Control. If the control is cached then this event is received only once when the control is first created. If the result view is displayed again then ResultView.Control can be accessed starting in the ResultViews_Activate event.

Activate is called when the result view is about to be displayed. It can also be used for list view population. If a result view is cached, it will receive Activate when it is about to be reused. See "ScopePaneItems" for more information on result view caching.

Deactivate is called when the result view is about to be removed from the result pane. If the snap-in needs to cache the result view it can return Keep=True from this event. If the snap-in needs to override the user's column customization or sort settings it should do so during this event. For more information see "Using Column Persistence."

Terminate is called when the result view is destroyed.

ListItemDblClick is called when the user double-clicks a list item. ScopeItemDblClick is called when the user double-clicks a scope item in the result pane. Both events have a DoDefault parameter that if returned as True indicates to MMC to take the default action. If the event is not handled or DoDefault is not changed then the default action will occur. Default action for a scope item is to select it in the scope pane and expand it. Default action for a list item is the default verb. The default verb is open unless the snap-in changes it in the Views_Select event. Double-clicking a scope item in the scope pane does not fire an event because MMC always expands or collapses the node in response to this action.

ColumnClick is called when the user clicks a column header to initiate sorting. MMC begins the sort operation following this event.

CompareItems is called during a sort operation to allow the snap-in to do customized sorting (for example, comparing dates or other binary fields). If the snap-in does not handle this event or its handler does not return a result then the designer runtime does a case-insensitive comparison of the column text. In MMC 1.1 this event is only passed list items. This is because MMC 1.1 does not support sorting child scope items in the result pane. In MMC 1.2 CompareItems can receive any combination of both list items and scope items. This allows the snap-in to determine how child scope items will be sorted in the result pane.

ColumnsChanged is called when the user has customized the column settings using the Choose Columns dialog box from MMC's View menu. If the snap-in returns Persist=True (the default) then MMC will persist the user's changes. If the user selects another node in the scope pane with the same column set ID or returns to this node then the column settings will be preserved. See "ScopePaneItem" for more information on setting the column set ID.

ItemRename is called if the snap-in enabled the rename verb in Views_Select and the user selected Rename from the context menu or used a slow double-click to initiate the rename operation.

ItemViewChange is called in every result view when the snap-in calls MMCListItem.UpdateAllViews. This is useful for operations like rename where the action occurs in one view but other views are potentially displaying the same list item. The snap-in should check whether it is displaying the same list item and update MMCListItem.Text and MMCListItem.ListSubItems accordingly.

PropertyChanged is called when a property page calls MMCListItem.PropertyChanged to inform the snap-in of changes made in the property sheet.

FilterChange is called for filtered list views when the user changes the filter value and the time-out designated by MMCListView.FilterChangeTimeout has elapsed. The snap-in can examine the new value in MMCColumnHeader.TextFilter or MMCColumnHeader.NumericFilter.

FilterButtonClick is fired when the user clicks the filter button. The snap-in should display a pop-up menu using View.PopupMenu to allow the user to change the filter criteria.

For virtual list views, a number of events are fired as MMC needs information to populate the list view. GetVirtualItemDisplayInfo is fired when MMC needs the list item and list subitem text. GetVirtualItemData is fired to allow the snap-in to set exported data for extensions in MMCListItem.Data and to enable dynamic extensions for the list item using MMCListItem.DynamicExtensions. SortItems is fired to inform the snap-in that list items will be fetched in sorted order on a particular column. CacheHint is fired to allow the snap-in to begin asynchronous fetching of data for list items that are likely to be displayed soon. FindItem is fired when the user searches for items by typing the initial letters. DeselectAll is fired when the user deselects everything in the list view so that the snap-in can update console verbs and toolbars.

TaskClick is fired when the user clicks a task in a taskpad. TaskNotify is fired when a custom taskpad calls MMCCtrl.TaskNotify. For more information on using MMCCtrl on a custom taskpad DHTML page see the MMC SDK documentation.

ListpadButtonClick is fired when the user clicks the button on a list view taskpad.

Syntax

ResultView As ResultView

Properties

Count | Count of ResultView objects in the collection.
Item | References a ResultView object in the collection by index or key.

Methods

This object has no methods.

Events

These events will appear in the Visual Basic code as ResultViews_<EventName>.

Activate | Called when a result view is about to be shown in the result pane.
CacheHint | Virtual lists only. Called to allow the snap-in to start asynchronous caching of list items that will likely be displayed.
ColumnClick | Called when the user clicks a list view column header.
ColumnsChanged | Called when the user makes a change to the column configuration in a list view.
CompareItems | Non-virtual lists only. Called during a sort operation to allow the snap-in to do custom comparison of items in the result pane.
Deactivate | Called when a result view is being removed from the result pane.
DeselectAll | Virtual lists only. Called when all items in the specified list view have been deselected.
FilterButtonClick | Called when the user clicks the filter button on the header control.
FilterChange | Called when the user has made a change to the filter value for a column.
FindItem | Virtual lists only. Called to find the ordinal index of an item by name.
GetVirtualItemData | Virtual lists only. Called to allow the snap-in to initialize MMCListItem.Data.
GetVirtualItemDisplayInfo | Virtual lists only. Called when the snap-in must initialize display properties for a list item.
Help | Called when the user has requested help for the specified result view item.
Initialize | Called when a ResultView object is created.
InitializeControl | Called when an ActiveX control is created in a result pane.
ItemRename | Called when the user requests to rename the specified list item.
ItemViewChange | Called when the result view needs to be refreshed in response to an MMCListItem.UpdateAllViews() call.
ListItemDblClick | Called when the user double clicks on a list item.
ListpadButtonClick | Called when the user has clicked the button on a snap-in list view taskpad.
PropertyChanged | Called when a property page calls MMCListItem.PropertyChanged to inform the snap-in of changes made in the property sheet.
ScopeItemDblClick | Called when the user double clicks on a scope item in the result pane.
SortItems | Virtual lists only. Called to inform the snap-in that the list items will be fetched in sorted order.
TaskClick | Called when the user has clicked a task on a snap-in taskpad.
TaskNotify | Called from a custom taskpad when script has called MMCCtrl.TaskNotify.
Terminate | Called when a ResultView object is about to be destroyed.

Remarks

Built on Wednesday, October 27, 1999


Activate Event

The Activate event informs the snap-in that the ResultView is about to be displayed in the result pane..

Syntax

Private Sub ResultViews_Activate(ResultView As ResultView)

The Activate event syntax has these parts:

Part | Description
ResultView | The ResultView object that is about to be displayed.

Remarks

The snap-in should ensure that the result view is initialized and populated. If the result pane is a list view and a predefined list view is not being used, the snap-in should set column headers and images if it did not do so in ResultViews_Initialize. For any list view the snap-in should populate ResultView.ListView.ListItems if it did not do so in ResultViews_Initialize. For OCX result views, control properties can be set at this time by accessing ResultView.Control.

This event is particularly important for cached result views as in that case the snap-in does not receive the ResultViews_Initialize event. A result view is cached when a snap-in returns Keep = True from the ResultViews_Deactivate event and specifies reuse of the result view in the ScopePaneItems_GetResultView event.

For non-cached result views, the initialization tasks can be performed in this event or in ResultViews_Initialize.

For virtual list views, the snap-in must call ResultView.ListView.ListItems.SetItemCount in this event so that MMC will know how to display its scroll bars and request display information for the correct item numbers.


CacheHint Event

Virtual lists only. The CacheHint event informs the snap-in that the specified range of items is likely to be viewed by the user. This gives the snap-in the opportunity to begin an asynchronous fetch of the data that will be needed.

Syntax

Private Sub ResultViews_CacheHint(ResultView As ResultView, [in] long StartingIndex, [in] long EndingIndex)

The CacheHint event syntax has these parts:

Part | Description
ResultView | ResultView object for which the event items might be requested.
StartingIndex | The starting index at which items might be requested.
EndingIndex | The ending index at which items might be requested.

Remarks

Snap-ins typically use a virtual list because the number of list items is large or because acquiring the list item display information is costly. This event allows the snap-in to initiate asynchronous data fetching so that likely upcoming requests from the user to view the specified range of list items will have a quick response time. Note that there is no guarantee that the snap-in will receive subsequent ResultViews_GetVirtualItemDisplayInfo events for the specified range of list items.


ColumnClick Event

The ColumnClick event informs the snap-in that a list view's column header was clicked.

Syntax

Private Sub ResultViews_ColumnClick(ResultView As ResultView, ColumnNumber As Long, SortOrder As SnapInSortOrderConstants)

The ColumnClick event syntax has these parts:

Part | Description
ResultView | ResultView in which the column header was clicked.
ColumnNumber | The number of the column whose header was clicked.
SortOrder | The sort order: siAscending or siDescending.

Remarks

This event allows the snap-in to monitor sorting changes initiated by the user. For non-virtual lists no action is required as the designer runtime has all of the display data. The snap-in should not initiate a sort of the list view in response to this event as MMC will do so. The snap-in will receive subsequent ResultViews_CompareItems events during the sorting operation.

For virtual lists, the snap-in will receive a subsequent ResultViews_SortItems event to request that it prepare its data for subsequent ResultViews_GetVirtualItemDisplayInfo events in the specified sort order.


ColumnsChanged Event

The ColumnsChanged event informs the snap-in that the user has changed the column configuration by using the "Choose Columns…" option from the "View" menu.

Syntax

Private Sub ResultViews_ColumnsChanged(ResultView As ResultView, Columns, Persist As Boolean)

The ColumnClick event syntax has these parts:

Part | Description
ResultView | ResultView in which the column configuration was changed.
Columns | Array of numbers of visible columns in the order set by the user
Persist | Set to True to allow MMC to persist the column settings for the node.

Remarks

This event allows the snap-in to accept or reject the user's column configuration change. If the snap-in chooses to reject it by setting Persist to False then it should display a message to the user explaining why.

The Columns parameter contains an array of the column numbers of visible columns in the order set by the user. For example, consider a list view with four columns. If the user moved column 3 before column 2 and hid column 4, then the array would contain the numbers 1, 3, 2.

If the snap-in accepts the change then it can use the information to optimize fetching of display data by omitting the data for hidden columns.

Requires MMC 1.2 or greater.


CompareItems Event

The CompareItems event is fired when a sort operation is in progress in a non-virtual list view.

Syntax

Private Sub ResultViews_CompareItems(ResultView As ResultView, Object1 As Object, Object2 As Object, Column As Long, Result) As Integer

The CompareItems event syntax has these parts:

Part | Description
ResultView | The ResultView in which the sorting operation is taking place.
Object1 | The first object to compare. Can be a ScopeItem or MMCListItem.
Objec2 | Can be a ScopeItem or MMCListItem.
Column | The column on which the sort is occurring
Result | Result of comparison returned here: -1 Object1 < Object2 0 Object1 = Object2 1 Object1 > Object2

Remarks

If the snap-in does not handle this event or its handler does not set Result then the designer runtime does a case-insensitive comparison of the column text.

In MMC 1.1 Object1 and Object2 will always be MMCListItem objects. This is because MMC 1.1 does not support sorting child scope items in the result pane. In MMC 1.2 Object1 and Object2 can be any combination of MMCListItem and ScopeItem objects. This allows the snap-in to determine how child scope items will be sorted in the result pane. The snap-in should check the type of the object using the TypeOf keyword e.g.

If (TypeOf Object1 Is MMCListItem) And _
(TypeOf Object2 Is MMCListItem) Then
    …do list item comparison…
End If

The comparison operation is independent of the sort direction (ascending or descending). The console interprets the result according to the direction.

Result should be set as follows:

  • 0 if the objects are lexically equivalent.
  • – 1 if Object1 is lexically lower than Object2.
  • 1 if Object1 is lexically greater than Object2
The meaning of the comparison is defined by the snap-in. For example, the FileExplorer sample supports sorting on the "Date" column in its list views. It does this by handling ResultViews_CompareItems and doing a comparison of the file or folder last modification date.

Snap-ins can also do customized multicolumn sorting but it is up to the snap-in to translate the request to sort on a single column to its custom sorting algorithm.


Count Property

The Count property represents the number of ResultViews in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


Deactivate Event

The Deactivate event informs the snap-in that the result view is about to be replaced in the result pane. This can occur because the user selected a different result view on the same scope item or because a new scope item was selected.

Syntax

Private Sub ResultViews_Deactivate(ResultView As ResultView, Keep As Boolean)

The Deactivate event syntax has these parts:

Part | Description
ResultView | The ResultView being deactivated
Keep | Determines whether the ResultView object should be destroyed or kept in its owning ScopePaneItem.ResultViews collection.

Remarks

If Keep is set to True then the ResultView remains in the owning ScopePaneItem.ResultViews collection and can be reused when the node is again selected in the scope pane by handling ScopePaneItems_GetResultView.

This technique is known as result view caching. It can be useful if the contents of the result view are costly to produce and the snap-in knows that the user will likely return to the node. If the snap-in caches the result view and then specifies its reuse in the ScopePaneItems_GetResultView event, then ResultViews_Initialize will not be fired again – the snap-in will only receive ResultViews_Activate when the cached result view is shown.

A cached result view will be destroyed when the owning view is destroyed or when the snap-in is removed from the console. The owning view is destroyed when the user closes the view's window or closes MMC.


DeselectAll Event

Virtual lists only. The DeselectAll event informs the snap-in that all items in the list view were deselected. The snap-in should enabled/disable console verbs, toolbar buttons, and menu buttons as appropriate.

Syntax

Private Sub ResultViews_DeselectAll(ResultView As ResultView, ConsoleVerbs As MMCConsoleVerbs, Controlbar As MMCControlbar)

The DeselectAll event syntax has these parts:

Part | Description
ResultView | The ResultView in which the deselection occurred
ConsoleVerbs | MMCConsoleVerbs collection used to update the console verbs
Controlbar | MMCControlbar object used to update

Remarks

The snap-in uses this event to set the state of the console verbs. Console verbs are enabled and disabled using the MMCConsoleVerbs collection indexed by SnapInConsoleVerbConstants. For example, to enable the print verb use:

ConsoleVerbs(siPrint).Enabled = True

For more information see "MMConsoleVerbs".

The snap-in can update the state of its toolbar and menu buttons by using MMCButton and MMCButtonMenu properties.

The snap-in can attach and detach toolbars and menu buttons to and from MMC's controlbar by calling MMCControlbar.Attach and MMCControlbar.Detach.

The MMCConsoleVerbs and MMCControlbar objects can only be used during this event handler and the snap-in should not store a reference to it.


FilterButtonClick Event

The FilterButtonClick event is fired when the user clicks the small funnel button on the right hand side of the column header in a filtered view.

Syntax

Private Sub ResultViews_FilterButtonClick(ResultView As ResultView, Column As MMCColumnHeader, Left As Long, Top As Long, Height As Long, Width As Long)

The FilterButtonClick event syntax has these parts:

Part | Description
ResultView | The ResultView in which the filter button was clicked
Column | MMCColumnHeader object representing the column that was clicked.
Left | Horizontal position of top left corner of the filter button in screen coordinates.
Top | Vertical position of top left corner of the filter button in screen coordinates.
Height | Height of the filter button in screen coordinates.
Width | Width of the filter button in screen coordinates.

Remarks

The user typically clicks the filter button after entering a new filter value in the column header. If the snap-in handles this event it should display a popup menu to allow the user to choose a filter operator that interprets the filter value. The popup menu can be displayed by using CurrentView.PopupMenu. Filter values and operators are defined by the snap-in. For more information see "Using Column Filtering".

Requires MMC 1.2 or greater.


FilterChange Event

Platform SDK: Management Console

FilterChange

The FilterChange event is fired when the user has made a change to the filter value in the column header of a filtered view or has enabled or disabled filtering by switching to a different list view mode.

Syntax

Private Sub ResultViews_FilterChange ResultView As ResultView, Column As MMCColumnHeader, ChangeType As SnapInFilterChangeTypeConstants)

The FilterButtonClick event syntax has these parts:
Part | Description
ResultView | The ResultView in which the filter value was changed.
Column | MMCColumnHeader object representing the column for which the filter value was changed. Only used if ChangeType is siValueChange.
ChangeType | The type of change made by the user. See below.

ChangeType can be one of the following:

siDisable | The user has turned off filtering by switching to a different list view mode (e.g. detail or list)
siEnable | The user has turned on filtering by switching the list view to filtered mode.
siValueChange | The user has entered a new filter value in the column header. Column indicates the column in which the change occurred. The snap-in can get the new value from Column.TextFilter or Column.NumericFilter.

Remarks

ChangeType will be siValueChange if the user enters a new filter value and presses Enter or the interval specified by MMCListView.FilterChangeTimeout has passed.

If the user has changed the filter value then it is up to the snap-in to interpret it. MMC only fires this event.

For more information see "Using Column Filtering".

Requires MMC 1.2 or greater.


FindItem Event

Virtual lists only. Fired when the user presses character keys to navigate to a particular item in the list view.

Syntax

Private Sub ResultViews_FindItem(ResultView As ResultView, Name As String, StartingIndex As Long, Wrap As Boolean, PartialName As Boolean, Found As Boolean, Index As Long)

The FindItem event syntax has these parts:

Part | Description
ResultView | The ResultView in which the user is navigating the list view.
Name | Characters typed by the user so far.
StartingIndex | Index at which the snap-in should begin searching.
Wrap | Indicates whether the search should continue from the start of the data if the requested item is not found between StartingIndex and the end of the data.
PartialName | If True then the snap-in should consider an item that begins with Name as a match.
Found | Set to True if the snap-in found a matching item.
Index | If a matching item was found then return its index here.

Remarks

When a user navigates by typing characters in a non-virtual list view MMC performs the function of this event handler. In a virtual list view, MMC does not know the text for every item in the list view so it asks the snap-in to help by searching through its underlying data for a matching item. The snap-in should search its data using the following generalized algorithm:

While not item found and not at end of data
If current item's name matches Name then
 Item found
Else if PartialName and current item's name begins with Name then
 Item found
Else
If not last item then
current item = current item + 1
Else if Wrap then
current item = first item
Else
' at last item and Wrap is not requested
at end of data
End If
If current item is at StartingIndex then
at end of data ' wrapped around to the starting point
End if
End If
End While

For more information see "Using Virtual List Views".


GetVirtualItemData Event

Virtual lists only. The GetVirtualItemData event allows the snap-in to export data for a virtual list item.

Syntax

Private Sub ResultViews_GetVirtualItemData(ResultView As ResultView, ListItem As MMCListItem)

The GetVirtualItemData event syntax has these parts:

Part | Description
ResultView | The ResultView in which containing the list item
ListItem | MMCListItem object representing the virtual list item.

Remarks

MMC asks the snap-in for its data associated with a list item when the user performs an operation that may require it such as selection, copy, etc. The MMCListItem object passed to this event cannot be used after the event handler completes. The only properties of ListItem that will be set upon entry to this event are:

Index

ItemTypeGUID

ID

The snap-in should identify the underlying data based on ListItem.Index.

The snap-in can set any exported data by calling ListItem.Data.SetData.

The snap-in can also use this event to request that dynamic extensions for the list item by loaded by enabling them in ListItem.DynamicExtensions.

The snap-in can also change ListItem.ID and ListItem.ItemTypeGUID if needed.

The snap-in should not set ListItem.Text or add anything to ListItem.ListSubItems as these values will be discarded after the event handler completes. These properties are set for a virtual list item in the ResultViews_GetVirtualItemDisplayInfo event.

For more information see "Using Virtual List Views" and "Publishing and Interpreting Data Formats from a Visual Basic Snap-in".


GetVirtualItemDisplayInfo Event

Virtual lists only. The GetVirtualItemDisplayInfo event allows the snap-in to set the item text and column text for a virtual list item.

Syntax

Private Sub ResultViews_GetVirtualItemDisplayInfo(ResultView As ResultView, ListItem As MMCListItem)

The GetVirtualItemDisplayInfo event syntax has these parts:

Part | Description
ResultView | The ResultView in which containing the list item
ListItem | MMCListItem object representing the virtual list item.

Remarks

MMC asks the snap-in for its display information for a list item when the list item is displayed in the result pane. The MMCListItem object passed to this event cannot be used after the event handler completes. The only properties of ListItem that will be set upon entry to this event are:

Index

ItemTypeGUID

ID

ListItem.ItemTypeGUID and ListItem.ID will have default values. If the snap-in changed these properties in a prior ResultViews_GetVirtualItemData event, those values will not appear in this event.

The snap-in should identify the underlying data based on ListItem.Index and set ListItem.Text and populate ListItem.ListSubItems. The snap-in should not change any other properties of ListItem as they will be discarded when the event handler completes. Other properties such as ListItem.Data are set for a virtual list item in the ResultViews_GetVirtualItemData event.

For more information see "Using Virtual List Views" and "Publishing and Interpreting Data Formats from a Visual Basic Snap-in".


Help Event

The Help event informs the snap-in that the user has requested help for the specified list item.

Syntax

Private Sub ResultViews_Help(ResultView As ResultView, ListItem As MMCListItem)

The Help event syntax has these parts:

Part | Description
ResultView | ResultView object in which the help request occurred.
ListItem | MMCListItem object for which the user requested help.

Remarks

This event is only fired if the snap-in is using merged HTML help by setting SnapIn.Help. The snap-in should call SnapIn.ShowHelpTopic to display help for the list item. See "Adding Help to a Snap-in" for more information.


Initialize Event

The Initialize event informs the snap-in that a new ResultView object has been created.

Syntax

Private Sub ResultViews_Initialize(ResultView As ResultView)

The Initialize event syntax has these parts:

Part | Description
ResultView | ResultView object that was created.

Remarks

This event is fired when the user selects a node owned by the snap-in in the scope pane and MMC has asked the snap-in to determine the type of result view that will be displayed.

Upon entry to this event the following properties will be initialized:

ResultView.AlwaysCreateNewOCX

ResultView.DefaultItemTypeGUID

ResultView.DisplayString

ResultView.Index

ResultView.ListView properties if using a predefined list view

ResultView.MessageView properties if the snap-in called ScopePaneItem.DisplayMessageView

ResultView.ScopePaneItem

ResultView.Taskpad properties if using a predefined taskpad

ResultVIew.Type

Properties that can be set during this event:

ResultView.Key

ResultView.Name

ResultView.Tag

ResultView.ListView properties

ResultView.Taskpad properties

ResultView.MessageView properties

ResultView.AlwaysCreateNewOCX

ResultView.DefaultItemTypeGUID

The designer runtime does not use ResultView.Key and ResultView.Name. The snap-in may set these properties as needed to identify the result view.

ResultView.SetDescBarText cannot be called during this event.

For non-virtual list views, the snap-in can use this event to populate column headers and list items.

For virtual list views, the snap-in should not call ResultView.ListView.ListItems.SetItemCount at this time. That call should be made in the ResultViews_Activate event.

Any properties that affect the display of the result view will not take effect until after the subsequent ResultViews_Activate event when the result view is displayed in the result pane.

This event is not fired for cached result views that are reused by handling the ResultViews_Deactivate and ScopePaneItems_GetResultView events.


InitializeControl Event

This event is fired for OCX result views when a new control is created. ResultView.Control is valid from this time forth. Snap-ins typically initialize the control's properties at this time.

Syntax

Private Sub ResultViews_InitializeControl(ResultView As ResultView)

The InitializeControl event syntax has these parts:

Part | Description
ResultView | ResultView in which the ActiveX control was created.

Remarks

If the snap-in set ResultVIew.AlwaysCreateNewOCX to True in the ResultViews_Initialize event then this event will be fired. If that property was not set, and the AcitveX control was previously used by the snap-in in the result pane then the snap-in will have access to ResultView.Control starting with the ResultViews_Activate event.


Item Property

The Item property returns a ResultView indexed by ordinal integer or by key. This is the default property.

Syntax

ResultViews.Item(Index) As ResultView

or

ResultViews(Index) As ResultView

The Item property syntax has these parts:

Part | Description
Index | Index or key of the ResultView in the collection.

Remarks

Built on Wednesday, October 27, 1999


ItemRename Event

The ItemRename event informs the snap-in that the user has invoked the rename verb by slowly double clicking the list item or clicking the rename context menu item.

Syntax

Private Sub ResultViews_ItemRename(ResultView As ResultView, ListItem As MMCListItem, NewName As String)

The ItemRename event syntax has these parts:

Part | Description
ResultView | ResultView in which the rename operation occurred
ListItem | MMCListItem objec the user has requested to rename
NewName | New name entered by the user.

Remarks

This event can only be fired if the snap-in enabled the rename verb in the Views_Select event. MMC does nothing more than fire the event. It is up to the snap-in to perform the operation on it is underlying data.


ItemViewChange Event

The ItemViewChange event informs the snap-in that the result view needs to be refreshed if it is displaying any of the list item's data. This event is fired in all views when the snap-in calls MMCListItem.UpdateAllVIews.

Syntax

Private Sub ResultViews_ListItemViewChange(ResultView As ResultView, ListItem As MMCListItem, Hint)

The ItemViewChange event syntax has these parts:

Part | Description
ResultView | ResultView in which the snap-in should update its displayed data
ListItem | The list item that was updated
Hint | The Hint parameter passed to MMCListItem.UpdateAllViews.

Remarks

The handler should not assume that the list item belongs to its own result view. For example, a list view displaying a directory might receive a file name change. It needs to notify all other listv views currently displayed by the snap-in in other views to update the file name but a particular view might not be displaying the file. The snap-in can use ListItem.Index, ListItem.Key, ListItem.ID, ListItem.Data, ListItem.Tag, ListItem.ItemTypeGUID or any other means necessary to uniquely identify the underlying object.

When a snap-in calls MMCListItem.UpdateAllViews from an event handler in a particular view, the event will be fired for the source view as well. The snap-in's event handler should detect that condition by checking whether the display data needs to be updated.


ListItemDblClick Event

The ListItemDblClick event informs the snap-in that the user double-clicked or pressed the Enter key on the specified list item.

Syntax

Private Sub ResultViews_ListItemDblClick(ResultView As ResultView, ListItem As MMCListItem, DoDefault As Boolean)

The ListItemDblClick event syntax has these parts:

Part | Description
ResultView | ResultView in which the double click occurred.
ListItem | MMCListItem on which the user pressed Enter or double clicked.
DoDefault | Set to True to request that MMC perform the default action.

Remarks

If the snap-in sets DoDefault to True then the console will take the default action. If DoDefault is False then the console will not respond to the double-click. The default value for DoDefault is True. If this event is not handled then the console will take the default action.

The default action depends on whether the snap-in has set the default verb. If the snap-in has not set the default verb then there is no default action. The snap-in can only make properties the default verb and it must be done in the Views_Select event as follows:

ConsoleVerbs(siProperties).Default = True


ListpadButtonClick Event

Used only in snap-in list view taskpads. The ListpadButtonClick event informs the snap-in that the user has clicked the button at the top right corner of the list view in the taskpad.

Syntax

Private Sub ResultViews_ListpadButtonClick(ResultView As ResultView)

The ListpadButtonClick event syntax has these parts:

Part | Description
ResultView | ResultView in which the user clicked the button.

Remarks

Snap-ins should respond to a listpad button click by changing the contents of list view in some way. For example, the DriveStats sample snap-in uses a listpad to display drive statistics. When the user clicks the listpad button the snap-in displays a form with a listbox that allows the user to choose a different drive. The snap-in changes the list view to display the statistics for the drive chosen by the user.


PropertyChange Event

Platform SDK: Management Console

PropertyChanged Event

The PropertyChanged is fired when a property page calls MMCListItem.PropertyChanged.

Syntax

Private Sub ResultViews_PropertyChanged(ResultView As ResultView, ListItem As MMCListItem, Data)

The PropertyChange event syntax has these parts:

Part | Description
ResultView | ResultView in which the list item is displayed.
ListItem | MMCListItem object on which the property page called PropertyChanged.
Data | Data parameter passed to MMCListItem.PropertyChanged

Remarks

The runtime handles the marshaling of the Data parameter between the property page thread and the snap-in thread. The contents of Data are defined by the snap-in. Typically this event handler will examine Data and make corresponding changes to the object represented by the list item.


ScopeItemDblClick Event

The ScopeItemDblClick event informs the snap-in that the user double-clicked or pressed the Enter key on the specified scope item in the result pane.

Syntax

Private Sub ResultViews_ScopeItemDblClick(ResultView As ResultView, ScopeItem As ScopeItem, DoDefault As Boolean)

The ScopeItemDblClick event syntax has these parts:

Part | Description
ResultView | ResultView in which the double click occurred.
ScopeItem | ScopeItem on which the user pressed Enter or double clicked.
DoDefault | Set to True to request that MMC perform the default action.

Remarks

If the snap-in sets DoDefault to True then the console will take the default action. If DoDefault is False then the console will not respond to the double-click. The default value for DoDefault is True. If this event is not handled then the console will take the default action.

The default action depends on whether the snap-in has set the default verb. If the snap-in has not set the default verb then there is no default action. The snap-in can only make properties the default verb and it must be done in the Views_Select event as follows:

ConsoleVerbs(siProperties).Default = True


SortItems Event

Virtual lists only. The SortItems event informs the snap-in that the virtual list must be sorted according to the specified column and sort order.

Syntax

Private Sub ResultViews_SortItems(ResultView As ResultView, Column As Long, SortOrder As SnapInSortOrderConstants)

The SortItems event syntax has these parts:

Part | Description
ResultView | ResultView in which the sort was requested
Column | Column on which the sort was requested
SortOrder | Direction of the sort: siAscending or siDescending

Remarks

The snap-in should do whatever is needed to sort the data and be prepared to respond to ResultViews_GetVirtualItemDisplayInfo events according to the new sort order.


TaskClick Event

The TaskClick event informs the snap-in that the user has clicked a task on a snap-in taskpad.

Syntax

Private Sub ResultViews_TaskClick(ResultView As ResultView, Task As Task)

The TaskClick event syntax has these parts:

Part | Description
ResultView | ResultView in which the task was clicked.
Task | Task object representing the task that was clicked.

Remarks

Built on Wednesday, October 27, 1999


TaskNotify Event

The TaskNotify event informs the snap-in that script code in a custom taskpad has called MMCCtrl.TaskNotify.

Syntax

TaskNotify(ResultView As ResultView, Arg, Param)

The TaskNotify event syntax has these parts:

Part | Description
ResultView | ResultView in which the custom taskpad is displayed.
Arg | The value of the pvArg parameter passed to MMCCtrl.TaskNotify.
Param | The value of the pvParam parameter passed to MMCCtrl.TaskNotify.

Remarks

If a node owned by the snap-in has both snap-in taskpad and custom taskpad result views, the custom taskpad should not call MMCCtrl.TaskNotify and pass a number in pvArg between zero and the number of tasks on the snap-in taskpad. If the node has more than one snap-in taskpad, then pvArg should not contain a number between zero and the greatest number of tasks on any snap-in taskpad.

For example, assume that a node has two result views: a snap-in taskpad with five tasks and a custom taskpad. The custom taskpad should not call MMCCtrl.TaskNotify and pass a number in pvArg between zero and five.

This restriction is due to the way in which MMC notifies the designer runtime of snap-in taskpad task clicks and MMCCtrl.TaskNotify calls. The designer runtime cannot distinguish between the two different events if the numbers are not distinct.


Terminate Event

The Terminate event informs the snap-in that the specified result view is being destroyed.

Syntax

Terminate(ResultView As ResultView)

The Terminate event syntax has these parts:

Part | Description
ResultView | ResultView being destroyed.

Remarks

If the snap-in did not cache the result view by setting Keep to True in the ResultViews_Deactivate event, then this event will be fired following ResultViews_Deactivate. If the snap-in did cache a result view, then it will be destroyed when the owning view is destroyed or when the snap-in is removed from the console. The owning view is destroyed when the user closes the view's window or closes MMC.


ResultView

The ResultView object encapsulates the properties of the result pane. It contains objects that control the properties of the list view, taskpad, and message view.

The Type and DisplayString properties are read-only copies of the owning ScopePaneItem's properties. See "ScopePaneItem" for more information.

ScopePaneItem contains a reference to the ScopePaneItem that owns the ResultView.

The Control property contains a reference to the ActiveX control in the result pane when the ResultView is an OCX view. Control can be assigned to a variable of the control's type in order to make access to its properties and methods more efficient. For example:

Dim Ctl As MyControl
Set Ctl = ResultView.Control
Ctl.SomeProperty = SomeValue

AlwaysCreateNewOCX determines whether MMC will cache the ActiveX control in an OCX view. The default is False meaning that MMC will cache. If caching is not desirable then this property should be set to True in ResultViews_Initialize.

ListView is a reference to an MMCListView object that encapsulates the properties of the list view. It is used when the ResultView is a list view and also when it is a list view taskpad. See "MMCListView" for more information.

Taskpad is a reference to a Taskpad object that encapsulates the properties of a snap-in taskpad. It is used when the ResultView is a taskpad or a list view taskpad. See "Taskpad" for more information.

MessageView is a reference to an MMCMessageView object that encapsulates the properties of a message view. It is used when the ResultView is a message view. See "MMCMessageView" for more information.

DefaultItemTypeGUID is used as the node type for list items in a list view. When a list item is created its ItemTypeGUID property is set from this value. For list views defined at design time it is generated by the designer. If the list view is extensible then the node type is registered under MMC's NodeType key in the registration database. For list views defined in code it is generated by the designer runtime. The snap-in can change DefaultItemTypeGUID and it can change ItemTypeGUID for individual list items, but in that case the developer is responsible for the registration database entries.

SetDescBarText inserts text into the result pane's description bar. The description is not visible by default. The user must request to make it visible using MMC's View menu in MMC 1.1 or using the Customize dialog box from the View menu in MMC 1.2.

Syntax

ResultView As ResultView

Properties

AlwaysCreateNewOCX | Determines whether an ActiveX control is cached.
Control | Gives the snap-in access to the ActiveX control in an OCX result view
DefaultItemTypeGUID | Default value assigned to MMCListITem.ItemTypeGUID for list items in a list view.
DisplayString | Together with Type indicates the type of result view.
Index | Index of the ResultView in its owning ResultViews collection.
Key | Key of the ResultView in its owning ResultViews collection.
ListView | MMCListView object used when result view contains a list view.
MessageView | MMCMessageView object used when result view contains a message view.
Name | For snap-in use to identify the ResultView object.
ScopePaneItem | ScopePaneItem object that owns the ResultView object.
Tag | For snap-in use to associate data with the ResultView object.
Taskpad | Taskpad object used when the result view contains a snap-in taskpad.
Type | Together with DisplayString indicates the type of result view.

Methods

SetDescBarText Sets the text in MMC's description bar for the result view.

Events

This object has no events.


AddToViewMenu Property

Platform SDK: Management Console

AlwaysCreateNewOCX Property

The AlwaysCreateNewOCX property controls ActiveX control caching in MMC.

Syntax

ResultView. AlwaysCreateNewOCX As Boolean

Remarks

When a node first uses an ActiveX control in a result view, MMC creates the control. If AlwaysCreateNewOCX is True then MMC will destroy the control when the result view is destroyed. If AlwaysCreateNewOCX is False then MMC will keep a reference to the control and reuse it the next time a node from the snap-in uses the control in a result view.

The default is value of this property is False meaning that MMC will cache the control. If caching is not desirable then this property should be set to True in ResultViews_Initialize.


Control Property

The Control property contains a reference the ActiveX control created by MMC for an OCX result view. Read-only.

Syntax

ResultView.Control As Object

Remarks

For a newly created control, this property is available beginning with the ResultViews_InitializeControl event. For a cached control, it is available from the ResultViews_Activate event.


DefaultItemTypeGUID Property

List views only. The DefaultItemTypeGUID property specifies the GUID that is used as the default item type identifier if MMCListItem.ItemTypeGUID is not explicitly set by the snap-in.

Syntax

ResultView.DefaultItemTypeGUID As String

Remarks

Every list item in a list view is identified by an item type GUID for the purpose of loading extension snap-ins. When a list item is created its ItemTypeGUID property is assigned the value of DefaultItemTypeGUID.

For list views defined at design time, the designer runtime generates the value of this property and uses the same value for all instances of the list view. If the list view is marked as extensible at design time, then the designer adds a key for it under MMC's NodeTypes key in the registration database using this value so that other snap-ins can extend its list items.

For list views defined in code, the runtime generates a GUID when the result view is created. The snap-in can change the value of DefaultItemTypeGUID in the ResultViews_Initialize event before it creates any list items.


ResultViewDisplayString Property

Platform SDK: Management Console

DisplayString Property

The DisplayString property together with the Type property indicate the type of the result view. Read-only.

Syntax

ResultView.DisplayString As String

Remarks

For settings of DisplayString and Type see "ScopePaneItem".


Index Property

Ordinal index of the ResultView in its owning ResultViews collection.

Syntax

ResultView.Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Key of the ResultView in its owning ResultViews collection.

Syntax

ResultView.Key As String

Remarks

The designer runtime does not use the Key property. The snap-in may change it as desired to identify the ResultView object.


ListView Property

The ListView property is an MMCListView object that is a simplified version of Visual Basic's ListView control. It is used when the result view type is a list view to manage the collection of rows and columns and their corresponding headers and icons. Read-only.

Syntax

ResultView.ListView As MMCListView

Remarks

The properties of ResultView.ListView should generally be initialized in the ResultViews_Initialize event. When using a cached result view, ResultView.ListView should be initialized in the ResultViews_Activate event. A cached result view is used when the snap-in sets Keep to True in the ResultViews_Deactivate event and specifies its reuse in the ScopePaneItems_GetResultView event.

When using a predefined list view, ResultView.ListView will be initialized with all of the properties set at design time before the ResultViews_Initialize event.


MessageView Property

The MessageView property is an MMCMessageView object that gives the snap-in access to a message view in the result pane. Read-only.

Syntax

ResultView.MessageView As MMCMessageView

Remarks

If the snap-in called ScopePaneItem.DisplayMessageView to display the message view then there is no need to initialize the properties of the MMMCMessageView object. If the snap-in displayed the message view by specifying it in the ScopePaneItems_GetResultViewInfo event then the properties of ResultView.MessageView should be initialized in the ResultViews_Initialize event. When using a cached result view, ResultView.MessageView should be initialized in the ResultViews_Activate event. A cached result view is used when the snap-in sets Keep to True in the ResultViews_Deactivate event and specifies its reuse in the ScopePaneItems_GetResultView event.

Requires MMC 1.2 or greater.


Name Property

The Name property can be used to identify the ResultView object in Visual Basic code. This is the default property.

Syntax

ResultView.Name As String

Remarks

The designer runtime does not use the Name property. The snap-in may change it as desired to identify the ResultView object.


ScopePaneItem Property

The ScopePaneItem property contains the ScopePaneItem object that owns the result view. Read-only.

Syntax

ResultView.ScopePaneItem As ScopePaneItem

Remarks

Built on Wednesday, October 27, 1999


SetDescBarText Method

The SetDescBarText method sets the description bar text in the result pane.

Syntax

ResultView.SetDescBarText(Text As String)

The SetDescBarText method syntax has these parts:

Part | Description
Text | Text to display in the description bar.

Remarks

The description bar is a status bar at the top of the result pane. It is not displayed by default but the user can request its display by using "Customize…" on the "View" menu in MMC 1.2 or clicking "Description Bar" on the "View" menu in MMC 1.1.


Tag Property

The Tag property can be used by the snap-in-to associate data with the result view.

Syntax

ResultView.Tag As Variant

Remarks

Built on Wednesday, October 27, 1999


Taskpad Property

The Taskpad property is a TaskPad object that gives the snap-in access to the properties of a snap-in taskpad in the result pane. Read-only.

Syntax

ResultView.Taskpad As Taskpad

Remarks

The properties of ResultView.Taskpad should be initialized in the ResultViews_Initialize event. When using a cached result view, ResultView.Taskpad should be initialized in the ResultViews_Activate event. A cached result view is used when the snap-in sets Keep to True in the ResultViews_Deactivate event and specifies its reuse in the ScopePaneItems_GetResultView event.

When using a predefined taskpad, ResultView.Taskpad will be initialized with all of the properties set at design time before the ResultViews_Initialize event. If a snap-in needs to hide a task on a predefined taskpad, then it should set ResultView.Taskpad.Tasks(<key>).Visible = False in the ResultViews_Initialize event.


ResultViewType Property

Platform SDK: Management Console

Type Property

The Type property together with the DisplayString property indicate the type of the result view. Read-only.

Syntax

ResultView.Type As SnapInResultViewTypeConstants

Remarks

For settings of DisplayString and Type see "ScopePaneItem".


MMCImageList

MMCImageList is similar to a Visual Basic Common Controls ImageList control and is used to hold images used in the scope pane, in the result pane, and in toolbars. Image lists can be created at design time or at run time using the New keyword. An image list created at design time becomes a module-level object in the snap-in at run time. It can be referenced by its design-time name, for example, ImageList1.Tag = 1.

Image lists can only contain bitmaps and all bitmaps in an image list must be the same size. Small bitmaps are 16X16 pixels and large bitmaps are 32x32 pixels.

MaskColor is used to determine which color pixel will be treated as transparent at run time. Pixels of this color will not be painted so that the underlying background will show through.

ListImages references an MMCImages collection containing the images.


Properties, Methods, and Events

Properties

ListImages | Collection of snap-in list image objects.
MaskColor | Pixels of this color will appear as transparent when an image from the list is rendered.
Name | Name used to identify the image list within Visual Basic code.
Tag | Get/set any extra data needed by the snap-in.

Methods

This object has no methods.

Events

This object has no events.


ListImages Property

The ListImages property is a collection of snap-in list image objects. The objects contain the images in the list.

Syntax

ListImages As MMCImages

Remarks

Built on Wednesday, October 27, 1999


MaskColor Property

Pixels of the color defined by the MaskColor property will appear as transparent when an image from the list is rendered.

Syntax

MaskColor As OLE_COLOR

Remarks

Built on Wednesday, October 27, 1999


Name Property

The Name property is the name used to identify the image list within Visual Basic code.

Syntax

Name As String

Remarks

Built on Wednesday, October 27, 1999


Tag Property

The Tag property can be used by the snap-in to associate data with the image list.

Syntax

Tag As Variant

Remarks

Built on Wednesday, October 27, 1999


MMCImages

MMCImages is a collection of MMCImage objects used by MMCImageList. It is a standard collection and the snap-in can both add and remove images at run time.


Properties, Methods, and Events

Properties

Count | Count of images in the collection.
Item | Get/set an image from the collection indexed by ordinal integer or by key.

Methods

Add | Adds a new image to the collection.
Clear | Removes all images from the collection.
Remove | Removes an image from the collection indexed by ordinal integer or by key.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Add Method

Adds a new image to the collection.

Syntax

Add([Index], [Key], [Picture]) As MMCImage

The Add method syntax has these parts:

Part | Description
Index | Index of new image. If not specified then image is appended.
Key | Key of new image. If not specified then key will be index as string.
Picture | StdPicture object. If not specified, the snap-in can set MMCImage.Picture.

Return Values

Returns a new MMCImage object added to the collection.

Remarks

Built on Wednesday, October 27, 1999


Clear Method

Removes all images from the collection.

Syntax

Clear()

Return Values

Remarks

Built on Wednesday, October 27, 1999


Count Property

Count of images in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


Item Property

Get/set an image from the collection indexed by ordinal integer or by key.

Syntax

MMCImages.Item(Index) As MMCImage

or

MMCImages(Index) As MMCImage

Remarks

Built on Wednesday, October 27, 1999


Remove Method

Removes an image from the collection indexed by ordinal integer or by key.

Syntax

Remove(Index)

The Remove method syntax has these parts:

Part | Description
Index | Index or key of image to remove.

Return Values

Remarks

Built on Wednesday, October 27, 1999


MMCImage

MMCImage represents a single bitmap. It uses a Visual Basic StdPicture object to hold the bitmap.


Properties, Methods, and Events

Properties

Index | Read-only.
Key | Returns the key of the image in the MMCImages collection.
Picture | Get/set the picture object used by the image.
Tag | Get/set any extra data needed by the snap-in.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Index Property

Ordinal index of the MMCImage object in the MMCImages collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Key of the MMCImage object in the MMCImages collection.

Syntax

Key As String

Remarks

Built on Wednesday, October 27, 1999


Picture Property

The Picture property gets or sets the picture object used by the image.

Syntax

Picture As StdPicture

Remarks

A snap-in can load a bitmap from a .bmp file on disk into a StdPicture object by using the Visual Basic function LoadPicture


Tag Property

The Tag property gets or sets any extra data needed by the snap-in.

Syntax

Tag As Variant

Remarks

Built on Wednesday, October 27, 1999


MMCListView

MMCListView defines the contents of a list view in the result pane and allows the snap-in to change its properties. It works very similarly to the Common Controls ListView object.

ColumnHeaders references an MMCColumnHeaders collection that defines the columns used when the list view is in report mode.

ListItems references an MMCListItems collection that defines the list items displayed in the list view. A snap-in can only add list items to a list view. Child scope items that appear for container nodes are added automatically by MMC. The list items can be initially populated in the ResultViews_Initialize or ResultViews_Activate event. List items can also be added or removed at any time following these events in response to UI interactions (for example, toolbar button click, context menu selection) or as asynchronously fetched data arrives. For more information on asynchronous list view population see "Asynchronous Population of Scope and Result Panes."

SelectedItems references an MMCClipboard object that contains the currently selected item(s) in the list view.

SetScopeItemState can be used to change the appearance and selection status of a scope item that appears in a list view because its parent node is selected in the scope pane. The MMCListView.ListItems collection does not contain elements that represent scope items as MMC automatically adds child scope items to a list view. A ScopeItem object represents a scope item and its properties determine the text displayed in either the scope pane or in the result pane. This method allows programmatically selecting, highlighting, etc. a scope item when it is in the result pane. A snap-in can only determine whether a scope item appears in the list view by checking whether its parent node is the currently selected scope item (referenced by SnapIn.CurrentScopeItem).

View determines the view mode of the list view (large icons, small icons, list, detail, or filtered). Filtered views require MMC 1.2 or later.

Icons and SmallIcons reference MMCImageList objects that define the bitmaps displayed with the list items as well as the child scope items that appear in the list view. For more information on using image lists in list views and in the scope pane see "Coordinating Image Lists."

MultiSelect determines whether the list view will support multiple selection. It can be set at design time or at run time in ResultViews_Initialize. Multiple selection is very easy to support in a Visual Basic snap-in because the MMCClipboardObject that contains the selected items simply uses list item and scope item collections that can be iterated. See "MMCClipboard" for more information.

Virtual determines whether the list view will contain list items (nonvirtual) or whether the snap-in will respond to requests from MMC to supply list item data (virtual). This property can be set at design time or at run time in ResultViews_Initialize. Virtual list views are useful when the logical data set consists of a large number of list items and the snap-in does not want to prefetch the entire set. MMC does not automatically add child scope items to virtual list views so if the snap-in requires them, it must add fake scope items using list items that display the same data and respond similarly to selection and double-clicks. See "ResultViews" for events that must be handled by virtual list views.

HideSelection determines whether the list view will support multiple selection. It can be set at design time or at run time in ResultViews_Initialize.

ShowChildScopeItems determines whether the list view will display child scope items. It requires MMC 1.2 or later. It can be set at design time or at run time in ResultViews_Initialize.

UseFontLinking determines whether strings used for list item and list subitem text will contain multiple languages. If True then the list view will determine which fonts it needs based on the language of the Unicode characters within the strings. For more information on using Unicode characters in list item text see "Using Unicode Strings."

There are numerous properties that relate to sorting. SortOrder determines whether sorting will be ascending or descending. SortKey determines the column on which the list view is sorted. SortHeader determines whether clicking a column header initiates a sort operation. The Sorted property determines whether the list view will be sorted. These can all be set at design time or at run time. Setting Sorted=True at run time will initiate a sort operation. During a sort operation the ResultViews_CompareItems event will be fired. If the snap-in does not handle that event then the designer runtime uses a case-insensitive string comparison.

MMC 1.2 added some additional sorting properties. SortIcon determines whether the up- and down-arrow icons will appear in the column headers when clicked by the user to initiate a sort. MMC sorts on a single column only but the snap-in can make comparisons based on multiple columns in the ResultViews_CompareItems event. In this case the snap-in can turn off the sort icon because it would falsely indicate to the user that the sort is on a single column. SortIcon can be set at design time or at run time in ResultViews_Initialize.

Also added in MMC 1.2 is LexicalSort. In MMC 1.1, scope items in the result pane are left unsorted and appear at the top of the list view. In MMC 1.2, if LexicalSort=True then the ResultViews_CompareItems event is not fired and MMC uses a lexical sort on the scope items followed by the list items. LexicalSort can be set at design time or at run time in ResultViews_Initialize.

FilterChangeTimeOut determines the interval between the time the user makes a filter value change and the firing of the ResultViews_FilterChange event. The time-out is used when the user makes a change but does not press ENTER. FilterChangeTimeOut requires MMC 1.2 or later. It can be set at design time or at run time. See "Using Column Filtering" for more information.


Properties, Methods, and Events

Properties

ColumnHeaders | Collection of column headers used in the report and filtered view modes.
FilterChangeTimeOut | Sets the interval between the time the user makes a filter value change and the firing of ResultViews_FilterChange. The time-out is used when the user makes a change but does not press ENTER. Requires MMC 1.2 or later.
HideSelection | Set/get flag to determine whether selected text appears highlighted when the list view loses the focus.
Icons | Image list containing large icons used in the icon view mode.
LexicalSort | Set/get flag to determine whether MMC will sort scope items and then list items lexically in the result pane. If True then ResultViews_CompareItems is not called. Requires MMC 1.2 or greater.
ListItems | Collection of list items that are displayed in the list view.
MultiSelect | Set/get flag to determine whether list view supports multiple-selection.
SelectedItems | The currently selected items in the list view. This may include scope items and list items owned by the snap-in.
ShowChildScopeItems | Set/get flag to determine whether child scope items will appear in the result pane when the list view is displayed. Requires MMC 1.2 or greater.
SmallIcons | Image list containing small icons used in the report, small icon, and list view modes.
Sorted | Set/get flag to determine whether items in the list view will be sorted.
SortHeader | Set/get flag to determine whether clicking on a column header in report or filtered view initiates sorting.
SortIcon | Set/get flag to determine whether column headers in report or filtered view show sorting direction arrows. Requires MMC 1.2 or greater.
SortKey | Set/get index of column used to sort the list view.
SortOrder | Set/get order of sort: ascending or descending.
Tag | Get/set any extra data needed by the snap-in.
UseFontLinking | Set/get flag to determine whether the list view uses font linking for multi-language list item and list sub-item text.
View | Set/get mode of list view: icons, small icons, report, filtered, or list.
Virtual | Set/get flag to determine whether list view is virtual.

Methods

SetScopeItemState Set the appearance of a scope item in the list view (select, focused, cut, drop-highlighted).

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


ColumnHeaders Property

The ColumnHeaders property is a collection of column headers used in the report and filtered view modes.

Syntax

ColumnHeaders As MMCColumnHeaders

Remarks

In order for a list view to display text in the columns of a list view in report or filtered mode, this collection must be populated. For predefined list views the column headers are defined at design time and the collection will already be populated when the snap-in receives the ResultViews_Initialize event. For list views defined in code, this collection must be populated in the ResultViews_Initialize event.

The keys of this collection and the keys of every MMCListItem.ListSubItems collection in MMCListView.ListItems must match. Also, the order of elements in MMCListItem.ListSubItems must match the order of the column headers in MMCListView.ColumnHeaders.


FilterChangeTimeOut Property

Sets the interval between the time the user makes a filter value change and the firing of ResultViews_FilterChange. The timeout is used when the user makes a change but does not press ENTER. Requires MMC 1.2 or greater.

Syntax

FilterChangeTimeOut As Long

Remarks

See "Using Column Filtering" for more information.


HideSelection Property

Set/get flag to determine whether selected text appears highlighted when the list view loses the focus.

Syntax

HideSelection As Boolean

Remarks

Built on Wednesday, October 27, 1999


Icons Property

Image list containing icons used in the large icon view mode.

Syntax

Icons As MMCImageList

Remarks

The indexes and keys in this image list must match those in the image list specified by the LargeIcons property. For more information see "Coordinating Image Lists".


LexicalSort Property

Set/get flag to determine whether MMC will sort scope items and then list items lexically in the result pane.

Syntax

LexicalSort As Boolean

Remarks

If LexcialSort is True then the ResultViews_CompareItems event is not called and MMC will sort the list view. Requires MMC 1.2 or greater.


ListItems Property

Collection of items that are displayed in the list view.

Syntax

ListItems As MMCListItems

Remarks

This collection contains an MMCListItem object for every list item that appears in the list view. For non-virtual list views the snap-in can populate the collection in the ResultViews_Initialize or ResultViews_Activate event. For cached result views, the snap-in can make any needed changes to the collection in ResultViews_Activate. For more information on caching result views see ResultViews_Deactivate.

At any time after the ResultViews_Initialize or ResultViews_Activate events the snap-in can add or remove items from the list view by changing the contents of this collection.

For virtual list views, the collection is never populated but the snap-in can access the properties of any virtual item in the list view at any time by referencing the collection using a numerical index. For more information see Using Virtual List Views.

Note that this collection does not contain elements for child scope items that appear in a list view. Child scope items are added by MMC and they are represented by their ScopeItem objects. When the list view is in report or filtered mode, the column data displayed for a child scope item is taken from ScopeItem.ListSubItems. For more information see ScopeItem.


MultiSelect Property

Set/get flag to determine whether list view supports multiple-selection.

Syntax

MultiSelect As Boolean

Remarks

For list views defined at runtime, this property must be set in the ResultViews_Initialize event.


SelectedItems Property

Returns the currently selected items in the list view. This may include scope items and list items owned by the snap-in.

Syntax

SelectedItems As MMCClipboard

Remarks

The MMCClipboard.ScopeItems and MMCClipboard.ListItems collections will contain references for every scope item and list item that is currently selected in the list view.


SetScopeItemState Method

Syntax

SetScopeItemState(ScopeItem As ScopeItem, State As SnapInListItemStateConstants, Value As Boolean)

The SetScopeItemState method syntax has these parts:

Part | Description
ScopeItem | The ScopeItem for which the state should be changed.
State | The type of state to change. See below.
Value | New value of the state.

Settings

The State argument settings are:

Constant | Description
siCutHilited | Determines whether the scope item is marked as cut for a cut and paste operation.
siDropHilited | Determines whether the scope item is highlighted as a drag/drop target.
siFocused | Determines whether the scope item has the focus, so that it is surrounded by a standard focus rectangle. Although more than one item can be selected, only one item can have the focus.
siSelected | Determines whether the scope item is highlighted as a selected item. In a multiple-selection list view, more than one scope item can be selected.

Return Values

Remarks

Built on Wednesday, October 27, 1999


ShowChildScopeItems Property

Set/get flag to determine whether child scope items will appear in the result pane when the list view is displayed. Requires MMC 1.2 or greater.

Syntax

ShowChildScopeItems As Boolean

Remarks

In MMC 1.1, child scope items are always added to a list view automatically by MMC. In MMC 1.2, the snap-in can control whether they are added by setting the ShowChildScopeItems property.


SmallIcons Property

Image list containing small icons used in the list, small icon, report, and filtered view modes.

Syntax

SmallIcons As MMCImageList

Remarks

The indexes and keys in this image list must match those in the image list specified by the Icons property. For more information see "Coordinating Image Lists".


Sorted Property

Set/get flag to determine whether items in the list view will be sorted.

Syntax

Sorted As Boolean

Remarks

The Sorted property can be set during the ResultViews_Initialize event or the ResultViews_Activate event to request that the list view be sorted when it is initially displayed. For predefined list views, Sorted will have its design time value upon entry to the ResultViews_Initialize event.

If Sorted is set to True after the ResultViews_Activate event then it will cause MMC to sort the list view.

Before setting Sorted, the snap-in should set SortKey and SortOrder to determine the column on which to sort and the direction of the sort.


SortHeader Property

Set/get flag to determine whether clicking on a column header in report or filtered view initiates sorting.

Syntax

SortHeader As Boolean

Remarks

If the SortHeader property is True then when the user clicks on a column in report or filtered view MMC will sort the list view on that column.

SortHeader can be set during the ResultViews_Initialize event or the ResultViews_Activate event to request that the column header clicking be enabled in the list view. For predefined list views, SortHeader will have its design time value upon entry to the ResultViews_Initialize event.

Setting SortHeader after the ResultViews_Activate event has no effect on the list view.


SortIcon Property

Set/get flag to determine whether column headers in report view show sorting direction arrows.

Syntax

SortIcon As Boolean

Remarks

If the SortHeader property is True then when the user clicks on a column in report or filtered view MMC will sort the list view on that column. In MMC 1.2, if SortHeader and SortIcon are both True then clicking the column header causes a sorting direction arrow to be displayed. This icon gives the user visual indication that the list view is sorted on the particular column in the indicated direction.

SortIcon can be set during the ResultViews_Initialize event or the ResultViews_Activate event to request that the sort icons be displayed in the list view. For predefined list views, SortIcon will have its design time value upon entry to the ResultViews_Initialize event.

Setting SortIcon after the ResultViews_Activate event has no effect on the list view.

Requires MMC 1.2 or greater.


SortKey Property

Set/get index of column used to sort the list view.

Syntax

SortKey As Integer

Remarks

The SortKey property is used when the Sorted property is True. It indicates the column on which to sort the list view. For more information see Sorted.


SortOrder Property

Set/get order of sort: ascending or descending.

Syntax

SortOrder As SnapInSortOrderConstants

Remarks

The SortOrder property is used when the Sorted property is True. It indicates the direction in which to sort the list view. For more information see Sorted.

Settings

The SortOrder property settings are:

Constant | Description
siAcending | Ascending sort.
siDescending | Descending sort.


Tag Property

The Tag property can be used by the snap-in to associate data with the list view.

Syntax

Tag As Variant

Remarks

Built on Wednesday, October 27, 1999


UseFontLinking Property

Set/get flag to determine whether the list view uses font linking for multi-language list item and list sub-item text.

Syntax

UseFontLinking As Boolean

Remarks

The UseFontLinking property should be set to True if the snap-in needs to display multiple languages within a list view. For more information see "Using Unicode Strings".[FIX UP HYERLINK]


View Property

Set/get mode of list view: icons, small icons, report, filtered, or list.

Syntax

View As SnapInViewModeConstants

Remarks

The View property can be set during the ResultViews_Initialize event or the ResultViews_Activate event to request that the list view be displayed in a particular mode. For predefined list views, View will have its design time value upon entry to the ResultViews_Initialize event.

If View is set to after the ResultViews_Activate event then it will cause MMC to change the list view mode.


Virtual Property

Set/get flag to determine whether list view is virtual.

Syntax

Virtual As Boolean

Remarks

The Virtual property can be set during the ResultViews_Initialize event or the ResultViews_Activate event to request that the list view be virtual. For predefined list views, Virtual will have its design time value upon entry to the ResultViews_Initialize event.

A virtual list view does not store its list item display information in the list items collection. When MMC needs to display a list item the snap-in will receive the ResultViews_GetVirtualItemDisplayInfo event. Virtual list views should be used when the list view represents a large amount of underlying data that cannot all be efficiently fetched before the list view is displayed.

If Virtual is set after the ResultViews_Activate event then it has no effect on the list view.

For more information see "Using Virtual List Views".


MMCColumnHeaders

MMCColumnHeaders is a collection of the MMCColumnHeader objects that define the columns displayed when a list view is in detail or filtered mode. Column headers can be defined at design time in the list view property sheet or at run time in the ResultViews_Initialize or ResultViews_Activate event. Virtual list views that define columns programmatically must do so in ResultViews_Initialize only.

The ScopeItem object also uses an MMCColumnHeaders collection to map the data it displays when it appears in a list view.

For more information see "MMCListView " and "ScopeItem".


Properties, Methods, and Events

Properties

Count | Returns the count of column headers in the collection.
Item | Returns a column header from the collection indexed by ordinal integer or by key.

Methods

Add | Adds a new column header to the collection.
Clear | Removes all column headers from the collection.
Remove | Removes a column header from the collection indexed by ordinal integer or by key.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Add Method

Adds a new column header to the collection.

Syntax

Add([Index], [Key], [Text], [Width], [Alignment]) As MMCColumnHeader

The Add method syntax has these parts:

Part | Description
Index | Index of the new MMCColumnHeader object in the collection. If not specified then the new object is appended to the collection.
Key | Key of the new MMCColumnHeader object in the collection. If not specified then the key will be set to the index as a string.
Text | Initial value for MMCColumnHeader.Text
Width | Initial value for MMCColumnHeader.Width
Alignment | Initial value for MMCColumnHeader.Alignment

Settings

The Width argument settings are:

Value | Description
Positive integer | This width of the column in pixels.
siColumnAutoWidth | The width of the column is automatically set to the width of MMCColumnHeader.Text in the font used by the list view.

Settings

The Alignment argument settings are:

Constant | Description
siColumnCenter | Text is centered in the column.
siColumnLeft | Text is aligned to the left of the column.
siColumnRight | Text is aligned to the right of the column.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Clear Method

Removes all column headers from the collection.

Syntax

Clear()

Return Values

Remarks

Built on Wednesday, October 27, 1999


Count Property

Returns count of column headers in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


Item Property

Returns a column header from the collection indexed by ordinal integer or by key. This is the default property.

Syntax

MMCColumnHeaders.Item(Index) As MMCColumnHeader

or

MMCColumnHeaders (Index) As MMCColumnHeader

The Item property syntax has these parts:

Part | Description
Index | Index or key of MMCColumnHeader object to be retrieved from the collection.

Remarks

Built on Wednesday, October 27, 1999


Remove Method

Removes a column header from the collection indexed by ordinal integer or by key.

Syntax

Remove(Index)

The Remove method syntax has these parts:

Part | Description
Index | Index or key of MMCColumnHeader object to be removed from the collection.

Return Values

Remarks

Built on Wednesday, October 27, 1999


MMCColumnHeader

MMCColumnHeader defines the properties of a single column displayed in a list view in detail or filtered mode.

Text is the text displayed in the column header. Text can be changed at any point at run time.

Width determines the column's width in pixels. It can also be set to siColumnAutoWidth to indicate that the width should match the length of the column's text. Width can be changed at any point during run time.

Alignment determines whether the column's text will be aligned left, right, or centered. It can only be specified at design time or when the column header is added by calling MMCColumnHeaders.Add. After the column has been added this property can only be used to examine the alignment.

Hidden determines whether the column will be visible. It must be set at run time in the ResultViews_Initialize or ResultViews_Activate event. Virtual list views must set it in ResultViews_Initialize only.

In MMC 1.2 or later the list view can use column filtering. The filter value for a column can be numeric or textual. The NumericFilter property is used to set a numeric filter value. The snap-in can also get its value to determine if the user has entered a numeric value in the column filter and examine its value. The TextFilter property serves the same function for text values. If the filter value is blank then both properties return an empty Variant. To make the value empty set either property to an empty Variant.


Properties, Methods, and Events

Properties

Alignment | Returns the column's alignment specified when the column was added to the MMCColumnHeaders collection.
Hidden | MMC 1.2 or greater. Indicates whether a column is hidden in the list view. If a hidden column is revealed by the user or the snap-in then it will use auto-width unless a specific column width has been set.
Index | Returns the index of the MMCColumnHeader object the MMCColumnHeaders collection.
Key | Returns the key of the MMCColumnHeader object the MMCColumnHeaders collection.
NumericFilter | MMC 1.2 or greater. Get/set the value of a numeric filter for the column. To set an empty filter set the Variant to Empty.
Tag | Get/set any extra data needed by the snap-in.
Text | Get/set the text of column header.
TextFilter | MMC 1.2 or greater. Get/set the value of a text filter for the column.
TextFilterMaxLen | MMC 1.2 or greater. Get/set the maximum length of text that the user may enter into the text filter.
Width | Get/set the column width in pixels. This property may also be set to siColumnAutoWidth to set the width based on the width of the text in the column's title.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Alignment Property

Returns the column's alignment specified when the column was added to the column headers collection.

Syntax

Alignment As SnapInColumnAlignmentConstants

Settings

The Alignment property settings are:

Constant | Description
siColumnCenter | Text is centered in the column.
siColumnLeft | Text is aligned to the left of the column.
siColumnRight | Text is aligned to the right of the column.

Remarks

Built on Wednesday, October 27, 1999


Hidden Property

MMC 1.2 or greater. Determines whether a column is hidden in the list view. If a hidden column is revealed by the user or the snap-in then it will use auto-width unless a specific column width has been set.

Syntax

Hidden As Boolean

Remarks

Built on Wednesday, October 27, 1999


Index Property

Returns the index of the item in the MMCColumnHeaders collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Returns the key of the item in the MMCColumnHeaders collection.

Syntax

Key As String

Remarks

Built on Wednesday, October 27, 1999


NumericFilter Property

MMC 1.2 or greater. Get/set the value of a numeric filter for the column.

Syntax

NumericFilter As Variant

Remarks

To set an empty filter set this property to Empty. When getting this property, if the filter value is blank then it will return Empty.

For more information see "Using Column Filtering".


Tag Property

Allows the snap-in to associate data with the MMCColumnHeader object.

Syntax

Tag As Variant

Remarks

Built on Wednesday, October 27, 1999


Text Property

Get/set the text of the column header.

Syntax

Text As String

Remarks

Built on Wednesday, October 27, 1999


TextFilter Property

MMC 1.2 or greater. Get/set the value of a text filter for the column.

Syntax

TextFilter As Variant

Remarks

To set an empty filter set the property to Empty. When getting this property, if the filter value is blank then it will return Empty.

For more information see "Using Column Filtering".


TextFilterMaxLen Property

MMC 1.2 or greater. Get/set the maximum length of text that the user may enter into the filter value.

Syntax

TextFilterMaxLen As Long

Remarks

For more information see "Using Column Filtering".


Width Property

Get/set the column width in pixels.

Syntax

Width As Integer

Settings

The Width property settings are:

Value | Description
Positive integer | This width of the column in pixels.
siColumnAutoWidth | The width of the column is automatically set to the width of MMCColumnHeader.Text in the font used by the list view.

Remarks

Built on Wednesday, October 27, 1999


MMCListItems

MMCListItems is a collection of the MMCListItem objects that define the contents of a list view. A list view's list items collection can be initially populated in the ResultViews_Initialize or ResultViews_Activate event. List items can also be added or removed at any time following these events in response to UI interactions (for example, toolbar button click, context menu selection) or as asynchronously fetched data arrives. For more information on asynchronous list view population see "Asynchronous Population of Scope and Result Panes."

In virtual list views, the collection is always empty but the snap-in can reference the properties of any virtual item by using an index (keys cannot be used). For more information see "Using Virtual List Views."

In addition to standard collection methods and properties, MMCListItems also has a SetItemCount method. For nonvirtual list views, calling this method asks MMC to preallocate memory for the specified number of items in order to improve performance. For virtual lists, this method tells MMC how many items exist in the list so that it can correctly paint the scroll bars and handle navigation using the END key. SetItemCount must be called in the ResultViews_Activate event.


Properties, Methods, and Events

Properties

Count | Returns the count of list items in the collection.
Item | Returns an item from the collection indexed by ordinal integer or by key.

Methods

Add | Adds a new item to the collection.
Clear | Removes all items from the collection.
Remove | Removes an item from the collection indexed by ordinal integer or by key.
SetItemCount | For virtual lists tells MMC how many items exist in the list. For non-virtual lists asks MMC to preallocate memory for the specified number of items.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Add Method

Adds a new item to the collection.

Syntax

Add([Index], [Key], [Text], [Icon]) As MMCListItem

The Add method syntax has these parts:

Part | Description
Index | Index of the newly created MMCListItem object. If not specified, then object is appended to the collection.
Key | Key of the newly created MMCListItem object. If not specified, then index is set to key as string.
Text | Initial value of MMCListItem.Text.
Icon | Initial value of MMCListItem.Icon.

Return Values

Remarks

When adding a list item after the ResultViews_Activate event, it is always appended to the list view regardless of the index specified.

This method is not used for virtual lists.

For more information see "MMCListView " and "Using Virtual Lists".


Clear Method

Removes all MMCListItem objects from the collection.

Syntax

Clear()

Return Values

Remarks

When used after the ResultViews_Activate event this method will clear out the list view.

Not used for virtual lists.


Count Property

Returns the count of MMCListItem objects in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


Item Property

Returns an MMCListItem object from the collection indexed by ordinal integer or by key. This is the default property.

Syntax

MMCListItems.Item(Index) As MMCListItem

or

MMCListItems (Index) As MMCListItem

Remarks

This property can be used for both virtual and non-virtual lists. It can be used for a virtual list when the snap-in needs to update the displayed properties of a list item. No other properties should be changed. Display properties are MMCListItem.Text, MMCListItem.Icon, MMCListItem.SubItems(<index>), and MMCListItem.ListSubItems(<key>).Text. After changing display properties the snap-in should call MMCListItem.Update to update the display.


Remove Method

Removes an MMCListItem object from the collection indexed by ordinal integer or by key.

Syntax

Remove(Index)

The Remove method syntax has these parts:

Part | Description
Index |

Return Values

Remarks

When used after the ResultViews_Activate event this method will remove the item from the list view.

Not used for virtual lists.


SetItemCount Method

For virtual lists tells MMC how many items exist in the list. For non-virtual lists asks MMC to pre-allocate memory for the specified number of items.

Syntax

SetItemCount(Count As Long, [Repaint], [Scroll])

The SetItemCount method syntax has these parts:

Part | Description
Count | New count of items in list view.
Repaint | Optional. If specified and True then MMC repaints the list view. Default is True.
Scroll | Optional. If specified and True then MMC adjusts the scroll bar for the new item count. Default is True.

Return Values

Remarks

Virtual lists must call this method in the ResultViews_Activate event so that MMC will know how to position its scroll bars and request display data from the snap-in.

For large non-virtual lists, snap-ins can call this method to request that MMC pre-allocate memory for the list items in order to improve performance.


MMCListItem

MMCListItem represents a single list item in a list view.

The Text property defines the text displayed for the list item when the list view is in large icon, small icon, or list mode.

The ListSubItems property references a collection of MMCListSubItem objects that define the text for the columns when the list view is in detail or filtered mode. The SubItems property is a string array that can be used as shorthand for referencing the Text property of each MMCListSubItem. For example, the following lines of code are equivalent:

ListSubItems(1).Text = "Some Text"
SubItems(1) = "Some Text"

Note that the snap-in must add items to the MMCListSubItems collection before they can be referenced using SubItems.

Icon contains the numerical index or string key of the image displayed with the list item. The index or key must be the same in the containing list view's LargeIcons and Icons image lists. For more information on using image lists see "Coordinating Image Lists."

Selected determines whether a list item is selected in the list view.

DropHilited determines whether a list item is highlighted as a drag/drop target.

Focused determines whether a list item is currently surrounded by a standard focus rectangle. Only one item has the focus, even in a multiple selection.

ItemTypeGUID contains the node type GUID for the list item. This defaults to the containing result view's DefaultItemTypeGUID property but can be changed by the snap-in at any time.

Data references an MMCDataObject containing the data exported by the snap-in for the list item. Snap-ins that extend the list item's node type use this data to determine their actions. For more information see "Developing Extension and Dual-Mode Snap-ins."

DynamicExtensions is a collection of Extension objects representing the set of dynamic extensions registered for the list item type. Dynamic extensions are only loaded for an instance of a list item if they are enabled by setting Extension.Enabled=True. This can be done when the list item is created or when in the specific feature event handler (for example, Views_AddNewMenuItems). The first time DynamicExtensions is accessed the designer runtime will read the registration database. If performance is a concern then the snap-in should defer enabling dynamic extensions until the feature event handler.

ID is a string property that uniquely identifies a list item with the underlying data that it represents. Its default value is the same as Key in a non-virtual list view. In a virtual list view its default value is the string representation of the list item's index. The designer runtime uses this property when comparing list items to determine whether they represent the same underlying data. This may happen after displaying a property page for a list item(s) when the user selects a different scope item in the scope pane. The list view that owns the list item(s) will be destroyed but the property page may be holding on to the orphaned MMCListItem object(s). For more information on handling this situation see "Handling Orphaned Property Pages".


Properties, Methods, and Events

Properties

Cut | Get/set flag indicating whether the list item is currently marked as cut for a cut and paste operation.
Data | Contains the snap-in's data exported for extension snap-ins that extend the list item's node type.
DropHilited | Get/set flag indicating whether the list item is currently highlighted as a drag/drop target.
DynamicExtensions | Collection of objects representing the set of dynamic extensions registered for the list item type. In the feature event (e.g. Views_AddNewMenuItems) set Enabled to have the extension created for the list item instance.
Focused | Get/set flag indicating whether the list item is currently surrounded by a standard focus rectangle. Only one item has the focus, even in a multiple selection.
Icon | Get/set the ordinal index or key of the icon for the item in the list view's Icons image list.
ID | Get/set string that uniquely identifies the list item. Defaults to value of key. Used by the runtime to determine whether two list items represent the same underlying data. This comparison may be made between two list items from the same list view, from different list views, or from different instances of the same list view.
Index | Returns the index of the item in the MMCListItems collection.
ItemTypeGUID | GUID exposed as the node type for the list item. Used by MMC to load extensions for the list item based on entries in the resgistration database under MMC's NodeTypes key.
Key | Returns the key of the list item in the MMCListItems collection.
ListSubItems | Returns the list sub-items collection for the list item.
Pasted | Set during a paste operation to indicate that the list item was successfully pasted.
Selected | Get/set flag indicating whether the list item is currently selected.
SubItems | Get/set the text for a sub-item. Index is the one-based column number. MMCListItem.SubItems(i) is shorthand for accessing MMCListItem.ListSubItems(i).Text.
Tag | Get/set any extra data needed by the snap-in.
Text | Get/set the text of the list item displayed in icon, small icon and list views. In report view this is the column zero text.

Methods

PropertyChanged | Called from a property page to inform the snap-in of changes made in the property sheet. Causes ResultViews_PropertyChanged to be called.
Update | Causes the list item to be redrawn.
UpdateAllViews | Causes a ResultViews_ItemViewChange event to be fired for all views. This method should be called when a list item's display properties have been changed so that all other result views may display the update.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Cut Property

Get/set flag indicating whether the list item is currently marked as cut for a cut and paste operation.

Syntax

Cut As Boolean

Remarks

Built on Wednesday, October 27, 1999


Data Property

The Data property is an MMCDataObject that contains data exported by the snap-in for extensions that extend the list item's node type.

Syntax

Data As MMCDataObject

Remarks

See "MMCDataObject" for more information on how to set data for export. See "Developing Extension and Dual-Mode Snap-ins" for more information on extensions.

For extensible list views defined at design time the list item's node type name is the same as the list view name in the designer's tree view. The node type GUID is generated by the designer and the list view's node type is automatically registered under MMC's NodeTypes key.

For list views defined at runtime, the list item is extensible if the snap-in developer has added its node type GUID to the registration database.


DropHilited Property

Get/set flag indicating whether the list item is currently highlighted as a drag/drop target.

Syntax

DropHilited As Boolean

Remarks

Built on Wednesday, October 27, 1999


DynamicExtensions Property

Collection of objects representing the set of dynamic extensions registered for the list item's node type.

Syntax

DynamicExtensions As Extensions

Remarks

A snap-in can load a dynamic extension by setting MMCListItem.DynamicExtensions(<extension CLSID> ). Enabled=True. For more information on registered extensions see "Extension." This can be done when the list item is created or in the specific feature event handler (for example, Views_AddNewMenuItems). The first time DynamicExtensions is accessed the designer runtime will read the registration database. If performance is a concern then the snap-in should defer enabling dynamic extensions until the feature event handler.

For virtual list lists, dynamic extensions must be enabled in the ResultViews_GetVirtualItemData event.


Focused Property

Get/set flag indicating whether the list item is currently surrounded by a standard focus rectangle.

Syntax

Focused As Boolean

Remarks

Only one list item in a list view has the focus, even in a multiple selection.


Icon Property

Get/set the ordinal index or key of the icon for the item in the list view's image lists.

Syntax

Icon As Variant

Remarks

The key and index of the images for the list item must be the same in the image lists referenced by MMCListView.Icons and MMCListView.SmallIcons.


ID Property

Get/set string that uniquely identifies the list item.

Syntax

ID As String

Remarks

The default value value of the ID property is the value of Key. The ID property is used by the runtime to determine whether two list items represent the same underlying data. This comparison may be made between two list items from the same list view, from different list views, or from different instances of the same list view.

In virtual list views MMCListItem.ID is set to a string containing the index of the list item. If the snap-in needs to change this property it should do so in the GetVirtualItemData event.

The designer runtime uses this property when MMC asks it compare two list items. This may happen after displaying a property page for a list item when the user selects a different scope item in the scope pane. The list view that owns the list item will be destroyed but the property page may be holding on to the orphaned MMCListItem object(s). For more information on handling this situation see "Handling Orphaned Property Pages".


Index Property

Returns the index of the MMCListItem object in the MMCListItems collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


ItemTypeGUID Property

GUID exposed as the node type for the list item. Used by MMC to load extensions for the list item based on entries in the resgistration database under MMC's NodeTypes key.

Syntax

ItemTypeGUID As String

Remarks

ItemTypeGUID is used as the node type for list items in a list view. When a list item is created its ItemTypeGUID property is set from ResultView.DefaultItemTypeGUID. For list views defined at design time it is generated by the designer. If the list view is extensible then the node type is registered under MMC's NodeType key in the registration database. For list views defined in code it is generated by the designer runtime. The snap-in can change ResultView.DefaultItemTypeGUID and it can change ItemTypeGUID for individual list items, but in that case the developer is responsible for the registration database entries.

For virtual list views, if the snap-in must change ItemTypeGUID it should do so in the ResultViews_GetVirtualItemData event.


Key Property

Returns the index of the MMCListItem object in the MMCListItems collection.

Syntax

Key As String

Remarks

Built on Wednesday, October 27, 1999


ListSubItems Property

Get/set the list sub-items collection for the list item.

Syntax

ListSubItems As MMCListSubItems

Remarks

When a list item is displayed in detail mode, the text for its columns comes from the Text property of each MMCListSubItem object in MMCListItem.ListSubItems. This collection should contain an MMCListSubItem object for every column in the list view.

To change the MMCListSubItem.Text for a sub-tem that is already displayed, set the new value and call MMCListItem.Update.

For non-virtual list view, this collection should be populated in either the ResultViews_Initialize or ResultVIews_Activate event. If the result view is cached then any changes to the collection should be made in the ResultViews_Activate event. For more information on caching result views see the ResultViews_Deactivate event.

For virtual list views, this collection should be populated in the ResultViews_GetVirtualItemDisplayInfo event.


Pasted Property

Set during a paste operation to indicate that the list item was successfully pasted.

Syntax

Pasted As Boolean

Remarks

In the Views_Paste event, if the user is pasting list items that belong to the same instance of the snap-in, then the snap-in should set MMCListItem.Pasted to True for each list item that was successfully pasted. If the operation is a move, then the snap-in will receive a Views_Cut event in which it can examine this property to determine what must be deleted from its underlying data.

For more information see "Implementing Drag/Drop and Cut/Copy/Paste."


PropertyChanged Method

Called from a property page to inform the snap-in of changes made in the property sheet. Causes the ResultViews_PropertyChanged event to be called.

Syntax

PropertyChanged(Data)

The PropertyChanged method syntax has these parts:

Part | Description
Data | Any data that the property page needs to pass to the snap-in. This Variant will be passed as the Data parameter to the ResultViews_PropertyChanged event.

Return Values

Remarks

When a property page detects a change to the underlying data that requires an update to the list item in the list view, it should call this method. In the ResultViews_PropertyChanged event the snap-in should make the changes to MMCListItem.Text and MMCListItem.ListSubItems and call MMCListItem.Update to update the list view's display.


Selected Property

Get/set flag indicating whether the list item is currently selected.

Syntax

Selected As Boolean

Remarks

Setting this property cause the list item to become selected.


SubItems Property

Get/set the text for a sub-item. Index is the one-based column number. MMCListItem.SubItems(i) is shorthand for accessing MMCListItem.ListSubItems(i).Text.

Syntax

SubItems(Index As Integer) As String

Remarks

The text for a list sub-item can only be accessed using the SubItems property after it has been added to the collection by calling MMCListItem.ListSubItems.Add. For example:

ResultView.ListView.ListSubItems.Add 1, "New Sub-Item"
ResultView.ListView.SubItems(1) = "Text for New Sub-Item"

See ListSubItems property for more information.


Tag Property

Get/set any extra data needed by the snap-in.

Syntax

Tag As Variant

Remarks

The Tag property allows the snap-in to store data associated with the list item. This is typically used to reference the underlying data that the list item represents.


Text Property

Get/set the text of the list item displayed in icon, small icon and list views.

Syntax

Text As String

Remarks

To change the Text property for a list item that is already displayed, set the new value and call MMCListItem.Update.


Update Method

Causes the list item to be redrawn.

Syntax

Update()

Return Values

Remarks

This method should be called after changing the display properties of the list item after the ResultViews_Activate event (e.g. in response to a toolbar button click). Display properties are Text, ListSubItems, SubItems, and Icon.


UpdateAllViews Method

The UpdateAllViews method causes a ResultViews_ItemViewChange event to be fired for all views. This method should be called when a list item's display properties have been changed so that all other result views may display the update.

Syntax

UpdateAllViews([Hint])

The UpdateAllViews method syntax has these parts:

Part | Description
Hint | Snap-in defined data that will be passed as the Hint parameter to the ResultViews_ItemViewChange event.

Return Values

Remarks

This method is typically called in response to a user action that changes the display properties of a list item. For example, if a user renames a list item, then the snap-in must change the displayed name in the current view and in any other views that might be displaying the list item. The Hint parameter allows the snap-in to pass information regarding the properties that have changed to the ResultViews_ItemViewChange event. For more information see ResultViews_ItemViewChange.


MMCListSubItems

MMCListSubItems is a collection of MMCListSubItem objects used to define the text displayed in the columns of a list view in detail or filtered mode. Snap-ins do not create MMCListSubItems objects. They are added to the MMCListView.ListSubItems or ScopeItem.ListSubItems collections. ScopeItem.ListSubItems is only used when a ScopeItem appears in a list view.

The text of a list sub-item can also be accessed using the string array referenced by MMCListView.SubItems or ScopeItem.SubItems. The advantage of using the MMCListSubItems collection is that the MMCListSubItem object has a Tag property that allows the snap-in to store extra information with the list subitem. This is useful when the snap-in needs to keep extra information on a per-column, per-row basis.


Properties, Methods, and Events

Properties

Count | Returns count of MMCListSubItem objects in the collection.
Item | Returns an MMCListSubItem object from the collection indexed by ordinal integer or by key.

Methods

Add | Adds a new MMCListSubItem object to the collection. Index and key must correspond to the column header index and key.
Clear | Removes all MMCListSubItem objects from the collection.
Remove | Removes an MMCListSubItem object from the collection indexed by ordinal integer or by key.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Add Method

Adds a new MMCListSubItem object to the collection. Index and key must correspond to the column header index and key.

Syntax

Add([Index], [Key], [Text]) As MMCListSubItem

The Add method syntax has these parts:

Part | Description
Index | Index of new MMCListSubItem object. If not specified, then new object is appended to the collection.
Key | Key of MMCListSubItem object. If not specified then key is index as string.
Text | Initial value of MMCListSubItem.Text.

Return Values

Remarks

Elements should be added to the collection so that they match both the position and keys of the column headers for which they will be displayed. The designer runtime uses this information to match an element from ResultView.ListView.ListSubItems to a request from MMC for column text.

When adding to ScopeItem.ListSubItems the key must match a column header key in the list view defined by its parent scope item. For more information see ScopeItem.


Clear Method

Removes all MMCListSubItem objects from the collection.

Syntax

Clear()

Return Values

Remarks

Built on Wednesday, October 27, 1999


Count Property

Returns count of MMCListSubItem objects in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


Item Property

Returns an MMCListSubItem object from the collection indexed by ordinal integer or by key. This is the default property.

Syntax

MMCListSubItems.Item(Index) As MMCListSubItem

or

MMCListSubItems(Index) As MMCListSubItem

The Item property syntax has these parts:

Part | Description
Index | Index or key of MMCListSubItem object to be returned.

Remarks

Built on Wednesday, October 27, 1999


Remove Method

Removes an MMCListSubItem object from the collection indexed by ordinal integer or by key.

Syntax

Remove(Index)

The Remove method syntax has these parts:

Part | Description
Index | Index or key of MMCListSubItem object to be removed.

Return Values

Remarks

Built on Wednesday, October 27, 1999


MMCListSubItem

MMCListSubItem defines the text displayed in a column of a list view in detail or filtered mode. The Text property holds the text displayed. The Tag property allows the snap-in to associate extra information with the list sub-item.


Properties, Methods, and Events

Properties

Index | Returns the index of the item in the list sub-items collection. The index corresponds to a column header index.
Key | Returns the key of the item in the list sub-items collection. The key corresponds to a column header key.
Tag | Get/set any extra data needed by the snap-in.
Text | Get/set the text of sub-item.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Index Property

Returns the index of the item in the list sub-items collection. The index corresponds to a column header index.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Returns the key of the item in the list sub-items collection. The key corresponds to a column header key.

Syntax

Key As String

Remarks

Built on Wednesday, October 27, 1999


Tag Property

Get/set any extra data needed by the snap-in.

Syntax

Tag As Variant

Remarks

The Tag property allows a snap-in to associate data with a particular row and column in a list view.


Text Property

Get/set the text of sub-item.

Syntax

Text As String

Remarks

Built on Wednesday, October 27, 1999


MMCDataObjects

MMCDataObjects is a collection of MMCDataObject objects used to export data to and import data from other snap-ins. See "MMCDataObject" for more information.


Properties, Methods, and Events

Properties

Count | Count of data objects in the collection.
Item | Returns a data object in the collection indexed by ordinal integer or by key.

Methods

Add | Adds a new data object to the collection.
Clear | Clears all data objects from the collection.
Remove | Removes a data object from the collection indexed by ordinal integer or by key.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Add Method

Adds a new data object to the collection.

Syntax

Add([Index], [Key]) As MMCDataObject

The Add method syntax has these parts:

Part | Description
Index | Index of the new data object. If not specified the object will be appended.
Key | Key of the new data object. If not specified the key will be the index as a string.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Clear Method

Removes all data objects from the collection.

Syntax

Clear()

Return Values

Remarks

Built on Wednesday, October 27, 1999


Count Property

Count of data objects in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


Item Property

Returns a data object in the collection indexed by ordinal integer or by key. This is the default property.

Syntax

MMCDataObjects.Item(Index) As MMCDataObject

or

MMCDataObjects(Index) As MMCDataObject

Remarks

Built on Wednesday, October 27, 1999


Remove Method

Removes a data object from the collection indexed by ordinal integer or by key.

Syntax

Remove(Index)

The Remove method syntax has these parts:

Part | Description
Index |

Return Values

Remarks

Built on Wednesday, October 27, 1999


MMCDataObject

MMCDataObject is used to export data to and import data from other snap-ins. Every ScopeItem and every MMCListItem has a Data property that returns an MMCDataObject containing the data exported by that object.

MMCDataObject.SetData exports data from the snap-in. It takes a Variant containing the data and format name. The Variant can contain any simple type (Integer, Long, String, and so on), an object that supports persistence (such as a Visual Basic class), Byte arrays, and String arrays.

MMCDataObject.GetFormat checks to see whether a data format is available when importing data.

MMCDataObject.GetData retrieves the data for a specific format as a Byte array in a Variant.

The FormatData method can be used to interpret any subset of the Byte array as any simple data type, a persisted object, or multiple concatenated null-terminated Unicode strings.

MMCDataObject.ObjectTypes returns a String array containing the node type GUIDs of all the object types exported by the snap-in when multiselection is used.

Clear removes all data added by SetData.

For more information see "Importing Data from C++ Snap-ins" and "Developing Extension and Dual-Mode Snap-ins."


Properties, Methods, and Events

Properties

Index | Returns the index of the data object when it is part of a data objects collection.
Key | Get/set the key of the data object when it is part of a data objects collection. Defaults to index as string.
ObjectTypes | A read-only array of strings that contain the GUIDs of the objects types whose data is contained within the data object.

Methods

Clear | Removes all snap-in defined data formats from the data object.
FormatData | Formats raw data in a byte array into Visual Basic data types.
GetData | Returns the data in the data object in the specified format.
GetFormat | Indicates whether data in the specified format is currently available from the data object.
SetData | Puts data in the data object using the specified format. If the data is an object then pass a value from the SnapInObjectFormatConstants enumeration for the ObjectType parameter.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Clear Method

Empties the data object.

Syntax

Clear()

Return Values

Remarks

Built on Wednesday, October 27, 1999


FormatData Method

Formats raw data in a byte array into Visual Basic data types.

Syntax

FormatData(Data, StartingIndex As Long, Format As SnapInFormatConstants, [BytesUsed])

The FormatData method syntax has these parts:

Part | Description
Data | A Variant containing a Byte array that holds the raw data received from a call to MMCDataObject.GetData.
StartingIndex | The one-based index of the element in the Byte array from which to begin interpreting the data.
Format | Determines the data type to which the raw data should be converted to.
BytesUsed | Optional. Returns the number of bytes read and converted into the requested data type.

Settings

The Format argument settings are:

Constant | Description
siBoolean | Read 4 bytes and return them as a Boolean
siCBoolean | Read 2 bytes, convert them from a C/C++ language BOOL and return them as a Boolean.
siCurrency | Read 8 bytes and return them as a Currency.
siDate | Read 8 bytes and return them as a Date.
siDouble | Read 8 bytes and return them as a Double.
siGUID | Read 16 bytes as a binary GUID and return them as string in string format {00000000-0000-0000-0000-000000000000}
siInteger | Read 2 bytes and return them as an Integer.
siLong | Read 4 bytes and return them as a Long.
siMultiString | Read bytes as concatenated null-terminated UNICODE strings terminated by a double UNICODE null character. Return as an array of String.
siObject | Read CLSID from start of bytes and remainder of bytes as the contents of a stream. Create an instance of the object and load it from the stream. Visual Basic classes that are marked Persistable can be exported by the primary snap-in for this type.
siObjectInstance | Read the data as a reference to an instance of an object and return it as an Object.
siSingle | Read 4 bytes and return them as a Single.
siString | Read bytes as a null-terminated UNICODE string. Return as a String. Visual Basic String variables exported by the primary snap-in are read using this type.

Return Values

The FormatData method returns a Variant containing the data type requested in the Format argument.

Remarks

This method is used in ExtensionSnapIn events to interpret the imported data. For more information see "MMCDataObject", "Importing Data from C++ Snap-ins", and "Publishing and Interpreting Data Formats from a Visual Basic Snap-in."


GetData Method

Returns the data in the data object in the specified format.

Syntax

GetData(Format As String, [MaximumLength])

The GetData method syntax has these parts:

Part | Description
Format | Name of data format.
MaximumLength | Optional. Maximum possible length of data when importing from a C++ snap-in that requires use of IDataObject::GetDataHere and TYMED_HGOBAL.

Return Values

Returns a Variant containing a Byte array with the data.

Remarks

This method is called in an extension snap-in to get the data exported by the extended snap-in. The extension snap-in developer should consult the documentation for the extended snap-in to get the data format name and layout of the data. The data in the Byte array can be converted to Visual Basic data types using the MMCDataObject.FormatData or SnapIn.FormatData method.

When a Visual Basic snap-in imports data from a C++ snap-in, the designer runtime will try both IDataObject::GetData and IDataObject::GetDataHere with TYMED_HGLOBAL and TYMED_ISTREAM. If the MaximumLength parameter is passed in then the designer runtime will ask the extended snap-in for its data by calling IDataObject::GetDataHere(TYMED_HGLOBAL) with a buffer of the specified length. If the parameter is not passed the runtime will try various combinations of IDataObject::GetData and IDataObject::GetDataHere using TYMED_HGLOBAL and TYMED_ISTREAM.

For more information see "MMCDataObject", "Importing Data from C++ Snap-ins", and "Publishing and Interpreting Data Formats from a Visual Basic Snap-in."


GetFormat Method

Indicates whether data in the specified format is currently available from the data object.

Syntax

GetFormat(Format As String) As Boolean

The GetFormat method syntax has these parts:

Part | Description
Format | Name of data format.

Return Values

Returns True is the data format is available.

Remarks

This method is called in an extension snap-in to to determine if data exported by the extended snap-in is present in the data object. The extension snap-in developer should consult the documentation for the extended snap-in to get the data format name and layout of the data. The data can be retrieved in a Byte array by calling MMCDataObject.GetData. The data in the Byte array can be converted to Visual Basic data types using the MMCDataObject.FormatData or SnapIn.FormatData method.

For more information see "MMCDataObject", "Importing Data from C++ Snap-ins", and "Publishing and Interpreting Data Formats from a Visual Basic Snap-in."


Index Property

Returns the index of the data object when it is part of an MMCDataObjects collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Get/set the key of the data object when it is part of an MMCDataObjects collection. Defaults to same value as index.

Syntax

Key As String

Remarks

The designer runtime does not use the Key property. The snap-in can set it as needed to identify the data object. Note that setting MMCDataObject.Key in an extended snap-in does not make that same value available in an extension snap-in.


ObjectTypes Property

A read-only array of strings that contain the GUIDs of the objects types whose data is contained within the data object.

Syntax

ObjectTypes As String()

Remarks

This ObjectTypes property is used in an extension snap-in to determine what objects are represented in the data. For data exported from a Visual Basic snap-in, this array will contain a GUID for the ScopeItem.ScopeNode.NodeTypeGUID property and MMCListItem.ItemTypeGUID property of every scope item and list item represented in the data.

When the exporting snap-in is written in C++, consult the snap-in's documentation for the object types. C++ snap-ins export this information using the CCF_OBJECT_TYPES_IN_MULTI_SELECT data format.


SetData Method

Puts data in the data object using the specified format so that it will be available to extension snap-ins.

Syntax

SetData(Data, Format As String, [ObjectType])

The SetData method syntax has these parts:

Part | Description
Data | Variant containing the data to be exported.
Format | Name of the data format.
ObjectType | If the data is an object then pass a value from the SnapInObjectFormatConstants enumeration for this parameter.

Settings

The ObjectType argument settings are:

Constant | Description
siObjectReference | Stores a reference to the object. A snap-in that imports this data format will receive a reference to the same instance of the object.
siPersistsedObject | Persists the object. A snap-in that imports this data format will receive its own instance of the object loaded from its persisted data.

Return Values

Remarks

This method is used by primary snap-ins to export data for use by extension snap-ins. The snap-in must document the format name, data type, and data content.

When passing an object and using the siPersistsedObject option, the object must support persistence using the IPersistStreamInit interface. A Visual Basic class can be used by marking it persistable in the property browser and implementing the Class_WriteProperties and Class_ReadProperties events.

For more information see "MMCDataObject", "Importing Data from C++ Snap-ins", and "Publishing and Interpreting Data Formats from a Visual Basic Snap-in."


MMCClipboard

MMCClipboard is used to hold the user's selections in the result pane. It contains collections of ScopeItems, MMCListItems, and MMCDataObjects. It is very simple to use and makes supporting multiple selection just as easy as supporting single selection. The snap-in need only iterate through each of the collections to determine what is selected.

The SelectionType property is an enumeration that allows a snap-in to quickly determine the nature of the selection. It has the following values:

Value | Meaning
siSingleScopeItem | A single scope item owned by the snap-in.
siSingleListItem | A single list item owned by the snap-in.
siSingleForeign | A single item owned by another snap-in.
siMultiScopeItems | Multiple scope items owned by the snap-in.
siMultiListItems | Multiple list items owned by the snap-in.
siMultiMixed | List items and scope items owned by the snap-in.
siMultiForeign | Multiple items owned by other snap-ins.
siMultiMixedForeign | Multiple items. Some are owned by the snap-in and some by other snap-ins.
siSpecialWeb | The user has selected or deselected the result pane that currently contains a URL view or a taskpad view. Used for Views_Select, Views_UpdateControlbar, toolbar, and menu button events when the result pane contains a snap-in taskpad or a URL result view.
siSpecialOcx | The user has selected or deselected the result pane that currently contains an OCX view. Used for Views_Select, Views_UpdateControlbar, toolbar, and menu button events when the result pane contains an OCX result view.
siEmpty | There are no currently selected objects.


Properties, Methods, and Events

Properties

DataObjects | An MMCDataObject collection containing a data object for every snap-in that owns items in the selection other than the primary snap-in.
ListItems | Collection of the list items owned by the snap-in that are currently in the clipboard.
ScopeItems | Collection of the scope items owned by the snap-in that are currently in the clipboard.
SelectionType | Type of selection currently contained by the MMCClipboard object.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


DataObjects Property

An MMCDataObject collection containing a data object for every snap-in that owns items in the selection other than the primary snap-in.

Syntax

DataObjects As MMCDataObjects

Remarks

This property is used in extension snap-ins when examining data exported by a primary snap-in. The collection will typically contain a single MMCDataObject that contains the primary snap-in's exported data. Note that even in a multiple selection where all items are owned by the primary snap-in the collection will still only contain a single MMCDataObject.

This property is used in primary snap-ins when there is a multiple selection in the result pane of a list view that includes child scope items belonging to namespace extensions. This situation can occur when the node selected in the scope pane is owned by the snap-in and it has namespace extensions that have added child nodes. The collection will contain one MMCDataObject for every extension snap-in that owns child scope items in the selection.


ListItems Property

Collection of the list items owned by the snap-in that are currently in the clipboard.

Syntax

ListItems As MMCListItems

Remarks

When a selection contains list items owned by a snap-in, this collection will contain references to those MMCListItem objects. ResultView.ListView.ListItems and MMCClipboard.ListItems contain references to the same objects meaning that the object temporarily resides in two collections. Note that each MMCListItem object will retain its original Index property value. For example, if a multiple selection includes ResultView.ListView.ListItems(3) and ResultView.ListView.ListItems(5) then MMCClipboard.ListItems.Count will be two and MMCClipboard.ListItems(1).Index will be 3 and MMCClipboard.ListItems(2).Index will be 5.


ScopeItems Property

Collection of the scope items owned by the snap-in that are currently in the clipboard.

Syntax

ScopeItems As ScopeItems

Remarks

When a selection contains scope items owned by a snap-in, this collection will contain references to those ScopeItem objects. SnapIn.ScopeItems and MMCClipboard.ListItems contain references to the same objects meaning that the object temporarily resides in two collections. Note that each ScopeItem object will retain its original Index property value. For example, if a multiple selection includes SnapIn.ScopeItems (3) and SnapIn.ScopeItems (5) then MMCClipboard.ScopeItems.Count will be two and MMCClipboard.ScopeItems(1).Index will be 3 and MMCClipboard.ScopeItems(2).Index will be 5.


SelectionType Property

Type of selection currently contained by the MMCClipboard object.

Syntax

SelectionType As SnapInSelectionTypeConstants

Settings for SelectionType are:

Value | Meaning
siSingleScopeItem | A single scope item owned by the snap-in.
siSingleListItem | A single list item owned by the snap-in.
siSingleForeign | A single item owned by another snap-in.
siMultiScopeItems | Multiple scope items owned by the snap-in.
siMultiListItems | Multiple list items owned by the snap-in.
siMultiMixed | List items and scope items owned by the snap-in.
siMultiForeign | Multiple items owned by other snap-ins.
siMultiMixedForeign | Multiple items. Some are owned by the snap-in and some by other snap-ins.
siSpecialWeb | The user has selected or deselected the result pane that currently contains a URL view or a taskpad view. Used for Views_Select, Views_UpdateControlbar, toolbar, and menu button events when the result pane contains a snap-in taskpad or a URL result view.
siSpecialOcx | The user has selected or deselected the result pane that currently contains an OCX view. Used for Views_Select, Views_UpdateControlbar, toolbar, and menu button events when the result pane contains an OCX result view.
siEmpty | There are no currently selected objects.

Remarks

This property allows the snap-in to conveniently determine the contents of the MMCClipboard object without having to check MMCClipboard.ScopeItems.Count, MMCClipboard.ListItems.Count etc.


MMCMenus

MMCMenus is a collection of MMCMenu objects. It is used to hold the child menus of an MMCMenu object referenced from its Children property. See "MMCMenu" and "Menus" for more information.


Properties, Methods, and Events

Properties

Count | Returns count of MMCMenu objects in the collection.
Item | Returns an MMCMenu object in the collection specified by ordinal integer or by key.

Methods

Add | Adds a new MMCMenu object to the collection.
Clear | Removes all MMCMenu objects from the collection.
Remove | Removes an MMCMenu object from the collection.

Events

This object has no events.

Remarks

For more information see Menus.


Add Method

Adds a new MMCMenu object to the collection.

Syntax

Add([Index], [Key]) As MMCMenu

The Add method syntax has these parts:

Part | Description
Index | Index of the new MMCMenu object. If not specified then the object is appended to the collection.
Key | Key of the new MMCMenu object. If not specified then key is set to the index as a string.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Clear Method

Removes all MMCMenu objects from the collection.

Syntax

Clear()

Return Values

Remarks

Built on Wednesday, October 27, 1999


Count Property

Returns the count of MMCMenu objects in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


Item Property

Returns an MMCMenu object in the collection specified by ordinal integer or by key. This is the default property.

Syntax

MMCMenus.Item(Index) As MMCMenu

or

MMCMenus(Index) As MMCMenu

The Item proeprty syntax has these parts:

Part | Description
Index | Index or key of the MMCMenu object to be retrieved

Remarks

Built on Wednesday, October 27, 1999


Remove Method

Removes an MMCMenu object from the collection.

Syntax

Remove(Index)

The Remove method syntax has these parts:

Part | Description
Index | Index or key of the MMCMenu object to be removed.

Return Values

Remarks

Built on Wednesday, October 27, 1999


MMCMenu

MMCMenu is similar to the Visual Basic intrinsic menu control. It is used to represent a single item on a console context menu as well as a container of menu items added at a single insertion point (top, View menu, All Tasks menu, and New menu). Events are fired on the individual MMCMenu objects and on the containing MMCMenu. Menus can be defined at design time, at run time, or a combination of both (for example, adding children to a menu created at design time).

The Name property is used to identify the MMCMenu object in Visual Basic code. A menu created at design time becomes a module-level object in the snap-in at run time. It can be referenced by its design-time name, for example, Menu1.Tag = 1.

The Index property determines the menu's position both in the collection and when it is added to the insertion point in MMC's context menu. The Key property is for snap-in use to help further identify the menu.

Caption contains the text displayed in MMC's context menu.

StatusBarText contains the text displayed in the status bar when the menu is highlighted by the user.

Visible determines whether the menu is visible at run time.

Enabled determines whether the user can select the menu at run time.

Grayed determines whether the menu is dimmed and disabled at run time.

Checked determines whether the menu has a check mark displayed next to its caption.

MenuBreak indicates whether the menu item begins a new column.

MenuBarBreak indicates whether the menu item begins a new column with a separating vertical line.

There is no separator property because MMC does not permit snap-ins to add separator lines to its context menus. You may have seen some C++ snap-ins that do this, but it is against the MMC UI guidelines and is consequently not possible from a Visual Basic snap-in.

Children contains the collection of child menus contained by the menu. Menus can be nested to any level. An MMCMenu object that has children cannot be selected by the user (that is, it defines a submenu).

The Click event is fired when the user selects the item represented by the MMCMenu object. It is fired on both the object and its containing MMCMenu. If the snap-in handles the event on the containing menu then the Index parameter indicates which element in its Children collection was clicked.

For more information on using menus in a snap-in see "Menus."


Properties, Methods, and Events

Properties

Caption | Get/set the text of the menu item.
Checked | Get/set a value that determines whether a check mark is displayed next to the menu item.
Children | Collection of child menu objects. Used to represent cascading menus.
Default | Get/set a value that determines whether a menu item is displayed in bold. Only one menu item among siblings can have this attribute.
Enabled | Get/set flag indicating whether the user can select the menu item.
Grayed | Get/set flag indicating whether the menu item is grayed.
Index | Get/set the index of the menu in its parent's MMCMenus.Children collection.
Key | Get/set the key of the menu object in its parent's MMCMenus.Children collection.
MenuBarBreak | Get/set flag indicating whether the menu item begins a new column with a separating vertical line.
MenuBreak | Get/set flag indicating whether the menu item begins a new column without any separating vertical line.
Name | Returns the name used to identify the menu in Visual Basic code.
StatusBarText | Get/set the text displayed in the status bar when the menu item is highlighted.
Tag | Get/set any extra data needed by the snap-in
Visible | Get/set a value that determines whether a menu item is visible.

Methods

This object has no methods.

Events

Click Called when the user selects an item from a context menu.

Remarks

Built on Wednesday, October 27, 1999


Caption Property

Get/set the text of the menu item.

Syntax

Caption As String

Remarks

Built on Wednesday, October 27, 1999


Checked Property

Get/set a value that determines whether a check mark is displayed next to the menu item.

Syntax

Checked As Boolean

Remarks

Built on Wednesday, October 27, 1999


Children Property

Collection of child MMCMenu objects. Used to represent cascading menus.

Syntax

Children As MMCMenus

Remarks

Built on Wednesday, October 27, 1999


Click Event

Called when the user selects an item from a context menu. The snap-in should check the contents of the MMCClipboard object to determine the currently selected item(s).

Syntax

Click(Index As Long, Selection As MMCClipboard)

The Click event syntax has these parts:

Part | Description
Index | Index of the menu in its parent's MMCMenus.Children collection.
Selection | Currently selected item(s). The selection can be in the scope pane or in the result pane.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Default Property

Get/set a value that determines whether a menu item is displayed in bold. Only one menu item among siblings can have this attribute.

Syntax

Default As Boolean

Remarks

Built on Wednesday, October 27, 1999


Enabled Property

Get/set flag indicating whether the user can select the menu item.

Syntax

Enabled As Boolean

Remarks

Built on Wednesday, October 27, 1999


Grayed Property

Get/set flag indicating whether the menu item is grayed.

Syntax

Grayed As Boolean

Remarks

Built on Wednesday, October 27, 1999


Index Property

Get/set the index of the menu in its parent's MMCMenus.Children collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Get/set the key of the menu object in its parent's MMCMenus.Children collection.

Syntax

Key As String

Remarks

Built on Wednesday, October 27, 1999


MenuBarBreak Property

Get/set flag indicating whether the menu item begins a new column with a separating vertical line.

Syntax

MenuBarBreak As Boolean

Remarks

Built on Wednesday, October 27, 1999


MenuBreak Property

Get/set flag indicating whether the menu item begins a new column without any separating vertical line.

Syntax

MenuBreak As Boolean

Remarks

Built on Wednesday, October 27, 1999


Name Property

Returns the name used to identify the menu in code.

Syntax

Name As String

Remarks

When adding a menu to MMC by calling ContextMenu.AddMenu specify this name.


StatusBarText Property

Get/set the text displayed in the status bar when the menu item is highlighted.

Syntax

StatusBarText As String

Remarks

Built on Wednesday, October 27, 1999


Tag Property

Get/set any extra data needed by the snap-in.

Syntax

Tag As Variant

Remarks

Allows the snap-in to associate data with the MMCMenu object.


Visible Property

Get/set a value that determines whether a menu item is visible.

Syntax

Visible As Boolean

Remarks

Built on Wednesday, October 27, 1999


ContextMenu

ContextMenu represents the console's context menu and is used to add MMCMenu objects. It is passed as a parameter to the menu insertion events such as Views_AddTaskMenuItems. It has a single method AddMenu that receives the name of the menu being added. The designer runtime adds all of the items in MMCMenu.Children to the insertion point in MMC's context menu. This object cannot be used outside of these events.


Properties, Methods, and Events

Properties

This object has no properties.

Methods

AddMenu Adds a menu object to the context menu.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


AddMenu Method

Adds a menu object to the context menu.

Syntax

AddMenu(Menu As MMCMenu)

The AddMenu method syntax has these parts:

Part | Description
Menu | MMCMenu object to add to MMC's context menu.

Return Values

Remarks

When an MMCMenu object is added to MMC's context menu, its child items in MMCMenu.Children will appear in the menu. The MMCMenu object itself will not appear and is only used as a reference.


MMCPropertySheet

MMCPropertySheet represents a Win32 property sheet displayed by the console. An MMCPropertySheet object is passed as a parameter to the SnapIn_CreateConfigurationWizard and Views_CreatePropertyPages events to allow the snap-in to add its pages to the wizard or property sheet.

Property pages that implement IMMCPropertyPage also receive an MMCPropertySheet object in the IMMCPropertyPage_Initialize method so that a reference to it may be stored in a module-level variable. This allows the property page to modify the state of the property sheet while it is running.

AddPage adds a property page to the sheet if it is a property sheet. It is usually called from the Views_CreatePropertyPages event but it can also be called from a property page to dynamically add a page to a running property sheet,

AddWizardPage adds a page for wizards. It can only be called before the property sheet is running. The object passed in the ConfigurationObject parameter will be available to the property page in its PropertyPage_SelectionChanged event in SelectedControls(0).

For both AddPage and AddWizardPage, the page is identified by its name passed as a literal string.

GetPagePosition returns the one-based position of the property page within the property sheet.

InsertPage can be called from a property page to insert a new page at a specified position.

RecalcPageSize should be called from a property page after adding or inserting a page that is not the same size as the existing pages.

AddPageProvider can be called from a property page to pass the CLSID of a C++ COM object that will add pages to the property sheet. It creates the object and returns a reference to it along with the HWND of the property sheet. The caller can then pass the sheet's HWND to the object and it can use the Win32 PSM_ADDPAGE or PSM_INSERTPAGE message to add its pages. This mechanism allows using existing C++

ActivatePage can be called from a property page to select a new page. This is the programmatic equivalent of the user selecting the page's tab.

RemovePage can be called from a property page to remove a page from a running property sheet.

SetTitle can be called from a property page to change the title of a running property sheet.

PressButton can be called from a property page to programmatically simulate the user pressing one of the property sheet's buttons.

ChangeCancelToClose can be called from a property page to change the Cancel button to a Close button. This can be used when the user has made changes that cannot be reversed.

SetWizardButtons c an be called from a property page in a wizard to change the state of the wizard's Back, Next, and Finish buttons.

SetFinishButtonText can be called from a property page in a wizard to change the text of the Finish button and enable it. Also hides the Back and Next buttons.

RebootSystem and RestartWindows can be called from a property page to tell MMC to reboot the system or restart windows after the property sheet is closed if the user clicked the OK button.

For more information see "Property Pages."


Properties, Methods, and Events

Properties

This object has no properties.

Methods

ActivatePage | Can be called from a property page to activate another property page.
AddPage | Adds a property page to the property sheet.
AddPageProvider | Can be called from a property page to create a COM object that will add property pages to the sheet.
AddWizardPage | Adds a property page to a wizard property sheet.
ChangeCancelToClose | Can be called from a property page to change the Cancel button to a Close button.
GetPagePosition | Can be called from a property page to determine its one-based position in the property sheet.
InsertPage | Can be called from a property page to insert a new page into the property sheet
PressButton | Can be called from a property page to simulate pressing a property sheet button.
RebootSystem | Can be called from a property page to request that MMC reboot the system if the user clicks the OK button to close the property sheet.
RecalcPageSizes | Can be called from a property page to request that the property sheet recalculate the page sizes.
RemovePage | Can be called from a property page to remove a page from the property sheet.
RestartWindows | Can be called from a property page to request that MMC restart windows if the user clicks the OK button to close the property sheet.
SetFinishButtonText | Can be called from a property page in a wizard to change the text of the Finish button and enable it.
SetTitle | Can be called from a property page to change the title of the property sheet.
SetWizardButtons | Can be called from a property page in a wizard to change the state of the wizard's Back, Next, and Finish buttons.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


ActivatePage Method

Can be called from a property page to activate another property page. The page is specified by its one-based position in the sheet.

Syntax

ActivatePage(Position As Integer)

The ActivatePage method syntax has these parts:

Part | Description
Position | One-based position of the page in the property sheet.

Return Values

Remarks

A property page can get its own position by calling MMCPropertySheet.GetPagePosition.


AddPage Method

Adds a property page to the property sheet.

Syntax

AddPage(PageName As String, [Caption], [UseHelpButton], [RightToLeft], [InitData])

The AddPage method syntax has these parts:

Part | Description
PageName | The name of the property page as it appears in the project window.
Caption | Optional. If specified will be used as the page's caption. If not specified then the page's Caption property set at design time will be used. The caption text is displayed on the tab for the page.
UseHelpButton | Optional. If True then a "Help" button will appear on the property sheet when the page is active.
RightToLeft | Optional. If True then the page is using a right-to-left language such as Hebrew or Arabic.
InitData | Optional. If specified and the property page implements the IMMCPropertyPage interface then the page will receive this as the Data parameter to IMMCPropertyPage_Initialize.

Return Values

Remarks

The AddPage method is typically called from the snap-in in the Views_CreatePropertyPages event but it can also be called from within a property page to add a page to a running property sheet.


AddPageProvider Method

Can be called from a property page to create a C++ COM object that will add property pages to the sheet.

Syntax

AddPageProvider(CLSIDPageProvider As String, hwndSheet As Long) As Object

The AddPageProvider method syntax has these parts:

Part | Description
CLSIDPageProvider | CLSID of the object to be created. Specify as GUID string in registry format e.g. {00000000-0000-0000-0000-000000000000}
hwndSheet | The window handle of the property sheet is returned in this parameter.

Return Values

Returns an instance of the object specified by CLSIDPageProvider.

Remarks

This method creates an instance of the object and returns it along with the window handle of the property sheet. The property page can then pass the property sheet's window handle to the COM object so that it can add pages to the property sheet by using the Win32 PSM_ADDPAGE or PSM_INSERTPAGE messages.

This method is typically used to take advantage of existing property pages implemented in C++ such as those provided by the Win32 CreateSecurityPage API. For more information see "Displaying Property Pages to Edit Security Attributes".


AddWizardPage Method

Adds a property page to a wizard property sheet.

Syntax

AddWizardPage(PageName As String, ConfigurationObject As Object, [UseHelpButton], [RightToLeft], [InitData], [Caption])

The AddWizardPage method syntax has these parts:

Part | Description
PageName | The name of the property page as it appears in the project window.
ConfigurationObject | An object of the snap-in's choosing. The specified object will be available to the wizard's property pages as SelectedControls(0). All pages in a wizard should pass the same object for this parameter.
UseHelpButton | Optional. If True then a "Help" button will appear on the property sheet when the page is active.
RightToLeft | Optional. If True then the page is using a right-to-left language such as Hebrew or Arabic.
InitData | Optional. If specified and the property page implements the IMMCPropertyPage interface then the page will receive this as the Data parameter to IMMCPropertyPage_Initialize.
Caption | Optional. If specified will be used as the page's caption. If not specified then the page's Caption property set at design time will be used. The caption is displayed in the wizard's title bar when the page is active.

Return Values

Remarks

For configuration wizards run by MMC, when the user clicks the finish button the snap-in will receive the SnapIn_ConfigurationComplete event and ConfigurationObject will be passed as the parameter to that event.


ChangeCancelToClose Method

Can be called from a property page to change the Cancel button to a Close button.

Syntax

ChangeCancelToClose()

Return Values

Remarks

The ChangeCancelToClose method can be used when the user has made changes in a property sheet that cannot be reversed.


GetPagePosition Method

Can be called from a property page to determine its one-based position in the property sheet.

Syntax

GetPagePosition(hwndPage As Long) As Integer

The GetPagePosition method syntax has these parts:

Part | Description
hwndPage | The property page's window handle. Pass PropertyPage.hWnd.

Return Values

Remarks

This method can be used when the page's position is need in order to call other methods such as MMCPropertySheet.InsertPage and MMCPropertySheet.RemovePage.


InsertPage Method

Can be called from a property page to insert a new page into the property sheet at the specified one-based position.

Syntax

InsertPage(Position As Integer, PageName As String, [Caption], [UseHelpButton], [RightToLeft], [InitData])

The InsertPage method syntax has these parts:

Part | Description
Position | The one-based position at which to insert the page. To determine the position of an existing page use MMCPropertySheet.GetPagePosition.
PageName | The name of the property page as it appears in the project window.
Caption | Optional. If specified will be used as the page's caption. If not specified then the page's Caption property set at design time will be used.
UseHelpButton | Optional. If True then a "Help" button will appear on the property sheet when the page is active.
RightToLeft | Optional. If True then the page is using a right-to-left language such as Hebrew or Arabic.
InitData | Optional. If specified and the property page implements the IMMCPropertyPage interface then the page will receive this as the Data parameter to IMMCPropertyPage_Initialize.

Return Values

Remarks

This method can only be used from within a property page and should not be called from the Views_CreatePropertyPages event. To add property pages in that event use MMCPropertySheet.AddPage.


PressButton Method

Can be called from a property page to simulate pressing a property sheet button.

Syntax

PressButton(Button As SnapInPropertySheetButtonConstants)

The PressButton method syntax has these parts:

Part | Description
Button | Button to be pressed. See below.

Settings

The Button argument settings are:

Constant | Description
siApplyButton | Apply button (property sheets only).
siBackButton | Back button (wizards only).
siCancelButton | Cancel button
siFinishButton | Finish button (wizards only).
siHelpButton | Help button.
siNextButton | Next button (wizards only).
siOKButton | OK button (property sheets only).

Return Values

Remarks

Built on Wednesday, October 27, 1999


RebootSystem Method

Can be called from a property page to request that MMC reboot the system if the user clicks the OK button to close the property sheet.

Syntax

RebootSystem()

Return Values

Remarks

Built on Wednesday, October 27, 1999


RecalcPageSizes Method

Can be called from a property page to request that the property sheet recalculate the page sizes.

Syntax

RecalcPageSizes()

Return Values

Remarks

The RecalcPageSizes method should be called from a property page after adding or inserting a new property page that is not the same size as the existing pages.


RemovePage Method

Can be called from a property page to remove a page from the property sheet.

Syntax

RemovePage(Position As Integer)

The RemovePage method syntax has these parts:

Part | Description
Position | One-based position of the page.

Return Values

Remarks

A page can determine its one-based position by calling MMCPropertySheet.GetPagePosition.


RestartWindows Method

Can be called from a property page to request that MMC restart windows if the user clicks the OK button to close the property sheet.

Syntax

RestartWindows()

Return Values

Remarks

This method has the same effect as MMCPropertySheet.RebootSystem. If it is called and the user clicks the OK button, then the system will be rebooted. It is maintained for compatibility with the corresponding Win32 property sheet interface.


SetFinishButtonText Method

Can be called from a property page in a wizard to change the text of the Finish button and enable it.

Syntax

SetFinishButtonText(Text As String)

The SetFinishButtonText method syntax has these parts:

Part | Description
Text | New text for Finish button.

Return Values

Remarks

This method also hides the Back and Next buttons.


SetTitle Method

Can be called from a property page to change the title of the property sheet.

Syntax

SetTitle(Text As String, UsePropertiesForInTitle As Boolean)

The SetTitle method syntax has these parts:

Part | Description
Text | New title text.
UsePropertiesForInTitle | If True then Win32 adds "Properties for" to the beginning of the property sheet title.

Return Values

Remarks

Built on Wednesday, October 27, 1999


SetWizardButtons Method

Can be called from a property page in a wizard to change the state of the wizard's Back, Next, and Finish buttons.

Syntax

SetWizardButtons(EnableBack As Boolean, NextOrFinish As WizardPageButtonConstants)

The SetWizardButtons method syntax has these parts:

Part | Description
EnableBack | If True then the Back button is enabled.
NextOrFinish | Determines whether a Next or Finish button will be displayed. See below.

Settings

The NextOrFinish argument settings are:

Constant | Description
EnabledNextButton | Display an enabled Next button instead of the Finish button.
DisabledNextButton | Display an disabled Next button instead of the Finish button.
EnabledFinishButton | Display an enabled Finish button instead of the next button.
DisabledFinishButton | Display an disabled Finish button instead of the Next button.

Return Values

Remarks

Built on Wednesday, October 27, 1999


MMCPropertySheetProvider

MMCPropertySheetProvider is available as a property of the current View. It allows the snap-in to programmatically initiate the display of a property sheet or wizard.

CreatePropertySheet creates a new property sheet. The Type parameter determines whether the property sheet will contain property pages or a wizard. Wizard 97-style wizards require using Picture objects on the property pages to hold the header and watermark bitmaps. For more information see "Creating Wizard97 Style Wizards." The Objects parameter may contain one or more objects that will be passed in the Selection parameter to the subsequent Views_QueryPagesFor and Views_CreatePropertyPages events. For property sheets, this object (or objects) will also available to the property page in its PropertyPage_SelectionChanged event in SelectedControls. For wizards, the object in SelectedControls(0) is the ConfigurationObject parameter to MMCPropertySheet.AddWizardPage.

AddPrimaryPages asks MMC to allow the snap-in to add its pages to the sheet. This causes the Views_QueryPagesFor and Views_CreatePropertyPages events to be fired.

AddExtensionPages asks MMC to allow extension snap-ins to add their pages to the sheet. Extension snap-ins implemented in Visual Basic will receive the ExtensionSnapIn_CreatePropertyPages event.

Show displays the property sheet or runs the wizard. The Page parameter specifies the page that should be shown first. It is the one-based ordinal position of the sequence in which pages were added in Views_CreatePropertyPages.

FindPropertySheet asks MMC to determine whether the property sheet for the specified object(s) is currently being displayed. If it is found then the sheet is made active and the method returns True.

Clear tells MMC to release all resources associated with the property sheet. This method should be called if a property sheet is created but not shown.

For more information see "Initiating Property Sheet and Wizard Displays Programmatically."


Properties, Methods, and Events

Properties

This object has no properties.

Methods

AddExtensionPages | Requests that MMC ask extensions to add their property pages to the property sheet or wizard.
AddPrimaryPages | Requests that MMC ask the snap-in to add its property pages to the property sheet or wizard.
Clear | Tells MMC to release all resources associated with the property sheet. Should be called if a property sheet is created but not shown.
CreatePropertySheet | Creates a new property sheet or wizard. Objects may contain either a single ScopeItem, a single MMCListItem, or an array of objects containing any combination of ScopeItems and/or MMCListItems.
FindPropertySheet | Asks MMC to determine whether the property sheet for the specified object(s) is currently being displayed. If found then the sheet is made active and the method returns True.
Show | Asks MMC to display the property sheet or wizard. If HWND is not specified then the console's main frame window is used.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


AddExtensionPages Method

Requests that MMC ask extensions to add their property pages to the property sheet or wizard.

Syntax

AddExtensionPages()

Return Values

Remarks

This method should be called after MMCPropertySheetProvider.CreatePropertySheet and MMCPropertySheetProvider.AddPrimaryPages.

If a property page extension is written in Visual Basic then it will receive the ExtensionSnapIn_CreatePropertyPages event during this call.


AddPrimaryPages Method

Requests that MMC ask the snap-in to add its property pages to the property sheet or wizard.

Syntax

AddPrimaryPages(InScopePane As Boolean)

The AddPrimaryPages method syntax has these parts:

Part | Description
InScopePane | If True then the object for which the property sheet is being displayed is in the scope pane.

Return Values

Remarks

This method should be called after MMCPropertySheetProvider.CreatePropertySheet and before MMCPropertySheetProvider.AddExtensionPages.

During this method call the snap-in will receive the Views_QueryPagesFor and Views_CreatePropertyPages events. The Selection parameter to those events will contain the objects passed to the prior MMCPropertySheetProvider.CreatePropertySheet call.


Clear Method

Tells MMC to release all resources associated with the property sheet. Should be called if a property sheet is created but not shown.

Syntax

Clear()

Return Values

Remarks

This method should be called if the snap-in calls MMCPropertySheetProvider.CreatePropertySheet followed by MMCPropertySheetProvider.AddPrimaryPages and MMCPropertySheetProvider.AddExtensionPages and then encounters some error that prevents it from calling MMCPropertySheetProvider.Show.


CreatePropertySheet Method

Creates a new property sheet or wizard.

Syntax

CreatePropertySheet(Title As String, Type As SnapInPropertySheetTypeConstants, Objects, [UsePropertiesForInTitle], [UseApplyNowButton])

The CreatePropertySheet method syntax has these parts:

Part | Description
Title | Text displayed in the property sheet's title bar.
Type | Type of property sheet. See below.
Objects | Variant containing either a single ScopeItem, a single MMCListItem, or an array of Object containing any combination of ScopeItem and/or MMCListItem objects.
UsePropertiesForInTitle | Optional. If True then Win32 adds "Properties for" to the beginning of the property sheet title.
UseApplyNowButton | Optional. If True then the property sheet will have an Apply button.

Settings

The Type argument settings are:

Constant | Description
siPropertySheet | Display a property sheet.
siWizard | Display a wizard
siWizard97 | Display a Wizard97-style wizard.

Return Values

Remarks

After calling this method the snap-in must call MMCPropertySheet.AddPrimaryPages, optionally call MMCPropertySheet.AddExtensionPages, and then MMCPropertySheet.Show.

For Wizard97-style wizards the snap-in must add bitmaps to the page for the watermark and header. For more information see "Creating Wizard97-Style Wizards".


FindPropertySheet Method

Asks MMC to determine whether the property sheet for the specified object(s) is currently being displayed.

Syntax

FindPropertySheet(Objects) As Boolean

The FindPropertySheet method syntax has these parts:

Part | Description
Objects | Pass the same value passed as the Objects parameter to MMCPropertySheetProvider.CreatePropertySheet

Return Values

If the property sheet for the specified object(s) is currently displayed then it will receive the focus and this method will return True. If the property sheet is not currently displayed then this method will return False.

Remarks

MMC runs property sheets in a separate thread. This method allows the snap-in to determine whether a property sheet displayed using MMCPropertySheetProvider is still open.


Show Method

Asks MMC to display the property sheet or wizard.

Syntax

Show(Page As Long, [hwnd])

The Show method syntax has these parts:

Part | Description
Page | Number of the page to display first. Pages are numbered sequentially from one in the order they were added to the property sheet.
hwnd | Optional. Handle of parent window for property sheet. If not specified then the console's main frame window is used.

Return Values

Remarks

Built on Wednesday, October 27, 1999


MMCConsoleVerbs

MMCConsoleVerbs is a fixed-size collection that represents the verbs exposed by the console: copy, cut, paste, rename, delete, open, properties, print, and refresh. It allows the snap-in to enable/disable verbs during the selection events Views_Select and ResultViews_DeselectAll (see "Views") and it can only be used during these events. The collection is indexed using the SnapInConsoleVerbConstants enumeration rather than by integers. This enumeration has values such as siCopy, siCut, and so on. Snap-ins cannot add or remove elements from this collection.

Verb execution occurs when the user clicks the corresponding context menu item, toolbar button, or presses the corresponding shortcut key. For example, when the user clicks the print button, the snap-in receives the Views_Print event. The following is a table of SnapInConsoleVerbConstants and their corresponding events:

The return value settings are:

Verb | Event
siCopy | None. Handled by MMC
SICut | Views_Cut
siDelete | Views_Delete
siNone | None.
siOpen | ScopeItems_Expand (only for a scope item in the result pane).
siPaste | Views_Paste
siPrint | Views_Print
siProperties | Views_QueryPagesFor and Views_CreatePropertyPages
siRefresh | Views_Refresh
siRename | ScopeItems_Rename for a scope item or ResultViews_ItemRename for a list item.

The DefaultVerb property returns the verb that MMC executes when the user presses ENTER or double-clicks the selected items in the result pane. The default verb is also displayed in bold on context menus.

The snap-in can set the default verb by setting Default=True on the corresponding MMCConsoleVerb object. For example, to make properties the default verb the code is:

ConsoleVerbs(siPrint).Default=True

If open is the default verb and the selection is a single scope item in the result pane, then when the user double clicks or presses ENTER MMC expands that scope item and selects it in the scope pane. If open is the default verb and the selection is a list item then MMC does nothing for a double click or ENTER.

If the selection contains scope and/or list items and the default verb is properties then MMC initiates a property sheet display for a double click or ENTER. In that case the snap-in will receive the Views_QueryPageFor and Views_CreatePropertyPages events.

For all other default verbs MMC does nothing on double click or ENTER. To instruct MMC to always do nothing in response to double click and ENTER set the default verb to none:

ConsoleVerbs(siNone).Default=True

See "MMCConsoleVerb" for information on enabling and disabling verbs.


Properties, Methods, and Events

Properties

Count | Returns count of MMCConsoleVerb in the collection.
DefaultVerb | Returns the current default verb.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Count Property

Returns the count of MMCConsoleVerb objects in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


DefaultVerb Property

Returns the currently set default verb.

Syntax

DefaultVerb As SnapInConsoleVerbConstants

Settings

The return value settings are:

Constant | Description
siCopy | Copy verb
SICut | Cut verb
siDelete | Delete verb
siNone | Open verb
siOpen | Open verb
siPaste | Paste verb
siPrint | Print verb
siProperties | Properties verb
siRefresh | Refresh verb
siRename | Rename verb

Remarks

For more information on the default verb see "MMCConsoleVerbs".


MMCConsoleVerb

MMCConsoleVerb encapsulates the properties of a single console verb. Its properties determine whether MMC adds the corresponding toolbar and context menu items to its UI.

Enabled determines whether the verb is enabled for the selected items.

Hidden determines whether the verb's UI elements will be visible.

Checked determines whether a check mark will appear next to the corresponding context menu item and the toolbar button will appear pressed in with the checked style.

Indeterminate determines whether the corresponding toolbar button and context menu item will appear dimmed.

ButtonPressed determines whether the button is currently pressed.


Properties, Methods, and Events

Properties

ButtonPressed | Get/set flag indicating whether the button is being pressed.
Checked | Get/set flag indicating whether the button has the checked style and is being pressed.
Default | Get/set flag indicating whether the verb is executed when the user takes default action such as pressing ENTER or double clicking an item.
Enabled | Get/set flag indicating whether the button accepts user input. A button that does not have this state does not accept user input and is grayed.
Hidden | Get/set flag indicating whether the button is visible and can receive user input.
Indeterminate | Get/set flag indicating whether the button is grayed.
Index | Index of MMCConsoleVerb object in the MMCConsoleVerbs collection.
Key | Key of MMCConsoleVerb object in the MMCConsoleVerbs collection.
Verb | Returns the verb represented by the MMCConsoleVerb object.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


ButtonPressed Property

Get/set flag indicating whether the button is being pressed.

Syntax

ButtonPressed As Boolean

Remarks

Built on Wednesday, October 27, 1999


Checked Property

Get/set flag indicating whether the button has the checked style and is being pressed.

Syntax

Checked As Boolean

Remarks

Built on Wednesday, October 27, 1999


Default Property

Get/set flag indicating whether the verb is displayed in bold in the context menu executed when the user takes default action such as pressing ENTER or double clicking an item.

Syntax

Default As Boolean

Remarks

For more information on the default verb see "MMCConsoleVerbs".


Enabled Property

Get/set flag indicating whether the button accepts user input and the item is enabled on the context menu. A button that does not have this state does not accept user input and is grayed.

Syntax

Enabled As Boolean

Remarks

For verbs that have shortcut keys, a disabled verb will not generate the corresponding event (e.g F5 for refresh).


Hidden Property

Get/set flag indicating whether the button and context menu item is visible and can receive user input.

Syntax

Hidden As Boolean

Remarks

For verbs that have shortcut keys, a hidden verb will not generate the corresponding event (e.g F5 for refresh).


Indeterminate Property

Get/set flag indicating whether the button is grayed.

Syntax

Indeterminate As Boolean

Remarks

Built on Wednesday, October 27, 1999


Index Property

The Index property returns the index of the MMConsoleVerb object in the MMCConsoleVerbs collection. Read-only.

Syntax

Index As Long

Remarks

The MMCConsoleVerbs collection is indexed using the SnapInConsoleVerbConstants enumeration. Possible Index values are:

Constant | Description
siCopy | Copy verb
SICut | Cut verb
siDelete | Delete verb
siNone | Open verb
siOpen | Open verb
siPaste | Paste verb
siPrint | Print verb
siProperties | Properties verb
siRefresh | Refresh verb
siRename | Rename verb


Key Property

The Key property returns the Index property as a string. Read-only.

Syntax

Key As String

Remarks

Built on Wednesday, October 27, 1999


Verb Property

Returns the verb represented by the MMCConsoleVerb object. Read-only.

Syntax

Verb As SnapInConsoleVerbConstants

Settings

Possible settings for the Verb property are:

Constant | Description
siCopy | Copy verb
SICut | Cut verb
siDelete | Delete verb
siNone | Open verb
siOpen | Open verb
siPaste | Paste verb
siPrint | Print verb
siProperties | Properties verb
siRefresh | Refresh verb
siRename | Rename verb

Remarks

Built on Wednesday, October 27, 1999


MMCToolbar

MMCToolbar is similar to the Visual Basic Common Controls Toolbar. It is used to encapsulate the properties of toolbars and menu buttons added by the snap-in to MMC's control bar. Events are fired on the MMCToolbar object. A toolbar can be added to or removed from MMC's control bar in the Views_SetControlbar event for primary snap-ins and in ExtensionSnapIn_SetControlbar for toolbar extensions.

MMC does not allow mixing toolbar buttons and menu buttons within the same toolbar. This means that within a single MMCToolbar object either all buttons have the drop-down style (for menu buttons) or they all have any of the other button styles (default, separator, checked, or group).

The Name property is used to identify the toolbar object in Visual Basic code. A toolbar created at design time becomes a module-level object in the snap-in at run time. It can be referenced by its design-time name, for example, Toolbar1.Tag = 1.

The Buttons property contains a reference to an MMCButtons collection that defines the buttons appearing on the toolbar.

The ImageList property references an image list that contains the bitmaps used for the toolbar buttons. All bitmaps in the image list must be 16x16 pixels.

The ButtonClick event is fired when the user clicks a toolbar button.

ButtonDropDown is fired when the user clicks a menu button before the designer runtime displays the drop-down menu. This allows the snap-in to change the state of and add or remove items on the drop-down menu.

ButtonMenuClick is fired when the user selects an item on a button's drop-down menu.


Properties, Methods, and Events

Properties

Buttons | Returns collection of toolbar buttons.
ImageList | Get/set image list control containing button images.
Name | Get/set name used to identify the toolbar in Visual Basic code.
Tag | Get/set any extra data needed by the snap-in.

Methods

This object has no methods.

Events

ButtonClick | Called when the user clicks on a toolbar button.
ButtonDropDown | Called when the user clicks on a menu button before the menu is displayed.
ButtonMenuClick | Called when the user clicks on a menu button item.

Remarks

Built on Wednesday, October 27, 1999


ButtonClick Event

Called when the user clicks on a toolbar button.

Syntax

ButtonClick(Selection As MMCClipboard, Button As MMCButton)

The ButtonClick event syntax has these parts:

Part | Description
Selection | Scope items and or list items selected in the scope or result panes.
Button | Button clicked.

Return Values

Remarks

Built on Wednesday, October 27, 1999


ButtonDropDown Event

Called when the user clicks on a menu button before the menu is displayed.

Syntax

ButtonDropDown(Selection As MMCClipboard, Button As MMCButton)

The ButtonDropDown event syntax has these parts:

Part | Description
Selection | Scope items and or list items selected in the scope or result panes.
Button | Menu button clicked.

Return Values

Remarks

Built on Wednesday, October 27, 1999


ButtonMenuClick Event

Called when the user clicks on a menu button item.

Syntax

ButtonMenuClick(Selection As MMCClipboard, ButtonMenu As MMCButtonMenu)

The ButtonMenuClick event syntax has these parts:

Part | Description
Selection | Scope items and or list items selected in the scope or result panes.
ButtonMenu | Item on menu button drop-down menu that was clicked.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Buttons Property

Returns collection of toolbar buttons.

Syntax

Buttons As MMCButtons

Remarks

Buttons are normally defined at design time but they can be added and removed from the collection at runtime both before and while the toolbar is displayed. Changing the contents of the collection while the toolbar is displayed changes the toolbar displayed by MMC.


ImageList Property

Get/set image list control containing button images.

Syntax

ImageList As MMCImageList

Remarks

Built on Wednesday, October 27, 1999


Name Property

Get/set name used to identify the toolbar in Visual Basic code.

Syntax

Name As String

Remarks

Built on Wednesday, October 27, 1999


Tag Property

Allows the snap-in to associate data with the toolbar.

Syntax

Index Tag As Variant

Remarks

Built on Wednesday, October 27, 1999


MMCButtons

MMCButtons contains a collection of MMCButton objects that represent the buttons on a toolbar. Buttons can be added or removed at run time before or after the toolbar is added to MMC's control bar.


Properties, Methods, and Events

Properties

Count | Get/set count of buttons in the collection.
Item | Get/set a button from the collection indexed by ordinal integer or by key.

Methods

Add | Adds a new button to the collection.
Clear | Removes all buttons from the collection.
Remove | Removes a button from the collection indexed by ordinal integer or by key.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Add Method

Adds a new button to the collection.

Syntax

Add([Index], [Key], [Caption], [Style], [Image], [ToolTipText]) As MMCButton

The Add method syntax has these parts:

Part | Description
Index | Index of the new button in the collection. If not specified the button is appended.
Key | Key of the new button in the collection. If not specified then the key is set to the index as a string.
Caption | Optional. Only used if the toolbar defines a menu button. Specifies the initial value of MMCButton.Caption which is displayed as the text of the menu button.
Style | Optional. Determines button style and initial value of MMCButton.Style. For menu buttons, this must be siDropDown. For toolbars, it must be anything but siDropDown.
Image | Optional. Toolbars only. Index or key of image for button in MMCToolbar.ImageList. Initial value for MMCButton.Image.
ToolTipText | Optional. Toolbars only. Tooltip displayed when user holds mouse over button. Initial value for MMCButton.ToolTipText. When adding a button to a currently displayed toolbar this property must be specified if a tooltip is desired. Setting MMCButton.ToolTipText later has no effect.

Settings

Possible settings for Style are:

Constant | Description
siButtonGroup | The button remains pressed until another button in the group is pressed. Exactly one button in the group can be pressed at any one moment.
siCheck | The button is a check button that can be checked or unchecked.
siDefault | The button is a regular push button.
siDropDown | Menu button drop down. Use this style to create a toolbar that defines a menu button.
siSeparator | The button functions as a separator.

Return Values

Newly created MMCButton object.

Remarks

An MMCToolbar object can define either a toolbar or a menu button (MMC does not allow mixing the two).If the MMCToolbar object defines a menu button then all buttons must have the siDropDown style. If the MMCToolbar object defines a toolbar then the buttons can have any style except siDropDown.


Clear Method

Removes all buttons from the collection.

Syntax

Clear()

Return Values

Remarks

If the toolbar is currently displayed then all buttons will be removed from MMC toolbar.


Count Property

Get/set count of buttons in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


Item Property

Get/set a button from the collection indexed by ordinal integer or by key. This is the default property.

Syntax

MMCButtons.Item(Index) As MMCButton

or

MMCButtons (Index) As MMCButton

Remarks

Built on Wednesday, October 27, 1999


Remove Method

Removes a button from the collection indexed by ordinal integer or by key.

Syntax

Remove(Index)

The Remove method syntax has these parts:

Part | Description
Index | Index or key of button to remove.

Return Values

Remarks

If the toolbar is currently displayed then the button will be removed from MMC toolbar.


MMCButton

MMCButton represents a single button on a toolbar. Except for Style, button properties can be changed at any time.

Style determines the type of button. If a button has the drop-down style then it represents a menu button and the snap-in must populate its ButtonMenus collection. MMC does not allow mixing buttons and menu buttons on the same toolbar. If one button has the drop-down style then all other buttons must also have that style.

Caption is used only for menu buttons. It contains the text that is displayed within the button on MMC's control bar.

ToolTipText contains the text for the tooltip displayed when the user holds the mouse over the button.

Image contains the index or key of the image for the button in the toolbar's image list. It is not used for menu buttons.

Enabled determines whether the button will accept user input.

Value determines whether the button is currently pressed.

Visible determines whether the button is visible.

MixedState determines whether the button appears in indeterminate state (dimmed).

ButtonMenus contains a reference to an MMCButtonMenu collection that defines the items displayed when a button menu drops down.


Properties, Methods, and Events

Properties

ButtonMenus | Returns collection of button menu objects for a menu button.
Caption | Get/Set caption for a menu button. Not used for a toolbar button.
Enabled | Get/set flag indicating whether the button accepts user input. A button that does not have this state does not accept user input and is grayed.
Image | Get/set the ordinal index or key of the image for the button in the toolbar's image list.
Index | Returns the index of the button in the buttons collection.
Key | Returns the key of the button in the buttons collection.
MixedState | Get/set a flag indicating whether the button appears in an indeterminate state
Style | Get/set the button style.
Tag | Get/set any extra data needed by the snap-in
ToolTipText | Get/set the text displayed when the mouse cursor is over the button.
Value | Get/set a flag indicating whether the button is currently pressed.
Visible | Get/set a flag indicating whether the button is currently visible.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


ButtonMenus Property

Returns collection of MMCButtonMenu objects for the button. If the button defines a menu button, then this collection contains an element for each item displayed on the drop-down menu when the user clicks the menu button.

Syntax

ButtonMenus As MMCButtonMenus

Remarks

Built on Wednesday, October 27, 1999


Caption Property

Get/Set caption for a menu button. Not used for a button.

Syntax

Caption As String

Remarks

Built on Wednesday, October 27, 1999


Enabled Property

Get/set flag indicating whether the button accepts user input. A button that does not have this state does not accept user input and is grayed.

Syntax

Enabled As Boolean

Remarks

Built on Wednesday, October 27, 1999


Image Property

Get/set the ordinal index or key of the image for the button in the toolbar's image list (MMCToolbar.ImageList).

Syntax

Image As Variant

Remarks

Built on Wednesday, October 27, 1999


Index Property

Returns the index of the button in the buttons collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Returns the key of the button in the buttons collection.

Syntax

Key As String

Remarks

Built on Wednesday, October 27, 1999


MixedState Property

Get/set a flag indicating whether the button appears in an indeterminate state.

Syntax

MixedState As Boolean

Remarks

Built on Wednesday, October 27, 1999


Style Property

Get/set the button style.

Syntax

Style As SnapInButtonStyleConstants

Settings

Possible settings for the Style property are:

Constant | Description
siButtonGroup | The button remains pressed until another button in the group is pressed. Exactly one button in the group can be pressed at any one moment.
siCheck | The button is a check button that can be checked or unchecked.
siDefault | The button is a regular push button.
siDropDown | Menu button drop down. Use this style to create a toolbar that defines a menu button.
siSeparator | The button functions as a separator.

Remarks

An MMCToolbar object can define either a toolbar or a menu button (MMC does not allow mixing the two).If the MMCToolbar object defines a menu button then all buttons must have the siDropDown style. If the MMCToolbar object defines a toolbar then the buttons can have any style except siDropDown.


Tag Property

Allows the snap-in to associate data with the button.

Syntax

Tag As Variant

Remarks

Built on Wednesday, October 27, 1999


ToolTipText Property

Get/set the text displayed when the mouse cursor is over the button.

Syntax

ToolTipText As String

Remarks

This property can be set at design time or when a new button is added to the collection at runtime. Setting it after the button is displayed by MMC has no effect.


Value Property

Get/set a flag indicating whether the button is currently pressed.

Syntax

Value As SnapInButtonValueConstants

Remarks

Built on Wednesday, October 27, 1999


Visible Property

Get/set a flag indicating whether the button is currently visible.

Syntax

Visible As Boolean

Remarks

Built on Wednesday, October 27, 1999


MMCButtonMenus

MMCButtonMenus is a collection of MMCButtonMenu objects that defines the items displayed when a button menu drops down. It is referenced in MMCButton.ButtonMenus. Button menus can be added or removed at any time except while the drop-down menu is displayed. Snap-ins typically use the MMCToolbar_ButtonDropDown event to adjust the contents of the collection prior to the display of the drop-down menu.


Properties, Methods, and Events

Properties

Count | Get/set count of button menu objects in the collection.
Item | Get/set a button menu object from the collection indexed by ordinal integer or by key.

Methods

Add | Adds a new button menu object to the collection.
Clear | Removes all button menu objects from the collection.
Remove | Removes a button menu object from the collection indexed by ordinal integer or by key.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Add Method

Adds a new button menu object to the collection.

Syntax

Add([Index], [Key], [Text]) As MMCButtonMenu

The Add method syntax has these parts:

Part | Description
Index | Optional. Index of new MMCButtonMenu object. If not specified object is appended to the collection.
Key | Optional. Key of new MMCButtonMenu object. If not specified key is set to index as string.
Text | Initial value for MMCButtonMenu.Text.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Clear Method

Removes all button menu objects from the collection.

Syntax

Clear()

Return Values

Remarks

Built on Wednesday, October 27, 1999


Count Property

Get/set count of button menu objects in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


Item Property

Get/set a button menu object from the collection indexed by ordinal integer or by key.

Syntax

Item(Index) As MMCButtonMenu

Remarks

Built on Wednesday, October 27, 1999


Remove Method

Removes a button menu object from the collection indexed by ordinal integer or by key.

Syntax

Remove(Index)

The Remove method syntax has these parts:

Part | Description
Index | Index or key of MMCButtonMenu object to be removed from the collection.

Return Values

Remarks

Built on Wednesday, October 27, 1999


MMCButtonMenu

MMCButtonMenu represents an item displayed when a button menu drops down.

Text contains the text for the menu item.

Visible determines whether the menu is visible at run time.

Enabled determines whether the user can select the menu at run time.

Grayed determines whether the menu is dimmed and disabled at run time.

Checked determines whether the menu has a check mark displayed next to its caption.

MenuBreak indicates whether the menu item begins a new column.

MenuBarBreak indicates whether the menu item begins a new column with a separating vertical line.

Separator determines whether the item is a horizontal separator line.

Parent references the MMCButton object that owns the MMCButtonMenus collection that contains the menu item.


Properties, Methods, and Events

Properties

Checked | Get/set a flag indicating whether the button menu item appears with a check mark.
Enabled | Get/set flag indicating whether the user can select the button menu item.
Grayed | Get/set a flag indicating whether the button menu item is grayed.
Index | Returns the index of the button menu object in the button menu collection.
Key | Returns the key of the button menu object in the button menu collection.
MenuBarBreak | Get/set a flag indicating whether the button menu item begins a new column with a separating vertical line.
MenuBreak | Get/set a flag indicating whether the button menu item begins a new column without any separating vertical line.
Parent | Returns the button object that owns the button menu.
Separator | Get/set a flag indicating whether the button menu item is a horizontal separator line.
Tag | Get/set any extra data needed by the snap-in.
Text | Get/set the text of the button menu item.
Visible | Get/set a flag indicating whether the button menu item is currently visible.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Checked Property

Get/set a flag indicating whether the button menu item appears with a check mark.

Syntax

Checked As Boolean

Remarks

Built on Wednesday, October 27, 1999


Enabled Property

Get/set flag indicating whether the user can select the button menu item.

Syntax

Enabled As Boolean

Remarks

Built on Wednesday, October 27, 1999


Grayed Property

Get/set a flag indicating whether the button menu item is grayed.

Syntax

Grayed As Boolean

Remarks

Built on Wednesday, October 27, 1999


Index Property

Returns the index of the button menu object in the button menu collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Returns the key of the button menu object in the button menu collection.

Syntax

Key As String

Remarks

Built on Wednesday, October 27, 1999


MenuBarBreak Property

Get/set a flag indicating whether the button menu item begins a new column with a separating vertical line.

Syntax

MenuBarBreak As Boolean

Remarks

Built on Wednesday, October 27, 1999


MenuBreak Property

Get/set a flag indicating whether the button menu item begins a new column without any separating vertical line.

Syntax

MenuBreak As Boolean

Remarks

Built on Wednesday, October 27, 1999


Parent Property

Returns the button object that owns the button menu.

Syntax

Parent As MMCButton

Remarks

Built on Wednesday, October 27, 1999


Separator Property

Get/set a flag indicating whether the button menu item is a horizontal separator line.

Syntax

Separator As Boolean

Remarks

Built on Wednesday, October 27, 1999


Tag Property

Get/set any extra data needed by the snap-in.

Syntax

Tag As Variant

Remarks

Built on Wednesday, October 27, 1999


Text Property

Get/set the text of the button menu item.

Syntax

Text As String

Remarks

Built on Wednesday, October 27, 1999


Visible Property

Get/set a flag indicating whether the button menu item is currently visible.

Syntax

Visible As Boolean

Remarks

Built on Wednesday, October 27, 1999


MMCControlbar

MMCControlbar represents the console's control bar and is used to add and remove the snap-in's toolbars and menu buttons. This object is only available within the Views_SetControlbar, Views_UpdateControlbar, ExtensionSnapIn_SetControlbar, and ExtensionSnapIn_UpdateControlbar events.

The Attach method adds a control to MMC's control bar.

The Detach method removes a control from MMC's control bar.

In MMC 1.1 and MMC 1.2 MMCToolbar is the only type of control that can be added to the control bar.


Properties, Methods, and Events

Properties

This object has no properties.

Methods

Attach | Attaches a control to the console's control bar. Only MMCToolbar controls are supported at this time. An MMCToolbar object must contain exclusively buttons or exclusively menu buttons.
Detach | Detaches a control from the console's control bar. Only MMCToolbar controls are supported at this time.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Attach Method

Attaches a control to the console's control bar. Only MMCToolbar controls are supported at this time. Toolbars must contain exclusively buttons or exclusively menu buttons.

Syntax

Attach(Control As Object)

The Attach method syntax has these parts:

Part | Description
Control | MMCToolbar object to be added to the console's controlbar.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Detach Method

Detaches a control from the console's control bar. Only MMCToolbar controls are supported at this time.

Syntax

Detach(Control As Object)

The Detach method syntax has these parts:

Part | Description
Control | MMCToolbar object to be removed from the console's controlbar.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Taskpad

Taskpad encapsulates the properties of a snap-in taskpad. It is referenced from MMCListView.Taskpad.

Name identifies the taskpad in Visual Basic code. If a taskpad is defined at design time in the designer window then Name will be the same as the taskpad's name in the designer. It is also used as the group name. Primary Visual Basic snap-ins do not use the group name but extension snap-ins (both Visual Basic and C++) need to know the group name in order to extend the taskpad.

Type is an enumeration that indicates whether the snap-in is a taskpad, a list view taskpad, or a custom taskpad.

Title is a string displayed at the top of the taskpad.

DescriptiveText is a string displayed at the top of the taskpad beneath the title. This text can be a phrase that serves as a subtitle or instructions.

For list view taskpads ListpadStyle determines whether the listpad control on the taskpad is vertical or horizontal. The default is vertical. ListpadTitle contains the string displayed directly above the list view control. ListpadHasButton indicates whether a button is displayed to the right of the list pad title. If ListpadHasButton=True then ListpadButtonText contains the text displayed on the button. ListView contains the name of a list view defined at design time that is used to access the listpad control on the list view taskpad. At run time the snap-in uses ResultView.ListView just as it would for a list view in the result pane. If Taskpad.ListView is not set then the snap-in must initialize the properties of ResultView.ListView in ResultViews_Initialize.

For custom taskpads URL contains the res:// URL of the taskpad template.

For default taskpads and list view taskpads BackgroundType is an enumeration that indicates what type of background image the snap-in wants to display on the taskpad. The following table describes the different image types and the extra information required for each type.

Value | Meaning
siBitmap | MouseOverImage contains the res:// URL of a bitmap resource.
siVanillaGIF | MouseOverImage contains the res:// URL of a custom resource containing a transparent GIF image where index 0 is transparent.
siChocolateGIF | MouseOverImage contains the res:// URL of a custom resource containing a transparent GIF image where index 1 is transparent.
siSymbol | The image consists of a string of characters in a symbol font. SymbolString contains the string. EOTFile contains the res:// URL of the font file. FontFamily contains the font family name used to display the string.
siNoImage | No image is used. No extra information is needed.

For more information on using images see "Using Resources in Taskpads."

Tasks contains a reference to the Tasks collection that defines the task buttons on a taskpad or list view taskpad.


Properties, Methods, and Events

Properties

BackgroundType | Background image type when using an MMC taskpad template (default or list view taskpad). A background image is not required.
DescriptiveText | Text displayed at the top of the taskpad beneath the title. This text can be a phrase that serves as a subtitle or instructions (such as 'Click an action to perform.').
EOTFile | res:// URL of the font's EOT file
FontFamily | Font family name of the symbol string to display
ListpadButtonText | If ListpadHasButton is True then this is the text for the button.
ListpadHasButton | If set to True then a button is placed directly above the list control to the right of the title text. When the user clicks on this button the ResultViews_ListpadButtonClick event is fired.
ListpadStyle | Determines whether the list view control uses a vertical or horizontal layout.
ListpadTitle | The text placed directly above the list view control.
ListView | For list view taskpads this can optionally be the name of an associated list view that will be used to define the list view control's configuration.
MouseOffImage | Reserved for future use. Not currently used.
MouseOverImage | res:// URL of image displayed for taskpad background when user moves mouse over taskpad area.
Name | Name used to identify the taskpad in Visual Basic code.
SymbolString | Characters to display using the symbol font.
Tasks | Collection of objects containing the properties of each task in the taskpad.
Title | Title displayed at the top of the taskpad. Optional.
Type | Type of taskpad (default, listpad, or custom).
URL | For custom taskpads only. res:// URL of the HTML page used by the taskpad.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


BackgroundType Property

Background image type when using an MMC taskpad template (default or list view taskpad). A background image is not required.

Syntax

BackgroundType As SnapInTaskpadImageTypeConstants

Settings

Possible settings for the BackgroundType property are:

Constant | Description
siBitmap | MouseOverImage contains the res:// URL of a bitmap image.
siChocolateGIF | MouseOverImage contains the res:// URL of a custom resource containing a transparent GIF image where index 1 is transparent.
siNoImage | The taskpad does not have a background image.
siSymbol | The background image consists of a string of characters in a symbol font. SymbolString contains the string. EOTFile contains the res:// URL of the font file. FontFamily contains the font family name used to display the string.
siVanillaGIF | MouseOverImage contains the res:// URL of a custom resource containing a transparent GIF image where index 0 is transparent.

Remarks

Built on Wednesday, October 27, 1999


DescriptiveText Property

Text displayed at the top of the taskpad beneath the title. This text can be a phrase that serves as a subtitle or instructions (such as 'Click an action to perform.').

Syntax

DescriptiveText As String

Remarks

Built on Wednesday, October 27, 1999


EOTFile Property

res::// URL of the symbol font's EOT file

Syntax

EOTFile As String

Remarks

Only used if BackgroundImageType is siSymbol. See "Using Resources in Taskpads" for more information.


FontFamily Property

Font family name of the symbol string to display.

Syntax

FontFamily As String

Remarks

Only used if BackgroundImageType is siSymbol. See "Using Resources in Taskpads" for more information.


ListpadButtonText Property

If the ListpadHasButton is True then this is the text for the button.

Syntax

ListpadButtonText As String

Remarks

Built on Wednesday, October 27, 1999


ListpadHasButton Property

If the ListpadHasButton property is True then a button is placed directly above the list view control to the right of the title text. When the user clicks on this button the ResultViews_ ListpadButtonClick event is fired.

Syntax

ListpadHasButton As Boolean

Remarks

Built on Wednesday, October 27, 1999


ListpadStyle Property

Determines whether the list view control in a list view taskpad uses a vertical or horizontal layout.

Syntax

ListpadStyle As SnapInListpadStyleConstants

Settings

Possible settings for the ListpadStyle property are:

Constant | Description
siHorizontal | The list view control has a horizontal orientation giving it longer rows with a shorter height.
siVertical | The list view control has a vertical orientation giving it shorter rows with greater height.

Remarks

Built on Wednesday, October 27, 1999


ListpadTitle Property

The text placed directly above the list view control in a list view taskpad.

Syntax

ListpadTitle As String

Remarks

Built on Wednesday, October 27, 1999


ListView Property

For list view taskpads this can optionally be the name of an associated list view that will be used to define the list view control configuration.

Syntax

ListView As String

Remarks

When the snap-in displays a list view taskpad it uses ResultView.Taskpad to access the taskpad properties and ResultView.ListView to access the list view control (the same as for a regular list view in the result pane). If both the taskpad and the list view are defined at design time, then this property may be set at design time to the name of the list view. At runtime, prior to the ResultViews_Initialize event, ResultView.ListView will be initialized with the design time settings.


MouseOffImage Property

Reserved for future use. Not currently used.

Syntax

MouseOffImage As String

Remarks

Built on Wednesday, October 27, 1999


MouseOverImage Property

res:// URL of image displayed for taskpad background when user moves mouse over taskpad area.

Syntax

MouseOverImage As String

Remarks

Only used if BackgroundImageType is siBitmap, siChocolateGIF, or siVanillaGIF. See "Using Resources in Taskpads" for more information.


Name Property

Name used to identify the taskpad in Visual Basic code.

Syntax

Name As String

Remarks

Built on Wednesday, October 27, 1999


SymbolString Property

Characters to display using the symbol font.

Syntax

SymbolString As String

Remarks

Only used if BackgroundImageType is siSymbol. See "Using Resources in Taskpads" for more information.


Tasks Property

Collection of objects containing the properties of each task in the taskpad.

Syntax

Tasks As Tasks

Remarks

For a taskpad defined at design time, this collection will be populated prior to the ResultView_Initialize event. The snap-in can make any runtime changes in that event.


Title Property

Title displayed at the top of the taskpad. Optional.

Syntax

Title As String

Remarks

Built on Wednesday, October 27, 1999


Type Property

Type of taskpad (default, listpad, or custom).

Syntax

Type As SnapInTaskpadTypeConstants

Settings

Possible settings for the Type property are:

Constant | Description
Default | Default taskpad defined by MMC.
Listpad | List view taskpad defined by MMC.
Custom | Custom taskpad defined by the snap-in.

Remarks

Built on Wednesday, October 27, 1999


URL Property

For custom taskpads only. res:// URL of the HTML page used by the taskpad.

Syntax

URL As String

Remarks

The custom taskpad's HTML file can be stored on disk or as a resource in the snap-in's dll. See "Using Resources in Taskpads" for more information.


Tasks

Tasks is collection of Task objects that define the task buttons on a taskpad or list view taskpad. For a taskpad defined at design time the collection is populated by the designer runtime prior to the ResultViews_Initialize event. Individual task properties can be changed before display in the ResultViews_Initialize event. For taskpads defined at design time that event should be used to populate the collection.


Properties, Methods, and Events

Properties

Count | Count of tasks in the collection.
Item | Returns a task object from the collection indexed by ordinal integer or by key.

Methods

Add | Adds a new task object to the collection.
Clear | Removes all task objects from the collection.
Remove | Removes a task object from the collection indexed by ordinal integer or by key.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Add Method

Adds a new task object to the collection.

Syntax

Add([Index], [Key], [Text]) As Task

The Add method syntax has these parts:

Part | Description
Index | Index of the new task in the collection. If not specified the task is appended.
Key | Key of the new task in the collection. If not specified then the key is set to the index as a string.
Text | Initial value for Task.Text

Return Values

Remarks

Built on Wednesday, October 27, 1999


Clear Method

Removes all task objects from the collection.

Syntax

Clear()

Return Values

Remarks

Built on Wednesday, October 27, 1999


Count Property

Returns count of tasks in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


Item Property

Returns a task object from the collection indexed by ordinal integer or by key.

Syntax

Tasks.Item(Index) As Task

or

Tasks(Index) As Task

Remarks

Built on Wednesday, October 27, 1999


Remove Method

Removes a task object from the collection indexed by ordinal integer or by key.

Syntax

Remove(Index)

The Remove method syntax has these parts:

Part | Description
Index | Index or key of task to be removed.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Task

The Task object defines a task button on a default taskpad or list view taskpad.

The Text property contains the text displayed underneath the task's image.

HelpString contains the text displayed in a tooltip when the user moves the mouse over the task's image or text.

Visible indicates whether the task should be displayed in the taskpad. It can be set in ResultView_Initialize. Typical usage of this property is to hide one or more tasks in a taskpad defined at design time.

ActionType is an enumeration that determines the type of action taken when the user clicks the task. The following table shows the different action types, additional information required, and the resulting action.

Value | Action | Additional information
siNotify | Snap-in receives ResultViews_TaskClick. | None.
siURL | MMC navigates to URL in the result pane. | URL property contains URL that MMC should navigate to.
siScript | Executes script code. | Script property specifies a string containing the script code to execute.

When using the siScript action the Script property can optionally begin with one of the following language identifiers: "VBSCRIPT:", "JSCRIPT:", or "JAVASCRIPT:". If the language is not specified then MMC assumes it is "JAVASCRIPT:". An example script is:

"JSCRIPT:alert('Message displayed from a script action')"

For VBSCRIPT MMC calls window.execScript to execute the script. For JSCRIPT and JAVASCRIPT MMC calls eval to execute the script. These calls are made within the DHTML code in MMC's default taskpad and list view taskpad HTML pages.

ImageType is an enumeration that indicates what type of image MMC displays for the task. Every task must have an image. The following table describes the different image types and the extra information required for each type.

Value | Meaning
siBitmap | MouseOverImage contains the res:// URL of a bitmap resource. This bitmap is displayed when the user moves the mouse over the task area. MouseOffImage contains the res:// URL of a bitmap resource displayed when the mouse is not over the task area. At least one of these properties must be set.
siVanillaGIF | MouseOverImage contains the res:// URL of a custom resource containing a transparent GIF image where index 0 is transparent. This image is displayed when the user moves the mouse over the task area. MouseOffImage contains the res:// URL of the same type of GIF displayed when the mouse is not over the task area. At least one of these properties must be set.
siChocolateGIF | MouseOverImage contains the res:// URL of a custom resource containing a transparent GIF image where index 1 is transparent. This image is displayed when the user moves the mouse over the task area. MouseOffImage contains the res:// URL of the same type of GIF displayed when the mouse is not over the task area. At least one of these properties must be set.
siSymbol | The image consists of a string of characters in a symbol font. SymbolString contains the string. EOTFile contains the res:// URL of the font file. FontFamily contains the font family name used to display the string.

For more information on using images see "Using Resources in Taskpads."


Properties, Methods, and Events

Properties

ActionType | An enumeration indicating the type of action triggered when the user clicks a task on the taskpad.
EOTFile | res:: URL of the font's EOT file
FontFamily | Font family name of the symbol string to display
HelpString | The descriptive text displayed in a tooltip when the user moves the mouse over the image or the text for the task.
ImageType | Type of image displayed for task. An image is required.
Index | Returns the index of the task object in the tasks collection.
Key | Returns the key of the task object in the tasks collection.
MouseOffImage | res: URL of image displayed for task when mouse is not over task area. At least one of MouseOverImage and MouseOffImage must be set.
MouseOverImage | res: URL of image displayed for task when user moves mouse over task area. At least one of MouseOverImage and MouseOffImage must be set.
Script | Used only for action type siScript. Contains script code that is run on the taskpad DHTML page when the user clicks the task.
SymbolString | Characters to display using the symbol font.
Tag | Get/set any extra data needed by the snap-in.
Text | The text placed directly to the right of the mouse-over image. This text serves as the label for the task. This text should be an action in the imperative such as 'Add a new user'.
URL | If the action type is siURL then this is the URL to navigate to in the result pane when the user clicks the task.
Visible | Get/set flag indicating whether a task should be displayed in a taskpad. Must be set in ResultViews_Initialize.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


ActionType Property

An enumeration indicating the type of action triggered when the user clicks a task on the taskpad.

Syntax

ActionType As SnapInActionTypeConstants

Settings

Possible settings for the ActionType property are:

Value | Action | Additional information
siNotify | Snap-in receives ResultViews_TaskClick. | None.
siURL | MMC navigates to URL in the result pane. | URL property contains URL that MMC should navigate to.
siScript | Executes script code. | Script property specifies a string containing the script code to execute.

Remarks

Built on Wednesday, October 27, 1999


EOTFile Property

res://: URL of the font's EOT file

Syntax

EOTFile As String

Remarks

Only used if ImageType is siSymbol. See "Using Resources in Taskpads" for more information.


FontFamily Property

Font family name of the symbol string to display

Syntax

FontFamily As String

Remarks

Only used if ImageType is siSymbol. See "Using Resources in Taskpads" for more information.


HelpString Property

The descriptive text displayed in a tooltip when the user moves the mouse over the image or the text for the task.

Syntax

HelpString As String

Remarks

Built on Wednesday, October 27, 1999


ImageType Property

Type of image displayed for task. An image is required.

Syntax

ImageType As SnapInTaskpadImageTypeConstants

Settings

Possible settings for the BackgroundType property are:

Value | Meaning
siBitmap | MouseOverImage contains the res:// URL of a bitmap resource. This bitmap is displayed when the user moves the mouse over the task area. MouseOffImage contains the res:// URL of a bitmap resource displayed when the mouse is not over the task area. At least one of these properties must be set.
siVanillaGIF | MouseOverImage contains the res:// URL of a custom resource containing a transparent GIF image where index 0 is transparent. This image is displayed when the user moves the mouse over the task area. MouseOffImage contains the res:// URL of the same type of GIF displayed when the mouse is not over the task area. At least one of these properties must be set.
siChocolateGIF | MouseOverImage contains the res:// URL of a custom resource containing a transparent GIF image where index 1 is transparent. This image is displayed when the user moves the mouse over the task area. MouseOffImage contains the res:// URL of the same type of GIF displayed when the mouse is not over the task area. At least one of these properties must be set.
siSymbol | The image consists of a string of characters in a symbol font. SymbolString contains the string. EOTFile contains the res:// URL of the font file. FontFamily contains the font family name used to display the string.

Remarks

See "Using Resources in Taskpads" for more information.


Index Property

Returns the index of the task object in the tasks collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Returns the key of the task object in the tasks collection.

Syntax

Key As String

Remarks

Built on Wednesday, October 27, 1999


MouseOffImage Property

res:// URL of image displayed for task when mouse is not over task area. At least one of MouseOverImage and MouseOffImage must be set.

Syntax

MouseOffImage As String

Remarks

Only used if ImageType is siBitmap, siChocolateGIF, or siVanillaGIF. See "Using Resources in Taskpads" for more information.


MouseOverImage Property

res:// URL of image displayed for task when user moves mouse over task area. At least one of MouseOverImage and MouseOffImage must be set.

Syntax

MouseOverImage As String

Remarks

Only used if ImageType is siBitmap, siChocolateGIF, or siVanillaGIF. See "Using Resources in Taskpads" for more information.


Script Property

Used only if ActionType property is siScript. Contains script code that is run on the taskpad DHTML page when the user clicks the task.

Syntax

Script As String

Remarks

When using the siScript action the Script property can optionally begin with one of the following language identifiers: "VBSCRIPT:", "JSCRIPT:", or "JAVASCRIPT:". If the language is not specified then MMC assumes it is "JAVASCRIPT:". An example script is:

"JSCRIPT:alert('Message displayed from a script action')"

For VBSCRIPT MMC calls window.execScript to execute the script. For JSCRIPT and JAVASCRIPT MMC calls eval to execute the script. These calls are made within the DHTML code in MMC's default taskpad and list view taskpad HTML pages.


SymbolString Property

Characters to display using the symbol font.

Syntax

SymbolString As String

Remarks

Only used if ImageType is siSymbol. See "Using Resources in Taskpads" for more information.


Tag Property

Allows the snap-in to associate data with the task.

Syntax

Tag As Variant

Remarks

Built on Wednesday, October 27, 1999


Text Property

The text placed directly to the right of the mouse-over image. This text serves as the label for the task. It should be an action in the imperative such as 'Add a new user'.

Syntax

Text As String

Remarks

Built on Wednesday, October 27, 1999


URL Property

Used only if ActionType property is siURL. This is the URL to navigate to in the result pane when the user clicks the task.

Syntax

URL As String

Remarks

The URL can reference an external resource such as a web site or it can reference an HTML file stored as a resource in the snap-in's DLL. For more information see "Using Resources in Taskpads" and "Using Relative URLs".


Visible Property

Get/set flag indicating whether a task should be displayed in a taskpad. Must be set in ResultViews_Initialize.

Syntax

Visible As Boolean

Remarks

This property is useful when a taskpad defines a set of tasks at design time that may not all need to be displayed at runtime. The snap-in can hid selected tasks in the ResultViews_Initialize event.


MMCMessageView

MMCMessageView encapsulates the properties of a message view in the result pane. It is referenced in MMCListView.MessageView.

TitleText contains the text displayed in the message view's title.

BodyText contains the text displayed in the body of the message view.

IconType is an enumeration that determines the icon displayed in the message view. These are similar to the standard icons used in a message box (error, information, question, warning, and none).


Properties, Methods, and Events

Properties

BodyText | Get/Set the text for the result pane message.
IconType | Get/Set the icon for the result pane message.
TitleText | Get/Set the title for the result pane message.

Methods

Clear Clears the title, text, and icon of the result pane message.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


BodyText Property

Get/Set the text for the result pane message.

Syntax

BodyText As String

Remarks

Built on Wednesday, October 27, 1999


Clear Method

Clears the title, text, and icon of the result pane message.

Syntax

Clear()

Return Values

Remarks

Built on Wednesday, October 27, 1999


IconType Property

Get/Set the icon for the result pane message.

Syntax

IconType As SnapInMessageViewIconTypeConstants

Remarks

Built on Wednesday, October 27, 1999


TitleText Property

Get/Set the title for the result pane message.

Syntax

TitleText As String

Remarks

Built on Wednesday, October 27, 1999


Extensions

Extensions is a collection of Extension objects that encapsulate the properties of all extensions registered for a particular node type. Snap-ins do not directly create Extensions collections. They are referenced in the following object properties:

Reference | Contents
SnapIn.RequiredExtensions | The set of all extensions registered for all of the snap-in's node types.
ScopeItem.DynamicExtensions | The set of dynamic extensions registered for the scope item's node type.
MMCListItem.DynamicExtensions | The set of dynamic extensions registered for the list item's node type.

Extensions.EnableAll enables all of the extensions in the collection.

Extensions.EnableAllStatic enables all of the static extensions in the collection.

For more information see "Extension."


Properties, Methods, and Events

Properties

Count | Count of extension objects in the collection.
Item | Returns an extension object from the collection indexed by ordinal integer or CLSID as string.

Methods

EnableAll | Sets the Enabled property of all extension objects in the collection to the specified value.
EnableAllStatic | Set the Enabled property of all static extension objects in the collection to the specified value.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Count Property

Returns the count of extension objects in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


EnableAll Method

Sets the Enabled property of all extension objects in the collection to the specified value.

Syntax

EnableAll(Enabled As Boolean)

The EnableAll method syntax has these parts:

Part | Description
Enabled | Setting for the Extension.Enabled property of all extension objects in the collection.

Return Values

Remarks

Built on Wednesday, October 27, 1999


EnableAllStatic Method

Set the Enabled property of all static extension objects in the collection to the specified value.

Syntax

EnableAllStatic(Enabled As Boolean)

The EnableAllStatic method syntax has these parts:

Part | Description
Enabled | Setting for the Extension.Enabled property of all extension objects in the collection that represent static extensions.

Return Values

Remarks

An extension is static if does not register itself under the DynamicExtensions sub-key of the snap-in's node type key in the registration database.


Item Property

Returns an extension object from the collection indexed by ordinal integer or CLSID.

Syntax

Extensions.Item(Index) As Extension

or

Extensions (Index) As Extension

Remarks

To reference an extension by CLSID use the registry format as a string e.g. Extensions("{00000000-0000-0000-0000-000000000000}").Enabled = True.


Extension

Extension holds the registration database information for a snap-in registered to extend one of a snap-in's node types.

CLSID contains the extension's CLSID as a string. This is also used as the key for the Extension in the collection.

Name is the extension's name string in the registry. Snap-ins don't always register a name so this string can be empty.

ExtendsContextMenu, ExtendsNameSpace, ExtendsPropertySheet, ExtendsTaskpad, and ExtendsToolbar indicate which features the snap-in extends.

Type is an enumeration that indicates whether the extension is static or dynamic. A static extension is always loaded when the user invokes the extended feature for the node type. For example, a static context menu extension for one of a snap-in's scope items is always loaded when the user displays a context menu. A dynamic extension must be enabled before it can be loaded.

The Enabled property determines whether an extension will be loaded. If the Extension object is part of SnapIn.RequiredExtensions it can be enabled in SnapIn_Initialize to indicate to MMC that the extension should be loaded when the snap-in is loaded. If the Extension object is part of ScopeItem.DynamicExtensions or MMCListItem.DynamicExtensions then it can be enabled when the scope item or list item is created or when the particular feature event is fired (for example, a dynamic context menu extension could be enabled in Views_AddTaskMenuItems). When an extension collection is accessed for the first time, the designer runtime must read the registration database. If performance is critical then the snap-in should defer enabling dynamic extensions until the feature event is fired.

NameSpaceEnabled is used only for dynamic namespace extensions. If NameSpaceEnabled is set to True before the node it extends is expanded, then when the node later expands, the extension will be loaded and it will have the opportunity to add child nodes to the expanding node. If the extension is a Visual Basic snap-in then it will receive the ExtensionSnapIn_Expand event. If NameSpaceEnabled is set to True after the node it extends is expanded, then it will be loaded at that time.

For more information see "Developing Extension and Dual-Mode Snap-ins."


Properties, Methods, and Events

Properties

CLSID | CLSID of the extension.
Enabled | Indicates whether the extension should be created for types other than namespace.
ExtendsContextMenu | Indicates whether the extension extends context menus.
ExtendsNameSpace | Indicates whether the extension extends the name space.
ExtendsPropertySheet | Indicates whether the extension extends property sheets.
ExtendsTaskpad | Indicates whether the extension extends taskpads.
ExtendsToolbar | Indicates whether the extension extends the toolbar.
Index | Index of the extension object in the collection.
Key | Key of the extension object in the collection. Same as CLSID.
Name | Name of the extension. Not always available as some extension snap-ins do not put their name in the registry.
NameSpaceEnabled | Indicates whether the extension should be created for namespace. Used only for dynamic extensions.
Type | Indicates whether the extension is static or dynamic.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


CLSID Property

CLSID of the extension.

Syntax

CLSID As String

Remarks

Stored in registry format e.g. "{00000000-0000-0000-0000-000000000000}".


Enabled Property

Indicates whether the extension should be created for types other than namespace.

Syntax

Enabled As Boolean

Remarks

This property is used for both static and dynamic extensions. For dynamic namepspace extensions, the NameSpaceEnabled property controls the loading of the extension.


ExtendsContextMenu Property

Indicates whether the extension extends context menus.

Syntax

ExtendsContextMenu As Boolean

Remarks

Built on Wednesday, October 27, 1999


ExtendsNameSpace Property

Indicates whether the extension extends the name space.

Syntax

ExtendsNameSpace As Boolean

Remarks

Built on Wednesday, October 27, 1999


ExtendsPropertySheet Property

Indicates whether the extension extends property sheets.

Syntax

ExtendsPropertySheet As Boolean

Remarks

Built on Wednesday, October 27, 1999


ExtendsTaskpad Property

Indicates whether the extension extends taskpads.

Syntax

ExtendsTaskpad As Boolean

Remarks

Built on Wednesday, October 27, 1999


ExtendsToolbar Property

Indicates whether the extension extends the toolbar.

Syntax

ExtendsToolbar As Boolean

Remarks

Built on Wednesday, October 27, 1999


Index Property

Index of the extension object in the collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Key of the extension object in the collection. Same as CLSID.

Syntax

Key As String

Remarks

Built on Wednesday, October 27, 1999


Name Property

Name of the extension. Not always available as some extension snap-ins do not put their name in the registry.

Syntax

Name As String

Remarks

Built on Wednesday, October 27, 1999


NameSpaceEnabled Property

Indicates whether the extension should be created for namespace.

Syntax

NameSpaceEnabled As Boolean

Remarks

Used only for dynamic namspace extensions.


Type Property

Indicates whether the extension is static or dynamic.

Syntax

Type As SnapInExtensionTypeConstants

Settings

Possible settings for the BackgroundType property are:

Value | Meaning
siDynamic | Dynamic extension - only loaded for a feature if enabled by the snap-in in ScopeItem.DyanmicExtensions or MMCListItem.DynamicExtensions.
siStatic | Static extension - always loaded when the features it extends are used (e.g. context menu displayed).

Remarks

Built on Wednesday, October 27, 1999


ColumnSettings

ColumnSettings is a collection of ColumnSetting objects that contain MMC's column persistence properties. The collection is referenced in View.ColumnSettings. If the collection is empty then MMC does not have any column persistence data. The snap-in can populate the collection and call ColumnSettings.Persist in order to create new column settings.

MMC's column persistence data is stored according to column set ID. ColumnSettings.ColumnSetID contains the ID. For more information on column set IDs and column persistence see "Using Column Persistence."

Requires MMC 1.2 or greater.


Properties, Methods, and Events

Properties

ColumnSetID | String that uniquely identifies the column set in MMC's column persistence data.
Count | Returns count of column settings in the collection.
Item | Returns a column setting from the collection indexed by ordinal integer or by key.

Methods

Add | Adds a new column setting to the collection.
Clear | Removes all column settings from the collection.
Persist | Asks MMC to persists the column settings.
Remove | Removes a column setting from the collection indexed by ordinal integer or by key.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Add Method

Adds a new column setting to the collection.

Syntax

Add([Index], [Key], [Width], [Hidden], [Position]) As ColumnSetting

The Add method syntax has these parts:

Part | Description
Index | Index of the new ColumnSetting object in the collection. If not specified the task is appended.
Key | Key of the new ColumnSetting object in the collection. If not specified key is set to index as string.
Width | Intial value for ColumnSetting.Width.
Hidden | Intial value for ColumnSetting.Hidden.
Position | Intial value for ColumnSetting.Position.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Clear Method

Removes all column settings from the collection.

Syntax

Clear()

Return Values

Remarks

Built on Wednesday, October 27, 1999


ColumnSetID Property

String that uniquely identifies the column set in MMC's column persistence data.

Syntax

ColumnSetID As String

Remarks

Built on Wednesday, October 27, 1999


Count Property

Returns count of column settings in the collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Item Property

Returns a ColumnSetting object from the collection indexed by ordinal integer or by key.

Syntax

ColumnSettings.Item(Index) As ColumnSetting

or

ColumnSettings (Index) As ColumnSetting

Remarks

Built on Wednesday, October 27, 1999


Persist Method

Asks MMC to persists the column settings.

Syntax

Persist()

Return Values

Remarks

Built on Wednesday, October 27, 1999


Remove Method

Removes a column setting from the collection indexed by ordinal integer or by key.

Syntax

Remove(Index)

The Remove method syntax has these parts:

Part | Description
Index | Index or key of the ColumnSetting object to remove.

Return Values

Remarks

Built on Wednesday, October 27, 1999


ColumnSetting

The ColumnSetting object contains properties that define the customization of a single column in MMC's column persistence data.

Width contains the column's width.

Hidden determines whether the column is visible.

Position is the one-based location of the column in the list view. A user can change a column's position by using the Customize dialog box from the MMC View menu.

For more information on column persistence see "Using Column Persistence." Requires MMC 1.2 or greater.


Properties, Methods, and Events

Properties

Hidden | Indicates whether a column is hidden in the list view. If a hidden column is revealed by the user or the snap-in then it will use auto-width unless a specific column width has been set.
Index | Returns the index of the ColumnSetting object in the ColumnSettings collection.
Key | Returns the key of the ColumnSetting object in the ColumnSettings collection.
Position | Get/set the one-based position of the column in the list view.
Width | Get/set the column width in pixels. This property may also be set to siColumnAutoWidth to set the width based on the width of the text in the column's title.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Hidden Property

Indicates whether a column is hidden in the list view. If a hidden column is revealed by the user or the snap-in then it will use auto-width unless a specific column width has been set.

Syntax

Hidden As Boolean

Remarks

Built on Wednesday, October 27, 1999


Index Property

Returns the index of the ColumnSetting object in the ColumnSettings collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Get/set the key of the ColumnSetting object in the ColumnSettings collection.

Syntax

Key As String

Remarks

Built on Wednesday, October 27, 1999


Position Property

Get/set the one-based position of the column in the list view.

Syntax

Position As Long

Remarks

Built on Wednesday, October 27, 1999


Width Property

Get/set the column width in pixels. This property may also be set to siColumnAutoWidth to set the width based on the width of the text in the column's title.

Syntax

Width As Long

Remarks

Built on Wednesday, October 27, 1999


SortKeys

SortKeys is a collection of SortKey objects that contain MMC's column persistence sorting properties. The collection is referenced in View.SortSettings. If the collection is empty then MMC does not have any column persistence data. The snap-in can populate the collection and call SortKeys.Persist to create new column settings. As of MMC 1.2 there can only be one sort key.

MMC's column persistence data is stored according to column set ID. SortKeys.ColumnSetID contains the ID. For more information on column set IDs and column persistence see "Using Column Persistence."

Requires MMC 1.2 or greater.


Properties, Methods, and Events

Properties

ColumnSetID | String that uniquely identifies the sort settings in MMC's column persistence data.
Count | Returns count of sort keys in the collection.
Item | Returns a sort key from the collection indexed by ordinal integer or by key.

Methods

Add | Adds a new sort key to the collection.
Clear | Removes all sort keys from the collection.
Persist | Asks MMC to persists the sort settings.
Remove | Removes a sort key from the collection indexed by ordinal integer or by key.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Add Method

Adds a new sort key to the collection.

Syntax

Add([Index], [Key], [Column], [SortOrder], [SortIcon]) As SortKey

The Add method syntax has these parts:

Part | Description
Index | Index of the new SortKey object in the collection. If not specified the object is appended.
Key | Key of the new SortKey object in the collection. If not specified key is set to index as string.
Column | Initial value of SortKey.Column. Column on which key is defined.
SortOrder | Initial value of SortKey.SortOrder. Order in which column is sorted.
SortIcon | Initial value of SortKey.SortIcon. Determines whether column headers display arrow for sorting direction.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Clear Method

Removes all sort keys from the collection.

Syntax

Clear()

Return Values

Remarks

Built on Wednesday, October 27, 1999


ColumnSetID Property

String that uniquely identifies the sort settings in MMC's column persistence data.

Syntax

ColumnSetID As String

Remarks

Built on Wednesday, October 27, 1999


Count Property

Returns count of sort keys in the collection.

Syntax

Count As Long

Remarks

Built on Wednesday, October 27, 1999


Item Property

Returns a sort key from the collection indexed by ordinal integer or by key. This is the default property.

Syntax

SortKeys.Item(Index) As SortKey

or

SortKeys (Index) As SortKey

Remarks

Built on Wednesday, October 27, 1999


Persist Method

Asks MMC to persists the sort settings.

Syntax

Persist()

Return Values

Remarks

Built on Wednesday, October 27, 1999


Remove Method

Removes a sort key from the collection indexed by ordinal integer or by key.

Syntax

Remove(Index)

The Remove method syntax has these parts:

Part | Description
Index | Index or key of SortKey object to remove.

Return Values

Remarks

Built on Wednesday, October 27, 1999


SortKey

The SortKey object contains properties that define the sort criteria of a single column in MMC's column persistence data.

Column contains the column number of the key.

SortOrder determines whether sorting on the column is ascending or descending.

SortIcon determines whether the column header displays an arrow icon indicating the sort direction.

For more information on column persistence see "Using Column Persistence." Requires MMC 1.2 or greater.


Properties, Methods, and Events

Properties

Column | Set/get column number of this sort key.
Index | Returns the index of the item in the sort keys collection.
Key | Returns the key of the item in the sort keys collection.
SortIcon | Set/get flag to determine whether column headers in report view show sorting direction arrows.
SortOrder | Set/get order of sort on this sort key: ascending or descending.

Methods

This object has no methods.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Column Property

Set/get column number of this sort key.

Syntax

Column As Long

Remarks

Built on Wednesday, October 27, 1999


Index Property

Returns the index of the item in the sort keys collection.

Syntax

Index As Long

Remarks

Built on Wednesday, October 27, 1999


Key Property

Returns the key of the item in the sort keys collection.

Syntax

Key As String

Remarks

Built on Wednesday, October 27, 1999


SortIcon Property

Set/get flag to determine whether column headers in report view show sorting direction arrows.

Syntax

SortIcon As Boolean

Remarks

Built on Wednesday, October 27, 1999


SortOrder Property

Set/get order of sort on this sort key: ascending or descending.

Syntax

SortOrder As SnapInSortOrderConstants

Remarks

Built on Wednesday, October 27, 1999


MMCStringTable

The MMCStringTable object provides a means of storing string data with the snap-in. MMC creates a string table in the console file (.msc) as needed for each snap-in.

Currently, the only parser available for parsing the strings in the string table is the one for LocStudio, an internal Microsoft localization tool. The MMCStringTable object is therefore not very useful for non-Microsoft use.

The MMCStringTable object is a collection of strings in which every string has an ID that is a Long. The collection is indexed by the ID. The Add method adds a string and returns the ID. Find returns the ID of a string that was previously added to the collection.


Properties, Methods, and Events

Properties

Item Retrieves the string specified by the ID from the string table.

Methods

Add | Adds a string to the string table and returns its ID.
Clear | Removes all strings from the string table.
Find | Searches the string table for the specified string and returns its ID.
Remove | Removes the string specified by ID from the string table.

Events

This object has no events.

Remarks

Built on Wednesday, October 27, 1999


Add Method

Adds a string to the string table and returns its ID.

Syntax

Add(String As String) As Long

The Add method syntax has these parts:

Part | Description
String | String to be added to collection.

Return Values

ID of newly added string.

Remarks

Built on Wednesday, October 27, 1999


Clear Method

Removes all strings from the string table.

Syntax

Clear()

Return Values

Remarks

Built on Wednesday, October 27, 1999


Find Method

Searches the string table for the specified string and returns its ID.

Syntax

Find(String As String) As Long

The Find method syntax has these parts:

Part | Description
String | Text of string to search for.

Return Values

ID of string

Remarks

Built on Wednesday, October 27, 1999


Item Property

Retrieves the string specified by the ID from the string table. This is the default property.

Syntax

MMCStringTable.Item(ID As Long) As String

or

MMCStringTable (ID As Long) As String

Remarks

Built on Wednesday, October 27, 1999


Remove Method

Removes the string specified by ID from the string table.

Syntax

Remove(ID As Long)

The Remove method syntax has these parts:

Part | Description
ID | ID of string to be removed.

Return Values

Remarks

Built on Wednesday, October 27, 1999


IWizardPage

IWizardPage is an interface defined by the snap-in designer that must be implemented by property pages used in a wizard. Visual Basic uses COM property pages that were not originally designed to be used in the Win32 property sheets used by MMC. This interface allows the designer runtime to forward events, such as page activation and button clicks, to the property page. Using out parameters from IWizardPage methods, the property page can control the user's navigation among the pages.

Property pages use the Implements keyword at the top of the module as follows:

Implements IWizardPage

This informs Visual Basic that the property page module will implement all of the methods in this interface. In the code window, the left combo box will show IWizardPage and the right combo box can be used to navigate to its methods.

The Activate method is called when a page is about to be displayed. It asks the property page whether to enable the Back button and whether to display a Next or Finish button. If the snap-in chooses a Finish button then it can also choose the text to display in that button.

The Back and Next methods are called when the user clicks Back and Next. They both have a single NextPage As Long parameter that allows the property page to determine what will happen next. The following table explains the possible return values.

Returned value of NextPage | Action
0 (default) | Go to the next or previous page as the user intended.
– 1 | Stay on the current page.
> 0 | Go to that page number. Page numbers start at 1 and are implied by the order in which they were added to the wizard property sheet using MMCPropertySheet.AddWizardPage.

The Finish method is called when the user clicks Finish. It has an Allow As Boolean parameter that the property page can set to indicate whether the property sheet should be closed.

Most wizard pages will also need to implement IMMCPropertyPage. That interface has methods that provide both property sheet and wizard pages with information regarding the user's interaction with the page. For more information see "IMMCPropertyPage".


Properties, Methods, and Events

Properties

This interface has no properties.

Methods

Activate | Called when a page is about to be displayed to allow button settings.
Back | Called when the user clicks the Next button in a configuration wizard. Set NextPage as follows: 0 to go to previous page, -1 to stay on the current page, > 0 to go to that page. Page numbers are implied by the order in which they were added.
Finish | Called when the user clicks the Finish button in a configuration wizard. Indicates whether to allow the wizard to end or to stay on the current page. If allowed then snap-in receives SnapIn_ConfigurationComplete event with data.
Next | Called when the user clicks the Next button in a configuration wizard. Set NextPage as follows: 0 to go to next page, -1 to stay on the current page, > 0 to go to that page. Page numbers are implied by the order in which they were added.

Events

This interface has no events.

Remarks

Built on Wednesday, October 27, 1999


Activate Method

Called when a property page in a wizard is about to be displayed to allow button settings.

Syntax

Activate(EnableBack As Boolean, NextOrFinish As WizardPageButtonConstants, FinishText As String)

The Activate method syntax has these parts:

Part | Description
EnableBack | If True then the Back button is enabled.
NextOrFinish | Determines whether a Next or Finish button is displayed. See below.
FinishText | If a Finish button is used then this argument specifies text within the button.

Settings

The NextOrFinish argument settings are:

Constant | Description
EnabledNextButton | Display an enabled Next button instead of the Finish button.
DisabledNextButton | Display an disabled Next button instead of the Finish button.
EnabledFinishButton | Display an enabled Finish button instead of the next button.
DisabledFinishButton | Display an disabled Finish button instead of the Next button.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Back Method

Called when the user clicks the Back button in a wizard.

Syntax

Back(NextPage As Long)

The Back method syntax has these parts:

Part | Description
NextPage | Determines next page that will be displayed. See below.

Settings

The NextPage argument settings are:

Constant | Description
0 | Allow the user to go to the previous page.
-1 | Stay on the current page.
>0 | Go to the specified page. Pages are numbered from one in the order they were added to the wizard.

Return Values

Remarks

Built on Wednesday, October 27, 1999


Finish Method

Called when the user clicks the Finish button in a configuration wizard.

Syntax

Finish(Allow As Boolean)

The Finish method syntax has these parts:

Part | Description
Allow | If True then the wizard completes. If False then the current page remains displayed.

Return Values

For configuration wizards run by MMC when a snap-in is added to a console, returning Allow=True causes the SnapIn_ConfigurationComplete event.

Remarks

Built on Wednesday, October 27, 1999


Next Method

Called when the user clicks the Next button in a configuration wizard.

Syntax

Next(NextPage As Long)

The Next method syntax has these parts:

Part | Description
NextPage | Determines next page that will be displayed. See below.

Settings

The NextPage argument settings are:

Constant | Description
0 | Allow the user to go to the next page.
-1 | Stay on the current page.
>0 | Go to the specified page. Pages are numbered from one in the order they were added to the wizard.

Return Values

Remarks

Built on Wednesday, October 27, 1999


IMMCPropertyPage

Property pages can optionally implement an interface defined by the designer runtime called IMMCPropertyPage. This interface gives the property page access to extra functionality in MMC that is not part of a standard Visual Basic property page. Property pages use the Implements keyword at the top of the module as follows:

Implements IMMCPropertyPage

This informs Visual Basic that the property page module will implement all of the methods in this interface. In the code window, the left combo box will show IMMCPropertyPage and the right combo box can be used to navigate to its methods.

IMMCPropertyPage_Initialize is called when the page is created following the PropertyPage_SelectionChanged event. It receives a reference to the MMCPropertySheet object and the optional InitData parameter passed to MMCPropertySheet.AddPage. This allows the snap-in to communicate any extra data to the property page other than what is contained in the selected objects. While this parameter is available to all snap-ins, primary snap-ins should store any extra data in ScopeItem.Tag or MMCListItem.Tag. The InitData parameter is only really needed for property page extensions calling MMCPropertySheet.AddPage in the ExtensionSnapIn_CreatePropertyPages event as they do not have access to any Tag properties.

The property page can store the MMCPropertySheet object passed to IMMCPropertyPage_Initialize in a module-level variable and use it to dynamically add and remove pages, activate pages, change button states, and request a reboot after the sheet is closed. For more information see "MMCPropertySheet".

Before the page is displayed, IMMCPropertyPage_GetDialogUnitSize is called to allow the page to determine its size using dialog units. For more information see "Creating Display-Independent Property Pages".

When the user clicks Help on the property sheet the runtime will call IMMCPropertyPage_Help. The property page can call the MMCPropertyHelp function (exported from mssnapr.dll) to ask MMC to display its integrated Help. See "MMCPropertyHelp" for more information.

When the user attempts to cancel the property sheet by hitting ESC, clicking Cancel, or clicking the 'X' button in the upper right corner, then IMMCPropertyPage_QueryCancel is called. The page uses this method to decide whether to allow the cancellation request. If it is allowed then IMMCPropertyPage_Cancel is called for ESC or the Cancel button and IMMCPropertyPage_Close is called for the 'X' button.


Properties, Methods, and Events

Properties

This interface has no properties.

Methods

Cancel | Called when a property sheet or wizard is closed because the user pressed ESC or clicked the Cancel button.
Close | Called when a property sheet or wizard is closed because the user clicked the 'X' button in the upper right corner.
GetDialogUnitSize | Called when a property page is created to allow optionally specifying its size in dialog units. If this method does not contain any code then the design time size will be used.
Help | Called when the user clicks the Help button on a property sheet.
Initialize | Called following PropertyPage_Initialize and PropertyPage_SelectionChanged to pass initialization data received from the snap-in in its MMCPropertySheet.AddPage or AddWizardPage call.
QueryCancel | Called when the user cancels the property sheet or wizard by pressing ESC, clicking the Cancel button, or clicking the 'X' button in the upper right corner.

Events

This interface has no events.

Remarks

Built on Wednesday, October 27, 1999


Cancel Method

Called when a property sheet or wizard is closed because the user pressed ESC or clicked the Cancel button.

Syntax

Cancel()

Return Values

Remarks

Built on Wednesday, October 27, 1999


Close Method

Called when a property sheet or wizard is closed because the user clicked the 'X' button in the upper right corner.

Syntax

Close()

Return Values

Remarks

Built on Wednesday, October 27, 1999


GetDialogUnitSize Method

Called when a property page is created to allow optionally specifying its size in dialog units.

Syntax

GetDialogUnitSize(Height, Width)

The GetDialogUnitSize method syntax has these parts:

Part | Description
Height | Height of property page in dialog units
Width | Width of property page in dialog units

Return Values

Remarks

If this method does not contain any code then the design time size will be used.

For more information see "Creating Display-Independent Property Pages".


Help Method

Called when the user clicks the Help button on a property sheet.

Syntax

Help()

Return Values

Remarks

If the snap-in uses merged HTML help it can display a topic by calling the MMCPropertyHelp API supplied by the designer runtime. For more information on the Help topic format see "MMCPropertyHelp" and "Adding Help to a Snap-in."


Initialize Method

Called following PropertyPage_Initialize and PropertyPage_SelectionChanged to pass initialization data received from the snap-in in its MMCPropertySheet.AddPage or MMCPropertySheet.AddWizardPage call.

Syntax

Initialize(Data, PropertySheet As MMCPropertySheet)

The Initialize method syntax has these parts:

Part | Description
Data | The InitData parameter passed to MMCPropertySheet.AddPage or MMCPropertySheet.AddWizardPage.
PropertySheet | The MMCPropertySheet object used to create the sheet or wizard.

Return Values

Remarks

The property page may store a reference to the MMCPropertySheet object for use following this method.


QueryCancel Method

Called when the user cancels the property sheet or wizard by pressing ESC, clicking the Cancel button, or clicking the 'X' button in the upper right corner.

Syntax

QueryCancel(Allow As Boolean)

The QueryCancel method syntax has these parts:

Part | Description
Allow | If True the property sheet will be canceled.

Return Values

Remarks

If the snap-in returns Allow=True then it will receive a subsequent IMMCPropertyPage_Cancel or IMMCPropertyPage_Close call depending on how the user initiated the cancellation.


MMCPropertyHelp

MMCPropertyHelp is an exported API function from the designer runtime (mssnapr.dll) that allows a property page to invoke MMC's integrated HTML Help. A property page can call this function at any time but it is typically used when the user clicks the property sheet's Help button. Property pages can detect the Help button click by implementing the IMMCPropertyPage interface. IMMCPropertyPage_Help is called when the user clicks Help. To call MMCPropertyHelp the property page needs to declare the function as follows:

Private Declare Function MMCPropertyHelp Lib "mssnapr.dll" (ByVal HelpTopic As String) As Long

The HelpTopic parameter uses the same format as SnapIn.Help. The following is an example of calling MMCPropertyHelp to display this Help topic in this .chm file:

Private Sub IMMCPropertyPage_Help()
    MMCPropertyHelp "VBSnapInsGuide.chm::VBSnapInsGuide/VBSnapInsGuide_15.htm")
End Sub

For more information on the Help topic format see "Adding Help to a Snap-in."


Diagrams

The following diagrams illustrate some of the more commonly used object model elements as they relate to the MMC UI.


Order of Events for Typical Scenarios

[This is preliminary documentation and subject to change.] The following topics describe the order in which events are fired in a snap-in during typical user scenarios.


Loading a Snap-in

[This is preliminary documentation and subject to change.]

SnapIn_Initialize

SnapIn_Load


Expanding a Node

[This is preliminary documentation and subject to change.]

ScopeItems_Expand (only occurs when node is first expanded in the namespace)

ScopeItems_Initialize for every child added


Selecting a Scope Item That Will Display a List View

[This is preliminary documentation and subject to change.]

ScopePaneItems_Initialize

ScopePaneItems_GetResultViewInfo

ResultViews_Initialize

ResultViews_Activate

Views_UpdateControlbar (scope item selected)

Views_Select (scope item selected)

Views_QueryPaste (target is scope item)


Deselecting That Same Scope Item

[This is preliminary documentation and subject to change.]

Views_UpdateControlbar (scope item deselected)

Views_Select (scope item deselected)


Selecting a List Item in the Result Pane

[This is preliminary documentation and subject to change.]

Views_UpdateControlbar (list item selected)

Views_Select (list item selected)


Deselecting That Same List Item in the Result Pane

[This is preliminary documentation and subject to change.]

Views_UpdateControlbar (list item deselected)

Views_Select (list item deselected)


Selecting a Scope Item in the Result Pane

[This is preliminary documentation and subject to change.]

Views_UpdateControlbar (scope item selected)

Views_Select (scope item selected)

Views_QueryPaste (target is scope item)


Deselecting That Same Scope Item in the Result Pane

[This is preliminary documentation and subject to change.]

Views_UpdateControlbar (scope item deselected)

Views_Select (scope item deselected)


Unloading a Snap-in

[This is preliminary documentation and subject to change.]

This scenario assumes that a scope item is selected in the scope pane and it is displaying a list view in the result pane.

Views_UpdateControlbar (scope item deselected)

Views_Select (scope item deselected)

Views_Deactivate

ResultViews_Deactivate

ResultViews_Terminate

Views_Terminate

ScopeItems_Terminate (once for each scope item)

SnapIn_Unload

SnapIn_Terminate


Changes from Beta 2

[This is preliminary documentation and subject to change.]

There have been some feature additions and object model changes since the beta 2 release of the designer in August 1999. This section describes these changes in detail. All snap-ins built with the beta2 release must be recompiled and there will be minor source changes required for some events as explained below.

Accessing the MMC.EXE Command Line Parameters

A snap-in can access the contents of the command line used to start MMC.EXE using SnapIn.MMCCommandLine. For more information see SnapIn.

Changing the State of a ScopeItem in the Result Pane

MMCListView.SetScopeItemState can be used to select, highlight, etc. a ScopeItem in the result pane. For more information see MMCListView.

Storing a Reference to a Live Object in MMCDataObject

It is now possible to pass an object reference through an MMCData object so that a snap-in and an extension can communicate with each other. MMCDataObject.SetData now takes an extra optional parameter that is used when the data contains an object. Pass siObjectReference to indicate that a reference to the object should be stored in the data object. Pass siPersistedObject for peristable VB classes that should be stored using their persistence data. The default is siObjectReference. In the extension snap-in pass the new format specifier siObjectInstance to FormatData in order to get a reference to the object. For persisted objects use the old siObject. For more information see MMCDataObject.

Property Sheets and Wizards

IMMCPropertyPage_Initialize has a new parameter that is the MMCPropertySheet object. This method is now called after PropertyPage_SelectionChanged. If your page needs the Data parameter of IMMCPropertyPage_Initialize then it should set up the page in that method rather than in PropertyPage_SelectionChanged. The page can store the MMCPropertySheet object in a module level variable and use it to control the property sheet using the following new methods:

MMCPropertySheet.ChangeCancelToClose - changes Cancel button to Close

MMCPropertySheet.InsertPage - Inserts a new page into the sheet

MMCPropertySheet.AddPage can also be called to append a new page (pages cannot be added to wizards)

MMCPropertySheet.RecalcPageSizes - resizes the pages, used after adding a page larger than the existing ones

MMCPropertySheet.PressButton - simulates pressing one of the property sheet buttons

MMCPropertySheet.RemovePage - removes a page from the sheet

MMCPropertySheet.ActivatePage - simulates clicking on the tab for a page

MMCPropertySheet.SetFinishButtonText - changes the text of the Finish button on a wizard

MMCPropertySheet.SetTitle - sets the sheet's title

MMCPropertySheet.SetWizardButtons - configures the buttons on a wizard

MMCPropertySheet.GetPagePosition - returns the page's one-based position in the sheet

MMCPropertySheet.RestartWindows - requests that Win32 restart windows when the sheet or wizard is done

MMCPropertySheet.RebootSystem - requests that Win32 reboot the system when the sheet or wizard is done

MMCPropertySheet.AddPageProvider - pass the CLSID of a C++ COM object that will add pages to the sheet. Returns an instance of the object. Typical usage is to take advantage of the CreateSecurityPage API on Windows 2000 for editing ACLs.

IMMCPropertyPage also has some new methods:

IMMCPropertyPage_GetDialogUnitSize is called before a property page is displayed to allow the page to specify its size in dialog units (dlus). MMC's recommended property page size is 252 dlus wide by 218 dlus high. At design time, you can size your page by using a new dlus to twips calculator available on the context menu of the designer treeview. Use the default twips ScaleMode for your property page and it should size correctly on any system.

IMMCPropertyPage_QueryCancel is called when the user attempts to cancel the page by clicking cancel, pressing Esc, or clicking the X in the upper right corner. If you return True then the sheet or wizard will be cancelled and your page will receive IMMCPropertyPage_Cancel.for the cancel button and Esc or IMMCPropertyPage_Close for the X.

The methods IWizardPage_Cancel, IWizardPage_RebootSystem, and IWizardPage_RestartWindows have been removed

For more information see MMCPropertySheet and IMMCPropertyPage.

ScopeItem.PreserveSelection and ScopeItem.ExpandOnReload Replaced by ScopeItem.SlowRetrieval

ScopeItem.ExpandOnReload and ScopeItem.PreserveSelection have been replaced with a single property ScopeItem.SlowRetrieval. If this property is True then MMC will not reselect a scope item when the .msc file is reloaded unless it is the target of a console taskpad. The same rule applies for persisting a view if the scope item is at the root of a view (regardless of whether it is selected). For more information see ScopeItem.

ScopeNode Methods Moved to View

ScopeNode.ExpandInTreeview, ScopeNode.CollapseInTreeview and ScopeNode.NewWindow have been moved to View. For more information see View.

MMCButtons.Add has new TooltipText Parameter

MMCButtons.Add now has an extra optional parameter for the tooltip text. When adding a button at runtime you must pass the tooltip text or it will not appear. For more information see MMCButtons.


Changes from Beta 1

[This is preliminary documentation and subject to change.]

There have been numerous feature additions and object model changes since the beta 1 release of the designer at the MMC Code-a-Thon in March 1999. This section describes these changes in detail. All snap-ins built with the beta1 release must be recompiled and there will be minor source changes required for some events as explained below.

Controlling Appearance of the Plus Sign in the Scope Pane

A snap-in can now remove the plus sign (+) sign from ScopeItems that will not have children. For more information see ScopeNode.

Importing Data from C++ Snap-ins Improved

MMCDataObject now tries multiple ways when using IDataObject to import data from a C++ snapin. For more information see Importing Data from C++ Snap-ins.

Multiple-Selection Property Pages

Multiple-selection property pages are now supported. FileExplorer now supports selecting multiple files and displaying properties. For more information see Developing Extension and Dual-Mode Snap-ins.

Column Persistence

MMC 1.2 column persistence is now supported. See Using Column Persistence for more information.

Column Filtering

MMC 1.2 column filtering is now supported. See Using Column Filtering for more information.

Programmatically Invoking Property Sheets and Wizards

There is a new object MMCPropertySheetProvider and a new property View.PropertySheetProvider that lets a snap-in initiate a property sheet or a wizard. See Initiating Property Sheet and Wizard Displays Programmatically for more information.

Help Topic Links

There is a new property SnapIn.LinkedTopics that can be set to a semicolon-separated list of linked Help topics. See Adding Help to a Snap-in for more information..

Package and Deployment Wizard Installation Directory Changed

When using the Visual Basic Package and Deployment Wizard to create a setup wizard for a snap-in, the snap-in designer runtime (mssnapr.dll) will be installed in <OS drive:>\Program Files\Common Files\Microsoft Shared\ SnapInDesigner.

If a snap-in does not use the Package and Deployment Wizard then its installation program must install mssnapr.dll in this directory in order to ensure compatibility with future versions of the designer. See Deploying a Snap-in for more information.

Command-Line Builds

A snap-in can now be built from a command window by using the /MAKE switch. For example, to build FileExplorer use the following:

"C:\Program Files\Microsoft Visual Studio\VB98\VB6.EXE" /Make FileExplorerSample.vbp

Enabling Dynamic Namespace Extensions

Dynamic namespace extensions can now be added at any time by setting the property Extension.NamespaceEnabled. Until now, this property could only be set in ScopeItems_Initialize. For more information see Developing Extension and Dual-Mode Snap-ins.

Code-Defined Menus

Until now it was not possible to dynamically define new menus or add to existing menus at run time. The menu object model has changed so that MMCMenu now has a Children property that is a collection of MMCMenu objects. For menus defined at design time this collection is populated by the runtime. A snap-in can add items to Children to any number of levels of nesting. See the section on menus for more information.

Control OCX Caching

Snap-ins can now control whether MMC will cache ActiveX controls used in OCX views. See OCX Views for more information.

Font Linking in List Views

Snap-ins can ask MMC to enable font linking in list views using the new property MMCListView.UseFontLinking. See MMCListView for more information.

Initiating Reboot from Property Sheet

Snap-ins can now ask MMC to reboot the system by implementing IMMCPropertyPage in their property pages. See Property Pages for more information.

Message Views

MMC 1.2 now supports a new type of result view called a message view. This is simply an OCX with an icon, a title, and some message text. See Message Views for more information.

Hiding Child Scope Items in the Result Pane

MMC 1.2 has an option to hide child scope items in a result pane. Snap-ins can control this using a new property MMCListView.ShowChildScopeItems. See MMCListView for more information..

Sorting Scope Items in the Result Pane

MMC 1.2 has a feature that allows a snap-in to completely control the sorting of scope items in the result pane. In order to support this feature, the event ResultViews_CompareItems has been changed to receive two parameters of type Object rather than MMCListItem. The snap-in must now check the object types and then decide how to compare them. FileExplorer has a detailed example. Snap-ins that run on MMC 1.1 still use the same event for result pane sorting but the objects passed will always be MMCListItem.

Controlling Task Visibility in Snap-in Taskpads

The Task object has a new property Visible that determines whether a task will be displayed in a taskpad. See Task for more information.

Disabling Sort Buttons on Column Headers

Snap-ins can now specify that the buttons on column headers be disabled in order to prevent the user from initiating a sort. A new property MMCListView.SortHeader controls this setting. See MMCListView for more information.

Hiding Sort Direction Arrows on Column Headers

MMC 1.2 allows a snap-in to hide the sort direction arrows on column headers. A new property MMCListView.SortIcon controls this setting. See MMCListView for more information.

New Selection Type for Non-List Views

When the user sets the focus to a result pane containing a taskpad, URL view, or OCX view, MMC will generate Views_UpdateControlbar and Views_Select events. If your snap-in has toolbar buttons and menu buttons you may also get the drop-down and click events. Because no ScopeItems or ListItems are selected, there are new values for MMCClipboard.SelectionType to represent these cases. They are called siSpecialWeb and siSpecialOcx. See MMCClipboard for more information.

New Event Views_SpecialPropertiesClick

When the result pane contains a non-list view (OCX, URL, or taskpad), and the result pane has focus, and the snap-in has enabled the properties verb, and the user clicks the properties button on the toolbar, this event will be fired. See Views for more information.

Refresh and Print Events Moved to Views

ScopeItems_Refresh, ScopeItems_Print, and ResultViews_ItemPrint have all moved to the Views collection. These have been consolidated into the new events Views_Refresh and Views_Print. Both events have an MMCClipboard parameter containing the current selection. The reason for this move is because the selection can be in a non-list view result pane. In this case, the MMCClipboard's collections are empty and MMClipboard.SelectionType will be siSpecialWeb or siSpecialOCX

Syntax Change for Designer Objects

In new snap-ins or in new event handlers in existing snap-ins there is a slight syntax change for all snap-in designer objects. Prior to this release snap-in objects were represented by their default interfaces, for example:

Views_Select(View As SnapInLib.IView, …

The syntax will now follow the Visual Basic convention of using the class name rather than the default interface name, for example:

Views_Select(View As SnapInLib.View, …

This does not affect any existing snap-ins and it should not make any difference in the way a snap-in is coded.

Property Page Events Moved To Views

The ScopeItems and ResultViews events QueryPagesFor and CreatePropertyPages have been moved to Views. If you have an existing snap-in that handles those events you will need to copy and consolidate the code into the new events. See FileExplorer for examples.

SnapIn.FormatData Now Also on MMCDataObject

The SnapIn.FormatData method is now also available as MMCDataObject.FormatData. This was needed to allow property page extensions to extract data and format it.

ScopeItem Selection Moved to View

There is now a new method View.SelectScopeItem that allows selecting a scope item in the scope pane of the view. If the scope item is not currently in the scope pane then no error occurs.

The properties ScopePaneItem.Expanded and ScopePaneItem.Selected have been removed from the object model. There is no way they can be made to work given the available information from MMC. Setting ScopePaneItem.Selected was being used to programmatically select a ScopeItem. That has been replaced by View.SelectScopeItem. For more information see View.

New Shorthand Properties

There are some new properties of the top-level SnapIn object that serve as shorthand for commonly used objects: CurrentView, CurrentScopePaneItem, CurrentScopeItem, CurrentResultView, and CurrentListView. For more information see SnapIn.

Detecting MMC Version

The View object now has new properties MMCMajorVersion and MMCMinorVersion. These can be used to distinguish between MMC 1.1 and MMC 1.2. See View for more information.

New Views_Load Event

The Views object has a new event called Load. It is fired when the View has been completely initialized by MMC. The new properties View.MMCMajorVersion and View.MMCMinorVersion are available starting from this event. For more information see Views.


Bugs and Caveats

[This is preliminary documentation and subject to change.]

Because this release is a beta there are certain known bugs that can affect usage of the designer. This section lists these issues and recommends workarounds where possible.


Designer Registration

[This is preliminary documentation and subject to change.]

The designer handles all registration and deregistration. When running under the Visual Basic IDE, after you press F5 or click the run button Visual Basic asks the designer to register itself. When you later press the stop button or click End on the Run menu the designer is asked to deregister itself. During the deregister operation all entries under the key HKEY_LOCAL_MACHINE\Software\Microsoft\MMC are removed. If you do not build your snap-in DLL before leaving the IDE then your snap-in will not be registered.

Another side effect of this deregistration in the IDE is that any extensions that registered themselves as extending your snap-in will have their extension entries removed (but not their own entries such as their HKEY_LOCAL_MACHINE\Software\Microsoft\MMC\SnapIns key). A workaround for this is to use a project group for your snap-in and all of its extension snap-ins. When you run in the IDE all projects in the group are compiled and registered. The FileExplorer sample and its extension use a project group for this purpose. To create a project group, open the main snap-in project. For each project to be added, click File, click Add Project, and specify the project's .vbp file. When all the projects have been added, click File, and then click Save Project Group to save the .vbg file that contains the project group information. To build all of the snap-ins in a project group, click File, and then click Make Project Group. To open a project group, select its .vbg file in the Open Project dialog box.


Taskpad Images Not Available Under Debugger

[This is preliminary documentation and subject to change.]

When debugging a snap-in in the Visual Basic IDE, taskpad images will not appear in MMC. This is due to the fact that the res:// URLs required by MMC cannot be created by the runtime when running under the debugger because the snap-in DLL is not loaded and may not even be built. If it is essential to see a taskpad image when debugging then you can use the following steps:

  1. Temporarily change the taskpad properties to a fully qualified res:// URL using the path of your snap-in DLL on the development computer. For example: a bitmap normally specified as #2/MyBitmap should be changed to res://c:\MyProject\MySnapIn.dll/#2/MyBitmap.
  2. Build the snap-in DLL.
  3. Debug the snap-in in the IDE as desired. The snap-in code is executed within the IDE but the taskpad image will be taken from the built DLL.
  4. When debugging is complete, change back the taskpad property and rebuild the DLL.


User Controls Not Created Under Debugger

[This is preliminary documentation and subject to change.]

When debugging a snap-in containing a user control that is used as an OCX view, MMC will not be able to display the OCX view. This problem can be seen when running the FileExplorer sample under the debugger. Select the static node and on the View menu click Welcome to File Explorer. Click the About task and you will see that the MMC splash screen is not displayed in the result pane. There is currently no workaround for this problem.


Moving the Visual Basic 6.0 Installation

[This is preliminary documentation and subject to change.]

If you remove your Visual Basic 6.0 installation and reinstall it at a different location on your hard disk then you must reinstall the snap-in designer.


"Retained in Memory" Project Option Cannot be Used

[This is preliminary documentation and subject to change.]

Visual Basic 6.0 has an option available on the Project/Properties/General page called "Retained in Memory" that is used for Internet Information Server (IIS) applications running on an IIS server. This option instructs the Visual Basic runtime to keep itself and its project information loaded in memory even after the IIS application has terminated. This option cannot be used with snap-ins in order to keep the Visual Basic runtime loaded within mmc.exe.


List View Does Not Repaint when Property Page Open Under Debugger

[This is preliminary documentation and subject to change.]

When running a snap-in under the debugger, if a property page is displayed for a list item, the list view may not correctly paint the list items. To see the list items just move the property sheet window.


Runtime Errors when Debugging Property Pages

[This is preliminary documentation and subject to change.]

Under certain circumstances on Windows NT 4.0, attempting to display property pages while under the Visual Basic debugger will display the runtime error &H800706F8, "The supplied user buffer is not valid for the requested operation." If this occurs then Service Pack is required on the Windows NT 4.0 system.


Tabbing in Property Pages Repeats Property Sheet Buttons

[This is preliminary documentation and subject to change.]

Under certain circumstances on Windows NT 4.0, attempting to display property pages while under the Visual Basic debugger will display the runtime error &H800706F8, "The supplied user buffer is not valid for the requested operation." If this occurs then Service Pack is required on the Windows NT 4.0 system.


Trappable Errors

Trappable errors can occur while a snap-in is running, either within the Visual Basic environment or in MMC. Some of these can also occur during design time or compile time. You can test and respond to trappable errors using the On Error statement and the Err object's Number property. Unused error numbers in the range 1 to 1000 are reserved for future use by Visual Basic.

Note The description "Application-defined or object-defined error" occurs when an error is generated using the Err object's Raise method or the Error statement, but the number does not correspond to an error defined by Visual Basic for applications. Such errors may be defined by the host application (for example, Microsoft Excel or Visual Basic), but if you want to generate them from code, you must use the Raise method, and fill in all relevant arguments.

Remember, while developing in Visual Basic you can get information from Help on a message by pressing F1 or clicking the Help button on a message box or property sheet.


siErrException (Error 9500)

An internal exception has occurred in the snap-in designer runtime. Contact Microsoft product support.


siErrOutOfMemory (Error 9501)

The snap-in designer runtime.could not allocate memory.


siErrInvalidArg (Error 9502)

The snap-in designer runtime found that a parameter passed to a method or property contains an invalid value. This can also occur when an object is passed that has an invalid property value. Re-check the values of all parameters passed.


siErrConsoleError (Error 9503)

MMC.EXE returned the specified error to the snap-in designer runtime.


siErrUnknownFormat (Error 9504)

The snap-in was created using a different version of the snap-in designer and cannot be processed by the current version.


siErrTextSerialzation (Error 9505)

An invalid object was found in the text serialization of a snap-in designer project. This can happen if the snap-in's .DSR file has been damaged or edited.


siErrInternalError (Error 9506)

The snap-in designer encountered an internal error that cannot be handled by the snap-in. Contact Microsoft product support.


siErrUnsupportedStgMedium (Error 9507)

The designer does not support the requested storage medium for serialization. This can occur if the designer is hosted in an environment that attempts to serialize it using an interface other than IPeristStream.


siErrIncompleteWrite (Error 9508)

A serialization write operation completed only partially. This may occur if the snap-in projects files have been corrupted or in the case of a file system error.


siErrIncompleteRead (Error 9509)

A serialization read operation completed only partially. This may occur if the snap-in projects files have been corrupted or in the case of a file system error.


siErrUnsupportedType (Error 9510)

The specified data type is not supported. This error can occur when attempting to set a Variant property on a snap-in designer object. It indicates that the Variant contains a data type that is not supported by the designer.


siErrKeyNotUnique (Error 9511)

The snap-in attempted to add an item to a collection with a key that is already in use by an existing item in that same collection. Change the key name and retry the operation.


siErrElementNotFound (Error 9512)

The snap-in attempted to reference an item in a collection with an index or key that is not used by any element in that collection. Correct the index or key and retry the operation.

This error may occur due to an explicit collection reference or due to an implicit reference as a result of another operation. For example, setting ScopeItem.Folder at runtime will implicitly reference SnapIn.SmallFolders to check that the specified index or key exists in that collection.


siErrInvalidImageType (Error 9514)

A property of type Picture or an MMCImage object does contain the correct type of picture. This can occur if any image used in a list view or in the scope pane contains something other than a bitmap. It can also occur if SnapIn.Icon is set to a picture object containing something other than an icon.


siErrDetachedObject (Error 9515)

This error occurs when a snap-in attempts to use an object that is not a member of an appropriate owning collection or was not referenced from its owning object. For example the following code would return this error:

Dim li As New MMCListItem
li.Text = "Some Text"
li.Update

An MMCListItem object can only be used if it has been created by calling MMCListItems.Add or it is passed as a parameter to an event handler.


siErrToolbarHasNoImageList (Error 9516)

This error occurs when a snap-in attempts to attach a toolbar to MMC by calling MMCControlBar.Attach but the toolbar does not have an image list in its MMCToolbar.ImageList property.


siErrToolbarHasNoImages (Error 9517)

This error occurs when a snap-in attempts to attach a toolbar to MMC by calling MMCControlBar.Attach but the toolbar's image list in its MMCToolbar.ImageList property does not contain any images.


siErrToolbarImageNotFound (Error 9518)

This error occurs when a snap-in attempts to attach a toolbar to MMC by calling MMCControlBar.Attach or add a button by calling MMCToolbar.Buttons.Add but the toolbar's image list in its MMCToolbar.ImageList property does not contain the image at the index or key specified by the button's MMCButton.Image property.


siErrSystemError (Error 9519)

The snap-in designer runtime encountered an unexpected operating system error. Contact Microsoft product support.


siErrTooManyMenuItems (Error 9520)

The snap-in passed an MMCMenu object to ContextMenu.AddMenu that contains more than 65,535 items in all of its submenus. The menu must be restructured to contain less items.


siErrInvalidPropertyPageName (Error 9525)

The snap-in passed a property page name to MMCPropertySheet.AddPage or MMCPropertySheet.InsertPage that is not a valid name of a property page in the snap-in's project. Common causes of this error:

Property page name is misspelled.

The property page was not associated with SnapInControl. Double click SnapInControl in the project window and select the PropertyPages property in the property browser. Click the ellipsis button (…) to display the property pages dialog and click the checkbox for the property page.


siErrInvalidVariant (Error 9526)

The snap-in has set a Variant property on an object such as Tag to a Variant containing an object set to Nothing. This could happen with the following code:

Dim v As Variant
Dim o As SomeObject
Set o = Nothing
Set v = 0
Set SomeScopeItem.Tag = v


siErrObjectNotPersistable (Error 9527)

A method parameter or a Tag property contains an object that does not support persistence. If the object is implemented by a Visual Basic class module then set its Persistable property to True and implement the ReadProperties and WriteProperties methods. This error can occur when passing an object in a call to MMCDataObject.SetData with the ObjectType parameter passed as siPersistedObject.


siErrObjectNotPublicCreatable (Error 9528)

A method parameter or a Tag property contains an object that is not public and creatable. If the object is implemented in a Visual Basic class module then set its Instancing property to a publicly creatable option. For other objects, check their registration database entries. This error can occur when passing an object in a call to MMCDataObject.SetData with the ObjectType parameter passed as siPersistedObject.


siErrUnknownListView (Error 9529)

Taskpad.ListView contains a name that cannot be identified with a list view defined at design time. This property must contain the name of a list view defined in the designer window at design time.


siErrUnknownListView (Error 9530)

siErrInvalidRawDataType (Error 9530)

The snap-in has called MMCDataObject.SetData and passed a Variant containing a data type that is not supported by the designer runtime. Supported data types are Byte, Byte array, Integer, Long, Single, Double, Currency, Date, Boolean, String, String array, and Object.


siErrFormatNotAvailable (Error 9531)

The snap-in has called MMCDataObject.GetData and passed a data format that is not present in the MMCDataObject.


siErrNotExtensible (Error 9532)

The snap-in has attempted to access ScopeItem.DynamicExtensions for a node defined at design time as non-extensible. This collection is only available for nodes defined at runtime and nodes defined at design time as extensible.


siErrSerialzationCorrupt (Error 9533)

A snap-in has been loaded into MMC but its dynamic link library (the snap-in's .dll file) is corrupted.


siErrCantRemoveStaticNode (Error 9534)

A snap-in has called ScopeItems.Remove for the static node or a snap-in has called ScopeItems.Clear. The static node cannot be removed programmatically as the console controls its lifetime. If the console is closed or the user removes the snap-in from the console the static node will be removed and the snap-in will receive the ScopeItems_Terminate event for the static node.


siErrCantChangeUnownedScopeNode (Error 9535)

Properties of a ScopeNode object not owned by the snap-in are read-only. The snap-in will receive this error if attempts to change ScopeNode.DisplayName on a ScopeNode object that represents a node owned by another snap-in.


siErrUnsupportedOnVirtualList (Error 9536)

A snap-in has attempted an operation that is not supported on a virtual list view such as calling MMCListItems.Add. Snap-ins do not explicitly add list items to a virtual list view. The snap-in sets the count by calling MMCListItems.Count in in the ResultViews_Activate event to tell MMC how many items are in the list view. For more information see "Using Virtual List Views."


siErrNoKeyOnVirtualItems (Error 9537)

A snap-in has attempted to reference a virtual list item by key. Virtual list items can only be referenced by index. For more information see "Using Virtual List Views."


siErrIndexOutOfRange (Error 9538)

A snap-in has attempted to reference an item in a collection using an index that is not within the range of items currently in the collection. Valid indexes are 1 to <collection name>.Count. For virtual list views the range is determined by a prior call to MMCListItems.SetItemCount.


siErrNotConnectedToMMC (Error 9539)

A method was called before the designer runtime has connected to MMC in order to allow access to MMC services. This can happen when attempting to use an MMC feature such as ConsoleMsgBox before the SnapIn_Load event or calling View.NewWindow before the Views_Load event.


siErrControlbarNotAvailable (Error 9542)

An attempt was made to alter a toolbar or menu button during an event in which access to MMC's controlbar is not available. Access to the controlbar is available only in Views_SetControlbar, Views_UpdateControlbar, ExtensionSnapIn_SetControlbar, and ExtensionSnapIn_UpdateControlbar.


siErrCollectionReadOnly (Error 9543)

An attempt was made to alter a read-only collection. Methods that alter the collection, such as Add, Remove, and Clear, may not be used. Read-only collections are used in MMCClipboard objects passed as event parameters to describe the current selection.


siErrInvalidColumnSetID (Error 9544)

The snap-in has set ScopePaneItem.ColumnSetID to vbNullString or to a zero length string. All column configuration operations require that this property be set to a valid string.


siErrMMCFeatureNotAvailable (Error 9545)

The snap-in has attempted to use a feature that is not available on the installed version of MMC. For example, features such as column persistence and column filtering cannot be used on MMC 1.1.


siErrIconRequired (Error 9547)

The snap-in has attempted to use a bitmap in a Picture property that must contain an icon. Bitmaps and other picture types cannot be used.


siErrCantDeleteIcon (Error 9548)

The snap-in has attempted to set SnapIn.Icon to Nothing. If your snap-in does not have its own icon then do not alter the value of this property and the designer runtime will use the MMC icon as a default.


siErrToolbarInconsistent (Error 9549)

The snap-in has attempted to use a toolbar that contains both buttons and menu buttons. A toolbar's buttons must all be drop-down style or they all must be something else. MMC does not allow mixing toolbar buttons and menu buttons within a toolbar.


siErrUnsupportedDataMedium (Error 9550)

The snap-in has called MMCDataObject.GetData for a data object from another snap-in implemented in C++ and that snap-in has returned data using an unsupported storage medium. The snap-in designer can import data using TYMED_HGLOBAL and TYMED_ISTREAM. For more information see "Importing Data from C++ Snap-ins" and "Developing Extension and Dual-Mode Snap-ins."


siErrDataTooLarge (Error 9551)

The snap-in has called MMCDataObject.GetData for a data object from another snap-in and the data is longer than 4GB. The snap-in designer does not support importing data greater than 4GB.


siErrMMCVersionNotAvailable (Error 9552)

A snap-in has attempted to access View.MMCMajorVersion or View.MMCMajorVersion prior to the Views_Load event. The snap-in designer runtime cannot detect the MMC version before this event is fired.


siErrScopeNodeNotConnectedToMMC (Error 9554)

The snap-in has attempted to access the properties of a ScopeNode object before it is not connected to MMC. This can happen with the static node before the ScopeItems_Expand event has been received for it.


siErrNoScopeItemsInVirtualList (Error 9555)

A snap-in has called MMCListView::SetScopeItemState for a virtual list view. MMC does not automatically add child scope items to a virtual list view. The snap-in can simulate their presence by adding list items that use the child scope items' icon and column data. For more information see "Using Virtual List Views."


siErrCantAlterPageCount (Error 9556)

Win32 does not permit adding or removing pages from a property sheet during this event or method. In general, pages should be added or removed during IMMCPropertyPage_Initialize or in response to UI interaction with controls on the property page.


Column Header Apply Failed

The apply operation for the column header properties failed. Common causes are an empty or duplicate Key. Check the keys of all the column headers to make sure there are no duplicates or empties. Correct any problems and retry the apply.


Identifier in Use

The name specified is already being used as a property of your snap-in for a toolbar, menu or image list. Choose a unique name and retry the operation.


Invalid GUID

The string entered for the node type is not a valid GUID. Enter a GUID in registry format e.g. {D6CC9C30-318F-11D3-AA43-00104B880587}.


Invalid Identifier

The name specified is not a valid Visual Basic identifier. Please choose a different name. A valid identifier:

Must begin with a letter.

Can't contain an embedded period or embedded type-declaration character.

Must not exceed 255 characters.

Must be unique within the snap-in.


Invalid Picture

The picture file specified does not contain a bitmap. Retry the operation and select a file that contains a bitmap. If you are not sure what type of picture the file contains, check its file type in the Windows Explorer.


Node has Chldren

Node has Children

You have attempted to delete a node that has child nodes, result views, or both. Delete the child nodes and/or result views before deleting the node.


Result View in Use

You have attempted to delete a result view that is being used by your snap-in. Remove the result view from all nodes that are using and then delete the result view.