TDHAppBar - A Library to Convert a Windows.Forms.Form into an Application Desktop Toolbar

• Download demo - 85.01 KB
• Download source - 103.92 KB

Background

Recently, I was in the market for code to enable Desktop docking of a small toolbar applet. I came across this CodeProject article from 2003, C# does Shell, Part 3, which seemed at first to be just what I wanted. (I don't at all mean to slight "arikp's" article or code: it's a well written and informative article; the code just wasn't what I needed for the task at hand.) And, in fact, rather than going into technical details in this article, I refer the reader back to "arikp's" original article, of which the present article is purely derivative.

Fortunately for me, in the comments section to the above referenced article, back in December of 2006, "GWB@s1c" posted code answering the particular issues I had.

Since "GWB@s1c" hasn't written an article on his code (and since I've added my own particular spin to it), I submit this article to make the code more readily available to the CodeProject community.

The 'AppBar.ApplicationDesktopToolbar' Class

TDHAppBar is strictly the name for this article and of the project/assembly I've written based on the original code; the namespace and class-name are AppBar.ApplicationDesktopToolbar as in the original code example "GWB@s1c" posted last December. It was my intention to make minimal changes to the original code and to clearly delineate my changes; thus I've retained the original namespace and class-name (while giving my project a unique name, should "GWB@s1c" ever choose to submit an article on some version of his code).

Using The 'AppBar.ApplicationDesktopToolbar' Class

To use AppBar.ApplicationDesktopToolbar as is, add a reference in your project to the class library TDHAppBar.dll. Example usage follows:

using AppBar;
// 
private AppBar.ApplicationDesktopToolbar appBar = null;
//
private void cmnuMain_Dock_Click(object sender, System.EventArgs e)
{
    AppBar.AppBarEdges theAppBarEdge = AppBar.AppBarEdges.Right;    // example

    if (this.appBar == null)
    {
        appBar = new AppBar.ApplicationDesktopToolbar(
            this, theAppBarEdge,
            // HorizConfig delegate
            new AppBar.AltitudeConfigDelegate(this.Configure_Horizontal),
            // VertConfig delegate
            new AppBar.AltitudeConfigDelegate(this.Configure_Vertical),  
            // AutoHideConfig delegate
            new AppBar.AutoHideChangedDelegate(this.Configure_AutoHide), 
            // Docking dimensions (max height OR max width, depending upon .Edge)
            106, 82,  
            false);    // set .AutoHide
    }
    else
    if (this.appBar.Edge != theAppBarEdge)
    {
        appBar.Edge = theAppBarEdge;    // Change the Docked .Edge
    }

}

private void Configure_AutoHide(bool asAutoHide)
{
    // do something
}
private void Configure_Horizontal(bool asDocked)
{
    // do something
}

private void Configure_Vertical(bool asDocked)
{
    // do something
}

private void cmnuMain_DockAutoHide_Click(object sender, System.EventArgs e)
{
    if (this.appBar != null)
    {
        this.cmnuMain_DockAutoHide.Checked = !this.cmnuMain_DockAutoHide.Checked;
        this.appBar.AutoHide = this.cmnuMain_DockAutoHide.Checked;
    }
    else
    {
        this.cmnuMain_DockAutoHide.Checked = false;
        this.cmnuMain_DockAutoHide.Enabled = false;
    }
}

private void cmnuMain_Float_Click(object sender, System.EventArgs e)
{
    if (this.appBar != null)
    {
        if (!this.appBar.UnDock(AppBar.Altitude.Horizontal))    // example
        {
            this.appBar.Dispose();
        }
        this.appBar = null;
    }
}

The TDHAppBar project was written (and compiled) using Visual Studio 2003 (.NET 1.1). Converting it to .NET 1.0, if necessary, should be a straight forward matter of adding the ApplicationDesktopToolbar.cs and ShellApi.cs source code files to one's project.

Points-of-Interest of the 'AppBar.ApplicationDesktopToolbar' Class

Some of the methods of the class do have the potential for throwing exceptions. These are related to either a failure to register the Form as an AppBar or a failure to "de-register" it. For instance, the class constructor itself could possibly throw an exception (so, the example code above really ought to take that into account). The set accessor for the .Edge property also has the potential to throw an exception, since it sets the AppBar Form to a different Desktop edge by first "de-registering" the AppBar and then creating/registering a new AppBar as docked to the new edge.

The constructor for my version of the AppBar.ApplicationDesktopToolbar class records various properties of the Form being converted to an AppBar. These values are used to restore the Form to its original state when the .Undock() or .Dispose() methods are executed. Some signatures of the .Undock() method allow for new values to be given for some of these properties.

With my version of the class, it is not necessary that the original Form's [.FormBorderStyle == FormBorderStyle.None]; - the class will make that change when converting the Form to an AppBar. And, when converting it back to a standard Form, the class restores this property value. Nor is it necessary that the original Form's [.TopMost == true]; - the class will set this property as necessary.

The members-of-interest of the namespace AppBar are:

• AppBar.Altitude - The elements of this enum indicate to the instance of the AppBar.ApplicationDesktopToolbar class which configuration delegate (if given to the constructor) to invoke when UnDocking the AppBar Form (i.e. converting it back to a standard Form).
• AppBar.AppBarEdges - The elements of this enum indicate which Desktop edge the instance of the AppBar.ApplicationDesktopToolbar class is to dock the AppBar Form.

• public delegate void AltitudeConfigDelegate(bool asDocked) - The appropriate instance of this delegate (if given to the constructor) is invoked by the instance of the AppBar.ApplicationDesktopToolbar class as necessary to reconfigure the AppBar Form between vertical and horizontal orientations.
• public delegate void AutoHideChangedDelegate(bool asAutoHide) - This delegate (if given to the constructor) is invoked by the instance of the AppBar.ApplicationDesktopToolbar class when its .AutoHide property changes.

The members-of-interest of the interface of class AppBar.ApplicationDesktopToolbar are:

• AutoHide - This property gets or sets whether the instance of the AppBar.ApplicationDesktopToolbar class has been instructed to autohide the AppBar Form.
• Edge - This property gets or sets which Desktop edge the instance of the AppBar.ApplicationDesktopToolbar class is to dock (or re-dock) the AppBar Form.

• UnDock() - This method (of which there are various signatures) converts the AppBar Form back into a standard Form. Calling .UnDock() with no arguments attempts to return the Form to its state before it was converted to an AppBar; the other signatures may be used to specify a new state for the Form.
• Dispose() - In my version of the class, this method is essentially the same as .UnDock() with no arguments.

History

• 2007 December 17: Submission of TDHAppBar project Version 1.0.001 to The Code Project
• 2007 December 18: Version 1.0.002:
  • Fixed a minor annoyance with the .AutoHide mode -- when the AppBar Form had been set to .AutoHide, the context menu might vanish before one had a chance to make a selection.