Tratamento de mensagens e destinos de comando

A interface IOleCommandTarget de despacho de comandos define um mecanismo simples e extensível para consultar e executar comandos. Esse mecanismo é mais simples do que o IDispatch da automação porque depende inteiramente de um conjunto padrão de comandos, os comandos raramente têm argumentos e nenhuma informação de tipo está envolvida (a segurança do tipo também é diminuída para argumentos de comando).

No design da interface de despacho de comandos, cada comando pertence a um "grupo de comandos" que é identificado com um GUID. Portanto, qualquer pessoa pode definir um novo grupo e definir todos os comandos dentro desse grupo sem qualquer necessidade de coordenar com a Microsoft ou qualquer outro fornecedor. (Este é essencialmente o mesmo meio de definição que um dispinterface mais dispIDs na Automação. Há sobreposição aqui, embora este mecanismo de roteamento de comandos seja apenas para roteamento de comandos e não para scripting/programabilidade em grande escala como a Automação lida com.)

IOleCommandTarget lida com os seguintes cenários:

• Quando um objeto é ativado no local, apenas as barras de ferramentas do objeto são normalmente exibidas e as barras de ferramentas do objeto podem ter botões para alguns dos comandos do contêiner, como Imprimir, Visualizar Impressão, Salvar, Novo, Zoom e outros. (Os padrões de ativação no local recomendam que os objetos removam esses botões de suas barras de ferramentas ou, pelo menos, os desativem. Esse design permite que esses comandos sejam habilitados e ainda roteados para o gestor correto.) Atualmente, não há nenhum mecanismo para o objeto despachar esses comandos para o contêiner.

• Quando um documento ativo é incorporado em um contêiner de documento ativo (como o Office Binder), o contêiner pode precisar enviar comandos como Imprimir, Configurar Página, Propriedades e outros para o documento ativo contido.

Esse roteamento de comando simples pode ser manipulado por meio de padrões de automação existentes e IDispatch. No entanto, a sobrecarga envolvida com IDispatch é maior do que o necessário aqui, por isso IOleCommandTarget fornece um meio mais simples de alcançar os mesmos fins.

interface IOleCommandTarget : IUnknown
    {
    HRESULT QueryStatus(
        [in] GUID *pguidCmdGroup,
        [in] ULONG cCmds,
        [in,out][size_is(cCmds)] OLECMD *prgCmds,
        [in,out] OLECMDTEXT *pCmdText);
    HRESULT Exec(
        [in] GUID *pguidCmdGroup,
        [in] DWORD nCmdID,
        [in] DWORD nCmdExecOpt,
        [in] VARIANTARG *pvaIn,
        [in,out] VARIANTARG *pvaOut);
    }

O QueryStatus método aqui testa se um determinado conjunto de comandos, sendo o conjunto identificado com um GUID, é suportado. Esta chamada preenche uma matriz de valores OLECMD (estruturas) com a lista de comandos suportados, bem como retorna texto descrevendo o nome de um comando e/ou informações de status. Quando o chamador deseja invocar um comando, ele pode passar o comando (e o GUID definido) para Exec junto com opções e argumentos, recebendo de volta um valor de retorno.

Ver também

Contêineres de documentos ativos