Udostępnij za pośrednictwem

Arkusze właściwości i strony właściwości

  • Artykuł

Właściwości obiektu są widoczne dla klientów tak samo jak metody za pośrednictwem interfejsów COM lub implementacji obiektu IDispatch, co umożliwia zmianę właściwości przez programy wywołujące te metody. Technologia OLE stron właściwości umożliwia utworzenie interfejsu użytkownika dla właściwości obiektu zgodnie ze standardami interfejsu użytkownika systemu Windows. W związku z tym właściwości są widoczne dla użytkowników końcowych. Arkusz właściwości obiektu to okno dialogowe z kartami, w którym każda karta odpowiada określonej stronie właściwości. Model OLE do pracy ze stronami właściwości składa się z następujących funkcji:

  • Każda strona właściwości jest zarządzana przez obiekt procesu, który implementuje IPropertyPage lub IPropertyPage2. Każda strona jest identyfikowana z własnym unikatowym identyfikatorem CLSID.
  • Obiekt określa obsługę stron właściwości przez zaimplementowanie ISpecifyPropertyPages. Za pomocą tego interfejsu obiekt wywołujący może uzyskać listę identyfikatorów CLSID identyfikujących określone strony właściwości obsługiwane przez obiekt. Jeśli obiekt określa stronę właściwości CLSID, obiekt musi mieć możliwość odbierania zmian właściwości ze strony właściwości.
  • Dowolny fragment kodu (klienta lub obiektu), który chce wyświetlić arkusz właściwości obiektu przekazuje IUnknown wskaźnik obiektu (lub tablicę, jeśli wiele obiektów ma mieć wpływ) wraz z tablicą identyfikatorów CLSID strony w celu OleCreatePropertyFrame lub OleCreatePropertyFrameIndirect, co powoduje utworzenie okna dialogowego z kartą.
  • Okno dialogowe ramki właściwości tworzy wystąpienie pojedynczego wystąpienia każdej strony właściwości przy użyciu CoCreateInstance dla każdego identyfikatora CLSID. Ramka właściwości uzyskuje co najmniej wskaźnik IPropertyPage dla każdej strony. Ponadto ramka tworzy sam obiekt witryny strony właściwości dla każdej strony. Każda witryna implementuje IPropertyPageSite i ten wskaźnik jest przekazywany do każdej strony. Następnie strona komunikuje się z witryną za pośrednictwem tego wskaźnika interfejsu.
  • Każda strona jest również świadoma obiektu lub obiektów, dla których została wywołana; oznacza to, że ramka właściwości przekazuje IUnknownwskaźniki obiektów do każdej strony. Po poinstruowania, aby zastosować zmiany do obiektów, każda strona wykonuje zapytania dotyczące odpowiedniego wskaźnika interfejsu i przekazuje nowe wartości właściwości do obiektów w dowolny sposób. Nie ma żadnych ograniczeń dotyczących tego, jak taka komunikacja musi się zdarzyć.
  • Obiekt może również obsługiwać przeglądanie poszczególnych właściwości za pośrednictwem IPerPropertyBrows ing interfejs zezwalający obiektowi na określenie właściwości, która powinna otrzymywać początkową fokus, gdy strona właściwości jest wyświetlana i określa ciągi i wartości, które mogą być wyświetlane przez klienta we własnym interfejsie użytkownika.

Te funkcje przedstawiono na poniższym diagramie:

Diagram przedstawiający funkcje arkuszy właściwości i stron właściwości.

Te interfejsy są definiowane w następujący sposób:

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); 
  }

Metoda ISpecifyPropertyPages::GetPages zwraca zliczoną tablicę wartości UUID (GUID), z których każdy opisuje identyfikator CLSID strony właściwości, która będzie wyświetlana przez obiekt. Każdy, kto wywołuje arkusz właściwości za pomocą OleCreatePropertyFrame lub OleCreatePropertyFrameIndirect, przekazuje tę tablicę do funkcji. Należy pamiętać, że jeśli obiekt wywołujący chce wyświetlić strony właściwości dla wielu obiektów, musi on przechodzić tylko przecięcie list CLSID wszystkich obiektów do tych funkcji. Innymi słowy, obiekt wywołujący musi wywoływać tylko strony właściwości, które są wspólne dla wszystkich obiektów.

