Creating a New Tab

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

In order to extend the Windows Home Server Console, you will need to create a new tab. The tabs that are already on the console after Setup completes cannot be altered or changed, so if you want to add new functionality to the console, you will need to add a new tab and then customize it for your purposes. In this topic, we create a simple tab on the Windows Home Server Console.

Creating a New Tab Example

With Visual Studio open to the MyWHSApp project that you created in Setting Up Your Project, right-click HomeServerTabExtender.cs in Solution Explorer and then click View code from the popup menu. The rest of the Tutorial assumes you are writing your code in this file.

Step 1 - Implement the IConsoleTab interface.

Since HomeServerExt.dll only contains interfaces and not concrete classes, you will need to implement the exposed interfaces in a concrete class and then build that class into a custom .dll file. To create a new tab, implement the IConsoleTab interface.

First, create a class that implements the IConsoleTab interface. It's important that you declare the class as follows:

public class HomeServerTabExtender : Microsoft.HomeServer.Extensibility.IConsoleTab  

Notice that the class name is HomeServerTabExtender. You must name your class with this name in order for your code to work. This is because HomeServerConsole.exe will search your custom .dll for a class of this name before it will load your tab.

Again, notice that when declaring your custom class, it must implement the IConsoleTab interface.

Step 2 - Code the constructor

HomeServerConsole.exe is the program that runs the Windows Home Server Console. When HomeServerConsole.exe finds the HomeServerTabExtender class inside your custom .dll, it calls the constructor to initialize your new tab. The constructor must have the following signature:

public HomeServerTabExtender(int width, int height, IConsoleServices services)

When a user selects your custom tab on the Windows Home Server Console the pane area for the console changes. The pane area is the area where you can display a single object of type Control for your tab; however, the Control object can contain and display other Controls within itself. If you want a Control to appear in the pane area for your tab, you must code the TabControl property to return a reference to that Control.

When HomeServerConsole.exe calls the constructor method of the HomeServerExtender class, it will pass in values for the width, height, and Console Services objects for your custom tab as parameters to the constructor call.

Create private fields in the HomeServerTabExtender class to hold the values passed in with the constructor call, as well as a private field to reference the Control that you want to display in the pane area.

Use these passed in values to initialize your custom tab and also to initialize the Control that you want to display in the pane area (in this case, it is a Panel control named tabControl). Here it is all together:

// The class declaration
public class HomeServerTabExtender : Microsoft.HomeServer.Extensibility.IConsoleTab
  {
    private int width;
    private int height;
    private IConsoleServices services;
    private Control tabControl

// The constructor
    public HomeServerTabExtender(int width, int height, IConsoleServices consoleServices)
      {
         this.width = width;
         this.height = height;
         this.services = consoleServices;
         tabControl = new Panel();
         tabControl.Width = width;
         tabControl.Height = height;
       }
  }

Step 3 - Implement the TabText property

The TabText property is read-only and returns a string that contains the caption or text of the tab. This is the caption that describes your tab. For example, the TabText property for the tab that deals with user accounts is User Accounts.

Code the TabText property so that it returns "My Tab" as in the following code snippet:

public string TabText { get { return "My Tab"; } }

Step 4 - Implement the TabImage property

The TabImage property of the IConsoleTab interface should return a bitmap. This bitmap is displayed above the custom tab next to the TabText. For this example, we use the image file OemIcon.png

Use the Assembly.GetExecutingAssembly().GetManifestResourceStream() method to return OemIcon.png to the calling code:

public Bitmap TabImage 
  {
    get 
      {
        return new Bitmap
        ( Assembly.GetExecutingAssembly().GetManifestResourceStream(
"MyApp.Images.OemIcon.png"));                
       } 
  } 

Step 5 - Implement the TabControl property

The TabControl property returns the Control that appears on the pane area of the console when you select the tab, as mentioned in Step 1 of this topic.

Code the TabControl property so that it returns the Control, tabControl, that you created in the constructor for HomeServerTabExtender in Step 1:

public Control TabControl { get { return tabControl; } }

Step 6 - Implement the GetHelp() method

When a user selects your custom tab and then clicks the Help button on the Windows Home Server Console, the GetHelp method is called. Although you must implement the GetHelp method as part of the IConsoleTab interface, you are not required to hook up your own help content to your custom tab. If you do not hook up your own custom help, the Help button will open the default help content for Windows Home Server.

The signature of the GetHelp method only requires you to return a Boolean value that indicates whether or not you want to use the default help content for your tab. A return value of true indicates that we want to use our own custom help.

For this walkthrough, we do not implement custom help, so code GetHelp so that it returns false:

public bool GetHelp()
  {
    return false;
  }

Returning a value of false signals that the default help content for Windows Home Server should open.

Step 7 - Implement the SettingsGuid property

After the user selects your custom tab, the Windows Home Server Console display changes and the pane area of the console displays the Control that you implemented for the TabControl property. Depending upon your tab, you may want to allow users to set options for your application. To do so, you create a custom Settings tab on the Settings page dialog for the Windows Home Server Console.

For example, when a user wants to make settings changes related to shared folders, he clicks the Settings button on the console. When the Settings page dialog appears, the user clicks Shared Folders in the tab area of the Settings page and can then make settings changes related to shared folders on the server. The custom Settings tab must be an implementation of the ISettingsTab interface.

For the SettingsGuid property, you have two choices:

• Return your custom Settings tab. To do this, you must return a System.Guid object with the GUID of your custom Settings tab.
• Return an empty Guid. Returning an empty System.Guid causes the default Settings page dialog for Windows Home Server to appear.

For the walkthrough, code the SettingsGuid so that it returns the GUID of the custom Settings tab that you will create in the topic, Creating a Settings Tab:

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

Alternatively, you could have coded the SettingsGuid property so that it will not call a custom Settings page. In that case, you would use the following code:

public Guid SettingsGuid { get { return Guid.Empty; } }.

See Also

Reference

IConsoleTab
ISettingsTab

Concepts

Extending the Windows Home Server Console
Setting Up Your Project
Creating a Settings Tab
Changing Tab Order
Deploying Your Console Tab