Struktur PRINTDLGEXA (commdlg.h)
Berisi informasi yang digunakan fungsi PrintDlgEx untuk menginisialisasi lembar properti Cetak. Setelah pengguna menutup lembar properti, sistem menggunakan struktur ini untuk mengembalikan informasi tentang pilihan pengguna.
Sintaks
typedef struct tagPDEXA {
DWORD lStructSize;
HWND hwndOwner;
HGLOBAL hDevMode;
HGLOBAL hDevNames;
HDC hDC;
DWORD Flags;
DWORD Flags2;
DWORD ExclusionFlags;
DWORD nPageRanges;
DWORD nMaxPageRanges;
LPPRINTPAGERANGE lpPageRanges;
DWORD nMinPage;
DWORD nMaxPage;
DWORD nCopies;
HINSTANCE hInstance;
LPCSTR lpPrintTemplateName;
LPUNKNOWN lpCallback;
DWORD nPropertyPages;
HPROPSHEETPAGE *lphPropertyPages;
DWORD nStartPage;
DWORD dwResultAction;
} PRINTDLGEXA, *LPPRINTDLGEXA;
Anggota
lStructSize
Jenis: DWORD
Ukuran struktur, dalam byte.
hwndOwner
Jenis: HWND
Handel ke jendela yang memiliki lembar properti. Anggota ini harus merupakan handel jendela yang valid; tidak boleh NULL.
hDevMode
Jenis: HGLOBAL
Handel ke objek memori global yang dapat diubah yang berisi struktur DEVMODE . Jika hDevMode bukan NULL pada input, Anda harus mengalokasikan blok memori yang dapat dipindahkan untuk struktur DEVMODE dan menginisialisasi anggotanya. Fungsi PrintDlgEx menggunakan data input untuk menginisialisasi kontrol dalam lembar properti. Saat PrintDlgEx kembali, anggota DEVMODE menunjukkan input pengguna.
Jika hDevModeADALAH NULL pada input, PrintDlgEx mengalokasikan memori untuk struktur DEVMODE , menginisialisasi anggotanya untuk menunjukkan input pengguna, dan mengembalikan handel yang mengidentifikasinya.
Untuk informasi selengkapnya tentang anggota hDevMode dan hDevNames , lihat bagian Keterangan di akhir topik ini.
hDevNames
Jenis: HGLOBAL
Handel ke objek memori global yang dapat di-movable yang berisi struktur DEVNAMES . Jika hDevNames bukan NULL pada input, Anda harus mengalokasikan blok memori yang dapat dipindahkan untuk struktur DEVNAMES dan menginisialisasi anggotanya. Fungsi PrintDlgEx menggunakan data input untuk menginisialisasi kontrol dalam lembar properti. Ketika PrintDlgEx kembali, anggota DEVNAMES berisi informasi untuk printer yang dipilih oleh pengguna. Anda dapat menggunakan informasi ini untuk membuat konteks perangkat atau konteks informasi.
Anggota hDevNames dapat berupa NULL, dalam hal ini, PrintDlgEx mengalokasikan memori untuk struktur DEVNAMES , menginisialisasi anggotanya untuk menunjukkan input pengguna, dan mengembalikan handel yang mengidentifikasinya.
Untuk informasi selengkapnya tentang anggota hDevMode dan hDevNames , lihat bagian Keterangan di akhir topik ini.
hDC
Jenis: HDC
Handel ke konteks perangkat atau konteks informasi, tergantung pada apakah anggota Bendera menentukan benderaPD_RETURNDC atau PC_RETURNIC . Jika tidak ada bendera yang ditentukan, maka nilai anggota ini tidak ditentukan. Jika kedua bendera ditentukan, maka PD_RETURNDC memiliki prioritas. Jika hDC bukan NULL, maka Anda harus memanggil DeleteDC untuk membebaskan objek GDI setelah Anda tidak lagi membutuhkannya; jika tidak, Anda akan membocorkan objek GDI setiap kali Anda memanggil API PrintDlgw .
Flags
Jenis: DWORD
Sekumpulan bendera bit yang bisa Anda gunakan untuk menginisialisasi lembar properti Cetak . Saat fungsi PrintDlgEx kembali, fungsi ini mengatur bendera ini untuk menunjukkan input pengguna. Anggota ini bisa menjadi satu atau beberapa nilai berikut.
Untuk memastikan bahwa PrintDlg atau PrintDlgEx mengembalikan nilai yang benar dalam anggota dmCopies dan dmCollate dari struktur DEVMODE , atur PD_RETURNDC = TRUE dan PD_USEDEVMODECOPIESANDCOLLATE = TRUE. Dengan demikian, anggota nCopies dari struktur PRINTDLG selalu 1 dan PD_COLLATE selalu FALSE.
Untuk memastikan bahwa PrintDlg atau PrintDlgEx mengembalikan nilai yang benar dalam nCopies dan PD_COLLATE, atur PD_RETURNDC = TRUE dan PD_USEDEVMODECOPIESANDCOLLATE = FALSE. Dengan demikian, dmCopies selalu 1 dan dmCollate selalu FALSE.
Dimulai dengan Windows Vista, ketika Anda memanggil PrintDlg atau PrintDlgEx dengan PD_RETURNDC diatur ke TRUE dan PD_USEDEVMODECOPIESANDCOLLATE diatur ke FALSE, fungsi PrintDlg atau PrintDlgEx mengatur jumlah salinan dalam anggota nCopies dari struktur PRINTDLG , dan mengatur jumlah salinan dalam struktur yang diwakili oleh anggota hDC dari struktur PRINTDLG .
Saat melakukan panggilan ke GDI, Anda harus mengabaikan nilai nCopies, mempertimbangkan nilai sebagai 1, dan menggunakan hDC yang dikembalikan untuk menghindari pencetakan salinan duplikat.
| Nilai | Makna |
|---|---|
|
Bendera default yang menunjukkan bahwa tombol radio Semua awalnya dipilih. Bendera ini digunakan sebagai tempat penampung untuk menunjukkan bahwa bendera PD_PAGENUMS, PD_SELECTION, dan PD_CURRENTPAGE tidak ditentukan. |
|
Jika bendera ini diatur, kotak centang Kolase dipilih.
Jika bendera ini diatur ketika fungsi PrintDlgEx kembali, aplikasi harus mensimulasikan kolase beberapa salinan. Untuk informasi selengkapnya, lihat deskripsi bendera PD_USEDEVMODECOPIESANDCOLLATE . Lihat PD_NOPAGENUMS. |
|
Jika bendera ini diatur, tombol radio Halaman Saat Ini dipilih. Jika tidak ada bendera PD_PAGENUMS, PD_SELECTION, atau PD_CURRENTPAGE yang diatur, tombol radio Semua dipilih. |
|
Menonaktifkan kotak centang Cetak ke File . |
|
Menunjukkan bahwa anggota hInstance dan lpPrintTemplateName menentukan pengganti templat kotak dialog default di bagian bawah halaman Umum . Templat default berisi kontrol yang mirip dengan kontrol kotak dialog Cetak . Sistem menggunakan templat yang ditentukan untuk membuat jendela yang merupakan anak dari halaman Umum . |
|
Menunjukkan bahwa anggota hInstance mengidentifikasi blok data yang berisi templat kotak dialog yang dimuat sebelumnya. Templat ini menggantikan templat kotak dialog default di bagian bawah halaman Umum . Sistem menggunakan templat yang ditentukan untuk membuat jendela yang merupakan anak dari halaman Umum . Sistem mengabaikan anggota lpPrintTemplateName jika bendera ini ditentukan. |
|
Menunjukkan bahwa anggota ExclusionFlags mengidentifikasi item yang akan dikecualikan dari halaman properti driver printer. Jika bendera ini tidak disetel, item akan dikecualikan secara default dari halaman properti pengandar pencetak. Pengecualian mencegah duplikasi item di antara halaman Umum , halaman yang ditentukan aplikasi apa pun, dan halaman driver printer. |
|
Sembunyikan kotak centang Cetak ke File . |
|
Menonaktifkan tombol radio Halaman Saat Ini . |
|
Menonaktifkan tombol radio Pages dan kontrol edit terkait. Selain itu, ini menyebabkan kotak centang Kolase muncul dalam dialog. |
|
Menonaktifkan tombol radio Pilihan . |
|
Mencegah pesan peringatan ditampilkan ketika terjadi kesalahan. |
|
Jika bendera ini diatur, tombol radio Pages dipilih. Jika tidak ada bendera PD_PAGENUMS, PD_SELECTION, atau PD_CURRENTPAGE yang diatur, tombol radio Semua dipilih. Jika bendera ini diatur ketika fungsi PrintDlgEx kembali, anggota lpPageRanges menunjukkan rentang halaman yang ditentukan oleh pengguna. |
|
Jika bendera ini diatur, kotak centang Cetak ke File dipilih. Jika bendera ini diatur ketika PrintDlgEx kembali, offset yang ditunjukkan oleh anggota wOutputOffset dari struktur DEVNAMES berisi string "FILE:". Ketika Anda memanggil fungsi StartDoc untuk memulai operasi pencetakan, tentukan string "FILE:" ini di anggota lpszOutput dari struktur DOCINFO . Menentukan string ini menyebabkan subsistem cetak mengkueri pengguna untuk nama file output. |
|
Menyebabkan PrintDlgEx mengembalikan konteks perangkat yang cocok dengan pilihan yang dibuat pengguna dalam lembar properti. Konteks perangkat dikembalikan dalam hDC. |
|
Jika bendera ini diatur, fungsi PrintDlgEx tidak menampilkan lembar properti. Sebaliknya, ini mengatur anggota hDevNames dan hDevMode untuk ditangani ke struktur DEVNAMES dan DEVMODE yang diinisialisasi untuk printer default sistem. hDevNames dan hDevMode harus NULL, atau PrintDlgEx mengembalikan kesalahan. |
|
Mirip dengan bendera PD_RETURNDC , kecuali bendera ini mengembalikan konteks informasi daripada konteks perangkat. Jika tidak ada PD_RETURNDC atau PD_RETURNIC yang ditentukan, hDC tidak ditentukan pada output. |
|
Jika bendera ini diatur, tombol radio Pilihan dipilih. Jika tidak ada bendera PD_PAGENUMS, PD_SELECTION, atau PD_CURRENTPAGE diatur, tombol radio Semua dipilih. |
|
Sama seperti PD_USEDEVMODECOPIESANDCOLLATE. |
|
Bendera ini menunjukkan apakah aplikasi Anda mendukung beberapa salinan dan kolajeasi. Atur bendera ini pada input untuk menunjukkan bahwa aplikasi Anda tidak mendukung beberapa salinan dan kolase. Dalam hal ini, anggota nCopies dari struktur PRINTDLGEX selalu mengembalikan 1, dan PD_COLLATE tidak pernah diatur dalam anggota Bendera .
Jika bendera ini tidak diatur, aplikasi bertanggung jawab untuk mencetak dan menyusun beberapa salinan. Dalam hal ini, anggota nCopies dari struktur PRINTDLGEX menunjukkan jumlah salinan yang ingin dicetak pengguna, dan bendera PD_COLLATE di anggota Bendera menunjukkan apakah pengguna menginginkan kolaset. Terlepas dari apakah bendera ini diatur, aplikasi dapat menentukan dari nCopies dan PD_COLLATE berapa banyak salinan yang akan dirender dan apakah akan mencetaknya disatukan. Jika bendera ini disetel dan pengandar pencetak tidak mendukung beberapa salinan, kontrol edit Salinan dinonaktifkan. Demikian pula, jika bendera ini diatur dan driver printer tidak mendukung kolase, kotak centang Susun dinonaktifkan. Anggota dmCopies dan dmCollate dari struktur DEVMODE berisi salinan dan menyusun informasi yang digunakan oleh driver printer. Jika bendera ini diatur dan driver printer mendukung beberapa salinan, anggota dmCopies menunjukkan jumlah salinan yang diminta oleh pengguna. Jika bendera ini diatur dan driver printer mendukung kolase, anggota dmCollate dari struktur DEVMODE menunjukkan apakah pengguna menginginkan kolase. Jika bendera ini tidak diatur, anggota dmCopies selalu mengembalikan 1, dan anggota dmCollate selalu nol. Di versi Windows sebelum Windows Vista, jika bendera ini tidak diatur oleh aplikasi panggilan dan anggota dmCopies dari struktur DEVMODE lebih besar dari 1, gunakan nilai tersebut untuk jumlah salinan; jika tidak, gunakan nilai anggota nCopies dari struktur PRINTDLGEX . |
|
Memaksa lembar properti untuk menggunakan templat besar untuk halaman Umum . Templat yang lebih besar menyediakan lebih banyak ruang untuk aplikasi yang menentukan templat kustom untuk bagian bawah halaman Umum . |
Flags2
Jenis: DWORD
ExclusionFlags
Jenis: DWORD
Set bendera bit yang dapat mengecualikan item dari halaman properti pengandar printer dalam lembar properti Cetak . Nilai ini hanya digunakan jika bendera PD_EXCLUSIONFLAGS diatur dalam anggota Bendera . Bendera pengecualian harus digunakan hanya jika item yang akan dikecualikan akan disertakan pada halaman Umum atau pada halaman yang ditentukan aplikasi di lembar properti Cetak . Anggota ini dapat menentukan bendera berikut.
PD_EXCL_COPIESANDCOLLATE
Mengecualikan kontrol Salin dan Susun dari halaman properti pengandar pencetak dalam lembar properti Cetak . Bendera ini harus selalu diatur ketika aplikasi menggunakan kontrol Salin dan Kolase default yang disediakan oleh bagian bawah halaman Umum dari lembar properti Cetak .
nPageRanges
Jenis: DWORD
Pada input, atur anggota ini ke jumlah awal rentang halaman yang ditentukan dalam array lpPageRanges . Saat fungsi PrintDlgEx kembali, nPageRanges menunjukkan jumlah rentang halaman yang ditentukan pengguna yang disimpan dalam array lpPageRanges . Jika bendera PD_NOPAGENUMS ditentukan, nilai ini tidak valid.
nMaxPageRanges
Jenis: DWORD
Ukuran, dalam elemen array, dari buffer lpPageRanges . Nilai ini menunjukkan jumlah maksimum rentang halaman yang dapat disimpan dalam array. Jika bendera PD_NOPAGENUMS ditentukan, nilai ini tidak valid. Jika bendera PD_NOPAGENUMS tidak ditentukan, nilai ini harus lebih besar dari nol.
lpPageRanges
Jenis: LPPRINTPAGERANGE
Penunjuk ke buffer yang berisi array struktur PRINTPAGERANGE . Pada input, array berisi rentang halaman awal untuk ditampilkan di kontrol edit Halaman . Saat fungsi PrintDlgEx kembali, array berisi rentang halaman yang ditentukan oleh pengguna. Jika bendera PD_NOPAGENUMS ditentukan, nilai ini tidak valid. Jika bendera PD_NOPAGENUMS tidak ditentukan, lpPageRanges harus non-NULL.
nMinPage
Jenis: DWORD
Nilai minimum untuk rentang halaman yang ditentukan dalam kontrol edit Halaman . Jika bendera PD_NOPAGENUMS ditentukan, nilai ini tidak valid.
nMaxPage
Jenis: DWORD
Nilai maksimum untuk rentang halaman yang ditentukan dalam kontrol edit Halaman . Jika bendera PD_NOPAGENUMS ditentukan, nilai ini tidak valid.
nCopies
Jenis: DWORD
Berisi jumlah awal salinan untuk kontrol edit Salinan jika hDevMode adalah NULL; jika tidak, anggota dmCopies dari struktur DEVMODE berisi nilai awal. Ketika PrintDlgEx kembali, nCopies berisi jumlah salinan aktual yang harus dicetak aplikasi. Nilai ini tergantung pada apakah aplikasi atau pengandar pencetak bertanggung jawab untuk mencetak beberapa salinan. Jika bendera PD_USEDEVMODECOPIESANDCOLLATE diatur di anggota Bendera , nCopies selalu 1 saat kembali, dan driver printer bertanggung jawab untuk mencetak beberapa salinan. Jika bendera tidak diatur, aplikasi bertanggung jawab untuk mencetak jumlah salinan yang ditentukan oleh nCopies. Untuk informasi selengkapnya, lihat deskripsi bendera PD_USEDEVMODECOPIESANDCOLLATE .
hInstance
Jenis: HINSTANCE
Jika bendera PD_ENABLEPRINTTEMPLATE diatur di anggota Bendera , hInstance adalah handel ke instans aplikasi atau modul yang berisi templat kotak dialog yang dinamai oleh anggota lpPrintTemplateName . Jika bendera PD_ENABLEPRINTTEMPLATEHANDLE diatur di anggota Bendera , hInstance adalah handel ke objek memori yang berisi templat kotak dialog. Jika tidak ada bendera templat yang diatur di anggota Bendera , hInstance harus NULL.
lpPrintTemplateName
Jenis: LPCTSTR
Nama sumber daya templat kotak dialog dalam modul yang diidentifikasi oleh anggota hInstance . Templat ini menggantikan templat kotak dialog default di bagian bawah halaman Umum . Templat default berisi kontrol yang mirip dengan yang ada di kotak dialog Cetak . Anggota ini diabaikan kecuali bendera PD_ENABLEPRINTTEMPLATE diatur di anggota Bendera .
lpCallback
Jenis: LPUNKNOWN
Penunjuk ke objek panggilan balik yang ditentukan aplikasi.
Objek harus berisi kelas IPrintDialogCallback untuk menerima pesan untuk kotak dialog anak di bagian bawah halaman Umum .
Objek panggilan balik juga harus berisi kelas IObjectWithSite untuk menerima pointer ke antarmuka IPrintDialogServices . Fungsi PrintDlgEx memanggil IUnknown::QueryInterface pada objek panggilan balik untuk IID_IPrintDialogCallback dan IID_IObjectWithSite untuk menentukan antarmuka mana yang didukung.
Jika Anda tidak ingin mengambil informasi panggilan balik apa pun, atur lpCallback ke NULL.
nPropertyPages
Jenis: DWORD
Jumlah handel halaman properti dalam array lphPropertyPages .
lphPropertyPages
Jenis: HPROPSHEETPAGE*
Berisi array handel halaman properti untuk ditambahkan ke lembar properti Cetak . Halaman properti tambahan mengikuti halaman Umum . Gunakan fungsi CreatePropertySheetPage untuk membuat halaman tambahan ini. Ketika fungsi PrintDlgEx kembali, semua handel HPROPSHEETPAGE dalam array lphPropertyPages telah dihancurkan. Jika nPropertyPages adalah nol, lphPropertyPages harus NULL.
nStartPage
Jenis: DWORD
Halaman properti yang awalnya ditampilkan. Untuk menampilkan halaman Umum , tentukan START_PAGE_GENERAL. Jika tidak, tentukan indeks berbasis nol dari halaman properti dalam array yang ditentukan dalam anggota lphPropertyPages . Untuk konsistensi, disarankan agar lembar properti selalu dimulai di halaman Umum .
dwResultAction
Jenis: DWORD
Pada input, atur anggota ini ke nol. Jika fungsi PrintDlgEx mengembalikan S_OK, dwResultAction berisi hasil dialog. Jika PrintDlgEx mengembalikan kesalahan, anggota ini harus diabaikan. Anggota dwResultAction bisa menjadi salah satu nilai berikut.
PD_RESULT_APPLY
Pengguna mengklik tombol Terapkan dan kemudian mengklik tombol Batalkan . Ini menunjukkan bahwa pengguna ingin menerapkan perubahan yang dibuat di lembar properti, tetapi belum ingin mencetak. Struktur PRINTDLGEX berisi informasi yang ditentukan oleh pengguna pada saat tombol Terapkan diklik.
PD_RESULT_CANCEL
Pengguna mengklik tombol Batalkan . Informasi dalam struktur PRINTDLGEX tidak berubah.
PD_RESULT_PRINT
Pengguna mengklik tombol Cetak . Struktur PRINTDLGEX berisi informasi yang ditentukan oleh pengguna.
Keterangan
Jika hDevMode dan hDevNamesadalah NULL, PrintDlgEx menginisialisasi lembar properti menggunakan printer default saat ini. Untuk menginisialisasi lembar properti untuk printer yang berbeda, gunakan anggota wDeviceOffset dari struktur DEVNAMES untuk menentukan nama printer.
Perhatikan bahwa anggota dmDeviceName dari struktur DEVMODE juga menentukan nama printer. Namun, dmDeviceName dibatasi hingga 32 karakter, dan nama wDeviceOffset tidak. Jika nama wDeviceOffset dan dmDeviceName tidak sama, PrintDlgEx menginisialisasi lembar properti menggunakan printer yang ditentukan oleh wDeviceOffset.
Jika bendera PD_RETURNDEFAULT diatur dan hDevMode dan hDevNamesadalah NULL, PrintDlgEx menggunakan anggota hDevNames dan hDevMode untuk mengembalikan informasi tentang printer default saat ini tanpa menampilkan kotak dialog.
Selama eksekusi PrintDlgEx, struktur DEVMODE dan DEVNAMES yang Anda tentukan dalam struktur PRINTDLGEX mungkin tidak selalu berisi data saat ini. Untuk alasan ini, halaman properti khusus aplikasi serta rutinitas IPrintDialogCallback untuk halaman awal harus menggunakan antarmuka IPrintDialogServices untuk mengambil informasi tentang status printer saat ini.
Catatan
Header commdlg.h mendefinisikan PRINTDLGEX sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Klien minimum yang didukung | Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Header | commdlg.h (sertakan Windows.h) |
Lihat juga
Konseptual
Referensi
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk