Hinzufügen einer Eigenschaftenseite (ATL-Lernprogramm, Teil 6)

Artikel
04/03/2023

Hinweis

Der ATL-OLE DB-Anbieter-Assistent ist in Visual Studio 2019 und höher nicht verfügbar.

Eigenschaftenseiten werden als separate COM-Objekte implementiert, sodass sie bei Bedarf gemeinsam genutzt werden können. In diesem Schritt führen Sie die folgenden Aufgaben aus, um dem Steuerelement eine Eigenschaftenseite hinzuzufügen:

Erstellen der Eigenschaftenseitenressource
Hinzufügen von Code zum Erstellen und Verwalten der Eigenschaftenseite
Hinzufügen der Eigenschaftenseite zum Steuerelement

Erstellen der Eigenschaftenseitenressource

Um dem Steuerelement eine Eigenschaftenseite hinzuzufügen, verwenden Sie die Vorlage für ATL-Eigenschaftenseiten.

So fügen Sie eine Eigenschaftenseite hinzu

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Polygon.
Klicken Sie im Kontextmenü auf Hinzufügen>Neues Element.
Wählen Sie aus der Liste der Vorlagen ATL>ATL-Eigenschaftenseite aus, und klicken Sie auf Hinzufügen.
Wenn der ATL-Eigenschaftenseiten-Assistent angezeigt wird, geben Sie PolyProp als Kurznamen ein.
Klicken Sie auf Zeichenfolgen, um die Seite Zeichenfolgen zu öffnen, und geben Sie &Polygon als Titel ein.

Der Titel der Eigenschaftenseite ist die Zeichenfolge, die auf der Registerkarte für diese Seite angezeigt wird. Die Dokumentzeichenfolge ist eine Beschreibung, die von einem Eigenschaftenframe in einer Statuszeile oder QuickInfo angezeigt wird. Beachten Sie, dass der standardmäßige Eigenschaftenframe diese Zeichenfolge derzeit nicht verwendet, Sie können also den Standardinhalt beibehalten. Da Sie an diesem Punkt keine Hilfedatei generieren, löschen Sie den Eintrag in diesem Textfeld.
Klicken Sie auf Fertig stellen – das Eigenschaftenseitenobjekt wird erstellt.

Die folgenden drei Dateien werden erstellt:

Datei	Beschreibung
PolyProp.h	Enthält die C++-Klasse `CPolyProp`, die die Eigenschaftenseite implementiert.
PolyProp.cpp	Enthält die Datei „PolyProp.h“.
PolyProp.rgs	Das Registrierungsskript, das das Eigenschaftenseitenobjekt registriert.

Es werden auch folgende Codeänderungen vorgenommen:

Die neue Eigenschaftenseite wird zur Objekteintragszuordnung in „Polygon.cpp“ hinzugefügt.
Die Klasse PolyProp wird zur Datei „Polygon.idl“ hinzugefügt.
Die neue Registrierungsskriptdatei „PolyProp.rgs“ wird zur Projektressource hinzugefügt.
Der Projektressource für die Eigenschaftenseite wird eine Dialogfeldvorlage hinzugefügt.
Die von Ihnen angegebenen Eigenschaftenzeichenfolgen werden zur Tabelle mit Ressourcenzeichenfolgen hinzugefügt.

Fügen Sie jetzt die Felder hinzu, die auf der Eigenschaftenseite angezeigt werden sollen.

So fügen Sie der Eigenschaftenseite Felder hinzu

Doppelklicken Sie im Projektmappen-Explorer auf die Ressourcendatei „Polygon.rc“. Dadurch wird die Ressourcenansicht geöffnet.
Erweitern Sie in der Ressourcenansicht den Knoten Dialog, und doppelklicken Sie auf IDD_POLYPROP. Beachten Sie, dass das angezeigte Dialogfeld leer ist, bis auf einen Text, der angibt, dass Sie hier Ihre Steuerelemente einfügen können.
Wählen Sie diesen Text aus, und ändern Sie im Fenster Eigenschaften den Text für Beschriftung zu Sides:.
Passen Sie die Größe des Beschriftungsfelds an die Textgröße an.
Ziehen Sie ein Bearbeitungssteuerelement aus der Toolbox rechts neben die Beschriftung.
Als Letztes ändern Sie die ID des Bearbeitungssteuerelements im Fenster Eigenschaften zu IDC_SIDES.

