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.

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.

Dim vsEnvironment As DTE = DirectCast(GetService(GetType(SDTE)), DTE)

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.

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.

Dim propertiesList As Properties = vsEnvironment.get_Properties("TextEditor", "Basic")
If propertiesList Is Nothing Then 
    ' The specified properties collection is not available.  
    Exit Sub 
End If

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.

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.

Dim tabSize As [Property] = propertiesList.Item("TabSize")
        Dim oldSize As Short = CShort(tabSize.Value)

        Dim message As String 
        If oldSize <> 4 Then
            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)
        End If

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 Programmatically

Concepts

Creating Options Pages By Using Interop Assemblies

Creating Options Pages By Using Managed Package Framework Classes

Creating Options Pages By Using Automation

Controlling Options Settings

Registering Custom Options Pages

Other Resources

User Settings and Options