Bagikan melalui

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

Untuk menerapkan lembar properti dalam aplikasi Anda, sertakan file header Prsht.h dalam proyek Anda. Prsht.h mencakup semua pengidentifikasi yang digunakan pada 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 Date-Time menampilkan lembar properti berikut.

cuplikan layar lembar properti dengan dua tab, salah satunya memperlihatkan jam dan kontrol kalender bulanan

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 dalam mode tunggal atau bebas mode. Ini termasuk bingkai, bilah judul, dan empat tombol: OK, Batalkan, Terapkan, dan (opsional) Bantuan. Prosedur kotak dialog untuk halaman menerima kode pemberitahuan dalam bentuk pesan WM_NOTIFY saat pengguna mengklik tombol.

Nota

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 modal yang ditentukan oleh aplikasi dan mengelola jendela kontrol yang digunakan untuk melihat dan mengedit properti suatu 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, Batalkan, Terapkan, atau Bantuan. Pemberitahuan dikirim dalam bentuk pesan WM_NOTIFY. Parameter lParam adalah alamat strukturNMHDRyang 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 fungsiSetWindowLonguntuk 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 penangan ke kotak dialog induk. Ini memastikan bahwa pengguna dapat menggunakan mnemonik dan tombol navigasi kotak dialog untuk memindahkan fokus ke kontrol dalam kotak dialog di dalam kotak dialog lain.

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 fungsiEndDialog. 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 halaman pada lembar properti kecil, dalam satuan dialog.
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 satuan dialog, dari halaman besar lembar properti.
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 strukturPROPSHEETPAGEdengan informasi tentang halaman—ikon, label, templat kotak dialog, prosedur kotak dialog, dan sebagainya—lalu menentukan alamat struktur dalam panggilan ke fungsi CreatePropertySheetPage. Fungsi ini mengembalikan handle ke jenis HPROPSHEETPAGE yang mengidentifikasi halaman secara unik.

Untuk membuat lembar properti, Anda menentukan alamat strukturPROPSHEETHEADER dalam panggilan ke fungsiPropertySheet. Struktur menentukan ikon dan judul untuk lembar properti dan juga menyertakan alamat dari array handle HPROPSHEETPAGE yang Anda peroleh dengan menggunakan CreatePropertySheetPage. Saat PropertySheet membuat lembar properti, lembar tersebut menyertakan halaman-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 HPROPSHEETPAGE handle. Dalam hal ini, PropertySheet membuat handle untuk halaman sebelum menambahkannya ke lembar properti.

Saat halaman dibuat, prosedur kotak dialognya menerima pesan WM_INITDIALOG. Parameter lParam pesan adalah penunjuk ke salinan strukturPROPSHEETPAGE yang ditentukan saat halaman dibuat. Secara khusus, ketika halaman dibuat, struktur anggota lParam dapat digunakan untuk meneruskan informasi yang ditentukan aplikasi ke prosedur kotak dialog. Dengan pengecualian anggota lParam, struktur ini harus diperlakukan sebagai hanya-baca. 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. Karena anggota lParam diabaikan oleh sistem, 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 lebar dan tinggi properti templat dialog dalam file sumber daya. LihatSumber Daya DIALOGatau 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 templatDIALOGEXdan 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.

Nota

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, atau saat menangani pemberitahuan berikut dan pesan Windows.

Jika diperlukan untuk memodifikasi halaman lembar properti saat Anda menangani salah satu pesan ini atau saat PropSheetPageProc sedang beroperasi, kirimkan 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, secara otomatis akan 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 fungsiCreatePropertySheetPage tetapi tidak ditambahkan ke lembar properti, gunakan fungsi DestroyPropertySheetPage.

Judul Lembar Properti dan Label Halaman

Anda menentukan judul lembar properti di strukturPROPSHEETHEADER yang digunakan untuk membuat lembar properti. Jika anggota dwFlags menyertakan nilai PSH_PROPTITLE, lembar properti menambahkan akhiran "Properties" atau awalan "Properties for", 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 pada anggota dwFlags dari struktur PROPSHEETPAGE yang menentukan halaman tersebut. Ketika PSP_USETITLE ditentukan, anggota pszTitle harus berisi alamat string label untuk halaman tersebut.

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 fungsiSetWindowLonguntuk 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 diperbolehkan 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 sensitif terhadap konteks.

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

  • Atur bendera PSH_HASHELP dalam anggota dwFlags dari struktur PROPSHEETHEADER lembar properti.
  • Untuk setiap halaman yang akan menampilkan tombol Bantuan, atur PSP_HASHELP flag 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 fungsiWinHelp.

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 pada 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 menetapkan flag PSH_NOCONTEXTHELP dalam 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 pada lembar properti yang menghapus tombol Bantuan pada bilah keterangan:

  • Atur bendera PSH_USECALLBACK dalam anggota dwFlags dari struktur lembar properti PROPSHEETHEADER.
  • 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 strukturDLGTEMPLATEEXtidak 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 menginstruksikan halaman lembar properti untuk memvalidasi dan menerapkan perubahan properti yang dilakukan oleh pengguna. Satu-satunya perbedaan adalah mengklik tombol OK menyebabkan lembar properti dihancurkan setelah perubahan diterapkan.

Ketika 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 mengatur 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 memberitahu kepada lembar properti bahwa perubahan valid untuk halaman, panggil SetWindowLong dengan DWL_MSGRESULT diatur ke PSNRET_NOERROR. Jika perubahan tidak valid untuk halaman, kembalikan pesan 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 dihapus, dan fokus akan kembali 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 pemilihan tombol Terapkan.

Tombol Terapkan awalnya dinonaktifkan ketika 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-pesan ini menyebabkan fungsiPropertySheet mengembalikan nilai ID_PSRESTARTWINDOWS atau ID_PSREBOOTSYSTEM setelah lembar properti dihapus.

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.

Penyihir

Wizard adalah jenis khusus dari 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 dari halaman selamat datang asisten

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

cuplikan layar halaman pertama Aero Wizard

Lihat Membuat Wizard untuk pembahasan lengkap mengenai wizard.

  • Last updated on