Windows 7 for Developers : Sample Code

Fishbowl for Facebook Using the Windows 7 Taskbar for Extra Spice

Yochay Kiriaty — Fri, 20 Nov 2009 01:41:00 GMT

During Wednesday’s keynote, Brian Goldfarb demoed an amazing Silverlight 4 client for Facebook. Beyond its amazing looks, this Silverlight 4 demo provides a full and complete desktop client application for Windows (and Mac). SilverFace is built on top of Silverlight 4 – also announced during the keynote. If you want a cool Facebook client application to work on from your Windows desktop, you should take a look at the Fishbowl for Facebook Preview. Fishbowl is a great WPF application that you can install and enjoy as a user, and at the same time it is a great code sample for developers whom are looking to write WPF applications that use Windows 7 features. If you are interested, you can download the source code for Fishbowl.

In today's world, the client’s experience is more important than ever before. Your application doesn’t just have to be fun and interesting; it has to be good looking, polished, and functional, providing a “natural” user experience that just works. As a developer, you need to push the envelope and use any available technical tool that the OS provides or any other available means (if installed on mobile devices) to provide a superior user experience, or users will switch to the next guy. In such a competitive scenario, using the Windows 7 Taskbar to shave a few seconds from day-to-day tasks looks like a very obvious choice.

Both Silverlight 4 demo and Fishbowl applications each provide a great UX and enhance user productivity. Scott Guthrie also announced the Facebook SDK for managed code applications that combines the latest in Web and Client platform innovations with leading Social technologies (services) to help developers plug into Facebook. But, beside the new Facebook SDK and beside the great looks, the Fishbowl application is a great WPF (3.5) example that demonstrates how to write applications that produce amazing experiences on Windows 7.

As a WPF application, Fishbowl runs on multiple Windows versions, including Windows XP, Windows Vista, and Windows 7, and it integrates with the Windows 7 Taskbar and Multitouch. One of the main ideas behind the Taskbar is to provide users with quick and easy access to their content and help them accomplish tasks and navigate between windows easier and with more confidence. For example, JumpList provides a great tool for surfacing common work items and tasks. If you have a task that you perform once or twice a day, taking two or three clicks to perform the task is not that bad. However, if you have a task that you perform 10, 20, or even 30 more times, using JumpList tasks or items in the recent category list goes a long way. Facebook users often check their wall, write notifications and messages, view friends' pictures, and so on. Therefore, in some scenarios, the Taskbar JumpList tasks, icon notification, thumbnail buttons, and other functionality become major tools in the application.

Fishbowl uses the taskbar to provide a quick, easy, and seamless integration with Facebook functionality directly from your Taskbar. Let’s review some of the user functionality before jumping into code behind.

The Fishbowl taskbar offers a few tasks even before you start your application. You can go to Facebook.com, or you can actually “jump” directly and see your wall, friend's picture, and more, as the following image shows.
One of the amazing things in Fishbowl for Facebook is that it changes it functionality between the different modes of the application. Being able to use the taskbar differently for

different scenarios provides an amazing user experience in heavily used application like Fishbowl.

When Fishbowl runs in normal mode, the Taskbar JumpList reflects items and tasks that you can actually perform in the context of a running application, like viewing the last few notifications and messages that you received without opening the application, as shown by the following image.

If you hover with the mouse above the Fishbowl control, you see the thumbnail preview provided by Windows 7 taskbar. However, Fishbowl uses the thumbnail button again allowing you to both view a preview of the application and act immediately upon the thumbnail preview as shown in the following image.

(And thank you Raman for writing so many PDC tweets J)

Fishbowl also has a mini-mode operation mode. This mode shows just one message in a small window. As you can see in the following image, a small arrow allows you to switch between messages. When you hover over Fishbowl taskbar icon, you can see the preview but you can also control the message, again using the taskbar thumbnail preview.

Besides great Taskbar integration, Fishbowl offers a great Multitouch experience, allowing you to scroll between messages using your finger to touch the touch screen. It is a little hard to illustrate Multitouch with screen capture so you will have to trust me on this one.

We've covered most of the Fishbowl features unique to Windows 7, and in the next post I will dive into the API that enabled these Taskbar and Multitouch features. If you are interested, you can download the source code for Fishbowl.

New Windows API Code Pack Version

Yochay Kiriaty — Thu, 19 Nov 2009 00:02:42 GMT

I am glad to announce that today we shipped a new version of the Windows API Code Pack – version 1.0.1. This is not a major version with a lot of new features, but rather a minor version focused on fixing bugs, improving performance, adding demos and few features updates (new wrappers…)

But before we dive into this new version of the Windows Code Pack let’s better understand what this Windows API Code Pack is all about.

Windows 7 offers new features like the taskbar, libraries, and the Sensor and Location platform, to name a few. These features enable new scenarios and create new opportunities for developers to make their applications shine on Windows 7. All these great features are exposed via the Win32 native API. Currently there is no “Windows 7” namespace in the .NET Framework, and no easy way to use these features from managed code applications. To help managed code developers access them, we released version 1.0 of the Windows API Code Pack for the .NET Framework in August (just after Windows 7 RTM).

The Windows API Code Pack is a free, managed Source Code Library provided by Microsoft as is. You should consider this library as if you wrote it yourself, as if it is your own code. It is a great starting point and provides a really good and solid solution for managed code developers. It covers a lot of the new Windows 7 features as well as some more fundamental core features from the Windows Vista timeframe. You may think of the Windows API Code Pack as the closest thing to an “official” managed API for Windows. But you need to remember that it’s not a product with 24x7 technical support available from Microsoft Customer Service and Support. We believe it is a great solution, and that the codebase is very solid and high quality.

Our goal with the code pack is to enable managed code developers to take advantage of Windows APIs that are not part of the .NET Framework. We feel that as a shared source that is separate from the .NET runtime libraries, the Windows API Code Pack provides an optimal compromise between the Microsoft Win32 managed wrapper, short time-to-market -we released the Windows API Code Pack just a month after the Win7 RTM, and we ship full source code of the library.

The Windows API Code Pack includes a great deal of managed API for Windows (7). For example:

Extensive integration with the Windows Shell namespace, with support for the Windows Shell property system, providing control like explorer browser and access to Windows Libraries
A completely 100% feature parity with the native Taskbar API including (but not limited to) JumpLists, Icon Overlay, Progress bar, Thumbnail, custom switcher, Thumbnail Button, etc…
Windows Task Dialogs , other controls
Support for Direct3D 11.0 and DXGI 1.0/1.1 APIs
Support for the Sensor Platform APIs
Extended Linguistic Services APIs
Windows Restart Manager
Power APIs
And many other features

Each technology represented in the Windows API Code Pack has multiple demos and examples (including source) in C# and VB. We are planning on releasing updates to the Windows API Code Pack roughly every three months. We will be investing mainly in stability (meaning fixing bugs), fundamentals, testing and documentation, as well as new feature support (based on customer feedback).

You may ask yourself, “Why isn't the Windows API Code Pack part of the .NET Framework?”

We ship open source code that we might bring into the runtime sometime in the future, if we feel it's sufficiently core to the entire framework to be worth the size increase. Remember the .NET Framework runs on both Windows Vista and Windows XP. However, Windows 7 is here now, and we want to enable you to access this set of free, open source library sooner rather than later. We’re shipping this library in a community-supported form and, as you can see, we intend to keep updating it. While this version (1.0.1) is a minor release, we are planning on another release in the next few months. In the meantime, you get the best of both worlds in a package that you can use as a whole or in parts without restriction.

Another question you may ask is, “Will .NET 4 replace the need to use the Windows API Code pack?”

When .NET 4 ships, you will be able to use its Windows 7 features such as Taskbar and multitouch integration with WPF, DirectWrite support, and the location API via the Devices namespace. Continue to access other features such as libraries, Restart Manager, and Sensors via the Windows API Code Pack.

Last but not least, we are looking for feedback from the community – that is you the .NET developer using this library to write managed code applications for Windows 7. On the Windows API Code Pack site, you can ask questions, provide feedback, report bugs, and follow open bugs. Your input is critical for the continuation of this library, so please send us your feedback and questions.

To learn more about how to use the Windows API Code Pack check the Windows 7 Training on Channel 9

Windows 7 RTM – Go Get It

Yochay Kiriaty — Thu, 06 Aug 2009 22:36:48 GMT

This is it people. Windows 7 RTM is available for download from MSDN & TechNet sites! If you have a MSDN subscription you can get Windows 7 RTM in English. On October 1st, the remaining languages will be released, for more information read - Windows 7 RTM Available Today for MSDN & TechNet Subscribers. You can also get the Windows 7 SDK and the RTM version of the Windows API Code Pack for .NET Framework.

Make sure you get them all today to start testing your applications, and to make sure your applications are ready for Windows 7 RTM! Now is the time to work on your applications to make sure they are Windows 7 compatible. On top of that, you can use new Windows 7 features such as the Sensor and Location Platform, Taskbar, Libraries, Multi-Touch, the new Graphics APIs, the Windows Ribbon, and many other important and exciting Windows 7 technologies to make your application shine on Windows 7.

New Windows 7 Training Kit for Developers - Get it NOW!

To help you get your application on Windows 7 as soon as possible, we updated the Windows 7 Training Kit for Developers for the RTM version and gave it a new look and better functionality. You can still find all existing topics such as: Taskbar, Sensor and Location, Libraries and Shell, DirectX, Multi-touch, Ribbon, etc. No dev was left behind! The kit is built for both native Win32

C++ developers and .NET developers, so now most topics have multiple labs.We also added 6 new Application Compatibility labs: Version Checking, Data Redirection, UIPI, Installer Detection, Session 0 Isolation, and High DPI, to help you get over the most common application compatibility issues. All the topics in the training kit include additional information like whitepapers, links to MSDN, and links to videos from Channel 9.

Updated Windows Topic Area on Channel 9

We also gave the Windows topic area on Channel 9 a brand new look and functionality to help you to better choose the right Windows 7 content you need. In the new Windows topic area for Channel 9, you can choose from three main topic areas:

Using Windows 7 – Contains consumer- and user-related videos such as how to install Windows 7 and how to set up a home group network
Programming Windows 7 – I don’t really need to explain what goes here, right?
Last but not least, “Under the Hood” – Contains classics like the interview with Mark Russinovich on Windows 7 Internals.

