Eigenschaftenblätter und Eigenschaftenseiten

Die Eigenschaften eines Objekts werden clients über COM-Schnittstellen oder die IDispatch-Implementierung des Objekts auf die gleichen Weise wie Methoden verfügbar gemacht, sodass Eigenschaften von Programmen geändert werden können, die diese Methoden aufrufen. Die OLE-Technologie von Eigenschaftenseiten bietet die Möglichkeit, eine Benutzeroberfläche für die Eigenschaften eines Objekts gemäß den Windows-Benutzeroberflächesstandards zu erstellen. Daher werden die Eigenschaften für Endbenutzer verfügbar gemacht. Das Eigenschaftenblatt eines Objekts ist ein Registerkartendialogfeld, in dem jede Registerkarte einer bestimmten Eigenschaftenseite entspricht. Das OLE-Modell für die Arbeit mit Eigenschaftenseiten besteht aus den folgenden Features:

• Jede Eigenschaftenseite wird von einem prozessinternen Objekt verwaltet, das entweder IPropertyPage oder IPropertyPage2 implementiert. Jede Seite wird mit einer eigenen eindeutigen CLSID identifiziert.
• Ein -Objekt gibt die Unterstützung für Eigenschaftenseiten an, indem ISpecifyPropertyPages implementiert wird. Über diese Schnittstelle kann der Aufrufer eine Liste von CLSIDs abrufen, die die spezifischen Eigenschaftenseiten identifizieren, die das Objekt unterstützt. Wenn das Objekt eine CLSID der Eigenschaftenseite angibt, muss das Objekt Eigenschaftenänderungen von der Eigenschaftenseite empfangen können.
• Jeder Codeteil (Client oder Objekt), der das Eigenschaftenblatt eines Objekts anzeigen möchte, übergibt den IUnknown-Zeiger des Objekts (oder ein Array, wenn mehrere Objekte betroffen sein sollen) zusammen mit einem Array von Seiten-CLSIDs an OleCreatePropertyFrame oder OleCreatePropertyFrameIndirect, wodurch das Registerkartendialogfeld erstellt wird.
• Das Dialogfeld "Eigenschaftenrahmen" instanziiert eine einzelne instance jeder Eigenschaftenseite, wobei CoCreateInstance für jede CLSID verwendet wird. Der Eigenschaftenrahmen ruft mindestens einen IPropertyPage-Zeiger für jede Seite ab. Darüber hinaus erstellt der Frame für jede Seite selbst ein Eigenschaftenseitenwebsiteobjekt. Jede Website implementiert IPropertyPageSite , und dieser Zeiger wird an jede Seite übergeben. Die Seite kommuniziert dann über diesen Schnittstellenzeiger mit der Website.
• Jede Seite wird auch auf das Objekt oder die Objekte aufmerksam gemacht, für die sie aufgerufen wurde. Das heißt, der Eigenschaftenrahmen übergibt die IUnknown-Zeigerder -Objekte an jede Seite. Wenn sie angewiesen wird, Änderungen auf die Objekte anzuwenden, fragt jede Seite den entsprechenden Schnittstellenzeiger ab und übergibt neue Eigenschaftswerte in beliebiger Weise an die Objekte. Es gibt keine Vorgabe, wie eine solche Kommunikation erfolgen muss.
• Ein -Objekt kann auch das Durchsuchen der IPerPropertyBrowsing-Schnittstelle pro Eigenschaft unterstützen, sodass das Objekt angeben kann, welche Eigenschaft beim Anzeigen der Eigenschaftenseite den anfänglichen Fokus erhalten soll, und Zeichenfolgen und Werte anzugeben, die vom Client auf seiner eigenen Benutzeroberfläche angezeigt werden können.

Diese Features werden im folgenden Diagramm veranschaulicht:

Diese Schnittstellen werden in der folgenden Weise definiert:

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

Die ISpecifyPropertyPages::GetPages-Methode gibt ein gezähltes Array von GUID-Werten (UUID) zurück, die jeweils die CLSID einer Eigenschaftenseite beschreiben, die das Objekt angezeigt werden soll. Wer das Eigenschaftenblatt mit OleCreatePropertyFrame oder OleCreatePropertyFrameIndirect aufruft, übergibt dieses Array an die Funktion. Wenn der Aufrufer Eigenschaftenseiten für mehrere Objekte anzeigen möchte, muss er nur die Schnittmenge der CLSID-Listen aller Objekte an diese Funktionen übergeben. Anders ausgedrückt: Der Aufrufer darf nur Eigenschaftenseiten aufrufen, die allen -Objekten gemeinsam sind.

