Walkthrough: Exposing Properties to the Properties Window

Article
02/28/2011

This walkthrough exposes the public properties of an object to the Properties window. The changes you make to these properties are reflected in the Properties window.

Prerequisites

To complete this walkthrough, you must install the Visual Studio 2010 SDK.

Notes

For more information about the Visual Studio SDK, see Visual Studio Integration SDK. To find out how to download the Visual Studio SDK, see Visual Studio Extensibility Developer Center on the MSDN Web site.

Locations for the Visual Studio Package Project Template

The Visual Studio Package project template can be found in three different locations in the New Project dialog:

Under Visual Basic Extensibility. The default language of the project is Visual Basic.
Under C# Extensibility. The default language of the project is C#.
Under Other Project Types Extensibility. The default language of the project is C++.

Exposing Properties to the Properties Window

In this section, you create a basic tool window package and display the public properties of the associated window pane object in the Properties window.

To expose properties to the Properties window

Create a Visual Studio Package project named MyObjectProps.

For more information about how to create a managed VSPackage, see Walkthrough: Creating a Menu Command By Using the Visual Studio Package Template.
On the Select a Programming Language page, select Visual C#. You can use Visual Basic to create a package, but this walkthrough uses Visual C#.
On the Select VSPackage Options page, select Tool Window.
On the Tool Window Options page, change the Window Name to My Object Properties, and then click Finish.

The template creates the managed project, MyObjectProps.
Open the file, MyToolWindow.cs, and add the following fields to the MyToolWindow class.
```
private ITrackSelection trackSel;
private SelectionContainer selContainer;
```

Add the following code to the MyToolWindow class.

    Private ReadOnly Property TrackSelection() As ITrackSelection
        Get
            If trackSel Is Nothing Then
                trackSel = TryCast(GetService(GetType(STrackSelection)), ITrackSelection)
            End If
            Return trackSel
        End Get
    End Property

    Public Sub UpdateSelection()
        Dim track As ITrackSelection = TrackSelection
        If track IsNot Nothing Then
            track.OnSelectChange(DirectCast(selContainer, ISelectionContainer))
        End If
    End Sub

    Public Sub SelectList(ByVal list As ArrayList)
        selContainer = New SelectionContainer(True, False)
        selContainer.SelectableObjects = list
        selContainer.SelectedObjects = list
        UpdateSelection()
    End Sub

    Public Overloads Overrides Sub OnToolWindowCreated()
        Dim listObjects As New ArrayList()
        listObjects.Add(Me)
        SelectList(listObjects)
    End Sub
    Private checked As Boolean = False
    <Category("My Properties")> _
    <Description("MyControl properties")> _
    Public Property IsChecked() As Boolean
        Get
            Return IsChecked
        End Get
        Set(ByVal value As Boolean)
            checked = value
            control.checkBox1.Checked = value
        End Set
    End Property
    Private sObject As Simple = Nothing
    Public ReadOnly Property SimpleObject() As Simple
        Get
            If sObject Is Nothing Then
                SimpleObject = New Simple()
            End If
            Return sObject
        End Get
    End Property
    Public Sub SelectSimpleList()
        Dim listObjects As New ArrayList()
        listObjects.Add(SimpleObject)
        SelectList(listObjects)
    End Sub

    Public Sub SelectThisList()
        Dim listObjects As New ArrayList()
        listObjects.Add(Me)
        SelectList(listObjects)
    End Sub

private ITrackSelection TrackSelection
{
    get
    {
        if (trackSel == null)
            trackSel =
               GetService(typeof(STrackSelection)) as ITrackSelection;
        return trackSel;
    }
}

public void UpdateSelection()
{
    ITrackSelection track = TrackSelection;
    if (track != null)
        track.OnSelectChange((ISelectionContainer)selContainer);
}

public void SelectList(ArrayList list)
{
    selContainer = new SelectionContainer(true, false);
    selContainer.SelectableObjects = list;
    selContainer.SelectedObjects = list;
    UpdateSelection();
}

