Share via

Writing the Settings Tab Code

  • Article

The sample Windows Home Server add-in that you create in this tutorial contains a Settings tab. Create a Settings tab when you want to provide a way for users to set options for your custom application.

On the Console tab that you created in the topic Writing the Console Tab Code, you placed a button that opens the Windows Home Server Settings dialog to a specific Settings tab when it is clicked. This section explains how to create that Settings tab.

Write the Settings Tab Application Code

Adding the Settings Tab Class File to Your Project

To begin writing code for the Settings tab, you need to add a class file to your project. Create the Settings tab class within the same Visual Studio project that you created in the topic Setting Up an Add-In Solution.

To add a new class file

  1. With the SDKSample project open in Visual Studio, in Solution Explorer, right-click SDKSample, point to Add, then click Class.

  2. In the Add New Item dialog, replace the default name, Class1.cs (Class1.vb in Visual Basic), with SampleSettings.cs (SampleSettings.vb in Visual Basic).

  3. Click Add.

  4. At the top of the SampleSettings code file, add the following using statements (Imports in Visual Basic):

    using System.Drawing;
using System.Windows.Forms;
using Microsoft.HomeServer.Extensibility;

Step 1: Declare a class that implements the ISettingsTab interface

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

Declare a class that implements the ISettingsTab interface. Replace the default class name of SampleSettings with HomeServerSettingsExtender, as shown in the following code snippet:

public class HomeServerSettingsExtender : Microsoft.HomeServer.Extensibility.ISettingsTab

Important

Note that the access modifier is public. The class that implements the ISettingsTab interface must be public or the tab will not load.

Step 2: Create a control to display on the pane area of the Windows Home Server Settings page

The pane area of the Windows Home Server Settings dialog is available for you to display an object of type Control. Like the Console tab control, the Settings tab control can contain other controls within itself. This is the control that is referenced by the TabControl property of the Settings tab.

For the sample Settings tab in this tutorial, create a very simple RichTextbox Control named SampleControl. Place the code for this class in SampleSettings.cs immediately after the namespace declaration. If you are writing in Visual Basic, place the code in SampleSettings.vb immediately after the Imports statements:

namespace SampleSettings
{
internal class SampleControl : RichTextBox
    {
        public SampleControl(int width, int height)
        {
            RichTextBox rtDisplay = new RichTextBox();
            rtDisplay.BorderStyle = BorderStyle.FixedSingle;
            rtDisplay.SetBounds(0, 0, width, height);
            rtDisplay.Multiline = true;
            rtDisplay.ReadOnly = true;
            rtDisplay.Text = "SDK Sample Settings.";
            rtDisplay.Parent = this;
        }
    }

In this snippet, SampleControl is defined in the same namespace as the HomeServerSettingsExtender class. SampleControl inherits from the RichTextBox Control, and it has the internal access modifier (friend in Visual Basic), so it can be accessed only by code that is within the same assembly. Note also that the dimensions of SampleControl are set by the height and width parameters that are passed in with the constructor call.

When you click the sample Settings tab in the Windows Home Server Settings dialog, SampleControl appears in the pane area of the Windows Home Server Settings dialog as a read-only text area with the text "SDK Sample Settings."

Note

In Step 6, you code the TabControl property so that it returns a reference to this control.

Step 3: Code the class fields and HomeServerSettingsExtender constructor

Now that you have defined the custom Control class for the Control object that appears on the pane area of the Windows Home Server Settings dialog, you can code the class fields and constructor for your sample Settings tab:

public class HomeServerSettingsExtender : Microsoft.HomeServer.Extensibility.ISettingsTab
{
  private SampleControl tabControl;
  private IConsoleServices services;

