Tentang Lembar Properti

Lembar properti adalah jendela yang memungkinkan pengguna untuk melihat dan mengedit properti item. Misalnya, aplikasi spreadsheet dapat menggunakan lembar properti untuk memungkinkan pengguna mengatur properti font dan batas sel atau untuk melihat dan mengatur properti perangkat, seperti drive disk, printer, atau mouse.

Bagian ini membahas topik berikut.

• Dasar-Dasar Lembar Properti
• Kotak Dialog Lembar Properti
• Halaman
• Pembuatan Lembar Properti
• Menambahkan dan Menghapus Halaman
• Judul Lembar Properti dan Label Halaman
• Aktivasi Halaman
• Tombol Bantuan
  • Menghapus Tombol Bantuan Bilah Keterangan
• OK, Batalkan, dan Terapkan Tombol
• Penyihir

Dasar-Dasar Lembar Properti

Untuk menerapkan lembar properti dalam aplikasi Anda, sertakan file header Prsht.h dalam proyek Anda. Prsht.h berisi semua pengidentifikasi yang digunakan dengan lembar properti.

Lembar properti berisi satu atau beberapa jendela anak yang tumpang tindih yang disebut halaman, masing-masing berisi jendela kontrol untuk mengatur sekelompok properti terkait. Misalnya, halaman dapat berisi kontrol untuk mengatur properti font item, termasuk gaya jenis, ukuran titik, warna, dan sebagainya. Setiap halaman memiliki tab yang dapat dipilih pengguna untuk membawa halaman ke latar depan lembar properti. Misalnya, aplikasi panel kontrol Tanggal-Waktu menampilkan lembar properti berikut.

Lembar properti standar dengan beberapa halaman bertab memungkinkan pengguna akses acak ke semua properti. Jika lebih tepat untuk mengatur properti secara berurutan, Anda bisa menggunakan wizard.

Kotak Dialog Lembar Properti

Lembar properti dan halaman yang dikandungnya sebenarnya adalah kotak dialog. Lembar properti adalah kotak dialog yang ditentukan sistem yang mengelola halaman dan menyediakan kontainer umum untuk mereka. Kotak dialog lembar properti bisa modal atau tanpa mode. Ini termasuk bingkai, bilah judul, dan empat tombol: BANTUAN OK, Batal, Terapkan, dan (opsional). Prosedur kotak dialog untuk halaman menerima kode pemberitahuan dalam bentuk pesan WM_NOTIFY saat pengguna mengklik tombol.

Catatan

Tidak semua informasi di bagian ini berlaku untuk wizard, yang memiliki tampilan dan perilaku yang agak berbeda. Misalnya, wizard memiliki sekumpulan tombol yang berbeda dan tanpa tab. Untuk informasi selengkapnya, lihat Membuat Wizard.

Setiap halaman dalam lembar properti adalah kotak dialog tanpa mode yang ditentukan aplikasi yang mengelola jendela kontrol yang digunakan untuk melihat dan mengedit properti item. Anda menyediakan templat kotak dialog yang digunakan untuk membuat setiap halaman serta prosedur kotak dialog yang mengelola kontrol dan mengatur properti item terkait.

Lembar properti mengirim kode pemberitahuan ke prosedur kotak dialog untuk halaman saat halaman mendapatkan atau kehilangan aktivasi dan ketika pengguna mengklik tombol OK, Batal, Terapkan, atau Bantuan . Pemberitahuan dikirim dalam bentuk pesan WM_NOTIFY. Parameter lParam adalah alamat struktur NMHDR yang menyertakan handel jendela ke kotak dialog lembar properti.

Beberapa kode pemberitahuan mengharuskan halaman mengembalikan TRUE atau FALSE sebagai respons terhadap pesan WM_NOTIFY. Untuk melakukan ini, halaman harus menggunakan fungsi SetWindowLong untuk mengatur nilai DWL_MSGRESULT untuk kotak dialog halaman ke TRUE atau FALSE.

Halaman

