Using Options Pages

The Visual Studio automation model provides the DTE object to enable VSPackages to access the Options dialog box on the Tools menu.

Typically, pages in the Options dialog box can be accessed by using the automation model, whether the pages are provided by the Visual Studio integrated development environment (IDE) or by a VSPackage. However, there are some exceptions, as follows:

• The settings of the Dynamic Help page cannot be accessed programmatically. The Dynamic Help feature can be controlled by using the automation model, but control must be accomplished directly in code. For more information, see How to: Control the Dynamic Help Window.

• Control of the Fonts and Color page settings is provided through its own API, not through the automation model. For more information, see Fonts.

• Language-specific properties cannot be obtained through the automation model.

Options pages that do not support the Visual Studio automation model may not return an automation Properties collection when queried. If the collection is returned, not all features are present. For information about how to manage these features, see DTE Properties Collections.

Managing Options Pages

To manage Options pages, a VSPackage must get a DTE object from the automation model.

Note

When a VSPackage uses the automation model to query and change settings on installed Options pages, it does not extend the IDE functionality. Therefore, the package does not have to implement an automation object.

To obtain a DTE object through the automation model, call the QueryService method and provide a service ID argument of SID_SDTE and an interface argument of IID__DTE, as follows.

pServiceProvider->QueryService(SID_SDTE, IID__DTE, (LPVOID*)pDTE);

To obtain a DTE object by using the Managed Package Framework (MPF), call the GetService method and provide a serviceType parameter of type SDTE.

DTE vsEnvironment = (DTE)GetService(typeof(SDTE));

An Options page is specified by two identifiers. The first identifier is a string that indicates the folder that contains the Options page. The second identifier is a string that indicates the specific item in that folder. These are referred to as an Options page category and subcategory, or its topic and subtopic.

For example, the text editor settings for handling Basic code are on the navigation pane as the Basic member of the Text Editor folder. The identifier for the category is TextEditor and its subcategory is Basic, and the Options page itself is referred to as the TextEditor.Basic page.

Note

For localization and other reasons, the names displayed on Options pages may differ from the strings used as category and subcategory identifiers. You may have to use automation to query the IDE to obtain the correct identifiers, if they are not documented elsewhere. The registry location is HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<VS Version>\AutomationProperties, where <VS Version> is the version number of the release of Visual Studio. For more information, see Registering Custom Options Pages.

You can obtain the properties for the TextEditor.Basic page through the automation model by using the following example.

CComPtr<_DTE> srpDTE;
CComPtr<Properties> srpDTEPropertiesList;
hr = srpDTE->get_Properties("TextEditor", "Basic", &srpDTEPropertiesList);

To obtain the properties by using the MPF, use the Properties method.

Properties propertiesList = vsEnvironment.get_Properties("TextEditor", "Basic");
if (null == propertiesList)
{
    // The specified properties collection is not available. 
    return;
}

The Item method returns individual settings from the Properties collection as a Property object.

As with categories and subcategories, each setting has an identifier that is a unique string. For example, the Tab Size setting on the TextEditor.Basic page is identified by the string, TabSize.

Note

For localization and other reasons, the names displayed on Options pages may differ from the strings used as setting identifiers. You may have to use automation to query the IDE to obtain the correct identifiers, if they are not documented elsewhere.

You can use the Value of the Property object that is returned by the Item method of the Properties collection to query and change the settings state.

For example, to set the Tab Size setting on the TextEditor.Basic page through the automation model, use the Properties object returned in the following example.

CComPtr<Property> srpProperty;
hr = srpDTEPropertiesList->Item("TabSize", &srpProperty);
hr= srpProperty.set_Value(4);

The following example demonstrates how to update the Tab Size setting by using the MPF.

Property tabSize = propertiesList.Item("TabSize");
short oldSize = (short)tabSize.Value;

string message;
if (oldSize != 4)
{
    tabSize.Value = 4;
    message = string.Format(CultureInfo.CurrentUICulture,
        "For Basic, the Text Editor had a tab size of {0}" +
        " and now has a tab size of {1}.", oldSize, tabSize.Value);
}
else
{
    message = string.Format(CultureInfo.CurrentUICulture,
        "For Basic, the Text Editor has a tab size of {0}.", tabSize.Value);
}

MessageBox.Show(message, "Text Editor, Basic, Tab Size:",
    MessageBoxButtons.OK, MessageBoxIcon.Information,
    MessageBoxDefaultButton.Button1, 0);

For more information, see Controlling Options Settings.

Persisting Options Page Settings

The IDE implements state persistence of Options pages that fully support the Visual Studio automation model.

Settings on pages that are included in the IDE are automatically saved (or retrieved) when a user clicks the Import/Export Settings command on the Tools menu.

You can enable your custom Options page to use this automatic persistence support by adding the ProfileSave flag to the custom Options page registry entry under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<VS Version>\AutomationProperties, where <VS Version> is the version number of the release of Visual Studio. For more information, see Registering Custom Options Pages.

See Also

Tasks

How to: Open an Options Page

Concepts

Creating Options Pages By Using Interop Assemblies

Controlling Options Settings

Registering Custom Options Pages

Reference

DTE

Other Resources

Creating and Controlling Environment Windows

Change History

Date	History	Reason
July 2008	Added Managed Package Framework examples.	Content bug fix.