Damit ist der Prozess der Erstellung der Eigenschaftenseitenressource abgeschlossen.

Hinzufügen von Code zum Erstellen und Verwalten der Eigenschaftenseite

Nachdem Sie die Eigenschaftenseitenressource erstellt haben, müssen Sie jetzt den Implementierungscode schreiben.

Als Erstes ermöglichen Sie es der CPolyProp-Klasse, die Anzahl von Seiten in Ihrem Objekt festzulegen, wenn die Schaltfläche Anwenden betätigt wird.

So ändern Sie die Anwenden-Funktion zum Festlegen der Anzahl von Seiten

Ersetzen Sie die Funktion Apply in „PolyProp.h“ durch den folgenden Code:

STDMETHOD(Apply)(void)
{
   USES_CONVERSION;
   ATLTRACE(_T("CPolyProp::Apply\n"));
   for (UINT i = 0; i < m_nObjects; i++)
   {
      CComQIPtr<IPolyCtl, &IID_IPolyCtl> pPoly(m_ppUnk[i]);
      short nSides = (short)GetDlgItemInt(IDC_SIDES);
      if FAILED(pPoly->put_Sides(nSides))
      {
         CComPtr<IErrorInfo> pError;
         CComBSTR strError;
         GetErrorInfo(0, &pError);
         pError->GetDescription(&strError);
         MessageBox(OLE2T(strError), _T("Error"), MB_ICONEXCLAMATION);
         return E_FAIL;
      }
   }
   m_bDirty = FALSE;
   return S_OK;
}

An eine Eigenschaftenseite können mehrere Clients gleichzeitig angefügt sein, deshalb wird die Apply-Funktion in einer Schleife ausgeführt und ruft put_Sides für jeden Client mit dem Wert auf, der aus dem Bearbeitungsfeld abgerufen wurde. Sie verwenden die Klasse CComQIPtr, QueryInterface in jedem Objekt ausführt, um die IPolyCtl-Schnittstelle aus der IUnknown-Schnittstelle abzurufen (gespeichert im m_ppUnk-Array).

Der Code überprüft jetzt, ob das Festlegen der Sides-Eigenschaft tatsächlich funktioniert hat. Bei einem Fehler zeigt der Code ein Meldungsfeld mit den Fehlerdetails aus der IErrorInfo-Schnittstelle an. In der Regel fragt ein Container ein Objekt nach der ISupportErrorInfo-Schnittstelle ab und ruft zuerst InterfaceSupportsErrorInfo auf, um zu ermitteln, ob das Objekt das Festlegen von Fehlerinformationen unterstützt. Sie können diese Aufgabe überspringen.

CComPtr kümmert sich automatisch um die Verweiszählung, sodass ein Aufruf von Release in der Schnittstelle nicht erforderlich ist. CComBSTR hilft Ihnen bei der BSTR-Verarbeitung, damit Sie den finalen Aufruf von SysFreeString nicht ausführen müssen. Sie können auch eine der unterschiedlichen Klassen für die Zeichenfolgenkonvertierung verwenden, um BSTR bei Bedarf konvertieren zu können (aus diesem Grund befindet sich das USES_CONVERSION-Makro am Anfang der Funktion).

Sie müssen auch das Änderungsflag der Eigenschaftenseite festlegen, um anzugeben, dass die Schaltfläche Anwenden aktiviert werden muss. Dies erfolgt, wenn ein Benutzer den Wert im Bearbeitungsfeld Seiten ändert.

So verarbeiten Sie die Schaltfläche „Anwenden“

Klicken Sie in der Klassenansicht mit der rechten Maustaste auf CPolyProp, und klicken Sie im Kontextmenü auf Eigenschaften.
Klicken Sie im Fenster Eigenschaften auf das Symbol Ereignisse.
Erweitern Sie in der Ereignisliste den Knoten IDC_SIDES.
Wählen Sie aus, und klicken Sie EN_CHANGEim Dropdownmenü rechts auf <"OnEnChangeSides hinzufügen">. Die Deklaration des Handlers OnEnChangeSides wird zu „Polyprop.h“ hinzugefügt, die Handlerimplementierung zu „Polyprop.cpp“.

Als Nächstes ändern Sie den Handler.

So ändern Sie die OnEnChangeSides-Methode