While we hope you find all this helpful, this is only the start! We are working on more new and exciting content that will be shipped in the following weeks, so stay tuned.

In the meantime, here is some additional useful information:

The Windows page on MSDN is the one-stop shop for Windows client developers
At Develop for Windows 7, you can find all the information you need about specific technologies like Direct2D, Taskbar, Sensor and Location, Power Shell 2, Windows Ribbon, and many more
Windows Application Compatibility is the one page you want to visit to make sure your application runs properly on Windows 7; it includes content and tools to test and fix many application compatibility issues. Directly accessible from that page, is the Windows 7 Application Quality Cookbook
Also still very relevant, is the Windows Vista Application Compatibility Cookbook--most Windows 7 compatibility issues are the direct result of the changes introduced in the Windows Vista timeframe, and are included as topics in this Cookbook (UAC, Session 0 Service Isolation, IE Protected Mode, etc.), which is a great starting point for addressing these issues
New Windows 7 videos on the Channel 9 Windows page explore specific features and technologies, and are great “windows” to the Windows engineering team
As always, the E7 blog is an amazing source of the engineering back story behind Windows 7
Last, but not least, for IT-Pro, we have our SPRINGBOARD SERIES, and edge on TechNet

And, of course, continue to watch for new posts.

Version Checking (Just Don’t Do It)

Yochay Kiriaty — Wed, 05 Aug 2009 22:55:33 GMT

Version checking is probably one of the most common Application Compatibility issues that both developers and users are facing. This is another post in a series of posts about Getting Ready for Windows 7.

As said, this is probably the most common application compatibility issue that users as well as developers face is when an application fails upon checking the operating system version. A lot can go wrong when version checking is misused. A user might experience a “silent fail” where the application simply fails to load and nothing happens. Or, a user might see a dialog box indicating something to the effect of “you must be running Microsoft Windows XP or later” when in fact, the computer is running Windows 7. Many other consequences to poor version checking can inconvenience users as well.

Applications fail due to version checking for two main reasons:

A flaw (bug) in the version checking code, which fails if the minor version is decreased, even if the major version is increased, for example, changing versions from 5.1(Windows XP) to 6.0 (Windows Vista), or if the expected service pack (SP) is not installed, even if you're running a newer operating system (for example, changing versions from Windows XP SP 2 to Windows Vista SP 1). We recommend that you check functionality rather then checking version, as you can read in this post.
An intentional blocking that prevents the application from running on operating system versions not tested by its developers. We recommend that you do not block applications from running on future operating systems.

When an application runs on an "incompatible" (due to poor version checking) version of Windows, it will generally display an error message, but it may also exit silently or behave erratically. Often, if we work around the version checking, the application will run well. End-users and IT professionals may apply a fix to let the application think it is running on an older version of Windows.

Working Around The Problem (not really solving the bug)

Compatibility mode: Designed for end users (not for developers to not fix their bugs), compatibility mode is an easy way to work around compatibility issues. When enabled, it applies a set of compatibility fixes that provide a runtime environment more compatible with applications written for older versions of Windows. One of those fixes is the "version lie," which makes the version query functions return the operating system version the user chose in the Compatibility tab of the Properties dialog box instead of the actual Windows version.

To enable compatibility mode:

Right-click the executable or shortcut to the executable.
Click Properties.
Click the Compatibility tab.
Enable Run this program in compatibility mode for: and select the operating system version you think the application should be able to run on.
Some applications consist of several executables. You may need to apply this fix to each one.

Click OK to close the dialog box.
Run the application.

Checking for Features Rather Than Version

As mentioned previously, checking the operating system version is not the best way to confirm that a specific operating system feature is available. This is because the operating system may have had new features added in a redistributable DLL. Rather than using GetVersionEx to determine the operating system platform or version number, it is more effective to test for the presence of the feature itself. For example, we plan to make the Direct2D and DirectWrite APIs and the Ribbon API available in Windows Vista, so there is no need to block your application from using these APIs when running on Windows Vista. You just need to check if these features are available on the Operation System that you are running. If possible, your application should still run if the feature is unavailable, though with reduced functionality or performance.

You can use one of the following techniques to find out if a specific features is available on the given OS.

For Win32 developers:

Use LoadLibrary() to load a library which is not yet loaded into your application. If you are interested in a new function of a DLL which is already loaded (for example, kernel32.dll), then call GetModuleHandle() to obtain the module handle. If either of these functions return NULL, then this indicates an error.
Use GetProcAddress() to obtain a function pointer. If GetProcAddress() returns NULL, then the function may not exist. Cast the pointer to a function pointer of an appropriate prototype. Some functions, although they exist may actually be stubs that return a "not implemented" error. Be such to check for such errors.

Windows 7 introduces a new timer API - SetWaitableTimerEXProc, which adds one more input variable to the regular SetWaitableTimerProc. The TolerableDelay lets you specific a time tolerance window in which the timer can expire. This is a new in Windows 7, that we will use to demonstrate how to check for feature.

      // define function pointer type
    typedef BOOL (WINAPI *SetWaitableTimerExProc)(
      __in  HANDLE hTimer,
      __in  const LARGE_INTEGER *lpDueTime,
      __in  LONG lPeriod,
      __in  PTIMERAPCROUTINE pfnCompletionRoutine,
      __in  LPVOID lpArgToCompletionRoutine,
      __in  PREASON_CONTEXT WakeContext,
      __in  ULONG TolerableDelay
    );

    LARGE_INTEGER liDueTime;
    liDueTime.QuadPart = 0;
    nt period = 1000;
    unsigned int tolerance = 1000;
    HANDLE hTimer = // Get timer handle

    REASON_CONTEXT reasonContext = {0};
    reasonContext.Version = 0;
    reasonContext.Flags = POWER_REQUEST_CONTEXT_SIMPLE_STRING;
    reasonContext.Reason.SimpleReasonString = L"MyTimer";

    // Get module handle to a module which is already loaded
    HMODULE hKernel32Module = GetModuleHandle(_T("kernel32.dll"));
    if (hKernel32Module == NULL)
        return FALSE;

    // Get Address of function
    SetWaitableTimerExProc pFnSetWaitableTimerEx =
    (SetWaitableTimerExProc) ::GetProcAddress(hKernel32Module,     
        "SetWaitableTimerEx");

    // Check if the function exists    
    if (pFnSetWaitableTimerEx == NULL)
        return FALSE;

    // Call function
    if (!pFnSetWaitableTimerEx(hTimer, &liDueTime, period, NULL, NULL,
            &reasonContext, tolerance)
    { // handle error }

Alternatively, you may use DLL delayed loading and call functions in a __try...__except block. (For more information, see Linker Support for Delay-Loaded DLLs.)

For COM APIs, handle errors returned by CoCreateInstance and QueryInterface.NET framework applications that call Win32 APIs via P/Invoke should handle EntryPointNotFoundException and DllNotFoundException exceptions.

If You Must Check OS Version Number

Identifying the current operating system is not the best way to determine whether a particular operating system feature is present. However, if you can’t design your application to check for specific feature availability and the only way to ensure compatibility is through version checking, then please consider the following.

For native applications, you will need to ensure your application's logic will work with newer versions of Windows. Please DO NOT BLOCK on version change! The following is a Win32 code example that uses GetVersionEx. If the major version is greater than 5 (Windows Vista, Windows® Server 2008 R2 and Windows 7), the check passes. If it equals 5, then the minor version should be 1 or greater (Windows XP or Windows Server 2003).

#include <windows.h>
#include <stdio.h>

void main()
{
    OSVERSIONINFO osvi;
    BOOL bIsWindowsXPorLater;

    ZeroMemory(&osvi, sizeof(OSVERSIONINFO));
    osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFO);

    GetVersionEx(&osvi);

    bIsWindowsXPorLater = 
 ( (osvi.dwMajorVersion > 5) ||
       ( (osvi.dwMajorVersion == 5) && (osvi.dwMinorVersion >= 1) ));

    if(bIsWindowsXPorLater)
  printf("The system meets the requirements.\n");
    else printf("The system does not meet the requirements.\n");
}

However there is a better way to verify the minimum OS version required using VerifiyVersionInfo(). This function compares a set of operating system version requirements to the corresponding values for the currently running version of the system. The following code example uses VerifyVersionInfo to check the operating system version against minimal requirements (Windows XP SP2):

#include <windows.h>
BOOL Is_WinXP_SP2_or_Later () 
{
   OSVERSIONINFOEX osvi;
   DWORDLONG dwlConditionMask = 0;
   int op=VER_GREATER_EQUAL;

   // Initialize the OSVERSIONINFOEX structure.

   ZeroMemory(&osvi, sizeof(OSVERSIONINFOEX));
   osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEX);
   osvi.dwMajorVersion = 5;
   osvi.dwMinorVersion = 1;
   osvi.wServicePackMajor = 2;
   osvi.wServicePackMinor = 0;

   // Initialize the condition mask.

   VER_SET_CONDITION( dwlConditionMask, VER_MAJORVERSION, op );
   VER_SET_CONDITION( dwlConditionMask, VER_MINORVERSION, op );
   VER_SET_CONDITION( dwlConditionMask, VER_SERVICEPACKMAJOR, op );
   VER_SET_CONDITION( dwlConditionMask, VER_SERVICEPACKMINOR, op );

   // Perform the test.

   return VerifyVersionInfo(
      &osvi, 
      VER_MAJORVERSION | VER_MINORVERSION | 
      VER_SERVICEPACKMAJOR | VER_SERVICEPACKMINOR,
      dwlConditionMask);
}

In this code you can see how we use the VerifyVersion with a set of conditions to return TRUE incase we run on any OS grater than Windows XP Service Pack 2.

For .NET Framework developers, use the ==, !=, <=, <, >, >= operators of the Version object returned by Environment.OSVersion.Version:

// This code checks if the OS is at least Windows XP
  if (Environment.OSVersion.Version < new Version(5, 1))
  {
        MessageBox.Show("Windows XP or later required.",
         "Incompatible Operating System", MessageBoxButtons.OK,
                MessageBoxIcon.Error);
        return;
  }

It is highly recommended that you don’t check for version at all and try looking to work with features. It will prove valuable for the future…

Just incase you want to read more, here are some useful links

Application Compatibility Cookbook: http://msdn.microsoft.com/en-us/library/bb963893.aspx
Version Lie and Managed Applications: http://blogs.msdn.com/cjacks/archive/2007/09/10/version-lie-shims-and-managed-code-on-windows-vista.aspx