Darüber hinaus übergibt der Aufrufer die IUnknown-Zeiger an die betroffenen Objekte auch an die API-Funktionen. Beide API-Funktionen erstellen ein Eigenschaftenframedialogfeld und instanziieren eine Seitenwebsite mit IPropertyPageSite für jede seite, die geladen wird. Über diese Schnittstelle kann eine Eigenschaftenseite Folgendes ausführen:

• Rufen Sie die aktuelle Sprache ab, die im Eigenschaftenblatt über GetLocaleID verwendet wird.
• Bitten Sie den Frame, Tastatureingaben über TranslateAccelerator zu verarbeiten.
• Benachrichtigen Sie den Frame über Änderungen auf der Seite über OnStatusChange.
• Abrufen eines Schnittstellenzeigers für den Frame selbst über GetPageContainer, obwohl derzeit keine Schnittstellen für den Frame definiert sind, gibt diese Funktion immer E_NOTIMPL zurück.

Der Eigenschaftenrahmen instanziiert jedes Eigenschaftenseitenobjekt und ruft die IPropertyPage-Schnittstelle jeder Seite ab. Über diese Schnittstelle informiert der Frame die Seite seiner Seitenwebsite (SetPageSite), ruft Seitenabmessungen und Zeichenfolgen (GetPageInfo) ab, übergibt die Schnittstellenzeiger auf die betroffenen Objekte (SetObjects), teilt der Seite mit, wann die Steuerelemente erstellt und zerstört werden soll (Aktivieren und Deaktivieren), weist die Seite an, sich selbst anzuzeigen oder neu zu positionieren (Anzeigen und Verschieben), weist die Seite an, ihre aktuellen Werte auf die betroffenen Objekte anzuwenden (Apply Apply) ), überprüft die modifiziert status der Seite (IsPageDirty), ruft Hilfe (Hilfe) auf und übergibt Tastatureingaben an die Seite (TranslateAccelerator).

Ein -Objekt kann auch das Durchsuchen pro Eigenschaft unterstützen, was Folgendes bietet:

1. Eine Möglichkeit (über IPerPropertyBrowsing und IPropertyPage2), um anzugeben, welche Eigenschaft auf welcher Eigenschaftenseite den anfänglichen Fokus erhalten soll, wenn ein Eigenschaftenblatt zum ersten Mal angezeigt wird.
2. Eine Möglichkeit (über IPerPropertyBrowsing) für das Objekt, vordefinierte Werte und entsprechende beschreibende Zeichenfolgen anzugeben, die in der eigenen Benutzeroberfläche eines Clients für Eigenschaften angezeigt werden können.

Ein Objekt kann (2) ohne Unterstützung (1) unterstützen, z. B. wenn das Objekt kein Eigenschaftenblatt aufweist.

Die Schnittstellen IPropertyPage2 und IPerPropertyBrowsing sind wie folgt definiert:

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

Um die Unterstützung für solche Funktionen anzugeben, implementiert das Objekt IPerPropertyBrowsing. Über diese Schnittstelle kann der Aufrufer die informationen anfordern, die zum Erreichen des Browsens erforderlich sind, z. B. vordefinierte Zeichenfolgen (GetPredefinedStrings) und Werte (GetPredefinedValue) sowie eine Anzeigezeichenfolge für eine bestimmte Eigenschaft (GetDisplayString).

Darüber hinaus kann der Client die CLSID der Eigenschaftenseite abrufen, die es dem Benutzer ermöglicht, eine bestimmte Eigenschaft zu bearbeiten, die mit einer DISPID (MapPropertyToPage) identifiziert wurde. Der Client weist dann den Eigenschaftenrahmen an, diese Seite zunächst zu aktivieren, indem er die CLSID und die DISPID an OleCreatePropertyFrameIndirect übergibt. Der Frame aktiviert zuerst diese Seite und übergibt die DISPID über IPropertyPage2::EditProperty an die Seite. Die Seite legt dann den Fokus auf das Bearbeitungsfeld dieser Eigenschaft fest. Auf diese Weise kann ein Client von einem Eigenschaftennamen in seiner eigenen Benutzeroberfläche zur Eigenschaftenseite springen, die diese Eigenschaft bearbeiten kann.

Zugehörige Themen

Eigenschaftenseiten und Eigenschaftenblätter