TaskDialog-Funktion (commctrl.h)
Die TaskDialog-Funktion erstellt, zeigt ein Aufgabendialogfeld an und betreibt es. Das Aufgabendialogfeld enthält anwendungsdefinierten Nachrichtentext und -titel, Symbole und eine beliebige Kombination vordefinierter Schaltflächen. Diese Funktion unterstützt die Registrierung einer Rückruffunktion zum Empfangen von Benachrichtigungen nicht.
Syntax
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
);
Parameter
[in] hwndOwner
Typ: HWND
Handle an das Besitzerfenster des zu erstellenden Aufgabendialogfelds. Wenn dieser Parameter NULL ist, hat das Aufgabendialogfeld kein Besitzerfenster.
[in] hInstance
Typ: HINSTANCE
Handle für das Modul, das die vom pszIcon-Member identifizierte Symbolressource und die Zeichenfolgenressourcen enthält, die durch die Member pszWindowTitle und pszMainInstruction identifiziert werden. Wenn dieser Parameter NULL ist, muss pszIconNULL oder ein Zeiger auf eine mit NULL endende Unicode-Zeichenfolge sein, die einen Systemressourcenbezeichner enthält, z. B. TD_ERROR_ICON.
[in] pszWindowTitle
Typ: PCWSTR
Zeiger auf die Zeichenfolge, die für den Aufgabendialogtitel verwendet werden soll. Dieser Parameter ist eine mit NULL endende Unicode-Zeichenfolge, die entweder Text oder einen ganzzahligen Ressourcenbezeichner enthält, der über das MAKEINTRESOURCE-Makro übergeben wird. Wenn dieser Parameter NULL ist, wird der Dateiname des ausführbaren Programms verwendet.
[in] pszMainInstruction
Typ: PCWSTR
Zeiger auf die Zeichenfolge, die für die Standard-Anweisung verwendet werden soll. Dieser Parameter ist eine mit NULL endende Unicode-Zeichenfolge, die entweder Text oder einen ganzzahligen Ressourcenbezeichner enthält, der über das MAKEINTRESOURCE-Makro übergeben wird. Dieser Parameter kann NULL sein, wenn keine Standard Anweisung gewünscht wird.
[in] pszContent
Typ: PCWSTR
Zeiger auf eine Zeichenfolge, die für zusätzlichen Text verwendet wird, der unter der Standard-Anweisung in einer kleineren Schriftart angezeigt wird. Dieser Parameter ist eine mit NULL endende Unicode-Zeichenfolge, die entweder Text oder einen ganzzahligen Ressourcenbezeichner enthält, der über das MAKEINTRESOURCE-Makro übergeben wird. Kann NULL sein, wenn kein zusätzlicher Text gewünscht wird.
[in] dwCommonButtons
Typ: TASKDIALOG_COMMON_BUTTON_FLAGS
Gibt die im Dialogfeld angezeigten Drucktasten an. Dieser Parameter kann eine Kombination aus Flags aus der folgenden Gruppe sein.
[in] pszIcon
Typ: PCWSTR
Zeiger auf eine Zeichenfolge, die das symbol identifiziert, das im Aufgabendialogfeld angezeigt werden soll. Bei diesem Parameter muss es sich um einen ganzzahligen Ressourcenbezeichner handeln, der an das MAKEINTRESOURCE-Makro oder einen der folgenden vordefinierten Werte übergeben wird. Wenn dieser Parameter NULL ist, wird kein Symbol angezeigt. Wenn der hInstance-ParameterNULL ist und einer der vordefinierten Werte nicht verwendet wird, schlägt die TaskDialog-Funktion fehl.
[out] pnButton
Typ: int*
Wenn diese Funktion zurückgibt, enthält einen Zeiger auf eine ganzzahlige Position, die einen der folgenden Werte empfängt:
| Wert | BESCHREIBUNG |
|---|---|
| 0 | Fehler beim Funktionsaufruf. Weitere Informationen finden Sie unter Rückgabewert. |
| IDCANCEL | Die Schaltfläche Abbrechen wurde ausgewählt, ALT-F4 wurde gedrückt, Escape wurde gedrückt, oder der Benutzer klickte auf die Schaltfläche zum Schließen des Fensters. |
| IDNO | Es wurde keine Schaltfläche ausgewählt. |
| IDOK | Die Schaltfläche OK wurde ausgewählt. |
| IDRETRY | Die Schaltfläche "Wiederholen " wurde ausgewählt. |
| IDYES | Die Schaltfläche "Ja" wurde ausgewählt. |
| IDCLOSE | Die Schaltfläche "Schließen " wurde ausgewählt. |
Wenn dieser Wert NULL ist, wird kein Wert zurückgegeben.
Rückgabewert
Typ: HRESULT
Diese Funktion kann einen dieser Werte zurückgeben.
| Rückgabecode | BESCHREIBUNG |
|---|---|
|
Der Vorgang wurde erfolgreich abgeschlossen. |
|
Es ist nicht genügend Arbeitsspeicher vorhanden, um den Vorgang abzuschließen. |
|
Mindestens ein Argument ist ungültig. |
|
Fehler beim Vorgang. |
Hinweise
Wenn Sie ein Aufgabendialogfeld verwenden, um anzugeben, dass das System wenig Arbeitsspeicher hat, sollten die Zeichenfolgen, auf die von den Parametern pszMainInstruction und pszWindowTitle verwiesen wird, nicht aus einer Ressourcendatei entnommen werden, da der Versuch, die Ressource zu laden, möglicherweise fehlschlägt.
Wenn Sie ein Aufgabendialogfeld erstellen, während ein Dialogfeld vorhanden ist, verwenden Sie ein Handle für das Dialogfeld als hWndParent-Parameter . Der Parameter hWndParent sollte kein untergeordnetes Fenster identifizieren, z. B. ein Steuerelement in einem Dialogfeld.
Da Aufgabendialogfelder die richtigen systemdefinierte UI-Elemente verwenden, sollten Sie diese anstelle von Meldungsfeldern verwenden, die mit der MessageBox-Funktion erstellt wurden. Um mehr Funktionalität zu erzielen, verwenden Sie TaskDialogIndirect.
Der folgende Beispielcode, der als Teil eines größeren Programms enthalten sein soll, zeigt, wie Sie ein Aufgabendialogfeld erstellen und Eingaben erfassen.
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
}
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | commctrl.h (include Commctrl.h) |
| Bibliothek | Comctl32.lib |
| DLL | Comctl32.dll (Version 6) |