MFC ActiveX-Steuerelemente: Hinzufügen von benutzerdefinierten Eigenschaften

Benutzerdefinierte Eigenschaften unterscheiden sich von Aktieneigenschaften darin, dass benutzerdefinierte Eigenschaften nicht bereits von der COleControl Klasse implementiert werden. Eine benutzerdefinierte Eigenschaft wird verwendet, um einen bestimmten Zustand oder ein Erscheinungsbild eines ActiveX-Steuerelements für einen Programmierer mithilfe des Steuerelements verfügbar zu machen.

In diesem Artikel wird beschrieben, wie Sie dem ActiveX-Steuerelement mithilfe des Assistenten zum Hinzufügen von Eigenschaften eine benutzerdefinierte Eigenschaft hinzufügen und die resultierenden Codeänderungen erläutern. Dabei werden folgende Themen behandelt:

• Hinzufügen einer benutzerdefinierten Eigenschaft mit dem Assistenten für Eigenschaften

• Änderungen des Eigenschaften-Assistenten für benutzerdefinierte Eigenschaften hinzufügen

Benutzerdefinierte Eigenschaften gibt es in vier Implementierungsvarianten: Mitgliedervariable, Mitgliedervariable mit Benachrichtigung, Methoden abrufen/festlegen und parametriert.

• Implementierung der Mitgliedsvariablen

  Diese Implementierung stellt den Zustand der Eigenschaft als Membervariable in der Steuerelementklasse dar. Verwenden Sie die Membervariable-Implementierung, wenn es nicht wichtig ist zu wissen, wann sich der Eigenschaftswert ändert. Von den drei Typen erstellt diese Implementierung den geringsten Unterstützungscode für die Eigenschaft. Das Makro für den Verteilungszuordnungseintrag für die Implementierung der Mitgliedvariablen ist Disp_PROPERTY.

• Mitgliedsvariable mit Benachrichtigungsimplementierung

  Diese Implementierung besteht aus einer Membervariable und einer Benachrichtigungsfunktion, die durch den Assistenten zum Hinzufügen von Eigenschaften erstellt wird. Die Benachrichtigungsfunktion wird automatisch vom Framework aufgerufen, nachdem sich der Eigenschaftswert geändert hat. Verwenden Sie die Implementierung der Member-Variable mit Benachrichtigung, wenn Sie benachrichtigt werden müssen, nachdem sich ein Eigenschaftswert geändert hat. Diese Implementierung erfordert mehr Zeit, da ein Funktionsaufruf erforderlich ist. Das Makro für den Dispatch-Map-Eintrag in dieser Implementierung ist DISP_PROPERTY_NOTIFY.

• Methodenimplementierung abrufen/festlegen

  Diese Implementierung besteht aus einem Paar von Mitgliedsfunktionen in der Kontrollklasse. Die Implementierung der Get/Set-Methoden ruft automatisch die Get-Member-Funktion auf, wenn der Benutzer des Steuerelements den aktuellen Wert der Eigenschaft und die Set-Memberfunktion anfordert, wenn der Benutzer des Steuerelements anfordert, dass die Eigenschaft geändert wird. Verwenden Sie diese Implementierung, wenn Sie den Wert einer Eigenschaft während der Laufzeit berechnen müssen, einen vom Benutzer des Steuerelements übergebenen Wert überprüfen, bevor Sie die tatsächliche Eigenschaft ändern oder einen schreibgeschützten Eigenschaftstyp implementieren. Das Dispositionszuordnungseintragsmakro für diese Implementierung ist Disp_PROPERTY_EX. Der folgende Abschnitt verwendet den Assistenten zum Hinzufügen einer benutzerdefinierten Eigenschaft, um die benutzerdefinierte Eigenschaft CircleOffset als Beispiel für diese Implementierung zu veranschaulichen.

• Parametrisierte Implementierung

  Die parametrisierte Implementierung wird vom Assistenten zum Hinzufügen von Eigenschaften unterstützt. Eine parametrisierte Eigenschaft (manchmal auch als Eigenschaftenarray bezeichnet) kann verwendet werden, um über eine einzelne Eigenschaft Ihres Steuerelements auf eine Gruppe von Werten zuzugreifen. Das Dispositionszuordnungseintragsmakro für diese Implementierung ist Disp_PROPERTY_PARAM. Weitere Informationen zur Implementierung dieses Typs finden Sie unter Implementieren einer parametrisierten Eigenschaft im Artikel ActiveX-Steuerelemente: Erweiterte Themen.

Verwenden des Assistenten zum Hinzufügen von Eigenschaften, um eine benutzerdefinierte Eigenschaft hinzuzufügen

