Using Tools Options Pages
The Visual Studio automation model uses the DTE object to provide VSPackages access to most Options dialog boxes on the Tools menu (Tools Options pages).
Most Tools Options pages, whether provided by the Visual Studio integrated development environment (IDE) or by a VSPackage, are accessible through the automation model. Here are some noteworthy exceptions:
The settings of the Dynamic Help property page cannot be accessed programmatically. Direct control of the Dynamic Help feature can be obtained through the automation model, but this is not reflected on the Dynamic Help property page. For more information, see How to: Control the Dynamic Help Window.
Control of the Fonts and Color property page setting is provided through its own API rather than through the automation model. For more information, see Fonts.
Language-specific properties cannot be obtained through the automation model.
Tools 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. To understand how to manage these features, consult the documentation for DTE Properties Collections.
Managing Options Pages through Automation
Because a VSPackage accesses the IDE's configuration through the automation model, it must get a DTE object to manage the Tools Options pages.
Nota
Although a VSPackage uses the automation model to query and change settings on existing ToolsOptions pages, it is not extending the IDE functionality and, therefore, does not need to implement an automation object itself.
To obtain a DTE object, call the QueryService method with a service ID argument of SID_SDTE and the interface argument of IID__DTE:
pServiceProvider->QueryService(SID_SDTE, IID__DTE, (LPVOID*)pDTE);
A Tools Options page is specified by two identifiers. The first identifier is a string that indicates the folder containing the Tools Options page on the Tools menu. The second identifier is a string that indicates the specific item in that folder. These are referred to as a Tools Options pages category and subcategory or its topic and subtopic.
For instance, the text editor's settings for handling Basic code are under the Options menu as the Basic member of Text Editor folder. The identifier for the category is TextEditor, its subcategory is Basic, and the Tools Options page itself is referred to as the TextEditor.Basic page.
Nota
Because of localization and other issues, the names displayed on the Options section of the Tools menu may not exactly correspond with the strings used as category and subcategory identifiers. It may be necessary to use automation to query the IDE to obtain the correct identifiers, if 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 example, 8.0). For more information, see Registering Custom Tools Options Pages.
You can obtain the properties for the TextEditor.Basic page with the following example:
CComPtr<_DTE> srpDTE;
CComPtr<Properties> srpDTEPropertiesList;
hr = srpDTE->get_Properties("TextEditor", "Basic", &srpDTEPropertiesList);
The Item(Object) method returns individual settings from the Properties collection as a Property object.
As with categories and subcategories, each setting has as an identifier, which is a unique string. For example, the Tab Size setting on the TextEditor.Basic page is identified with the string, TabSize.
Nota
Similarly, names displayed on an Options page may not exactly correspond with a setting's identifier because of localization-related issues. It may be necessary to use automation to query the IDE to obtain the correct identifiers, if not documented elsewhere.
The Value() of the Property object that is returned by the Item(Object) method of the Properties collection can query and change the settings state.
For example, to set the Tab Size entry on the TextEditor.Basic page, use the Properties object returned in the following example:
CComPtr<Property> srpProperty;
hr = srpDTEPropertiesList->Item("TabSize", &srpProperty);
hr= srpProperty.set_Value(4);
For more information, see Controlling Options Settings.
Persisting Tools Options Page Settings
The IDE itself implements state persistence of a Tools Options page that fully supports the Visual Studio automation model.
Settings that the environment's Tools Options pages control, those provided by default through the IDE, are automatically saved (or retrieved) when a user clicks the Import/Export Settings command on the Tools menu.
Custom Tools Options pages have the option of taking advantage of this automatic persistence support.
VSPackages can persist the settings controlled by their custom Tools Options pages by adding the ProfileSave flag to the Tools Options page's 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 example, 8.0). For more information, see Registering Custom Tools Options Pages.
See Also
Concepts
Creating and Controlling Environment Windows
Creating Tools Options Pages with Interop Assemblies
Registering Custom Tools Options Pages
Reference
DTE