Hands-On Lab. Taskbar -.NET (WPF) Lab version: 1.0.0

Transcription

1 Hands-On Lab Taskbar -.NET (WPF) Lab version: Last updated: 12/3/2010

2 CONTENTS OVERVIEW... 3 EXERCISE: EXPERIMENT WITH THE NEW WINDOWS 7 TASKBAR FEATURES... 5 Task 1 Using Taskbar Overlay Icons... 6 Task 2 Using Taskbar Progress Bars... 8 Task 3 Using Thumbnail Toolbars Task 4 Using Live Thumbnail Previews Task 5 Using Thumbnail Clips Task 6 Using Taskbar Jump Lists SUMMARY

3 Overview The new Windows 7 Taskbar represents the culmination of many years of Windows launch surface evolution. 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 Controlling the application without leaving the taskbar thumbnail Figure 1 The new Windows 7 Taskbar and Start Menu The new taskbar is a differentiating opportunity that allows applications to shine on the Windows 7 platform. It is the end user s primary point-of-contact for initiating and managing activities. Thus, the integration of new taskbar features into modern Windows 7 applications is a critically important goal. 3

4 The consolidation of features into the new taskbar user interface is designed to provide a cleaner look to Windows, reduce the number of concepts users must learn in order to interact with the system, ease discoverability of key features, tasks and destinations, and make common end-user scenarios more accessible. Objectives In this Hands-On Lab, you will learn how to integrate your application with the Windows 7 Taskbar, including: Providing visual progress and status indicators using taskbar progress bars and overlay icons Remotely controlling a window from the taskbar thumbnail using thumbnail toolbars Customizing the taskbar thumbnail and live preview using thumbnail clips and fully custom ondemand thumbnails Quickly accessing common tasks and frequent destinations using jump list tasks, system categories and custom categories System Requirements You must have the following items to complete this lab: Microsoft Visual Studio 2008 SP1 Windows 7 RC or later Windows API Code Pack 1.00 and above Graphics card fully supporting Windows Aero 4

5 Exercise: Experiment with the New Windows 7 Taskbar Features In this exercise, you will experiment with the new Windows 7 taskbar features. You will extend a showcase application that demonstrates the use of the new taskbar functionality to provide a taskbar progress bar, overlay icon, custom thumbnail, jump list and more. Most of the application s user interface is already implemented; you will have to fill in the missing parts to interact with the Windows 7 taskbar using the Windows API Code Pack. To begin this exercise, open the TaskbarConcepts_Starter solution (under the HOL root folder) in Visual Studio. VB Figure 2 Taskbar Concepts solution structure in Visual Studio 5

6 Spend a minute or two exploring the XAML and or VB files that comprise the demo application. For your convenience, ensure that the Task List tool window is visible (in the View menu, choose Task List) and in the tool window s combo box select Comments you will now see TODO items for each of the tasks in this exercise. Help In the interests of brevity and simplicity, the demo application does not demonstrate best practices of WPF UI development, nor does it exhibit the best design guidelines for working with the Windows 7 Taskbar. For more information, consult the Windows 7 User Experience Guidelines (Taskbar) at and the Taskbar Extensions article at Task 1 Using Taskbar Overlay Icons In this task, you will toggle an overlay icon on the application s taskbar button when an icon is selected by the user. 1. Navigate to the Overlays.xaml.cs () or Overlays.xaml.vb (VB) code file and locate the ShowOrHideOverlayIcon method. 2. In the method s code, check whether the ShowOverlay checkbox is checked. 3. If the checkbox is checked, retrieve the currently selected icon from the list using the iconslist.selecteditem property, and if it is not null, pass it to the TaskbarManager.Instance.SetOverlayIcon method along with an appropriate textual description. This will cause an overlay icon to appear in the bottom-right corner of the application s taskbar button, providing an immediate status indicator without the need to switch to the application s window. This feature is used by Windows Live Messenger to display online availability status, by Microsoft Office Outlook 14 to display the new mail notification and by many other applications. 4. If the checkbox is not checked, pass null to the same method to clear the overlay icon. (You may also pass null for the textual description.) 5. The complete code should be similar to the following: if (ShowOverlay.IsChecked.Value) { Icon icon = iconslist.selecteditem as Icon; if (icon!= null) TaskbarManager.Instance.SetOverlayIcon( icon, "icon" + iconslist.selectedindex.tostring()); } 6