public override void OnToolWindowCreated()
{
    ArrayList listObjects = new ArrayList();
    listObjects.Add(this);
    SelectList(listObjects);
}

The TrackSelection property uses GetService to obtain an STrackSelection service, which provides an ITrackSelection interface. The OnToolWindowCreated event handler and SelectList method together create a list of selected objects that contains only the tool window pane object itself. The UpdateSelection method tells the Properties window to display the public properties of the tool window pane.

Build and start the project in debug mode by pressing F5. This starts Visual Studio Exp.

Notes

Two versions of Visual Studio are open now.
If the Properties window is not visible, open it by pressing F4.
In Visual Studio Exp, on the View menu, point to Other Windows, and then click My Object Properties.

The window opens and the public properties of the window pane appear in the Properties window.
Click in Solution Explorer. The properties in the Properties window disappear. Click the My Object Properties window. The properties reappear.
Change the Caption property in the Properties window to Something Else.

The My Object Properties window caption changes accordingly.

Exposing Tool Window Properties

In this section, you add a tool window and expose its properties. The changes you make to properties are reflected in the Properties window.

To expose tool window properties

Close Visual Studio Exp.

Open MyToolWindow.cs, and add the public boolean property IsChecked to the MyToolWindow class.

Private checked As Boolean = False
<Category("My Properties")> _
<Description("MyControl properties")> _
Public Property IsChecked() As Boolean
    Get
        Return IsChecked
    End Get
    Set(ByVal value As Boolean)
        checked = value
        control.checkBox1.Checked = value
    End Set
End Property

[Category("My Properties")]
[Description("MyControl properties")]
public bool IsChecked
{
    get {
        if (base.Content == null)  return false;
        return (bool)((MyControl) base.Content).checkBox1.IsChecked; 
    }
    set {
        ((MyControl) base.Content).checkBox1.IsChecked = value;
    }
}

This property reads and writes its state directly from the WPF checkbox you create in a later step.

In the MyToolWindow constructor, add a this keyword to the MyControl constructor:
```
control = New MyControl(Me)
```
```
base.Content = new MyControl(this);
```

Open the file, MyControl.xaml.cs, and replace the constructor by using the following code.

Private pane As MyToolWindow
Public Sub New(ByVal pane As MyToolWindow)
    InitializeComponent()
    Me.pane = pane
    checkBox1.Checked = pane.IsChecked
End Sub

private MyToolWindow pane;
public MyControl(MyToolWindow pane)
{
    InitializeComponent();
    this.pane = pane;
    checkBox1.IsChecked = false;
}

This gives MyControl access to the MyToolWindow pane.

Change to Design view.
Delete the button control. Add a check box from the Toolbox to the upper, left corner.
Double-click the check box.

This creates the checkBox1_Checked event handler and opens it in the code editor.
In the Properties window, double-click the checkBox1 Unchecked event handler.

This creates the checkBox1_Unchecked event handler and opens it in the code editor.

Replace the check box event handlers by using the following code.

Private Sub checkBox1_CheckedChanged(ByVal sender As Object, ByVal e As System.EventArgs) Handles checkBox1.CheckedChanged
    pane.IsChecked = checkBox1.Checked
    pane.UpdateSelection()
    If pane.IsChecked Then
        pane.SelectSimpleList()
    Else
        pane.SelectThisList()
    End If
End Sub

private void checkBox1_Checked(object sender, RoutedEventArgs e)
{
    pane.IsChecked = true;
    pane.UpdateSelection();
}
private void checkBox1_Unchecked(object sender, RoutedEventArgs e)
{
    pane.IsChecked = false;
    pane.UpdateSelection();
}

Build and start the project in debug mode by pressing F5. This starts Visual Studio Exp.
In Visual Studio Exp, on the View menu, point to Other Windows, and then click My Object Properties.

The public properties of the window pane appear in the Properties window. The IsChecked property appears under the category, My Properties.
Click the IsChecked property.

The description MyControl Properties appears at the bottom of the Properties window.
Select the check box in the My Object Properties window. IsChecked changes to True. Clear the check box. IsChecked changes to False. Change the value of IsChecked in the Properties window. The check box in the My Object Properties window changes to match the new value.

