TaskDialog-Funktion (commctrl.h)

  • Artikel

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.

Hinweis Wenn keine Schaltflächen angegeben sind, enthält das Dialogfeld standardmäßig die Schaltfläche OK .
 
Wert Bedeutung
TDCBF_OK_BUTTON
 Das Aufgabendialogfeld enthält die Schaltfläche " OK".
TDCBF_YES_BUTTON
 Das Aufgabendialogfeld enthält die Schaltfläche " Ja".
TDCBF_NO_BUTTON
 Das Aufgabendialogfeld enthält die Schaltfläche " Nein".
TDCBF_CANCEL_BUTTON
 Das Aufgabendialogfeld enthält die Schaltfläche " Abbrechen". Diese Schaltfläche muss angegeben werden, damit das Dialogfeld auf typische Abbruchaktionen reagieren kann (ALT-F4 und Escape).
TDCBF_RETRY_BUTTON
 Das Dialogfeld "Aufgabe" enthält die Schaltfläche " Wiederholen".
TDCBF_CLOSE_BUTTON
 Das Dialogfeld "Aufgabe" enthält die Schaltfläche " Schließen".

[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.

Wert Bedeutung
TD_ERROR_ICON
 Im Aufgabendialogfeld wird ein Stoppzeichensymbol angezeigt.
TD_INFORMATION_ICON
 Ein Symbol, das aus einem Kleinbuchstaben i in einem Kreis besteht, wird im Aufgabendialogfeld angezeigt.
TD_SHIELD_ICON
 Im Aufgabendialogfeld wird ein Symbol für den Sicherheitsschild angezeigt.
TD_WARNING_ICON
 Im Aufgabendialogfeld wird ein Ausrufezeichen angezeigt.

[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
S_OK
 Der Vorgang wurde erfolgreich abgeschlossen.
E_OUTOFMEMORY
 Es ist nicht genügend Arbeitsspeicher vorhanden, um den Vorgang abzuschließen.
E_INVALIDARG
 Mindestens ein Argument ist ungültig.
E_FAIL
 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)

Weitere Informationen

Dialogfelder