7 else { TaskbarManager.Instance.SetOverlayIcon(null, null); } Visual Basic If ShowOverlay.IsChecked.Value Then Dim icon As Icon = TryCast(iconsList.SelectedItem, Icon) If icon IsNot Nothing Then TaskbarManager.Instance.SetOverlayIcon(icon, "icon" & _ iconslist.selectedindex.tostring()) End If Else TaskbarManager.Instance.SetOverlayIcon(Nothing, Nothing) End If 6. Compile and run the application. 7. Navigate to the Overlay Icon tab, check the checkbox and make sure that an overlay icon appears on the application s taskbar button. For example: Figure 3 Taskbar overlay icon shown when the Show selected icon as overlay checkbox is checked 8. Select another icon and make sure that the overlay icon changes. 9. Clear the checkbox and make sure that the overlay icon is cleared as well. 7

8 Task 2 Using Taskbar Progress Bars In this task, you will set the state and value of the application s taskbar progress bar when the user selects the progress state from a combo box or changes the value by using a slider. 1. Navigate to the ProgressBar.xaml.cs() or ProgressBar.xaml.vb (VB) code file and locate the UpdateProgress method. 2. In the method s code, check whether the ShowProgressBar checkbox is checked. 3. If the checkbox is checked, use the TaskbarManager.Instance.SetProgressValue method to set the progress value to the value of the progressslider.value property. Use the number 100 for the maximum progress value. 4. If the checkbox is checked, use the TaskbarManager.Instance.SetProgressState method to set the progress state to the value of the ProgressStateSelection.SelectedItem property. This will cause a progress bar to appear in the application s taskbar button, providing an immediate progress indicator without the need to switch to the application s main window. This feature is extensively used by Windows Explorer when performing file operations, by Internet Explorer when downloading files and by other Windows applications. 5. If the checkbox is not checked, use the method from the previous step to set the progress state to TaskbarProgressState.NoProgress, clearing the progress bar. 6. The complete code should be similar to the following: if (ShowProgressBar.IsChecked.Value) { TaskbarManager.Instance.SetProgressValue((int)progressSlider.Value, 100); TaskbarManager.Instance.SetProgressState( (TaskbarProgressBarState)ProgressStateSelection.SelectedItem); } else { TaskbarManager.Instance.SetProgressState( TaskbarProgressBarState.NoProgress); } Visual Basic If ShowProgressBar.IsChecked.Value Then TaskbarManager.Instance.SetProgressValue(CInt(Fix(progressSlider.Value)), _ 100) TaskbarManager.Instance.SetProgressState( _ CType(ProgressStateSelection.SelectedItem, _ TaskbarProgressBarState)) Else 8

9 TaskbarManager.Instance.SetProgressState( _ TaskbarProgressBarState.NoProgress) End If 7. Navigate to the ProgressStateSelection_SelectionChanged method. 8. In the method s code, check whether the ProgressStateSelection.SelectedItem property is equal to TaskbarProgressState.NoProgress. 9. If it is equal, set the ShowProgressBar.IsChecked property to false. 10. Otherwise, set the same property to true. 11. Finally, call the UpdateProgress method you wrote earlier to update the taskbar progress state and value if necessary. 12. The complete code should be similar to the following: if ((TaskbarProgressBarState)ProgressStateSelection.SelectedItem == TaskbarProgressBarState.NoProgress) { ShowProgressBar.IsChecked = false; } else { ShowProgressBar.IsChecked = true; } UpdateProgress(); Visual Basic If CType(ProgressStateSelection.SelectedItem, TaskbarProgressBarState) = _ TaskbarProgressBarState.NoProgress Then ShowProgressBar.IsChecked = False Else ShowProgressBar.IsChecked = True End If UpdateProgress() 13. Navigate to the ShowProgressBar_Click method. 14. In the method s code, check whether the ShowProgressBar.IsChecked property is true. 15. If it is, set the ProgressStateSelection.SelectedItem property to TaskbarProgressState.Normal. 16. Otherwise, set the same property to TaskbarProgressState.NoProgress. 9

10 17. Finally, call the UpdateProgress method you wrote earlier to update the taskbar progress state and value if necessary. 18. The complete code should be similar to the following: if (ShowProgressBar.IsChecked.Value) { ProgressStateSelection.SelectedItem = TaskbarProgressBarState.Normal; } else { ProgressStateSelection.SelectedItem = TaskbarProgressBarState.NoProgress; } UpdateProgress(); Visual Basic If ShowProgressBar.IsChecked.Value Then ProgressStateSelection.SelectedItem = TaskbarProgressBarState.Normal Else ProgressStateSelection.SelectedItem = TaskbarProgressBarState.NoProgress End If UpdateProgress() 19. Compile and run the application. 20. Navigate to the Progress Bar tab, check the checkbox and move the slider to the middle. Make sure that a taskbar progress bar is displayed and updated accordingly. For example: 10

11 Figure 4 Taskbar progress bar reflects the slide value when the Show slider s value in progress bar checkbox is checked 21. Select a different progress state from the combo box and make sure the progress state changes (for example, the Error progress state corresponds to a red progress bar). Figure 5 Taskbar progress indicator reflects the progress state selected in the combo box, in this case Error 11