You can also download a HOL and code sample for this topic.

Developing for the Windows 7 Taskbar – Jump into Jump Lists – Part 3

Yochay Kiriaty — Thu, 02 Jul 2009 20:59:29 GMT

So far, you have seen how you can opt into the Windows 7 Taskbar Jump List experience by creating a Jump List for your application (in the Developing for the Windows 7 Taskbar – Jump into Jump Lists – Part 2 post.) You have also seen the Windows 7 default support for listing “Recent” or “Frequent” destinations as well as how to create your own custom categories. In this post, we will explore more of the Jump List features and discover how easy it is to add Tasks to your application's Jump List.

User tasks are customized tasks that get their own Tasks category. As a developer, you can set the title of the displayed task, the icon on the left and, more important, and the “application” that is launched once you activate this task. You can view user’s tasks as shortcuts to the functionality our applications can provide. As you might remember, user tasks are the verbs in our vocabulary; for example, Windows Media Player provides a “Resume last playlist” task and Sticky Notes provides a “New note” task.

A user task is usually an IShellLink object that launches any given application (your application or any other one you choose) with specific command line parameters. While you cannot categorize tasks, you can separate them using a special separator object. Here’s an example of a Jump List that uses a separator to split three tasks into a group of two plus an additional task:

So what does it take to add tasks to a Jump List? Well, not that much. Basically it is a single call to the AddUserTasks function in an interface that we are already familiar with, the ICustomDestinationList (ICustomDestinationList::AddUserTasks(IObjectArray) Method). Looking at the code, you will see a single line of code, hr = pcdl->AddUserTasks(poa);. However, as always, someone needs to create and build that poa, IObjectArray, and parameter and fill it with relevant information. Let’s review that process now.

We are going to create a collection of IShellLinks. This collection will be later cast to the required IObjectArray parameter. The following code is the beginning of that process.

IObjectCollection *poc;
HRESULT hr = CoCreateInstance(
D_EnumerableObjectCollection, NULL, CLSCTX_INPROC, IID_PPV_ARGS(&poc));
if (SUCCEEDED(hr))
{
    IShellLink * psl;
    hr = _CreateShellLink(L"/Task1", L"Task 1", &psl);
    if (SUCCEEDED(hr))
    {
        hr = poc->AddObject(psl);
        psl->Release();
    }
}

Here you can see that we used COM (again) and CoCreate and IObjectCollection, poc. Next, we call to a helper function called CreateShellLink that receives three parameters:

The first parameter is the command line argument to the task
The second parameter is the title that will be displayed
The last parameter is a pointer to IShellLink

The object is then filed according to the relevant information.

Last, we add the recently created IShellLink to the object collection. You may ask yourself where the parameter that provides the path to the executable that we plan to launch is. Well that is a good question. For simplicity, we have hard-coded that information as shown in the following code snippet:

if (SUCCEEDED(hr))
{
    hr = _CreateShellLink2(
            L"C:\\Users\\<my user>\\Documents\\new text file.txt", 
            L"NotePad", 
            &psl);

    if (SUCCEEDED(hr))
    {
        hr = poc->AddObject(psl);
        psl->Release();
    }
}

Here you can see we call to a hard-coded _CreateShellLink2 function. This receives a path to a text file as one of its parameters and, as you can see, we are launching Notepad.

Here is the code for the CreateShellLink2 function:

HRESULT _CreateShellLink2(
            PCWSTR pszArguments, PCWSTR pszTitle, 
            IShellLink **ppsl)
{
    IShellLink *psl;
    HRESULT hr = CoCreateInstance(
                    CLSID_ShellLink, 
                    NULL, 
                    CLSCTX_INPROC_SERVER, 
                    IID_PPV_ARGS(&psl));
    if (SUCCEEDED(hr))
    {
        hr = psl->SetPath(c_szNotePadExecPath);
            if (SUCCEEDED(hr))
            {
                hr = psl->SetArguments(pszArguments);
                if (SUCCEEDED(hr))
                {
                    // The title property is required on Jump List items 
                    // provided as an IShellLink instance. This value is used 
                    // as the display name in the Jump List.
                    IPropertyStore *pps;
                    hr = psl->QueryInterface(IID_PPV_ARGS(&pps));
                    if (SUCCEEDED(hr))
                    {
                        PROPVARIANT propvar;
                        hr = InitPropVariantFromString(pszTitle, &propvar);
                        if (SUCCEEDED(hr))
                        {
                            hr = pps->SetValue(PKEY_Title, propvar);
                            if (SUCCEEDED(hr))
                            {
                                hr = pps->Commit();
                                if (SUCCEEDED(hr))
                                {
                                    hr = psl->QueryInterface
                                            (IID_PPV_ARGS(ppsl));
                                }
                            }
                            PropVariantClear(&propvar);
                        }
                        pps->Release();
                    }
                }
            }
        else
        {
            hr = HRESULT_FROM_WIN32(GetLastError());
        }
        psl->Release();
    }
    return hr;
}

To start with, again we need to use COM and CoCreate to create an IShellLink COM object. A quick look at the SDK reveals that the IShellLink object has many functions. Here are few that we will use:

GetPath Gets the path and file name of a Shell link object, that is the path to the executable
GetShowCmd Gets the show command for a Shell link object, the executable name
SetArguments Sets the command-line arguments for a Shell link object
SetDescription Sets the description for a Shell link object; the description can be any application-defined string
SetIconLocation Sets the location (path and index) of the icon for a Shell link object SetPath Sets the path and file name of a Shell link object
SetWorkingDirectory Sets the name of the working directory for a Shell link object

As you can see, for each parameter we must get and set appropriate methods. There are additional parameters; take a look at the SDK - IShellLink if you want to learn more.

In the above example, we set the path to Notepad (by default in the Windows 7 installation, c:\windows\notepad.exe). We also passed a hard-coded (not a good practice) command line argument pointing to a text file in my private document folder (C:\Users\<my user>\Documents\new text file.txt.) The rest of the code sets the title property that is required on Jump List items.

We call the CreateShellLink2 and CreateShellLink a few more times to add all three shortcuts as shown in the above screen capture.

Now let’s add a separator.

To add a separator to our Task List, we need to create an IShellLink, and set the PKEY_AppUserModel_IsDestListSeparator property using the COM property variant as shown in the following code snippet:

// The Tasks category of Jump Lists supports separator items. 
// These are simply IShellLink instances that have the 
//  PKEY_AppUserModel_IsDestListSeparator property set to TRUE. 
// All other values are ignored when this property is set.
HRESULT _CreateSeparatorLink(IShellLink **ppsl)
{
    IPropertyStore *pps;
    HRESULT hr = CoCreateInstance(
                    CLSID_ShellLink, 
                    NULL, 
                    CLSCTX_INPROC_SERVER, 
                    IID_PPV_ARGS(&pps));
    if (SUCCEEDED(hr))
    {
        PROPVARIANT propvar;
        hr = InitPropVariantFromBoolean(TRUE, &propvar);
        if (SUCCEEDED(hr))
        {
            hr = pps->SetValue(PKEY_AppUserModel_IsDestListSeparator, propvar);
            if (SUCCEEDED(hr))
            {
                hr = pps->Commit();
                if (SUCCEEDED(hr))
                {
                    hr = pps->QueryInterface(IID_PPV_ARGS(ppsl));
                }
            }
            PropVariantClear(&propvar);
        }
        pps->Release();
    }
    return hr;
}

Here you can see that we used CoCreate to create an IShellLink object. Next, we set a PROPVARIANT, propvar, to true and set the IShellLink object PKEY_AppUserModel_IsDestListSeparator property to true. This will instruct the OS to render this IShellLink as a separator and not just as regular IShellLink.

OK, that was long. Now let’s look at the short version, using .NET. For that we are going to use the Windows API Code pack for the .NET Framework.

As we can expect from .NET, we get abstraction from most of the “COM code behind” that is required. The Microsoft.WindowsAPICodePack.Shell.Taskbar namespace includes a JumpListLink object that extends the ShellLink object and implements IJumpListTasks.

The JumpList class contains the UserTasks collection of IJumpListTasks to which you can simple add new JumpListLink objects as shown in the following code snippet:

// Path to Windows system folder
string systemFolder = 
        Environment.GetFolderPath(Environment.SpecialFolder.System);

jumpList.UserTasks.Add(new JumpListLink
{
    Title = "Open Notepad",
    Path = Path.Combine(systemFolder, "notepad.exe"),
    IconReference = new IconReference(
(systemFolder, "notepad.exe"), 0)
});

Using the C# 3.0 syntax, we initialize a new JumpListLink object and add it to the UserTasks collection. As you can see, the managed code JumpListLink has very similar properties to the native one (which makes perfect sense). We also added an icon to the Notepad shortcut to the above code, but didn't provide any command line parameters.

You want to add a separator? Well, that is also very easy: just add a JumpListSeperator object to the UserTasks collection.

jumpList.UserTasks.Add(new JumpListSeparator());

Please note that, as always, when working with the Windows Code pack API Taskbar, you have to call the “refresh” function in order to commit the changes, as we explained in the previous post.

Taskbar.JumpList.RefreshTaskbarList();

After the refresh, the Jump List looks as follows:

I’ve compiled a version of a native example from the Windows 7 SDK. You can get a copy of that code from here

You can download the Windows API Code Pack that includes the manage code example we used in this post.

This concludes our Jump List discussion. Our next Taskbar topic is Icon Overlay.

Developing for the Windows 7 Taskbar – Jump into Jump Lists – Part 2

Yochay Kiriaty — Fri, 26 Jun 2009 01:19:07 GMT

This is the second post about the Taskbar Jump List in a series of Windows 7 Taskbar posts. In the previous post, Developing for the Windows 7 Taskbar – Jump into Jump Lists – Part 1, we introduced the elements that comprise the Taskbar Jump Lists: the destination (also referred to as “nouns”) and the Tasks (also referred to as “verbs”). As developer, you have a large amount of control over these elements. In this post, we walk through the different APIs that you can use when programming the Taskbar Jump Lists.

