WHS Dev Tip #14: ITabExtender, Part 1: TabOrdinal
A little secret is buried away in the Windows Home Server Console, a secret so useful it should have been officially documented and made available to the coding public long ago (in the opinion of this humble blogger) with a couple of tweaks.
This secret... ITabExtender (Microsoft.HomeServer.Extensibility, HomeServerControls.dll).
An extension of IConsoleTab, ITabExtender provides numerous options that many wish they had already... the ability to specify a tab's location, refreshing, notification just prior to the tab being displayed... even external status notification and multiple tabs in a single assembly.
All of these gems are made possible with ITabExtender, a topic I'll be discussing over the next 4 posts which will cover in the following order:
In order to use ITabExtender, we first need to add a reference to HomeServerControls.dll and can use the interface in place of (or in addition to) IConsoleTab:
Once done we will need to fully implement the interface which includes the following additional properties and members:
Visual Studio will can generate the methods for us by right clicking on the interface and selecting Implement Interface. Once done we'll need to take a moment to cleanse the new methods and remove their raising a few exceptions informing you that the method hasn't yet been implemented and make the code null when applicable... bringing our additions to:
Once added and cleansed the add-in will be compilable and usable, now we want to use it for it's advanced features.
In the code featured above, in only one of the properties or methods are we doing anything or returning anything of use. In the TabOrdinal property a value is returned which is used to specify it's location in the Home Server Console... within reason.
As specified by the Changing the Tab Order page on MSDN, tab positions 2-32 are reserved for Microsoft... this is not merely a suggestion but an absolute requirement. If in your ITabExtender you specify a TabOrdinal inside of the range reserved for Microsoft it will likely not be displayed at all.
Outside of that range though we are pretty free to specify what we want and where... just remember that the general order of tabs in the Home Server console is as follows:
- OEM tab(s)
- Microsoft Tabs
- Tabs with specified location
- Through HomeServerConsole.exe.config file
- All other tabs
At times a conflict may occur where one or more tabs have the same number or none at all, in such cases the disputed tabs inserted in alphabetical order.
This means that a tab that implements ITabExtender will ordinarily appear earlier in the list than the average add-in that does not implement it and does not have it's location overridden through the .config file.
As nice as it might be to have ones own add-in be nice and early in the list, chances are that all users may not agree and instead the user would be forced deal with an undesirable situation, manually change the order, use an add-in to change the order, or remove the offending add-in outright.
Care must be taken when using ITabExtender.TabOrdinal so as not to annoy the end user and not assume that our add-in is the end all be all (even if it is).
All of the discussion previously has been with regards to a tab for the main Home Server Window. On the settings side of things the ISettingsExtender (Microsoft.HomeServer.Extensibility, HomeServerControls.dll) interface exists and does much the same job the same job as ITabExtender (even inheriting from it) and TabOrdinal works the same way in the Settings dialog as it does in the main form.
A sample add-in demonstrating everything discussed here will be part of the last post on Thursday.
ITabExtender allows a programmer the useful ability to specify a tab index of their own. This should however only be done with the knowledge that end users may not agree with the ordering as specified by the programmer and may become annoyed by a new add-in forcing itself ahead of all others even if such positioning is changeable.
Tomorrow: Tab refreshing
Note: The information in this post is based on undocumented and at times deduced information on Windows Home Server and is not officially supported or endorsed by Microsoft and could very easily be wrong or subject to change in future, so please take it and everything else said on this blog with a grain of salt and use with caution.
Labels: WHS Dev Tips