12 22. Clear the checkbox and make sure the progress bar is cleared as well. Task 3 Using Thumbnail Toolbars In this task, you will create taskbar thumbnail toolbar buttons to navigate images displayed in the main application window. 1. Navigate to the ToolbarButtons.xaml.cs() or ToolbarButtons.xaml.vb (VB) code file and locate the CreateToolbarButtons method. You will create four thumbnail toolbar buttons for image navigation, and add these buttons to the application s thumbnail toolbar. As a result, the user will be able to navigate the images from the taskbar thumbnail, without switching to the application s main window. Thumbnail toolbars are used by Windows Media Player to provide convenient navigation between tracks in the current playlist without switching to the Media Player window. This effectively replaces the need for the Media Player taskbar desk-band, which introduced clutter into the Windows taskbar and consumed a significant amount of screen estate that can be used for taskbar buttons. Figure 6 The Windows Media Player thumbnail toolbar 12

13 2. In the method s code, assign the buttonfirst member variable with a new instance of the ThumbnailToolbarButton class. Pass to the constructor the TaskbarConcepts.Resources.first image and the string First Image as the tooltip. 3. Set the buttonfirst.enabled property to false. 4. Register the buttonfirst_click method to the buttonfirst.click event. 5. Repeat steps 2-4 for the buttonprevious member variable with the TaskbarConcepts.Resources.prevArrow image and the string Previous Image. 6. Repeat steps 2 and 4 (without step 3) for the buttonnext member variable with the TaskbarConcepts.Resources.nextArrow image and the string Next Image. 7. Repeat steps 2 and 4 (without step 3) for the buttonlast member variable with the TaskbarConcepts.Resources.last image and the string Last Image. 8. Call the TaskbarManager.Instance.ThumbnailToolbars.AddButtons method, passing the application s main window handle as the first parameter, followed by the buttons created in the previous steps. This step creates the taskbar thumbnail toolbar. 9. The complete code should be similar to the following: buttonfirst = new ThumbnailToolbarButton( TaskbarConcepts.Resources.first, "First Image"); buttonfirst.enabled = false; buttonfirst.click += buttonfirst_click; buttonprevious = new ThumbnailToolbarButton( TaskbarConcepts.Resources.prevArrow, "Previous Image"); buttonprevious.enabled = false; buttonprevious.click += buttonprevious_click; buttonnext = new ThumbnailToolbarButton( TaskbarConcepts.Resources.nextArrow, "Next Image"); buttonnext.click += buttonnext_click; buttonlast = new ThumbnailToolbarButton( TaskbarConcepts.Resources.last, "Last Image"); buttonlast.click += buttonlast_click; TaskbarManager.Instance.ThumbnailToolbars.AddButtons( new WindowInteropHelper(Application.Current.MainWindow).Handle, buttonfirst, buttonprevious, buttonnext, buttonlast); Visual Basic 13

14 buttonfirst = New ThumbnailToolbarButton(TaskbarConcepts.Resources.first, _ "First Image") buttonfirst.enabled = False buttonfirst.click += buttonfirst_click buttonprevious = New ThumbnailToolbarButton(TaskbarConcepts.Resources.prevArrow, "Previous Image") buttonprevious.enabled = False buttonprevious.click += buttonprevious_click buttonnext = New ThumbnailToolbarButton(TaskbarConcepts.Resources.nextArrow, _ "Next Image") buttonnext.click += buttonnext_click buttonlast = New ThumbnailToolbarButton(TaskbarConcepts.Resources.last, _ "Last Image") buttonlast.click += buttonlast_click TaskbarManager.Instance.ThumbnailToolbars.AddButtons(New WindowInteropHelper(Application.Current.MainWindow).Handle, buttonfirst, _ buttonprevious, buttonnext, buttonlast) 10. Compile and run the application. 11. Navigate to the Thumbnail Toolbar tab and ensure that there are images shown. If there are no images, make sure your Pictures library contains a few images. 12. Hover over the application s taskbar button until the thumbnail is shown. Use the four thumbnail toolbar buttons to navigate between the images. For example: 14

15 Figure 7 Thumbnail toolbar allows navigation between images while hovering over the application s thumbnail Task 4 Using Live Thumbnail Previews In this task, you will customize live thumbnails (and previews) of the application s window and provide the displayed thumbnail lazily (on demand). 1. Navigate to the Thumbnail.xaml.cs() or Thumbnail.xaml.vb (VB) code file and locate the createondemandthumbnail_click method. 2. In the method s code, check whether the trickyborder visual element has a thumbnail preview. You can use the Utilities.HasThumbnailPreview method for this purpose. 15

