RadTaskbarButton
Represents a taskbar button that provides enhanced taskbar functionality including progress indicators, overlay icons, thumbnail previews, and thumbnail toolbar buttons.
Definition
Namespace:Telerik.WinControls.UI
Assembly:Telerik.WinControls.UI.dll
Syntax:
public class RadTaskbarButton : Component, IComponent, IDisposableInheritance: objectMarshalByRefObjectComponentRadTaskbarButton
Implements:
Constructors
Initializes a new instance of the RadTaskbarButton class with default settings.
public RadTaskbarButton()Fields
The maximum number of thumbnail buttons that can be added to the taskbar button thumbnail toolbar. This limitation is imposed by the Windows API.
public const int MaxThumbnailButtonsCount = 7Properties
Gets or sets the control whose bounds will define the visible area in the thumbnail preview.
public Control ClipControl { get; set; }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 Empty. Set to null to show the entire form in the thumbnail.
Gets or sets the rectangular area of the form that will be shown in the thumbnail preview.
public Rectangle ClipRectangle { get; set; }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 Empty to show the entire form in the thumbnail.
Gets or sets the overlay icon that will be displayed over the taskbar button to indicate application status.
public Bitmap OverlayIcon { get; set; }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.
Gets or sets the form that is represented on the taskbar and will receive the enhanced taskbar functionality.
public Form OwnerForm { get; set; }The form must have 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.
Gets or sets the progress value displayed as a percentage (0-100) on the taskbar button progress indicator.
public int ProgressPercentage { get; set; }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.
Gets or sets the progress state that determines how the progress indicator is displayed on the taskbar button.
public TaskbarProgressState ProgressState { get; set; }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).
Gets or sets the site that binds the component to its container and enables communication with the design-time environment.
public override ISite Site { get; set; }Overrides:
When the component is used in a designer, this property automatically sets the OwnerForm to the root component if it is a form.
Gets the collection of thumbnail buttons that will be displayed in the taskbar button thumbnail toolbar.
public ObservableCollection<RadThumbnailButton> ThumbnailButtons { get; }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 Shown event, the toolbar will be automatically created and populated. After the 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.
Gets or sets the ImageList that contains the images displayed by the thumbnail buttons.
[Browsable(true)]
public ImageList ThumbnailButtonsImageList { get; set; }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.
Gets or sets the tooltip text that appears when hovering over the taskbar button thumbnail.
public string ThumbnailTooltip { get; set; }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
Adds all buttons from the ThumbnailButtons collection to the taskbar thumbnail toolbar.
public virtual void AddThumbnailButtons()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.
Creates and returns a new filter window instance for handling Windows messages related to thumbnail toolbar interactions.
protected virtual TaskbarFilterWindow CreateFilterWindow()A new TaskbarFilterWindow instance.
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.
Releases the managed resources used by the RadTaskbarButton and optionally releases the unmanaged resources.
protected override void Dispose(bool disposing)True to release both managed and unmanaged resources; false to release only unmanaged resources.
Overrides:
Flashes the taskbar button to attract user attention without changing the active state of the window.
public void Flash(int count = 2147483647, int timeout = 0)The number of times the taskbar button will flash. Use MaxValue for infinite flashing until StopFlash() is called.
timeoutintThe rate at which the window flashes in milliseconds. Use 0 for the default cursor blink rate.
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.
Flashes the taskbar button until the window is activated by the user.
public void FlashUntilActive(int count = 2147483647, int timeout = 0)The maximum number of times the taskbar button will flash. Use MaxValue for infinite flashing until the application is focused or StopFlash() is called.
timeoutintThe rate at which the window flashes in milliseconds. Use 0 for the default cursor blink rate.
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.
Initializes the internal fields with their default values.
protected virtual void InitializeFields()Updates a specific thumbnail button after its properties have been changed.
public virtual void OnThumbnailButtonChanged(RadThumbnailButton button)The thumbnail button that has been modified and needs to be updated.
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.
Raises the ThumbnailButtonClick event when a thumbnail button is clicked.
protected virtual void OnThumbnailButtonClick(RadThumbnailButton button)The thumbnail button that was clicked.
This method can be overridden in derived classes to provide custom handling of thumbnail button clicks before or instead of raising the event.
Sets the overlay icon that appears on the taskbar button with optional accessibility text.
public void SetOverlayIcon(Bitmap image, string accessibilityText = null)The bitmap image to display as an overlay, or null to remove the overlay.
accessibilityTextstringOptional accessibility text that describes the overlay icon for screen readers.
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.
Sets the progress state that determines the visual appearance of the progress indicator on the taskbar button.
public void SetProgressState(TaskbarProgressState state)The progress state to apply to the taskbar button.
The progress state controls how the progress overlay is displayed: Normal (green), Error (red), Paused (yellow), Indeterminate (pulsing animation), or NoProgress (hidden).
Sets the progress value using absolute values for completed and total amounts.
public void SetProgressValue(int completed, int total)The number of completed units.
totalintThe total number of units.
This overload allows setting progress using absolute values rather than percentages. The progress percentage will be calculated as (completed / total) * 100.
Sets the progress value as a percentage (0-100) for the taskbar button progress indicator.
public void SetProgressValue(int percent)The progress value as a percentage from 0 to 100.
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.
Sets the thumbnail preview to show only the area occupied by the specified control.
public void SetThumbnailClip(Control clipControl)The control whose bounds will define the visible thumbnail area, or null to show the entire form.
This method provides a convenient way to focus the thumbnail preview on a specific control without manually calculating the control's screen coordinates.
Sets the thumbnail preview to show only the specified rectangular area of the form.
public void SetThumbnailClip(Rectangle clipRect)The rectangle defining the visible thumbnail area, or Empty to show the entire form.
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.
Sets the tooltip text that appears when hovering over the taskbar button thumbnail.
public void SetThumbnialTooltip(string thumbnailTooltip)The tooltip text to display, or null to use the default Windows behavior.
This tooltip is separate from the standard Windows tooltip and can provide additional context or status information about the application state.
Updates all taskbar features including thumbnail buttons, overlay icon, progress state, and thumbnail settings.
public virtual void UpdateAll()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.
Updates all thumbnail buttons in the toolbar after changes have been made to button properties.
public virtual void UpdateThumbnailButtons()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
Occurs when a thumbnail button in the taskbar toolbar is clicked by the user.
public event ThumbnailButtonEventHandler ThumbnailButtonClickThis 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.