Das folgende Verfahren veranschaulicht das Hinzufügen einer benutzerdefinierten Eigenschaft, CircleOffset, die die Implementierung der Get/Set-Methoden verwendet. Mit der benutzerdefinierten Eigenschaft CircleOffset kann der Benutzer des Steuerelements den Kreis von der Mitte des Begrenzungsrechtecks des Steuerelements versetzen. Das Verfahren zum Hinzufügen von benutzerdefinierten Eigenschaften mit einer anderen Implementierung als Get/Set-Methoden ist sehr ähnlich.

Dieses Verfahren kann auch verwendet werden, um andere benutzerdefinierte Eigenschaften hinzuzufügen, die Sie benötigen. Ersetzen Sie ihren benutzerdefinierten Eigenschaftennamen durch den CircleOffset-Eigenschaftsnamen und -parameter.

So fügen Sie die benutzerdefinierte Eigenschaft CircleOffset mithilfe des Assistenten zum Hinzufügen von Eigenschaften hinzu

1. Laden Sie das Steuerelementprojekt.

2. Erweitern Sie in der Klassenansicht den Bibliotheksknoten Ihres Steuerelements.

3. Klicken Sie mit der rechten Maustaste auf den Schnittstellenknoten des Steuerelements (den zweiten Knoten des Bibliotheksknotens), um das Kontextmenü zu öffnen.

4. Klicken Sie im Kontextmenü auf "Hinzufügen" und dann auf "Eigenschaft hinzufügen".

   Dadurch wird der Assistent zum Hinzufügen von Eigenschaften geöffnet.

5. Geben Sie im Feld Eigenschaftsname die Zeichenfolge CircleOffset ein.

6. Klicken Sie für den Implementierungstyp auf "Get/Set-Methoden".

7. Wählen Sie im Feld "Eigenschaftstyp " die Option shortaus.

8. Geben Sie eindeutige Namen für Ihre Get- und Set-Funktionen ein, oder akzeptieren Sie die Standardnamen.

9. Klicken Sie auf Fertig stellen.

Änderungen des Assistenten zum Hinzufügen von Eigenschaften für benutzerdefinierte Eigenschaften

Wenn Sie die benutzerdefinierte Eigenschaft CircleOffset hinzufügen, nimmt der Assistent zum Hinzufügen von Eigenschaften Änderungen an den Header-Dateien (.H) und den Implementierungsdateien (.CPP) der Steuerelementklasse vor.

Die folgenden Zeilen werden der .H-Datei hinzugefügt, um zwei Funktionen mit den Namen GetCircleOffset und SetCircleOffset zu deklarieren.

SHORT GetCircleOffset(void);
void SetCircleOffset(SHORT newVal);

Die folgende Zeile wird der IDL-Datei Ihres Steuerelements hinzugefügt.

[id(2), helpstring("property CircleOffset")] SHORT CircleOffset;
[id(3), helpstring("property MyProperty")] SHORT MyProperty;

Diese Zeile weist der CircleOffset-Eigenschaft eine bestimmte ID-Nummer zu, die von der Position der Methode in der Methoden- und Eigenschaftenliste des Assistenten zum Hinzufügen von Eigenschaften stammt.

Darüber hinaus wird der Versandzuordnung (in der .CPP-DATEI der Steuerungsklasse) die folgende Zeile hinzugefügt, um die Eigenschaft CircleOffset den beiden Handlerfunktionen des Steuerelements zuzuordnen:

DISP_PROPERTY_EX_ID(CMyAxUICtrl, "CircleOffset", dispidCircleOffset, GetCircleOffset, SetCircleOffset, VT_I2)

Schließlich werden die Implementierungen der GetCircleOffset- und SetCircleOffset-Funktionen am Ende der .CPP-Datei des Steuerelements hinzugefügt. In den meisten Fällen ändern Sie die Get-Funktion, um den Wert der Eigenschaft zurückzugeben. Die Set-Funktion enthält in der Regel Code, der entweder vor oder nach änderungen der Eigenschaft ausgeführt werden soll.

void CMyAxUICtrl::SetCircleOffset(SHORT /*newVal*/)
{
   AFX_MANAGE_STATE(AfxGetStaticModuleState());

   // TODO: Add your property handler code here

   SetModifiedFlag();
}

Beachten Sie, dass der Assistent zum Hinzufügen von Eigenschaften dem Text der Set -Funktion automatisch einen Aufruf zu SetModifiedFlag hinzufügt. Durch Aufrufen dieser Funktion wird das Steuerelement als geändert markiert. Wenn ein Steuerelement geändert wurde, wird der neue Zustand gespeichert, wenn der Container gespeichert wird. Diese Funktion sollte aufgerufen werden, wenn eine Eigenschaft, die als Teil des persistenten Zustands des Steuerelements gespeichert wird, den Wert ändert.

Siehe auch

MFC ActiveX-Steuerelemente
MFC ActiveX-Steuerelemente: Eigenschaften
MFC ActiveX-Steuerelemente: Methoden
COleControl-Klasse