Controlling Options Settings

You can activate or deactivate the settings of the various pages in the Options dialog box on the Tools menu (hereafter called "Options pages"). Simply use the Properties and Value properties and Item method of the DTE object in the Visual Studio automation model.

Note

Some items on some Options pages are not programmatically accessible. Most items, such as the comment Token list in the Task List Options page, can be viewed or changed programmatically. But some Options pages, such as the Dynamic Help page, which is in the Help node of the Environment page, cannot. In addition, while some Options pages have programmable settings, some items on the page are not necessarily accessible. If you find you cannot affect a setting, you may need to use the Visual Studio Industry Partner (VSIP) program to do so. For more information, see the "Adding Settings to Existing Options Pages" section later in this topic. For a complete list of the programmatically accessible options and their exact names, see "Property Item Names" in Determining the Names of Property Items in Options Pages.

Displaying Options Settings

Use the Properties collection and Property object to access the settings for an existing Options page. The following VSMacro example displays all names and current values of all items in the Documents Options page.

' Macro code.
Sub PropertiesExample()
    ' Create and initialize a variable to represent the Documents 
    ' Options page.
    Dim envGenTab As EnvDTE.Properties = _
    DTE.Properties("Environment", "Documents")
    Dim prop As EnvDTE.Property
    Dim msg As String

    ' Loop through each item in the Documents Options box.
    For Each prop In envGenTab
        msg += ("PROP NAME: " & prop.Name & "   VALUE: " & _
        prop.Value) & vbCr
    Next
    MsgBox(msg)
End Sub

The following VSMacro example displays all available properties in the Options page for the Task List under the Environment node. It also lists all available values for the comment Token list.

' Macro code.
Sub DisplayProperties()
    ' Variables to represent the properties collection
    ' and each property in the Options dialog box.
    Dim prop As EnvDTE.Property
    Dim props As EnvDTE.Properties
    Dim propVals As Object()
    Dim propVal, msg As String

    ' Represents the Task List Node under the 
    ' Enviroment node.
    props = DTE.Properties("Environment", "TaskList")
    ' Represents the items in the comment Token list
    ' and their priorities (1-3/low-high).
    prop = props.Item("CommentTokens")
    propVals = prop.Value

    Try
        ' List each property name for the Options page
        ' and all of its possible values.
        For Each prop In props
            msg += "PROP NAME: " & prop.Name & vbCr
            For Each propVal In propVals
                msg += "  Value: " & propVal & vbCr
            Next
        Next
        MsgBox(msg)
    Catch ex As System.Exception
        MsgBox("ERROR: " & ex.Message)
    End Try
End Sub

This example lists all programmable settings for the Options page under Text Editor | C# | Formatting.

' Macro code.
Sub PropertiesExample()
    ' Create and initialize a variable to represent the C# 
    ' Formatting text editor options page.
    Dim txtEdCSFormat As EnvDTE.Properties = _
    DTE.Properties("TextEditor", "CSharp - Formatting")
    Dim prop As EnvDTE.Property
    Dim msg As String

    ' Loop through each item in the C# Formatting Options page.
    For Each prop In txtEdCSFormat
        msg += ("PROP NAME: " & prop.Name & "   VALUE: " & _
        prop.Value) & vbCr
    Next
    MsgBox(msg)
End Sub

Changing Options Settings

While you can change the value of controls on an existing Options page, you cannot add, remove, or modify any of its controls or settings. To specify your own settings, you must create a custom Options page. For more information, see How to: Create Custom Tools Options Pages.

Changing the value of an item in an Options page is very similar to displaying its value. The following macro examples demonstrate how to do this.

The first example (ToolOpt1) toggles the boolean value of ReuseSavedActiveDocWindow, which equates to the "Reuse current document window, if saved" option on the Documents page of the Environment node.