Fügen Sie folgenden Code in „Polyprop.cpp“ zur OnEnChangeSides-Methode hinzu (löschen Sie dabei sämtlichen Code, den der Assistent eingefügt hat):
```
LRESULT CPolyProp::OnEnChangeSides(WORD /*wNotifyCode*/, WORD /*wID*/, 
   HWND /*hWndCtl*/, BOOL& /*bHandled*/)
{
   SetDirty(TRUE);

   return 0;
}
```

OnEnChangeSides wird aufgerufen, wenn eine WM_COMMAND-Meldung mit der EN_CHANGE-Benachrichtigung für das IDC_SIDES-Steuerelement gesendet wird. OnEnChangeSides ruft dann SetDirty auf, und übergibt TRUE, um anzugeben, dass die Eigenschaftenseite geändert wurde und die Schaltfläche Anwenden aktiviert werden muss.

Hinzufügen der Eigenschaftenseite zum Steuerelement

Die Vorlage und der Assistent für ATL-Eigenschaftenseiten fügen die Eigenschaftenseite nicht automatisch zu Ihrem Steuerelement hinzu, weil mehrere Steuerelemente in Ihrem Projekt vorhanden sein können. Sie müssen einen Eintrag zur Eigenschaftenzuordnung des Steuerelements hinzufügen.

So fügen Sie die Eigenschaftenseite hinzu

Öffnen Sie „PolyCtl.h“, und fügen Sie die folgenden Zeilen zur Eigenschaftenzuordnung hinzu:
```
PROP_ENTRY_TYPE("Sides", 1, CLSID_PolyProp, VT_INT)
PROP_PAGE(CLSID_PolyProp)
```

Die Eigenschaftenzuordnung des Steuerelements sieht jetzt folgendermaßen aus:

BEGIN_PROP_MAP(CPolyCtl)
   PROP_DATA_ENTRY("_cx", m_sizeExtent.cx, VT_UI4)
   PROP_DATA_ENTRY("_cy", m_sizeExtent.cy, VT_UI4)
#ifndef _WIN32_WCE
   PROP_ENTRY_TYPE("FillColor", DISPID_FILLCOLOR, CLSID_StockColorPage, VT_UI4)
#endif
   PROP_ENTRY_TYPE("Sides", 1, CLSID_PolyProp, VT_INT)
   PROP_PAGE(CLSID_PolyProp)
   // Example entries
   // PROP_ENTRY("Property Description", dispid, clsid)
   // PROP_PAGE(CLSID_StockColorPage)
END_PROP_MAP()

Sie hätten auch ein PROP_PAGE-Makro mit der CLSID Ihrer Eigenschaftenseite hinzufügen können. Wenn Sie aber das PROP_ENTRY-Makro wie gezeigt verwenden, wird der Wert der Sides-Eigenschaft auch gespeichert, wenn das Steuerelement gespeichert wird.

Die drei Parameter im Makro sind die Beschreibung der Eigenschaft, die DISPID der Eigenschaft und die CLSID der Eigenschaftenseite, in der sich die Eigenschaft befindet. Dies ist nützlich, wenn Sie z.B. das Steuerelement in Visual Basic laden und die Anzahl von Seiten zur Entwurfszeit festlegen. Da die Anzahl von Seiten gespeichert wird, wird dieser Wert beim erneuten Laden des Visual Basic-Projekts wiederhergestellt.

Erstellen und Testen des Steuerelements

Jetzt erstellen Sie das Steuerelement und fügen es in einen Testcontainer für ActiveX-Steuerelemente ein. Klicken Sie im Testcontainer im Menü Bearbeiten auf PolyCtl-Klassenobjekt. Die Eigenschaftenseite wird mit den von Ihnen hinzugefügten Informationen angezeigt.

Die Schaltfläche Anwenden ist anfangs deaktiviert. Beginnen Sie mit der Eingabe eines Werts in das Feld Seiten. Die Schaltfläche Anwenden wird aktiviert. Wenn Sie den Wert fertig eingegeben haben, klicken Sie auf die Schaltfläche Anwenden. Die Anzeige des Steuerelements ändert sich, und die Schaltfläche Anwenden ist wieder deaktiviert. Geben Sie einen ungültigen Wert ein. Es wird ein Meldungsfeld mit der Fehlerbeschreibung angezeigt, die Sie über die put_Sides-Funktion festgelegt haben.

Als Nächstes fügen Sie Ihr Steuerelement auf einer Webseite ein.

Zurück zu Schritt 5 | Weiter zu Schritt 7

Siehe auch

Tutorial