Lembar properti harus berisi setidaknya satu halaman, tetapi tidak boleh berisi lebih dari nilai MAXPROPPAGES seperti yang didefinisikan dalam file header Windows. Setiap halaman memiliki indeks berbasis nol yang ditetapkan lembar properti sesuai dengan urutan halaman ditambahkan ke lembar properti. Indeks digunakan dalam pesan yang Anda kirim ke lembar properti.

Halaman properti dapat berisi kotak dialog berlapis. Jika ya, Anda harus menyertakan gaya WS_EX_CONTROLPARENT untuk kotak dialog tingkat atas dan memanggil fungsi IsDialogMessage dengan handel ke kotak dialog induk. Ini memastikan bahwa pengguna dapat menggunakan mnemonics dan tombol navigasi kotak dialog untuk memindahkan fokus ke kontrol dalam kotak dialog berlapis.

Setiap halaman memiliki ikon dan label yang sesuai. Lembar properti membuat tab untuk setiap halaman dan menampilkan ikon dan label di tab. Semua halaman lembar properti diharapkan menggunakan font nonbold. Untuk memastikan bahwa font tidak tebal, tentukan gaya DS_3DLOOK dalam templat kotak dialog.

Prosedur kotak dialog untuk halaman tidak boleh memanggil fungsi EndDialog. Melakukannya akan menghancurkan seluruh lembar properti, bukan hanya halaman.

Ukuran minimum untuk halaman lembar properti adalah 212 unit dialog secara horizontal dan 114 unit dialog secara vertikal. Jika dialog halaman lebih kecil dari ini, halaman akan diperbesar hingga memenuhi ukuran minimum. File header Prsht.h berisi tiga set ukuran yang direkomendasikan untuk halaman lembar properti, seperti yang diperlihatkan dalam tabel berikut.

Ukuran	Deskripsi
PROP_SM_CXDLG	Lebar, dalam unit dialog, dari halaman lembar properti kecil.
PROP_SM_CYDLG	Tinggi, dalam unit dialog, dari halaman lembar properti kecil.
PROP_MED_CXDLG	Lebar, dalam unit dialog, dari halaman lembar properti berukuran sedang.
PROP_MED_CYDLG	Tinggi, dalam unit dialog, dari halaman lembar properti berukuran sedang.
PROP_LG_CXDLG	Lebar, dalam unit dialog, dari halaman lembar properti besar.
PROP_LG_CYDLG	Tinggi, dalam unit dialog, dari halaman lembar properti besar.

Menggunakan ukuran yang direkomendasikan ini akan membantu memastikan konsistensi visual antara aplikasi Anda dan aplikasi Microsoft Windows lainnya.

Di editor sumber daya Microsoft Visual Studio, Anda dapat membuat halaman dengan ukuran yang sesuai dalam kotak dialog Tambahkan Sumber Daya . Perluas simpul Dialog dan pilih IDD_PROPPAGE_LARGE, IDD_PROPPAGE_MEDIUM, atau IDD_PROPPAGE_SMALL.

Lembar properti secara otomatis berukuran untuk mengakomodasi halaman terbesar.

Pembuatan Lembar Properti

Sebelum membuat lembar properti, Anda harus menentukan satu atau beberapa halaman. Ini melibatkan pengisian struktur PROPSHEETPAGE dengan informasi tentang halaman—ikon, label, templat kotak dialog, prosedur kotak dialog, dan sebagainya—lalu menentukan alamat struktur dalam panggilan ke fungsi CreatePropertySheetPage. Fungsi mengembalikan handel ke jenis HPROPSHEETPAGE yang secara unik mengidentifikasi halaman.

Untuk membuat lembar properti, Anda menentukan alamat struktur PROPSHEETHEADER dalam panggilan ke fungsi PropertySheet. Struktur menentukan ikon dan judul untuk lembar properti dan juga menyertakan alamat array handel HPROPSHEETPAGE yang Anda peroleh dengan menggunakan CreatePropertySheetPage. Saat PropertySheet membuat lembar properti, lembar properti menyertakan halaman yang diidentifikasi dalam array. Halaman muncul di lembar properti dalam urutan yang sama yang terdapat dalam array.

Cara lain untuk menetapkan halaman ke lembar properti adalah dengan menentukan array struktur PROPSHEETPAGE alih-alih array handel HPROPSHEETPAGE. Dalam hal ini, PropertySheet membuat handel untuk halaman sebelum menambahkannya ke lembar properti.

