Class RadTaskbarButton

Represents a taskbar button that provides enhanced taskbar functionality including progress indicators, overlay icons, thumbnail previews, and thumbnail toolbar buttons.

Inheritance
System.Object
RadTaskbarButton
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll

Syntax

public class RadTaskbarButton : Component, IThumbnailButtonOwner
Remarks

The RadTaskbarButton class enables applications to integrate with the Windows taskbar to provide rich user feedback and quick access features. It supports progress indicators with different states, overlay icons for status indication, thumbnail clipping for focused preview areas, and thumbnail toolbar buttons for quick actions directly from the taskbar preview. This component requires Windows 7 or higher and only works with forms that have System.Windows.Forms.Form.ShowInTaskbar set to true.

Constructors

RadTaskbarButton()

Initializes a new instance of the RadTaskbarButton class with default settings.

Declaration
public RadTaskbarButton()

Fields

MaxThumbnailButtonsCount

The maximum number of thumbnail buttons that can be added to the taskbar button thumbnail toolbar. This limitation is imposed by the Windows API.

Declaration
public const int MaxThumbnailButtonsCount = 7
Field Value
System.Int32

Remarks

For more information, see: https://learn.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-itaskbarlist3-thumbbaraddbuttons

Properties

ClipControl

Gets or sets the control whose bounds will define the visible area in the thumbnail preview.

Declaration
public Control ClipControl { get; set; }
Property Value
System.Windows.Forms.Control

Remarks

When set, the thumbnail preview will be clipped to show only the area occupied by the specified control. This provides a convenient way to focus the thumbnail on important content without manually calculating coordinates.

Setting this property will automatically reset the ClipRectangle property to System.Drawing.Rectangle.Empty. Set to null to show the entire form in the thumbnail.

ClipRectangle

Gets or sets the rectangular area of the form that will be shown in the thumbnail preview.

Declaration
public Rectangle ClipRectangle { get; set; }
Property Value
System.Drawing.Rectangle

Remarks

When set, only the specified rectangular area of the form will be visible in the taskbar thumbnail preview. This is useful for focusing the preview on a specific area of the application, such as the main content area.

Setting this property will automatically reset the ClipControl property to null. Set to System.Drawing.Rectangle.Empty to show the entire form in the thumbnail.

OverlayIcon

Gets or sets the overlay icon that will be displayed over the taskbar button to indicate application status.

Declaration
public Bitmap OverlayIcon { get; set; }
Property Value
System.Drawing.Bitmap

Remarks

The overlay icon appears as a small badge in the bottom-right corner of the taskbar button. It is typically used to indicate application state such as new messages, alerts, or status information. Set to null to remove the overlay icon.

OwnerForm

Gets or sets the form that is represented on the taskbar and will receive the enhanced taskbar functionality.

Declaration
public Form OwnerForm { get; set; }
Property Value
System.Windows.Forms.Form

Remarks

The form must have System.Windows.Forms.Form.ShowInTaskbar set to true for taskbar features to work. Taskbar functionality is only available on Windows 7 and higher operating systems. Setting this property will automatically initialize the necessary Windows API components if the requirements are met.

ProgressPercentage

Gets or sets the progress value displayed as a percentage (0-100) on the taskbar button progress indicator.

Declaration
public int ProgressPercentage { get; set; }
Property Value
System.Int32

Remarks

The progress percentage is only visible when ProgressState is set to Normal, Error, or Paused. Values are automatically clamped to the range 0-100. The progress bar appears as an overlay on the taskbar button.

ProgressState

Gets or sets the progress state that determines how the progress indicator is displayed on the taskbar button.

Declaration
public TaskbarProgressState ProgressState { get; set; }
Property Value
TaskbarProgressState

Remarks

The progress state controls the visual appearance of the progress bar overlay on the taskbar button. Different states provide different visual feedback: Normal (green), Error (red), Paused (yellow), Indeterminate (pulsing animation), or NoProgress (hidden).

Site

Gets or sets the site that binds the component to its container and enables communication with the design-time environment.

Declaration
public override ISite Site { get; set; }
Property Value
System.ComponentModel.ISite

Remarks

When the component is used in a designer, this property automatically sets the OwnerForm to the root component if it is a form.

ThumbnailButtons

Gets the collection of thumbnail buttons that will be displayed in the taskbar button thumbnail toolbar.

Declaration
public ObservableCollection<RadThumbnailButton> ThumbnailButtons { get; }
Property Value
System.Collections.ObjectModel.ObservableCollection<RadThumbnailButton>

Remarks

The thumbnail buttons represent a toolbar that appears below the application preview in the taskbar flyout. A maximum of MaxThumbnailButtonsCount buttons can be added to the collection.