16 3. If it doesn t have a preview yet, continue to the following steps. Otherwise, return from the method there is already a thumbnail for this element and there s no need to create it again. 4. Calculate the offset of the trickyborder visual element from the application s main window (you can retrieve the main window frame using the Application.Current.MainWindow property). To calculate the offset, you can use the helper method Utilities.GetOffset. The reason for calculating the offset is that we want the actual taskbar thumbnail to display only the image itself, and not the entire window frame. In this case, the taskbar thumbnail APIs require the offset from the application s main window frame to be specified. Thumbnail customization can be useful if you want to draw attention to a specific part of the window when it s displayed as a thumbnail, or when you want to dynamically decide which part of the window to display in the thumbnail. Technically, it s not binding for you to display a part of your window in the thumbnail you could provide a completely custom image but this has the potential to confuse users. Figure 8 Internet Explorer 8 features tabbed thumbnails of its TDI interface 16

17 5. Create a new instance of the TabbedThumbnail class and pass to its constructor the application s main window, the trickyborder visual element and the offset calculated in the previous step. 6. Use the TaskbarManager.Instance.TabbedThumbnail.AddThumbnailPreview method to add the newly created preview object to the taskbar. 7. Register for the TabbedThumbnailBitmapRequested event of the TabbedThumbnail instance using the TabbedThumbnail_TabbedThumbnailBitmapRequested method. This means that we are not providing the thumbnail bitmap statically; instead, the DWM will call back into our event implementation so that we provide the bitmap dynamically, only when it s needed. 8. Set the Tooltip property of the TabbedThumbnail instance to a string of your choice. 9. The complete code should be similar to the following: if (!Utilities.HasThumbnailPreview(trickyBorder)) { Vector offset = Utilities.GetOffset( Application.Current.MainWindow, trickyborder); TabbedThumbnail preview = new TabbedThumbnail( Application.Current.MainWindow, trickyborder, offset); TaskbarManager.Instance.TabbedThumbnail.AddThumbnailPreview(preview); preview.tabbedthumbnailbitmaprequested += TabbedThumbnail_TabbedThumbnailBitmapRequested; } preview.tooltip = "This bitmap is created and returned on demand"; Visual Basic If Not Utilities.HasThumbnailPreview(trickyBorder) Then Dim offset As Vector = _ Utilities.GetOffset(Application.Current.MainWindow, trickyborder) Dim preview As New TabbedThumbnail(Application.Current.MainWindow, _ trickyborder, offset) TaskbarManager.Instance.TabbedThumbnail.AddThumbnailPreview(preview) preview.tabbedthumbnailbitmaprequested += _ TabbedThumbnail_TabbedThumbnailBitmapRequested preview.tooltip = "This bitmap is created and returned on demand" End If 17

18 10. Navigate to the removeondemandthumbnail_click method. 11. In the method s code, retrieve the TabbedThumbnail object corresponding to the trickyborder visual element s thumbnail using the TaskbarManager.Instance.TabbedThumbnail.GetThumbnailPreview method. 12. If the retrieved instance is not null, use the TaskbarManager.Instance.TabbedThumbnail.RemoveThumbnailPreview method to remove the thumbnail preview. 13. The complete code should be similar to the following: TabbedThumbnail preview = TaskbarManager.Instance.TabbedThumbnail.GetThumbnailPreview(trickyBorder); if (preview!= null) TaskbarManager.Instance.TabbedThumbnail.RemoveThumbnailPreview(preview); Visual Basic Dim preview As TabbedThumbnail = _ TaskbarManager.Instance.TabbedThumbnail.GetThumbnailPreview(trickyBorder) If preview IsNot Nothing Then TaskbarManager.Instance.TabbedThumbnail.RemoveThumbnailPreview(preview) End If 14. Navigate to the TabbedThumbnail_TabbedThumbnailBitmapRequested method. 15. In the method s code, check whether the _sneakysource member variable is null. 16. If it is, assign to it a new BitmapImage object, call its BeginInit method, set its DecodePixelHeight property to the number 200, set its UriSource property to a new Uri instance initialized with the string pack://application:,,,/assets/speedygonzalez.jpg and then call its EndInit method. 17. Finally, use the TabbedThumbnail.SetImage method of the event arguments parameter and pass to it the _sneakysource member variable. 18. The complete code should be similar to the following: if (_sneakysource == null) { _sneakysource = new BitmapImage(); _sneakysource.begininit(); _sneakysource.decodepixelheight = 200; 18