Ponadto obiekt wywołujący przekazuje również wskaźniki IUnknown do obiektów, których dotyczy problem, do funkcji interfejsu API. Obie funkcje interfejsu API tworzą okno dialogowe ramki właściwości i tworzy wystąpienie witryny strony przy użyciu IPropertyPageSite dla każdej strony, która zostanie załadowana. Za pośrednictwem tego interfejsu strona właściwości może wykonywać następujące czynności:

  • Pobierz bieżący język używany w arkuszu właściwości za pomocą GetLocaleID.
  • Poproś ramkę o przetworzenie naciśnięć za pomocą TranslateAccelerator.
  • Powiadom ramkę zmian na stronie za pomocą OnStatusChange.
  • Uzyskaj wskaźnik interfejsu dla samej ramki za pośrednictwem GetPageContainer, chociaż w tej chwili nie ma żadnych interfejsów zdefiniowanych dla tej funkcji zawsze zwraca E_NOTIMPL.

Ramka właściwości tworzy wystąpienie każdego obiektu strony właściwości i uzyskuje interfejsIPropertyPage każdej strony. Za pomocą tego interfejsu ramka informuje stronę swojej witryny strony (SetPageSite), pobiera wymiary strony i ciągi (GetPageInfo), przekazuje wskaźniki interfejsu do obiektów, których dotyczy problem (SetObjects), informuje stronę, kiedy utworzyć i zniszczyć kontrolki (Uaktywnij i Dezaktywuj), instruuje stronę, aby pokazywała lub zmieniała położenie (Show and Move), instruuje stronę, aby zastosować bieżące wartości do obiektów, których dotyczy problem (Zastosuj), sprawdza, czy strona ma być stosowana stan zanieczyszczonej strony (IsPageDirty), wywołuje pomoc (Pomoc) i przekazuje naciśnięcia do strony (TranslateAccelerator).

Obiekt może również obsługiwać przeglądanie poszczególnych właściwości, co zapewnia:

  1. Sposób (za pośrednictwem IPerPropertyBrowsing i IPropertyPage2) w celu określenia właściwości, na której stronie właściwości należy przy pierwszym wyświetleniu arkusza właściwości.
  2. Sposób (za pośrednictwem IPerPropertyBrowsing) dla obiektu w celu określenia wstępnie zdefiniowanych wartości i odpowiadających im ciągów opisowych, które mogą być wyświetlane we własnym interfejsie użytkownika klienta dla właściwości.

Obiekt może wybrać obsługę (2) bez obsługi (1), na przykład wtedy, gdy obiekt nie ma arkusza właściwości.

Interfejsy IPropertyPage2 i IPerPropertyBrowsing są definiowane w następujący sposób:

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); 
  }

Aby określić jego obsługę takich możliwości, obiekt implementuje IPerPropertyBrowsing. Za pomocą tego interfejsu obiekt wywołujący może zażądać informacji niezbędnych do osiągnięcia przeglądania, takich jak wstępnie zdefiniowane ciągi (GetPredefinedStrings) i wartości (GetPredefinedValue), a także ciąg wyświetlania dla danej właściwości (GetDisplayString).

Ponadto klient może uzyskać identyfikator CLSID strony właściwości, która umożliwia użytkownikowi edytowanie danej właściwości zidentyfikowanej za pomocą identyfikatora DISPID (MapPropertyToPage). Następnie klient instruuje ramkę właściwości, aby aktywować stronę, przekazując identyfikator CLSID i IDENTYFIKATOR DISPID do OleCreatePropertyFrameIndirect. Ramka najpierw aktywuje stronę i przekazuje identyfikator DISPID do strony za pośrednictwem IPropertyPage2::EditProperty. Następnie strona ustawia fokus na pole edycji tej właściwości. W ten sposób klient może przejść z nazwy właściwości we własnym interfejsie użytkownika do strony właściwości, która może manipulować tą właściwością.

strony właściwości i arkusze właściwości