TN071 : Implémentation IOleCommandTarget MFC

L’interface IOleCommandTarget permet aux objets et à leurs conteneurs de distribuer des commandes les unes aux autres. Par exemple, les barres d’outils d’un objet peuvent contenir des boutons pour les commandes telles que Print, , Print Preview, Save, Newet Zoom. Si un tel objet a été incorporé dans un conteneur qui prend en charge IOleCommandTarget, l’objet peut activer ses boutons et transférer les commandes au conteneur pour traitement lorsque l’utilisateur les a cliqués. Si un conteneur voulait que l’objet incorporé s’imprime lui-même, il pouvait effectuer cette requête en envoyant une commande via l’interface IOleCommandTarget de l’objet incorporé.

IOleCommandTarget est une interface de type Automation dans laquelle elle est utilisée par un client pour appeler des méthodes sur un serveur. Toutefois, l’utilisation IOleCommandTarget permet d’économiser la surcharge liée à l’exécution d’appels via des interfaces Automation, car les programmeurs n’ont pas besoin d’utiliser la méthode généralement coûteuse Invoke de IDispatch.

Dans MFC, l’interface IOleCommandTarget est utilisée par les serveurs de documents actifs pour permettre aux conteneurs de documents actifs de distribuer des commandes au serveur. La classe de serveur de documents active, CDocObjectServerItemutilise des mappages d’interface MFC (voir TN038 : implémentation MFC/OLE IUnknown) pour implémenter l’interface IOleCommandTarget .

IOleCommandTarget est également implémenté dans la COleFrameHook classe. COleFrameHook est une classe MFC non documentée qui implémente la fonctionnalité de fenêtre frame des conteneurs d’édition sur place. COleFrameHook utilise également des mappages d’interface MFC pour implémenter l’interface IOleCommandTarget . COleFrameHookimplémentation des IOleCommandTarget commandes OLE transférées vers COleDocObjectItemdes conteneurs de documents actifs dérivés. Cela permet à n’importe quel conteneur de documents actif MFC de recevoir des messages provenant de serveurs de documents actifs contenus.

Cartes de commande OLE MFC

Les développeurs MFC peuvent tirer parti des mappages de IOleCommandTarget commandes OLE MFC. Les mappages de commandes OLE sont similaires aux mappages de messages, car ils peuvent être utilisés pour mapper les commandes OLE aux fonctions membres de la classe qui contient le mappage de commandes. Pour effectuer ce travail, placez des macros dans le mappage de commandes pour spécifier le groupe de commandes OLE de la commande que vous souhaitez gérer, la commande OLE et l’ID de commande du message WM_COMMAND qui sera envoyé lorsque la commande OLE est reçue. MFC fournit également un certain nombre de macros prédéfinies pour les commandes OLE standard. Pour obtenir la liste des commandes OLE standard conçues à l’origine pour une utilisation avec Microsoft application Office lications, consultez l’énumération OLECMDID, qui est définie dans docobj.h.

Lorsqu’une commande OLE est reçue par une application MFC qui contient un mappage de commandes OLE, MFC tente de trouver l’ID de commande et le groupe de commandes pour la commande demandée dans le mappage de commandes OLE de l’application. Si une correspondance est trouvée, un message WM_COMMAND est envoyé à l’application contenant le mappage de commandes avec l’ID de la commande demandée. (Consultez la description ci-dessous ON_OLECMD .) De cette façon, les commandes OLE distribuées à une application sont transformées en messages WM_COMMAND par MFC. Les messages WM_COMMAND sont ensuite routés via les mappages de messages de l’application à l’aide de l’architecture de routage des commandes standard MFC.

Contrairement aux mappages de messages, les mappages de commandes OLE MFC ne sont pas pris en charge par ClassWizard. Les développeurs MFC doivent ajouter manuellement la prise en charge de la carte de commandes OLE et les entrées de mappage de commandes OLE. Les mappages de commandes OLE peuvent être ajoutés aux serveurs de documents actifs MFC dans n’importe quelle classe qui se trouve dans la chaîne de routage des messages WM_COMMAND au moment où le document Actif est actif dans un conteneur. Ces classes incluent les classes de l’application dérivées de CWinApp, CView, CDocument et COleIPFrameWnd. Dans les conteneurs de documents actifs, les mappages de commandes OLE ne peuvent être ajoutés qu’à la classe dérivée de COleDocObjectItem. En outre, dans les conteneurs de documents actifs, les messages WM_COMMAND ne seront distribués qu’à la carte des messages dans la COleDocObjectItemclasse dérivée.

