ITaskbarList3::SetProgressState-Methode (shobjidl_core.h)

Artikel
08/26/2023

Legt den Typ und den Status der Statusanzeige fest, die auf einer Taskleistenschaltfläche angezeigt wird.

Syntax

HRESULT SetProgressState(
  [in] HWND    hwnd,
  [in] TBPFLAG tbpFlags
);

Parameter

[in] hwnd

Typ: HWND

Das Handle des Fensters, in dem der Fortschritt eines Vorgangs angezeigt wird. Die dem Fenster zugeordnete Taskleistenschaltfläche zeigt die Statusanzeige an.

[in] tbpFlags

Typ: TBPFLAG

Flags, die den aktuellen Status der Statusschaltfläche steuern. Geben Sie nur eines der folgenden Flags an: alle Zustände schließen sich gegenseitig von allen anderen aus.

TBPF_NOPROGRESS (0x00000000)

Beendet die Anzeige des Fortschritts und versetzt die Schaltfläche in ihren normalen Zustand zurück. Rufen Sie diese Methode mit diesem Flag auf, um die Statusanzeige zu schließen, wenn der Vorgang abgeschlossen oder abgebrochen wird.

TBPF_INDETERMINATE (0x00000001)

Die Statusanzeige wächst nicht, sondern wechselt wiederholt entlang der Länge der Taskleistenschaltfläche. Dies gibt die Aktivität an, ohne anzugeben, welcher Anteil des Fortschritts abgeschlossen ist. Der Fortschritt ist im Gange, aber es gibt keine Vorhersage, wie lange der Vorgang dauern wird.

TBPF_NORMAL (0x00000002)

Der Statusindikator wächst von links nach rechts im Verhältnis zur geschätzten Menge des abgeschlossenen Vorgangs. Dies ist ein bestimmter Fortschrittsindikator; es wird eine Vorhersage über die Dauer des Vorgangs getroffen.

TBPF_ERROR (0x00000004)

Die Statusanzeige wird rot, um anzuzeigen, dass ein Fehler in einem der Fenster aufgetreten ist, das den Status sendet. Dies ist ein bestimmter Zustand. Wenn sich der Statusindikator im unbestimmten Zustand befindet, wechselt er zu einer roten, bestimmenden Anzeige eines generischen Prozentsatzes, der nicht auf den tatsächlichen Fortschritt hinweist.

TBPF_PAUSED (0x00000008)

Die Statusanzeige wird gelb, um anzuzeigen, dass der Fortschritt derzeit in einem der Fenster beendet wird, aber vom Benutzer fortgesetzt werden kann. Es ist keine Fehlerbedingung vorhanden, und nichts hindert den Fortschritt daran, den Fortschritt fortzusetzen. Dies ist ein bestimmter Zustand. Wenn sich der Statusindikator im unbestimmten Zustand befindet, wechselt er zu einer gelben, bestimmenden Anzeige eines generischen Prozentsatzes, der nicht auf den tatsächlichen Fortschritt hinweist.

Rückgabewert

Typ: HRESULT

Wenn diese Methode erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Statusanzeigeninformationen werden in Farbschemas mit hohem Kontrast nicht angezeigt, um sicherzustellen, dass keine Barrierefreiheitsanforderungen beeinträchtigt werden.

Entwickler, die mit dem vorhandenen Statusleisten-Steuerelement vertraut sind, sollten die Statusanzeige der Taskleistenschaltfläche sowohl in Konzepten als auch visuals als ähnlich empfinden. Hier wird die Taskleistenschaltfläche selbst zu einer Statusanzeige. Die Statusanzeige einer Taskleistenschaltfläche sollte eine detailliertere Statusanzeige im zugeordneten Fenster sein. Auf diese Weise kann der Benutzer Bestimmtes anzeigen, z. B. die Anzahl des Prozentsatzes und die verbleibende Zeit, die nicht in einer Taskleistenschaltfläche angezeigt werden können. Da eine Taskleistenschaltfläche den Fortschritt eines einzelnen Fensters in einer Gruppe anzeigen kann, kann der Benutzer den Fortschritt einzelner Fenster überprüfen. Außerdem werden dem Benutzer Statusinformationen bereitgestellt, wenn die Taskleistenschaltfläche nicht möglich ist, z. B. in einem Farbschema mit hohem Kontrast.