Before we begin, there is one very important thing you need to know. “Items” in the Recent category, or in any other category (any destination), must have a registered file handler for your application in the registry. This doesn’t mean that your application must be the default handler for that specific file type, it just means that your application must have a registered handler for all the files that you want to be visible in the Jump List. Therefore, “items” can only be files. Remember, by clicking on one of the items in the Jump List, the OS executes the command associated with that file as it relates to your application. When you register a file handler, you also specify the application that handles this file, and you define how to pass the input parameter for the application. Another important note to remember: All the items (files) have to be local – that is, on the local hard drive, and accessible to your application. Therefore, we can say that each and every item among the Jump List destinations is an accessible, local file, with a file handler registered to your application.

As we explain in the following section, once you have registered your file handlers, the OS actually helps you keep track of all your files. We will cover file handler registration in the next post.

Step 1 – Use the Out-of-the-Box Windows Experience and Default Behavior

By default, a Jump List contains a Recent category that is populated automatically for file-based applications through the SHAddToRecentDocs function. This function adds the used “item” (file) to the Shell's list of recently used documents. In addition to updating its list of recent documents, the Shell adds a shortcut to the user's Recent directory. The Windows 7 Taskbar uses that list and the Recent directory to populate the list of recent items in the Jump Lists.

Windows can also do the work for you if your application's file type is registered. Anytime you double click on a file type with a registered handler, before Windows launches your application it automatically calls SHAddToRecentDocs on your application's behalf. This inserts the item in the Windows Recent list and eventually into the Jump List Recent Category. The same automatic behavior occurs when using the Windows Common File Dialog (CFD) to open files through our applications. Therefore, this is another good reason to use the CFD introduced in the Windows Vista timeframe, and it also plays a vital role regarding libraries, as we explained in the Light Up with Windows 7 Libraries post.

Both of the above cases exploit default Windows behavior in cases where you have a registered handler and an Application ID by which the files are associated with Recent and Frequent lists. In both cases, Windows automatically inserts the items into the Jump Lists unless you specifically remove this functionality by using the COM API. Obviously, users also have the option to remove any items from their Jump Lists. By explicitly removing an item from the Jump List, you insert it into the Removed Items List, which we will discuss below.

Step 2 – Create Your Own Category

If the default Recent or Frequent categories do not meet your application's needs, it is time to create your own custom category. In order to do so, you need to use the ICustomDestinationList interface to create a custom Destination List.

The ICustomDestinationList exposes methods that allow an application to provide a custom Jump List, including destinations and tasks, for display in the Taskbar. Here are the methods that we are using for the example below:

AppendCategory Defines a custom category and the destinations that it contains for inclusion in a custom Jump List
AppendKnownCategory Specifies that the Frequent or Recent category should be included in the Jump List
BeginList Initiates a building session for a custom Jump List
CommitList Declares that the Jump List initiated by a call to BeginList is complete and ready for display

The following code snippet shows how to create a new custom list called “Custom Lists” and appends a few items to it:

void CreateJumpList()
{    
    ICustomDestinationList *pcdl;
    HRESULT hr = CoCreateInstance(
                    CLSID_DestinationList, 
                    NULL, 
                    CLSCTX_INPROC_SERVER, 
                    IID_PPV_ARGS(&pcdl));
    if (SUCCEEDED(hr))
    {
        //important to setup App Id for the Jump List
        hr = pcdl->SetAppID(c_szAppID);
        if (SUCCEEDED(hr))
        {
            UINT uMaxSlots;
            IObjectArray *poaRemoved;
            hr = pcdl->BeginList(
                            &uMaxSlots, 
                            IID_PPV_ARGS(&poaRemoved));
            if (SUCCEEDED(hr))
            {
                hr = _AddCategoryToList(pcdl, poaRemoved);
                if (SUCCEEDED(hr))
                {
                    pcdl->CommitList();
                }
                poaRemoved->Release();
            }
        }
    }
}

Here you see that we started with a standard COM initialization call. We call CoCreateInstance to initialize the ICustomDestinationList object (this is the joy of working with COM….). Next, we set the Application ID in order to allow you to start populating items to the list.

The BeginList function initiated the build session for the custom Jump List. This function returns the maximum number of items that can fit in a given Jump List; the default is 10. You may note the Remove item parameter, IObjectArray *poaRemoved, that the BeginList() returned as an out parameter. This holds any specific items that the user removed from the Jump List in his current session. We discuss the Removed Items List later in this post.

Next we called a helper function, _AddCategoryToList(), to do the actual work of adding items into the custom category.

// This is the helper function that actually appends the items to a collection 
// object HRESULT _AddCategoryToList(ICustomDestinationList *pcdl, 
// IObjectArray *poaRemoved)
{
    IObjectCollection *poc;
    HRESULT hr = CoCreateInstance
                    (CLSID_EnumerableObjectCollection, 
                    NULL, 
                    CLSCTX_INPROC_SERVER, 
                    IID_PPV_ARGS(&poc));
    if (SUCCEEDED(hr))
    {
        for (UINT i = 0; i < ARRAYSIZE(c_rgpszFiles); i++)
        {
            IShellItem *psi;
            if (SUCCEEDED(SHCreateItemInKnownFolder(
                                FOLDERID_Documents, 
                                KF_FLAG_DEFAULT, 
                                c_rgpszFiles[i], 
                                IID_PPV_ARGS(&psi)))
                )
            {
                if(!_IsItemInArray(psi, poaRemoved))
                {
                    poc->AddObject(psi);
                }

                psi->Release();
            }
        }

        IObjectArray *poa;
        hr = poc->QueryInterface(IID_PPV_ARGS(&poa));
        if (SUCCEEDED(hr))
        {
            pcdl->AppendCategory(L"Custom category", poa);
            poa->Release();
        }
        poc->Release();
    }
    return hr;
}

Another new interface that we use is the IObjectCollection that represents a collection of objects that support IUnknown. To this collection we add IShellItems. Each item (file) that we added to the Jump List is of an IShellItem type. In the above code, we created a Shell item object for a single file that exists inside a known folder, Documents. However, before we actually added the new item to the collection, we needed to determine if the user had already removed it. If the user explicitly removed an item from the Jump List, that item will be in the Removed Items List (again associated with the AppID), and, as developers, we need to respect the user's requests and avoid adding that item to the Jump List. We already have the list of removed items, IObjectArray *poaRemoved, that we got when we called the BeginList(…) function when we initiated creation of a new list.

At this stage, you have a collection of Shell items that the user expects to see in the Jump List. Next we added that collection to the ICustomDestinationList object and created a new category named “Custom category”, pcdl->AppendCategory (L"Custom category", poa);.

So now you have successfully created a new category in the Taskbar called “Custom category” and populated it with four items. However, our work is not done yet. The final step in the CreateJumpList function is to call CommitList() to end the “transaction” that began with calling BeginList(). Only after our call to CommitList() are the new category and new items displayed. Calling CommitList() causes the stored list of removed items to be cleared and a new Removed Items List to begin. The ICustomDestinationList interface provides a "transactional base" API.

In order to ensure a positive end user experience, make sure that a safe copy of the new repopulated list is complete and ready for use, and that the only operation the Taskbar must perform is to switch the pointer to the new list. The end result looks like:

Using the Windows API Code Pack we can write the same application using managed code.

Once we are sure that we are using the same AppID with all the Taskbar elements, we can create an instance of the Taskbar Jump List for the button that we are working on, as shown in the following code snippet. This code snippet is part of the CTOR of the main application window:

// Set the application specific id
Taskbar.AppId = appId;
// Retrieve the taskbar jump list
jumpList = Taskbar.JumpList;
category1 = new CustomCategory("Custom Category 1");
category2 = new CustomCategory("Custom Category 2");
// Add custom categories
jumpList.CustomCategories.Add(category1);
jumpList.CustomCategories.Add(category2);
// Default values for jump lists
comboBoxKnownCategoryType.SelectedItem = "Recent";

Here you can see that we set the AppID using the AppId property and created an instance of the Taskbar Jump List using the Taskbar.JumpList static property. We also create two categories, named Custom Category 1 and Custom Category 2. Next, we add these categories to the Jump List custom categories container. Last we set the Known category of this Taskbar Jump List to Recent. This will automatically get populated as described above.

After we set up the custom category, it is time to put some content in it. To do so, we just need to call the Add function to add a JumpListItem to the JumpListCollection. The JumpListItemCollection is a generic collection (of<IJumpListItem>) holding IJumpListItem items. IJumpListItem item is basically some sort of wrapper for the native IShellItem.

// Specify path for shell item
string path = String.Format("{0}\\test{1}.txt",
                            executableFolder,
                            category1.JumpListItems.Count);
// Add shell item to custom category
category1.JumpListItems.Add(new JumpListItem(path));

First, we need to construct a path to the file we want to include in the Jump List. Please remember that we can call the Add function only if this file is local and accessible to your user. The above code (along with a few other methods that we will describe in future posts), results in a Taskbar dialog that looks like:

Finally, we need to call the Taskbar.JumpList.RefreshTaskbarList() Function. As with the native Jump List implementation, we need to “commit” the changes made to the Jump List. A closer look at this Refresh function (you have access to it in the Code Pack API) shows a call to the AppendCustomCategories function that appends any custom categories to the Taskbar button Jump List. Within this function, you can find a managed code implementation of the native code shown above. It includes a call to the AppendCateogry function that is a wrapper for the native AppendCategory function above.

IObjectCollection categoryContent =
    (IObjectCollection)new CEnumerableObjectCollection();

// Add each link's shell representation to the object array
foreach (IJumpListItem link in category.JumpListItems)
    categoryContent.AddObject(link.GetShellRepresentation());

// Add current category to destination list
HRESULT hr = customDestinationList.AppendCategory(
    category.Name,
    (IObjectArray)categoryContent);

As you can see, it is easy to opt into the Windows 7 Taskbar functionality. Windows automatically performs most of the work for you and, if you do need to create your own category, that is also very easy.

In the next post we will describe how you can add new Tasks to the Jump List and how to register a file handler.

Developing for the Windows 7 Taskbar – Application ID – Part 2

Yochay Kiriaty — Fri, 19 Jun 2009 17:06:55 GMT

[June 19th - I added a code sample and new screenshots.]

In response to some of the comments I included a link to the download and new screenshots to show the effect of changing Application ID in run time. And Just to make sure we are all on the same page here are two images to illustrate the power of AppID. You can clearly see that the same application (with the same original application ID) can have two different Taskbar buttons. You can also download the code for this application.

Just a note as response to one of the comments. Yes you can place a different Taskbar button between to windows with different AppID!

download the code for this application

