Share via

Writing the Console Tab Code

  • Article
  • 03/19/2009

The Console tab that you create in this tutorial allows end users to retrieve information about Windows Home Server objects and then display that information in the Console tab pane area. The Console tab also allows end users to show an associated Settings tab.

To provide this functionality, you need to write code that responds to actions that end users take on your Console tab.

Important

Before you start this section, ensure that you have performed the steps enumerated in the previous topic, Creating the Console Tab User Interface.

Write the Console Tab application code

With Visual Studio open to the SDKSample project that you created in Setting Up an Add-In Solution, right-click HomeServerTabExtender.cs (HomeServerTabExtender.vb in Visual Basic) in Solution Explorer, and then click View code from the popup menu.

Before you begin adding code for your Console tab, add the appropriate using statements (Imports in Visual Basic) to your code file:

using System.Drawing;
using System.Windows.Forms;
using Microsoft.HomeServer.Extensibility;
using Microsoft.HomeServer.SDK.Interop.v1;

Step 1: Declare a class that implements the IConsoleTab interface

To create a Console tab, you must create a class that implements the Microsoft.HomeServer.Extensibility.IConsoleTab interface. The IConsoleTab interface contains methods and properties that all Console tabs should contain. Later in this topic, you implement the methods and properties of the interface.

Declare a class that implements the IConsoleTab interface. Delete the existing class declaration for Class1, and replace it with the following:

public class HomeServerTabExtender : Microsoft.HomeServer.Extensibility.IConsoleTab

Important

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

Step 2: Code the class fields and the HomeServerTabExtender constructor

HomeServerConsole.exe is the program that runs the Windows Home Server Console. When HomeServerConsole.exe finds the HomeServerTabExtender class inside your .dll, it calls the HomeServerTabExtender class constructor to initialize your tab. HomeServerConsole.exe passes in values for the width, height, and Console Services objects for your Console tab as parameters to the constructor call.

In this step, you create three private fields in the HomeServerTabExtender class. The first private field holds the reference to the IConsoleServices object that is passed in with the constructor call. The second private field references the instance of the user control, ShowWHSInfoPanel, that appears in the Console tab pane area. Because the Console tab needs to access information about Windows Home Server objects on the server, you create a third private field for an instance of WHSInfoClass. This is a Microsoft.HomeServer.SDK.Interop.v1 type that provides methods to get information about several Windows Home Server objects.

Note

Console Services objects are explained in the API Reference topic IConsoleServices.

After creating the private fields, you code the HomeServerTabExtender constructor, which must have the following signature:

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

In the constructor, initialize each of the private fields, and hook up event handlers (that you code in the next step) for the button click events for all three buttons on the instance of the ShowWHSInfoPanel user control.

// The class declaration
public class HomeServerTabExtender : Microsoft.HomeServer.Extensibility.IConsoleTab
  {
    // Private fields declared
    private IConsoleServices services;
    // Declare an instance of the UserControl, ShowWHSInfoPanel
    private ShowWHSInfoPanel nPanel;
    private WHSInfoClass whsInfo;

// The constructor
    public HomeServerTabExtender(int width, int height, IConsoleServices consoleServices)
      {
         // Initialize the private fields
         nPanel = new ShowWHSInfoPanel();
         nPanel.Size = new Size(width, height);
         this.services = consoleServices;
         whsInfo = new WHSInfoClass();

         // Hook up event handlers for the nPanel buttons
         nPanel.btnClearInfo.Click += new EventHandler(BtnClearInfo_Click);
         nPanel.btnShowInfo.Click += new EventHandler(BtnShowInfo_Click);
         nPanel.btnOpenSettings.Click += new EventHandler(BtnOpenSettings_Click);
       }
  }

Step 3: Code event handlers

In the section of code above, you hooked up event handlers with the click event for each of the three buttons on the ShowWHSInfoPanel instance, nPanel. In this step, you write the three event-handler methods.

Code the BtnShowInfo Click method

First, code the event handler for the nPanel.btnShowInfo.Click event. When an end user clicks Show WHS Info on the Console tab pane area, the BtnShowInfo_Click method sets the Text property for the RichTextBox Control, nPanel.rtShowWHSInfo, to a string that contains information about some Windows Home Server objects that are on the server.

The BtnShowInfo_Click method creates three Array objects, and then populates each Array with objects of a given Windows Home Server type. Then, the method loops through each Array, collecting information about each item in the Array. Finally, the text property for the nPanel.rtShowInfo RichTextBox Control is set to the string that contains all of the collected information:

