Fonction TaskDialog (commctrl.h)

  • Article

La fonction TaskDialog crée, affiche et exploite une boîte de dialogue de tâche. La boîte de dialogue de tâche contient le texte et le titre du message défini par l’application, les icônes et toute combinaison de boutons push prédéfinis. Cette fonction ne prend pas en charge l’inscription d’une fonction de rappel pour recevoir des notifications.

Syntaxe

HRESULT TaskDialog(
  [in]  HWND                           hwndOwner,
  [in]  HINSTANCE                      hInstance,
  [in]  PCWSTR                         pszWindowTitle,
  [in]  PCWSTR                         pszMainInstruction,
  [in]  PCWSTR                         pszContent,
  [in]  TASKDIALOG_COMMON_BUTTON_FLAGS dwCommonButtons,
  [in]  PCWSTR                         pszIcon,
  [out] int                            *pnButton
);

Paramètres

[in] hwndOwner

Type : HWND

Gérer vers la fenêtre propriétaire de la boîte de dialogue de tâche à créer. Si ce paramètre a la valeur NULL, la boîte de dialogue de tâche n’a pas de fenêtre propriétaire.

[in] hInstance

Type : HINSTANCE

Gérez le module qui contient la ressource d’icône identifiée par le membre pszIcon et les ressources de chaîne identifiées par les membres pszWindowTitle et pszMainInstruction . Si ce paramètre a la valeur NULL, pszIcon doit avoir la valeur NULL ou un pointeur vers une chaîne Unicode terminée par null qui contient un identificateur de ressource système, par exemple, TD_ERROR_ICON.

[in] pszWindowTitle

Type : PCWSTR

Pointeur vers la chaîne à utiliser pour le titre de la boîte de dialogue de tâche. Ce paramètre est une chaîne Unicode terminée par null qui contient du texte ou un identificateur de ressource entier transmis via la macro MAKEINTRESOURCE . Si ce paramètre a la valeur NULL, le nom de fichier du programme exécutable est utilisé.

[in] pszMainInstruction

Type : PCWSTR

Pointeur vers la chaîne à utiliser pour l’instruction main. Ce paramètre est une chaîne Unicode terminée par null qui contient du texte ou un identificateur de ressource entier transmis via la macro MAKEINTRESOURCE . Ce paramètre peut avoir la valeur NULL si aucune instruction main n’est souhaitée.

[in] pszContent

Type : PCWSTR

Pointeur vers une chaîne utilisée pour le texte supplémentaire qui apparaît sous l’instruction main, dans une police plus petite. Ce paramètre est une chaîne Unicode terminée par null qui contient du texte ou un identificateur de ressource entier transmis via la macro MAKEINTRESOURCE . Peut avoir la valeur NULL si aucun texte supplémentaire n’est recherché.

[in] dwCommonButtons

Type : TASKDIALOG_COMMON_BUTTON_FLAGS

Spécifie les boutons push affichés dans la boîte de dialogue. Ce paramètre peut être une combinaison d’indicateurs du groupe suivant.

Note Si aucun bouton n’est spécifié, la boîte de dialogue contient le bouton OK par défaut.
 
Valeur Signification
TDCBF_OK_BUTTON
 La boîte de dialogue de tâche contient le bouton push : OK.
TDCBF_YES_BUTTON
 La boîte de dialogue de tâche contient le bouton push : Oui.
TDCBF_NO_BUTTON
 La boîte de dialogue de tâche contient le bouton push : Non.
TDCBF_CANCEL_BUTTON
 La boîte de dialogue de tâche contient le bouton push : Annuler. Ce bouton doit être spécifié pour que la boîte de dialogue réponde aux actions d’annulation classiques (Alt-F4 et Échappement).
TDCBF_RETRY_BUTTON
 La boîte de dialogue de tâche contient le bouton push : Réessayer.
TDCBF_CLOSE_BUTTON
 La boîte de dialogue de tâche contient le bouton push : Fermer.

[in] pszIcon

Type : PCWSTR

