Classe CCmdTarget

A classe base para a arquitetura de mapa de mensagens da biblioteca Microsoft Foundation Class.

Sintaxe

class CCmdTarget : public CObject

Membros

Construtores públicos

Nome	Descrição
CCmdTarget::CCmdTarget	Constrói um objeto CCmdTarget.

Métodos públicos

Nome	Descrição
CCmdTarget::BeginWaitCursor	Exibe o cursor como um cursor de ampulheta.
CCmdTarget::DoOleVerb	Faz com que uma ação especificada por um verbo OLE seja executada.
CCmdTarget::EnableAutomation	Permite a automação OLE para o objeto CCmdTarget.
CCmdTarget::EnableConnections	Habilita o acionamento de eventos por pontos de conexão.
CCmdTarget::EnableTypeLib	Habilita a biblioteca de tipos de um objeto.
CCmdTarget::EndWaitCursor	Retorna ao cursor anterior.
CCmdTarget::EnumOleVerbs	Enumera os verbos OLE de um objeto.
CCmdTarget::FromIDispatch	Retorna um ponteiro para o objeto CCmdTarget associado ao ponteiro IDispatch.
CCmdTarget::GetDispatchIID	Obtém a ID da interface de expedição primária.
CCmdTarget::GetIDispatch	Retorna um ponteiro para o objeto IDispatch associado ao objeto CCmdTarget.
CCmdTarget::GetTypeInfoCount	Retorna o número de interfaces de informações de tipo que um objeto fornece.
CCmdTarget::GetTypeInfoOfGuid	Recupera a descrição de tipo que corresponde ao GUID especificado.
CCmdTarget::GetTypeLib	Obtém um ponteiro para uma biblioteca de tipos.
CCmdTarget::GetTypeLibCache	Obtém o cache da biblioteca de tipos.
CCmdTarget::IsInvokeAllowed	Habilita a invocação do método de automação.
CCmdTarget::IsResultExpected	Retornará diferente de zero caso uma função de automação deva retornar um valor.
CCmdTarget::OnCmdMsg	Roteia e despacha mensagens de comando.
CCmdTarget::OnFinalRelease	Faz a limpeza após a última referência OLE ser lançada.
CCmdTarget::RestoreWaitCursor	Restaura o cursor de ampulheta.

Comentários

Um mapa de mensagens roteia comandos ou mensagens para as funções membro que você escreve para lidar com eles. (Um comando é uma mensagem de um item de menu, um botão de comando ou uma tecla de acelerador.)

As classes de estrutura chave derivadas de CCmdTarget incluem CView, CWinApp, CDocument, CWnd e CFrameWnd. Se você pretende que uma nova classe manipule mensagens, derive-a de uma dessas classes derivadas de CCmdTarget. Raramente, você derivará uma classe diretamente de CCmdTarget.

Para ter uma visão geral dos destinos de comando e do roteamento de OnCmdMsg, consulte Destinos de comando, Roteamento de comando e Mensagens de mapeamento.

CCmdTarget inclui funções membro que lidam com a exibição de um cursor de ampulheta. Exiba o cursor de ampulheta quando você esperar que um comando leve um período perceptível para ser executado.

Mapas de expedição, semelhantes a mapas de mensagens, são usados para expor a funcionalidade IDispatch de automação OLE. Com a exposição dessa interface, outros aplicativos (como o Visual Basic) podem chamar seu aplicativo.

Hierarquia de herança

CObject

CCmdTarget

Requisitos

Cabeçalho: afxwin.h

CCmdTarget::BeginWaitCursor

Chame essa função para exibir o cursor como uma ampulheta quando você esperar que um comando leve um período perceptível para ser executado.

void BeginWaitCursor();

Comentários

A estrutura chama essa função para mostrar ao usuário que está ocupada, por exemplo, quando um objeto CDocument é carregado ou se salva em um arquivo.

As ações de BeginWaitCursor nem sempre são eficazes fora de um só manipulador de mensagens, pois outras ações, como a manipulação de OnSetCursor, podem alterar o cursor.

Chame EndWaitCursor para restaurar o cursor anterior.

Exemplo

// The following example illustrates the most common case
// of displaying the hourglass cursor during some lengthy
// processing of a command handler implemented in some
// CCmdTarget-derived class, such as a document or view.
void CMyView::OnBeginSleepEnd()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// The next example illustrates RestoreWaitCursor.
void CMyView::OnBeginDlgRestore()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   // The dialog box will normally change the cursor to
   // the standard arrow cursor, and leave the cursor in
   // as the standard arrow cursor when the dialog box is
   // closed.
   CFileDialog dlg(TRUE);
   dlg.DoModal();

   // It is necessary to call RestoreWaitCursor here in order
   // to change the cursor back to the hourglass cursor.
   RestoreWaitCursor();
   // do some more lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// In the above example, the dialog was clearly invoked between