19 _sneakysource.urisource = new Uri("pack://application:,,,/assets/SpeedyGonzales.jpg"); _sneakysource.endinit(); } e.tabbedthumbnail.setimage(_sneakysource); Visual Basic If _sneakysource Is Nothing Then _sneakysource = New BitmapImage() _sneakysource.begininit() _sneakysource.decodepixelheight = 200 _sneakysource.urisource = New Uri("pack://application:,,,/assets/SpeedyGonzales.jpg") _sneakysource.endinit() End If e.tabbedthumbnail.setimage(_sneakysource) 19. Navigate to the createthumbnail_click method. In this method, we will use a statically set bitmap for the thumbnail, without registering for the event that is invoked by the DWM. As a result, we will have to manually invalidate the thumbnail whenever it becomes stale. 20. Repeat steps 2-8 for the image visual element, but this time do not register for the TabbedThumbnailBitmapRequested event. Instead, call the TaskbarManager.Instance.TabbedThumbnail.SetActiveTab method and pass to it the newly created TabbedThumbnail instance. 21. The complete code should be similar to the following: if (!Utilities.HasThumbnailPreview(image)) { Vector offset = Utilities.GetOffset( Application.Current.MainWindow, image); TabbedThumbnail preview = new TabbedThumbnail( Application.Current.MainWindow, image, offset); TaskbarManager.Instance.TabbedThumbnail.AddThumbnailPreview(preview); preview.tooltip = "This image will be replaced and invalidated"; TaskbarManager.Instance.TabbedThumbnail.SetActiveTab(preview); } Visual Basic If Not Utilities.HasThumbnailPreview(image) Then Dim offset As Vector = _ Utilities.GetOffset(Application.Current.MainWindow, image) 19

20 Dim preview As New TabbedThumbnail(Application.Current.MainWindow, _ image, offset) TaskbarManager.Instance.TabbedThumbnail.AddThumbnailPreview(preview) preview.tooltip = "This image will be replaced and invalidated" TaskbarManager.Instance.TabbedThumbnail.SetActiveTab(preview) End If 22. Navigate to the removethumbnail_click method. 23. Repeat steps for the image visual element. 24. The complete code should be similar to the following: TabbedThumbnail preview = TaskbarManager.Instance.TabbedThumbnail.GetThumbnailPreview(image); if (preview!= null) TaskbarManager.Instance.TabbedThumbnail.RemoveThumbnailPreview(preview); Visual Basic Dim preview As TabbedThumbnail = _ TaskbarManager.Instance.TabbedThumbnail.GetThumbnailPreview(image) If preview IsNot Nothing Then TaskbarManager.Instance.TabbedThumbnail.RemoveThumbnailPreview(preview) End If 25. Navigate to the invalidatethumbnail_click method. The invalidation is necessary because we did not register an event handler for the thumbnail bitmap, and therefore the bitmap remains static until we explicitly invalidate it. 26. In the method s code, check whether there is a thumbnail preview for the image visual element (see steps for an example). 27. If there is, use the InvalidatePreview method of the resulting TabbedThumbnail object to invalidate the thumbnail preview. 28. The complete code should be similar to the following: TabbedThumbnail preview = TaskbarManager.Instance.TabbedThumbnail.GetThumbnailPreview(image); if (preview!= null) preview.invalidatepreview(); 20

21 Visual Basic Dim preview As TabbedThumbnail = _ TaskbarManager.Instance.TabbedThumbnail.GetThumbnailPreview(image) If preview IsNot Nothing Then preview.invalidatepreview() End If 29. Compile and run the application. 30. Navigate to the Thumbnail Preview tab and click the Add as thumbnail button in the Thumbnail with Callback group. 31. Hover over the application s taskbar button and ensure that the thumbnail displays an image instead of the black rectangle. Hover over the thumbnail and ensure that the live preview also displays the same image instead of the black rectangle. For example: Figure 9 Live thumbnail and live preview showing an image generated on-demand instead of the black rectangle in the application s window 21

22 32. Click the Remove thumbnail button in the Thumbnail with Callback group and ensure that the application s taskbar thumbnail and live preview are back to the default (the entire window). 33. Click the Add as thumbnail button in the Tabbed Thumbnail group. 34. Hover over the application s taskbar button and ensure that the thumbnail and live preview reflect the current image in the main window. 35. Click the Update image button in the Tabbed Thumbnail group and notice that the thumbnail is not refreshed it still displays the previous image. For example: Figure 10 The thumbnail is not automatically refreshed (because it is not generated on demand), and shows a stale image that doesn t reflect the UI unless explicitly invalidated 36. Click the Invalidate thumbnail button in the Tabbed Thumbnail group and ensure that the thumbnail is updated to reflect the new image. 37. Finally, click the Remove thumbnail button in the Tabbed Thumbnail group and ensure that the application s taskbar thumbnail and live preview are back to the default (the entire window). 22

