Creating a Settings Tab

Article
03/26/2007

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

You create a Settings tab when you want to provide a way for users to set options for your custom application. When a user clicks the Settings button on the Windows Home Server Console, the Settings page dialog appears and displays your custom Settings tab.

To create a Settings tab for the Windows Home Server Console, implement the ISettingsTab interface. The ISettingsTab interface is virtually identical to the IConsoleTab interface that you implement to create a custom console tab. In fact, the ISettingsTab interface implements the IConsoleTab interface, so it contains all the same methods and properties with one addition--the Commit method.

For that reason, this topic only demonstrates what is unique to the ISettingsTab interface.

Adding the Settings Tab Class File to Your Project

For this walkthrough, create the Settings tab class within the same Visual Studio project that you use to create your custom tab for the Windows Home Server Console.

Add a class file to your console tab project and begin coding your custom Settings tab within the same namespace and the same using directives as you used for the custom console tab. For the examples in this topic, create an additional class file, SampleSettings.cs, in the project, MyWHSApp, that you created in the topic, Creating a New Tab. SampleSettings.cs will hold the code for our custom Settings tab class.

To add a new class file

With the Visual Studio project MyWHSApp open, right-click MyWHSApp, point to Add, and then click New Item.
In the Add New Item dialog, click Class.
In Name, replace Class1.cs with SampleSettings.cs.
Click Add.

For more information about how to set up Visual Studio for a custom tab project for the Windows Home Server Console, see Creating a New Tab.

Creating a Custom Settings Tab Example

The Settings Tab

The Settings page dialog for the Windows Home Server Console will display every time a user clicks the Settings button on the Windows Home Server Console. The Settings page is divided into three areas: the left tab area, which contains all Settings tabs; the right display or pane area, which changes when you select a different Settings tab in the tab area; and the button area below the pane area, which contains the OK, Apply, and Cancel buttons. When you create a custom Settings tab, you add a tab to the Settings tab area of the Settings page dialog.

When a user clicks the Settings button on the Windows Home Server Console, the Settings page dialog will appear. If you have not created a custom Settings tab, then only the current Settings tabs appear in the tab area of the Settings page. If you have created a custom Settings tab, the constructor for your Settings tab is called and the Settings page will display your Settings tab in the tab area.

Step 1 - Implementing the ISettingsTab interface

As previously mentioned, HomeServerExt.dll only contains interfaces and not concrete classes. To create a custom Settings tab, implement the ISettingsTab interface.

First, code a concrete class that implements the ISettingsTab interface. It is critical that you name your class as in the following example. In SampleSettings.cs, type the following class declaration:

public class HomeServerSettingsExtender : Microsoft.HomeServer.Extensibility.ISettingsTab

Note

You'll need to replace the class name that Visual Studio automatically creates, in this case, SampleSettings, with HomeServerSettingsExtender.

Note that the class name is HomeServerSettingsExtender. You must name your class with this name in order for your code to work. This is because HomeServerConsole.exe will search your .dll file for a class of this name. If your class is not named HomeServerSettingsExtender, HomeServerConsole.exe will not load it.

Step 2 - Create a control to display on the Settings page pane area

The Settings page pane area is available for you to display an object of type Control. This can be any control of your choosing and this is the control that is referenced by the TabControl property of the Settings tab. If you want a control to appear in the Settings page pane area, you must code the TabControl property so that it returns a reference to that control.

For your sample Settings tab, define a custom control class, SampleControl, for the control that will appear in the Settings page pane area:

internal class SampleControl : Panel
{
  public SampleControl(int width, int height)
  {
    Panel frame = new Panel();
    frame.BorderStyle = BorderStyle.FixedSingle;
    frame.SetBounds(0, 0, width, height);
    frame.Parent = this;
  }
}

In this example, SampleControl is defined in the SampleSettings.cs file in the same namespace as the HomeServerSettingsExtender class. It has the internal access modifier so it can only be accessed by code within the same assembly, such as code in the HomeServerExtender.cs file, which contains the code for the custom tab.

Step 3 - Code the Constructor for the custom Settings tab

Now that you have defined the custom Control class for the Control object that will display on the Settings page pane area, you can go back and code the constructor for your custom Settings tab (the namespace and class declarations are repeated here to give context):

public class HomeServerSettingsExtender : Microsoft.HomeServer.Extensibility.ISettingsTab
{
  private SampleControl tabControl;
  private IConsoleServices services;
  public HomeServerSettingsExtender(int width, int height, IConsoleServices consoleServices)
  {
    tabControl = new SampleControl(width, height);
    this.services = consoleServices;
  }
…
}

First, note the private field that refers to a private instance of the custom Control, SampleControl:

private SampleControl tabControl;

Second, note that the constructor for HomeServerSettingsExtender:

public HomeServerSettingsExtender(int width, int height, IConsoleServices consoleServices)

When HomeServerConsole.exe calls the constructor method of your HomeServerSettingsExtender class, it will pass in values for the width, height, and console services objects.

For the walkthrough, use the values passed in by the parameters in the constructor call to initialize the private instance of SampleControl:

public HomeServerSettingsExtender(int width, int height, IConsoleServices consoleServices)
{
  tabControl = new SampleControl(width, height);
  this.services = consoleServices;
}

By default, the values for width and height that HomeServerConsole.exe passes in the call to the HomeServerSettingsExtender constructor reflect an area that fills the entire Settings page pane area. In the HomeServerSettingsExtender constructor, these same values are in turn passed to the constructor for tabControl, so when tabControl is displayed on the Settings page, it will fill the whole pane area.

Step 4 - Implement the TabControl property

Now that the custom control, tabControl, is defined, code the TabControl property of the HomeServerSettingsExtender class so that it returns a reference to tabControl:

public Control TabControl { get { return tabControl; } }

Step 5 - Implement the Commit() method

The Commit method provides a way for you to commit changes to backend objects. When a user clicks OK or Apply on the Settings page, settings changes will be committed. For example, if you turn on Media Library sharing for a shared folder in the Shared Folders Settings page and then click OK, the change to that folder will be committed and the folder will be marked as a Media Library Sharing folder.

Important

Clicking OK or Apply commits changes globally across all Settings tabs. For example, if a user makes settings changes to the General Settings tab, the User Accounts Settings tab, or the Shared Folders Settings tab, and then makes settings changes to your custom Settings tab, when OK or Apply is clicked, changes for all four Settings tabs will be committed, not just the last Settings tab visited.

If you code Commit to return true, then you are signaling to the calling code that all changes have been committed to backend objects. For the walkthrough, no changes are committed, so code the Commit method so that it returns false.

public bool Commit ()
  { 
     return false;
  }

Step 6 - Implement the SettingsGuid property

The last step in creating a custom Settings tab is to implement the SettingsGuid property. When a user clicks the Settings button, the Settings page will use the SettingsGuid property to locate your Settings tab. Code the SettingsGuid with the following GUID:

public Guid SettingsGuid { get { return new Guid("????????-B09B-417E-A3C9-CC6AC9F934FF"); } }

This is the same GUID that used for the SettingsGuid property of the custom tab, HomeServerTabExtender, that was demonstrated in the topic, Creating a New Tab. When you build and then deploy your custom tab, clicking the Settings button will cause the Settings page to display with your custom Settings tab.

Step 7 - Implement the rest of the ISettingsTab interface

Now that you have walked through the issues that are unique to implementing the ISettingsTab interface, you can go back and code the rest of the ISettingsTab implementation. For a detailed look at the other members of the ISettingsTab interface, see the topic, Creating a New Tab.

Share via