You can find the managed code Taskbar object in the Windows API Code pack project.

Developing for the Windows 7 Taskbar – Application ID

Yochay Kiriaty — Thu, 18 Jun 2009 17:18:35 GMT

This is the first post in a new Windows 7 Taskbar series. One of the first Windows 7 changes that developers should pay attention to is the new Windows Taskbar. We all need to understand the functionality this feature introduces so that we can ensure that our applications work well with the Taskbar, resulting in an enhanced experience for our end users.

I assume that by now you are familiar with the basic functionality that Windows 7 Taskbar offers and the reasons behind the change we made from previous taskbar versions. If you are not familiar with and haven’t seen any demonstrations of the Windows 7 Taskbar, please watch the Windows 7 Taskbar Overview webcast on Channel 9. There are also great posts on the E7 blog like The Windows 7 Taskbar about some of the reasons we introduced the new Taskbar and desktop experience in Windows 7. I do encourage you to read these posts and watch the video so that you have some context for the technical material we are going to cover here.

The new Taskbar is probably the most noticeable change to Windows 7 when you first log on. The Windows 7 Taskbar is an application-launching and window-switching mechanism that consolidates the functions of previous Windows Desktop mechanisms, such as Quick Launch, Recent Documents, Notification Area icons, desktop shortcuts, and running application windows. Windows 7 Taskbar offers features like Jump Lists, Preview Handler, and Overlay Icons. But before we start diving into the various Windows 7 Taskbar features, let’s lay the basic foundation to our discussion and define some Windows 7 taskbar terminology.

The basic component is the Taskbar button. The Taskbar button is represented as an icon displayed on the Taskbar. As you can see in the following image, the Taskbar contains several buttons. You can tell what their status is by how they are displayed.

For example, the Media Player button has no frame or border, but simply sits directly on the Taskbar. This indicates that Media Player is not running. But it is pinned to the Taskbar, and will stay on the Taskbar unless we unpin it. A transparent frame that lets most of the color of the underlying Taskbar through the Windows Explorer button. This indicates that the app is running but is not the active application. The Visual Studio icon has a more opaque rectangular frame underlying its icon indicating that the user is actively using this app. You will also notice that Word has a “stack” of icons representing that multiple instances of Word or multiple Windows are grouped under the same Taskbar button. It is very important to understand the logic that underlies the creation, assignment, and grouping of Taskbar buttons.

A very large number of applications that run on Windows 7 (for example, Office Word 2007 and Visual Studio 2008), were not designed to work with the Windows 7 Taskbar, so how is it that they can play ball with the Taskbar, group multiple instances, and even take advantage of Word Jump Lists? Basically, a behind-the-scenes Application ID (AppID) is automatically computed and assigned to an application once you launch it. Every running application has an AppID assigned to it, either automatically computed for the app by Windows, or set by the app itself. Guess what? It is not a GUID; it is just a string (with a maximum of 128 characters), that either you provide or is being computed by the OS. All windows and applications, including Jump Lists, which have the same AppID are grouped under the same Taskbar button. Therefore, it is important to understand that every component (process, shortcut, window, Taskbar button, and document type – that is, registered file type handler) of your application has the AppID associated with it.

You may ask, "Where do AppIDs come from?" As mentioned before, the OS generates Application IDs for your application using a very simple, yet important to understand heuristic. Since in Windows 7 you can assign AppIDs to individual windows, the OS tries to extrapolate the AppID from a window. Applications usually display at least one window that the OS can query for its AppID. However, most existing apps do not have an AppID attached to each window (or, for that matter, any AppID at all), and therefore the OS falls back to the process to which the window belongs for the AppID. Each process has several properties that the OS can check, like the executable of the process. But even then, the process may not provide a granular enough separation. Different shortcuts may provide different start up command line parameters to the same executable and launch different applications (imagine a “launcher” application) that will be grouped under the same Taskbar button. In such cases, the OS has the ability to look into the specific shortcut that launched the application, to find the executable, the command line parameters, and so on. Note that if you have a register file, this registration points to an application that gets launched once you double click that file. Again, this is another way to calculate the AppID. The following image illustrates this automatic computation process.

If you are interested in really understanding the internals of the Windows 7 taskbar, a great Channel 9 video describes its underlying architecture. Watch the Rob Jarrett and Ben Bets Windows 7 Taskbar - Behind the Scenes video and, specifically for the Application ID overview, watch Jump into the Windows 7 Taskbar Jump Lists (between 29:30 and 34:40).

While the OS can compute AppIDs for you, you may want to have greater control over the AppID for a given application or even an individual window in your application. Assume that you have an application that hosts (runs) another application (like what happens when you debug an application using Visual Studio). Or you have several different applications or processes that you wish to group under the same Taskbar button. The Taskbar API offers you ways to control the Application ID per application or per window. IN ANY CASE, if you are writing a new application that targets Windows 7, we highly recommend that you provide your own application ID, as we will describe below.

OK, let’s examine the API that allows you to control the AppID associations of your application.

If you want to have a separate Taskbar button for each process (including all windows owned by that process), you can set an explicit AppID for the entire process that affects all windows within the process that do not have their own explicit AppID. Setting the explicit process AppID is very easy. All it takes is a single call to the SetCurrentProcessExplicitAppUserModelID function as shown in the following code snippet:

SetCurrentProcessExplicitAppUserModelID(c_rgszAppID[0]);

Where c_rgszAppID[0] is a pointer to a string. You should note that according to the SDK documentation, “This method must be called during an application's initial startup routine before the application presents any user interface (UI) or makes any manipulation of its Jump Lists.”

In managed code, from the latest Windows API Code Pack Library, you can use the AppID property that is part of the Taskbar object, which you can find in the Microsoft.WindowsAPICodePack.Shell.Taskbar namespace. Using that property you can set and get the application ID of a given application.

Setting the AppID for a window is a bit more complicated (but only a bit). It requires calling the SHGetPropertyStoreForWindow function and then manipulating the resulting IPropertyStore object to retrieve the requested property as shown in the following code snippet:

void SetAppID(HWND hWnd, int iAppID)
{
    IPropertyStore *pps;
    HRESULT hr = SHGetPropertyStoreForWindow(hWnd, IID_PPV_ARGS(&pps));
    if (SUCCEEDED(hr))
    {
        PROPVARIANT pv;
        if (iAppID >= 0)
        {
            hr = InitPropVariantFromString(c_rgszAppID[iAppID], &pv);
        }
        else
        {
            PropVariantInit(&pv);
        }
        if (SUCCEEDED(hr))
        {
            hr = pps->SetValue(PKEY_AppUserModel_ID, pv);
            PropVariantClear(&pv);
        }
        pps->Release();
    }
}

Here you can see how we extract the current windows property store by calling SHGetPropertyStoreForWindow, passing hWnd as refrence to the window. Next we initiate, InitPropVariantFromString(c_rgszAppID[iAppID], &pv), a property variant with a string that represents the AppID for that window. Finally, we set the value of the new property store to the window.

Unfortunately, the current Windows API Code pack doesn’t support setting specific application IDs per window, although all you need to do is add the following function to the Taskbar.cs file:

private static void SetWindowAppId(string appId)
{
    Microsoft.WindowsAPICodePack.Shell.ShellNativeMethods.SetWindowAppId
        (OwnerHandle, "name here");
}

Since the Windows API Code Pack provides the source code, you can actually check the specific implementation of SetWindowAppId function and see for yourself that it is very similar to the SetAppID example above. Note you don’t have to use the full qualified assembly name “Microsoft.WindowsAPICodePack.Shell’, but I did to help you navigate the Windows API Code Pack hierarchy.

By the way, the window AppID is dynamic, so it’s entirely possible for a window to show up as part of one Taskbar button and then change its AppID so that it appears on an entirely different Taskbar button. This has interesting effects. For example, the Jump List is attached to a Taskbar button (with a specific AppID), so the same window might show a different Jump List when it is reattached to an entirely different Taskbar button. This potentially can confuse users, so the recommended practice is to set the window AppID and stick to it, using the same process for determining the AppID every time the window displays.

You can find the managed code Taskbar object in the Windows API Code pack project.

[Sasha Goldshtein helped write this post, and you can find his original posting here].

Windows 7 RC Training Kit for Developers

Yochay Kiriaty — Fri, 12 Jun 2009 17:09:38 GMT

This week we released the Windows 7 RC Training Kit for Developers as part of our ongoing effort to give you, all the Windows developers out there, and valuable content to work with while making your application shine on Windows 7. This version of the training kit includes 10 presentations and 8 Hands-On-Labs (HOL), covering most of the Windows 7 light-up features as well as application compatibility topics. Note that the HOL gives you the opportunity to get firsthand experience in programming key Windows 7 Light-Up features, such as the Taskbar, Libraries, Multi-Touch, Sensors and Location, Graphics, Ribbon, Trigger Start Services, Instrumentation and Event Tracing for Windows (ETW). We also provide a brief Application Compatibility overview.

This is an “early preview” to the full set of Windows 7 Training for Developers that will be released shortly after RTM. You can download the training kit and get started, but make sure you have a Windows 7 RC machine to work with, and install Visual Studio 2008 SP 1 and Windows 7 RC SDK as some of the native applications requires libraries from the SDK.

Modules:

Taskbar

The Windows 7 Taskbar is a differentiating opportunity that allows applications to shine on the Windows 7 platform. The new Taskbar streamlines many end-user scenarios including launching applications, switching between running applications and windows within a single application, managing recent/frequent user destinations, accessing common application tasks, reporting progress and status notifications through the taskbar button, and controlling the application without leaving the taskbar thumbnail. The Taskbar is the end user’s primary point-of-contact for initiating and managing activities; as such, the integration of the new taskbar features into modern Windows 7 applications is a critically important goal. This module talks about the different aspects and APIs associated with programming the Windows 7 Taskbar.

Libraries

Libraries are the new entry points to user data. Libraries are a natural evolution of the 'My Documents' folder concept that blends into the Windows Explorer user experience. A library is a common store of user defined locations that applications can leverage to manage user content as their part of the user experience. Because libraries are not file system locations, you will need to update some applications to work with them like folders. This module explains the basic concepts underlying Windows 7 Libraries, including how to make your application library-aware, how to work with libraries as though they were file system folders, and how to leverage the library system.

Multi-Touch

