ITaskbarList3::SetProgressState, méthode (shobjidl_core.h)
Définit le type et l’état de l’indicateur de progression affiché sur un bouton de barre des tâches.
Syntaxe
HRESULT SetProgressState(
[in] HWND hwnd,
[in] TBPFLAG tbpFlags
);
Paramètres
[in] hwnd
Type : HWND
Handle de la fenêtre dans laquelle la progression d’une opération est affichée. Le bouton de barre des tâches associé à cette fenêtre affiche la barre de progression.
[in] tbpFlags
Type : TBPFLAG
Indicateurs qui contrôlent l’état actuel du bouton de progression. Spécifiez un seul des indicateurs suivants : tous les états s’excluent mutuellement de tous les autres.
TBPF_NOPROGRESS (0x00000000)
Arrête l’affichage de la progression et retourne le bouton à son état normal. Appelez cette méthode avec cet indicateur pour ignorer la barre de progression lorsque l’opération est terminée ou annulée.
TBPF_INDETERMINATE (0x00000001)
L’indicateur de progression n’augmente pas en taille, mais il effectue des cycles répétés le long du bouton de la barre des tâches. Cela indique l’activité sans spécifier la proportion de la progression terminée. Des progrès sont en cours, mais il n’existe aucune prédiction quant à la durée de l’opération.
TBPF_NORMAL (0x00000002)
L’indicateur de progression augmente en taille de gauche à droite en proportion de la quantité estimée de l’opération terminée. Il s’agit d’un indicateur de progression déterminé; une prédiction est effectuée quant à la durée de l’opération.
TBPF_ERROR (0x00000004)
L’indicateur de progression devient rouge pour indiquer qu’une erreur s’est produite dans l’une des fenêtres qui diffuse la progression. Il s’agit d’un état déterminé. Si l’indicateur de progression est à l’état indéterminé, il passe à un affichage déterminé rouge d’un pourcentage générique qui n’indique pas la progression réelle.
TBPF_PAUSED (0x00000008)
L’indicateur de progression devient jaune pour indiquer que la progression est actuellement arrêtée dans l’une des fenêtres, mais qu’elle peut être reprise par l’utilisateur. Aucune condition d’erreur n’existe et rien n’empêche la progression de continuer. Il s’agit d’un état déterminé. Si l’indicateur de progression est à l’état indéterminé, il passe à un affichage déterminé jaune d’un pourcentage générique qui n’indique pas la progression réelle.
Valeur retournée
Type : HRESULT
Si cette méthode réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.
Remarques
Les informations de barre de progression ne sont pas affichées dans les jeux de couleurs à contraste élevé pour garantir qu’aucun besoin d’accessibilité n’est compromis.
Les développeurs habitués au contrôle de barre de progression existant doivent trouver l’indicateur de progression du bouton de la barre des tâches comme une expérience similaire à la fois dans le concept et les visuels. Ici, le bouton de la barre des tâches lui-même devient une barre de progression. L’indicateur de progression d’un bouton de barre des tâches doit être le reflet d’une barre de progression plus détaillée dans la fenêtre associée. Cela permet à l’utilisateur de voir des spécificités, telles que le nombre de pourcentages et la durée restante, qui ne peuvent pas être affichées dans un bouton de barre des tâches. En outre, étant donné qu’un bouton de barre des tâches peut afficher la progression d’une seule fenêtre dans un groupe, il permet à l’utilisateur d’case activée la progression des fenêtres individuelles. Il fournit également des informations sur la progression à l’utilisateur lorsque le bouton de la barre des tâches ne peut pas, par exemple dans un jeu de couleurs à contraste élevé.
Notez qu’une barre de progression de bouton de barre des tâches n’est pas destinée à être utilisée avec des actions normalement périphériques telles que le chargement d’une page web ou l’impression d’un document. Ce type de progression doit continuer à s’afficher dans la barre de status d’une fenêtre.
L’indicateur de progression s’affiche entre l’icône ou le texte du bouton de la barre des tâches et l’arrière-plan. Si la progression est affichée pour le bouton de barre des tâches actif et un bouton inactif, l’ombrage dans les barres de progression respectives est telle que le bouton actif est toujours évident pour l’utilisateur. En outre, les fonctionnalités de bouton telles que l’affichage des miniatures continuent de fonctionner normalement lorsque le bouton est utilisé pour afficher la progression.
Lorsque vous quittez un état d’erreur ou suspendu, appelez à nouveau cette méthode avec l’indicateur TBPF_NORMAL ou TBPF_INDETERMINATE pour continuer dans l’état d’origine ou TBPF_NOPROGRESS si l’opération est annulée.
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. Cela inclut la situation où le bouton de barre des tâches représente un groupe et où plusieurs fenêtres de ce groupe diffusent des informations sur la progression. Dans ce cas, le bouton de la barre des tâches choisit son affichage de progression en fonction de la priorité d’état. La priorité d’état est indiquée dans le tableau suivant, la priorité 1 étant la plus élevée.| Priorité | State |
|---|---|
| 1 | TBPF_ERROR |
| 2 | TBPF_PAUSED |
| 3 | TBPF_NORMAL |
| 4 | TBPF_INDETERMINATE |
La modification de l’état d’une fenêtre modifie sa priorité par rapport aux autres fenêtres du groupe, ce qui peut à son tour modifier la fenêtre d’un groupe utilisée pour l’indicateur de progression dans le bouton de la barre des tâches.
Dans le cas d’une collision de priorité entre deux fenêtres qui diffusent une progression déterminé, la fenêtre avec la progression la plus faible est utilisée.
En fonction de cette priorité, l’indicateur de progression indéterminée peut être affiché dans le bouton de la barre des tâches uniquement 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 a défini TBPF_INDETERMINATE.
- 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 a défini TBPF_INDETERMINATE.
- Le bouton de la barre des tâches représente un groupe, plusieurs fenêtres de ce groupe diffusent des informations de progression, et toutes ces fenêtres ont défini TBPF_INDETERMINATE.
Un indicateur de progression déterminé 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.
- 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.
- 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 précises et aucune fenêtre n’a défini TBPF_ERROR ou TBPF_PAUSED.
Notez qu’un appel à SetProgressValue bascule un indicateur de progression actuellement en mode indéterminé (TBPF_INDETERMINATE) vers un affichage normal (déterminé) et efface l’indicateur TBPF_INDETERMINATE .
Configuration requise
| 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 |