TN071: Implementação de MFC IOleCommandTarget

A IOleCommandTarget interface permite que objetos e seus contêineres expendam comandos uns para os outros. Por exemplo, as barras de ferramentas de um objeto podem conter botões para comandos como Print, Print Preview, , SaveNew, e Zoom. Se tal objeto fosse incorporado em um contêiner que suportasse IOleCommandTarget, o objeto poderia habilitar seus botões e encaminhar os comandos para o contêiner para processamento quando o usuário clicasse neles. Se um contêiner quisesse que o objeto incorporado fosse impresso, ele poderia fazer essa solicitação enviando um comando através da IOleCommandTarget interface do objeto incorporado.

IOleCommandTarget é uma interface semelhante à automação, na medida em que é usada por um cliente para invocar métodos em um servidor. No entanto, o uso de IOleCommandTarget reduz o impacto das chamadas realizadas por meio de interfaces de automação, pois os programadores não precisam recorrer ao método, geralmente caro, Invoke de IDispatch.

No MFC, a IOleCommandTarget interface é usada por servidores de documentos ativos para permitir que contêineres de documentos ativos expendam comandos para o servidor. A classe de servidor de documentos ativo, CDocObjectServerItem, usa mapas de interface MFC (consulte TN038: MFC/OLE IUnknown Implementation) para implementar a IOleCommandTarget interface.

IOleCommandTarget também é implementado na COleFrameHook classe. COleFrameHook é uma classe MFC não documentada que implementa a funcionalidade de janela de moldura de contêineres de edição in-situ. COleFrameHook também usa mapas de interface MFC para implementar a IOleCommandTarget interface. A implementação de COleFrameHook encaminha comandos OLE para contentores de documentos ativos derivados de IOleCommandTarget. Isso permite que qualquer contêiner de documento MFC Ative receba mensagens de servidores de documentos ativos contidos.

Mapas de comando OLE MFC

Os desenvolvedores do MFC podem tirar proveito de IOleCommandTarget ao usar mapas de comando MFC OLE. Os mapas de comandos OLE são como mapas de mensagens porque podem ser usados para mapear comandos OLE para funções de membro da classe que contém o mapa de comandos. Para que isso funcione, coloque macros no mapa de comandos para especificar o grupo de comandos OLE do comando que você deseja manipular, o comando OLE e a ID de comando da mensagem WM_COMMAND que será enviada quando o comando OLE for recebido. MFC também fornece uma série de macros predefinidas para comandos OLE padrão. Para obter uma lista dos comandos OLE padrão que foram originalmente projetados para uso com aplicativos do Microsoft Office, consulte a enumeração OLECMDID, que é definida em docobj.h.

Quando um comando OLE é recebido por um aplicativo MFC que contém um mapa de comando OLE, MFC tenta localizar o ID de comando e grupo de comandos para o comando solicitado no mapa de comando OLE do aplicativo. Se uma correspondência for encontrada, uma mensagem WM_COMMAND será despachada para a aplicação, contendo o mapa de comandos com o ID do comando solicitado. (Veja a descrição abaixo ON_OLECMD ). Dessa forma, os comandos OLE enviados para um aplicativo são transformados em mensagens WM_COMMAND pelo MFC. As mensagens WM_COMMAND são então roteadas através dos mapas de mensagens do aplicativo usando a arquitetura de roteamento de comando padrão MFC.

Ao contrário dos mapas de mensagens, os mapas de comando OLE MFC não são suportados pelo ClassWizard. Os desenvolvedores MFC devem adicionar manualmente suporte ao mapa de comando OLE e as respetivas entradas. Os mapas de comando OLE podem ser adicionados aos servidores de documentos ativos MFC em qualquer classe que esteja na sequência de encaminhamento de mensagens WM_COMMAND no momento em que o documento ativo estiver ativo no local em um contêiner. Essas classes incluem as classes do aplicativo derivadas de CWinApp, CView, CDocument e COleIPFrameWnd. Em contêineres de documentos ativos, os mapas de comando OLE só podem ser adicionados à classe derivada de COleDocObjectItem. Além disso, em contentores de documentos ativos, as mensagens WM_COMMAND só serão enviadas para o mapa de mensagens na classe derivada COleDocObjectItem.

