TN071: Implementação de IOleCommandTarget do MFC

A IOleCommandTarget interface permite que objetos e seus contêineres enviem comandos uns para os outros. Por exemplo, as barras de ferramentas de um objeto podem conter botões para comandos como Print, , Print Preview, Savee NewZoom. Se esse objeto tiver sido inserido em um contêiner compatível IOleCommandTarget, o objeto poderá 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 inserido se imprimesse, ele poderia fazer essa solicitação enviando um comando por meio da IOleCommandTarget interface do objeto inserido.

IOleCommandTarget é uma interface semelhante à Automação na qual é usada por um cliente para invocar métodos em um servidor. No entanto, o uso IOleCommandTarget salva a sobrecarga de fazer chamadas por meio de interfaces de Automação porque os programadores não precisam usar o método normalmente caro Invoke de IDispatch.

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

IOleCommandTarget também é implementado na COleFrameHook classe. COleFrameHook é uma classe MFC não documentada que implementa a funcionalidade da janela de quadros de contêineres de edição in-loco. COleFrameHook também usa mapas de interface MFC para implementar a IOleCommandTarget interface. COleFrameHook's implementação de IOleCommandTarget comandos OLE encaminhados para COleDocObjectItemcontêineres de documentos ativos derivados. Isso permite que qualquer contêiner de documento ativo do MFC receba mensagens de servidores de documentos ativos independentes.

Mapas de comando OLE do MFC

Os desenvolvedores do MFC podem aproveitar usando mapas de IOleCommandTarget comando OLE do MFC. Mapas de comando OLE são como mapas de mensagens porque podem ser usados para mapear comandos OLE para funções membro da classe que contém o mapa de comandos. Para fazer isso funcionar, coloque macros no mapa de comando 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. O MFC também fornece várias 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, o MFC tenta localizar a ID de comando e o grupo de comandos para o comando solicitado no mapa de comando OLE do aplicativo. Se uma correspondência for encontrada, uma mensagem de WM_COMMAND será enviada para o aplicativo que contém o mapa de comando com a ID do comando solicitado. (Consulte 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 roteadas por meio dos mapas de mensagens do aplicativo usando a arquitetura de roteamento de comando padrão do MFC.

Ao contrário dos mapas de mensagens, os mapas de comando OLE do MFC não têm suporte do ClassWizard. Os desenvolvedores do MFC devem adicionar suporte ao mapa de comandos OLE e entradas de mapa de comando OLE manualmente. Os mapas de comando OLE podem ser adicionados aos servidores de documentos ativos do MFC em qualquer classe que esteja no WM_COMMAND cadeia de roteamento de mensagens no momento em que o documento Ativo estiver ativo 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 contêineres de documentos ativos, as mensagens de WM_COMMAND serão enviadas apenas para o mapa de mensagens na COleDocObjectItemclasse derivada.

Macros de mapa de comando OLE

Use as macros a seguir para adicionar a funcionalidade de mapa de comandos à 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 comandos.

BEGIN_OLECMD_MAP(theClass, baseClass)

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

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

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

END_OLECMD_MAP()

Essa macro marca o final do mapa de comandos. Use essa macro no arquivo de implementação para a classe que contém o mapa de comandos. Essa 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. Esse parâmetro é NULL para o grupo de comandos OLE padrão.

olecmdid
ID de comando OLE do comando a ser invocado.

id
ID da mensagem WM_COMMAND a ser enviada ao aplicativo que contém o mapa de comandos 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 forem recebidos, eles serão convertidos na mensagem de WM_COMMAND especificada e roteados por meio do mapa de mensagens do aplicativo usando a arquitetura de roteamento de comando MFC padrão.

Exemplo

O exemplo a seguir mostra como adicionar a funcionalidade de tratamento de comando OLE a um servidor de documentos ativo do MFC para lidar com o comando OLE OLECMDID_PRINT . Este exemplo pressupõe que você usou o 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 CViewclasse derivada porque ela é 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 da CViewclasse derivada, adicione as macros BEGIN_OLECMD_MAP e END_OLECMD_MAP:

   BEGIN_OLECMD_MAP(CMyServerView, CView)
   
   END_OLECMD_MAP()
   

3. Para lidar com 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 do WM_COMMAND. ID_FILE_PRINT é a ID de comando de impressão padrão usada pelos 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, definidas 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 de contêiner envia a esse servidor um comando OLECMDID_PRINT por meio da interface do IOleCommandTarget servidor, o manipulador de comandos 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 de impressão adicionado nas etapas acima teria esta 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();
}

Consulte também

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