Windows 7 features improved touch and gesture support that empowers developers to quickly and easily create unique application experiences that go beyond simple mouse pointing, clicking, and dragging. The new multi-touch APIs support rich gestures, such as pan, zoom, and rotate. The Windows 7 Multi-Touch Platform also provides raw touch data inputs and advance manipulation and interties. This module explains the basics of Windows 7 multi-touch and its APIs.

Sensor and Location Platform

Windows 7 has changed how developers use sensors. The Sensor and Location Platform includes native support for sensors, expanded by a new development platform for working with sensors, including location sensors such as GPS devices. Built on the Sensor platform, the new Windows Location APIs enable application developers to access the user’s physical location information. This module explains what the Sensor and Location Platform is and how to work with its APIs.

Ribbon

Windows 7 incorporates the Ribbon interface introduced in Office 2007 throughout the operating system, enabling improved user interface development on the platform. This means that developers can eliminate much of the drudgery of Win32 UI development and deliver a rich, graphical, animated, and highly familiar user interfaces by using a markup-based UI and a small, high-performance, native code runtime. The Ribbon control helps developers improve usability by exposing your application's most frequently accessed features directly to end users. The Ribbon makes it easier for end users to find and use application features because functionality is more visible, resulting in greater productivity. This module shows the different aspects of the Windows 7 Ribbon and provides a guide on how to incorporate the Windows 7 Ribbon into existing applications.

Background Processes, Services, and Tasks

Services and background processes have tremendous influence on the overall performance of the system, and therefore the applications. If we could cut down on the total number of services, we could reduce the total power consumption and increase the overall stability of the system. The Windows 7 Service Control Manager has been extended so that a service can be automatically started and stopped when a specific system event, or trigger, occurs on the system. Trigger-start capabilities remove the need for services to start up automatically at computer startup and then poll or wait for an event to occur. This module explains the different options available to developers for configuring and using trigger-start services.

Windows 7 Instrumentation and Performance

Windows 7 includes new Event Tracing for Windows (ETW) capabilities that developers can take advantage of during the development process to optimize application performance. Instrumentation has always been part of Windows, but Windows 7 includes new ETW underlying technology that makes the task of including instrumentation in your application a whole lot easier. This module describes the different options for using instrumentation in Windows, including the new ETW.

Windows 7 Application Compatibility

Windows 7 is built on top of Windows Vista, which means if your application does not work or if it has some issues when running on Windows Vista, most probably it will have similar issues running on Windows 7. This module is a short overview of the top major issues regarding Windows 7 compatibility, including Data Redirection, Service Isolation, Version Checking, and High DPI.

Windows 7 Libraries – Managed Code

Yochay Kiriaty — Tue, 09 Jun 2009 21:53:49 GMT

We are wrapping up our comprehensive drilldown into the Windows 7 Libraries API and architecture with one final post about the managed API for working with Windows 7 Libraries. Previously we talked about: Understanding Windows 7 Libraries, Libraries Under the Hood, Light Up with Windows 7 Libraries, Consuming the Contents of Windows 7 Libraries, Stay in Sync with Windows 7 Libraries, Windows 7 Libraries Helpers

In this post we focus on the managed API for working with Windows 7 Libraries. The Windows API Code Pack for the Microsoft .NET Framework Library (Windows API Code Pack) provides a .NET interface into the Windows native API, thereby enabling the 7 key Windows Light-Up features as well as tapping into more advanced shell integration, as we described in the Windows 7 Managed Code APIs post. You can download the Windows Code Pack API

The Windows API Code Pack has a very good managed interface to the Windows Shell, and particularly to the Windows 7 Libraries API. ShellLibrary (a part of the Microsoft.WindowsAPICodePack.Shell dll that you need to add as a reference to your .NET application in order to work with Windows 7 libraries), is the only object that represents Libraries. The image to the left displays the ShellLibrary class.

Now you can start working with Libraries. First, you need to create a Library object using one of the four available constructors. You might want to use the constructor that takes a Known Folder as a parameter. This is to allow developers easy maintenance while developing. Note, however, that most constructors receive an overwrite Boolean. Make sure you don’t overwrite your own existing Documents library (or any other library), since the creation of a new

ShellLibrary object saves the library’s XML detention file to the Library’s Known Folder, as we described in Libraries Under the Hood. The following single line of code creates a new ShellLibrary object, thus creating a new Library.

ShellLibrary library = new ShellLibrary(“new test lib1”, true);

If you don’t have to create a new library, you can load an existing library to obtain the required ShellLibrary object. Keep in mind that all load functions are static functions that don’t require an already existing ShellLibrary instance. Every load function’s last parameter is a isReadOnly Boolean that you may use when you just need to read a library's contents and without changing it. For example, an application that backs up all your libraries has no need to change the library. The following code snippet is all that is needed to load an existing library:

ShellLibrary library = ShellLibrary.Load("My Pictures", true);

OK, you have a ShellLibrary object -- what can you do with it? Well there are few things ways to have fun with libraries. First, you can add or remove specific folders from the library. Remember that libraries are just abstract containers and don’t really hold files, but just point to the actually folders that do hold the files, as explained in the Understanding Windows 7 Libraries post. To add a folder just call the Add function, in a similar way, call the remove function to remove a folder. You can add or remove folders by either using a specific path represented by a string or using a FileSystemFolder object as shown in the following code snippet:

public void Add(FileSystemFolder item);
public void Add(string folderPath);
public bool Remove(FileSystemFolder item);
public bool Remove(string folderPath);

Besides managing folders in your library, you can also set the default save location of the library by using the DefaultSaveFolder property. Assuming the library is a ShellLibrary object, the following code snippet returns the default save location of the Library:

String dsfStr = library.DefaultSaveFolder

Note that when setting the default save folder, you need to provide a valid system folder for which you have write and read permission. If this folder is not already part of the library, it will be added to the library and will become the default save location. As a developer, you can also add unsupported folder locations that are not indexed and can’t be indexed.

Another very cool feature is control of the library icon. This one of those features that end users don’t have access to, and it is SO easy to use, as shown in the following code snippet:

library.IconResourceId = new IconReference(icon);

You will have to obtain an IconReference object, but after doing so you get to change the library’s Icon and set your own special icons. This is a really fun feature to play with, as you can see from the following picture:

Another important feature of the ShellLibrary object is the capability to list all the items and folders in a library. The ShellLibrary object implements the IList<FileSystemFolder> interface. This supports enumeration of the folders in the library by calling the GetEnumerator function or by using the foreach statement as shown in the following code snippet that prints the folder’s name and default save location:

foreach (ShellFolder folder in library)
{
    Console.WriteLine(
            "\t\t{0} {1}", 
            folder.Name, 
            defaultSaveFolder == folder.Name ? "*" : "")
}

You can control the library type by using the LibraryType property, and you can elect to pin the library listing to the left navigation pane of Windows Explorer using the IsPinnedToNavigationPane property.

Last, I want to talk about displaying the Library Manager window. It is important to display this window if you wish to create a consistent user experience for managing libraries in Windows Explorer and your application. Since displaying the Library Manager window displays a new dialog window in an existing application, you need to take into account the technology used by the application. The function ShowManageLibraryUI can receive either a Win32 window handle (whnd) that will work great with WinForms, or a WPF windows object for WPF applications.

library.ShowManageLibraryUI(IntPtr.Zero, “title of dialog”, "help text…", true);

The last thing we are going to talk about is deleting a library. The ShellLibrary object doesn’t have a self destruct mechanism and therefore you can’t delete a library using the ShellLibrary object. To delete a library you need to delete the library XML definition file. The code snippet below gets a string representing the library name that correlates to same library definition file. See Understanding Windows 7 Libraries for more information.

public static void DeleteLibrary(string name)
{
    string librariesPath = Path.Combine(
        Environment.GetFolderPath(
            Environment.SpecialFolder.ApplicationData),
            ShellLibrary.LibrariesKnownFolder.RelativePath);

    string libraryPath = Path.Combine(librariesPath, name);
    string libraryFullPath = Path.ChangeExtension(libraryPath, "library-ms");

    File.Delete(libraryFullPath);
}

As you can see, we first use a combination of the Environment.SpecialFolder.ApplicationData and the ShellLibrary ShellLibrary.LibrariesKnownFolder.RelativePath to assemble the folder in which all the libraries definition files are stored. Then we append the library-ms file extension, and finally we delete the file. Remember, by deleting the file, we delete the library; so again, be careful not to delete any important libraries.

We have covered all the important functionality of the Libraries managed code API and, together with the previous posts; you now should have a very good sense of how Windows 7 Libraries work and how to use them in your applications.

In addition, you can get first-hand coding experience with Windows 7 by going through the Windows 7 Libraries Hands-On-Lab (HOL) that is part of the Windows 7 RC Training Kit for Developers. The Library HOL includes the code used in this post, so go ahead and download the training kit.

New Windows 7 Videos on Channel 9

Yochay Kiriaty — Thu, 07 May 2009 19:58:00 GMT

Note – this post will be updated from time to time, to include new content. Last update: June 13^th(New Sensor, Location and Windows Animation videos)

During the past couple of months, we have being working on Windows 7 videos featuring the new technologies in Windows 7. We’ve also created a Windows Topic area on Channel 9 to make it easier for you to find specific Windows 7 content. This topic area includes all the Windows 7 videos since PDC08, which was when we first introduced Windows 7. Since PDC, we have created enough content about specific Windows 7 features that it makes sense to group these topics into categories so they are easier for potential viewers to find. We hope these videos will help you to get started programming for Windows 7. Here is one new of the many videos we have for you on Channel 9.

Here is the list of category topics and their associated videos:

Kernel and Internals

Inside Windows 7 - User Mode Scheduler

Inside Windows 7 - Service Control Manager

Mark Russinovich – Inside Windows 7

New NUMA Support with Windows 7

Windows 7: Best Practices for Developing for Windows Standard User

Taskbar

Windows 7 New Taskbar - An Overview

Taskbar - Behind the Scenes

Designing the Windows 7 Taskbar

Jump into the Windows 7 Taskbar Jump Lists

Windows 7 Taskbar Beta Feedback

Windows 7 Taskbar Advanced Topics

Graphics

Windows 7 Graphics Architecture Overview – Part 1

Windows 7 Graphics Architecture Overview – Part 2

Windows 7 Graphics Architecture Overview – Part 3

Windows 7 Graphics - WIC

Windows 7 Graphics - High DPI

Multi-Touch

Using Touch in Line-of-Business Applications

