The TaskbarButton class represents the Windows taskbar button for a top-level window. More...

Public Types
enum	ProgressState { Hidden , Busy , Normal , Stopped , Paused }

Public Slots
void	clearOverlayIcon ()

void	resetProgress ()

void	setOverlayAccessibleDescription (const QString &description)

void	setOverlayIcon (const QIcon &icon)

void	setProgressMaximum (int progressMaximum)

void	setProgressMinimum (int progressMinimum)

void	setProgressRange (int progressMinimum, int progressMaximum)

void	setProgressState (TaskbarButton::ProgressState progressState)

void	setProgressValue (int progressValue)

Signals
void	progressMaximumChanged (int progressMaximum)

void	progressMinimumChanged (int progressMinimum)

void	progressStateChanged (TaskbarButton::ProgressState progressState)

void	progressValueChanged (int progressValue)

Public Member Functions
	TaskbarButton (QObject *parent=nullptr)

	~TaskbarButton ()

QString	overlayAccessibleDescription () const

QIcon	overlayIcon () const

int	progressMaximum () const

int	progressMinimum () const

ProgressState	progressState () const

int	progressValue () const

void	setWindow (QWindow *window)

QWindow *	window () const

Properties
QString	overlayAccessibleDescription
	The description of the overlay for accessibility purposes.

QIcon	overlayIcon
	The overlay icon of the taskbar button.

int	progressMaximum
	The maximum value of the progress indicator.

int	progressMinimum
	The minimum value of the progress indicator.

ProgressState	progressState
	The display state of the progress indicator.

int	progressValue
	The current value of the progress indicator.

QWindow *	window
	The window whose taskbar button is manipulated.

Detailed Description

A TaskbarButton instance enables one to manipulate the overlay icon, overlay accessibility description, and progress indicator of the taskbar button that its connected window is associated with.

An overlay icon indicates change in the state of an application, whereas a progress indicator shows how time-consuming tasks are progressing.

The following example code illustrates how to use the TaskbarButton class to adjust the look of the taskbar button:

// Create a taskbar button interface
TaskbarButton* button = new TaskbarButton(widget);
 
// Connect the window to the widgets window
button->setWindow(widget->windowHandle());
 
// Change the button's overlay icon
button->setOverlayIcon(QIcon(":/loading.png"));
 
// Change the button's progress indicator
button->setProgressState(Qx::TaskbarButton::ProgressState::Normal);
progress->setValue(50);

Note: QWidget::windowHandle() returns a valid instance of a QWindow only after the widget has been shown. It is therefore recommended to delay the initialization of the TaskbarButton instances until QWidget::showEvent().

Progress:

: A progress indicator is used to give the user an indication of the progress of an operation and to reassure them that the application is still running.

: The progress indicator uses the concept of steps. It is set up by specifying the minimum and maximum possible step values, and it will display the percentage of steps that have been completed when you later give it the current step value. The percentage is calculated by dividing the progress (progressValue() - progressMinimum()) divided by progressMaximum() - progressMinimum().

: The minimum and maximum number of steps can be specified by calling setProgressMinimum() and setProgressMaximum(). The current number of steps is set with setProgressValue(). The progress indicator can be rewound to the beginning with resetProgress().

: If progressMinimum and progressMaximum both are set to 0, the indicator state is automatically changed to Busy if it was previously Normal. This is useful when it is not possible to determine the number of steps. The progress state will be returned to normal when non-zero progress range is set and progress changes.

The different progress states of a taskbar button (at 50% progress)
Progress State	Appearance
Hidden
Busy
Normal
Stopped
Paused

Note: The final appearance of the progress indicator varies depending on the active Windows theme.

Member Enumeration Documentation

◆ ProgressState

enum Qx::TaskbarButton::ProgressState

This enum represents the display state of a task bar button's progress indicator.

Enumerator
Hidden	The progress indicator is hidden.
Busy	The progress indicator is stylized to indicate progress is indeterminate.
Normal	The progress indicator is in a normal state.
Stopped	The progress indicator is stylized to indicate progress has been stopped.
Paused	The progress indicator is stylized to indicate progress has been paused.

Constructor & Destructor Documentation

◆ TaskbarButton()

Qx::TaskbarButton::TaskbarButton ( QObject * parent = nullptr )

explicit

Constructs a TaskbarButton with the specified parent.

If parent is an instance of QWindow, it is automatically assigned as the taskbar button's window.

◆ ~TaskbarButton()

Qx::TaskbarButton::~TaskbarButton ( )

Destroys the TaskbarButton.

Member Function Documentation

◆ clearOverlayIcon

void Qx::TaskbarButton::clearOverlayIcon ( )

slot

Clears the taskbar button's icon overlay and its description, if any.

◆ overlayAccessibleDescription()

QString Qx::TaskbarButton::overlayAccessibleDescription ( ) const