// the pair of calls to BeginWaitCursor and EndWaitCursor.
// Sometimes it may not be clear whether the dialog is invoked
// in between a pair of calls to BeginWaitCursor and EndWaitCursor.
// It is permissible to call RestoreWaitCursor, even if
// BeginWaitCursor was not previously called.  This case is
// illustrated below, where CMyView::AnotherFunction does not
// need to know whether it was called in the context of an
// hourglass cursor.
void CMyView::OnDlgRestore()
{
   // some processing ...
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   RestoreWaitCursor();

   // some more processing ...
}

// If the dialog is invoked from a member function of
// some non-CCmdTarget, then you can call CWinApp::DoWaitCursor
// with a 0 parameter value to restore the hourglass cursor.
void CMyObject::OnDlgDoWait()
{
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   AfxGetApp()->DoWaitCursor(0); // same as CCmdTarget::RestoreWaitCursor
}

CCmdTarget::CCmdTarget

Constrói um objeto CCmdTarget.

CCmdTarget();

CCmdTarget::DoOleVerb

Faz com que uma ação especificada por um verbo OLE seja executada.

BOOL DoOleVerb(
    LONG iVerb,
    LPMSG lpMsg,
    HWND hWndParent,
    LPCRECT lpRect);

Parâmetros

iVerb
Identificador numérico do verbo.

lpMsg
Ponteiro para a estrutura MSG que descreve o evento (como um clique duplo) que invocou o verbo.

hWndParent
Identificador da janela do documento que contém o objeto.

lpRect
Ponteiro para a estrutura RECT que contém as coordenadas, em pixels, que definem o retângulo delimitador de um objeto em hWndParent.

Valor de retorno

TRUE se for bem-sucedido, caso contrário, FALSE.

Comentários

Essa função membro é basicamente uma implementação de IOleObject::DoVerb. As ações possíveis são enumeradas por CCmdTarget::EnumOleVerbs.

CCmdTarget::EnableAutomation

Chame essa função para habilitar a automação OLE de um objeto.

void EnableAutomation();

Comentários

Essa função normalmente é chamada do construtor do objeto e só deve ser chamada se um mapa de expedição tiver sido declarado para a classe. Para obter mais informações sobre automação, consulte os artigos Clientes de automação e Servidores de automação.

CCmdTarget::EnableConnections

Habilita o acionamento de eventos por pontos de conexão.

void EnableConnections();

Comentários

Para habilitar os pontos de conexão, chame essa função membro no construtor de sua classe derivada.

CCmdTarget::EnableTypeLib

Habilita a biblioteca de tipos de um objeto.

void EnableTypeLib();

Comentários

Chame essa função membro no construtor do objeto derivado de CCmdTarget se ele fornecer informações de tipo.

CCmdTarget::EndWaitCursor

Chame essa função após ter chamado a função membro BeginWaitCursor para voltar do cursor de ampulheta para o cursor anterior.

void EndWaitCursor();

Comentários

A estrutura também chama essa função membro depois de ter chamado o cursor de ampulheta.

Exemplo

// The following example illustrates the most common case
// of displaying the hourglass cursor during some lengthy
// processing of a command handler implemented in some
// CCmdTarget-derived class, such as a document or view.
void CMyView::OnBeginSleepEnd()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// The next example illustrates RestoreWaitCursor.
void CMyView::OnBeginDlgRestore()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   // The dialog box will normally change the cursor to
   // the standard arrow cursor, and leave the cursor in
   // as the standard arrow cursor when the dialog box is
   // closed.
   CFileDialog dlg(TRUE);
   dlg.DoModal();

   // It is necessary to call RestoreWaitCursor here in order
   // to change the cursor back to the hourglass cursor.
   RestoreWaitCursor();
   // do some more lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// In the above example, the dialog was clearly invoked between
// the pair of calls to BeginWaitCursor and EndWaitCursor.
// Sometimes it may not be clear whether the dialog is invoked
// in between a pair of calls to BeginWaitCursor and EndWaitCursor.
// It is permissible to call RestoreWaitCursor, even if
// BeginWaitCursor was not previously called.  This case is
// illustrated below, where CMyView::AnotherFunction does not
// need to know whether it was called in the context of an
// hourglass cursor.
void CMyView::OnDlgRestore()
{
   // some processing ...
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   RestoreWaitCursor();

   // some more processing ...
}