23 Task 5 Using Thumbnail Clips In this task, you will set a clipping rectangle that will be shown in the window s taskbar thumbnail in order to zoom in on the relevant part of the window. 1. Navigate to the ThumbnailClip.xaml.cs() or ThumbnailClip.xaml.vb(VB) code file and locate the mediaelement_mediaopened method. 2. In the method s code, calculate the offset of the mediaelement visual element from the main window frame (you can retrieve the main window frame using the Application.Current.MainWindow property). To calculate the offset, you can use the helper method Utilities.GetOffset. 3. Retrieve the main window s handle using the WindowInteropHelper class. 4. Create a clipping rectangle (a System.Drawing.Rectangle object). Initialize its x,y coordinates with the coordinates of the offset calculated in step 2, and initialize its height and width to the height and width of the mediaelement. 5. Use the Dispatcher.BeginInvoke class to set the thumbnail clip in the background, by using the TaskbarManager.Instance.TabbedThumbnail.SetThumbnailClip method and pass to it the main window s handle from step 3 and the clipping rectangle from step 4. Clipped thumbnails are useful when you want to focus on a specific section of your window, and you don t want to create a custom thumbnail handler for this purpose and draw the thumbnail yourself. For example, a text editor might benefit from a thumbnail clip that shows several lines around the current cursor position this would be more readable than the entire text editor window. 6. The complete code should be similar to the following: Vector offset = Utilities.GetOffset( Application.Current.MainWindow, (Visual)mediaElement); Dispatcher.BeginInvoke(DispatcherPriority.Background, new Action(() => { IntPtr mainwindowhandle = new WindowInteropHelper( Application.Current.MainWindow).Handle; System.Drawing.Rectangle cliprect = new System.Drawing.Rectangle( (int)offset.x, (int)offset.y, (int)mediaelement.actualwidth, (int)mediaelement.actualheight); TaskbarManager.Instance.TabbedThumbnail.SetThumbnailClip( mainwindowhandle, cliprect); })); 23

24 Visual Basic Private offset As Vector = Utilities.GetOffset( _ Application.Current.MainWindow, CType(mediaElement, Visual)) Dispatcher.BeginInvoke(DispatcherPriority.Background, New Action( _ Function() AnonymousMethod1())) Private Function AnonymousMethod1() As Object Dim mainwindowhandle As IntPtr = New _ WindowInteropHelper(Application.Current.MainWindow).Handle Dim cliprect As New System.Drawing.Rectangle(CInt(Fix(offset.X)), _ CInt(Fix(offset.Y)), CInt(Fix(mediaElement.ActualWidth)), _ CInt(Fix(mediaElement.ActualHeight))) TaskbarManager.Instance.TabbedThumbnail.SetThumbnailClip( _ mainwindowhandle, cliprect) Return Nothing End Function 7. Compile and run the application. 8. Navigate to the Thumbnail Clip tab and click the button to select a video file (you can download one from the Internet or use the video under the Sample Videos folder on your machine). 9. While the video is playing, hover over the application s taskbar button and ensure that the thumbnail displays only a part of the window, roughly clipped to the video area. For example: 24

25 Figure 11 Thumbnail clipping ensures that only the relevant parts of the window are shown in the taskbar thumbnail Task 6 Using Taskbar Jump Lists In this task, you will add the functionality to support adding user tasks, custom categories and destinations to the application s jump list, as well as clearing the list of user tasks. 1. Navigate to the JL.xaml.cs() or JL.xaml.vb (VB) code file and locate the OnAddTasks method. 2. In the method s code, create an instance of the JumpListLink class and pass to its constructor the path to notepad.exe (use the Environment.GetFolderPath method to determine the location of the System32 directory in which the Notepad executable resides), and the string Open Notepad for the link s title. 3. Set the IconReference property of the newly created instance to a new instance of the IconReference class, and pass to the constructor the path to notepad.exe (obtained in the previous step), and the number 0 as the icon index. 4. Repeat steps 2 and 3 to create links to calc.exe and mspaint.exe with the corresponding Open Calculator and Open Paint title strings. 25

26 5. Call the JumpList.AddUserTasks method and pass to it the Notepad and Calculator link objects, followed by a new instance of JumpListSeparator, followed by the Paint link object. As a result, you ve added common user tasks to your application s jump list. In practice, it would be uncommon for an application to include user tasks that launch unrelated applications. Instead, common user tasks would include launching the application with different command line arguments, navigating to a specific area in the application, or even specifying commands for a running instance of the application. For example, Windows Live Messenger uses jump list tasks for changing the user s online availability status. Figure 12 The Windows Live Messenger taskbar jump list, featuring user tasks 6. Finally, call the JumpList.Refresh method to refresh the application s jump list. 7. The complete code should be similar to the following: string systemfolder = Environment.GetFolderPath( Environment.SpecialFolder.System); 26

