ITaskbarList3 ::SetProgressValue, méthode (shobjidl_core.h)

Article
03/15/2023

Affiche ou met à jour une barre de progression hébergée dans un bouton de barre des tâches pour afficher le pourcentage spécifique de l’opération complète.

Syntaxe

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

Paramètres

[in] hwnd

Type : HWND

Handle de la fenêtre dont le bouton de barre des tâches associé est utilisé comme indicateur de progression.

[in] ullCompleted

Type : ULONGLONG

Valeur définie par l’application qui indique la proportion de l’opération qui a été terminée au moment où la méthode est appelée.

[in] ullTotal

Type : ULONGLONG

Valeur définie par l’application qui spécifie la valeur ullCompleted une fois l’opération terminée.

Valeur retournée

Type : HRESULT

Si cette méthode réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.

Remarques

Déterminer le cycle de vie de la barre de progression

Une application appelle d’abord SetProgressValue pour commencer l’affichage d’une barre de progression déterminé, puis l’appelle à nouveau si nécessaire pour mettre à jour la barre à mesure que la progression change. Une fois la progression terminée, l’application doit appeler SetProgressState avec l’indicateur TBPF_NOPROGRESS pour ignorer la barre de progression.

Comment le bouton de la barre des tâches choisit l’indicateur de progression d’un groupe

Le bouton de la barre des tâches peut afficher un indicateur de progression pour une seule fenêtre à la fois. Lorsque le bouton de la barre des tâches représente un groupe et que plusieurs fenêtres de ce groupe diffusent des informations de progression, le bouton de barre des tâches choisit son affichage de progression en fonction de la priorité d’état suivante.

Priorité	State
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

À moins que SetProgressState n’ait défini un état de blocage (TBPF_ERROR ou TBPF_PAUSED) pour la fenêtre, un appel à SetProgressValue suppose l’état TBPF_NORMAL même s’il n’est pas défini explicitement. Un appel à SetProgressValue remplace et efface l’état TBPF_INDETERMINATE.

Dans le cas d’une collision de priorité où deux fenêtres diffusent une progression déterminé, la fenêtre avec la progression la plus faible est utilisée.

En fonction de cette priorité, cet indicateur de progression déterminé (pourcentage spécifique) peut être affiché dans les cas suivants :

Le bouton de la barre des tâches ne représente pas un groupe et la fenêtre unique qu’il représente diffuse des informations de progression déterminés via cette méthode.
Le bouton de la barre des tâches représente un groupe, une seule fenêtre de ce groupe diffuse des informations de progression et cette fenêtre diffuse des informations de progression déterminés par le biais de cette méthode.
Le bouton de la barre des tâches représente un groupe, plusieurs fenêtres de ce groupe diffusent des informations de progression, au moins une de ces fenêtres diffuse des informations de progression via cette méthode, et aucune de ces fenêtres n’a défini l’état TBPF_ERROR ou TBPF_PAUSED .

Si une fenêtre du groupe a défini TBPF_ERROR ou TBPF_PAUSED, cet état est utilisé pour l’affichage du bouton. Toutefois, vous pouvez toujours effectuer des appels à SetProgressValue sur d’autres fenêtres débloquées du groupe pour mettre à jour leur progression en arrière-plan.

Exemples

Voici un exemple de la façon dont une application peut utiliser ITaskbarList3 pour afficher la progression pendant qu’elle effectue des opérations.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shobjidl_core.h (incluez Shobjidl.h)
Bibliothèque	Explorerframe.lib
DLL	Explorerframe.dll