Pointeur vers une chaîne qui identifie l’icône à afficher dans la boîte de dialogue de tâche. Ce paramètre doit être un identificateur de ressource entier passé à la macro MAKEINTRESOURCE ou à l’une des valeurs prédéfinies suivantes. Si ce paramètre a la valeur NULL, aucune icône ne s’affiche. Si le paramètre hInstance a la valeur NULL et qu’une des valeurs prédéfinies n’est pas utilisée, la fonction TaskDialog échoue.

Valeur Signification
TD_ERROR_ICON
 Une icône de signe d’arrêt s’affiche dans la boîte de dialogue de tâche.
TD_INFORMATION_ICON
 Une icône composée d’une lettre minuscule i dans un cercle apparaît dans la boîte de dialogue de la tâche.
TD_SHIELD_ICON
 Une icône de bouclier de sécurité s’affiche dans la boîte de dialogue de la tâche.
TD_WARNING_ICON
 Une icône de point d’exclamation s’affiche dans la boîte de dialogue de la tâche.

[out] pnButton

Type : int*

Lorsque cette fonction retourne, contient un pointeur vers un emplacement entier qui reçoit l’une des valeurs suivantes :

Valeur Description
0 Échec de l’appel de fonction. Pour plus d’informations, reportez-vous à la valeur de retour.
IDCANCEL Le bouton Annuler a été sélectionné, la touche Alt-F4 a été enfoncée, la touche Échappement a été enfoncée ou l’utilisateur a cliqué sur le bouton fermer la fenêtre .
IDNO Aucun bouton n’a été sélectionné.
IDOK Le bouton OK a été sélectionné.
IDRETRY Le bouton Réessayer a été sélectionné.
IDYES Le bouton Oui a été sélectionné.
IDCLOSE Le bouton Fermer a été sélectionné.
 

Si cette valeur est NULL, aucune valeur n’est retournée.

Valeur retournée

Type : HRESULT

Cette fonction peut retourner l’une de ces valeurs.

Code de retour Description
S_OK
 L’opération s’est terminée avec succès.
E_OUTOFMEMORY
 La mémoire est insuffisante pour terminer l’opération.
E_INVALIDARG
 Un ou plusieurs arguments ne sont pas valides.
E_FAIL
 L'opération a échoué.

Remarques

Lorsque vous utilisez une boîte de dialogue de tâche pour indiquer que le système est faible en mémoire, les chaînes pointées par les paramètres pszMainInstruction et pszWindowTitle ne doivent pas être extraites d’un fichier de ressources, car une tentative de chargement de la ressource peut échouer.

Si vous créez une boîte de dialogue de tâche alors qu’une boîte de dialogue est présente, utilisez un handle dans la boîte de dialogue comme paramètre hWndParent . Le paramètre hWndParent ne doit pas identifier une fenêtre enfant, telle qu’un contrôle dans une boîte de dialogue.

Étant donné que les boîtes de dialogue de tâche utilisent les éléments d’interface utilisateur définis par le système appropriés, vous devez les utiliser au lieu d’utiliser des boîtes de message créées avec la fonction MessageBox . Pour obtenir plus de fonctionnalités, utilisez TaskDialogIndirect.

L’exemple de code suivant, à inclure dans le cadre d’un programme plus large, montre comment créer une boîte de dialogue de tâche et capturer des entrées.


int nButtonPressed = 0;
TaskDialog(NULL, hInst, 
    MAKEINTRESOURCE(IDS_APPLICATION_TITLE),
    MAKEINTRESOURCE(IDS_DOSOMETHING), 
    MAKEINTRESOURCE(IDS_SOMECONTENT), 
    TDCBF_OK_BUTTON | TDCBF_CANCEL_BUTTON,
    TD_WARNING_ICON, 
    &nButtonPressed);

if (IDOK == nButtonPressed)
{
    // OK button pressed
}
else if (IDCANCEL == nButtonPressed)
{
    // Cancel pressed
}

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau uniquement]
Plateforme cible Windows
En-tête commctrl.h (include Commctrl.h)
Bibliothèque Comctl32.lib
DLL Comctl32.dll (version 6)

Voir aussi

Boîtes de dialogue