Lembar Properti dan Halaman Properti

Properti objek diekspos ke klien sama dengan metode melalui antarmuka COM atau implementasi IDispatch objek, memungkinkan properti diubah oleh program yang memanggil metode ini. Teknologi OLE halaman properti menyediakan sarana untuk membangun antarmuka pengguna untuk properti objek sesuai dengan standar antarmuka pengguna Windows. Dengan demikian, properti diekspos ke pengguna akhir. Lembar properti objek adalah dialog bertab di mana setiap tab sesuai dengan halaman properti tertentu. Model OLE untuk bekerja dengan halaman properti terdiri dari fitur-fitur berikut:

• Setiap halaman properti dikelola oleh objek dalam proses yang mengimplementasikan IPropertyPage atau IPropertyPage2. Setiap halaman diidentifikasi dengan CLSID uniknya sendiri.
• Objek menentukan dukungannya untuk halaman properti dengan menerapkan ISpecifyPropertyPages. Melalui antarmuka ini, pemanggil dapat memperoleh daftar CLSID yang mengidentifikasi halaman properti tertentu yang didukung objek. Jika objek menentukan halaman properti CLSID, objek harus dapat menerima perubahan properti dari halaman properti.
• Setiap bagian kode (klien atau objek) yang ingin menampilkan lembar properti objek melewati pointer IUnknown objek (atau array jika beberapa objek akan terpengaruh) bersama dengan array CLSID halaman ke OleCreatePropertyFrame atau OleCreatePropertyFrameIndirect, yang membuat kotak dialog bertab.
• Dialog bingkai properti membuat instans tunggal dari setiap halaman properti, menggunakan CoCreateInstance pada setiap CLSID. Bingkai properti memperoleh setidaknya penunjuk IPropertyPage untuk setiap halaman. Selain itu, bingkai membuat objek situs halaman properti itu sendiri untuk setiap halaman. Setiap situs mengimplementasikan IPropertyPageSite dan pointer ini diteruskan ke setiap halaman. Halaman kemudian berkomunikasi dengan situs melalui penunjuk antarmuka ini.
• Setiap halaman juga mengetahui objek atau objek yang telah dipanggil; artinya, bingkai properti meneruskan pointer IUnknownobjek ke setiap halaman. Ketika diinstruksikan untuk menerapkan perubahan pada objek, setiap halaman meminta penunjuk antarmuka yang sesuai dan meneruskan nilai properti baru ke objek dengan cara apa pun yang diinginkan. Tidak ada ketentuan tentang bagaimana komunikasi tersebut harus terjadi.
• Objek juga dapat mendukung per properti yang menelusuri melalui antarmuka IPerPropertyBrowsing yang mengizinkan objek untuk menentukan properti mana yang harus menerima fokus awal ketika halaman properti ditampilkan dan untuk menentukan string dan nilai yang dapat ditampilkan oleh klien di antarmuka penggunanya sendiri.

Fitur-fitur ini diilustrasikan dalam diagram berikut:

Antarmuka ini didefinisikan sebagai berikut:

interface ISpecifyPropertyPages : IUnknown 
  { 
    HRESULT GetPages([out] CAUUID *pPages); 
  }; 
 
 
interface IPropertyPage : IUnknown 
  { 
    HRESULT SetPageSite([in] IPropertyPageSite *pPageSite); 
    HRESULT Activate([in] HWND hWndParent, [in] LPCRECT prc 
        , [in] BOOL bModal); 
    HRESULT Deactivate(void); 
    HRESULT GetPageInfo([out] PROPPAGEINFO *pPageInfo); 
    HRESULT SetObjects([in] ULONG cObjects 
        , [in, max_is(cObjects)] IUnknown **ppunk); 
    HRESULT Show([in] UINT nCmdShow); 
    HRESULT Move([in] LPCRECT prc); 
    HRESULT IsPageDirty(void); 
    HRESULT Apply(void); 
    HRESULT Help([in] LPCOLESTR pszHelpDir); 
    HRESULT TranslateAccelerator([in] LPMSG pMsg); 
  } 
 
interface IPropertyPageSite : IUnknown 
  { 
    HRESULT OnStatusChange([in] DWORD dwFlags); 
    HRESULT GetLocaleID([out] LCID *pLocaleID); 
    HRESULT GetPageContainer([out] IUnknown **ppUnk); 
    HRESULT TranslateAccelerator([in] LPMSG pMsg); 
  } 
 

Metode ISpecifyPropertyPages::GetPages mengembalikan nilai array UUID (GUID) yang dihitung yang masing-masing menjelaskan CLSID halaman properti yang ingin ditampilkan objek. Siapa perintah lembar properti dengan OleCreatePropertyFrame atau OleCreatePropertyFrameIndirect meneruskan array ini ke fungsi . Perhatikan bahwa jika pemanggil ingin menampilkan halaman properti untuk beberapa objek, pemanggil hanya boleh meneruskan persimpangan daftar CLSID dari semua objek ke fungsi ini. Dengan kata lain, pemanggil hanya boleh memanggil halaman properti yang umum untuk semua objek.