Notes

If you must dispose of a property or object displayed in the Properties window, call OnSelectChange with a null selection container first. After disposing the property or object, you can change to a selection container that has updated SelectableObjects and SelectedObjects lists.

Changing Selection Lists

In this section, you add a selection list for a basic property class and use the tool window interface to choose which selection list to display.

To change selection lists

Close Visual Studio Exp.

Open MyToolWindow.cs or MyToolWindow.vb, and add the public class, Simple, to the beginning of the file, just after the namespace statement and opening curlique bracket.

Public Class Simple
    Private m_someText As String = ""

    <Category("My Properties")> _
    <Description("Simple Properties")> _
    <DisplayName("MyText")> _
    Public Property SomeText() As String
        Get
            Return m_someText
        End Get
        Set(ByVal value As String)
            m_someText = value
        End Set
    End Property

    <Category("My Properties")> _
    <Description("Read-only property")> _
    Public ReadOnly Property [ReadOnly]() As String
        Get
            Return "Hello"
        End Get
    End Property
End Class

public class Simple
{
    private string someText = "";

    [Category("My Properties")]
    [Description("Simple Properties")]
    [DisplayName("MyText")]
    public string SomeText
    {
        get { return someText; }
        set { someText = value; }
    }

    [Category("My Properties")]
    [Description("Read-only property")]
    public string ReadOnly
    {
        get { return "Hello"; }
    }
}

An object of type Simple has the public string properties, SomeText, and ReadOnly.

Add this code to the end of the MyToolWindow class, just after the IsChecked property.

Private sObject As Simple = Nothing
Public ReadOnly Property SimpleObject() As Simple
    Get
        If sObject Is Nothing Then
            SimpleObject = New Simple()
        End If
        Return sObject
    End Get
End Property
Public Sub SelectSimpleList()
    Dim listObjects As New ArrayList()
    listObjects.Add(SimpleObject)
    SelectList(listObjects)
End Sub

Public Sub SelectThisList()
    Dim listObjects As New ArrayList()
    listObjects.Add(Me)
    SelectList(listObjects)
End Sub

public void SelectSimpleList()
{
    ArrayList listObjects = new ArrayList();
    listObjects.Add(SimpleObject);
    SelectList(listObjects);
}

public void SelectThisList()
{
    ArrayList listObjects = new ArrayList();
    listObjects.Add(this);
    SelectList(listObjects);
}

This creates the singleton property, SimpleObject, and two methods to switch the Properties window selection between the window pane and the Simple object.

Open MyControl.cs or MyControl.vb in Code view. Replace the check box handlers with these lines of code:

If pane.IsChecked Then
    pane.SelectSimpleList()
Else
    pane.SelectThisList()
End If

private void checkBox1_Checked(object sender, RoutedEventArgs e)
{
    pane.IsChecked = true;
    pane.SelectSimpleList();
    pane.UpdateSelection();
}
private void checkBox1_Unchecked(object sender, RoutedEventArgs e)
{
    pane.IsChecked = false;
    pane.SelectThisList();
    pane.UpdateSelection();
}

Build and start the project in debug mode by pressing F5.

This starts Visual Studio Exp.
In Visual Studio Exp, on the View menu, point to Other Windows, and then click My Object Properties.

The window opens and the public properties of the window pane appear in the Properties window.
Select the check box in the My Object Properties window. The Properties window displays the Simple object properties, SomeText and ReadOnly. Clear the check box. The public properties of the window pane appear in the Properties window.

Notes

The display name of Some Text is My Text.

Best Practice

In this walkthrough, ISelectionContainer is implemented so that the selectable object collection and the selected object collection are the same collection. Only the selected object appears in the Property Browser list. For a more complete ISelectionContainer implementation, see the Reference.ToolWindow samples.

Visual Studio tool windows persist between Visual Studio sessions. For more information on persisting the tool window state, see ProvideProfileAttribute.

Partager via