Support for Options Pages

Article
01/30/2013

Clicking Options on the Tools menu opens the Options dialog box. The options in this dialog box are collectively referred to as options pages. The tree control in the navigation pane includes options categories, and every category has options pages. When you select a page, its options appear in the right pane. These pages let you change the values of the options that determine the state of a VSPackage.

Support for Options Pages

The Package class provides support for creating options pages and options categories. The DialogPage class implements an options page.

The default implementation of DialogPage offers its public properties to a user in a generic grid of properties. You can customize this behavior by overriding various methods on the page to create a custom options page that has its own user interface (UI). For more information, see Walkthrough: Creating an Options Page.

The DialogPage class implements IProfileManager, which provides persistence for options pages and also for user settings. The default implementations of the LoadSettingsFromStorage and SaveSettingsToStorage methods persist property changes into a user section of the registry if the property can be converted to and from a string.

Options Page Registry Path

By default, the registry path of the properties managed by an options page is determined by combining UserRegistryRoot, the word DialogPage, and the type name of the options page class. For example, an options page class might be defined as follows.

Namespace Company.OptionsPage
    Public Class OptionsPageGeneral
        Inherits DialogPage
    End Class
End Namespace

namespace Company.OptionsPage
{
    public class OptionsPageGeneral : DialogPage
    {
    }
}

If the UserRegistryRoot is HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\8.0Exp, then the property name and value pairs are subkeys of HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\8.0Exp\DialogPage\Company.OptionsPage.OptionsPageGeneral.

The registry path of the options page itself is determined by combining ApplicationRegistryRoot, the word, ToolsOptionsPages, and the options page category and name. For example, if the Custom options page has the category, My Option Pages, and the ApplicationRegistryRoot is HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0Exp, then the options page has the registry key, HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0Exp\ToolsOptionsPages\My Option Pages\Custom.

Tools/Options Page Attributes and Layout

The ProvideOptionPageAttribute attribute determines the grouping of custom options pages into categories in the navigation tree of the Options dialog box. The ProvideOptionPageAttribute attribute associates an options page with the VSPackage that provides the interface. Consider the following code fragment:

<ProvideOptionPage(GetType(OptionsPageGeneral), "My Option Pages", "General", 101, 106, True),
 ProvideOptionPage(GetType(OptionsPageCustom), "My Option Pages", "Custom", 101, 107, True),
 Guid("B0002DC2-56EE-4931-93F7-70D6E9863940")>
Public Class MyPackage
    Inherits Package

[ProvideOptionPage(typeof(OptionsPageGeneral),"My Option Pages", "General", 101, 106, true)]
[ProvideOptionPage(typeof(OptionsPageCustom), "My Option Pages", "Custom", 101, 107, true)]
[Guid("B0002DC2-56EE-4931-93F7-70D6E9863940")]
public class MyPackage : Package

This declares that MyPackage provides two options pages, OptionsPageGeneral and OptionsPageCustom. In the Options dialog box, both options pages appear in the My Option Pages category as General and Custom, respectively.

Option Attributes and Layout

The user interface (UI) that the page provides determines the appearance of options in a custom options page. The layout, labeling, and description of options in a generic options page are determined by the following attributes:

CategoryAttribute determines the category of the option.
DisplayNameAttribute determines the display name of the option.
DescriptionAttribute determines the description of the option.

Note

Equivalent attributes, SRCategory, LocDisplayName, and SRDescription, use string resources for localization and are defined in the managed project sample.

Consider the following code fragment:

Private _optionInt As Integer

<Category("My Options"),
DisplayName("Integer Option"),
Description("My integer option")>
Public Property OptionInteger() As Integer
    Get
        Return _optionInt
    End Get
    Set(ByVal value As Integer)
        _optionInt = value
    End Set
End Property

[Category("My Options")]
[DisplayName("Integer Option")]
[Description("My integer option")]
public int OptionInteger { get; set; }

The OptionInteger option appears on the options page as Integer Option in the My Options category. If the option is selected, the description, My integer option, appears in the description box.

Accessing Options Pages from Another VSPackage

A VSPackage that hosts and manages an options page can be programmatically accessed from another VSPackage by using the automation model. For example, in the following code a VSPackage is registered as hosting an option page.

<ProvideOptionPage(GetType(MyOptionPage), "My Category", "My Grid Page", 0, 0, True)>
<Guid("6bb6942e-014c-489e-a612-a935680f703d")>
Public NotInheritable Class MyToolsOptions
    Inherits Package

[ProvideOptionPage(typeof(MyOptionPage), "My Category", "My Grid Page", 0, 0, true)]
[Guid("6bb6942e-014c-489e-a612-a935680f703d")]
public sealed class MyToolsOptions : Package

The following code fragment gets the value of OptionInteger from MyOptionPage:

Dim dte As DTE = CType(GetService(GetType(DTE)), DTE)
Dim props As EnvDTE.Properties = dte.get_Properties("My Category", "My Grid Page")
Dim n As Integer = CInt(Fix(props.Item("OptionInteger").Value))

DTE dte = (DTE)GetService(typeof(DTE));
EnvDTE.Properties props = dte.get_Properties("My Category", "My Grid Page");
int n = (int)props.Item("OptionInteger").Value;

When the ProvideOptionPageAttribute attribute registers an options page, the page is registered under the AutomationProperties key if the SupportsAutomation argument of the attribute is true. Automation examines this registry entry to find the associated VSPackage, and automation then accesses the property through the hosted options page, in this case, My Grid Page.

The registry path of the automation property is determined by combining ApplicationRegistryRoot, the word, AutomationProperties, and the options page category and name. For example, if the options page has the My Category category, the My Grid Page name, and the ApplicationRegistryRoot, HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0Exp, then the automation property has the registry key, HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0Exp\AutomationProperties\My Category\My Grid Page.

Note

The canonical name, My Category.My Grid Page, is the value of the Name subkey of this key.

Support for Options Pages