TN071: MFC-IOleCommandTarget-Implementierung

Die IOleCommandTarget Schnittstelle ermöglicht Objekten und deren Containern das Verteilen von Befehlen aneinander. Beispielsweise können die Symbolleisten eines Objekts Schaltflächen für Befehle wie Print, , Print Preview, , Saveund NewZoom. Wenn ein solches Objekt in einen Container eingebettet wurde, der unterstützt IOleCommandTarget, kann das Objekt seine Schaltflächen aktivieren und die Befehle zur Verarbeitung an den Container weiterleiten, wenn der Benutzer darauf geklickt hat. Wenn ein Container das eingebettete Objekt selbst drucken wollte, kann er diese Anforderung durch Senden eines Befehls über die IOleCommandTarget Schnittstelle des eingebetteten Objekts vornehmen.

IOleCommandTarget ist eine automatisierungsähnliche Schnittstelle, in der sie von einem Client zum Aufrufen von Methoden auf einem Server verwendet wird. Die Verwendung IOleCommandTarget spart jedoch den Aufwand der Aufrufe über Automatisierungsschnittstellen, da Programmierer nicht die in der Regel teure Invoke Methode verwenden IDispatchmüssen.

In MFC wird die IOleCommandTarget Schnittstelle von aktiven Dokumentservern verwendet, um aktiven Dokumentcontainern das Verteilen von Befehlen an den Server zu ermöglichen. Die Active Document Server-Klasse CDocObjectServerItemverwendet MFC-Schnittstellenzuordnungen (siehe TN038: MFC/OLE IUnknown-Implementierung), um die IOleCommandTarget Schnittstelle zu implementieren.

IOleCommandTarget wird auch in der COleFrameHook Klasse implementiert. COleFrameHook ist eine nicht dokumentierte MFC-Klasse, die die Framefensterfunktionalität von direkten Bearbeitungscontainern implementiert. COleFrameHook verwendet auch MFC-Schnittstellenzuordnungen, um die IOleCommandTarget Schnittstelle zu implementieren. COleFrameHookDie Implementierung von IOleCommandTarget OLE-Befehlen leitet ole-Befehle an COleDocObjectItemabgeleitete aktive Dokumentcontainer weiter. Auf diese Weise kann jeder MFC Active Document Container Nachrichten von enthaltenen aktiven Dokumentservern empfangen.

MFC OLE Command Karten

MFC-Entwickler können die Vorteile IOleCommandTarget nutzen, indem Sie MFC OLE-Befehlszuordnungen verwenden. OLE-Befehlszuordnungen ähneln Nachrichtenzuordnungen, da sie zum Zuordnen von OLE-Befehlen zu Memberfunktionen der Klasse verwendet werden können, die die Befehlszuordnung enthält. Um dies zu vereinfachen, platzieren Sie Makros in der Befehlszuordnung, um die OLE-Befehlsgruppe des befehls anzugeben, den Sie behandeln möchten, den OLE-Befehl und die Befehls-ID der WM_COMMAND Nachricht, die gesendet wird, wenn der OLE-Befehl empfangen wird. MFC stellt auch eine Reihe vordefinierter Makros für standardmäßige OLE-Befehle bereit. Eine Liste der standardmäßigen OLE-Befehle, die ursprünglich für die Verwendung mit Microsoft Office-App lications entwickelt wurden, finden Sie in der OLECMDID-Aufzählung, die in docobj.h definiert ist.

Wenn ein OLE-Befehl von einer MFC-Anwendung empfangen wird, die eine OLE-Befehlszuordnung enthält, versucht MFC, die Befehls-ID und Befehlsgruppe für den angeforderten Befehl in der OLE-Befehlszuordnung der Anwendung zu finden. Wenn eine Übereinstimmung gefunden wird, wird eine WM_COMMAND Nachricht an die Anwendung mit der Befehlszuordnung mit der ID des angeforderten Befehls verteilt. (Siehe beschreibung unten ON_OLECMD .) Auf diese Weise werden OLE-Befehle, die an eine Anwendung verteilt werden, in WM_COMMAND Nachrichten von MFC umgewandelt. Die WM_COMMAND Nachrichten werden dann mithilfe der MFC-Standardbefehlsroutingarchitektur durch die Nachrichtenzuordnungen der Anwendung weitergeleitet.

Im Gegensatz zu Nachrichtenzuordnungen werden MFC OLE-Befehlszuordnungen von ClassWizard nicht unterstützt. MFC-Entwickler müssen die OLE-Befehlszuordnungsunterstützung und OLE-Befehlszuordnungseinträge manuell hinzufügen. OLE-Befehlszuordnungen können MFC Active-Dokumentservern in jeder Klasse hinzugefügt werden, die sich in der WM_COMMAND Nachrichtenroutingkette befindet, wenn das aktive Dokument in einem Container aktiv ist. Zu diesen Klassen gehören die Klassen der Anwendung, die von CWinApp, CView, CDocument und COleIPFrameWnd abgeleitet sind. In Aktiven Dokumentcontainern können OLE-Befehlszuordnungen nur der von COleDocObjectItem abgeleiteten Klasse hinzugefügt werden. Außerdem werden die WM_COMMAND Nachrichten in aktiven Dokumentcontainern nur an die Nachrichtenzuordnung in der COleDocObjectItemabgeleiteten Klasse verteilt.

OLE-Befehlszuordnungsmakros

Verwenden Sie die folgenden Makros, um Ihrer Klasse Befehlszuordnungsfunktionen hinzuzufügen:

DECLARE_OLECMD_MAP ()

Dieses Makro wird in die Klassendeklaration (in der Regel in der Headerdatei) der Klasse eingefügt, die die Befehlszuordnung enthält.