Programming Windows 7 Multi Touch – Part 1

Programming Windows 7 Multi Touch - Part 2

Sensor and Location

Windows 7: The Sensor and Location Platform - Building Context Aware Applications

Windows 7 Sensor and Location Platform Overview

Windows 7 Location Platform Overview

Windows 7 Sensor and Location Platform – Deep Dive

Ribbon

A Lap around Windows 7 Ribbon

Ribbon Markup Overview

Ribbon Deep Dive

Windows Animation Manager

Windows Animation Overview

Inside Windows 7: Animation Manager Deep Dive and Tutorial

Libraries and Federated Search

Windows 7: Find and Organize Part 1 - The User Experience

Windows 7: Find and Organize Part 2 - Building Federated Search applications

Windows 7: Empower users to find, visualize and organize their data with Libraries and the Explorer

PowerShell

PowerShell V2 Functions

PowerShell V2 Sessions and Debugging

PowerShell V2 Modules

General

The story behind a few of the new Windows 7 wallpapers

Windows 7 RC Features Slideshow on eWeek

Consuming the Contents of Windows 7 Libraries

Yochay Kiriaty — Thu, 23 Apr 2009 23:16:28 GMT

This is the fifth post about Windows 7 Libraries. By now, you should be familiar with Windows 7 Libraries (Understanding Windows 7 Libraries) and understand the internal structure of Libraries and how they integrate into the Windows Shell (Libraries Under the Hood). In the previous post, we explained the different programming models and ways to work with Windows 7 Libraries. In this post, we focus on the Windows Shell Programming model that you can use to access libraries even without using the latest IShellLibrray APIs.

In the previous post, we talked about the importance of using the right version of the Common File Dialog (CFD) to enable the complete Libraries user experience in Windows 7. In this post we will further explorer the opportunities to let users select and consume Libraries as if they where regular folders. Let’s imagine the case of a slideshow application that presents users' pictures. By using the Pictures Library, users are essentially telling the system that their important pictures are stored in the Pictures Library, and therefore, our slideshow application can simply be pointed directly to the Pictures Library and show the users' entire pictures collections. Furthermore, from developers’ point of view, using the Libraries system can eliminate the need to maintain a separate configuration file or database, since developers can rely on the Libraries System. But before we dive into the Shell Libraries programming APIs, we need to understand the few concepts regarding the Shell Programming Model.

Shell Programming Model

IShellItem, commonly referred to as an item, is the currency of the Shell UI model and its programming model. Items are individual, self-contained content sources. Take for example the above-mentioned Common File Dialogs. Quite few of the interface methods used for controlling the file dialogs use Shell items to refer to folders instead of file system paths. This is important because the CFD can communicate information about both file system folders and other virtual folders that you find in the shell, such as the Control Panel or the Computer folder.
IShellFolder interface represents shell folder objects from the shell namespace. Using IShellFolder you can traverse through the contents of a folder, to retrieve the display name of an item in a folder, parse a display name relative to the folder, and obtain an item ID list.
IShellLink interface represents a link, usually to a file, folder, or an executable.
IPropertyStore interface can be used to manage the property store associated with various shell objects.
IShellLibrary interface represents a Windows 7 Library, which we will cover in depth in future posts.

Now that we have defined the different players in the Shell Programming Model, we can see how Libraries fit into this model. Since Libraries are not file system locations, you cannot use file system-specific APIs. Therefore, you have two main options to consume library contents - the Shell Programming Model and the new IShellLibrary API.

Using the Shell Programming Model

You can use the IShellItem and IShellFolder interfaces and a bunch of helper functions to enumerate the contents of Libraries just as if they were regular folders. This means that applications can consume Libraries contents without using the new Libraries API and with very little change to their existing code.

The following code snippet shows how to use the IShellFolder interface to enumerate through the entire contents of the Picture library.

IShellItem *psi;
HRESULT hr =  SHGetKnownFolderItem(
            FOLDERID_PicturesLibrary, 
            KF_FLAG_CREATE, 
            NULL, 
            IID_PPV_ARGS(&psi));
if(SUCCEEDED(hr))
{
    IShellFolder *psf;
    hr = psi->BindToHandler(NULL, BHID_SFObject, IID_PPV_ARGS(&psf));
    if(SUCCEEDED(hr))
    {
        IEnumIDList *penumIDList;
        psf->EnumObjects(NULL, 
                        SHCONTF_FOLDERS  | SHCONTF_NONFOLDERS, 
                        IID_PPV_ARGS(&penumIDList));
        //use penumIDList to enumerate the content of the folder
    }
}

Here you can see that by using the helper function SHGetKnownFolderItem, we can retrieve the correct library location by passing the FOLDERID_PicturesLibrary, which is a GUID representing the known folder, in our case the Pictures Library.The SHGetKnownFolderItem is a Shell Helper function and is part of a larger group of helper functions that can be found in the shlobj.h header file in the Windows 7 SDK. A successful call will fill the IShellItem *psi with the correct information about the Library represented as a Shell Item. From this point the rest of the code is standard Windows Shell programming, where we use the BindToHandler to bind the previously obtained Shell Item to a Shell folder. Next, we enumerate through the different items in the Shell folder, which in case of a library can be either files or folders. Note the SHCONTF_FOLDERS | SHCONTF_NONFOLDERS flags that we are passing, this is telling the shell folder that we want to return all of the files and folders in a library. We could pass SHCONTF_NAVIGATION_ENUM to get the library locations instead of the library

Using the New IShellLibrary API

You can achieve the same functionality as the code above by using the new Windows 7 IShellLibrary API as shown by the next code snippet.

IShellLibrary *pslLibrary;
HRESULT hr = SHLoadLibraryFromKnownFolder(
                FOLDERID_PicturesLibrary, 
                STGM_READ, 
                IID_PPV_ARGS(&pslLibrary));
if(SUCCEEDED(hr))
{
    IShellItemArray *psiaFolders;
    hr = pslLibrary->GetFolders(
                            LFF_STORAGEITEMS, 
                            IID_PPV_ARGS(&psiaFolders)); 
    IEnumShellItems *penumShellItems;
    psiaFolders->EnumItems(&penumShellItems);
    //work with penumShellItem to enumerate the library locations.
}

Here you can see that we used another helper function SHLoadLibraryFromKnownFolder to create the IShellLibrary object from which we can call the GetFolders method to return an IShellItemArray that contains the library locations. This is the same as using SHCONTF_NAVIGATION_ENUM in the above Shell programming model example. You can directly enumerate the contents of each of the library locations using the shell programming model or get the path of each of the locations.

In the next post we will focus more on the rest of the IShellLibrary API.

Light Up with Windows 7 Libraries

Yochay Kiriaty — Thu, 16 Apr 2009 22:55:46 GMT

OK, it is time we to dive into the gist of Windows 7 Libraries. This is the fourth post in a series of Windows 7 Libraries posts. So far, we discussed what Windows 7 Libraries are (Understanding Windows 7 Libraries) and we reviewed the internal structure of Libraries and how they integrate into the Windows Shell Libraries Under The Hood. In this post, we review the different programming models developers can use when integrating Libraries into their applications.

Libraries are the new entry points for user’s data In Windows 7. Libraries are an integral part of the Shell and are promoted across Windows in Windows Explorer, Start Menu, and Common File Dialog. Windows 7 Users will use Libraries in their day-to-day activities. As such, they will expect applications that are running on Windows 7 to work properly with their Libraries and provide the same user experience as Windows Explorer. It is therefore important that, as developers, we know how to work with libraries and make our applications Libraries-aware.

But before we start, I want to note that while most applications should just work fine with Windows 7 Libraries, there is an opportunity to tap into the Windows 7 Libraries environment to provide a richer user experiences.

Making an application Libraries-aware

One may wonder what would happen if “my application does not support Libraries.” Let’s imagine an application that, as part of its functionality, needs to save a file to the disk. The application prompts the user with the option to select a location for the file. The user may pick the Documents Library as his save "folder" since this is where the user usual goes when he needs to work on a document. However, if the application doesn’t recognize that the user selected the Documents Library and not a regular folder, the application may try to save to the Documents Library. This is a problem, since by now, as we already know, that Libraries are non –file system location and therefore can’t be address as regular folders.

A Library-aware application should include mechanisms for handling situations where users inadvertently try to pick libraries as if they are folder for either saving files to a Library or loading the contents of a Library. Furthermore, most applications allow users to interact with the file system as part of the application experience. An application should provide users with the same familiar entry points and UI offered by the Windows 7 Libraries. By including folders in a Library, users designate where their important data is stored, and thus applications should promote these locations by enabling Library browsing.

Developers have three integration points with Windows 7 that can help applications become Library-aware. You should review and become familiar with all three points and choose according to your needs.

The most basic integration method is simply to use the new Common File Dialog (CFD) for picking files and folders while performing either save or load operations
The second integration point offers applications the opportunity to Light Up on Windows 7 by enabling applications to select Libraries and consume Libraries contents.
The last and most advanced integration point is to stay in sync with Library contents and directly manipulate Libraries by using the new IShellLibrary API that allows full control over libraries, including creating new libraries.

Let’s start by looking at the basic integration point, which can also be viewed as the bare minimum requirement for application compatibility when working with Windows 7 Libraries.

Using the Common File Dialog (CFD)

The good news is that Windows 7 Libraries are first class citizens in the CFD, allowing users to browse through Libraries, search Libraries, and even pick a specific Library as a save location, not an actual folder in the Library, but rather the Library itself!

But (there is always a but), we highly recommended that you use the new CFD interfaces that was introduced with Windows Vista, and not older or customized versions of the CFD. It is very important to note that the APIs for using the legacy CFD have not changed since Windows Vista, and XP to support application compatibility. However, the legacy version of the CFD (as is displayed in the next image) doesn’t directly support Libraries or the full new user experience offered in Windows 7.

Even if Libraries are presented in the right navigation pane, they require an extra click to save into one of the folders rather than just the Library. Also the legacy CFD doesn’t expose the search and arrangement views functionality that libraries offer. Finally, the legacy CFD doesn’t support the multiple selections of files across several folders, a basic functionality promoted in Libraries.

Therefore, it is important to use the proper APIs to show the correct CFD version. When using .NET, developers can use either the System.Windows.Forms.FileDialog or the Microsoft.Win32.FileDialog namespace. The latter uses the legacy version of the CFD; therefore, .NET developers should always use the WinForms namespace to show the new CFD. The following is a code snippet that prompts the user to choose a save location by showing the common save file dialog as shown in the next image.