Beachten Sie, dass eine Statusleiste der Taskleiste für Schaltflächen nicht für die Verwendung mit normalerweise peripheren Aktionen wie dem Laden einer Webseite oder dem Drucken eines Dokuments vorgesehen ist. Dieser Statustyp sollte weiterhin in der status leiste eines Fensters angezeigt werden.

Die Statusanzeige wird zwischen dem Symbol oder Text der Taskleistenschaltfläche und dem Hintergrund angezeigt. Wenn der Fortschritt sowohl für die aktive Taskleistenschaltfläche als auch für eine inaktive Schaltfläche angezeigt wird, ist die Schattierung in den jeweiligen Statusanzeigen so, dass die aktive Schaltfläche für den Benutzer weiterhin offensichtlich ist. Außerdem funktionieren Schaltflächenfunktionen wie die Anzeige von Miniaturansichten weiterhin normal, wenn die Schaltfläche zum Anzeigen des Fortschritts verwendet wird.

Wenn Sie einen Fehler oder einen angehaltenen Zustand beenden, rufen Sie diese Methode erneut mit dem TBPF_NORMAL - oder TBPF_INDETERMINATE-Flag auf, um im ursprünglichen Zustand fortzufahren, oder TBPF_NOPROGRESS , wenn der Vorgang abgebrochen wird.

Wie die Taskleistenschaltfläche den Statusindikator für eine Gruppe auswäht

Die Taskleistenschaltfläche kann jeweils nur für ein Fenster eine Statusanzeige anzeigen. Dies schließt die Situation ein, in der die Taskleistenschaltfläche eine Gruppe darstellt und mehr als ein Fenster in dieser Gruppe Statusinformationen sendet. In diesem Fall wählt die Taskleistenschaltfläche die Statusanzeige basierend auf der Statuspriorität aus. Die Statuspriorität wird in der folgenden Tabelle mit der höchsten Priorität 1 angezeigt.

Priority	State
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

Das Ändern des Status eines Fensters ändert seine Priorität im Verhältnis zu anderen Fenstern in der Gruppe, was wiederum ändern kann, welches Fenster in einer Gruppe für die Statusanzeige in der Taskleistenschaltfläche verwendet wird.

Im Falle einer Prioritätskollision zwischen zwei Fenstern, die den statusbestimmenden Status übertragen, wird das Fenster mit dem geringsten Fortschritt verwendet.

Basierend auf dieser Priorität kann die Unbestimmte Statusanzeige nur in den folgenden Fällen auf der Taskleistenschaltfläche angezeigt werden:

Die Taskleistenschaltfläche stellt keine Gruppe dar, und das einzelne Fenster, das sie darstellt, hat TBPF_INDETERMINATE festgelegt.
Die Taskleistenschaltfläche stellt eine Gruppe dar. Nur ein Fenster in dieser Gruppe sendet Statusinformationen, und dieses Fenster hat TBPF_INDETERMINATE festgelegt.
Die Taskleistenschaltfläche stellt eine Gruppe dar, mehrere Fenster in dieser Gruppe senden Statusinformationen, und alle diese Fenster haben TBPF_INDETERMINATE festgelegt.

In diesen Fällen kann ein bestimmter Statusindikator angezeigt werden:

Die Taskleistenschaltfläche stellt keine Gruppe dar, und das einzelne Fenster, das sie darstellt, sendet bestimmte Statusinformationen.
Die Taskleistenschaltfläche stellt eine Gruppe dar. Nur ein Fenster in dieser Gruppe sendet Statusinformationen, und dieses Fenster sendet festgelegte Statusinformationen.
Die Taskleistenschaltfläche stellt eine Gruppe dar. Mehrere Fenster in dieser Gruppe senden Statusinformationen, mindestens eines dieser Fenster sendet bestimmte Statusinformationen, und kein Fenster hat TBPF_ERROR oder TBPF_PAUSED festgelegt.

Beachten Sie, dass ein Aufruf von SetProgressValue eine Statusanzeige, die sich derzeit in einem unbestimmten Modus (TBPF_INDETERMINATE) befindet, in eine normale (bestimmte) Anzeige umschaltet und das flag TBPF_INDETERMINATE gelöscht wird.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shobjidl_core.h (shobjidl.h einschließen)
Bibliothek	Explorerframe.lib
DLL	Explorerframe.dll