Saat halaman dibuat, prosedur kotak dialognya menerima pesan WM_INITDIALOG. Parameter lParam pesan adalah penunjuk ke salinan struktur PROPSHEETPAGE yang ditentukan saat halaman dibuat. Secara khusus, ketika halaman dibuat, anggota lParam struktur dapat digunakan untuk meneruskan informasi yang ditentukan aplikasi ke prosedur kotak dialog. Dengan pengecualian anggota lParam , struktur ini harus diperlakukan sebagai baca-saja. Memodifikasi apa pun selain lParam akan memiliki konsekuensi yang tidak dapat diprediksi.

Ketika sistem kemudian meneruskan salinan struktur PROPSHEETPAGE halaman ke aplikasi Anda, sistem menggunakan pointer yang sama. Setiap perubahan pada struktur akan diteruskan bersama. Karena anggota lParam diabaikan oleh sistem, anggota lParam dapat dimodifikasi untuk mengirim informasi ke bagian lain dari aplikasi Anda. Misalnya, Anda dapat menggunakan lParam untuk meneruskan informasi ke fungsi panggilan balik PropSheetPageProc halaman.

PropertySheet secara otomatis mengatur ukuran dan posisi awal lembar properti. Posisi didasarkan pada posisi jendela pemilik, dan ukurannya didasarkan pada halaman terbesar yang ditentukan dalam array halaman saat lembar properti dibuat. Jika Anda ingin halaman cocok dengan lebar empat tombol di bagian bawah lembar properti, atur lebar halaman terluas ke 190 unit dialog.

Ukuran lembar properti dihitung dari properti lebar dan tinggi templat dialog dalam file sumber daya. Lihat Sumber Daya DIALOG atau Sumber Daya DIALOGEX untuk detail lebih lanjut. Namun, perhatikan bahwa untuk alasan kompatibilitas, dimensi dihitung relatif terhadap font MS Shell Dlg daripada font yang digunakan oleh halaman. Jika Anda mendesain halaman yang menggunakan font lain, salah satu saran berikut dapat digunakan.

• Sesuaikan dimensi templat dialog untuk mengimbangi perbedaan ukuran antara font MS Shell Dlg dan font yang benar-benar digunakan halaman. Misalnya, jika Anda memilih font yang dua kali lebih lebar dari MS Shell Dlg, maka atur properti lebar templat dialog menjadi dua kali penggunaan normal.
• Gunakan templat DIALOGEX dan atur gaya dialog DS_SHELLFONT. Dalam hal ini, manajer lembar properti menginterpretasikan dimensi templat dialog relatif terhadap font yang digunakan oleh templat dialog.

Menambahkan dan Menghapus Halaman

Setelah membuat lembar properti, aplikasi dapat menambahkan halaman ke akhir kumpulan halaman yang ada dengan mengirim pesan PSM_ADDPAGE . Untuk menyisipkan halaman di antara halaman yang sudah ada, kirim pesan PropSheet_InsertPage . Perhatikan bahwa ukuran lembar properti tidak dapat berubah setelah dibuat. Setiap halaman yang ditambahkan atau disisipkan tidak boleh lebih besar dari halaman terbesar yang saat ini ada di lembar properti. Untuk menghapus halaman, kirim pesan PSM_REMOVEPAGE .

Saat menentukan halaman, Anda dapat menentukan alamat fungsi panggilan balik PropSheetPageProc yang dipanggil lembar properti saat membuat atau menghapus halaman. Menggunakan PropSheetPageProc memberi Anda kesempatan untuk melakukan operasi inisialisasi dan pembersihan untuk halaman individual.

Catatan

Sejumlah pesan dan satu panggilan fungsi terjadi saat lembar properti sedang memanipulasi daftar halaman. Saat tindakan ini sedang berlangsung, mencoba mengubah daftar halaman akan memiliki hasil yang tidak dapat diprediksi. Jangan menambahkan, menyisipkan, atau menghapus halaman dalam implementasi PropSheetPageProc Anda, atau saat menangani pemberitahuan berikut dan pesan Windows.

