Windows Vista Bridge Sample Library = A Managed API for Windows

I am sure some of you are asking right now, “Why are we writing and talking about Windows Vista in the Windows 7® Blog for Developers?” The answer is simple. We are talking about Windows Vista because Windows 7 is based on the solid foundation of Windows Vista, and provides backward compatibility to the Windows Vista programming model. With that said, we are listening to customer feedback and making great improvements in regard to performance including better resource utilization, reliability, compatibility, and security, thereby perfecting the overall user experience while at the same time providing great value for developers. The Windows Engineering (E7) blog has a great post about this topic.

It is no secret that the Windows Operating System (OS) is based on C / C++ and therefore uses a native programming model, most commonly known by its informal name WinAPI or Win32 API. The Windows API is a native C style or COM-based API. This makes using the API very easy and natural for native C /C++ developers. But what can we offer managed code developers? Are there any managed code APIs for Windows Vista or Windows 7?

The .NET Framework offers an easy and intuitive programming model targeting Windows clients (Web, servers, mobile, etc.) And, together with a set of tools and libraries, it provides a productive and effective framework for writing Windows client applications. One of the strengths of the .NET Framework is that it is a library-based framework, and anyone can add libraries to enhance the framework’s functionality. In fact, the out-of-the-box .NET experience offers a large number of libraries that abstracts the native Windows API, making development for a given Windows client (regardless of the OS version – XP, Vista, or 7) a much easier task than using the native Windows API.

A good example is the .NET WinForms assembly (assembly is .NET’s name for libraries), which contains a set of wrapper classes that wrap a traditional Win 32 API for creating and handling windows in the Windows OS. By abstracting the native API, .NET WinForms ensures that we don’t need to directly work with pointers (HWND) or handles (HINSTANCE) or other Windows native API constructs that could result in code that looks like this:

Rest assured, WinForms is HWND based. A .NET developer can easily access a given Windows form Handle or (HWND) by using the MSG.hwnd property that can be found in the System.Windows.Interop class in the WindowsBase assembly (WindowsBase.dll).

But as comprehensive as the .NET Framework is, it does not offer managed APIs to all Windows’ native APIs. For example, a managed code developer doesn’t have any managed APIs to work with Windows Vista User Account Control (UAC) API, Restart Manager API, or the new Windows Vista Search API. These are just few examples of key native Windows APIs that .NET Framework doesn’t provide interfaces to and yet are crucial for a given application to successfully deploy on Windows while bringing excitement and innovations to end users.

The Windows Vista Bridge Sample Library (VBSL) is an ongoing effort by the Microsoft SDK team to bridge between the .NET framework and the native Windows API. The VBSL is a class library that makes it much easier for managed developers to access light-up Windows Vista features with no need to worry about the Interop layer. Vista Bridge 1.3 provides managed developers with a set of classes, libraries, and samples written in .NET that allows developers to take advantage of Vista features including UAC, Power Management, Restart & Recovery, Restart Manager, Network, Aero Glass, among many others. It is important to say that all the Vista Bridge managed libraries work well with Windows 7 APIs and will continue to work in future release as the SDK team will continue to support this project.

The Vista Bridge Sample Library (download Vista Bridge Sample Library) is part of the Windows SDK. However, this project is important enough to be placed front center in the Code Gallery.

In future posts, we will drill into a few of the features mentioned above, mainly to show how you can take advantage of Windows Vista today in order to make the migration path to Windows 7 much easier in the future.

One area where the VBSL can make a big difference is in dialogs.

Windows Vista offers a wide variety of dialog boxes for different purposes. For examples, if you are using Windows Vista I am sure you are familiar this UI format:

Or with this one:

Both of the above screenshots are fancy dialog boxes based on command links. With command links, users select a single response to a main instruction and by doing so, move on to the next step in a task. Command links have a clean, lightweight appearance that allows for descriptive labels, and are displayed with either a standard arrow or custom icon, and an optional supplemental explanation.

Here is an example of a typical set of command links.

Command links are similar to radio buttons in that they are used to select from a set of mutually exclusive, related choices. Like radio buttons, command links are always presented in sets, never individually. Command links have a lightweight appearance similar to regular links, without a frame or other strong click affordance. Command links are also similar to command buttons, in that they can be the default "command button" and they can have an access key assigned. Like commit buttons, when clicked they either close the window (for dialog boxes) or advance to the next page (for wizards and pages flows).

Using the Windows Vista Bridge Sample Library, you can now create fancy Task Dialogs that look like this:

The Task Dialog is an object in the Vista Bridge Sample Library, Microsoft.SDK.Samples.VistaBridge.Library.TaskDialog and has no design time properties; therefore, you must program the Dialog. But this is easy, as shown in the next examples.

First, create a task dialog: TaskDialog td = new TaskDialog();

Then start setting its attributes, for example, caption, instructions, main content area, and the main icon:

 //main content section
