Support for Options Pages
Selecting Options on the Tools menu opens the Options dialog box. The options in this dialog box are collectively referred to as Tools/Options pages. The tree control in the navigation pane includes option categories, and each category has option 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 Tools/Options Pages
The Package class provides support for creating option pages and option categories. The DialogPage class implements an option 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 Tools/Options page with its own user interface (UI). For more information, see Walkthrough: Creating an Options Page and OptionsPage.
The DialogPage class implements IProfileManager, which provides persistence for both options pages and user settings. The default implementations of the LoadSettingsFromStorage and SaveSettingsToStorage methods persist property changes into a user's section of the registry if the property can be converted to and from a string.
Tools/Options Page Registry Path
By default, the registry path of the properties managed by an option page is determined by combining UserRegistryRoot, the word DialogPage, and the type name of the option page class. For example, an option page class might be defined as follows:
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 option page itself is determined by combining ApplicationRegistryRoot, the word, ToolsOptionsPages, and the option page category and name. For example, if the Custom option page has the category, My Option Pages, and the ApplicationRegistryRoot is HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0Exp, then the option 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 option pages into categories in the navigation tree of the Options dialog box. The ProvideOptionPageAttribute attribute associates an option 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 option pages, OptionsPageGeneral and OptionsPageCustom. In the Options dialog box, both option 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 option page. The layout, labeling, and description of options in a generic option 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:
<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 { return _optionInt; }
set { _optionInt = value; }
}
The OptionInteger option appears on the option 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 Option Pages from Another VSPackage
A VSPackage that hosts and manages an options page can be programmatically accessed from another VSPackage using the automation model. For example, in the following code a VSPackage is registered as hosting an option page:
[ProvideOptionPage(typeof(MyOptionPage), "My Category", "My Grid Page", 0, 0, true)]
[Guid("6bb6942e-014c-489e-a612-a935680f703d")]
public sealed class MyToolsOptions : 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 option 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 option page category and name. For example, if the option 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.
See Also
Tasks
Walkthrough: Creating an Options Page
Concepts
Support for Settings Categories