27 IJumpListTask notepadtask = new JumpListLink( System.IO.Path.Combine(systemFolder, "notepad.exe"), "Open Notepad") { IconReference = new IconReference( Path.Combine(systemFolder, "notepad.exe"), 0) }; IJumpListTask calctask = new JumpListLink( Path.Combine(systemFolder, "calc.exe"), "Open Calculator") { IconReference = new IconReference( Path.Combine(systemFolder, "calc.exe"), 0) }; IJumpListTask painttask = new JumpListLink( Path.Combine(systemFolder, "mspaint.exe"), "Open Paint") { IconReference = new IconReference( Path.Combine(systemFolder, "mspaint.exe"), 0) }; JumpList.AddUserTasks( notepadtask, calctask, new JumpListSeparator(), painttask); JumpList.Refresh(); Visual Basic Dim systemfolder As String = _ Environment.GetFolderPath(Environment.SpecialFolder.System) Dim notepadtask As IJumpListTask = New _ JumpListLink(System.IO.Path.Combine(systemFolder, "notepad.exe"), _ "Open Notepad") With {.IconReference = New _ IconReference(Path.Combine(systemFolder, "notepad.exe"), 0)} Dim calctask As IJumpListTask = New JumpListLink(Path.Combine(systemFolder, _ "calc.exe"), "Open Calculator") With {.IconReference = New _ IconReference(Path.Combine(systemFolder, "calc.exe"), 0)} Dim painttask As IJumpListTask = New JumpListLink(Path.Combine(systemFolder, _ "mspaint.exe"), "Open Paint") With {.IconReference = New _ IconReference(Path.Combine(systemFolder, "mspaint.exe"), 0)} JumpList.AddUserTasks(notepadTask, calctask, New JumpListSeparator(), _ painttask) JumpList.Refresh() 8. Navigate to the JumpList property. 27

28 9. In the property s get accessor, check if the _jumplist member variable is null. 10. If it is, set its value to the result of the JumpList.CreateJumpList method, set its KnownCategoryToDisplay property to JumpListKnownCategoryType.Recent if the showrecent.ischecked property is true or JumpListKnownCategoryType.Frequent if it s false; finally, call the JumpList.Refresh method to refresh the jump list. There are two system categories that you can opt in to use by default: the Recent category, which shows documents most recently accessed by your application, and the Frequent category, which shows documents most frequently accessed. Using both categories is discouraged and the managed wrapper doesn t allow it at all. Help In order to have items appear in the Recent or Frequent categories, your application needs a properly defined file-type association in the Windows Registry (although it does not have to be the default handler for that file-type). The sample application can be registered to handle PNG image files. For more information about file-type associations, consult Return the value of the _jumplist member variable from the get accessor. 12. The complete code should be similar to the following: if (_jumplist == null) { _jumplist = JumpList.CreateJumpList(); _jumplist.knowncategorytodisplay = showrecent.ischecked.value? JumpListKnownCategoryType.Recent : JumpListKnownCategoryType.Frequent; _jumplist.refresh(); } return _jumplist; Visual Basic If _jumplist Is Nothing Then _jumplist = JumpList.CreateJumpList() _jumplist.knowncategorytodisplay = If(showRecent.IsChecked.Value, _ JumpListKnownCategoryType.Recent, JumpListKnownCategoryType.Frequent) _jumplist.refresh() End If Return _jumplist 28

29 13. Navigate to the showrecent_click method. 14. In the method s code, set the JumpList.KnownCategoryToDisplay property according to the same logic as in step 10 above, and call the JumpList.Refresh method. 15. The complete code should be similar to the following: JumpList.KnownCategoryToDisplay = showrecent.ischecked.value? JumpListKnownCategoryType.Recent : JumpListKnownCategoryType.Frequent; JumpList.Refresh(); Visual Basic JumpList.KnownCategoryToDisplay = If(showRecent.IsChecked.Value, _ JumpListKnownCategoryType.Recent, JumpListKnownCategoryType.Frequent) JumpList.Refresh() 16. Navigate to the OnClearTasks method. 17. In the method s code, call the JumpList.ClearAllUserTasks method to clear the jump list from all user tasks. 18. Call the JumpList.Refresh method for the changes to take effect. 19. The complete code should be similar to the following: JumpList.ClearAllUserTasks(); JumpList.Refresh(); Visual Basic JumpList.ClearAllUserTasks() JumpList.Refresh() 20. Navigate to the createcategory_click method. 21. In the method s code, assign to the _currentcategory member variable a new instance of the JumpListCustomCategory class, passing to its constructor the name of the category obtained from the txtcategory member variable. 29