td.Caption = "Fancy \"Vista\" Task Dialog on Win 7";
td.Instruction = "Your instructions go here";
td.Content = "Download Windows Vista Bridge Library";
td.MainIcon = TaskDialogStandardIcon.Information;

Now add the optional footer text and footer icon:

 td.FooterText = "Footer text goes here";
td.FooterIcon = TaskDialogStandardIcon.Shield;

But the fun starts when you start playing with the TaskDialog.Controls, a collection of (you guessed it) TaskDialog controls DialogControlCollection<TaskDialogControl>.

To which you can add TaskDialogControl objects:

 td.Controls.Add(new TaskDialogCommandLink("new tdcl", "main text here", "instruction"));

In addition to adding Command Links, the Task Dialog also exposes a set of events that lets you manipulate and interact with users as they operate the dialog. The Task Dialog object exposes the Tick event to work with the progress bar, Open, and Closing events, as well as HelpInvoked and HyperLinkClick to manage user requests for more information and help.

 //events that you can catch
td.Tick += new EventHandler<TaskDialogTickEventArgs>(OnMyTick);
td.Opened += new EventHandler(OnOpenInvoked);
td.HelpInvoked += new EventHandler(OnHelpInvoked);

You can also add Progress Bar, CheckBox, or Radio Button. Basically, the Windows Vista Task Dialogs API is a mini Dialog framework that saves you a lot of time dealing with wizards and fancy dialog screens.

Now it is up to you. Go ahead and download the Windows Vista Bridge Sample Library, and start using Vista styles dialog—they all work just as well on a Windows 7 machine.

(This blog was written on a Windows 7 machine)

J

The code for the examples above

    1:  td = new TaskDialog();

    2:   

    3:  //

    4:  td.StartupLocation = TaskDialogStartupLocation.CenterOwner;

    5:  td.Cancelable = true;

    6:   

    7:  //main content section

    8:  td.Caption = "Fancy \"Vista\" Task Dialog on Win 7";

    9:  td.Instruction = "Your instructions go here";

   10:  td.Content = "Download Windows Vista Bridge Library Sample";

   11:  td.MainIcon = TaskDialogStandardIcon.Information;

   12:   

   13:  //setting footer content

   14:  td.FooterText = "Footer text goes here";

   15:  td.FooterIcon = TaskDialogStandardIcon.Shield;

   16:   

   17:  //Command Links

   18:  td.Controls.Add(new TaskDialogCommandLink("new tdcl", "Main text here", "Instruction"));

   19:  td.Controls.Add(new TaskDialogCommandLink

           ("Another new tdcl", " Another main text here", "More instruction"));

   20:   

   21:  //Expanding 

   22:  td.ExpansionMode = TaskDialogExpandedInformationLocation.ExpandContent;

   23:  td.ExpandedControlText = "Expanded Control Text";

   24:  td.ExpandedText = "This is some expanded text, only visible when expanded"; 

   25:  td.CollapsedControlText = "Collapsed Control Text";

   26:  td.HyperlinksEnabled = true;

   27:   

   28:  //Prograss Bar

   29:  TaskDialogProgressBar tdpb = new TaskDialogProgressBar();

   30:  tdpb.Name = "myPrograssBar1";

   31:  tdpb.Minimum = 0;

   32:  tdpb.Maximum = 100;

   33:  td.ProgressBar = tdpb; //adding to main Task Dialog

   34:   

   35:  // Check Box

   36:  td.CheckBoxChecked = true;

   37:  td.CheckBoxText = "This is a checkbox, we can register to listen for its events";

   38:   

   39:  //events that you can catch

   40:  td.Tick += new EventHandler<TaskDialogTickEventArgs>(OnMyTick);

   41:  td.Opened += new EventHandler(OnOpenInvoked);

   42:  td.HelpInvoked += new EventHandler(OnHelpInvoked);

   43:  td.Closing += new EventHandler<TaskDialogClosingEventArgs>(OnDialogClosing);

   44:  td.HyperlinkClick += new EventHandler<TaskDialogHyperlinkClickedEventArgs>(td_HyperlinkClick);

   45:   

   46:  td.Show(); 

Comments

• Anonymous
  November 16, 2008
  I understand that the Windows API is very very vast, but still is there a list (Excel file maybe) somewhere showing native APIs and their managed code equivalents and vice versa?

• Anonymous
  December 02, 2008
  In these days of ever-increasing mobile computing, laptop power consumption is ever more important. With

• Anonymous
  December 07, 2008
  It's great that Vista Bridge Sample Library is being released, but why so long (two years!) after the release of Vista? Planning ahead for Windows 7, it would be great if official managed interop libraries such as this could be released before, or at the very latest at the same time, as the release of the operating system. It's no surprise that developer take up of Vista has been so slow when the tools that managed devs need in order to easily work with the new features aren't available.

• Anonymous
  December 14, 2008
  The comment has been removed

• Anonymous
  February 11, 2009
  After all the introductions (see also the Windows 7 blog ), there’s nothing left but to dive into the