• PSN_APPLY
• PSN_KILLACTIVE
• PSN_RESET
• PSN_SETACTIVE
• PSN_WIZBACK
• PSN_WIZNEXT
• WM_INITDIALOG
• WM_DESTROY

Jika kebutuhan muncul untuk memodifikasi halaman lembar properti saat Anda menangani salah satu pesan ini atau saat PropSheetPageProc sedang beroperasi, posting pesan Windows privat. Aplikasi Anda tidak akan menerima pesan tersebut sampai setelah manajer lembar properti menyelesaikan tugasnya, di mana akan aman untuk mengubah daftar halaman.

Ketika lembar properti dihancurkan, lembar properti secara otomatis menghancurkan semua halaman yang telah ditambahkan ke dalamnya. Halaman dihancurkan dalam urutan terbalik dari yang ditentukan dalam array yang digunakan untuk membuat halaman. Untuk menghancurkan halaman yang dibuat oleh fungsi CreatePropertySheetPage tetapi tidak ditambahkan ke lembar properti, gunakan fungsi DestroyPropertySheetPage.

Judul Lembar Properti dan Label Halaman

Anda menentukan judul lembar properti dalam struktur PROPSHEETHEADER yang digunakan untuk membuat lembar properti. Jika anggota dwFlags menyertakan nilai PSH_PROPTITLE, lembar properti menambahkan akhiran "Properti" atau awalan "Properti untuk", tergantung pada versinya. Anda dapat mengubah judul setelah lembar properti dibuat dengan menggunakan pesan PSM_SETTITLE. Dalam Wizard Aero, pesan ini dapat digunakan untuk mengubah judul halaman interior secara dinamis.

Secara default, lembar properti menggunakan string nama yang ditentukan dalam templat kotak dialog sebagai label untuk halaman. Anda dapat mengganti string nama dengan menyertakan nilai PSP_USETITLE di anggota dwFlags dari struktur PROPSHEETPAGE yang menentukan halaman. Ketika PSP_USETITLE ditentukan, anggota pszTitle harus berisi alamat string label untuk halaman.

Aktivasi Halaman

Lembar properti hanya dapat memiliki satu halaman aktif pada satu waktu. Halaman yang memiliki aktivasi berada di latar depan tumpukan halaman yang tumpang tindih. Pengguna mengaktifkan halaman dengan memilih tabnya; aplikasi mengaktifkan halaman dengan menggunakan pesan PSM_SETCURSEL.

Lembar properti mengirimkan kode pemberitahuan PSN_KILLACTIVE ke halaman yang akan kehilangan aktivasi. Sebagai respons, halaman harus memvalidasi perubahan apa pun yang telah dilakukan pengguna ke halaman. Jika halaman memerlukan input pengguna tambahan sebelum kehilangan aktivasi, gunakan fungsi SetWindowLong untuk mengatur nilai DWL_MSGRESULT halaman ke TRUE. Selain itu, halaman harus menampilkan kotak pesan yang menjelaskan masalah dan menyediakan tindakan yang direkomendasikan. Atur DWL_MSGRESULT ke FALSE saat tidak apa-apa untuk kehilangan aktivasi.

Sebelum halaman yang mendapatkan aktivasi terlihat, lembar properti mengirimkan kode pemberitahuan PSN_SETACTIVE ke halaman. Halaman harus merespons dengan menginisialisasi jendela kontrolnya.

Tombol Bantuan

Lembar properti dapat menampilkan dua tombol Bantuan: tombol Bantuan lembar properti yang ditampilkan di bagian bawah bingkai, di samping tombol OK/Batal/terapkan, dan tombol bilah keterangan standar yang menyediakan Bantuan peka konteks.

Tombol Bantuan lembar properti bersifat opsional, dan dapat diaktifkan pada halaman berdasarkan halaman. Untuk menampilkan tombol Bantuan lembar properti untuk satu atau beberapa halaman:

• Atur bendera PSH_HASHELP di anggota dwFlags dari struktur PROPSHEETHEADER lembar properti.
• Untuk setiap halaman yang akan menampilkan tombol Bantuan, atur bendera PSP_HASHELP di anggota dwFlags dari struktur PROPSHEETPAGE halaman.