// If the dialog is invoked from a member function of
// some non-CCmdTarget, then you can call CWinApp::DoWaitCursor
// with a 0 parameter value to restore the hourglass cursor.
void CMyObject::OnDlgDoWait()
{
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   AfxGetApp()->DoWaitCursor(0); // same as CCmdTarget::RestoreWaitCursor
}

CCmdTarget::EnumOleVerbs

Enumera os verbos OLE de um objeto.

BOOL EnumOleVerbs(LPENUMOLEVERB* ppenumOleVerb);

Parâmetros

ppenumOleVerb
Um ponteiro para um ponteiro para uma interface IEnumOLEVERB.

Valor de retorno

TRUE se o objeto der suporte a pelo menos um verbo OLE (nesse caso, *ppenumOleVerb aponta para uma interface de enumerador IEnumOLEVERB); caso contrário, FALSE.

Comentários

Essa função membro é basicamente uma implementação de IOleObject::EnumVerbs.

CCmdTarget::FromIDispatch

Chame essa função para mapear um ponteiro IDispatch, recebido das funções membro de automação de uma classe, para o objeto CCmdTarget que implementa as interfaces do objeto IDispatch.

static CCmdTarget* PASCAL FromIDispatch(LPDISPATCH lpDispatch);

Parâmetros

lpDispatch
Um ponteiro para um objeto IDispatch.

Valor de retorno

Um ponteiro para o objeto CCmdTarget associado a lpDispatch. Essa função retornará NULL se o objeto IDispatch não for reconhecido como um objeto IDispatch da Microsoft Foundation Class.

Comentários

O resultado dessa função é o inverso de uma chamada para a função membro GetIDispatch.

CCmdTarget::GetDispatchIID

Obtém a ID da interface de expedição primária.

virtual BOOL GetDispatchIID(IID* pIID);

Parâmetros

pIID
Um ponteiro para uma ID de interface (um GUID).

Valor de retorno

TRUE se for bem-sucedido, caso contrário, FALSE. Se for bem-sucedido, *pIID será definido como a ID da interface de expedição primária.

Comentários

Classes derivadas devem substituir essa função membro (se não for substituída, GetDispatchIID retornará FALSE). Consulte COleControl.

CCmdTarget::GetIDispatch

Chame essa função membro para recuperar o ponteiro IDispatch de um método de automação que retorna um ponteiro IDispatch ou usa um ponteiro IDispatch por referência.

LPDISPATCH GetIDispatch(BOOL bAddRef);

Parâmetros

bAddRef
Especifica se a contagem de referência para o objeto deve ser incrementada.

Valor de retorno

O ponteiro IDispatch associado ao objeto.

Comentários

Para objetos que chamam EnableAutomation em seus construtores, habilitando-os para automação, essa função retorna um ponteiro para a implementação da Foundation Class de IDispatch que é usada por clientes que se comunicam por meio da interface IDispatch. Chamar essa função adiciona automaticamente uma referência ao ponteiro, portanto não é necessário fazer uma chamada para IUnknown::AddRef.

CCmdTarget::GetTypeInfoCount

Retorna o número de interfaces de informações de tipo que um objeto fornece.

virtual UINT GetTypeInfoCount();

Valor de retorno

O número de interfaces de informações de tipo.

Comentários

Essa função membro basicamente implementa IDispatch::GetTypeInfoCount.

Classes derivadas devem substituir essa função para retornar o número de interfaces de informações de tipo fornecidas (0 ou 1). Se não for substituído, GetTypeInfoCount retornará 0. Para substituir, use a macro IMPLEMENT_OLETYPELIB, que também implementa GetTypeLib e GetTypeLibCache.

CCmdTarget::GetTypeInfoOfGuid

Recupera a descrição de tipo que corresponde ao GUID especificado.

HRESULT GetTypeInfoOfGuid(
    LCID lcid,
    const GUID& guid,
    LPTYPEINFO* ppTypeInfo);

Parâmetros

lcid
Um identificador de local ( LCID).

guid
O GUID da descrição do tipo.

ppTypeInfo
Ponteiro para um ponteiro para a interface ITypeInfo.

Valor de retorno

Um HRESULT que indica o êxito ou falha da chamada. Se bem-sucedido, *ppTypeInfo apontará para a interface de informações de tipo.

CCmdTarget::GetTypeLib

Obtém um ponteiro para uma biblioteca de tipos.