' Macro code.
Sub ToolOpt1()
    Dim props As EnvDTE.Properties = DTE.Properties("Environment", _
    "Documents")
    Dim prop As EnvDTE.Property

    prop = props.Item("ReuseSavedActiveDocWindow")
    ' If value is TRUE, change it to FALSE, or vice-versa.
    MsgBox("PROP NAME: " & prop.Name & "   VALUE: " & prop.Value)
    prop.Value = Not (prop.Value)
    MsgBox("PROP NAME: " & prop.Name & "   VALUE: " & prop.Value)
    ' Change it to the original value.
    prop.Value = Not (prop.Value)
End Sub

The following VSMacro example changes and then resets the Tab size value in the Tabs section of the Basic page of the Text Editor node.

' Macro code.
Sub ToolOpt2()
    Dim props As EnvDTE.Properties = DTE.Properties("TextEditor", _
    "Basic")
    Dim prop As EnvDTE.Property
    Dim tmp As String

    prop = props.Item("TabSize")
    ' Set a new value for Tab Size.
    MsgBox("PROP NAME: " & prop.Name & "   VALUE: " & prop.Value)
    tmp = prop.Value
    prop.Value = 10
    MsgBox("PROP NAME: " & prop.Name & "   VALUE: " & prop.Value)
    ' Change it back to the original value.
    prop.Value = tmp
    MsgBox("PROP NAME: " & prop.Name & "   VALUE: " & prop.Value)
End Sub

This VSMacro example changes a setting in the Fonts and Colors page of the Environment node.

' Macro code.
Sub ToolOpt3()
    ' Changes the background color of text in the Fonts and Colors
    ' page of the Options dialog box on the Tools menu.
    Dim props As EnvDTE.Properties
    Dim prop As EnvDTE.Property
    Dim fontColorItems As EnvDTE.FontsAndColorsItems

    props = DTE.Properties("FontsAndColors", "TextEditor")
    prop = props.Item("FontsAndColorsItems")
    fontColorItems = prop.Object

    Try
        MsgBox("NAME: " & prop.Name & vbCr & "BACKGROUND VALUE: " & _
        CStr(fontColorItems.Item("Plain Text").Background.ToString))
        ' Turn the text background from its current color to red.
        fontColorItems.Item("Plain Text").Background = 255
        MsgBox("NAME: " & prop.Name & vbCr & "BACKGROUND VALUE: " & _
        Hex(fontColorItems.Item("Plain Text").Background.ToString))
    Catch ex As System.Exception
        MsgBox("ERROR: " & ex.Message)
    End Try
End Sub

This VSMacro example turns on line numbering for several languages in the Text Editor node of the Options dialog box.

' Macro code.
Sub TurnOnLineNumbers()
   DTE.Properties("TextEditor", "Basic").Item("ShowLineNumbers") _
   .Value = True
   DTE.Properties("TextEditor", "PlainText").Item("ShowLineNumbers") _
   .Value = True
   DTE.Properties("TextEditor", "CSharp").Item("ShowLineNumbers") _
   .Value = True
   DTE.Properties("TextEditor", "HTML/XML").Item("ShowLineNumbers") _
   .Value = True
   DTE.Properties("TextEditor", "C/C++").Item("ShowLineNumbers") _
   .Value = True
   DTE.Properties("TextEditor", "Visual JSharp") _
   .Item("ShowLineNumbers").Value = True
End Sub

Adding Settings to Existing Options Pages

You may, at some point, want to alter or add your own settings to existing Options pages, such as adding your own font settings into the Fonts and Colors page. This cannot be done by using the Visual Studio automation model. You must use the Visual Studio Industry Partner (VSIP) program. For more information, see the Visual Studio Industry Partner Web site.

See Also

Tasks

How to: Create Custom Tools Options Pages

How to: Change Window Characteristics

How to: Create an Add-In

Walkthrough: Creating a Wizard

Concepts

Automation Object Model Chart

Other Resources

Creating and Controlling Environment Windows

Creating Add-ins and Wizards

Automation and Extensibility Reference