If buttons are created at design time or before the System.Windows.Forms.Form.Shown event, the toolbar will be automatically created and populated. After the System.Windows.Forms.Form.Shown event, you must explicitly call AddThumbnailButtons() to create the toolbar.

Once a toolbar has been added, buttons can only be modified through UpdateThumbnailButtons(). Individual buttons cannot be added or removed, but they can be shown and hidden as needed. The toolbar itself cannot be removed without recreating the window.

ThumbnailButtonsImageList

Gets or sets the System.Windows.Forms.ImageList that contains the images displayed by the thumbnail buttons.

Declaration
public ImageList ThumbnailButtonsImageList { get; set; }
Property Value
System.Windows.Forms.ImageList

Implements
Remarks

This image list provides the icons for the thumbnail toolbar buttons. The ImageKey or ImageIndex properties of individual buttons reference images in this collection. Changes to this property automatically update all existing thumbnail buttons.

ThumbnailTooltip

Gets or sets the tooltip text that appears when hovering over the taskbar button thumbnail.

Declaration
public string ThumbnailTooltip { get; set; }
Property Value
System.String

Remarks

This tooltip is separate from the standard Windows tooltip that shows the window title. It can be used to provide additional context or status information about the application. Set to null or empty string to use the default Windows behavior.

Methods

AddThumbnailButtons()

Adds all buttons from the ThumbnailButtons collection to the taskbar thumbnail toolbar.

Declaration
public virtual void AddThumbnailButtons()
Remarks

Once this method is executed and a toolbar has been created, buttons can only be modified through UpdateThumbnailButtons(). Individual buttons cannot be added or removed after the toolbar is created, but they can be shown and hidden as needed. The toolbar itself cannot be removed without recreating the window.

If the toolbar has already been created, this method will call UpdateThumbnailButtons() instead. A maximum of MaxThumbnailButtonsCount buttons can be added.

CreateFilterWindow()

Creates and returns a new filter window instance for handling Windows messages related to thumbnail toolbar interactions.

Declaration
protected virtual TaskbarFilterWindow CreateFilterWindow()
Returns
TaskbarFilterWindow

A new TaskbarFilterWindow instance.
Remarks

This method is called internally to create the message filter window that processes thumbnail button click messages. Derived classes can override this method to provide custom filter window implementations.

Dispose(Boolean)

Releases the managed resources used by the RadTaskbarButton and optionally releases the unmanaged resources.

Declaration
protected override void Dispose(bool disposing)
Parameters
System.Boolean disposing

True to release both managed and unmanaged resources; false to release only unmanaged resources.

Flash(Int32, Int32)

Flashes the taskbar button to attract user attention without changing the active state of the window.

Declaration
public void Flash(int count = 2147483647, int timeout = 0)
Parameters
System.Int32 count

The number of times the taskbar button will flash. Use System.Int32.MaxValue for infinite flashing until StopFlash() is called.
System.Int32 timeout

The rate at which the window flashes in milliseconds. Use 0 for the default cursor blink rate.
Remarks

Flashing is typically used to inform the user that the window requires attention but does not currently have keyboard focus. When a window flashes, it appears to change from inactive to active status - an inactive caption bar changes to active and vice versa.

The flashing continues for the specified count or until StopFlash() is called.

FlashUntilActive(Int32, Int32)

Flashes the taskbar button until the window is activated by the user.

Declaration
public void FlashUntilActive(int count = 2147483647, int timeout = 0)
Parameters
System.Int32 count

The maximum number of times the taskbar button will flash. Use System.Int32.MaxValue for infinite flashing until the application is focused or StopFlash() is called.
System.Int32 timeout

The rate at which the window flashes in milliseconds. Use 0 for the default cursor blink rate.
Remarks

This method will not begin flashing if the window is currently active. The flashing automatically stops when the user activates the window.

This is particularly useful for applications that need to notify users of important events while respecting user focus.

InitializeFields()

Initializes the internal fields with their default values.

Declaration
protected virtual void InitializeFields()

OnThumbnailButtonChanged(RadThumbnailButton)

Updates a specific thumbnail button after its properties have been changed.

Declaration
public virtual void OnThumbnailButtonChanged(RadThumbnailButton button)
Parameters
RadThumbnailButton button

The thumbnail button that has been modified and needs to be updated.
Implements
Remarks

This method is called automatically when thumbnail button properties change, but can be called manually if needed. It updates only the specified button rather than all buttons for better performance.

OnThumbnailButtonClick(RadThumbnailButton)

Raises the ThumbnailButtonClick event when a thumbnail button is clicked.

Declaration
protected virtual void OnThumbnailButtonClick(RadThumbnailButton button)
Parameters
RadThumbnailButton button