30 Custom categories are an advanced feature that can be used by an application to provide more than just the Recent or Frequent system categories. For example, an application might provide Inbox, Follow-up and other custom categories in which messages are grouped. 22. Use the JumpList.AddCustomCategories method and pass to it the newly created category. 23. Call the JumpList.Refresh method to commit the changes. 24. Set the IsEnabled property of the createcategoryitem, createcategorylink, txtcategoryitem and txtcategorylink member variables to true. 25. The complete code should be similar to the following: _currentcategory = new JumpListCustomCategory(this.txtCategory.Text); JumpList.AddCustomCategories(_currentCategory); JumpList.Refresh(); this.createcategoryitem.isenabled = true; this.createcategorylink.isenabled = true; this.txtcategoryitem.isenabled = true; this.txtcategorylink.isenabled = true; Visual Basic _currentcategory = New JumpListCustomCategory(Me.txtCategory.Text) JumpList.AddCustomCategories(_currentCategory) JumpList.Refresh() Me.createCategoryItem.IsEnabled = True Me.createCategoryLink.IsEnabled = True Me.txtCategoryItem.IsEnabled = True Me.txtCategoryLink.IsEnabled = True 26. Navigate to the createcategoryitem_click method. 27. In the method s code, call the CheckFileName method and pass to it the Text property of the txtcategoryitem member variable. If the method returns false, return from this method without doing anything. 28. Otherwise, create a new instance of the JumpListItem class and pass to its constructor the result of calling the GetTempFileName method with the txtcategoryitem.text property. (The latter method creates a new temporary file with an appropriate file name.) 29. Use the AddJumpListItems method of the _currentcategory member variable and pass to it the newly created JumpListItem instance. 30

31 30. Call the JumpList.Refresh method to commit the changes to the jump list. 31. The complete code should be similar to the following: if (!CheckFileName(txtCategoryItem.Text)) return; JumpListItem jli = new JumpListItem(GetTempFileName(txtCategoryItem.Text)); _currentcategory.addjumplistitems(jli); JumpList.Refresh(); Visual Basic If Not CheckFileName(txtCategoryItem.Text) Then Return End If Dim jli As New JumpListItem(GetTempFileName(txtCategoryItem.Text)) _currentcategory.addjumplistitems(jli) JumpList.Refresh() 32. Navigate to the createcategorylink_click method. 33. Repeat steps 27-31, but instead of using txtcategoryitem use txtcategorylink and instead of using JumpListItem use JumpListLink. The JumpListLink constructor requires an additional title parameter you should pass the txtcategorylink.text property for this parameter. The difference between shell items and shell links (represented as JumpListItem and JumpListLink in the managed wrapper, and by IShellItem and IShellLink in the underlying COM Shell APIs) is that a shell item contains only a path to a document that your application is registered to handle, but a shell link contains additional information and serves as a shortcut, including the application to launch, command-line arguments to pass to that application, a shortcut icon and other properties. 34. The complete code should be similar to the following: if (!CheckFileName(txtCategoryItem.Text)) return; JumpListLink jli = new JumpListLink( GetTempFileName(txtCategoryLink.Text), txtcategorylink.text); _currentcategory.addjumplistitems(jli); JumpList.Refresh(); 31

32 Visual Basic If Not CheckFileName(txtCategoryItem.Text) Then Return End If Dim jli As New JumpListLink(GetTempFileName(txtCategoryLink.Text), _ txtcategorylink.text) _currentcategory.addjumplistitems(jli) JumpList.Refresh() 35. Compile and run the application. 36. Navigate to the Jump List tab and click the Ensure type registration button. The application will register the.png file association with itself in the Windows Registry. This may cause a User Account Control consent prompt confirm the action if prompted. 37. Check the Show recent category checkbox and click the button above it. In the common file dialog, select a PNG file. Ensure that the application s jump list now contains the selected PNG file in the Recent category. 38. Click the Add Tasks button and ensure that the jump list now contains links to Notepad, Calculator and Paint (and that there is a separator between the first two and the last one). 39. Enter Important in the category name textbox and click the Create button. 40. Enter Activity report in the item textbox and click the Add ShellItem button. Ensure that the jump list now contains a category called Important with a single item called Activity report. For example: Figure 13 32

33 The application s jump list shows user tasks, the Recent system category and the Important custom category Summary In this lab, you have experimented with the Windows 7 Taskbar APIs and integrated a sample application with the Windows 7 Taskbar. You have seen how easy it is to provide relevant progress and status information from the taskbar button using progress bars and overlay icons, how to quickly access common tasks and destinations using jump lists, how to remotely control an application using a thumbnail toolbar, and how to customize thumbnails and live previews for greater flexibility over what is shown in the application s thumbnail. Integrating a production-quality application with the Windows 7 Taskbar might require slightly more work than you have done in this lab, but you are now sufficiently prepared to begin this quest on your own. 33