BEGIN_OLECMD_MAP(theClass, baseClass)

theClass
Name der Klasse, die die Befehlszuordnung enthält.

Baseclass
Name der Basisklasse der Klasse, die die Befehlszuordnung enthält.

Mit diesem Makro wird der Anfang der Befehlszuordnung markiert. Verwenden Sie dieses Makro in der Implementierungsdatei für die Klasse, die die Befehlszuordnung enthält.

END_OLECMD_MAP()

Mit diesem Makro wird das Ende der Befehlszuordnung markiert. Verwenden Sie dieses Makro in der Implementierungsdatei für die Klasse, die die Befehlszuordnung enthält. Dieses Makro muss immer dem BEGIN_OLECMD_MAP Makro folgen.

ON_OLECMD(pguid, olecmdid, id)

pguid
Zeigen Sie auf die GUID der Befehlsgruppe des OLE-Befehls. Dieser Parameter ist NULL für die standardmäßige OLE-Befehlsgruppe.

olecmdid
OLE-Befehls-ID des befehls, der aufgerufen werden soll.

id
ID der WM_COMMAND Nachricht, die an die Anwendung gesendet werden soll, die die Befehlszuordnung enthält, wenn dieser OLE-Befehl aufgerufen wird.

Verwenden Sie das ON_OLECMD-Makro in der Befehlszuordnung, um Einträge für die OLE-Befehle hinzuzufügen, die Sie behandeln möchten. Wenn die OLE-Befehle empfangen werden, werden sie mithilfe der standardmäßigen MFC-Befehlsroutingarchitektur in die angegebene WM_COMMAND Nachricht konvertiert und über die Nachrichtenzuordnung der Anwendung weitergeleitet.

Beispiel

Das folgende Beispiel zeigt, wie Sie einem MFC Active Document Server OLE-Befehlsbehandlungsfunktionen hinzufügen, um den OLECMDID_PRINT OLE-Befehl zu verarbeiten. In diesem Beispiel wird davon ausgegangen, dass Sie AppWizard verwendet haben, um eine MFC-Anwendung zu generieren, die ein aktiver Dokumentserver ist.

1. Fügen Sie in der Headerdatei ihrer CViewabgeleiteten Klasse das DECLARE_OLECMD_MAP Makro zur Klassendeklaration hinzu.

   Hinweis

   Verwenden Sie die CViewabgeleitete Klasse, da sie eine der Klassen auf dem Aktiven Dokumentserver ist, die sich in der WM_COMMAND Nachrichtenroutingkette befindet.

   class CMyServerView : public CView
   {
   protected: // create from serialization only
       CMyServerView();
       DECLARE_DYNCREATE(CMyServerView)
       DECLARE_OLECMD_MAP()
       // . . .
   };
   

2. Fügen Sie in der Implementierungsdatei für die CViewabgeleitete Klasse die BEGIN_OLECMD_MAP und END_OLECMD_MAP Makros hinzu:

   BEGIN_OLECMD_MAP(CMyServerView, CView)
   
   END_OLECMD_MAP()
   

3. Um den standardmäßigen OLE-Druckbefehl zu behandeln, fügen Sie der Befehlszuordnung ein ON_OLECMD Makro hinzu, das die OLE-Befehls-ID für den Standarddruckbefehl angibt, und ID_FILE_PRINT für die WM_COMMAND-ID. ID_FILE_PRINT ist die standardmäßige Druckbefehls-ID, die von AppWizard-generierten MFC-Anwendungen verwendet wird:

   BEGIN_OLECMD_MAP(CMyServerView, CView)
       ON_OLECMD(NULL, OLECMDID_PRINT, ID_FILE_PRINT)
   END_OLECMD_MAP()
   

Beachten Sie, dass eines der standardmäßigen OLE-Befehlsmakros, die in afxdocob.h definiert sind, anstelle des ON_OLECMD Makros verwendet werden kann, da OLECMDID_PRINT eine standardmäßige OLE-Befehls-ID ist. Das ON_OLECMD_PRINT Makro führt dieselbe Aufgabe wie das oben gezeigte ON_OLECMD Makro aus.

Wenn eine Containeranwendung diesen Server über die Schnittstelle des Servers IOleCommandTarget an einen OLECMDID_PRINT Befehl sendet, wird der MFC-Druckbefehlshandler auf dem Server aufgerufen, wodurch der Server die Anwendung druckt. Der Code des Aktiven Dokumentcontainers zum Aufrufen des in den obigen Schritten hinzugefügten Druckbefehls würde etwa wie folgt aussehen:

void CContainerCntrItem::DoOleCmd()
{
    IOleCommandTarget *pCmd = NULL;
    HRESULT hr = E_FAIL;
    OLECMD ocm={OLECMDID_PRINT, 0};

    hr = m_lpObject->QueryInterface(
        IID_IOleCommandTarget,reinterpret_cast<void**>(&pCmd));

    if (FAILED(hr))
        return;

    hr = pCmd->QueryStatus(NULL, 1, &ocm, NULL);

    if (SUCCEEDED(hr) && (ocm.cmdf& OLECMDF_ENABLED))
    {
        //Command is available and enabled so call it
        COleVariant vIn;
        COleVariant vOut;
        hr = pCmd->Exec(NULL, OLECMDID_PRINT,
            OLECMDEXECOPT_DODEFAULT, &vIn, &vOut);
        ASSERT(SUCCEEDED(hr));
    }
    pCmd->Release();
}

Siehe auch

Technische Hinweise – nach Nummern geordnet
Technische Hinweise – nach Kategorien geordnet