virtual HRESULT GetTypeLib(
    LCID lcid,
    LPTYPELIB* ppTypeLib);

Parâmetros

lcid
Um LCID (ID de localidade).

ppTypeLib
[out] Um ponteiro para um ponteiro para a interface ITypeLib.

Valor de retorno

Um HRESULT que indica o êxito ou falha da chamada. Se bem-sucedido, *ppTypeLib apontará para a interface da biblioteca de tipos.

Comentários

Classes derivadas devem substituir essa função membro (se não for substituída, GetTypeLib retornará TYPE_E_CANTLOADLIBRARY). Use a macro IMPLEMENT_OLETYPELIB, que também implementa GetTypeInfoCount e GetTypeLibCache.

CCmdTarget::GetTypeLibCache

Obtém o cache da biblioteca de tipos.

virtual CTypeLibCache* GetTypeLibCache();

Valor de retorno

Um ponteiro para um objeto CTypeLibCache.

Comentários

Classes derivadas devem substituir essa função membro (se não for substituída, GetTypeLibCache retornará NULL). Use a macro IMPLEMENT_OLETYPELIB, que também implementa GetTypeInfoCount e GetTypeLib.

CCmdTarget::IsInvokeAllowed

Essa função é chamada pela implementação do MFC de IDispatch::Invoke para determinar se um determinado método de automação (identificado por dispid) pode ser invocado.

virtual BOOL IsInvokeAllowed(DISPID dispid);

Parâmetros

dispid
Uma ID de expedição.

Valor de retorno

TRUE se o método puder ser invocado, caso contrário FALSE.

Comentários

Se IsInvokeAllowed retornar TRUE, Invoke chamará o método; caso contrário, Invoke falhará, retornando E_UNEXPECTED.

As classes derivadas podem substituir essa função para retornar os valores apropriados (se não forem substituída, IsInvokeAllowed retornará TRUE). Confira, especificamente, COleControl::IsInvokeAllowed.

CCmdTarget::IsResultExpected

Use IsResultExpected para verificar se um cliente espera um valor retornado da chamada para uma função de automação.

BOOL IsResultExpected();

Valor de retorno

Diferente de zero caso uma função de automação deva retornar um valor; caso contrário, 0.

Comentários

A interface OLE informa ao MFC se o cliente está usando ou ignorando o resultado de uma chamada de função. O MFC, por sua vez, usa essa informação para determinar o resultado de uma chamada para IsResultExpected. Se a produção de um valor retornado fizer uso intensivo de recursos ou de tempo, você poderá aumentar a eficiência chamando essa função antes de calcular o valor retornado.

Essa função retornará 0 apenas uma vez, para que você obtenha valores retornados válidos de outras funções de automação se você chamá-las da função de automação chamada pelo cliente.

IsResultExpected retornará um valor diferente de zero se chamado quando uma chamada de função de automação não estiver em andamento.

CCmdTarget::OnCmdMsg

Chamado pela estrutura para rotear e expedir mensagens de comando e para tratar da atualização dos objetos da interface do usuário de comando.

virtual BOOL OnCmdMsg(
    UINT nID,
    int nCode,
    void* pExtra,
    AFX_CMDHANDLERINFO* pHandlerInfo);

Parâmetros

nID
Contém a ID do comando.

nCode
Identifica o código de notificação de comando. Confira os Comentários para obter mais informações sobre os valores de nCode.

pExtra
Usado de acordo com o valor de nCode. Confira os Comentários para obter mais informações sobre pExtra.

pHandlerInfo
Se não for NULL, OnCmdMsg preencherá os membros pTarget e pmf da estrutura pHandlerInfo em vez de expedir o comando. Normalmente, esse parâmetro deve ser NULL.

Valor de retorno

Diferente de zero se a mensagem for tratada, caso contrário, 0.

Comentários

Essa é a principal rotina de implementação da arquitetura de comando da estrutura.

Em tempo de execução, OnCmdMsg expede um comando para outros objetos ou trata do comando por conta própria chamando a classe raiz CCmdTarget::OnCmdMsg, que faz a pesquisa de mapa de mensagens real. Para obter uma descrição completa do roteamento de comandos padrão, consulte Tópicos sobre mapeamento e tratamento de mensagens.

Em raras ocasiões, talvez você queira substituir essa função membro para estender o roteamento de comandos padrão da estrutura. Consulte a Nota técnica 21 para obter detalhes avançados sobre arquitetura de roteamento de comandos.

Se você substituir OnCmdMsg, precisará fornecer o valor apropriado para nCode, o código de notificação de comando e pExtra, que depende do valor de nCode. A seguinte tabela lista os valores correspondentes:

nCode valor	pExtra valor
CN_COMMAND	CCmdUI*
CN_EVENT	AFX_EVENT*
CN_UPDATE_COMMAND_UI	CCmdUI*
CN_OLECOMMAND	COleCmdUI*
CN_OLE_UNREGISTER	NULL

Exemplo

// This example illustrates extending the framework's standard command
// route from the view to objects managed by the view.  This example
// is from an object-oriented drawing application, similar to the
// DRAWCLI sample application, which draws and edits "shapes".
BOOL CMyView::OnCmdMsg(UINT nID,
                       int nCode,
                       void *pExtra,
                       AFX_CMDHANDLERINFO *pHandlerInfo)
{
   // Extend the framework's command route from the view to
   // the application-specific CMyShape that is currently selected
   // in the view. m_pActiveShape is NULL if no shape object
   // is currently selected in the view.
   if ((m_pActiveShape != NULL) &&
       m_pActiveShape->OnCmdMsg(nID, nCode, pExtra, pHandlerInfo))
      return TRUE;

   // If the object(s) in the extended command route don't handle
   // the command, then let the base class OnCmdMsg handle it.
   return CView::OnCmdMsg(nID, nCode, pExtra, pHandlerInfo);
}

 

// The command handler for ID_SHAPE_COLOR (menu command to change
// the color of the currently selected shape) was added to the message
// map of CMyShape (note, not CMyView) using the Properties window.
// The menu item will be automatically enabled or disabled, depending
// on whether a CMyShape is currently selected in the view, that is,
// depending on whether CMyView::m_pActiveView is NULL.  It is not
// necessary to implement an ON_UPDATE_COMMAND_UI handler to enable
// or disable the menu item.
BEGIN_MESSAGE_MAP(CMyShape, CCmdTarget)
ON_COMMAND(ID_SHAPE_COLOR, &CMyShape::OnShapeColor)
END_MESSAGE_MAP()

CCmdTarget::OnFinalRelease

Chamado pela estrutura quando a última referência de OLE de ou para o objeto é liberada.

virtual void OnFinalRelease();

Comentários

Substitua essa função para fornecer tratamento especial para essa situação. A implementação padrão exclui o objeto.

CCmdTarget::RestoreWaitCursor

Chame essa função para restaurar o cursor de ampulheta apropriado após o cursor do sistema ser alterado (por exemplo, após uma caixa de mensagem ser aberta e, em seguida, fechada no meio de uma operação demorada).

void RestoreWaitCursor();

Exemplo

// The following example illustrates the most common case
// of displaying the hourglass cursor during some lengthy
// processing of a command handler implemented in some
// CCmdTarget-derived class, such as a document or view.
void CMyView::OnBeginSleepEnd()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// The next example illustrates RestoreWaitCursor.
void CMyView::OnBeginDlgRestore()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   // The dialog box will normally change the cursor to
   // the standard arrow cursor, and leave the cursor in
   // as the standard arrow cursor when the dialog box is
   // closed.
   CFileDialog dlg(TRUE);
   dlg.DoModal();

   // It is necessary to call RestoreWaitCursor here in order
   // to change the cursor back to the hourglass cursor.
   RestoreWaitCursor();
   // do some more lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// In the above example, the dialog was clearly invoked between
// the pair of calls to BeginWaitCursor and EndWaitCursor.
// Sometimes it may not be clear whether the dialog is invoked
// in between a pair of calls to BeginWaitCursor and EndWaitCursor.
// It is permissible to call RestoreWaitCursor, even if
// BeginWaitCursor was not previously called.  This case is
// illustrated below, where CMyView::AnotherFunction does not
// need to know whether it was called in the context of an
// hourglass cursor.
void CMyView::OnDlgRestore()
{
   // some processing ...
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   RestoreWaitCursor();

   // some more processing ...
}

// If the dialog is invoked from a member function of
// some non-CCmdTarget, then you can call CWinApp::DoWaitCursor
// with a 0 parameter value to restore the hourglass cursor.
void CMyObject::OnDlgDoWait()
{
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   AfxGetApp()->DoWaitCursor(0); // same as CCmdTarget::RestoreWaitCursor
}

Confira também

Exemplo de MFC ACDUAL
Classe CObject
Gráfico da hierarquia
Classe CCmdUI
Classe CDocument
Classe CDocTemplate
Classe CWinApp
Classe CWnd
Classe CView
Classe CFrameWnd
Classe COleDispatchDriver