Saat pengguna mengklik tombol Bantuan, halaman aktif menerima kode pemberitahuan PSN_HELP . Halaman harus merespons dengan menampilkan informasi Bantuan, biasanya dengan memanggil fungsi WinHelp.

Menghapus Tombol Bantuan Bilah Keterangan

Tombol Bantuan bilah keterangan ditampilkan secara default, sehingga Bantuan peka konteks selalu tersedia untuk tombol OK/Batal/Terapkan. Namun, tombol ini dapat dihapus, jika perlu. Untuk menghapus tombol Bantuan bilah keterangan lembar properti:

• Untuk versi kontrol umum sebelum versi 5.80, Anda harus menerapkan fungsi panggilan balik lembar properti.
• Untuk versi 5.80 dan yang lebih baru dari kontrol umum, Anda cukup mengatur bendera PSH_NOCONTEXTHELP di anggota dwFlags dari struktur PROPSHEETHEADER lembar properti. Namun, jika Anda memerlukan kompatibilitas mundur dengan versi kontrol umum sebelumnya, Anda harus menerapkan fungsi panggilan balik.

Untuk menerapkan fungsi panggilan balik lembar properti yang menghapus tombol Bantuan bilah keterangan:

• Atur bendera PSH_USECALLBACK di anggota dwFlags dari struktur PROPSHEETHEADER lembar properti.
• Atur anggota pfnCallBack dari struktur PROPSHEETHEADER untuk menunjuk ke fungsi panggilan balik.
• Menerapkan fungsi panggilan balik. Ketika fungsi ini menerima pesan PSCB_PRECREATE , fungsi ini juga akan menerima penunjuk ke templat kotak dialog lembar properti. Hapus gaya DS_CONTEXTHELP dari templat ini.

Contoh berikut mengilustrasikan cara menerapkan fungsi panggilan balik seperti itu:

int CALLBACK RemoveContextHelpProc(HWND hwnd, UINT message, LPARAM lParam)
{
    switch (message) 
    {
    case PSCB_PRECREATE:
        // Remove the DS_CONTEXTHELP style from the
        // dialog box template
        if (((LPDLGTEMPLATEEX)lParam)->signature ==    
           0xFFFF)
           {
            ((LPDLGTEMPLATEEX)lParam)->style 
            &= ~DS_CONTEXTHELP;
        }
        else {
            ((LPDLGTEMPLATE)lParam)->style 
            &= ~DS_CONTEXTHELP;
        }
        return TRUE;
    }
    return TRUE;
}

Jika struktur DLGTEMPLATEEX tidak ditentukan, sertakan deklarasi berikut:

#include <pshpack1.h>

typedef struct DLGTEMPLATEEX
{
    WORD dlgVer;
    WORD signature;
    DWORD helpID;
    DWORD exStyle;
    DWORD style;
    WORD cDlgItems;
    short x;
    short y;
    short cx;
    short cy;
} DLGTEMPLATEEX, *LPDLGTEMPLATEEX;

#include <poppack.h>

OK, Batalkan, dan Terapkan Tombol

Tombol OK dan Terapkan serupa; keduanya mengarahkan halaman lembar properti untuk memvalidasi dan menerapkan perubahan properti yang telah dibuat pengguna. Satu-satunya perbedaan adalah bahwa mengklik tombol OK menyebabkan lembar properti dihancurkan setelah perubahan diterapkan.

Saat pengguna mengklik tombol OK atau Terapkan , lembar properti mengirimkan pemberitahuan PSN_KILLACTIVE ke halaman aktif, memberinya kesempatan untuk memvalidasi perubahan pengguna. Jika perubahan valid, halaman harus memanggil fungsi SetWindowLong dengan nilai DWL_MSGRESULT diatur ke FALSE. Jika perubahan pengguna tidak valid, halaman harus mengatur DWL_MSGRESULT ke TRUE dan menampilkan kotak dialog yang memberi tahu pengguna tentang masalah tersebut. Halaman tetap aktif hingga diatur DWL_MSGRESULT ke FALSE sebagai respons terhadap pesan PSN_KILLACTIVE.

