Funzione TaskDialog (commctrl.h)
La funzione TaskDialog crea, visualizza e gestisce una finestra di dialogo attività. La finestra di dialogo attività contiene testo e titolo del messaggio definiti dall'applicazione, icone e qualsiasi combinazione di pulsanti di push predefiniti. Questa funzione non supporta la registrazione di una funzione di callback per ricevere notifiche.
Sintassi
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
);
Parametri
[in] hwndOwner
Tipo: HWND
Handle per la finestra di proprietario della finestra di dialogo attività da creare. Se questo parametro è NULL, la finestra di dialogo attività non ha una finestra di proprietario.
[in] hInstance
Tipo: HINSTANCE
Gestire il modulo che contiene la risorsa icona identificata dal membro pszIcon e le risorse stringa identificate dai membri pszWindowTitle e pszMainInstruction . Se questo parametro è NULL, pszIcon deve essere NULL o un puntatore a una stringa Unicode con terminazione Null che contiene un identificatore di risorsa di sistema, ad esempio TD_ERROR_ICON.
[in] pszWindowTitle
Tipo: PCWSTR
Puntatore alla stringa da usare per il titolo della finestra di dialogo attività. Questo parametro è una stringa Unicode con terminazione Null che contiene testo o un identificatore di risorsa integer passato tramite la macro MAKEINTRESOURCE . Se questo parametro è NULL, viene usato il nome file del programma eseguibile.
[in] pszMainInstruction
Tipo: PCWSTR
Puntatore alla stringa da usare per l'istruzione principale. Questo parametro è una stringa Unicode con terminazione Null che contiene testo o un identificatore di risorsa integer passato tramite la macro MAKEINTRESOURCE . Questo parametro può essere NULL se non è necessaria alcuna istruzione principale.
[in] pszContent
Tipo: PCWSTR
Puntatore a una stringa utilizzata per testo aggiuntivo visualizzato sotto l'istruzione principale, in un tipo di carattere più piccolo. Questo parametro è una stringa Unicode con terminazione Null che contiene testo o un identificatore di risorsa integer passato tramite la macro MAKEINTRESOURCE . Può essere NULL se non si desidera testo aggiuntivo.
[in] dwCommonButtons
Tipo: TASKDIALOG_COMMON_BUTTON_FLAGS
Specifica i pulsanti di scelta rapida visualizzati nella finestra di dialogo. Questo parametro può essere una combinazione di flag del gruppo seguente.
[in] pszIcon
Tipo: PCWSTR
Puntatore a una stringa che identifica l'icona da visualizzare nella finestra di dialogo attività. Questo parametro deve essere un identificatore di risorsa integer passato alla macro MAKEINTRESOURCE o uno dei valori predefiniti seguenti. Se questo parametro è NULL, non verrà visualizzata alcuna icona. Se il parametro hInstance è NULL e uno dei valori predefiniti non viene usato, la funzione TaskDialog ha esito negativo.
[out] pnButton
Tipo: int*
Quando termina, questa funzione contiene un puntatore a una posizione integer che riceve uno dei valori seguenti:
| Valore | Descrizione |
|---|---|
| 0 | Chiamata di funzione non riuscita. Per altre informazioni, fare riferimento al valore restituito. |
| IDCANCEL | Il pulsante Annulla è stato selezionato, è stato premuto ALT-F4, Escape è stato premuto o l'utente ha fatto clic sul pulsante della finestra di chiusura . |
| IDNO | Nessun pulsante selezionato. |
| IDOK | È stato selezionato il pulsante OK. |
| IDRETRY | È stato selezionato il pulsante Riprova. |
| IDYES | È stato selezionato il pulsante Sì. |
| IDCLOSE | Pulsante Chiudi selezionato. |
Se questo valore è NULL, non viene restituito alcun valore.
Valore restituito
Tipo: HRESULT
Questa funzione può restituire uno di questi valori.
| Codice restituito | Descrizione |
|---|---|
|
Operazione riuscita. |
|
Memoria insufficiente per completare l'operazione. |
|
Uno o più argomenti non sono validi. |
|
Operazione non riuscita. |
Commenti
Quando si usa una finestra di dialogo attività per indicare che la memoria del sistema è insufficiente, le stringhe a cui puntano i parametri pszMainInstruction e pszWindowTitle non devono essere ricavate da un file di risorse perché un tentativo di caricamento della risorsa potrebbe non riuscire.
Se si crea una finestra di dialogo attività mentre è presente una finestra di dialogo, usare un handle per la finestra di dialogo come parametro hWndParent . Il parametro hWndParent non deve identificare una finestra figlio, ad esempio un controllo in una finestra di dialogo.
Poiché le finestre di dialogo attività usano gli elementi dell'interfaccia utente definiti dal sistema corretti, è consigliabile usarle invece di usare le finestre di messaggio create con la funzione MessageBox . Per ottenere altre funzionalità, usare TaskDialogIndirect.
Il codice di esempio seguente, da includere come parte di un programma più grande, illustra come creare una finestra di dialogo attività e acquisire l'input.
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
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | commctrl.h (includere Commctrl.h) |
| Libreria | Comctl32.lib |
| DLL | Comctl32.dll (versione 6) |