The thumbnail button that was clicked.
Remarks

This method can be overridden in derived classes to provide custom handling of thumbnail button clicks before or instead of raising the event.

SetOverlayIcon(Bitmap, String)

Sets the overlay icon that appears on the taskbar button with optional accessibility text.

Declaration
public void SetOverlayIcon(Bitmap image, string accessibilityText = null)
Parameters
System.Drawing.Bitmap image

The bitmap image to display as an overlay, or null to remove the overlay.
System.String accessibilityText

Optional accessibility text that describes the overlay icon for screen readers.
Remarks

The overlay icon appears as a small badge in the bottom-right corner of the taskbar button. Providing accessibility text improves the experience for users with screen readers.

SetProgressState(TaskbarProgressState)

Sets the progress state that determines the visual appearance of the progress indicator on the taskbar button.

Declaration
public void SetProgressState(TaskbarProgressState state)
Parameters
TaskbarProgressState state

The progress state to apply to the taskbar button.
Remarks

The progress state controls how the progress overlay is displayed: Normal (green), Error (red), Paused (yellow), Indeterminate (pulsing animation), or NoProgress (hidden).

SetProgressValue(Int32)

Sets the progress value as a percentage (0-100) for the taskbar button progress indicator.

Declaration
public void SetProgressValue(int percent)
Parameters
System.Int32 percent

The progress value as a percentage from 0 to 100.
Remarks

The progress value is only visible when the progress state is Normal, Error, or Paused. Values outside the 0-100 range will be clamped automatically.

SetProgressValue(Int32, Int32)

Sets the progress value using absolute values for completed and total amounts.

Declaration
public void SetProgressValue(int completed, int total)
Parameters
System.Int32 completed

The number of completed units.
System.Int32 total

The total number of units.
Remarks

This overload allows setting progress using absolute values rather than percentages. The progress percentage will be calculated as (completed / total) * 100.

SetThumbnailClip(Rectangle)

Sets the thumbnail preview to show only the specified rectangular area of the form.

Declaration
public void SetThumbnailClip(Rectangle clipRect)
Parameters
System.Drawing.Rectangle clipRect

The rectangle defining the visible thumbnail area, or System.Drawing.Rectangle.Empty to show the entire form.
Remarks

The rectangle coordinates should be relative to the client area of the owner form. This method allows precise control over which part of the form appears in the thumbnail preview.

SetThumbnailClip(Control)

Sets the thumbnail preview to show only the area occupied by the specified control.

Declaration
public void SetThumbnailClip(Control clipControl)
Parameters
System.Windows.Forms.Control clipControl

The control whose bounds will define the visible thumbnail area, or null to show the entire form.
Remarks

This method provides a convenient way to focus the thumbnail preview on a specific control without manually calculating the control's screen coordinates.

SetThumbnialTooltip(String)

Sets the tooltip text that appears when hovering over the taskbar button thumbnail.

Declaration
public void SetThumbnialTooltip(string thumbnailTooltip)
Parameters
System.String thumbnailTooltip

The tooltip text to display, or null to use the default Windows behavior.
Remarks

This tooltip is separate from the standard Windows tooltip and can provide additional context or status information about the application state.

StopFlash()

Stops any ongoing flashing of the taskbar button immediately.

Declaration
public void StopFlash()
Remarks

This method can be called to stop flashing that was initiated by Flash(Int32, Int32) or FlashUntilActive(Int32, Int32). It is safe to call this method even if the window is not currently flashing.

UpdateAll()

Updates all taskbar features including thumbnail buttons, overlay icon, progress state, and thumbnail settings.

Declaration
public virtual void UpdateAll()
Remarks

This method is typically called automatically when the owner form is shown, but can be called manually to refresh all taskbar features after making multiple changes.

UpdateThumbnailButtons()

Updates all thumbnail buttons in the toolbar after changes have been made to button properties.

Declaration
public virtual void UpdateThumbnailButtons()
Remarks

After a thumbnail toolbar has been created with AddThumbnailButtons(), this is the only way to modify button properties. Individual buttons cannot be added or removed, but their properties (such as visibility, enabled state, and icons) can be updated.

This method updates all buttons in the toolbar. For updating a single button, use OnThumbnailButtonChanged(RadThumbnailButton) which is more efficient.

Events

ThumbnailButtonClick

Occurs when a thumbnail button in the taskbar toolbar is clicked by the user.

Declaration
public event ThumbnailButtonEventHandler ThumbnailButtonClick
Event Type
ThumbnailButtonEventHandler

Remarks

This event is raised after the individual button's internal click handling is processed. The event provides access to the clicked button through the ThumbnailButtonEventArgs parameter.

Extension Methods