Setelah halaman merespons pemberitahuan PSN_KILLACTIVE dengan mengatur DWL_MSGRESULT ke FALSE, lembar properti akan mengirim pemberitahuan PSN_APPLY ke setiap halaman. Ketika halaman menerima pemberitahuan ini, halaman harus menerapkan properti baru ke item yang sesuai. Untuk menunjukkan ke lembar properti bahwa perubahan valid untuk halaman, panggil SetWindowLong dengan DWL_MSGRESULT diatur ke PSNRET_NOERROR. Jika perubahan tidak valid untuk halaman, kembalikan kesalahan. Melakukannya mencegah lembar properti dihancurkan dan mengembalikan fokus ke halaman yang menerima pemberitahuan PSN_APPLY atau halaman yang memiliki fokus saat tombol Terapkan ditekan. Untuk mengembalikan kesalahan, dan menunjukkan halaman mana yang akan menerima fokus, atur DWL_MSGRESULT ke salah satu nilai berikut.

• PSNRET_INVALID. Lembar properti tidak akan dihancurkan, dan fokus akan dikembalikan ke halaman ini.
• PSNRET_INVALID_NOCHANGEPAGE. Lembar properti tidak akan dihancurkan, dan fokus akan dikembalikan ke halaman yang memiliki fokus saat tombol ditekan.

Aplikasi dapat menggunakan pesan PSM_APPLY untuk mensimulasikan pilihan tombol Terapkan.

Tombol Terapkan awalnya dinonaktifkan saat halaman menjadi aktif, menunjukkan bahwa belum ada perubahan properti yang akan diterapkan. Ketika halaman menerima input melalui salah satu kontrolnya yang menunjukkan bahwa pengguna telah mengedit properti, halaman harus mengirim pesan PSM_CHANGED ke lembar properti. Pesan menyebabkan lembar properti mengaktifkan tombol Terapkan . Jika pengguna kemudian mengklik tombol Terapkan atau Batalkan, halaman harus menginisialisasi ulang kontrolnya lalu mengirim pesan PSM_UNCHANGED untuk menonaktifkan lagi tombol Terapkan.

Terkadang tombol Terapkan menyebabkan halaman membuat perubahan pada lembar properti, dan perubahan tidak dapat dibatalkan. Ketika ini terjadi, halaman harus mengirim pesan PSM_CANCELTOCLOSE ke lembar properti. Pesan menyebabkan lembar properti mengubah teks tombol OK menjadi "Tutup", yang menunjukkan bahwa perubahan yang diterapkan tidak dapat dibatalkan.

Terkadang halaman membuat perubahan pada konfigurasi sistem yang mengharuskan Windows dimulai ulang atau sistem di-boot ulang sebelum perubahan dapat berlaku. Setelah membuat perubahan seperti itu, halaman harus mengirim pesan PSM_RESTARTWINDOWS atau PSM_REBOOTSYSTEM ke lembar properti. Pesan ini menyebabkan fungsi PropertySheet mengembalikan nilai ID_PSRESTARTWINDOWS atau ID_PSREBOOTSYSTEM setelah lembar properti dihancurkan.

Saat pengguna mengklik tombol Batalkan , lembar properti mengirimkan kode pemberitahuan PSN_RESET ke semua halaman, yang menunjukkan bahwa lembar properti akan dihancurkan. Halaman harus menggunakan pemberitahuan untuk melakukan operasi pembersihan.

Wizard

Wizard adalah tipe khusus lembar properti. Wizard dirancang untuk menyajikan halaman satu per satu secara berurutan yang dikontrol oleh aplikasi. Alih-alih memilih dari sekelompok halaman dengan mengklik tab, pengguna menavigasi maju dan mundur melalui urutan, satu halaman sekaligus, dengan mengklik tombol. Misalnya, cuplikan layar berikut menunjukkan halaman selamat datang dari wizard Tambahkan Perangkat Keras:

Cuplikan layar berikut menunjukkan halaman pertama Wizard Aero, gaya baru yang diperkenalkan di Windows Vista.

Lihat Membuat Wizard untuk diskusi lengkap panduan.