Selain itu, penelepon meneruskan pointer IUnknown ke objek yang terpengaruh ke fungsi API juga. Kedua fungsi API membuat dialog bingkai properti dan membuat instans situs halaman dengan IPropertyPageSite untuk setiap halaman yang akan dimuat. Melalui antarmuka ini, halaman properti dapat:

• Ambil bahasa saat ini yang digunakan dalam lembar properti melalui GetLocaleID.
• Minta bingkai untuk memproses penekanan tombol melalui TranslateAccelerator.
• Beri tahu bingkai perubahan di halaman melalui OnStatusChange.
• Dapatkan penunjuk antarmuka untuk bingkai itu sendiri melalui GetPageContainer, meskipun tidak ada antarmuka yang ditentukan untuk bingkai saat ini untuk fungsi ini selalu mengembalikan E_NOTIMPL.

Bingkai properti membuat instans setiap objek halaman properti dan mendapatkan antarmuka IPropertyPage setiap halaman. Melalui antarmuka ini, bingkai menginformasikan halaman situs halamannya (SetPageSite), mengambil dimensi dan string halaman (GetPageInfo), meneruskan pointer antarmuka ke objek yang terpengaruh (SetObjects), memberi tahu halaman kapan harus membuat dan menghancurkan kontrolnya (Aktifkan dan Nonaktifkan), menginstruksikan halaman untuk menampilkan atau memposisikan ulang dirinya sendiri (Tampilkan dan Pindahkan), menginstruksikan halaman untuk menerapkan nilainya saat ini ke objek yang terpengaruh (Terapkan), memeriksa status kotor halaman (IsPageDirty), memanggil bantuan (Bantuan), dan meneruskan penekanan tombol ke halaman (TranslateAccelerator).

Objek juga dapat mendukung penjelajahan per properti, yang menyediakan:

1. Cara (melalui IPerPropertyBrowsing dan IPropertyPage2) untuk menentukan properti mana di halaman properti mana yang harus diberi fokus awal saat lembar properti pertama kali ditampilkan
2. Cara (melalui IPerPropertyBrowsing) agar objek menentukan nilai yang telah ditentukan dan string deskriptif terkait yang dapat ditampilkan di antarmuka pengguna klien sendiri untuk properti.

Objek dapat memilih untuk mendukung (2) tanpa dukungan (1), seperti ketika objek tidak memiliki lembar properti.

Antarmuka IPropertyPage2 dan IPerPropertyBrowsing didefinisikan sebagai berikut:

interface IPerPropertyBrowsing : IUnknown 
  { 
    HRESULT GetDisplayString([in] DISPID dispID, [out] BSTR *pbstr); 
    HRESULT MapPropertyToPage([in] DISPID dispID, [out] CLSID *pclsid); 
    HRESULT GetPredefinedStrings([in] DISPID dispID, [out] CALPOLESTR *pcaStringsOut, [out] CADWORD *pcaCookiesOut); 
    HRESULT GetPredefinedValue([in] DISPID dispID, [in] DWORD dwCookie, [out] VARIANT *pvarOut); 
  } 
 
interface IPropertyPage2 : IPropertyPage 
  { 
    HRESULT EditProperty([in] DISPID dispID); 
  } 
 

Untuk menentukan dukungannya untuk kemampuan tersebut, objek mengimplementasikan IPerPropertyBrowsing. Melalui antarmuka ini, pemanggil dapat meminta informasi yang diperlukan untuk mencapai penjelajahan, seperti string yang telah ditentukan sebelumnya (GetPredefinedStrings) dan nilai (GetPredefinedValue) serta string tampilan untuk properti tertentu (GetDisplayString).

Selain itu, klien dapat memperoleh CLSID halaman properti yang memungkinkan pengguna mengedit properti tertentu yang diidentifikasi dengan DISPID (MapPropertyToPage). Klien kemudian menginstruksikan bingkai properti untuk mengaktifkan halaman tersebut pada awalnya dengan meneruskan CLSID dan DISPID ke OleCreatePropertyFrameIndirect. Bingkai mengaktifkan halaman tersebut terlebih dahulu dan meneruskan DISPID ke halaman melalui IPropertyPage2::EditProperty. Halaman kemudian mengatur fokus ke bidang pengeditan properti tersebut. Dengan cara ini, klien dapat melompat dari nama properti di antarmuka penggunanya sendiri ke halaman properti yang dapat memanipulasi properti tersebut.

Topik terkait

Halaman Properti dan Lembar Properti