Fungsi TaskDialog (commctrl.h)

  • Artikel

Fungsi TaskDialog membuat, menampilkan, dan mengoperasikan dialog tugas. Dialog tugas berisi teks pesan dan judul yang ditentukan aplikasi, ikon, dan kombinasi tombol tekan yang telah ditentukan sebelumnya. Fungsi ini tidak mendukung pendaftaran fungsi panggilan balik untuk menerima pemberitahuan.

Sintaks

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

Jenis: HWND

Tangani ke jendela pemilik dialog tugas yang akan dibuat. Jika parameter ini NULL, dialog tugas tidak memiliki jendela pemilik.

[in] hInstance

Jenis: HINSTANCE

Tangani ke modul yang berisi sumber daya ikon yang diidentifikasi oleh anggota pszIcon , dan sumber daya string yang diidentifikasi oleh anggota pszWindowTitle dan pszMainInstruction . Jika parameter ini NULL, pszIcon harus NULL atau pointer ke string Unicode null-dihentikan yang berisi pengidentifikasi sumber daya sistem, misalnya, TD_ERROR_ICON.

[in] pszWindowTitle

Jenis: PCWSTR

Penunjuk ke string yang akan digunakan untuk judul dialog tugas. Parameter ini adalah string Unicode yang dihentikan null yang berisi teks, atau pengidentifikasi sumber daya bilangan bulat yang melewati makro MAKEINTRESOURCE . Jika parameter ini ADALAH NULL, nama file program yang dapat dieksekusi digunakan.

[in] pszMainInstruction

Jenis: PCWSTR

Penunjuk ke string yang akan digunakan untuk instruksi utama. Parameter ini adalah string Unicode yang dihentikan null yang berisi teks, atau pengidentifikasi sumber daya bilangan bulat yang melewati makro MAKEINTRESOURCE . Parameter ini bisa NULL jika tidak ada instruksi utama yang diinginkan.

[in] pszContent

Jenis: PCWSTR

Penunjuk ke string yang digunakan untuk teks tambahan yang muncul di bawah instruksi utama, dalam font yang lebih kecil. Parameter ini adalah string Unicode yang dihentikan null yang berisi teks, atau pengidentifikasi sumber daya bilangan bulat yang melewati makro MAKEINTRESOURCE . Bisa null jika tidak ada teks tambahan yang diinginkan.

[in] dwCommonButtons

Jenis: TASKDIALOG_COMMON_BUTTON_FLAGS

Menentukan tombol dorong yang ditampilkan dalam kotak dialog. Parameter ini mungkin merupakan kombinasi bendera dari grup berikut.

Catatan Jika tidak ada tombol yang ditentukan, kotak dialog akan berisi tombol OK secara default.
 
Nilai Makna
TDCBF_OK_BUTTON
 Dialog tugas berisi tombol tekan: OK.
TDCBF_YES_BUTTON
 Dialog tugas berisi tombol tekan: Ya.
TDCBF_NO_BUTTON
 Dialog tugas berisi tombol tekan: Tidak.
TDCBF_CANCEL_BUTTON
 Dialog tugas berisi tombol tekan: Batal. Tombol ini harus ditentukan agar kotak dialog merespons tindakan pembatalan umum (Alt-F4 dan Escape).
TDCBF_RETRY_BUTTON
 Dialog tugas berisi tombol tekan: Coba lagi.
TDCBF_CLOSE_BUTTON
 Dialog tugas berisi tombol tekan: Tutup.

[in] pszIcon

Jenis: PCWSTR

Penunjuk ke string yang mengidentifikasi ikon untuk ditampilkan dalam dialog tugas. Parameter ini harus merupakan pengidentifikasi sumber daya bilangan bulat yang diteruskan ke makro MAKEINTRESOURCE atau salah satu nilai yang telah ditentukan sebelumnya berikut ini. Jika parameter ini NULL, tidak ada ikon yang akan ditampilkan. Jika parameter hInstance adalah NULL dan salah satu nilai yang telah ditentukan sebelumnya tidak digunakan, fungsi TaskDialog gagal.

Nilai Makna
TD_ERROR_ICON
 Ikon tanda berhenti muncul dalam dialog tugas.
TD_INFORMATION_ICON
 Ikon yang terdiri dari huruf kecil i dalam lingkaran muncul dalam dialog tugas.
TD_SHIELD_ICON
 Ikon perisai keamanan muncul dalam dialog tugas.
TD_WARNING_ICON
 Ikon tanda seru muncul dalam dialog tugas.

[out] pnButton

Jenis: int*

Saat fungsi ini kembali, berisi penunjuk ke lokasi bilangan bulat yang menerima salah satu nilai berikut:

Nilai Deskripsi
0 Panggilan fungsi gagal. Lihat mengembalikan nilai untuk informasi selengkapnya.
IDCANCEL Tombol Batal dipilih, Alt-F4 ditekan, Escape ditekan atau pengguna mengklik tombol tutup jendela .
IDNO Tidak ada tombol yang dipilih.
IDOK Tombol OK dipilih.
IDRETRY Tombol Coba lagi dipilih.
IDYES Tombol Ya dipilih.
IDCLOSE Tombol Tutup dipilih.
 

Jika nilai ini NULL, tidak ada nilai yang dikembalikan.

Mengembalikan nilai

Jenis: HRESULT

Fungsi ini dapat mengembalikan salah satu nilai ini.

Menampilkan kode Deskripsi
S_OK
 Operasi berhasil diselesaikan.
E_OUTOFMEMORY
 Memori tidak cukup untuk menyelesaikan operasi.
E_INVALIDARG
 Satu atau beberapa argumen tidak valid.
E_FAIL
 Operasi gagal.

Keterangan

Saat Anda menggunakan kotak dialog tugas untuk menunjukkan bahwa sistem kehabisan memori, string yang ditunjukkan oleh parameter pszMainInstruction dan pszWindowTitle tidak boleh diambil dari file sumber daya karena upaya untuk memuat sumber daya mungkin gagal.

Jika Anda membuat dialog tugas saat kotak dialog ada, gunakan handel ke kotak dialog sebagai parameter hWndParent . Parameter hWndParent tidak boleh mengidentifikasi jendela anak, seperti kontrol dalam kotak dialog.

Karena kotak dialog tugas menggunakan elemen UI yang ditentukan sistem yang benar, Anda harus menggunakannya alih-alih menggunakan kotak pesan yang dibuat dengan fungsi MessageBox . Untuk mencapai lebih banyak fungsionalitas, gunakan TaskDialogIndirect.

Contoh kode berikut, yang akan disertakan sebagai bagian dari program yang lebih besar, menunjukkan cara membuat dialog tugas dan menangkap 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
}

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2008 [hanya aplikasi desktop]
Target Platform Windows
Header commctrl.h (termasuk Commctrl.h)
Pustaka Comctl32.lib
DLL Comctl32.dll (versi 6)

Lihat juga

Kotak Dialog