internal void BtnShowInfo_Click(object sender, EventArgs e)
  {
    string displayText;
            
    // Fill each array with WHS objects
    Array disks = whsInfo.GetDiskInfo();
    Array volumes = whsInfo.GetVolumeInfo();
    Array shares = whsInfo.GetShareInfo();

    displayText = "DISK INFORMATION:\nSystem Name\t\tSize\n";

    // Iterate through each array and get individual WHS object information
    foreach (IDiskInfo pDisk in disks)
      {
         displayText += pDisk.DevicePath.ToString() + "\t\t" + pDisk.Size.ToString() + "\n\n";
      }

    displayText += "VOLUME INFORMATION:\nPath\t\tSize\n";

    foreach (IVolumeInfo pVolume in volumes)
      {
        displayText += pVolume.Path.ToString() + "\t\t" + pVolume.Size.ToString() + "\n\n"; 
      }

    displayText += "SHARE INFORMATION:\nName\t\tIs Duplicated\n";

    foreach (IShareInfo pShare in shares)
      {
        displayText += pShare.Name.ToString() + "\t\t" + pShare.IsDuplicated.ToString() + "\n\n";
      }

    // Display the collected information
    nPanel.rtShowWHSInfo.Text = displayText;
  }

Code the BtnClearInfo Click method

Next, code the event handler for the nPanel.btnClearInfo.Click event. The BtnClearInfo_Click method is fairly simple. It uses one line of code to clear any text from the display area of the nPanel user control.

When an end user clicks Clear Display on the nPanel user control, the BtnClearInfo_Click method sets the Text property of the nPanel.rtShowWHSInfo RichTextBox control to an empty string:

internal void BtnClearInfo_Click(object sender, EventArgs e)
  {
    nPanel.rtShowWHSInfo.Clear();
  }

Code the BtnOpenSettings Click method

Finally, code the event handler for the nPanel.btnOpenSettings.Click event. When an end user clicks Open Settings on the nPanel user control, the Windows Home Server Settings dialog opens to the Settings tab that you specify in the BtnOpenSettings_Click method.

The BtnOpenSettings_Click method calls the Microsoft.HomeServer.Extensibility.IConsoleServices.OpenSettings(System.Guid) method, passing the globally unique identifier (GUID) for a specific Settings tab as the only argument:

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

Note

You code the Settings tab that is specified here later in the tutorial.

Step 4: Implement the TabText property

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

Note

The amount of space that is available for the tab text is limited. Consider limiting your tab text to approximately 14 characters so that it is not cropped when being displayed.

Code the TabText 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 property

The TabImage property of the IConsoleTab interface returns a bitmap. This bitmap appears on the Console tab above 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.

Use the image file SDKSampleImg that you 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

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. For the purposes of this tutorial, return the Control nPanel UserControl, that you instantiated in the HomeServerTabExtender class constructor.

Code the TabControl property so that it returns the Control, nPanel:

public Control TabControl
  {
    get 
      {
        return nPanel;
      }
  }

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 Console tab. Implementing the TabControl property so that it creates and 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 on the Windows Home Server Console 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 Console 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 Console 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, 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

Depending upon how your add-in works, you may want to provide end users the ability to set options for your application. To do so, create a custom Settings tab on the Settings page dialog for the Windows Home Server Console. The custom Settings tab must be an implementation of the ISettingsTab interface.

For example, a user who wants to change settings for shared folders 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 dialog, and then changes the settings.

You can also associate a Settings tab with a Console tab. You create the association by using the SettingsGuid property.

For the SettingsGuid property, you have two choices:

  • Return a GUID for a specific Settings tab. To do this, you must return a System.Guid object with the GUID of the Settings tab that you want to associate with your Console tab.

  • Return an empty Guid. Returning an empty System.Guid indicates that you do not want to associate a Settings tab with your Console tab.

For this tutorial, do not use this property to create an association between the Console tab and a Settings tab because this tutorial implements a button on the Console tab pane area that opens the Settings page dialog directly.

Code the SettingsGuid so that it does not create an association with a Settings tab:

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

Tip

You can test the console tab as it is by compiling the project and copying the output .dll file to the C:\Program Files\Windows Home Server\ directory on the server and restarting the Windows Home Server Console. Note that a directory by this name exists on both the client and the server. The add-in will only be visible if the .dll file is copied to the server directory.

Summary

You have now created a Windows Home Server Console tab. Work through the rest of the tutorial to finish your sample add-in solution.

See Also

Concepts

Changing the Tab Order
Creating a Settings Tab
Creating a Console Tab