  //The constructor
  public HomeServerSettingsExtender(int width, int height, IConsoleServices consoleServices)
  {
    //Initialize private fields
    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 contains three parameters: two integer parameters, width and height, and a Microsoft.HomeServer.Extensibility.IConsoleServices object:

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

When HomeServerConsole.exe calls the constructor for HomeServerSettingsExtender, it passes in values for the width, height, and IConsoleServices arguments.

Third, note that you use the height and width values that are passed in by the arguments to the constructor call to initialize the private instance of SampleControl:

public HomeServerSettingsExtender(int width, int height, IConsoleServices consoleServices)
{
  //Initialize private fields
  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 available pane area of the Windows Home Server Settings dialog. In the HomeServerSettingsExtender constructor, you pass these same values to the constructor for tabControl, so when tabControl appears in the pane area of the Windows Home Server Settings dialog, it fills the whole pane area.

Important

HomeServerConsole.exe always calls the constructor for the HomeServerSettingsExtender class by using the following values for the width and height arguments: width set to 390 and height set to 410. If you create a Control for your custom Settings tab that exceeds these dimensions, it is cropped.

Step 4: Implement the TabText property

When your Settings tab appears in the Windows Home Server Settings dialog, it should have a brief, descriptive name that helps users understand what settings it contains. Set this name with the TabText property. For this tutorial, implement this property so that it returns "SDK Sample," as in the following code snippet:

public string TabText
  { 
    get 
      { 
        return "SDK Sample";
      }
  }

Step 5: Implement the TabImage

The ISettingsTab interface implements the TabImage property of the IConsoleTab interface. TabImage returns a bitmap that appears on the Settings tab next to the TabText.

Important

The bitmap must be 32 x 32 pixels and have a resolution of 96 DPI. A bitmap of any other dimensions does not display correctly.

The following code snippet references the image file SDKSampleImg, which was added as a resource to the SDKSample project in the topic Setting Up an Add-In Solution:

public Bitmap TabImage 
  {
    get 
      {
        return Properties.Resources.SDKSampleImg;
      }
  }

Step 6: Implement the TabControl property

With the custom control tabControl, which you defined and initialized in Step 3 of this topic, code the TabControl property of the HomeServerSettingsExtender class so that it returns a reference to tabControl:

public Control TabControl
  { 
    get
      {
        return tabControl;
      }
  }

Important

You must use the approach shown here, where the TabControl property returns a reference to the same Control object that you created and initialized in the constructor for your Settings tab. Implementing the TabControl property so that it creates and a returns a new Control object each time it is called causes unwanted results.

Step 7: Implement the GetHelp() method

Use GetHelp to display help content when an end user selects your tab and presses one of the help keys (Help or F1). You must implement the GetHelp method as part of the IConsoleTab interface, and if you are an OEM or system builder you must hook up your own help content to your Settings tab.

The signature of the GetHelp method requires you to return a Boolean value that indicates that you will display custom help content for your Settings tab. A return value of true indicates that you will display your custom help content.

For this tutorial, you can just display a MsgBox for your help content, but when you create an actual production tab, you may want to display a help topic in a compiled Help file (.chm):

public bool GetHelp()
  {
        // Open a simple Message Box for Help
        MsgBox(“You clicked Help or pressed F1.”, , “My Tab Help”);

        // Open a custom compiled Help file (.chm)topic
        // this.services.OpenHelp(“MyHelpFile.chm”,”<MyTopicGUID>”);
        return true;
  }

Step 8: Implement the SettingsGuid property

An important step in creating a Settings tab is to implement the SettingsGuid property. When it is implemented as a property for a Settings tab, the SettingsGuid is used much differently than it is when implemented as part of a Console tab.

As a property of a Settings tab, the SettingsGuid property provides a way for you to call your Settings tab from your application or to associate it with a Console tab. In the sample Console tab that you created earlier in this tutorial, you placed a button on the Console tab pane area that calls a Settings tab (by referencing the Settings tab's GUID) when it is clicked:

internal void BtnOpenSettings_Click(object sender, EventArgs e)
  {
    this.services.OpenSettings(new Guid("{A99FEB96-A120-44af-9972-3CB942F521A0}"));
  }

To make the Settings tab appear when a user clicks the Open Settings button on the Console tab, implement the SettingsGuid property so that it uses the same GUID as the one used in the calling code in the BtnOpenSettings_Click method:

public Guid SettingsGuid
  {
    get
      {
        return new Guid("{A99FEB96-A120-44af-9972-3CB942F521A0}");
      }
  }

Step 9: 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 Windows Home Server Settings dialog, changes to the settings are committed. For example, if you turn on Media Library Sharing for a shared folder in the Shared Folders Windows Home Server Settings dialog and then click OK, the change to that folder is committed and the folder is marked as a Media Library Sharing folder.

Important

Clicking OK or Apply commits changes globally across all Settings tabs. For example, if a user changes settings on the General Settings tab, the User Accounts Settings tab, or the Shared Folders Settings tab, and then changes the settings on your custom Settings tab, when OK or Apply is clicked, changes for all four Settings tabs are 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 this tutorial, you are not allowing users to change the settings for your application, so no changes need to be committed. Code the Commit method so that it returns false.

public bool Commit ()
  { 
    return false;
  }

Summary

You now have a Windows Home Server Settings tab. Continue with the Deploying an Add-In section of this tutorial to finish your sample Add-in solution.

See Also

Concepts

Creating a Settings Tab
Creating a Console Tab