OLE Command Map Macros

Utilisez les macros suivantes pour ajouter des fonctionnalités de mappage de commandes à votre classe :

DECLARE_OLECMD_MAP ()

Cette macro se trouve dans la déclaration de classe (généralement dans le fichier d’en-tête) de la classe qui contient le mappage de commandes.

BEGIN_OLECMD_MAP(theClass, baseClass)

theClass
Nom de la classe qui contient le mappage de commandes.

Baseclass
Nom de la classe de base de la classe qui contient le mappage de commandes.

Cette macro marque le début de la carte de commandes. Utilisez cette macro dans le fichier d’implémentation de la classe qui contient le mappage de commandes.

END_OLECMD_MAP()

Cette macro marque la fin du mappage de commandes. Utilisez cette macro dans le fichier d’implémentation de la classe qui contient le mappage de commandes. Cette macro doit toujours suivre la macro BEGIN_OLECMD_MAP.

ON_OLECMD(pguid, olecmdid, id)

pguid
Pointeur vers le GUID du groupe de commandes de la commande OLE. Ce paramètre est NULL pour le groupe de commandes OLE standard.

olecmdid
ID de commande OLE de la commande à appeler.

id
ID du message WM_COMMAND à envoyer à l’application contenant le mappage de commandes lorsque cette commande OLE est appelée.

Utilisez la macro ON_OLECMD dans le mappage de commandes pour ajouter des entrées pour les commandes OLE que vous souhaitez gérer. Lorsque les commandes OLE sont reçues, elles sont converties en message WM_COMMAND spécifié et routées via la carte de messages de l’application à l’aide de l’architecture de routage des commandes MFC standard.

Exemple

L’exemple suivant montre comment ajouter une fonctionnalité de gestion des commandes OLE à un serveur de documents actif MFC pour gérer la commande OLE OLECMDID_PRINT . Cet exemple suppose que vous avez utilisé AppWizard pour générer une application MFC qui est un serveur de documents actif.

1. Dans le fichier d’en-tête de votre CViewclasse dérivée, ajoutez la macro DECLARE_OLECMD_MAP à la déclaration de classe.

   Remarque

   Utilisez la CViewclasse dérivée ,car il s’agit de l’une des classes du serveur de documents actif qui se trouve dans la chaîne de routage de messages WM_COMMAND.

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

2. Dans le fichier d’implémentation de la CViewclasse dérivée, ajoutez les macros BEGIN_OLECMD_MAP et END_OLECMD_MAP :

   BEGIN_OLECMD_MAP(CMyServerView, CView)
   
   END_OLECMD_MAP()
   

3. Pour gérer la commande d’impression OLE standard, ajoutez une macro ON_OLECMD à la carte de commandes en spécifiant l’ID de commande OLE pour la commande d’impression standard et ID_FILE_PRINT pour l’ID de WM_COMMAND. ID_FILE_PRINT est l’ID de commande d’impression standard utilisé par les applications MFC générées par AppWizard :

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

Notez qu’une des macros de commande OLE standard, définies dans afxdocob.h, peut être utilisée à la place de la macro ON_OLECMD, car OLECMDID_PRINT est un ID de commande OLE standard. La macro ON_OLECMD_PRINT accomplira la même tâche que la macro ON_OLECMD indiquée ci-dessus.

Lorsqu’une application conteneur envoie ce serveur à une commande OLECMDID_PRINT via l’interface du serveur, le gestionnaire de IOleCommandTarget commandes d’impression MFC est appelé sur le serveur, ce qui entraîne l’impression du serveur. Le code du conteneur de documents actif pour appeler la commande d’impression ajoutée dans les étapes ci-dessus ressemble à ceci :

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

Voir aussi

Notes techniques par numéro
Notes techniques par catégorie