Metodo ITaskbarList3::SetProgressValue (shobjidl_core.h)

Articolo
03/02/2024

Visualizza o aggiorna un indicatore di stato ospitato in un pulsante della barra delle applicazioni per visualizzare la percentuale specifica completata dell'operazione completa.

Sintassi

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

Parametri

[in] hwnd

Tipo: HWND

Handle della finestra il cui pulsante della barra delle applicazioni associato viene utilizzato come indicatore di stato.

[in] ullCompleted

Tipo: ULONGLONG

Valore definito dall'applicazione che indica la proporzione dell'operazione completata al momento della chiamata al metodo.

[in] ullTotal

Tipo: ULONGLONG

Valore definito dall'applicazione che specifica il valore ullCompleted avrà al termine dell'operazione.

Valore restituito

Tipo: HRESULT

Se questo metodo ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

Ciclo di vita dell'indicatore di stato determinato

Un'applicazione chiama innanzitutto SetProgressValue per avviare la visualizzazione di un indicatore di stato determinato e quindi lo chiama nuovamente in base alle esigenze per aggiornare la barra man mano che cambia lo stato di avanzamento. Al termine dell'avanzamento, l'applicazione deve chiamare SetProgressState con il flag TBPF_NOPROGRESS per ignorare l'indicatore di stato.

Come il pulsante della barra delle applicazioni sceglie l'indicatore di stato per un gruppo

Il pulsante della barra delle applicazioni può visualizzare un indicatore di stato per una sola finestra alla volta. Quando il pulsante della barra delle applicazioni rappresenta un gruppo e più finestre di tale gruppo trasmettono informazioni sullo stato di avanzamento, il pulsante della barra delle applicazioni sceglie la visualizzazione dello stato in base alla priorità di stato seguente.

Priorità	State
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

A meno che SetProgressState non abbia impostato uno stato di blocco (TBPF_ERROR o TBPF_PAUSED) per la finestra, una chiamata a SetProgressValue presuppone lo stato TBPF_NORMAL anche se non è impostato in modo esplicito. Una chiamata a SetProgressValue esegue l'override e cancella lo stato TBPF_INDETERMINATE.

Nel caso di una collisione di priorità in cui due finestre trasmettono lo stato di avanzamento determinato, viene usata la finestra con il minimo stato di avanzamento.

In base a tale priorità, questo indicatore di stato determinato (percentuale specifica) può essere visualizzato in questi casi:

Il pulsante della barra delle applicazioni non rappresenta un gruppo e la singola finestra che rappresenta trasmette informazioni sullo stato di avanzamento determinate tramite questo metodo.
Il pulsante della barra delle applicazioni rappresenta un gruppo, una sola finestra del gruppo trasmette informazioni sullo stato di avanzamento e tale finestra trasmette informazioni sullo stato di avanzamento determinate tramite questo metodo.
Il pulsante della barra delle applicazioni rappresenta un gruppo, più finestre in tale gruppo trasmettono informazioni sullo stato di avanzamento, almeno una di queste finestre trasmette informazioni sullo stato di avanzamento tramite questo metodo e nessuna di queste finestre ha impostato lo stato TBPF_ERROR o TBPF_PAUSED .

Se una finestra del gruppo ha impostato TBPF_ERROR o TBPF_PAUSED, tale stato verrà utilizzato per la visualizzazione del pulsante. Tuttavia, è comunque possibile effettuare chiamate a SetProgressValue in altre finestre sbloccate nel gruppo per aggiornarne lo stato in background.

Esempio

Ecco un esempio di come un'applicazione può usare ITaskbarList3 per visualizzare lo stato di avanzamento durante l'esecuzione delle operazioni.

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;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7 [solo app desktop]
Server minimo supportato	Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shobjidl_core.h (include Shobjidl.h)
Libreria	Explorerframe.lib
DLL	Explorerframe.dll