ITaskbarList3 interface
Applies to: desktop apps only
Extends ITaskbarList2 by exposing methods that support the unified launching and switching taskbar button functionality added in Windows 7. This functionality includes thumbnail representations and switch targets based on individual tabs in a tabbed application, thumbnail toolbars, notification and status overlays, and progress indicators.
Members
The ITaskbarList3 interface inherits from ITaskbarList2. ITaskbarList3 also has these types of members:
Methods
The ITaskbarList3 interface has these methods.
| Method | Description |
|---|---|
| RegisterTab |
Informs the taskbar that a new tab or document thumbnail has been provided for display in an application's taskbar group flyout. |
| SetOverlayIcon |
Applies an overlay to a taskbar button to indicate application status or a notification to the user. |
| SetProgressState |
Sets the type and state of the progress indicator displayed on a taskbar button. |
| SetProgressValue |
Displays or updates a progress bar hosted in a taskbar button to show the specific percentage completed of the full operation. |
| SetTabActive |
Informs the taskbar that a tab or document window has been made the active window. |
| SetTabOrder |
Inserts a new thumbnail into a TDI or MDI application's group flyout or moves an existing thumbnail to a new position in the application's group. |
| SetThumbnailClip |
Selects a portion of a window's client area to display as that window's thumbnail in the taskbar. |
| SetThumbnailTooltip |
Specifies or updates the text of the tooltip that is displayed when the mouse pointer rests on an individual preview thumbnail in a taskbar button flyout. |
| ThumbBarAddButtons |
Adds a thumbnail toolbar with a specified set of buttons to the thumbnail image of a window in a taskbar button flyout. |
| ThumbBarSetImageList |
Specifies an image list that contains button images for a toolbar embedded in a thumbnail image of a window in a taskbar button flyout. |
| ThumbBarUpdateButtons |
Shows, enables, disables, or hides buttons in a thumbnail toolbar as required by the window's current state. A thumbnail toolbar is a toolbar embedded in a thumbnail image of a window in a taskbar button flyout. |
| UnregisterTab |
Removes a thumbnail from an application's preview group when that tab or document is closed in the application. |
Remarks
This interface also provides the methods of the ITaskbarList and ITaskbarList2 interfaces, from which it inherits.
When to Implement
An implementation of this interface is provided in Windows as CLSID_TaskbarList. This interface is not implemented by third parties.
When to Use
Use the methods of this interface to do the following:
- When working with a TDI application (such as Windows Internet Explorer) or a MDI application (such as Microsoft Excel) that is displaying its windows as a group on the taskbar:
- Provide the taskbar with a thumbnail that represents the view of an individual tab or document.
- Remove the thumbnail of an individual tab or document from the group.
- Change the order of thumbnails in the group.
- Set a tab thumbnail as the selected item when the thumbnails are shown.
- When applying an overlay to a taskbar icon, such as a notification.
- When showing the progress of an operation, such as copying or installing an item.
- When adding a toolbar to a thumbnail.
When an application displays a window, its taskbar button is created by the system. When the button is in place, the taskbar sends a TaskbarButtonCreated message to the window. Your application should call RegisterWindowMessage(L"TaskbarButtonCreated") and handle that message in its wndproc. That message must be received by your application before it calls any ITaskbarList3 method.
Note Applications cannot programmatically pin themselves to the taskbar. That functionality is reserved strictly for the user.
Requirements
|
Minimum supported client | Windows 7 |
|---|---|
|
Minimum supported server | Windows Server 2008 R2 |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
Send comments about this topic to Microsoft
Build date: 3/7/2012
internal interface ITaskbarList
{
#region ITaskbarList
void HrInit();
void AddTab(IntPtr hWnd);
void DeleteTab(IntPtr hWnd);
void ActivateTab(IntPtr hWnd);
void SetActiveAlt(IntPtr hWnd);
#endregion
#region ITaskbarList2
HRESULT MarkFullscreenWindow(IntPtr hWnd, bool fFullscreen);
#endregion
#region ITaskbarList3
/// <summary>
/// 设置任务栏显示进度
/// </summary>
/// <param name="hWnd">任务栏对应的窗口句柄</param>
/// <param name="Completed">进度的当前值</param>
/// <param name="Total">总的进度值</param>
void SetProgressValue(IntPtr hWnd, ulong Completed, ulong Total);
/// <summary>
/// 设置任务栏状态
/// </summary>
/// <param name="hWnd">任务栏对应的窗口句柄</param>
/// <param name="Flags">状态指示,具体见TbpFlag定义</param>
void SetProgressState(IntPtr hWnd, TbpFlag Flags);
/// <summary>
///
/// </summary>
/// <param name="hWndTab"></param>
/// <param name="hWndMDI"></param>
void RegisterTab(IntPtr hWndTab, IntPtr hWndMDI);
/// <summary>
///
/// </summary>
/// <param name="hWndTab"></param>
void UnregisterTab(IntPtr hWndTab);
void SetTabOrder(IntPtr hWndTab, IntPtr hwndInsertBefore);
void SetTabActive(IntPtr hWndTab, IntPtr hWndMDI, uint dwReserved);
void ThumbBarAddButtons(IntPtr hWnd, uint cButtons, [MarshalAs(UnmanagedType.LPArray)] ThumbButton[] pButtons);
void ThumbBarUpdateButtons(IntPtr hWnd, uint cButtons, [MarshalAs(UnmanagedType.LPArray)]ThumbButton[] pButtons);
void ThumbBarSetImageList(IntPtr hWnd, IntPtr himl);
void SetOverlayIcon(IntPtr hWnd, IntPtr hIcon, [MarshalAs(UnmanagedType.LPWStr)]string pszDescription);
void SetThumbnailTooltip(IntPtr hWnd, [MarshalAs(UnmanagedType.LPWStr)]string pszTip);
void SetThumbnailClip(IntPtr hWnd, ref tagRECT prcClip);
#endregion
}
[ComImport(),Guid("56FDF344-FD6D-11d0-958A-006097C9A090"),ClassInterface(ClassInterfaceType.None)]
internal class TaskbarList { }
[Flags]
public enum TbpFlag : uint
{
NoProgress = 0x00, //不显示进度
Indeterminate = 0x01, //进度循环显示
Normal = 0x02, //进度条显示绿色
Error = 0x04, //进度条红色显示
Paused = 0x08 //进度条黄色显示
}
/// <summary>
/// 指名在ThumbButton结构中哪个成员包含有有效信息
/// </summary>
[Flags]
public enum ThumbButtonMask : uint
{
Bitmap = 0x01, //ThumbButton.iBitmap包含有效信息
Icon = 0x02, //ThumbButton.hIcon包含有效信息
ToolTip = 0x04, //ThumbButton.szTip包含有效信息
Flags = 0x08 //ThumbButton.dwFlags包含有效信息
}
[Flags]
public enum ThumbButtonFlags : uint
{
Enabled = 0x00, //按钮是可用的
Disabled = 0x01, //按钮是不可用的
DisMissonClick = 0x02, //当按钮被点击,任务栏按钮的弹出立刻关闭
NoBackground = 0x04, //不标示按钮边框,只显示按钮图像
Hidden = 0x08, //隐藏按钮
NonInterActive = 0x10 //该按钮启用,但没有互动,没有按下按钮的状态绘制。此值用于按钮所在的通知是在使用实例。
}
[StructLayout(LayoutKind.Sequential)]
public struct tagRECT
{
public int left;
public int top;
public int right;
public int bottom;
}
public struct ThumbButton
{
public ThumbButtonMask dwMask;
public uint iID;
public uint iBitmap;
IntPtr hIcon;
[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 260)]
public string szTip;
public ThumbButtonFlags dwFlags;
}
- 10/30/2009
- ChinaPhoenix
<ComImport(), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("EA1AFB91-9E28-4B86-90E9-9E9F8A5EEFAF")> _
Public Interface ITaskbarList3
Inherits ITaskbarList2
Overloads Sub HrInit()
Overloads Sub AddTab(<[In]()> ByVal hwnd As IntPtr)
Overloads Sub DeleteTab(<[In]()> ByVal hwnd As IntPtr)
Overloads Sub ActivateTab(<[In]()> ByVal hwnd As IntPtr)
Overloads Sub SetActivateAlt(<[In]()> ByVal hwnd As IntPtr)
Overloads Sub MarkFullscreenWindow(<[In]()> ByVal hwnd As IntPtr, <[In]()> ByVal fFullscreen As Integer)
Sub SetProgressValue(<[In]()> ByVal hwnd As IntPtr, <[In]()> ByVal ullCompleted As UInt64, <[In]()> ByVal ullTotal As UInt64)
Sub SetProgressState(<[In]()> ByVal hwnd As IntPtr, <[In]()> ByVal tbpFlags As TBPFLAG)
Sub RegisterTab(<[In]()> ByVal hwndTab As IntPtr, <[In](), ComAliasName("TaskbarLib.wireHWND")> ByRef hwndMDI As RemotableHandle)
Sub UnregisterTab(<[In]()> ByVal hwndTab As IntPtr)
Sub SetTabOrder(<[In]()> ByVal hwndTab As IntPtr, <[In]()> ByVal hwndInsertBefore As Integer)
Sub SetTabActive(<[In]()> ByVal hwndTab As IntPtr, <[In]()> ByVal hwndMDI As Integer, <[In]()> ByVal tbatFlags As TBATFLAG)
Sub ThumbBarAddButtons(<[In]()> ByVal hwnd As IntPtr, <[In]()> ByVal cButtons As UInt32, <[In]()> ByRef pButton As tagTHUMBBUTTON)
Sub ThumbBarUpdateButtons(<[In]()> ByVal hwnd As IntPtr, <[In]()> ByVal cButtons As UInt32, <[In]()> ByRef pButton As tagTHUMBBUTTON)
Sub ThumbBarSetImageList(<[In]()> ByVal hwnd As IntPtr, <[In](), MarshalAs(UnmanagedType.IUnknown)> ByVal himl As Object)
Sub SetOverlayIcon(<[In]()> ByVal hwnd As IntPtr, <[In]()> ByVal hIcon As IntPtr, <[In](), MarshalAs(UnmanagedType.LPWStr)> ByVal pszDescription As String)
Sub SetThumbnailTooltip(<[In]()> ByVal hwnd As IntPtr, <[In](), MarshalAs(UnmanagedType.LPWStr)> ByVal pszTip As String)
Sub SetThumbnailClip(<[In]()> ByVal hwnd As IntPtr, <[In]()> ByRef prcClip As tagRECT)
End Interface
- 3/31/2009
- dmex
- 9/24/2009
- Tim Roberts