Macros de mapa de comando OLE

Use as seguintes macros para adicionar a funcionalidade de mapa de comando à sua classe:

DECLARE_OLECMD_MAP ()

Essa macro vai na declaração de classe (normalmente no arquivo de cabeçalho) da classe que contém o mapa de comando.

BEGIN_OLECMD_MAP(theClass, baseClass)

a Classe
Nome da classe que contém o mapa de comandos.

Classe base
Nome da classe base da classe que contém o mapa de comandos.

Esta macro marca o início do mapa de comandos. Use esta macro no arquivo de implementação para a classe que contém o mapa de comando.

END_OLECMD_MAP()

Esta macro marca o fim do mapa de comandos. Use esta macro no arquivo de implementação para a classe que contém o mapa de comando. Esta macro deve sempre seguir a macro BEGIN_OLECMD_MAP.

ON_OLECMD(pguid, olecmdid, id)

Pguid
Ponteiro para o GUID do grupo de comandos do comando OLE. Este parâmetro é NULL para o grupo de comandos OLE padrão.

Olecmdid
ID de comando OLE a ser invocado.

ID
ID da mensagem de WM_COMMAND a ser enviada para o aplicativo que contém o mapa de comando quando esse comando OLE é invocado.

Use a macro ON_OLECMD no mapa de comandos para adicionar entradas para os comandos OLE que você deseja manipular. Quando os comandos OLE são recebidos, eles serão convertidos para a mensagem de WM_COMMAND especificada e roteados através do mapa de mensagens do aplicativo usando a arquitetura de roteamento de comandos MFC padrão.

Exemplo

O exemplo a seguir mostra como adicionar a capacidade de manipulação de comandos OLE a um servidor de documentos MFC Ative para manipular o comando OLECMDID_PRINT OLE. Este exemplo pressupõe que você usou AppWizard para gerar um aplicativo MFC que é um servidor de documentos ativo.

1. CViewNo arquivo de cabeçalho da classe derivada, adicione a macro DECLARE_OLECMD_MAP à declaração de classe.

   Observação

   Use a classe derivada de CView porque é uma das classes no servidor de documentos ativo que está na cadeia de roteamento de mensagens WM_COMMAND.

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

2. No arquivo de implementação para a CViewclasse -derivada, adicione as macros BEGIN_OLECMD_MAP e END_OLECMD_MAP:

   BEGIN_OLECMD_MAP(CMyServerView, CView)
   
   END_OLECMD_MAP()
   

3. Para manipular o comando de impressão OLE padrão, adicione uma macro ON_OLECMD ao mapa de comandos especificando a ID do comando OLE para o comando de impressão padrão e ID_FILE_PRINT para a ID de WM_COMMAND. ID_FILE_PRINT é o ID de comando de impressão padrão usado por aplicativos MFC gerados pelo AppWizard:

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

Observe que uma das macros de comando OLE padrão, definida em afxdocob.h, pode ser usada no lugar da macro ON_OLECMD porque OLECMDID_PRINT é uma ID de comando OLE padrão. A macro ON_OLECMD_PRINT realizará a mesma tarefa que a macro ON_OLECMD mostrada acima.

Quando um aplicativo contêiner envia a este servidor um comando OLECMDID_PRINT através da interface do IOleCommandTarget servidor, o manipulador de comando de impressão MFC será invocado no servidor, fazendo com que o servidor imprima o aplicativo. O código do contêiner de documento ativo para invocar o comando print adicionado nas etapas acima teria a seguinte aparência:

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

Ver também

Notas técnicas por número
Notas técnicas por categoria