System.Windows.Forms.SaveFileDialog _fd = 
        new System.Windows.Forms.SaveFileDialog();
_fd.Title = "Please choose a location to save your file";
_fd.FileName = "[Get Folder…]";
_fd.Filter = "Library|no.files";
if (_fd.ShowDialog() == System.Windows.Forms.DialogResult.OK)
{
    string dir_path = System.IO.Path.GetDirectoryName(_fd.FileName);
    if (dir_path != null && dir_path.Length > 0)
    { 
        //this returns the path to the default save location
        lblResult.Content = dir_path; 
    }
}

Native code developers should use the new family of IFileDialog native APIs (IFileDialog, IFileOpenDialog, IFileSaveDialog, IFileDialogCustomize, IFileDialogEvents, IFileDialogControlEvents) that are replacing the legacy GetOpenFileName and GetSaveFileName APIs from earlier Windows versions.

The Shell native APIs are COM-based; therefore, before using any COM object we must remember to initialize the COM object by calling CoCreateInstance. As an example, the following code snippet prompts the user to choose a Library or a folder to save the file to, by showing the common save file dialog.

*ppsi = NULL;
IFileSaveDialog *pfod;
hr = CoCreateInstance(
            CLSID_FileSaveDialog, 
            NULL, 
            CLSCTX_INPROC, 
            IID_PPV_ARGS(&pfod));

if (SUCCEEDED(hr))
{
      hr = pfod->SetOptions(FOS_PICKFOLDERS);
      if (SUCCEEDED(hr))
      {
          hr = pfod->Show(hWndParent);
           if (SUCCEEDED(hr))
           {
               hr = pfod->GetResult(ppsi);
           }
    }
    pfod->Release();
}

After initializing the *pfod IFileSaveDialog variable, we set the dialog options to pick folders by passing the FOS_PICKFOLDERS flag to the IFileOpenDialog.SetOptions(). This code tells the Open dialog to enable the user to choose folders rather than files, and allows the user to choose a Library. If choosing a library, the CFD will then return the default save location folder that is associated with the chosen Library.

The two above code snippets are very simple and don’t show any new code; however, it is important to promote consistency among applications running on Windows 7 and supporting Windows 7 Libraries.

In the next post, we will (finally) show the new Windows 7 library API, as well as how to consume Library contents with the existing Shell APIs.

Windows 7 Libraries .NET Sample Library – an Overview

Yochay Kiriaty — Tue, 07 Apr 2009 00:38:37 GMT

Libraries are the primary entry points to user data in Windows 7. They are the natural evolution from the user’s Known Folders, including those for documents, pictures, music, and videos. However, before jumping into the technicalities, let’s try to explain what a Library in Windows 7 is. A Windows 7 Library is a user-defined collection of content that represents the user’s data independently from the folder hierarchy. Users can unify and flatten the folder hierarchy by aggregating any number of physical locations (on their local machine or on remote machines) into a single view – which is the library. By including folders in Libraries, users tell Windows where their important data are located. In Windows 7 therefore, most applications should use a Library instead of the user’s Known Folders. It is important to note that as Libraries are an integral part of the Windows Shell, they play a greater role in the Windows 7 Explorer user experience. Accordingly, the importance and integration points of Libraries span multiple parts of the Windows Shell, including the Common File Dialog, Folder Picker, and the Windows Explorer Browser control (not Internet Explorer!).

This is the first post in a series of Library posts. It provides an overview of both the Windows 7 Library functionality and the Libraries Sample .NET Interop Library, which is a managed code wrapper and part of the Windows 7 .NET Interop Sample Libraries. The second post is all about Understanding Windows 7 Libraries. In future posts, we will dive into the internal implementation of Libraries as well as how to use the Libraries programming model and APIs.

If you are unfamiliar with and haven’t seen any demonstrations of the updated Windows 7 Shell and Libraries in action, I suggest you watch the Windows 7: Find and Organize Part 1 webcast on Channel 9. This will give you some context for the technical material we cover here.

Let’s review the Windows 7 Libraries .NET Interop Sample Library architecture and note the important classes. Please remember that the Libraries sample is part of the Taskbar and Libraries assembly. Since both Taskbar and the Libraries share many common integration points with the Windows Shell, it makes sense to have them grouped together and use the same Shell structures and methods.

Opening the solution reveals the following structure:

The Demos folder containing several demo projects that show the various aspects of both the Taskbar and Libraries wrappers as you can see from the image; we will focus on the Libraries
The Wrappers folder containing the Windows7.DesktopIntegration assembly, which is the main manager API for both the Taskbar and Libraries
A modified version of the Vista Bridge Sample Library - We based our code on the 1.4 version. And as mentioned before, the Windows Vista bridge Project will be superseded by the new Windows API Code Pack for the .NET Library

Let’s take a quick look at the main class that enables developers to take advantage of the new Library functionality. The ShellLibrary.cs file contains the ShellLibrary class, which is the main entry point for managed code developers. Using the ShellLibrary, developers can programmatically perform all Library operations, including:

Create new library
Load existing library
Delete library
Add / remove folders from the library
Set the default save location of the library
Set the folder type
Show the library management dialog box
Set the library icon
Pin and unpin the library from the left navigation pan in Windows Explorer

The demos in the Libraries folder highlight all the above-mentioned Library functionality. Let’s review them:

The LibraryManagerDemo is a Windows Presentation Foundation (WPF) application that showcases all the functionality offered by libraries. It is a very simple application that offers developers a great opportunity to review all the above-mentioned Libraries functionality.

The SLUtil (not Silverlight) is a command line interface that allows users and developers to manage their Libraries. Again, it offers all the above-mentioned Libraries functionality.

Here are some additional resources for programming Windows 7 Libraries:

Download Documentation and samples from the Windows 7 Libraries: Developer Resources page on MSDN.

View Channel 9 videos:

Additional blog posts

Understanding Windows 7 Libraries

Alon Fliess contributed to this post

Windows 7 Taskbar .NET Sample Library – an Overview

Yochay Kiriaty — Fri, 03 Apr 2009 07:32:29 GMT

One of the first noticeable changes in Windows 7 Desktop is the new Taskbar. The Windows 7 Taskbar post on the E7 blog clearly documents the reasons driving the Windows 7 Taskbar look and feel. The Windows 7 taskbar introduces new functionality that developers need to understand in order for them to take full advantage of it in their own applications and enhance their end users’ experiences. The Windows 7 Taskbar is an application-launching and window-switching mechanism that consolidates the functionalities from previous Windows Desktop mechanisms such as Quick Launch, Recent Documents, Notification area icons, desktop shortcuts, and running application windows.

If you are unfamiliar with and haven’t seen any demonstrations of the Windows 7 Taskbar, please watch the Windows 7 Taskbar Overview webcast on Channel 9. This will give you some context for the technical material we cover here.

This is the first post in a series of Taskbar posts. It provides an overview of both the new Taskbar functionality and the Taskbar and Libraries Sample .NET Interop Library, which is a managed code wrapper and part of the Windows 7 .NET Interop Sample Libraries.

Let’s review the Windows 7 Taskbar and Libraries .NET Interop Sample Library architecture and note the important classes. Opening the solution reveals the following structure:

A modified version of the Vista Bridge Sample Library - We based our code on the 1.4 version. And as mentioned before, the Windows Vista bridge Project will be superseded by the new Windows API Code Pack for the .NET Library
The Demos folder containing several demo projects that show the various aspects of both the Taskbar and Libraries wrappers as you can see from the image
The Wrappers folder containing the Windows7.DesktopIntegration assembly, which is the main manager API for both the Taskbar and Libraries

Let’s take a quick look at the main classes that enable developers to take advantage of the new taskbar functionality:

The Windows7Taskbar class provides low-level facilities for manipulating the process-wide and window-specific application IDs, controlling custom window preview bitmaps, setting the Taskbar overlay icon and progress bar, and clipping the Taskbar thumbnail
The JumpListManager class provides an abstraction of the application’s jump list, including facilities to manipulate custom destinations, user tasks, the Recent and Frequent lists, and items removed by the user
The ThumbButtonManager class provides an abstraction of the Taskbar thumbnail toolbar, including the facilities to create thumbnail toolbar buttons and receive notifications when they are clicked
The CustomWindowsManager class provides an abstraction of a customized window thumbnail preview and live preview (peek), including the facilities to receive a notification when a preview bitmap is requested by the Desktop Window Manager (DWM), and to automatically grab the preview bitmap of a window

The Taskbar demos showcase all of the above-mentioned Taskbar functionality. Let’s review them:

The MainDemo sample is a simple WinForm application that showcases all the functions that are expose via the API, including building a jump list with custom categories and custom tasks, setting an overlay icon and progress bar, and creating and handling events from Thumbnail Toolbar buttons:

In order for the main demo application to run properly, you will need to register this application as a registered handler for text files (*.txt). By registering this application and a handler for text files, you ensure that each time you open a text file directly from Windows Explorer. Windows automatically calls SHAddToRecentDocs on your application's behalf. This inserts the item in the Windows Recent list and eventually into the Jump List Recent Category. The same automatic behavior occurs when using the Windows common file dialog to open files through our applications.

You can register the application from the Administrative tool strip menu.

The DocumentReader sample demonstrates how developers can provide better Taskbar Thumbnail preview experiences for their users by clipping and customizing the Thumbnail Preview.

The IMClient sample demonstrates how Taskbar overlay icons and Taskbar progress bars can light up an application’s Taskbar button instead of relying on an additional dialog or on an icon in the system notification area (the tray). It is important to note that in Windows 7, the notification area has undergone a few changes and now shows the least number of icons in order to keep the taskbar clean and reduce the number of balloon notification messages.

The last demo, WebBrowser, demonstrates how to customize both the Thumbnail previews and the window preview (AeroPeek), and display internal tabs. As you can see from the following images, we can override the default behavior by flipping the images and adding some text on top of the preview image.

Here are some additional resources for programming the Windows 7 Taskbar:

Download Documentation and samples from the Windows 7 taskbar: Developer Resources page on MSDN.

Channel 9 videos:

Sasha Goldstein contributed to this blog - http://blogs.microsoft.co.il/blogs/sasha/archive/2009/02/12/windows-7-taskbar-apis.aspx