Returns the taskbar button's current overlay description.

◆ overlayIcon()

QIcon Qx::TaskbarButton::overlayIcon ( ) const

Returns the taskbar button's current icon overlay.

◆ progressMaximum()

int Qx::TaskbarButton::progressMaximum ( ) const

Returns the maximum value of the taskbar button's progress indicator.

◆ progressMaximumChanged

void Qx::TaskbarButton::progressMaximumChanged ( int progressMaximum )

signal

This signal is emitted whenever the taskbar button's maximum progress value changes.

◆ progressMinimum()

int Qx::TaskbarButton::progressMinimum ( ) const

Returns the minimum value of the taskbar button's progress indicator.

◆ progressMinimumChanged

void Qx::TaskbarButton::progressMinimumChanged ( int progressMinimum )

signal

This signal is emitted whenever the taskbar button's minimum progress value changes.

◆ progressState()

TaskbarButton::ProgressState Qx::TaskbarButton::progressState ( ) const

Returns the display state of the taskbar button's progress indicator.

◆ progressStateChanged

void Qx::TaskbarButton::progressStateChanged ( TaskbarButton::ProgressState progressState )

signal

This signal is emitted whenever the taskbar button's progress display state changes.

◆ progressValue()

int Qx::TaskbarButton::progressValue ( ) const

Returns the current value of the taskbar button's progress indicator.

◆ progressValueChanged

void Qx::TaskbarButton::progressValueChanged ( int progressValue )

signal

This signal is emitted whenever the taskbar button's current progress value changes.

◆ resetProgress

void Qx::TaskbarButton::resetProgress ( )

slot

Resets the current value of the taskbar button's progress indicator to the minimum value.

◆ setOverlayAccessibleDescription

void Qx::TaskbarButton::setOverlayAccessibleDescription ( const QString & description )

slot

Sets the taskbar button's icon overlay description to description.

◆ setOverlayIcon

void Qx::TaskbarButton::setOverlayIcon ( const QIcon & icon )

slot

Sets the taskbar button's icon overlay to icon.

◆ setProgressMaximum

void Qx::TaskbarButton::setProgressMaximum ( int progressMaximum )

slot

Sets the maximum value of the taskbar button's progress indicator.

◆ setProgressMinimum

void Qx::TaskbarButton::setProgressMinimum ( int progressMinimum )

slot

Sets the minimum value of the taskbar button's progress indicator.

◆ setProgressRange

void Qx::TaskbarButton::setProgressRange	(	int	progressMinimum,
		int	progressMaximum )

slot

Sets the minimum and maximum value of the taskbar button's progress indicator.

◆ setProgressState

void Qx::TaskbarButton::setProgressState ( TaskbarButton::ProgressState progressState )

slot

Sets the display state of the taskbar button's progress indicator.

◆ setProgressValue

void Qx::TaskbarButton::setProgressValue ( int progressValue )

slot

Sets the current value of the taskbar button's progress indicator.

◆ setWindow()

void Qx::TaskbarButton::setWindow ( QWindow * window )

Sets the taskbar button's associated window.

◆ window()

QWindow * Qx::TaskbarButton::window ( ) const

Returns the window that the taskbar button is currently associated with.

Property Documentation

◆ overlayAccessibleDescription

QString Qx::TaskbarButton::overlayAccessibleDescription

readwrite

See also: overlayIcon

◆ progressMaximum

int Qx::TaskbarButton::progressMaximum

readwrite

The default value is 100.

◆ progressMinimum

int Qx::TaskbarButton::progressMinimum

readwrite

The default value is 0.

◆ progressState

ProgressState Qx::TaskbarButton::progressState

readwrite

The default value is ProgressState::Hidden.

◆ progressValue

int Qx::TaskbarButton::progressValue

readwrite

The default value is 0.

The documentation for this class was generated from the following files:

qx-taskbarbutton.h
qx-taskbarbutton.cpp

Public Types

Public Slots

Signals

Public Member Functions

Properties

Detailed Description

Member Enumeration Documentation

◆ ProgressState

Constructor & Destructor Documentation

◆ TaskbarButton()

◆ ~TaskbarButton()

Member Function Documentation

◆ clearOverlayIcon

◆ overlayAccessibleDescription()

◆ overlayIcon()

◆ progressMaximum()

◆ progressMaximumChanged

◆ progressMinimum()

◆ progressMinimumChanged

◆ progressState()

◆ progressStateChanged

◆ progressValue()

◆ progressValueChanged

◆ resetProgress

◆ setOverlayAccessibleDescription

◆ setOverlayIcon

◆ setProgressMaximum

◆ setProgressMinimum

◆ setProgressRange

◆ setProgressState

◆ setProgressValue

◆ setWindow()

◆ window()

Property Documentation

◆ overlayAccessibleDescription

◆ progressMaximum

◆ progressMinimum

◆ progressState

◆ progressValue