ITaskbarList3::SetProgressValue-Methode (shobjidl_core.h)

Artikel
03/02/2024

Zeigt eine Statusleiste an, die in einer Taskleistenschaltfläche gehostet wird, oder aktualisiert sie, um den bestimmten Prozentsatz anzuzeigen, der für den vollständigen Vorgang abgeschlossen wurde.

Syntax

HRESULT SetProgressValue(
  [in] HWND      hwnd,
  [in] ULONGLONG ullCompleted,
  [in] ULONGLONG ullTotal
);

Parameter

[in] hwnd

Typ: HWND

Das Handle des Fensters, dessen zugeordnete Taskleistenschaltfläche als Statusanzeige verwendet wird.

[in] ullCompleted

Typ: ULONGLONG

Ein anwendungsdefinierter Wert, der den Anteil des Vorgangs angibt, der zum Zeitpunkt des Aufrufs der Methode abgeschlossen wurde.

[in] ullTotal

Typ: ULONGLONG

Ein anwendungsdefinierter Wert, der den Wert von ullCompleted angibt, wird nach Abschluss des Vorgangs angezeigt.

Rückgabewert

Typ: HRESULT

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

Hinweise

Bestimmen des Statusleistenlebenszyklus

Eine Anwendung ruft zuerst SetProgressValue auf, um mit der Anzeige einer bestimmten Statusanzeige zu beginnen, und ruft sie dann bei Bedarf erneut auf, um die Leiste zu aktualisieren, wenn sich der Fortschritt ändert. Wenn der Fortschritt abgeschlossen ist, muss die Anwendung SetProgressState mit dem flag TBPF_NOPROGRESS aufrufen, um die Statusanzeige zu schließen.

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. Wenn die Taskleistenschaltfläche eine Gruppe darstellt und mehrere Fenster in dieser Gruppe Statusinformationen senden, wählt die Taskleistenschaltfläche ihre Statusanzeige basierend auf der folgenden Statuspriorität aus.

Priority	State
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

Sofern SetProgressState keinen blockierenden Zustand (TBPF_ERROR oder TBPF_PAUSED) für das Fenster festgelegt hat, wird bei einem Aufruf von SetProgressValue der TBPF_NORMAL Zustand vorausgesetzt, auch wenn er nicht explizit festgelegt ist. Ein Aufruf von SetProgressValue überschreibt und löscht den TBPF_INDETERMINATE Zustand.

Bei einer Prioritätskollision, bei der zwei Fenster den Status bestimmen, wird das Fenster mit dem geringsten Fortschritt verwendet.

Basierend auf dieser Priorität kann dieser bestimmte Fortschrittsindikator (bestimmter Prozentsatz) in den folgenden Fällen angezeigt werden:

Die Taskleistenschaltfläche stellt keine Gruppe dar, und das einzelne Fenster, das sie darstellt, sendet bestimmte Statusinformationen über diese Methode.
Die Taskleistenschaltfläche stellt eine Gruppe dar. Nur ein Fenster in dieser Gruppe sendet Statusinformationen, und dieses Fenster sendet bestimmte Statusinformationen über diese Methode.
Die Taskleistenschaltfläche stellt eine Gruppe dar. Mehrere Fenster in dieser Gruppe senden Statusinformationen, mindestens eines dieser Fenster sendet Statusinformationen über diese Methode, und keines dieser Fenster hat den TBPF_ERROR oder TBPF_PAUSED Zustand festgelegt.

Wenn ein Fenster in der Gruppe TBPF_ERROR oder TBPF_PAUSED festgelegt hat, wird dieser Zustand für die Schaltflächenanzeige verwendet. Sie können jedoch weiterhin SetProgressValue für andere, nicht blockierte Fenster in der Gruppe aufrufen, um deren Fortschritt im Hintergrund zu aktualisieren.

Beispiele

Im Folgenden finden Sie ein Beispiel dafür, wie eine Anwendung ITaskbarList3 verwenden kann, um den Fortschritt während der Ausführung von Vorgängen anzuzeigen.

HRESULT CMyApp::ShowProgressInTaskbar(HWND hwnd, __in ITaskbarList3 *pTL)
{
    // Set the progress state of the button to indeterminate while you calculate
    // the number of operations to be performed.
    HRESULT hr = pTL->SetProgressState(hwnd, TBPF_INDETERMINATE);

    // Calculate the number of operations to perform.
    int cTotalOperations = _CalculateNumberOfOperationsToPerform();

    for (int i=0; i < cTotalOperations && SUCCEEDED(hr); i++)
    {
        // Update the progress. This call to SetProgressValue cancels the
        // indeterminate state and puts the button into normal progress mode.
        pTL->SetProgressValue(hwnd, i, cTotalOperations);
       
        // Do whatever operation your application needs to perform.
        hr = _PerformOperation(i);
    }

    // Tell the button that progress no longer needs to be displayed.
    pTL->SetProgressState(hwnd, TBPF_NOPROGRESS);
    
    return hr;
}

Anforderungen

Anforderung	Wert
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