Kotak dialog Buka dan Simpan Sebagai
Catatan
Fungsi GetOpenFileName ditunjukkan dalam sampel File sedang digunakan.
[Dimulai dengan Windows Vista, kotak dialog Buka dan Simpan Sebagai umum telah digantikan oleh Dialog Item Umum. Kami menyarankan agar Anda menggunakan API Dialog Item Umum alih-alih kotak dialog ini dari Pustaka Kotak Dialog Umum.]
Kotak dialog Buka memungkinkan pengguna menentukan drive, direktori, dan nama file atau sekumpulan file untuk dibuka. Anda membuat dan menampilkan kotak dialog Buka dengan menginisialisasi struktur OPENFILENAME dan meneruskan struktur ke fungsi GetOpenFileName .
Kotak dialog Simpan Sebagai memungkinkan pengguna menentukan drive, direktori, dan nama file untuk disimpan. Anda membuat dan menampilkan kotak dialog Simpan Sebagai dengan menginisialisasi struktur OPENFILENAME dan meneruskan struktur ke fungsi GetSaveFileName .
Kotak dialog Buka dan Simpan Sebagai gaya Explorer menyediakan fitur antarmuka pengguna yang mirip dengan Windows Explorer. Namun, sistem terus mendukung kotak dialog Buka dan Simpan Sebagai gaya lama untuk aplikasi yang harus konsisten dengan antarmuka pengguna gaya lama.
Selain perbedaan tampilan, kotak dialog Gaya penjelajah dan gaya lama berbeda dalam penggunaan templat kustom dan prosedur kait untuk menyesuaikan kotak dialog. Namun, kotak dialog Gaya penjelajah dan gaya lama memiliki perilaku yang sama untuk sebagian besar operasi dasar, seperti menentukan filter nama file, memvalidasi input pengguna, dan mendapatkan nama file yang ditentukan oleh pengguna. Untuk informasi selengkapnya tentang kotak dialog Gaya penjelajah dan gaya lama, lihat Membuka dan Menyimpan Sebagai Kustomisasi Kotak Dialog.
Ilustrasi berikut ini memperlihatkan kotak dialog Buka gaya Explorer yang khas.
Ilustrasi berikut ini memperlihatkan kotak dialog Simpan Sebagai gaya Explorer yang khas.
Jika pengguna menentukan nama file dan mengklik tombol OK , GetOpenFileName atau GetSaveFileName mengembalikan TRUE. Buffer yang ditujukkan oleh anggota lpstrFile dari struktur OPENFILENAME berisi jalur lengkap dan nama file yang ditentukan oleh pengguna.
Jika pengguna membatalkan kotak dialog Buka atau Simpan Sebagai atau terjadi kesalahan, fungsi mengembalikan FALSE. Untuk menentukan penyebab kesalahan, panggil fungsi CommDlgExtendedError untuk mengambil nilai kesalahan yang diperluas. Jika buffer lpstrFile terlalu kecil untuk menerima nama lengkap, CommDlgExtendedError mengembalikan FNERR_BUFFERTOOSMALL dan 2 byte pertama buffer yang ditunjukkan oleh anggota lpstrFile diatur ke nilai bilangan bulat yang menentukan ukuran yang diperlukan untuk menerima nama lengkap.
Topik berikut dibahas di bagian ini.
- Nama dan Direktori File
- Filter
- Validasi File dan Direktori
- Kustomisasi Kotak Dialog Buka dan Simpan Sebagai
- Prosedur Hook Gaya Penjelajah
- Templat Kustom Gaya Penjelajah
- Pengidentifikasi Kontrol Gaya Penjelajah
- Menyesuaikan Kotak Dialog Old-Style
Nama dan Direktori File
Informasi di bagian ini berlaku untuk kotak dialog Buka dan Simpan Sebagai gaya penjelajah dan gaya lama.
Sebelum memanggil fungsi GetOpenFileName atau GetSaveFileName , anggota lpstrFile dari struktur OPENFILENAME harus menunjuk ke buffer untuk menerima nama file. Anggota nMaxFile harus menentukan ukuran, dalam karakter, dari buffer lpstrFile . Untuk fungsi ANSI ini adalah jumlah byte, tetapi untuk fungsi Unicode ini adalah jumlah karakter.
Jika pengguna menentukan nama file dan mengklik tombol OK , kotak dialog menyalin drive, direktori, dan nama file yang dipilih ke buffer lpstrFile . Fungsi ini juga mengatur anggota nFileOffset dan nFileExtension ke offset, dalam karakter, dari awal buffer ke nama file dan ke ekstensi nama file, masing-masing.
Untuk mengambil hanya nama file dan ekstensi, atur anggota lpstrFileTitle untuk menunjuk ke buffer dan atur anggota nMaxFileTitle ke ukuran, dalam karakter, dari buffer. Atau, Anda dapat meneruskan buffer lpstrFile dalam panggilan ke fungsi GetFileTitle untuk mendapatkan nama tampilan file yang dipilih. Namun, perhatikan bahwa nama file yang dikembalikan GetFileTitle menyertakan ekstensi hanya jika itu adalah preferensi pengguna untuk menampilkan nama file.
Kotak dialog menggunakan direktori saat ini untuk proses panggilan sebagai direktori awal untuk menampilkan file dan direktori. Gunakan fungsi GetCurrentDirectory dan SetCurrentDirectory untuk mendapatkan dan mengubah direktori proses saat ini. Untuk menentukan direktori awal yang berbeda tanpa mengubah direktori Anda saat ini, gunakan anggota lpstrInitialDir untuk menentukan nama direktori. Kotak dialog secara otomatis mengubah direktori Anda saat ini saat pengguna memilih drive atau direktori yang berbeda. Untuk mencegah kotak dialog mengubah direktori Anda saat ini, atur bendera OFN_NOCHANGEDIR . Bendera ini tidak mencegah pengguna mengubah direktori untuk menemukan file.
Untuk menentukan ekstensi nama file default, gunakan anggota lpstrDefExt . Jika pengguna menentukan nama file yang tidak memiliki ekstensi, kotak dialog menambahkan ekstensi default Anda. Jika Anda menentukan ekstensi default dan pengguna menentukan nama file dengan ekstensi yang berbeda, kotak dialog mengatur bendera OFN_EXTENSIONDIFFERENT .
Untuk memungkinkan pengguna memilih lebih dari satu file dari direktori, atur bendera OFN_ALLOWMULTISELECT . Untuk kompatibilitas dengan aplikasi yang lebih lama, kotak dialog beberapa pilihan default menggunakan antarmuka pengguna gaya lama. Untuk menampilkan kotak dialog beberapa pilihan gaya Explorer, Anda juga harus mengatur bendera OFN_EXPLORER .
Jika pengguna memilih lebih dari satu file, buffer yang diarahkan oleh anggota lpstrFile mengembalikan jalur ke direktori saat ini diikuti dengan nama file dari file yang dipilih. Anggota nFileOffset adalah offset ke nama file pertama, dan anggota nFileExtension tidak digunakan. Tabel berikut ini menjelaskan perbedaan antara kotak dialog gaya Explorer dan gaya lama dalam mengembalikan beberapa nama file.
| Gaya kotak dialog | Deskripsi |
|---|---|
| Kotak dialog gaya penjelajah | String direktori dan nama file dipisahkan NULL , dengan karakter NULL tambahan setelah nama file terakhir. Format ini memungkinkan kotak dialog Gaya penjelajah untuk mengembalikan nama file panjang yang menyertakan spasi. |
| Kotak dialog gaya lama | String direktori dan nama file dipisahkan oleh spasi. Untuk nama file dengan spasi, fungsi menggunakan nama file pendek. |
Anda dapat menggunakan fungsi FindFirstFile untuk mengonversi antara nama file panjang dan pendek.
Jika Anda menentukan OFN_ALLOWMULTISELECT dan pengguna hanya memilih satu file, string lpstrFile tidak memiliki pemisah antara jalur dan nama file.
Filter
Informasi di bagian ini berlaku untuk kotak dialog Buka dan Simpan Sebagai gaya penjelajah dan gaya lama.
Anda dapat menyediakan filter nama file untuk membantu pengguna membatasi nama file yang ditampilkan kotak dialog. Filter nama file terdiri dari sepasang string yang dihentikan null, deskripsi dan pola, satu digabungkan ke yang lain. Kotak dialog menampilkan deskripsi untuk memungkinkan pengguna memilih filter mana yang akan digunakan; dan menggunakan pola untuk memilih file yang akan ditampilkan.
Untuk menentukan filter, atur anggota lpstrFilter dari struktur OPENFILENAME untuk menunjuk ke buffer yang berisi array pasangan string filter. String terakhir dalam array harus diikuti oleh karakter null tambahan.
String pola dapat berupa kombinasi karakter nama file yang valid dan tanda bintang (*). Tanda bintang adalah kartubebas yang mewakili kombinasi karakter nama file yang valid. Kotak dialog hanya menampilkan file yang cocok dengan pola. Untuk menentukan beberapa pola untuk deskripsi yang sama, Anda harus menggunakan titik koma (;) untuk memisahkan pola. Perhatikan bahwa karakter spasi dalam string pola dapat menghasilkan hasil yang tidak terduga.
Fragmen kode berikut menentukan dua filter. Filter dengan deskripsi "Sumber" memiliki dua pola. Jika pengguna memilih filter ini, kotak dialog hanya menampilkan file yang memiliki . C dan . Ekstensi CXX. Catatan, dalam bahasa pemrograman C, string yang diapit tanda kutip ganda dihentikan null.
OPENFILENAME ofn; // common dialog box structure
ofn.lpstrFilter = "Source\0*.C;*.CXX\0All\0*.*\0"
ofn.nFilterIndex = 1;
Anggota nFilterIndex dari struktur OPENFILENAME menentukan indeks yang menunjukkan filter kotak dialog yang awalnya digunakan. Filter pertama dalam buffer memiliki indeks 1, 2 kedua, dan sebagainya. Jika pengguna mengubah filter saat menggunakan kotak dialog, anggota nFilterIndex diatur ke indeks filter yang dipilih saat dikembalikan.
Anda dapat membuat filter kustom dengan mengatur anggota lpstrCustomFilter ke alamat buffer yang berisi satu filter, dan dengan mengatur anggota nMaxCustFilter ke ukuran buffer, dalam karakter atau byte. Kotak dialog selalu menempatkan filter kustom di awal daftar filter dan, saat kembali, selalu memperbarui bagian pola filter dengan pola dari filter yang dipilih oleh pengguna.
Untuk kotak dialog Gaya penjelajah, ekstensi default dapat berubah jika pengguna memilih filter yang berbeda. Jika pengguna memilih filter yang pola pertamanya adalah formulir *. xxx (yaitu, ekstensi tidak menyertakan karakter kartubebas), kotak dialog menggunakan xxx sebagai ekstensi default. Ini hanya terjadi jika Anda menentukan ekstensi default di anggota lpstrDefExt dari struktur OPENFILENAME . Misalnya, jika pengguna memilih "Source\0*. C;*. Filter CXX\0", ekstensi default berubah menjadi "C". Namun, jika Anda telah mendefinisikan filter sebagai "Source\0*. C*\0", ekstensi default tidak akan berubah karena ekstensi menyertakan kartubebas.
Pesan pemberitahuan CDN_INCLUDEITEM menyediakan cara lain untuk memfilter nama yang ditampilkan kotak dialog. Untuk menggunakan pesan ini, berikan prosedur hook OFNHookProc dan tentukan bendera OFN_ENABLEINCLUDENOTIFY dalam struktur OPENFILENAME saat Anda membuat kotak dialog. Setiap kali pengguna membuka folder, kotak dialog mengirimkan pemberitahuan CDN_INCLUDEITEM ke prosedur hook Anda untuk setiap item di folder yang baru dibuka. Nilai pengembalian prosedur kait menunjukkan apakah kotak dialog harus menampilkan item dalam daftar item folder.
Validasi File dan Direktori
Kecuali seperti yang disebutkan, informasi di bagian ini berlaku untuk kotak dialog Buka dan Simpan Sebagai gaya-penjelajah dan gaya lama.
Kotak dialog secara otomatis memvalidasi nama file yang di ketik oleh pengguna untuk memastikan bahwa nama hanya berisi karakter yang valid. Untuk mengganti validasi karakter nama file, atur bendera OFN_NOVALIDATE .
Untuk memaksa kotak dialog memverifikasi bahwa pengguna menentukan nama file yang sudah ada, atur bendera OFN_FILEMUSTEXIST . Untuk memaksa verifikasi bahwa jalur yang ditentukan ada, atur bendera OFN_PATHMUSTEXIST . Jika Anda mengatur bendera OFN_CREATEPROMPT , kotak dialog meminta izin kepada pengguna untuk membuat file yang tidak ada. Jika bendera ini diatur dan pengguna memilih untuk membuat file baru, kotak dialog ditutup, dan fungsi mengembalikan nama yang ditentukan. Jika tidak, kotak dialog tetap terbuka.
Saat menggunakan kotak dialog Simpan Sebagai , Anda bisa mengarahkan kotak dialog untuk meminta izin kepada pengguna untuk menimpa file yang sudah ada dengan mengatur bendera OFN_OVERWRITEPROMPT .
Secara default, kotak dialog membuat file uji panjang nol untuk menentukan apakah file baru dapat dibuat di direktori yang dipilih. Untuk mencegah pembuatan file pengujian ini, atur bendera OFN_NOTESTFILECREATE .
Jika Anda mengaktifkan prosedur hook, kotak dialog akan memberi tahu prosedur hook Anda saat pelanggaran berbagi jaringan terjadi untuk nama file yang ditentukan oleh pengguna. Jika Anda mengatur bendera OFN_EXPLORER , kotak dialog mengirimkan pesan CDN_SHAREVIOLATION ke prosedur hook. Jika Anda tidak mengatur OFN_EXPLORER, kotak dialog mengirimkan pesan terdaftar SHAREVISTRING ke prosedur kait. Untuk mencegah kotak dialog mengirim pemberitahuan apa pun untuk berbagi pelanggaran, atur bendera OFN_SHAREAWARE .
Jika pengguna memilih kotak centang baca-saja, kotak dialog mengatur bendera OFN_READONLY saat dikembalikan. Untuk menyembunyikan kotak centang Buka Sebagai Baca Saja , atur bendera OFN_HIDEREADONLY . Untuk mencegah kotak dialog mengembalikan nama file yang ada yang memiliki atribut baca-saja, atur bendera OFN_NOREADONLYRETURN .
Untuk mencegah kotak dialog mendereferensikan file tautan, atur nilai OFN_NODEREFERENCELINKS . Dalam hal ini, kotak dialog mengembalikan nama file tautan daripada nama file yang dirujuk oleh file tautan.
Kustomisasi Kotak Dialog Buka dan Simpan Sebagai
Anda bisa mengkustomisasi kotak dialog Buka atau Simpan Sebagai dengan menyediakan prosedur kait, templat kustom, atau keduanya. Namun, versi gaya Explorer dan gaya lama dari kotak dialog berbeda dalam penggunaan templat kustom dan prosedur kait.
Untuk informasi tentang mengkustomisasi kotak dialog Gaya Penjelajah, lihat Prosedur Hook Gaya Penjelajah, Templat Kustom Gaya Penjelajah, dan Pengidentifikasi Kontrol Gaya Penjelajah. Untuk informasi tentang mengkustomisasi kotak dialog gaya lama, lihat Mengkustomisasi kotak dialog Old-Style.
Tabel berikut ini meringkas perbedaan antara dua gaya.
| Kustomisasi | Deskripsi |
|---|---|
| Prosedur Hook gaya penjelajah | Prosedur hook menerima pesan pemberitahuan yang dikirim dari kotak dialog umum dan pesan untuk kontrol tambahan apa pun yang Anda tentukan dengan menentukan templat dialog anak. Prosedur kait tidak menerima pesan untuk kontrol standar kotak dialog default. |
| Templat Kustom gaya Penjelajah | Sistem menggunakan templat kustom untuk membuat kotak dialog anak. Templat dapat menentukan kontrol tambahan, dan dapat menentukan lokasi kluster kontrol standar. Templat kustom tidak menggantikan templat default. |
| Prosedur Hook gaya lama | Prosedur kait menerima semua pesan yang dikirim ke kotak dialog, termasuk pesan untuk kontrol standar dan kontrol kustom apa pun. Prosedur hook juga menerima pesan terdaftar yang dikirim dari kotak dialog umum. |
| Templat Kustom gaya lama | Templat kustom menggantikan templat default. Buat templat kustom dengan memodifikasi templat default yang ditentukan dalam file Fileopen.dlg. |
Judul default untuk kotak dialog Gaya penjelajah dan gaya lama adalah "Buka" atau "Simpan Sebagai." Untuk mengubah judul, tentukan judul baru di anggota lpstrTitle dari struktur OPENFILENAME .
Sarang registri HKEY_CURRENT_USER pengguna dapat berisi nilai yang mengkustomisasi konten kotak dialog Buka dan Simpan Sebagai gaya Explorer. Entri registri ini hanya memengaruhi kotak dialog yang ditampilkan untuk pengguna yang terkait dengan sarang registri.
Untuk menyembunyikan fitur kotak dialog Buka dan Simpan Sebagai gaya Explorer, administrator bisa mengatur nilai dalam tabel berikut di bawah subkunci ini:
HKEY_CURRENT_USER
Software
Microsoft
Windows
CurrentVersion
Policies
Comdlg32
| Nama nilai | Nilai | Makna |
|---|---|---|
| Bilah Tempat | 1 | Menyembunyikan bilah tempat. |
| NoFileMRU | 1 | Menyembunyikan daftar Yang Terakhir Digunakan (MRU). |
| NoBackButton | 1 | Menyembunyikan tombol Kembali . |
Isi bilah Tempat ditentukan oleh konten subkuntang berikut:
HKEY_CURRENT_USER
Software
Microsoft
Windows
CurrentVersion
Policies
Comdlg32
Placesbar
Saat ini, hanya ada lima entri di bawah kunci ini, dan indeks nilai/nama berbasis nol. Nama untuk entri harus Place0, Place1, Place2,Place3, dan Place4. Nilai entri dapat REG_DWORD, REG_SZ, atau nilai REG_EXPAND_SZ yang mengidentifikasi lokasi untuk disertakan di bilah tempat.
| Jenis nilai | Makna |
|---|---|
| REG_DWORD | Nilai CSIDL yang mengidentifikasi folder. Untuk daftar nilai CSIDL, lihat nilai CSIDL. |
| REG_SZ atau REG_EXPAND_SZ | String yang dihentikan null yang menentukan jalur yang valid. |
Prosedur Kait Explorer-Style
Anda bisa mengkustomisasi kotak dialog Buka atau Simpan Sebagai gaya Explorer dengan menyediakan prosedur kait, templat kustom, atau keduanya. Jika Anda menyediakan prosedur kait untuk kotak dialog Gaya penjelajah, sistem membuat kotak dialog yang merupakan anak dari kotak dialog default. Prosedur hook bertindak sebagai prosedur dialog untuk kotak dialog anak. Kotak dialog anak ini didasarkan pada templat kustom, atau pada templat default jika tidak ada yang disediakan. Untuk informasi selengkapnya, lihat Templat Kustom Gaya Penjelajah.
Untuk mengaktifkan prosedur kait untuk kotak dialog Buka atau Simpan Sebagai gaya Explorer, gunakan struktur OPENFILENAME saat Anda membuat kotak dialog. Atur bendera OFN_ENABLEHOOK dan OFN_EXPLORER di anggota Bendera dan tentukan alamat prosedur hook OFNHookProc di anggota lpfnHook . Jika Anda memberikan prosedur kait dan menghilangkan bendera OFN_EXPLORER , Anda harus menggunakan prosedur kait OFNHookProcOldStyle dan Anda akan mendapatkan antarmuka pengguna gaya lama. Untuk informasi selengkapnya, lihat Menyesuaikan kotak dialog Old-Style.
Prosedur kait gaya Explorer menerima berbagai pesan saat kotak dialog terbuka. Manfaatnya meliputi:
- Pesan WM_INITDIALOG dan pesan kotak dialog standar lainnya seperti pesan warna kontrol WM_CTLCOLORDLG .
- Sekumpulan pesan pemberitahuan WM_NOTIFY yang menunjukkan tindakan yang diambil oleh pengguna atau peristiwa kotak dialog lainnya.
- Pesan untuk kontrol tambahan apa pun yang Anda tentukan dengan menentukan templat dialog anak.
Selain itu, ada sekumpulan pesan yang bisa Anda kirim ke kotak dialog Gaya Penjelajah untuk mendapatkan informasi atau untuk mengontrol perilaku dan tampilan kotak dialog.
Jika Anda menyediakan prosedur kait untuk kotak dialog Gaya penjelajah, prosedur kotak dialog default membuat kotak dialog anak saat prosedur dialog default sedang memproses pesan WM_INITDIALOG . Prosedur hook bertindak sebagai prosedur dialog untuk kotak dialog anak. Saat ini, prosedur kait menerima pesan WM_INITDIALOG sendiri dengan parameter lParam yang diatur ke alamat struktur OPENFILENAME yang digunakan untuk menginisialisasi kotak dialog. Setelah dialog anak selesai memproses pesan WM_INITDIALOG sendiri, prosedur dialog default memindahkan kontrol standar, jika perlu, untuk memberi ruang bagi kontrol tambahan dari kotak dialog anak. Prosedur dialog default kemudian mengirim pesan pemberitahuan CDN_INITDONE ke prosedur kait.
Prosedur hook menerima WM_NOTIFY pesan pemberitahuan yang menunjukkan tindakan yang diambil oleh pengguna dalam kotak dialog. Anda dapat menggunakan beberapa pesan ini untuk mengontrol perilaku kotak dialog. Misalnya, prosedur kait menerima pesan CDN_FILEOK saat pengguna memilih nama file dan mengklik tombol OK . Menanggapi pesan ini, prosedur kait dapat menggunakan fungsi SetWindowLong untuk menolak nama yang dipilih dan memaksa kotak dialog untuk tetap terbuka.
Parameter lParam untuk setiap pesan WM_NOTIFY adalah penunjuk ke struktur OFNOTIFY atau OFNOTIFYEX yang menentukan tindakan. Anggota kode di header struktur ini berisi salah satu pesan pemberitahuan berikut.
| Pesan | Makna |
|---|---|
| CDN_FILEOK | Pengguna mengklik tombol OK ; kotak dialog akan ditutup. |
| CDN_FOLDERCHANGE | Pengguna membuka folder atau direktori baru. |
| CDN_HELP | Pengguna mengklik tombol Bantuan . |
| CDN_INCLUDEITEM | Menentukan apakah item harus ditampilkan. Ketika pengguna membuka folder atau direktori baru, sistem mengirimkan pemberitahuan ini untuk setiap item dalam folder atau direktori. Sistem mengirimkan pemberitahuan ini hanya jika bendera OFN_ENABLEINCLUDENOTIFY disetel. |
| CDN_INITDONE | Sistem telah selesai menginisialisasi kotak dialog, dan kotak dialog telah selesai memproses pesan WM_INITDIALOG . Selain itu, sistem telah selesai mengatur kontrol dalam kotak dialog umum untuk memberi ruang bagi kontrol kotak dialog anak (jika ada). |
| CDN_SELCHANGE | Pengguna memilih file atau folder baru dari daftar file. |
| CDN_SHAREVIOLATION | Kotak dialog umum mengalami pelanggaran berbagi pada file yang akan dikembalikan. |
| CDN_TYPECHANGE | Pengguna memilih tipe file baru dari daftar tipe file. |
Pesan WM_NOTIFY ini menggantikan pesan terdaftar FILEOKSTRING, LBSELCHSTRING, SHAREVISTRING, dan HELPMSGSTRING yang digunakan oleh versi kotak dialog Buka dan Simpan Sebagai sebelumnya. Namun, prosedur kait juga menerima pesan yang digantikan setelah pesan WM_NOTIFY jika pemrosesan WM_NOTIFY tidak menggunakan SetWindowLong untuk menetapkan nilai DWL_MSGRESULT bukan nol.
Untuk mengambil informasi tentang status kotak dialog atau untuk mengontrol perilaku dan tampilan kotak dialog, prosedur kait bisa mengirim pesan berikut ke kotak dialog.
| Pesan | Makna |
|---|---|
| CDM_GETFILEPATH | Mengambil jalur dan nama file dari file yang dipilih. |
| CDM_GETFOLDERIDLIST | Mengambil daftar pengidentifikasi item yang terkait dengan folder saat ini yang telah dibuka kotak dialog. Untuk informasi selengkapnya tentang daftar pengidentifikasi item, lihat Pengantar Namespace Shell. |
| CDM_GETFOLDERPATH | Mengambil jalur folder atau direktori saat ini untuk kotak dialog. |
| CDM_GETSPEC | Mengambil nama file (tidak termasuk jalur) file yang saat ini dipilih dalam kotak dialog. |
| CDM_HIDECONTROL | Menyembunyikan kontrol yang ditentukan. |
| CDM_SETCONTROLTEXT | Mengatur teks dalam kontrol yang ditentukan. |
| CDM_SETDEFEXT | Mengatur ekstensi nama file default untuk kotak dialog. |
templat kustom Explorer-Style
Untuk menentukan kontrol tambahan untuk kotak dialog Buka atau Simpan Sebagai gaya Explorer, gunakan struktur OPENFILENAME untuk menentukan templat untuk kotak dialog anak yang berisi kontrol tambahan. Jika templat dialog anak Anda adalah sumber daya dalam aplikasi atau pustaka tautan dinamis, atur bendera OFN_ENABLETEMPLATE di anggota Bendera dan gunakan anggota hInstance dan lpTemplateName struktur untuk mengidentifikasi modul dan nama sumber daya. Jika templat sudah dalam memori, atur bendera OFN_ENABLETEMPLATEHANDLE dan gunakan anggota hInstance untuk mengidentifikasi objek memori yang berisi templat. Saat menyediakan templat dialog anak untuk kotak dialog Gaya Penjelajah, Anda juga harus mengatur bendera OFN_EXPLORER ; jika tidak, sistem mengasumsikan Anda menyediakan templat pengganti untuk kotak dialog gaya lama. Biasanya, jika Anda memberikan kontrol tambahan, Anda juga harus menyediakan prosedur kait gaya Explorer untuk memproses pesan untuk kontrol baru.
Anda bisa membuat templat kotak dialog anak saat Anda melakukan templat lain, kecuali Anda harus menentukan gaya WS_CHILD dan WS_CLIPSIBLINGS dan harus menentukan gaya DS_3DLOOK dan DS_CONTROL . Sistem memerlukan gaya WS_CHILD karena templat Anda menentukan dialog anak dari kotak dialog Buka atau Simpan Sebagai default. Gaya WS_CLIPSIBLINGS memastikan bahwa kotak dialog anak tidak melukis di atas kontrol apa pun dalam kotak dialog default. Gaya DS_3DLOOK memastikan bahwa tampilan kontrol dalam kotak dialog anak konsisten dengan kontrol dalam kotak dialog default. Gaya DS_CONTROL memastikan bahwa pengguna dapat menggunakan TAB dan tombol navigasi lainnya untuk berpindah di antara semua kontrol, default atau kustom, dalam kotak dialog yang dikustomisasi.
Untuk memberi ruang bagi kontrol baru, sistem memperluas kotak dialog default menurut lebar dan tinggi kotak dialog kustom. Secara default, semua kontrol dari kotak dialog kustom diposisikan di bawah kontrol dalam kotak dialog default. Namun, Anda dapat mengganti posisi default ini dengan menyertakan kontrol teks statis dalam templat kotak dialog kustom Anda dan menetapkannya nilai pengidentifikasi kontrol stc32. (Nilai ini ditentukan dalam file header Dlgs.h.) Dalam hal ini, sistem menggunakan kontrol sebagai titik referensi untuk menentukan di mana memposisikan kontrol baru. Semua kontrol baru di atas dan di sebelah kiri kontrol stc32 diposisikan dengan jumlah yang sama di atas dan di sebelah kiri kontrol dalam kotak dialog default. Kontrol baru di bawah dan di sebelah kanan kontrol stc32 diposisikan di bawah ini dan di sebelah kanan kontrol default. Secara umum, setiap kontrol baru diposisikan sehingga memiliki posisi yang sama relatif terhadap kontrol default karena harus kontrol stc32 . Untuk memberi ruang bagi kontrol baru ini, sistem menambahkan ruang ke kiri, kanan, bawah, dan atas kotak dialog default sesuai kebutuhan.
Sistem memerlukan prosedur kait untuk memproses semua pesan yang ditujukan untuk kotak dialog kustom dan karenanya mengirim pesan jendela yang sama ke prosedur kait seperti prosedur kotak dialog lainnya. Misalnya, prosedur kait menerima WM_COMMAND pesan saat pengguna mengklik kontrol tombol dalam kotak dialog kustom. Prosedur kait bertanggung jawab untuk menginisialisasi kontrol ini dan mengambil nilai dari kontrol saat kotak dialog ditutup. Perhatikan bahwa ketika prosedur kait menerima pesan WM_INITDIALOG , sistem belum memindahkan kontrol ke posisi akhir mereka.
Prosedur kotak dialog default menangani pesan untuk semua kontrol dalam kotak dialog default, tetapi prosedur kait menerima pesan pemberitahuan untuk tindakan pengguna pada kontrol ini seperti yang dijelaskan dalam Prosedur Hook Gaya Penjelajah.
Pengidentifikasi Kontrol Explorer-Style
Windows Software Development Kit (SDK) menyediakan templat kotak dialog default untuk kotak dialog gaya lama, tetapi tidak menyertakan templat default untuk kotak dialog gaya Explorer. Ini karena kotak dialog Gaya penjelajah memungkinkan Anda menambahkan kontrol Anda sendiri tetapi tidak mendukung modifikasi templat untuk kontrol standar. Namun, dalam beberapa kasus, Anda mungkin perlu mengetahui pengidentifikasi kontrol yang digunakan dalam templat default. Misalnya, pesan CDM_HIDECONTROL dan CDM_SETCONTROLTEXT memerlukan pengidentifikasi kontrol.
Tabel berikut ini memperlihatkan pengidentifikasi kontrol standar dalam kotak dialog Buka dan Simpan Sebagai gaya Explorer. Pengidentifikasi adalah konstanta yang ditentukan dalam Dlgs.h dan Winuser.h.
| Pengidentifikasi kontrol | Deskripsi kontrol |
|---|---|
| chx1 | Kotak centang baca-saja |
| cmb1 | Kotak kombo drop-down yang menampilkan daftar filter jenis file |
| stc2 | Label untuk kotak kombo cmb1 |
| cmb2 | Kotak kombo drop-down yang menampilkan drive atau folder saat ini, dan yang memungkinkan pengguna untuk memilih drive atau folder untuk dibuka |
| stc4 | Label untuk kotak kombo cmb2 |
| cmb13 | Kotak kombo turun bawah yang menampilkan nama file saat ini, memungkinkan pengguna mengetik nama file untuk dibuka, dan memilih file yang telah dibuka atau disimpan baru-baru ini. Ini untuk aplikasi yang kompatibel dengan Explorer sebelumnya tanpa kait atau templat dialog. Bandingkan dengan edt1. |
| edt1 | Edit kontrol yang menampilkan nama file saat ini, atau memungkinkan pengguna mengetik nama file untuk dibuka. Bandingkan dengan cmb13. |
| stc3 | Label untuk kotak kombo cmb13 dan kontrol edit edt1 |
| lst1 | Kotak daftar yang menampilkan isi drive atau folder saat ini |
| stc1 | Label untuk kotak daftar lst1 |
| IDOK | Tombol perintah OK (tombol tekan) |
| IDCANCEL | Tombol Batalkan perintah (tombol tekan) |
| pshHelp | Tombol perintah Bantuan (tombol tekan) |
Mengkustomisasi kotak dialog Old-Style
Anda bisa mengkustomisasi kotak dialog Buka atau Simpan Sebagai gaya lama dengan menyediakan prosedur kait OFNHookProcOldStyle yang menerima pesan atau pemberitahuan yang ditujukan untuk prosedur kotak dialog default. Anda juga dapat menyediakan templat kustom untuk digunakan sebagai pengganti templat default. Prosedur kait dan templat yang digunakan dengan kotak dialog gaya lama mirip dengan yang digunakan dengan kotak dialog umum lainnya. Untuk informasi selengkapnya, lihat Prosedur Hook untuk Kotak Dialog Umum dan Templat Kustom.
Untuk mengaktifkan prosedur kait untuk kotak dialog Buka atau Simpan Sebagai gaya lama, gunakan struktur OPENFILENAME saat Anda membuat kotak dialog. Atur bendera OFN_ENABLEHOOK di anggota Bendera dan tentukan alamat prosedur kait OFNHookProcOldStyle di anggota lpfnHook . Prosedur kotak dialog mengirimkan pesan WM_INITDIALOG ke prosedur kait dengan parameter Param diatur ke alamat struktur OPENFILENAME yang digunakan untuk menginisialisasi kotak dialog.
Anda bisa menggunakan struktur OPENFILENAME untuk menentukan templat kustom untuk kotak dialog Buka atau Simpan Sebagai untuk digunakan sebagai pengganti templat default. Jika templat kustom Anda adalah sumber daya dalam aplikasi atau pustaka tautan dinamis, atur bendera OFN_ENABLETEMPLATE di anggota Bendera dan gunakan anggota hInstance dan lpTemplateName struktur untuk mengidentifikasi modul dan nama sumber daya. Jika templat kustom Anda sudah dalam memori, atur bendera OFN_ENABLETEMPLATEHANDLE dan gunakan anggota hInstance untuk mengidentifikasi objek memori yang berisi templat. Buat templat kustom dengan memodifikasi templat default yang ditentukan dalam file Fileopen.dlg. Pengidentifikasi kontrol yang digunakan dalam templat dialog Temukan dan Ganti default ditentukan dalam file Dlgs.h.
Secara default, fungsi GetOpenFileName dan GetSaveFileName menampilkan kotak dialog Gaya penjelajah. Jika Anda ingin menampilkan kotak dialog gaya lama, Anda harus menyediakan prosedur kait OFNHookProcOldStyle dan memastikan bahwa bendera OFN_EXPLORER tidak diatur dalam anggota Bendera struktur OPENFILENAME .
Jika Anda mengatur bendera OFN_EXPLORER , sistem memperlakukan prosedur kait atau templat kustom sebagai kustomisasi gaya Explorer. Untuk informasi tentang mengkustomisasi kotak dialog Gaya Penjelajah, lihat Templat Kustom Gaya Penjelajah.